新增陷阱(只追加、不复用旧号):
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 全绿。
7.1 KiB
变更记录
这个文件就是版本号的唯一来源。 正本 §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:依赖漏洞例外登记(缺字段/过期/批准人是占位值 ⇒ 例外无效)。- 依赖:
vite7.1.3 → 7.3.7、vitest3.2.4 → 5.0.3(清掉 npm audit 的 2 critical + 2 high + 1 moderate, 现在全量 0 命中);新增prettier3.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 ~ C9docs/OPERATIONS_RUNBOOK.md—— 现行用户操作流程与运维步骤
⚠️ 冒烟通过 ≠ 验收通过。面向上线的那一次验收必须走完 C1~C9,由人确认并留下记录; "服务健康"只是可继续验收的前提,不是验收本身。
⚠️ 上面的端口(8088)与容器名前缀(knowledge-governance-p1-)是本机运行栈的实测值;
换环境(测试机 / 生产)要按那边的运行栈改,别无脑照抄。