# 项目进度 当前阶段:DEPLOY-003 集群可用性与远程验收进行中 已完成:DEMO-001~DEMO-010、DEMO-012、DEMO-014~DEMO-016、ARCH-001~ARCH-006、PLAN-001~PLAN-002、DEPLOY-001~DEPLOY-002 进行中:DEPLOY-003 阻塞:目标 Kubernetes context、Registry 镜像坐标、DNS/TLS 与远程 WorkBuddy 环境参数未提供 下一门槛:在明确目标集群执行 DEPLOY-003 完整验收;通过前不开始后续任务。 Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → ARCH-005 → ARCH-006` 执行并已完成。DEMO-010 在迁移闭环验收后实施,未扩大为完整 V1 Admin Console。 ## 任务记录 ### 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 与索引状态。 ### DEMO-008 - 新增与厂商无关的 `RerankerProvider` / `RerankResult` 契约及确定性 Fake,使用原始 candidate index 映射精排结果,业务服务不依赖千帆响应结构。 - 新增千帆 v2 Reranker Adapter(初始为 `qwen3-reranker-0.6b`,ARCH-004 已迁移至 `bce-reranker-base`),调用 `/v2/rerank`,严格限制 Query、 documents 和 Top-N,校验响应数量、唯一索引、回显文本、有限分数与降序关系;错误不会 回显请求内容或凭证。 - 新增 `SearchService`,完成 Dense Top20 → Reranker → Top5。Reranker 选中候选后按 `chunk_id` 回查 PostgreSQL canonical Chunk,再生成包含 document、filename、page、 section、chunk、content、Dense score 和 rerank score 的最终 Source Result。 - Source Enrichment 对缺失 Chunk、document_id 不一致和 stale vector content 采用失败 关闭,防止 Mochow 副本与 canonical 来源不一致时返回错误证据。 - 新增 Provider、配置脱敏、排序映射、canonical 回查、一致性失败和 Golden Dataset 全链路回归。默认测试不调用真实千帆;真实联调边界记录在 `docs/development/RERANKER_SETUP.md`。公开 Search REST API 留在 DEMO-009。 ### DEMO-009 - 新增 `/api/v1/documents` 上传/列表、`/api/v1/documents/{document_id}` 详情/直接删除和 `/api/v1/search`,通过 OpenAPI 固化 multipart 上传、Document 状态和最小 Source Result 契约;API 响应不暴露 storage key、Index Profile 或厂商实现。 - 上传接口同步复用 DEMO-003~006 的完整入库流水线,并在完成后回读 PostgreSQL canonical Document,确保返回最终 `ready` 状态和数据库生成时间戳。 - 新增文档查询/删除应用服务。删除覆盖当前及历史已记录 Index Profile 的向量行、 ChunkIndexState、Chunk、Document、解析 JSON 和原始文件;向量清理失败时保留 canonical 数据,来源清理失败返回明确错误并记录 Demo 一致性边界。 - 业务依赖延迟创建,因此健康检查和 OpenAPI 启动不要求云端凭证;Provider 配置不完整时 业务接口返回 `503`,上游异常使用收敛后的错误响应,避免泄露凭证或厂商正文。 - 新增完全离线的 REST 全链路测试,覆盖上传、列表、详情、Dense/Reranker 检索、来源字段、 直接删除、OpenAPI 路径、输入校验、404、Provider 延迟加载及删除失败保护。 ### ARCH-001 - 接受 BOS、OceanBase Vector、千帆 `bge-large-zh` 和 `bce-reranker-base` 作为新的 V1 Provider 基线;PostgreSQL 继续保存 canonical 数据,OceanBase 只保存可重建索引。 - 新增 ADR-009~ADR-011 和独立迁移计划,将 ARCH-002~ARCH-006 的范围、依赖、验收顺序 与安全边界写入任务清单。 - 保留 Demo 的 Dense Top20 → Reranker Top5、现有 Parser/Chunk、API/MCP 业务契约;不随迁移 引入 Top50、RRF、Marker/Pandoc、LLM 派生索引、ACL 或 Hybrid/BM25 扩展。 - 本任务只调整架构和产品文档,不修改运行时代码;旧系统地址、账号和凭据均未写入仓库, 真实验收只允许使用轮换后的 Secret 与受控测试资源。 ### ARCH-002 - 新增官方 `bce-python-sdk` 驱动的 `BosObjectStorage`,保持逻辑 key 与 Bucket/Prefix 分离, 覆盖 Put、流式 Open、HEAD Exists 和 Delete。 - 上传先使用可回卷临时流确定长度,再通过 `If-None-Match: *` 原子拒绝覆盖;404/412 和 其他 SDK 异常映射为不泄露 Endpoint、响应正文或凭据的稳定存储错误。 - 新增 `local|bos` 类型化配置和运行时工厂;BOS AK/SK 使用 `SecretStr`,Bucket、Endpoint、 Prefix 和超时均由环境注入。Local 仍是测试/开发及 ARCH-005 前的默认实现。 - 新增完全离线的 BOS Adapter、配置、Provider wiring 测试和中文配置说明;未使用内部配置 清单中的真实地址或凭据,真实 BOS 联调留在 ARCH-006。 ### ARCH-003 - 新增官方 `pyobvector` 驱动的 `OceanBaseVectorStore`,覆盖批量 Upsert、按 Document/Profile 参数化删除和 Profile 条件下推的 Cosine ANN TopN;SDK 类型不进入业务服务。检索固定使用 OceanBase 4.6 的 `VECTOR_INDEX(... pre_filter)`,不依赖普通 `WHERE` 的自适应过滤,也不做 全局 TopK 后过滤。 - 将低值优先的 `cosine_distance` 转为 `score = 1 - distance`,并对向量维度、有限值、 非零范数、返回字段、UUID、Profile、距离范围和排序执行失败关闭校验。 - 新增 `VECTOR(1024)`、Cosine HNSW、Profile/Document 标量索引的预置 DDL;应用不自动执行 外部索引 DDL,PostgreSQL 继续保存 canonical 数据,OceanBase 表可重建。 - 新增 `mochow|oceanbase` 类型化配置、SecretStr 密码和运行时工厂;Mochow 保持 ARCH-005 前的默认实现。全部 Adapter、配置、Schema 和 wiring 测试均离线运行,真实数据库验收留在 ARCH-006。 ### ARCH-004 - 将千帆 Reranker 运行基线从 `qwen3-reranker-0.6b` 切换为已接受的 `bce-reranker-base`;配置使用受限 Literal,业务 API、Provider 抽象和 Dense Top20 → Reranker Top5 行为保持不变。 - 按千帆 `POST /v2/rerank` 官方约束复核并保留 Query 1600 字符、64 个候选、单文档 4096 字符、Top-N 及响应排序/索引/分数失败关闭校验;真实 API Key 不进入代码和测试。 - 更新 Adapter、环境示例、Provider wiring、配置与请求契约测试;Golden Dataset 继续使用 确定性 Fake 离线评估,但显式绑定 `bce-reranker-base` 当前模型标识。真实 BCE 质量与延迟 统一留在 ARCH-006 使用轮换凭据验收。 ### ARCH-005 - 将正式运行默认值切换为 BOS、OceanBase Vector 和 `bce-reranker-base`,新 Profile ID 为 `demo-bge-large-zh-structure-v1-oceanbase-v1`;Local/Fake 仍用于显式本地和离线测试。 - 新增 PostgreSQL canonical `index_profiles` 迁移与 `shadow / active / retired` 生命周期, 通过局部唯一索引保证至多一个 Active Profile;API 启动时优先解析数据库 Active Profile, 无记录的新部署才使用配置基线。 - 新增 `ekp-index-rebuild build|verify|activate`:从 canonical Chunk 分文档重建,确定性 Upsert, 重试时跳过完整文档并清理目标 Profile 的部分写入;激活前核对全部 ChunkIndexState,并在 PostgreSQL 事务内锁定 Chunk 写入、退役旧 Profile、激活新 Profile。 - 移除 Mochow 运行配置、公开 Adapter、测试、配置文档及 `pymochow` 依赖;不自动删除旧 外部索引,保留受控回滚和运维退役边界。 - 新增重建/重试/完整性失败/单 Active/激活/迁移/CLI 脱敏测试及中文操作文档。真实资源 构建、BOS/OceanBase/Qianfan 连通性和 30~50 条脱敏查询验收仍属于 ARCH-006。 ### ARCH-006(已完成) - Golden Dataset 已扩展为 32 条完全合成 Query,覆盖退款、技术支持、住宿标准和报销材料; Dense、Reranker、canonical Source Result 的离线回归全部通过。 - 新增 `ekp-live-acceptance` / `make live-acceptance`,实际覆盖上传、解析、Chunk、Embedding、 OceanBase Dense Top20、BCE Reranker Top5、canonical 来源核对及本次运行数据清理。 - live 命令强制要求 `APP_ENV=test`、专用 `live-acceptance/` BOS Prefix、凭据授权确认、资源 授权确认和显式运行开关;当前环境下已验证会在创建 Provider 前失败关闭且不泄露细节。 - 根据最新配置清单和 test 环境只读探测,确认没有独立 PostgreSQL;目标为 OceanBase 4.3.5.4 MySQL 模式,同一数据库承载 canonical 关系数据和逻辑隔离的向量表。ADR-012 已 取代先前 PostgreSQL 部署假设,业务事实来源与可重建索引的逻辑边界保持不变。 - 已在目标 test 集群只读验证数据库连通、版本与兼容模式,并通过 `EXPLAIN` 确认 `VECTOR_INDEX(... pre_filter)` 生成 `VECTOR INDEX ADAPTIVE SCAN (PRE-FILTER)`;未读取 业务正文或输出任何连接信息/凭据。 - canonical SQLAlchemy 默认已切换为 `mysql+pymysql`,数据库 URL 使用 `SecretStr`,新增 有界连接池/超时配置;新增 forward-only migration,以生成列唯一索引保证 OceanBase 与 SQLite 下至多一个 Active Profile;PostgreSQL 驱动已移除。 - 配置清单中的 test 凭据仅按用户明确授权临时注入本次验收,不保存为 `.env`、不提交、 不连接 fat/prod;完成后仍记录为待轮换风险。 - 已在 test OceanBase 执行全部 forward-only migration,并对本项目表完成列、类型、默认值、 主键的 scoped schema drift 核对;OceanBase 扩展语法导致标准 MySQL 反射器不能可靠比较的 二级索引/唯一约束/外键,由 SQLite 全量 drift、真实唯一约束事务和 live 级联删除补充验证。创建 `knowledge_chunks_v1` 12 列专用向量表和 Cosine HNSW,确认 PRE-FILTER 执行计划。迁移前 已确认所有目标表均不存在,没有覆盖原有 31 张业务表;事务内双 Active 写入实测被唯一 索引拒绝并完整回滚。 - 已完成 OceanBase canonical → BOS → `bge-large-zh` → OceanBase Vector → `bce-reranker-base` → canonical Source Result 正式验收:32 条查询的 Recall@1/3/5、MRR、 NDCG@5 均为 `1.0`,P50 `3787.61 ms`、P95 `4759.21 ms`,通过 P95 `10000 ms` 门槛。 - 正式命令退出码为 `0`;两份合成文档、canonical Chunk/State、向量行与 BOS 对象均走随机 前缀清理,数据库复核 `live-` Document/Chunk/Vector 残留均为 `0`。首次 live 运行曾出现 一次瞬时失败,分阶段诊断及随后完整 32 查询均成功,仍需在后续稳定性任务关注 Provider 重试、限流和告警。 ### DEMO-010(已完成) - 新增同源轻量 Admin Console,提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个直接可访问页面;FastAPI 只负责静态文件路由,页面业务操作全部复用 `/api/v1`,没有复制上传、文档管理或检索逻辑。 - 上传页支持 PDF、DOCX、TXT、Markdown 文件选择、处理状态和结果摘要;文档页展示文件名、 类型、上传时间、状态,支持详情与确认删除;Search Lab 显式展示 Rank、Filename、Page、 Section、Chunk Content、Dense Score 和 Rerank Score。 - 前端使用安全 DOM 文本节点渲染 API 数据,不注入 HTML,不展示 storage key、Index Profile、 Provider Endpoint 或凭据;只实现 Demo 规定的三个页面,没有引入 ACL/RBAC、任务、审计、 Compiled Knowledge、MCP、Hybrid/BM25 或额外前端构建工具链。 - 新增静态路由、资产、范围和 API First 契约测试;浏览器使用本地确定性 Provider 完成 `README.md` 上传 → Ready → 列表/详情 → Top5 检索,并验证桌面和 390px 移动布局无横向 溢出、无前端警告或错误。删除的 UI 确认和服务端清理语义由现有 REST 全链路测试覆盖。 - 完整验证结果:Ruff Format/Lint、Mypy、JavaScript 语法、Git diff、依赖锁、Alembic Head/ 离线升级均通过;Unit + Integration `150 passed`,RAG Evaluation `5 passed`。本任务没有 修改检索算法或 Provider,不重复调用真实资源验收;ARCH-006 的 32 条真实查询结果继续 作为底层链路基线。 - 已知非阻塞风险保持不变:配置清单中的历史 test 凭据仍应轮换;真实 Provider 瞬时失败的 重试、限流与告警留待后续明确 Task。Demo Console 本身没有新增凭据或生产 Endpoint。 ### DEMO-014(已完成) - 将 DEMO-010 通用绿色界面升级为地瓜机器人品牌化 Admin Console,使用唯一品牌强调色 `#FF3C00`、黑白高对比、无衬线中文排版、低圆角工业组件和与三步操作对应的计算信号轨; 没有增加页面、接口或业务能力。 - 品牌标记由内联 SVG 与 CSS 原生绘制,不下载、复制或热链官网资产。页面没有新增外部 Runtime、字体请求或第三方脚本,继续保持原生 HTML/CSS/JS 和同源 `/api/v1` 调用。 - GitHub 调研确认官方 `openai/skills` 当前没有通用前端设计 Skill;选择并安装了 Apache-2.0 的 `anthropics/skills/skills/frontend-design`。该 Skill 只影响视觉策划和自检方法,不进入 项目运行依赖或仓库产物。 - 浏览器使用本地确定性 Provider 再次完成 README 上传 → Ready → 文档列表 → Top5 检索; 1440px 桌面端和移动端均无根页面横向溢出、无前端警告或错误。复验中发现隐藏表头将移动 页面撑宽至 503px,已改为 `aria-label`,最终根宽度与 463px 视口一致,表格只在容器内滚动。 - 完整验证结果: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`。 ### DEMO-012(已完成) - 新增独立 `ekp-mcp` Streamable HTTP Gateway 和 `make run-mcp` 入口,使用官方 MCP Python SDK v2;默认只监听 `127.0.0.1:8766/mcp`,且只注册 `search_knowledge` 一个业务 Tool。 - Gateway 直接复用现有 `SearchService`,没有复制 Dense Retrieval、Reranker 或 Source Enrichment;结构化输出与 REST 保持相同来源字段,不返回 Index Profile 或 Provider 信息。 - 新增运行时专用 Bearer Token 验证,将凭据映射为显式 client/service identity 和最小 `knowledge:search` scope;Token 至少 32 字符并通过 `SecretStr` 管理,不允许写入仓库。 当前身份层是 Demo 边界,不宣称完成 V1 OAuth、Document ACL 或用户委托授权。 - 启用 Host/Origin allowlist 和请求体限制;缺失/错误认证、scope、参数和检索异常均按安全 边界收敛,响应和日志不回显 Token、内部 Endpoint、数据库、模型或索引实现。 - 新增官方 MCP Client 的协议级测试,覆盖 initialize、tools/list、tools/call、唯一 Tool、 identity 传递、REST 字段一致性、无结果、参数拒绝、认证失败、Origin 防护和错误脱敏; WorkBuddy 的 HTTP + Bearer + 环境变量配置记录于 `docs/development/MCP_SETUP.md`。 - 验证结果:Ruff Format/Lint、Mypy、Git diff、Alembic Head/离线升级全部通过;Unit + Integration `165 passed`,RAG Evaluation `5 passed`。本任务未改变检索算法或数据库结构, 不重复消耗真实 Embedding/OceanBase/Reranker 资源。 - 2026-09-02 补充完成 WorkBuddy 现场验收:本机 WorkBuddy Desktop `5.3.14` 自带的 CodeBuddy CLI `2.115.0` 通过仓库交付的 `deploy/workbuddy-mcp.example.json` 建立 Streamable HTTP + Bearer 连接,健康检查为 `Connected`,仅发现 `mcp__enterprise-knowledge__search_knowledge`,并以 `query` + `top_k=1` 完成真实 Tool 调用、读取结构化来源字段。验收使用真实 Gateway、认证、身份传递、Schema 和 Tool 注册代码,检索应用返回确定性数据,以隔离 WorkBuddy 兼容性与外部 Provider 波动。 - 非交互客户端调用使用仅对当前会话放行 `DeferExecuteTool` 的权限设置,没有持久化放宽权限; 临时客户端配置已删除、Gateway 已停止,仓库和用户配置中均未留下测试 Token。至此 `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`。 ### DEMO-015(已完成) - 新增 OceanBase canonical `ingestion_jobs` / `ingestion_attempts` 与 forward-only migration; Document 唯一 Job、Attempt 编号上限和单一运行中 Attempt 均由数据库约束保护。 - `POST /api/v1/documents` 改为持久化不可变 Source、Document、Job 后返回 `202`,新增 `GET /api/v1/jobs/{job_id}`;活动 Job 的 Document 删除返回 `409`,避免与 Worker 竞态。 - 新增队列无关的 Dispatcher 与 Job Runner,首个适配器使用 Celery/RabbitMQ;消息只包含 Job ID,启用 late ack、worker-lost reject、单任务 prefetch 与周期性持久化 Job 恢复扫描。 - 瞬时错误按配置执行指数退避和最多三次总 Attempt;Worker 租约有效时重复投递不创建新 Attempt,租约过期后关闭旧 Attempt 并恢复。错误记录为固定安全摘要,不保存 Provider 正文。 - 第二次及后续 Attempt 前依次清理向量、ChunkIndexState、Chunk 与 parsed JSON,再从不可变 源文件重建;清理失败直接终止且不创建新 Attempt。Job 创建失败会补偿 Document 与源对象。 - Admin Console 仅将上传提示调整为“已接收并进入队列”;批量选择、Job 轮询和逐文件状态 UI 没有提前实现,继续属于 `DEMO-016`。 - 验证结果:Ruff Format/Lint、Mypy、JavaScript 语法、依赖锁、Alembic Head/离线 MySQL SQL 与 SQLite schema drift 均通过;Unit + Integration `179 passed`,RAG Evaluation `5 passed`; Worker 入口确认注册 `ekp.ingestion.run` 与 `ekp.ingestion.recover`。 - 环境限制:当前工作站没有 Docker/RabbitMQ,也没有持久化注入目标 OceanBase URL,因此未做 真实 Broker 断连/确认超时和目标库 migration;这些真实环境项必须在 DEPLOY-003 集群验收 重跑。本任务以 Celery 配置测试、SQLite 持久化/唯一约束和故障注入集成测试闭环代码语义。 - 下一任务:`DEMO-016`。 ### DEMO-016(已完成) - 新增 canonical `ingestion_batches` / `ingestion_batch_items` 及 forward-only migration,保存 输入顺序、逐文件接收结果与 Document/Job 引用;异步阶段和最终结果仍以 Job 为事实源, 批次不是跨文件事务。 - 新增 `POST /api/v1/ingestion-batches` 与 `GET /api/v1/ingestion-batches/{batch_id}`;批量 请求字段为 `files`,成功返回 `202`、聚合状态和逐文件接收/Job 状态。类型、大小或内容错误 只拒绝当前文件,错误映射为固定安全摘要,其他文件继续接收。 - 新增 `BATCH_MAX_FILES` 与 `BATCH_MAX_TOTAL_BYTES`,复用 `MAX_UPLOAD_BYTES` 约束单文件; 上传流共享总字节预算,不把整批文件读入内存。数量超限在创建批次前返回 `413`。 - Admin Console 支持多选提交,显示当前批次的接收数量、完成数量、逐文件阶段、Attempt 与安全 错误,并每 1.5 秒自动轮询;进入 `completed`、`partial_failure` 或 `failed` 后停止轮询。 DOM 数据继续只通过文本节点渲染。 - 集成测试覆盖顺序稳定、部分拒绝不回滚、数量/单文件/批次总大小、全成功/部分失败聚合、 未知批次、OpenAPI 和前端契约;迁移 drift 增加两张新表。Ruff Format/Lint、Mypy、 JavaScript 语法、依赖锁、Alembic Head/离线升级均通过;Unit + Integration `183 passed`, RAG Evaluation `5 passed`。 - 浏览器验收确认桌面布局和 390px 窄屏布局正常、无根页面横向溢出、无控制台警告或错误; 本地页面不注入云端凭据,批次结果行为由确定性 API 集成测试验证。 - 未扩展目录上传、压缩包解包、断点续传、手动重试、去重、用户或 ACL;自动重试和清理继续 复用 DEMO-015,Accepted ADR 未变更。 - 下一任务:`DEPLOY-001`。 ### DEPLOY-001(已完成) - 新增共享生产 Dockerfile 的 `api`、`mcp`、`worker` 三个 target,使用精确 Python/uv 版本、 frozen production dependencies、固定非 root UID/GID、exec-form 启动命令和逐 target 健康检查。 - 新增 amd64/arm64 Buildx Bake 计划、镜像构建/渲染/推送 Make 入口和 `.dockerignore`;构建上下文 排除凭据、本地状态、缓存、测试与开发产物,镜像不包含环境 Endpoint 或 Secret。 - Admin 静态目录新增类型化运行时覆盖,使非 editable 安装后的 API 镜像仍能提供同源页面; 源码运行继续使用既有默认目录。 - 新增不依赖 Docker daemon 的镜像契约测试与中文运行文档;基础 Python/uv 镜像同时固定精确 tag 与 manifest digest,Registry 地址和本项目发布 digest 继续由部署环境提供。 - 使用 Docker Buildx `0.36.1` + Colima 分别实际构建并加载全部三个 `linux/arm64` 和三个 `linux/amd64` target;最终 digest 固定版本再次构建命中相同业务 layer。没有执行 Registry push,也没有在构建参数、history 或镜像文件系统中发现凭据。 - API 镜像以 `10001:10001` 启动并进入 healthy,`/healthz`、`/admin/upload`、OpenAPI 及 DEMO-016 批量路径 smoke test 通过;MCP/Worker 镜像以同一非 root 用户完成安装入口导入, 默认 CMD 与 HEALTHCHECK 元数据核对通过。真实 Provider/Broker 启动仍属于 DEPLOY-003。 - Ruff Format/Lint、Mypy、Docker Bake 渲染、JavaScript/依赖锁/Alembic 与完整测试门禁通过; Unit + Integration `187 passed`,RAG Evaluation `5 passed`。下一任务:`DEPLOY-002`。 ### DEPLOY-002(已完成) - 新增 `deploy/helm/knowledge-platform` Helm Chart,部署 API/Admin、MCP Gateway、Async Worker、 单实例 Recovery Scheduler、串行 Migration Job、Service、Ingress/TLS 和可选 Demo RabbitMQ; API/MCP 默认各两个副本,Worker 可独立扩缩,Beat 使用 `Recreate` 避免重复调度。 - 新增严格 `values.schema.json` 与仓库外环境 Values 示例,拒绝未知顶层字段、`latest` tag、 非法 digest、API/MCP 单副本和错误类型;跨字段模板校验继续约束批量大小、重试、Chunk 和 Top-K 关系。应用和可选 RabbitMQ 镜像均支持 digest,Demo RabbitMQ 已固定 manifest digest。 - 敏感配置只通过预建 `existingSecret` 注入;ConfigMap 仅渲染显式白名单内的非敏感字段, 没有任意 `extraEnv` 或 Secret 对象。`scripts/deploy.sh` 在部署前校验 Values、Namespace、运行时 Secret/必需键、可选 RabbitMQ Secret/键和启用 Ingress 时的 TLS Secret 引用,不读取 Secret 值;Helm 3/4 分别使用等价的原子失败回滚参数。 - Migration 使用 `pre-install,pre-upgrade` Hook、固定名称和 `before-hook-creation`,安装/升级在 Migration 成功前不更新业务 Pod。应用容器固定非 root UID/GID、只读根文件系统、丢弃全部 capabilities、禁用 ServiceAccount Token,并为临时目录、RabbitMQ 日志和 Beat 状态提供 `emptyDir`;API/MCP/Worker/Scheduler 均配置启动和存活/就绪探针及资源 requests/limits。 - 本机使用 K3s `v1.35.0+k3s1`、Helm `4.2.4` 和 DEPLOY-001 ARM64 镜像完成真实安装;Migration 成功,API/MCP 为 `2/2`,Worker、Scheduler 与可选 RabbitMQ 全部 Ready。首次安装暴露的 RabbitMQ 只读日志目录和 Beat 调度文件权限问题已修复,随后相同 Values 连续升级至 Revision 3~5 均成功;API `/healthz` 和 Admin 上传页 smoke test 通过。 - 默认、环境示例和 RabbitMQ 三种 Helm lint 均通过;含 Ingress/TLS/RabbitMQ 的 14 个最终 资源通过 kubeconform strict 校验。仓库、Helm manifest、Pod 日志三路 Secret 值扫描均为 `0`; Ruff Format/Lint、Mypy、Alembic、Bash 语法与完整门禁通过,Unit + Integration `195 passed`, RAG Evaluation `5 passed`。 - 目标企业集群的稳定 HTTPS、滚动重启、Worker 故障恢复、真实外部依赖监测与远程 WorkBuddy 仍属于 `DEPLOY-003`;本任务没有把这些项提前标记完成,也没有改变 Accepted ADR 或公共知识库 范围。下一任务:`DEPLOY-003`。 ### DEPLOY-003(进行中) - 新增 API/MCP PodDisruptionBudget,继续使用双副本和 `maxUnavailable: 0`,覆盖节点维护与滚动 更新的最小可用性;没有引入新微服务或扩大公共知识库范围。 - 新增字段白名单 JSON 日志、请求相关 ID、API 低基数 `/metrics`,并为上传、批次、检索、MCP、 Worker Attempt/Stage/Retry/Cleanup/Recovery 补充安全事件;异常正文、Query、文件名、Provider Endpoint 和凭据不进入结构化字段。 - 新增显式 context 核对和 `ACCEPTANCE_CONFIRM` 二次确认的集群验收入口;完整模式验证相同 Values 两次升级、HTTPS、PDB、连续滚动探测,并在合成 Job 运行时非优雅删除单个 Worker Pod,等待 canonical 租约与恢复调度器收敛后清理验收文档。 - 新增官方 MCP Client 远程验收脚本;Token 只从进程环境读取,输出只包含 Tool/结果存在性, 不包含 Token 或检索正文。远程 WorkBuddy 仍需在最终用户网络路径现场确认。 - 新增中文集群运行手册和验收记录,明确 OceanBase canonical/BOS、可重建向量、RabbitMQ、TLS、 Registry、日志指标与备份恢复的责任边界。完整 Observability 平台和灾备演练保持后置。 - 仓库侧验证已通过 Ruff Format/Lint、Mypy、Bash 语法、三种 Helm lint、13 个渲染资源的 kubeconform strict、Alembic Head/离线 SQL、Unit + Integration `200 passed` 和 RAG Evaluation `5 passed`;本地运行 API 的 `/healthz`、`/metrics` 与 JSON 事件烟测通过。 - 新生产镜像的首次本地重建被 Docker Hub 匿名授权连接重置阻塞,两次重试结果一致,没有改动 固定 digest 或镜像来源规避;当前机器同时没有目标 Kubernetes context、目标 Registry 坐标、 DNS/TLS 或远程 WorkBuddy 参数。因此现场复选项保持未完成;当前任务分支仅保存并推送仓库侧 阶段性实现,在现场验收闭环前不合并 `main`。