RAG/docs/04-project-todo.md

# 项目全生命周期 TODO 与进度看板

| 项目 | 当前值 |
|---|---|
| 基线日期 | 2026-07-12 |
| 当前阶段 | Stage 1：模型与数据库 PoC，`IN_PROGRESS` |
| 已完成阶段 | Stage 0：仓库、安全和设计基线 |
| 整体完成度 | 约 12%，合理区间 10%–15% |
| 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
| 业务代码完成度 | 约 8%；Stage 1 的离线/数据库 PoC 已验收，真实百炼 smoke 仍待新 Key，前端产品功能尚未实现 |
| 当前预计剩余工期 | 约 9–13 周，含 300 题正式标注、盲测、论文和答辩缓冲 |
| 进度权威来源 | 本文的阶段状态、验收证据和已推送提交 |

本文把 [总体设计](00-overall-design.md)、[数据与评测设计](01-data-and-evaluation.md)、[部署与安全设计](02-deployment-and-security.md) 和 [实施计划](03-implementation-plan.md) 转换为从当前状态到最终答辩、归档的可执行清单。它只表示计划和已验证事实，不因文档完整就声称系统代码已经完成。

## 1. 状态与完成度规则

### 1.1 状态定义

| 状态 | 含义 | 进入条件 | 退出条件 |
|---|---|---|---|
| `DONE` | 阶段已形成可验证闭环 | 功能、测试、文档、提交均完成 | 验收证据齐全且提交已推送 |
| `IN_PROGRESS` | 当前正在实施 | 依赖满足并已有明确执行任务 | 达到 `DONE`，或因硬门禁转为 `BLOCKED` |
| `TODO` | 尚未开始 | 前置阶段或资源未满足 | 依赖满足并正式启动 |
| `BLOCKED` | 硬门禁阻止继续 | 缺授权、密钥、外部服务或必要决策 | 阻断证据消除并记录恢复原因 |
| `OPTIONAL` | 不影响首版答辩主链路 | 核心目标已满足且仍有时间 | 完成或明确延期 |

阶段只有在以下四项同时成立时才能标记 `DONE`：

1. 范围内功能及失败路径已经实现。
2. 适用的自动测试、静态检查和安全检查通过。
3. 验收证据可复查，设计与运行文档已同步。
4. 符合 Lore 协议的提交已经推送，远端提交可见。

### 1.2 进度口径

当前进度采用里程碑权重，不采用“文件数量”或“代码行数”：

| 阶段 | 权重 | 当前状态 | 已计入进度 |
|---|---:|---|---:|
| Stage 0 设计与安全基线 | 12% | `DONE` | 12% |
| Stage 1 模型与数据库 PoC | 8% | `IN_PROGRESS` | 0% |
| Stage 2 完整工程骨架 | 10% | `TODO` | 0% |
| Stage 3 数字文档入库 | 14% | `TODO` | 0% |
| Stage 4 检索与重排 | 12% | `TODO` | 0% |
| Stage 5 生成、引用和 UI | 12% | `TODO` | 0% |
| Stage 6 OCR、表格与质量 | 10% | `TODO` | 0% |
| Stage 7 正式评测与消融 | 12% | `TODO` | 0% |
| Stage 8 安全、恢复、性能和论文 | 7% | `TODO` | 0% |
| Stage 9 答辩、发布与归档 | 3% | `TODO` | 0% |
| **合计** | **100%** | — | **12%** |

Stage 1 已完成可离线验收的数据库、适配器契约和 synthetic seed 子闭环，阶段内部约完成 85%；但真实三模型 smoke 仍依赖轮换后的新 Key，因此 Stage 1 不提前计入整体里程碑。本文复选框表示“已通过验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑约 12%，Stage 1 离线部分可运行，真实百炼验证尚未完成。**

## 2. 阶段依赖与关键路径

```text
Stage 0 DONE
  -> Stage 1 模型/数据库 PoC
  -> Stage 2 完整工程骨架
  -> Stage 3 数字文档入库
       -> Stage 4 检索与重排
       -> Stage 6 OCR/表格（可与 Stage 4、5 部分并行）
  -> Stage 5 生成/引用/UI
  -> Stage 7 正式评测（标注可在 Stage 3 后提前启动）
  -> Stage 8 安全/恢复/性能/论文
  -> Stage 9 答辩/发布/归档
```

| 阶段 | 必须依赖 | 可提前并行的工作 | 不得提前做的工作 |
|---|---|---|---|
| Stage 1 | Stage 0、已轮换 Secret、受控联网 | 虚构数据和 fake server 契约测试 | 使用真实地质资料，或使用已暴露密钥 |
| Stage 2 | Stage 1 三模型和迁移 PoC | 前端静态布局、OpenAPI 生成脚本 | 绕过任务租约直接做不可恢复长任务 |
| Stage 3 | Stage 2 服务骨架 | 合法语料清单、标注规范准备 | 未通过 `CLOUD_APPROVED` 的内容出域 |
| Stage 4 | Stage 3 可追溯切片与向量 | 100 组三元组完善 | 用测试集调相似度、Top K 或阈值 |
| Stage 5 | Stage 4 稳定候选和引用 ID | UI 组件、Prompt fake 测试 | 让前端直接接触模型 Key |
| Stage 6 | Stage 3 数据状态机 | 与 Stage 4、5 并行开发 | 把图例 OCR 宣称为完整图件理解 |
| Stage 7 | Stage 4、5；正式总评需 Stage 6 | Stage 3 后开始问题编写和双审 | 开发者查看盲测答案，或把 Gold 入库 |
| Stage 8 | Stage 2–7 主链路稳定 | 论文各章随阶段持续写作 | 未恢复验证就声称备份可用 |
| Stage 9 | Stage 8 发布候选通过 | 演讲稿和演示素材提前准备 | 在最终演示前临时升级依赖或模型配置 |

## 3. Stage 0：仓库、安全和设计基线

- **状态：** `DONE`
- **工期：** 已完成
- **依赖：** 无

### 已完成任务

- [x] 建立仓库说明、贡献约定、安全说明和 AGENTS 约束。
- [x] 建立 `backend/`、`frontend/`、`data/`、`ops/`、`scripts/` 和 `docs/` 结构。
- [x] 完成 00–03 总体、数据评测、部署安全和实施计划设计基线。
- [x] 建立 ADR 入口和首批关键架构决策。
- [x] 建立 `.gitignore`、本地 Secret 扫描钩子和 Gitea 工作流基线。
- [x] 建立 `make verify-design`、Markdown 相对链接和 diff 检查。
- [x] 将 Stage 0 基线提交推送到 `origin/main`。

### 验收证据

- `git status --short --branch` 显示 `main...origin/main`，Stage 0 基线提交远端可见。
- `make verify-design` 可检查 Secret、设计文档、相对链接和 diff。
- [00-overall-design.md](00-overall-design.md) 明确状态为“设计基线，待实现验证”。
- 当前不存在可运行应用，因此 Stage 0 的完成只代表设计和工程防线完成。

### 已完成提交/推送节点

- [x] `S0-A`：建立安全、架构、数据、部署和实施设计基线。
- [x] 推送 `main` 并确认 `origin/main` 指向 Stage 0 基线提交。

### 后续仍持续生效的门禁

- 真实 Key、真实工作空间地址、受限数据和私有 benchmark 永不进入 Git。
- 新实现若改变边界、数据状态或模型契约，必须先更新 ADR/设计再验收。
- Stage 0 完成不能被用于宣称模型、数据库、后端或前端已经可运行。

## 4. Stage 1：模型与数据库 PoC

- **状态：** `IN_PROGRESS`
- **预计工期：** 1–2 个工作日；外部密钥或网络未就绪时暂停计时
- **依赖：** Stage 0；已轮换百炼 Key；允许的工作空间端点；本机 Docker

### 具体实现任务

#### 4.1 安全与供应商前置

- [ ] 在百炼控制台撤销聊天中曾暴露的旧 Key，创建新 Key。
- [ ] 通过 Docker Secret 或未提交的本地 Secret 文件注入新 Key；禁止写入 `.env.example`。
- [ ] 分别确认 Embedding、Rerank 和 Chat 的实际路径、请求协议、模型返回名和能力指纹。
- [ ] 记录脱敏的 endpoint identity hash、region、resolved revision 或受控 cache epoch。
- [x] 建立 live provider 测试的手动开关；默认 CI 只使用 fake server。

#### 4.2 最小后端和 Compose

- [x] 创建 `backend/pyproject.toml` 和依赖锁文件，不引入未说明依赖。
- [x] 创建最小 `backend/Dockerfile`，使用非 root 用户和固定基础镜像 digest。
- [x] 创建最小 `compose.yaml`，包含 `db + migrate + provider-smoke + seed-demo/offline`。
- [x] 创建 PostgreSQL bootstrap、migrator 和 app 分权角色初始化脚本；备份只读角色在备份功能落地时单独创建。
- [x] 创建 Alembic 基线迁移，启用 pgvector 并建立 1024 维向量表/HNSW 基线。
- [x] 确保运行期服务不挂载 bootstrap 或 migrator Secret。

#### 4.3 三模型适配器

- [x] 实现 `EmbeddingProvider.embed_documents` 和 `embed_query` 契约。
- [x] 通过 MockTransport 验证 `text-embedding-v4` 的 1024 维、批次下标和有限浮点数；真实响应待 smoke。
- [ ] 对原生 Embedding 模式区分 `document/query`；兼容模式能力必须显式记录。
- [x] 实现 `qwen3-rerank` 候选索引回填、Token 预检、Top 10 保存。
- [x] 实现 `deepseek-v4-flash` 最小流式 Chat，默认关闭搜索和思考。
- [x] 为三个适配器实现 timeout、429/5xx 有界重试和脱敏错误映射。

#### 4.4 虚构数据和测试

- [x] 创建 `provider_smoke`，只输出状态、模型、耗时、request ID 和脱敏错误码。
- [x] 创建 `seed-demo`，使用 20 条明确标记的虚构文本完成写入、检索和重排。
- [x] 重复运行 seed，证明行数和任务不增长。
- [x] 建立 fake server 契约测试，覆盖成功、乱序、无效响应、401、429、5xx 和超时。
- [x] 建立并执行迁移空 volume、角色权限和 Docker 重启持久化测试。
- [x] 明确文档族 split、盲测保管人和“盲测用于调参即退役”规则。
- [x] 扩展 `make verify`，纳入 Stage 1 后端格式、类型和测试门禁。

### 验收证据

- [x] `docker compose up db migrate` 在空 volume 成功建立扩展、角色和表。
- [ ] `docker compose run --rm provider-smoke` 三模型探测成功，日志无 Secret。
- [x] `docker compose run --rm seed-demo-offline` 完成 20 条虚构数据写入、检索和重排；真实模式待新 Key。
- [x] 第二次运行 seed 后数据库计数与第一次相同，均为 chunks/vectors/searchable = 20/20/20。
- [x] 41 项测试证明 Embedding 维度/下标、Rerank 下标、Chat 流式响应和失败路径正确。
- [x] `make verify`、Secret 扫描、固定镜像构建和 `git diff --check` 通过。

### 2026-07-12 已验证运行证据

- 全新 volume 上 `db` 达到 healthy，`migrate` 以非超级用户退出码 0，版本为 `0001_initial_schema`。
- `vector` 扩展与 HNSW 基线存在；app/migrator 均非超级用户，app 无 `rag` schema DDL 权限但具有所需 DML。
- 两次离线 seed 均输出 20/20/20，9 个可回答虚构问题 Hit@3 = 9/9。
- PostgreSQL 重启后计数仍为 20/20/20。
- app 尝试修改已 `CLOUD_APPROVED` 的 `cloud_text` 被审批不可变触发器拒绝；尝试建表被权限拒绝。
- 唯一未验收项是真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` smoke 与真实模式 seed。

### 提交/推送节点

- [ ] `S1-A`：数据库初始化、分权角色、迁移和最小 Compose；验证后提交并推送。
- [ ] `S1-B`：三模型适配器、fake 契约测试和 live smoke；验证后提交并推送。
- [ ] `S1-C`：20 条虚构 seed、幂等验证、运行证据和文档同步；验证后提交并推送。

建议最终阶段提交意图：`Prove the selected model chain before building product workflows`。

### 风险门禁

- **停止条件：** 新 Key 未轮换、Secret 出现在日志/镜像、真实端点能力不明、迁移使用超级用户运行。
- **禁止数据：** Stage 1 只使用虚构文本，不上传任何真实地质报告。
- **降级策略：** 供应商暂不可用时完成 fake 契约和数据库工作，但 Stage 1 不得标记 `DONE`。
- **进入 Stage 2 的门槛：** 三模型真实 smoke、迁移和 seed 幂等全部通过。

## 5. Stage 2：扩展为完整工程骨架

- **状态：** `TODO`
- **预计工期：** 3–4 个工作日
- **依赖：** Stage 1 `DONE`

### 具体实现任务

- [ ] 建立 FastAPI 应用工厂、配置加载、稳定错误码和 OpenAPI。
- [ ] 按 `domain -> ports -> services -> adapters/persistence` 落实后端依赖边界。
- [ ] 建立 SQLAlchemy 仓储、Alembic 迁移运行器和事务边界。
- [ ] 建立 PostgreSQL `background_jobs`、租约、lease token、fencing 和重试状态机。
- [ ] 建立 Worker maintenance loop、advisory-lock reaper 和强杀恢复测试。
- [ ] 建立 `/health/live`、`/health/ready` 和管理员模型能力探测端点。
- [ ] 建立 React + TypeScript strict、路由、TanStack Query 和 OpenAPI 客户端生成。
- [ ] 建立 Nginx，仅发布 Web 端口；API、Worker、DB 只在内部网络。
- [ ] 建立完整 Compose：`web/api/worker/db/migrate`，OCR profile 默认关闭。
- [ ] 建立 Ruff、类型、pytest、ESLint、TypeScript、Vitest 和镜像检查。
- [ ] 建立 Gitea CI 的 fake provider 测试；外部 PR 不运行真实 Key 测试。

### 验收证据

- [ ] 空白机器仅按 README 执行即可启动完整骨架。
- [ ] migration 只执行一次，失败时 API readiness 不通过。
- [ ] `docker compose ps` 只暴露 Nginx/Web 端口。
- [ ] Docker 重启后数据库数据保留。
- [ ] 强杀 Worker 后验证可重领、耗尽进入 `FAILED`、旧 token 不能提交。
- [ ] 后端/前端 lint、类型、单元和集成测试均通过。

### 提交/推送节点

- [ ] `S2-A`：FastAPI、持久化、健康端点和错误契约。
- [ ] `S2-B`：任务租约、reaper、fencing 和恢复测试。
- [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档。
- [ ] 每个节点验证后独立提交并推送；Stage 2 完成时在本文更新状态。

### 风险门禁

- 不为单机毕设提前引入 Redis、Celery、微服务或独立向量数据库。
- readiness 不把百炼短时故障等同于 API 容器不可用；模型健康单独展示。
- 前端构建产物、OpenAPI 示例和测试日志不得包含 Key 或真实受限数据。

## 6. Stage 3：数字文档入库主链路

- **状态：** `TODO`
- **预计工期：** 1 周
- **依赖：** Stage 2 `DONE`；合法数字资料样本和审核人可用

### 具体实现任务

- [ ] 实现上传流式大小、扩展名、MIME、页数、加密和恶意文件检查。
- [ ] 实现 `QUARANTINED_LOCAL_REVIEW -> LOCAL_PARSED_PENDING_CLOUD_REVIEW -> CLOUD_APPROVED/REJECTED` 状态机。
- [ ] 在隔离本地完成数字 PDF/DOCX/TXT/Markdown 解析、页码和章节恢复。
- [ ] 生成 `raw_text`、脱敏 `cloud_text` 和 outbound manifest；所有外发调用前核对哈希。
- [ ] 实现 512 Token 基线切分、64 Token 重叠、表头上下文和元数据前缀开关。
- [ ] 实现精确去重、近重复族、版本关系和确定性 chunk ID。
- [ ] 实现 Embedding 批次、内容缓存、chunk assignment、检查点和有界重试。
- [ ] 实现 `documents.active_version_id` 与 `chunks.searchable` 单事务切换和持续对账。
- [ ] 实现删除立即退出检索、后台物理清理和最小审计记录。
- [ ] 实现知识库、文档列表、上传进度、复核状态和错误详情 UI。
- [ ] 冻结 corpus manifest 与文档族 60/20/20 split；盲测标签由独立保管人控制。
- [ ] 用允许使用的小规模数字 PDF 语料完成端到端入库演练。

### 验收证据

- [ ] 100% `searchable` 切片可追溯当前文档版本、页码和 outbound manifest。
- [ ] `approved chunks == READY vector assignments`，维度和文本/profile 哈希一致。
- [ ] 同一文件重复上传、任务重跑和中断恢复不产生重复记录或重复费用。
- [ ] 新版本未完整 READY 前旧版本继续可检索；切换没有空窗。
- [ ] 删除后在线查询立即不可命中，物理清理可审计。
- [ ] 未获云审批的文档不会触发 Embedding、Rerank 或 LLM 请求。

### 提交/推送节点

- [ ] `S3-A`：上传、数据治理状态机和本地解析。
- [ ] `S3-B`：结构切分、去重、向量任务和版本激活。
- [ ] `S3-C`：文档 UI、删除/恢复测试、corpus manifest 和证据。
- [ ] 每个节点通过安全与回归门禁后提交、推送。

### 风险门禁

- 权利、涉密等级、云处理权限任一不明确即停止外发。
- `cloud_text`、处理器或 manifest 任一变化自动撤销原审批。
- 解析失败页、跨页表和低置信内容必须显式失败或进入复核，不静默丢弃。

## 7. Stage 4：检索与重排

- **状态：** `TODO`
- **预计工期：** 1 周
- **依赖：** Stage 3 `DONE`；开发集 qrels/100 组三元组可用

### 具体实现任务

- [ ] 实现 query embedding，并在原生模式使用 `text_type=query`。
- [ ] 实现同权限过滤条件下的 exact Cosine Top K 基线。
- [ ] 实现 HNSW、iterative scan、`ef_search`、over-fetch 和 ANN 对账。
- [ ] 在候选生成 SQL 内应用知识库、角色、文档状态和可见范围过滤。
- [ ] 实现 Dense Top 50、`qwen3-rerank` Top 10、生成上下文 Top 8。
- [ ] 实现 Rerank 总 Token 预检、响应 index 回填、裁剪和错误分类。
- [ ] 实现候选去重、邻接补全和上下文 Token 预算。
- [ ] 实现检索实验室：展示查询配置、初召回、重排、来源和耗时。
- [ ] 完善 100 组三元组，覆盖同义词、实体冲突、数字、单位、OCR 和难负例。
- [ ] 校准 Top K 和阈值；所有参数只使用开发集。

### 验收证据

- [ ] 三元组 `sim(query, positive) > sim(query, hard_negative)` 达到预设目标或形成完整错误报告。
- [ ] 至少 200 个查询的 ANN Recall@10 相对 exact 基线达到目标，过滤条件完全相同。
- [ ] 未授权文档从候选生成阶段即被排除。
- [ ] Rerank 前后 MRR/nDCG、延迟和 Token 可复查。
- [ ] 相同运行配置可由 `config.yaml` 和 provider profile 重现。

### 提交/推送节点

- [ ] `S4-A`：exact/HNSW、权限过滤和 ANN 质量测试。
- [ ] `S4-B`：Rerank、上下文构建和错误处理。
- [ ] `S4-C`：检索实验室、三元组报告和参数冻结。

### 风险门禁

- 不使用一个固定余弦或 Rerank 分数跨所有问题通用。
- Rerank 不能恢复初召回未命中的证据，错误归因必须分层。
- 不得查看盲测答案后调整维度、Top K、阈值或 instruct。

## 8. Stage 5：生成、引用和问答 UI

- **状态：** `TODO`
- **预计工期：** 1 周
- **依赖：** Stage 4 `DONE`

### 具体实现任务

- [ ] 建立版本化 Grounded Answer Prompt，要求仅依据编号证据回答。
- [ ] 实现 `deepseek-v4-flash` SSE、取消传播、超时和流式错误事件。
- [ ] 后端将模型引用编号映射到真实 chunk/doc/page，拒绝模型自造引用。
- [ ] 实现证据不足拒答、模型失败时保留检索结果、资料冲突分来源陈述。
- [ ] 实现会话与消息持久化、来源卡片、页码定位和用户反馈。
- [ ] 实现文档管理、聊天、检索实验室、评测和系统状态页面导航。
- [ ] 清理 Markdown/HTML，验证 XSS、危险链接和 Prompt Injection 回归。
- [ ] 测试用户取消后 Embedding/Rerank/Chat 下游请求停止。
- [ ] 记录 trace、阶段耗时、Token、request ID 和脱敏错误。

### 验收证据

- [ ] 回答中的每个引用均可打开到授权文档和正确页码。
- [ ] 模型伪造、越界或不存在的引用被后端拦截。
- [ ] 无答案题正确拒答；系统错误与“证据不足”状态不同。
- [ ] 模型不可用时仍展示检索来源和可理解错误。
- [ ] Playwright 覆盖上传、问答、引用、取消、失败重试和 XSS。

### 提交/推送节点

- [ ] `S5-A`：生成服务、证据 Prompt、引用验证和拒答。
- [ ] `S5-B`：聊天/来源 UI、SSE 取消和错误状态。
- [ ] `S5-C`：端到端、安全回归、可观测性和文档。

### 风险门禁

- 模型输出永远视为不可信数据；引用和 Markdown 必须后端/前端双层校验。
- 前端不得获得模型 Key、工作空间凭证或未授权文档正文。
- 不把问答系统输出表述为勘查结论、储量评估或投资建议。

## 9. Stage 6：OCR、表格和数据质量挑战集

- **状态：** `TODO`
- **预计工期：** 1–2 周
- **依赖：** Stage 3 `DONE`；可与 Stage 4、5 部分并行

### 具体实现任务

- [ ] 建立页级数字/扫描/混合 PDF 检测。
- [ ] 建立隔离的 OCR worker profile、资源限制和临时文件清理。
- [ ] 实现 300 DPI 渲染、旋转/倾斜校正、PaddleOCR/PP-Structure 输出。
- [ ] 保留 `raw_text`、修订文本、bbox、置信度、修订人和处理器 profile。
- [ ] 建立低置信页、数值密集页、表格页人工复核队列。
- [ ] 提取表格 JSON、Markdown、截图引用和逐行语义文本。
- [ ] 处理跨页表、合并单元格、表头、单位和脚注；无法确认时显式失败。
- [ ] 建立 OCR 金标准页、术语/数字/单位和表格行列对齐评测。
- [ ] 建立图件挑战集和 UI 边界提示，不宣称已理解空间几何。

### 验收证据

- [ ] 金标准页 CER ≤ 3%，地质术语准确率 ≥ 95%，数字/符号/单位准确率 ≥ 98%。
- [ ] 表格行列对齐 ≥ 97%，数值及单位准确率 ≥ 99%。
- [ ] OCR 原文和人工修订文本均可追溯且不会互相覆盖。
- [ ] 跨页表/合并单元格失败可见，不产生静默错位。
- [ ] 只依赖图件空间关系的问题被标记为挑战集或拒答。

### 提交/推送节点

- [ ] `S6-A`：扫描检测、OCR worker 和复核队列。
- [ ] `S6-B`：表格结构、语义行和数值校验。
- [ ] `S6-C`：金标准质量报告、图件边界和文档。

### 风险门禁

- OCR/表格完整处理必须在出域审批前于隔离环境完成。
- 低置信结果不得自动变为 `searchable`。
- OCR 模型、预处理或修订变化后，outbound manifest 和向量审批必须失效重做。

## 10. Stage 7：正式验证集、盲测与消融

- **状态：** `TODO`
- **预计工期：** 3–4 周；语料标注可在 Stage 3 后提前并行
- **依赖：** 问题编写依赖 Stage 3；最终评测依赖 Stage 4–6 `DONE`

### 具体实现任务

- [ ] 建立至少 300 题：构建、开发、盲测各 100；500 题仅作为资源充足时扩展。
- [ ] 按文档族、来源、矿种、题型、模态、难度和多跳分层。
- [ ] 为 Gold 和全部 0–3 judgment 建立不可变源锚点。
- [ ] 双人独立审核答案、证据和可回答性；第三名地质评审裁决。
- [ ] 建立 `anchored_judgments.jsonl`、manifest、版本和 SHA-256。
- [ ] 使用 Dense/词法/Hybrid/Rerank union pooling；未判定结果先补标再计分。
- [ ] 每个 run 生成独立 qrels、anchor resolution、预测、指标和错误报告。
- [ ] 实现 Hit、CompleteHit、EvidenceGroupRecall、MRR、nDCG、专家答案、忠实度、引用和拒答指标。
- [ ] 对查询做 1000 次 bootstrap，输出 95% 置信区间和分层结果。
- [ ] 在开发集完成维度、切片、重叠、前缀、Rerank、上下文、Query 改写等消融。
- [ ] 冻结最终配置、corpus、judgment set 和盲测哈希，再执行一次正式盲测。
- [ ] 补标或裁决变化后生成新 judgment 版本，并对比较表中全部系统重新计分。
- [ ] 生成论文图表、成本/延迟对比和错误分类案例。

### 验收证据

- [ ] Gold、参考答案、qrels、`eval/` 和 `runs/` 永不被知识库导入器扫描。
- [ ] 正式盲测标签在参数冻结前对开发者不可见。
- [ ] 检索、重排、生成、引用、拒答和端到端指标均有版本化输入与配置。
- [ ] 所有比较系统使用相同 judgment snapshot、resolver 和 corpus manifest。
- [ ] 所有论文实验图表可由冻结运行产物重新生成。
- [ ] 若盲测结果用于调参，该集合立即退役，最终结论改用新盲测集。

### 提交/推送节点

- [ ] `S7-A`：问题 schema、源锚点、标注工具和构建/开发集。
- [ ] `S7-B`：盲测托管、union pooling、评测 runner 和评分规约。
- [ ] `S7-C`：消融、配置冻结和最终盲测。
- [ ] `S7-D`：图表、错误分析、成本和论文实验章节。

### 风险门禁

- 盲测问题、答案和标签必须由独立保管人/受控凭据管理。
- 公开 benchmark 只能包含允许再分发或充分脱敏的内容。
- LLM 可以辅助出题或评分，但不能同时成为唯一出题者、唯一裁判和最终评分者。
- 工期不足时缩减到 300 题，不降低盲测隔离、双审和可复现要求。

## 11. Stage 8：安全加固、恢复、性能和论文定稿

- **状态：** `TODO`
- **预计工期：** 1 周，论文写作应贯穿前序阶段
- **依赖：** Stage 2–7 主链路和评测结果稳定

### 具体实现任务

- [ ] 完成管理员、资料员、评测人员和普通用户 RBAC。
- [ ] 完成对象级知识库/文档权限、审计日志和越权回归。
- [ ] 完成上传限制、路径穿越、压缩炸弹、XSS、Prompt Injection 和限流测试。
- [ ] 完成结构化日志脱敏、trace、模型 Token/耗时、任务和索引监控。
- [ ] 固定镜像 digest、依赖锁和数据库迁移版本。
- [ ] 建立数据库、允许备份文件和独立 Secret 的备份策略。
- [ ] 在全新 Compose project 恢复数据库与文件，重建或校验索引。
- [ ] 恢复后运行固定 20 题冒烟并记录 RTO、缺口和哈希。
- [ ] 测量入库吞吐、查询 p50/p95、并发、错误率和每 1000 查询费用。
- [ ] 完成论文各章、系统截图、实验图表、失败案例和局限性。
- [ ] 完成部署手册、管理员手册、演示故障降级和恢复手册。

### 验收证据

- [ ] `make verify`、Secret 扫描、镜像检查、单元/集成/契约/E2E/安全测试通过。
- [ ] 空白环境恢复成功，并通过固定 20 题冒烟。
- [ ] 端到端 p95、稳态错误率、并发和成本均为实测结果。
- [ ] 论文中的每张实验图表可追溯到 run manifest。
- [ ] 论文明确系统边界，不夸大图件理解、找矿预测或专业决策能力。

### 提交/推送节点

- [ ] `S8-A`：RBAC、审计、安全和限流。
- [ ] `S8-B`：备份、恢复、性能和费用报告。
- [ ] `S8-C`：论文定稿、运维手册和 release candidate。

### 风险门禁

- 只有备份文件、没有空环境恢复证据，不得通过验收。
- 性能数字必须注明硬件、网络、数据规模、模型配置和采样窗口。
- release candidate 后不再做非必要依赖升级或架构替换。

## 12. Stage 9：答辩、发布与归档

- **状态：** `TODO`
- **预计工期：** 2–3 个工作日，另预留答辩排期缓冲
- **依赖：** Stage 8 release candidate `DONE`

### 具体实现任务

- [ ] 冻结答辩 release candidate、镜像 digest、迁移、模型配置和演示数据。
- [ ] 在干净机器完整执行 `docker compose up -d --build` 和健康检查。
- [ ] 按 [实施计划的答辩脚本](03-implementation-plan.md#8-最终答辩演示脚本) 连续彩排至少两次。
- [ ] 准备模型临时不可用时的降级演示、预录视频和静态证据。
- [ ] 检查答辩 PPT、论文、截图、日志和视频中没有 Secret 或受限原文。
- [ ] 准备演示问题：正常问答、无答案、版本冲突、表格数值和局限性。
- [ ] 生成公开归档包与内部受控归档包；两者使用不同 manifest。
- [ ] 归档源代码、迁移、锁文件、镜像 digest、公开样例、运行配置、论文和演示材料。
- [ ] 归档数据库/文件恢复说明、校验和、保留周期和销毁策略。
- [ ] 删除临时 Secret、临时文件和未授权数据；按策略轮换或撤销演示 Key。
- [ ] 创建最终 Git tag/release，推送远端并记录 commit、tag 和归档 SHA-256。
- [ ] 记录已知限制、未完成 OPTIONAL 项、后续维护人和恢复入口。

### 验收证据

- [ ] 干净环境演示全流程成功，或按预定降级方案完成而不泄漏数据。
- [ ] 答辩十步脚本中的每一步都有实时或冻结证据。
- [ ] 公开包通过 Secret、版权、坐标和商业秘密复核。
- [ ] 内部包访问控制、保留期、销毁责任人和恢复步骤明确。
- [ ] 最终 tag/release、论文版本、镜像 digest、run manifest 和归档哈希相互可追踪。

### 提交/推送节点

- [ ] `S9-A`：答辩 release candidate、演示脚本和故障降级证据。
- [ ] `S9-B`：论文/材料最终修订、公开与内部归档 manifest。
- [ ] `S9-C`：最终 tag/release、远端推送和归档校验记录。

### 风险门禁

- 答辩当天不临时升级模型、依赖、数据库或重新生成整套索引。
- 公开 release 不包含真实 Key、工作空间地址、受限语料、私有 benchmark 或可逆脱敏内容。
- 未验证恢复的备份、未固定哈希的实验和未推送提交不能作为最终归档证据。

## 13. 跨阶段风险登记与停止条件

| 风险 | 等级 | 触发信号 | 必须动作 | 解除门槛 |
|---|---|---|---|---|
| 已暴露或疑似暴露 Key | 严重 | Key 出现在聊天、日志、Git、镜像 | 立即停止真实调用并轮换；运行 Secret 扫描 | 新 Key 仅由 Secret 注入，旧 Key 已撤销 |
| 未授权/涉密资料出域 | 严重 | 许可、坐标、保密等级或云处理权不清 | 保持隔离，不调用任何云模型 | 审核 exact outbound manifest 并进入 `CLOUD_APPROVED` |
| Gold/盲测泄漏 | 严重 | `eval/` 被入库、开发者看到盲测标签 | 停止评测，作废受污染集合 | 新盲测集、独立保管和导入 allowlist 测试通过 |
| 模型别名漂移 | 高 | 能力指纹或响应模型变化 | 提升 cache epoch，冻结新 profile，重跑受影响实验 | 新旧运行明确分版，比较不混用 |
| 向量/版本不一致 | 高 | 文本哈希、profile、维度或 active 投影不一致 | 阻止激活并运行 reconciliation | 新版本全部 READY，原子切换验证通过 |
| OCR/表格静默错误 | 高 | 数值、单位、行列错位或低置信未处理 | 降级为复核/失败，不进入检索 | 金标准和人工复核门槛通过 |
| 供应商不可用/限流 | 中 | 429、5xx、超时或区域故障 | 有界重试、熔断、展示检索降级 | smoke 恢复且错误率正常 |
| 标注工期失控 | 高 | 3–4 周内无法完成 500 题 | 缩减到 300 题，保持双审与盲测 | 300 题各 split/题型覆盖满足规范 |
| 范围蔓延 | 中 | 提前引入微服务、多模态预测或新数据库 | 回到首版非目标，记录 ADR | 核心主链路和论文证据完成后再评估 |
| 答辩环境不稳定 | 高 | 干净机器失败、模型网络不稳 | 冻结 RC、准备预录和离线证据 | 连续两次彩排通过且有降级路径 |

## 14. 每阶段统一收尾清单

每个阶段完成前复制并勾选以下清单：

- [ ] 实现范围与本阶段 TODO 一致，未静默扩展权限、依赖或服务。
- [ ] 正常路径、失败路径和恢复路径均有验证。
- [ ] Ruff/类型/pytest、ESLint/TypeScript/Vitest/Playwright 等适用检查通过。
- [ ] `make verify`、Secret 扫描、Markdown 链接和 diff 检查通过。
- [ ] 数据库迁移可在空环境向前应用，必要时有回滚/恢复说明。
- [ ] API、配置、数据格式、ADR 和本文状态已同步。
- [ ] 验收证据记录命令、时间、commit、数据/配置哈希和已知缺口。
- [ ] 使用 Lore 协议提交；`Tested` 和 `Not-tested` 如实填写。
- [ ] 推送远端并确认提交、CI 和证据可见。
- [ ] 只有全部必选项完成后，才把阶段状态改为 `DONE` 并更新整体进度。

## 15. 下一步执行顺序

当前只推进 Stage 1，建议按以下顺序开始：

1. 轮换并受控注入新百炼 Key，确认真实端点不写入仓库。
2. 创建最小 Python 包、数据库初始化、Alembic 和 `db + migrate` Compose。
3. 用 fake server 实现并验证三模型适配器契约。
4. 运行受控 live smoke，记录 provider profile 和能力指纹。
5. 用 20 条虚构数据完成写入、检索、重排和幂等闭环。
6. 扩展 `make verify`，保存验收证据，完成 S1-A/S1-B/S1-C 提交与推送。

在 Stage 1 验收之前，不并行展开真实语料入库、完整 UI 或正式验证集调参。