082afcf673
原先把规范放在 /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)放行。
templates/ —— 可直接落仓的骨架
每个文件都替换掉附件原稿的 GitLab 口径;改法见
../04-模板评估与修正.md。 ⚠️ 复制到仓库后不要就地重写:ci_gate.py/ci_report.py请从已验证的仓库逐字节复制 (Weknora/knowledge-governance/.gitea/scripts/或/srv/aiball/ci/attach/)。
| 文件 | 落仓位置 | 说明 |
|---|---|---|
gitea-build.yml |
.gitea/workflows/build.yml |
提交触发的校验+编译+预览+上报;deploy:test 是待填骨架 |
gitea-prod-deploy.yml |
.gitea/workflows/deploy-production.yml |
生产发布唯一入口,只 workflow_dispatch,不构建 |
gitignore |
.gitignore |
去掉原稿自相矛盾的 !src/secrets/ 例外 |
commit-msg |
~/.githooks/commit-msg |
本机提交闸门;规则必须与 ci_gate.py 一致 |
AGENTS.md 骨架 |
AGENTS.md |
见下(agent 指令文件有写入保护,故内联在此) |
| —— 随仓携带 | .gitea/scripts/ci_gate.py.gitea/scripts/ci_report.py |
逐字节复制已验证版本,不要重写 |
落仓后的自检(反向自检,规范 §3.2-3)
# 1) 故意违规的提交必须被闸门拦住,且 build 不跑
git commit -F - <<'EOF'
update stuff
EOF
# 判据:本地 hook 报 ❌;push 后 CI 的 gate 红、build 未执行
# 2) 合规提交必须过(正例对照:证明不是"永远红")
git commit -F - <<'EOF'
ci(deploy): 接入 Gitea Actions 生产发布 workflow
生产发布改成独立 workflow(只 workflow_dispatch),避免塞进 push 流水线;
concurrency 明确 cancel-in-progress: false —— 取消不是回滚。
验证:手动发起一次,confirm 不匹配时 guard 作业必须红。
EOF
# 3) 产物地址每个都要 200
curl -m 5 -o /dev/null -w '%{http_code}\n' http://192.168.50.134:8899/healthz
curl -m 5 -o /dev/null -w '%{http_code}\n' http://100.92.49.78:8899/healthz
AGENTS.md 骨架(复制到仓库根,按本工程改写 TODO)
# AGENTS.md — 给在 <PROJECT> 里干活的 AI 代理
> 这是**操作手册**,不是给用户看的介绍。改代码前先读「硬约束」与「已知陷阱」。
>
> **系统级规范(本机所有 Gitea 仓库都适用)**:仓库 `zheromiku/eng-standards`(本机工作副本 `~/eng-standards/`)
> —— `01-规范-Git与CI-CD(Gitea版).md`(正本)+ `02-流程说明与Runbook.md`。
> 做 git / 提交 / CI / 发布 / 回滚 / 密钥 这些事之前先读它;本文件只写**本工程特有**的东西。
## 0. 这个工程是什么
<PROJECT>(一句话说清做什么、给谁用、部署在哪)。
## 1. 硬约束(违反其中任何一条,这次改动就不合格)
1. TODO:不许改变对外可观测行为(接口、报文、退出码、配置语义)
2. TODO:本工程最硬的那条证据是什么(对拍 / 契约 / 字节一致 / 快照)
3. **同一含义的代码只准有一份**(禁止同义复制)
4. **注释写"为什么"**,不写"是什么"
5. 提交按"一件事一个提交",conventional commits,正文用中文,标题 ≤72 字符
6. **生产使用测试验收过的同一份构建产物**(同 sha / 同镜像 ID)—— 不许在生产机上另行 build
## 2. 本地验证闭环(提交前的最低要求)
```bash
make check # 或 npm run verify —— 一条命令跑完本地门禁;跳过项会显式警告"不算全绿"
```
- 门禁**串行**、失败即停:构建会清空产物目录,而端到端测的是构建产物 —— 并行会制造假失败。
- 改到部署脚本或产物形状时,必须另外跑一次真实的装配/启动自检。
## 3. CI 闭环
```bash
giteactl runs <ns>/<repo> # 最近运行
giteactl logs <ns>/<repo> <runId> # 作业日志
python3 ~/.hermes/scripts/gitea_api.py GET "/api/v1/repos/<ns>/<repo>/actions/tasks?limit=5"
```
- 失败时**先读日志再改代码**;追到第一处 `❌`。
- `status=pending` 且 `status_count=0` **不是**失败(那是"没有配置任何状态检查")。
- run 一直 `queued` ⇒ 先查**本仓库有没有自己的 Runner**,别怀疑工作流。
- 合并读回:`GET /pulls/{n}` → `state=closed` + `merged=true` + `merge_commit_sha` 非空。
⚠️ 合并接口成功时可能返回**空 body** → **永不重试**,改读回。
## 4. 已知陷阱(索引)
全文在 `docs/agents/traps.md`。**只追加、不重排、不复用旧号**;编号会被代码注释与测试引用。
⚠️ 新增陷阱要改两处(traps.md 加全文 + 这张表加一行)。
| # | 一句话 | 全文 |
| --- | ------ | ---- |
| 1 | TODO | [读](docs/agents/traps.md#trap-1) |
## 5. 提交与推送
- conventional commits,正文中文,**说清"为什么"**;一件事一个提交。
- 提交信息不要用反引号 / `$()`(会触发命令替换):用 `git commit -F -` + heredoc。
- 推之前跑完第 2 节;推送后用第 3 节确认流水线,失败就**先读 trace 再改代码**。
- 生产发布**不走 push**:它是独立的 `deploy-production` workflow,只由人手动发起(见规范 §5.2)。