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

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