AirCoding/状态交接.md

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. 复现命令（在新设备上验证）

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 复现并继续。