Files

T

build / build (push) Successful in 1m26s

Details

trap-17：分页窗口当索引 —— "当前生效版本"不能按最近 N 条找。它比 trap-14 更
隐蔽：读成"没有"不报错，只是让错误的选择看起来合理（重写已上线的目标、给已有
权威版本的目标再建基线）。写清判据（250 条历史 + 窗口里看不到 + 精确查询仍命中）
与修法（身份/当前状态一律精确查，窗口只用于列表）。AGENTS.md 的陷阱索引同步加
一行；CHANGELOG 记录当前生效版本查询修复与固定同步屏障；test-scope 声明新增的
真实 PG 用例为"可选未运行"并写清理由（未声明 skip 判红）。

2026-10-30 03:09:37 +08:00

4.1 KiB

Raw Blame History

AGENTS.md — 给在 knowledge-governance 里干活的 AI 代理

这是操作手册，不是给用户看的介绍。改代码前先读「硬约束」与「已知陷阱」。

系统级规范（本机所有 Gitea 仓库都适用）：仓库 zheromiku/eng-standards-main （本机工作副本 ~/eng-standards/）—— 01-规范-Git与CI-CD（Gitea版）.md（正本）+ 02-流程说明与Runbook.md。做 git / 提交 / CI / 发布 / 回滚 / 密钥这些事之前先读它，或加载技能 eng-standards。本文件只写本工程特有的东西。

0. 这个工程是什么

知识治理控制台 —— 多源知识库的治理/监控/发布工作台（Go 后端 + TypeScript/Vite 前端）。

1. 本仓现状（已核实；事实变了就更新这张表，别让它过期）

项	值
默认分支	`main` —— 已启用分支保护：禁止直接推送、必须走 PR、必须 `build / build (push)` 状态检查通过
技术栈	Go（后端 / worker / 若干 `cmd/`）+ TypeScript + Vite（前端）
CI	`.gitea/workflows/build.yml` —— `on: push: branches: ""`（推任意分支**都跑，所以 PR 头提交拿得到状态）作业：`gate`（提交信息闸门）→ `build`（go build/vet/test + npm ci && build）→ 预览发布 + 微信上报
Runner	`runner-weknora-kg-01`（仓库级，`capacity: 1` ⇒ 同时只跑一个作业）
本机运行栈	`knowledge-governance-p1-*` 容器（api / web / worker / release-worker / postgres / dingtalk-login）；web 在 `:8088`

⚠️ main 已受保护：git push origin main 会被服务端拒绝（Not allowed to push to protected branch）。一切改动走短命分支 + PR。

2. 硬约束（违反其中任何一条，这次改动就不合格）

同一含义的代码只准有一份（禁止同义复制）
注释写「为什么」，不写「是什么」
提交：conventional commits，标题中文，≤72 字符、结尾不加句号，一件事一个提交
生产部署只部署测试验收过的那一份产物（同 sha / 同镜像 ID），不许在生产机上另行 build
TODO：本工程最硬的那条证据是什么（对拍 / 契约 / 字节一致 / 快照）—— 待补

3. 提交与推送

git switch -c <type>/<slug>          # 短命分支，合完即删
# … 改动 …
make check                            # 或本仓的门禁命令；跳过项会显式警告「不算全绿」
git commit -F - <<'EOF'
<type>(<scope>): 标题（中文）

为什么这么改、试过什么、怎么验的。
EOF
git push -u origin HEAD               # 然后开 PR，等 CI 绿，合并后读回

⚠️ 提交信息不要用 -m 写多行：正文里的反引号 / $() 会被 shell 先执行，且退出码仍是 0。

4. 看 CI

giteactl runs Weknora/knowledge-governance
giteactl logs Weknora/knowledge-governance <runId>
python3 ~/.hermes/scripts/gitea_api.py GET "/api/v1/repos/Weknora/knowledge-governance/actions/tasks?limit=5"

run 一直 queued ⇒ 先查本仓有没有自己的 runner，别怀疑工作流。
status=pending 且 status_count=0 不是失败（那是「没有配置任何状态检查」）。
合并读回：GET /pulls/{n} 要 state=closed + merged=true + merge_commit_sha 非空。 ⚠️ 合并接口成功时返回 空 body → 解析 JSON 会误报失败 → 永不重试，改读回。

5. 已知陷阱（索引）

全文在 docs/agents/traps.md（还没有就建）。只追加、不重排、不复用旧号 —— 编号会被代码注释与测试引用。新增一条要改两处（traps.md 加全文 + 这张表加一行）。

#	一句话	全文
14	包一层装饰器就丢掉可选接口 ⇒ 写集合台账被静默跳过	`docs/agents/traps.md`
15	Stat/Delete/Copy 与 Open/Put 吃不同的定位符形状	`docs/agents/traps.md`
16	"资源不在预备份范围"≠"属于别的知识库"，复用只认可审计证据	`docs/agents/traps.md`
17	分页窗口当索引："当前生效版本"不能按最近 N 条找	`docs/agents/traps.md`

4.1 KiB Raw Blame History Unescape Escape