- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实 - 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」 - 补笔记校验入口与其他技能的调用方式 - .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
11 KiB
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。
✅ 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.mdWindows/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):
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):
# 单条门禁
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.mdAI 异步链路 - 技能(
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 本仓库:
git clone -b main ssh://git@git.cat-shark.xyz:2222/cat-shark/lpt-meta.git lpt-meta
只拉取本 meta 仓库时,下列子项目目录不会包含在 Git 内容中。agent 在开始任务前应检查目录是否存在;如果缺失,直接自动 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 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。
跨项目调用关系
浏览器 → 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。