plate 项目 autogoal 技能体系解析：docs 目标计划模板的结构、门禁与验证机制

plate 项目 autogoal 技能体系解析：docs 目标计划模板的结构、门禁与验证机制

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

导读

本文以 plate 仓库中 autogoal 技能的文档主导型目标计划模板 docs.md 为核心，拆解一套"先立契约、再干活、后验证据"的文档写作工作流：从目标定义、检查点、完成阈值、验证表面到机械校验脚本check-complete.mjs的完整闭环。读完本文，你将掌握如何在 plate 仓库内为文档型任务（如编写插件指南、序列化说明、API 参考）创建可审计的目标计划，理解各门禁表与检查清单的含义，并能在实际任务中正确填写占位符、处理 N/A 分支并完成收尾验证。

一、模板在 autogoal 技能体系中的定位

autogoal 是 plate 仓库.agents/skills/下的一套 Agent 原生技能，其定位是"目标生命周期内核"（goal lifecycle kernel），核心思想在 SKILL.md 中有明确表述：普通提示词是"做下一件事"，而目标是"持续工作直到某个结果为真，或直到证据表明存在真实阻塞"。它不负责项目策略（命令、包管理器、发布规则、浏览器工具属于派生技能或项目自有模板），只负责客观形状、可测量的完成阈值、证据标准、活跃目标冲突处理、持久计划状态、阻塞与完成规则。

目标计划的模板按"主导风险"选择主模板，并可按"触及面"叠加包（pack）：

• 主模板：task（普通执行）、docs（文档主导）、major-task（重架构/提案）、goal-repair（修复模式），以及项目自有的领域模板。
• 包（packs）：docs（触及文档但非主导交付物）、agent-native（改动 Agent 指令/技能/钩子/命令/提示词）、browser（需要真实浏览器/路由/UI 证明）、package-api（改动公共 API/包边界/发布产物）。

本文主角是docs主模板，其通用版本位于 .agents/skills/autogoal/assets/templates/docs.md，而 plate 项目还维护了项目级强化版本 docs/plans/templates/docs.md（下文第六节对比）。模板本身是静态外壳，占位符（{{TITLE}}、{{PLAN_PATH}}、{{TEMPLATE_PATH}}）由辅助脚本物化为具体的docs/plans/<goal-plan>.md计划文件；物化后的计划文件才是运行时真相（runtime truth），校验器只校验这份物化计划。

二、模板骨架逐节拆解

1. Objective：240 字符内的目标句柄

模板要求写出不超过 240 字符的短目标句柄，完整契约放在下方各节。SKILL.md 给出了推荐形状：

<desired end state>; done when <short threshold>; plan <docs/plans/path>.

例如：Write date plugin docs; done when claims source-backed and build passes; plan docs/plans/2026-09-13-date-docs.md。命令、完整 pass 计划、长 issue 列表、约束、边界、迭代策略与阻塞报告都不应塞进create_goal.objective，它们属于计划文件。

2. Goal plan 与 Template 指针

模板通过{{PLAN_PATH}}和{{TEMPLATE_PATH}}记录物化后的计划文件路径与所用模板路径。这不仅是元信息，也是后续check-complete.mjs与修复模式的定位依据：SKILL.md 的 Repair Mode 指出，当出现预期落空时，先读计划中的Template:、技能名、阶段表与完成门禁来定位责任人。

3. Docs source：文档来源登记

模板要求登记文档任务的来源事实：

Docs source: - type: pending - id / link: pending - title: pending - acceptance criteria: pending

这保证任何文档目标都有可追溯的来源（issue、PR、需求描述），并明确"什么算完成"的验收标准，避免凭空写作。

4. First checkpoint：实现前的需求提取闸门

这是模板中最强调的一步：在实现或广泛探索之前，把用户提示中的每一个显式需求复制为计划中可勾选的检查点，覆盖范围（scope）、非目标（non-goals）、时间/时长（timing/duration）、停止条件（stop conditions）、交付物（deliverables）、最终交接章节（final handoff sections）、验证表面（verification surface）与成功标准（success criteria）。原因写在 SKILL.md 中：Codex 输出可能被压缩而丢失提示词约束，因此"不要在本步完成或明确标记 N/A 并给出理由之前进入实现"。

5. Timed checkpoint：时长检查点语义

当用户给出30m、1h、2 hours、10h之类的时长时，除非显式声明max、stop at、budget cap或timebox hard stop，一律视为"最小活跃工作时长"而非硬停止。语义要点：

• 不是"前几个门禁通过就可以提前收工"的许可；
• 在没有更优度量时，先建立 0–100 的初始置信度记分卡，记录初始分、各维度分、什么能提升分数、什么会压低置信度、下一个改进包、交接时的最终分；
• 到达时长后要干净收尾：完成当前数据包、验证、回滚或隔离不安全的半成品、更新计划、交接，不允许因为"时钟到期"而留下脏的半成品。

6. Completion threshold：可度量的完成阈值

通用 docs 模板要求"定义精确的 docs done 状态"，并给出可度量的示例（分数、数量、延迟、覆盖率、通过数、失败的 repro 数、issue 行数、显式命令成功），或可审计的二进制工件清单（命名文件存在且含必需章节、命名浏览器路由有截图证明且无控制台错误、命名 API 示例可编译且符合已接受的公共形状）。plate 项目级 docs 模板进一步细化：文档关闭仅在"页面教授最快正确路径、每个声明都有源码背书、docs 车道形态满足、必需 MDX/链接/预览检查已记录、check-complete.mjs通过"时合法。

7. Verification surface 与 Constraints

验证表面必须指名"哪个命令、工件、浏览器证明、源码审计或报告能证明阈值"。通用模板的约束包括：

• 遵循最近的既有文档风格；
• 只写当前状态（current-state）文档，不用变更日志口吻；
• 示例必须仓库背书且可复制粘贴；
• 不得发明 API、路由、演示、导入、组件、变换或选项。

项目级模板追加了：遵循.agents/rules/docs-creator.mdc的文档风格与工作流；微小文案/拼写类编辑不引入文档仪式。

8. Boundaries 与 Blocked condition

边界明确"可以碰什么"：真相来源、允许编辑范围、浏览器表面、追踪器同步、非目标；阻塞条件则指名"缺少哪个源码、文档入口、路由、产品决策或命令失败会停止自主文档工作"。这两节是目标契约的"护栏"，防止 Agent 越界或在不该停的时候停、在该停的时候硬撑。

三、Start Gates：开工前的事实闸门

通用 docs 模板的开工门禁表（含Gate/Applies/Evidence三列）如下：

plate 项目级模板扩展到 12 行，新增docs-creator已加载、文档车道已选择、文档风格教义已读、所有权图已起草、插件页规则决策、浏览器/渲染证明决策、PR/追踪器预期决策等。这些行构成"动笔之前必须读完目标文档、兄弟文档与文档化源码"的证据链。

四、Work Checklist 与 Completion Gates：写作与收尾的机械约束

1. 工作检查清单（勾选即证据）

通用模板的清单要求：目标/阈值/验证表面/约束/边界/阻塞条件具体化；工作阶段以证据更新；决策与权衡被记录；失败尝试与下一个不同动作被记录。项目级模板扩充为 18 项，值得注意的条目包括：

• 打开语不超过三句且避免泛泛套话；
• 命名 API、选项、变换、组件、导入、路由与包说明符必须精确且最新；
• 插件文档满足 kit/manual/API 顺序与无头包所有权；
• 序列化文档先拆分方向并在示例前说明环境约束；
• API 参考文档用精确契约、避免教程式填充；
• 演示/预览必须是真实注册表条目或标记 N/A 并说明理由；
• 反废话（anti-slop）审计通过：无变更日志口吻、无假 API、无占位注释、无 TODO、无死锚点、无冗余摘要章节；
• 工作区权威记录：每个证明命令都要点名拥有变更文档的 cwd/工具；
• 非平凡文档工作选择评审/自动评审目标，或标记 N/A。

2. 完成门禁（收尾前必须逐行关闭）

通用模板的完成门禁包括：命名验证阈值、类型检查/构建/测试证明、浏览器证明、Autoreview、Timed checkpoint、Goal plan complete。项目级 docs 模板的完成门禁更贴近 plate 的工程流水线：

• Named verification threshold：运行计划中指名的源码审计、parser/build、链接/演示检查或评审；
• Docs lane shape satisfied：按docs-creator检查车道特定结构；
• Source-backed claim audit：逐个核对命名的 API/选项/变换/组件/导入/路由；
• Ownership map verified：确认包/层/kit/应用本地所有权声明；
• MDX/content parser：MDX/内容变更需运行pnpm --filter www build:source，或记录 N/A；
• Links/routes/previews verified：检查叶子链接、路由、锚点与<ComponentPreview>名称，或记录 N/A；
• Plugin page specifics：插件页应用docs-creator的 kit/manual/API 规则，或记录 N/A；
• Browser/render surface changed：用 Browser Use 采集证明或记录显式豁免/阻塞；
• Package/API behavior changed：加 changeset 或记录 N/A；
• Agent rules or skills changed：运行pnpm install并验证生成的技能同步；
• Autoreview：加载.agents/skills/autoreview/SKILL.md运行正确目标，微小/无本地补丁工作可记录 N/A；
• Final lint：运行pnpm lint:fix或等价的局部命令；
• Goal plan complete：运行node .agents/skills/autogoal/scripts/check-complete.mjs {{PLAN_PATH}}。

可见：门禁表不只是仪式，它把"文档写完了吗"翻译成可执行的工程动作（构建、链接检查、lint、autoreview），且每一项都允许诚实的 N/A 分支。

五、check-complete.mjs：机械校验器如何工作

完成门禁中唯一的"必选"行（Applies = yes）是Goal plan complete，它调用 check-complete.mjs。这个脚本是纯机械校验，源码实现（见 check-complete.mjs#L88-L161）逐条检查计划内容：

• 路径约束：目标计划必须位于docs/plans/之下（relativePlanPath.startsWith('docs/plans/')），否则直接报goal plan must live under docs/plans/；
• 必需章节具体化：Objective、Completion threshold、Verification surface、Constraints、Boundaries、Blocked condition必须存在且"具体"——hasConcreteContent会剔除 HTML 注释与纯分隔线、拒绝含TODO/TBD的内容、拒绝只有pending/none yet的占位内容；
• 工作清单：必须包含- [ ]/- [x]形式的清单项，且不能残留未勾选项（state === ' '的行会被列出具体行号）；
• 门禁表：Start Gates与Completion Gates表必须包含gate、applies、evidence列，每一行的Gate/Applies/Evidence与其余自定义列都不能为空、pending、TODO或TBD（见 check-complete.mjs#L163-L213）；
• 阶段表：Phase / pass table至少一行状态，且不允许残留pending/in_progress/todo/open之类的开放状态；
• 收尾章节：Verification evidence必须记录新鲜的最终证据，Reboot status必须当前，Open risks必须记录（即使值是None）。

脚本通过向上查找AGENTS.md定位仓库根（findRepoRoot，见 check-complete.mjs#L370-L388），因此可在仓库任意子目录执行。需要强调的是：脚本只能证明"计划看起来关闭了"，不能证明"工作真的对了"，正如其--help输出所说——它不能替代计划点名的测试、浏览器证明、源码审计或工件验证。

六、通用模板与 plate 项目级模板的差异

对比 .agents/skills/autogoal/assets/templates/docs.md 与 docs/plans/templates/docs.md 可以发现项目级模板做了三方面强化：

1. 车道分类：新增Docs lane节，要求把文档任务归类为 install、guide/system、plugin/feature、serialization/conversion、workflow/AI、API reference 或 spec/law 之一，并据此套用不同的结构规则（写进 Work Checklist）；
2. 领域约束：把docs-creator规则、pnpm --filter www build:source、pnpm lint:fix、changeset、autoreview 等 plate 工程事实物化为门禁行；
3. 交接契约：新增Final handoff contract与Final handoff / sync两节，要求最终响应携带 PR 行、issue/追踪器行、置信度行、文档车道、源码背书声明、内容构建/parser、链接/演示/预览、浏览器检查、结果、注意事项与已验证状态，把"交接给人类"也变成可勾选的契约。

七、packs：可选叠加的触及面门禁

当文档不是主导交付物，但工作确实触及文档时，用--with docs叠加 docs pack。它追加三行开工门禁（docs pack 已选择、目标文档与最近兄弟文档已读、文档化源码所有者已识别）、三条清单项（API/导入/选项/路由/组件/演示/预览有源码背书或标记 N/A；使用当前状态口吻而非变更日志口吻）与三条完成门禁（源码背书声明审计、链接/路由/预览验证、文档 parser/build）。

其余包的语义（源码见 packs/agent-native.md、packs/browser.md、packs/package-api.md）：

• agent-native：改动 Agent 指令/技能/钩子/命令/提示词时使用，要求识别规范源与生成副本、检查技能 frontmatter、运行验证器或安装检查；
• browser：行为有真实浏览器/路由/UI/选择/交互/控制台/网络表面时使用，要求记录路由与交互路径、按 Browser→Chrome→Computer Use 的次序选择证明工具、检查控制台与网络错误；
• package-api：改动公共 API/包边界/导出/发布产物时使用，要求记录公共契约与边界、显式做出兼容/迁移/硬切决定、运行包级 typecheck/build/test 证明。

模板组合采用"静态物化"模型：辅助脚本把包的行复制进生成计划的Start Gates、Work Checklist与Completion Gates，此后生成计划即真相，不存在运行时模板继承。

八、实战流程：从脚手架到收尾

结合 SKILL.md 的 Start Workflow 与 README.md，一个文档型目标的标准流程是：

1. 读与选：读取用户请求与命名来源，用get_goal检查活跃目标，选择流模式（文档实现任务默认 one-shot execution）；

2. 建计划外壳（若docs/plans/templates/缺失先初始化）：

   node .agents/skills/autogoal/scripts/init-templates.mjs node .agents/skills/autogoal/scripts/create-goal-scratchpad.mjs \ --template docs \ --title "<short docs task title>"

   辅助脚本写入docs/plans/YYYY-MM-DD-<slug>.md（issue 驱动时用docs/plans/<ticket>-<slug>.md）。目标/阈值/验证表面/约束/边界/阻塞条件不要通过 CLI 标志传入，CLI 只创建静态外壳；

3. 填满物化计划：立即替换占位符、逐行解决门禁，不适用的行标记为N/A: <reason>并附证据；不要删除、整体替换或手工收窄已开始持久工作的计划；

4. 首个检查点：实现前完成需求提取，逐条可勾选；

5. 分片工作并随时记录证据：每个决策、发现、权衡、失败尝试、评审修复、验证运行与范围变更都要更新计划；

6. 自动评审：非平凡文档变更加载 autoreview 技能运行合适目标，修复或记录已接受的问题；

7. 机械校验：

   node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/<goal-plan>.md

   校验通过后，仅在目标真实达成时才调用update_goal(status: complete)；因"用户改主意"而完成的旧目标不算完成——完成意味着旧目标本身为真。

九、填写模板的实践要点

• 占位符处理：TODO、pending、TBD三类文本会被校验器视为未解决，必须替换为具体内容或N/A: <原因>；
• 数值优先：能用数字（分数、通过数、覆盖率、延迟）就用数字；不适合数字时用可从文件/命令/截图/浏览器证明/源码引用审计的二进制工件清单；
• 证据类型契约：每条完成证明至少属于一种类型——command（命令+cwd+通过/失败）、source-audit（精确文件或搜索查询）、browser（路由+交互+截图或控制台/网络说明）、artifact（生成文件/报告/PR 体/issue 评论）、review（评审者/工具+接受的问题+修复）、external-source（作为权威的外部来源）、N/A:<reason>；
• 输出预算纪律：活跃目标内优先窄读（精确文件、聚焦的rg -n、定向 glob、短sed -n区间），tmp/**、日志、二进制、构建产物、node_modules、.next、.turbo与覆盖率目录默认排除；宽审计先要计数/文件名/顶部匹配，再考虑打印匹配行；意外的大输出后立即停止宽探索并记录到错误尝试行。

十、小结

docs.md 模板是 autogoal 体系把"文档写作"变成"可审计目标"的载体：开工前的需求提取与来源登记、过程中的分阶段证据、收尾时的源码背书审计、内容构建、链接/演示检查、lint 与 autoreview，最后由check-complete.mjs做一次纯机械的完整性把关。它刻意区分"计划看起来关闭"与"工作真实完成"，并允许每一行诚实的 N/A 分支，避免仪式压过实质。在 plate 仓库中，这套机制与 docs/plans/templates/docs.md 的项目级强化结合，构成了面向文档车道、可机器校验、可交接给人类的完整闭环。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate