ClawHub 的 specs/ 治理体系：规格、计划与回归记录的双轨文档系统

后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载ClawHubOpenClaw 的 Skill Plugin Registry在仓库中维护了一套“公开文档docs/ 维护者规格specs/”的双轨文档体系。本文基于 specs/README.md 展开讲清specs/目录的定位与收录范围、它与docs/的边界规则、目录索引的组织方式并结合 AGENTS.md 的 Durable Intent 策略与 scripts/docs-list.ts、scripts/docs-run.ts 等工具说明规格文档如何在 ClawHub 项目中承载设计意图、约束协作流程以及何时“毕业”进入公开文档。1. specs/ 的定位维护者可见的设计记录区specs/收录的是maintainer-only 或不在导航中出现的记录maintainer-only or non-navigated records这些内容默认不会发布到公开的 ClawHub 文档页docs tab。它的存在是为了让设计决策、系统不变量invariants和设计历史有一个持久、可追溯的落脚点而不是散落在 PR 描述里。按照 specs/README.md 的定义适合放进specs/的内容有五类类别说明目录中的实例产品与实现规格Product and implementation specs描述产品模型与实现契约spec.md253 行registry v1 完整规格、orgs.md580 行前瞻性计划与迁移笔记Forward-looking plans and migration notes尚未落地的路线图、跨仓库迁移记录plans/plugins.md、openclaw-docs-extraction.md回归记录与设计历史Regression notes and design history某个设计决策为何必须保持防止回归regression-notes/5 篇如2026-08-06-discovery-icon-hierarchy.md维护者验证与 CI 策略记录Maintainer validation or CI policy records部署清单、CI 审计标签策略、CLI 冒烟清单ci.md、deploy.md、manual-testing.md跨仓库提取笔记Cross-repo extraction notes评审者需要但用户不需要的上下文openclaw-docs-extraction.md从目录体量看该定位是实打实的当前specs/顶层已有39 个规格文件合计约 5865 行 Markdown另含plans/、regression-notes/、superpowers/三个子目录。体量最大的是 security-moderation.md808 行审核实现与扫描器行为笔记、orgs.md580 行、github-backed-skills.md503 行。2. 与 docs/ 的边界一条“毕业”规则specs/README.md给出了双轨体系最核心的边界规则面向用户/操作者的公开文档属于docs/。当一个 spec 毕业成用户应该阅读的内容时把面向公众的材料移动或概括进docs/specs/里只保留设计记录。这条规则在 docs/README.md 中从另一侧得到了印证docs/是“可发布的、面向用户页面的源”publishable source会被镜像进 OpenClaw 文档站的ClawHub标签页而“仓库搭建、生产部署 runbook、实现计划、设计动机、回归记录、维护者验证记录、内部子系统的意图”这类内容如果某页在教人如何运行或部署 ClawHub 项目本身就应属于specs/而不是公开文档页。也就是说两个目录的分工可以概括为一句话docs/回答“现在怎么用”how to discover, install, publish, report, integratespecs/回答“为什么必须这样工作”why this must work this way。AGENTS.md 的 “Durable Intent Specs” 章节把这条边界写成了对协作方包括 AI Agent的硬约束用specs/持久化系统/子系统意图、不变量与设计动机特别是安全敏感流程moderation、上传门禁、扫描器结论、申诉、封禁、所有权、包可安装性、API 信任边界当代码变更暴露或改变了某个子系统的既定工作方式时更新对应 spec 或补一篇聚焦的 spec 笔记而不是把意图只埋在 PR 文本或公开文档里docs/保持面向用户/操作者解释当前行为与命令内部的“为什么必须这样”上下文放进specs/。一个具体的“毕业”案例可见 openclaw-docs-extraction.mdCLAW-89ClawHub 把原先寄生在 OpenClaw 文档里的 registry 材料抽回本仓库docs/使docs/成为规范源规格笔记记录的是抽取分类哪些内容移入、哪些在 OpenClaw 侧保留摘要链接、哪些完全留在 OpenClaw属于典型“评审者需要、用户不需要”的跨仓库记录。3. 目录索引README 基线 实际增长specs/README.md 的 Index 部分列出了初始的规格清单这里完整保留spec.md原始 registry 模型的产品 实现规格orgs.md组织、发布者成员与 scoped identity 计划github-import.mdGitHub 导入功能规格github-backed-skills.md源端 GitHub 支撑的 skill 目录与安装不变量diffing.mdskill 版本 diff 的 UI/API 设计slug-routing.md内部 Web 路由优先级与 plugin 别名契约og-routes.md公开 OG 卡片元数据抓取与挂起超时catalog-taxonomy.md分类存储、作者主题、浏览排序与修正契约ci.mdPR 检查与生产部署审计标签策略manual-testing.md维护者 CLI 冒烟清单dev-worktrees.md一次性 Worktrunk/Codex worktree 生命周期契约dev-seeding.md本地开发 fixture 播种的归属规则feature-flags.mdKrill Switch 的 SSR、hydration、context 与 fallback 契约mintlify.md文档发布设置笔记openclaw-docs-extraction.mdCLAW-89 抽取分类deploy.mdClawHub 项目的维护者部署清单security-moderation.md审核实现与扫描器行为的详细笔记webhook.mdDiscord webhook 环境变量与 payload 笔记plans/plugins.mdOpenClaw 插件托管的长期计划regression-notes/回归防护笔记如2026-08-06-discovery-icon-hierarchy.md跨内容类型、视口与加载状态的发现页图标策略superpowers/install-surface 设计历史从源码结构看目录实际上已经显著增长除 Index 所列文件外还新增了auth-identity.md、auth-loading.md、download-metering.md、rate-limiting.md、search-insights.md、search-relevance.md、search-weekly-digest.md、plugin-search-intelligence.md/plugin-search-intelligence-web.md、plugin-icon-presentation.md、plugin-inspector-reliability.md、ui-proof.md等 20 余篇规格覆盖鉴权、下载计量、限流、搜索智能、插件展示与 UI 证明等子系统。这些文件遵循同样的组织原则——每篇聚焦一个子系统的意图与不变量而非泛泛的项目介绍。4. 规格文档的 Front Matter 约定summary 与 read_when翻开任意一篇规格例如 spec.md 或 mintlify.md可以看到统一的 YAML front matter 结构--- summary: Mintlify setup notes for publishing docs/. read_when: - Setting up docs site ---summary一句话说明这篇文档的内容read_when一组触发条件告诉读者和 Agent“当你的任务命中以下场景时先读这篇再动手”。这套约定的执行机制在 scripts/docs-list.ts 中脚本会递归扫描文档目录逐个解析 front matter对缺失 front matter、未闭合的 front matter、缺少或为空summary的文件打印错误标记missing front matter、summary key missing等最后输出一张“路径 — 摘要 — Read when”清单并附上提醒“当你的任务命中任何 Read when 提示时先读该文档再编码缺少覆盖时建议补充”。package.json中对应的命令是bun run docs:list # scripts/docs-list.ts列出文档并校验 front matter从源码结构看docs-list.ts扫描的目录由DOCS_DIR环境变量或docs/决定它直接服务于docs/的发布质量而specs/文件沿用相同的 front matter 风格使两类文档在“可检索性”上保持一致——对 LLM 与 Agent 而言read_when本质上是一份机器可读的检索索引。5. 公开文档管道specs 如何不参与、又如何支撑 docsspecs/之所以能“默认不公开”是因为 ClawHub 的公开文档发布链路只消费docs/。从 scripts/docs-run.ts 可以看到这条链路定位 OpenClaw 仓库OPENCLAW_REPO_PATH默认为 sibling 目录校验其存在scripts/docs-sync-publish.mjs取两个仓库的git rev-parse HEADSHA调用 OpenClaw 侧的同步脚本把 ClawHubdocs/同步进本地预览目录.cache/openclaw-docs-preview在预览目录启动 Mintlifymint dev让维护者在本地/clawhub路径检查即将发布的页面。对应命令package.json 第 46–47 行bun run docs:run # 同步 docs/ 到 OpenClaw 文档预览并启动 Mintlify而 specs/mintlify.md 本身就是一个典型的“规格即操作笔记”它记录了发布docs/为可浏览文档站的目标、当前仓库尚未包含 Mintlify 配置mint.jsonmissing的事实、一份最小mint.json示例含 navigation 分组 Start / Concepts / Reference以及推荐的文档 UX 补充。这类“给维护者看的发布设置笔记”按边界规则正是specs/的合法内容——它讲的是如何运维这个项目而不是如何使用这个产品。openclaw-docs-extraction.md 还补充了一条锚点契约anchor contractClawHub 拥有docs/中的入站链接OpenClaw 拥有渲染器与链接审计脚本同步步骤会重写相对页面路径但保留 fragment因此链接问题要在规范源中修复不能在生成镜像里修。这体现了 specs 作为“跨仓库协作契约记录”的价值。6. 代表性规格速览spec.md 与 security-moderation.mdspec.md——v1 产品 实现规格。它是整个 registry 的基线设计Goals 包括快速浏览/发布 agent skill 的最小化 SPAskills 存储于 Convex文件 元数据 版本 统计GitHub OAuth 登录、Convex 备份作为托管 registry 灾难恢复的事实源基于 skill 文本与元数据的向量搜索版本、标签latest 用户标签、changelog 与回滚公开可读、上传需鉴权moderation 徽章 举报处理 全程审计。Non-goals 则明确划出 v1 边界不做付费功能、私有 skills、二进制资产。这种“Goals / Non-goals / Core objects”的结构是后续各子系统规格的共同范式。security-moderation.md——安全敏感流程的意图记录808 行目录中最大。按照 AGENTS.md 的要求moderation、上传门禁、扫描器结论、申诉、封禁、所有权等安全敏感流程的“应当如何工作”必须沉淀在specs/中。specs/README.md 对它的定位是“detailed moderation implementation and scanner behavior notes”——审核实现与扫描器行为的详细笔记供维护者在改动convex/lib/moderation*.ts、securityScan*.ts等模块前对齐既有意图。7. 实操何时往 specs/ 里加内容结合 specs/README.md 与 AGENTS.md 的规则维护者在以下场景应新增或更新specs/文件设计一个跨模块特性前写一份产品/实现规格参照 spec.md 的 Goals / Non-goals / Core objects 结构并加summaryread_whenfront matter代码改动改变了子系统既定行为时更新对应规格或新增聚焦笔记避免意图只存在于 PR 讨论中修复一个容易回归的问题后在 regression-notes/ 下以日期命名文件如2026-09-21-homepage-catalog-defaults.md记录图标层级、UI 契约等防护约束制定部署/CI/验证策略时写入 deploy.md、ci.md、manual-testing.md 一类 runbook材料面向最终用户时不要停留在specs/按“毕业”规则移动或概括进 docs/specs/只留设计记录写完跑一遍bun run docs:list确认 front matter 完整、摘要与 read_when 可被检索工具正常解析。8. 小结ClawHub 的specs/目录不是“过期的设计草稿堆放处”而是一套有明确边界、有校验工具、有毕业机制的文档治理系统它用read_when让 Agent 与人类在动手前找到正确的设计意图用docs/与specs/的分工保证公开文档只承载“怎么用”用 CLAW-89 抽取、Mintlify 同步脚本等实例证明规格笔记能直接支撑跨仓库协作与发布流程。对阅读本仓库的工程师来说遇到安全、moderation、路由、搜索等子系统的改动时第一站应是 specs/README.md 的索引而非直接扎进convex/或src/源码。赞分享后端前端AI 技能AI 插件搜索引擎【免费下载链接】clawhubSkill Plugin Registry for OpenClaw项目地址https://gitcode.com/gh_mirrors/mo/clawhub点击查看免费下载相关推荐LeetCode-Go中的递归算法设计模式分治、回溯与动态规划的联系LeetCode Go中的递归算法设计模式分治、回溯与动态规划的联系 递归算法Recursion Algorithm是解决复杂问题的高效方法尤其在处理具示例工程Mermaid Live Editor 上手指南用代码编辑与分享 Mermaid 图表Mermaid Live Editor 上手指南用代码编辑与分享 Mermaid 图表 Mermaid Live Editor 是一个开源在线图表编辑器。它把前端开发者工具数据可视化Learn Harness Engineering 的 Design-Docs 索引与设计文档治理让 Agent 以仓库为系统记录源Learn Harness Engineering 的 Design Docs 索引与设计文档治理让 Agent 以仓库为系统记录源 本篇文章围绕 learn上一篇Flatris 项目推荐下一篇Kornia 约定与陷阱完全指南张量布局、坐标体系、旋转方向与对齐方式的权威参考创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考