JinDaGe - impact-preview MCP Details

article

README

🚀 智能代理策略（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 编辑文件，它现在具备以下工具： | 工具 | 功能 | |------|--------------| | preview_file_write | 在任何编辑操作前显示差异 | | preview_file_delete | 显示将丢失的内容 | | preview_shell_command | 标记危险命令 | | check_path_risk | 对任何路径进行快速风险检查 |

示例提示：

“预览如果将 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

| 端点 | 方法 | 描述 | |----------|--------|-------------| | /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

# 可选
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 智能体的开发者打造。

impact-preview