Files
knowledge-governance/CHANGELOG.md
T
姚章浩 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

7.1 KiB
Raw Blame History

变更记录

这个文件就是版本号的唯一来源。 正本 §3.1 要求"版本号只有一个来源",所以这里不放 VERSION 文件, 也不靠 git tag(CI 是 git fetch --depth 50,取不到 tag ⇒ git describe 会失败)。

用法与断言(都可复现,别手抄版本号):

python3 scripts/version.py            # 打印顶部那个「已发布」版本号
python3 scripts/check-changelog.py    # 结构自检:每个版本都要有「改了什么」「怎么验收」

构建时用 -ldflags "-X knowledge-governance/internal/version.Number=<号>" 注入, CI 断言"二进制报出的版本 == 本文件顶部"。没有条目 ⇒ 解析失败 ⇒ 构建红, 所以"忘了记变更"这件事过不去。

每个已发布版本必须有两节:### 改了什么 与 ### 怎么验收。 缺任一节 check-changelog.py 报红(CI 会跑它)。

纪律:最新版本在最上面;版本号只增不减(回退走部署层,不改这个文件); 日期写 YYYY-MM-DD;## [Unreleased] 段可以只有「改了什么」。

[Unreleased]

改了什么

  • 待合并:PR #2 —— 批量发布 / 建批即锁定 / 需下架逐条移除 / 数据源勾选改造(23 个提交,80 个文件)
  • 待合并:仓库卫生 —— 撤出误入库的 node_modules/.vite/.../results.json 与 8 个历史 scripts/__pycache__/*.pyc

改了什么(CI 接入这一批)

唯一权威门禁:make verify = python3 scripts/ci_checks.py —— 一条命令跑完 14 项必需检查、 串行、失败即停,产出结构化报告 ci-report.json。本地与 CI 跑的是同一条命令(不再各写一套)。

  • 新增 14 项检查:identity(检出 == 事件完整 SHA)、commits、deps-install(按锁安装)、 format(Go gofmt + 前端 prettier)、static-go(go vet)、static-web(tsc)、 build-go(带版本注入)、build-web、tests-go、tests-web、contracts(版本契约必须真 PASS)、 security-secrets、security-deps(govulncheck + npm audit 分级 + 例外)、manifests-locked。
  • 汇总按清单逐项核对:失败即停后剩下的记 not_run,未运行/被跳过一律不算通过。
  • .gitea/workflows/build.yml 改成单作业(避免跨作业 /tmp 状态传递的假契约):检出固定事件完整 SHA → 环境与工具链 → make verify → 静态预览(只在全部必需检查通过后发布,且断言包里有 index.html、 报告里每个地址都 200)→ 上报 ci-bridge(通知失败不改变质量结论)。
  • 本 workflow 只做 CI:删掉了 deploy:test 占位作业(原来它会打印 TODO 然后返回成功 = 假报成功)。
  • 新增脚本:scripts/ci_checks.py(门禁 + 汇总)、scripts/check_format.py(格式,含只能减的基线)、 scripts/check_secrets.py(密钥扫描,带双向自检)、scripts/check_deps_vuln.py(依赖漏洞分级)。 四个脚本都带 --self-test(反向自检:故意弄坏必须红)。
  • security/dependency-exceptions.json:依赖漏洞例外登记(缺字段/过期/批准人是占位值 ⇒ 例外无效)。
  • 依赖:vite 7.1.3 → 7.3.7、vitest 3.2.4 → 5.0.3(清掉 npm audit 的 2 critical + 2 high + 1 moderate, 现在全量 0 命中);新增 prettier 3.9.10;web/package.json 加 format / format:check。
  • 格式债:Go 侧 6 个文件 gofmt -w(存量清干净,Go 侧一条都不欠);前端 79 个文件的存量格式债 记入 web/.prettier-baseline.json(列明 + 只能减 + 2026-12-31 到期,不新增欠账即绿)。
  • AGENTS.md 的现状表已过期(写着"main 已启用分支保护",实际 GET /branch_protections = [])—— 修正稿已拟好,但该文件受写入保护,待人工批准后应用(见交付说明)。

怎么验收

# 1) 门禁自身可跑、且能证明自己会红(反向自检)
python3 scripts/ci_checks.py --self-test     # 期望:✅ 汇总逻辑 7 个分支符合预期
python3 scripts/check_format.py --self-test  # 期望:✅ 6 个判定分支
python3 scripts/check_secrets.py --self-test # 期望:✅ 7 条合成密钥全部命中,良性对照零误报
python3 scripts/check_deps_vuln.py --self-test  # 期望:✅ 9 个判据 + JSON 流解析器

# 2) 一条命令跑完全部门禁(约 1 分钟;会跑 npm ci,请留时间)
make verify
# 期望:末尾"总体:success(档案 local)",identity=skipped(本地无事件负载,已在清单里声明)

# 3) 清单与真实结果对账
make list                                    # 期望:14 项,identity 标 ci
python3 -c "import json;d=json.load(open('ci-report.json'));print(d['overall_status'],len(d['checks']))"
# 期望:success 14

[0.1.0] - 2026-10-10

改了什么

初始基线(补记):本仓此前既没有版本号、也没有变更记录,本次首次建立。 下面按已上线能力归纳,不逐条追溯历史提交。

  • 来源与目录:列出可选的钉钉知识库 → 勾选 → 变成来源;快照与变更集
  • 发布管理:计划 → 建批 → 锁定 → 授权发布(落 WeKnora 生产)
  • 监控 + 需下架车道:测试库知识逐条下架
  • 钉钉侧:知识库发现 / 注册、取件走 dws;登录与系统设置
  • 运行形态:knowledge-governance-p1-* —— api / web / worker / release-worker / dingtalk-login / postgres 共 6 个容器;web 发布在 :8088

怎么验收

冒烟(约 2 分钟;下面每条都是本机运行栈的实测结果,不是设计意图)

# 1) 容器都在(期望 6 个:api / web / worker / release-worker / dingtalk-login / postgres)
docker ps --format '{{.Names}}' | grep knowledge-governance-p1-

# 2) 存活与就绪(web 的 nginx 反代 /health 与 /api/ 到 api 容器)
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/health   # 期望 200
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/livez    # 期望 200
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/readyz   # 期望 200
curl -fsS http://127.0.0.1:8088/readyz | head -c 400                       # 期望 postgres / queue 非 blocked

# 3) 控制台能打开
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8088/          # 期望 200

# 4) api 容器自带 healthcheck 的状态
docker inspect knowledge-governance-p1-api-1 --format '{{.State.Health.Status}}'   # 期望 healthy

业务流程(逐条走,每条都写了"操作 → 期望现象")

  • docs/USER_FLOWS_ACCEPTANCE.md —— C1 ~ C9
  • docs/OPERATIONS_RUNBOOK.md —— 现行用户操作流程与运维步骤

⚠️ 冒烟通过 ≠ 验收通过。面向上线的那一次验收必须走完 C1~C9,由人确认并留下记录; "服务健康"只是可继续验收的前提,不是验收本身。

⚠️ 上面的端口(8088)与容器名前缀(knowledge-governance-p1-)是本机运行栈的实测值; 换环境(测试机 / 生产)要按那边的运行栈改,别无脑照抄。