2026Technology-Competition/docs/architecture-eng-review.md

整体架构工程审查报告（plan-eng-review）

版本: v1.0 | 日期: 2026-08-11 | 状态: 已裁定

审查技能: gstack plan-eng-review（version 1.0.0）| 审查对象: 整体架构全景（docs/design.md + agent-runtime-design.md + rag-layer-design.md + api-design.md + implementation-plan.md）| 当前进度: Phase3 Word 解析收尾（160 tests / 100%）

---

1. 审查范围与裁定摘要

本次审查锁定整体架构全景，目标为后续 Phase4-6（RAG / Impact / Writer / Web UI）实施提供架构定论。

审查阶段	结果
Step 0 Scope Challenge	范围缩减：移除 Qdrant 切换抽象 + Redis/Valkey 双实现（单一 Chroma + InMemoryQueue）
Section 1 Architecture	7 个 issue，全部裁定
Section 2 Code Quality	3 个 issue，全部裁定
Section 3 Test Review	覆盖图完成，无独立缺口（随架构裁定覆盖）
Section 4 Performance	2 个 issue，全部裁定
Outside Voice	独立挑战完成，8 项全部接受

---

2. Step 0: Scope Challenge 裁定

复杂度检查触发（全架构远超 8 文件/2 服务阈值），发现 2 处过度设计：

#	过度设计点	裁定
S1	Qdrant 可切换抽象（rag-layer §9 StorageAdapter）	移除 — v1 单机竞赛场景 Chroma 嵌入式足够（搜索验证：<10 万向量 Chroma 正确默认）
S2	Redis/Valkey TaskQueue 双实现（api-design §5）	移除 — v1 InMemoryQueue 满足演示需求，抽象接口保留但双实现不建

Search Check 结论：手写 RAG（chromadb+rank_bm25+RRF）与 2026 主流实践一致；Chroma 嵌入式对小规模规则库正确。

---

3. Section 1: Architecture Review（7 issue 全裁定）

#	严重度	置信度	发现	裁定
I1	P1	9/10	chat_structured 无真正 schema 校验（engine.py:160 直接 json.loads 返回）	加 jsonschema 真校验（失败→带错误重试→parse_error+校验详情）
I2	P2	8/10	解析重试路径硬编码首选模型，从不降级（engine.py:155）	解析重试也走降级链（primary→fallback）
I3	P1	7/10	状态机 8 状态无 cancelled/aborted 定义，但 api 有 cancel 端点	加 cancelled+resume 状态（cancelled 终态 + resume 回到中断前）
I4	P2	7/10	design §8.1 宣称「引擎统一注入防护」但 engine.py 无实现	引擎层统一防护（边界包裹+系统指令恒定性，全 Agent 生效）
I5	P2	8/10	config.py 残留 QdrantStoreConfig（L95-103）/ redis_url（L38-41）死配置	删死配置+同步文档
I6	P2	7/10	RAG 设计缺 rerank 精排（2026 主流实践为 向量→rerank→精排）	v1 加 rerank（bge-reranker-v2-m3）
I7	P3	5/10	三层记忆 + DataGate + AgentState 对单进程场景可能过度	完整实现（用户认为记忆系统是核心价值）

4. Section 2: Code Quality Review（3 issue 全裁定）

#	严重度	置信度	发现	裁定
I8	P2	9/10	SourceParser 三重复制校验（source_aggregator.py:39-66 DRY 违规）	提取 _validate_path helper
I9	P2	8/10	client.py:82 time.sleep 阻塞 asyncio 任务池 + client 生命周期未闭环	全异步化（AsyncClient + asyncio.sleep + async 上下文）
I10	P3	6/10	chat_structured 重复调用 _model_names(None)[0]（4 处）	随 I2 一并修

5. Section 3: Test Review

已实现部分 160 tests / 100% 覆盖（fail_under=99 门禁生效），FakeLLMClient 注入模式成熟。覆盖图确认关键测试缺口集中在已裁定架构变更（jsonschema/降级链/注入防护/异步化需测试先行）与后续阶段（RAG chunker/检索 eval、状态机、渲染链路 E2E）。

6. Section 4: Performance Review（2 issue 全裁定）

#	严重度	置信度	发现	裁定
I11	P2	7/10	token.py:18 cl100k_base 对 CJK 严重低估 token 数 → 裁剪策略失效	CJK 保守估算（模型 tokenizer 优先，退化 CJK 字符×1.5）
I14	P2	7/10	Writer 逐章串行生成 3-5 分钟	保持串行+文档约束（章间引用需前章摘要，并行复杂；UI 预估时长提示）

7. Outside Voice（独立挑战，8 项全接受）

#	发现	裁定
OV1	审查决策未写回执行文档（rag-layer/api-design/runtime/plan 仍含双实现描述，Phase4 会重建放弃的抽象）	接受：T5 同步修订四处文档
OV2	bge-small-zh-v1.5 面向中文，实际语料为日文	接受：T11 切换 bge-m3+日文样本验证
OV3	可追溯性标准未操作性定义（URI 格式不一致、无 resolver、QA#8 可作弊）	接受：T12 统一 URI+resolver+强验证
OV4	成功标准无量度（无黄金集/评分器）	接受：T13 建立黄金集+评分器
OV5	DataGate 是原则非机制，1000 行 Excel 上下文爆炸	接受：T14 机制化+规模测试前置
OV6	QA 循环无边界 + 自校验盲区（DeepSeek 检查 DeepSeek）	接受：T15 护栏+QA 走 fallback_model
OV7	崩溃恢复只到会话级，任务层丢数据	接受：T16 任务级持久化
OV8	最难成功标准（格式精度）排关键路径末尾	接受：T17 docx 注入原型提前

---

8. Required Outputs

8.1 NOT in scope（本次审查明确延后）

项	延后理由
Qdrant/QdrantAdapter	与 S1 裁定一致，移除（v2 触发项）
Redis/Valkey Queue 实现	与 S2 裁定一致，接口保留（v2 触发项）
LLM 调用缓存	design §9.2 已列 v2，识别为有意延期
成本/限流监控	design §9.1 v2 预留
Type C 参考设计文档 RAG	rag-layer §1.1 已声明可选增强，初期聚焦 Type A+B
多用户并发隔离	v1 单用户演示，多用户隔离基线保留（§8.2）

8.2 What already exists（设计复用核查）

已实现	复用情况
InferenceEngine（M3.1）	✅ 设计直接复用；需按 I1/I2/I4/I9 加固
Excel/Word/混合 Parser（Phase2/2.5/3）	✅ 设计直接复用；I8 微重构
PromptRegistry / token 估算	✅ 复用；I11 修正估算
7 个脱敏真实样本（samples/）	✅ T13 黄金集基础
config 三 yaml + env 覆盖	✅ 复用；I5 清理死配置

8.3 失败模式（关键路径）

路径	失败场景	测试覆盖	错误处理	用户可见性
chat_structured 输出不合 schema	LLM 返回缺字段 JSON → 消费方 KeyError	I1 修复后新增	I1 修复后 parse_error	✅ 重试后显示失败
解析重试主模型弱	重试 2 次全败 → 无降级	I2 修复后新增	I2 修复后 fallback	✅ 降级事件可见
用户取消生成	状态悬置无定义	I3 修复后新增	I3 修复后 cancelled	✅ cancel 端点语义明确
恶意规则文档注入	规则含「忽略以上指令」→ 污染输出	I4 修复后新增	I4 修复后引擎级阻断	⚠️ 需测试验证
日文长文本超上下文	裁剪低估 → API 超限拒绝 → 重试循环	I11 修复后新增	I11 修复后裁剪准确	✅ 重试机制
服务重启丢进行中任务	中断后重复章节或卡死	OV7(T16) 后新增	需任务落盘	⚠️ 当前静默失败

8.4 Worktree 并行化策略

Lane A（前端+编排）：T3 状态机 → T14 DataGate → T16 任务持久化（共享 orchestrator/）
Lane B（RAG 独立）  ：T6 rerank → T11 bge-m3（共享 rag/，不与 A 冲突）
Lane C（推理加固）  ：T1 jsonschema → T2 降级链 → T4 注入防护 → T8 异步 → T9 token（共享 inference/，串行）
Lane D（基础设施）  ：T7 helper / T5 死配置 / T10 文档 / T12 resolver / T13 黄金集 / T15 QA / T17 原型

执行序：C（加固核心）先于一切 → A + B 并行 → D 穿插。Lane C 与 A 共享引擎层，建议 C 完成后 A 再启动。

---

9. Implementation Tasks（17 项）

全部任务已输出至 ~/.gstack/projects/unknown/tasks-eng-review-20260811-160000.jsonl（/autoplan 可聚合）。

• T1 (P1, human: ~2h / CC: ~20min) — inference — chat_structured 接入 jsonschema 真校验
• T2 (P1, human: ~1.5h / CC: ~15min) — inference — 解析重试降级链 + 模型名局部变量
• T3 (P1, human: ~3h / CC: ~40min) — orchestrator — 状态机 cancelled+resume
• T4 (P1, human: ~3h / CC: ~30min) — inference — 引擎层统一注入防护
• T5 (P2, human: ~1h / CC: ~10min) — config — 删死配置+同步文档（含 OV1）
• T6 (P2, human: ~4h / CC: ~45min) — rag — v1 rerank 精排
• T7 (P2, human: ~30min / CC: ~5min) — parsers — 提取 _validate_path helper
• T8 (P1, human: ~5h / CC: ~1h) — inference — LLM 客户端全异步化
• T9 (P2, human: ~1h / CC: ~15min) — inference — CJK 保守 token 估算
• T10 (P3, human: ~1h / CC: ~10min) — documentation — Writer 串行约束写回
• T11 (P2, human: ~3h / CC: ~30min) — rag — bge-m3 + 日文样本验证（OV2）
• T12 (P1, human: ~6h / CC: ~1.5h) — provenance — URI 统一+resolver（OV3）
• T13 (P1, human: ~8h / CC: ~2h) — eval — 黄金集+评分器（OV4）
• T14 (P2, human: ~5h / CC: ~1h) — orchestrator — DataGate 机制化（OV5）
• T15 (P2, human: ~3h / CC: ~40min) — qa — QA 护栏+fallback 路由（OV6）
• T16 (P2, human: ~6h / CC: ~1.5h) — orchestrator — 任务级持久化（OV7）
• T17 (P1, human: ~6h / CC: ~1.5h) — writer — docx 注入原型提前（OV8）

---

10. 完成摘要（Completion Summary）

• Step 0 Scope Challenge: 范围缩减（移除 2 处双实现抽象）
• Architecture Review: 7 issues found（全部裁定）
• Code Quality Review: 3 issues found（全部裁定）
• Test Review: 覆盖图已产出，0 独立缺口（随架构裁定覆盖）
• Performance Review: 2 issues found（全部裁定）
• NOT in scope: 已写入（§8.1）
• What already exists: 已写入（§8.2）
• TODOS.md: N/A（项目无此文件；17 项任务已入 JSONL）
• Failure modes: 6 条关键路径记录，1 处临界缺口（重启丢任务静默失败 → T16 修复）
• Outside voice: 已运行（Claude 子代理），8 项全部接受
• Parallelization: 4 lanes，C→(A+B) 并行，D 穿插
• Lake Score: 17/17 推荐选择完整方案

---

GSTACK REVIEW REPORT

Review	Trigger	Why	Runs	Status	Findings
CEO Review	/plan-ceo-review	Scope & strategy	0	—	—
Codex Review	/codex review	Independent 2nd opinion	0	—	—
Eng Review	/plan-eng-review	Architecture & tests (required)	1	ISSUES_OPEN	11 issues + 8 outside voice
Design Review	/plan-design-review	UI/UX gaps	0	—	—
DX Review	/plan-devex-review	Developer experience gaps	0	—	—

• CROSS-MODEL: Outside voice（Claude 子代理）与主审查交叉验证——OV1 为已裁定项的执行监督，OV2/3/4/5/6/7/8 为互补新发现，无实质分歧。
• VERDICT: ENG REVIEW 完成（11 issues + 8 findings 全部裁定，待实施后复核）。eng review not yet CLEAR — 需任务实施后重跑确认。

UNRESOLVED DECISIONS:

• 无（全部 19 项裁定完成）