docs: plan async ingestion and prioritize MCP

This commit is contained in:
d-robotics 2026-09-02 16:00:42 +08:00
parent fe9d85b6da
commit e3b5b4d50f
10 changed files with 311 additions and 8 deletions

View File

@ -11,6 +11,8 @@ Use OpenAPI as executable source of truth once implementation starts. Provider-s
DEMO-009 公开以下最小接口。`docs/demo/DEMO_SCOPE.md` 中的 `/api/*` 逻辑路径按本契约统一
版本化为 `/api/v1/*`。
下表描述当前已实现的同步 Demo 契约;它将在 `DEMO-015` 完成时由后文的异步契约替代。
| Method | Path | 行为 |
|---|---|---|
| `POST` | `/api/v1/documents` | multipart 单文件上传并同步执行完整入库流水线 |
@ -60,3 +62,36 @@ Search 响应:
DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个客户端路由,
`/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST
契约;所有业务操作仍调用 `/api/v1`。
## Planned async ingestion contract(DEMO-015/016,尚未实现)
| Method | Path | 行为 |
|---|---|---|
| `POST` | `/api/v1/documents` | 单文件接收;持久化 Source、Document、Job 后返回 `202` |
| `POST` | `/api/v1/ingestion-batches` | multipart 多文件接收,返回批次及逐文件 Document/Job 标识 |
| `GET` | `/api/v1/ingestion-batches/{batch_id}` | 返回批次汇总和逐文件最新状态 |
| `GET` | `/api/v1/jobs/{job_id}` | 返回阶段、状态、attempt、最大尝试次数和安全错误信息 |
单文件与批量上传都不等待解析、Chunk、Embedding 或索引完成。批量响应示意:
```json
{
"batch_id": "d21f8012-4c4e-4bb4-89af-e11c0f9f470e",
"items": [
{
"filename": "退款政策.md",
"document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752",
"job_id": "7adc4278-1157-4c3d-95a4-6926ad77a04e",
"status": "queued"
}
]
}
```
Job 公开状态为 `queued | running | retrying | succeeded | failed | cancelled`,并通过 `stage`
表示 `parsing | cleaning | chunking | embedding | indexing`。错误字段只返回有界、安全摘要。
批次允许逐文件部分接收/失败,不以一个文件的处理结果回滚其他文件。文件数量、单文件大小和
请求总大小均由服务端配置限制。
自动重试是服务端 Job 行为,不要求客户端再次上传,也不新增公开手动重试接口。每次重试前
清理派生数据但保留原始文件和稳定的 Document ID;达到次数上限或清理失败后进入 `failed`。

View File

@ -9,3 +9,27 @@ P0 business tools:
- `list_knowledge_bases`
Every request maps to a user/service identity and uses the same authorization/application services as REST. Do not expose OceanBase Vector, BOS, model names, parsers or other infrastructure choices.
## Demo priority slice(DEMO-012,尚未实现)
`DEMO-012` 已提升为当前最高实现优先级。首个可运行 Gateway 只注册
`search_knowledge`,其输入与 `/api/v1/search` 对齐:
```json
{
"query": "产品A退款周期是多少?",
"top_k": 5
}
```
输出保留业务来源字段:`document_id`、`filename`、`page`、`section`、`chunk_id`、`content`
和排序分数。Gateway 必须复用现有 Search Service 或正式 REST API,不得复制检索、来源补全
或排序逻辑。
Demo 验证也必须建立 user/service identity 映射边界,禁止使用共享超级管理员 Token。由于
Document ACL 尚未进入 Demo Scope,`DEMO-012` 只能证明身份传递、认证拒绝和业务服务复用,
不能声称完成 V1 ACL 授权闭环。错误响应和日志不得包含 Provider Endpoint、凭据、数据库表名
或模型名。
验收至少覆盖:MCP 工具发现、参数校验、成功检索、无结果、认证失败、安全错误收敛,以及
WorkBuddy Enterprise 的一次端到端调用。其余 P0 tools 继续留在完整 V1 `EKP-071`。

View File

@ -174,6 +174,34 @@ Queued / Parsing / Cleaning / Chunking / Embedding / Indexing / Completed / Fail
- 软删除;
- 来源页码和章节追踪。
### 4.2.1 批量异步提交与失败恢复
API 只负责校验并持久化不可变源文件、Document 和 Ingestion Job,然后返回 `202`。批次是
提交与聚合查询边界,不是跨文件数据库事务;每个文件独立排队、执行和失败。
```text
Batch Request
├─ Source A + Document A + Job A ─→ Worker
├─ Source B + Document B + Job B ─→ Worker
└─ Source C + Document C + Job C ─→ Worker
```
Worker 对可重试错误执行有界退避。重新执行前必须通过独立的派生数据清理服务按以下顺序
恢复干净状态:
```text
Vector/Sparse rows
→ ChunkIndexState
→ Chunks
→ Parsed artifact + parsed_storage_key
→ reset processing state
→ next attempt from immutable source
```
清理服务与 Document 删除语义分离:重试清理保留原始 BOS 对象、Document 和 Job/Attempt
历史。清理失败时 Job 终止,不能在未知状态继续执行。Job 通过数据库状态、唯一有效 Attempt
和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。
---
### 4.3 文档结构与 Chunk
@ -604,6 +632,11 @@ ReindexJob
EvaluationJob
```
当前增量实现先提供单个 `IngestionJob` 编排既有 Parse/Clean/Chunk/Embedding/Indexing 阶段,
保留阶段级状态和 Attempt 历史;以后拆分为独立阶段 Job 时不得改变公开批次/Job 查询契约。
Demo 默认最多 3 次总尝试,只有瞬时 Provider、网络、存储或数据库错误进入自动重试;输入
校验和确定性内容错误直接终止。
GPU 节点优先承担:
- MinerU / OCR;

View File

@ -305,7 +305,7 @@ Search Response 示例:
---
## 8. P1 可选增强
## 8. Demo 后续增强
### DEMO-011 Hybrid Search
@ -323,12 +323,25 @@ Reranker
### DEMO-012 MCP
只实现一个最小 MCP Tool:`search_knowledge`,内部调用 `/api/search`,用于验证 WorkBuddy 接入。
**已批准并提升为下一优先级。** 只实现一个最小 MCP Tool:`search_knowledge`,复用现有
Search Service 或 `/api/v1/search`,用于验证标准 MCP、identity 边界和 WorkBuddy 接入。
不在本 Task 扩展其他 P0 tools 或声称完成尚未实施的 Document ACL。
### DEMO-013 OCR / MinerU
增加扫描 PDF、图片、OCR 和复杂中文 PDF 处理能力。
### DEMO-015 异步入库 Job 与自动重试清理
将现有同步入库流水线放入持久化 Ingestion Job。可重试失败自动执行有界重试;每次重试前
删除旧解析产物、Chunk、索引状态和向量数据,但保留不可变原始文件、Document 和 Attempt
历史。清理失败时终止,不在未知脏状态继续执行。
### DEMO-016 批量异步上传
在 DEMO-015 基础上支持一次提交多个文件、逐文件 Document/Job 状态、批次聚合查询和
Admin Console 状态展示。批次内文件相互隔离,不包含目录上传、压缩包解包或断点续传。
---
## 9. 明确后置能力
@ -369,22 +382,36 @@ DEMO-007 Dense Retrieval
DEMO-008 Reranker + Source Result
DEMO-009 Document/Search REST API
DEMO-010 简单 Admin Console
DEMO-012 MCP search_knowledge(已提升优先级)
DEMO-014 地瓜机器人品牌化前端优化(用户新增)
DEMO-015 异步入库 Job + 自动重试前清理(用户新增)
DEMO-016 批量异步上传 + 状态展示(用户新增)
ARCH-001~006 Provider 架构迁移与真实验收
```
实施状态(2026-09-02):`DEMO-001~DEMO-010`、用户新增的 `DEMO-014` 与
`ARCH-001~ARCH-006` 均已完成并通过当前 Scope 的闭环验收。`DEMO-011~DEMO-013` 仍为
可选项,不因本状态记录自动进入范围。
`ARCH-001~ARCH-006` 均已完成并通过当前 Scope 的闭环验收。`PLAN-001` 已完成现状审计和
任务拆分;`DEMO-012`、`DEMO-015`、`DEMO-016` 已批准,按该顺序实施。`DEMO-011` 和
`DEMO-013` 仍为可选项,不因本状态记录自动进入范围。
可选:
```text
DEMO-011 Hybrid Search
DEMO-012 MCP search_knowledge
DEMO-013 OCR / MinerU
```
已批准顺序:
```text
DEMO-012 MCP search_knowledge
→ DEMO-015 Async Job + Retry Cleanup
→ DEMO-016 Batch Async Upload + UI
```
详细 Task 映射、依赖与验收边界见
[`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`](../plans/ASYNC_INGESTION_MCP_PLAN.md)。
---
## 11. Demo 测试数据
@ -473,7 +500,8 @@ Demo 阶段不设严格生产指标。
## 14. Codex 开发约束
Codex 当前只能实现 `DEMO-001 ~ DEMO-010` 和已批准的 `ARCH-001 ~ ARCH-006`。
Codex 当前只能实现 `DEMO-001 ~ DEMO-010`、`DEMO-012`、`DEMO-014 ~ DEMO-016` 和已批准的
`ARCH-001 ~ ARCH-006`。
ARCH 迁移任务不授权实现下列被排除的完整 V1 能力。
除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、微服务、Kubernetes 和企业级 Job Queue。
@ -551,10 +579,14 @@ Upload
```text
Demo
↓
Hybrid Search
↓
MCP
↓
Async Job + Retry Cleanup
↓
Batch Async Upload
↓
Hybrid Search
↓
OCR / Complex Parsing
↓
Document Version

View File

@ -1,3 +1,12 @@
# Definition of Done
A task is done only when scope is implemented, architecture invariants hold, format/lint/typecheck pass, relevant tests pass, migrations/contracts/docs are updated as needed, no secrets are committed, retrieval changes include RAG regression results, and known limitations are documented.
For asynchronous ingestion or retry tasks, relevant tests must also prove durable Job/Attempt state,
bounded retry classification, idempotent duplicate delivery, cleanup-before-retry, preservation of the
immutable source, and terminal behavior when cleanup fails. Batch ingestion must cover per-file partial
failure and configured limits.
For MCP tasks, contract tests must cover tool discovery, identity propagation, authorization/error
boundaries, REST/application-service parity, infrastructure redaction, and the explicitly targeted MCP
client compatibility check.

View File

@ -0,0 +1,109 @@
# MCP 与异步批量入库优先级方案
**Task:** PLAN-001
**Status:** Accepted planning baseline
**Date:** 2026-09-02
## 1. 现状判断
| 能力 | 当前实现 | 结论 |
|---|---|---|
| 单文件上传 | `POST /api/v1/documents` 接收一个 `file`,并在请求线程内同步完成解析、Chunk、Embedding 和索引 | 已实现,但不满足 V1 异步要求 |
| 批量上传 | API 与 Admin Console 都只支持一个文件 | 未实现 |
| 失败补偿 | 上传元数据失败会删除源对象;解析元数据失败会删除本次解析产物;索引失败会删除当前 Document/Profile 的可能残留向量 | 已有局部补偿,不是自动重试 |
| 自动重试 | 没有持久化 Job、Attempt、调度器、退避策略或自动重新执行入口 | 未实现 |
| 重试前清理 | 影子索引重建能清理目标 Profile 的部分写入;正常上传流水线没有统一清理解析产物、Chunk、索引状态和向量的能力 | 未实现 |
| MCP | 已有 MCP 业务契约和可复用 Search Service/REST API,没有可运行 MCP Gateway 或 WorkBuddy 验证 | 未实现 |
因此,现有失败补偿只能降低一次执行留下半成品的概率,不能满足“失败后自动重新执行,并在重新执行前清理旧数据”。
## 2. Task 归并结论
### DEMO-012:MCP `search_knowledge`(提升为最高优先级)
保留既有 Task ID,不新建重复任务。范围限定为:
- 提供可运行的标准 MCP Gateway;
- 只暴露 `search_knowledge`;
- 复用现有 Search Service 或正式 `/api/v1/search`,不复制检索逻辑;
- 建立 WorkBuddy 所需的 user/service identity 边界,不使用共享超级管理员凭据;
- 完成协议契约、错误收敛、凭据脱敏和 WorkBuddy 兼容性验证。
该 Task 是 `EKP-070`、`EKP-071`、`EKP-072` 的最小垂直切片,不能据此把三个完整 V1 Task 标记为完成。
### DEMO-015:异步入库 Job 与自动重试清理(新增)
从 `EKP-017` 和 `EKP-023` 抽取 Demo 所需的最小基础能力,并复用 DEMO-003~006 的处理服务:
- 新增持久化 Ingestion Job/Attempt,记录阶段、状态、尝试次数、安全错误和时间戳;
- 源文件成功写入 BOS 且 Document 已持久化后立即排队,API 不等待解析和索引;
- 同一 Document 同时最多一个有效执行,任务投递和消费具备幂等保护;
- 对可重试的瞬时错误自动执行有界重试和退避;Demo 默认最多 3 次总尝试,允许通过非敏感配置调整;
- 格式不支持、文件为空、无可提取内容等确定性错误直接失败,不进行无意义重试;
- 每次重新执行前,按顺序清理该 Document 的向量行、`ChunkIndexState`、Chunk 和解析产物,再从不可变原始文件重新处理;
- 原始文件、Document 标识和审计所需的 Job/Attempt 历史不得被重试清理删除;
- 任一清理步骤失败时禁止启动下一次尝试,并记录为终止失败,避免在未知脏状态上重复执行。
该 Task 只完成 Demo 入库所需的 Job/Retry 基线,不扩展到完整审计系统、Compilation、OCR、分布式高可用或通用企业级 Job 平台。
### DEMO-016:批量异步上传与状态展示(新增)
建立在 DEMO-015 之上,不与 Job 基础合并:
- 新增批量上传 API,一次接收多个 Demo 支持类型文件;
- 每个文件独立生成 Document 和 Ingestion Job,单个文件失败不回滚已成功接收的其他文件;
- 返回批次 ID、逐文件 Document ID、Job ID 和接收状态,不等待后台处理完成;
- 提供批次/Job 查询能力,并在 Admin Console 展示逐文件阶段、重试次数和最终结果;
- 文件数量、单文件大小和请求总大小均受可配置限制;
- 不在本 Task 引入目录上传、压缩包解包、断点续传或跨批次去重。
该 Task 对应 `EKP-021` 的批量异步扩展及 `EKP-080`/`EKP-081` 的最小状态 UI 切片,不能据此把完整 V1 Task 标记为完成。
## 3. 实施顺序与依赖
```text
DEMO-009 + ARCH-006
└──→ DEMO-012 MCP search_knowledge
DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006
└──→ DEMO-015 Async Job + Retry Cleanup
└──→ DEMO-016 Batch Async Upload + UI
```
推荐严格按以下顺序执行并逐项闭环:
1. `DEMO-012`
2. `DEMO-015`
3. `DEMO-016`
MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不会阻塞后续批量上传。`DEMO-016` 必须等待 `DEMO-015`,否则会把同步流水线简单并发放大,缺少可靠的状态、隔离和恢复边界。
## 4. 验收边界
### DEMO-012
- MCP Inspector/标准客户端能发现并调用 `search_knowledge`;
- WorkBuddy 使用已映射的 user/service identity 完成一次端到端检索;
- REST 与 MCP 对同一查询复用同一业务逻辑并返回一致的来源字段;
- 响应与日志不泄露 OceanBase、BOS、模型名、Endpoint 或凭据。
### DEMO-015
- 上传接口在源文件和 Job 持久化后返回 `202`,后台完成现有全流水线;
- 注入一次可重试故障后可观察到自动重试,并最终成功;
- 第二次尝试开始前,旧解析产物、Chunk、索引状态和向量均已清理,原始源文件仍存在;
- 永久错误不重试,达到次数上限后稳定进入 `failed`;
- 并发或重复投递不会产生双重有效执行和重复派生数据。
### DEMO-016
- 一次提交多个文件后立即得到逐文件 Document/Job 标识;
- 批次内成功、处理中、重试中和失败状态互不影响且可查询;
- Admin Console 无需刷新即可轮询展示逐文件进度和最终状态;
- 批次边界、大小限制、部分失败和重试清理均有集成测试。
## 5. 非目标与 ADR 影响
- 不把 RabbitMQ/Celery、Kubernetes、高可用或完整 Observability 纳入上述 Demo Task;具体执行器继续通过接口隔离,后续 V1 可替换。
- 不改变 OceanBase/BOS canonical、向量索引可重建、原始文档不可变、Provider 抽象和 MCP 隐藏基础设施等 Accepted ADR。
- 本次只是任务拆分、优先级和契约澄清,不需要新增或重开 Accepted ADR。

View File

@ -267,3 +267,21 @@ Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → AR
- 完整验证结果:Ruff Format/Lint、Mypy、JavaScript 语法与 Git diff 通过;Unit、Integration
和 RAG Evaluation 合计 `155 passed`;Alembic Head 与离线升级通过。本任务不修改 API、
检索算法、Provider 或数据库,不重复调用真实资源验收。
### PLAN-001(已完成)
- 审计确认当前 `/api/v1/documents` 仅接受一个文件,并在请求线程同步执行解析、Chunk、
Embedding 和索引;API 与 Admin Console 均没有批量提交、Job 查询或后台状态轮询。
- 当前上传、解析和向量索引具备阶段内失败补偿,影子索引重建具备目标 Profile 的重试安全
清理,但正常上传流水线没有持久化 Job/Attempt、自动调度退避或统一的重试前派生数据清理,
因而不能视为已实现自动重试。
- 保留既有 `DEMO-012` 并提升为最高优先级;新增 `DEMO-015` 承担 Async Job、自动重试和
重试前清理,新增 `DEMO-016` 承担批量异步上传和逐文件状态 UI。严格执行顺序为
`DEMO-012 → DEMO-015 → DEMO-016`。
- 已更新 PRD、Architecture、API/MCP Contract、Execution Plan、Task List、Demo Scope 与 DoD;
本任务只形成规划和待实现契约,没有修改业务代码、数据库 Migration 或 Accepted ADR。
- 验证结果:Ruff Format/Lint、Mypy、Git diff 与 Alembic Head/离线升级通过;Unit + Integration
`150 passed`,RAG Evaluation `5 passed`。首次受限网络运行因无法解析 PyPI 失败,获准联网
获取已锁定的构建依赖后全套复验通过。
- 下一任务:`DEMO-012`。详细依赖、范围和验收标准见
`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`。

View File

@ -23,6 +23,23 @@ ARCH-001
Each architecture task uses an independent branch and is merged into `main` only after its own
validation. Provider credentials and internal endpoints are runtime inputs and never task artifacts.
## Post-Demo priority plan
- [x] PLAN-001 MCP 与异步批量入库现状审计、任务拆分和契约基线
- [ ] DEMO-012 MCP `search_knowledge` Gateway + identity + WorkBuddy verification
- [ ] DEMO-015 Async ingestion Job + bounded automatic retry + pre-retry cleanup
- [ ] DEMO-016 Batch async upload API + per-file Job status + Admin Console
Dependencies and acceptance boundaries are defined in
[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md). These Demo tasks are vertical slices of
the V1 backlog below; completing a slice does not automatically complete its corresponding `EKP-*`
task.
```text
DEMO-009 + ARCH-006 → DEMO-012
DEMO-003~006 → DEMO-015 → DEMO-016
```
## Phase 0
- [ ] EKP-001 Repository bootstrap
- [ ] EKP-002 Backend Python toolchain

View File

@ -9,3 +9,15 @@
7. Admin Console
8. Knowledge Compilation
9. Evaluation, security and release hardening
## 当前增量实施顺序(2026-09-02)
在不扩大 V1 范围的前提下,当前先按 Demo 垂直切片补齐已确认的高优先级能力:
1. `DEMO-012`:MCP `search_knowledge`、identity 边界和 WorkBuddy 验证;
2. `DEMO-015`:异步入库 Job、自动重试和重试前派生数据清理;
3. `DEMO-016`:批量异步上传、批次/Job 查询和 Admin Console 状态展示。
`DEMO-012` 复用已经完成的 Search Service,可独立先行。`DEMO-016` 依赖 `DEMO-015`,不得在
缺少持久化状态、幂等执行和恢复边界时直接并发调用当前同步流水线。详细范围和验收标准见
[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md)。

View File

@ -447,6 +447,9 @@ V1 必须支持:
Document processing 必须异步执行。
源文件与 Document/Job 成功持久化后返回 `202 Accepted`。批量上传中的每个文件拥有独立的
Document ID 和 Ingestion Job;单个文件处理失败不得阻塞或回滚批次内其他已接收文件。
**REQ-INGEST-004**
展示处理阶段:
@ -468,10 +471,18 @@ Failed
失败必须展示:
- Failed Stage;
- Attempt Count;
- 是否仍会自动重试;
- Error Code;
- Error Message;
- Retry。
**REQ-INGEST-006**
可重试的瞬时执行失败必须自动进行有界重试。每次重新执行前必须清理该 Document 的旧解析
产物、Chunk、Chunk Index State 和向量/稀疏索引数据,再从不可变原始文件开始处理。清理不得
删除原始文件、Document 标识或 Job/Attempt 历史;清理失败时不得继续重试。
---
# 11. 文件版本和去重
@ -1814,6 +1825,9 @@ Cancelled
Retry
```
Retry 必须记录 Attempt 历史并区分可重试的瞬时错误与确定性永久错误;重试执行前遵循
`REQ-INGEST-006` 的派生数据清理规则。
---
# 57. 删除语义