docs: plan public knowledge cluster delivery

This commit is contained in:
d-robotics 2026-09-02 19:41:13 +08:00
parent 6f16c971e4
commit f47634e104
12 changed files with 316 additions and 46 deletions

View File

@ -63,6 +63,15 @@ DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个
`/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST
契约;所有业务操作仍调用 `/api/v1`。
## 当前公共知识库部署边界(PLAN-002)
当前阶段所有 Document 属于同一个公共知识可见域,不新增用户、知识库或 ACL 字段,也不把
这些完整未实现能力伪装为默认放行。Admin 写接口只允许部署在企业受控网络或统一接入网关后;
Ingress 是否进一步认证属于部署配置,但前端隐藏按钮或隐藏路由不构成安全控制。
集群重启、扩缩容和滚动部署不得改变本契约或要求浏览器重新注入 Provider 配置。数据库、BOS、
模型与队列凭据由服务端 Secret 提供,任何 API 响应都不得返回这些值。
## Planned async ingestion contract(DEMO-015/016,尚未实现)
| Method | Path | 行为 |

View File

@ -42,3 +42,10 @@ ACL 或用户委托授权。
公开错误边界:缺失/无效 Token 为 HTTP `401`,scope 不足为 `403`;Tool 参数不合法返回 MCP
参数错误;检索运行失败只返回 `knowledge search failed`。Host/Origin allowlist 默认只允许
本机,远程部署必须显式注入公开域名。
## 当前公共知识库部署边界(PLAN-002)
集群阶段仍只暴露只读 `search_knowledge`,并为 WorkBuddy 配置稳定的 HTTPS MCP 地址。
Credential 由 Kubernetes Secret 在服务端运行时注入,客户端只保存管理员分发的最小
`knowledge:search` Token;Pod 重启或滚动升级不得要求重新生成配置。公共知识域不等于匿名
访问或超级管理员身份,未来引入非公共知识前必须升级为用户委托身份与 ACL-aware Search。

View File

@ -25,6 +25,17 @@ canonical Chunk 重建的检索行。共用数据库实例不改变两类数据
`VECTOR_INDEX(... pre_filter)` 产生 `VECTOR INDEX ADAPTIVE SCAN (PRE-FILTER)`;版本下限与
运行检查据此调整为 4.3.5.4。生产升级和重新验收仍由运维流程控制。
## Public knowledge delivery boundary
PLAN-002 将当前交付阶段限定为企业受控网络内的单一公共知识可见域,并加入 Kubernetes/Helm
集群交付任务。这是部署范围和实施顺序调整,不是新的架构选型:继续采用 ADR-002 的模块化
单体 API、独立 Worker 和 MCP Gateway,以及架构既定的 Celery/RabbitMQ;OceanBase/BOS
边界继续遵循 ADR-012。
ADR-007 仍为 Accepted。当前阶段只是延后用户/组/角色和 Document ACL;开始接收任何非公共
知识前,必须先实现 Permission Resolver 和检索前/检索中 ACL 下推。公共知识库也不等于匿名
公网开放,Admin 写操作只允许经受控网络或统一接入网关访问,MCP 使用最小只读服务身份。
The migration retains the Demo's Dense Top20 → Reranker Top5 behavior and current lightweight
Parser scope. Top50 retrieval, distance thresholds, dual-query RRF, Marker/Pandoc and LLM-derived
index content require separate product and evaluation decisions.

View File

@ -202,6 +202,11 @@ Vector/Sparse rows
历史。清理失败时 Job 终止,不能在未知状态继续执行。Job 通过数据库状态、唯一有效 Attempt
和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。
公共知识库集群交付阶段由 Celery/RabbitMQ 作为首个生产执行器。API 只调用队列执行器抽象,
Celery task 只负责恢复应用上下文并调用 Ingestion Application Service;重试分类、Attempt 状态、
清理顺序和业务幂等仍由应用层持有。Broker 消息不是 Job 的 source of truth,Worker 重启或消息
重复投递必须以 OceanBase 中的持久化 Job/Attempt 状态收敛。
---
### 4.3 文档结构与 Chunk
@ -732,6 +737,25 @@ Observability
未来根据负载再拆服务。
### 16.1 当前公共知识库集群交付基线
PLAN-002 将当前交付范围收敛为企业受控网络内的单一公共知识可见域。该范围不重开 ADR-007:
所有现有文档共享同一可见性,因而当前检索不执行事后 ACL 过滤;接收任何非公共知识前,必须
先实现 Permission Resolver 和数据库/向量检索前置过滤。Admin 写接口不得直接暴露到匿名公网,
MCP 使用运行时 Secret 注入的最小 `knowledge:search` 服务身份。
集群中 API/Admin、MCP Gateway 和 Async Worker 分别部署并独立扩缩容,业务核心继续保持模块化
单体。当前 Parser 及云端 Embedding/Reranker 不需要 GPU Worker,因此它不进入最小交付,但角色
边界保留。OceanBase、BOS 和 AI Provider 使用外部服务;RabbitMQ 默认使用外部地址,可为开发/
演示显式启用 Chart 依赖。
Kubernetes/Helm 必须提供:生产镜像、`existingSecret`、串行 Migration Job、Ingress/TLS、
readiness/liveness、资源限制、非 root 与只读根文件系统、多副本和滚动更新。仓库的一键入口只
编排已有集群和外部服务,不创建云账号或把凭据写入 Values、镜像、命令行及日志。现有
`docker-compose.dev.yml` 包含已被 ADR-012 取代的 PostgreSQL/MinIO 假设,只能视为待清理的
本地开发资产,不能作为集群模板。详细依赖和验收见
[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。
---
## 17. V1 验收重点

View File

@ -92,7 +92,7 @@ Demo 阶段优先简单实现,不引入不必要的基础设施。
| Vector DB | OceanBase Vector | 当前默认,通过 `VectorStore` 隔离 SDK,不做多数据库运行时切换 |
| Reranker | `bce-reranker-base` | 延续当前可调用的千帆 Reranker,Demo 中保留 |
| Frontend | 简单 React/Vue 或 FastAPI HTML | 以最小可用为目标 |
| Deployment | 本地 / 单机 Docker | 暂不考虑 K8s |
| Deployment | Kubernetes/Helm | PLAN-002 起面向企业受控网络交付;本地模式仅用于开发测试 |
---
@ -335,7 +335,8 @@ Search Service 或 `/api/v1/search`,用于验证标准 MCP、identity 边界
将现有同步入库流水线放入持久化 Ingestion Job。可重试失败自动执行有界重试;每次重试前
删除旧解析产物、Chunk、索引状态和向量数据,但保留不可变原始文件、Document 和 Attempt
历史。清理失败时终止,不在未知脏状态继续执行。
历史。清理失败时终止,不在未知脏状态继续执行。通过执行器抽象接入 Celery/RabbitMQ,使
API 与 Worker 可独立部署,并以持久化状态处理 Worker 重启和重复消息。
### DEMO-016 批量异步上传
@ -361,12 +362,13 @@ Admin Console 状态展示。批次内文件相互隔离,不包含目录上传
- 多 Embedding Benchmark Platform;
- 多 Vector DB;
- 动态 Provider;
- RabbitMQ / Celery;
- Kubernetes;
- 高可用;
- 灾备;
- 完整 Observability。
用户/权限隔离属于完整 V1 后置能力,不因“公共知识库”而取消;本阶段所有已接收知识共享一个
可见域,且仅部署在企业受控网络或统一接入网关后。RabbitMQ/Celery 与最小 Kubernetes 可用性
已由 PLAN-002 纳入当前交付,跨区域容灾和完整平台级高可用仍不在范围内。
---
## 10. Demo Task 清单
@ -387,12 +389,17 @@ DEMO-014 地瓜机器人品牌化前端优化(用户新增)
DEMO-015 异步入库 Job + 自动重试前清理(用户新增)
DEMO-016 批量异步上传 + 状态展示(用户新增)
ARCH-001~006 Provider 架构迁移与真实验收
PLAN-002 公共知识库集群交付规划(已完成)
DEPLOY-001 API/Admin、MCP Gateway、Async Worker 生产镜像
DEPLOY-002 Kubernetes/Helm 一键部署
DEPLOY-003 可用性、滚动升级和远程 WorkBuddy 验收
```
实施状态(2026-09-02):`DEMO-001~DEMO-010`、用户新增的 `DEMO-014` 与
`ARCH-001~ARCH-006` 均已完成并通过当前 Scope 的闭环验收。`PLAN-001` 已完成现状审计和
任务拆分;`DEMO-012` 已完成,`DEMO-015`、`DEMO-016` 已批准并按顺序实施。`DEMO-011` 和
`DEMO-013` 仍为可选项,不因本状态记录自动进入范围。
任务拆分;`DEMO-012` 已完成。`PLAN-002` 已将公共知识库集群交付纳入范围,后续严格按
`DEMO-015`、`DEMO-016`、`DEPLOY-001~003` 顺序实施。`DEMO-011` 和 `DEMO-013` 仍为
可选项,不因本状态记录自动进入范围。
可选:
@ -404,13 +411,17 @@ DEMO-013 OCR / MinerU
已批准顺序:
```text
DEMO-012 MCP search_knowledge
→ DEMO-015 Async Job + Retry Cleanup
PLAN-002 Public Knowledge Cluster Plan
→ DEMO-015 Celery/RabbitMQ Async Job + Retry Cleanup
→ DEMO-016 Batch Async Upload + UI
→ DEPLOY-001 Production Images
→ DEPLOY-002 Kubernetes/Helm One-click Deploy
→ DEPLOY-003 Availability + Remote Acceptance
```
详细 Task 映射、依赖与验收边界见
[`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`](../plans/ASYNC_INGESTION_MCP_PLAN.md)。
[`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`](../plans/ASYNC_INGESTION_MCP_PLAN.md) 和
[`docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。
---
@ -500,11 +511,13 @@ Demo 阶段不设严格生产指标。
## 14. Codex 开发约束
Codex 当前只能实现 `DEMO-001 ~ DEMO-010`、`DEMO-012`、`DEMO-014 ~ DEMO-016` 和已批准的
`ARCH-001 ~ ARCH-006`。
ARCH 迁移任务不授权实现下列被排除的完整 V1 能力。
Codex 当前只能实现 `DEMO-001 ~ DEMO-010`、`DEMO-012`、`DEMO-014 ~ DEMO-016`、
`ARCH-001 ~ ARCH-006`、`PLAN-001 ~ PLAN-002` 和 `DEPLOY-001 ~ DEPLOY-003`。
PLAN-002 只授权实现 Celery/RabbitMQ 异步执行器与最小 Kubernetes/Helm 集群交付,不授权
拆分额外微服务或扩大业务能力。
除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、微服务、Kubernetes 和企业级 Job Queue。
除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、
额外微服务、跨区域容灾和完整 Observability 平台。
当本文件与完整 PRD 的实现优先级冲突时:
@ -533,10 +546,10 @@ docs/demo/DEMO_SCOPE.md
>
完整 V1 PRD
只允许实现 DEMO-001 ~ DEMO-010 以及本文件明确列出的 ARCH-001 ~ ARCH-006。
Provider 架构迁移任务按顺序完成后,再继续 DEMO-010。
只允许实现本文件明确列出的 Demo、Architecture、Plan 与 Deploy Task,并且一次只执行一个
Task。当前严格顺序为 DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003。
当前 Demo 的目标只有:
当前公共知识库阶段的业务目标保持为:
Upload
→ Parse/Clean
@ -548,6 +561,14 @@ Upload
→ Source Result
→ Search UI
并补齐以下交付能力:
Async Job / Retry Cleanup
→ Batch Async Upload
→ Production Images
→ Kubernetes/Helm One-click Deploy
→ Availability + Remote WorkBuddy Acceptance
不要提前实现:
- ACL
@ -557,9 +578,9 @@ Upload
- Knowledge Compilation
- Multi Vector Store
- Embedding Benchmark Platform
- Celery/RabbitMQ
- Kubernetes
- 企业级高可用
- 额外微服务
- 跨区域容灾
- 完整 Observability 平台
先不要修改代码。
@ -568,7 +589,7 @@ Upload
1. 当前仓库状态;
2. 为完成 Demo 需要保留哪些现有结构;
3. 哪些完整 V1 设计可以暂时不实现;
4. DEMO-001 ~ DEMO-010 与 ARCH-001 ~ ARCH-006 的建议执行顺序;
4. 当前已批准 Task 的执行顺序;
5. 下一步应该实施的第一个 Task。
```
@ -585,6 +606,12 @@ Async Job + Retry Cleanup
↓
Batch Async Upload
↓
Production Images
↓
Kubernetes/Helm One-click Deploy
↓
Availability + Remote WorkBuddy Acceptance
↓
Hybrid Search
↓
OCR / Complex Parsing

View File

@ -10,3 +10,10 @@ 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.
For cluster delivery tasks, completion also requires reproducible production images, Secret-only
sensitive configuration, serialized migration, readiness/liveness probes, resource and pod-security
defaults, idempotent Helm install/upgrade, rolling-restart verification, durable worker recovery, stable
HTTPS Admin/MCP endpoints, and remote WorkBuddy acceptance. Manifests, rendered output, logs and images
must be checked for credential leakage. Public-knowledge delivery does not complete or waive V1
user/ACL tasks.

View File

@ -43,8 +43,13 @@
- 每次重新执行前,按顺序清理该 Document 的向量行、`ChunkIndexState`、Chunk 和解析产物,再从不可变原始文件重新处理;
- 原始文件、Document 标识和审计所需的 Job/Attempt 历史不得被重试清理删除;
- 任一清理步骤失败时禁止启动下一次尝试,并记录为终止失败,避免在未知脏状态上重复执行。
- 通过执行器抽象接入 Celery/RabbitMQ,使 API 和 Worker 可独立部署;业务应用服务不得直接
依赖 Celery API,确保执行器仍可替换;
- Worker 重启、消息重复投递和确认超时必须保持持久化 Job 状态一致,不能产生双重有效
Attempt 或重复派生数据。
该 Task 只完成 Demo 入库所需的 Job/Retry 基线,不扩展到完整审计系统、Compilation、OCR、分布式高可用或通用企业级 Job 平台。
该 Task 只完成公共知识库入库所需的 Job/Retry 与队列基线,不扩展到完整审计系统、
Compilation、OCR、跨区域高可用或通用企业级 Job 平台。
### DEMO-016:批量异步上传与状态展示(新增)
@ -62,19 +67,23 @@
## 3. 实施顺序与依赖
```text
DEMO-009 + ARCH-006
└──→ DEMO-012 MCP search_knowledge
DEMO-009 + ARCH-006 → DEMO-012(已完成)
DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006
└──→ DEMO-015 Async Job + Retry Cleanup
└──→ DEMO-016 Batch Async Upload + UI
PLAN-002(已完成)
└──→ DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006
└──→ DEMO-015 Async Job + Celery/RabbitMQ + Retry Cleanup
└──→ DEMO-016 Batch Async Upload + UI
└──→ DEPLOY-001 → DEPLOY-002 → DEPLOY-003
```
推荐严格按以下顺序执行并逐项闭环:
1. `DEMO-012`
1. `PLAN-002`(已完成)
2. `DEMO-015`
3. `DEMO-016`
4. `DEPLOY-001`
5. `DEPLOY-002`
6. `DEPLOY-003`
MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不会阻塞后续批量上传。`DEMO-016` 必须等待 `DEMO-015`,否则会把同步流水线简单并发放大,缺少可靠的状态、隔离和恢复边界。
@ -94,6 +103,7 @@ MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不
- 第二次尝试开始前,旧解析产物、Chunk、索引状态和向量均已清理,原始源文件仍存在;
- 永久错误不重试,达到次数上限后稳定进入 `failed`;
- 并发或重复投递不会产生双重有效执行和重复派生数据。
- RabbitMQ 消息确认超时或 Worker 重启后,Job 可恢复到终态且不会重复生成派生数据。
### DEMO-016
@ -104,6 +114,10 @@ MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不
## 5. 非目标与 ADR 影响
- 不把 RabbitMQ/Celery、Kubernetes、高可用或完整 Observability 纳入上述 Demo Task;具体执行器继续通过接口隔离,后续 V1 可替换。
- PLAN-002 已把 Celery/RabbitMQ 纳入 `DEMO-015`,并以独立 `DEPLOY-*` Task 纳入最小
Kubernetes、多副本和滚动升级能力;跨区域容灾、自动云资源编排和完整 Observability
仍为非目标。
- 不改变 OceanBase/BOS canonical、向量索引可重建、原始文档不可变、Provider 抽象和 MCP 隐藏基础设施等 Accepted ADR。
- 本次只是任务拆分、优先级和契约澄清,不需要新增或重开 Accepted ADR。
- 公共知识库只是阶段性单一可见域;ADR-007 保持 Accepted,用户/ACL 实现后置且不得用全局
Top-K 后过滤替代。
- 本次任务拆分和交付边界不需要新增或重开 Accepted ADR。

View File

@ -1,13 +1,12 @@
# 项目进度
当前阶段:Retrieval Demo 与品牌界面闭环完成
当前阶段:公共知识库集群交付规划完成,准备实施异步入库
已完成:DEMO-001~DEMO-010、DEMO-014、ARCH-001~ARCH-006
已完成:DEMO-001~DEMO-010、DEMO-012、DEMO-014、ARCH-001~ARCH-006、PLAN-001~PLAN-002
进行中:无
阻塞:无
下一任务:无。`docs/demo/DEMO_SCOPE.md` 当前批准的必做任务和 DEMO-014 已经完成;可选
DEMO-011~013 或 V1 backlog 需在明确选定新 Task 后再开始。
下一任务:`DEMO-015`。随后严格执行 `DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003`。
Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → ARCH-005 → ARCH-006`
执行并已完成。DEMO-010 在迁移闭环验收后实施,未扩大为完整 V1 Admin Console。
@ -314,3 +313,22 @@ Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → AR
`DEMO-012` 约定的 WorkBuddy 客户端验收项闭环;公网 HTTPS 部署验证属于部署环境验收,
不阻塞本地 Demo Task 完成。
- 下一任务:`DEMO-015`。
### PLAN-002(已完成)
- 将当前交付目标明确为企业受控网络内的单一公共知识库:本阶段所有知识共享一个可见域,
暂缓用户、角色、知识库空间和 Document ACL,但不废弃 ADR-007,也不把未实现项标记完成。
- 保持 Accepted ADR 的模块化单体边界,确定 API/Admin、MCP Gateway 和 Async Worker 独立
部署;OceanBase/BOS/AI Provider 使用外部服务,当前云端模型链路不启用 GPU Worker。
- 将 Celery/RabbitMQ 正式并入 `DEMO-015`,并新增 `DEPLOY-001~003`,严格顺序为
`DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003`。
- 定义 `make deploy VALUES=...` 的一键部署边界:操作者预先提供集群访问与 Secret,仓库负责
生产镜像、串行 Migration、Helm 安装/升级、Ingress/TLS、探针、资源与 Pod 安全配置;不得
将凭据写入 Git、镜像、命令行或日志。
- 明确现有 `docker-compose.dev.yml` 的 PostgreSQL/MinIO 假设已被 ADR-012 取代,不作为集群
交付模板;新增 `docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md` 作为任务范围和验收基线。
- 本任务仅修改规划、产品、架构、API/MCP 契约、Demo Scope 和 DoD 文档,没有修改业务代码、
数据库 Migration 或 Accepted ADR 状态。
- 验证结果:Markdown 相对链接、敏感值模式和 Git diff 检查通过;Ruff Format/Lint、Mypy、
Alembic Head/离线升级通过;Unit + Integration `165 passed`,RAG Evaluation `5 passed`。
- 下一任务:`DEMO-015`。

View File

@ -0,0 +1,120 @@
# 公共知识库集群交付计划
**Task:** PLAN-002
**Status:** Accepted planning baseline
**Date:** 2026-09-02
## 1. 阶段目标与边界
当前阶段只交付一个面向企业内部受控网络的公共知识库,先保证服务持续可用、可重复部署,
并让使用者打开 Admin Console 或连接 WorkBuddy 后即可使用,无需感知后端进程启停。
“公共”表示本阶段所有已接收知识处于同一个可见域,不代表面向公网匿名开放,也不代表
ADR-007 被废弃。用户、用户组、角色、知识库多空间、Document ACL、SSO、OAuth 用户委托等
完整 V1 能力继续后置;一旦需要接收非公共知识,必须先实现 Permission Resolver 和检索前/
检索中 ACL 下推,禁止先做全局 Top-K 再过滤。
Admin 写操作只部署在企业受控网络或统一接入网关后。MCP 继续使用运行时注入、只具备
`knowledge:search` scope 的服务凭据;静态 Demo credential 不得演变为共享超级管理员 Token。
## 2. 目标部署拓扑
```text
Ingress / TLS
│
┌──────────────┴──────────────┐
│ │
Admin Console + Knowledge API MCP Gateway
replicas replicas
│ │
└──────── Application Services ────────┐
│
┌─────────────────────────────┼─────────────┐
│ │ │
OceanBase MySQL BOS RabbitMQ
canonical + vector │
▼
Async Worker(s)
```
沿用 ADR-002:业务核心仍为模块化单体,不拆分额外微服务;API、MCP Gateway 和异步 Worker
分别作为可独立扩缩容的进程/容器交付。当前 Parser 与云端 Embedding/Reranker 不需要本地 GPU,
因此 GPU Worker 不进入本轮最小部署,未来引入本地 OCR/模型时再按既有架构角色启用。
OceanBase、BOS 和模型服务使用集群外已有服务。RabbitMQ 默认使用外部地址;Helm Chart 可以
提供显式开关安装开发/演示依赖,但生产值不得把队列数据生命周期绑定到应用 Pod。
## 3. “一键部署”的定义
在操作者已具备 Kubernetes 访问权限、目标 Namespace 和 Secret 的前提下,仓库提供单一入口:
```text
make deploy VALUES=<environment-values.yaml>
```
该入口负责:
- 校验非敏感配置和 `existingSecret` 引用,不把凭据写入 Git、镜像、命令行或日志;
- 运行一次性、可追踪且串行的数据库 Migration Job;
- 安装或升级 API/Admin、MCP Gateway、Async Worker、Service 和可选 RabbitMQ 依赖;
- 配置 Ingress/TLS、资源 requests/limits、非 root、只读根文件系统和最小 ServiceAccount;
- 配置 readiness/liveness probe、副本数和滚动升级策略;
- 支持重复执行和幂等升级,并提供对应卸载/回滚说明。
本定义不承诺自动创建 OceanBase、BOS、域名证书或云厂商账号,也不允许在仓库内保存这些
资源的敏感凭据。
## 4. Task 顺序与依赖
```text
PLAN-002
└──→ DEMO-015 Celery/RabbitMQ Async Job + Retry Cleanup
└──→ DEMO-016 Batch Async Upload + Status UI
└──→ DEPLOY-001 Production Images
└──→ DEPLOY-002 Kubernetes/Helm One-click Deploy
└──→ DEPLOY-003 Availability + Remote Acceptance
```
### DEMO-015
实现持久化 Job/Attempt、重试前清理、幂等消费和有界自动重试,并把执行器正式接入
Celery/RabbitMQ。队列调用保持在抽象边界后,不允许业务服务直接依赖 Celery API。
### DEMO-016
基于 DEMO-015 提供逐文件隔离的批量异步提交、批次/Job 查询和 Admin Console 状态展示。
### DEPLOY-001
交付 API/Admin、MCP Gateway、Async Worker 的生产容器镜像与启动约定;镜像使用固定依赖、
非 root 用户、健康检查和多架构可构建基线,不内置凭据。
### DEPLOY-002
交付 Kubernetes/Helm Chart、环境 Values Schema、`existingSecret`、Migration Job、Ingress/TLS、
Pod 安全、资源限制、探针和 `make deploy` 入口。现有 `docker-compose.dev.yml` 仍仅作为旧的
本地开发文件,因其 PostgreSQL/MinIO 假设与 ADR-012 不一致,不得作为集群交付模板。
### DEPLOY-003
在目标集群完成安装、幂等升级、滚动重启、Worker 故障恢复和远程 WorkBuddy 验收;形成运行
手册、备份/恢复责任边界和最小日志/指标检查。灾备演练与完整 Observability 平台仍属后置项。
## 5. 最小验收标准
- 新 Namespace 可由单一命令完成安装,重复执行不会破坏已有数据;
- Migration 在应用升级前串行成功,失败时新版本不继续接管流量;
- Admin/API 与 MCP 使用稳定 HTTPS 地址,重启或滚动升级不要求最终用户重新注入配置;
- API/MCP 支持至少两个副本,readiness 未通过的 Pod 不接收流量;
- Worker 重启后持久化 Job 可继续恢复,重复消息不产生双重有效执行或重复派生数据;
- 远程 WorkBuddy 仅发现批准的 `search_knowledge` Tool,并完成一次真实检索;
- 清单、镜像、日志和验收产物不包含凭据,敏感值均来自 Secret;
- 关键请求、Job 和外部依赖失败具备可定位的结构化日志和最小指标。
## 6. 明确后置能力
- 用户、用户组、角色、多租户、知识库空间隔离和 Document ACL;
- LDAP/SSO、OAuth 用户委托、公共互联网匿名访问;
- GPU Worker、本地模型、OCR/MinerU;
- 跨区域容灾、自动云资源编排和完整 Observability 平台;
- 未被既有 Demo/V1 明确批准的业务能力。

View File

@ -27,17 +27,24 @@ validation. Provider credentials and internal endpoints are runtime inputs and n
- [x] PLAN-001 MCP 与异步批量入库现状审计、任务拆分和契约基线
- [x] DEMO-012 MCP `search_knowledge` Gateway + identity + WorkBuddy verification
- [ ] DEMO-015 Async ingestion Job + bounded automatic retry + pre-retry cleanup
- [x] PLAN-002 公共知识库集群交付范围、任务拆分和一键部署基线
- [ ] DEMO-015 Async ingestion Job + Celery/RabbitMQ + bounded retry + pre-retry cleanup
- [ ] DEMO-016 Batch async upload API + per-file Job status + Admin Console
- [ ] DEPLOY-001 Production images for API/Admin, MCP Gateway and Async Worker
- [ ] DEPLOY-002 Kubernetes/Helm one-click deployment + Secret/Migration/Ingress baseline
- [ ] DEPLOY-003 Availability, rolling upgrade and remote WorkBuddy acceptance
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.
[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md) and
[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md). These Demo/Deploy tasks are
vertical slices of the V1 backlog below; completing a slice does not automatically complete its
corresponding `EKP-*` task. The current public-knowledge phase defers, but does not complete or
supersede, the unchecked user/ACL tasks.
```text
DEMO-009 + ARCH-006 → DEMO-012
DEMO-003~006 → DEMO-015 → DEMO-016
PLAN-002
└→ DEMO-003~006 → DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003
```
## Phase 0

View File

@ -12,12 +12,23 @@
## 当前增量实施顺序(2026-09-02)
在不扩大 V1 范围的前提下,当前先按 Demo 垂直切片补齐已确认的高优先级能力:
`DEMO-012` 已完成 MCP `search_knowledge` 与本地 WorkBuddy 验收。根据 PLAN-002,当前阶段按
“单一公共知识可见域、企业受控网络、持续可用和一键集群部署”推进,不提前实现用户/权限隔离:
1. `DEMO-012`:MCP `search_knowledge`、identity 边界和 WorkBuddy 验证;
2. `DEMO-015`:异步入库 Job、自动重试和重试前派生数据清理;
3. `DEMO-016`:批量异步上传、批次/Job 查询和 Admin Console 状态展示。
1. `PLAN-002`:确定公共知识库交付边界、目标拓扑、Task 拆分与验收门槛;
2. `DEMO-015`:持久化异步 Job、Celery/RabbitMQ 执行器、自动重试和重试前清理;
3. `DEMO-016`:批量异步上传、批次/Job 查询和 Admin Console 状态展示;
4. `DEPLOY-001`:API/Admin、MCP Gateway、Async Worker 生产镜像;
5. `DEPLOY-002`:Kubernetes/Helm、Secret、Migration、Ingress/TLS 和一键部署入口;
6. `DEPLOY-003`:多副本可用性、滚动升级、Worker 恢复和远程 WorkBuddy 验收。
`DEMO-012` 复用已经完成的 Search Service,可独立先行。`DEMO-016` 依赖 `DEMO-015`,不得在
缺少持久化状态、幂等执行和恢复边界时直接并发调用当前同步流水线。详细范围和验收标准见
[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md)。
严格依赖为:
```text
PLAN-002 → DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003
```
`DEMO-016` 不得在缺少持久化状态、幂等消费和恢复边界时直接并发调用同步流水线;集群交付也
不得继续使用 `docker-compose.dev.yml` 中已被 ADR-012 取代的 PostgreSQL/MinIO 假设。详细
范围和验收标准见 [`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md) 与
[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。

View File

@ -10,6 +10,21 @@
---
## 当前阶段交付覆盖(PLAN-002)
为优先达成服务可用和一键集群部署,当前阶段只交付企业受控网络内的单一公共知识库:所有
已接收知识处于同一个可见域,用户打开 Admin Console 或连接 WorkBuddy 即可使用,无需感知
后端进程启停。用户、用户组、角色、知识库多空间、Document ACL、LDAP/SSO 和 OAuth 用户
委托仍是本 PRD 的后续 V1 要求,本阶段不实现,也不得标记为完成。
该阶段覆盖不会取代安全原则:公共知识库不等于匿名公网开放;Admin 写操作必须位于受控网络
或统一接入网关后,MCP 使用运行时注入的最小 `knowledge:search` 服务凭据。一旦平台需要接收
非公共知识,必须先完成 Permission Resolver 与检索前/检索中 ACL 下推,禁止全局 Top-K 后置
过滤。实施顺序和集群验收边界见
[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。
---
# 1. 项目背景
企业内部存在大量分散于 PDF、Word、PPT、Excel、Markdown、图片、扫描件及其他文件中的知识资产。