92 Commits

Author	SHA1	Message	Date
姚章浩	c2ab658033	docs: 记录写集合证据被整份覆盖的陷阱 ... 新增 trap 20：复用预备份时重新造一份证据，会让已登记的写集合锚点被整份 抹掉（现场 backup_bytes:0 + writeset_* 全丢）。写明症状、根因、负例优先的 判据与修法，含预备份版本行「一条只属于首次登记的作业」这一归属语义。 AGENTS.md 索引表那一行受写入保护、需主人批准，本次未改（见交接单待批准项）。	2026-10-30 09:14:14 +08:00
姚章浩	c57c22c65e	docs: 记录接管证据陷阱与判据变化 ... - traps §19：汇总日志与阶段文案都不是接管证据；认领/决策行必须带作业 id 且晚于 杀点；prebackup 允许 succeeded，但要证明复用同一份而不是重做； - traps 索引第 19 行待主人批准（AGENTS.md 受写入保护），草稿在 docs/agents/traps-index-pending.md； - 验收矩阵：S04-b 记"写链路已实测、脚本级验收未成立"，并补一节 "这一轮到底验到了什么/还没成立什么"。旧 FAIL 证据不改写。 verify: make verify overall success（16 项）。文档不含会漂移的统计数字。	2026-10-30 07:56:20 +08:00
姚章浩	d0fe257531	docs: 记录接管身份陷阱与演练判据变化 ... trap-18：快照相等 ≠ 本作业完成。写清真实现场（只写 database 阶段却被判成功）、 根因（版本行主键由 kind+scope+快照决定，登记是 upsert 会改写 source_job_id）、 判据（负例优先：内存 + 真实 PG 两个方向）与修法（effectiveOwnedBy 一份实现， foreign_effective 走拒绝接管出口）。 AGENTS.md 是受保护文件，索引表那一行没有落盘：批准稿放在 docs/agents/traps-index-pending.md，列为已知未完成项。 CHANGELOG 记录本轮 Fixed/Changed 两条。	2026-10-30 03:40:23 +08:00
姚章浩	465cae80bd	docs: 记录"窗口当索引"陷阱与本次改动 ... trap-17：分页窗口当索引 —— "当前生效版本"不能按最近 N 条找。它比 trap-14 更 隐蔽：读成"没有"不报错，只是让错误的选择看起来合理（重写已上线的目标、给已有 权威版本的目标再建基线）。写清判据（250 条历史 + 窗口里看不到 + 精确查询仍命中） 与修法（身份/当前状态一律精确查，窗口只用于列表）。AGENTS.md 的陷阱索引同步加 一行；CHANGELOG 记录当前生效版本查询修复与固定同步屏障；test-scope 声明新增的 真实 PG 用例为"可选未运行"并写清理由（未声明 skip 判红）。	2026-10-30 03:09:37 +08:00
姚章浩	18683ca63c	docs(agents): 记录资源范围冲突与可审计复用判据 ... trap-16：resources 是多知识库共享表，“不在预备份范围”不等于“属于别的 知识库”；恢复保留下来的行是本目标上次成功同步的结果。判据、修法与反例 写进全文，索引表加一行。	2026-10-30 01:59:35 +08:00
姚章浩	cf3f4662cc	docs: 记录写集合与定位符陷阱并归档真作业证据 ... 两条陷阱都是这次真作业里查出来的，且都被"只测内层/只喂裸 key"的用例盖住过： 包装层丢掉可选接口导致写集合静默跳过；对象存储四个入口吃不同定位符形状。 docs/evidence/2026-10-30-real-sync-restore 只放脱敏结果：作业/阶段/版本/维护窗口、 22 个资源与桶内字节、归档三处 sha256 对拍、以及"归档根下没有 writesets/"这个事实。	2026-10-30 01:34:41 +08:00
姚章浩	271f9f5f09	docs: 台账补记 0.1.198–0.1.199 ... 记录接管分类与维护释放幂等的真实 SHA、CI run（236）与候选栈身份注入后 /api/v1/build-info 的读回结果。	2026-10-29 14:27:53 +08:00
姚章浩	691e4e0225	docs: 台账补记 0.1.195–0.1.197 ... 记录 R1 身份契约、封存资源诊断与 R4 成功边界三个提交的真实 SHA 与 CI run， 标明候选栈 clean 构建（vcs.modified=false）与真实验收覆盖范围。	2026-10-29 14:07:35 +08:00
姚章浩	6ed06357f9	fix(library): 期望执行器身份随 capture 请求送达并在执行前核对 ... 原来 worker 先 health 再 capture，两次拨号之间 socket 可能被换成另一个实例的 执行器：错的 agent 已经把写入者停了、快照也出了，事后 postcheck 只能拒绝登记， 副作用无法撤销。 现在 capture 请求自带期望身份（治理侧配置生成：project 必填，source_app / archive_root 配了就绑定）与覆盖三项的稳定指纹；接收方在操作互斥内、执行任何源 操作之前比对，缺字段、指纹与字段不一致、project/source_app 不符都直接拒绝， **错的执行器一次 capture 都不跑**。封存结果回显该指纹，worker 事后复核按它对照， postcheck 只作为证据防线。恢复路径不要求期望（它只把写入者恢复回来）。 负例是确定性的：两个真实 agent 各占一个 socket，把调用方指向错的那个，断言它的 capture 调用为 0 且仍能回答 health；同一份期望打到对的 socket 则只跑一次。	2026-10-29 13:23:56 +08:00
姚章浩	5d42cba6c6	docs: 执行器证据绑定到确切代码 SHA 而不是版本号 ... 矩阵里写"0.1.187 构建"会与台账的版本号漂移；改成代码 SHA 4c79052（0.1.192 工作树）， 与候选二进制来源一致。	2026-10-29 13:12:33 +08:00
姚章浩	a47f9323e0	docs: 台账补记执行器可用性与还原入口（0.1.188–0.1.192） ... 记录真实 SHA、CI run 229（head 4c79052，必需 context success）、候选栈二进制来源与 回退目录。代码 SHA 与已部署候选产物分开写，不把文档提交当成部署证据。	2026-10-29 13:07:51 +08:00
姚章浩	18276d0839	docs: 按用户决定收窄整库还原范围并记录执行器证据 ... 发布管理不承担 Wiki 语义撤销：V03-a 的原始失败证据保留，但移到"模块范围外"， 不再阻断发布，也不改判为通过。矩阵同步补上执行器运行时可用性与按版本恢复入口的 真实证据（候选栈），并把尚未跑的部分（真实封存身份复核、新构建上的真实恢复） 写在"已实现·未跑"。正式 release-worker 的崩溃根因按实测写清：目标库主机 prod-pg 不可解析，修正配置属于正式栈变更，需要部署窗口。	2026-10-29 13:01:51 +08:00
姚章浩	a06945516f	docs(acceptance): V03 撤销语义不通过，补 B02/V05/死信实测 ... 按父审后重跑的真实结果改写验收矩阵：V03-a 单列"失败/不通过"（共享页正文仍带 撤销方独有事实）；V05 并发阻断、B02 删源对象后目标应用读回、死信精确解除的 "已做/未演练"分开放；记 R03 实测耗时与正式栈 socket 风险；台账补 0.1.181–0.1.186 与 run 222–227。	2026-10-29 07:22:16 +08:00
姚章浩	958292d1ff	docs(ledger): 按实际运行的二进制记封存闭环时序	2026-10-29 06:36:05 +08:00
姚章浩	bc49b85b56	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
姚章浩	4d6ecda310	feat(libraryctl): 源对象存储端点可按宿主机地址覆盖 ... 容器 env 里的 MINIO_ENDPOINT 往往是服务名（langfuse-minio:9000），封存跑在宿主机上 解析不到，真实封存报 read library resource 并整体失败。 新增 -source-s3-endpoint：只换访问入口，桶与对象键不变；缺 scheme 直接拒绝； status 会打印实际使用的 endpoint。 试过：make verify 15 项全绿；新增覆盖用例（生效 + 拒绝无 scheme）。	2026-10-29 06:09:56 +08:00
姚章浩	11c52ad81b	fix(libraryctl): 封存窗口接上实例级入口闸门与后台静默 ... 库级窗口永远拿不到在途排空证据：被代理的 WeKnora 收到 SIGTERM 就 exit(1)， 写者退出码不能当作请求已排空。capture/recover 改由 librarymaintenance.Manager 装配入口闸门、后台静默检查、目标指纹与入口探针（与发布链路同一套实现）， 排空证据来自闸门 drain 记录；缺 LIBRARY_TARGET_* 时在开窗口前拒绝并点名。 维护接线解析收敛到 internal/librarymaintenance/env.go，agent 与 worker 讲同一组 变量名；agent 启动如实打印接线状态；安装脚本强制 0600 agent.env。 试过：make verify 15 项全绿；新增 7 个用例（接线解析/身份绑定/缺闸门拒绝）。	2026-10-29 05:48:38 +08:00
姚章浩	ee7688f24e	docs(matrix): Wiki 撤销检查实际 13 项，改正计数	2026-10-29 05:18:42 +08:00
姚章浩	9d0fe33c13	docs(ledger): 补记 0.1.162–0.1.167 与验收代码 SHA ... 0.1.166（1faf513）是本轮验收代码 SHA；f82eb07 起的文档提交不改代码。 0.1.165 因后续提交被 CI 取消，按事实记为 cancelled，不改写成成功。	2026-10-29 05:15:53 +08:00
姚章浩	f82eb0735f	docs(acceptance): 矩阵按四段重排，补封存链路缺口与 8088 部署方案 ... 矩阵不再在顶部叠报告：已完成 / 缺代码 / 已实现未跑 / 需授权四段分开， 把本轮 Wiki 撤销真实验收（12 项检查）、贡献级差异、维护面板写进对应行， 并如实记下封存链路缺口（CLI 无入口排空证明、API 封存未接线）、 死信无解除契约、Neo4j 场景与排空探针未跑。 新增正式 8088 待验收部署方案：迁移 067–072、loopback 配置差异、 缺配即拒绝的 fail-closed 规则、回滚与账号数据保留。只准备，未执行。	2026-10-29 05:13:15 +08:00
姚章浩	def6022048	docs(ledger): 补记 0.1.137/0.1.138 并把进度文件更新到最终真实版本	2026-10-28 20:19:10 +08:00
姚章浩	e7ba2057ac	docs(matrix): V03 标注架构阻塞、P02 真实计数、R01 恢复已验证	2026-10-28 20:06:07 +08:00
姚章浩	f722ea8727	docs(ledger): 补记 0.1.135 cancelled 与 0.1.136 success	2026-10-28 19:34:27 +08:00
姚章浩	e47e6d825d	docs(matrix): 追加入口级 8 场景真实验收对照 ... 为什么：矩阵要与固定 SHA 的证据文件对应。	2026-10-28 19:31:17 +08:00
姚章浩	7a2188a0ee	docs(release): 入口级 8 场景真实验收证据与台账 ... 为什么：证据必须对应固定 SHA；旧证据与报告冲突的部分保留但不再引用。	2026-10-28 19:31:09 +08:00
姚章浩	ca51cbe202	docs(release): 台账补记 0.1.131–0.1.132 与候选验收报告 ... 为什么：版本→SHA→CI→是否部署要可审计，候选 E2E 证据要指向固定路径。	2026-10-28 17:58:42 +08:00
姚章浩	8a68ea2da2	docs(release): 台账补记 0.1.129–0.1.130 ... 为什么：候选 SHA、CI 结论与真实服务验收事实要落台账。	2026-10-28 16:30:08 +08:00
姚章浩	6ca8481e8e	docs(release): 台账补记 0.1.126 与真实服务验收结论 ... 为什么：候选 SHA 与 CI/验收结论要落在台账里，便于父审独立核对。	2026-10-28 16:00:16 +08:00
姚章浩	8da4666e76	test(library): 端到端编排在本机真实 PG/ES 上跑通 ... 为什么：只验证单阶段写入还不够，完整链路（授权→预备份→四类写入→校验）也要在真实服务上跑。 本机 WeKnora 测试栈一次性库与随机索引已通过，CI 无这些服务故在 test-scope 声明为可选。	2026-10-28 15:58:06 +08:00
姚章浩	281699a431	feat(library): 生产整库真实读写/校验/恢复与本机真实服务验收 ... 为什么：生产目标此前是"无条件失败"的占位，编排再完整也不能落地；本轮把它做成真实实现， 并在本机 WeKnora 测试栈的真实 PG/ES 上跑通导入、撤销、预备份与故障恢复。 - ProductionLibraryTarget：Current 读行数+身份摘要；Apply 按阶段真实写入（database/wiki 同事务先删本库再插、resources 传对象、index 搬运原始文档与向量）；Verify 比对身份摘要； Restore 按预备份快照回放。 - 撤销真正生效：索引阶段写入后 PruneScope 删除快照里没有的文档。 - ProductionBackupStore：导出前独立完整预备份，导出前后行数不一致即失败。 - worker 用注入配置装配目标与预备份；缺项把变量名写进阶段并失败，不再有占位对象。 - capacity 安全加法防溢出；保留策略组合语义明确（各维度都超限才候选）。 - 新增本机真实服务集成测试（一次性 kg_library_test_* 库 + 随机 ES 索引）， 覆盖导入/校验/撤销/预备份/故障注入/恢复。	2026-10-28 15:54:01 +08:00
姚章浩	444b820210	docs(release): 台账补记 0.1.123 与 run164 失败说明 ... 为什么：run164 的失败原因与修复要留在台账里，不能让失败消失。	2026-10-28 15:32:52 +08:00
姚章浩	7e3075f0fc	docs(release): 台账补记 0.1.121–0.1.122 与候选说明 ... 为什么：每个开发版本的 SHA 与 CI 结论要能独立审计，不留在交付报告里。	2026-10-28 15:17:48 +08:00
姚章浩	2038462dbb	feat(library): Wiki 页面级差异与页面展示 ... 为什么：撤销文档后 Wiki 变化此前只有"快照保存"证据；页面级差异能给出增/改/撤， 但必须写明它不等于实体、概念、边与引用的语义重算。 - overview 差异新增 wiki 字段：读两份快照的 wiki_pages 行数组比较，缺部件时 unknown。 - 发布管理"本次变更"显示 Wiki 新增/更新/撤销页数与页面级声明。 - 真实归档验证：对内 vs 对外 = 新增 31 / 撤销 1，反向镜像一致。	2026-10-28 15:15:33 +08:00
姚章浩	7b8cc0384b	feat(library): 生产发布授权与同步/恢复编排，worker 接线 ... 为什么：同步入口此前只会拒绝；授权、预备份、四类写入、验证与失败恢复都没有代码。 本轮把编排与授权实现出来，真实生产执行仍按授权闸口关闭。 - internal/libraryrelease：预备份 → 数据库/资源/索引/Wiki → 验证 → 失败恢复； 授权过期/目标不符/快照不符/参数变化在动生产前拒绝；恢复失败单独上报。 - 迁移 000067 library_release_authorizations（目标+快照+参数摘要+有效期，可撤销）。 - POST/GET /api/v1/library/authorizations 与 /{id}/revoke，仅管理员签发，5–1440 分钟。 - worker library.sync 接编排：先闸口再授权，阶段落库，只有编排成功才标成功。 - 生产目标适配器未配置时显式失败（不返回零值状态），预备份存储同。 - overview 返回授权状态，页面"生产保护与恢复"显示签发人与有效期。 - 验收矩阵区分"已实现·隔离测试通过"与"真实执行未授权"。	2026-10-28 15:11:27 +08:00
姚章浩	12bb839d8a	docs(release): 台账补记 0.1.116–0.1.118 的 CI 结论 ... 为什么：版本台账要能独立审计每个版本的 SHA 与 CI 结论，不能只留在交付报告里。	2026-10-28 14:43:22 +08:00
姚章浩	e313ae12f2	feat(library): 真实差异比对 + 孤儿作业回收 + 验收矩阵与台账 ... 为什么：发布管理的差异一直显示"未接入"，业务作业也可能因队列丢作业而永久占锁； 本轮把这两件做成真实实现，并把 30 个验收项与 CI/版本身份落成可审计文档。 - internal/librarydiff：稳定文档 ID + 排除易变列的整行摘要做增改撤销；overview 在 生产权威版本与测试封存都在时给出 computed 差异并标注两侧快照，缺一侧仍是 unknown。 - 发布管理"本次变更"列文档身份与比对版本；无差异时明确写"没有文档差异"。 - ReconcileLibraryJobs：worker 启动清理队列已无对应作业的孤儿，避免永久互斥。 - docs/library-acceptance-matrix.md 与 docs/release-ledger.md 固定证据与版本事实。	2026-10-28 14:39:17 +08:00
姚章浩	58d0483d44	feat(release): 按确认稿重做发布管理（两库页签 + 单作业区 + 版本抽屉） ... - 顶部只有对内/对外两个知识库页签，切换只渲染选中库的一个作业区 - 同步前：生产当前→拟发布、新增/更新/删除与 Wiki 完整快照、准备清单、 版本与快照/启动同步、本次变更 + 生产保护与恢复、五段作业阶段 - 同步中：作业阶段/版本/已用时 + 四类数据卡 + 同步明细与异常，未接入项 只显示状态、不编百分比 - 版本与快照抽屉按 scope 列全部封存记录与分项摘要，恢复入口在真实演练前禁用 - 存储口径移到系统设置→存储管理只读区；保留/清理/自动清理标未接线 - 生产段无真实数据一律"未接入/尚无记录"，启动同步禁用并说明	2026-10-28 13:23:55 +08:00
姚章浩	910c0fcd76	feat(library): 页面发起封存的最小权限主机侧执行边界 ... - libraryagent：0700 目录内 0600 unix socket + SO_PEERCRED 同 uid， 固定 binary/归档/日志/项目/写入者声明，请求只能选范围与作业号 - API：POST/GET /api/v1/library/captures（入队 library.capture + 读队列状态） - worker：library.capture handler 走 socket；启动先 recover；不挂 Docker socket、 不持有来源凭据 - web：整库版本页显示真实作业状态并可发起封存（未接线/无权限给出原因） - scripts/library-agent-install.sh：构建、安装 systemd user 服务并读回权限	2026-10-28 12:11:08 +08:00
姚章浩	c5e033dd0e	fix(library): 幂等重放、跨版本去重用量与契约复核 ... - 同作业号重跑读持久日志+已封存清单按首次请求重放（source_read=false, writers_stopped=false），换范围/绑定库或清单校验失败即拒绝 - 归档用量按跨版本去重统计内容字节，清单/未引用 blob/实际分配单列， 不再用各版本 unique 之和冒充归档占用 - 冻结窗口内复核来源契约，不一致即中止；拒绝组外同镜像运行容器 - 补齐整库只读接口的 OpenAPI 契约 - 按用户确认取消 A06：文档/页面/接口不再把效果测试列为封版门槛	2026-10-28 12:01:09 +08:00
姚章浩	045fc44f0e	feat(library): 接通整库封存真实入口与只读版本页 ... - libraryctl：status/preflight/capture/list/verify/recover，只读来源会话、 结清检查、契约推导、维护窗口内停写者、导出十表+索引+对象+Wiki、封存候选后恢复 - libraryfreeze.ProjectController：按 Compose 项目逐服务声明固定身份， 未声明服务/容器重建即拒绝，仅 SIGTERM，恢复后必须 healthy - httpapi：GET /api/v1/library/snapshots[/{id}] 只读列出封存产物 - web：「整库版本」页（只读、未接线显示原因、无假按钮） - api：LIBRARY_ARCHIVE_ROOT + 归档根只读挂载 - docs/library-capture.md：运维手册与 2026-10-28 两次真实封存实测 不代表整库业务验收通过：内容/问答/性能验收、跨系统切点、Wiki 删除语义重算、 生产预备份/恢复演练/双闸/同步协调仍未完成。	2026-10-28 11:39:50 +08:00
姚章浩	864a1632e0	test(snapshot): 增加真实测试源只读诊断并记录孤立索引阻塞	2026-10-28 08:32:23 +08:00
姚章浩	9f990158b9	test(snapshot): 联合验证真实隔离存储与暂停恢复链	2026-10-28 08:22:21 +08:00
姚章浩	76f687b52d	feat(snapshot): 按已确认口径保留索引产物并标记验收策略	2026-10-28 08:01:46 +08:00
姚章浩	bf049cee1f	fix(snapshot): 暂停前后强制检查共享源全库任务	2026-10-28 01:05:44 +08:00
姚章浩	2c5ecdf0f3	fix(version): 补齐整库基础版本的独立快照说明	2026-10-28 00:34:20 +08:00
姚章浩	9105f8316c	feat(snapshot): 增加整库独立快照及测试停写恢复基础	2026-10-27 23:44:12 +08:00
姚章浩	c1d49adb62	docs(agents): 补三Agent交接闭环工作流（状态机、快照tag与验收模板） ... 工单 #6。三个会话（架构/开发/验收）在同一仓库串行协作时缺一份可核对的 书面契约，口头约定会漂移：状态标签命名不统一（仓里还留着 status/working）、 快照 tag 被当正式版本用、验收拿开发总结当结论。 本文件把契约写死：角色边界、main 单线串行、六个状态名与 blocked 要素、 快照 tag snapshot/vX.Y.Z 与正式版本 vX.Y.Z 分线、不可变与回退规则、 开发与验收交接模板、关单条件、安全边界。 为什么快照不能沿用 vX.Y.Z：make verify 里的 check_changelog --tags 会对每个 正式 tag 断言其提交内 CHANGELOG 顶部版本一致；在临时仓库实测正式 v0.1.1 与 v0.1.2 都判红，而 snapshot/v0.1.1 被归为非正式 tag 通过。故快照改用 snapshot 前缀，正式版本仍走单独批准与 CHANGELOG 流程。 范围：仅新增这一个文档，不改 CHANGELOG 与 CI。 验证：make verify 15 项全 success（档案 local，退出码 0）。	2026-10-14 17:33:22 +08:00
姚章浩	64b32c2da6	feat(settings): 数据源配置默认只列 PP 资料 + 「可加入的来源」 ... 主人要求：AList 已由钉盘文件替代、钉钉知识库改为按当前账号发现 ⇒ 这两类不再出现在 数据源配置里，只保留 PP 资料与「可加入的来源」（按当前钉钉账号列出可访问的知识库与钉盘空间）。 实现（非破坏、可逆）： - 新增纯函数 splitSourceConnections(connections, showLegacy)：把 alist 与 dingtalk 归为 legacy，默认只返回 PP／手工等其余来源；showLegacy=true 时原样返回（顺序不变、一条不少）。 - 「数据源配置」新增一行折叠开关「显示 AList／钉钉知识库来源（N）」：默认收起，只显示 PP 资料（+手动导入）；展开后这 N 个来源照旧可改刷新周期、启停、看修订历史。 **没有删除任何来源，也没有动它们的调度与目录快照。** - 区块文案说明登记路径：新来源只从「可加入的来源」勾选登记（钉盘文件已替代 AList）。 - 测试：splitSourceConnections 直测（默认折起 a/d、展开 a/b/c/d）+ SSR 断言默认视图只含 PP、 折叠项不在默认视图（原断言的 dingtalk 卡片标记改为折叠后的期望）。 验证：make verify 15/15；SystemSettings 用例 7/7。	2026-10-14 12:01:47 +08:00
姚章浩	0974d8dfa2	feat(version-history): 「版本记录」页 —— 追踪远端 main 全部提交（只读 + 管理员手动同步） ... 按已确认的契约实现（口径见 docs/VERSION_HISTORY.md）： - **版本号口径（只给有证据的）**：注释 tag + tag 指向该提交 + 该提交内 CHANGELOG 顶部三者一致 ⇒ 正式版本； tag 之后的提交按 `<主>.<次>.<自该 tag 的提交数>` 显示开发号（与 scripts/version.py **同规则**）； 证据不足 ⇒ 「历史提交 · 短SHA」+ 原因码，**不补造版本号**。完整 SHA 是唯一身份、版本号不是唯一键 （tag 之后两条并行分支各自的第 1 个提交都算 0.1.1 ⇒ 两条都保留，用短 SHA 区分）。 - **迁移 000046**：version_history_commits（提交记录，主键 repo_key+commit_sha）+ version_history_sync_runs （同步状态）。快照 = 一次同步：抓完并与 X-Total-Count 对账通过才切换；失败不切换快照、不清空历史、 last_success_at 不动（页面显示"上次同步失败（原因）· 仍展示上次成功数据"）；「同步成功」≠「历史完整」。 - **只读客户端（匿名，不使用任何凭据）**：白名单 origin + 固定仓库、拒绝任意 URL 与跨主机重定向、 响应上限 5MB / 超时 15s、仅 5xx/429 退避重试（最多 3 次）；逐页抓到短页为止；每次全量扫 tag ⇒ 旧提交后补的 tag 会更新既有记录（不新增第二行）。 - **接口**（三个都登记进 api/openapi.yaml）：GET /api/v1/build-info（viewer）、 GET /api/v1/version-history（viewer；游标绑定快照，过期返回 409 cursor_expired；不返回伪造 total）、 POST /api/v1/version-history/sync（admin；并发同步复用同一作业，靠 IdempotencyKey）。 - **「当前运行」只认精确匹配**：产物注入的完整 SHA 命中某条记录才标该条；开发构建显式标注"开发构建"； 没有可用标识 ⇒ "当前运行版本未知"；**不拿最新 main / 最新 tag 顶替**，CI 成功不等于已部署。 - **前端**：一级菜单第 5 项（版本记录）+ 时间线页面（全部/正式/开发/历史四段筛选、正文展开、 加载更多、760px 单列无横向溢出、提交正文与变更记录按纯文本渲染）；无打 tag / 发布 / 部署入口。 新增配置（留空即未接线，页面降级）：VERSION_HISTORY_GITEA_BASE_URL / _REPO / _ALLOWED_ORIGINS / _HTTP_TIMEOUT / _MAX_PAGES。 验证：`make verify` 15/15 success（tests-go 578 通过 / 0 失败；tests-web 209 通过 / 0 失败）； 新增 Go 用例 30（版本口径与图遍历 12、客户端守卫 6、同步编排 5、接口 7）；前端新增 18（组件 10 + 客户端 8）； 真实仓库匿名快照拉取（`VERSION_HISTORY_LIVE_BASE_URL=… go test -run TestLiveSyncAgainstRealRepository`）： 抓到 113 条与 X-Total-Count 一致、v0.1.0 是注释 tag 且目标与 `git rev-parse v0.1.0^{commit}` 一致、 开发号逐个等于 `git rev-list --count v0.1.0..<sha>`（正式 1 / 开发 22 / 历史 90）。	2026-10-13 19:40:19 +08:00
姚章浩	ad9c5d20d4	Merge remote-tracking branch 'origin/main'	2026-10-13 19:08:54 +08:00