fix: integrate audit findings round 1 - tools, worker, scheduler, main agent

- Unify ToolResultEnvelope (output vs content) for built-in tools - Fix shell.run AsyncGenerator consumption in ToolRegistry.call/streaming - Scheduler: consume WorkerResult.status instead of marking all running tasks completed - WorkerProcess/WorkerManager: surface exit events and generate failed/cancelled result - MainAgent: integrate ContextAssembler, Chinese destructive regex, ArchitectureDesigner impact gate - run.ts: pendingConfirmation flow, dispatch extracted, .air files filtered from /results - CapabilityRegistry wired into RuntimeApp and ServiceRegistry; DoctorService uses it - release.ts: findRepoRoot/findBun, run air e2e + depcruise + runtime regression - New gates: release-critical-gates, CLI run command regression - 14/14 e2e gates pass; 3/3 release dry-run pass Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-05 18:39:10 +08:00
parent a2d7aa0339
commit ddefcbb2b1
24 changed files with 1992 additions and 186 deletions
--- a/状态交接.md
+++ b/状态交接.md
@@ -0,0 +1,230 @@
+# AirCoding 集成修复第一轮 - 状态交接
+
+> 用于在另一台设备继续。包含上下文、真实问题、修复方案、验证结果、剩余事项和复现命令。
+
+## 1. 项目与远端
+
+- 仓库根：`/home/airlongdian/DataDevices/AirWorkSpace/AirCoding`
+- 仓库地址：`http://admin:L753865h@39.106.174.106/admin/AirCoding.git`
+- 当前分支：`GLM5-Achieve`
+- 推送目标：`origin/GLM5-Achieve`
+- 仓库不在 Git 根级 `package.json` 下，子包为 monorepo；用 Bun 运行命令。
+
+## 2. 本轮目标与边界
+
+用户要求：架构与设计冻结、需求已明确；不允许回退或降级；汇总多轮四视角审查报告的真实问题并修复；修复后跑真实 UAT 演示。
+
+**架构与设计冻结点（不要修改）**：
+- 7 个 monorepo 包：`contracts / cli / tui / runtime / llm / toolchain-cpp / workers`
+- 5 个 Domain Invariants（INV-1~INV-5）
+- 工具契约 `ToolResultEnvelope { status, output, error, artifact_ids, evidence_ref_ids, metadata }`（`packages/contracts/src/tool.ts`）
+- Worker/Scheduler IPC 协议
+- 状态机：`MainAgent` 15 态、`Scheduler` 13 态
+
+**真实阻断问题（来源：MiniMax-M3 / Deepseek / GLM5.1 / Gpt5.5 四份审查报告）**：
+- 工具结果 `content` 与 `output` 契约不一致
+- `shell.run` AsyncGenerator 无法被普通 `call()` 消费
+- Scheduler 在 `!has_running()` 时把所有 running task 标 completed
+- Worker 无结果退出后状态丢失
+- MainAgent 回答未接入 ContextAssembler
+- `run.ts` 危险操作 confirmation y/n 路由断裂
+- ExecutorRole DONE 判定宽松、code block 全局反转义破坏源码
+- E2E/release gates 不覆盖真实成功场景
+- 报告 `集成测试阶段GLM5.1审查结果.md` / `集成测试阶段Gpt5.5审查结果.md` 在仓库根目录
+
+## 3. 已完成的源码修复
+
+### 3.1 工具契约与 shell.run
+- `packages/runtime/src/tools/BuiltInToolRegistrar.ts`：`create_real_executor()` 中 18 个工具成功返回从 `{ type, content }` 改为 canonical `{ status: 'ok', output, metadata }`。
+- `packages/runtime/src/tools/ToolRegistry.ts`：`ToolExecutor` 支持 `Promise | AsyncIterable` 返回；`execute_branch` 通过 `execute_executor_final` 消费 streaming final envelope；`call_streaming` 透传 chunks 并保证 final 出现。
+- `packages/runtime/src/tools/shell/index.ts`：streaming executor 立即 yield `command.started`，stdout/stderr chunk 收集后 yield，final envelope 包含 `metadata.is_final = true` 与 `output.{exit_code, stdout, stderr, timed_out}`。
+
+### 3.2 Worker/Scheduler 结果闭环
+- `packages/runtime/src/workers/WorkerProcess.ts`：新增 `on_exit` 回调，触发退出时把信息分发给 WorkerManager。
+- `packages/runtime/src/workers/WorkerManager.ts`：
+  - `WorkerHandle.state` 增加 `failed`，`worker.result` 按 payload.status 决定 handle state；保留 wrapped result。
+  - `wrap_worker_result` 把 `changes[].file → changed_files`、verification object → `verification[]`、role status `fixed/pass → completed`、others → `failed`。
+  - `handle_worker_exit` 在 worker 退出但无 result 时构造 `failed/cancelled` result。
+  - 暴露 `get_result_for_task` / `get_handle_for_task`。
+  - 给 ToolRegistry 调用上下文传 `project_root` + `agent_type: 'executor'`，不再用 `cwd` 伪字段。
+- `packages/runtime/src/scheduler/Scheduler.ts`：`MONITORING` 改为按 `WorkerResult.status` 消费 `task.completed` / `task.blocked` / `task.cancelled` / `task.failed` durable events；删除"`!has_running()` 直接 completed"逻辑。
+
+### 3.3 MainAgent 上下文、确认门、ArchitectureDesigner
+- `packages/runtime/src/context/ContextAssembler.ts`：
+  - 修复 L6 `evidence_store.list_for_entity` 调用签名。
+  - 修复 L8 兼容 `role: 'tool' / 'tool_result' / 'tool_use'`。
+  - 新增 L3 `project_files` 快照层（实现 `build_project_files_snapshot`）。
+  - 移除 additional_layers 重复追加。
+- `packages/runtime/src/app/RuntimeApp.ts`：`start()` 中实例化 `CapabilityRegistry`、绑定 ToolRegistry、注入 DoctorService；创建 `MessageRepository` / `EvidenceRepository` 并 `context_assembler.set_data_sources`。
+- `packages/runtime/src/app/ServiceRegistry.ts`：同步接入 `CapabilityRegistry`、把 WorkerManager/Scheduler 走同一个 tool registry。
+- `packages/runtime/src/agents/main/MainAgent.ts`：
+  - 新增 `context_assembler / architecture_designer / project_root / agent_id / task_id` 字段。
+  - `chat_with_llm()` 使用 `ContextAssembler.assemble` 生成 L0-L9 消息再追加 user message。
+  - `classify_via_llm` 改用 `complete_text` 与 `ProviderManager` 既有 API 对齐。
+  - 危险操作正则覆盖中文：`删除|删掉|清除|移除|销毁`。
+  - 委托前调用 `ArchitectureDesigner.assess_impact`，`reject_or_escalate/requires_replan` 转 `ARCHITECTURE_DESIGNING`，`requires_user_confirmation` 转 `CONFIRMING`。
+  - 新增 `infer_changed_files` 推断受影响组件。
+- `packages/cli/src/commands/run.ts`：
+  - MainAgent 构造时传入 `context_assembler` 与 `project_root`。
+  - 把调度逻辑抽取为 `dispatchTask`，避免重复代码。
+  - `pendingConfirmation` 状态机：进入 CONFIRMING 时只展示提示并保存原始任务；`y` → `handle_confirmation(true)` 后 `dispatchTask`；`n` → `handle_confirmation(false)` 提示取消，不创建任务。
+  - `/results` 优先使用 `WorkerResult.changed_files`，过滤 `.air` 内部文件。
+- `packages/cli/src/commands/ask.ts`：MainAgent 接入 `context_assembler`/`project_root`；`execute_task` 中 `ctx` 改为 canonical ToolExecutionContext。
+
+### 3.4 ExecutorRole
+- `packages/workers/src/roles/ExecutorRole.ts`：
+  - 引入 `is_done_signal(text)` 严格判定（仅当整行等于 `DONE` 或 `TASK_COMPLETE`）。
+  - 工具失败且 LLM 输出 DONE 时不返回 `completed`，而是让 LLM 修复。
+  - 移除 code block 内容的全局 `\\n/\\t/\\\\/\\"` 反转义，保留原文。
+
+### 3.5 Permission 与 TUI
+- `packages/runtime/src/tools/ToolRegistry.ts`：`ask_user`/`deny` 分支保留 `call.call_id`。
+- `packages/cli/src/commands/release.ts`：增加 `findRepoRoot` / `findBun`，将 release gates 改为运行 `air e2e`、runtime regression、depcruise，timeout 600s，并输出失败尾部。
+
+## 4. 新增门禁与测试
+
+- `packages/runtime/test/regression/release-critical-gates.test.ts`（已接入 e2e P0-REL）：
+  1. `built-in tool success envelopes use output, not content`
+  2. `shell.run returns a final envelope through call and streaming APIs`
+  3. `scheduler does not mark running tasks completed without a worker result`
+  4. `MainAgent answer mode uses assembled project context`
+  5. `destructive requests enter confirmation and rejection returns to idle`
+- `packages/cli/test/run-command-regression.test.ts`（已接入 e2e P0-REL）：
+  - 锁定 `run.ts` 使用 WorkerResult.changed_files、过滤 `.air`、维护 pendingConfirmation。
+- `packages/runtime/test/regression/worker-result-envelope.test.ts` 更新断言为新 `wrap_worker_result` 实现。
+- `packages/runtime/test/regression/tool-registry-permission.test.ts` 新增 ask_user/deny 保留 call_id 断言。
+- `packages/cli/src/commands/e2e.ts` 新增 `P0: Release-critical functional gates`。
+
+## 5. 验证结果
+
+```
+$ /home/airlongdian/.bun/bin/bun run packages/cli/src/index.ts e2e
+14/14 gates passed
+  - P0: Monorepo structure
+  - P0: depcruise dependency boundary (INV-4)
+  - P0: tsc strict typecheck (0 errors)
+  - P0: Release-critical functional gates
+  - P1: Storage/Events
+  - P2: Tools/Permission
+  - P3: Provider/Context
+  - P4: Worker IPC
+  - P5: C++ Toolchain
+  - P6: Projection/TUI
+  - P7: Agents
+  - P8: Full regression suite
+  - SEC: Command injection regression
+  - CAP: Capability trust regression
+
+$ /home/airlongdian/.bun/bin/bun run packages/cli/src/index.ts release --dry-run
+3/3 gates passed - Release READY
+```
+
+## 6. 真实 UAT 演示（临时目录 `/tmp/air-uat.Y2H5dz`）
+
+- LLM 配置：`OPENAI_API_KEY=sk-...`、`OPENAI_BASE_URL=http://newapi.airlongdian.fun`（注意：env 中 `AIRCODING_*` 会被适配器再次加 `/v1`，应直接用 `OPENAI_*`）、`AIRCODING_MODEL=glm-5.1`。
+- 场景结果：
+  1. `air ask "创建一个 hello.txt，内容是 HelloWorld"` → 真实写入 `HelloWorld` 磁盘。
+  2. `air ask "我的项目里有哪些文件?"` → 回答引用项目文件快照（`hello.txt`），无幻觉。
+  3. `air run` 输入 `请删除 hello.txt` 后 `n` → 提示 "Cancelled. No task was created."，文件保留。
+  4. `air run` 输入 `请删除 hello.txt` 后 `y` → 调度 `shell.run rm`，文件被删除。
+- UAT 临时发现并修复：MainAgent 原危险正则不匹配中文，补充 `删除|删掉|清除|移除|销毁`。
+
+## 7. 复现命令（在新设备上验证）
+
+```bash
+REPO=/home/airlongdian/DataDevices/AirWorkSpace/AirCoding
+cd "$REPO"
+
+# 1) Type check
+/home/airlongdian/.bun/bin/bun run node_modules/.bin/tsc --noEmit -p tsconfig.check.json
+
+# 2) E2E
+/home/airlongdian/.bun/bin/bun run packages/cli/src/index.ts e2e
+
+# 3) Release dry-run
+/home/airlongdian/.bun/bin/bun run packages/cli/src/index.ts release --dry-run
+
+# 4) 临时目录演示
+TMP=$(mktemp -d /tmp/air-uat.XXXXXX)
+cd "$TMP"
+/home/airlongdian/.bun/bin/bun run "$REPO/packages/cli/src/index.ts" init .
+OPENAI_API_KEY=<your_key> \
+OPENAI_BASE_URL=http://newapi.airlongdian.fun \
+AIRCODING_MODEL=glm-5.1 \
+AIRCODING_REPO_ROOT="$REPO" \
+/home/airlongdian/.bun/bin/bun run "$REPO/packages/cli/src/index.ts" ask "创建一个 hello.txt，内容是 HelloWorld"
+cat hello.txt
+```
+
+## 8. 关键文件清单
+
+修改：
+- `packages/cli/src/commands/ask.ts`
+- `packages/cli/src/commands/e2e.ts`
+- `packages/cli/src/commands/release.ts`
+- `packages/cli/src/commands/run.ts`
+- `packages/runtime/src/agents/main/MainAgent.ts`
+- `packages/runtime/src/app/RuntimeApp.ts`
+- `packages/runtime/src/app/ServiceRegistry.ts`
+- `packages/runtime/src/context/ContextAssembler.ts`
+- `packages/runtime/src/scheduler/Scheduler.ts`
+- `packages/runtime/src/tools/BuiltInToolRegistrar.ts`
+- `packages/runtime/src/tools/ToolRegistry.ts`
+- `packages/runtime/src/tools/shell/index.ts`
+- `packages/runtime/src/workers/WorkerManager.ts`
+- `packages/runtime/src/workers/WorkerProcess.ts`
+- `packages/runtime/test/regression/tool-registry-permission.test.ts`
+- `packages/runtime/test/regression/worker-result-envelope.test.ts`
+- `packages/workers/src/roles/ExecutorRole.ts`
+
+新增：
+- `packages/runtime/test/regression/release-critical-gates.test.ts`
+- `packages/cli/test/run-command-regression.test.ts`
+
+报告（在仓库根目录）：
+- `集成测试阶段Deepseek审查结果.md`
+- `集成测试阶段GLM5.1审查结果.md`
+- `集成测试阶段Gpt5.5审查结果.md`
+- `集成测试阶段MiniMax-M3审查结果.md`
+- `集成测试阶段GLM5.1审查结果.md`
+- `状态交接.md`（本文件）
+
+## 9. 提交策略
+
+本轮一次性提交，commit message：
+
+```
+fix: integrate audit findings (round 1) - tools, worker, scheduler, main agent
+
+- Unify ToolResultEnvelope (output vs content) for built-in tools
+- Fix shell.run AsyncGenerator consumption in ToolRegistry.call
+- Scheduler: consume WorkerResult.status instead of marking all running tasks completed
+- WorkerProcess/WorkerManager: surface exit events and generate failed/cancelled result
+- MainAgent: integrate ContextAssembler, Chinese destructive regex, ArchitectureDesigner impact gate
+- run.ts: pendingConfirmation flow, dispatch extracted, .air files filtered from /results
+- CapabilityRegistry wired into RuntimeApp and ServiceRegistry; DoctorService uses it
+- release.ts: findRepoRoot/findBun, run air e2e + depcruise + runtime regression
+- New gates: release-critical-gates, CLI run command regression
+- 14/14 e2e gates pass; 3/3 release dry-run pass
+```
+
+## 10. 已知与待办
+
+- TUI 完整输入/快捷键统一收口仍是可改进点（UAT 已在非 TTY 走通 readline），建议后续在 TUI 内增加任务输入框。
+- Projection 事实源收口已做（`/results` 走 WorkerResult，ProjectionClient 接收 ProjectionStore 推送），但 TUI 渲染仍以手工 snapshot 为初值；下一步可以由 EventStore/ProjectionStore 完全驱动。
+- 新增 `集成测试阶段Gpt5.5审查结果.md` 等报告应作为证据纳入未来 release notes。
+
+---
+
+**会话记录**（从对话恢复继续的关键节点）：
+1. 四份审计报告汇总去重 → 真实问题清单。
+2. Phase 1: 工具契约 + shell.run 修复（ToolRegistry 消费 AsyncIterable、shell final envelope）。
+3. Phase 2: WorkerProcess exit handler → WorkerManager → Scheduler MONITORING 改按 WorkerResult 状态入事件。
+4. Phase 3: MainAgent 接入 ContextAssembler，CONFIRMING y/n 路由，ArchitectureDesigner 主路径，CapabilityRegistry 接入，Permission call_id 保留。
+5. Phase 4: ExecutorRole 严格 DONE、保留 code block 原文、失败不 completed。
+6. Phase 5: 新增 release-critical-gates / CLI run regression，air e2e 14/14。
+7. Phase 6: run.ts `/results` 走 WorkerResult，release.ts 找 repo root。
+8. 真实 UAT：air ask 创建/追问；air run 中文删除拒绝/确认；运行中 UAT 触发并修复中文确认门正则。
+9. 准备状态交接与一次性 git 提交推送。
+
+会话总耗时较长，过程已通过自动化避免重复。回到本机可直接按 §7 复现并继续。