AirCoding/集成测试阶段Deepseek审查结果.md

集成测试阶段 Deepseek 审查结果

审计日期: 2026-06-05 项目: AirCoding V1.0.0 Alpha 审计模式: 四视角交叉审计（系统架构师 / 开发工程师 / 真实用户 / 测试工程师）

---

0. 前置验证

TypeScript 类型检查: PASS (0 errors) E2E Gates: 13/13 PASS

---

1. 系统架构师审查报告

一、实际运行验证结果

三项测试全部通过：

• Test 1 (tsc): 零类型错误，17 个 contracts 文件完整
• Test 2 (E2E gates): 13/13 通过，覆盖 P0 monorepo/depcruise/tsc + P1-P8 回归测试 + SEC 命令注入 + CAP 能力信任
• Test 3 (集成测试): RuntimeApp 启动成功，MainAgent regex 正确将 "Create hello.txt" 路由为 delegate，Scheduler 调度完成，文件真实创建（内容 "HELLO from AirCoding"），39 个工具注册完毕，fs.read/fs.list 正确返回

二、FR 实现情况

真正实现的 FR（完整端到端链路可通）

FR	描述	实现状态
FR-001	CLI 启动与项目初始化	✅ runCommand 含 auto-init、项目检测
FR-002/003	项目本地状态与 Session 持久化	✅ SQLite session.db + 16 Repository
FR-005	Main Agent 15 状态机 + 分类	✅ regex/llm 双模式 + chat_with_llm
FR-007	Scheduler 13 状态机 + TaskGraph	✅ 完整状态链 + WavePlanner/RetryPlanner
FR-008	5 种 Worker Agent + NDJSON IPC	✅ Executor/Reviewer/Debugger/Compactor/ExperienceMiner
FR-009	执行原语 (code block + tool_call 解析)	✅ ExecutorRole.parse_actions 三种解析模式
FR-010	ToolRegistry 39 工具	✅ fs/shell/git/cpp/project/artifact 全覆盖
FR-013	Provider 层 (Anthropic + OpenAI-compatible)	✅ 适配器边界清晰

名存实亡的 FR（结构存在但深度不足）

FR	描述	问题
FR-004	事件驱动运行时	EventBus/Store/Ingestor 类齐全，但 run.ts 同步阻塞 push Scheduler，未真正依赖事件总线驱动状态流转
FR-006	Architecture Designer	影响评估类完整，但 MainAgent.classify() 路由到 delegate 时从未调用 ArchitectureDesigner——架构审查是死代码
FR-011	Permission/Security	PermissionEngine 六层模型存在，但 ToolRegistry.call() 未显示逐调用通过 PermissionEngine 评估的证据
FR-012	Plugin/Capability Foundation	CapabilityRegistry 存在但运行时未深入集成
FR-016	TUI/HUD	TuiApp.ts 渲染 ANSI 视图，但 run.ts 手工推送构造数据而非 ProjectionStore 作为单一可信源
FR-017	C++ 工作流	cpp.* 工具存在但 debug→fix→review 证据闭环未端到端验证

三、架构基线遵守评估

遵守良好:

• 依赖方向正确：tui 不 import runtime，depcruise 零违规
• IPC 协议正确：NDJSON over stdio，worker.ready 握手，heartbeat 心跳
• contracts 包独立，17 个文件覆盖所有核心类型

关键偏离:

1. 依赖边界: runtime/cli 直接依赖 @aircoding/llm 创建适配器——架构基线要求 runtime 通过接口间接使用 llm
2. 事件驱动承诺未兑现: 基线 §6 声明 "AirCoding is event-driven"，但主循环是同步 pull 模式
3. TUI 消费方式偏离: 基线 §18 要求 "HUD/TUI consumes ProjectionStore only"，但 TuiApp 接收手工 snapshot 而非 ProjectionStore hydrate/apply

四、状态机评估

Scheduler 状态机 (13 状态): 逻辑完整但 MONITORING 状态存在竞态——200ms 轮询 vs 事件驱动等待，has_running() 与 graph.update_status 之间的窗口可能导致假完成。

MainAgent 状态机 (15 状态): CONFIRMING 状态仅在 regex 检测 breaking 词时触发，但确认回调在 run.ts 中断裂。ARCHITECTURE_DESIGNING 和 ARCHITECTURE_REVISING 状态无实际触发路径。

五、架构师结论

V1.0.0 Alpha 已实现核心能力闭环：CLI→MainAgent→Scheduler→Worker→LLM→Tool→File 的完整链路可以跑通并创建真实文件。三个关键缺口：(a) Architecture Designer 是死代码，(b) PermissionEngine 未在 ToolRegistry 调用路径中逐次生效，(c) Scheduler 轮询等待对长任务存在竞态窗口。

---

2. 开发工程师审计报告

P0 问题

1. BuiltInToolRegistrar 中 18 个工具的结果形状不一致 (create_real_executor.ts:175-437) create_real_executor 返回 { status, call_id, tool_name, type, content, metadata }，但正确的 ToolResultEnvelope 形状使用 output 而非 content。影响：fs.stat, process.kill, cpp.detect, cpp.build, cpp.test, doctor.run, project.scan, debug.run, gui.screenshot, network.capture 等。

WorkerManager 第 191 行执行 result.output || result.error || {}——每个通过 worker IPC 调用这些工具的任务都会收到空内容 {}。ExecutorRole 的 LLM 循环看不到任何工具输出，导致每项任务崩溃或无限循环。

P1 问题

2. shell.run 生成器未被解包 (shell/index.ts) createShellExecutor 返回 async function*。ToolRegistry.execute_branch 直接调用执行器并返回结果——对生成器函数来说，返回的是生成器对象而非 ToolResultEnvelope。WorkerManager 会再次回退到 {}。shell 命令无法通过 worker chain 工作。

3. MainAgent.classify_via_llm API 不匹配 (MainAgent.ts:185) classify_via_llm 调用 this.provider_manager.complete(...)，但 run.ts 创建的提供者只挂接了 complete_text。如果 classify_mode: 'llm'，provider_manager.complete is not a function 会导致崩溃。

4. Scheduler DISPATCHING 缺少 await (Scheduler.ts:163) this.worker_manager.spawn(...) 没有 await——方法返回 Promise，但计划程序立即进入 MONITORING。worker 进程在调度程序检查 has_running() 时可能尚未准备好，任务被错误标记。

P2 问题

5. 资源泄漏: run.ts progressInterval 在 run_until_idle() 拒绝时永不清理 6. 空 catch 块: scanDir 中的 catch {} 默默丢弃所有文件系统错误 7. 延迟浪费: Scheduler.step() 使用 setTimeout(r, 200) 轮询而非事件驱动 8. require() 调用: DoctorService.check_capability_deps 使用同步 require('child_process') 而非静态导入

用户可感知的核心影响

用户输入 "创建一个 C++ hello world 程序"，MainAgent 正确分类委托，Scheduler 调度到 DISPATCHING，Worker 启动并调用 LLM。LLM 响应代码块，ExecutorRole 调用 fs.write（成功），然后 LLM 调用 cpp.detect（通过 IPC）。WorkerManager 收到成功结果但提取 result.output 为 undefined，向 worker 发送 {}。LLM 看不到工具输出，困惑，重试，15 轮后被 BLOCKED。用户只看到 "Task blocked" 而没有文件。根本原因是形状不一致——约 50% 的工具注册表通过 worker 路径被静默破坏。

---

3. 真实用户测试报告

测试结果汇总

测试	命令	结果	关键观察
Test 1	air init	PASS	创建 6 个子目录 + project.json，project_id 自动生成
Test 2	air doctor	PASS	5/6 检查通过；project_structure 报 FAIL（缺少 package.json/tsconfig.json），标记为 fixable
Test 3	air ask 创建hello.txt	PASS	委托模式正常工作，1 轮完成，文件内容正确 (HelloWorld, 10 bytes)
Test 4	air ask C++项目	部分通过	main.cpp 和 CMakeLists.txt 创建成功，但 cpp.build 和 shell.run 报错，LLM 却声称 "程序已成功编译"
Test 5	air run TUI	PASS	TUI 渲染正常，面板和快捷键显示正确，输入 q 退出干净
Test 6	air e2e	PASS	13/13 gates 全部通过
Test 7	air history / session list	PASS	三个 session 被正确记录

用户最痛 3 个问题

1. doctor 语义误导: "All checks: FAIL" 用红色大字——但只是缺少 package.json 和 tsconfig.json 模板文件。新用户看到 FAIL 会以为产品坏了，其实项目完全正常工作。

2. 结果不可信——工具报错但 LLM 说成功: Test 4 中 cpp.build 返回了 Error，shell.run 返回了 Error: undefined，但最终输出却写着 "程序已成功编译并输出 Hello World"。用户分不清到底是真成功了还是 LLM 幻觉。这是信任问题。

3. session/history 毫无辨识度: air history 输出裸 session_id 数字加大小，不知道哪个 session 干了什么。用户做了 3 次 air ask，回头想找之前的任务，面对 3 个无区分的数字完全懵了。

用户体验评分: 5/10

扣分项:

• 工具错误被吞掉（-2 分）：信任问题，用户无法区分真实成功和幻觉
• doctor 诊断语义不准确（-1 分）：把可修复警告当成硬失败
• session/history 不可辨识（-1 分）：无法快速定位之前的任务
• 多轮交互体验存疑（-1 分）

加分项: init 流程干净、TUI 渲染正常、e2e 全绿、响应速度快

---

4. QA 测试报告

测试矩阵

Test	描述	结果	严重级别
T1	TypeScript 类型检查	PASS	-
T2	E2E Gates (13门)	13/13 PASS	-
T3	简单文件创建	PASS (Worker 退出信号异常)	P1
T4	C++ AI 终端 (FR-017)	PASS (Worker 退出信号异常)	P1
T5	追问上下文验证	FAIL	P0

详细测试分析

T3: 简单文件创建 — PASS (P1 警告)

• hello.txt 成功创建，内容 HELLO（6 字节），分类正确为 delegate。
• 警告: Worker 输出 [Worker] exited with code 0 (error): Unrecoverable error occurred。Worker 以 exit code 0 退出但附加 "(error)" 标记——信号噪音导致诊断困难。

T4: C++ AI 终端 (FR-017) — PASS (P1 警告)

• 成功生成 main.cpp（13824 字节，含 #include 和 main()）、CMakeLists.txt 和 script.sh。
• 功能需求基本满足：代码具备 C++ 程序骨架。
• 警告: 同样出现 Worker exit code 噪音。

T5: 追问上下文验证 — FAIL (P0)

• LLM 回答: "抱歉，我目前无法直接访问您的本地文件系统，所以不知道您的项目里有哪些源代码文件。"
• 根因: MainAgent.chat_with_llm() 方法（MainAgent.ts:102-122）完全绕过 ContextAssembler。仅发送一条裸 system prompt 'You are AirCoding, an AI coding assistant...'，没有注入项目根路径、文件列表、对话历史等任何上下文。
• 影响: 所有问答类交互（占总交互的很大比例）都没有项目上下文感知能力。

问题分类

P0 — 阻断发布

1. MainAgent.chat_with_llm 无 ContextAssembler 集成 (MainAgent.ts:102-122) 修复方向：chat_with_llm 应接收 AssemblyContext 参数，先通过 ContextAssembler 组装上下文再发给 LLM。

P1 — 重要缺陷

2. Worker 退出信号不一致 (T3/T4): Worker 以 exit code 0 退出但附带 "(error)" 字符串——应排查 Worker 退出码逻辑。

3. BuiltInToolRegistrar 结果形状不一致 (工程审计 P0): 18 个工具的返回形状使用 content 而非 output，导致 WorkerManager 收到空结果。

4. shell.run 生成器未解包 (工程审计 P1)

P2 — 改进项

5. 无 workspace files 快照层：ContextAssembler 缺少 project_files 提示层
6. Scheduler DISPATCHING 缺少 await (竞态)
7. classify_via_llm API 不匹配
8. history/session 输出缺乏可辨识性

E2E Gates 补充建议

当前 13 个 gate 全部基于单元测试和静态检查，缺少以下端到端 gate:

优先级	建议 Gate	检查内容
P0	Answer-Mode Context Gate	验证 chat_with_llm 回复包含项目文件信息
P0	Simple E2E Create Gate	LLM 驱动的文件创建端到端
P0	Tool Output Shape Gate	验证所有 39 个工具的返回形状符合 ToolResultEnvelope
P1	Complex E2E Generate Gate	多文件代码生成端到端
P1	Worker Exit Consistency Gate	验证 Worker exit code 0 不与 "(error)" 同时
P1	Follow-up Context Gate	新建文件后追问，验证 Agent 感知已有文件
P2	ContextAssembler Integration Gate	验证所有 Agent 路由经过 ContextAssembler

---

5. 四视角交叉审计综合结论

P0 问题汇总（3 项，阻塞发布）

#	问题	来源视角	触发条件	影响范围
1	MainAgent.chat_with_llm 无项目上下文	QA + 架构师 + 用户	所有 answer 交互	用户追问项目状态时 LLM 100% 幻觉
2	BuiltInToolRegistrar 18 个工具结果形状不一致	工程师 + QA	Worker IPC 调用这些工具	50% 工具通过 worker 返回空结果
3	shell.run 生成器未解包	工程师	任何 shell.run 调用	shell 命令 100% 失败

P1 问题汇总（5 项）

#	问题	来源视角
4	Worker 退出信号噪音	QA + 架构师
5	Scheduler MONITORING 竞态窗口	架构师 + 工程师
6	classify_via_llm API 不匹配	工程师
7	Scheduler DISPATCHING 缺少 await	工程师
8	工具错误被吞掉 + false-positive 成功	用户

P2 问题汇总（5 项）

#	问题	来源视角
9	Architecture Designer 是死代码	架构师
10	PermissionEngine 未在调用路径生效	架构师
11	history/session 输出不可辨识	用户
12	doctor 语义误导 (warn→FAIL)	用户
13	资源泄漏 + 空 catch	工程师

根因分析

本轮与前几轮审计相同的模式再次出现：

1. E2E gates 框架盲区 — 13/13 gates pass 但真实场景 5/13 (38%) 核心功能失败。gates 检查代码质量（tsc、depcruise、单元测试），不检查功能可用性（工具结果形状、LLM 上下文注入、Worker IPC 往返完整性）。

2. 集成测试仅覆盖 Happy Path — 测试创建 hello.txt 验证了最简单场景，但未覆盖 C++ 多文件任务、shell 执行、追问上下文等复杂度递增的场景。

3. 组件间接口契约缺失 — BuiltInToolRegistrar 返回 { content } vs WorkerManager 期望 { output }，这种接口不一致在组件隔离开发时无法发现，只能在集成时暴露。缺少跨组件的 TypeScript 接口强约束。

4. 审计员不跑端到端 — 所有审计员检查了 MainAgent.ts 的方法签名、Chat 函数的类型正确性，但没有人实际问一句 "LLM 回到 '我没有文件系统访问' 合理吗？"

发布建议

不建议发布 V1.0.0 Alpha。3 个 P0 问题影响了核心体验链路：

• P0-1: 用户追问项目状态 → LLM 答"我无法访问文件系统"（每次触发）
• P0-2: Worker 调用 cpp.detect / doctor.run / project.scan 等 → 收到空结果 → LLM 困惑 → 任务假完成或失败
• P0-3: LLM 调用 shell.run → 永远返回 undefined → 编译/运行/测试全部失败

修复 P0 后，必须：

1. 将真实任务端到端集成测试加入 E2E gate suite
2. 统一工具结果形状为 contracts.ToolResultEnvelope (使用 output 字段)
3. MainAgent 注入 ContextAssembler 到所有路由

---

6. 修复优先级矩阵

优先级	数量	问题
P0	3	chat_with_llm 无上下文、工具结果形状不一致、shell.run 坏死
P1	5	Worker exit 噪音、Scheduler 竞态、classify API、spawn await 缺、false-positive
P2	5	ArchDesigner 死代码、PermissionEngine 未生效、history 不可读、doctor 语义、资源泄漏
E2E gates 增强	6	新增 answer-mode context gate, simple E2E create gate, tool output shape gate 等

总计: 需修复 13 个代码问题 + 新增 6 个 E2E gate