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

14 KiB
Raw Blame History

整库同步验收矩阵(真实证据对照,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. 死信解除仍缺产品路径,最小外部契约如下(未实现,不冒充):①保留原始死信行与错误证据,不做删除;②解除必须在治理侧留下审计记录(谁、何时、依据哪条证据、绑定哪个实例/库/任务指纹);③只有在"重放该任务并成功、且源侧结清"之后才允许解除,解除记录挂在精确项上(不允许按实例或通配解除);④未解除的死信继续阻断结算与封存。本轮没有新增死信,也没有用它绕过任何门槛。