From 1b7c70102cae3b392c0492ffb87a5f6e5a96494b Mon Sep 17 00:00:00 2001 From: cnphpbb Date: Thu, 4 Jun 2026 14:33:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85Git=E6=8F=90=E4=BA=A4?= =?UTF-8?q?=E8=A7=84=E8=8C=83=E4=B8=8EAGENTS.md=E7=BB=B4=E6=8A=A4=E8=A7=84?= =?UTF-8?q?=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 Git 提交规范章节（Conventional Commits 格式、type/scope、提交粒度、提交前自检） - 新增 AGENTS.md 维护规则章节（何时更新、内容质量、章节组织、验证清单） - 规则基于本仓库历史 commit 风格制定，兼容现有中英文混用 --- AGENTS.md | 184 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 184 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index cbcb80b..f7c27fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -141,3 +141,187 @@ docker compose -p <名称> --env-file ./builder/golang/env.cfg -f ./builder/gola - 连接队列大小（somaxconn、syn backlog） - 内存管理（swappiness、脏页阈值） - 安全加固（ICMP 重定向拒绝、反向路径过滤、kptr_restrict） + +## Git 提交规范 + +### Commit Message 格式 + +本仓库 commit message **优先使用 Conventional Commits** 规范，与历史风格保持一致。格式： + +``` +(): # 中文 +(): # 英文 +``` + +### Type 类型 + +| Type | 用途 | 示例 | +| ---------- | ------------------------------------ | --------------------------------------------- | +| `feat` | 新增服务/新功能 | `feat: add adminer docker deployment files` | +| `fix` | 修复 bug | `fix(gitea): 修复备份脚本权限问题` | +| `docs` | 文档变更（readme、AGENTS.md 等） | `docs: 添加git提交信息规则文件` | +| `refactor` | 重构（不改功能） | `refactor(status.py): 重构OLED状态显示代码` | +| `perf` | 性能优化 | `perf(redis): 调整内存淘汰策略` | +| `build` | 构建相关（Dockerfile、compose、依赖）| `build(moltbot): 添加生产环境docker compose` | +| `chore` | 杂项（版本号、配置、镜像标签） | `chore: 更新 Joplin 服务器镜像版本至 3.6.1` | +| `style` | 格式调整（不影响代码逻辑） | `style: 统一 yaml 缩进为 2 空格` | +| `test` | 测试相关 | `test: 添加 memos 部署验证脚本` | + +### Scope 范围（可选） + +- 服务名（目录名小写）：`gitea`、`memos`、`haproxy`、`postgres`、`portainer-ce` 等 +- 顶层目录：`builder`、`crontab`、`etc`、`shell`、`i2c.py` +- 省略：当改动跨多个服务或为全局性变更 + +### Subject 主题规则 + +1. **中文项目**用中文描述，**英文项目**用英文，统一保持 +2. **首字母小写**（中文不受影响） +3. **不超过 50 个字符**，尽量精炼 +4. **不要句末加句号** +5. **动词开头**：添加/更新/修复/重构/删除 或 add/update/fix/refactor/remove +6. **写明对象**：要让人一眼看出改了什么 + +### Body 与 Footer（可选） + +需要时换行后空一行写正文： + +``` +feat(gitea): 添加 lfs 存储后端配置 + +- 使用 minio 作为 lfs 对象存储 +- 调整 gitea app.ini 路径映射 +- 备份脚本需同步调整 + +Refs: #123 +``` + +### 提交前自检 + +```bash +# 1. 查看变更文件 +git status + +# 2. 检查 diff 大小（避免误提交敏感文件） +git diff --stat + +# 3. 确认无 env.cfg / 凭据被误提交 +git diff | grep -iE "password|secret|token|key" # 应无敏感输出 + +# 4. 暂存并提交 +git add +git commit -m "(): " + +# 5. 推送 +git push origin main +``` + +### 提交粒度 + +- **一个 commit 只做一件事**：不要把无关改动混在一起 +- **服务级别独立提交**：新增一个服务（如 `gitea/`）应该是独立 commit +- **版本号更新单独 commit**：`chore(): bump image tag to x.y.z` +- **不要 commit 内容**： + - `env.cfg`（含敏感信息，已 gitignore） + - 编译产物（`*.bin`、`main`、`__pycache__/` 等） + - IDE 配置（`.vscode/`、`.idea/`） + - 系统级配置（`/data/volumes/` 下的实际数据） + +### 历史风格兼容性 + +仓库早期 commit 有少量非 Conventional 风格（如 `Add lsd config and color theme`）， +**新增 commit 一律遵循本规范**，历史风格不强制改写。 + +## AGENTS.md 维护规则 + +AGENTS.md 是给 AI 助手（Claude Code、Codex、Hermes 等）和协作者阅读的项目宪法。 +它**不是写完就不动的文档**，而是要跟着仓库演进持续更新。 + +### 何时更新 AGENTS.md + +出现以下情况之一，**必须**同步更新本文件（在同一个 PR/commit 或紧随其后）： + +1. **新增/删除服务**：增减顶层服务目录（如新增 `gitea/`、下线 `flame/`） +2. **架构变更**：目录结构、命名约定、文件组织方式发生调整 +3. **新增通用约定**：跨多个服务复用的规则（如新的环境变量命名、新的备份策略） +4. **重大操作变更**：升级 Docker 版本、Compose 规范变更、镜像源切换 +5. **AI 助手踩坑**：发现 AI 反复犯同样的错误（如改 Harbor compose.yaml、提交 env.cfg） +6. **私有仓库/凭据变动**：新增私有镜像仓库、凭据管理方式变化 + +### 何时**不**更新 AGENTS.md + +- 单个服务的局部配置变更（写到该服务的 `readme.md`） +- 镜像版本小版本号 bump（写到该服务 `chore` commit） +- 一次性的 bug 修复 +- 与项目规范无关的个人偏好 + +### 内容质量要求 + +写给 AI 看的规则必须**明确、可执行、有上下文**： + +- ✅ **好的写法**： + > `harbor/compose.yaml` 是 `./prepare` 生成的输出文件，**不要手动修改**。 +- ❌ **差的写法**： + > 注意 Harbor 的 compose 文件。 + +好的写法具备三要素： +1. **是什么**（明确对象/文件/命令） +2. **为什么**（背景/原因，让 AI 理解） +3. **怎么办**（具体操作/替代方案） + +### 章节组织 + +新增章节时遵循现有结构： + +```markdown +# 标题 + 简介 + +## 架构与组织 +## 服务规范 +## 部署与运维 +## 重要注意事项 +## 系统配置（etc/） +## Git 提交规范 +## AGENTS.md 维护规则 ← 新章节放在最后 +``` + +- 章节顺序按 **"项目结构 → 规范 → 注意事项 → 工具/脚本 → 治理"** 排列 +- 新章节优先放在文档末尾，避免大改章节编号 +- 章节标题用 `##` 一级章节，**保持中文**（与全文风格一致） + +### 更新流程建议 + +```bash +# 1. 修改 AGENTS.md +$EDITOR AGENTS.md + +# 2. 单独提交（不要和服务代码改动混在一起） +git add AGENTS.md +git commit -m "docs: <本次更新的内容>" + +# 3. 推送到远程 +git push origin main +``` + +典型 commit 消息： +- `docs: 补充 git 提交规范章节` +- `docs: 新增 postgres 服务的部署注意事项` +- `docs: 更新 AGENTS.md 维护规则` +- `docs: 修正 harbor compose.yaml 描述` + +### 验证清单 + +每次更新后过一遍： + +- [ ] 章节顺序合理，编号未乱 +- [ ] 链接、命令路径、文件名拼写正确 +- [ ] 中英文混用风格与现有章节一致 +- [ ] 没有把敏感信息（密码、token）写进文档 +- [ ] 涉及 AI 助手的提醒**具体到文件/命令**，不空泛 +- [ ] 改动反映在 `git status` 中**只**包含 `AGENTS.md` + +### 同步与传播 + +- 复制到其他 stack 仓库时**只复制骨架**（章节标题），不要直接复制内容 +- 不同 stack 的"重要注意事项"差异很大，混用会导致 AI 误判 +- 如果有 fork/PR 流程，AGENTS.md 变更要在 PR 描述里说明理由