9.7 KiB
9.7 KiB
LPT Workspace Meta-Repo
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 Codex 一次性了解多个独立项目,并在缺失子项目时自动拉取。
调研与问题定位规则
- 本规则适用于「调研、排查、定位问题」类任务(例如“现象是不是这个改动引起的”“为什么这里变慢了”),不适用于已有明确改法的一次性修改。
- 「1 轮调研」指一条连续的最小验证路径:确认现象范围 → 对比可疑改动 → 拿到可复现/可量化的证据。
- 如果 1 轮调研后仍未定位到根因,必须停止自行扩大调查范围,先向用户汇报,由用户决定是否继续调查或调整方向。
- 汇报必须按以下固定三段式表述,顺序不变;只写结论与关键证据,不要罗列调查过程:
- 根因:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 附上已排除的可能原因及排除依据。
- 修复方案:怎么改。分为「必做 / 建议做 / 不建议做」三类,每项标注代价、以及由谁执行(我 / 用户)。
- 附上当前卡点:还缺哪个信息、需要谁提供。
- 影响范围:受影响的功能、用户、环境与数据;不修会怎样;修了会不会连带影响其它东西。
- 根因:问题的直接原因,以及支撑它的证据(命令、文件、提交、返回值)。没有证据的推测禁止写进这一段。
- 三段式之外不另起新段式;额外信息(已排除项、卡点)归到对应段落下面。
- 先用一句话给出结论,再展开三段;不要让用户从推导过程里自己提炼结论。
- 汇报后等待用户决定,不要一边汇报一边继续发散式尝试;同一方向连续失败两次就转为汇报。
- 禁止把「可能是 X」直接当成结论去改代码;只有拿到证据的结论才允许进入修改阶段。
提交规范
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:
类型: 简述,例如docs: 更新说明。
本仓库
| 项目 | SSH 地址 | 建议分支 |
|---|---|---|
| LPT meta | ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git |
main |
仓库结构
| 目录 | 用途 |
|---|---|
lpt-docs |
概念与设计文档项目,只维护系统概念和设计思路 |
工作区级代理技能在
.agents/skills/,图表评审产物在docs/diagrams/。 |lpt-be| Java Spring Boot 后端,提供 REST API、认证、数据库访问 | |lpt-fe| Vue 3 + TypeScript 前端 | |lpt-ai| TypeScript + Fastify 独立 AI 服务 | |lpt-infra| Kubernetes / Traefik 部署与基础设施清单 |
子项目 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 本仓库:
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git lpt-meta
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。Codex 在开始任务前应检查目录是否存在;如果缺失,直接自动 clone,无需用户手动操作:
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。
工作区规则
- 默认并行:不同子项目之间、或同一项目内互不依赖的任务,必须同时推进,不要逐个串行。
- 可并行的工作优先用
subagent派到对应子项目执行;同一仓库/工作目录同时只允许一个写入者(第二个写入者要么等,要么用 worktree 隔离)。 - 只有存在真实依赖(后一步要用前一步的产出)时才串行,并在派发说明里写明依赖点;不要凭「感觉」串行。
- 派发子任务时把已确认口径、涉及文件、验收命令、提交信息写清楚;
OPTIMIZATION_BACKLOG.md只由主代理更新,子代理不要改(避免 meta 仓库并发写)。 - 本 meta 仓库只维护
AGENTS.md、.gitignore、.agents/(代理技能)和docs/diagrams/(图表评审产物),不要在本仓库根目录创建业务代码或系统文档。 .gitignore忽略所有子项目目录,只放行上述根级条目,避免把独立 Git 仓库提交进本 meta 仓库。- 不要删除子项目内的
.git,也不要对子项目执行跨仓库的git add .。 - 对子项目执行 Git 操作时使用
git -C lpt-be <command>这类形式。 - 如果某个子项目目录已存在但不是 Git 仓库,或 clone 因 SSH 权限/网络失败,应停止并说明原因,不要用空目录或本地副本替代。
代理技能与图表
- 工作区级技能放在
.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.md。 lpt-docs只维护系统概念描述和设计思路,不保存开发记录、系统中间态和开发过程产物。- 跨仓库的实现优化清单记录在本仓库
OPTIMIZATION_BACKLOG.md(只放待办、依据与验收标准);概念与设计仍归lpt-docs。 - 修改
lpt-docs后,如需在 meta 仓库补充说明,保持 meta 仓库不复制文档正文。
跨项目调用关系
浏览器 → 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不存在时用 Pythonsqlite3查询,不反复尝试不存在的 CLI。- 编辑文件优先
apply_patch;不要用复杂 PowerShell 字符串重写文件。 - 数据库或生产内容写操作前先查询当前数据;写入必须有明确筛选条件,禁止无条件
DELETE/UPDATE。 - 出现
ParserError、CommandNotFoundException、ParameterBindingException、Cannot find path、PythonSyntaxError时,先排查 shell 语法、引用、PATH、PowerShell 5.1 兼容和workdir。 - 同一 PowerShell 命令连续失败两次后,停止微调长命令;改短命令、脚本文件、数组 splatting 或分步验证。