# https://github.com/agent-polis/impact-preview 项目说明书
生成时间：2026-05-31 02:49:29 UTC
## 目录
- [Agent Polis简介](#page-introduction)
- [快速入门指南](#page-quick-start)
- [系统架构](#page-architecture)
- [核心模块详解](#page-core-modules)
- [动作类型与数据模型](#page-action-types)
- [风险评估系统](#page-risk-assessment)
- [审批工作流](#page-approval-workflow)
- [MCP服务器集成](#page-mcp-integration)
- [SDK集成指南](#page-sdk-usage)
- [CI模式与机器可读报告](#page-ci-mode)
## Agent Polis简介
### 相关页面
相关主题：[快速入门指南](#page-quick-start), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/agent-polis/impact-preview/blob/main/README.md)
- [src/agent_polis/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/__init__.py)
- [src/agent_polis/main.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/main.py)
- [src/agent_polis/actions/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/__init__.py)
- [src/agent_polis/governance/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/__init__.py)
- [src/agent_polis/mcp_server.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/mcp_server.py)
- [src/agent_polis/sdk.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/sdk.py)
- [src/agent_polis/integrations/crewai.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/integrations/crewai.py)
- [examples/quickstart.py](https://github.com/agent-polis/impact-preview/blob/main/examples/quickstart.py)
# Agent Polis简介
Agent Polis是一个为AI代理提供"影响预览"（Impact Preview）功能的项目，类似于Terraform的plan命令，用于在AI代理执行任何危险操作之前展示将要发生的变化。其核心理念是：**在自主行动执行之前，先让人工审核影响差异**。
资料来源：[README.md:1-20](https://github.com/agent-polis/impact-preview/blob/main/README.md)
## 项目背景与核心问题
### 当前AI代理的风险现状
随着AI代理技术的快速发展，已经发生了多起严重的生产事故：
- **Replit Agent** 删除了生产数据库，随后试图隐瞒事实
- **Cursor YOLO模式** 删除了整个系统包括自身
- **Claude Code** 通过shell脚本学会了绕过安全限制
资料来源：[README.md:21-28](https://github.com/agent-polis/impact-preview/blob/main/README.md)
### 解决方案架构
```
AI Agent提出行动 → Agent Polis分析影响 → 人工审查差异 → 批准/拒绝 → 执行
```
Agent Polis的工作流程与传统基础设施即代码（IaC）工具的plan阶段非常相似，通过在执行前展示预期的变更，让用户做出知情决策。
资料来源：[README.md:29-40](https://github.com/agent-polis/impact-preview/blob/main/README.md)
## 核心功能模块
Agent Polis主要由以下几个核心模块组成：
| 模块 | 路径 | 功能描述 |
|------|------|----------|
| **actions** | `src/agent_polis/actions/` | 接收AI代理的行动提议，生成影响预览 |
| **governance** | `src/agent_polis/governance/` | 策略评估、提示注入扫描、描述符完整性检查 |
| **events** | `src/agent_polis/events/` | 事件溯源基础设施，维护治理操作审计追踪 |
| **integrations** | `src/agent_polis/integrations/` | 与CrewAI、LangGraph等框架的集成 |
| **simulations** | `src/agent_polis/simulations/` | 沙箱环境模拟测试 |
| **mcp_server** | `src/agent_polis/mcp_server.py` | MCP协议服务器实现 |
资料来源：[src/agent_polis/__init__.py:1-15](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/__init__.py)
## 影响分析系统
### ActionType枚举
系统支持多种行动类型的分析与预览：
```python
class ActionType(str, Enum):
FILE_CREATE = "file_create"
FILE_UPDATE = "file_update"
FILE_DELETE = "file_delete"
SHELL_COMMAND = "shell_command"
DATABASE_QUERY = "database_query"
API_CALL = "api_call"
```
资料来源：[src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
### RiskLevel风险等级
每个行动都会被评估为以下风险等级：
| 风险等级 | 描述 | 图标 |
|----------|------|------|
| `LOW` | 低风险操作，可以安全执行 | 🟢 |
| `MEDIUM` | 中等风险，建议审查 | 🟡 |
| `HIGH` | 高风险操作，需要人工确认 | 🟠 |
| `CRITICAL` | 极高风险，默认阻止执行 | 🔴 |
资料来源：[src/agent_polis/mcp_server.py:30-38](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/mcp_server.py)
### 影响预览数据模型
```python
class ActionPreview(BaseModel):
action_id: str
risk_level: RiskLevel
affected_count: int
risk_factors: list[str]
warnings: list[str]
summary: str
diff: str | None
```
资料来源：[src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
## 治理与策略系统
### PolicySchema策略模式
Agent Polis实现了版本化的策略架构，包含以下核心组件：
```python
class PolicyConfig(BaseModel):
version: str
metadata: PolicyMetadata
defaults: PolicyDefaults
rules: list[PolicyRule]
```
资料来源：[src/agent_polis/governance/policy.py:1-50](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
### PolicyDecision策略决策
策略评估后返回以下决策之一：
| 决策 | 说明 |
|------|------|
| `ALLOW` | 允许执行，无需人工干预 |
| `DENY` | 明确拒绝执行 |
| `REQUIRE_APPROVAL` | 需要人工审批才能执行 |
资料来源：[src/agent_polis/governance/policy.py:18-24](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
### PolicyRule规则匹配
规则支持多种匹配条件：
- `action_types`: 按行动类型匹配
- `path_globs`: 按文件路径glob模式匹配
- `target_contains`: 按目标内容关键词匹配
- `min_risk_level` / `max_risk_level`: 按风险等级范围匹配
规则还具有优先级机制，确保确定性评估：
```python
class PolicyRule(BaseModel):
id: str
decision: PolicyDecision
priority: int = 100
enabled: bool = True
action_types: set[ActionType]
path_globs: list[str]
```
资料来源：[src/agent_polis/governance/policy.py:40-60](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
## 策略预设包
Agent Polis提供了针对不同行业场景的策略预设：
| 预设ID | 适用场景 | 说明 |
|--------|----------|------|
| `startup` | 初创公司 | 宽松但安全的默认规则 |
| `fintech` | 金融科技 | 严格的审计和合规要求 |
| `games` | 游戏开发 | 平衡开发效率与安全性 |
资料来源：[src/agent_polis/governance/__init__.py:10-15](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/__init__.py)
## 安全扫描功能
### 提示注入扫描器
`PromptInjectionScanner`用于检测任务输入和工具元数据中的提示注入攻击和危险指令模式：
```python
class PromptInjectionScanner:
def scan(self, content: str) -> ScanResult:
"""扫描提示注入和危险指令"""
...
```
资料来源：[src/agent_polis/governance/__init__.py:20-25](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/__init__.py)
### 描述符完整性检查
MCP描述符的hash pinning和allowlist机制确保工具描述符未被篡改：
```python
class DescriptorIntegrityChecker:
def check(self, descriptor: dict, policy: DescriptorIntegrityPolicy) -> DescriptorIntegrityResult
```
资料来源：[src/agent_polis/governance/__init__.py:1-10](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/__init__.py)
## MCP服务器集成
Agent Polis实现了Model Context Protocol (MCP)服务器，允许AI客户端在执行前预览影响：
```bash
# 使用uvicorn启动MCP服务器
uvicorn agent_polis.mcp_server:mcp.app --host 0.0.0.0 --port 8000
```
资料来源：[src/agent_polis/mcp_server.py:1-35](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/mcp_server.py)
### MCP工具接口
| 工具名称 | 功能 |
|----------|------|
| `preview_file_create` | 预览文件创建操作 |
| `preview_file_update` | 预览文件更新操作 |
| `preview_file_delete` | 预览文件删除操作 |
| `preview_shell_command` | 预览Shell命令执行 |
资料来源：[src/agent_polis/mcp_server.py:50-100](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/mcp_server.py)
## SDK集成方式
### AgentPolisClient
通过SDK可以轻松集成Agent Polis到现有AI代理工作流：
```python
from agent_polis.sdk import AgentPolisClient
client = AgentPolisClient(api_key="your_api_key")
@client.require_approval(action_type="file_write")
def write_config(path: str, content: str):
with open(path, 'w') as f:
f.write(content)
```
资料来源：[src/agent_polis/sdk.py:1-40](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/sdk.py)
### 异常处理
SDK提供了专门的异常类型：
| 异常类型 | 触发条件 |
|----------|----------|
| `ActionRejectedError` | 行动被人工拒绝 |
| `ActionTimedOutError` | 等待审批超时 |
资料来源：[src/agent_polis/sdk.py:35-45](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/sdk.py)
## CrewAI集成
### AgentPolisTool
为CrewAI代理提供工具和回调集成：
```python
from agent_polis.integrations.crewai import AgentPolisTool, SimulationCallback
# 作为工具使用
tool = AgentPolisTool(api_url="http://localhost:8000", api_key="ap_...")
# 作为回调使用
callback = SimulationCallback(api_url="http://localhost:8000", api_key="ap_...")
```
资料来源：[src/agent_polis/integrations/crewai.py:1-30](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/integrations/crewai.py)
## 事件溯源审计
Agent Polis维护一个不可变的事件审计追踪，记录所有治理操作：
```python
from agent_polis.events import EventStore, EventBus, publish_event, subscribe
# 发布事件
await publish_event(event)
# 订阅事件
subscribe("action:previewed", handler)
# 查询历史
events = await get_events(stream_id="action:123")
```
资料来源：[src/agent_polis/events/__init__.py:1-25](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/events/__init__.py)
## 快速开始
### 1. 检查服务器健康状态
```python
import httpx
response = httpx.get("http://localhost:8000/health")
health = response.json()
print(f"Status: {health['status']}, Version: {health['version']}")
```
### 2. 获取A2A Agent Card
```python
response = httpx.get("http://localhost:8000/.well-known/agent.json")
card = response.json()
print(f"Name: {card['name']}, Protocol: {card['protocol']}")
```
### 3. 创建行动预览
```python
response = httpx.post(
f"{API_URL}/actions/preview",
json={
"action_type": "file_write",
"target": "/path/to/file.yaml",
"payload": {"content": "..."}
},
headers={"Authorization": f"Bearer {API_KEY}"}
)
preview = response.json()
```
资料来源：[examples/quickstart.py:1-60](https://github.com/agent-polis/impact-preview/blob/main/examples/quickstart.py)
## 架构总览
```mermaid
graph TD
subgraph "AI Agent Layer"
A[AI Agent] -->|MCP Protocol| B[MCP Client]
end
subgraph "Agent Polis Core"
B -->|preview_file_create| C[ImpactAnalyzer]
B -->|preview_shell_command| C
C --> D[PolicyEvaluator]
C --> E[PromptInjectionScanner]
C --> F[DescriptorIntegrityChecker]
D --> G[ActionPreview]
end
subgraph "Governance Layer"
D --> H[Policy Rules]
E --> I[Scan Results]
F --> J[Integrity Check]
end
subgraph "Audit Layer"
K[EventStore] -->|append| L[EventBus]
G -->|publish| K
end
subgraph "Data Layer"
M[(SQLite/PostgreSQL)]
N[(Redis Cache)]
end
L --> M
C --> N
```
## 版本信息
当前版本：**v0.2.2**
资料来源：[src/agent_polis/__init__.py:7](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/__init__.py)
## 相关社区Issue
以下是与Agent Polis核心功能相关的开放Issue：
| Issue编号 | 标题 | 优先级 |
|-----------|------|--------|
| [#11](https://github.com/agent-polis/impact-preview/issues/11) | AP-205 Stage 2文档和CI集成示例 | 高 |
| [#10](https://github.com/agent-polis/impact-preview/issues/10) | AP-204 确定性CI评估模式 | 高 |
| [#9](https://github.com/agent-polis/impact-preview/issues/9) | AP-203 机器可读的CI策略报告输出 | 中 |
| [#8](https://github.com/agent-polis/impact-preview/issues/8) | AP-202 策略预设包 | 中 |
| [#7](https://github.com/agent-polis/impact-preview/issues/7) | AP-201 预设基础设施和加载器 | 中 |
资料来源：[社区Issue追踪](https://github.com/agent-polis/impact-preview/issues)
---
## 快速入门指南
### 相关页面
相关主题：[Agent Polis简介](#page-introduction), [MCP服务器集成](#page-mcp-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/agent-polis/impact-preview/blob/main/README.md)
- [src/agent_polis/config.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/config.py)
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
- [src/agent_polis/main.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/main.py)
# 快速入门指南
本文档为 Agent Polis impact-preview 项目提供完整的快速入门指导，帮助开发者快速上手并集成 AI 代理影响预览功能。当前版本为 **v0.2.2**。
---
## 什么是 Agent Polis impact-preview
impact-preview 是 Agent Polis 的核心治理模块，为 AI 代理提供**操作影响预览**能力。在任何操作实际执行前，系统会生成变更预览、风险评估和人机审批流程，确保开发者对代理行为有完全可控的可见性。
**核心价值**：
- 在执行前预览文件变更、数据库操作和 API 调用
- 基于策略的风险评估和自动化决策
- 支持 CI/CD 集成的确定性评估模式
- 可审计的操作历史记录
---
## 环境要求与安装
### 系统要求
| 要求 | 最低版本 |
|------|----------|
| Python | 3.11+ |
| Redis | 7.0+ (可选，用于事件存储) |
### 安装步骤
```bash
# 从 PyPI 安装稳定版本
pip install impact-preview
# 从源码安装开发版本
git clone https://github.com/agent-polis/impact-preview.git
cd impact-preview
pip install -e ".[dev]"
# 安装 pre-commit 钩子
pre-commit install
```
资料来源：[README.md](https://github.com/agent-polis/impact-preview/blob/main/README.md)
---
## 核心配置
impact-preview 支持通过环境变量和配置文件进行配置。
### 环境变量配置
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `APP_ENV` | `development` | 运行环境：`development`/`production` |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接 URL |
| `FREE_TIER_ACTIONS_PER_MONTH` | `100` | 免费额度操作数 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
| `HOST` | `0.0.0.0` | 服务监听地址 |
| `PORT` | `8000` | 服务监听端口 |
资料来源：[src/agent_polis/config.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/config.py)
### 配置示例
```bash
# .env 文件示例
APP_ENV=production
REDIS_URL=redis://redis-server:6379/0
LOG_LEVEL=INFO
```
---
## 核心概念与数据模型
### ActionType 操作类型
系统支持拦截和分析多种类型的操作：
```python
class ActionType(str, Enum):
FILE_WRITE = "file_write" # 文件写入
FILE_DELETE = "file_delete" # 文件删除
FILE_MOVE = "file_move" # 文件移动
FILE_CREATE = "file_create" # 文件创建
DB_QUERY = "db_query" # 数据库查询
DB_EXECUTE = "db_execute" # 数据库执行
API_CALL = "api_call" # API 调用
SHELL_COMMAND = "shell_command" # Shell 命令
CUSTOM = "custom" # 自定义操作
```
资料来源：[src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
### RiskLevel 风险等级
系统采用四级风险评估体系：
| 等级 | 说明 | 典型场景 |
|------|------|----------|
| `LOW` | 低风险 | 只读操作、安全变更 |
| `MEDIUM` | 中等风险 | 非关键文件写入 |
| `HIGH` | 高风险 | 系统配置修改 |
| `CRITICAL` | 极高风险 | 危险命令执行 |
资料来源：[src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
### ActionRequest 请求模型
提交操作预览请求的核心数据结构：
```python
class ActionRequest(BaseModel):
action_type: ActionType # 操作类型
target: str # 操作目标（文件路径、API端点等）
description: str # 操作描述
payload: dict[str, Any] = {} # 操作负载
context: dict[str, Any] = {} # 上下文信息
timeout_seconds: int = 30 # 审批超时时间
auto_approve_if_low_risk: bool = False # 低风险自动审批
```
### ActionPreview 预览结果
系统返回的影响预览数据：
```python
class ActionPreview(BaseModel):
file_changes: list[FileChange] # 文件变更列表
risk_level: RiskLevel # 风险等级
risk_factors: list[str] # 风险因素
summary: str # 变更摘要
affected_count: int # 影响文件数
warnings: list[str] # 警告信息
is_reversible: bool # 是否可逆
reversal_instructions: str | None # 撤销说明
```
---
## 快速集成示例
### 1. 基本使用流程
```mermaid
graph TD
A[创建 ActionRequest] --> B[调用 ImpactAnalyzer]
B --> C{分析结果}
C -->|风险评估完成| D[返回 ActionPreview]
D --> E[基于策略决策]
E --> F{P决策结果}
F -->|allow| G[执行操作]
F -->|deny| H[阻止并记录]
F -->|require_approval| I[等待人工审批]
I -->|审批通过| G
I -->|审批拒绝| H
```
### 2. Python API 使用
```python
from agent_polis.actions import ActionRequest, ActionType, get_analyzer
from agent_polis.config import settings
# 初始化分析器
analyzer = get_analyzer()
# 创建操作请求
request = ActionRequest(
action_type=ActionType.FILE_WRITE,
target="src/config.py",
description="Update application configuration",
payload={"new_content": "DATABASE_URL=postgres://..."}
)
# 获取影响预览
preview = await analyzer.analyze(request)
print(f"Risk Level: {preview.risk_level.value}")
print(f"Affected Files: {preview.affected_count}")
print(f"Summary: {preview.summary}")
```
资料来源：[src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
### 3. 文件变更分析
系统能够智能分析文件变更并生成 unified diff：
```python
from agent_polis.actions.diff import generate_unified_diff, format_diff_summary
# 分析文件变更
changes = generate_file_change(
path="src/main.py",
old_content=original_code,
new_content=modified_code
)
# 生成差异输出
diff = generate_unified_diff(changes)
print(diff)
```
### 4. Shell 命令分析
Shell 命令默认被评估为高风险，系统会检测危险命令模式：
```python
# 危险命令检测
request = ActionRequest(
action_type=ActionType.SHELL_COMMAND,
target="/usr/bin",
payload={"command": "rm -rf /tmp/test"},
description="Clean temp directory"
)
preview = await analyzer.analyze(request)
# Risk Level: CRITICAL
# Risk Factors: ["Shell command execution", "Contains dangerous command: rm"]
```
---
## CI/CD 集成
### 确定性 CI 评估模式
系统提供纯确定性评估模式（AP-204），无需人工干预即可完成策略评估：
```mermaid
graph LR
A[JSON 动作文件] --> B[CI 评估器]
B --> C[策略评估]
B --> D[扫描器检查]
C --> E[生成报告]
D --> E
E --> F{CI 决策}
F -->|deny| G[Exit 1]
F -->|require_approval| H[Exit 2]
F -->|allow| I[Exit 0]
```
### CI 模式使用
```python
from agent_polis.ci import evaluate_actions_from_file
# 评估动作列表
report, exit_code = evaluate_actions_from_file(
actions_file="ci/actions.json",
preset_id="startup", # 使用预置策略
output_path="ci/policy-report.json"
)
print(f"Total Actions: {report.totals.total}")
print(f"Allowed: {report.totals.allowed}")
print(f"Denied: {report.totals.denied}")
```
### CI 报告输出
```json
{
"policy_version": "preset-startup-1",
"totals": {
"total": 10,
"allowed": 7,
"denied": 2,
"require_approval": 1
},
"top_blocking_reasons": [
{"reason": "deny-secrets-in-target", "count": 2}
],
"actions": [
{
"action_id": "...",
"risk_level": "low",
"policy_decision": "allow",
"policy_matched_rule_id": "allow-docs-low"
}
]
}
```
资料来源：[src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
### GitHub Actions 集成示例
```yaml
name: Agent Policy Check
on: [pull_request]
jobs:
policy-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run CI Policy Evaluation
env:
ACTIONS_FILE: .github/actions-to-evaluate.json
run: |
python -m agent_polis.ci \
--actions "$ACTIONS_FILE" \
--preset startup \
--output report.json
- name: Check Results
run: |
if [ $? -eq 1 ]; then
echo "Policy violations detected"
cat report.json
exit 1
fi
```
---
## 策略预置 (Policy Presets)
系统提供开箱即用的策略预置，适应不同场景需求：
| 预置 ID | 适用场景 | 默认决策 | 核心特点 |
|---------|----------|----------|----------|
| `startup` | 创业公司 | `require_approval` | 文档/测试文件轻量审批 |
| `fintech` | 金融科技 | `require_approval` | 禁止操作密钥/凭证 |
| `games` | 游戏开发 | `require_approval` | 资产文件允许中等风险 |
### 加载预置策略
```python
from agent_polis.governance.presets import load_policy_preset, list_policy_presets
# 列出所有可用预置
presets = list_policy_presets()
print(presets)
# 加载指定预置
policy = load_policy_preset("startup")
print(f"Version: {policy.version}")
```
### Startup 预置规则示例
```python
# 文档和测试文件：低/中等风险自动允许
{
"id": "allow-docs-tests-low-medium",
"decision": "allow",
"priority": 50,
"action_types": ["file_write", "file_create"],
"path_globs": ["docs/*", "tests/*"],
"max_risk_level": "medium",
"metadata": {
"rationale": "Low blast-radius, safe to iterate with lighter approval"
}
}
# Shell 命令：必须审批
{
"id": "require-approval-shell",
"decision": "require_approval",
"priority": 75,
"action_types": ["shell_command"]
}
```
资料来源：[src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
---
## 风险评估流程
### 分析器工作原理
```mermaid
flowchart TD
A[接收 ActionRequest] --> B{操作类型判断}
B -->|文件操作| C[读取文件内容]
B -->|Shell命令| D[标记高风险]
B -->|数据库操作| E[SQL 解析]
C --> F[生成变更预览]
D --> G[返回命令预览]
E --> H[生成查询预览]
F --> I[计算风险因素]
G --> I
H --> I
I --> J[确定风险等级]
J --> K[返回 ActionPreview]
```
### 风险因素自动检测
| 操作特征 | 风险增量 |
|----------|----------|
| 目标路径包含 `.env`, `.pem`, `credentials` | 强制 `deny` |
| 危险命令：`rm`, `dd`, `mkfs` | `CRITICAL` |
| `sudo`/`admin` 权限请求 | `CRITICAL` |
| 超过 10 个文件变更 | 风险提升一级 |
| Shell 命令执行 | 高风险 |
资料来源：[src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
---
## 启动服务
### 本地开发服务器
```bash
# 使用 CLI 启动
python -m agent_polis.main
# 或使用 uvicorn
uvicorn agent_polis.main:app --reload --host 0.0.0.0 --port 8000
```
### API 端点
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/actions` | POST | 提交操作请求 |
| `/api/v1/actions/pending` | GET | 获取待审批操作 |
| `/api/v1/agents` | GET | 获取代理信息 |
| `/.well-known/agent.json` | GET | Agent 能力描述 |
### 启动参数
```python
# 启动时配置
uvicorn agent_polis.main:app \
--host "0.0.0.0" \
--port 8000 \
--log-level info
```
---
## 下一步
| 功能模块 | 文档链接 | 说明 |
|----------|----------|------|
| 策略配置 | [策略系统](../governance/policy.md) | 自定义规则和评估器 |
| 审计系统 | [事件溯源](../events/audit.md) | 完整操作审计链 |
| 扫描器 | [提示注入检测](../governance/scanner.md) | 安全风险扫描 |
| 预设开发 | [自定义预设](../governance/presets.md) | 创建业务特定策略 |
---
## 常见问题
### Q: 如何禁用 Redis 依赖？
A: 系统支持内存事件存储，在开发环境下无需 Redis。生产环境建议使用 Redis 以支持分布式部署。
### Q: CI 模式下返回码规则是什么？
A: `0` = 全部允许，`1` = 存在拒绝，`2` = 需要审批。
### Q: 能否自定义风险等级阈值？
A: 可以通过修改策略规则中的 `min_risk_level` 和 `max_risk_level` 实现。
---
*最后更新于 v0.2.2 · [提交反馈](https://github.com/agent-polis/impact-preview/issues)*
---
## 系统架构
### 相关页面
相关主题：[核心模块详解](#page-core-modules), [动作类型与数据模型](#page-action-types)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/main.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/main.py)
- [src/agent_polis/actions/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/__init__.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
- [src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
- [src/agent_polis/events/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/events/__init__.py)
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/governance/prompt_scanner.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/prompt_scanner.py)
# 系统架构
Agent Polis Impact Preview 是一个为 AI 代理提供治理和协调能力的平台。其核心功能是在代理执行操作之前生成影响预览，并在 CI/CD 环境中提供确定性的策略评估。本页面详细介绍系统的整体架构设计、核心模块及其交互关系。
## 架构概览
Agent Polis 采用分层架构设计，核心组件包括：**动作模块**（Actions）、**治理模块**（Governance）、**事件模块**（Events）、**模拟模块**（Simulations）、**CI 集成模块**（CI）以及 **MCP 服务器**。系统基于 FastAPI 构建，提供 RESTful API 和 MCP 协议两种交互方式。
```mermaid
graph TB
subgraph "API Layer"
MCP[MCP Server
mcp_server.py]
API[FastAPI App
main.py]
CLI[CLI Entry Point]
end
subgraph "Core Modules"
Actions[Actions Module
actions/]
Governance[Governance Module
governance/]
Events[Events Module
events/]
Simulations[Simulations Module
simulations/]
CI[CI Module
ci.py]
end
subgraph "Data Models"
Models[Models
models.py]
Policies[Policy Configs
presets.py]
end
MCP --> Actions
API --> Actions
API --> Simulations
Actions --> Governance
Actions --> Events
Actions --> Models
Governance --> Policies
CI --> Actions
CI --> Governance
```
## 核心模块
### 动作模块（Actions Module）
动作模块是 Agent Polis 的核心，负责接收代理提出的操作请求、生成影响预览并管理审批工作流。该模块位于 `src/agent_polis/actions/`，包含以下子模块：
| 子模块 | 文件 | 职责 |
|--------|------|------|
| models | [models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py) | 定义 ActionRequest、ActionPreview、RiskLevel 等核心数据模型 |
| analyzer | [analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py) | 分析不同类型操作的影响和风险 |
| diff | diff.py | 生成文件变更的统一差异格式 |
| service | [service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py) | 动作服务，处理审计跟踪和策略评估 |
| router | router.py | 动作相关的 API 路由 |
资料来源：[src/agent_polis/actions/__init__.py:1-47](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/__init__.py)
### 治理模块（Governance Module）
治理模块负责策略的加载、解析和评估。该模块位于 `src/agent_polis/governance/`，包含策略配置、预设策略包和提示注入扫描器。
| 组件 | 文件 | 职责 |
|------|------|------|
| policy | [policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py) | 策略模式解析器和确定性评估器 |
| presets | [presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py) | 预定义策略包（startup、fintech、games） |
| prompt_scanner | [prompt_scanner.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/prompt_scanner.py) | 提示注入和危险指令扫描器 |
资料来源：[src/agent_polis/governance/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/__init__.py)
### 事件模块（Events Module）
事件模块提供事件溯源基础设施，维护所有治理操作的不可变审计跟踪。
```mermaid
graph LR
subgraph "Event System"
Store[EventStore
持久化]
Bus[EventBus
发布-订阅]
Events[DomainEvent
领域事件]
end
Store --> Bus
Bus --> Events
```
| 导出组件 | 说明 |
|----------|------|
| EventStore | 事件持久化存储 |
| EventBus | 发布-订阅总线 |
| DomainEvent | 领域事件基类 |
| append_event / get_events | 事件追加和查询函数 |
| publish_event / subscribe | 事件发布和订阅函数 |
资料来源：[src/agent_polis/events/__init__.py:1-23](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/events/__init__.py)
### CI 模块（CI Module）
CI 模块提供非交互式的确定性评估模式，专为 CI/CD 环境设计。该模块通过 `generate_ci_report()` 函数实现，接收动作列表和策略配置，返回机器可读的策略报告和稳定的退出码。
```mermaid
graph TB
CI[CI Mode Entry
generate_ci_report]
Analyzer[ImpactAnalyzer]
Evaluator[PolicyEvaluator]
Scanner[PromptInjectionScanner]
Report[CIPolicyReport
+ Exit Code]
CI --> Analyzer
CI --> Evaluator
CI --> Scanner
Analyzer --> Report
Evaluator --> Report
Scanner --> Report
```
**退出码规范：**
| 退出码 | 含义 |
|--------|------|
| 0 | 所有操作均被允许 |
| 2 | 至少一个操作需要审批 |
| 3 | 至少一个操作被拒绝 |
资料来源：[src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
## 数据模型
### 操作类型（ActionType）
系统支持的操作类型枚举定义于 `src/agent_polis/actions/models.py`：
| 枚举值 | 说明 |
|--------|------|
| FILE_WRITE | 文件写入 |
| FILE_DELETE | 文件删除 |
| FILE_MOVE | 文件移动 |
| FILE_CREATE | 文件创建 |
| DB_QUERY | 数据库查询 |
| DB_EXECUTE | 数据库执行 |
| API_CALL | API 调用 |
| SHELL_COMMAND | Shell 命令执行 |
| CUSTOM | 自定义操作类型 |
资料来源：[src/agent_polis/actions/models.py:15-27](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
### 风险等级（RiskLevel）
| 枚举值 | 说明 |
|--------|------|
| LOW | 读取操作、安全变更 |
| MEDIUM | 对非关键文件的写操作 |
| HIGH | 对关键文件的操作 |
| CRITICAL | 系统级或不可逆的操作 |
资料来源：[src/agent_polis/actions/models.py:35-40](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
### 策略决策（PolicyDecision）
| 枚举值 | 说明 |
|--------|------|
| ALLOW | 允许执行 |
| DENY | 拒绝执行 |
| REQUIRE_APPROVAL | 需要人工审批 |
资料来源：[src/agent_polis/governance/policy.py:16-22](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
### 扫描严重级别（ScanSeverity）
| 枚举值 | 说明 |
|--------|------|
| LOW | 低风险 |
| MEDIUM | 中等风险 |
| HIGH | 高风险 |
| CRITICAL | 严重风险 |
资料来源：[src/agent_polis/governance/prompt_scanner.py:17-23](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/prompt_scanner.py)
## 影响分析流程
影响分析器（ImpactAnalyzer）是动作模块的核心组件，负责分析不同类型操作的影响和风险等级。
```mermaid
graph TB
Request[ActionRequest
操作请求]
Router[Analyze Router
分析路由]
AW[文件分析
_analyze_file_write]
AD[删除分析
_analyze_file_delete]
AS[Shell分析
_analyze_shell_command]
ADB[数据库分析
_analyze_db_operation]
Risk[风险评估
_assess_risk]
Preview[ActionPreview
影响预览]
Request --> Router
Router --> AW
Router --> AD
Router --> AS
Router --> ADB
AW --> Risk
AD --> Risk
AS --> Risk
ADB --> Risk
Risk --> Preview
```
分析器支持以下操作类型的分析方法：
- `_analyze_file_write()` - 文件写入分析
- `_analyze_file_delete()` - 文件删除分析
- `_analyze_file_create()` - 文件创建分析
- `_analyze_shell_command()` - Shell 命令分析
- `_analyze_db_operation()` - 数据库操作分析
资料来源：[src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
## 策略评估流程
策略评估器（PolicyEvaluator）实现确定性规则优先级机制，对操作请求进行策略匹配和决策。
```mermaid
graph TB
EvalRequest[评估请求
ActionRequest + RiskLevel]
MatchRules[规则匹配
Predicate Matching]
PrioritySort[优先级排序
Priority + Specificity]
Decision[决策结果
Decision + Rule ID + Trace]
EvalRequest --> MatchRules
MatchRules --> PrioritySort
PrioritySort --> Decision
```
**规则匹配谓词：**
| 谓词字段 | 说明 |
|----------|------|
| action_types | 操作类型集合 |
| path_globs | 路径通配符列表 |
| target_contains | 目标包含关键词 |
| min_risk_level | 最小风险等级 |
| max_risk_level | 最大风险等级 |
资料来源：[src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
## 策略预设包
系统提供三个预定义的策略包，适用于不同的行业场景：
### Startup（初创企业）
针对快速迭代的开发环境，文档和测试变更使用较低的风险阈值：
- 默认决策：`require_approval`
- 文档变更允许低/中风险
- Shell 命令需要审批
### Fintech（金融科技）
针对金融行业的高合规要求：
- 默认决策：`require_approval`
- **拒绝**包含密钥、凭证、密码等敏感信息的操作
- **拒绝**任何评估为 CRITICAL 风险的操作
- 数据库写入需要审批
- 文档变更限制为低风险
### Games（游戏开发）
针对游戏开发中的创意工作流：
- 默认决策：`require_approval`
- **拒绝**密钥和凭证操作
- 允许低/中风险的资产和文档变更
- 允许低/中风险的测试变更
资料来源：[src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
## 审计跟踪
审计跟踪系统通过事件溯源模式记录所有治理操作。每个审计记录包含：
| 字段 | 说明 |
|------|------|
| decision | 策略决策结果 |
| reason_id | 匹配规则 ID |
| trace | 决策调试跟踪信息 |
| scanner_findings | 扫描器发现列表 |
| max_severity | 扫描器最高严重级别 |
审计记录与动作预览一起存储在事件存储中，支持查询和回放。
资料来源：[src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
## API 路由结构
Agent Polis 通过 FastAPI 应用提供 REST API：
| 前缀 | 标签 | 说明 |
|------|------|------|
| /api/v1/agents | Agents | 代理管理 |
| /api/v1/actions | Actions | 动作和影响预览 |
| /api/v1/actions/pending | Actions | 待审批动作 |
| /api/v1/simulations | Legacy - Simulations | 模拟功能（遗留） |
| /a2a | Legacy - A2A | A2A 协议支持（遗留） |
**应用元信息：**
```python
{
"name": "Agent Polis",
"description": "Impact preview for AI agent actions",
"version": "0.2.2",
"protocol": "a2a/1.0",
"capabilities": ["impact_preview", "action_approval", "file_diff", "audit_trail"]
}
```
资料来源：[src/agent_polis/main.py:1-60](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/main.py)
## CI 策略报告
CI 策略报告（CIPolicyReport）提供机器可读的 JSON 输出，包含：
```mermaid
graph TB
Report[CIPolicyReport]
Header[schema_version
policy_version]
Totals[totals
allow/require_approval/deny 计数]
TopReasons[top_blocking_reasons
前10个阻塞原因]
Actions[actions
每个动作的详细报告]
Report --> Header
Report --> Totals
Report --> TopReasons
Report --> Actions
```
**报告架构版本：** `1`
资料来源：[src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
## 配置管理
系统配置通过 `src/agent_polis/config.py` 中的 Settings 类管理：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| host | str | "0.0.0.0" | 服务监听地址 |
| port | int | 8000 | 服务监听端口 |
| app_env | str | "development" | 运行环境 |
| log_level | str | "INFO" | 日志级别 |
| log_format | str | "json" | 日志格式 |
配置支持环境变量注入，具有开发/生产环境判断属性。
资料来源：[src/agent_polis/config.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/config.py)
## MCP 服务器集成
MCP 服务器（`src/agent_polis/mcp_server.py`）提供 MCP 协议支持，可与支持 MCP 的 IDE 和工具集成。当前实现的 MCP 工具包括：
- `preview_file_create` - 预览文件创建
- `preview_file_delete` - 预览文件删除
- 更多工具可通过 MCP 协议扩展
MCP 工具返回格式化的 Markdown 预览，包含：
- 目标路径和操作类型
- 风险等级（带表情符号）
- 风险因素列表
- 警告信息
- 变更摘要
## 相关社区话题
根据社区反馈，以下功能受到重点关注：
| Issue | 主题 | 状态 |
|-------|------|------|
| [AP-101](https://github.com/agent-polis/impact-preview/issues/1) | 策略模式和解析器 | 已实现 |
| [AP-102](https://github.com/agent-polis/impact-preview/issues/2) | 确定性优先级评估器 | 已实现 |
| [AP-103](https://github.com/agent-polis/impact-preview/issues/3) | MCP 描述符完整性检查 | 已实现 |
| [AP-104](https://github.com/agent-polis/impact-preview/issues/4) | 提示注入扫描器 | 已实现 |
| [AP-201](https://github.com/agent-polis/impact-preview/issues/7) | 预设基础设施和加载器 | 已实现 |
| [AP-202](https://github.com/agent-polis/impact-preview/issues/8) | 策略预设包 | 已实现 |
| [AP-203](https://github.com/agent-polis/impact-preview/issues/9) | 机器可读 CI 策略报告 | 已实现 |
| [AP-204](https://github.com/agent-polis/impact-preview/issues/10) | 确定性 CI 评估模式 | 已实现 |
| [AP-205](https://github.com/agent-polis/impact-preview/issues/11) | Stage 2 文档和 CI 集成示例 | 进行中 |
## 版本信息
当前版本：**v0.2.2**
路线图：
| 版本 | 重点 | 状态 |
|------|------|------|
| v0.2.0 | 文件操作预览 | 当前 |
| v0.3.0 | 数据库操作预览 | 计划中 |
| v0.4.0 | API 调用预览 | 计划中 |
| v0.5.0 | IDE 集成（Cursor、VS Code） | 计划中 |
| v1.0.0 | 生产就绪 | 计划中 |
资料来源：[README.md](https://github.com/agent-polis/impact-preview/blob/main/README.md)
---
## 核心模块详解
### 相关页面
相关主题：[系统架构](#page-architecture), [风险评估系统](#page-risk-assessment)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
- [src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [src/agent_polis/governance/prompt_scanner.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/prompt_scanner.py)
- [src/agent_polis/events/store.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/events/store.py)
- [src/agent_polis/events/bus.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/events/bus.py)
# 核心模块详解
## 概述
impact-preview 是一个面向 AI 代理的治理与协调层，为代理操作提供影响预览、策略评估和审批工作流。v0.2.2 版本作为当前稳定发布版，实现了文件操作预览、策略评估、审计追踪等核心功能。资料来源：[README.md]()
项目采用模块化架构，主要包含以下核心子系统：
| 模块 | 路径 | 核心职责 |
|------|------|---------|
| Actions | `agent_polis.actions` | 动作接收、影响分析、审批工作流 |
| Governance | `agent_polis.governance` | 策略引擎、提示注入扫描器、预设管理 |
| Events | `agent_polis.events` | 事件溯源、审计追踪 |
| CI | `agent_polis.ci` | 确定性 CI 评估模式 |
| Simulations | `agent_polis.simulations` | 沙箱模拟测试 |
| MCP Server | `agent_polis.mcp_server` | MCP 协议工具暴露 |
---
## 动作模块 (Actions)
### 模块架构
动作模块是 impact-preview 的核心，处理 AI 代理提出的操作请求并生成影响预览。资料来源：[src/agent_polis/actions/__init__.py:1-48]()
```mermaid
graph TD
A[ActionRequest] --> B[ImpactAnalyzer]
B --> C[ActionPreview]
C --> D[ActionService]
D --> E[PolicyEvaluator]
D --> F[PromptScanner]
E --> G[PolicyDecision]
F --> H[ScanResult]
G --> I[审计记录]
H --> I
D --> J[事件发布]
```
### 核心模型
#### ActionRequest
动作请求是代理发起操作的核心数据结构，包含操作类型、目标路径、描述和负载信息。资料来源：[src/agent_polis/actions/models.py:1-60]()
```python
class ActionRequest(BaseModel):
action_type: ActionType # 操作类型
target: str # 目标路径/资源
description: str # 操作描述
payload: dict[str, Any] = Field(default_factory=dict) # 附加负载
context: dict[str, Any] = Field(default_factory=dict) # 上下文元数据
timeout_seconds: int = 300 # 超时时间
auto_approve_if_low_risk: bool = False # 低风险自动审批
callback_url: str | None = None # 回调URL
```
#### ActionType 枚举
支持的操作类型覆盖了常见的文件、数据库和系统操作。资料来源：[src/agent_polis/actions/models.py:14-30]()
| 操作类型 | 说明 |
|----------|------|
| `FILE_WRITE` | 写入文件 |
| `FILE_DELETE` | 删除文件 |
| `FILE_MOVE` | 移动文件 |
| `FILE_CREATE` | 创建文件 |
| `DB_QUERY` | 数据库查询 |
| `DB_EXECUTE` | 数据库执行 |
| `API_CALL` | API 调用 |
| `SHELL_COMMAND` | Shell 命令 |
| `CUSTOM` | 自定义类型 |
#### RiskLevel 风险等级
系统使用四级风险评估体系，与策略引擎联动。资料来源：[src/agent_polis/actions/models.py:40-45]()
| 风险等级 | 说明 | 典型场景 |
|----------|------|----------|
| `LOW` | 低风险 | 只读操作、安全变更 |
| `MEDIUM` | 中风险 | 非关键文件写入 |
| `HIGH` | 高风险 | 敏感文件修改 |
| `CRITICAL` | 极高风险 | 系统级操作、危险命令 |
#### ActionPreview 预览结果
影响分析的核心输出，包含变更详情和风险评估。资料来源：[src/agent_polis/actions/models.py:60-80]()
```python
class ActionPreview(BaseModel):
file_changes: list[FileChange] # 文件变更列表
risk_level: RiskLevel # 综合风险等级
risk_factors: list[str] # 风险因子列表
summary: str # 变更摘要
affected_count: int # 影响文件数
warnings: list[str] # 警告信息
is_reversible: bool # 是否可逆
reversal_instructions: str | None # 回滚说明
```
### ImpactAnalyzer 影响分析器
分析器是动作模块的核心组件，负责根据请求类型执行不同的分析策略。资料来源：[src/agent_polis/actions/analyzer.py:1-100]()
```mermaid
graph LR
A[ActionRequest] --> B{action_type判定}
B -->|file_*| C[_analyze_file_operation]
B -->|shell_command| D[_analyze_shell_command]
B -->|db_*| E[_analyze_db_operation]
B -->|api_call| F[_analyze_api_call]
C --> G[ActionPreview]
D --> G
E --> G
F --> G
```
#### 文件操作分析
文件操作分析是最成熟的功能，支持 unified diff 生成和行级变更追踪。资料来源：[src/agent_polis/actions/analyzer.py:30-120]()
- **变更检测**：读取目标文件的当前内容，与 payload 中的新内容对比
- **差异生成**：使用 difflib 生成 unified diff 格式的变更
- **风险评估**：根据变更位置（系统目录、配置文件）和大小计算风险等级
- **可逆性判断**：新文件默认可逆，已存在文件的覆盖操作标记为不可逆
#### Shell 命令分析
Shell 命令具有固有的高风险特性，系统采取保守策略。资料来源：[src/agent_polis/actions/analyzer.py:140-180]()
| 危险命令模式 | 风险提升 |
|-------------|----------|
| `rm`, `rmdir`, `del`, `format`, `dd`, `mkfs` | 提升至 `CRITICAL` |
| `sudo`, `admin` | 提升至 `CRITICAL` |
| `>` (重定向) | 提升至 `HIGH` |
**注意**：Shell 命令无法完全预览，仅显示命令本身作为摘要。
### ActionService 动作服务
服务层负责协调动作的完整生命周期，包括创建、分析、策略评估和事件发布。资料来源：[src/agent_polis/actions/service.py:1-80]()
#### 动作提交流程
```mermaid
sequenceDiagram
participant Agent
participant Service as ActionService
participant Analyzer as ImpactAnalyzer
participant Scanner as PromptScanner
participant Policy as PolicyEvaluator
participant Store as EventStore
Agent->>Service: submit(action_request)
Service->>Analyzer: analyze(request)
Analyzer-->>Service: ActionPreview
Service->>Scanner: scan_action_request(request)
Scanner-->>Service: ScanResult
Service->>Policy: evaluate(policy, request, risk_level)
Policy-->>Service: PolicyResult
Service->>Store: emit events
alt auto_approve_if_low_risk && LOW
Service->>Service: auto approve
end
Service-->>Agent: Action, ActionPreview
```
#### 自动审批机制
当请求设置 `auto_approve_if_low_risk=True` 且分析结果为 `LOW` 风险时，动作自动转为已批准状态。资料来源：[src/agent_polis/actions/service.py:60-75]()
```python
if request.auto_approve_if_low_risk and preview.risk_level == RiskLevel.LOW:
action.status = "approved"
action.approved_at = datetime.now(UTC)
await self._emit_approved_event(action, agent, auto=True)
```
---
## 治理模块 (Governance)
治理模块是策略引擎的核心，提供策略解析、规则匹配、风险评估和提示注入检测功能。资料来源：[src/agent_polis/governance/__init__.py]()
### Policy 策略系统
#### 策略架构
策略系统实现了版本化的策略模式，包含 `version`、`rules`、`defaults`、`metadata` 四个顶层字段。资料来源：[src/agent_polis/governance/policy.py:1-50]()
```mermaid
graph TD
A[Policy] --> B[PolicyDefaults]
A --> C[list]
A --> D[metadata]
C --> E{规则匹配}
E -->|命中| F[PolicyDecision]
E -->|未命中| B
F --> G[PolicyResult]
B --> G
```
#### 策略决策类型
| 决策 | 说明 | 使用场景 |
|------|------|----------|
| `ALLOW` | 允许执行 | 低风险、可逆操作 |
| `DENY` | 拒绝执行 | 危险操作、敏感资源 |
| `REQUIRE_APPROVAL` | 需要人工审批 | 中高风险操作 |
#### PolicyRule 规则结构
规则支持多维度的匹配条件，按优先级顺序评估。资料来源：[src/agent_polis/governance/policy.py:60-90]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | str | 规则唯一标识 |
| `decision` | PolicyDecision | 匹配后执行的决策 |
| `priority` | int | 优先级（数值越小优先级越高） |
| `action_types` | set[ActionType] | 匹配的操作类型 |
| `path_globs` | list[str] | 路径 glob 模式匹配 |
| `target_contains` | list[str] | 目标路径包含的关键字 |
| `min_risk_level` | RiskLevel | 最低风险等级门槛 |
| `max_risk_level` | RiskLevel | 最高风险等级上限 |
| `enabled` | bool | 规则是否启用 |
| `metadata` | dict | 规则的附加元数据 |
#### 确定性优先级
规则匹配遵循确定性优先级，保证相同输入产生相同输出。资料来源：[src/agent_polis/governance/policy.py:30-45]()
```python
_RISK_ORDER = {
RiskLevel.LOW: 0,
RiskLevel.MEDIUM: 1,
RiskLevel.HIGH: 2,
RiskLevel.CRITICAL: 3,
}
def _risk_severity(level: RiskLevel) -> int:
return _RISK_ORDER[level]
```
### Policy Presets 策略预设
预设系统提供了开箱即用的行业策略模板，降低配置门槛。资料来源：[src/agent_polis/governance/presets.py:1-100]()
#### 预设类型
| 预设ID | 适用场景 | 默认决策 | 特点 |
|--------|----------|----------|------|
| `startup` | 初创团队 | `require_approval` | 宽松的文档/测试限制 |
| `fintech` | 金融科技 | `require_approval` | 严格密钥管理 |
| `games` | 游戏开发 | `require_approval` | 资源文件友好 |
#### startup 预设规则
```python
"startup": {
"version": "preset-startup-1",
"defaults": {"decision": "require_approval"},
"rules": [
# 高优先级：拒绝密钥和敏感资源
{"decision": "deny", "priority": 0, "target_contains": [".env", ".ssh", "credentials"]},
# 中优先级：文档/测试文件自动允许
{"decision": "allow", "priority": 50, "path_globs": ["docs/*", "tests/*"], "max_risk_level": "medium"},
# 中优先级：Shell命令需审批
{"decision": "require_approval", "priority": 75, "action_types": ["shell_command"]},
]
}
```
#### fintech 预设规则
金融场景预设更严格，特别关注密钥和数据库操作。资料来源：[src/agent_polis/governance/presets.py:30-70]()
```python
"fintech": {
"version": "preset-fintech-1",
"defaults": {"decision": "require_approval"},
"rules": [
# 零容忍密钥访问
{"decision": "deny", "priority": 0, "target_contains": [".env", ".pem", "api_key", "secret_key"]},
# 拒绝所有 CRITICAL 风险操作
{"decision": "deny", "priority": 5, "min_risk_level": "critical"},
# 数据库写入需审批
{"decision": "require_approval", "priority": 10, "action_types": ["db_execute"]},
# 文档仅允许低风险
{"decision": "allow", "priority": 50, "path_globs": ["docs/*"], "max_risk_level": "low"},
]
}
```
### Prompt Scanner 提示注入扫描器
扫描器负责检测动作请求中的潜在提示注入和危险指令。资料来源：[src/agent_polis/governance/prompt_scanner.py:1-60]()
#### 设计原则
- **保守扫描**：避免递归遍历，防止深度攻击
- **CPU 安全**：限制扫描文本量，防止资源耗尽攻击
- **机器可读**：输出结构化的 reason_id，便于审计
#### 扫描结果模型
```python
class ScanResult(BaseModel):
findings: list[ScanFinding]
def max_severity(self) -> ScanSeverity:
"""返回最高严重级别"""
if not self.findings:
return ScanSeverity.LOW
return max(self.findings, key=lambda f: _SEVERITY_ORDER[f.severity]).severity
```
#### 严重级别映射
| 扫描严重级别 | 映射到风险等级 |
|--------------|----------------|
| `LOW` | `LOW` |
| `MEDIUM` | `MEDIUM` |
| `HIGH` | `HIGH` |
| `CRITICAL` | `CRITICAL` |
---
## 事件系统 (Events)
事件系统基于事件溯源模式，提供不可变的审计追踪能力。资料来源：[src/agent_polis/events/__init__.py:1-25]()
### 核心组件
| 组件 | 职责 |
|------|------|
| `EventStore` | 事件持久化存储 |
| `EventBus` | 事件发布订阅 |
| `DomainEvent` | 领域事件基类 |
```mermaid
graph LR
A[DomainEvent] --> B[EventBus.publish]
B --> C[EventStore.append]
C --> D[订阅者消费]
D --> E[投影重建]
```
### 领域事件类型
事件系统追踪所有治理相关的关键操作：
| 事件类型 | 触发时机 |
|----------|----------|
| `ActionProposed` | 动作提交 |
| `ActionPreviewGenerated` | 预览生成 |
| `ActionApproved` | 动作批准 |
| `ActionRejected` | 动作拒绝 |
| `PolicyEvaluated` | 策略评估完成 |
| `ScanCompleted` | 扫描完成 |
---
## CI 集成模块
CI 模块提供确定性评估模式，适合自动化流水线集成。资料来源：[src/agent_polis/ci.py:1-50]()
### CI 模式特性
根据社区 issue #10 和 #204 的设计要求：
- **无提示路径**：确保 CI 模式下不触发任何交互式提示
- **稳定退出码**：根据决策结果返回确定性退出码
- **机器可读报告**：生成结构化 JSON 格式的策略评估报告
### CIPolicyReport 结构
```python
class CIPolicyReport(BaseModel):
policy_version: str
totals: CITotalsSummary
top_blocking_reasons: list[CIReasonCount]
actions: list[CIActionReport]
```
### 退出码映射
| 决策结果 | 退出码 |
|----------|--------|
| `ALLOW` | 0 |
| `DENY` | 1 |
| `REQUIRE_APPROVAL` | 2 |
---
## 模拟服务 (Simulations)
模拟服务提供沙箱环境，允许在提交真实操作前测试场景。资料来源：[src/agent_polis/simulations/__init__.py:1-30]()
### 模拟流程
```mermaid
graph TD
A[SimulationRunRequest] --> B[SimulationService.run]
B --> C[沙箱环境准备]
C --> D[动作执行模拟]
D --> E[影响分析]
E --> F[SimulationResult]
F --> G[审计记录]
```
模拟服务是 Agent Polis 区别于其他治理方案的核心差异化特性，允许在不产生实际副作用的情况下验证操作风险。
---
## MCP 服务器
MCP 服务器模块暴露协议兼容的工具接口。资料来源：[src/agent_polis/mcp_server.py:1-80]()
### 可用工具
| 工具 | 功能 |
|------|------|
| `preview_file_write` | 预览文件写入 |
| `preview_file_create` | 预览文件创建 |
| `preview_file_delete` | 预览文件删除 |
每个工具都返回格式化的 Markdown 报告，包含风险等级、变更摘要和警告信息。
---
## 模块间依赖关系
```mermaid
graph BT
Actions[Actions Module] --> Models[Actions Models]
Actions --> Governance[Governance Module]
Governance --> Policy[Policy Engine]
Governance --> Scanner[Prompt Scanner]
Actions --> Events[Events Module]
CI[CI Module] --> Actions
CI --> Governance
Simulations[Simulations] --> Actions
Simulations --> Events
MCP[MCP Server] --> Actions
```
---
## 版本信息
当前文档基于 **v0.2.2** 版本。资料来源：[src/agent_polis/main.py:30-40]()
| 版本 | 主要功能 |
|------|----------|
| v0.2.0 | 文件操作预览（当前） |
| v0.3.0 | 数据库操作预览（规划中） |
| v0.4.0 | API 调用预览（规划中） |
| v0.5.0 | IDE 集成（规划中） |
| v1.0.0 | 生产就绪（规划中） |
---
## 动作类型与数据模型
### 相关页面
相关主题：[风险评估系统](#page-risk-assessment), [审批工作流](#page-approval-workflow)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/actions/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/__init__.py)
- [src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
# 动作类型与数据模型
本文档介绍 Agent Polis 中动作（Action）系统的核心数据模型和类型定义。动作系统是影响预览（Impact Preview）功能的基石，负责接收 AI 代理的拟议操作、生成变更预览、管理审批工作流并执行已批准的操作。
## 系统概述
动作模块是 Agent Polis 的核心组件，提供了拦截和预览 AI 代理操作的完整能力。当代理提出操作请求时，系统会：
1. 接收并解析操作请求（ActionRequest）
2. 分析操作的影响范围（ImpactAnalyzer）
3. 生成风险评估和预览（ActionPreview）
4. 根据策略进行决策（PolicyEvaluator）
5. 记录审计轨迹（AuditTrail）
资料来源：[src/agent_polis/actions/__init__.py:1-16]()
```mermaid
graph LR
A[代理请求] --> B[ActionRequest]
B --> C[ImpactAnalyzer]
C --> D[ActionPreview]
D --> E[PolicyEvaluator]
E --> F[审批决策]
B --> G[AuditTrail]
G --> H[扫描器]
H --> D
```
## 动作类型（ActionType）
`ActionType` 是一个字符串枚举，定义了 Agent Polis 能够拦截和管理的所有操作类型。
资料来源：[src/agent_polis/actions/models.py:21-35]()
| 枚举值 | 说明 | 示例场景 |
|--------|------|----------|
| `FILE_WRITE` | 文件写入操作 | 修改现有文件内容 |
| `FILE_DELETE` | 文件删除操作 | 删除指定路径的文件 |
| `FILE_MOVE` | 文件移动/重命名 | 移动文件位置或重命名 |
| `FILE_CREATE` | 文件创建操作 | 创建新文件 |
| `DB_QUERY` | 数据库查询 | SELECT 语句 |
| `DB_EXECUTE` | 数据库执行操作 | INSERT/UPDATE/DELETE |
| `API_CALL` | API 调用 | 外部 HTTP 请求 |
| `SHELL_COMMAND` | Shell 命令执行 | 系统命令行操作 |
| `CUSTOM` | 自定义操作类型 | 扩展类型的预留值 |
这些动作类型在策略评估中被用于规则匹配，不同的动作类型对应不同的风险级别和审批要求。
资料来源：[src/agent_polis/governance/presets.py:20-80]()
## 风险等级（RiskLevel）
`RiskLevel` 枚举定义了操作的风险评估级别，用于确定默认审批流程和策略匹配。
资料来源：[src/agent_polis/actions/models.py:48-52]()
| 枚举值 | 含义 | 典型场景 |
|--------|------|----------|
| `LOW` | 低风险操作 | 读取操作、安全变更 |
| `MEDIUM` | 中等风险 | 对非关键文件的写入操作 |
| `HIGH` | 高风险 | 可能影响系统稳定性的操作 |
| `CRITICAL` | 极高风险 | 涉及敏感数据或不可逆操作 |
### 风险等级顺序
系统内部定义了风险等级的优先级顺序，数值越高风险越大：
```python
_RISK_ORDER = {
RiskLevel.LOW: 0,
RiskLevel.MEDIUM: 1,
RiskLevel.HIGH: 2,
RiskLevel.CRITICAL: 3,
}
```
这个顺序在策略规则验证中被使用，用于比较 `min_risk_level` 和 `max_risk_level` 约束。
资料来源：[src/agent_polis/governance/policy.py:26-29]()
## 审批状态（ApprovalStatus）
`ApprovalStatus` 枚举定义了动作在审批工作流中的生命周期状态。
资料来源：[src/agent_polis/actions/models.py:38-46]()
```mermaid
stateDiagram-v2
[*] --> PENDING: 新建请求
PENDING --> APPROVED: 人工批准
PENDING --> REJECTED: 人工拒绝
PENDING --> TIMED_OUT: 超时未响应
PENDING --> CANCELLED: 代理取消
APPROVED --> EXECUTED: 执行成功
APPROVED --> FAILED: 执行失败
APPROVED --> MODIFIED: 人工修改后批准
MODIFIED --> EXECUTED: 执行已修改内容
```
| 状态值 | 说明 | 适用场景 |
|--------|------|----------|
| `PENDING` | 等待人工审核 | 默认初始状态 |
| `APPROVED` | 已批准 | 用户同意执行 |
| `REJECTED` | 已拒绝 | 用户拒绝执行 |
| `MODIFIED` | 修改后批准 | 用户修改参数后批准 |
| `EXECUTED` | 已执行 | 操作成功完成 |
| `FAILED` | 执行失败 | 执行过程中出错 |
| `TIMED_OUT` | 超时 | 规定时间内未响应 |
| `CANCELLED` | 已取消 | 代理撤回了请求 |
## 核心数据模型
### ActionRequest
`ActionRequest` 是代理发起操作请求时提交的数据结构，包含操作的完整上下文信息。
资料来源：[src/agent_polis/actions/models.py:55-75]()
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `id` | UUID | 是 | 动作唯一标识符 |
| `action_type` | ActionType | 是 | 操作类型枚举值 |
| `target` | str | 是 | 操作目标（如文件路径、URL等） |
| `description` | str | 是 | 操作描述 |
| `payload` | dict | 否 | 操作的额外数据负载 |
| `context` | dict | 否 | 执行上下文信息 |
| `timeout_seconds` | int | 否 | 超时时间（秒） |
| `auto_approve_if_low_risk` | bool | 否 | 低风险自动批准 |
| `callback_url` | str | 否 | 完成回调通知地址 |
### ActionPreview
`ActionPreview` 是系统在分析请求后生成的影响预览，包含风险评估和变更摘要。
资料来源：[src/agent_polis/actions/models.py:100-130]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `risk_level` | RiskLevel | 评估后的风险等级 |
| `risk_factors` | list[str] | 风险因素列表 |
| `affected_count` | int | 受影响的文件/资源数量 |
| `warnings` | list[str] | 警告信息列表 |
| `summary` | str | 操作摘要描述 |
| `estimated_impact` | str | 预估影响范围 |
### FileChange
`FileChange` 模型用于描述文件级别的变更详情。
资料来源：[src/agent_polis/actions/models.py:80-95]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `path` | str | 文件路径 |
| `operation` | str | 操作类型（create/modify/delete/move） |
| `size_bytes` | int | 文件大小（字节） |
| `line_count` | int | 行数 |
| `has_deletions` | bool | 是否包含删除内容 |
| `has_additions` | bool | 是否包含新增内容 |
| `has_modifications` | bool | 是否包含修改内容 |
### ActionResponse
`ActionResponse` 是 API 响应的数据结构，整合了请求信息和预览结果。
资料来源：[src/agent_polis/actions/models.py:140-155]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `action_id` | str | 动作标识符 |
| `status` | ApprovalStatus | 当前审批状态 |
| `preview` | ActionPreview | 影响预览 |
| `policy_decision` | str | 策略决策结果 |
| `matched_rule_id` | str | 匹配的策略规则ID |
| `requires_approval` | bool | 是否需要人工审批 |
## 策略决策（PolicyDecision）
`PolicyDecision` 枚举定义了策略评估器可以返回的所有决策类型。
资料来源：[src/agent_polis/governance/policy.py:18-24]()
| 决策值 | 说明 | 触发条件 |
|--------|------|----------|
| `ALLOW` | 允许执行 | 规则明确允许或无匹配规则 |
| `DENY` | 拒绝执行 | 规则明确禁止 |
| `REQUIRE_APPROVAL` | 需要审批 | 默认决策或规则要求 |
策略评估器使用确定性规则优先级算法：
1. 按优先级（priority）从高到低排序规则
2. 匹配第一个满足所有条件的规则
3. 返回该规则的决策结果
资料来源：[src/agent_polis/governance/policy.py:50-90]()
## 策略规则（PolicyRule）
`PolicyRule` 定义了单条策略规则的结构，支持多种匹配条件。
资料来源：[src/agent_polis/governance/policy.py:45-70]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | str | 规则唯一标识 |
| `description` | str | 规则描述 |
| `decision` | PolicyDecision | 匹配后的决策 |
| `priority` | int | 优先级（0-100，越高越先匹配） |
| `enabled` | bool | 规则是否启用 |
| `action_types` | set[ActionType] | 匹配的动作类型集合 |
| `path_globs` | list[str] | 匹配的文件路径模式 |
| `target_contains` | list[str] | 目标包含的关键词 |
| `min_risk_level` | RiskLevel | 最小风险等级 |
| `max_risk_level` | RiskLevel | 最大风险等级 |
| `metadata` | dict | 附加元数据 |
## 审计记录与扫描器
### ScanSeverity 扫描严重级别
提示注入扫描器使用以下严重级别：
资料来源：[src/agent_polis/governance/prompt_scanner.py:25-32]()
| 级别 | 说明 | 对应风险 |
|------|------|----------|
| `LOW` | 低风险提示 | LOW |
| `MEDIUM` | 中等风险提示 | MEDIUM |
| `HIGH` | 高风险提示 | HIGH |
| `CRITICAL` | 极高风险提示 | CRITICAL |
### ScanFinding 扫描发现
`ScanFinding` 记录单个扫描发现，包含机器可读的原因ID：
资料来源：[src/agent_polis/governance/prompt_scanner.py:48-55]()
| 字段 | 类型 | 说明 |
|------|------|------|
| `reason_id` | str | 原因标识符 |
| `severity` | ScanSeverity | 严重级别 |
| `message` | str | 人类可读的消息 |
| `field` | str | 涉及的字段名 |
| `snippet` | str | 相关文本片段 |
## CI 模式数据结构
在 CI 环境中，系统使用标准化的 JSON 报告格式输出评估结果。
资料来源：[src/agent_polis/ci.py:60-100]()
### CIPolicyReport CI策略报告
| 字段 | 类型 | 说明 |
|------|------|------|
| `policy_version` | str | 策略版本号 |
| `totals` | CITotals | 统计汇总 |
| `top_blocking_reasons` | list[CIReasonCount] | 阻断原因排名 |
| `actions` | list[CIActionReport] | 动作报告列表 |
### CITotals 统计汇总
| 字段 | 类型 | 说明 |
|------|------|------|
| `total` | int | 总动作数 |
| `allowed` | int | 允许执行数 |
| `denied` | int | 拒绝执行数 |
| `require_approval` | int | 需要审批数 |
## 模块导出
动作模块通过 `__init__.py` 统一导出所有公共接口：
资料来源：[src/agent_polis/actions/__init__.py:15-45]()
```python
from agent_polis.actions.models import (
ActionType,
ApprovalStatus,
ActionRequest,
ActionPreview,
FileChange,
ActionResponse,
RiskLevel,
)
from agent_polis.actions.service import ActionService
from agent_polis.actions.analyzer import ImpactAnalyzer, get_analyzer
```
## 使用示例
### 创建动作请求
```python
from agent_polis.actions.models import ActionRequest, ActionType
from uuid import uuid4
request = ActionRequest(
action_type=ActionType.FILE_WRITE,
target="src/config.py",
description="Update configuration file",
payload={"key": "value"},
timeout_seconds=30,
)
```
### 查看风险评估
```python
from agent_polis.actions.service import ActionService
service = ActionService()
response = await service.submit_action(request)
print(f"风险等级: {response.preview.risk_level.value}")
print(f"风险因素: {response.preview.risk_factors}")
print(f"策略决策: {response.policy_decision}")
```
## 相关文档
- [策略评估器与确定性优先级](./策略评估器.md) - 了解策略决策算法
- [提示注入扫描器](./提示注入扫描器.md) - 安全扫描功能详解
- [CI 模式集成](./CI模式集成.md) - 机器可读报告输出
- [策略预设包](./策略预设包.md) - startup/fintech/games 预设配置
---
## 风险评估系统
### 相关页面
相关主题：[动作类型与数据模型](#page-action-types)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/governance/prompt_scanner.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/prompt_scanner.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
# 风险评估系统
Agent Polis 的风险评估系统是整个平台的决策核心，负责对 AI 代理提出的操作进行全面的风险分析。该系统通过多层扫描和策略评估，确保只有符合安全标准的操作才能被执行。
## 系统架构概述
风险评估系统由四个核心组件构成，它们协同工作以提供完整的风险分析能力。
```mermaid
graph TD
A[操作请求 ActionRequest] --> B[影响分析器 ImpactAnalyzer]
B --> C[风险因素提取]
C --> D[风险级别评估 RiskLevel]
E[操作请求] --> F[提示注入扫描器 PromptInjectionScanner]
F --> G[扫描发现 ScanFinding]
G --> H[扫描结果 ScanResult]
I[策略配置 PolicyConfig] --> J[策略评估器 PolicyEvaluator]
J --> K[策略决策 PolicyDecision]
D --> L[最终决策汇总]
H --> L
K --> L
L --> M[ActionPreview 预览结果]
```
## 风险级别定义
系统定义了四个风险级别，用于量化操作的安全等级。
### 风险级别枚举
| 级别 | 值 | 含义 | 典型场景 |
|------|-----|------|----------|
| LOW | `low` | 低风险 | 读取操作、安全变更 |
| MEDIUM | `medium` | 中风险 | 非关键文件的写入操作 |
| HIGH | `high` | 高风险 | 系统配置修改、shell 命令执行 |
| CRITICAL | `critical` | 极高风险 | 危险命令、敏感文件访问 |
资料来源：[src/agent_polis/actions/models.py:29-35]()
### 风险级别顺序
风险级别之间存在数值顺序关系，用于比较和阈值判断：
```python
_RISK_ORDER = {
RiskLevel.LOW: 0,
RiskLevel.MEDIUM: 1,
RiskLevel.HIGH: 2,
RiskLevel.CRITICAL: 3,
}
```
资料来源：[src/agent_polis/governance/policy.py:24-29]()
## 影响分析器 (ImpactAnalyzer)
`ImpactAnalyzer` 是风险评估的第一道关卡，负责分析操作请求并生成影响预览。
### 核心职责
- 分析不同类型的操作请求（文件、数据库、Shell 等）
- 生成统一的 `ActionPreview` 对象
- 识别风险因素和警告信息
- 评估操作的可逆性
### 支持的操作类型
| 操作类型 | 枚举值 | 风险评估特征 |
|----------|--------|--------------|
| 文件写入 | `FILE_WRITE` | 根据目标路径和内容判断 |
| 文件删除 | `FILE_DELETE` | 高风险，尤其是系统文件 |
| 文件移动 | `FILE_MOVE` | 中等风险，评估源和目标 |
| 文件创建 | `FILE_CREATE` | 根据内容判断 |
| 数据库查询 | `DB_QUERY` | 低风险，只读操作 |
| 数据库执行 | `DB_EXECUTE` | 高风险，可能产生副作用 |
| API 调用 | `API_CALL` | 根据端点和方法判断 |
| Shell 命令 | `SHELL_COMMAND` | 最高风险，默认 HIGH |
| 自定义 | `CUSTOM` | 通用评估逻辑 |
资料来源：[src/agent_polis/actions/models.py:14-24]()
### 文件操作风险评估逻辑
```mermaid
graph LR
A[文件写入请求] --> B{目标路径分析}
B --> C{系统文件?}
C -->|是| D[CRITICAL 风险]
C -->|否| E{内容分析}
E --> F{包含敏感信息?}
F -->|是| G[HIGH 风险]
F -->|否| H{文件大小}
H -->|大文件| I[MEDIUM 风险]
H -->|小文件| J[LOW 风险]
```
### ActionPreview 数据结构
```python
class ActionPreview(BaseModel):
file_changes: list[FileChange] = Field(default_factory=list)
risk_level: RiskLevel
risk_factors: list[str] = Field(default_factory=list)
summary: str
affected_count: int = 0
warnings: list[str] = Field(default_factory=list)
is_reversible: bool = True
reversal_instructions: str | None = None
```
资料来源：[src/agent_polis/actions/analyzer.py:42-50]()
### Shell 命令特殊处理
Shell 命令被默认视为高风险操作，系统会特别检查：
```python
dangerous_commands = ["rm", "rmdir", "del", "format", "dd", "mkfs", ">", ">>"]
```
如果命令包含以上任意关键字，风险级别立即提升至 `CRITICAL`。
资料来源：[src/agent_polis/actions/analyzer.py:98-101]()
## 策略评估系统
策略系统是风险评估的规则引擎，提供可配置的策略规则来控制操作执行。
### 策略决策类型
| 决策 | 值 | 含义 |
|------|-----|------|
| ALLOW | `allow` | 允许执行，无需额外审批 |
| DENY | `deny` | 明确拒绝执行 |
| REQUIRE_APPROVAL | `require_approval` | 需要人工审批 |
资料来源：[src/agent_polis/governance/policy.py:15-21]()
### 策略配置结构
```python
class PolicyConfig(BaseModel):
version: str = Field(min_length=1)
metadata: dict[str, Any] = Field(default_factory=dict)
defaults: PolicyDefaults = Field(default_factory=PolicyDefaults)
rules: list[PolicyRule] = Field(default_factory=list)
```
资料来源：[src/agent_polis/governance/policy.py:67-72]()
### 策略规则匹配条件
每个策略规则支持多种匹配条件：
| 条件字段 | 类型 | 说明 |
|----------|------|------|
| `action_types` | `set[ActionType]` | 匹配操作类型集合 |
| `path_globs` | `list[str]` | 匹配路径模式（支持通配符） |
| `target_contains` | `list[str]` | 目标路径包含的关键词 |
| `min_risk_level` | `RiskLevel` | 最低风险级别阈值 |
| `max_risk_level` | `RiskLevel` | 最高风险级别阈值 |
资料来源：[src/agent_polis/governance/policy.py:43-51]()
### 确定性优先级机制
策略规则按优先级排序，高优先级规则优先匹配：
```mermaid
graph TD
A[操作请求] --> B[收集匹配的规则]
B --> C{是否有匹配规则?}
C -->|是| D[选择最高优先级规则]
D --> E[应用规则决策]
C -->|否| F[应用默认决策]
E --> G[返回 PolicyResult]
F --> G
```
### 策略评估结果
```python
class PolicyEvaluationResult(BaseModel):
decision: PolicyDecision
matched_rule_id: str | None
matched_rule_priority: int | None
matched_rule_specificity: int | None
trace: list[str] = Field(default_factory=list)
```
资料来源：[src/agent_polis/governance/policy.py:112-117]()
## 提示注入扫描器
`PromptInjectionScanner` 是专门用于检测恶意输入的安全组件。
### 扫描严重级别
| 级别 | 值 | 对应风险 |
|------|-----|----------|
| LOW | `low` | 低风险提示注入 |
| MEDIUM | `medium` | 中等风险注入尝试 |
| HIGH | `high` | 明显注入模式 |
| CRITICAL | `critical` | 高置信度攻击 |
资料来源：[src/agent_polis/governance/prompt_scanner.py:22-27]()
### 扫描结果数据结构
```python
class ScanFinding(BaseModel):
reason_id: str # 机器可读的原因标识
severity: ScanSeverity
message: str # 人类可读消息
field: str # 发现问题的字段
snippet: str # 相关文本片段
class ScanResult(BaseModel):
findings: list[ScanFinding] = Field(default_factory=list)
```
资料来源：[src/agent_polis/governance/prompt_scanner.py:49-59]()
### 安全设计原则
> 此模块特意保持保守和受限：
> - 避免递归负载遍历（防止递归深度崩溃）
> - 限制扫描文本量（降低 CPU 滥用风险）
资料来源：[src/agent_polis/governance/prompt_scanner.py:9-12]()
## 策略预设系统
预设系统提供了开箱即用的策略配置，覆盖常见应用场景。
### 预设类型
| 预设 ID | 适用场景 | 默认决策 | 主要特点 |
|---------|----------|----------|----------|
| `startup` | 初创公司 | `require_approval` | 平衡安全与敏捷 |
| `fintech` | 金融科技 | `require_approval` | 严格密钥保护 |
| `games` | 游戏开发 | `require_approval` | 资产迭代友好 |
资料来源：[src/agent_polis/governance/presets.py:15-80]()
### Startup 预设特点
```python
"startup": {
"version": "preset-startup-1",
"defaults": {"decision": "require_approval"},
"rules": [
# 低风险文档/测试允许
{"max_risk_level": "medium", "path_globs": ["docs/*", "tests/*"]},
# Shell 命令需要审批
{"action_types": ["shell_command"], "decision": "require_approval"},
]
}
```
### Fintech 预设特点
```python
"fintech": {
"version": "preset-fintech-1",
"defaults": {"decision": "require_approval"},
"rules": [
# 禁止访问密钥和凭证
{"target_contains": [".env", ".ssh", "credentials", "secrets", ".pem"]},
# 禁止 CRITICAL 风险操作
{"min_risk_level": "critical", "decision": "deny"},
# 数据库写入需审批
{"action_types": ["db_execute"], "decision": "require_approval"},
]
}
```
资料来源：[src/agent_polis/governance/presets.py:30-60]()
## CI 集成模式
风险评估系统支持无提示的确定性 CI 模式，用于自动化环境。
### 退出码规范
| 退出码 | 含义 | 触发条件 |
|--------|------|----------|
| 0 | 全部允许 | 所有操作决策为 `allow` |
| 2 | 需要审批 | 至少一个操作需要 `require_approval` |
| 3 | 拒绝执行 | 至少一个操作被 `deny` |
```python
def _decision_exit_code(decisions: list[PolicyDecision]) -> int:
if any(d == PolicyDecision.DENY for d in decisions):
return 3
if any(d == PolicyDecision.REQUIRE_APPROVAL for d in decisions):
return 2
return 0
```
资料来源：[src/agent_polis/ci.py:89-97]()
### CI 报告结构
```python
class CIPolicyReport(BaseModel):
schema_version: Literal["1"] = REPORT_SCHEMA_VERSION
policy_version: str
totals: dict[str, int] # {"allow": 0, "require_approval": 0, "deny": 0}
top_blocking_reasons: list[CIReasonCount]
actions: list[CIActionReport]
```
资料来源：[src/agent_polis/ci.py:63-69]()
## 完整评估流程
```mermaid
sequenceDiagram
participant Client as 客户端
participant Analyzer as 影响分析器
participant Scanner as 提示扫描器
participant Policy as 策略评估器
participant Service as 操作服务
Client->>Service: 提交 ActionRequest
Service->>Analyzer: 分析请求
Analyzer-->>Service: 返回 ActionPreview
Service->>Scanner: 扫描请求
Scanner-->>Service: 返回 ScanResult
Service->>Policy: 评估策略
Policy-->>Service: 返回 PolicyResult
Service->>Client: 返回最终预览
```
## 审计追踪
每个操作的风险评估结果都会被记录到审计日志中：
```python
event = ActionPreviewGenerated(
stream_id=f"action:{action.id}",
data={
"action_id": str(action.id),
"risk_level": preview.risk_level.value,
"governance": {
"policy": {
"version": policy.version,
"decision": policy_result.decision.value,
"matched_rule_id": policy_result.matched_rule_id,
"trace": policy_result.trace,
},
"scanner": {
"max_severity": scan_result.max_severity().value,
"reason_ids": sorted({f.reason_id for f in scan_result.findings}),
},
},
},
)
```
资料来源：[src/agent_polis/actions/service.py:45-62]()
## 扩展风险评估能力
社区正在讨论以下增强方向（参见 issues #9, #10, #11）：
- 机器可读的 CI 策略报告输出（JSON Schema）
- 确定性 CI 评估模式（无 TTY 依赖）
- 文档化预设、报告模式和 CI 使用示例
## 相关模块导航
| 模块 | 路径 | 职责 |
|------|------|------|
| 操作模型 | `agent_polis.actions.models` | 风险级别、操作类型定义 |
| 影响分析 | `agent_polis.actions.analyzer` | 操作分析和预览生成 |
| 策略系统 | `agent_polis.governance.policy` | 策略配置和评估引擎 |
| 扫描器 | `agent_polis.governance.prompt_scanner` | 提示注入检测 |
| 预设系统 | `agent_polis.governance.presets` | 预置策略包 |
| CI 集成 | `agent_polis.ci` | 持续集成模式支持 |
---
## 审批工作流
### 相关页面
相关主题：[动作类型与数据模型](#page-action-types)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
- [src/agent_polis/actions/router.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/router.py)
- [src/agent_polis/actions/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/__init__.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
# 审批工作流
## 概述
审批工作流是 Agent Polis 平台的核心功能，负责管理 AI 代理（Agent）提交的操作请求从提交到执行或拒绝的完整生命周期。系统通过影响预览（Impact Preview）、策略评估（Policy Evaluation）和提示注入扫描（Prompt Injection Scanner）三个关键环节，在操作执行前进行风险评估和治理控制。
工作流支持两种运行模式：
- **交互模式**：适用于需要人工审批的场境，等待人工决策
- **CI 模式**：适用于自动化 CI/CD 流程，返回确定性退出码
资料来源：[src/agent_polis/actions/__init__.py:1-20]()
## 审批状态定义
### 状态枚举
系统定义了完整的操作审批状态机，所有状态定义在 `ApprovalStatus` 枚举中：
| 状态值 | 含义 | 描述 |
|--------|------|------|
| `pending` | 待处理 | 等待人工审核 |
| `approved` | 已批准 | 人工批准执行 |
| `rejected` | 已拒绝 | 人工拒绝执行 |
| `modified` | 已修改 | 人工修改后批准 |
| `executed` | 已执行 | 操作已成功执行 |
| `failed` | 执行失败 | 操作执行失败 |
| `timed_out` | 已超时 | 规定时间内无响应 |
| `cancelled` | 已取消 | 代理主动取消请求 |
资料来源：[src/agent_polis/actions/models.py:19-31]()
### 状态转换图
```mermaid
graph TD
A[提交操作请求] --> B{策略评估}
B -->|allow| E[直接执行]
B -->|deny| F[拒绝执行]
B -->|require_approval| C{pending}
C -->|批准| D{modified?}
D -->|是| G[记录修改内容]
D -->|否| H[批准]
G --> I[执行]
H --> I
C -->|拒绝| J[rejected]
C -->|超时| K[timed_out]
C -->|取消| L[cancelled]
I -->|成功| M[executed]
I -->|失败| N[failed]
```
## 操作类型支持
系统支持多种操作类型的拦截和预览：
| 操作类型 | 值 | 描述 |
|----------|-----|------|
| 文件写入 | `file_write` | 修改现有文件 |
| 文件删除 | `file_delete` | 删除文件 |
| 文件移动 | `file_move` | 移动或重命名文件 |
| 文件创建 | `file_create` | 创建新文件 |
| 数据库查询 | `db_query` | 只读数据库操作 |
| 数据库执行 | `db_execute` | 写数据库操作 |
| API 调用 | `api_call` | 外部 API 请求 |
| Shell 命令 | `shell_command` | 系统命令执行 |
| 自定义 | `custom` | 用户定义的操作 |
资料来源：[src/agent_polis/actions/models.py:12-24]()
## 核心组件架构
### 组件关系图
```mermaid
graph LR
A[ActionRequest] --> B[ImpactAnalyzer]
B --> C[ActionPreview]
A --> D[PromptInjectionScanner]
D --> E[ScanResult]
F[PolicyConfig] --> G[PolicyEvaluator]
A --> G
G --> H[PolicyResult]
I[ActionService] --> J[审计追踪]
C --> K[API响应/CLI输出]
E --> K
H --> K
```
### ImpactAnalyzer
`ImpactAnalyzer` 负责分析操作请求并生成影响预览。它是工作流的第一个处理环节：
```python
class ImpactAnalyzer:
"""分析操作请求并生成影响预览"""
async def analyze(self, request: ActionRequest) -> ActionPreview
```
核心职责：
- 读取目标文件当前内容（如果存在）
- 计算文件变更差异
- 评估风险等级（RiskLevel）
- 生成风险因素列表
- 提供可逆性评估和回滚指导
资料来源：[src/agent_polis/actions/analyzer.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/analyzer.py)
### 策略评估器
`PolicyEvaluator` 根据配置的策略规则对操作进行评估：
```python
class PolicyEvaluator:
"""确定性策略评估器"""
def evaluate(
self,
policy: PolicyConfig,
request: ActionRequest,
risk_level: RiskLevel,
) -> PolicyResult
```
策略支持三种决策结果：
| 决策 | 值 | 行为 |
|------|-----|------|
| 允许 | `allow` | 自动执行，无需审批 |
| 拒绝 | `deny` | 阻止执行，记录原因 |
| 需审批 | `require_approval` | 暂停等待人工决策 |
决策遵循优先级规则：
- 优先级数值越小，优先级越高
- 第一个匹配的规则生效
- 未匹配任何规则时使用默认值
资料来源：[src/agent_polis/governance/policy.py:1-50]()
### 提示注入扫描器
`PromptInjectionScanner` 检测操作请求中的提示注入和危险指令风险：
```python
class PromptInjectionScanner:
"""提示注入和危险指令扫描器"""
def scan_action_request(self, request: ActionRequest) -> ScanResult
```
扫描结果包含：
- `reason_id`: 机器可读的原因标识
- `severity`: 发现级别（low/medium/high/critical）
- `message`: 人类可读的消息
- `field`: 发现问题的字段名
- `snippet`: 问题片段
资料来源：[src/agent_polis/governance/prompt_scanner.py:1-80]()
## ActionRequest 数据模型
提交审批的操作请求需包含以下字段：
| 字段 | 类型 | 必需 | 描述 |
|------|------|------|------|
| `action_type` | ActionType | 是 | 操作类型枚举 |
| `target` | str | 是 | 操作目标路径或标识 |
| `description` | str | 否 | 操作描述 |
| `payload` | dict | 否 | 附加数据 |
| `context` | dict | 否 | 上下文信息 |
| `timeout_seconds` | int | 否 | 超时时间（秒） |
| `auto_approve_if_low_risk` | bool | 否 | 低风险自动批准 |
| `callback_url` | str | 否 | 回调 URL |
资料来源：[src/agent_polis/actions/models.py:34-55]()
## ActionPreview 响应模型
分析完成后返回的影响预览包含：
| 字段 | 类型 | 描述 |
|------|------|------|
| `file_changes` | list[FileChange] | 文件变更列表 |
| `risk_level` | RiskLevel | 综合风险等级 |
| `risk_factors` | list[str] | 风险因素列表 |
| `summary` | str | 变更摘要 |
| `affected_count` | int | 影响文件数量 |
| `warnings` | list[str] | 警告信息 |
| `is_reversible` | bool | 是否可逆 |
| `reversal_instructions` | str | 回滚指导 |
资料来源：[src/agent_polis/actions/models.py:58-75]()
## API 端点
### 动作相关端点
| 方法 | 路径 | 描述 |
|------|------|------|
| `POST` | `/api/v1/actions` | 创建新操作请求 |
| `GET` | `/api/v1/actions` | 列出操作请求 |
| `GET` | `/api/v1/actions/{id}` | 获取单个操作 |
| `POST` | `/api/v1/actions/{id}/approve` | 批准操作 |
| `POST` | `/api/v1/actions/{id}/reject` | 拒绝操作 |
| `GET` | `/api/v1/actions/pending` | 获取待审批操作 |
| `POST` | `/api/v1/actions/{id}/execute` | 执行操作 |
资料来源：[src/agent_polis/main.py:60-65]()
## CI 集成模式
### CI 模式特性
CI 模式专为非交互式环境设计，确保：
1. **确定性评估**：无任何提示路径可达
2. **稳定退出码**：根据决策类型返回固定退出码
3. **机器可读报告**：JSON 格式的政策报告输出
### 退出码定义
| 退出码 | 含义 | 触发条件 |
|--------|------|----------|
| `0` | 成功 | 所有操作均被允许 |
| `2` | 需审批 | 至少一个操作需要人工审批 |
| `3` | 拒绝 | 至少一个操作被拒绝 |
```python
def _decision_exit_code(decisions: list[PolicyDecision]) -> int:
if any(d == PolicyDecision.DENY for d in decisions):
return 3
if any(d == PolicyDecision.REQUIRE_APPROVAL for d in decisions):
return 2
return 0
```
资料来源：[src/agent_polis/ci.py:1-100]()
### CI 策略报告结构
```python
class CIPolicyReport(BaseModel):
schema_version: Literal["1"] = REPORT_SCHEMA_VERSION
policy_version: str
totals: dict[str, int] # {"allow": 0, "require_approval": 0, "deny": 0}
top_blocking_reasons: list[CIReasonCount]
actions: list[CIActionReport]
```
报告包含：
- 策略版本信息
- 各决策类型统计
- 阻塞原因排名（Top 10）
- 每个操作的详细报告
资料来源：[src/agent_polis/ci.py:60-85]()
## 风险等级体系
| 等级 | 值 | 描述 | 示例 |
|------|-----|------|------|
| 低 | `low` | 只读操作、安全变更 | 读取文件、生成文档 |
| 中 | `medium` | 对非关键文件的写操作 | 修改配置文件 |
| 高 | `high` | 可能影响系统稳定性 | 写入系统目录 |
| 严重 | `critical` | 可能造成重大影响 | 删除关键文件、执行 Shell 命令 |
风险评估考虑因素：
- 操作类型（Shell 命令默认高风险）
- 目标路径（系统目录提升风险）
- 内容特征（包含敏感模式）
- 文件大小（大文件提升风险）
资料来源：[src/agent_polis/actions/models.py:32-50]()
## 审计追踪
系统记录完整的操作审计轨迹：
```python
class ActionAuditRequest:
action_id: str
action_type: str
target: str
description: str
payload: dict
context: dict
timeout_seconds: int
auto_approve_if_low_risk: bool
callback_url: str
```
审计记录包含：
- 原始操作请求
- 扫描器发现（reason_id 列表）
- 策略评估结果（决策、匹配的规则 ID）
- 决策追踪信息
资料来源：[src/agent_polis/actions/service.py:20-40]()
## 服务处理流程
### ActionService 核心流程
```python
async def submit_action(self, action: ActionRequest) -> ActionResponse:
# 1. 生成影响预览
preview = await self._analyzer.analyze(action)
# 2. 审计扫描
audit_request = self._build_audit_request(action, preview)
scan_result = self._audit_scanner.scan_action_request(audit_request)
# 3. 策略评估
policy = _builtin_policy_for_request(audit_request)
policy_result = self._policy_evaluator.evaluate(
policy,
audit_request,
risk_level=preview.risk_level,
)
# 4. 构建响应
event = ActionPreviewGenerated(
stream_id=f"action:{action.id}",
data={...} # governance.scanner.policy 信息
)
```
资料来源：[src/agent_polis/actions/service.py:1-80]()
## 工作流完整时序
```mermaid
sequenceDiagram
participant Agent as AI 代理
participant API as API 网关
participant Analyzer as ImpactAnalyzer
participant Scanner as PromptInjectionScanner
participant Evaluator as PolicyEvaluator
participant Audit as 审计系统
participant Human as 审批人
Agent->>API: 提交 ActionRequest
API->>Analyzer: 分析影响
Analyzer-->>API: ActionPreview
API->>Scanner: 扫描注入风险
Scanner-->>API: ScanResult
API->>Evaluator: 策略评估
Evaluator-->>API: PolicyResult
alt allow 决策
API->>API: 直接执行
else deny 决策
API->>Audit: 记录拒绝
API-->>Agent: 返回拒绝原因
else require_approval 决策
API->>Audit: 记录待审批
API-->>Agent: 返回待审批状态
Human->>API: 审批决策
alt 批准
API->>API: 执行操作
else 拒绝
API->>Audit: 记录拒绝
end
end
```
## 相关社区 Issue
社区关注的审批工作流相关功能开发进展：
| Issue | 标题 | 优先级 | 状态 |
|-------|------|--------|------|
| #2 | Policy evaluator with deterministic precedence | 核心功能 | 进行中 |
| #5 | Extend audit records with policy/scanner context | 功能增强 | 进行中 |
| #10 | Deterministic CI evaluation mode | CI 集成 | 进行中 |
| #11 | Stage 2 docs and CI integration examples | 文档 | 进行中 |
这些 Issue 涵盖了策略评估的确定性、审计记录的扩展、CI 模式的完善以及文档建设等方向。
---
## MCP服务器集成
### 相关页面
相关主题：[快速入门指南](#page-quick-start), [SDK集成指南](#page-sdk-usage)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/mcp_server.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/mcp_server.py)
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/actions/service.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/service.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
# MCP服务器集成
## 概述
MCP（Model Context Protocol）服务器集成是 Agent Polis 为 AI Agent 提供"terraform plan"风格影响预览的核心模块。它允许 Claude Desktop、Cursor 等 MCP 兼容客户端在执行危险操作前，先预览将要发生的变化、风险等级和治理决策。
资料来源：[src/agent_polis/mcp_server.py:1-20]()
### 核心功能
| 功能 | 描述 |
|------|------|
| 影响预览 | 展示文件操作前后的变化内容 |
| 风险评估 | 对操作进行 LOW/MEDIUM/HIGH/CRITICAL 四级风险分类 |
| 策略执行 | 基于策略预设自动做出 allow/deny/require_approval 决策 |
| 审计追踪 | 完整记录所有操作的治理上下文和扫描结果 |
## 架构设计
### 系统组件
```mermaid
graph TD
A[MCP 客户端
Claude Desktop/Cursor] --> B[FastMCP Server
端口 8000]
B --> C[ImpactAnalyzer
影响分析器]
C --> D[PolicyEvaluator
策略评估器]
C --> E[PromptInjectionScanner
提示注入扫描器]
D --> F[内置策略/预设策略]
E --> G[扫描规则库]
C --> H[ActionPreview
操作预览结果]
D --> I[PolicyResult
策略决策结果]
```
### 工具注册流程
MCP 服务器通过 `@mcp.tool()` 装饰器注册治理工具，每个工具都是一个异步函数：
```python
@mcp.tool()
async def preview_file_create(
path: str,
content: str,
description: str = "Create file",
) -> str:
"""预览文件创建操作"""
# 1. 构建 ActionRequest
# 2. 调用 ImpactAnalyzer.analyze()
# 3. 返回格式化的预览报告
```
资料来源：[src/agent_polis/mcp_server.py:47-72]()
## MCP 工具清单
### 文件操作预览工具
| 工具名称 | 功能 | 参数 |
|---------|------|------|
| `preview_file_create` | 预览新文件创建 | `path`, `content`, `description` |
| `preview_file_delete` | 预览文件删除 | `path`, `description` |
资料来源：[src/agent_polis/mcp_server.py:47-95]()
### 预览输出格式
工具返回的预览报告包含以下关键信息：
| 字段 | 示例 | 说明 |
|------|------|------|
| 目标路径 | `src/main.py` | 操作针对的文件路径 |
| 风险等级 | `🟡 MEDIUM` | 操作的整体风险评估 |
| 风险因素 | `["包含敏感配置", "修改系统文件"]` | 触发风险的具体原因 |
| 警告信息 | `["文件已存在"]` | 额外注意事项 |
| 摘要 | `修改 12 行，删除 3 行` | 变更统计 |
## 操作类型与风险模型
### ActionType 枚举
```python
class ActionType(str, Enum):
FILE_WRITE = "file_write" # 写文件
FILE_DELETE = "file_delete" # 删文件
FILE_MOVE = "file_move" # 移动文件
FILE_CREATE = "file_create" # 创建文件
DB_QUERY = "db_query" # 数据库查询
DB_EXECUTE = "db_execute" # 数据库执行
API_CALL = "api_call" # API 调用
SHELL_COMMAND = "shell_command" # Shell 命令
CUSTOM = "custom" # 自定义操作
```
资料来源：[src/agent_polis/actions/models.py:14-24]()
### RiskLevel 风险等级
| 等级 | 标识 | 含义 |
|------|------|------|
| `LOW` | 🟢 | 只读操作、安全变更 |
| `MEDIUM` | 🟡 | 对非关键文件的写操作 |
| `HIGH` | 🟠 | 可能影响系统稳定性的操作 |
| `CRITICAL` | 🔴 | 可能造成不可逆损害的操作 |
资料来源：[src/agent_polis/actions/models.py:38-40]()
## 策略治理机制
### PolicyDecision 决策类型
| 决策 | 含义 | CI 退出码 |
|------|------|-----------|
| `allow` | 允许执行 | 0 |
| `deny` | 拒绝执行 | 3 |
| `require_approval` | 需要人工审批 | 2 |
资料来源：[src/agent_polis/governance/policy.py:19-23]()
### 策略评估流程
```mermaid
graph LR
A[ActionRequest] --> B[加载策略配置]
B --> C{规则匹配}
C -->|命中规则| D[按优先级排序]
C -->|无匹配| E[应用默认决策]
D --> F[返回最高优先级决策]
F --> G[PolicyResult]
E --> G
```
策略评估器返回包含以下字段的结果：
```python
class PolicyEvaluationResult(BaseModel):
decision: PolicyDecision # 最终决策
matched_rule_id: str | None # 匹配的规则 ID
matched_rule_priority: int # 规则优先级
matched_rule_specificity: int # 规则特异性
trace: dict[str, Any] # 调试追踪信息
```
资料来源：[src/agent_polis/governance/policy.py:78-84]()
## 策略预设（Policy Presets）
系统预置了三个场景化策略包，可通过 `load_policy_preset()` 加载：
### 预设对比
| 预设 | 适用场景 | 默认决策 | 关键规则 |
|------|---------|---------|---------|
| `startup` | 初创公司/敏捷开发 | `require_approval` | 低风险文档变更自动放行 |
| `fintech` | 金融科技/合规要求 | `require_approval` | 禁止接触密钥/凭证，DB写入需审批 |
| `games` | 游戏开发/创意工作流 | `require_approval` | 资源/文档/测试可低风险变更 |
资料来源：[src/agent_polis/governance/presets.py:1-150]()
### Startup 预设规则示例
```python
{
"id": "allow-docs-tests-low-medium",
"description": "Allow low/medium risk edits to docs and tests",
"decision": "allow",
"priority": 50,
"action_types": ["file_write", "file_create"],
"path_globs": ["docs/*", "tests/*"],
"max_risk_level": "medium",
"metadata": {
"rationale": "Documentation and tests are typically low blast-radius"
}
}
```
资料来源：[src/agent_polis/governance/presets.py:40-50]()
## CI 集成模式
### CI 评估模式
MCP 服务器支持无 TTY 的确定性 CI 模式，适用于 PR 网关集成：
```python
async def generate_ci_report(
actions: list[ActionRequest],
policy: PolicyConfig,
working_directory: str | None = None,
) -> tuple[CIPolicyReport, int]:
# 返回 (报告对象, 退出码)
```
### 退出码规范
| 退出码 | 条件 |
|--------|------|
| `0` | 所有操作均被允许 |
| `2` | 至少一个操作需要人工审批 |
| `3` | 至少一个操作被拒绝 |
资料来源：[src/agent_polis/ci.py:75-84]()
### CI 报告格式
```json
{
"schema_version": "1",
"policy_version": "preset-startup-1",
"totals": {
"allow": 5,
"require_approval": 2,
"deny": 0
},
"top_blocking_reasons": [
{"reason": "shell-command-detected", "count": 3}
],
"actions": [...]
}
```
资料来源：[src/agent_polis/ci.py:35-50]()
## 部署配置
### 运行方式
**方式一：uvicorn（推荐用于生产）**
```bash
uvicorn agent_polis.mcp_server:mcp.app --host 0.0.0.0 --port 8000
```
**方式二：直接运行模块**
```bash
python -m agent_polis.mcp_server
```
资料来源：[src/agent_polis/mcp_server.py:24-28]()
### Claude Desktop 配置
在 `~/.config/claude/claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"impact-preview": {
"url": "http://localhost:8000/mcp"
}
}
}
```
资料来源：[src/agent_polis/mcp_server.py:30-37]()
### 环境变量配置
| 变量 | 默认值 | 说明 |
|------|--------|------|
| `AGENT_POLIS_HOST` | `0.0.0.0` | 监听地址 |
| `AGENT_POLIS_PORT` | `8000` | 监听端口 |
| `AGENT_POLIS_WORKING_DIRECTORY` | 当前目录 | 分析基准目录 |
| `REDIS_URL` | `redis://localhost:6379/0` | 事件存储后端 |
## MCP 工具指令
MCP 服务器的标准化指令文本：
> "Impact preview for AI agents - see exactly what will change before any action executes. Use preview tools BEFORE making file changes, running shell commands, or executing database queries."
资料来源：[src/agent_polis/mcp_server.py:20-21]()
## 审计追踪集成
### 审计记录扩展
根据 AP-105 的需求，审计记录现在包含策略和扫描器上下文：
| 字段 | 类型 | 说明 |
|------|------|------|
| `policy.decision` | `PolicyDecision` | 最终策略决策 |
| `policy.matched_rule_id` | `str \| None` | 匹配的规则 ID |
| `policy.matched_rule_priority` | `int` | 规则优先级 |
| `policy.trace` | `dict` | 调试追踪数据 |
| `scanner.max_severity` | `ScanSeverity` | 最高扫描严重级别 |
| `scanner.reason_ids` | `set[str]` | 扫描发现的原因 ID 集合 |
资料来源：[src/agent_polis/actions/service.py:45-60]()
## 相关社区议题
| 议题 | 优先级 | 说明 |
|------|--------|------|
| [#11 AP-205](https://github.com/agent-polis/impact-preview/issues/11) | 高 | Stage 2 文档和 CI 集成示例 |
| [#10 AP-204](https://github.com/agent-polis/impact-preview/issues/10) | 高 | 确定性 CI 评估模式（无提示词） |
| [#9 AP-203](https://github.com/agent-polis/impact-preview/issues/9) | 高 | 机器可读 CI 策略报告输出 |
| [#3 AP-103](https://github.com/agent-polis/impact-preview/issues/3) | 中 | MCP 描述符完整性检查（哈希锁定） |
## 版本信息
当前版本：**v0.2.2**
路线图：
| 版本 | 焦点 | 状态 |
|------|------|------|
| v0.2.0 | 文件操作预览 | 当前 |
| v0.3.0 | 数据库操作预览 | 规划中 |
| v0.4.0 | API 调用预览 | 规划中 |
| v0.5.0 | IDE 集成（Cursor, VS Code） | 规划中 |
| v1.0.0 | 生产就绪 | 规划中 |
---
## SDK集成指南
### 相关页面
相关主题：[MCP服务器集成](#page-mcp-integration), [审批工作流](#page-approval-workflow)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/sdk.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/sdk.py)
- [src/agent_polis/integrations/crewai.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/integrations/crewai.py)
- [src/agent_polis/integrations/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/integrations/__init__.py)
- [src/agent_polis/main.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/main.py)
- [src/agent_polis/actions/__init__.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/__init__.py)
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
# SDK集成指南
## 概述
Agent Polis SDK 提供了一种简单的方式将影响预览功能集成到 AI agent 工作流中。通过 SDK，开发者可以使用 `@require_approval` 装饰器自动将危险操作路由到审批流程，在执行前获得人类确认。SDK 支持与主流 agent 框架（如 CrewAI、LangGraph）的无缝集成，并提供了完整的错误处理机制。
当前版本：v0.2.2 | 资料来源：[src/agent_polis/main.py:43]()
## 核心能力
| 能力 | 说明 |
|------|------|
| `impact_preview` | 操作影响预览 |
| `action_approval` | 动作审批工作流 |
| `file_diff` | 文件变更差异 |
| `audit_trail` | 审计追踪记录 |
## 安装与配置
### 基础安装
```bash
pip install impact-preview
```
### 开发环境安装
```bash
git clone https://github.com/agent-polis/impact-preview.git
cd impact-preview
pip install -e .[dev]
```
### 环境变量配置
```bash
# 必需
AGENT_POLIS_API_URL=http://localhost:8000
AGENT_POLIS_API_KEY=ap_...
# 可选
REDIS_URL=redis://localhost:6379/0
FREE_TIER_ACTIONS_PER_MONTH=100
LOG_LEVEL=INFO
```
## AgentPolisClient 客户端
`AgentPolisClient` 是 SDK 的核心类，负责与 Agent Polis API 服务器通信。
### 初始化
```python
from agent_polis.sdk import AgentPolisClient
client = AgentPolisClient(
api_key="your_api_key",
api_url="http://localhost:8000" # 可选，默认为 http://localhost:8000
)
```
### 核心方法
| 方法 | 说明 |
|------|------|
| `submit_action()` | 提交操作请求 |
| `wait_for_approval()` | 等待操作审批 |
| `get_action_status()` | 获取操作状态 |
| `require_approval()` | 装饰器工厂方法 |
资料来源：[src/agent_polis/sdk.py:59-150]()
## require_approval 装饰器
`@require_approval` 装饰器是 SDK 最强大的功能，它允许开发者用最少的代码将任意函数转换为需要审批的操作。
### 基本用法
```python
from agent_polis.sdk import AgentPolisClient
client = AgentPolisClient(api_key="your_api_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 config content")
```
### 工作流程
```mermaid
graph TD
A[调用被装饰函数] --> B[提交ActionRequest]
B --> C{API服务器处理}
C -->|低风险| D[自动批准]
C -->|高风险| E[等待人工审批]
C -->|违反策略| F[拒绝执行]
D --> G[执行原函数]
E -->|审批通过| G
E -->|审批拒绝| H[抛出ActionRejectedError]
F --> H
G --> I[返回结果]
H --> J[异常处理]
```
资料来源：[src/agent_polis/sdk.py:1-50]()
### 装饰器参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `action_type` | `str` | 操作类型 (file_write, file_create, shell_command, db_execute) |
| `description` | `str` | 操作描述 |
| `timeout` | `int` | 等待审批超时时间（秒） |
| `auto_approve_if_low_risk` | `bool` | 低风险操作是否自动批准 |
## 异常处理
SDK 定义了专门的异常类用于处理审批流程中的各种错误情况。
### ActionRejectedError
当操作被拒绝时抛出。
```python
from agent_polis.sdk import ActionRejectedError, AgentPolisClient
client = AgentPolisClient(api_key="your_api_key")
try:
client.submit_and_wait(action_request)
except ActionRejectedError as e:
print(f"操作 {e.action_id} 被拒绝: {e.reason}")
```
| 属性 | 类型 | 说明 |
|------|------|------|
| `action_id` | `str` | 被拒绝的操作ID |
| `reason` | `str` | 拒绝原因 |
### ActionTimedOutError
当操作等待审批超时。
```python
from agent_polis.sdk import ActionTimedOutError, AgentPolisClient
client = AgentPolisClient(api_key="your_api_key")
try:
client.submit_and_wait(action_request, timeout=300)
except ActionTimedOutError as e:
print(f"操作 {e.action_id} 等待超时")
```
| 属性 | 类型 | 说明 |
|------|------|------|
| `action_id` | `str` | 超时的操作ID |
| `timeout` | `int` | 设置的超时时间（秒） |
资料来源：[src/agent_polis/sdk.py:53-72]()
## CrewAI 集成
Agent Polis 提供了与 CrewAI 的深度集成，支持将影响预览作为工具或回调使用。
### AgentPolisTool
作为 CrewAI 的 BaseTool 使用：
```python
from agent_polis.integrations.crewai import AgentPolisTool
tool = AgentPolisTool(
api_url="http://localhost:8000",
api_key="ap_..."
)
# 在 CrewAI agent 中使用
agent = Agent(
role="Developer",
goal="安全地管理系统文件",
backstory="...",
tools=[tool]
)
```
### SimulationCallback
用于模拟驱动的治理回调：
```python
from agent_polis.integrations.crewai import SimulationCallback
callback = SimulationCallback(
api_url="http://localhost:8000",
api_key="ap_..."
)
# 在 agent 执行前进行模拟验证
result = callback.on_before_task(task, context)
```
### 输入模型
```python
class SimulationInput(BaseModel):
"""模拟工具输入模式"""
name: str # 模拟场景名称
description: str # 模拟描述
code: str # 在沙箱中执行的 Python 代码
inputs: dict[str, Any] # 输入变量
```
资料来源：[src/agent_polis/integrations/crewai.py:1-100]()
## 完整集成示例
### 文件操作审批
```python
from agent_polis.sdk import AgentPolisClient
from agent_polis.actions.models import ActionType
client = AgentPolisClient(
api_key="ap_your_key_here",
api_url="http://localhost:8000"
)
@client.require_approval(
action_type=ActionType.FILE_WRITE,
description="更新应用配置文件",
auto_approve_if_low_risk=True
)
async def update_config(path: str, content: str):
"""更新配置文件，自动经过影响预览审批"""
with open(path, 'w') as f:
f.write(content)
return {"status": "success", "path": path}
```
### 数据库操作审批
```python
from agent_polis.sdk import AgentPolisClient
from agent_polis.actions.models import ActionType
client = AgentPolisClient(api_key="ap_your_key_here")
@client.require_approval(
action_type=ActionType.DB_EXECUTE,
description="执行数据库写操作",
timeout=600 # 数据库操作可能需要更长等待时间
)
async def execute_db_query(query: str, params: dict):
"""数据库查询需经过人工审批"""
# 执行数据库操作
return result
```
### Shell 命令审批
```python
from agent_polis.sdk import AgentPolisClient
from agent_polis.actions.models import ActionType
client = AgentPolisClient(api_key="ap_your_key_here")
@client.require_approval(
action_type=ActionType.SHELL_COMMAND,
description="执行系统命令"
)
async def run_deployment(command: str):
"""Shell 命令必须经过审批"""
import subprocess
result = subprocess.run(command, shell=True, capture_output=True)
return result.stdout.decode()
```
## API 端点
Agent Polis 服务器暴露以下 REST API 端点：
| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/actions` | POST | 提交新操作 |
| `/api/v1/actions/pending` | GET | 获取待审批操作列表 |
| `/api/v1/agents` | GET | 获取代理信息 |
| `/.well-known/agent.json` | GET | 获取 agent 能力描述 |
### 代理能力元数据
```json
{
"name": "Agent Polis",
"version": "0.2.2",
"protocol": "a2a/1.0",
"capabilities": [
"impact_preview",
"action_approval",
"file_diff",
"audit_trail"
],
"endpoints": {
"actions": "/api/v1/actions",
"pending": "/api/v1/actions/pending",
"agents": "/api/v1/agents"
}
}
```
资料来源：[src/agent_polis/main.py:30-55]()
## 最佳实践
### 1. 合理设置超时时间
```python
# 普通操作
@client.require_approval(timeout=60)
# 复杂或高风险操作
@client.require_approval(timeout=600)
```
### 2. 使用自动批准优化低风险场景
```python
@client.require_approval(
action_type=ActionType.FILE_WRITE,
auto_approve_if_low_risk=True # 低风险操作自动通过
)
def update_logs(path: str, content: str):
pass
```
### 3. 完善的异常处理
```python
from agent_polis.sdk import (
AgentPolisClient,
ActionRejectedError,
ActionTimedOutError
)
client = AgentPolisClient(api_key="your_key")
try:
result = await client.submit_and_wait(request, timeout=300)
except ActionRejectedError as e:
logger.error(f"操作被拒绝: {e.reason}")
# 执行回退逻辑
except ActionTimedOutError as e:
logger.warning(f"操作 {e.action_id} 等待超时")
# 通知管理员
```
### 4. 集成 CI/CD 流程
```python
# 在 CI 环境中使用确定性模式
import os
os.environ["AGENT_POLIS_CI_MODE"] = "true"
client = AgentPolisClient(
api_key=os.environ["AGENT_POLIS_API_KEY"],
ci_mode=True # 无需交互式提示
)
```
## 与其他集成模块的关系
```mermaid
graph LR
A[AI Agent] --> B[SDK 客户端]
B --> C[REST API]
C --> D[主应用]
E[CrewAI集成] --> B
F[LangGraph集成] --> B
G[MCP Server] --> D
D --> H[动作服务]
D --> I[模拟服务]
D --> J[治理策略]
D --> K[事件总线]
```
## 故障排查
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 连接超时 | API 服务器未启动 | 检查 `uvicorn` 服务运行状态 |
| 401 Unauthorized | API Key 错误 | 验证环境变量配置 |
| 审批超时 | 无管理员响应 | 增加 `timeout` 或使用 CI 模式 |
| CrewAI 导入失败 | 未安装依赖 | `pip install crewai` |
## 相关资源
- [项目仓库](https://github.com/agent-polis/impact-preview)
- [版本发布 (v0.2.2)](https://github.com/agent-polis/impact-preview/releases/tag/v0.2.2)
- [路线图](./roadmap.md)
---
## CI模式与机器可读报告
相关源码文件
以下源码文件用于生成本页说明：
- [src/agent_polis/ci.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/ci.py)
- [src/agent_polis/governance/policy.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/policy.py)
- [src/agent_polis/governance/prompt_scanner.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/prompt_scanner.py)
- [src/agent_polis/actions/models.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/actions/models.py)
- [src/agent_polis/governance/presets.py](https://github.com/agent-polis/impact-preview/blob/main/src/agent_polis/governance/presets.py)
- [README.md](https://github.com/agent-polis/impact-preview/blob/main/README.md)
# CI模式与机器可读报告
## 概述
Agent Polis 提供了**确定性 CI 评估模式**，专为持续集成环境设计，用于在没有人工交互的情况下对动作请求进行策略评估。该模式的核心目标是：
- 确保 CI 流程中**不触发任何提示路径**，避免阻塞自动化管道
- 返回**稳定的退出码**，使 CI 工具能够根据策略决策自动采取行动
- 生成**机器可读的 JSON 报告**，便于 PR 门禁集成和数据聚合
CI 模式是 Agent Polis v0.2.x 的核心功能之一，支持与 GitHub Actions、GitLab CI、Jenkins 等主流 CI 系统无缝集成。资料来源：[src/agent_polis/ci.py:1-50]()
## 核心组件
### CI 模块架构
CI 模块位于 `src/agent_polis/ci.py`，主要包含以下组件：
```mermaid
graph TD
A[动作请求列表] --> B[ImpactAnalyzer]
B --> C[ActionPreview 风险评估]
C --> D[PromptInjectionScanner]
D --> E[PolicyEvaluator]
E --> F[CIPolicyReport]
F --> G[退出码判定]
G --> H[exit 0/2/3]
I[PolicyConfig] --> E
J[工作目录] --> B
```
### 关键数据结构
| 类名 | 用途 | 位置 |
|------|------|------|
| `CIPolicyReport` | 顶级 CI 报告输出 | `ci.py:41-48` |
| `CIActionReport` | 单个动作的评估报告 | `ci.py:29-39` |
| `CIReasonCount` | 阻断原因统计 | `ci.py:22-27` |
| `PolicyDecision` | 策略决策枚举 | `policy.py:14-18` |
资料来源：[src/agent_polis/ci.py:22-48]()
## 报告模式
### CIPolicyReport 结构
```json
{
"schema_version": "1",
"policy_version": "preset-startup-1",
"totals": {
"allow": 5,
"require_approval": 2,
"deny": 1
},
"top_blocking_reasons": [
{"reason": "prompt-injection-detected", "count": 3},
{"reason": "secrets-in-target", "count": 1}
],
"actions": [
{
"index": 0,
"action_type": "file_write",
"target": "src/main.py",
"risk_level": "low",
"policy_decision": "allow",
"policy_matched_rule_id": "allow-safe-writes",
"scanner_max_severity": "none",
"scanner_reason_ids": []
}
]
}
```
### CIActionReport 字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `index` | int | 动作在输入列表中的序号 |
| `action_type` | string | 动作类型（file_write, shell_command 等） |
| `target` | string | 目标路径或资源标识 |
| `risk_level` | string | 风险等级（low/medium/high/critical） |
| `policy_decision` | string | 策略决策结果 |
| `policy_matched_rule_id` | string\|null | 匹配的规则 ID |
| `scanner_max_severity` | string | 扫描器最高严重级别 |
| `scanner_reason_ids` | list[string] | 扫描发现的原因 ID 列表 |
资料来源：[src/agent_polis/ci.py:29-39]()
## 退出码机制
CI 模式通过退出码向 CI 系统传递评估结果，确保与 CI 工具的集成具有确定性。
```mermaid
graph LR
A[evaluate] --> B{存在 DENY?}
B -->|是| C[exit 3]
B -->|否| D{存在 REQUIRE_APPROVAL?}
D -->|是| E[exit 2]
D -->|否| F[exit 0]
style C fill:#ff6b6b
style E fill:#ffd93d
style F fill:#6bcf6b
```
### 退出码对照表
| 退出码 | 含义 | CI 行为建议 |
|--------|------|-------------|
| `0` | 所有动作均允许 | 构建通过，继续下一阶段 |
| `2` | 至少一个动作需要审批 | 构建暂停，等待人工审批 |
| `3` | 至少一个动作被拒绝 | 构建失败，阻止合并 |
此机制确保 CI 系统无需解析文本输出即可做出决策。资料来源：[src/agent_polis/ci.py:50-62]()
## CLI 使用方式
### 基础命令
```bash
# 使用默认 startup 预设评估动作
impact-preview ci --actions actions.json --output report.json
# 指定预设
impact-preview ci --preset fintech --actions actions.json
# 指定自定义策略文件
impact-preview ci --policy policy.json --actions actions.json --output report.json
# 仅返回退出码（不输出报告）
impact-preview ci --actions actions.json --exit-only
```
### 输入文件格式
```json
{
"actions": [
{
"action_type": "file_write",
"target": "src/config.py",
"description": "Update configuration",
"payload": {"content": "..."}
}
]
}
```
支持两种输入格式：
- JSON 数组：直接包含动作列表
- JSON 对象：包含 `actions` 键的对象
资料来源：[src/agent_polis/ci.py:105-125]()
## CI 模式下的策略评估
### 确定性原则
CI 模式下的策略评估遵循**确定性原则**：
1. **无随机性**：所有匹配规则的结果可重现
2. **规则优先级**：按 `priority` 字段降序匹配，高优先级规则优先
3. **规则特异性**：优先级相同时，更具体的规则优先
```mermaid
graph TD
A[接收动作请求] --> B[按优先级排序规则]
B --> C[遍历规则列表]
C --> D{规则匹配?}
D -->|否| E[下一规则]
D -->|是| F{规则启用?}
F -->|是| G[返回决策 + 规则ID]
F -->|否| E
E --> C
C --> H[应用默认决策]
```
### 决策追踪
每个策略评估结果包含 `trace` 字段，记录完整的匹配过程：
```python
@dataclass
class PolicyEvaluation:
decision: PolicyDecision
matched_rule_id: str | None
matched_rule_priority: int | None
matched_rule_specificity: int | None
trace: dict[str, Any]
```
资料来源：[src/agent_polis/governance/policy.py:40-55]()
## 扫描器集成
### 提示注入检测
CI 模式集成了 `PromptInjectionScanner`，用于检测动作请求中的提示注入和危险指令：
| 扫描严重级别 | 对应风险等级 | 说明 |
|--------------|--------------|------|
| `LOW` | 低风险 | 可疑模式但不明确 |
| `MEDIUM` | 中风险 | 可能存在注入尝试 |
| `HIGH` | 高风险 | 明显的注入模式 |
| `CRITICAL` | 严重风险 | 已确认的恶意模式 |
扫描结果汇总为机器可读的原因 ID 列表，便于在报告中聚合统计。资料来源：[src/agent_polis/governance/prompt_scanner.py:18-35]()
### 阻断原因聚合
`top_blocking_reasons` 字段按原因 ID 统计阻断次数，按频次降序排列：
```python
reason_counts: dict[str, int] = {}
for finding in scan.findings:
reason_counts[finding.reason_id] = reason_counts.get(finding.reason_id, 0) + 1
top_reasons = sorted(
(CIReasonCount(reason=reason, count=count)
for reason, count in reason_counts.items()),
key=lambda item: (-item.count, item.reason),
)[:10]
```
资料来源：[src/agent_polis/ci.py:88-94]()
## 预设包
CI 模式可与预设包配合使用，快速配置符合特定场景的策略规则。
### 预设对比
| 预设 | 适用场景 | 默认决策 | 特殊规则 |
|------|----------|----------|----------|
| `startup` | 早期创业公司 | `require_approval` | 文档/测试目录允许低中风险 |
| `fintech` | 金融科技 | `require_approval` | 拒绝访问 secrets/keys |
| `games` | 游戏开发 | `require_approval` | 允许资源文件低中风险变更 |
### fintech 预设示例
```python
{
"id": "deny-secrets-and-keys",
"description": "阻止访问 secrets/keys 文件",
"decision": "deny",
"priority": 0,
"target_contains": [".env", ".ssh", "credentials", "secrets", ".pem"],
"metadata": {
"rationale": "金融环境将密钥处理视为受监管控制面"
}
}
```
资料来源：[src/agent_polis/governance/presets.py:45-65]()
## GitHub Actions 集成
### 完整工作流示例
```yaml
name: Agent Polis CI Gate
on:
pull_request:
paths:
- 'src/**'
- 'lib/**'
jobs:
policy-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install impact-preview
run: pip install impact-preview
- name: Generate action requests
run: |
cat > actions.json << 'EOF'
{
"actions": [
{"action_type": "file_write", "target": "src/main.py", "description": "Update main"}
]
}
EOF
- name: Run CI evaluation
id: polis
run: |
impact-preview ci \
--preset startup \
--actions actions.json \
--output polis-report.json
echo "exit_code=$?" >> $GITHUB_OUTPUT
# 输出摘要
echo "## Agent Polis Report" >> $GITHUB_STEP_SUMMARY
echo "```json" >> $GITHUB_STEP_SUMMARY
cat polis-report.json >> $GITHUB_STEP_SUMMARY
echo "```" >> $GITHUB_STEP_SUMMARY
- name: Upload report
uses: actions/upload-artifact@v4
with:
name: polis-report
path: polis-report.json
```
### 条件分支策略
```yaml
- name: Handle result
run: |
if [ ${{ steps.polis.outputs.exit_code }} -eq 3 ]; then
echo "::error::Policy denied: blocking changes detected"
exit 1
elif [ ${{ steps.polis.outputs.exit_code }} -eq 2 ]; then
echo "::warning::Some actions require approval"
fi
```
## 与审计记录的关系
CI 模式生成的报告与审计系统共享策略和扫描器上下文：
```mermaid
graph LR
A[ActionService] --> B[Audit Trail]
A --> C[CI Report]
B --> D{包含决策 + 规则ID + 扫描结果}
C --> E{包含决策 + 规则ID + 扫描结果}
```
审计记录包含：
- 策略版本和决策
- 匹配的规则 ID 和优先级
- 扫描器发现列表
- 风险因子
资料来源：[src/agent_polis/actions/service.py:65-90]()
## 最佳实践
### 1. 报告文件命名
```bash
# 使用时间戳避免覆盖
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
impact-preview ci --actions actions.json --output "report_${TIMESTAMP}.json"
```
### 2. 失败时保留报告
```yaml
- name: Run CI evaluation
if: always() # 即使步骤失败也上传报告
uses: actions/upload-artifact@v4
with:
name: polis-report-fallback
path: polis-report.json
```
### 3. 与代码审查集成
将报告内容附加到 PR 评论：
```bash
# 生成 PR 评论内容
REPORT_SUMMARY=$(cat polis-report.json | jq -r '.totals | "Allowed: \(.allow), Pending: \(.require_approval), Denied: \(.deny)"')
gh pr comment $PR_NUMBER --body "Agent Polis: $REPORT_SUMMARY"
```
## 限制与已知问题
### 当前限制
| 限制项 | 说明 | 相关 Issue |
|--------|------|------------|
| 暂不支持数据库操作预览 | `db_execute` 类型动作的预览功能计划在 v0.3.0 实现 | AP-103 |
| 暂不支持 API 调用预览 | `api_call` 类型动作的预览功能计划在 v0.4.0 实现 | - |
| 报告大小上限 | 大型代码库的完整 diff 可能导致报告过大 | - |
### 稳定性保证
CI 模式经过以下测试验证：
- 非 TTY 环境下的确定性执行
- 稳定的状态码行为
- 回归测试覆盖绕过尝试
资料来源：[社区 Issue AP-204](https://github.com/agent-polis/impact-preview/issues/10)
## 路线图
| 版本 | 计划功能 | 状态 |
|------|----------|------|
| v0.2.x | CI 模式基础功能 | 已完成 |
| v0.3.0 | 数据库操作预览集成 | 规划中 |
| v0.4.0 | API 调用预览集成 | 规划中 |
| v0.5.0 | IDE 集成（Cursor, VS Code） | 规划中 |
| v1.0.0 | 生产就绪版本 | 规划中 |
资料来源：[README.md:80-90](https://github.com/agent-polis/impact-preview/blob/main/README.md)
## 相关文档
- [策略系统文档](./governance/policy.md)
- [预设包指南](./governance/presets.md)
- [提示注入扫描器](./governance/prompt_scanner.md)
- [审计系统](../events/audit_trail.md)
---
---
## Doramagic 踩坑日志
项目：agent-polis/impact-preview
摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：AP-101 Policy schema and parser。
## 1. 配置坑 · 来源证据：AP-101 Policy schema and parser
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AP-101 Policy schema and parser
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_52a7602d08fd4a34a02a058587179586 | https://github.com/agent-polis/impact-preview/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 配置坑 · 来源证据：AP-102 Policy evaluator with deterministic precedence
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AP-102 Policy evaluator with deterministic precedence
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7d4cca25cd1347289c9e6834c0f806fc | https://github.com/agent-polis/impact-preview/issues/2 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 配置坑 · 来源证据：AP-203 Machine-readable CI policy report output
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：AP-203 Machine-readable CI policy report output
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_71b0a0a48b3f4a3ea7107c911c8b8733 | https://github.com/agent-polis/impact-preview/issues/9 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | mcp_registry:io.github.agent-polis/impact-preview:0.2.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agent-polis%2Fimpact-preview/versions/0.2.1 | README/documentation is current enough for a first validation pass.
## 5. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.agent-polis/impact-preview:0.2.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agent-polis%2Fimpact-preview/versions/0.2.1 | last_activity_observed missing
## 6. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | mcp_registry:io.github.agent-polis/impact-preview:0.2.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agent-polis%2Fimpact-preview/versions/0.2.1 | no_demo; severity=medium
## 7. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | mcp_registry:io.github.agent-polis/impact-preview:0.2.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agent-polis%2Fimpact-preview/versions/0.2.1 | no_demo; severity=medium
## 8. 安全/权限坑 · 来源证据：AP-105 Extend audit records with policy/scanner context
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AP-105 Extend audit records with policy/scanner context
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ff00c63559844328a271d0587352d351 | https://github.com/agent-polis/impact-preview/issues/5 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.agent-polis/impact-preview:0.2.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agent-polis%2Fimpact-preview/versions/0.2.1 | issue_or_pr_quality=unknown
## 10. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | mcp_registry:io.github.agent-polis/impact-preview:0.2.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agent-polis%2Fimpact-preview/versions/0.2.1 | release_recency=unknown