Commit Graph

116 Commits

Author SHA1 Message Date
姚章浩 062a3b3cb6 fix(web): index.html 不再被 CDN/浏览器缓存(否则页面停在旧构建上)
build / build (push) Successful in 55s
现象:p1 已上线新构建(容器内 bundle 是新的),但主人通过公网入口 kg.zheromiku.top 看到的
仍是旧界面(左侧菜单只有 4 项、没有「版本记录」)。实测:

- 公网入口 `/` 引用 `index-CddbQIqQ.js`(10-10 的旧包),而本机 8088 已引用 `index-Dbnd-DW-.js`;
- 带上缓存破坏参数再取同一个公网地址 ⇒ 立刻拿到新包;响应头有 `EO-Cache-Status`/`EO-LOG-UUID`
  ⇒ 中间是腾讯云 EdgeOne,把**旧 index.html** 缓存住了(浏览器同理:index.html 无缓存头时按启发式缓存)。
- 根因:`deploy/nginx.conf` 里对 `index.html` **完全没设缓存头**。

修复(只动静态入口的缓存语义,不改任何业务逻辑):

- `index.html`(含 SPA 深链回退):`Cache-Control: no-cache, must-revalidate` ⇒ 每次回源校验,
  CDN/浏览器不会再把入口钉在旧构建上;
- `/assets/`(带内容哈希):`public, max-age=31536000, immutable` 长缓存,换版本必然换文件名;
- `/assets/` 未命中明确 `404`,不再回退成 `index.html`(否则浏览器把 HTML 当 JS 执行,报一堆语法错误)。

验证:本机 8088 与公网入口 `kg.zheromiku.top` 的 index.html 都只发一条 `no-cache, must-revalidate`,
且公网入口已引用新包 `index-Dbnd-DW-.js`(其中含「版本记录」);`nginx -t` 通过;旧哈希资源 404、
SPA 深链仍 200。CHANGELOG 补 Fixed 条目。

⚠️ 本次是"新功能看起来没上线"的真实原因,已记入 deploy/nginx.conf 注释,避免复发。
snapshot/v0.1.6
2026-10-14 10:38:44 +08:00
姚章浩 4d43a9386a fix(version-history): tag 之前的提交不再被编号 + 部署脚本注入构建身份
build / build (push) Successful in 1m5s
真实数据发现(本机 p1 实例第一次同步后核对):
- **缺陷**:tag `v0.1.0` 之前的 20 个提交,提交内 CHANGELOG 顶部**也已经**是 0.1.0(旧分支遗留条目),
  而它们的祖先集合被那个**更晚才打**的 tag 全覆盖 ⇒ 按提交数算得 0 ⇒ 被错标成「0.1.0 开发版」。
  它们的正确判定是「历史提交」:那个 tag 是后来才打的,当时还没有发布基线。
- **修复**:基线 tag 必须是该提交的**祖先(或就是该提交)**,否则不给号;新增原因码
  `release_tag_created_later`(页面文案:'该版本是在更晚的提交上发布的 —— 这个提交当时还没有 tag')。
  回归用例两条:`TestDeriveVersionsDoesNotNumberCommitsThatPredateTheTag`、
  `TestDeriveVersionsSideBranchWithoutTagStaysHistorical`(不含 tag 的侧分支同样不给号)。
- **部署脚本注入构建身份**:`scripts/deploy-api-web.sh` 原先不传 `-ldflags -X`,产物 `CommitSHA=unknown`
  ⇒ 页面只能显示"当前运行版本未知"(契约上诚实,但没用)。现在按 `scripts/version.py --identity`
  (唯一来源,与 Makefile/CI 同规则)注入 VERSION/RELEASE_VERSION/BUILD_KIND/COMMITS_SINCE_RELEASE/
  COMMIT_SHA/BUILD_TIME;取不到身份**拒绝继续**(宁可不上线,也不上线一个认不出自己的产物),
  并在收尾核对注入的 SHA 真的进了产物。
- compose.yaml:把 VERSION_HISTORY_* 五项接进应用环境(api/worker 共享锚点),留空即未接线。

验证:真实仓库复验(114 条对账一致)⇒ 正式 1 / 开发 4 / 历史 109(原来错的 19 条现在都是
`release_tag_created_later`);p1 实例重新同步后当前快照分布一致,带号的记录只剩 1 正式 + 4 开发
(含真实存在的「同号不同 SHA」:950c1b4 与 3a1d32d 都是 0.1.1,各占一行);
make verify 15/15 success;前端 18 用例 + typecheck 通过。
snapshot/v0.1.5
2026-10-14 10:00:27 +08:00
姚章浩 0974d8dfa2 feat(version-history): 「版本记录」页 —— 追踪远端 main 全部提交(只读 + 管理员手动同步)
build / build (push) Successful in 57s
按已确认的契约实现(口径见 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)。
snapshot/v0.1.4
2026-10-13 19:40:19 +08:00
姚章浩 ad9c5d20d4 Merge remote-tracking branch 'origin/main'
build / build (push) Successful in 49s
snapshot/v0.1.3
2026-10-13 19:08:54 +08:00
姚章浩 3a1d32da8f docs(readme): 重写平台定位与能力边界并归档原说明
build / build (push) Successful in 49s
2026-10-13 17:53:23 +08:00
t 950c1b429b feat(release): 抬档门禁(破坏性 ⇒ 0.x 抬次 / ≥1.0.0 抬主)+ 1.0.0 前置(稳定契约承诺)
原来预检只"打印破坏性条数",抬哪一档靠人自觉 ⇒ 改成硬门禁:

- **抬档门禁**:破坏性条数取自**目标提交里候选版本那一段**(发版事实看提交,不看工作区)。
  `0.x` 阶段有破坏性 ⇒ 必须抬**次版本**(或主版本),只抬修订 ⇒ 阻断并报出该抬到哪一档;
  `≥1.0.0` 之后有破坏性 ⇒ 必须抬**主版本**,抬次/修订都阻断。
  另加"候选号必须大于上一个正式版本"(版本只增不减)。
- **1.0.0 前置**:上一版本是 `0.x` 时,候选 `1.0.0` = 对外承诺契约稳定 ⇒ 必须先有写实的
  《稳定契约承诺》(覆盖 接口 / 数据模型 / 配置 / CLI 输出与退出码,不留 `待填`/`TODO`/`TBD`),
  **且候选发布记录里链接它**,缺任一条 ⇒ 阻断;`1.x → 2.0.0` 不重复要求。
- 预检新增"版本走向"事实行(上一版本 → 候选 / 抬哪一档 / 破坏性 N 条 ⇒ 要求哪一档 ✅⛔);
  `docs/RELEASE_RUNBOOK.md` 新增"抬哪一档"对照表与《稳定契约承诺》段(故意留占位)。

验证:release_preflight --self-test 32 分支全过(含新增 9 条);反向夹具新增 §24 六条真实临时仓库用例
(0.x 只抬修订 ⇒ 阻断、0.x 抬次 ⇒ 放行、≥1.0.0 抬次 ⇒ 阻断、1.0.0 留占位 ⇒ 阻断、写实+链接 ⇒ 放行、
写实但没链接 ⇒ 仍阻断)⇒ 夹具 91/0;make verify 15/15。
于是 0.1.0 之后的第一个提交(本提交)开发号 = 0.1.1。
2026-10-13 17:13:44 +08:00
t 6de5d52363 feat(version): 开发号随提交自动递增 + 首个正式版本 0.1.0
build / build (push) Successful in 51s
按使用者要求定的版本规则(自动升的是**开发标识**,发布版本与 tag 仍由人批准):

- **开发号自动递增**:display_version(development) = `<正式版本的主.次>.<自 v<正式版本> 以来的提交数>`
  (正式 0.1.0 之后第 1 个提交 0.1.1、第 12 个 0.1.12;恰在发布提交上 = 正式号)。
  它**不写进 CHANGELOG**(发布记录只在发版时动),由 git 算出来 ⇒ 每个提交都有自己的号、数字只增。
- **浅克隆不猜号**:`--depth` 会把条数算少 ⇒ 浅仓库里拒绝算号,退回 `<版本>-dev+g<短SHA>`;
  检出步骤在仓库有 tag 时 `--unshallow` 补全历史。
- 接线三处齐全:`version.py --identity` → 门禁 `-X …CommitsSinceRelease=<n>`;Makefile 的
  `COMMITS_SINCE_RELEASE`;Dockerfile 同名 build-arg;Go 侧新增 `CommitsSinceRelease` 与
  DisplayVersion() 新规则;契约测试**交叉核对**"注入的提交数 == git 算出的"(防注入错号)。
- **首个正式版本 0.1.0**:CHANGELOG 的 `[Unreleased]` 提成 `## [0.1.0] - 2026-10-13`;
  头部补"版本怎么走"两行;RELEASE_RUNBOOK 补递增规则与"下一次发布把次版本加一"。
- 发版预检新增:打印**当前开发号**,并挡住"候选正式版本 <= 当前开发号"(会把开发号当正式号;建议次版本加一)。

验证:version.py --self-test(含 tag 后第 2 个提交 = 0.2.2、恰在 tag 上 = 0.2.0、无 tag 不猜号);
release_preflight --self-test(21 分支,含开发号两条);go test 本地三态 + 临时仓库 tag+2 提交实测
(Python 与 Go 都得出 0.2.2);反向夹具 85/0;make verify 15/15 success。
v0.1.0
2026-10-13 16:45:56 +08:00
姚章浩 97f4b29661 fix(version): 就绪看目标提交的顶部版本 + 禁用自动发布路径
build / build (push) Successful in 52s
补两处残余(本轮不推、不打真实 tag、不部署;全部用临时仓库与 spy 验):

1) version_in_commit 必须比"目标提交 CHANGELOG 的**顶部**已发布版本",不是"历史里出现过":
   - 新增 top_version_in_commit(),version_in_commit() 直接比它;预检输出把该提交的顶部版本打出来
     (诊断可审计:例如"顶部是 `## [0.3.0]`,不是 0.2.0"),阻断信息里也带上真实顶部版本。
   - 顺带兜住"最新在最上面 / 版本只增不减"的排序要求。
   - 负例(自检 + 夹具各一遍):顶部 0.3.0、历史里 0.2.0 ⇒ 候选 0.2.0 拒绝;候选 0.3.0 通过。

2) 按只读约定**禁用 --execute 自动发布路径**:
   - 删掉写路径(打 tag / 推 tag / 建 Release 的代码整段移除),`--execute` / `--approve-version` /
     `--approve-sha` 只保留参数兼容(不报 unknown argument),传了就**明确拒绝**(rc=2)。
   - 拒绝发生在收集事实之前 ⇒ **零写操作、零 API 调用**;自检用 spy 断言拒绝路径
     "一个子进程都没跑、一个 API 都没发",并扫描生产路径不许出现直接执行 git 写命令的行。
   - 输出里也不再推荐自动路径;RELEASE_RUNBOOK 第 4 步改为由人执行。

验证:release_preflight --self-test 绿(就绪 20 分支 + 顶部/历史两态 + --execute 拒绝零写 +
源码写路径扫描);反向夹具 84/0(含 --execute rc=2 且跑完仓里 tag 不变);make verify 15/15 success。
2026-10-13 15:48:50 +08:00
姚章浩 7a9d51cc70 fix(version): 正式构建核证据 + 预检分"建议/就绪" + CI 就绪按必需 context
按要求补三项(本轮不推、不打真实 tag、不部署;全部用临时仓库与假对象验):

1) 正式构建身份不能只认 --release:
   - 新增 release_evidence():核①完整 40 位 SHA ②**指向该提交的注释 tag** v<版本号>
     ③该提交里 CHANGELOG 顶部版本一致。缺任一条 ⇒ rc=2,身份退回 development 并把
     release_blocked 的原因写进 JSON(给机器读,也给人看)。
   - version.py --self-test:六条负例(有版本无 tag / unknown SHA / 短 SHA / tag 指错提交 /
     轻量 tag / 版本不一致)+ 证据齐正例,**tag 全部在 mktemp 临时仓库里创建**。
   - Go 侧新增 TestReleaseBuildRequiresEvidence:release 构建必须 CommitSHA 完整且
     v<ReleaseVersion> 是**注释 tag** 并指向该提交(独立于 Python 的二次复核)。

2) 发布预检区分"准备建议"与"发布就绪":
   - 新增纯函数 readiness(facts) → (是否就绪, 阻塞项, 建议);输出分两段。
   - **就绪要求候选版本已写进目标提交**(version_in_commit:查 git show <sha>:CHANGELOG.md,
     工作区写了没提交不算);首发按**显式指定版本**处理,**不把"记录里有这个版本"当已发布**
     (已发布的证据是 tag,不是记录条目)。
   - 预检**不执行、也不在输出里推荐自动发布路径**(正式发版由人按 docs/RELEASE_RUNBOOK.md)。

3) CI 就绪判据:必需 context 集合来自 .gitea/required-contexts.txt(缺失/为空 ⇒ 没有策略 ⇒
   阻断,不用观察到的状态顶替);**全部 success 才通过**,失败/缺项/pending/查询异常一律阻断。
   Release 查询加 release_state():**只有 HTTP 404 才算不存在**,403/5xx/超时算查询异常 ⇒ 阻断。

验证:version.py --self-test 绿;release_preflight --self-test 绿(就绪判定 19 个分支 +
临时仓库验证 git show 语义 + 五个 HTTP 码语义);go test 三态(未注入 SKIP / 开发 PASS /
自称正式 RED);反向夹具 83/0(含临时仓库 go test 六例、预检"记录未进提交"两态);
make verify 15/15 success。
2026-10-13 15:26:49 +08:00
姚章浩 05144309c3 feat(version): 构建身份(release_version/build_kind/display_version),无基线也放行
解决"开发构建沿用已发布版本号,分不清开发版与正式版":

- 新增 `scripts/version.py --identity`:release_version(无基线即空)/ build_kind /
  commit_sha(完整 40 位)/ display_version / built_at。显示规则:发布 `X.Y.Z`、
  开发 `X.Y.Z-dev+g<短SHA>`、无基线 `dev+g<短SHA>`、什么都拿不到 `dev`。
- `build_kind=release` 只认**显式发布上下文**(`BUILD_KIND=release` / `--release`);
  声明发布构建却没有已发布版本 ⇒ 拒绝(rc=2)。普通 main 构建永远是 development,
  **不许只显示上一正式版本号、不许自称正式版**。
- Go 侧 `internal/version` 加 ReleaseVersion/BuildKind/DisplayVersion()/IsRelease()/Info(),
  原 Number/CommitSHA/BuildTime 语义不变(向后兼容);契约测试改成:发布构建必须等于
  CHANGELOG 顶部、开发构建必须是 dev 形状;`make verify` 的 contracts 项新增
  **负例**「自称正式版 ⇒ 必须红」(只有正例的契约会被静默掏空)。
- 构建接线:Makefile/Dockerfile/ci_checks `--internal-build` 统一走 identity;
  Makefile 的 `make version` 打印身份 JSON;Dockerfile 新增 RELEASE_VERSION/BUILD_KIND。
- `tests-go` 的"按设计跳过"声明补上 `TestDevBuildDoesNotClaimRelease`(它的强制点在 contracts)。

验证:go test 三态实测(未注入 SKIP、开发身份 PASS、自称正式版 FAIL);
--internal-build 产出并打印 dev+g<sha>;--internal-identity 契约项 rc=0;
make verify 15/15 success;反向夹具 80/0。
2026-10-13 14:59:36 +08:00
姚章浩 4f8ee0a8c5 feat(version): 变更记录改固定四类,破坏性变化带发布文档链接
按项目方给的规则重做 CHANGELOG 与检查器(本轮不推、不打 tag、不部署):

- 条目形状:四个自定义必填节(改了什么/兼容性与迁移影响/怎么验收/已知问题)
  → 固定四类 Added/Changed/Fixed/Security;分类可省略,**不许空栏目**;每个版本块
  至少一个非空分类;`[Unreleased]` 段不得写日期。
- 破坏性变化:固定写在 Changed 里、以 `**破坏性**` 开头,**必须链接发布文档**;
  仓内 `docs/….md` 链接**对账**(不存在 ⇒ 红)。写在别的分类里也判红。
- 结构判据补强:非法日期、重复版本、顺序必须严格递减、前导零;围栏代码块里的
  `##`/`###` 不算标题;**块正文以任意二级标题为界**(「## 能力基线(未发布)」这类
  不带方括号的标题原先不是边界,会把后文算成上一节的内容 ⇒ 空栏目被兜成"有内容",
  夹具真的抓到了这个假绿)。
- tag 一致性:远端专属清单 `.ci-remote-tags` → `ls-remote` → 本地 refs 三级来源;
  **没核对远端就不许说校验成功**(CI/预检用 `--require-remote`,拿不到清单即红),
  非正式 tag(如本地 `x`)不当作发布版本、不判红,没有 tag 不判红。
- `0.1.0` 定为**未发布的能力基线**(远端无 tag、无 Release):改成不带方括号的
  「## 能力基线(未发布)」,不补造 tag/发布日期/发布事实。
- 过程记录迁出:审查轮次与命令输出 → `docs/archive/CI_接入留档.md`(原文保留);
  未合并事项 → `docs/BACKLOG.md`;补 `docs/RELEASE_RUNBOOK.md`(破坏性变化的链接目标,
  同时修掉 CHANGELOG 里指向不存在文档的悬空引用)。
- 发版预检:无版本基线时把「首个正式版本号由人指定」列成阻塞项(不再要求先有基线才能跑);
  打印破坏性变化条数;远端 tag 查不到时明说未核对并阻塞;不再硬读已删除的『已知问题』节。
- traps trap-5 口径修正:不是"不用 tag",而是"构建时不要用 git describe 取版本号"。

验证:check_changelog --self-test 全过;反仓夹具 80/0(含五条真改文件的结构负例、
六条只在临时仓库里造 tag 的场景);make verify 15/15 success。
2026-10-13 14:59:35 +08:00
hermes c99332d770 feat(ci): 通知链接改用非秘密配置 CI_PUBLIC_BASE_URL(run/提交/变更统一),缺失或非法明确回退
build / build (push) Successful in 49s
为什么要改:通知里的链接一直用 GITHUB_SERVER_URL 拼(内网地址),群里/换网就点不开。

做法(不覆盖 GITHUB_SERVER_URL、不碰检出与内部调用):
- ci_report.py 新增 _link_base():CI_PUBLIC_BASE_URL 优先,缺/非法(非 http(s)、带 userinfo、带空白)⇒ 明确回退 GITHUB_SERVER_URL,并把来源写进 payload 的 link_base_source(可复盘)。
- 三类链接统一用它:run_url、commit_url(新增,提交行用短 SHA 展示、完整 SHA 在链接里)、compare_url;仓库必须是真 owner/repo、SHA 必须是完整 40 位,否则宁可不给链接。
- workflow 上报步骤加非秘密 CI_PUBLIC_BASE_URL: https://gitea.zheromiku.top(写在 YAML 里便于审查)。
- **不做消息文本的全局 URL 替换**:提交标题/摘要里的 URL 仍是文本(bridge 侧负例钉住)。
- 自检补 _link_base/_commit_url 分支(缺失回退、非法回退、尾斜杠、短 SHA 不拼链接)。
2026-10-13 10:27:43 +08:00
hermes 551da29b3b fix(ci-gate): 事件负载没有 total_commits 时不再抛未收敛异常;上报补齐通知所需字段
resolve_scope():declared 未初始化就参与判断 —— 负载缺 total_commits 时抛 UnboundLocalError(Gitea 推送负载一直带该字段,所以线上未暴露;换触发形状就是未收敛异常)。改为 declared=None 初始化。

ci_report.py:按通知消息规范补 job(从 workflow 文件读真实 job 名)/ run_number / run_attempt / commits(复用门禁同一个范围解析器,含 range_source)/ compare_url(只在有真实 before..after 时给)/ first_failure / next_step / limitations;commit_count 以准确范围为准。不改检查流程、不改 workflow。
2026-10-12 19:43:33 +08:00
姚章浩 0c0363512d test(ci): 反向夹具补版本记录与发版预检(22/23 节,共 74 条)
新增:缺『已知问题』节/前导零版本号/注释 tag 与提交内版本不符/轻量 tag 逐条判红;无 tag 与『只有 Unreleased』不判红;预检在脏工作区不给可发结论、跑完不留 tag、输出里没有写操作。夹具总数 60 → 74。
2026-10-12 17:58:06 +08:00
姚章浩 40d84994cb feat(ci): 版本记录检查(四节 + 正式 tag 一致性)+ 只读发版预检
check_changelog.py:正式版本条目必须四节齐备且非空(改了什么/兼容性与迁移影响/怎么验收/已知问题)、版本号三段无前导零、[Unreleased] 在最上面;新增 --tags 核对正式 tag(必须注释 tag)与它指到那个提交里的版本记录一致。只有 Unreleased 的新工程放行;没有正式 tag 不判红(开发版本不打 tag 是常态)。ci_checks.py:新增必需检查 version(门禁 15 项),策略版本 ci-checks/2。ci_checkout.sh:记录远端 tag 清单并取 tag 对象供核对。release_preflight.py:只读预检(版本建议/完整 SHA/CI 证据/CHANGELOG/远端 tag 与 Release/遗留项),写类 git 命令与 POST 在预检路径上被拒(--self-test 证明);批准后 --execute 才打注释 tag、推 tag、建 Release 并读回。CHANGELOG 0.1.0 补上原本缺的两节。
2026-10-12 17:57:43 +08:00
姚章浩 9ad13a8c62 docs(agents): 留档短命试验分支的真实 CI 运行记录(run #16 失败 / #17 通过)
build / build (push) Successful in 48s
记录真实 run 链接、完整 SHA、14 项必需检查、预览 URL 与探测结果、通知入队与 ret=-2 的送达状态、run #16 暴露的 total_commits=0 缺陷,以及未验证项。分支 ci-trial-20261012 已在试验后删除,远端只剩 main。
2026-10-12 17:00:21 +08:00
姚章浩 257a8a187a fix(gate): total_commits<=0 视为未声明,范围以 Git 为准(真实新分支事件形状)
build / build (push) Successful in 1m22s
真实 Runner 首跑(run #16, ci-trial-20261012)发现:新分支推送时 Gitea 给 total_commits=0、commits 列表被截断(5 条),而 Git 范围 12 条;原先'声明条数 != Git 范围就拒绝'让门禁第一次真实运行就红,且与代码质量无关。改成 Git 范围是唯一权威:total_commits>0 才交叉核对(保留'声明6/列表1/Git2 ⇒ 拒绝'的判据),<=0 或缺失视为未声明并以 Git 范围为准,同时把'负载条数不可信、列表被截断'写进来源说明。--self-test 增加该形状(15 分支);traps 22 记录教训:负例要照真实负载的形状造。
2026-10-12 16:55:41 +08:00
姚章浩 91b674f278 docs(agents): 清掉 traps.md 文件末尾的多余空行(git diff --check 报的最后一处)
build / build (push) Failing after 4s
2026-10-12 16:52:44 +08:00
姚章浩 d167a2b937 fix(ci): 第一步改最小 bootstrap(空工作区可启动),新分支范围以默认分支为基准
空工作区启动:workflow 第一步不再调用仓内脚本(此时它还不存在,实测 rc=127),改成只用 runner 环境变量的最小 bootstrap:校验协议/凭据 → git init+remote add → 取事件完整 SHA → checkout → 断言 HEAD==事件 SHA;检出后才调用 ci_checkout.sh --post-checkout 做再断言与补取(默认分支引用、事件 before)。按任意 SHA fetch 在服务端默认不可用(服务器不允许请求未公开的对象),改成取分支历史 + --deepen 再核事件 SHA。新分支范围:after --not --remotes 会把刚 fetch 的同名远端分支(=after)当排除集、排除自身得到 0 条;改为以远端默认分支为基准 refs/remotes/origin/<default>..<after>,取不到基准就明确失败。新增 scripts/ci_chain_fixture.py:本地 HTTP git 服务 + 把 workflow 的 bootstrap run 块原样抽出来在空目录执行,正/负例 12 项断言。
2026-10-12 16:45:10 +08:00
姚章浩 75a6085844 docs(agents): traps 14-18(假检查/预览顺序/观察到的 context/协议降级/范围退化) 2026-10-12 11:15:18 +08:00
姚章浩 164dc2f72c test(ci): 反向夹具扩到 54 条,含预览发布与合并调用链负例
新增 14~19 节:假 bridge 数 publish 请求(坏报告 0 次/好报告 1 次)、--verify-only 单跑核对、检出协议保留、合并调用链(假 Gitea 跑真实 merge_pr,13 分支)、生成器落齐新脚本与空策略文件。首轮 1 处失败暴露真实缺陷:无远端引用时 --not --remotes 退化成整部历史(把 Initial commit 算进来)⇒ 改为只核 HEAD 并写明。
2026-10-12 11:15:18 +08:00
姚章浩 9a178675f6 ci(workflow): 检出抽成脚本、预览先核对报告、提交范围以 Git 为准
检出:协议按 GITHUB_SERVER_URL 原样保留并断言不降级(https 不许变 http)、URL 不放凭据、把事件 before 也取下来。预览:发布前调 ci_report.verify(),有问题一个 publish 请求都不发(旧写法只读 overall+SHA,缺项报告会先发出去)。范围:push 用 before..after、新分支用 after --not --remotes,声明与范围不一致/空范围/浅克隆缺 before/列表提交不在检出里全部拒绝,手工运行只核 HEAD 并写明。合并必需 context 改由 .gitea/required-contexts.txt 声明,不再用观察到的状态。
2026-10-12 11:15:18 +08:00
姚章浩 88da069e1f ci(checks): 必需与可选测试按声明区分,未声明就跳过的用例判红
test-scope.json 提供声明:package/test 至少给一个、必须给 reason 与 owner、package 级要写 expected_skips(跳过数涨了要重新声明)、review_by 过期即失效。文件缺失或解析不了 = 声明不出来 ⇒ 不许默认放行。
2026-10-12 11:15:18 +08:00
姚章浩 96ac67e744 docs(agents): traps 补 5 条、CHANGELOG 记这批 CI 改动的改了什么与怎么验收
新增陷阱(只追加、不复用旧号):
trap-8 gofmt -l 列出文件时退出码仍是 0(只看退出码=假绿);
trap-9 tar -C dir . 产生 . 根成员 ⇒ 预览 404 而流水线显示成功;
trap-10 依赖清单被静默改写(-mod=mod、缺锁回落 npm install);
trap-11 汇总把"未运行/被跳过"当"通过";
trap-12 事件 SHA 与检出 SHA 不一致;
trap-13 密钥扫描规则过宽 ⇒ 永远的假红,最后被人整条注释掉。
(trap-13 来自实做:第一版规则用很宽的字符类抓口令段,把 postgres://{u.quote(...)} 这类
 模板表达式和 *** 脱敏也当成密钥,四条全是假阳性。收窄口径并把这些形状钉进良性对照防回归。)

AGENTS.md 的现状表需要同步(写着"main 已启用分支保护",实测 GET /branch_protections = [])——
该文件受写入保护,本次未改,修正稿另存待批准后应用。

验证:python3 scripts/check_changelog.py 结构自检通过;make verify 全绿。
2026-10-12 00:11:10 +08:00
姚章浩 1f74794696 test(ci): 加反向验收夹具(21 条,逐条证明门禁真的会红)
一个"永远返回 0 的校验器"比没有校验更糟 —— 它给人一种已经检查过的错觉。
所以每条判据都要有反例,而且反例必须在**隔离副本**里做,不往日常 main 推故意失败的提交。

scripts/ci_negative_fixtures.sh 的两道保险:必须显式设 CI_NEGATIVE_FIXTURE=1,
且工作区有 origin 远端时拒绝运行。逐项做完即恢复,并断言恢复后会重新变绿。

覆盖:格式(Go / 前端各一条)、前端用例失败、变更记录缺日期、版本用例被 SKIP(变异测试)、
缺锁文件、例外表缺失、合成密钥、事件 SHA 错配、必需项未运行不得报全绿(全量跑一次看 not_run)、
通知不可达不改质量结论、汇总报告缺失必须非 0。

实测(在 /home/zheromiku/.hermes/cache/scratch/kg-neg 的副本里,副本无 origin):
21 条全部符合预期、0 失败,夹具退出码 0。

顺带修掉一个真问题:夹具第一稿把"注入路径写错"改在 build-go 那一处(同名但无关),
于是看起来"契约没红"—— 其实是夹具没生效。现在断言注入点在文件里唯一命中。
2026-10-12 00:11:10 +08:00
姚章浩 46cd30e4f9 ci(workflow): 单作业 + 固定事件完整 SHA + 预览门禁 + 通知旁路;删掉假成功的部署占位
原来的 build.yml 有两处硬伤:
① 检出取的是"当时的分支 HEAD"(git fetch --depth 50 origin $BR + checkout FETCH_HEAD),
   事件之后若又有人推一次,跑的就是另一个提交 —— 报告里的"成功"没有对应提交。
② 末尾那个 deploy:test 作业会打印 TODO 然后返回成功:网页上看起来部署过了,实际什么都没做。

改法:
- 检出**核对**到事件完整 SHA(先按分支取,不一致就按精确 SHA 取,再取不到直接红)。
- 单作业串行:检出 → 环境与工具链(缺什么一次性报全)→ make verify → 预览 → 通知。
  单作业是有意的:跨作业传状态要靠 /tmp,而那个"契约"从来没保证过。
- 预览只在报告里 overall_status==success 时发布,并且断言报告 SHA == 事件 SHA、
  产物包里真的有 index.html、报告里给出的每个地址都探测到 200。
  打包不再产生 `.` 根成员(原来会,症状是通知发了、预览 404)。
- 通知用 if: always(),通知失败**不改质量结论**;只有"汇总报告读不到/解析不了"才非 0。
- 依赖清单在编译前后各取一次摘要,被任何一步改写即红(防 GOFLAGS=-mod=mod 与缺锁回落)。

验证:YAML 解析通过(触发 push/workflow_dispatch、单作业 build、5 步、无部署作业);
ci_report.py 对合成报告实跑:通知不可达时退出码 0 且 notification_status=failed,
报告缺失时退出码 1(不能报绿)。部署未涉及,本仓**未部署**。
2026-10-12 00:10:51 +08:00
姚章浩 a3a1319a11 feat(ci): 唯一权威门禁 make verify(14 项必需检查,汇总不认"未运行")
一次性把本地与 CI 的门禁收成一条命令:make verify = python3 scripts/ci_checks.py。
两边跑的是同一份逻辑,不再各写一套步骤(两边各写一套的结局是迟早只改一边)。

14 项必需检查:identity(检出 == 事件完整 SHA,只在 CI 必需)、commits、deps-install、
format、static-go、static-web、build-go、build-web、tests-go、tests-web、contracts、
security-secrets、security-deps、manifests-locked。make list 打印清单。

三条判据写死在代码里:
- 失败即停,但剩下的记 not_run 并如实写进报告;aggregate() 只认 success,
  未运行/被跳过都不算通过(不适用要在清单里声明 required_in,不许运行时悄悄 skip)。
- 工具缺失、依赖没按锁装、输出解析不了 ⇒ 失败,不当成"检查通过"。
- 测试必须真跑:go test 加 -count=1 并盘点通过/跳过数;前端读 vitest 的 JSON 报告,
  空套件不算通过。跳过原因会打进报告(当前 72 个集成用例因缺 TEST_DATABASE_URL 跳过)。

新增四个自带反向自检的脚本(--self-test 故意弄坏必须红):
scripts/check_format.py(Go 判输出而非退出码 + 前端只能减的基线)、
scripts/check_secrets.py(只打印位置与类别,绝不打印值)、
scripts/check_deps_vuln.py(govulncheck 锁 v1.1.4 + npm audit 分级 + 到期例外)、
scripts/ci_checks.py(门禁 + 汇总)。

验证(本机实跑,全部为真实退出码):
make verify → 总体 success(档案 local),identity=skipped 已在清单里声明为 CI 必需;
tests-go 执行 31 个包、通过 549 / 失败 0 / 跳过 72;tests-web 106 个套件、191 个用例全过;
security-deps:govulncheck v1.1.4 0 命中、npm audit 生产与全量均 0。
2026-10-12 00:10:51 +08:00
姚章浩 2fcd0ed684 build(web): vite 7.3.7 + vitest 5.0.3 清依赖漏洞,并加入 prettier
npm audit 全量原本报 2 critical + 2 high + 1 moderate,全在开发/测试链上
(vite dev server / vitest / tinypool / @vitest/mocker / source-map-js)。
不能靠"只记例外"糊过去:例外要人批,而这里是能真修的。
升到 vite 7.3.7 + vitest 5.0.3 后 audit 全量 0 命中,191 个前端用例仍全过。

同时锁 prettier 3.9.10 并加 format / format:check 脚本 —— 前端格式从此有门禁。
存量格式债(79 个文件,多为刻意压行的紧凑写法)记入 .prettier-baseline.json:
列明、只能减、2026-12-31 到期,新欠账一律判红(见 scripts/check_format.py)。

为什么不做全量格式化:一次性重排约 2 万行,会把"接入 CI"变成"重写前端";
那件事留作独立提交,由人决定何时做。

验证:前端 191 个用例全过、tsc 类型检查通过、vite 构建通过、npm audit 全量 0;
prettier --list-different 的输出与基线完全一致。
2026-10-12 00:10:31 +08:00
姚章浩 c04abd6530 style(go): 清掉存量 gofmt(6 个文件的字段对齐与文件末尾换行)
接入格式门禁前先量了一次存量:gofmt -l 在 295 个被跟踪的 .go 文件里报 6 个,
全是字段对齐与缺文件末尾换行这类机械问题。先一次性清干净,门禁接上后 Go 侧一条都不欠。

为什么独立一个提交:格式清理混进功能改动会让 diff 无法 review(正本要求存量清理独立提交)。
验证:gofmt -l 对被跟踪的 .go 文件输出为空;go vet 与 go test 全过。
2026-10-12 00:10:31 +08:00
姚章浩 5f3a71cade feat(version): 版本号唯一来源 = CHANGELOG.md,并要求写清改了什么与怎么验收
build / build (push) Successful in 26s
背景:本仓此前没有任何版本/构建元信息 —— 没有 ldflags 注入、也没有产物可读的
版本号,"线上跑的是哪个提交"答不出来;"这次改了什么、怎么验收"也没有载体。

落地:
- CHANGELOG.md:**版本号的唯一来源**(正本 §6.1:版本号只准有一处)。刻意不放
  VERSION 文件、也不靠 git tag —— CI 是 `git fetch --depth 50`,取不到 tag,
  `git describe` 会静默退化。每个已发布版本必须有两节:### 改了什么 与 ### 怎么验收。
- scripts/version.py:从 CHANGELOG 顶部解析版本号;解析不到即非 0 退出(构建据此失败)。
- scripts/check_changelog.py:结构自检(两节齐、带日期、版本号不重复且严格递减、
  小节不为空),带 --self-test 反向自检。
- internal/version:三个构建期注入变量 + 契约测试(注入的号必须等于 CHANGELOG 顶部)。
- Makefile:build 带 -ldflags 注入;verify 增加 changelog-check 与 version-contract。
- Dockerfile:ARG VERSION/COMMIT_SHA/BUILD_TIME + ldflags(未透传时落 dev —— 故意显眼,
  好过看起来正常的假版本号)。
- CI:新增「版本与变更记录契约」步,并显式断言契约测试真的 PASS(被跳过的断言等于没有断言)。
- docs/提交规范.md(ci_gate.py 的报错文案一直在指它)、docs/agents/traps.md(7 条实测陷阱)。

验证(都真跑过):
- make version → 0.1.0;make changelog-check → 合规
- make version-contract → PASS;注入 9.9.9(CHANGELOG 里没有)→ FAIL(反向自检)
- 删掉真实 CHANGELOG 的「怎么验收」小节 → 报红(对真实文件做,不只是夹具)
- go build ./... 与 go vet ./internal/version/... 通过

未做(会与在审 PR #2 冲突,待其合并后在 main 上补):
- GET /version 端点(internal/httpapi/server.go)与 cmd/api 的 -version 开关
- compose.yaml 透传 build args(当前由 compose 构建的镜像会报 dev)

⚠️ 未跑 make verify 全量(含 go test ./... 与前端),CI 是本次的测试证据。
2026-10-10 18:13:24 +08:00
姚章浩 63db2b8d1e fix(gitignore): 真正加上根级 node_modules 规则并撤出该产物
build / build (push) Has been cancelled
上一提交(fc9dd4c)有两处不成立,这里如实纠正:

1. 规则没加上。判断写成了 `"/node_modules/" not in 全文`,而
   `/web/node_modules/` 里就含这个子串 ⇒ 误判为"已存在",跳过了追加。
   改成对整行集合判断。
2. 产物没撤出。`git rm --cached node_modules` 之后又跑了 `git add -A`,
   而此时根级 node_modules 还没被忽略 ⇒ 文件被原样加回索引,净效果为零。
   正确顺序是:先让忽略规则生效,再撤出索引;否则 add -A 会把它搬回来。
   (8 个 .pyc 当时确实清掉了,因为 __pycache__/ 规则本来就在。)
3. 上一提交正文里"验证:git ls-files 里不再有 …"当时是不成立的。

验证(本次真跑):git check-ignore 命中 /node_modules/;
git ls-files 里 node_modules / __pycache__ / .pyc 计数为 0。
2026-10-10 17:43:13 +08:00
姚章浩 4f70aca10d Merge origin/main: 并入 AGENTS.md 指针(PR #1)
build / build (push) Successful in 28s
2026-10-10 17:42:10 +08:00
姚章浩 fc9dd4c328 chore(gitignore): 补根级 node_modules 规则,撤出已入库的构建产物
根级 node_modules 没有被任何规则覆盖(只写了带斜杠的 /web/node_modules/,
只管 web 下),于是 node_modules/.vite/vitest/.../results.json 随 a1b46d2
进了库。另有 8 个 scripts/__pycache__/*.pyc 是历史遗留 —— 规则在,但
.gitignore 对已入库文件无效(正本 §1.4-1)。两者一并撤出,保留磁盘文件。

验证:git ls-files 里不再有 node_modules / __pycache__ / .pyc。
2026-10-10 17:42:10 +08:00
姚章浩 d2856fd56f refactor(settings): 下线「+ 新增钉钉知识库」按钮,新增入口只剩勾选列表
用户:新增钉钉知识库可以去掉按钮了 —— 数据源发现面板已经能列出账号下所有可见的知识库与
钉盘空间,粘贴链接那条路不再需要,留着只是两个入口做同一件事。

- 删除 系统设置 → 数据源配置 标题上的 DingtalkSpaceRegistrar 及其组件/测试文件(不留死代码);
  标题文案改为「从下方「可加入的来源」勾选即可登记新来源」。
- 登记的 API 客户端(registerDingtalkSpace / 扫码会话续登)保持不变:发现面板仍在用。
- 回归断言:数据源配置页不得再出现「+ 新增钉钉知识库」。

测试:前端 191 条(少 1 条 = 被删组件的测试)+ tsc 干净。
面板实测:按钮消失,勾选列表照常(ATOM知识库/视觉文档/公司级技术支持知识库/技术诊断部知识沉淀/
公司级营销资料管理 已标「已是来源」)。
2026-10-10 17:21:31 +08:00
姚章浩 1283f65a95 feat(catalog): 首次扫描中的来源也出现在「来源与目录」,并显示实时进度
用户反馈:加了钉盘来源后「来源与目录」里看不到。根因不是丢数据,而是列表只列"已经有快照"
的来源 —— 首次扫描要几分钟到几十分钟(钉盘空间 2900+ 个文件夹),这段时间页面上什么都没有。

- 新 Store 方法 ListCatalogScanProgress:已启用 + 还没有 catalog head + 有在跑/排队的
  source.catalog.refresh(三条件同时成立)。进度直接取 worker 写在任务载荷里的同一份计数
  (progress/message/scanned_directories/discovered_directories/scanned_files),不另立口径。
- /api/v1/source-catalog/sources 在既有列表后追加这些行(snapshot_status="scanning" +
  scan_progress/scan_message)。走窄接口按需接线:未接线时安静跳过,不会把旧列表弄坏。
- 前端:左列显示「首次扫描中 44%」,选中后是进度面板(百分比 + 进度条 + 当前文案 +
  已发现文件数),并说明"扫完自动出现目录";有来源在扫描时每 3 秒自动刷新列表,
  扫完那一行自动变成「本地只读快照」。扫描中不拉目录节点、也不显示标注/格式入口。
- 解析器保持严格:snapshot_status 只接受 ready/scanning,scanning 必须带 scan_progress,
  否则整包拒绝 —— 不给"假装 0%"的机会。

测试:postgres 集成测试(真库)覆盖四种不该出现的来源(停用、已有快照、任务类型不符、
历史上已完成的那次任务);前端 parser + 渲染各一条;Go 全绿、前端 192 条 + tsc 干净。

面板实测:左列「公司级营销资料管理 · 首次扫描中 44%」,主区「首次扫描中 · 44% /
正在扫描目录:已完成 1540 个文件夹 / 已发现约 4934 份文件」。
2026-10-10 17:04:59 +08:00
姚章浩 ed60b20790 docs(acceptance): 补 C9 数据源配置(列出来→勾选→变成来源)实测记录 2026-10-10 16:47:06 +08:00
姚章浩 e00cab2f70 feat(settings): 数据源配置改成「列出来、勾选、变成来源」,并去掉文件格式筛选
用户对 系统设置 → 数据源配置 的四条要求:
① 这里不要做文件格式筛选(格式归目录级标注决定);
② 列出我账号下能看到的知识库;③ 列出钉盘能看到哪些;④ 勾选那些作为来源。

① 来源卡片不再渲染 FilenameFilterEditor(目录级筛选仍在「来源与目录」里,按目录就近覆盖)。
②③ 新端点 GET /api/v1/dingtalk-spaces/available(管理员,只读):用 dws 列举
   - 知识库:wiki +space-list --type orgWikiSpace/myWikiSpace(实测 17 + 1 个)
   - 钉盘:wiki space list --type mySpace/orgSpace(实测 我的文件 + 6 个组织空间)
   实测约束写进命令形态:--limit 上限是 50;翻页必须 --page-all(--max-items 兜底),
   否则超过一页的知识库会被静默截断(被截断时页面显示"可能不全"而不是假装列全)。
   列不出来 ≠ 空列表:dws 未登录/权限不足 → 503 + 原因;某一类失败只丢那一类。
④ 面板勾选后走既有登记路径(/api/v1/dingtalk-spaces),首次目录扫描自动排队;
   已登记的按空间名标「已是来源」并禁用勾选;扫码会话失效时直接弹二维码,扫完自动重试。

基础设施:api 与 worker 共享同一份 dws 状态(bind mount 同一份,refresh token 是轮换制,
不能各留一份)。子进程 HOME 必须指向 DWS_HOME —— 这条是实测踩出来的:漏了会报"未登录",
已有回归测试钉住。dws 子进程沿用白名单环境,库口令等变量不进子进程。

测试:新包 internal/dingtalkdiscovery(fixture 用真实 dws 输出形状):paging 约束、
截断提示、一类失败不连带、全部失败→ErrUnavailable、子进程环境;httpapi 侧 401/501/503/500
与不泄漏内部错误;OpenAPI 契约(400/503 组件)通过。前端 189 条 + tsc 干净。

面板实测:知识库(18)/钉盘(7)都列出来,已有三条钉钉来源自动标「已是来源」;
勾选「视觉文档」→ 加入为来源 → 新来源 sc-8a4be5b8293d1c9a048c3c7e9b194155(dingtalk,enabled)
+ source.catalog.refresh 已完成。
2026-10-10 16:46:39 +08:00
姚章浩 eca7fee5a8 refactor(release-ui): 发布页改成三块 + 一个折叠抽屉,删掉全部步骤脚手架
用户反馈「界面还是没优化,步骤太多」。上一轮只把动作合成了一键发布,但页面上仍铺着
7 步流程条、步骤编号、引导卡、分区页签和统计卡——用户看到的是"还有很多步要做"。

- 默认视图只剩三块:生产状态条 → 待发布(主操作,每行「发布到生产」+ 批量)→ 发布记录
  (查看结果/重排/回滚)。
- 待审核仅在有待审条目时出现(对内已自动批准,happy path 上通常不出现);已驳回收进折叠。
- 发布计划、下架选择、冻结清单、批次清单全部收进「<details>更多」,仍是完整能力,只是不再挡路。
- 删除 7 步流程条、步骤编号标题、引导卡、分区页签、四格统计卡。
- 保留全部安全信号:门禁/快照状态条、执行阶段与批次进度、审核策略说明、删除二次确认、
  固定确认语句弹窗、"锁定清单 ≠ 上线"。
- 测试:新增"步骤脚手架不得出现"回归断言(7 步流程条/步骤编号/引导卡/页签 class 一律不得渲染);
  183 条前端测试 + tsc 全过。

自测(面板实测):待发布里点「发布到生产」→ 输 publish-to-production → 确认 →
批次 rb-7088588bac30a109cfaae357d4095ffe(sealed) + 执行 rx-bceb1ca9c1ecdd088e541bad2ebe9d7f
(completed 1/1,项级 verified、production_revision=rv-934f2a64724611e0f50cccadf9a30f87);
再在页面上回滚 → rx-2618de118a7efabea34cdb8fdb384c20(rolled_back 1/1、项级 absent)。
2026-10-10 16:05:51 +08:00
姚章浩 f8faed0b21 feat(release): 发布到生产一键完成(建批+锁定+授权合成一个动作)
用户的反馈是对的:上一轮只砍掉了"冻结/锁定"两个按钮,但一条文档从"已批准"到"发出"实际仍要
~9 次交互(找条目→勾选→填名→建批→滚到清单→找批次→授权→输语句→提交),因为"批次仪式"本身
还留在路径上。

- 新端点 POST /api/v1/release-batches/publish-now:在同一操作里先建批(SealImmediately,冻结
  即锁定)再授权生产发布,返回 {batch, execution}。
- 不放松任何约束:请求门禁(403)、备份恢复验证门禁(412)、管理员身份(401)、固定确认语句(400)、
  发布前快照硬门禁(409)、建批门禁(422) 全部沿用既有实现,无旁路;名称可省(服务端固定回退名,
  保证重放指纹一致)。
- 界面:审核行上直接「发布到生产」(管理员 + 门禁开启时显示),工具栏支持选中多条一次发布;
  复用既有确认弹窗(固定语句)。批次名不再是必经步骤。
- 实测(面板):点行级按钮 → 输 `publish-to-production` → 提交 → 批次 rb-bee80550…(sealed)
  + 执行 rx-3d831129…(completed, 项级 verified) → 页面回滚 rx-43835fac…(rolled_back, absent)。

测试:publish_now_test.go(四道关卡 + 组合调用 + 名称回退)与 reviewRelease.test.ts(请求体/回传/错误原因);
Go 26 包、前端 183 条全过。
2026-10-10 15:48:30 +08:00
姚章浩 70131c6161 feat(release): 批量审核 + 建批即锁定 —— 发布管理单文档交互降到 3~4 次
P0-3:
- 批量审核:新增 POST /api/v1/review-candidates/batch-decision,逐条复用单条审核的写入
  路径(同一套合法性校验与"最新验收轮次"绑定),逐条回报 decided/skipped/skipped_ids;
  不可审核的条目只计入 skipped,不打断整批,其他错误整批回滚(不留半成品)。
  界面新增「全选可批准」「批量批准选中」「批量驳回选中」。
- 建批即锁定:建批请求加 seal 字段,服务端在创建后立即执行既有的密封(仍逐项复核门禁,
  失败整批回滚),草稿态不再单独占一步;界面按钮改为「创建并锁定清单」,流程说明从 8 步改 7 步。
- 判据修正:「可批准」原先把已驳回的算进去(review_state !== 'approved'),改为只含 pending + 门禁通过。

语义边界(写进测试):批量批准按人工身份记录,人工可推翻自己先前的驳回;system:auto 发起的
批量批准对人工驳回过的那条必须跳过(Decided=0/Skipped=1)——机器永远不覆盖人工。

测试:review_batch_integration_test.go(批量决定/跳报/重复 id 拒绝/机器不覆盖人工、
建批即锁定)、review_batch_test.go(幂等键、400/409/500/501 映射、服务端盖操作人)、
reviewRelease.test.ts(批量请求体与逐条回报、建批带 seal)。前端 181 条通过。
2026-10-10 15:29:31 +08:00
姚章浩 c83a6c8086 docs(runbook): 发布准备改为「勾选 → 建批 → 锁定」(建批时冻结 + 对内自动批准),并补 C6 实测 2026-10-10 15:06:44 +08:00
姚章浩 acf053faf3 feat(release): 建批时冻结 + 验收通过自动批准 —— 把"每份文档 8 步"砍掉两步并去掉两次卡死
背景:发布管理把"逐条核验"的仪式强加给每一份文档。实测一份文档要 9~11 次交互,
且有两处顺序陷阱(冻结后批准 → 建批 422;生成即固化 → 批准被永久钉住)。

P0-1 建批时冻结:
- CreateReleaseBatch 在未指定版本时,自己把当前实时计划冻结成一份**已确认**版本并绑定
  (同一事务;同摘要复用最近版本,planned 或 confirmed 都可复用,因此同一份计划不堆版本)。
- 语义不变:批一旦建立,清单/摘要/验收轮次/目标库绑定全部不可变、回滚按它走;变的只是
  "谁在什么时候按固化键"——从操作员的手动两步变成建批这一下。
- 效果:去掉「生成新版本」「确认冻结」两步;消灭"批准晚于冻结 → 422"这类顺序陷阱;
  前端不再传版本 id,也不再有"所选知识不在冻结清单里"的阻断。
- 计划→清单项的映射抽成 ChangeSetItemsFromPlan 供两处共用,否则两处算出的摘要不同,
  "同一计划复用同一版本"永远不命中。

P0-2 验收通过自动批准:
- 验收三项结论达发布门槛(knowledge_exists/chunks_present=passed,retrieval_hit 与门槛同
  口径)时,由 worker 写入 reviewer_ref='system:auto' 的批准记录,替代"每份文档点一次批准"。
- 策略 TEST_AUTO_REVIEW_POLICY = off | internal(默认,仅对内)| all;值不认识拒绝启动。
  只影响审核这一步:生产授权、双闸与发布前快照门禁不受影响。界面上只读展示当前策略。
- 安全边界(写死在审核 SQL 里):系统只允许写"第一条"审核——人工一旦表过态,机器不得用一条
  更晚的 approved 把人工结论翻回去;人工随时可再审。集成测试去掉该约束即 FAIL(已实测)。
- 自动批准自身的任何失败都不影响验收结论,只上报。

顺带(P1-1 前半,已被 P0-1 取代的部分已删除):
- 写操作失败把服务端 {"error": ...} 的原因带出来,并对已知原因给出下一步(不再只给 HTTP 状态码)。
- 当前的"不在已冻结清单里"标注与就地修复按钮随 P0-1 一起移除(该失败模式已不存在)。

测试:bind_time_freeze_integration_test.go(绑定已确认版本/同计划复用/冻结后不可变/
动作不符仍 NotEligible)、auto_review_integration_test.go(系统只写第一条、人工可再审)、
validate_test.go(对内自动/对外不自动/策略关闭/验收未过不批/自身失败不影响验收)、
auto_review_test.go、config_test 及前端能力解析测试。
实测耗时:本机 Go 全量 26 包通过、前端 178 条通过。
2026-10-10 15:05:20 +08:00
zheromiku 32b0ec58a6 Merge pull request 'docs(agents): 加 AGENTS.md 操作手册与规范指针' (#1) from docs/agents-pointer into main
build / build (push) Successful in 28s
2026-10-10 15:00:28 +08:00
姚章浩 d025fc9adf docs(agents): 加 AGENTS.md 操作手册与规范指针
build / build (push) Successful in 29s
本仓此前没有任何 agent 上下文文件,代理每次都得重新讲一遍规范。
新增 AGENTS.md:指向系统级规范(zheromiku/eng-standards-main),并写明
本仓已核实的现状(CI 作业链 / runner / 本机运行栈 / main 已受分支保护)。

为什么用 AGENTS.md 而不是 .hermes.md:Codex / Claude Code / OpenCode 读的
也是 AGENTS.md,跨工具可移植。
2026-10-10 14:59:50 +08:00
姚章浩 32450a7c7b fix(web): 建批失败只显示 HTTP 状态码 —— 把服务端原因与下一步带出来
写操作的服务端一直回 {"error": "<原因>"},但 getJSON/sendJSON 只把状态码拼进错误消息,
运维看到的是「创建封批失败(HTTP 422)」,无从下手。实测真实原因只有两种,且都有明确
下一步:所选知识不在已冻结的发布清单里(先「生成新版本」+「确认冻结」)、或所选知识当前
不满足发布条件。现在把原因带出,并对这两种已知原因直接给出下一步;其他原因原样展示。

背景(本次 422 的根因):ATOM群体广播控制方案使用方法.adoc 的批准时间 06:07:05Z 晚于
已冻结版本 v8 的冻结时间 03:23:48Z,v8 的 113 行里没有它的行,绑定校验因此不通过。
发布计划页显示的是实时计划(所以写着"可加入发布批次"),建批绑定的是已冻结版本——两者
不一致时必须先重新生成版本,这条顺带值得在产品上更醒目地提示。

测试:reviewRelease.test.ts 补 2 条(覆盖清单不足时给出下一步 / 未知原因原样带出)。
2026-10-10 14:20:11 +08:00
姚章浩 a1b46d2b7c feat(monitor): 需下架车道可逐条移除测试库知识 —— 补齐最后一个没有页面入口的流程
背景:来源侧被判「禁止导入」后,已建好的测试库知识不会自动消失;此前只有变更集
删除路径会入队 test.remove,页面既列不出条目也没有按钮,运维无法闭环(车道只有按
库计数)。

新增:
- GET /api/v1/test-publications?removal=required:条目级列表,判据与车道计数同源
  (superseded_at IS NULL / 有 knowledge_id / completed / retrieval_state NOT IN
  (disabling,disabled) / policy_state='blocked'),过滤是叠加而不是替换。
- POST /api/v1/test-publications/{id}/removal:engineer 级写路由,要求 Idempotency-Key,
  按条目幂等(operator-remove:<id>);置 disabling 并交既有 test.remove 工作流去删除
  远端知识并读回校验。错误映射 404/409(已移除)/409(不可移除)/501(未接线)。
- 界面:需下架车道逐条显示条目 + 「下架(从测试库移除)」,页内二次确认,成功提示,
  完成后计数归零。

修掉过程中踩到的两个真问题:
1. 二次确认的确认态原先经容器 props 传给视图,一次容器改动把三个 props 丢了 ——
   视图永远渲染原按钮、确认步骤静默消失,而所有静态单元测试仍然通过。改为把确认态
   放在视图内部;并把「取消」放在原按钮位置(真实指针连点两下只会落到取消)。
2. jobs 上有部分唯一索引 UNIQUE (business_change_set_id, business_version_id,
   business_target_kb_id, business_action) WHERE business_change_set_id IS NOT NULL。
   本路径给这三列写空串(非 NULL),('','','','remove') 对所有条目是同一个键 ——
   第一条之后每次 INSERT 都撞唯一索引、被 ON CONFLICT DO NOTHING 静默吞掉,留下
   「状态已 disabling、没有任务」的永久卡死条目,而车道恰好隐藏 disabling,运维也
   看不到。改为写 NULL(语义:无变更集身份)+ 冲突目标收敛到 idempotency_key +
   校验 RowsAffected()(0 行回查既有任务;查不到就报错,不提交无任务的 disabling)。
   卡死状态在重试时可自愈。

测试:internal/platform/postgres/test_publication_removal_integration_test.go(两条发布
各自入队、business_* 为 NULL、卡死自愈;把修复退回旧写法该测试即 FAIL,已实测)、
internal/httpapi/test_publication_removal_test.go(权限/幂等键/错误映射/未接线 501/列表
过滤)、前端 testPublications.test.ts + WeKnoraMonitor.test.tsx。

验收(纯界面,两条都走完):解析监控 → 需下架(2)→ 逐条「下架」+ 二次确认 →
retrieval_state=disabled(PDF 03:57:03Z、md 04:08:55Z),jobs completed(attempt 2,
首次 test_remove_pending=远端仍在处理,重试通过;工作流以 GetKnowledge 读回 404 判
成功)→ 车道需下架(0)。核验「确认前不执行」:首次点击后仍 unpublished、移除任务数仍 1。
2026-10-10 12:10:46 +08:00
姚章浩 e9a643cc33 fix(release): 禁止导入未被算进期望策略 —— 生产知识下不了架(计划与建批两处同源缺陷)
界面验收实测(2026-10-10):把已发布到生产的 PDF 改为「禁止导入」后,发布通道既给不出
delete、也建不了 delete 批次。

根因:禁止导入只写 source_items.policy_state='blocked',而"期望策略"的解析只看
source_item_scope_overrides / directory_scope_rules / source_items.visibility——
两处实现都不看 policy_state:
  1) release_plan.go 的 source_truth:被禁止且生产侧存在的条目被算成 unchanged/present、
     can_release=false → 永远不会出现 delete 动作;
  2) release_batches.go 的 releaseDeleteReadyCTEs.source_truth:同样口径 → 计划即使给了
     delete,创建封批仍被拒 422(实测原文「创建封批失败(HTTP 422)」)。

修复:两处都把 policy_state='blocked' 算进期望策略(各一行,注释写明成因)。
新增集成测试 release_plan_policy_state_integration_test.go:用 policy_state(真实路由的写法)
造"生产存在 + 已禁止"的条目,断言①计划给出 action=delete/can_release、②delete 批次可创建;
分别回退任一处修复,该测试即 FAIL(已实测两种回退都 FAIL)。

实测闭环:重新发布使生产存在(enable_status=enabled)→ 禁止导入 → 计划 delete(present/
can_release=true)→ v8 delete_count=1 → 批次 rb-8c1ad1c9…(sealed, action=delete) → 留档
20261010T033100Z + 门禁 PASS → 执行 rx-6c19232a… completed(项级 verified/delete、
production_revision=absent)→ 目标库该行 enable_status=disabled(行保留、检索停用、可恢复)。

附带:从未导入却被标为禁止的 82 条"等待测试"噪音不再占发布计划(195 → 113 项)。
证据与说明补进 docs/USER_FLOWS_ACCEPTANCE.md(C2b + F.3h)。
2026-10-10 11:36:08 +08:00
姚章浩 fa244c447c fix(deploy): 重建 api 会静默关掉生产门禁 —— 加前置保护 + 门禁状态回显
界面验收第三遍(PDF)踩到:授权发布被回绝 "production release requests are disabled"。
根因:scripts/deploy-api-web.sh 的 COMPOSE_FILES 默认只叠 compose.yaml,重建 api 时没叠
compose.release-gates.yaml → PRODUCTION_RELEASE_REQUESTS_ENABLED / PRODUCTION_BACKUP_RESTORE_VERIFIED
变 false,生产授权接口被静默关闭(页面只在点击那一刻提示一句,极易误判成功能坏了)。

- 前置保护:正在运行的 api 已开闸、而本次 COMPOSE_FILES 不含门禁文件时直接拒绝
  (REFUSED_WOULD_CLOSE_PRODUCTION_GATES,并打印保留门禁的正确命令;确要关闸用 ALLOW_GATE_OFF=1)
- 结尾新增 === 7b 打印重建后的两道门禁状态,避免"以为开着"
- 已用同一段判定逻辑覆盖三种情形(已开闸+不叠门禁→拒绝 / 已开闸+叠门禁→放行 / 显式 ALLOW_GATE_OFF→放行)

验收第三遍同时确认:PDF→MinerU 解析链路是通的(入库 completed、验收"内容处理:通过"),
发布首轮 completed/verified(in_scope=8 foreign=8 降级保留正常),回滚 rolled_back、
目标库 enable_status=disabled。证据补进 docs/USER_FLOWS_ACCEPTANCE.md。
2026-10-10 11:10:51 +08:00
姚章浩 d0a45d563f fix(monitor): 需下架车道恒为 0(判据用了没人写的状态)+ 隔离会改线上设置的集成测试
界面验收第三遍(禁止导入 → 需下架)暴露两处真问题:

1) 需下架车道死掉:判据 `retrieval_state='enabled'`,而 retrieval_state 在这套状态机里
   描述「是否发布到生产」(unpublished/disabling/disabled/failed),全仓没有任何代码写过
   'enabled',线上 5/5 发布单元都是 unpublished → 车道恒 0,界面「仍在知识库里的文件会
   出现在这里」的承诺不成立。改为与设计注释一致的口径:仍在测试库存活(completed + 有
   knowledge_id + 未 disabling/disabled)+ 来源项 policy_state='blocked'。
   线上对照:旧判据 0 → 新判据 1,命中被禁止导入的 DH-AG95夹爪适配-指令协议.md;
   修后页面显示「需下架(1)· 对内知识库 · 1 份仍在检索中」。新增集成测试覆盖
   存活/未禁止/移除中/已移除/未上传五种情形(真实 Postgres + 独立 schema)。

2) 集成测试改到线上设置(直接踩到并已恢复):ui_settings_integration_test.go 只判断
   TEST_DATABASE_URL 是否存在、无 schema 隔离,而它「创建候选并激活」——跑在共享库上会把
   真实 active 设置挤成 retired。已先备份(backups/ui-settings/…pre-restore.jsonl),再用
   单事务(先 retire 再 activate,uq_ui_setting_active 只允许一条 active)恢复
   uis-d40ea1fc…(15/30/1800/7200 + https://weknora-test.dobot.cn/),并复核线上值。
   根因修复:给该用例加 per-test schema 隔离,复跑后线上设置不再被改动。

同时把两处与事实不符的文案改实话(WeKnoraMonitor.tsx 需下架说明、SourceCatalogBrowser.tsx
禁止导入说明):移除走 test.remove 工作流(删除测试库知识条目,可再入库),入口当前由
变更集删除路径触发,页面尚无独立按钮——条目级列表与下架按钮列为待排期。
2026-10-10 10:55:03 +08:00
姚章浩 6a8db9ca98 docs(acceptance): 补第二遍界面验收(.md / drive 直下路由)
- A1:第二遍取件(DH-AG95夹爪适配-指令协议.md,3513 B)与内容级 sha256 去重的核对方法
  (content_objects 命中已有行时只更新 updated_at,不更新 created_at;必须走
  source_item_versions.content_object_id 关联,不要按 created_at 过滤)
- B1:tp-466164a074cb22efb → completed(polls=8,测试库 0c84a098…)
- C1:v4 rcs-2b22276e…(新增3/阻断193)+ 批次 rb-f1819fb0…(sealed、1 项)→ 再证「批准后才生成」顺序规则
- C2:留档 20261010T023538Z-0b217e8a + guardcheck PASS + 执行 rx-bc714172… 首轮 completed/verified
- C3:回滚 rolled_back + 独立核对目标库 enable_status=disabled(行不删)
- F:新增待办 3e——发布结果页不自动刷新(worker 已完成仍显示待执行,需手动刷新)
2026-10-10 10:41:49 +08:00