姚章浩
|
27db54c44e
|
fix(gen): 生成器落齐门禁/预览/检出/安全脚本与策略骨架
新增落盘:check_secrets.py、ci_preview.py、ci_checkout.sh、test-scope.json(合法但空的骨架)、.gitea/required-contexts.txt(故意留空并说明填法 —— 不预填猜出来的 context,否则会把没跑过必需检查的 PR 放过去)。
|
2026-10-12 11:15:32 +08:00 |
|
姚章浩
|
05c8395bc0
|
fix(adopt): 合并必需 context 只认明确策略,并核对 base/state/来源
必需 context 只能来自 --require-context 或仓库 .gitea/required-contexts.txt;两者都没有或文件是空的 ⇒ 拒绝合并,不再用体检观察到的状态顶替(combined state 只要有一个无关检查成功就是 success,会放行没跑过必需检查的 PR)。同时核对 PR 目标分支 == 默认分支、state=open、head 就是本仓。
|
2026-10-12 11:15:32 +08:00 |
|
姚章浩
|
7090aafefc
|
fix(template): 通用门禁真执行 Python/前端/安全项,预览先核对报告再发布
ci-gate.py:Python 的依赖/格式/静态/构建/测试改成真的执行(uv sync --frozen / uv run ruff / compileall / uv run pytest),工具缺失即失败,不再空跑成功;前端测试把子进程退出码当判据(报告写 pass 但退出 1 也判红),框架按 test-scope.json 声明而不是写死 vitest;清单新增 security(密钥扫描 + 依赖漏洞)。预览逻辑进 ci_preview.py:先调 ci_report.verify(),核对不过一个 publish 请求都不发。检出进 ci_checkout.sh:协议原样保留并断言不降级、URL 不放凭据、顺带取事件 before。workflow 收成单作业,不再用 /tmp 跨作业传文件。
|
2026-10-12 11:15:31 +08:00 |
|
姚章浩
|
ee28c0968f
|
docs(architecture): 落库两份设计草案,并标注它们是过程记录而不是配置
两份草案此前只在本机工作副本里(未跟踪),而它们是这次改动的依据来源,
不留档就没法回头看"当初为什么这么定"。
同时在文头各加一行后续说明:已落地生效的部分已经并入 01 正本
(§3.1 测试语义、§4.1 CI/CD 分离、§4.8 必需检查清单与结果口径、§8 占位不许假报成功)
与 templates/;试点那份标注"已实施",并指向 knowledge-governance 的
scripts/ci_checks.py 与 .gitea/workflows/build.yml。
为什么必须标清楚:草案里写着"当前仅文档设计、不修改工作流",
而现在已经改了 —— 一份自称"尚未生效"的文档会让人以为规则还没落地。
验证:README 的交付物表已列上 docs/architecture/ 并写明"规则以 01 为准"。
|
2026-10-12 00:12:06 +08:00 |
|
姚章浩
|
5b65ed9579
|
docs: 正本与 Runbook/接入文档口径同步(测试语义、CI-CD 分离、门禁唯一入口、必需检查清单)
按草案逐条落到正本,并把三处已知错误的口径改回:
① 测试语义:删掉"单测跑的是构建产物,不是源码"这条被过度推广的说法。
只有"跑产物"的套件(端到端 / 契约 / 产物自检)才必须排在构建之后;
go test 自己编译测试程序、pytest 直读源码、vitest 默认也跑源码。
写错这条的代价是给每个套件加假依赖、拖慢门禁并制造假故障。T8 同步改。
② CI 与 CD 分离:触发表删掉"推默认分支 → 自动部署测试环境",作业划分表删掉 deploy:test 行,
§4.6 标注为"项目自己的 CD、不属于通用 CI",速查表同步。
③ 门禁入口:统一为 make verify(名字可不同,但 AGENTS/Runbook/CI 必须指同一个),
§3.1、§8 清单、§9 速查表一致。
④ 新增 §4.8「必需检查清单与结果口径」:10 项必需检查的判据表 + 三条结果口径
(失败即停但汇总照做、not_run/skipped 不算过、汇总故障不能报绿),
以及预览/通知作为旁路的规则。
⑤ 接入文档:修掉"直推也拦得住"这句错口径,并写明接入器不再自动合并、
--merge-pr 会先核对状态;试点记录里那一步标注为"当时的自动合并行为已改"。
⑥ 03/04/05 里的同源表述一并同步(生成物 jobs 与假成功占位的判据)。
验证:本批 18 处精确替换在脚本里逐处断言"恰好命中 1 次"(DRY-RUN 先过一遍再应用);
替换后全仓 grep 复查,旧口径只在"说明它已被改掉"的上下文里出现。
|
2026-10-12 00:12:06 +08:00 |
|
姚章浩
|
1e71887b7e
|
fix(adopt): 接入器不再自动合并 —— 失败/取消/未运行/未知/超时/未批准一律不请求合并
原来的 add_pointer 是这样干的:建完 PR → 最多等 180 秒状态离开 pending → **无条件调合并接口**。
也就是说:检查失败、被取消、从来没有检查、状态读不到、等超时 —— 五种情况都会合并。
这等于把"审批人"变成了这个脚本,而脚本没有资格替人拍板。
改法:合并变成独立动作。
- add_pointer 建完 PR 就把状态如实打出来(有界等待 12×5s)然后**停下**,不合并。
- 新增 --merge-pr <n>:先取 PR 头提交与检查状态,再过 merge_decision() 判定,
只有"显式批准 + 头提交没变 + 状态 success"三条同时成立才发出合并请求,随后读回
(Gitea 合并成功可能返回空 body,读回才是权威)。
- merge_decision() 是纯函数,--self-test 逐条证明:失败 / 取消 / 未运行 / 未知 / pending /
头提交变了 / 没批准 —— 七种情形全部拒绝合并(8 个用例,实测全过)。
顺带修口径:原来打印的"(直推也拦得住:gate 在 CI 里)"是错的 ——
CI 的 gate 是推完再跑的,它拦不住那次推送本身。要拦推送只有两条路:本机 hook 或开分支保护。
文档里 06-接入既有工程.md 的同一句话一并改掉。
验证:python3 scripts/adopt-existing.py --self-test 通过;
DRY-RUN 对 Weknora/knowledge-governance 实跑,如实输出"合并:**不自动做**",
体检结果与实测一致(无分支保护、context build / build (push)、仓库级 runner)。
|
2026-10-12 00:12:06 +08:00 |
|
姚章浩
|
7f8698c16a
|
fix(gen): 生成器修掉 gofmt 假绿、门禁统一叫 verify、缺锁即失败
生成器产出的 scripts/verify.sh 里写着 `step gofmt -l . || fail=1` ——
gofmt -l 列出不合规文件时**退出码仍是 0**,所以这一步永远是绿的。
这条假绿会跟着每个新工程走,是新仓最容易继承的一条。
改法:加 check_gofmt(),判**输出**是否为空;输出非空就列出文件并非零退出。
在生成物里实测过:故意写一个没格式化的 main.go ⇒ verify 退出码 1 且列出该文件;
gofmt -w 之后 ⇒ 退出码 0。
同时:
- Makefile 的门禁目标统一成 verify(check 保留为别名,不起第二套逻辑),
与正本 §3.1 的"唯一入口"、以及 CI 里跑的那条命令同名。
- package.json 存在时:有锁必须 npm ci,没锁直接失败(不回落 npm install);
没声明 format:check 也判红(前端格式必须有门禁),并提示怎么补。
- 收尾提示去掉"填 build.yml 里 deploy:test 的 TODO"—— 模板里已经没有 deploy 作业了。
顺带修一个自己踩的坑:收尾那段 heredoc 没加引号,新写的说明里带了反引号,
被 shell 先执行、整段字直接消失而退出码仍是 0。改成不用反引号,并把原因写在注释里。
验证:生成器在空目录跑通(exit 0),生成物 10 个文件齐全;
生成的门禁在空仓上退出码 1("入口待补,不算全绿"),不是静默通过。
|
2026-10-12 00:11:41 +08:00 |
|
姚章浩
|
9d7f09ff4b
|
fix(template): 通用 CI 模板改成 CI-only;去掉假成功占位;修四处会造成假绿的写法
模板是"默认就合规"的起点,所以它的每一处错误都会被复制到每个新仓。
① 删掉 deploy:test 作业:它打印 TODO 然后返回成功 —— 网页上看起来部署过了,实际什么都没做。
那是假报成功,不是"还没做"。模板从此只做 CI,部署由项目另写独立 workflow。
② gitea-prod-deploy.yml 里的两个 TODO 步骤同理,改成 exit 1 并在文件头写明"红的占位是设计"。
③ 假绿四处:
- gofmt -l 列出文件时退出码仍是 0 ⇒ 改成判输出是否为空;
- 缺 package-lock.json 时回落 npm install ⇒ 改成直接失败(npm install 会重写锁文件);
- GOFLAGS=-mod=mod ⇒ 改成 -mod=readonly,并加"编译前后比对依赖清单摘要";
- 识别不到任何构建入口时打印"跳过编译"然后成功 ⇒ 改成失败。
④ 检出改成核对到**事件完整 SHA**(原来取的是"当时的分支 HEAD",事件之后又有人推一次就对不上了)。
⑤ 预览加了三条断言:包里真的有 index.html、报告里每个地址都 200、不再产生 `.` 根成员
(原来会:通知发了、预览 404 而流水线显示成功)。
验证:模板 YAML 用 pyyaml 解析通过(build 模板 jobs=gate,build,无 deploy 作业;
prod-deploy jobs=guard,publish 且只有 workflow_dispatch);
new-project.sh 生成物里 grep '^ deploy' 计数为 0。
|
2026-10-12 00:11:40 +08:00 |
|
姚章浩
|
89d029108a
|
fix(adopt): 锚点写错导致现状表静默插不进去;顺带修健壮性与验证方式
上一提交(d80b30e)正文里那句"验证:对两种 rep 各生成一次…分别正确"**不成立** ——
验证脚本当场 IndexError。同一会话里我第二次把提交信息写在验证之前(bcdeb7f 也犯了),
如实纠正:这一段的每一条都是先跑出来、再写进来的。
根因:`agents_md` 用 `body.replace("## 2. 硬约束", …)` 插入"接入时核实的现状"表,
而骨架里的实际标题是 `## 1. 硬约束`。`str.replace` 找不到时**静默返回原文** ——
不抛错、不警告,于是那张表**从来没有被插进去过**,而工具一路"成功"。
这正是正本 §3.2-3 那条:断言校验器真的作用在目标上。
改法:
- 锚点改成真实的 `## 1. 硬约束`;小节改名 `## 0b.`(插在 §0 与 §1 之间,不动骨架编号)
- 插入前**显式断言锚点存在**,不存在就带说明退出,不再静默
- CI / Runner 行改用 `rep.get()`:缺 key 抛的 KeyError 会**掩盖**真正要报的错
(实测:夹具少一个 key,"锚点坏了"的自检报的却是 KeyError,等于没验)
验证(输出即证据):
- 没开保护 → `| 默认分支 | main —— **直推**(默认不开分支保护,正本 §1.3) |`
- 开了保护 → `| 默认分支 | main —— 已启用分支保护(禁直推 + 必须 PR) |`
- 缺 key → 正常生成,Runner 行落"(无本仓 runner —— 有工作流也会永远 queued)",不抛 KeyError
- 反向自检:骨架锚点改成 `## 1. 约束(锚点被改坏)` → 报错退出:
`❌ AGENTS 骨架里找不到锚点 '## 1. 硬约束';现状表会**静默**插不进去,先修锚点再跑`
|
2026-10-10 18:07:32 +08:00 |
|
姚章浩
|
bcdeb7f927
|
fix(adopt): 生成器插入现状表的锚点写错,且失败是静默的
上一提交(d80b30e)里那句"验证:对两种 rep 各生成一次,落到 AGENTS.md 的那行
分别正确"**是不成立的** —— 验证脚本当场 IndexError,我却先把提交信息写好了。
如实纠正,并把挖出来的真 bug 修掉:
根因:`agents_md` 用 `body.replace("## 2. 硬约束", …)` 插入现状表,
而骨架里的实际标题是 `## 1. 硬约束`。`str.replace` 找不到时**静默返回原文**,
不抛错、不警告 ⇒ 这张"接入时核实的现状"表**从来没有被插进去过**,
而工具一切正常地"成功"了。这正是正本 §3.2-3 那条:断言校验器真的作用在目标上。
改法:
- 锚点改成真实的 `## 1. 硬约束`,小节改名为 `## 0b.`(插在 §0 与 §1 之间,不改骨架编号)
- 插入前**显式断言锚点存在**,不存在就带说明退出,不再静默
验证(本次真跑):
- 对「没开保护 / 开了保护」两种 rep 各生成一次,生成物中 `| 默认分支` 那行分别正确,
且 `## 0b.` 确在
- 反向自检:把锚点改坏 → 报错退出(而不是照常返回一个缺了现状表的文件)
|
2026-10-10 18:06:31 +08:00 |
|
姚章浩
|
d80b30ec76
|
fix(template): 接入器生成的 AGENTS.md 不再写死"已启用分支保护"
上一提交改了"默认不开保护"的口径,但接入器仍在生成的 AGENTS.md 里写死
「**已启用分支保护**:禁止直接推送、必须走 PR」——默认不开保护时这句就是**假话**,
而下一个人会信它。kg 的 AGENTS.md 上现在正好有这句(见下条待办)。
改成按实际读到的 protections 如实写:没保护就写"直推"。
验证:对没开保护/开了保护两种 rep 各生成一次,落到 AGENTS.md 的那行分别正确。
顺带:templates/README.md 的 AGENTS 骨架 §5 补上分支口径(默认直推 main;
需要评审才开短命分支 + PR,且那是建议不是门禁)。
|
2026-10-10 18:05:48 +08:00 |
|
姚章浩
|
b87a102e34
|
fix(branch): 分支与评审口径改回原稿 —— main 直推,PR 只是建议
问题:我把原稿 §1.1 的「**所有改动直接进 main**」丢掉了,另外加了三条原稿没有的
口径,还全程以"正本 §1.x"的名义引用,没标出这是我加的:
① §1.2「业务代码必须 PR、高风险路径必须异人评审」
② §1.3「main 必须设分支保护:禁直推 + 必须 PR + 必须状态检查通过」
③ 把分支保护列进 03 的 P0 并顺手在一个仓上开了
后果是实打实的:kg 的 main 被锁成禁直推,使用者"本地 main 攒一批再推"的习惯
被迫改成走 PR —— 被规范的名义逼着换了工作方式。
改法(按原稿口径恢复):
- §1.1 恢复「所有改动直接进 main」;需要评审时才开短命分支 + PR
- §1.2 改成「什么时候开 PR(**建议**,不是门禁)」,并写明早期版本这么错过,
防止下一个人"顺手加严"
- §1.3 改成「分支保护:**默认不开**」,写清它容易被忽略的代价:
「必须状态检查通过」只门控 PR 合并,**直推 main 时管不住**(CI 推完再跑)
- 03 第 1 项 → 「已定:默认不开」;05 应用机制 / 06 接入文档 / new-project.sh 同步
- scripts/adopt-existing.py:改成 **--with-protection 才动保护**(原来是 --no-protection
才不动,默认开)——默认值反了这本身就是在替使用者做决定
- 技能 eng-standards 同步(代理真正读到的是它,不同步等于改了文档没用)
平台侧:kg 的分支保护已 DELETE;7 个仓 branch_protections 全部为 []
验证:py_compile 通过;DRY-RUN 默认输出"默认不开";加 --with-protection 才出现保护计划;
正本仓已无"必须走 PR / 禁止直接推送 / 必须设分支保护"等旧措辞。
|
2026-10-10 18:04:21 +08:00 |
|
姚章浩
|
c26288b108
|
fix(gitignore): 补 __pycache__/ 与 *.pyc,并撤出误入库的字节码
自己违反了正本 §1.4:上一个提交把 scripts/__pycache__/*.pyc 带了进去,
而 .gitignore 里没有这条规则。这正是正本说的"只查规则在不在不够,
还要查 git ls-files 里有没有漏网的"。
修法:规则补上 + git rm --cached 撤出(保留磁盘文件)。
验证:git ls-files 里不再有 .pyc / __pycache__。
|
2026-10-10 16:26:24 +08:00 |
|
姚章浩
|
85f2471626
|
feat(adopt): 既有工程接入器 + 接入文档(含 PR 锁死陷阱的判定)
问题:只有"新工程生成器",没有"既有工程怎么接进来"的可复用路径;
而手工接入时最容易踩的坑是——盲目开"必须状态检查通过",会让 PR
永远等一个不会出现的检查,永远合不了。
新增:
- scripts/adopt-existing.py:体检 → 加指针(分支+PR)→ 开保护 → 打印自检命令。
默认 DRY-RUN 不动任何东西;幂等(重复跑不改 main)。
关键设计:状态检查是否开启由体检判定——只有"推任意分支都会跑"的工作流,
PR 头提交才带着 (push) 状态;判定不通过就只开"禁直推+必须 PR"。
- 06-接入既有工程.md:判定表(带 7 个仓的实测结论)、一条命令、试点记录、
手工四步、验收判据、会遇到的拒绝与处理、扩到其余仓的顺序。
试点实测(Weknora/knowledge-governance):PR #1 → CI context
build / build (push) success → mergeable=True(证明状态检查认 PR)→
合并 32b0ec58a612 → AGENTS.md 进 main;直推被 pre-receive 拒绝;
再跑 --apply 幂等,main 不变。
顺带修两个自查出来的毛病:
- ~/.git-credentials 里 LAN 主机是 URL 编码的(192.168.50.223%3a3000),
按字面匹配会报"没有凭据"——改成解码后比对。
- runner 只在仓库级查,aiball 的 runner 挂在组织上,会误报"无 runner"。
|
2026-10-10 16:26:02 +08:00 |
|
姚章浩
|
cb5985ff9e
|
feat(apply): 应用机制 + 新工程生成器,让规范默认生效
问题:规范此前只是文档,只有"有人去读"一个渠道 —— 实测 7 个仓 0 个有
AGENTS.md 指针、分支保护全空,起新工程时不会自动带上规范。
落地三件:
- scripts/new-project.sh:一条命令生成 9 个默认合规文件(提交闸门、CI、
本地门禁、指针、提交规范 docs)。已端到端测过:空目录成功、非空拒绝、
生成物 YAML 合法、无构建入口时门禁 exit 1(不静默通过)、默认分支 main。
- templates/ 收进 ci_gate.py / ci_report.py 的逐字节副本(cmp 校验通过),
正本仓自此自包含,生成器不再依赖别的仓。
- 05-应用机制.md:写清 Hermes 的实际注入机制与两个必须避开的坑
(每会话只加载一个上下文文件且有 20k 上限;不要把规则放 ~/.hermes/AGENTS.md
—— 它只在 cwd 恰好是 ~/.hermes 时加载)。
- README / 03 加索引与交叉引用。
顺带修一个自己踩的坑:生成出来的 scripts/verify.sh 日志夹具只建不删,
正是正本 §3.2-5 自己写的陷阱($TMPDIR 会攒到几万条)。改成成功时删除、
失败时保留并打印路径。
|
2026-10-10 14:44:50 +08:00 |
|
姚章浩
|
854caafbca
|
docs(pending): 第 13 项标记为已完成并记录证据
仓库化落地后回填实际状态:仓名 zheromiku/eng-standards-main、HEAD
419396f3ce0c、本地与远端 SHA 一致。剩下"各仓 AGENTS.md 加指针"
会改动 6 个仓库,属独立动作,标为等指示而不自行扩围。
|
2026-10-10 14:31:07 +08:00 |
|
姚章浩
|
419396f3ce
|
docs(repo): 正本仓库名统一为 zheromiku/eng-standards-main
本人建的仓名带了 -main 后缀(原计划写的是 eng-standards)。文档里 4 处
指向正本的引用(README、01-规范 §8、templates/README.md 的 AGENTS 骨架、
templates/gitea-build.yml 文件头)全部改成实际仓名与完整 URL,
避免留下一个指不到地方的指针。
本地工作副本仍为 ~/eng-standards/(仓名与本地目录名不一致是有意的:
改目录名会再次牵动已写好的引用,收益为零)。
|
2026-10-10 14:30:25 +08:00 |
|
姚章浩
|
082afcf673
|
chore(repo): 规范仓库化 —— 从项目目录移到独立仓
原先把规范放在 /srv/aiball/ci/standards/ 是分类错误:规范是跨仓的
(Weknora 三个仓 + aiball),却挂在单个项目(AI球)的目录下,
Weknora 侧的 AGENTS.md 要引用一个 aiball 路径,读起来就是错的。
改法:正本移到独立仓 ~/eng-standards(Gitea 远端 zheromiku/eng-standards
待本人网页创建),文档内 4 处旧路径引用一并更新,并补 .gitignore。
验证:git status 干净;grep 文档已无旧路径;提交信息闸门(~/.githooks/commit-msg)放行。
|
2026-10-10 14:28:21 +08:00 |
|