YoVinchen
c3bad0f186
Some checks failed
verify / verify (push) Has been cancelled
Expose the verified synthetic retrieval path through a typed React client and a non-root Nginx edge while keeping database credentials and data-network reachability out of the browser tier. A fixed-origin gateway preserves request boundaries and now closes upstream streams even when downstream disconnects before body iteration. The deployment ADR and runbooks record the four-network topology and its accepted Web edge-egress risk. Constraint: The previously exposed Bailian key must be revoked and no live provider credential may enter Git, images, logs, or the browser. Rejected: Connect Web directly to the data network | expands lateral reach to PostgreSQL. Rejected: Publish the database-aware API on the edge network | gives a credential-bearing process a public default route. Rejected: Buffer streaming responses in either proxy | prevents incremental chat delivery in the future. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Do not mark Stage 1 or Stage 2 complete until the rotated-key live smoke and remaining stage gates pass. Tested: make verify; 65 backend tests; 14 frontend tests; Docker image build; container health and isolation probes; real HTTP demo/status/search/docs/OpenAPI checks. Not-tested: Live Bailian models, real document ingestion, business chat SSE generation, and final browser screenshot automation because the browser skill runtime was unavailable.
573 lines
34 KiB
Markdown
573 lines
34 KiB
Markdown
# 项目全生命周期 TODO 与进度看板
|
||
|
||
| 项目 | 当前值 |
|
||
|---|---|
|
||
| 基线日期 | 2026-07-12 |
|
||
| 当前阶段 | Stage 1：模型与数据库 PoC，`IN_PROGRESS` |
|
||
| 已完成阶段 | Stage 0：仓库、安全和设计基线 |
|
||
| 整体完成度 | 约 12%，合理区间 10%–15% |
|
||
| 设计完成度 | 设计基线已完成；实现中发现新约束时继续通过 ADR 和文档修订维护 |
|
||
| 业务代码完成度 | 约 18%；Stage 1 的 Docker API、离线检索、数据库 PoC，以及 React 离线演示、Nginx 单入口和四网络隔离前置均已验收；真实百炼 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、只读 API 和 Web 演示子闭环，安全离线子阶段内部约完成 95%；但真实三模型 smoke 仍依赖轮换后的新 Key，因此 Stage 1 不提前计入整体里程碑。Stage 2 中不依赖云密钥的 React、Nginx、网络隔离和质量门禁前置已经完成，但 Worker 租约、完整产品工作流等必选项尚未完成，Stage 2 仍为 `TODO`。本文复选框表示“已通过验收”，不表示“文件是否已经出现”。当前可诚实表述为：**设计基线完成，整体里程碑约 12%，业务代码约 18%，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 | React 离线演示、OpenAPI 类型生成、Nginx 单入口和网络隔离前置 | 绕过任务租约直接做不可恢复长任务 |
|
||
| 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] 启动最小 FastAPI `api + gateway`，内部 API 无 egress，gateway 无 Secret 并仅发布回环端口；提供真实数据库 readiness、Swagger 和只读 synthetic demo 检索。
|
||
- [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] `api + gateway` 镜像构建并达到 healthy；live/ready/meta/demo status/demo search 均通过真实 HTTP 验收。
|
||
- [x] 第二次运行 seed 后数据库计数与第一次相同，均为 chunks/vectors/searchable = 20/20/20。
|
||
- [x] 65 项后端测试证明模型契约、健康检查、固定上游 gateway、SSE 代理分块与早断连释放契约、离线 demo、数据治理和失败路径正确。
|
||
- [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。
|
||
- FastAPI 容器使用 app 最小权限角色，根文件系统只读且无 egress；无 Secret gateway 仅提供回环入口；Swagger 可见，demo search 返回合成片段与不透明 citation ID。
|
||
- API 容器对公网 TCP 探测返回 `ENETUNREACH (101)`；gateway 的 mounts 为空且不含数据库或百炼业务环境变量。
|
||
- PostgreSQL 重启后计数仍为 20/20/20。
|
||
- app 尝试修改已 `CLOUD_APPROVED` 的 `cloud_text` 被审批不可变触发器拒绝；尝试建表被权限拒绝。
|
||
- React + TypeScript strict 离线演示已实现工作台与系统状态页；14 项前端测试、ESLint、类型检查和生产构建通过。
|
||
- Nginx 成为唯一回环入口，Compose 仅发布 `127.0.0.1:8000`；`web -> gateway -> api` 同源链路、Swagger、OpenAPI、健康检查和 synthetic search 均通过真实 HTTP 验收。
|
||
- `edge / ingress / data / egress` 四网络边界已落地；Web 不可解析数据库，API 与 gateway 无公网 TCP 出口，Web 与 gateway 均不持有 Secret。
|
||
- gateway 与 Nginx 已关闭代理缓冲，自动测试证明两个 SSE 事件保持为独立下游分块，且响应头阶段断连也会释放上游流；真实聊天生成与取消传播仍属于 Stage 5，尚未实现。
|
||
- 唯一未验收项是真实 `text-embedding-v4` / `qwen3-rerank` / `deepseek-v4-flash` smoke 与真实模式 seed。
|
||
|
||
### 提交/推送节点
|
||
|
||
- [x] `S1-A`：数据库初始化、分权角色、迁移和最小 Compose 已随 `f4ba5d5` 验证并推送。
|
||
- [ ] `S1-B`：三模型适配器和 fake 契约测试已随 `f4ba5d5` 推送；新 Key 下的 live smoke 未完成，因此节点保持未完成。
|
||
- [x] `S1-C`：20 条虚构 seed、幂等验证、运行证据和文档已随 `f4ba5d5` 推送。
|
||
- [x] `S1-D`：内部 API、无 Secret gateway、只读 demo 检索和真实 HTTP/Docker 运行证据已随 `cfd6d4c` 验证并推送。
|
||
|
||
`f4ba5d5` 是 Stage 1 离线可执行闭环提交，不代表 Stage 1 已完成；阶段完成仍以真实三模型 smoke 和真实模式 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`
|
||
- **已完成前置：** 不依赖云密钥的 React 离线演示、OpenAPI 类型、Nginx 单入口、四网络隔离和当前质量门禁已验收；这不代表 Stage 2 已启动或完成。
|
||
|
||
### 具体实现任务
|
||
|
||
- [ ] 建立 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` 和管理员模型能力探测端点。
|
||
- [x] 建立 React + TypeScript strict、路由、TanStack Query 和 OpenAPI 客户端生成。
|
||
- [x] 建立 Nginx，仅发布 Web 端口；当前 API、DB 只在内部网络，Worker 落地后必须沿用同一边界。
|
||
- [ ] 建立完整 Compose：`web/api/worker/db/migrate`，OCR profile 默认关闭。
|
||
- [x] 建立当前范围的 Ruff、类型、pytest、ESLint、TypeScript、Vitest 和镜像检查；Stage 2 新模块必须继续纳入门禁。
|
||
- [x] 建立 Gitea CI 的 fake provider 测试；外部 PR 不运行真实 Key 测试。
|
||
|
||
### 验收证据
|
||
|
||
- [ ] 空白机器仅按 README 执行即可启动完整骨架。
|
||
- [ ] migration 只执行一次，失败时 API readiness 不通过。
|
||
- [x] 当前 `docker compose ps` 只暴露 Nginx/Web 回环端口；加入 Worker 后须重新验收。
|
||
- [ ] Docker 重启后数据库数据保留。
|
||
- [ ] 强杀 Worker 后验证可重领、耗尽进入 `FAILED`、旧 token 不能提交。
|
||
- [x] 当前后端 65 项、前端 14 项测试及两端 lint、类型和构建门禁均通过；Stage 2 新功能仍需增量验证。
|
||
|
||
### 提交/推送节点
|
||
|
||
- [ ] `S2-A`：FastAPI、持久化、健康端点和错误契约。
|
||
- [ ] `S2-B`：任务租约、reaper、fencing 和恢复测试。
|
||
- [ ] `S2-C`：React、Nginx、完整 Compose、CI 和文档；其中 React/Nginx/CI 前置已完成，缺 Worker 与完整 Compose 验收，节点不得提前关闭。
|
||
- [ ] 每个节点验证后独立提交并推送；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 的真实供应商门禁；已完成的 React/Nginx 工作仅作为 Stage 2 安全前置保留。建议按以下顺序继续：
|
||
|
||
1. 在百炼控制台撤销聊天中暴露的旧 Key，创建新 Key，并仅通过未提交的 Docker Secret 注入。
|
||
2. 分别运行 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash` 受控 live smoke，记录脱敏 provider profile、能力指纹、维度、流式协议和错误映射。
|
||
3. 用现有 20 条 synthetic 数据运行真实 Embedding/Rerank/Chat 链路和幂等 seed；真实地质资料仍不得出域。
|
||
4. 关闭 S1-B 并把 Stage 1 标记为 `DONE` 后，再实现 Stage 2 的 Worker 租约、fencing、reaper、恢复测试和完整 Compose。
|
||
5. Stage 3 实现数字 PDF/DOCX/TXT/Markdown 的隔离解析、页码/章节恢复、审批状态机、切分、向量化写库和可追溯版本激活。
|
||
6. Stage 4 完成真实向量召回、重排与验证集评测；Stage 5 再实现 grounded chat SSE、取消传播、引用解析和聊天 UI，不把当前代理分块测试误称为聊天功能完成。
|
||
|
||
在 Stage 1 验收之前，不展开真实语料云端入库或正式验证集调参；前端可继续做不接触 Secret、不会绕过阶段门禁的离线可用性修正。
|