Agent 执行前闸门Fish121380/csc-agent-guard-v1

CSC Agent Guard V1

中文
  |  
English

CSC Agent Guard V1 是一个与框架无关、确定性的 Agent 工具调用执行前闸门。
它会在工具调用到达执行器之前，将结构化 tool call 与由宿主系统维护的、已经
验证过的世界状态和策略规则进行核验。

它只返回以下四种运行决策之一：

accept | reject | ask | conflict

插件不会执行受保护的工具，不会自行编造证据，也不应被暴露为模型可以自行选择
是否调用的普通工具。真正的强制边界由宿主编排器负责。

立即打开 GUI

GUI 不是 Agent 工具，而是给用户管理配置、审核草稿、运行 Shadow 和回滚版本的
本地网页控制台。请在工作区根目录执行：

请在工作区根目录（包含 plugins/ 和 runtime/ 的目录）运行以下命令。

第一次使用且还没有配置文件时执行一次
python plugins\csc-agent-guard-v1\scripts\run_cli.py --init-config runtime\csc-agent-guard.json

启动 GUI
python plugins\csc-agent-guard-v1\scripts\run_admin.py --config runtime\csc-agent-guard.json

然后打开：http://127.0.0.1:8765

如果 8765 端口已被占用，可改用：

python plugins\csc-agent-guard-v1\scripts\run_admin.py --config runtime\csc-agent-guard.json --port 8766

默认界面是中文，右上角可以切换 English。GUI 默认只监听本机；不要直接暴露到
公网。需要额外保护时，可加 --token YOUR_LOCAL_TOKEN。

文档入口

这是整个工作区面向新用户的主 README，建议从这里开始。工作区主 README 负责说明
安装、GUI、实验和三个案例；插件目录中的 插件 README
只负责说明可独立安装的插件包、API 和源代码结构。它们不是两个插件，也不需要重复阅读。

工作区目录职责见 docs/WORKSPACE_LAYOUT.md。真实场景案例集中在
plugins/csc-agent-guard-v1/scenarios/。

Skill：配置助手

如果你不知道该如何填写 profiles、aliases、evidence routes 或策略规则，
可以使用 CSC Guard 配置助手 Skill。
在 Codex 中可这样调用：

请使用 $csc-agent-guard-config-assistant，根据我的业务需求生成 Guard 配置草稿，
并说明每一项修改、风险和需要我确认的内容。

Skill 只会生成和审核 ConfigDraft，不会自动激活配置、批准版本、调用证据服务，
也不会把任何事实伪造成 verified。最终仍需通过 GUI 或 CLI 审核、Shadow 测试并批准。

其他文档

- 完整说明书：架构、API、治理和部署；英文版可在页面顶部切换；
- 工作区结构说明：每个目录的职责；
- 实验说明：矩阵测试、公开数据集和评分报告；
- 运行配置说明：本地配置和配置历史的用途；
- 其他 Agent 接入教程：Claude Code、DeepSeek harness、WorkBuddy 和通用 MCP 宿主；
- 插件技术说明：插件内部 API 与源码结构。

案例分析：从这里开始

下面三个案例都是可以运行的完整教程。每个案例都会手把手说明场景背景、风险、配置、
Skill 如何生成草稿、GUI/CLI 如何操作、运行结果代表什么，以及如何接入真实执行器。

| 案例 | 中文教程 | English tutorial |
| --- | --- | --- |
| 航空公司丧亲退票 | 打开中文案例 | Open English case |
| 政务问答 Agent | 打开中文案例 | Open English case |
| 企业应用 Agent | 打开中文案例 | Open English case |

工作内容

用户请求
|
v
Agent 规划器
|
v
结构化 tool_call
|
v
CSC Agent Guard
|  解析并规范化 literal
|  加载已验证的 WorldState 和活动策略
|  计算确定性的规则闭包
|  检查冲突、禁令和前置条件
v
Accept / Reject / Ask / Conflict
|
+--> 只有 Accept -> 执行前重新验证状态 -> 工具执行器
+--> Ask         -> 宿主收集证据或刷新状态 -> 再次验证
+--> Reject      -> 停止并报告阻断条件
+--> Conflict    -> 先解决相互矛盾的已验证声明

Guard 是一个控制组件，不是一个自主 Agent。模型可以提出动作，但宿主必须在
每一个受保护动作之前调用 Guard，并且必须阻止绕过 Guard 的执行路径。

适用场景

当 Agent 能产生有意义的副作用时，可以使用 CSC Agent Guard，例如：

- 批准支付、退款、授信或账户变更；
- 修改权限、访问控制或身份数据；
- 发布软件、删除数据或修改生产配置；
- 导出受监管、私密或处于法律保全状态的数据；
- 发送要求经过核验批准的外部消息；
- 调用授权依赖最新外部状态的工具。

当自然语言请求必须转换为结构化动作，并且宿主需要可记录、可复现的确定性
决策时，Guard 尤其有用。

决策契约

| 决策 | 含义 | 执行器行为 |
| --- | --- | --- |
| accept | 所有必要前置条件均已验证，规则推理已完成，且没有策略阻断或冲突。 | 重新验证动态状态后，才可以执行。 |
| reject | 必要前置条件被反证，或存在已验证的禁止条件。 | 永远不执行。 |
| ask | 缺少证据、输入无效、请求被取消，或运行时/预算边界阻止了最终决策。 | 永远不执行，按照机器可读诊断处理。 |
| conflict | 同一个 literal 同时存在正向和负向的已验证声明。 | 永远不执行，先解决来源冲突。 |

决策顺序是确定性的：

1. 同一个 literal 同时存在正负已验证声明时，返回 conflict。
2. 存在已验证的禁止条件时，返回 reject。
3. 必要前置条件被反证时，返回 reject。
4. 取消、输入格式错误、预算或运行时边界时，返回 ask。
5. 缺少必要前置条件时，返回 ask。
6. 只有以上检查都通过后，才返回 accept。

accept 不是永久授权令牌。对于会变化的系统，应在实际执行前立即调用
revalidate_execution_state，比较状态版本和 Guard 计算出的读取集合。

数据模型

Action

Action 是工具调用的结构化描述，tool 必填。前置条件和策略 literal 可以是
字符串，也可以是结构化对象。

{
"tool": "approve_payment",
"preconditions": [
"user_authenticated",
"recipient_verified",
"amount_within_limit"
],
"policy": {
"forbid_if": ["account_locked", "duplicate_payment"]
},
"arguments": {
"amount": 100,
"currency": "USD"
}
}

WorldState

WorldState 归宿主所有。它有版本号，并包含声明和确定性的蕴含规则。

{
"version": "world-42",
"claims": [
{
"predicate": "user_authenticated",
"status": "verified",
"source": "identity-service"
},
{
"predicate": "account_locked",
"polarity": "-",
"status": "verified",
"source": "account-service"
}
],
"rules": [
{
"rule_id": "identity-allows-payment",
"premises": ["user_authenticated", "recipient_verified"],
"conclusion": "payment_identity_ready"
}
]
}

只有 verified 声明可以授权动作。observed、inferred 和 hypothesized
声明可以保留用于上下文，但不能满足前置条件。source 只是来源元数据，本身
不会自动产生信任。

Literal

"user_authenticated"
"not account_locked"
{"predicate": "owns", "arguments": ["alice", "card-1"]}
{"predicate": "owns", "arguments": ["alice", "card-1"], "polarity": "-"}

Predicate 和参数会被规范化为小写。带参数的 literal 应使用结构化对象，不要
依赖自由文本语义匹配。规则是确定性的蕴含，不会在没有已验证前提时凭空创建
事实。

响应与诊断

面向 Agent 控制循环时，建议使用 response_mode: "compact"：

{
"case_id": "payment-001",
"decision": "ask",
"reason": "precondition_not_verified",
"execution_allowed": false,
"missing": ["recipient_verified"],
"contradicted": [],
"conflicts": [],
"next_actions": ["request_evidence", "refresh_world_state"],
"human_readable_guidance": "Collect verified evidence, then verify again.",
"decision_hash": "..."
}

主要诊断字段：

- missing：不在已验证闭包中的必要 literal；
- contradicted：对应的相反已验证 literal；
- conflicts：正负两种 polarity 均已验证的 literal；
- next_actions：固定的机器路由，例如 request_evidence、
refresh_world_state、resolve_conflict 和 inspect_input；
- decision_hash：决策 tuple 的稳定哈希，可用于回归测试和审计关联。

审计和调试时使用 response_mode: "full"。Full 响应会增加 case_outcome、
耗时、metadata、proof trace、审计链和执行收据，但这些字段不能替代执行器
闸门。

安装

从源码目录安装

插件没有第三方运行时依赖，需要 Python 3.10 或更高版本：

请从插件目录 plugins\csc-agent-guard-v1 运行。
python -m pip install .
python -m csc_agent_guard.quickstart

不安装、直接从源码运行：

python examples/quickstart.py

Codex / MCP 注册

从工作区根目录注册插件的 MCP server，并把插件目录作为工作目录。宿主必须把它当作强制中间件或网关：

{
"command": "python",
"args": ["scripts/run_mcp_server.py"],
"cwd": "plugins/csc-agent-guard-v1"
}

本工作区安装的 Codex 插件标识为 csc-agent-guard-v1@personal。修改插件文件后，
应启动新 task，让宿主加载更新后的插件进程。

零配置第一次运行

默认运行时安全且可以立即使用。它内置了金融、账户变更、破坏性操作和数据导出
四类工具的保守模板与常见别名。当识别出敏感工具时，即使模型漏写了前置条件，
Guard 也会补充更严格的要求；模板不会提供任何已验证事实：

'{"op":"verify_action","case_id":"first-run","action":{"tool":"approve_payment"},"response_mode":"compact"}' |
python scripts/run_cli.py

第一次运行预期会得到一个可执行的 ask，列出宿主需要提供的证据。这是有意设计的：
零配置意味着没有可信业务事实，而不是默认授权。对于无法识别的工具，还会要求
宿主提供绑定具体工具名的 tool_profile_registered(tool_name) 声明，因此漏写或
使用未知模板不会意外让有副作用的工具获得执行资格。

准备定制时，生成一份由宿主控制的配置文件：

python scripts/run_cli.py --init-config csc-agent-guard.json
python scripts/run_cli.py --config csc-agent-guard.json

生成的 starter 文件包含别名、工具模板，以及空的 world_state 和 evidence。
宿主可以添加经过认证的声明，或在宿主边界替换 provider。运行期间绝不能允许模型
修改这份文件。

动态策略与证据适配器

常驻 CLI 和 MCP 进程可以重新加载由宿主控制的配置文件：

python scripts/run_cli.py --config csc-agent-guard.json --watch-config
python scripts/run_mcp_server.py --config config\csc-agent-guard.json --watch-config

配置中的 version 会出现在附加的 adoption metadata 和 config_status 操作
中。生产环境应使用带版本的配置文件或外部配置管理系统，以便审核和回滚。

生产系统可以把策略和证据指向由宿主认证的 HTTP provider，而不是把变化中的事实
写进 JSON：

{
"version": "adoption-7",
"policy_provider": {
"type": "http",
"endpoint": "https://policy.internal/active",
"timeout_seconds": 2
},
"evidence_routes": {
"user_authenticated": {
"type": "http",
"endpoint": "https://identity.internal/evidence"
},
"amount_within_limit": {
"type": "http",
"endpoint": "https://finance.internal/evidence"
}
}
}

auto_repair: true 会把每个缺失 literal 路由到对应 provider，并执行一次重新
验证。provider 只能返回由宿主批准的声明。端点认证、授权、白名单、重试和密钥
仍由宿主负责。

alias_candidates 只是根据已配置名称和当前事实生成的审核建议，永远不会自动
应用。只有经过审核的配置变更才能提升候选别名；使用 config_status 和
metrics 观察发布效果。

每次 CLI/MCP 验证响应还会在附加的 adoption metadata 中返回实际使用的策略版本、
世界状态版本和 input_digest。它可以把决策绑定到验证当时的版本，同时不改变
向后兼容的 DecisionHash v2 契约。

配置治理与本地 GUI

对于还没有配置中心的团队，CLI 提供了一个最小治理流程：

python scripts/run_cli.py --validate-config csc-agent-guard.json
python scripts/run_cli.py --config csc-agent-guard.json --config-status
python scripts/run_cli.py --config csc-agent-guard.json --config-history
python scripts/run_cli.py --config csc-agent-guard.json --rollback adoption-6
python scripts/run_cli.py --config csc-agent-guard.json --approve-alias auth_ok=identity_verified --new-version adoption-8

成功加载和被拒绝的热加载都会记录到
csc-agent-guard.json.history.jsonl。合法配置使用原子写入。被监控的配置如果
格式错误，运行中的旧配置会继续生效，并通过 config_status 暴露错误，不会静默
变成新策略。

需要图形化操作时，启动本地管理控制台：

python scripts/run_admin.py --config csc-agent-guard.json

打开 http://127.0.0.1:8765。控制台提供配置编辑、校验、原子应用、重新加载、
版本历史、回滚、显式批准别名和 metrics。默认只绑定 localhost 且没有认证；如果要绑定网络接口，
必须由宿主补充认证和授权。

接入方式

Python API

当宿主和 Guard 在同一个 Python 进程中运行时，可以使用嵌入式 API：

from csc_agent_guard import (
DecisionStatus,
revalidate_execution_state,
record_execution_result,
verify_action,
)

result = verify_action(
action,
world_state_provider=provider,
policy_registry=active_policies,
case_id="payment-001",
)

check = revalidate_execution_state(result, provider)
if result.decision.status == DecisionStatus.ACCEPT and check.valid:
tool_result = executor(action)
result = record_execution_result(
result,
"succeeded",
tool_result,
external_execution_id="run-7",
)

对于 ask、reject 或 conflict，执行器不能放在 else 分支中运行。需要执行
收据和会话级审计链时，配置 AuditContext。

JSONL CLI

CLI 每行读取一个 JSON 请求，并每行写出一个 JSON 响应，不需要 MCP SDK：

请从插件目录 plugins\csc-agent-guard-v1 运行。
'{"op":"verify_action","case_id":"demo","action":{"tool":"approve","preconditions":["user_ok"]},"world_state":{"claims":[{"predicate":"user_ok","status":"verified"}]},"response_mode":"compact"}' |
python scripts/run_cli.py

常用命令：

python scripts/run_cli.py --init starter.json
python scripts/run_cli.py --demo
python -m csc_agent_guard.cli  缺证据时返回 ask -> 宿主提供证据
|
+-> JSON/CLI/GUI 配置 -> 校验 -> Shadow -> 人工审批
|
+-> 不可变快照 -> 验证 -> 执行前复核 -> 执行

JSONL 操作包括 validate_draft、shadow_draft、approve_draft、
config_status、config_history 和 metrics_prometheus。Skill 或 LLM 可以
生成草稿，但不能修改活动配置；每一项变更必须明确接受或编辑后才能审批。
证据部分成功会作为事务结果返回，但绝不会被当作权威事实。

启动本地管理界面：

python scripts/run_admin.py --config csc-agent-guard.json

默认只监听 localhost。需要额外保护时可使用 --token；如果要非本机暴露，
还应在前面部署经过认证的反向代理。

范围与限制

CSC Agent Guard V1 不提供自然语言事实核验、模糊 predicate 匹配、跨轮记忆、
工具执行、外部来源认证或法律/医疗/金融建议。本地历史和本地 GUI 适用于单一
可信主机；分布式部署应使用带认证的 HTTP/Redis 配置存储、集中式审计和宿主授权。
Shadow 是确定性的行为对比，不是独立的安全沙箱。

完整的中文运行说明书位于：
docs/CSC-Agent-Guard-V1-Manual.md。

版本状态

本工作区包含 CSC Agent Guard V1 0.2.0。接入真实副作用之前，请先审查宿主的
安全、隐私和数据留存要求。插件保持小型、无依赖，便于接入团队检查和测试整个
决策路径。