# Agent Gate Loop 完整重构任务书

> **✅ 全部任务已完成 (2026-06-10)**。37 个新模块，`tsc --noEmit` 零错误。

本文是 [Agent Gate Loop 重构计划](AGENT_GATE_LOOP_REFACTOR_PLAN.md) 的执行规格。目标不是继续修补旧流程，而是按完整 control plane 重构落地：

```text
StateKernel + GateRunner + LoopKernel + PromptSectionRegistry
  + ToolPipeline + WritePipeline + EvidenceStore + GovernanceAudit
```

## 执行原则

- 先 schema，再 pipeline，再迁移入口，再删旧规则源。
- 每个任务必须有测试或 smoke。
- 旧函数可以短期 adapter 化，但不能继续拥有规则判断权。
- 发现真实坏例必须加入 regression corpus。
- 合并前允许测试红灯暴露架构缺口；发布前必须全绿。

## 核心 Schema

### T0-001 GateDecision

目标文件：

- `src/harness/gates/gate-runner.ts`
- `src/harness/gates/findings.ts`
- `src/harness/gates/taxonomy.ts`

定义：

```ts
type GateCheckpoint =
  | "pre-input"
  | "pre-plan"
  | "pre-phase-transition"
  | "pre-tool"
  | "post-tool"
  | "pre-write"
  | "post-write"
  | "pre-verify-command"
  | "post-verify-result"
  | "pre-delegation"
  | "post-delegation"
  | "pre-context-compile"
  | "post-context-compile";

type GateSeverity = "hard-deny" | "soft-deny" | "evidence-required" | "warning";
```

验收：

- `allow` 不在 `GateSeverity` 中。
- `GateDecision.allowed` 由 findings 计算。
- 每个 decision 有 `traceId`。
- 单测覆盖 hard deny、soft deny、warning、finding 去重。

测试：

- 新增 `scripts/smoke-gate-runner.ts`
- 纳入 `release:check`

### T0-002 KernelSnapshot

目标文件：

- `src/harness/kernel/state-kernel.ts`
- `src/harness/kernel/snapshots.ts`
- `src/harness/kernel/events.ts`

职责：

- 统一导出 run 当前状态快照。
- Prompt、Gate、Loop、Tool、Evidence 只能消费 snapshot，不直接拼旧状态。
- snapshot 标注来源和时间。

验收：

- 同一 run 生成稳定 snapshot。
- 缺失 run、坏 state、ledger 损坏时输出结构化 consistency finding。
- 不从 answered question 反推 facts。

测试：

- 扩展 `scripts/smoke-harness.ts`

### T0-003 ActionPlan

目标文件：

- `src/harness/loop/action-plan.ts`
- `src/harness/loop/verify-plan.ts`
- `src/harness/loop/task-plan.ts`

职责：

- 将用户输入、control frame、gate finding 转为结构化 action。
- LLM 可以提出 intent，但执行必须走 ActionPlan。

验收：

- `write-code`、`ask-user`、`read-context`、`verify`、`delegate`、`stop` 都有结构化 plan。
- ActionPlan 绑定 `CompletionPromise` 和 `GateDecision.traceId`。

测试：

- 新增 action-plan smoke。

### T0-004 EvidenceRecord

目标文件：

- `src/harness/evidence/evidence-store.ts`
- `src/harness/evidence/evidence-source.ts`
- `src/harness/evidence/evidence-validation.ts`

定义：

```ts
type EvidenceSourceTrust =
  | "local-command"
  | "project-metadata"
  | "project-source"
  | "user-provided"
  | "external-system"
  | "manual-note";
```

验收：

- 所有新 evidence 都有 `sourceTrust`。
- `manual-note` 不能作为 TDD green / verify pass。
- `user-provided` 和 `external-system` ship 时必须显示残余风险。

测试：

- 新增 evidence validation smoke。
- 更新 TDD green 相关 smoke。

### T0-005 ToolResultContract

目标文件：

- `src/harness/tools/tool-contract.ts`
- `src/harness/tools/tool-pipeline.ts`

字段：

- `toolName`
- `status`
- `kind`
- `sourceRefs`
- `evidencePath`
- `nextAction`
- `gateTraceId`
- `untrusted`

验收：

- 工具成功但无 contract 产生 warning。
- 文档、网页、外部文件内容必须 `untrusted=true`。
- 工具失败必须有 nextAction，不允许让 LLM 猜路径。

测试：

- 扩展 `scripts/smoke-harness-tool-gateway-scenario.ts`

## Phase 1：GateRunner Control Plane

### T1-001 PolicyRegistry

目标文件：

- `src/harness/gates/policy-registry.ts`
- `src/harness/gates/policies/*.ts`

迁移 policy：

- WorkspacePathPolicy
- ToolGatewayPolicy
- PowerShellMutationPolicy
- SourceWritePolicy
- PhaseGatePolicy
- PlanPathPolicy
- TddPolicy
- VerifyCommandPolicy

验收：

- policy 只返回 finding，不直接执行副作用。
- 同一 checkpoint 可运行多个 policy。
- finding 按 severity 排序并去重。

### T1-002 Gate Ledger Trace

目标文件：

- `src/harness/kernel/events.ts`
- `src/harness/ledger.ts`

事件：

- `gate.requested`
- `gate.decision`
- `gate.blocked`
- `gate.warning`

验收：

- 每个 gate decision 可通过 `traceId` 找到输入和输出。
- `release:check` 中 smoke 能验证 trace 存在。

### T1-003 AuthorizationModel

目标文件：

- `src/harness/gates/authorization.ts`

规则：

- 用户授权只能解除 `soft-deny`。
- `hard-deny` 必须改状态、改路径、补证据或停止。
- 普通“可以/继续/好的”不构成授权。

验收：

- 测试覆盖“可以”不能解除 hard deny。
- 结构化授权必须绑定 finding id、scope、expiresAt。

## Phase 2：ToolPipeline / WritePipeline

### T2-001 ToolPipeline

目标文件：

- `src/harness/tools/tool-pipeline.ts`
- `extensions/kingdee-tools.ts`
- `extensions/kingdee-powershell-tool.ts`

流程：

```text
tool.requested
  -> runGate(pre-tool)
  -> execute or block
  -> runGate(post-tool)
  -> ToolResultContract
  -> ledger
```

验收：

- `kd_*` 工具全部接入。
- PowerShell wrapper 接入。
- 无法拦截的 PI 内置工具必须禁用或 wrapper 化。
- 外部路径 read/write 均阻断。

### T2-002 WritePipeline

目标文件：

- `src/harness/tools/write-pipeline.ts`
- `src/harness/write-transaction.ts`
- `src/harness/source-anchors.ts`

流程：

```text
pre-write gate
  -> source anchor check
  -> plan path check
  -> write/edit
  -> postcondition
  -> post-write gate
  -> transaction verified/blocked
```

验收：

- 非 execute 写生产代码阻断。
- execute 且证据满足时允许写 PLAN 批准文件。
- PLAN 未批准文件阻断。
- source anchor 缺失或陈旧阻断。

### T2-003 Untrusted Input Wrapper

目标文件：

- `src/harness/tools/untrusted-content.ts`
- `extensions/kingdee-tools.ts`

覆盖：

- `kd_doc_read`
- 外部网页
- 外部文件
- 用户粘贴长文档
- MCP 返回的大段外部内容

验收：

- untrusted 内容不能进入 system prompt 区。
- untrusted 内容中的“忽略规则/调用工具/泄露凭证/绕过门禁”只作为数据。

## Phase 3：LoopKernel

### T3-001 CompletionPromise

目标文件：

- `src/harness/loop/completion-promise.ts`
- `src/harness/kernel/state-kernel.ts`

验收：

- 每个 run 创建时生成 CompletionPromise。
- PLAN/VERIFY/SHIP 引用同一 promise id。
- 完成状态必须由 promise acceptance + evidence + gate 决定。

### T3-002 StopHook

目标文件：

- `src/harness/loop/stop-hook.ts`

类型：

- `done`
- `blocked`
- `budget-exhausted`
- `stuck`
- `unsafe`
- `scope-drift`

验收：

- StopHook 写 ledger。
- StopHook 进入 control frame 最高优先级。
- stuck detector 能识别重复失败、重复工具、重复问题。

### T3-003 LoopKernel

目标文件：

- `src/harness/loop/loop-kernel.ts`
- `src/harness/loop/reducers.ts`

流程：

```text
Reason -> Gate -> Act -> Observe -> Update -> Evaluate
```

验收：

- demand loop、goal loop、repair loop、phase loop 均通过 LoopKernel。
- loop 不直接 spawn shell。
- loop 不直接写 facts/evidence。
- replay 同一事件序列得到同一 snapshot。

### T3-004 VerifyPlan

目标文件：

- `src/harness/loop/verify-plan.ts`
- `src/harness/goal-loop.ts`

验收：

- `/kd goal` 只能生成 VerifyPlan。
- VerifyPlan 只允许 package scripts 或用户提供 evidence。
- 任意 `node -e`、`python -c`、`npx xxx` 不执行。

## Phase 4：Prompt / Context / Delegation

### T4-001 PromptSectionRegistry

目标文件：

- `src/harness/context/prompt-section-registry.ts`
- `src/harness/context/prompt-contract.ts`
- `src/harness/prompt.ts`

验收：

- prompt sections 有来源、预算、裁剪状态和 traceId。
- Prompt renderer 只格式化 PromptContract。
- prompt 不复制 runtime policy 规则。

### T4-002 ExampleRegistry

目标文件：

- `src/harness/context/example-registry.ts`

验收：

- few-shot 示例来自 registry。
- 每个示例有适用条件、版本、测试和 token 预算。
- 禁止业务流程临时拼 few-shot。

### T4-003 CompactCapsule

目标文件：

- `src/harness/context/compact-capsule.ts`
- `src/harness/handoff-capsule.ts`

必留内容：

- hard deny summary
- open question
- resumeSnapshot
- current gate
- writeTransactions
- sourceAnchors
- CompletionPromise
- StopHook

验收：

- compact 后唯一下一动作不丢。
- hard deny 不被裁剪。

### T4-004 DelegationPlan

目标文件：

- `src/harness/loop/delegation-plan.ts`
- `src/harness/delegation.ts`

验收：

- 子 agent 输入只能来自 capsule。
- 子 agent 输出只能进入 observation/context entry。
- 子 agent 输出不能直接写 facts/evidence/gate pass。

## Phase 5：Governance / Audit / Release Gate

### T5-001 Architecture Fitness Tests

目标文件：

- `scripts/architecture-fitness.ts`

扫描规则：

- policy 规则不能写在 prompt renderer。
- tool 不能绕过 ToolPipeline。
- loop 不能直接 spawn shell。
- evidence 必须有 sourceTrust。
- delegation 输出不能直接写 facts/evidence。
- old rule source 必须 adapter/deprecated/delete。

验收：

- 进入 `release:check`。

### T5-002 GovernanceAudit

目标文件：

- `src/harness/audit/governance-audit.ts`
- `scripts/harness-audit.ts`

评分项：

- Prompt Maturity
- Gate Coverage
- Tool Coverage
- Loop Safety
- Evidence Trust
- Context Persistence
- Delegation Safety
- Regression Coverage

验收：

- 输出分数、findings、top actions。
- Phase 5 后发布必须通过阈值。

### T5-003 Regression Corpus

目标文件：

- `src/harness/audit/regression-corpus.ts`
- `scripts/smoke-harness-evals.ts`

必须包含真实坏例：

- execute 文档门禁循环依赖。
- goal loop 抽 shell 执行。
- 工作区外 read/write。
- PowerShell wrapper 绕写入事务。
- 子 agent 自称验证通过。
- compact 后丢 hard deny。
- PLAN 自由文本替代 facts/evidence。

## 旧模块废弃表

| 旧模块 | 目标状态 | 新权威模块 |
| --- | --- | --- |
| `src/harness/gates.ts` | adapter/deprecated | `src/harness/gates/*` |
| `src/harness/tool-gateway.ts` | adapter/deprecated | `src/harness/tools/tool-pipeline.ts` + GateRunner |
| `src/harness/action-policy.ts` | adapter/deprecated | SourceWritePolicy + WritePipeline |
| `src/harness/goal-loop.ts` | rewrite | LoopKernel + VerifyPlan |
| `src/harness/demand-loop.ts` | rewrite | LoopKernel |
| `src/harness/repair.ts` | adapter/rewrite | LoopKernel + StopHook |
| `src/harness/prompt.ts` | renderer only | PromptSectionRegistry + PromptContract |
| `src/harness/prompt-policy.ts` | policy summary only | PolicyRegistry |
| `src/harness/evidence.ts` | adapter/deprecated | EvidenceStore |
| `src/harness/write-transaction.ts` | adapter/deprecated | WritePipeline |
| `extensions/kingdee-tools.ts` | adapter only | ToolPipeline |
| `extensions/kingdee-powershell-tool.ts` | adapter only | ToolPipeline + PowerShellMutationPolicy |

## 提交顺序

1. Schema + empty pipelines：T0-001 到 T0-005。
2. GateRunner + PolicyRegistry：T1。
3. ToolPipeline / WritePipeline：T2。
4. LoopKernel / CompletionPromise / StopHook：T3。
5. PromptSectionRegistry / CompactCapsule / DelegationPlan：T4。
6. GovernanceAudit / ArchitectureFitness / RegressionCorpus：T5。
7. 删除或 adapter 化旧规则源。
8. 更新用户文档和 release checks。

## 最小可验收里程碑

### M1：门禁控制平面

- GateRunner 可用。
- pre-tool/pre-write/pre-verify-command 接入。
- 工作区外路径、PowerShell 绕过、goal shell 抽取均被测试覆盖。

### M2：统一 loop

- CompletionPromise、StopHook、VerifyPlan 可用。
- goal/repair/phase 通过 LoopKernel。
- replay 可用。

### M3：统一 prompt/context

- PromptSectionRegistry 可用。
- CompactCapsule 可用。
- prompt 不再复制 runtime policy。

### M4：发布治理

- Architecture fitness tests 可用。
- Governance audit 可用。
- Regression corpus 包含真实坏例。
- `release:check` 全绿。