Skip to main content

moai spec 文档管理

更新 2026-07-15 2 分钟阅读 在 GitHub 上编辑 ↗

moai spec 管理 .moai/specs/ 目录中的 SPEC 文档。它提供状态更新、漂移检测、验收标准查看、EARS/GEARS lint、原子化关闭、era 审计、归档的子命令。

子命令

命令说明
moai spec status更新或列出 SPEC 状态
moai spec drift检测 frontmatter status 与 git log 之间的漂移
moai spec view <SPEC-ID>以树状结构查看验收标准
moai spec lint [spec.md...]lint EARS 合规性与结构有效性
moai spec close <SPEC-ID>原子化 4-phase 关闭(status: completed + progress.md backfill)
moai spec auditSPEC era 分类与 modern-era 状态漂移审计
moai spec archive将已关闭的 SPEC 归档至 .moai/specs/ 之外

moai spec status

bash 
moai spec status <SPEC-ID> <new-status>   # 更新状态
moai spec status --list                   # 列出全部 SPEC
moai spec status --sync-git               # 从 git log 同步状态
标志说明
--dry-run不写入,预览变更
--list列出全部 SPEC 及状态
--sync-git从 main 的 git log 同步 SPEC 状态
--yes--sync-git 非交互式自动确认(CI/管道必需)

moai spec drift

bash 
moai spec drift
标志说明
--jsonJSON 格式输出
--exit-code-on-drift检测到漂移时返回退出码 1
--count仅输出漂移数量
--no-cache绕过 HEAD-SHA 结果缓存后重新计算

moai spec lint

bash 
moai spec lint [spec.md...]
标志说明
--jsonJSON 格式输出
--sarifSARIF 2.1.0 格式输出
--strict将警告视为错误
--format <fmt>输出格式(table)

moai spec close

bash 
moai spec close SPEC-ID

以单次提交将 SPEC 原子化转换为 status: completed。

标志说明
--backfill-only仅执行 progress.md backfill
--dry-run不提交,预览
--force不确认强制关闭
--jsonJSON 格式输出

moai spec audit

bash 
moai spec audit

扫描 .moai/specs/SPEC-*/,用 era 启发式对每个 SPEC 分类并检测 modern-era 状态漂移。

标志说明
--jsonJSON 格式输出
--filter-era <era>按 era 过滤
--filter-spec <id>按 SPEC ID 过滤
--include-grandfathered包含 grandfather era SPEC
--strict严格模式

moai spec archive

bash 
moai spec archive --dry-run   # 确认目标(不移动)
moai spec archive --yes       # 应用计划

归档超过 grace 窗口(默认 90 天)的 terminal SPEC。

标志说明
--dry-run不移动,报告目标集合
--yes确认移动(应用时必需)
--grace-days <n>grace 窗口天数(0 = 默认值 90)
--json以 JSON 输出计划

相关文档