docs: AGENTS 瘦身,通用规则移入 roles 目录

This commit is contained in:
cat-shark
2026-10-10 15:07:44 +08:00
parent a6243c0887
commit eb73ab69f1
7 changed files with 118 additions and 86 deletions
+10 -4
View File
@@ -11,11 +11,12 @@
| 内容 | 位置 | 例子 |
|------|------|------|
| 通用规则(不限仓库) | 本目录,meta 统一管理 | 提交后收口 todo、轮末对账 |
| 项目专属规则 | 各仓库自己的 `AGENTS.md` | 后端的迁移写法、前端的测试隔离 |
| 通用规则(不限仓库) | meta 仓库 `.agents/roles/` | 提交规范、调研汇报、并行委派 |
| 项目专属规则 | 各仓库自己的 `roles/` | 后端的迁移规范、前端的代码标准 |
| 项目知识与架构约定 | 各仓库 `AGENTS.md` | 端口、调用关系、命名约定 |
| 跨仓库待办与验收标准 | `OPTIMIZATION_BACKLOG.md` | 优化条目 |
| 按任务触发的专业指令 | `.agents/skills/` | 绘图评审流程 |
| 工作区级技能 | `.agents/skills/` | `mermaid-diagram` |
| 项目专属技能 | 各仓库自己的 `skills/` | `lpt-be/skills/comment-cleanup` |
## 生效方式(重要)
@@ -50,7 +51,12 @@
## 规则清单
| 规则 | 文件 | 触发点 |
| 规则 | 文件 | 何时用(触发点) |
|------|------|--------|
| todo 收口纪律 | `todo-discipline.md` | 提交后 / 轮末 / 会话压缩后 |
| 并行与委派 | `parallel-and-delegation.md` | 开工排期、派发子任务时 |
| 提交规范 | `commit-convention.md` | 写提交信息时 |
| 调研与问题定位 | `research-and-reporting.md` | 调研/排查/定位问题类任务 |
| Windows / PowerShell 环境 | `shell-environment.md` | 执行 shell 命令、报错排查时 |
| 工作区资产归属 | `workspace-layout.md` | 决定文档/规则/技能放哪时 |
| 跨仓库 Git 操作 | `repo-operations.md` | 对子项目执行 git 命令时 |
+11
View File
@@ -0,0 +1,11 @@
# 提交规范
- **功能**:统一本工作区所有仓库的提交信息格式,让提交历史一眼可读。
- **何时用**:准备 `git commit` 时;写提交信息时;判断该用哪个类型前缀时。
## 规则
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `docs: 更新说明`、`feat: 新增用户登录接口`、`fix: 修复多租户拦截器空指针`、`perf: Feed 只返回摘要`。
适用于 meta 与全部子项目仓库。各仓库不必再重复这段规则,示例可按仓库语境自选。
+11
View File
@@ -0,0 +1,11 @@
# 跨仓库 Git 操作
- **功能**:规定在 meta 工作区里对子项目仓库执行 Git 与文件操作的方式,避免误提交、误删除、用错路径。
- **何时用**:对子项目执行 git 命令时;clone 子项目时;子项目目录存在但不是 Git 仓库时;需要跨仓库批量操作时;派发子任务到某个子项目时。
## 规则
- 可并行的工作优先用 `subagent` 派到对应子项目执行。
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
+20
View File
@@ -0,0 +1,20 @@
# 调研与问题定位
- **功能**:约束「调研、排查、定位问题」类任务的推进方式与汇报格式,避免发散式尝试、避免把推测当结论。
- **何时用**:任务是调研 / 排查 / 定位问题时(例如「现象是不是这个改动引起的」「为什么这里变慢了」);根因不明、需要先取证时;同一方向连续失败两次时。**不适用于已有明确改法的一次性修改。**
## 规则
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须按以下**固定三段式**表述,顺序不变;只写结论与关键证据,不要罗列调查过程:
1. **根因**:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 附上已排除的可能原因及排除依据。
2. **修复方案**:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。
- 附上当前卡点:还缺哪个信息、需要谁提供。
3. **影响范围**:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。
- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。
- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。
+27
View File
@@ -0,0 +1,27 @@
# Windows / PowerShell 环境
- **功能**:约束本机 shell 的用法,避免把 Bash 语法交给 PowerShell、避免 Windows 兼容与编码坑。
- **何时用**:执行 shell 命令时;命令报 `ParserError` / `CommandNotFoundException` / `ParameterBindingException` / `Cannot find path` / Python `SyntaxError` 时;要写脚本、处理引号或中文编码时;操作 Windows 原生组件时;同一命令连续失败两次后。
## 规则
- 默认 shell 视为 Windows PowerShell 5.1;不要假设 Bash、zsh 或 PowerShell 7。必要时先查 `$PSVersionTable.PSVersion`、`Get-Command pwsh -ErrorAction SilentlyContinue`。
- Windows 桌面、Visual Studio/MSBuild、WPF/WinForms/WinUI、COM、注册表、服务、系统托盘、PyInstaller、UI 自动化等任务优先用 Windows 原生环境;不要默认切 WSL。
- 仅在 Linux 部署、Bash 脚本、Linux 工具链或项目本身位于 WSL 时考虑 WSL;跨环境前确认仓库路径、依赖和运行目标。
- 禁止把 Bash 语法交给 PowerShell:`python - <<'PY'`、`cat <<EOF`、`export`、`source`、`rm -rf`、`cp -r`、`xargs`、Bash 后台 `&`。
- PowerShell 中 `&` 是调用运算符;URL 或参数含 `&` 时整体单引号引用。
- 避免 PowerShell 5.1 下使用 Bash 风格 `&&` / `||`;顺序步骤用多行 PowerShell、短命令或多次工具调用。
- 参数含空格、括号、中文、`&|;><$` 或引号时默认用单引号;只有需要变量插值时才用双引号。
- 外部程序路径可能有空格时,用 `& 'C:\path with spaces\tool.exe' arg1`;多参数外部命令优先数组 splatting。
- PowerShell 数组传给外部程序时直接 splat;不要把多个路径或参数拼成一个带空格的字符串。
- 文件操作优先 PowerShell 原生命令和 `-LiteralPath`;遇到参数不存在先按 PowerShell 5.1 兼容写法处理。
- 复杂 Python 不用 `python -c`;涉及 SQL、JSON、中文、反斜杠路径、换行或多层引号时,用仓库脚本、临时 `.py` 或 `apply_patch`。
- 禁止在 PowerShell 用 Bash here-doc。临时传 Python 源码只允许 PowerShell here-string,且尽量保持 ASCII。
- Python 源码含中文常量时,不通过 PowerShell 管道传给 `python -`;用 UTF-8 脚本文件、仓库脚本或 `\uXXXX`。
- 不只依赖 `chcp 65001` 解决编码;必要时同时设置 `$OutputEncoding`、`[Console]::InputEncoding`、`[Console]::OutputEncoding`、`PYTHONUTF8`、`PYTHONIOENCODING`。
- 搜索文本/文件优先 `rg` / `rg --files`;多个根目录作为多个独立参数传入。
- `sqlite3.exe` 不存在时用 Python `sqlite3` 查询,不反复尝试不存在的 CLI。
- 编辑文件优先 `apply_patch`;不要用复杂 PowerShell 字符串重写文件。
- 数据库或生产内容写操作前先查询当前数据;写入必须有明确筛选条件,禁止无条件 `DELETE` / `UPDATE`。
- 出现 `ParserError`、`CommandNotFoundException`、`ParameterBindingException`、`Cannot find path`、Python `SyntaxError` 时,先排查 shell 语法、引用、PATH、PowerShell 5.1 兼容和 `workdir`。
- 同一 PowerShell 命令连续失败两次后,停止微调长命令;改短命令、脚本文件、数组 splatting 或分步验证。
+24
View File
@@ -0,0 +1,24 @@
# 工作区资产归属
- **功能**:规定各类文档与产物放在哪个仓库/目录,避免重复、错位与正文复制。
- **何时用**:新增或修改文档时;决定某段说明该写进哪个仓库时;处理优化清单时;判断某个文件是否该出现在 meta 仓库时;放规则或技能时。
## 规则
### 文档归属
- 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。
- `lpt-docs` 只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。
- 跨仓库的实现优化清单记录在 meta 仓库 `OPTIMIZATION_BACKLOG.md`(只放待办、依据与验收标准);概念与设计仍归 `lpt-docs`。
- 修改 `lpt-docs` 后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。
### meta 仓库的维护边界
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
### 规则与技能的落位
- 通用规则(跨仓库)→ meta 仓库 `.agents/roles/`。
- 项目专属规则 → 该仓库自己的 `roles/`。
- 工作区级技能 → `.agents/skills/<技能名>/`;子项目专属技能 → 该仓库 `skills/`。
+15 -82
View File
@@ -1,27 +1,18 @@
# LPT Workspace Meta-Repo
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 Codex 一次性了解多个独立项目,并在缺失子项目时自动拉取。
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 agent 一次性了解多个独立项目,并在缺失子项目时自动拉取。
## 调研与问题定位规则
## 规则与技能位置
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须按以下**固定三段式**表述,顺序不变;只写结论与关键证据,不要罗列调查过程:
1. **根因**:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 附上已排除的可能原因及排除依据。
2. **修复方案**:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。
- 附上当前卡点:还缺哪个信息、需要谁提供。
3. **影响范围**:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。
- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。
- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。
- **通用规则(跨仓库)**:`.agents/roles/`
- `todo-discipline.md` 待办收口 · `parallel-and-delegation.md` 并行与委派 · `commit-convention.md` 提交规范
- `research-and-reporting.md` 调研与问题定位 · `shell-environment.md` Windows/PowerShell · `workspace-layout.md` 资产归属 · `repo-operations.md` 跨仓库 Git 操作
- **各子项目专属规则**:该仓库自己的 `roles/`(如 `lpt-be/roles/`、`lpt-fe/roles/`)
- **工作区级技能**:`.agents/skills/<技能名>/`
- **子项目专属技能**:该仓库自己的 `skills/`(如 `lpt-be/skills/`)
## 提交规范
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `docs: 更新说明`。
> 规则文件开头必须是三段:名称(一级标题)→ 功能简述 → 关键字/情况(何时用,要简短,正文放后面)。
> 规则与技能的存放边界见 `.agents/roles/workspace-layout.md`。
## 本仓库
@@ -39,7 +30,7 @@
| `lpt-infra` | Kubernetes / Traefik 部署与基础设施清单 |
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
> 工作区级代理技能在 `.agents/skills/`,跨仓库通用规则在 `.agents/roles/`,图表评审产物在 `docs/diagrams/`。
> 图表评审产物在 `docs/diagrams/`。
## 子项目 Git 仓库
@@ -59,7 +50,7 @@
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git lpt-meta
```
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。Codex 在开始任务前应检查目录是否存在;如果缺失,直接自动 clone,无需用户手动操作:
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。agent 在开始任务前应检查目录是否存在;如果缺失,直接自动 clone,无需用户手动操作:
```bash
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-be.git lpt-be
@@ -71,46 +62,6 @@ git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-docs.git lpt-do
clone 完成后,进入或修改某个子项目前,先读取该子项目根目录的 `AGENTS.md`;如果缺失,则读取 `README.md`。
## 工作区规则
> 「什么时候并行、什么时候串行、怎么派活」属于通用规则,见 `.agents/roles/parallel-and-delegation.md`,此处不再重复。
- 可并行的工作优先用 `subagent` 派到对应子项目执行。
- 本 meta 仓库只维护 `AGENTS.md`、`.gitignore`、`.agents/`(代理技能与通用规则)和 `docs/diagrams/`(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。
- `.gitignore` 忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。
- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
## 代理技能、规则与图表
### 规则放在哪
判断标准只有一句:**这条规则换到另一个仓库还成立吗?**
- **通用规则(不限仓库)** 放在 `.agents/roles/`,由本仓库统一管理;例如 todo 收口纪律。
- **项目专属规则** 留在各仓库自己的 `AGENTS.md`(后端迁移写法、前端测试隔离之类)。
- 新增通用规则时,记得在 `AGENTS.md` 里挂上入口:`.agents/roles/` **不是自动加载目录**,
只有 `AGENTS.md`(与按描述触发的 skills)会被读到,不引用等于不生效。
- **规则文件开头必须是三段**:名称(一级标题)→ 功能简述 → 关键字/情况(何时用,要简短,正文放后面)。
- 现行通用规则:`todo-discipline.md`(提交后收口 / 轮末对账 / 压缩后对账)、`parallel-and-delegation.md`(默认并行 / 单写入者 / 派发说明)。
### 技能
- 工作区级技能放在 `.agents/skills/<技能名>/`,不放进子项目;子项目专用技能才留在各仓库 `skills/`。
- `mermaid-diagram`:按业务主题在 `docs/diagrams/<主题>/` 生成 `.mmd` 图源与渲染页,起本地服务在线评审。
- 共享渲染器为 `docs/diagrams/viewer.js`,主题索引为 `docs/diagrams/index.html`;新增主题用脚手架:
`python3 .agents/skills/mermaid-diagram/scripts/new_figure.py --topic <主题> --title "<标题>" --figures "<图名>:<小节>"`。
- 图表面向跨仓库实现评审(链路、现状、架构、表关系),不写入 `lpt-docs`(该仓库只保留系统概念与设计)。
## 文档维护
- 所有系统文档统一在 `lpt-docs` 仓库维护,代码仓库不保留 README、`docs/` 等文档文件。
- 代理协作规范:通用规则在 `.agents/roles/`,各仓库专属规则保留在该仓库 `AGENTS.md`。
- `lpt-docs` 只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。
- 跨仓库的实现优化清单记录在本仓库 `OPTIMIZATION_BACKLOG.md`(只放待办、依据与验收标准);概念与设计仍归 `lpt-docs`。
- 修改 `lpt-docs` 后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。
## 跨项目调用关系
```text
@@ -121,25 +72,7 @@ clone 完成后,进入或修改某个子项目前,先读取该子项目根
lpt-infra 提供 dev/prod 的 Kubernetes 清单和 Traefik 路由。
## Windows / PowerShell 全局规则
## 图表
- 默认 shell 视为 Windows PowerShell 5.1;不要假设 Bash、zsh 或 PowerShell 7。必要时先查 `$PSVersionTable.PSVersion`、`Get-Command pwsh -ErrorAction SilentlyContinue`。
- Windows 桌面、Visual Studio/MSBuild、WPF/WinForms/WinUI、COM、注册表、服务、系统托盘、PyInstaller、UI 自动化等任务优先用 Windows 原生环境;不要默认切 WSL。
- 仅在 Linux 部署、Bash 脚本、Linux 工具链或项目本身位于 WSL 时考虑 WSL;跨环境前确认仓库路径、依赖和运行目标。
- 禁止把 Bash 语法交给 PowerShell:`python - <<'PY'`、`cat <<EOF`、`export`、`source`、`rm -rf`、`cp -r`、`xargs`、Bash 后台 `&`。
- PowerShell 中 `&` 是调用运算符;URL 或参数含 `&` 时整体单引号引用。
- 避免 PowerShell 5.1 下使用 Bash 风格 `&&` / `||`;顺序步骤用多行 PowerShell、短命令或多次工具调用。
- 参数含空格、括号、中文、`&|;><$` 或引号时默认用单引号;只有需要变量插值时才用双引号。
- 外部程序路径可能有空格时,用 `& 'C:\path with spaces\tool.exe' arg1`;多参数外部命令优先数组 splatting。
- PowerShell 数组传给外部程序时直接 splat;不要把多个路径或参数拼成一个带空格的字符串。
- 文件操作优先 PowerShell 原生命令和 `-LiteralPath`;遇到参数不存在先按 PowerShell 5.1 兼容写法处理。
- 复杂 Python 不用 `python -c`;涉及 SQL、JSON、中文、反斜杠路径、换行或多层引号时,用仓库脚本、临时 `.py` 或 `apply_patch`。
- 禁止在 PowerShell 用 Bash here-doc。临时传 Python 源码只允许 PowerShell here-string,且尽量保持 ASCII。
- Python 源码含中文常量时,不通过 PowerShell 管道传给 `python -`;用 UTF-8 脚本文件、仓库脚本或 `\uXXXX`。
- 不只依赖 `chcp 65001` 解决编码;必要时同时设置 `$OutputEncoding`、`[Console]::InputEncoding`、`[Console]::OutputEncoding`、`PYTHONUTF8`、`PYTHONIOENCODING`。
- 搜索文本/文件优先 `rg` / `rg --files`;多个根目录作为多个独立参数传入。
- `sqlite3.exe` 不存在时用 Python `sqlite3` 查询,不反复尝试不存在的 CLI。
- 编辑文件优先 `apply_patch`;不要用复杂 PowerShell 字符串重写文件。
- 数据库或生产内容写操作前先查询当前数据;写入必须有明确筛选条件,禁止无条件 `DELETE` / `UPDATE`。
- 出现 `ParserError`、`CommandNotFoundException`、`ParameterBindingException`、`Cannot find path`、Python `SyntaxError` 时,先排查 shell 语法、引用、PATH、PowerShell 5.1 兼容和 `workdir`。
- 同一 PowerShell 命令连续失败两次后,停止微调长命令;改短命令、脚本文件、数组 splatting 或分步验证。
- 工作区级技能 `mermaid-diagram`:按业务主题在 `docs/diagrams/<主题>/` 出图并本地起服务评审。用法见 `.agents/skills/mermaid-diagram/SKILL.md`。
- 图表根目录为 `docs/diagrams/`,共享渲染器 `docs/diagrams/viewer.js`,主题索引 `docs/diagrams/index.html`。