2026Technology-Competition/docs/design-review.md

设计评审报告

版本: v1.1 | 日期: 2026-07-30 | 状态: 评审完成 + 修复已完成

评审范围：全量四层（config+数据模型 → 核心 Agent+运行时 → RAG+API+WebUI → 一致性交付） 评审视角：结构 / 实现 / 需求 / QA 多视角交叉 严重级：P0=实现阻塞 P1=应修 P2=建议

---

评审进度与修复状态

层	范围	评审状态	修复
1	config-design + design §3/§6/§9 数据模型	✅ 完成	✅ 已修复
2	agent-runtime + design §2 Impact / §4 / §7 QA	✅ 完成	✅ 已修复
3	rag-layer + api-design + web-ui-design	✅ 完成	✅ 已修复（含第1/2层连带）
4	sample-spec + implementation-plan + 全量一致性	✅ 完成	✅ 已修复

---

第 1 层：config + 数据模型

发现问题

P0-1　数据模型前向引用 / 定义顺序倒置（实现阻塞）

design.md §2-3 的既有类型定义于 §9.4 数据类型之前，却在类体内引用后置类型。若按文档顺序在单一顶层模块实现，不加 from __future__ import annotations 会触发 NameError：

引用类型	定义位置	引用位置(更早定义处)	问题
CellFormatting	§3 行392	CellValue.formatting（行388，在 392 之前）	顺序倒置
SheetType	§9.4.1 行1373	ExcelTable.detected_type（行406）	跨章前向引用
ExtractionMethod	§9.4.1 行1409	ExcelTable.extraction_method（行407）	跨章前向引用
RuleDocument	§9.4.2 行1417	StructuredSource.rule_docs（行436）	跨章前向引用
ImageAnalysis	§9.4.2 行1427	StructuredSource.image_analyses（行437）	跨章前向引用

建议修复（P0）：

1. 在 design.md §9.4 末尾新增「实现落地说明」：全部数据模型统一置于 src/.../data_models.py，文件顶部 from __future__ import annotations（注解惰性求值，类定义顺序无关）或调整枚举/类定义前置。
2. implementation-plan Phase1 任务 1.2 补充「data_models.py 须启用 future.annotations」。

P1-1　运行时编排队列表述与配置决策冲突

• agent-runtime-design.md §3.1（行203）写「步骤内部: 任务队列（Redis）」。
• 但用户决策 + docs/api-design.md §5 + docs/config-design.md app.yaml task_queue.backend=memory 均约定「默认 InMemoryQueue，Redis/Valkey 可选」。

建议修复：agent-runtime §3.1 改为「任务队列（抽象 TaskQueue，默认 InMemory，可切 Redis/Valkey）」并指向 api-design §5。

P2-1　Embedding / 存储配置字段命名不一致

• rag-layer-design.md manifest（§5.2）与存储适配（§9.4）使用键 embedding_model、adapter、persist_dir。
• config-design.md rag.yaml 使用嵌套 embedding.model、vector_store.adapter/chroma/qdrant。

建议修复：统一为 embedding.model 或 embedding_model 二选一，并在 rag-layer §9.4 注明与 config 键名对齐；删除 manifest 中与 config 重复的 persist_dir 硬编码提示（应读 config）。

P2-2　ImageDescription vs ImageAnalysis 字段大量重复

• ImageDescription（§9.4.3，ImageAnalyzer 原始输出）与 ImageAnalysis（§9.4.2，Parser 组装）含相同 image_ref/description/confidence/model，仅后者增加 sheet_name/anchor_cell/nearby_text/status。实现易混用（后续若切换，调用方拿错类型）。

建议修复：在此补注释「ImageDescription 为原始识别输出，ImageAnalysis 为带 Sheet 锚点与状态的组装结果」；delete 或改名其一，避免两个相似命名。

P2-3　config 未覆盖运行时子层配置（已核查，保持建议）

config-design.md 未定义记忆（runtime §4 三层容量/清理）、编排（状态机超时）等运行时参数，全部依赖 runtime 文档默认值。已核查：runtime §4 亦未给出配置项名。结论：不阻塞（记忆容量/超时为运行时内部策略，有默认值即可），实现期按实际调优再下沉 config（见文末「遗留建议」）。

---

第 1 层积极评价

• inference.yaml 与 agent-runtime §2.3-2.7 高度对齐（重试退避 1/3/7s、超时 60s、structured_output.max_parse_retry=2、tiktoken 估算、裁剪优先级、prompts 目录、model deepseek/deepseek-chat）。
• rag.yaml 与 rag-layer §6（RRF k=60、通道 top-k=10、融合 top_k 默认 5、上下文增强、bge-small-zh）完全对齐。
• 敏感项（API Key）全部收敛至 .env，未落入 yaml，符合 AGENTS.md 信息安全要求。
• QUEUE_BACKEND/REDIS_URL 与 api-design TaskQueue 三实现（memory/redis/valkey）一一对应。

---

第 2 层：核心 Agent + 运行时

发现问题

P1-1　编排任务队列表述与配置决策冲突（三处）

agent-runtime-design.md §3.1（行205 附近）与 §3.5（行284 附近） 两处写「任务队列（Redis）」，与：

• 用户决策（抽象 TaskQueue + InMemory 默认 + Redis/Valkey 可选）
• docs/api-design.md §5（TaskQueue 三实现）
• docs/config-design.md app.yaml task_queue.backend=memory

冲突。已修复：两处改为「抽象 TaskQueue，默认 InMemory，生产可切 Redis/Valkey（接口见 api-design §5）」。

P2-4　impact_matrix 内部结构未定义

design.md §4.4 impact_matrix.impacts/impacted_by 原为 [...] 占位，下游 Writer 需消费关系对象但无 schema。 已修复：补示例 + 注明「复用 relations[] 关系对象结构，impacts=to 方向、impacted_by=from 方向」。

P2-5　writing 阶段回退端点缺失

runtime §3.2 白名单允许 writing → awaiting_impact_confirm，但 api-design 无对应端点。 已修复：api-design §2.5 新增 POST /api/sessions/{id}/rollback-to-impact（writing → awaiting_impact_confirm）。

第 2 层积极评价

• 状态机 8 状态与 api-design 端点状态转移完全对齐（uploading→parsing→…→done；confirm/reparse/reject/run-qa/writer-fix 齐全）。
• 幂等机制（runtime §7.2 (chapter_id, version)）与 Writer ContentBlock (chapter_id, version) 一致；任务幂等键 (session, step, chapter_id) 与 api-design §5.3 一致。
• 三层记忆 + DataGate ↔ Writer §6.8 数据门 ↔ WriterState 章间引用闭环。
• 安全基线（Prompt 注入边界）与 Writer §6.8 prompt 组装一致；确认事件持久化（§3.4）支撑崩溃恢复。
• 异常处理 UX（重试/跳过/中断）与 api-design 错误码 options 字段一一对应。

---

第 3 层：RAG + API + WebUI

发现问题

P2-1　Embedding / 存储配置字段命名不一致（连带修复）

rag-layer/design.md 技术选型与 manifest 使用 embedding_model，config-design/design.md rag.yaml 使用 embedding.model。 已修复：rag-layer §2 统一指向 config/rag.yaml 的 embedding.model；manifest §4.3 加注释「embedding_model 为版本记录字段，值与 config 保持一致，不单独配置」。

第 3 层积极评价

• rag.yaml（embedding/chunk/retrieval）与 rag-layer §2/§3/§6 参数完全对齐（RRF k=60、通道 top-k=10、融合默认 5、上下文增强、bge-small-zh）。
• api-design 端点、状态转移、错误码与 runtime §3 / design §8 页面完全对齐（除 P2-5 已修）。
• 部署拓扑（单容器/生产、Valkey 零许可风险）与 config-design 6 章 Docker Compose 一致。

---

第 4 层：一致性 + 可交付

发现问题

P0-1 连带　plan §1.2 缺未来式注解说明（已修复）

implementation-plan §1.2 数据模型任务未提 future annotations → 已补充「文件头部 from __future__ import annotations，定义顺序不依赖」。

第 4 层积极评价

• samples ↔ plan 验收项全覆盖：表格型/自由记述型/混合型/取消线/合并单元格/规则冲突对 → 7 个样本逐一对应（§2.9、§5.9、§9 验证）。
• sample-spec 已注明 1000 行大数据样本需另行生成（不纳入本集）✓。
• 全量交叉核查：术语（write/design/ref）、状态机编号、章节引用、docs/* 相互链接一致，无孤立文档。
• config 敏感项全部收敛 .env，符合 AGENTS.md 信息安全约束 ✓。

---

修复执行记录

#	动作	文件	状态
1	§9.4 补「实现落地说明」（data_models.py + from __future__ import annotations）	design.md	✅
2	§3.1 / §3.5 任务队列改抽象 TaskQueue 表述	agent-runtime-design.md	✅
3	§1.2 补 future.annotations 要求	implementation-plan.md	✅
4	embedding 字段命名统一 + manifest 记录字段说明	rag-layer.md	✅
5	ImageDescription vs ImageAnalysis 区分注释	design.md §9.2/§9.3	✅
6	impact_matrix 内部结构补全	design.md §4.4	✅
7	writing → awaiting_impact_confirm 回退端点	api-design.md §2.5	✅
8	评审报告落盘（本次）	design-review.md	✅

---

遗留建议（不阻塞，可后续迭代）

• P2-3：config 未定义记忆（runtime §4 三层容量/清理）、编排超时等运行时参数，当前依赖 runtime 默认值。实现期可根据实际调优再决定是否下沉到 config。
• v2 预留：LLM 调用缓存 / 成本限流（runtime §9）按迭代计划推进。