- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实 - 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」 - 补笔记校验入口与其他技能的调用方式 - .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
160 lines
11 KiB
Markdown
160 lines
11 KiB
Markdown
# LPT Workspace Meta-Repo
|
||
|
||
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 agent 一次性了解多个独立项目,并在缺失子项目时自动拉取。
|
||
|
||
## Agent 只在 meta 仓库根目录运行
|
||
|
||
**工作区里所有 agent 会话都从 meta 仓库根目录启动。** 除 `subagent` 之外,不存在「进入某个子项目目录单独起一个 agent」的正常用法。子项目目录是数据和代码的落点,不是工作目录的入口。
|
||
|
||
这条不是偏好,是几个硬约束推出来的结论:
|
||
|
||
- **上下文只向上读**:harness 只加载工作目录及其父目录的 `AGENTS.md`。从 meta 启动读得到全部子项目规则索引;从 `lpt-be/` 启动读不到另外四个仓库的约定,跨仓库改动就会各写一套。
|
||
- **技能只在一处**:共有技能集中在 meta 的 `.agents/skills/`(见下节)。子项目里没有副本,从子目录启动就发现不了这些技能。
|
||
- **笔记要一起校验**:笔记分散在各仓 `.agents/notes/`,但门禁由 `.agents/scripts/verify-notes.ts` 从 meta 视角一次跑完;在子目录里单跑只能看见一个仓库。
|
||
|
||
需要并行或分批处理多个子项目时,**用 `subagent` 派发,`cwd` 指向目标子项目**,子代理在其中读写文件、跑命令;主会话仍然留在 meta。
|
||
|
||
```text
|
||
✅ meta 根目录(主会话)── subagent(cwd=lpt-be) → 改后端
|
||
└─ subagent(cwd=lpt-fe) → 改前端
|
||
❌ cd lpt-be && 起 agent(看不到其他仓库,也没有共有技能)
|
||
```
|
||
|
||
## 规则与技能位置
|
||
|
||
- **通用规则(跨仓库)**:`.agents/roles/`
|
||
- `todo-discipline.md` 待办收口 · `parallel-and-delegation.md` 并行与委派 · `commit-convention.md` 提交规范
|
||
- `subagent-execution.md` 多部分改动交给子代理、主代理只复核 · `research-and-reporting.md` 调研与问题定位 · `shell-environment.md` Windows/PowerShell · `workspace-layout.md` 资产归属 · `repo-operations.md` 跨仓库 Git 操作
|
||
- `dev-unblock-and-escalation.md` 开发环境自解锁与求助阈值 · `service-boundaries-and-validation.md` 校验写在哪一层、拒绝重复防御
|
||
- `business-terminology.md` 业务名词收敛(**强制**:agent 之间交流系统概念只用 `lpt-docs/docs/concepts/README.md` 术语表里的名称,不自造同义词;表里没有的词先补表再用。代码标识符也由术语表的英文名派生,不为具体位置另起名字)
|
||
- **共有技能(唯一来源,只在 meta)**:`.agents/skills/<技能名>/`
|
||
- `write-notes-like-deepseek/` 非平凡改动留决策笔记(笔记契约 + 三条校验脚本)
|
||
- `mermaid-diagram/` 图表评审
|
||
- **子项目里不放共有技能的副本。** 重复副本会各自漂移,校验路径也会指回不同版本。
|
||
- **子项目 `.agents/` 只存该仓库独有的内容**:`<repo>/.agents/roles/`(该仓专属规则)与 `<repo>/.agents/skills/`(该仓专属技能)与 `<repo>/.agents/notes/`(该仓的决策笔记)。换到另一个仓库不成立的东西才放这里。
|
||
- **跨仓库决策笔记**:`.agents/notes/`(无法归属到单一仓库的决定)
|
||
|
||
> 规则文件开头必须是三段:名称(一级标题)→ 功能简述 → 关键字/情况(何时用,要简短,正文放后面)。
|
||
> 规则与技能的存放边界见 `.agents/roles/workspace-layout.md`。
|
||
|
||
### 笔记校验入口
|
||
|
||
笔记分散在四个仓库,用一条命令从 meta 视角统一校验(不需要切 cwd):
|
||
|
||
```bash
|
||
node .agents/scripts/verify-notes.ts # meta + lpt-be + lpt-fe + lpt-ai 全部跑一遍
|
||
node .agents/scripts/verify-notes.ts lpt-be # 只查指定仓库
|
||
node .agents/scripts/verify-notes.ts --changed # 只查工作区有未提交改动的仓库
|
||
```
|
||
|
||
三条门禁(目录结构、头部骨架、归档封印)任一失败即非零退出。写完或改完任何笔记后跑一次,红了先修再交。
|
||
|
||
需要单条门禁或一键归档时(`AGENT_NOTE_ROOT` 指定笔记根,不设时默认 `cwd/.agents/notes`):
|
||
|
||
```bash
|
||
# 单条门禁
|
||
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts
|
||
|
||
# 归档:只插 Archived: 一行 + 封印 + 列出谁还链着它
|
||
AGENT_NOTE_ROOT=$PWD/lpt-be/.agents/notes node .agents/skills/write-notes-like-deepseek/scripts/archive-agent-note.ts \
|
||
lpt-be/.agents/notes/implemented/<类别>/<文件名>.md \
|
||
--superseded-by lpt-be/.agents/notes/implemented/<类别>/<新笔记>.md
|
||
```
|
||
|
||
归档后未修的入站链接会被 tree 门禁当作死链报出(exit 1),所以死链不过夜。
|
||
|
||
### 子仓库规则与技能索引
|
||
|
||
> 子仓库的 `AGENTS.md` 不会在 meta 会话自动加载(只有工作目录及父目录的 `AGENTS.md` 会被读)。
|
||
> 改动某个子仓库前:先读它的 `AGENTS.md`,再按任务读下面匹配的规则文件;不匹配的不读。
|
||
> 本索引只列**子项目独有**的规则与技能;共有技能在 meta `.agents/skills/`,全仓通用,见上节。
|
||
|
||
- **lpt-fe**(`lpt-fe/AGENTS.md`)
|
||
- 规则(`lpt-fe/.agents/roles/`):`design-principles.md` 新增或重构页面 · `design-system.md` 取值与调性 · `code-standards.md` 写组件与请求层 · `ui-review-checklist.md` 交付自检 · `testing.md` 写测试 · `style-conventions.md` 样式与交互
|
||
- 技能(`lpt-fe/.agents/skills/`):`ui-review` 新页面或大范围 UI 改动
|
||
- **lpt-be**(`lpt-be/AGENTS.md`)
|
||
- 规则(`lpt-be/.agents/roles/`):`database-migration.md` 数据库迁移 · `data-access.md` 数据访问层 · `api-response.md` 响应与 DTO · `ownership-and-markers.md` 内容归属与标记 · `ai-integration.md` AI 异步链路
|
||
- 技能(`lpt-be/.agents/skills/`):`comment-cleanup` 注释清理
|
||
- **lpt-ai**(`lpt-ai/AGENTS.md`)
|
||
- 规则(`lpt-ai/.agents/roles/`):`task-queue.md` 队列契约 · `security-and-degradation.md` 安全边界与降级
|
||
- **lpt-docs**(`lpt-docs/AGENTS.md`):规则(`lpt-docs/.agents/roles/`):`documentation-scope.md` 文档边界
|
||
- 业务名词的唯一权威是 `lpt-docs/docs/concepts/README.md` 术语表;交流用词约束见 `business-terminology.md`
|
||
- **lpt-android / lpt-infra / lpt-companion**:暂无专属规则与技能,按各自 `AGENTS.md` 执行
|
||
|
||
> 索引只写路径与触发场景,不复制正文。新增或删除子仓库规则/技能时同步本节,约束见 `.agents/roles/workspace-layout.md`。
|
||
> 共有技能不进本节:它们只在 `.agents/skills/`,所有仓库通用,不需要逐仓登记。
|
||
|
||
## 本仓库
|
||
|
||
| 项目 | SSH 地址 | 默认拉取分支 |
|
||
|------|----------|--------------|
|
||
| LPT meta | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git` | `main` |
|
||
|
||
> 「默认拉取分支」只用于首次初始化:新人或 LLM 按这一列拉取仓库。它不表示当前的工作分支,实际在哪个分支上开发由维护者决定,不要据此推断。
|
||
|
||
## 仓库结构
|
||
|
||
| 目录 | 用途 |
|
||
|------|------|
|
||
| `lpt-be` | Java Spring Boot 后端,提供 REST API、认证、数据库访问 |
|
||
| `lpt-fe` | Vue 3 + TypeScript 前端 |
|
||
| `lpt-ai` | TypeScript + Fastify 独立 AI 服务 |
|
||
| `lpt-android` | Android 客户端(Kotlin + Compose),学习会话 + 系统级悬浮窗 |
|
||
| `lpt-infra` | Kubernetes / Traefik 部署与基础设施清单 |
|
||
| `lpt-docs` | 概念与设计文档项目,只维护系统概念和设计思路 |
|
||
|
||
> 图表评审产物在 `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` | `master` |
|
||
| `lpt-android` | `ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-android.git` | `master` |
|
||
| `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` |
|
||
|
||
> 「默认拉取分支」只用于首次克隆初始化,下面 `git clone -b` 用的就是这一列。clone 完成后不要假定工作分支:动手前先 `git branch --show-current` 看仓库实际所在分支。
|
||
>
|
||
> **分支 ↔ 环境对应**:`lpt-be` / `lpt-fe` / `lpt-ai` 均为「`master` → prod、`dev` → dev」,部署流水线第一步会校验两者匹配,跨环境出包(例如用 `dev` 发 prod)会被直接拒绝;`lpt-ai` 的 `main` 是历史分支(停在 prod 冻结点),不再用于发版。`lpt-infra` 单分支(`master`),靠 `dev/` 与 `prod/` 目录区分清单。`lpt-android` 为「`master` → 生产包、`dev` → 开发包」,两个分支**只差默认 API 地址**,不参与 k8s 部署(构建在 Gitea 手动触发,第一步会校验分支与默认地址是否匹配)。`lpt-docs` 不参与部署。
|
||
|
||
## 首次初始化
|
||
|
||
首次 clone 本仓库:
|
||
|
||
```bash
|
||
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git lpt-meta
|
||
```
|
||
|
||
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。agent 在开始任务前应检查目录是否存在;如果缺失,直接自动 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 master 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-android.git lpt-android
|
||
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`。
|
||
|
||
## 跨项目调用关系
|
||
|
||
```text
|
||
浏览器 → lpt-fe (5158) ──/api──→ lpt-be (5157) ──HTTP──→ lpt-ai (5199)
|
||
│
|
||
Android → lpt-android ──/api──────────┤
|
||
└── MySQL
|
||
```
|
||
|
||
lpt-android 通过 REST 直连后端,认证走 Sa-Token 请求头 `satoken`,只使用学习会话相关端点。
|
||
lpt-infra 提供 dev/prod 的 Kubernetes 清单和 Traefik 路由。
|
||
|
||
## 图表
|
||
|
||
- 工作区级技能 `mermaid-diagram`:按业务主题在 `docs/diagrams/<主题>/` 出图并本地起服务评审。用法见 `.agents/skills/mermaid-diagram/SKILL.md`。
|
||
- 图表根目录为 `docs/diagrams/`,共享渲染器 `docs/diagrams/viewer.js`,主题索引 `docs/diagrams/index.html`。
|