Impact Preview

🚀 智能代理策略（Agent Polis）

AI 智能體的影響預覽 - 為自主 AI 行動提供“基礎設施即代碼（Terraform）計劃”

Agent Polis 能夠讓你在任何 AI 智能體行動執行之前，確切瞭解即將發生的變化。它會攔截自主 AI 智能體提出的行動建議，分析其影響，向你展示即將發生變化的差異預覽，並僅在獲得人類批准後才執行操作。從此，你無需再擔心 AI 智能體刪除你的生產數據庫。

🚀 快速開始

嘗試 Agent Polis 的最快方法是使用 MCP 服務器搭配 Claude Desktop 或 Cursor。

1. 安裝並運行

pip install impact-preview
impact-preview-mcp

2. 配置 Claude Desktop

在你的配置文件（macOS 上為 ~/Library/Application Support/Claude/claude_desktop_config.json）中添加以下內容：

{
    "mcpServers": {
        "impact-preview": {
            "url": "http://localhost:8000/mcp"
        }
    }
}

3. 開始嘗試

讓 Claude 編輯文件，它現在具備以下工具：

示例提示：

“預覽如果將 config.yaml 中的數據庫 URL 更改為指向生產環境會發生什麼”

Claude 將在進行更改之前向你展示差異和風險評估。

✨ 主要特性

• 影響預覽：在執行前查看文件差異、風險評估和警告。
• 審批工作流：批准、拒絕或修改提議的操作。
• 風險評估：自動檢測高風險操作（生產數據、系統文件等）。
• 審計跟蹤：對每個提議和執行的操作進行事件溯源記錄。
• SDK 集成：為你的智能體代碼提供簡單的 @require_approval 裝飾器。
• 儀表盤：使用 Streamlit UI 審查和批准操作。

📦 安裝指南

完整服務器安裝

若要使用包含儀表盤和 API 的完整審批工作流，可按以下步驟操作：

# 使用 Docker（推薦）
docker-compose up -d

# 或本地安裝
pip install impact-preview
impact-preview

註冊智能體

curl -X POST http://localhost:8000/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My AI coding assistant"}'

提交操作 → 審查 → 批准

# 提交
curl -X POST http://localhost:8000/api/v1/actions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action_type": "file_write", "target": "/app/config.yaml", "description": "Update DB URL", "payload": {"content": "db: prod"}}'

# 預覽
curl http://localhost:8000/api/v1/actions/ACTION_ID/preview -H "X-API-Key: YOUR_API_KEY"

# 批准（或拒絕）
curl -X POST http://localhost:8000/api/v1/actions/ACTION_ID/approve -H "X-API-Key: YOUR_API_KEY"

審計跟蹤（事件）

你可以檢索某個操作的完整審計跟蹤記錄：

curl http://localhost:8000/api/v1/actions/ACTION_ID/events -H "X-API-Key: YOUR_API_KEY"

ActionPreviewGenerated 事件有效負載包含機器可讀的治理上下文：

• data.governance.policy.decision / data.governance.policy.matched_rule_id
• data.governance.scanner.reason_ids / data.governance.scanner.max_severity

💻 使用示例

基礎用法

from agent_polis import AgentPolisClient

client = AgentPolisClient(api_url="http://localhost:8000", api_key="YOUR_KEY")

# 裝飾器方法 - 阻塞直到人類批准
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
    with open(path, 'w') as f:
        f.write(content)

# 這將：提交 → 等待批准 → 僅在批准後執行
write_config("/etc/myapp/config.yaml", "new content")

高級用法

啟動 Streamlit 儀表盤以審查待處理的操作：

pip install impact-preview[ui]
streamlit run src/agent_polis/ui/app.py

📚 詳細文檔

操作 API

操作類型

• file_write - 向文件寫入內容
• file_create - 創建新文件
• file_delete - 刪除文件
• file_move - 移動/重命名文件
• db_query - 執行數據庫查詢（讀取）
• db_execute - 執行數據庫語句（寫入）
• api_call - 發起 HTTP 請求
• shell_command - 運行 shell 命令
• custom - 自定義操作類型

風險級別

• 低：讀取操作、安全更改
• 中：對非關鍵文件的寫入操作
• 高：刪除操作、系統文件
• 嚴重：生產數據、不可逆轉的更改

🔧 技術細節

配置

# .env
SECRET_KEY=your-secret-key
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agent_polis
REDIS_URL=redis://localhost:6379/0

# 可選
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO

路線圖

🤝貢獻指南

git clone https://github.com/agent-polis/impact-preview.git
cd impact-preview
pip install -e .[dev]
pre-commit install
pytest

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。

本項目專為希望使用可信賴 AI 智能體的開發者打造。