# 基于 PI 的 Harness Agent 设计与风控比对

## 背景

KCodeV2 的目标不是重新实现一个编码 Agent，而是在 PI Coding Agent 之上提供金蝶研发场景的 Harness Engineering 层。PI 继续负责会话、模型、工具调用、权限、上下文压缩、TUI/CLI 与运行时循环；KCodeV2 负责金蝶开发所需的工作流、事实门禁、证据链、工具策略、风险判断和可恢复状态。

本文基于 `E:\tmp` 下成熟项目的运行时形态做抽象，然后对照当前 KCodeV2 状态给出设计、差距和风控清单。

## 参考项目观察

### opencode

opencode 的成熟点在于把 Agent Runtime 拆成清晰的运行时服务：

- Session Runner：从已持久化的 session history 继续执行一次 provider turn，避免把会话推进逻辑散落在 UI 或命令层。
- System Context Registry：所有系统上下文通过注册表加载、排序和合并，避免不同扩展自己拼 prompt。
- Tool Definition：工具有输入 schema、输出 schema、模型可见输出和 runtime settle 过程。
- Permission：权限按 action/resource/ruleset 评估，支持 ask/allow/deny 和持久化 always 规则。
- Compaction：压缩摘要有固定结构，保留目标、约束、进展、阻塞、关键决策、下一步和相关文件。

可借鉴结论：KCodeV2 不应接管 PI 的 session runner；短期通过 PI extension 事件和 workflow prompt 注入 Kingdee control frame、context pack、gate、evidence 和 tool gateway 结果，长期应贴近 PI 原生 system context/compaction 扩展点，减少对长提示词提醒的依赖。

### ECC

ECC 的成熟点在于多 agent、规则、命令和质量门禁是可审计的：

- `commands/harness-audit.md` 要求运行确定性脚本，并按固定 rubric 输出分数、失败项和 Top Actions。
- `commands/quality-gate.md` 把 formatter gate 明确为 hook 输入驱动，且区分检查、修复和严格模式。
- `agents/` 和 `rules/` 把角色边界、语言规则、安全规则分离，减少单个大 prompt 的漂移。

可借鉴结论：KCodeV2 的 Harness 审计不能只靠人工 review，应有确定性评分脚本；子 agent 必须受角色边界和工具边界约束，主 Harness 是唯一状态机。

### oh-my-openagent-proxy

oh-my-openagent-proxy 的成熟点在于代理层动态构造 Agent 能力：

- 按 agent、模型、模式和环境组合动态 prompt sections。
- 后台任务、parent wake、状态分类和任务历史都有独立模块和测试。
- 规则注入、动态上下文裁剪、插件缓存和 post-compact 处理都有明确边界。

可借鉴结论：KCodeV2 应把“动态上下文选择”和“压缩/恢复后继续当前 run”作为一等能力，不把全部历史塞进 prompt；长期可增加后台验证/审计任务，但必须与主 run 状态隔离。

### claude-code-prompts

claude-code-prompts 的成熟点在于系统提示和安全监控明确化：

- 安全监控把 hard deny、soft deny、数据外泄、自修改、权限绕过等分开。
- 压缩摘要要求保留安全相关指令和约束。
- 工具拒绝后强调不能恶意绕过拒绝意图。

可借鉴结论：KCodeV2 风控要分层：不可授权硬阻断、可由用户授权的软阻断、需要证据的业务风险、需要提示保留的上下文约束。

## PI Harness Agent 目标架构

### 一句话定位

PI Harness Agent 是“运行在 PI Agent Runtime 之外、又参与 PI 每轮决策的 Kingdee 控制层”。它不生成新的 Agent loop，而是用确定性状态、门禁和证据约束 PI 的下一步行为。

### 分层设计

1. PI Runtime 层

由 PI 提供：session、model/provider、tool call、permission、compaction、TUI/CLI、MCP、subagent 或后台能力。KCodeV2 只消费 PI 扩展 API，不 fork 或复制该层。

2. KCode Extension Adapter 层

负责把 PI 事件转为 KCode Harness 事件：

- session start：发现 active run，提示 resume。
- user input：创建或恢复 run，记录输入事件，生成 control frame。
- tool preflight：调用 tool gateway 和 write transaction。
- tool result：记录 tool result contract、working set 和 ledger。
- command/tool registration：注册 `/kd-*` 命令和 `kd_*` 工具。

3. Harness State Kernel 层

唯一持久状态源：

- `RUN.json`：阶段、模式、产品画像、风险、门禁、facts、questions。
- `events/ledger.jsonl`：append-only 事件账本。
- `evidence/index.json`：证据索引。
- `workingSet`、`toolResults`、`actionCommits`、`writeTransactions`、`sourceAnchors`：操作上下文与写入边界。

4. Context Pack 层

每轮把状态编译成 PI 可消费上下文：

- control frame：当前焦点、唯一下一动作、本轮输入策略。
- required facts contract：实现、数据源、第三方对接缺口。
- durable context：文件结论、决策、风险、来源。
- stage artifacts：CONTEXT/SPEC/PLAN/EXECUTION/VERIFY/SHIP 摘要。
- evidence/tool/ledger 摘要和预算报告。
- handoff capsule：给新会话、压缩恢复和子 agent 的固定交接包；当前已包含 control frame、facts/questions、ledger、writeTransactions 和 sourceAnchors，后续需要把 hard/soft/evidence/warning 风险分类也固化为不可裁剪段落。

5. Gate 与 Risk 层

负责决定“能否继续”：

- 阶段门禁：discuss/spec/plan/execute/verify/ship。
- 事实门禁：FormId、字段/实体、插件事件、读写方式、接口字段映射、幂等、验收样例。
- 证据门禁：SDK signature、metadata/data-source、TDD red/green、verify pass、KSQL lint。
- 写入门禁：execute 阶段、PLAN 批准文件、source anchor、工作区内路径、后置条件。
- 风险门禁：normal 模式、风险等级、残余风险说明、外部验证证据。

6. Evaluation 层

所有 LLM 行为缺陷应沉淀成确定性 transcript eval 或 smoke：

- 用户回答后不丢文件上下文。
- open question 下禁止写代码。
- 工具失败后禁止猜路径。
- ledger replay 能恢复关键上下文。
- 子 agent 不能绕过主 run 门禁。

## 推荐工作流

```text
输入需求
  -> /kd <需求> 创建 run
  -> Control Frame 判断当前焦点
  -> Context Compiler 编译上下文包
  -> PI 执行模型 turn
  -> Tool Gateway / Permission / Write Transaction 拦截工具
  -> Evidence / Ledger / Working Set 落盘
  -> Gate 刷新
  -> 通过则推进阶段；阻塞则只处理唯一 blocker
```

关键原则：

- 最新用户消息不能覆盖恢复断点。
- 子 agent 只能旁路研究、审查、文档或验证分析，不能成为第二状态机。
- API 文档和知识库只能证明技术用法，不能替代业务事实。
- 生产源码写入必须有近期 source anchor 和 PLAN 批准范围。
- 验证必须记录真实命令、退出码和关键输出；不能把“待验证”当作绿灯。

## 与本项目逐项比对

| 能力项 | 成熟项目基准 | KCodeV2 当前状态 | 差距/风险 | 建议优先级 |
| --- | --- | --- | --- | --- |
| PI 边界 | 不复制 agent loop，扩展层介入 runtime | `ARCHITECTURE.md` 已明确“不重做 PI loop”；`package.json` 已声明 PI package resources | 需要持续避免 CLI/extension 里堆出第二套 runtime | P0 持续约束 |
| 系统上下文组合 | opencode 使用 registry 合并 system context | 已有 `context-compiler.ts`、`context-packet.ts`、`prompt.ts`，通过 PI extension/workflow prompt 注入 | 还不是 PI 原生 system context registry 形态，依赖扩展注入 prompt | P1 |
| 状态内核 | session/state/event 持久化 | 已有 `RUN.json`、active-run、ledger、facts、questions、workingSet | 需要持续防坏状态迁移和兼容分叉 | P0 |
| Control Frame | 每轮先确定焦点和唯一动作 | 已有 `control-frame.ts` 和 action router | 需要更多真实 transcript eval 覆盖边界场景 | P1 |
| 阶段门禁 | 可确定性检查 | 已有 `gates.ts`、模式 quick/normal、阶段 artifacts | KSQL/第三方/生产发布等高风险规则需持续扩展 | P0 |
| 事实门禁 | 业务事实必须结构化 | 已有 Required Facts Contract、factLabel、question memory | 事实来源目前主要靠文档和工具约束，仍需更多 UI/工具层强校验 | P0 |
| 证据链 | evidence 真实命令和索引 | 已有 `evidence.ts`、`/kd goal`、TDD/SDK/data-source 证据 | 外部人工验证证据仍可能弱，需要 evidence 模板和来源分级 | P1 |
| 工具 schema | 工具有输入/输出 contract | PI 工具注册已有 schema；KCode 有 Tool Result Contract | 非 `kd_*` 工具结果主要靠 extension 观测摘要，结构完整性有限 | P1 |
| 权限/风控 | action/resource allow/ask/deny | 当前有 tool gateway、write transaction、PowerShell mutation block，已覆盖 PI `write/edit` 和 Windows shell 常见文件变更绕过 | 缺少统一 hard/soft/evidence/warning taxonomy 与用户授权策略 | P0 |
| 写入安全 | 写入前权限、路径和后置条件 | 已有 external write、source-like、PLAN、source anchor、postcondition；PI `tool_call` 里的 `write/edit` 已接入事务 | Source anchor 依赖工具正确使用；未来新增写类工具必须默认接入 gateway/transaction，需审计覆盖 | P0 |
| 子 agent | 角色边界、工具边界、主状态机唯一 | 已有 delegation role、allowed tools、handoff capsule | 需要真实 PI subagent API 适配和并行委派回归 | P1 |
| 上下文压缩恢复 | 摘要保留约束/阻塞/文件 | 已有 handoff capsule、ledger replay、context budget；可用于手动 resume 和子 agent 交接 | 尚未与 PI compaction hook 深度集成；hard deny 和 resumeSnapshot 还未作为独立不可裁剪结构输出 | P1 |
| Harness 审计 | ECC 有 deterministic harness audit | 当前有 `smoke:harness`、`smoke:harness-evals` | 缺少面向仓库的固定评分审计命令 | P1 |
| 安全提示保留 | 压缩后保留安全约束 | Prompt policy 已集中管理持久规则 | 需要确保 compact/handoff 时硬风控规则不可被裁剪 | P0 |
| 后台任务 | 任务状态分类、parent wake | 当前以主会话同步推进为主 | 可选能力，先不引入复杂后台运行 | P2 |

## 风控设计

### 风险分层

1. Hard Deny

不可由用户普通确认放行：

- 写入工作区外生产源码路径。
- 绕过 write/edit 事务，用 PowerShell 重定向、`Set-Content`、`Out-File`、`Remove/Move/Copy` 等改文件。
- open blocking question 或 resumeSnapshot 未处理时写产品源码。
- 非 execute 阶段写 source-like 生产代码。
- 子 agent 创建子 agent、推进主 run 阶段、记录主验证结果或修改非授权文件。
- 把凭证写入仓库、文档、evidence、prompt 或提交说明。

2. Soft Deny

可由用户明确授权或修订计划后放行：

- 新增 PLAN 未列出的文件。
- 高风险工作从 quick 切到 normal。
- 验证连续失败达到修复上限后继续修复。
- 外部验证命令无法在本机执行，需要用户提供证据。

3. Evidence Required

不一定阻断工具，但阻断阶段推进或交付：

- SDK 签名必须来自当前项目 jar/dll/构建输出。
- 元数据、FormId、字段、表名没有当前项目证据。
- TDD red/green 缺失或绿灯没有 `Exit: 0`。
- `VERIFY.md` 没有真实命令、退出码和关键输出。
- `ship` 前没有风险等级和残余风险说明。

4. Warning

提示但不阻断：

- context budget 发生裁剪。
- tool result contract 摘要不完整。
- Deep Context 过期。
- 多个相关 run 可能混淆。

### 当前最高风险点

1. 写入口覆盖不完整

风险：PI 或未来扩展新增写工具后，如果没接入 `tool-gateway` 和 `write-transaction`，会绕过 PLAN、source anchor 和阶段门禁。

措施：新增“工具注册审计”或 smoke，枚举所有写类工具和 shell mutation pattern，断言必须经过 gateway。

2. 事实与 evidence 被自由文本替代

风险：PLAN 或聊天中写了 FormId/字段，模型误认为事实已满足。

措施：门禁继续只信 `run.facts` 和 evidence；新增 eval 覆盖“PLAN 提到字段但 facts/evidence 缺失时仍阻断”。

3. 压缩/恢复丢失安全约束

风险：上下文压缩后忘记 open question、source anchor、凭证规则或禁止绕过写入事务。

措施：handoff capsule 和 context pack 需要固定包含 hard deny、当前 gate、open question、resumeSnapshot、writeTransactions 和 sourceAnchors；其中当前已覆盖 gate/open question/writeTransactions/sourceAnchors，后续补齐正式风险分类和 post-compact eval。

4. 子 agent 输出被当成主证据

风险：review/verify 子 agent 说“已验证”，主 agent 误推进。

措施：子 agent 输出只能是建议；真实验证由主 agent 执行并通过 `/kd goal` 或 evidence 写入。

5. 外部系统和生产验证不可本地复现

风险：第三方接口、BOS 注册、生产环境 SQL/KSQL 只能由用户或外部系统验证，模型容易过度承诺。

措施：normal 模式强制风险说明；外部验证必须有用户提供的可核验证据；无法验证时 ship 只能标注残余风险，不能写“已通过”。

## 路线图建议

### P0：先补硬风控闭环

- 建立 hard/soft/evidence/warning 风险 taxonomy，集中在 `src/harness/risk-policy.ts` 或现有 policy 模块，并让 handoff/context pack 固定引用。
- 审计所有写入入口，确保新增工具默认进入 gateway；当前不要只依赖 `write/edit` 名称匹配。
- 增加“PLAN 自由文本不能满足事实门禁”的 smoke/eval。
- 确保 handoff capsule 永远包含 hard deny、open question、gate、resumeSnapshot、source anchor 和 write transaction 摘要。

### P1：补成熟度和可审计性

- 增加 `kcode harness-audit`，按固定 rubric 输出 Tool Coverage、Context Efficiency、Quality Gates、Memory Persistence、Eval Coverage、Security Guardrails。
- 将 KCode context pack 更贴近 PI system context 注册模型，减少直接注入长 workflow prompt 的比例。
- 扩展 transcript eval：压缩恢复、子 agent 委派、工具失败、验证失败修复上限。
- 增加 evidence 来源分级：local-command、project-metadata、user-provided、external-system、manual-note。

### P2：再考虑增强能力

- 后台只读审计任务。
- 验证任务状态分类和 parent wake。
- 针对长期 run 的自动总结和 run archive。
- 多 run 需求组的看板和冲突检测。

## 结论

KCodeV2 当前已经不是空白 harness：核心状态、门禁、证据、问题恢复、上下文包、写入事务和回归 smoke 都已成型。与成熟项目相比，最主要差距不是功能数量，而是三个工程化闭环：

- PI runtime 边界要更硬，避免扩展层长成第二 agent loop。
- 风控 taxonomy 要集中化，区分 hard deny、soft deny、evidence required 和 warning。
- 审计和 eval 要产品化，把每次发现的状态机漏洞、上下文丢失和门禁绕过变成确定性回归。

下一步优先做 P0 风控闭环，再做 P1 的 harness audit 和 PI system context 化。