# 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/` 只存该仓库独有的内容**:`/.agents/roles/`(该仓专属规则)与 `/.agents/skills/`(该仓专属技能)与 `/.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`。