Plate 开源仓库的 Agent 协作规范与工程化开发工作流指南

• 前端
• 富文本
• UI组件

本篇指南以 Plate 仓库根目录下的 .agents/AGENTS.md 为骨架，系统讲解这套面向 AI Agent 与人类维护者共用的"仓库宪法"：单一事实来源机制、Git/PR 纪律、包工程与文档规范、依赖环境重置、技能选择（Skill Diet）以及源码优先（source-first）的 typecheck 工作流。读完你将掌握在 Plate monorepo 中正确提交改动、排查环境故障、按序执行包级验证与交付 PR 的完整方法，并能把这些约定复用到其他大型开源仓库的协作场景中。

一、AGENTS.md 在 Plate 仓库中的角色：单一事实来源机制

在 Plate 仓库中，Agent 行为的最终权威不是散落在各处的说明文件，而是集中在.agents/目录下的一套"单一事实来源"（source of truth）机制。AGENTS.md 第一条就明确了这一点：

.agents/AGENTS.md和.agents/rules/*.mdc是 source of truth。编辑它们之后运行pnpm install来同步。绝不直接编辑SKILL.md。

这意味着仓库存在一条"规则源 → 生成产物"的单向管线：

• 规则权威文件：.agents/AGENTS.md（总纲）与 .agents/rules/（各主题细则，如task.mdc、major-task.mdc、docs-creator.mdc、changeset.mdc、release-lanes.mdc等）；
• 生成镜像：AGENTS.md（根目录，由 Skiller 生成，文件头注释标明Generated by Skiller与Source: .agents/AGENTS.md）以及.agents/skills/*/SKILL.md（由对应.mdc规则生成）；
• 同步动作：编辑源文件后执行pnpm install触发 skiller 重新应用（根 package.json 中prepare脚本为bun x skiller@latest apply）；
• 顶层入口：CLAUDE.md 全文只有一行@.agents/AGENTS.md，即 Claude Code 等其他 Agent 工具直接引用总纲。

除规则外，.agents/skiller.toml 还配置了默认应用到的 Agent 集合（default_agents = ["claude-code", "codex"]）、技能开关、gitignore 与 MCP 管理策略，并内置了两个 MCP Server 定义（plate，通过npx shadcn@latest mcp启动并注入REGISTRY_URL=http://localhost:3000/rd/registry.json；以及agentation）。

这套设计的直接收益是：任何 Agent（Codex、Claude、自定义工具）进入仓库后，读一个文件即可获得完整行为契约，而维护者只需维护.agents/源文件，避免多份文档漂移。

二、协作基线：沟通、Git 与 PR 纪律

沟通基线

AGENTS.md 对交互风格有两条硬约束，适用于所有提交信息与对话：

• 极度简洁，为简洁可以牺牲语法（"be extremely concise and sacrifice grammar for the sake of concision"）；
• 默认使用英语，仅当用户明确要求时才切换语言。

这两条降低了 Agent 与维护者之间长对话的信息噪声，让 PR 描述、提交信息和交接文本都保持高密度。

Git 纪律：默认不触碰远端

默认状态下禁止git add、commit、push或创建 PR，除非用户明确要求，或当前激活的命令/技能明确要求。这避免了 Agent 擅自污染共享分支；同时规定"脏工作区"不打断工作——不要为无关的本地改动停下来询问，继续工作并忽略无关 diff 即可。

推送范围规则也值得注意：当确实需要提交并推送时，应把src之外的无关脏文件一并纳入，因为这些往往是人工改动或同步的技能/文档更新，不应被静默遗漏。

Task PR 默认：验证过的代码改动默认交付为 PR

task与major-task技能明确要求：经过验证的代码改动必须被提交、推送并作为 PR 打开/更新，除非用户明确说不需要、改动没有本地补丁、或存在真实阻塞。不要把"用户没有单独说开 PR"当成阻塞理由。

配套的强约束是One PR, One Task：

• 每个 PR 都必须有自己独立的task调用和专属任务计划；
• PR body 必须点名该计划，计划必须存在于 PR head，且必须标识出精确的 PR；
• 批次计划只能决定 PR 顺序，永远不能替代每个 PR 的task证据。

autoclosure：不合规 PR 的关闭流程

autoclosure负责对缺少可验证 per-PR 任务证据的 PR 执行"注释 + 关闭"流程：注释必须解释要求、说明如何运行task，并且必须在关闭前成功发布；随后回读注释与CLOSED状态，然后停止，不再评审、修复或合并该 PR。

分支、检查与合并覆盖

• 开 PR 前必须运行check（即pnpm lint && pnpm typecheck && pnpm test:all && pnpm test:slowest，见 package.json），失败则停止修复或如实上报阻塞；
• 若用户明确要求开 PR：不询问确认；若当前分支是main，先创建codex/分支再提交推送；已在非main分支则直接进行；
• 合并覆盖：用户明确说"合并"，就直接合并，不等 CI 变绿、不重复询问，必要时使用 admin merge；
• 已有打开 PR 的分支上，任何后续改动都视为对整体 checkout 的推送授权，不允许把跟进改动只留在本地。

三、包工程与文档规范（Packages）

AGENTS.md 对包管理、文档与产物边界有明确约定：

• DX 优先：为人类与 AI Agent 同时优化体验，JSDoc 必须对 Agent 是一等公民，每个 API 表面应对人与 Agent 都直观；
• 文档只描述最新状态：严禁 changelog 式语言（"has been removed""new feature""previously""now supports"）。文档是面向用户的"当前状态参考"，写作语气与结构遵循 .agents/rules/docs-creator.mdc——即"教人类读得懂、同时让 Agent 解析得干净"；
• 模板是 CI 控制的产物：templates/**不允许手工编辑或提交模板源、manifest 或 lockfile；应修复源 registry、包或工作流输入，让 CI 重新生成模板。本地验证若改写了模板文件，交接前必须还原；
• Barrel 导出：当改动包导出、移动公共文件、增删导出目录下的文件，或 CI 报告pnpm brl产生变更时，必须在最终验证/提交前运行pnpm brl（对应根脚本"brl": "pnpm g:brl"，即turbo --filter "./packages/**" brl）并纳入生成的 barrel 更新；
• 代码风格：单次使用优先内联，仅在被复用时才抽取常量；不为死代码/遗留移除断言写 TDD 用例（例如"不应再包含旧 API X"），直接删除死路径、让测试聚焦当前行为。

这些规则与根 README.md 中"核心插件包 + shadcn/ui 组件 + AI 能力"的产品结构相互呼应：仓库以packages/*（core、slate、basic-nodes、markdown、table、yjs 等约 40 个包）为功能单元，任何公共面变更都会触发 barrel、changeset 与 registry 三道纪律。

四、工具链规范：依赖环境重置与"环境腐败"诊断

AGENTS.md 将本地开发中最容易误判的一类问题显式归类为"安装腐败（install corruption）优先"，而不是产品代码错误。当 typecheck/build/dev 突然出现与当前 diff 对不上的缺模块或包解析错误时，先运行一次pnpm run reinstall再深入调试。

React 运行时环境腐败信号

以下现象被明确列为"先怀疑本地环境，而非产品代码"：

• Invalid hook call；
• resolveDispatcher()/ null dispatcher 崩溃；
• packages/*下出现包级node_modules/react或node_modules/react-dom路径；
• 同一失败堆栈中出现混用的.bun与.pnpmReact 路径。

若pnpm test、bun test或pnpm check以这些信号突然失败，且与当前 diff 对不上，先运行一次pnpm run reinstall；失败形状改变或消失即证明是本地环境腐败；否则再回到正常调试。

reinstall 的清理范围

pnpm run reinstall被定位为"仓库重置按钮"。从 tooling/scripts/reinstall.sh 源码可以看到其精确行为：脚本以仓库根为基准，先收集根node_modules、.turbo、apps/www/.next，再递归查找（排除根node_modules、.git、templates后）所有node_modules与tsconfig.tsbuildinfo，逐一删除后执行pnpm install。

需要强调的是：规则同时警告不要把pnpm run reinstall当作修复真实代码错误的偷懒替代品；例如react-dnd/DnD 修复中若出现 Bun 的Invalid hook call或混用.bun+.pnpmReact 堆栈，不要据此断言 DnD 修复有误，同样先pnpm run reinstall一次再重新打开诊断。

五、技能选择（Skill Diet）与 Plate 专属边界

AGENTS.md 维护了一份"按需加载"的技能清单，默认以task（常规任务）和major-task（重量级架构/迁移/基准任务）为主干，仅在技能真正拥有硬性领域关卡时才加载细分技能：

对于.agents/**、.claude/**、.codex/**、技能、钩子、命令、提示词或用户操作工具这类"agent-native"面，AGENTS.md 规定使用 autogoal agent-native pack、运行agent-native-reviewer，最后以autoreview收尾；task、major-task及 agent-native 工作流可以在无需每次确认的情况下调用其必需的最终autoreview。

此外还有两条按文件触发的规则引用：更新包时在完成前按 .agents/rules/changeset.mdc 写 changeset；定义或更新编辑器行为法、权限图、协议行或一致性覆盖时遵循 .agents/rules/plate-plan.mdc。

Plate 专属 CE 排除

AGENTS.md 显式列出了本仓库默认不安装、不引用的 CE（Compound Engineering）代理清单：data-integrity-guardian、data-migration-expert、data-migrations-reviewer、schema-drift-detector、deployment-verification-agent、dhh-rails-reviewer、kieran-rails-reviewer、kieran-python-reviewer、previous-comments-reviewer、pr-comment-resolver、figma-design-sync，除非用户明确要求。理由是：Plate 是一个框架/编辑器仓库，数据迁移、Rails、部署、PR 线程与 Figma 工作流代理大多是过度的或不匹配的。

目标计划命名规范

• issue 驱动的目标工作：文件名以工单号开头，例如docs/plans/DEV-4510-fix-schema.md；
• 非工单目标工作：保持日期格式，例如docs/plans/2026-02-07-fix-schema.md。

该命名约定与仓库 docs/plans/ 目录中大量2026-04-xx-*.md计划文件完全吻合。

六、开发命令与 typecheck 工作流

Slate v2 兄弟仓库命令门禁

AGENTS.md 对.tmp/slate-v2兄弟仓库有一套分层门禁：日常迭代保持bun check快速（仅 lint、typecheck 与单元/包测试）；bun test:integration-local属于收尾/发布门禁而非迭代门禁，不放进bun check；需要完整浏览器扫描时才用bun check:full，且bun check:full必须先包含发布纪律、slate-browser 证明契约、受限移动端证明、持久 profile 浸泡等发布防护，再跑完整浏览器扫描与bun test:integration-local。真机移动端证明（bun test:mobile-device-proof:raw）只在能产出真实 Appium Android/iOS 证据的机器/设备车道上使用。编辑器内核/浏览器工作期间，优先使用聚焦包测试与聚焦 Playwright grep。

source-first typecheck 原则

仓库默认"源码优先类型检查"：不要仅为跑类型而构建包，除非仓库脚本或失败证明类型检查图仍解析的是构建后的dist产物。若 typecheck 因过期的 workspace 包声明、source/dist 分裂或未解析的包导出而失败，先检查包/应用的paths与源码入口配置；仅当受影响表面确实验证发布产物、或该包没有 source-first typecheck 路径时才构建。

修改包的标准 typecheck 序列

AGENTS.md 给出修改包后的强制命令序列：

# 1. 按任务或 lockfile 状态安装依赖 pnpm install # 2. 对修改的包做源码优先类型检查 pnpm turbo typecheck --filter=./packages/modified-package # 3. 若因图解析到构建产物而失败：当修复 source-entry / paths 是正确长期形态时修复它 # 4. 仅在检查产物输出、包导出或该包确实没有 source-first typecheck 路径时才构建 # 5. 自动修复 lint 问题 pnpm lint:fix

多包与替代命令

多包同时修改时，可在一条命令中指定多个 filter，随后统一 lint：

# 通过源码图同时类型检查多个指定包 pnpm turbo typecheck --filter=./packages/core --filter=./packages/utils # 多个包统一 lint pnpm lint:fix

按提交范围或分支范围做增量检查的替代方案：

# 检查自上次提交以来的改动 pnpm turbo typecheck --filter='[HEAD^1]' # 检查当前分支相对 origin/main 的所有变更包 pnpm turbo typecheck --filter='...[origin/main]' # workspace 粒度操作 pnpm --filter @platejs/core typecheck pnpm --filter @platejs/core lint:fix

这些命令与根 package.json 中的脚本体系一一对应：typecheck指向pnpm g:typecheck（先g:build再turbo --filter "./packages/**" typecheck --only），g:lint/g:lint:fix走 turbo 过滤，check则是"lint + typecheck + test:all + test:slowest"的完整提交门禁。此外 turbo.json 中typecheck任务声明了dependsOn: ["^build"]与缓存策略，lint、brl、clean等任务也有独立的缓存/输出语义，理解这些有助于解释为何局部改动只需跑 filter 级命令。

全项目慢命令（谨慎使用）

以下命令被明确标注为"仅在必要时使用，非常慢"：

• pnpm build：构建所有包；
• pnpm typecheck：根包类型检查（应走 source-first 包图；若它需要 build，除非检查明确面向产物，否则视为 source-entry 技术债）；
• bun run test：迭代期运行快速默认测试套件；
• bun test：仅在完整任务结束时运行全量测试套件。

迭代的正确姿势是"聚焦优先"：先跑包级/文件级针对性检查，只有收尾阶段才动用全项目命令，这与任务细则 .agents/rules/task.mdc 中"验证与变更范围匹配"的要求一致。

七、浏览器验证、goal 计划与最终交付

浏览器使用约束

更新content/**、apps/www/**或packages/**时，应启动相关 dev server 并用浏览器工具验证受影响的路由/UI/包行为；若表面没有可运行的浏览器路径或服务被阻塞，需显式说明。规范要求优先使用 browser-use 工具，不以前置 Playwright/Puppeteer/裸 Chrome DevTools 替代；涉及 Plate registry/浏览器证明时，优先走/blocks/[id]-demo独立演示路由而非 docs 包装页。

交付与验收

综合 AGENTS.md 及 CONTRIBUTING.md，一个合规交付的最终形态是：pnpm check通过、PR 有专属task计划证据、包改动带 changeset（核心包@platejs/slate、@platejs/core、platejs只用 patch，见 .agents/rules/changeset.mdc）、registry-only 改动走 registry-changelog、浏览器/UI 改动附截图或录像。交接文本保持极简，仅报告 PR、issue/tracker、置信度、测试、浏览器证明、结果、注意事项、设计选择与验证项。

八、仓库证据地图

理解上述规范时可直接对照以下文件：

这套规范的可复制之处在于：用"单一事实来源 + 生成镜像 + 同步命令"消除多文档漂移，用"技能按需加载 + PR 独立证据"控制 Agent 行为边界，用"source-first typecheck + 环境腐败优先诊断"保持大型 monorepo 的本地迭代速度。无论你是在 Plate 上贡献插件，还是为其他仓库搭建 Agent 协作体系，AGENTS.md 都是一份可以直接借鉴的工程模板。

• 前端
• 富文本
• UI组件