# 项目进度 当前阶段:Knowledge Retrieval Demo v0.1 已完成:DEMO-001、DEMO-002、DEMO-003、DEMO-004、DEMO-005、DEMO-006、DEMO-007 进行中:无 阻塞:无 下一任务:DEMO-008 完整 V1 待办将在 Demo Scope 完成后继续执行。当前任务顺序以 `docs/demo/DEMO_SCOPE.md` 为准。 ## 任务记录 ### DEMO-001 - 建立 Python 3.12/uv 工具链与依赖锁文件,新增 FastAPI 应用、类型化配置、 健康检查、OpenAPI 地址和可执行的 Make 命令。 - 新增可重复执行的单元测试、集成测试及 Evaluation 种子数据校验。 - 已验证格式、Lint、严格类型检查、测试、依赖锁、API 启动、健康检查响应及 版本化 OpenAPI 输出。 ### DEMO-002 - 新增 canonical Document 元数据、简化的处理状态、SQLAlchemy 数据库/Session 工厂,以及首个只向前执行的 Alembic 迁移。 - 新增与 Provider 无关的 ObjectStorage 接口和本地适配器,支持禁止覆盖、拒绝 不安全路径并清理写入中断产生的半文件。 - 新增模型、数据库、存储、迁移及 Schema Drift 测试;无需连接生产数据库即可 验证 PostgreSQL 方言的迁移 SQL。 ### DEMO-003 - 新增 PDF、DOCX、TXT、MD 单文件上传应用服务,完成文件名、扩展名、媒体类型、 空文件和流式大小限制校验。 - 上传使用 UUID 隔离的不可覆盖 storage key,并将原始文件与 `uploaded` 状态的 Document 元数据关联保存。 - 数据库写入失败时自动回滚并删除已保存文件;新增四类文件、拒绝规则、大小限制 和失败补偿集成测试。 - Parser 触发与公开上传 REST API 分别留在 DEMO-004 和 DEMO-009,不在本任务 提前实现。 ### DEMO-004 - 新增统一的 `ParsedDocument` / `ParsedBlock` 领域模型和 Parser Provider 接口, 使用 PyMuPDF、python-docx 及轻量文本解析器支持 PDF、DOCX、UTF-8 TXT、Markdown。 - PDF 保留一基页码,DOCX/Markdown 保留基础标题层级;基础 Cleaner 统一处理多余 空白、空行、异常换行和空块。 - 新增上传后同步触发解析的应用层编排,将版本化解析 JSON 作为可重建派生文件保存, 并通过数据库迁移增加 `parsed_storage_key` 追踪结果;原始文件保持不可变。 - 解析完成后文档保持 `processing`,等待 DEMO-005/006 完成后续流水线;解析失败记录 `failed` 和有界错误信息,派生结果写库失败时执行文件补偿。 - 新增四类格式、页码/章节、清洗、解析持久化、禁止覆盖和失败状态测试。公开 REST API 仍按计划留在 DEMO-009。 ### DEMO-005 - 新增可注入 `TokenCounter` 的 `structure_v1` Chunk 策略,默认使用 450 tokens 上限和 75 tokens overlap;标题或章节变化形成硬边界,同章节段落优先组合,超长内容按 token 窗口切分。 - 默认轻量计数器按 CJK 字符、标点和保守 ASCII 子词估算 token,避免引入模型运行时; 精确模型 tokenizer 可通过既有接口注入,留待 DEMO-006 与 bge-large-zh 联调。 - 新增 canonical Chunk 元数据与只向前迁移,原子保存确定性 `chunk_id`、文档/文件、 一基页码范围、章节路径、顺序、token 数和策略版本;禁止静默覆盖同策略结果。 - 新增上传 → 解析/清洗 → Chunk 的同步流水线编排。Chunk 完成后仍保持 `processing`, 等待 DEMO-006 Embedding/Mochow;失败时不产生半套 Chunk,并保留原始文件。 - 新增完全合成的 Markdown 测试文档和 Golden Dataset Chunk 回归,覆盖章节追踪、 token 上限、overlap、页码范围、迁移、持久化、重复执行和失败状态。 ### DEMO-006 - 新增与厂商无关的 `EmbeddingProvider` / `VectorStore` 契约及确定性 Fake,业务编排 不依赖 Mochow SDK 数据结构。 - 新增千帆 v2 `bge-large-zh` Adapter,使用 Bearer API Key,支持最多 16 条批量请求, Chunk 同时限制 450 tokens/2000 字符,并严格校验响应顺序、1024 维度和有限数值; 凭证使用 `SecretStr`, 不进入错误消息或提交记录。 - 新增官方 `pymochow` Adapter,支持分批 Upsert 和按 `document_id + index_profile_id` 删除;Mochow 只保存向量与检索元数据,PostgreSQL 继续保存 canonical Chunk 和索引状态。 - 新增版本化 `IndexProfile` 与 `chunk_index_states` 向前迁移,防止模型/Chunk 策略原地 覆盖;所有 Chunk 成功入库后文档才进入 `ready`。 - 新增上传 → 解析/清洗 → Chunk → Embedding → Mochow Upsert 同步编排。Mochow 批次 或 canonical 状态写入失败时按文档/profile 清理可能的半批索引并记录 `failed`。 - 新增 Qianfan、Mochow 映射、配置脱敏、索引状态、失败补偿和 Golden Dataset 全链路 回归测试。真实凭证/网络集成未在默认测试中执行;专用 Mochow 表需按 `docs/development/MOCHOW_SETUP.md` 预创建。 ### DEMO-007 - 新增 `DenseSearchRequest` / `DenseSearchCandidate` 与 `DenseRetrievalService`,完成 Query 清洗、同模型 Embedding、版本化 `index_profile_id` 过滤和默认 Top20 候选召回; 此阶段不加入 Reranker、最终 Source Result 或 REST API。 - `FakeVectorStore` 新增离线精确余弦检索,先按 profile 过滤再排序,并使用稳定的 UUID tie-break,支持无网络的单元/集成/Evaluation 回归。 - `MochowVectorStore` 新增官方 `VectorTopkSearchRequest` 调用,固定检索 `embedding` 字段, 下推 profile 标量过滤,支持可配置 HNSW `ef`,严格校验响应字段、UUID、有限分数和 Top-N 数量,异常不泄露 SDK 请求或凭证。 - 新增 Golden Dataset Dense Retrieval 回归,完整覆盖上传 → 解析/清洗 → Chunk → Embedding/入库 → Query Embedding → Dense Top20,确认两个合成 Query 均召回预期文件和 章节。 - 默认自动化测试不连接真实千帆/Mochow;真实环境仍需按 `docs/development/MOCHOW_SETUP.md` 注入凭证并验证网络、表 Schema 与索引状态。