diff --git a/.agents/roles/README.md b/.agents/roles/README.md index 7c426b7..86838f8 100644 --- a/.agents/roles/README.md +++ b/.agents/roles/README.md @@ -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 命令时 | diff --git a/.agents/roles/commit-convention.md b/.agents/roles/commit-convention.md new file mode 100644 index 0000000..8477d86 --- /dev/null +++ b/.agents/roles/commit-convention.md @@ -0,0 +1,11 @@ +# 提交规范 + +- **功能**:统一本工作区所有仓库的提交信息格式,让提交历史一眼可读。 +- **何时用**:准备 `git commit` 时;写提交信息时;判断该用哪个类型前缀时。 + +## 规则 + +- 提交信息必须简短且使用中文,不要使用英文长句。 +- 格式:`类型: 简述`,例如 `docs: 更新说明`、`feat: 新增用户登录接口`、`fix: 修复多租户拦截器空指针`、`perf: Feed 只返回摘要`。 + +适用于 meta 与全部子项目仓库。各仓库不必再重复这段规则,示例可按仓库语境自选。 diff --git a/.agents/roles/repo-operations.md b/.agents/roles/repo-operations.md new file mode 100644 index 0000000..8c300cd --- /dev/null +++ b/.agents/roles/repo-operations.md @@ -0,0 +1,11 @@ +# 跨仓库 Git 操作 + +- **功能**:规定在 meta 工作区里对子项目仓库执行 Git 与文件操作的方式,避免误提交、误删除、用错路径。 +- **何时用**:对子项目执行 git 命令时;clone 子项目时;子项目目录存在但不是 Git 仓库时;需要跨仓库批量操作时;派发子任务到某个子项目时。 + +## 规则 + +- 可并行的工作优先用 `subagent` 派到对应子项目执行。 +- 不要删除子项目内的 `.git`,也不要对子项目执行跨仓库的 `git add .`。 +- 对子项目执行 Git 操作时使用 `git -C lpt-be ` 这类形式。 +- 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。 diff --git a/.agents/roles/research-and-reporting.md b/.agents/roles/research-and-reporting.md new file mode 100644 index 0000000..5deb46f --- /dev/null +++ b/.agents/roles/research-and-reporting.md @@ -0,0 +1,20 @@ +# 调研与问题定位 + +- **功能**:约束「调研、排查、定位问题」类任务的推进方式与汇报格式,避免发散式尝试、避免把推测当结论。 +- **何时用**:任务是调研 / 排查 / 定位问题时(例如「现象是不是这个改动引起的」「为什么这里变慢了」);根因不明、需要先取证时;同一方向连续失败两次时。**不适用于已有明确改法的一次性修改。** + +## 规则 + +- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。 +- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。 +- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。 +- 汇报必须按以下**固定三段式**表述,顺序不变;只写结论与关键证据,不要罗列调查过程: + 1. **根因**:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。 + - 附上已排除的可能原因及排除依据。 + 2. **修复方案**:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。 + - 附上当前卡点:还缺哪个信息、需要谁提供。 + 3. **影响范围**:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。 +- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。 +- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。 +- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。 +- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。 diff --git a/.agents/roles/shell-environment.md b/.agents/roles/shell-environment.md new file mode 100644 index 0000000..8de276b --- /dev/null +++ b/.agents/roles/shell-environment.md @@ -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 <<$` 或引号时默认用单引号;只有需要变量插值时才用双引号。 +- 外部程序路径可能有空格时,用 `& '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 或分步验证。 diff --git a/.agents/roles/workspace-layout.md b/.agents/roles/workspace-layout.md new file mode 100644 index 0000000..860d563 --- /dev/null +++ b/.agents/roles/workspace-layout.md @@ -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/`。 diff --git a/AGENTS.md b/AGENTS.md index 6b06523..8ae5a33 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 ` 这类形式。 -- 如果某个子项目目录已存在但不是 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 <<$` 或引号时默认用单引号;只有需要变量插值时才用双引号。 -- 外部程序路径可能有空格时,用 `& '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`。