Commit Graph

132 Commits

Author SHA1 Message Date
姚章浩 828c2c5fa0 feat(qa-ops): 按确认口径补齐质量比例与分母明细
build / build (push) Successful in 1m6s
使用完整筛选范围的当前有效结论计算覆盖率和正确率,人工优先,失效与对应待确认/未评估/不计入排除;零分母返回null,界面展示原始分子分母和排除构成,前端拒绝不守恒或比例不一致的响应。

验证:make verify退出码0,Go658及前端257通过,91项声明可选集成跳过;隔离PG、三包竞态及合成/真实只读源浏览器验证通过。无新增迁移,不接AI模型,不改绩效,不写源库;本批未推送或部署,8088运行版保持0.1.21。
snapshot/v0.1.22
2026-10-18 02:00:31 +08:00
姚章浩 4b3aaff321 feat(qa-ops): 完成复检留档与人工复核闭环
治理侧保存输入观测版本、自动复检及人工复核历史,输入变化失效、版本冲突和幂等重放不覆盖人工记录。批量质量数量使用完整筛选元数据,未采集原文不伪造快照,延迟旧扫描不回退新输入。

验证:全仓 make verify 退出码0,Go656及前端253通过;五包竞态、源/组织/质量隔离PG、真实只读源和隔离网页读回复核通过。默认91个可选集成跳过不计通过。未接AI模型,不写DobotAI源库,未推送、未合并、未部署。
snapshot/v0.1.21
2026-10-17 22:37:26 +08:00
姚章浩 9556db1ef0 feat(qaops): 增加个人自然月用量与零记录人员明细 snapshot/v0.1.20 2026-10-17 19:59:33 +08:00
姚章浩 56b8cabed9 feat(qaops): 接入问答组织补全与区域使用统计 snapshot/v0.1.19 2026-10-17 19:02:13 +08:00
姚章浩 cc4906b6a9 feat(qaops): 接通网页通讯录持久化同步与后台接管 snapshot/v0.1.18 2026-10-17 17:36:07 +08:00
姚章浩 6adfdcdd4f fix(qaops): 修复长部门路径挤出区域与依据列 snapshot/v0.1.17 2026-10-17 16:24:00 +08:00
姚章浩 5874134e04 feat(qaops): 接入真实通讯录采集并补全根部门 snapshot/v0.1.16 2026-10-17 16:11:29 +08:00
姚章浩 dab74b706b feat(qaops): 增加版本化部门区域归属配置与预览 snapshot/v0.1.15 2026-10-17 11:39:38 +08:00
姚章浩 fd04bf7886 feat(qaops): 接入独立只读问答查询与治理覆盖复检 snapshot/v0.1.14 2026-10-17 09:04:19 +08:00
姚章浩 c1d49adb62 docs(agents): 补三Agent交接闭环工作流(状态机、快照tag与验收模板)
build / build (push) Successful in 53s
工单 #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)。
snapshot/v0.1.1 snapshot/v0.1.13
2026-10-14 17:33:22 +08:00
姚章浩 9a8a3e7795 fix(dingtalk): 登记钉钉知识库 409 space_registration_conflict —— 归档行占名 + 错误被吞
build / build (push) Successful in 57s
现象:点「公司级技术支持知识库」登记,返回 HTTP 409:space_registration_conflict。

根因(真数据取证):
- source_connections.name 有唯一约束。这 3 个钉钉来源是**早期路径**登记的
  (base_url 为空,id 与 dws 现在推导的确定性 id 不同):
  sc-18d10ca0… 公司级技术支持知识库 / sc-eaef0ec1… ATOM知识库 / sc-dc7cea1c… 技术诊断部知识沉淀。
- 上一步「去掉来源」只是归档下架,**名字仍占着唯一槽位** ⇒ 重新登记时 INSERT 撞
  UNIQUE(name)。
- 处理器把**所有**存储层错误都翻译成同一个 409 space_registration_conflict(真实原因被吞)。

修复:
- store:同名的另一行若**已归档** ⇒ 改名腾位(`…(已下架 · <短ID>)`,归档行不显示,
  数据与审计一行不动);若**仍在使用** ⇒ ErrDingtalkSpaceNameTaken(绝不悄悄改名)。
  同一个登记键解析到别的 root 时:在用中的行报 ErrDingtalkSpaceIdentityConflict;
  归档过的行允许就地改写("去掉后再用 dws 重新获取"的语义)。
- httpapi:分类映射 —— space_name_conflict / space_identity_conflict(409 + 可行动 hint),
  其余内部故障改回 500 space_registration_failed,不再伪装成冲突。
- web:读一次响应体同时取 error 与 hint,**hint 优先**;补两个新码的中文说明。

验证:真 postgres 集成测试复刻线上形态(旧行占名 + 归档 ⇒ 登记成功、旧行改名保持归档、
内容不丢;同名在用 ⇒ 拒绝;同键换 root 在用 ⇒ 拒绝、归档 ⇒ 就地改写);handler 分类测试
(409/409/500,且不回显内部细节);前端 hint 优先用例;make verify 15/15。
snapshot/v0.1.12
2026-10-14 12:59:52 +08:00
姚章浩 2c7265efc4 feat(sources): 数据源配置收敛成 dws 导入 + PP 导入;「去掉来源」= 归档下架(不删数据)
build / build (push) Successful in 58s
主人要求:去掉入口,统一成 dws 导入与 PP 导入;其他来源连数据一起下架,之后用 dws 重新获取。

界面(web):
- 「数据源配置」只剩两块:**dws 导入(钉钉)**(按当前钉钉账号列出可访问的知识库与钉盘空间)
  与 **PP 导入**(PP 资料下载中心)。上一步加的「显示 AList/钉钉知识库来源」折叠开关删除。
- 来源卡片新增管理员可见的「去掉来源」(带确认弹窗,说明是归档下架、数据保留可恢复)。
- 侧栏文案改成"只留两个入口";发现面板标题改为「dws 导入(钉钉)」。

后端(归档语义,可逆):
- 迁移 000047:source_connections 增 archived_at / archived_by + 只覆盖未归档行的部分索引。
- store:ArchiveSourceConnection / RestoreSourceConnection(幂等;归档同时停用并清空
  next_refresh_at,避免被手工改回后立刻带着旧调度跑)。列表、目录、计划刷新(claimDue)、
  手动扫描(triggerBlock/inspect)四类查询一律排除归档行。
- 注册路径(dws 重新获取):RegisterDingtalkSpace 的 ON CONFLICT 清掉归档标记 ——
  重新登记同一个空间**原地复活同一行**,不产生重复,历史快照仍属于同一行。
- HTTP:POST /api/v1/source-connections/{id}/archive|restore(管理员专属,写意图头
  source-archive / source-restore + Idempotency-Key;404 区分"不存在"与"已是目标状态");
  openapi 同步两条契约。

验证:
- 集成测试(真 postgres):归档从列表消失但 source_items 一行不少、重复归档不漂移归档时间与人、
  未知 ID 报 ErrSourceConnectionNotFound、归档来源不能再被扫描、恢复后回到列表但保持停用;
  dws 重新登记同一空间复活同一行。
- httpapi:写意图/幂等键门禁、200/403/404/500、错误体不回显内部细节、classifyRole 管理员专属。
- 迁移护栏:000047 结构 + 四类 SQL 必须含 archived_at is null(漏一条就是入口没去掉)。
- make verify 15/15。
snapshot/v0.1.11
2026-10-14 12:36:32 +08:00
姚章浩 64b32c2da6 feat(settings): 数据源配置默认只列 PP 资料 + 「可加入的来源」
build / build (push) Successful in 53s
主人要求: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。
snapshot/v0.1.10
2026-10-14 12:01:47 +08:00
姚章浩 b7f7e4f121 fix(deploy): 上线前校验 .env 键值形状(两行粘成一行的坏值不再能上线)
build / build (push) Successful in 1m1s
事故复盘(2026-10-14,测试实例 p1 整体不可用约 6 分钟):
- 我用 `rstrip("\n") + 新行` 往 `.env` 追加 `VERSION_HISTORY_LINK_ORIGIN`,而 `.env` 最后一行
  当时没有结尾换行 ⇒ 两行**粘成一行**:
  `VERSION_HISTORY_GITEA_BASE_URL=http://192.168.50.223:3000VERSION_HISTORY_LINK_ORIGIN=https://gitea.zheromiku.top`
- 配置校验按设计拒绝这个非法 origin ⇒ `cmd/api`/`cmd/worker` 启动即退出 ⇒ 容器 crash-loop
  (fail-closed 是对的,但代价是平台起不来)。

修复:
- `scripts/deploy-api-web.sh` 新增 **1a 步护栏**:上线前解析 `.env`,只要某行的值里又出现 `KEY=`
  (两行粘连)或键名不合法 ⇒ 打印 `ENV_VALUE_LOOKS_MERGED` 并**拒绝部署**(不动线上);
- `internal/appconfig` 在校验失败时补线索:值里含 `=` ⇒ 提示"`.env` 里两行可能粘成了一行";
- 回归用例 `TestLoadRejectsMergedVersionHistoryEnvValue`(粘行必拒 + 线索文案 + 合法值仍放行)。

验证:护栏对"粘行样例/键名非法"退出码 1、对"正常样例/当前真实 .env"退出码 0;Go 用例通过;
make verify 15/15。线上已修 `.env` 并重启 api+worker(healthy),重新同步后页面链接已全部走公网 origin。
snapshot/v0.1.9
2026-10-14 11:17:35 +08:00
姚章浩 4cb5110845 fix(version-history): 页面链接改走公网 origin(抓取仍走内网)+ tag 补链接
build / build (push) Successful in 1m1s
现象(主人反馈):点「查看提交」打开是空白页。原因:链接用的是**抓取用的内网地址**
(`http://192.168.50.223:3000/...`),内网外的浏览器到不了;而公网地址
`https://gitea.zheromiku.top/...` 实测 200。另外 tag 证据里**根本没有 url**,
页面渲染出空 `href`,点下去像"没反应"。

修复:

- 新增 `VERSION_HISTORY_LINK_ORIGIN`(页面链接 origin,公网;留空 = 与抓取 origin 相同):
  抓取仍匿名走内网白名单地址,**给人点的链接**用公网 origin 拼 —— 两者本就不该共用一个地址;
  校验必须是干净的 http(s) 绝对地址。
- tag 证据补 `url`(`<link origin>/<repo>/src/tag/<name>`),并在前端**没有链接就不渲染**该按钮。
- 测试:客户端(LinkOrigin 生效 / 未配时退回 / 非法拒绝)、规则(tag 链接写入证据 / 无基址不编链接)、
  前端(有链接才渲染「查看 tag」)。

验证:make verify 15/15;真实链路重同步后库里 commit_url = `https://gitea.zheromiku.top/...`(200)、
release_tags 带 url。
snapshot/v0.1.8
2026-10-14 11:06:13 +08:00
姚章浩 90db243a68 fix(web): 旧 index.html 的哈希资源回退到「上一版构建」,页面不再空白/裸奔
build / build (push) Successful in 56s
现象(主人反馈:页面**偶尔**变成"只有文字没样式"):旧入口 index.html 引用的是上一版的
`index-CddbQIqQ.js` / `index-DLg1Y9tN.css`,而新镜像里只剩当次构建的两个文件
⇒ JS 404 白屏、CSS 404 只有文字没样式。触发条件是"短时间内多次重建 web + CDN/浏览器还拿着旧入口"。

修复(三层,各管一段):

1. **入口不缓存**(上一笔已做):`index.html` → `no-cache, must-revalidate`,CDN/浏览器每次回源校验;
2. **旧哈希资源仍可取**(本笔):`/assets/` 未命中时先回退到只读挂载的
   `deploy/legacy-assets/assets`(**上一版构建**的资源),再 404 ⇒ 还持有旧入口的客户端
   不会因为一个文件 404 而白屏/裸奔;该目录由 `scripts/deploy-api-web.sh` 在**每次重建前**
   从"正在运行的那个镜像"里落盘(`LEGACY_ASSETS=` 会打在部署日志里),并加进 .gitignore;
3. **未命中不再回退成 HTML**:避免浏览器把 index.html 当 JS 执行报一堆语法错误。

验证:旧入口的两个引用 `assets/index-CddbQIqQ.js`、`assets/index-DLg1Y9tN.css` 现在都是 200
(旧客户端可用);当前入口的 `assets/index-Dbnd-DW-.js`、`assets/index-Bgkt4A1i.css` 也是 200;
不存在的文件名仍明确 404;`nginx -t` 通过;本机 8088 与公网入口 kg.zheromiku.top 一致;make verify 15/15。
snapshot/v0.1.7
2026-10-14 10:58:01 +08:00
姚章浩 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