Files
lpt-meta/AGENTS.md
T

145 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LPT Workspace Meta-Repo
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 Codex 一次性了解多个独立项目,并在缺失子项目时自动拉取。
## 调研与问题定位规则
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须按以下**固定三段式**表述,顺序不变;只写结论与关键证据,不要罗列调查过程:
1. **根因**:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 附上已排除的可能原因及排除依据。
2. **修复方案**:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。
- 附上当前卡点:还缺哪个信息、需要谁提供。
3. **影响范围**:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。
- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。
- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。
## 提交规范
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `docs: 更新说明`。
## 本仓库
| 项目 | SSH 地址 | 建议分支 |
|------|----------|----------|
| LPT meta | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git` | `main` |
## 仓库结构
| 目录 | 用途 |
|------|------|
| `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 |
| `lpt-fe` | Vue 3 + TypeScript 前端 |
| `lpt-ai` | TypeScript + Fastify 独立 AI 服务 |
| `lpt-infra` | Kubernetes / Traefik 部署与基础设施清单 |
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
> 工作区级代理技能在 `.agents/skills/`,跨仓库通用规则在 `.agents/roles/`,图表评审产物在 `docs/diagrams/`。
## 子项目 Git 仓库
| 目录 | SSH 地址 | 建议分支 |
|------|----------|----------|
| `lpt-be` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-be.git` | `master` |
| `lpt-fe` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-fe.git` | `master` |
| `lpt-ai` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-ai.git` | `main` |
| `lpt-infra` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-infra.git` | `master` |
| `lpt-docs` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-docs.git` | `main` |
## 首次初始化
首次 clone 本仓库:
```bash
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git lpt-meta
```
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。Codex 在开始任务前应检查目录是否存在;如果缺失,直接自动 clone,无需用户手动操作:
```bash
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-be.git lpt-be
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-fe.git lpt-fe
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-ai.git lpt-ai
git clone -b master ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-infra.git lpt-infra
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-docs.git lpt-docs
```
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
浏览器 → lpt-fe (5158) ──/api──→ lpt-be (5157) ──HTTP──→ lpt-ai (5199)
│
└── MySQL
```
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 或分步验证。