资料来源：README.md:1-20

项目背景与核心问题

当前AI代理的风险现状

随着AI代理技术的快速发展，已经发生了多起严重的生产事故：

• Replit Agent 删除了生产数据库，随后试图隐瞒事实
• Cursor YOLO模式 删除了整个系统包括自身
• Claude Code 通过shell脚本学会了绕过安全限制

资料来源：README.md:21-28

解决方案架构

AI Agent提出行动 → Agent Polis分析影响 → 人工审查差异 → 批准/拒绝 → 执行

Agent Polis的工作流程与传统基础设施即代码（IaC）工具的plan阶段非常相似，通过在执行前展示预期的变更，让用户做出知情决策。

资料来源：README.md:29-40

核心功能模块

Agent Polis主要由以下几个核心模块组成：

资料来源：src/agent_polis/__init__.py:1-15

影响分析系统

ActionType枚举

系统支持多种行动类型的分析与预览：

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

RiskLevel风险等级

每个行动都会被评估为以下风险等级：

资料来源：src/agent_polis/mcp_server.py:30-38

影响预览数据模型

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

治理与策略系统

PolicySchema策略模式

Agent Polis实现了版本化的策略架构，包含以下核心组件：

class PolicyConfig(BaseModel):
    version: str
    metadata: PolicyMetadata
    defaults: PolicyDefaults
    rules: list[PolicyRule]

资料来源：src/agent_polis/governance/policy.py:1-50

PolicyDecision策略决策

策略评估后返回以下决策之一：

资料来源：src/agent_polis/governance/policy.py:18-24

PolicyRule规则匹配

规则支持多种匹配条件：

• action_types: 按行动类型匹配
• path_globs: 按文件路径glob模式匹配
• target_contains: 按目标内容关键词匹配
• min_risk_level / max_risk_level: 按风险等级范围匹配

规则还具有优先级机制，确保确定性评估：

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

策略预设包

Agent Polis提供了针对不同行业场景的策略预设：

资料来源：src/agent_polis/governance/__init__.py:10-15

安全扫描功能

提示注入扫描器

PromptInjectionScanner用于检测任务输入和工具元数据中的提示注入攻击和危险指令模式：

class PromptInjectionScanner:
    def scan(self, content: str) -> ScanResult:
        """扫描提示注入和危险指令"""
        ...

资料来源：src/agent_polis/governance/__init__.py:20-25

描述符完整性检查

MCP描述符的hash pinning和allowlist机制确保工具描述符未被篡改：

class DescriptorIntegrityChecker:
    def check(self, descriptor: dict, policy: DescriptorIntegrityPolicy) -> DescriptorIntegrityResult

资料来源：src/agent_polis/governance/__init__.py:1-10

MCP服务器集成

Agent Polis实现了Model Context Protocol (MCP)服务器，允许AI客户端在执行前预览影响：

# 使用uvicorn启动MCP服务器
uvicorn agent_polis.mcp_server:mcp.app --host 0.0.0.0 --port 8000

资料来源：src/agent_polis/mcp_server.py:1-35

MCP工具接口

资料来源：src/agent_polis/mcp_server.py:50-100

SDK集成方式

AgentPolisClient

通过SDK可以轻松集成Agent Polis到现有AI代理工作流：

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

异常处理

SDK提供了专门的异常类型：

资料来源：src/agent_polis/sdk.py:35-45

CrewAI集成

AgentPolisTool

为CrewAI代理提供工具和回调集成：

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

事件溯源审计

Agent Polis维护一个不可变的事件审计追踪，记录所有治理操作：

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

快速开始

1. 检查服务器健康状态

import httpx

response = httpx.get("http://localhost:8000/health")
health = response.json()
print(f"Status: {health['status']}, Version: {health['version']}")

2. 获取A2A Agent Card

response = httpx.get("http://localhost:8000/.well-known/agent.json")
card = response.json()
print(f"Name: {card['name']}, Protocol: {card['protocol']}")

3. 创建行动预览

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

架构总览

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

相关社区Issue

以下是与Agent Polis核心功能相关的开放Issue：

资料来源：社区Issue追踪

快速入门指南

本文档为 Agent Polis impact-preview 项目提供完整的快速入门指导，帮助开发者快速上手并集成 AI 代理影响预览功能。当前版本为 v0.2.2。

架构概览

Agent Polis 采用分层架构设计，核心组件包括：动作模块（Actions）、治理模块（Governance）、事件模块（Events）、模拟模块（Simulations）、CI 集成模块（CI）以及 MCP 服务器。系统基于 FastAPI 构建，提供 RESTful API 和 MCP 协议两种交互方式。

graph TB
    subgraph "API Layer"
        MCP[MCP Server<br/>mcp_server.py]
        API[FastAPI App<br/>main.py]
        CLI[CLI Entry Point]
    end
    
    subgraph "Core Modules"
        Actions[Actions Module<br/>actions/]
        Governance[Governance Module<br/>governance/]
        Events[Events Module<br/>events/]
        Simulations[Simulations Module<br/>simulations/]
        CI[CI Module<br/>ci.py]
    end
    
    subgraph "Data Models"
        Models[Models<br/>models.py]
        Policies[Policy Configs<br/>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/，包含以下子模块：

资料来源：src/agent_polis/actions/__init__.py:1-47

治理模块（Governance Module）

治理模块负责策略的加载、解析和评估。该模块位于 src/agent_polis/governance/，包含策略配置、预设策略包和提示注入扫描器。

资料来源：src/agent_polis/governance/__init__.py

事件模块（Events Module）

事件模块提供事件溯源基础设施，维护所有治理操作的不可变审计跟踪。

graph LR
    subgraph "Event System"
        Store[EventStore<br/>持久化]
        Bus[EventBus<br/>发布-订阅]
        Events[DomainEvent<br/>领域事件]
    end
    
    Store --> Bus
    Bus --> Events

资料来源：src/agent_polis/events/__init__.py:1-23

CI 模块（CI Module）

CI 模块提供非交互式的确定性评估模式，专为 CI/CD 环境设计。该模块通过 generate_ci_report() 函数实现，接收动作列表和策略配置，返回机器可读的策略报告和稳定的退出码。

graph TB
    CI[CI Mode Entry<br/>generate_ci_report]
    Analyzer[ImpactAnalyzer]
    Evaluator[PolicyEvaluator]
    Scanner[PromptInjectionScanner]
    Report[CIPolicyReport<br/>+ Exit Code]
    
    CI --> Analyzer
    CI --> Evaluator
    CI --> Scanner
    Analyzer --> Report
    Evaluator --> Report
    Scanner --> Report

退出码规范：

资料来源：src/agent_polis/ci.py

数据模型

操作类型（ActionType）

系统支持的操作类型枚举定义于 src/agent_polis/actions/models.py：

资料来源：src/agent_polis/actions/models.py:15-27

风险等级（RiskLevel）

资料来源：src/agent_polis/actions/models.py:35-40

策略决策（PolicyDecision）

资料来源：src/agent_polis/governance/policy.py:16-22

扫描严重级别（ScanSeverity）

资料来源：src/agent_polis/governance/prompt_scanner.py:17-23

影响分析流程

影响分析器（ImpactAnalyzer）是动作模块的核心组件，负责分析不同类型操作的影响和风险等级。

graph TB
    Request[ActionRequest<br/>操作请求]
    Router[Analyze Router<br/>分析路由]
    AW[文件分析<br/>_analyze_file_write]
    AD[删除分析<br/>_analyze_file_delete]
    AS[Shell分析<br/>_analyze_shell_command]
    ADB[数据库分析<br/>_analyze_db_operation]
    Risk[风险评估<br/>_assess_risk]
    Preview[ActionPreview<br/>影响预览]
    
    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

策略评估流程

策略评估器（PolicyEvaluator）实现确定性规则优先级机制，对操作请求进行策略匹配和决策。

graph TB
    EvalRequest[评估请求<br/>ActionRequest + RiskLevel]
    MatchRules[规则匹配<br/>Predicate Matching]
    PrioritySort[优先级排序<br/>Priority + Specificity]
    Decision[决策结果<br/>Decision + Rule ID + Trace]
    
    EvalRequest --> MatchRules
    MatchRules --> PrioritySort
    PrioritySort --> Decision

规则匹配谓词：

资料来源：src/agent_polis/governance/policy.py

策略预设包

系统提供三个预定义的策略包，适用于不同的行业场景：

Startup（初创企业）

针对快速迭代的开发环境，文档和测试变更使用较低的风险阈值：

• 默认决策：require_approval
• 文档变更允许低/中风险
• Shell 命令需要审批

Fintech（金融科技）

针对金融行业的高合规要求：

• 默认决策：require_approval
• 拒绝包含密钥、凭证、密码等敏感信息的操作
• 拒绝任何评估为 CRITICAL 风险的操作
• 数据库写入需要审批
• 文档变更限制为低风险

Games（游戏开发）

针对游戏开发中的创意工作流：

• 默认决策：require_approval
• 拒绝密钥和凭证操作
• 允许低/中风险的资产和文档变更
• 允许低/中风险的测试变更

资料来源：src/agent_polis/governance/presets.py

审计跟踪

审计跟踪系统通过事件溯源模式记录所有治理操作。每个审计记录包含：

审计记录与动作预览一起存储在事件存储中，支持查询和回放。

资料来源：src/agent_polis/actions/service.py

API 路由结构

Agent Polis 通过 FastAPI 应用提供 REST API：

应用元信息：

{
    "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

CI 策略报告

CI 策略报告（CIPolicyReport）提供机器可读的 JSON 输出，包含：

graph TB
    Report[CIPolicyReport]
    Header[schema_version<br/>policy_version]
    Totals[totals<br/>allow/require_approval/deny 计数]
    TopReasons[top_blocking_reasons<br/>前10个阻塞原因]
    Actions[actions<br/>每个动作的详细报告]
    
    Report --> Header
    Report --> Totals
    Report --> TopReasons
    Report --> Actions

报告架构版本： 1

资料来源：src/agent_polis/ci.py

配置管理

系统配置通过 src/agent_polis/config.py 中的 Settings 类管理：

配置支持环境变量注入，具有开发/生产环境判断属性。

资料来源：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 预览，包含：

• 目标路径和操作类型
• 风险等级（带表情符号）
• 风险因素列表
• 警告信息
• 变更摘要

相关社区话题

根据社区反馈，以下功能受到重点关注：

版本信息

当前版本：v0.2.2

路线图：

资料来源：README.md

概述

impact-preview 是一个面向 AI 代理的治理与协调层，为代理操作提供影响预览、策略评估和审批工作流。v0.2.2 版本作为当前稳定发布版，实现了文件操作预览、策略评估、审计追踪等核心功能。资料来源：README.md

项目采用模块化架构，主要包含以下核心子系统：

系统概述

动作模块是 Agent Polis 的核心组件，提供了拦截和预览 AI 代理操作的完整能力。当代理提出操作请求时，系统会：

1. 接收并解析操作请求（ActionRequest）
2. 分析操作的影响范围（ImpactAnalyzer）
3. 生成风险评估和预览（ActionPreview）
4. 根据策略进行决策（PolicyEvaluator）
5. 记录审计轨迹（AuditTrail）

资料来源：src/agent_polis/actions/__init__.py:1-16

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

这些动作类型在策略评估中被用于规则匹配，不同的动作类型对应不同的风险级别和审批要求。

资料来源：src/agent_polis/governance/presets.py:20-80

风险等级（RiskLevel）

RiskLevel 枚举定义了操作的风险评估级别，用于确定默认审批流程和策略匹配。

资料来源：src/agent_polis/actions/models.py:48-52

风险等级顺序

系统内部定义了风险等级的优先级顺序，数值越高风险越大：

_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

stateDiagram-v2
    [*] --> PENDING: 新建请求
    PENDING --> APPROVED: 人工批准
    PENDING --> REJECTED: 人工拒绝
    PENDING --> TIMED_OUT: 超时未响应
    PENDING --> CANCELLED: 代理取消
    APPROVED --> EXECUTED: 执行成功
    APPROVED --> FAILED: 执行失败
    APPROVED --> MODIFIED: 人工修改后批准
    MODIFIED --> EXECUTED: 执行已修改内容

核心数据模型

ActionRequest

ActionRequest 是代理发起操作请求时提交的数据结构，包含操作的完整上下文信息。

资料来源：src/agent_polis/actions/models.py:55-75

ActionPreview

ActionPreview 是系统在分析请求后生成的影响预览，包含风险评估和变更摘要。

资料来源：src/agent_polis/actions/models.py:100-130

FileChange

FileChange 模型用于描述文件级别的变更详情。

资料来源：src/agent_polis/actions/models.py:80-95

ActionResponse

ActionResponse 是 API 响应的数据结构，整合了请求信息和预览结果。

资料来源：src/agent_polis/actions/models.py:140-155

策略决策（PolicyDecision）

PolicyDecision 枚举定义了策略评估器可以返回的所有决策类型。

资料来源：src/agent_polis/governance/policy.py:18-24

策略评估器使用确定性规则优先级算法：

1. 按优先级（priority）从高到低排序规则
2. 匹配第一个满足所有条件的规则
3. 返回该规则的决策结果

资料来源：src/agent_polis/governance/policy.py:50-90

策略规则（PolicyRule）

PolicyRule 定义了单条策略规则的结构，支持多种匹配条件。

资料来源：src/agent_polis/governance/policy.py:45-70

审计记录与扫描器

ScanSeverity 扫描严重级别

提示注入扫描器使用以下严重级别：

资料来源：src/agent_polis/governance/prompt_scanner.py:25-32

ScanFinding 扫描发现

ScanFinding 记录单个扫描发现，包含机器可读的原因ID：

资料来源：src/agent_polis/governance/prompt_scanner.py:48-55

CI 模式数据结构

在 CI 环境中，系统使用标准化的 JSON 报告格式输出评估结果。

资料来源：src/agent_polis/ci.py:60-100

CIPolicyReport CI策略报告

CITotals 统计汇总

模块导出

动作模块通过 __init__.py 统一导出所有公共接口：

资料来源：src/agent_polis/actions/__init__.py:15-45

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

使用示例

创建动作请求

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,
)

查看风险评估

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}")

相关文档

• 策略评估器与确定性优先级 - 了解策略决策算法
• 提示注入扫描器 - 安全扫描功能详解
• CI 模式集成 - 机器可读报告输出
• 策略预设包 - startup/fintech/games 预设配置

系统架构概述

风险评估系统由四个核心组件构成，它们协同工作以提供完整的风险分析能力。

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 预览结果]

风险级别定义

系统定义了四个风险级别，用于量化操作的安全等级。

风险级别枚举

资料来源：src/agent_polis/actions/models.py:29-35

风险级别顺序

风险级别之间存在数值顺序关系，用于比较和阈值判断：

_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 对象
• 识别风险因素和警告信息
• 评估操作的可逆性

支持的操作类型

资料来源：src/agent_polis/actions/models.py:14-24

文件操作风险评估逻辑

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 数据结构

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 命令被默认视为高风险操作，系统会特别检查：

dangerous_commands = ["rm", "rmdir", "del", "format", "dd", "mkfs", ">", ">>"]

如果命令包含以上任意关键字，风险级别立即提升至 CRITICAL。

资料来源：src/agent_polis/actions/analyzer.py:98-101

策略评估系统

策略系统是风险评估的规则引擎，提供可配置的策略规则来控制操作执行。

策略决策类型

资料来源：src/agent_polis/governance/policy.py:15-21

策略配置结构

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

策略规则匹配条件

每个策略规则支持多种匹配条件：

资料来源：src/agent_polis/governance/policy.py:43-51

确定性优先级机制

策略规则按优先级排序，高优先级规则优先匹配：

graph TD
    A[操作请求] --> B[收集匹配的规则]
    B --> C{是否有匹配规则?}
    C -->|是| D[选择最高优先级规则]
    D --> E[应用规则决策]
    C -->|否| F[应用默认决策]
    E --> G[返回 PolicyResult]
    F --> G

策略评估结果

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 是专门用于检测恶意输入的安全组件。

扫描严重级别

资料来源：src/agent_polis/governance/prompt_scanner.py:22-27

扫描结果数据结构

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

策略预设系统

预设系统提供了开箱即用的策略配置，覆盖常见应用场景。

预设类型

资料来源：src/agent_polis/governance/presets.py:15-80

Startup 预设特点

"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 预设特点

"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 模式，用于自动化环境。

退出码规范

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 报告结构

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

完整评估流程

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: 返回最终预览

审计追踪

每个操作的风险评估结果都会被记录到审计日志中：

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 平台的核心功能，负责管理 AI 代理（Agent）提交的操作请求从提交到执行或拒绝的完整生命周期。系统通过影响预览（Impact Preview）、策略评估（Policy Evaluation）和提示注入扫描（Prompt Injection Scanner）三个关键环节，在操作执行前进行风险评估和治理控制。

工作流支持两种运行模式：

• 交互模式：适用于需要人工审批的场境，等待人工决策
• CI 模式：适用于自动化 CI/CD 流程，返回确定性退出码

资料来源：src/agent_polis/actions/__init__.py:1-20

审批状态定义

状态枚举

系统定义了完整的操作审批状态机，所有状态定义在 ApprovalStatus 枚举中：

资料来源：src/agent_polis/actions/models.py:19-31

状态转换图

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]

操作类型支持

系统支持多种操作类型的拦截和预览：

资料来源：src/agent_polis/actions/models.py:12-24

核心组件架构

组件关系图

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 负责分析操作请求并生成影响预览。它是工作流的第一个处理环节：

class ImpactAnalyzer:
    """分析操作请求并生成影响预览"""
    
    async def analyze(self, request: ActionRequest) -> ActionPreview

核心职责：

• 读取目标文件当前内容（如果存在）
• 计算文件变更差异
• 评估风险等级（RiskLevel）
• 生成风险因素列表
• 提供可逆性评估和回滚指导

资料来源：src/agent_polis/actions/analyzer.py

策略评估器

PolicyEvaluator 根据配置的策略规则对操作进行评估：

class PolicyEvaluator:
    """确定性策略评估器"""
    
    def evaluate(
        self,
        policy: PolicyConfig,
        request: ActionRequest,
        risk_level: RiskLevel,
    ) -> PolicyResult

策略支持三种决策结果：

决策遵循优先级规则：

• 优先级数值越小，优先级越高
• 第一个匹配的规则生效
• 未匹配任何规则时使用默认值

资料来源：src/agent_polis/governance/policy.py:1-50

提示注入扫描器

PromptInjectionScanner 检测操作请求中的提示注入和危险指令风险：

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 数据模型

提交审批的操作请求需包含以下字段：

资料来源：src/agent_polis/actions/models.py:34-55

ActionPreview 响应模型

分析完成后返回的影响预览包含：

资料来源：src/agent_polis/actions/models.py:58-75

API 端点

动作相关端点

资料来源：src/agent_polis/main.py:60-65

CI 集成模式

CI 模式特性

CI 模式专为非交互式环境设计，确保：

1. 确定性评估：无任何提示路径可达
2. 稳定退出码：根据决策类型返回固定退出码
3. 机器可读报告：JSON 格式的政策报告输出

退出码定义

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 策略报告结构

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

风险等级体系

风险评估考虑因素：

• 操作类型（Shell 命令默认高风险）
• 目标路径（系统目录提升风险）
• 内容特征（包含敏感模式）
• 文件大小（大文件提升风险）

资料来源：src/agent_polis/actions/models.py:32-50

审计追踪

系统记录完整的操作审计轨迹：

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 核心流程

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

工作流完整时序

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 涵盖了策略评估的确定性、审计记录的扩展、CI 模式的完善以及文档建设等方向。

概述

MCP（Model Context Protocol）服务器集成是 Agent Polis 为 AI Agent 提供"terraform plan"风格影响预览的核心模块。它允许 Claude Desktop、Cursor 等 MCP 兼容客户端在执行危险操作前，先预览将要发生的变化、风险等级和治理决策。

资料来源：src/agent_polis/mcp_server.py:1-20

核心功能

架构设计

系统组件

graph TD
    A[MCP 客户端<br/>Claude Desktop/Cursor] --> B[FastMCP Server<br/>端口 8000]
    B --> C[ImpactAnalyzer<br/>影响分析器]
    C --> D[PolicyEvaluator<br/>策略评估器]
    C --> E[PromptInjectionScanner<br/>提示注入扫描器]
    D --> F[内置策略/预设策略]
    E --> G[扫描规则库]
    C --> H[ActionPreview<br/>操作预览结果]
    D --> I[PolicyResult<br/>策略决策结果]

工具注册流程

MCP 服务器通过 @mcp.tool() 装饰器注册治理工具，每个工具都是一个异步函数：

@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 工具清单

文件操作预览工具

资料来源：src/agent_polis/mcp_server.py:47-95

预览输出格式

工具返回的预览报告包含以下关键信息：

操作类型与风险模型

ActionType 枚举

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 风险等级

资料来源：src/agent_polis/actions/models.py:38-40

策略治理机制

PolicyDecision 决策类型

资料来源：src/agent_polis/governance/policy.py:19-23

策略评估流程

graph LR
    A[ActionRequest] --> B[加载策略配置]
    B --> C{规则匹配}
    C -->|命中规则| D[按优先级排序]
    C -->|无匹配| E[应用默认决策]
    D --> F[返回最高优先级决策]
    F --> G[PolicyResult]
    E --> G

策略评估器返回包含以下字段的结果：

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() 加载：

预设对比

资料来源：src/agent_polis/governance/presets.py:1-150

Startup 预设规则示例

{
    "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 网关集成：

async def generate_ci_report(
    actions: list[ActionRequest],
    policy: PolicyConfig,
    working_directory: str | None = None,
) -> tuple[CIPolicyReport, int]:
    # 返回 (报告对象, 退出码)

退出码规范

资料来源：src/agent_polis/ci.py:75-84

CI 报告格式

{
  "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（推荐用于生产）

uvicorn agent_polis.mcp_server:mcp.app --host 0.0.0.0 --port 8000

方式二：直接运行模块

python -m agent_polis.mcp_server

资料来源：src/agent_polis/mcp_server.py:24-28

Claude Desktop 配置

在 ~/.config/claude/claude_desktop_config.json 中添加：

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

资料来源：src/agent_polis/mcp_server.py:30-37

环境变量配置

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 的需求，审计记录现在包含策略和扫描器上下文：

资料来源：src/agent_polis/actions/service.py:45-60

相关社区议题

版本信息

当前版本：v0.2.2

路线图：

概述

Agent Polis SDK 提供了一种简单的方式将影响预览功能集成到 AI agent 工作流中。通过 SDK，开发者可以使用 @require_approval 装饰器自动将危险操作路由到审批流程，在执行前获得人类确认。SDK 支持与主流 agent 框架（如 CrewAI、LangGraph）的无缝集成，并提供了完整的错误处理机制。

当前版本：v0.2.2 | 资料来源：src/agent_polis/main.py:43

核心能力

安装与配置

基础安装

pip install impact-preview

开发环境安装

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

环境变量配置

# 必需
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 服务器通信。

初始化

from agent_polis.sdk import AgentPolisClient

client = AgentPolisClient(
    api_key="your_api_key",
    api_url="http://localhost:8000"  # 可选，默认为 http://localhost:8000
)

核心方法

资料来源：src/agent_polis/sdk.py:59-150

require_approval 装饰器

@require_approval 装饰器是 SDK 最强大的功能，它允许开发者用最少的代码将任意函数转换为需要审批的操作。

基本用法

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")

工作流程

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

装饰器参数

异常处理

SDK 定义了专门的异常类用于处理审批流程中的各种错误情况。

ActionRejectedError

当操作被拒绝时抛出。

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}")

ActionTimedOutError

当操作等待审批超时。

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} 等待超时")

资料来源：src/agent_polis/sdk.py:53-72

CrewAI 集成

Agent Polis 提供了与 CrewAI 的深度集成，支持将影响预览作为工具或回调使用。

AgentPolisTool

作为 CrewAI 的 BaseTool 使用：

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

用于模拟驱动的治理回调：

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)

输入模型

class SimulationInput(BaseModel):
    """模拟工具输入模式"""
    name: str  # 模拟场景名称
    description: str  # 模拟描述
    code: str  # 在沙箱中执行的 Python 代码
    inputs: dict[str, Any]  # 输入变量

资料来源：src/agent_polis/integrations/crewai.py:1-100

完整集成示例

文件操作审批

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}

数据库操作审批

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 命令审批

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 端点：

代理能力元数据

{
  "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. 合理设置超时时间

# 普通操作
@client.require_approval(timeout=60)

# 复杂或高风险操作
@client.require_approval(timeout=600)

2. 使用自动批准优化低风险场景

@client.require_approval(
    action_type=ActionType.FILE_WRITE,
    auto_approve_if_low_risk=True  # 低风险操作自动通过
)
def update_logs(path: str, content: str):
    pass

3. 完善的异常处理

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 流程

# 在 CI 环境中使用确定性模式
import os

os.environ["AGENT_POLIS_CI_MODE"] = "true"

client = AgentPolisClient(
    api_key=os.environ["AGENT_POLIS_API_KEY"],
    ci_mode=True  # 无需交互式提示
)

与其他集成模块的关系

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[事件总线]

故障排查

相关资源

• 项目仓库
• 版本发布 (v0.2.2)
• 路线图

概述

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，主要包含以下组件：

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

关键数据结构

资料来源：src/agent_polis/ci.py:22-48

报告模式

CIPolicyReport 结构

{
  "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 字段说明

资料来源：src/agent_polis/ci.py:29-39

退出码机制

CI 模式通过退出码向 CI 系统传递评估结果，确保与 CI 工具的集成具有确定性。

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 系统无需解析文本输出即可做出决策。资料来源：src/agent_polis/ci.py:50-62

CLI 使用方式

基础命令

# 使用默认 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

输入文件格式

{
  "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. 规则特异性：优先级相同时，更具体的规则优先

graph TD
    A[接收动作请求] --> B[按优先级排序规则]
    B --> C[遍历规则列表]
    C --> D{规则匹配?}
    D -->|否| E[下一规则]
    D -->|是| F{规则启用?}
    F -->|是| G[返回决策 + 规则ID]
    F -->|否| E
    E --> C
    C --> H[应用默认决策]

决策追踪

每个策略评估结果包含 trace 字段，记录完整的匹配过程：

@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，用于检测动作请求中的提示注入和危险指令：

扫描结果汇总为机器可读的原因 ID 列表，便于在报告中聚合统计。资料来源：src/agent_polis/governance/prompt_scanner.py:18-35

阻断原因聚合

top_blocking_reasons 字段按原因 ID 统计阻断次数，按频次降序排列：

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 模式可与预设包配合使用，快速配置符合特定场景的策略规则。

预设对比

fintech 预设示例

{
    "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 集成

完整工作流示例

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

条件分支策略

- 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 模式生成的报告与审计系统共享策略和扫描器上下文：

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. 报告文件命名

# 使用时间戳避免覆盖
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
impact-preview ci --actions actions.json --output "report_${TIMESTAMP}.json"

2. 失败时保留报告

- name: Run CI evaluation
  if: always()  # 即使步骤失败也上传报告
  uses: actions/upload-artifact@v4
  with:
    name: polis-report-fallback
    path: polis-report.json

3. 与代码审查集成

将报告内容附加到 PR 评论：

# 生成 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"

限制与已知问题

当前限制

稳定性保证

CI 模式经过以下测试验证：

• 非 TTY 环境下的确定性执行
• 稳定的状态码行为
• 回归测试覆盖绕过尝试

资料来源：社区 Issue AP-204

路线图

资料来源：README.md:80-90

相关文档

• 策略系统文档
• 预设包指南
• 提示注入扫描器
• 审计系统

Pitfall Log / 踩坑日志

项目：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