104 lines
6.5 KiB
Markdown
104 lines
6.5 KiB
Markdown
# LPT Workspace Meta-Repo
|
||
|
||
本仓库不是产品项目，不包含前后端业务代码。它只作为本地工作区协调仓库，用于让 Codex 一次性了解多个独立项目，并在缺失子项目时自动拉取。
|
||
|
||
## 提交规范
|
||
|
||
- 提交信息必须简短且使用中文，不要使用英文长句。
|
||
- 格式：`类型: 简述`，例如 `docs: 更新说明`。
|
||
|
||
## 本仓库
|
||
|
||
| 项目 | SSH 地址 | 建议分支 |
|
||
|------|----------|----------|
|
||
| LPT meta | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git` | `main` |
|
||
|
||
## 仓库结构
|
||
|
||
| 目录 | 用途 |
|
||
|------|------|
|
||
| `lpt-docs` | 概念与设计文档项目，只维护系统概念和设计思路 |
|
||
| `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 本仓库：
|
||
|
||
```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`。
|
||
|
||
## 工作区规则
|
||
|
||
- 本 meta 仓库只维护 `AGENTS.md` 和 `.gitignore`，不要在本仓库根目录创建业务代码或文档。
|
||
- `.gitignore` 忽略所有子项目目录，避免把独立 Git 仓库提交进本 meta 仓库。
|
||
- 不要删除子项目内的 `.git`，也不要对子项目执行跨仓库的 `git add .`。
|
||
- 对子项目执行 Git 操作时使用 `git -C lpt-be <command>` 这类形式。
|
||
- 如果某个子项目目录已存在但不是 Git 仓库，或 clone 因 SSH 权限/网络失败，应停止并说明原因，不要用空目录或本地副本替代。
|
||
|
||
## 文档维护
|
||
|
||
- 所有系统文档统一在 `lpt-docs` 仓库维护，代码仓库不保留 README、`docs/` 等文档文件。
|
||
- 代理协作规范保留在各仓库 `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 或分步验证。
|