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修复模式以及项目自有的领域模板。包packsdocs触及文档但非主导交付物、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. Objective240 字符内的目标句柄模板要求写出不超过 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三列如下GateAppliesEvidencePrompt requirements captured before workpendingpendingTimed checkpoint parsedpendingpendingActive goal checked or createdpendingpendingTarget docs readpendingpendingNearest sibling docs readpendingpendingDocumented source code readpendingpendingplate 项目级模板扩展到 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 parserMDX/内容变更需运行pnpm --filter www build:source或记录 N/ALinks/routes/previews verified检查叶子链接、路由、锚点与ComponentPreview名称或记录 N/APlugin page specifics插件页应用docs-creator的 kit/manual/API 规则或记录 N/ABrowser/render surface changed用 Browser Use 采集证明或记录显式豁免/阻塞Package/API behavior changed加 changeset 或记录 N/AAgent rules or skills changed运行pnpm install并验证生成的技能同步Autoreview加载.agents/skills/autoreview/SKILL.md运行正确目标微小/无本地补丁工作可记录 N/AFinal 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 可以发现项目级模板做了三方面强化车道分类新增Docs lane节要求把文档任务归类为 install、guide/system、plugin/feature、serialization/conversion、workflow/AI、API reference 或 spec/law 之一并据此套用不同的结构规则写进 Work Checklist领域约束把docs-creator规则、pnpm --filter www build:source、pnpm lint:fix、changeset、autoreview 等 plate 工程事实物化为门禁行交接契约新增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.mdagent-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一个文档型目标的标准流程是读与选读取用户请求与命名来源用get_goal检查活跃目标选择流模式文档实现任务默认 one-shot execution建计划外壳若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.mdissue 驱动时用docs/plans/ticket-slug.md。目标/阈值/验证表面/约束/边界/阻塞条件不要通过 CLI 标志传入CLI 只创建静态外壳填满物化计划立即替换占位符、逐行解决门禁不适用的行标记为N/A: reason并附证据不要删除、整体替换或手工收窄已开始持久工作的计划首个检查点实现前完成需求提取逐条可勾选分片工作并随时记录证据每个决策、发现、权衡、失败尝试、评审修复、验证运行与范围变更都要更新计划自动评审非平凡文档变更加载 autoreview 技能运行合适目标修复或记录已接受的问题机械校验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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考