尧图网站建设 
Plate 文档写作指南基于 docs-creator 技能构建人机可读的编辑器文档【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/platePlate本仓库开源项目Rich-text editor with AI and shadcn/ui的文档体系以docs-creator技能为文档法律的唯一事实来源。这套规则回答一个核心问题如何写出既教得会人、又能被 Agent 干净解析的文档。本文以 .agents/skills/docs-creator/SKILL.md及其源文件 .agents/rules/docs-creator.mdc为骨架结合仓库中的真实文档如 content/docs/index.mdx、content/docs/(guides)/plugin-rules.mdx/plugin-rules.mdx)、content/docs/installation/plate-ui.mdx与技能系统源码如 .agents/skills/autogoal系统讲解 Plate 文档的分类、语气、结构、编排与校验全流程。读完你将掌握为插件页、指南、安装文档、序列化文档、API 文档和规格文档选择正确页面形态并用可复现的命令与源码证据完成一篇不注水的 Plate 文档。什么是 docs-creatordocs-creator是 Plate 仓库中管理文档风格与工作流的技能skill其声明位于.agents/skills/docs-creator/SKILL.md的 frontmatterCreate or update Plate docs with conversational voice, lane-aware structure, explicit ownership, and code-backed accuracy。它覆盖的范围包括语气与语调voice and tone信息顺序information order泳道选择lane selection归属清晰度ownership clarity反注水规则anti-slop rulesAgent 可用性设计agent affordances插件页章节顺序、kit/手动结构、组件/API 校验、插件专属示例技能自身对坏文档的画像一针见血Most bad Plate docs fail the same way: reference dump instead of a working path, blurred ownership, missing why, vibes instead of code.即坏文档的典型失败模式是参考转储而非可用路径、归属模糊、缺少 Why、用感觉代替代码。源文件与生成副本的关系仓库采用源文件唯一的管理方式真正可编辑的源是 .agents/rules/docs-creator.mdc.agents/skills/docs-creator/SKILL.md 是由源生成的技能副本修改规则后需运行pnpm install重新生成技能副本并在交接前核对生成文本包含预期规则若生成结果漂移应修复源文件并重新生成禁止手工修补生成后的技能文本。这与整个仓库的技能体系一致skiller.toml.agents/skiller.toml管理.agents/skills下的全部技能docs-creator是其中之一。写作前必读清单Read First动笔之前技能要求只读真正能锚定页面的内容而不是从旧散文出发目标文档本身同一泳道内最近的兄弟文档被记录行为或 API 的源码最强基线文档content/docs/index.mdx首页/介绍content/docs/installation.mdx与content/docs/installation/plate-ui.mdx安装content/docs/(guides)/plugin-rules.mdx、content/docs/(guides)/plugin-input-rules.mdx指南content/docs/(plugins)/(serializing)/html.mdx、content/docs/(plugins)/(serializing)/markdown.mdx序列化content/docs/(plugins)/(ai)/ai.mdxAI 工作流当泳道涉及归属、规格真相、文档漂移或写作规范时参考docs/solutions/*的经验沉淀。核心原则是从代码加最佳基线文档出发而不是仅靠旧散文。技能同时强调Silence in the source code is a gap, not an agreement.源码中的沉默是缺口不是共识——文档声称运行时未实现的行为是文档错了。对于涉及 shadcn 风格、registry 组件或 MDX 组件用法的写作还需阅读本地 shadcn 参考语料库包括docs/sync/shadcn/docs-style-corpus-2026-05-31.md该文件记录了 shadcn v4 文档语料统计平均 175.6 行、中位 134 行、平均导语 14.9 词以及ComponentPreview、Steps、CodeTabs等 MDX 组件的使用频次。用法是用 shadcn 作密度、MDX 组件语法与页面脚手架参照用 Plate 源码作行为、归属、包名与示例的权威。泳道体系Lane Mapdocs-creator的核心设计是按泳道选页面形态而不是上次写了什么就用什么。仓库将其归纳为八条泳道泳道职责读者首先需要什么Install / get-started帮助他人采用 Plate选路径、安装、下一步Component / registry item讲解被复制的 UI 组件或 registry 条目预览、安装、用法Guide / system讲解运行时或概念心智模型、归属、快速开始Plugin / feature讲解单一能力它做什么、最快安装、手动路径Serialization / conversion解释导入/导出或往返方向拆分、环境约束Workflow / AI解释多表面流程安装路径、运行时流程、可选 UIAPI reference解释精确表面简短用途、精确契约、注意事项Spec / law / behavior锁定契约模型、归属、证据、明确缺口缺口分类与页面拓扑决策当被问文档有无缺口时技能要求给出页面拓扑决策而非一堆可能的页面。每条缺口对应一种修复方式缺口修复跨多个 API/包缺少心智模型新增指南/系统概念页缺少精确选项、签名或返回值改进 API/reference 部分某能力缺少安装路径改进插件/功能页同一概念被拆进两个小页面合并进更强页面并重定向链接页面只重复已有参考删除或收缩为指向权威页的链接行为在源码中存在但难以发现新增概念指南并交叉链接拥有该行为的参考页强默认原则当行为是一条管道pipeline时概念页优于零散原始页。例如不要为删除和合并各建一页而应建一个Editing Behavior指南把 delete 与 merge 作为小节再把 rule/API 参考链接进去。参考页保持参考Plugin Rules拥有plugin.rules键与动作API 页拥有精确签名与表格插件页拥有功能安装与功能专属行为概念指南拥有跨越这些页面的心智模型。新增概念页时只需在相邻参考页加一条精确交叉链接不要把同一解释复制到每一页。语音规范Voice技能明确指出文档通常在这里出错。核心规则如下直接Direct需要时用you但不要每节都用we或lets。shadcn 式密度Shadcn-dense短段落、具体动词、可见示例第一个可用路径之前不写散文。渐进Progressive每段只引入一个新想法绝不在基础之前落下高级模式。先 Why 后 What每个非显然的选择给出一行理由。引导而非展示Guide, dont just show每个代码块前给一句上下文代码永远不能替代散文。渐进构建Build progressively从简单路径开始读者有了可工作模型后再加复杂度。庆祝完成Celebrate completion用Done.、Thats it.或一句话收尾。真实代码Real code绝不写占位注释// your logic here写读者真正会写的代码。分层强化Reinforce in tiers概念用散文 → 示例用代码 → 枚举/选项矩阵用表格收束。突出真实坑点Highlight real gotchas用 Callout 提示环境约束、安全警告、显式而非自动的行为。关于语气切换技能给出干净解散文用对话式代码块与 API 参考区用 shadcn 极简式同一节内不要混两种语气。被禁止的开头In this guide, we will explore...This comprehensive guide...This robust, powerful, seamless...任何让读者在看见问题之前先吃一堆营销形容词的写法。技能还提供了正反示例对照Writing Voice Examples坏开头This guide provides a comprehensive overview of input rules. Input rules are a powerful feature of Plate...好开头Plugin Input Rules are Plates runtime for typed editor conversions. As you type, paste, or press Enter, the first matching rule transforms the editor on the spot —#becomes a heading,**bold**turns on bold, a pasted URL becomes a link.坏配置示例只写Plugin.configure({ /* options */ });加Here is an example。好配置示例Reach for.configure()when you need more than the default behavior. Lets add a keyboard shortcut:然后给出真实代码Plugin.configure({ shortcuts: { toggle: modalts } });。结构规则Structural Rules首个##之前的开场最多三句话页面讲什么、为读者做什么若存在兄弟概念用一句话内联区分用普通散文不用 Callout一句话说明本篇将走完的流程。第一个##之前不允许出现任何其他内容无功能炫耀、无营销形容词、无 TOC 模仿。仓库中 content/docs/index.mdx 的开场即符合这一形态Plate is a React framework for building rich-text editors...加一张 Choose a Path 卡片选择器随后用What Plate Owns表格明确分层归属。归属Ownership始终说明行为住在哪一层核心运行时、功能包、kit、还是应用本地复制的代码。若页面说kit 还加了 X归属边界就很重要——用表格或 Callout 呈现。对每个被点名的 API读者应在 10 秒内扫出它属于哪个包/层。跨包行为要逐层点名input rule、plugin rule、transform、normalization、selection、UI component、registry kit、app-local copy。未涉及的层不要暗示它存在。散文会模糊边界时用归属表。content/docs/index.mdx的What Plate Owns表格是典型示范platejs拥有核心运行时、platejs/*拥有无头插件、Plate UI registry 拥有经 shadcn CLI 安装的应用本地组件、你的应用拥有复制代码与业务行为。快速路径优先Quick path first读者先做事再进附录。kit 路径是本仓库默认的快速路径。手动/无头路径在后并标注为手动。有多个合法起点时在顶部放小型分支选择器卡片或跳转链接。CLI/手动安装选择优先用CodeTabs的Command与Manual标签页。包管理器变体用普通代码围栏写规范安装/运行命令让 Plate 的命令渲染器自动生成包管理器标签页。content/docs/installation/plate-ui.mdx正是这一模式的落地## CLI Installation (Recommended)放npx shadcnlatest add plate/plate-ui## Manual Installation放npm install platejs及逐插件依赖说明。参考置后Reference last精确 helper 签名、选项矩阵、原语 → 放在结尾的## API Reference。不要在教程章节里撒精确类型签名那会杀死阅读流。风格定位API Reference ProseMirror 式精确教程 Slate 式叙事。Agent 可找到的标题使用稳定、可预测、与代码真实 API 或概念一致的标题名。### createMarkInputRule优于 Creating a mark rule。## Kit Usage/## Manual Usage/## API Reference是仓库内稳定的 slug不要自创同义词。同泳道 → 同标题名。跨页一致性对 Agent 导航至关重要。页面长度超过约 300 行在顶部加锚点列表或 On this page 跳转块。超过约 600 行考虑拆分先问。导航与路由Navigation And Routing新增、移动、合并或删除文档页属于路由变更必须将 MDX 页面放入与其路由匹配的泳道文件夹原始页面树顺序变化时更新content/docs/meta.json根pages侧边栏需显示嵌套分组、标签、描述或中文标题时更新content/docs/meta.json的_plate.categoryGroups路由需要 title、label、description、keywords 或中文标题元数据时更新_plate.items从最近的拥有页加链接而非每个沾边的页面若未添加.cn.mdx页面须知道中文文档可能回退到英文——把它记录为注意事项而不是假装页面已翻译验证路由本身而不只是源文件翻页顺序与侧边栏分组都是渲染契约。不要留下孤儿页面每个新页面都需要路由、导航决策以及至少一条来自所属邻域的有效入站链接。发布文档Release Docs/docs/releases是文档拓扑而非 changeset 策略该路由渲染生成的包发布数据与生成的 Plate UI changelog JSON不要手工编写release-page 的 Plate UI 条目应使用registry-changelog技能负责源条目、生成与验证在/docs/releases保留最近两个主要版本组把更早的 v49 主要组移动到专属/docs/releases/major页面而非埋进大杂烩归档在Older releases下链接每个旧主版本页从Older releases将v48 and earlier链接到/docs/migration/v48changesets 拥有包发布要点但不拥有发布页的保留、路由或归档形态。代码示例规则Code Example Rules仅仓库支撑的示例若 kit 能做到你正在教的引用确切的 kit 文件。包含真实导入明确展示platejs、platejs/react、platejs/*路径。仅在省略显然时使用// ...otherPlugins,。无占位注释// your logic here、// Your validation logic。超过约 15 行的片段用showLineNumbers加{n-m}高亮。文件上下文重要时用titlefilename.tsx。行内代码卫生CommonMark 按反引号串长度匹配行内代码定界符字面 行内会破坏渲染——想展示三重反引号时应改写措辞a triple-backtick fence或用围栏块。链接、演示与预览Links, Demos and Previews链接到具体叶子页而非宽泛枢纽页。同一节内不要三次链接同一目标。若在取代旧页不要链接回旧页——那会强化你正在淘汰的页面。行内链接放在被引用的确切概念上。页面有近亲兄弟概念时在顶部附近链接兄弟页。ComponentPreview name... /仅在 demo 真实存在于 registry 时使用绝不为了页面平衡伪造 demo 名若 demo 晚于文档落地就无预览发布文档等 demo 真实存在后再补。Agent 可用性设计Agent AffordancesAgent 特别受益于散文中的精确名称API 名、文件路径、包说明符——写全拼不用转述可预测的标题 slug相似页面同节同名真实导入导入语句完整到可复制粘贴直接运行不发明 API源码没发布的东西就不存在枚举与变体用表格埋在列表里的枚举会被漏掉近名兄弟消歧若FooPlugin与FooClassicPlugin并存第一句话就要说清本页讲的是哪一个。这套要求的实际价值在仓库的技能生态中可见例如 .agents/skills/plate-plugin-creator/SKILL.md 等派生技能依赖可预测、源码可验证的文档导航skiller.toml中配置的 MCP 服务器npx shadcnlatest mcp也让 AI 工具能直接检查与应用 registry 条目文档越精确Agent 越可靠。反注水规则Anti-Slop Rules明确禁止使用 changelog 腔调previously、now supports、has been removed、new feature、updated to用通用废话或营销形容词开头comprehensive、robust、seamless、powerful、first-class在读者能做任何事之前用列表自夸在快乐路径之前倾倒完整 API 目录混淆包所有行为与应用本地复制代码因为气味相似就把相邻泳道压扁把关键环境限制藏到页面中后段发明跳过必需导入或依赖插件的示例贴大段代码墙却不解释代码为何重要用精确链接就能搞定时复制整块文档在散文中保留过期路由、文件路径、导入或包名写占位注释// your logic here声称运行时未实现的模型或行为以冗余的 Summary 或 Recap 结尾——完成庆祝行就够了发布指向不存在 demo 的ComponentPreview引用即将删除或取代的路由。写作工作流Workflow分类泳道Classify the lane。锁定归属图Lock the owner map。决定页面拓扑新增、合并、删除或交叉链接。定义最快成功路径。从代码收集 1–3 个真实示例。写快速路径。加深层解释与边界。只在物有所值时加入 API/参考材料。接通导航、邻页链接与元数据。剪掉重复、模糊形容词与虚假完整性。对照当前仓库核验每条声明。泳道模板详解Lane TemplatesInstall / Get Started入口文档如content/docs/index.mdx、content/docs/installation.mdx的必填形态短开场Plate 是什么或本篇做什么若有多个起点加紧凑分支选择器链接到精确章节推荐路径在前替代路径在后下一步/接下来去哪。语气动作有明显最佳路径时就替读者选择Lets start with the fastest setup 优于 Several setup options are available保持分支浅层链接精确的下一叶子页用Steps加###步骤标题承载真实流程展示一条可运行命令然后是最小的真实文件编辑来证明安装成功。Component / Registry ItemPlate UI 组件文档或 registry 条目文档应遵循 shadcn 组件形态除非 Plate 源码证明不同的归属模型Frontmatter 标题与描述demo 存在时frontmatter 后立即放真实ComponentPreview name... /## Installation用CodeTabsCommand标签放 CLI 命令仅当手动安装现实时Manual标签用Steps用ComponentSource展示被复制的源文件## Usage先导入再最小可用 JSX## Examples每个###一节一个可见变体源码/demo 真支持时可选## RTL、## Composition等行为节结尾## API Reference用紧凑 prop/option 表格。语气动作组件是视觉的就先预览再解释每个变体预览前一句话即可用精确 registry 名与文件路径除非本页教的就是包本身否则不要给 UI 组件页加PackageInfo不伪造手动路径——若 CLI 是唯一受支持路径直说。Guide / System如plugin-rules.mdx、plugin-input-rules.mdx开场按结构规则最多 3 句存在兄弟概念时立即内联消歧归属模型快速开始更深机制API reference 置后。语气动作开场讲清系统是什么、不是什么归属表放前不埋散文快乐路径先于完整原语目录某事物是显式的就说explicit绝不暗示隐藏默认每个机制节以一行落地语结束若指南讲解管道用可预测的阶段节名如Runtime Pipeline、Break Behavior、Delete Behavior、Merge Behavior、Normalize Behavior、Selection Behavior、Recipes、API Reference概念指南应高于细节、低于参考——让参考页更好用而不是取代它们。Behavior / Runtime Concept当行为跨多个源文件、插件或文档泳道时使用此泳道。读者需要生命周期而不是一堆选项带兄弟消歧的开场如 Use Plugin Rules for declarative node policy; use Editor Methods for imperative transforms.## Choose the Right Surface或等价决策表带归属图的## Runtime Pipeline每个管道阶段一节常见结果的## Recipes链接到权威参考的## API Reference。源码审计路径读公开参考文档 → 读核心分发器或覆写层 → 读真正变更文档的 transform 实现 → 读功能包默认值取示例 → 仅当行为由 UI 拥有时读 UI/registry 代码。语气动作说明哪个阶段拥有行为原语 API 留在参考链接里不在散文中重复决策路径与阶段行为用表格两个听起来相似的术语尽早拆开如文档级合并规则 ≠ 表格单元格合并命令以读者现在能决定或配置什么收尾。Plugin / Feature插件与功能页无头优先包/插件拥有功能Plate UI 组件只是渲染示例除非源码证明它们拥有行为短开场或demo 存在时真实ComponentPreview name... /PackageInfo的功能派生自源码而非营销要点kit 存在时## Kit Usage流程性安装包进Steps用### Installation与### Add Kit含ComponentSource nameactual-kit-name /从apps/www/src/registry/registry-kits.ts列出相关 kit 组件展示createPlateEditor({ plugins: [...RelevantKit] })## Manual Usage展示包安装命令从真实platejs或platejs/*路径导入插件 API将插件加入createPlateEditor仅赋值组件时用.withComponent()选项、快捷键、注入或额外行为参与示例时用.configure()无独立组件的样式插件应强调inject.nodeProps、默认值与inject.targetPlugins仅当工具栏入口真实存在时才写工具栏节——写*ToolbarButton、Turn Into 或 Insert 控件前先查 kit 依赖真实插件对象的## Plugins仅对真实存在的editor.api.plugin.*与editor.tf.plugin.*表面写## API Reference与## Transforms。语气动作kit 路径是快速路径直说即使快速路径用 UI也要让无头包契约保持显式组件是渲染示例不是功能本身绝不要文档化源码未真正发布的插件 API 或 transforms编辑既有页面时保留现有APIOptions、APIParameters、APIReturns格式目标页面无更好兄弟时以content/(plugins)/(functionality)/dnd.mdx为主要插件页结构基线。仓库中的apps/www/src/registry/registry-kits.ts是 kit 事实来源例如basic-blocks-base-kit的registryDependencies列出plate/blockquote-node、plate/heading-node、plate/hr-node、plate/paragraph-nodebasic-marks-base-kit依赖plate/code-node、plate/highlight-node、plate/kbd-node等——文档中描述 kit 时必须与这类 registry 条目一一对应。Serialization / Conversion如html.mdx、markdown.mdx开篇讲清两个方向A→B 与 B→A按方向拆分页面在第一个示例之前声明环境约束服务端 vs 客户端、静态 vs React基础路径清楚后再展示扩展点重的 API reference 放后面。语气动作A to B 与 B to A 绝不共享一节早期用 Callout 点出 server/client/static/React-only 边界为每个环境使用正确导入若往返行为有限制在读者会撞上的地方说明。Workflow / AI如ai.mdx功能启用什么一段最快安装路径运行时架构或流程客户端与服务端拆分可选 UI 表面工具与 API reference。语气动作把必需运行时部件与可选 UI 糖明确分开多表面流程保持显式editor、route、provider、streaming、transforms页面接近 300 行时顶部加页内跳转列表主工作流清楚之前不要倾倒每个 helper。API Reference当页面主要是契约而非上手引导时简短用途段表面分组精确参数、选项、返回值注意事项与约束。语气动作无教程模仿shadcn 极简仍用一句话说明何时使用该 API用API块或统一表格格式示例最小且精确。Spec / Law / Behavior行为规格、法律、协议文档目标或契约显式归属图模型先于 UX 镀铬证据或源码支撑证据缺失处有清晰缺口标记契约清楚后才放参考附录。语气动作在写 hover、toolbar、交互镀铬之前先锁定节点模型与亲和性把参考中的沉默当作缺口而非共识偏好二元措辞而非感觉若文档声称运行时未实现的行为代码改对之前文档就是错的。此泳道比普通概念指南更严格文档将成为未来实现或评审的契约时用它运行时已存在、读者需要理解它时用 Behavior / Runtime Concept。格式化与结构Structure FormattingSteps用于真实多步流程Steps内用###作子步骤CodeTabs仅用于 CLI/手动选择包管理器变体用普通安装/运行命令围栏组件页在预览存在时顶部放ComponentPreview页面要求读者复制 registry 文件时用ComponentSource分支选择用LinkedCard或紧凑卡片而非装饰文件上下文重要时用title...代码块大片段需要聚焦时用showLineNumbers加{n-m}行高亮选项矩阵、归属边界、变体比较用表格环境约束、安全警告、显式而非自动指导用 Callout。不要因为别的页面有ComponentPreview、PackageInfo或大特性列表就硬套——每一节都要凭本事赢得位置。Goal 模板非平凡文档工作的前置流程docs-creator与仓库的autogoal技能.agents/skills/autogoal/SKILL.md协作docs-creator拥有文档教义与路由docs goal 模板拥有结项契约泳道分类、源码支撑声明、归属图、链接/demo 校验、内容构建、反注水审计。对于非平凡文档工作使用 docs goal 模板node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template docs \ --title short docs title适用场景任务创建或重写页面、变更公开行为文档、触及插件/API/规格/序列化文档、移动路由、修改示例或可能留下过期导入、链接、预览、归属声明或 API 声明时。当文档只是另一主导任务下的支撑表面时不要把主模板切到docs而是把 docs pack 加入所属计划node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template task \ --with docs \ --title short task title重型架构或提案工作同时改文档时用主模板加 packs例如node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template major-task \ --with docs \ --title short major task title不要为微小文案编辑、错别字修复或一行链接修复使用 goal 流程除非调用者明确要求 goal 背书的文档任务。docs pack 的契约见 .agents/skills/autogoal/assets/templates/packs/docs.md包含Start Gatesdocs pack 已选、目标文档与最近兄弟文档已读、已识别被记录源码拥有者、Work Checklist命名 API/导入/选项/路由/组件/demo/预览均有源码背书或标记 N/A、使用当前状态参考语气而非 changelog 语气以及 Completion Gates源码背书声明审计、链接/路由/预览校验、文档解析器/构建、autoreview。校验清单Verification Checklist完成文档变更前逐项核对pnpm --filter www build:source能干净解析 MDX可能影响文档源码对齐或生成源时pnpm --filter www check:docs通过每个被点名的 API、选项、transform、组件都存在于源码每个导入路径与当前仓库/包布局匹配每条归属声明与代码匹配每个链接目标或路由真实存在且不会被移除每个ComponentPreview名字指向真实存在的 demo文档导航元数据变化时content/docs/meta.json能解析本地路由检查证明新增/移动页面能渲染——纯文本页用 curl 即可视觉/组件行为用 Browser 证明开场在 3 句或更少内落地首次阅读的读者在到达## API Reference前能完成快乐路径无占位注释、无 TODO、无死锚点无 changelog 腔调previously、now supports、has been removed相邻泳道拆分得足够干净读者能回答这个行为住在哪里若.agents/rules/docs-creator.mdc有变更pnpm install已重新生成技能副本且生成的SKILL.md反映源文件。技能以一句收尾作为终审标准If the page still reads like stitched-together notes, it is not done.如果页面读起来仍像拼贴笔记它就没完成。——这也是整份docs-creator教义的浓缩文档要让读者在最短路径上完成可验证的动作让 Agent 在可预测的结构中精确检索并且每个断言都能在当前仓库的源码里找到落点。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plate 文档写作指南：基于 docs-creator 技能构建人机可读的编辑器文档
Plate 文档写作指南基于 docs-creator 技能构建人机可读的编辑器文档【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/platePlate本仓库开源项目Rich-text editor with AI and shadcn/ui的文档体系以docs-creator技能为文档法律的唯一事实来源。这套规则回答一个核心问题如何写出既教得会人、又能被 Agent 干净解析的文档。本文以 .agents/skills/docs-creator/SKILL.md及其源文件 .agents/rules/docs-creator.mdc为骨架结合仓库中的真实文档如 content/docs/index.mdx、content/docs/(guides)/plugin-rules.mdx/plugin-rules.mdx)、content/docs/installation/plate-ui.mdx与技能系统源码如 .agents/skills/autogoal系统讲解 Plate 文档的分类、语气、结构、编排与校验全流程。读完你将掌握为插件页、指南、安装文档、序列化文档、API 文档和规格文档选择正确页面形态并用可复现的命令与源码证据完成一篇不注水的 Plate 文档。什么是 docs-creatordocs-creator是 Plate 仓库中管理文档风格与工作流的技能skill其声明位于.agents/skills/docs-creator/SKILL.md的 frontmatterCreate or update Plate docs with conversational voice, lane-aware structure, explicit ownership, and code-backed accuracy。它覆盖的范围包括语气与语调voice and tone信息顺序information order泳道选择lane selection归属清晰度ownership clarity反注水规则anti-slop rulesAgent 可用性设计agent affordances插件页章节顺序、kit/手动结构、组件/API 校验、插件专属示例技能自身对坏文档的画像一针见血Most bad Plate docs fail the same way: reference dump instead of a working path, blurred ownership, missing why, vibes instead of code.即坏文档的典型失败模式是参考转储而非可用路径、归属模糊、缺少 Why、用感觉代替代码。源文件与生成副本的关系仓库采用源文件唯一的管理方式真正可编辑的源是 .agents/rules/docs-creator.mdc.agents/skills/docs-creator/SKILL.md 是由源生成的技能副本修改规则后需运行pnpm install重新生成技能副本并在交接前核对生成文本包含预期规则若生成结果漂移应修复源文件并重新生成禁止手工修补生成后的技能文本。这与整个仓库的技能体系一致skiller.toml.agents/skiller.toml管理.agents/skills下的全部技能docs-creator是其中之一。写作前必读清单Read First动笔之前技能要求只读真正能锚定页面的内容而不是从旧散文出发目标文档本身同一泳道内最近的兄弟文档被记录行为或 API 的源码最强基线文档content/docs/index.mdx首页/介绍content/docs/installation.mdx与content/docs/installation/plate-ui.mdx安装content/docs/(guides)/plugin-rules.mdx、content/docs/(guides)/plugin-input-rules.mdx指南content/docs/(plugins)/(serializing)/html.mdx、content/docs/(plugins)/(serializing)/markdown.mdx序列化content/docs/(plugins)/(ai)/ai.mdxAI 工作流当泳道涉及归属、规格真相、文档漂移或写作规范时参考docs/solutions/*的经验沉淀。核心原则是从代码加最佳基线文档出发而不是仅靠旧散文。技能同时强调Silence in the source code is a gap, not an agreement.源码中的沉默是缺口不是共识——文档声称运行时未实现的行为是文档错了。对于涉及 shadcn 风格、registry 组件或 MDX 组件用法的写作还需阅读本地 shadcn 参考语料库包括docs/sync/shadcn/docs-style-corpus-2026-05-31.md该文件记录了 shadcn v4 文档语料统计平均 175.6 行、中位 134 行、平均导语 14.9 词以及ComponentPreview、Steps、CodeTabs等 MDX 组件的使用频次。用法是用 shadcn 作密度、MDX 组件语法与页面脚手架参照用 Plate 源码作行为、归属、包名与示例的权威。泳道体系Lane Mapdocs-creator的核心设计是按泳道选页面形态而不是上次写了什么就用什么。仓库将其归纳为八条泳道泳道职责读者首先需要什么Install / get-started帮助他人采用 Plate选路径、安装、下一步Component / registry item讲解被复制的 UI 组件或 registry 条目预览、安装、用法Guide / system讲解运行时或概念心智模型、归属、快速开始Plugin / feature讲解单一能力它做什么、最快安装、手动路径Serialization / conversion解释导入/导出或往返方向拆分、环境约束Workflow / AI解释多表面流程安装路径、运行时流程、可选 UIAPI reference解释精确表面简短用途、精确契约、注意事项Spec / law / behavior锁定契约模型、归属、证据、明确缺口缺口分类与页面拓扑决策当被问文档有无缺口时技能要求给出页面拓扑决策而非一堆可能的页面。每条缺口对应一种修复方式缺口修复跨多个 API/包缺少心智模型新增指南/系统概念页缺少精确选项、签名或返回值改进 API/reference 部分某能力缺少安装路径改进插件/功能页同一概念被拆进两个小页面合并进更强页面并重定向链接页面只重复已有参考删除或收缩为指向权威页的链接行为在源码中存在但难以发现新增概念指南并交叉链接拥有该行为的参考页强默认原则当行为是一条管道pipeline时概念页优于零散原始页。例如不要为删除和合并各建一页而应建一个Editing Behavior指南把 delete 与 merge 作为小节再把 rule/API 参考链接进去。参考页保持参考Plugin Rules拥有plugin.rules键与动作API 页拥有精确签名与表格插件页拥有功能安装与功能专属行为概念指南拥有跨越这些页面的心智模型。新增概念页时只需在相邻参考页加一条精确交叉链接不要把同一解释复制到每一页。语音规范Voice技能明确指出文档通常在这里出错。核心规则如下直接Direct需要时用you但不要每节都用we或lets。shadcn 式密度Shadcn-dense短段落、具体动词、可见示例第一个可用路径之前不写散文。渐进Progressive每段只引入一个新想法绝不在基础之前落下高级模式。先 Why 后 What每个非显然的选择给出一行理由。引导而非展示Guide, dont just show每个代码块前给一句上下文代码永远不能替代散文。渐进构建Build progressively从简单路径开始读者有了可工作模型后再加复杂度。庆祝完成Celebrate completion用Done.、Thats it.或一句话收尾。真实代码Real code绝不写占位注释// your logic here写读者真正会写的代码。分层强化Reinforce in tiers概念用散文 → 示例用代码 → 枚举/选项矩阵用表格收束。突出真实坑点Highlight real gotchas用 Callout 提示环境约束、安全警告、显式而非自动的行为。关于语气切换技能给出干净解散文用对话式代码块与 API 参考区用 shadcn 极简式同一节内不要混两种语气。被禁止的开头In this guide, we will explore...This comprehensive guide...This robust, powerful, seamless...任何让读者在看见问题之前先吃一堆营销形容词的写法。技能还提供了正反示例对照Writing Voice Examples坏开头This guide provides a comprehensive overview of input rules. Input rules are a powerful feature of Plate...好开头Plugin Input Rules are Plates runtime for typed editor conversions. As you type, paste, or press Enter, the first matching rule transforms the editor on the spot —#becomes a heading,**bold**turns on bold, a pasted URL becomes a link.坏配置示例只写Plugin.configure({ /* options */ });加Here is an example。好配置示例Reach for.configure()when you need more than the default behavior. Lets add a keyboard shortcut:然后给出真实代码Plugin.configure({ shortcuts: { toggle: modalts } });。结构规则Structural Rules首个##之前的开场最多三句话页面讲什么、为读者做什么若存在兄弟概念用一句话内联区分用普通散文不用 Callout一句话说明本篇将走完的流程。第一个##之前不允许出现任何其他内容无功能炫耀、无营销形容词、无 TOC 模仿。仓库中 content/docs/index.mdx 的开场即符合这一形态Plate is a React framework for building rich-text editors...加一张 Choose a Path 卡片选择器随后用What Plate Owns表格明确分层归属。归属Ownership始终说明行为住在哪一层核心运行时、功能包、kit、还是应用本地复制的代码。若页面说kit 还加了 X归属边界就很重要——用表格或 Callout 呈现。对每个被点名的 API读者应在 10 秒内扫出它属于哪个包/层。跨包行为要逐层点名input rule、plugin rule、transform、normalization、selection、UI component、registry kit、app-local copy。未涉及的层不要暗示它存在。散文会模糊边界时用归属表。content/docs/index.mdx的What Plate Owns表格是典型示范platejs拥有核心运行时、platejs/*拥有无头插件、Plate UI registry 拥有经 shadcn CLI 安装的应用本地组件、你的应用拥有复制代码与业务行为。快速路径优先Quick path first读者先做事再进附录。kit 路径是本仓库默认的快速路径。手动/无头路径在后并标注为手动。有多个合法起点时在顶部放小型分支选择器卡片或跳转链接。CLI/手动安装选择优先用CodeTabs的Command与Manual标签页。包管理器变体用普通代码围栏写规范安装/运行命令让 Plate 的命令渲染器自动生成包管理器标签页。content/docs/installation/plate-ui.mdx正是这一模式的落地## CLI Installation (Recommended)放npx shadcnlatest add plate/plate-ui## Manual Installation放npm install platejs及逐插件依赖说明。参考置后Reference last精确 helper 签名、选项矩阵、原语 → 放在结尾的## API Reference。不要在教程章节里撒精确类型签名那会杀死阅读流。风格定位API Reference ProseMirror 式精确教程 Slate 式叙事。Agent 可找到的标题使用稳定、可预测、与代码真实 API 或概念一致的标题名。### createMarkInputRule优于 Creating a mark rule。## Kit Usage/## Manual Usage/## API Reference是仓库内稳定的 slug不要自创同义词。同泳道 → 同标题名。跨页一致性对 Agent 导航至关重要。页面长度超过约 300 行在顶部加锚点列表或 On this page 跳转块。超过约 600 行考虑拆分先问。导航与路由Navigation And Routing新增、移动、合并或删除文档页属于路由变更必须将 MDX 页面放入与其路由匹配的泳道文件夹原始页面树顺序变化时更新content/docs/meta.json根pages侧边栏需显示嵌套分组、标签、描述或中文标题时更新content/docs/meta.json的_plate.categoryGroups路由需要 title、label、description、keywords 或中文标题元数据时更新_plate.items从最近的拥有页加链接而非每个沾边的页面若未添加.cn.mdx页面须知道中文文档可能回退到英文——把它记录为注意事项而不是假装页面已翻译验证路由本身而不只是源文件翻页顺序与侧边栏分组都是渲染契约。不要留下孤儿页面每个新页面都需要路由、导航决策以及至少一条来自所属邻域的有效入站链接。发布文档Release Docs/docs/releases是文档拓扑而非 changeset 策略该路由渲染生成的包发布数据与生成的 Plate UI changelog JSON不要手工编写release-page 的 Plate UI 条目应使用registry-changelog技能负责源条目、生成与验证在/docs/releases保留最近两个主要版本组把更早的 v49 主要组移动到专属/docs/releases/major页面而非埋进大杂烩归档在Older releases下链接每个旧主版本页从Older releases将v48 and earlier链接到/docs/migration/v48changesets 拥有包发布要点但不拥有发布页的保留、路由或归档形态。代码示例规则Code Example Rules仅仓库支撑的示例若 kit 能做到你正在教的引用确切的 kit 文件。包含真实导入明确展示platejs、platejs/react、platejs/*路径。仅在省略显然时使用// ...otherPlugins,。无占位注释// your logic here、// Your validation logic。超过约 15 行的片段用showLineNumbers加{n-m}高亮。文件上下文重要时用titlefilename.tsx。行内代码卫生CommonMark 按反引号串长度匹配行内代码定界符字面 行内会破坏渲染——想展示三重反引号时应改写措辞a triple-backtick fence或用围栏块。链接、演示与预览Links, Demos and Previews链接到具体叶子页而非宽泛枢纽页。同一节内不要三次链接同一目标。若在取代旧页不要链接回旧页——那会强化你正在淘汰的页面。行内链接放在被引用的确切概念上。页面有近亲兄弟概念时在顶部附近链接兄弟页。ComponentPreview name... /仅在 demo 真实存在于 registry 时使用绝不为了页面平衡伪造 demo 名若 demo 晚于文档落地就无预览发布文档等 demo 真实存在后再补。Agent 可用性设计Agent AffordancesAgent 特别受益于散文中的精确名称API 名、文件路径、包说明符——写全拼不用转述可预测的标题 slug相似页面同节同名真实导入导入语句完整到可复制粘贴直接运行不发明 API源码没发布的东西就不存在枚举与变体用表格埋在列表里的枚举会被漏掉近名兄弟消歧若FooPlugin与FooClassicPlugin并存第一句话就要说清本页讲的是哪一个。这套要求的实际价值在仓库的技能生态中可见例如 .agents/skills/plate-plugin-creator/SKILL.md 等派生技能依赖可预测、源码可验证的文档导航skiller.toml中配置的 MCP 服务器npx shadcnlatest mcp也让 AI 工具能直接检查与应用 registry 条目文档越精确Agent 越可靠。反注水规则Anti-Slop Rules明确禁止使用 changelog 腔调previously、now supports、has been removed、new feature、updated to用通用废话或营销形容词开头comprehensive、robust、seamless、powerful、first-class在读者能做任何事之前用列表自夸在快乐路径之前倾倒完整 API 目录混淆包所有行为与应用本地复制代码因为气味相似就把相邻泳道压扁把关键环境限制藏到页面中后段发明跳过必需导入或依赖插件的示例贴大段代码墙却不解释代码为何重要用精确链接就能搞定时复制整块文档在散文中保留过期路由、文件路径、导入或包名写占位注释// your logic here声称运行时未实现的模型或行为以冗余的 Summary 或 Recap 结尾——完成庆祝行就够了发布指向不存在 demo 的ComponentPreview引用即将删除或取代的路由。写作工作流Workflow分类泳道Classify the lane。锁定归属图Lock the owner map。决定页面拓扑新增、合并、删除或交叉链接。定义最快成功路径。从代码收集 1–3 个真实示例。写快速路径。加深层解释与边界。只在物有所值时加入 API/参考材料。接通导航、邻页链接与元数据。剪掉重复、模糊形容词与虚假完整性。对照当前仓库核验每条声明。泳道模板详解Lane TemplatesInstall / Get Started入口文档如content/docs/index.mdx、content/docs/installation.mdx的必填形态短开场Plate 是什么或本篇做什么若有多个起点加紧凑分支选择器链接到精确章节推荐路径在前替代路径在后下一步/接下来去哪。语气动作有明显最佳路径时就替读者选择Lets start with the fastest setup 优于 Several setup options are available保持分支浅层链接精确的下一叶子页用Steps加###步骤标题承载真实流程展示一条可运行命令然后是最小的真实文件编辑来证明安装成功。Component / Registry ItemPlate UI 组件文档或 registry 条目文档应遵循 shadcn 组件形态除非 Plate 源码证明不同的归属模型Frontmatter 标题与描述demo 存在时frontmatter 后立即放真实ComponentPreview name... /## Installation用CodeTabsCommand标签放 CLI 命令仅当手动安装现实时Manual标签用Steps用ComponentSource展示被复制的源文件## Usage先导入再最小可用 JSX## Examples每个###一节一个可见变体源码/demo 真支持时可选## RTL、## Composition等行为节结尾## API Reference用紧凑 prop/option 表格。语气动作组件是视觉的就先预览再解释每个变体预览前一句话即可用精确 registry 名与文件路径除非本页教的就是包本身否则不要给 UI 组件页加PackageInfo不伪造手动路径——若 CLI 是唯一受支持路径直说。Guide / System如plugin-rules.mdx、plugin-input-rules.mdx开场按结构规则最多 3 句存在兄弟概念时立即内联消歧归属模型快速开始更深机制API reference 置后。语气动作开场讲清系统是什么、不是什么归属表放前不埋散文快乐路径先于完整原语目录某事物是显式的就说explicit绝不暗示隐藏默认每个机制节以一行落地语结束若指南讲解管道用可预测的阶段节名如Runtime Pipeline、Break Behavior、Delete Behavior、Merge Behavior、Normalize Behavior、Selection Behavior、Recipes、API Reference概念指南应高于细节、低于参考——让参考页更好用而不是取代它们。Behavior / Runtime Concept当行为跨多个源文件、插件或文档泳道时使用此泳道。读者需要生命周期而不是一堆选项带兄弟消歧的开场如 Use Plugin Rules for declarative node policy; use Editor Methods for imperative transforms.## Choose the Right Surface或等价决策表带归属图的## Runtime Pipeline每个管道阶段一节常见结果的## Recipes链接到权威参考的## API Reference。源码审计路径读公开参考文档 → 读核心分发器或覆写层 → 读真正变更文档的 transform 实现 → 读功能包默认值取示例 → 仅当行为由 UI 拥有时读 UI/registry 代码。语气动作说明哪个阶段拥有行为原语 API 留在参考链接里不在散文中重复决策路径与阶段行为用表格两个听起来相似的术语尽早拆开如文档级合并规则 ≠ 表格单元格合并命令以读者现在能决定或配置什么收尾。Plugin / Feature插件与功能页无头优先包/插件拥有功能Plate UI 组件只是渲染示例除非源码证明它们拥有行为短开场或demo 存在时真实ComponentPreview name... /PackageInfo的功能派生自源码而非营销要点kit 存在时## Kit Usage流程性安装包进Steps用### Installation与### Add Kit含ComponentSource nameactual-kit-name /从apps/www/src/registry/registry-kits.ts列出相关 kit 组件展示createPlateEditor({ plugins: [...RelevantKit] })## Manual Usage展示包安装命令从真实platejs或platejs/*路径导入插件 API将插件加入createPlateEditor仅赋值组件时用.withComponent()选项、快捷键、注入或额外行为参与示例时用.configure()无独立组件的样式插件应强调inject.nodeProps、默认值与inject.targetPlugins仅当工具栏入口真实存在时才写工具栏节——写*ToolbarButton、Turn Into 或 Insert 控件前先查 kit 依赖真实插件对象的## Plugins仅对真实存在的editor.api.plugin.*与editor.tf.plugin.*表面写## API Reference与## Transforms。语气动作kit 路径是快速路径直说即使快速路径用 UI也要让无头包契约保持显式组件是渲染示例不是功能本身绝不要文档化源码未真正发布的插件 API 或 transforms编辑既有页面时保留现有APIOptions、APIParameters、APIReturns格式目标页面无更好兄弟时以content/(plugins)/(functionality)/dnd.mdx为主要插件页结构基线。仓库中的apps/www/src/registry/registry-kits.ts是 kit 事实来源例如basic-blocks-base-kit的registryDependencies列出plate/blockquote-node、plate/heading-node、plate/hr-node、plate/paragraph-nodebasic-marks-base-kit依赖plate/code-node、plate/highlight-node、plate/kbd-node等——文档中描述 kit 时必须与这类 registry 条目一一对应。Serialization / Conversion如html.mdx、markdown.mdx开篇讲清两个方向A→B 与 B→A按方向拆分页面在第一个示例之前声明环境约束服务端 vs 客户端、静态 vs React基础路径清楚后再展示扩展点重的 API reference 放后面。语气动作A to B 与 B to A 绝不共享一节早期用 Callout 点出 server/client/static/React-only 边界为每个环境使用正确导入若往返行为有限制在读者会撞上的地方说明。Workflow / AI如ai.mdx功能启用什么一段最快安装路径运行时架构或流程客户端与服务端拆分可选 UI 表面工具与 API reference。语气动作把必需运行时部件与可选 UI 糖明确分开多表面流程保持显式editor、route、provider、streaming、transforms页面接近 300 行时顶部加页内跳转列表主工作流清楚之前不要倾倒每个 helper。API Reference当页面主要是契约而非上手引导时简短用途段表面分组精确参数、选项、返回值注意事项与约束。语气动作无教程模仿shadcn 极简仍用一句话说明何时使用该 API用API块或统一表格格式示例最小且精确。Spec / Law / Behavior行为规格、法律、协议文档目标或契约显式归属图模型先于 UX 镀铬证据或源码支撑证据缺失处有清晰缺口标记契约清楚后才放参考附录。语气动作在写 hover、toolbar、交互镀铬之前先锁定节点模型与亲和性把参考中的沉默当作缺口而非共识偏好二元措辞而非感觉若文档声称运行时未实现的行为代码改对之前文档就是错的。此泳道比普通概念指南更严格文档将成为未来实现或评审的契约时用它运行时已存在、读者需要理解它时用 Behavior / Runtime Concept。格式化与结构Structure FormattingSteps用于真实多步流程Steps内用###作子步骤CodeTabs仅用于 CLI/手动选择包管理器变体用普通安装/运行命令围栏组件页在预览存在时顶部放ComponentPreview页面要求读者复制 registry 文件时用ComponentSource分支选择用LinkedCard或紧凑卡片而非装饰文件上下文重要时用title...代码块大片段需要聚焦时用showLineNumbers加{n-m}行高亮选项矩阵、归属边界、变体比较用表格环境约束、安全警告、显式而非自动指导用 Callout。不要因为别的页面有ComponentPreview、PackageInfo或大特性列表就硬套——每一节都要凭本事赢得位置。Goal 模板非平凡文档工作的前置流程docs-creator与仓库的autogoal技能.agents/skills/autogoal/SKILL.md协作docs-creator拥有文档教义与路由docs goal 模板拥有结项契约泳道分类、源码支撑声明、归属图、链接/demo 校验、内容构建、反注水审计。对于非平凡文档工作使用 docs goal 模板node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template docs \ --title short docs title适用场景任务创建或重写页面、变更公开行为文档、触及插件/API/规格/序列化文档、移动路由、修改示例或可能留下过期导入、链接、预览、归属声明或 API 声明时。当文档只是另一主导任务下的支撑表面时不要把主模板切到docs而是把 docs pack 加入所属计划node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template task \ --with docs \ --title short task title重型架构或提案工作同时改文档时用主模板加 packs例如node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template major-task \ --with docs \ --title short major task title不要为微小文案编辑、错别字修复或一行链接修复使用 goal 流程除非调用者明确要求 goal 背书的文档任务。docs pack 的契约见 .agents/skills/autogoal/assets/templates/packs/docs.md包含Start Gatesdocs pack 已选、目标文档与最近兄弟文档已读、已识别被记录源码拥有者、Work Checklist命名 API/导入/选项/路由/组件/demo/预览均有源码背书或标记 N/A、使用当前状态参考语气而非 changelog 语气以及 Completion Gates源码背书声明审计、链接/路由/预览校验、文档解析器/构建、autoreview。校验清单Verification Checklist完成文档变更前逐项核对pnpm --filter www build:source能干净解析 MDX可能影响文档源码对齐或生成源时pnpm --filter www check:docs通过每个被点名的 API、选项、transform、组件都存在于源码每个导入路径与当前仓库/包布局匹配每条归属声明与代码匹配每个链接目标或路由真实存在且不会被移除每个ComponentPreview名字指向真实存在的 demo文档导航元数据变化时content/docs/meta.json能解析本地路由检查证明新增/移动页面能渲染——纯文本页用 curl 即可视觉/组件行为用 Browser 证明开场在 3 句或更少内落地首次阅读的读者在到达## API Reference前能完成快乐路径无占位注释、无 TODO、无死锚点无 changelog 腔调previously、now supports、has been removed相邻泳道拆分得足够干净读者能回答这个行为住在哪里若.agents/rules/docs-creator.mdc有变更pnpm install已重新生成技能副本且生成的SKILL.md反映源文件。技能以一句收尾作为终审标准If the page still reads like stitched-together notes, it is not done.如果页面读起来仍像拼贴笔记它就没完成。——这也是整份docs-creator教义的浓缩文档要让读者在最短路径上完成可验证的动作让 Agent 在可预测的结构中精确检索并且每个断言都能在当前仓库的源码里找到落点。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考