Files
lpt-meta/AGENTS.md
T
cat-shark 84ce312e4b docs: 明确 agent 只在 meta 运行,并登记跨仓库笔记
- AGENTS.md 首页新增「Agent 只在 meta 仓库根目录运行」及三条支撑事实
- 规则与技能位置区分「共有技能唯一来源」与「子项目独有内容」
- 补笔记校验入口与其他技能的调用方式
- .agents/notes/ 收录两篇跨仓库决策笔记;.gitignore 放行 .rgignore
2026-11-18 14:59:56 +08:00

11 KiB
Raw Blame History

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.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):

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.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 本仓库:

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。