部署检查清单

在将 Apothem 生态系统部署到新机器、与他人共享或将其视为可投入生产之前的 飞行前验证步骤。

1. YAML 有效性Copy Anchor Link

• 所有规则文件均无 YAML 错误地解析——frontmatter 块以 --- 开头、以 --- 结尾，且块外无孤立内容
• 所有委派工作者文件均无 YAML 错误地解析
• 所有命令文件均无 YAML 错误地解析
• 所有技能 SKILL.md 文件均无 YAML 错误地解析

验证方法： python scripts/dev/validate_ecosystem.py 解析每个制品的 frontmatter，并标记 YAML 错误和缺失的必填字段。如需临时 检测孤立列表项：rg -n "^- " src/apothem/rules/*.md。

2. Frontmatter 完整性Copy Anchor Link

对于每种制品类型，验证必填字段是否存在：

规则（src/apothem/rules/*.md）Copy Anchor Link

• name——与文件名匹配的 kebab-case 标识符
• description——单句摘要
• alwaysApply——始终生效的规则为 true，按路径过滤的规则为 false
• pathFilter——每条规则都必须存在：始终生效的规则（alwaysApply: true）为 ""，按路径过滤的规则（alwaysApply: false）为逗号分隔的 glob 列表

规则不包含 version、updated、scope 或 portability 键。

命令（src/apothem/commands/*.md）Copy Anchor Link

• name——kebab-case 命令名
• version、updated、description、argument-hint、portability、allowed-tools 均存在
• disable-model-invocation 存在且为有意设置（只读或咨询类命令为 false；仅当运行该命令会改变工作树之外的状态，或依赖操作者选择执行时机时，才为 true）
• 不得包含 effort 键：command.schema.json 设置了 additionalProperties: false，且不接受该键

委派工作者Copy Anchor Link

路径：

src/apothem/agents/*.md

• name、version、updated、description 均存在
• tools——允许使用的工具的逗号分隔列表
• disallowedTools——明确列出禁止使用的工具
• maxTurns——已设置（若大于 10，则附带理由注释）
• permissionMode——不得为 "bypassPermissions"；保持该键未设置，因为与宿主无关的态势不预设权限模式
• memory——除非有意启用持久内存，否则省略；设置时须为 user、project、local 之一（不接受布尔形式）

技能（src/apothem/skills/*/SKILL.md）Copy Anchor Link

• name、version、updated、description、archetype、disable-model-invocation、allowed-tools 均存在
• 已声明 userInvocable（true/false）。源码中的写法为 userInvocable；一个技能恰好携带 userInvocable 或 user-invocable 其中之一（后者是 Claude Code 的写法）。

3. 安全性Copy Anchor Link

• 没有任何委派工作者使用 permissionMode: "bypassPermissions"——这会绕过对 Write/Bash 操作的交互式确认
• 工作者的 tools 列表保持最小化——只包含工作者确实需要的工具
• 具有 Bash 访问权限的工作者有正当理由，并设有 maxTurns 限制
• 任何制品中均无硬编码的路径、令牌或密钥
• settings.json 中的钩子设置了合理的超时时间（≤ 60 秒），且不会执行来自用户输入的任意代码

4. 交叉引用完整性Copy Anchor Link

• src/apothem/rules/ 表中列出的每条规则都按所述路径存在于磁盘上
• src/apothem/commands/ 表中列出的每条命令都存在于磁盘上
• src/apothem/agents/ 注册表中列出的每个委派工作者都存在于磁盘上
• src/apothem/skills/ 表中列出的每项技能都存在于磁盘上
• src/apothem/hooks/ 表中的每个钩子在 settings.json 中都有对应的条目
• 所有 src/apothem/rules/*.md 文件均存在，且其 Bindings 交叉引用都可解析

5. 准则覆盖Copy Anchor Link

• 每个 CM-N 准则都有执行位置（规则文件或显式内联定义）
• 没有任何规则文件与另一规则文件相矛盾（尤其是在严肃性分级方面）
• 遵守 CM-21 三方面划分——没有任何规则声称拥有另一规则的 CM-21 方面

6. 功能冒烟测试Copy Anchor Link

首先运行 Python 验证面——它快速、离线，并能捕获 结构性回归：

• pytest tests——钩子运行时的单元测试，全部通过
• python scripts/dev/validate_hooks.py——钩子结构 + 仅 Python 的卫生检查通过
• python scripts/dev/validate_ecosystem.py——完整树 + frontmatter + 受托钩子检查通过
• python scripts/dev/chaos_pass.py——每个已配置的钩子命令在降级输入下都返回有效的 JSON 信封

然后是实时场景：

• /plan-spec <sample-file> —— 完成摄取／澄清，且无命令级错误
• /plan-generate --dry-run —— 生成结构预览，且不写入文件
• 对完整的计划套件运行 /plan-status —— 返回准确的阶段计数
• 委派工作者调度：以较小范围调用 codebase-explorer 工作者，在 maxTurns 内完成并返回结构化输出

7. 文档时效性Copy Anchor Link

• CHANGELOG.md（位于生态系统根目录）反映了自上次发布以来的每项制品变更；下一个发布版本的条目在标签落地之前已填充，或每项变更都已切入某个已发布的版本条目
• site/content/docs/developer-guide.mdx 准确描述了当前的制品结构
• site/content/docs/reference/artifact-schema.mdx 与制品中实际存在的 frontmatter 字段相符
• site/content/docs/reference/settings-reference.mdx 与 settings.json 中的实际钩子配置相符
• README.md 与磁盘上的树保持一致

8. 可移植性（如果与他人共享）Copy Anchor Link

• 钩子命令中的所有路径都与环境无关或使用 ~ 展开
• 钩子命令使用 exec 形式，并避免特定于 shell 的命令字符串
• 任何制品中均无硬编码的 C:\Users\username 或 /home/username 路径
• settings.json 使用单一的钩子事件覆盖表和规范的调度模块路径

9. 版本对齐Copy Anchor Link

• CLAUDE.md 的 version 是树中任何制品里最高的（或按惯例等于最近一次提升版本的制品的版本）
• 每个制品的 version 都与所述语义化版本（MAJOR.MINOR.PATCH）相符
• 打标签前，CHANGELOG.md 恰好包含目标版本的发布条目
• 每个制品的 updated 字段处于其最后一次行为变更编辑的日期之时或之后
• 没有任何制品携带低于其最后一次改动时所处版本的 version（无回退）
• src/apothem/skills/plan-suite/SKILL.md 和 src/apothem/skills/plan-suite/master-template.md 固定在同一模板版本线上

签字确认Copy Anchor Link

部署批准人： ___________________ 日期： ___________________ 部署的生态系统版本： ___________________