Files
lpt-meta/AGENTS.md
T

165 lines
12 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
本仓库不是产品项目,不包含前后端业务代码。它只作为本地工作区协调仓库,用于让 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` 提交规范
- `visual-communication.md` 图示优先(**强制**:布局、流程、结构一律用截图 / SVG / Mermaid 表达,禁止在回复里用等宽字符拼框图)
- `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` 校验写在哪一层、拒绝重复防御
- `plain-language.md` 说人话(**强制**:回答「是什么 / 缺什么 / 怎么改」先给具体对象与取值,再决定要不要统称;颜色、间距、圆角这类就叫「取值」,不拿 token、设计令牌、体系、机制等行话包装;一句话最多一层抽象)
- `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` 取值与调性 · `responsive.md` 窄屏与断点 · `code-standards.md` 写组件与请求层 · `ui-review-checklist.md` 交付自检 · `testing.md` 写测试 · `style-conventions.md` 样式与交互
- 技能(`lpt-fe/.agents/skills/`):`ui-review` 新页面或大范围 UI 改动 · `rule-fixture` 看当前规则下会设计成什么样(改规则前后各跑一次,人工判规则缺口)
- **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 异步链路 · `code-standards.md` 代码规范与 Checkstyle 门禁 · `code-review-checklist.md` 工具查不了的评审项
- 技能(`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-android/AGENTS.md`)
- 规则(`lpt-android/.agents/roles/`):`design-principles.md` 写码前设计计划与页面结构取舍 · `design-system.md` 颜色间距圆角文字与按钮状态取值 · `code-standards.md` Compose 写法与请求层 · `ui-review-checklist.md` 快检与交付自检 · `testing.md` 测试分层与真机验证矩阵
- 技能(`lpt-android/.agents/skills/`):`ui-review` 新页面或整页改版的真机截图评审
- **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`。