Files
knowledge-governance/docs/library-acceptance-matrix.md
T
姚章浩 bc49b85b56
build / build (push) Successful in 1m12s
docs(acceptance): 封存闭环进"已完成",补死信最小外部契约
- 矩阵:新增 S06/S06-a/S06-b/V03-c/Neo4j 拒绝行(都有真跑证据);把"封存入口未接线"、
  "CLI 库级窗口"从缺口里移走;排空时序旧结论保留但标注被确定性做法取代。
- 死信解除仍缺产品路径,写出最小外部治理契约(保留原始行、审计、验证真实处理成功后
  按精确项解除、未解除继续阻断)。
- 台账补 0.1.169–0.1.180 的 SHA 与 run(含 211/215 failure、218 cancelled,不涂改)。
- library-capture / 8088 部署方案同步成本轮真实结果。
2026-10-29 06:34:05 +08:00

88 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 整库同步验收矩阵(真实证据对照,2026-10-29 重排)
本文件是**唯一口径**:状态只写实际发生的事,四类严格分开,不用"部分通过"含糊过去。
| 口径 | 含义 |
| --- | --- |
| **已完成·已验证** | 有代码 + 真实服务(真实 PG/ES/对象存储/原版 WeKnora API)跑出来的证据,或既有 CI 检查覆盖 |
| **缺代码** | 功能/契约本身没有实现;界面按"未接入"显示,不冒充 |
| **已实现·未跑** | 代码与测试在位,缺真实环境执行证据(不是权限问题) |
| **需授权/需环境** | 实现所需的动作属于生产写入/读取/恢复,或需要本会话拿不到的资源 |
A06(内容、问答、引用图片效果、性能报告)已由用户取消,不作为门槛,也不在本表。
---
## 一、已完成·已验证
| ID | 要点 | 承载位置 | 证据(本轮或前轮,均可回看) |
| --- | --- | --- | --- |
| V01 | 只有对内/对外两个目标,身份来自配置映射 | `internal/httpapi/library_*.go`;`web/src/ReleaseTargets.tsx` | overview 对非法 scope 返回 400;真实归档 internal/external 各自解析到唯一 KB |
| V02 | 解析/索引/Wiki 就绪,验收绑定本版 | `v071/library_source_settlement.go` | 结清检查在封存前执行、缺项阻断;页面注明依据哪次快照 |
| V04 | 完整固定版本:文档+处理结果+资源+索引+完整 Wiki | `internal/librarysnapshot/*` | 真实快照 f992d64e…:4 文档/38 分块/122 索引/21 资源/31 Wiki 页/55,309,044 字节,部件摘要逐项校验 |
| V06 | 只同步知识数据,不含账号/会话/凭据 | 导出白名单(10 知识表 + 知识域索引 + 资源 + Wiki) | 部件清单无 users/sessions/api_keys |
| B01 | 每次生产写入前完整预备份,失败零写入 | `v071.ProductionBackupStore.Prepare` + prebackup 阶段 | 真实 PG/ES 上预备份 3111e823…;故障注入后用它恢复并校验 |
| B03 | 每版保存完整 Wiki 与引用关联并校验 | `library_snapshot` wiki 部件 + 摘要 | 真实快照 31 页逐页摘要;manifest 记录数量/字节 |
| S01 | 数据库/资源/索引/Wiki 真实落地并校验 | `v071.ProductionLibraryTarget.Apply/Verify` | 本轮 sync `libsync-internal-…1793221776816380302`:database 67 行、resources 21、index 122、**wiki 63 行**全部 succeeded + verify succeeded;目标库 wiki 31 页 |
| S02 | 生产不再解析/Embedding/生成 Wiki | index 阶段直接搬运归档 embedding | 真实 ES 写入归档 embedding,未调用模型 |
| S04 | 各阶段失败/超时/重启可追溯可恢复 | `library_jobs`/`library_job_stages` + `ReconcileLibraryJobs` | 阶段与错误持久化;worker 清理"队列无对应作业"的孤儿 |
| S05 | 幂等与互斥(多 worker 安全) | 幂等表 + active 唯一索引 | 真实 PG:同目标第二作业被拒;同键同 digest 复用;换 digest 冲突 |
| R01 | 按指定版本手工恢复 | `POST /library/restores` + `library.restore` | 真实跑通:撤旧授权→503;签发 restore 授权→202→succeeded,内容回到目标版本(`evidence/B_restore.json`) |
| R02 | 恢复失败显式异常、不回退测试库 | `Outcome.State=rollback_failed` + 独立阶段 | 隔离测试 + 前轮真半写场景(`partial.json`) |
| P01 | 作业阶段与整体状态 | `library_jobs.state/stage`;页面阶段条 | 阶段勾选只认当前作业证据;无作业显示"尚未开始" |
| P02 | 四类分项计数/字节/错误 | `stageSizesFrom(manifest)` + `library_job_stages` | 真实数据:database 67/88086B、resources 21/53490166B、index 122/1624880B、wiki 63/105912B |
| P03 | 同步明细与异常 | 页面"同步明细"读阶段行 | 行来自持久阶段,刷新/重启可复现 |
| U01 | 发布管理为主要入口(两库+单作业区) | `web/src/ReleaseTargets.tsx` | 按确认稿布局,父会话已在登录浏览器核验 |
| U02 | 权限边界 | `canWrite`/`canCapture`,写操作需 engineer+ | 无权限不给封存入口;未接线显示通道状态 |
| U03 | 操作确认 | 封存按钮 + 作业号 + notice | 同一作业号重放返回已存作业并提示 |
| D01 | 保留策略(数量/天数) | `internal/libraryretention` | 未设置=0 按"全部保留",不编默认值 |
| D02 | 占用测量 | `internal/librarysnapshot/usage.go` | 版本数/去重内容/blob/未引用/清单;两份真实清单 55,309,693 字节 |
| D03 | 依赖保护 | `libraryretention.Build` 的 Protected/ProtectedBy | 真实归档两版均因"最近测试封存"受保护 |
| D04 | 清理预览 | `Build` 的 Candidates/ReclaimPreviewBytes | keep=1 时仍 0 候选;回收预览只计独占字节 |
| D05 | 容量门禁 | `CheckCapacity` + sync gate | 预算未设置→阻断;超预算→阻断并给预计字节 |
| D06 | 测试残留口径 | 未引用 blob 统计 | 真实归档未引用 blob 为 0(口径,不等于扫过全部残留) |
| **S03** | 实例级维护窗口:关入口→排空→静默证明→停写者→写入→校验→开入口 | `internal/libraryfreeze` + `librarymaintenance` + 迁移 070–072 | 前轮 7 场景真跑全绿(normal/kill/applyfail/partial/crossscope/recover_refuse/recover_ok),本轮 sync/drain 场景继续复用;`quiesce` 证据、`post_stop_*`、journal、gate drain.json 均可回看 |
| **V03-a** | 撤销一份共享贡献后,保留另一份贡献、清除撤销方独有正文/引用/实体边、目录正确 | 由 WeKnora 源侧执行(`cleanupWikiOnKnowledgeDelete` + `EnqueueWikiRetract`),治理侧只比对/搬运 | **本轮真实验收**:kgmaint 隔离实例、原版 API 顺序入库两篇文档 → `entity/fa-bu-zha-men` 同页双来源(2097 字节)→ 真实 `DELETE /api/v1/knowledge/{id}` → 页面保留、来源只剩保留文档、A 独有正文(ZEBRA-A-7731/9910)清除、B 贡献仍在、引用 2→1 且只剩 B 的分块、目录不变、A 独有页面/摘要整页删除、索引页不再列出、实体边无死链。13/13 检查通过。证据:`kg-candidate-e2e/evidence-wiki-final/s8-final-checks-r1.json` + `06-wiki-*-r1.json` + `s3/s6-db-*.json` |
| **V03-b** | 治理侧能把上述语义变化说清楚(不是页面级"无变化") | `internal/librarydiff/wiki.go` `CompareWiki`;`GET /library/overview` 的 `diff.wiki` | 逐页比对正文/来源/引用/出入边/目录,输出 `sources_removed`、`citations_before→after`、`changed`;单测 `wiki_test.go`、视图单测 `library_wiki_diff_test.go`;页面逐行展示(`wikiContributionLines` + 测试) |
| **S06** | 页面/API 发起封存 → 主机 agent → 实例级窗口封存(真实冻结) | `POST /library/captures` + `cmd/libraryagent`(0600 socket、固定命令)+ `libraryctl capture`(实例级:闸门/后台静默/指纹) | **本轮真跑**:`POST /api/v1/library/captures`(job `lib-internal-20261029T0614`)202 → worker → agent → CLI → 关闸门排空 → 等后台静默 → 停 `kgmaint-app`(exit=1 但入口已排空,`drain_verified=true`)→ 导出 → 恢复写入者与入口;作业 `libseal-…` succeeded,快照 `1196c518…`。证据 `kg-capture-loop/evidence/04-inflight-capture.json`、journal `freeze-kgmaint/lib-internal-20261029T0614.json` |
| **S06-a** | 排空证明取自真实在途请求(不靠 202 后抢时序) | 闸门 `drain.json` + 客户端真实上传握手 | **本轮真跑**:先发一半 multipart 正文 → 闸门日志 `conn:open active=1` → 再发起封存 → 入口关闭(拒绝新连接)→ 补完正文,应用 200 并完成解析/嵌入 → `drain.json phase=drained active_at_close=1 served=126 drain_ms=302`;窗口 `quiesce.samples=18 stable_ms=1617` 且停写者后指纹不变。同一次窗口里派生任务真的跑完(探针文档 `de475a32…` completed / 10 分块) |
| **V03-c** | 带"撤销后共享页"的整库封存 → 独立目标同步 → 恢复,逐项真实读回 | `libraryctl` 封存 + `ProductionLibraryTarget` + `libraryrelease` | **本轮真跑**:源 kgmaint 撤销后 KB `e64e82b5`(9 Wiki 页、1 文档、2 分块、1 资源)→ 快照 `1196c518…` 与源逐页比对全部一致(正文 md5/来源/引用/目录/18 条边)→ 同步到**独立实例** kgseal(自己的 PG/索引/桶,非同一份存储)`libsync-internal-1793226278273693890` succeeded+verify succeeded → 目标逐页/索引/资源字节一致(`07-target-compare.json`,`ok=true`,目标桶对象 sha256 与源一致)→ 人为偏离(删整库 Wiki 页)→ `librestore-internal-1793226571284097366-retry` succeeded → 目标回到与快照逐项一致(同一份 `07-target-compare.json` 摘要,`ok=true`) |
| **S06-b** | 主机侧封存/恢复必须与 worker 讲同一份维护声明 | `internal/librarymaintenance/env.go`(`LIBRARY_TARGET_*` 唯一解析处) | 缺项时 `capture` 在开窗口前拒绝并点名;agent 启动打印维护目标;单测 5 项(逐项缺失/空白/口令空格/队列库号) |
| **Neo4j 启用场景** | 启用图谱的库必须被真实拒绝 | `v071/library_export.go` 读 `indexing_strategy.graph_enabled` | **本轮真跑**:在 kgmaint 建 `graph_enabled=true` 的真实 KB `8de41ca7…`,用真实 CLI 预检 → 退出码 1、`LIBRARYCTL_FAILED: Neo4j graph snapshot is not supported`(`evidence/10-neo4j-refuse.txt`)。不是 skip |
| **U04** | 维护级别/进度/恢复错误真实呈现 | `MaintenanceCard`(`web/src/ReleaseTargets.tsx`)、`/api/v1/library/maintenance` | 显示实例级/库级、持有 scope+作业、阶段、入口开/关、服务、开始/释放、进度(阶段名中文化)、恢复错误与处理记录;仅"窗口仍持有且作业失败"时给"按预备份恢复";无记录时"未接入 + fail closed"。组件测试 6 项 |
## 二、缺代码
| ID | 缺口 | 现状与影响 |
| --- | --- | --- |
| R03 | 存快/恢复快对比 | 没有测速实现,也未测。不写没有测量的数字 |
| 死信解除契约 | 死信只能靠人工清理,没有"解除/豁免"契约 | WeKnora `task_dead_letters` 无解决标记;导出/封存按"存在即阻断"(`library_source_settlement.go`)。本轮真实验证:早期错误模型配置产生的 2 条 wiki 死信直接阻断整实例结算,清理方式只能是删除行(记录:`deadletters-before-delete.json`,sha256 `dd4d8f08…`)。要变成可运维契约,需要上游给出解决标记或治理侧设计"带证据的解除"——**未实现**。本轮未再新增死信,没有用它绕过任何一项;仍需的最小外部契约见第五节第 5 条 |
## 三、已实现·未跑
| ID | 要点 | 为什么未跑 |
| --- | --- | --- |
| V05 | 导出中源变更则拒绝或隔离 | 预备份导出前后行数静默检查已有(本机验证会拒绝);真实并发写入的隔离演练未做 |
| B02 | 资源在测试侧删除后仍可恢复 | 归档内容寻址已实现;"删测试侧对象再从归档恢复"实测未做 |
| S03-b | 死信/孤儿任务阻断的负向演练(本轮只验证了真实死信阻断) | 真实阻断已发生并记录;系统化的负向矩阵未跑 |
| 排空时序(历史结论) | 旧做法"202 之后抢时序上传"在 1faf513 上重跑 6 次全部 `Broken pipe`(`drain-task-final-1faf513*.json` 保留,不记通过) | 已被 S06-a 的确定性做法取代:先证明请求已被闸门接收,再启动维护。旧证据保留,不覆盖 |
| U05 | 正式 8088 页面验收 | 正式栈仍是 0.1.114,本轮未替换;维护面板/逐页 Wiki 差异只在测试与候选构建里验证过 |
## 四、需授权 / 需环境
| ID | 事项 | 缺什么 |
| --- | --- | --- |
| D07 | 实际回收(真删对象/版本) | 自动清理默认关闭;删除属于真实清理,需单独授权 |
| 远程生产 | 生产写入/恢复/清理 | 用户授权范围只到本机专用验收实例;远程生产一律未执行 |
| 生产目标维护 | 对共享业务栈开维护窗口 | 本轮明确不停 `WKNFull-app`;维护只在 kgmaint 专用实例上跑 |
| 生产封存/同步真实链路 | 需要在生产机部署 `libraryagent` 并接线 | 需要用户批准的部署窗口与凭据录入 |
---
## 五、本轮新增结论(写在这里而不是报告顶部)
1. **Wiki 撤销语义是上游行为,必须用上游 API 验**:顺序入库才产生"两篇共贡献一页"(并行入库会各自抽到不同 slug 生成两页,这是上游已知行为)。撤销后页面保留、贡献按文档摘除,12 项检查全部通过。
2. **治理侧不能只报页面级差异**:撤销共享贡献时页面仍是"更新",页面级计数会显示成"无变化"。已改为逐页语义比对,能指出"来源 -1、引用 2→1、正文变了、出边少了一条"。
3. **封存链路本轮真的打通了,而且不是放松校验**:CLI 改为实例级窗口(闸门 + 后台静默 + 目标指纹),"写者 exit=1"由闸门的 `drained/active_at_close` 证据解释,而不是被忽略;排空证明改成"先在途、再关入口"的确定性顺序,不再靠 202 之后抢时序。
4. **接线后暴露的四个真缺陷(都已修,都有用例)**:`jobs.id` 列宽 36 让封存作业根本投不进去;v0.7.1 的 app 写索引不带 `tenant_id` 导致导出 0 条;全新实例的空索引被当成"索引被改坏";恢复作业 id 带 `.` 被维护窗口拒。另有资源定位符仍写来源桶——同步过去的目标取不到图/附件。
5. **死信解除仍缺产品路径,最小外部契约如下(未实现,不冒充)**:①保留原始死信行与错误证据,不做删除;②解除必须在治理侧留下审计记录(谁、何时、依据哪条证据、绑定哪个实例/库/任务指纹);③只有在"重放该任务并成功、且源侧结清"之后才允许解除,解除记录挂在精确项上(不允许按实例或通配解除);④未解除的死信继续阻断结算与封存。本轮没有新增死信,也没有用它绕过任何门槛。