# 设计评审报告

> 版本: 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）按迭代计划推进。