impact-preview

🔍 Agent Polis

AI Agent 影响预览——自主 AI 操作的“Terraform plan”

在任何 AI Agent 操作执行前，准确查看将发生的变更。

Agent Polis 会拦截自主 AI Agent 提出的操作，分析其影响，向你展示变更内容的差异预览，并且只有在获得人工批准后才会执行。再也不用担心 AI Agent 删除你的生产数据库。

🎯 问题

自主 AI Agent 功能强大，但也很危险。近期发生的事件包括：

• Replit Agent 删除了生产数据库，随后还对此撒谎
• Cursor YOLO mode 删除了整个系统，包括它自身
• Claude Code 学会了通过 shell 脚本绕过安全限制

开发者想要使用 AI Agent，却不信任它们。当前的解决方案只展示 Agent 想要做什么，而不是实际会发生什么。AI Agent 操作没有相当于“terraform plan”的功能。

🚀 解决方案

AI Agent proposes action → Agent Polis analyzes impact → Human reviews diff → Approve/Reject → Execute

# Example: Agent wants to write to config.yaml
- database_url: postgresql://localhost:5432/dev
+ database_url: postgresql://prod-server:5432/production
! WARNING: Production database URL detected (CRITICAL RISK)

✨ 功能

• 影响预览：在执行前查看文件差异、风险评估和警告
• 审批工作流：批准、拒绝或修改提议的操作
• 风险评估：自动检测高风险操作（生产数据、系统文件等）
• 审计跟踪：采用事件溯源的日志，记录每项提议和已执行的操作
• SDK 集成：使用简便的 @require_approval 装饰器编写 Agent 代码
• 仪表板：用于审查和批准操作的 Streamlit UI

🚀 快速开始（2 分钟）

使用 Claude Desktop 或 Cursor 搭配 MCP 服务，是体验 Agent Polis 最快捷的方式。

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 编辑一个文件，它现在可以使用以下工具：

工具	功能
preview_file_write	在进行任何编辑前显示差异
preview_file_delete	显示将会丢失的内容
preview_shell_command	标记危险命令
check_path_risk	快速检查任意路径的风险

提示词示例：

“预览将 config.yaml 中的数据库 URL 改为指向生产环境会产生什么影响”

Claude 会在进行更改之前向你展示差异和风险评估。

---

📦 完整服务安装

如需使用包含仪表板和 API 的完整审批工作流：

# Using Docker (recommended)
docker-compose up -d

# Or locally
pip install impact-preview
impact-preview

注册 Agent

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

提交操作 → 审查 → 批准

# Submit
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"}}'

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

# Approve (or reject)
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

---

🐍 SDK 集成

为 Agent 中的危险操作添加封装：

from agent_polis import AgentPolisClient

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

# Decorator approach - blocks until human approves
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
    with open(path, 'w') as f:
        f.write(content)

# This will: submit → wait for approval → execute only if approved
write_config("/etc/myapp/config.yaml", "new content")

🖥️ 仪表板

启动 Streamlit 仪表板，审查待处理的操作：

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

📚 API 参考

操作 API

端点	方法	说明
/api/v1/actions	POST	提交操作以供批准
/api/v1/actions	GET	列出你的操作
/api/v1/actions/pending	GET	列出待审批操作
/api/v1/actions/{id}	GET	获取操作详情
/api/v1/actions/{id}/preview	GET	获取影响预览
/api/v1/actions/{id}/diff	GET	获取差异输出
/api/v1/actions/{id}/approve	POST	批准操作
/api/v1/actions/{id}/reject	POST	拒绝操作
/api/v1/actions/{id}/execute	POST	执行已批准的操作

操作类型

• 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

# Optional
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO

🗺️ 路线图

版本	重点	状态
v0.2.0	文件操作预览	当前
v0.3.0	数据库操作预览	计划中
v0.4.0	API 调用预览	计划中
v0.5.0	IDE 集成（Cursor、VS Code）	计划中
v1.0.0	可用于生产环境	计划中

🤝 参与贡献

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

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE。

---

为希望拥有值得信赖的 AI Agent 的开发者打造。