From 67a4a6582be8e0c891c266f3bef88bee32fcefa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= Date: Sat, 10 Oct 2026 14:51:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E5=8A=A0=20AGENTS.md=20?= =?UTF-8?q?=E6=93=8D=E4=BD=9C=E6=89=8B=E5=86=8C=E4=B8=8E=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E6=8C=87=E9=92=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 本仓此前没有任何 agent 上下文文件，代理每次都得重新讲一遍规范。 新增 AGENTS.md：指向系统级规范（zheromiku/eng-standards-main），并写明 本仓已核实的现状（CI / runner / main 已受分支保护）。 为什么用 AGENTS.md 而不是 .hermes.md：Codex / Claude Code / OpenCode 读的 也是 AGENTS.md，跨工具可移植。 --- AGENTS.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c7035ae --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,71 @@ +# AGENTS.md — 给在 knowledge-adapter-service 里干活的 AI 代理 + +> 这是**操作手册**，不是给用户看的介绍。改代码前先读「硬约束」与「已知陷阱」。 +> +> **系统级规范（本机所有 Gitea 仓库都适用）**：仓库 `zheromiku/eng-standards-main` +> （本机工作副本 `~/eng-standards/`）—— `01-规范-Git与CI-CD（Gitea版）.md`（正本）+ +> `02-流程说明与Runbook.md`。做 git / 提交 / CI / 发布 / 回滚 / 密钥 这些事之前先读它， +> 或加载技能 `eng-standards`。**本文件只写本工程特有的东西。** + +## 0. 这个工程是什么 + +knowledge-adapter-service —— Python 服务：把知识源适配/导入到 WeKnora。 + +## 1. 本仓现状（已核实；事实变了就更新这张表，别让它过期） + +| 项 | 值 | +|---|---| +| 默认分支 | `main` —— **已启用分支保护**：禁止直接推送、必须走 PR | +| 技术栈 | Python 3 + Makefile + PLpgSQL | +| CI | **main 上目前没有任何 CI**（`build.yml` 只存在于 `ci/setup` 分支）—— 推 main 不会触发校验。待把工作流合到 main。 | +| Runner | `runner-weknora-ka-01`（仓库级） | +| 强制状态检查 | 未启用（main 无 CI，强制会锁死 PR） | + +⚠️ **main 已受保护**：`git push origin main` 会被服务端拒绝（`Not allowed to push to protected branch`）。 +一切改动走短命分支 + PR。 + +## 2. 硬约束（违反其中任何一条，这次改动就不合格） + +1. **同一含义的代码只准有一份**（禁止同义复制） +2. **注释写「为什么」**，不写「是什么」 +3. 提交：conventional commits，标题中文，**≤72 字符、结尾不加句号**，一件事一个提交 +4. **生产部署只部署测试验收过的那一份产物**（同 sha / 同镜像 ID），不许在生产机上另行 build +5. TODO：本工程最硬的那条证据是什么（对拍 / 契约 / 字节一致 / 快照） + +## 3. 提交与推送 + +```bash +git switch -c / # 短命分支，合完即删 +# … 改动 … +make check # 或本仓的门禁命令；跳过项会显式警告「不算全绿」 +git commit -F - <<'EOF' +(): 标题（中文） + +为什么这么改、试过什么、怎么验的。 +EOF +git push -u origin HEAD # 然后开 PR，等 CI，合并后读回 +``` + +⚠️ 提交信息**不要用 `-m` 写多行**：正文里的反引号 / `$()` 会被 shell 先执行，且退出码仍是 0。 + +## 4. 看 CI + +```bash +giteactl runs Weknora/knowledge-adapter-service +giteactl logs Weknora/knowledge-adapter-service +python3 ~/.hermes/scripts/gitea_api.py GET "/api/v1/repos/Weknora/knowledge-adapter-service/actions/tasks?limit=5" +``` + +- run 一直 `queued` ⇒ 先查**本仓有没有自己的 runner**，别怀疑工作流。 +- `status=pending` 且 `status_count=0` **不是**失败（那是「没有配置任何状态检查」）。 +- 合并读回：`GET /pulls/{n}` 要 `state=closed` + `merged=true` + `merge_commit_sha` 非空。 + ⚠️ 合并接口成功时可能返回**空 body** → **永不重试**，改读回。 + +## 5. 已知陷阱（索引） + +全文在 `docs/agents/traps.md`（还没有就建）。**只追加、不重排、不复用旧号** —— 编号会被代码注释与测试引用。 +新增一条要改两处（traps.md 加全文 + 这张表加一行）。 + +| # | 一句话 | 全文 | +| --- | ------ | ---- | +| — | （待填） | — | -- 2.52.0