姚章浩
d025fc9adf
build / build (push) Successful in 29s
本仓此前没有任何 agent 上下文文件，代理每次都得重新讲一遍规范。 新增 AGENTS.md：指向系统级规范（zheromiku/eng-standards-main），并写明 本仓已核实的现状（CI 作业链 / runner / 本机运行栈 / main 已受分支保护）。 为什么用 AGENTS.md 而不是 .hermes.md：Codex / Claude Code / OpenCode 读的 也是 AGENTS.md，跨工具可移植。
72 lines
3.8 KiB
Markdown
72 lines
3.8 KiB
Markdown
# 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 头提交拿得到状态）<br>作业：`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. 硬约束（违反其中任何一条，这次改动就不合格）
|
||
|
||
1. **同一含义的代码只准有一份**（禁止同义复制）
|
||
2. **注释写「为什么」**，不写「是什么」
|
||
3. 提交：conventional commits，标题中文，**≤72 字符、结尾不加句号**，一件事一个提交
|
||
4. **生产部署只部署测试验收过的那一份产物**（同 sha / 同镜像 ID），不许在生产机上另行 build
|
||
5. TODO：本工程最硬的那条证据是什么（对拍 / 契约 / 字节一致 / 快照）—— 待补
|
||
|
||
## 3. 提交与推送
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
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 加全文 + 这张表加一行）。
|
||
|
||
| # | 一句话 | 全文 |
|
||
| --- | ------ | ---- |
|
||
| — | （待填） | — |
|