msd-core/docs/zh-CN/CLI-TOOLS.md

# MSD CLI 工具参考

> `msd-tools` CLI（`msd-core/bin/msd-tools.cjs`）参考文档。斜杠命令与用户流程请参见[命令参考](COMMANDS.md)。返回[文档索引](README.md)。

---

## 概述

`msd-tools.cjs` 集中处理配置解析、模型解析、阶段查找、Git 提交、摘要验证、状态管理以及模板操作，供 MSD 命令、工作流和代理使用。


|                    |                                                                                                                                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **发布路径**   | `msd-core/bin/msd-tools.cjs`                                                                                                                                                                      |
| **实现**       | `msd-core/bin/lib/` 下的 20 个领域模块（以该目录为准）                                                                                                                                              |
| **状态**       | 编排、工作流和自动化的主要运行时命令接口。 |


**用法（CJS）：**

```bash
node msd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```

**全局标志（CJS）：**


| 标志           | 说明                                                                  |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw`        | 机器可读输出（JSON 或纯文本，无格式）                  |
| `--cwd <path>` | 覆盖工作目录（用于沙箱子代理）                         |
| `--ws <name>`  | `.planning/workstreams/<name>` 路径的工作流上下文 |


---

## 状态命令

管理 `.planning/STATE.md`——项目的活动记忆。

```bash
# 以 JSON 格式加载完整项目配置和状态
node msd-tools.cjs state load

# 以 JSON 格式输出 STATE.md frontmatter
node msd-tools.cjs state json

# 更新单个字段
node msd-tools.cjs state update <field> <value>

# 获取 STATE.md 内容或特定章节
node msd-tools.cjs state get [section]

# 批量更新多个字段
node msd-tools.cjs state patch --field1 val1 --field2 val2

# 递增计划计数器
node msd-tools.cjs state advance-plan

# 记录执行指标
node msd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]

# 重新计算进度条
node msd-tools.cjs state update-progress

# 添加决策
node msd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# 或从文件读取：
node msd-tools.cjs state add-decision --summary-file path [--rationale-file path]

# 添加/解决阻塞项
node msd-tools.cjs state add-blocker --text "..."
node msd-tools.cjs state resolve-blocker --text "..."

# 记录会话连续性
node msd-tools.cjs state record-session --stopped-at "..." [--resume-file path]

# 阶段开始——为新阶段更新 STATE.md 的状态/最后活动
node msd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT

# 代理可发现的阻塞信号（由 discuss-phase / UI 流程使用）
node msd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node msd-tools.cjs state signal-resume
```

### 状态快照

对完整 STATE.md 进行结构化解析：

```bash
node msd-tools.cjs state-snapshot
```

返回 JSON，包含：当前位置、阶段、计划、状态、决策、阻塞项、指标、最后活动。

---

## 阶段命令

管理阶段——目录、编号和路线图同步。

```bash
# 按编号查找阶段目录
node msd-tools.cjs find-phase <phase>

# 计算插入用的下一个小数阶段编号
node msd-tools.cjs phase next-decimal <phase>

# 向路线图追加新阶段并创建目录
node msd-tools.cjs phase add <description>

# 在现有阶段后插入小数阶段
node msd-tools.cjs phase insert <after> <description>

# 移除阶段，对后续阶段重新编号
node msd-tools.cjs phase remove <phase> [--force]

# 标记阶段完成，更新状态和路线图
node msd-tools.cjs phase complete <phase>

# 按波次和状态索引计划
node msd-tools.cjs phase-plan-index <phase>

# 列出阶段并过滤
node msd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```

---

## 路线图命令

解析和更新 `ROADMAP.md`。

```bash
# 从 ROADMAP.md 提取阶段章节
node msd-tools.cjs roadmap get-phase <phase>

# 带磁盘状态的完整路线图解析
node msd-tools.cjs roadmap analyze

# 从磁盘更新进度表行
node msd-tools.cjs roadmap update-plan-progress <N>
```

---

## 配置命令

读写 `.planning/config.json`。

```bash
# 以默认值初始化 config.json
node msd-tools.cjs config-ensure-section

# 设置配置值（点号表示法）
node msd-tools.cjs config-set <key> <value>

# 获取配置值
node msd-tools.cjs config-get <key>

# 设置模型配置文件
node msd-tools.cjs config-set-model-profile <profile>
```

---

## 模型解析

```bash
# 根据当前配置文件获取代理使用的模型
node msd-tools.cjs resolve-model <agent-name>
# 原始输出返回所选模型 ID/层级。
# JSON 输出还包括配置文件，以及当活跃运行时支持时的
# reasoning_effort。
```

代理名称：`msd-planner`、`msd-executor`、`msd-phase-researcher`、`msd-project-researcher`、`msd-research-synthesizer`、`msd-verifier`、`msd-plan-checker`、`msd-integration-checker`、`msd-roadmapper`、`msd-debugger`、`msd-codebase-mapper`、`msd-nyquist-auditor`

---

## 验证命令

验证计划、阶段、引用和提交。

```bash
# 验证 SUMMARY.md 文件
node msd-tools.cjs verify-summary <path> [--check-count N]

# 检查 PLAN.md 结构和任务
node msd-tools.cjs verify plan-structure <file>

# 检查所有计划是否有摘要
node msd-tools.cjs verify phase-completeness <phase>

# 检查 @-引用和路径是否可解析
node msd-tools.cjs verify references <file>

# 批量验证提交哈希
node msd-tools.cjs verify commits <hash1> [hash2] ...

# 检查 must_haves.artifacts
node msd-tools.cjs verify artifacts <plan-file>

# 检查 must_haves.key_links
node msd-tools.cjs verify key-links <plan-file>
```

---

## 校验命令

检查项目完整性。

```bash
# 检查阶段编号、磁盘/路线图同步
node msd-tools.cjs validate consistency

# 检查 .planning/ 完整性，可选修复
node msd-tools.cjs validate health [--repair]

# 探测上下文窗口利用率（用于状态行/钩子调用方）（v1.40.0）
node msd-tools.cjs validate context

# 以类型化 JSON 接口输出上下文利用率（#455）
node msd-tools.cjs validate context --json
```

`validate context` 输出包含 `utilization`、`status`（在 60% / 70% 阈值处分别为 `ok` / `warn` / `critical`）以及 `suggestion` 字符串的结构化信封。相同数据支撑 `/msd-health --context`。
传入 `--json` 可直接接收类型化中间表示（适用于脚本和测试断言）。

---

## 模板命令

模板选择与填充。

```bash
# 根据粒度选择摘要模板
node msd-tools.cjs template select <type>

# 用变量填充模板
node msd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
```

`fill` 的模板类型：`summary`、`plan`、`verification`

---

## Frontmatter 命令

对任意 Markdown 文件执行 YAML frontmatter 的增删改查。

```bash
# 以 JSON 格式提取 frontmatter
node msd-tools.cjs frontmatter get <file> [--field key]

# 更新单个字段
node msd-tools.cjs frontmatter set <file> --field key --value jsonVal

# 将 JSON 合并到 frontmatter
node msd-tools.cjs frontmatter merge <file> --data '{json}'

# 验证必填字段
node msd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
```

---

## 脚手架命令

创建预结构化文件和目录。

```bash
# 创建 CONTEXT.md 模板
node msd-tools.cjs scaffold context --phase N

# 创建 UAT.md 模板
node msd-tools.cjs scaffold uat --phase N

# 创建 VERIFICATION.md 模板
node msd-tools.cjs scaffold verification --phase N

# 创建阶段目录
node msd-tools.cjs scaffold phase-dir --phase N --name "phase name"
```

---

## Init 命令（复合上下文加载）

通过单次调用加载特定工作流所需的所有上下文。返回包含项目信息、配置、状态和工作流专属数据的 JSON。`init onboard [--fast] [--text]` 会为 `/msd-onboard` 返回 brownfield 信号、planning 文档候选、代码库映射完整性、fast 映射就绪状态、文本模式路由、部分 planning 状态和 onboarding summary 状态。

```bash
node msd-tools.cjs init execute-phase <phase>
node msd-tools.cjs init plan-phase <phase>
node msd-tools.cjs init new-project
node msd-tools.cjs init new-milestone
node msd-tools.cjs init onboard [--fast] [--text]
node msd-tools.cjs init quick <description>
node msd-tools.cjs init resume
node msd-tools.cjs init verify-work <phase>
node msd-tools.cjs init phase-op <phase>
node msd-tools.cjs init todos [area]
node msd-tools.cjs init milestone-op
node msd-tools.cjs init map-codebase
node msd-tools.cjs init progress

# 工作流范围的 init（`--ws` 标志）
node msd-tools.cjs init execute-phase <phase> --ws <name>
node msd-tools.cjs init plan-phase <phase> --ws <name>
```

**大载荷处理：** 当输出超过约 50KB 时，CLI 会将内容写入临时文件并返回 `@file:/tmp/msd-init-XXXXX.json`。工作流检查 `@file:` 前缀并从磁盘读取：

```bash
INIT=$(node msd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```

---

## 里程碑命令

```bash
# 归档里程碑
node msd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]

# 将需求标记为完成
node msd-tools.cjs requirements mark-complete <ids>
# 接受格式：REQ-01,REQ-02 或 REQ-01 REQ-02 或 [REQ-01, REQ-02]
```

---

## 代理技能

输出指定代理类型的技能块。

```bash
# 输出原始 XML 技能块（默认——适合 shell 展开）
node msd-tools.cjs agent-skills <agent-type>

# 输出类型化 JSON 接口（#455）——{ agent_type, block, skills_count }
node msd-tools.cjs agent-skills <agent-type> --json
```

`--json` 标志返回适合结构化消费和测试断言的类型化中间表示对象，而默认（无标志）保留工作流 shell 展开所依赖的原始 XML 输出。

---

## 技能清单

预计算并缓存技能发现结果，以加快命令加载速度。

```bash
# 生成技能清单（写入 .claude/skill-manifest.json）
node msd-tools.cjs skill-manifest

# 生成并指定自定义输出路径
node msd-tools.cjs skill-manifest --output <path>
```

返回所有可用 MSD 技能的 JSON 映射，包含其元数据（名称、描述、文件路径、参数提示）。由安装程序和会话启动钩子使用，以避免重复的文件系统扫描。

---

## 工具命令

```bash
# 将文本转换为 URL 安全的 slug
node msd-tools.cjs generate-slug "Some Text Here"
# → some-text-here

# 获取时间戳
node msd-tools.cjs current-timestamp [full|date|filename]

# 统计并列出待办事项
node msd-tools.cjs list-todos [area]

# 检查文件/目录是否存在
node msd-tools.cjs verify-path-exists <path>

# 聚合所有 SUMMARY.md 数据
node msd-tools.cjs history-digest

# 从 SUMMARY.md 提取结构化数据
node msd-tools.cjs summary-extract <path> [--fields field1,field2]

# 项目统计
node msd-tools.cjs stats [json|table]

# 进度渲染（人类可读）
node msd-tools.cjs progress [json|table|bar]

# 以类型化 JSON 接口输出进度（#455）
node msd-tools.cjs progress --json

# 完成待办事项
node msd-tools.cjs todo complete <filename> [--dry-run]

# UAT 审计——扫描所有阶段的未解决事项
node msd-tools.cjs audit-uat

# 跨制品审计队列——扫描 `.planning/` 中未解决的审计事项
node msd-tools.cjs audit-open [--json]

# 将 GSD-2 项目反向迁移到当前结构（支撑 `/msd-import --from-gsd2`）
node msd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]

# 带配置检查的 Git 提交
node msd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```

> `--no-verify`：跳过预提交钩子。由并行执行器代理在基于波次的执行过程中使用，以避免构建锁争用（例如 Rust 项目中的 cargo lock 冲突）。编排器在每个波次完成后运行一次钩子。顺序执行时不要使用 `--no-verify`——让钩子正常运行。
> `--files <paths>` **暂存行为**：默认情况下，`--files` 在提交前对每个命名文件运行 `git add -- <path>`。这会覆盖通过 `git add -p` 设置的任何按块暂存。传入 `--respect-staged` 可跳过 `git add` 步骤，仅提交已在索引中且在请求路径规格内的内容。如果该范围内没有已暂存的内容，命令将返回 `{ committed: false, reason: 'nothing staged' }` 而不报错。两种模式下提交都会附加 `-- <paths>` 路径规格，因此 `--files` 范围之外已暂存的文件永远不会被包含（#3061 不变量）。

# 网页搜索（需要 Brave API 密钥）
node msd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```

---

## Graphify

在 `.planning/graphs/` 中构建、查询和检查项目知识图谱。需要在 `config.json` 中设置 `graphify.enabled: true`（参见[配置参考](CONFIGURATION.md#graphify-settings)）。

```bash
# 构建或重建知识图谱
node msd-tools.cjs graphify build

# 在图谱中搜索某个词
node msd-tools.cjs graphify query <term>

# 显示图谱新鲜度和统计数据
node msd-tools.cjs graphify status

# 显示自上次构建以来的变更
node msd-tools.cjs graphify diff

# 写入当前图谱的命名快照
node msd-tools.cjs graphify snapshot [name]
```

用户入口：`/msd-graphify`（参见[命令参考](COMMANDS.md#msd-graphify)）。

---

## 模块架构

| 模块 | 文件 | 导出 |
|--------|------|---------|
| 核心 | `lib/core.cjs` | `error()`、`output()`、`parseArgs()`、共享工具、兼容性重导出 |
| 状态 | `lib/state.cjs` | 所有 `state` 子命令、`state-snapshot` |
| 阶段 | `lib/phase.cjs` | 阶段增删改查、`find-phase`、`phase-plan-index`、`phases list` |
| 规划工作区 | `lib/planning-workspace.cjs` | 规划接缝：`planningDir`、`planningPaths`、活跃工作流路由、`.planning/.lock` |
| 路线图 | `lib/roadmap.cjs` | 路线图解析、阶段提取、进度更新 |
| 配置 | `lib/config.cjs` | 配置读写、章节初始化 |
| 验证 | `lib/verify.cjs` | 所有验证和校验命令 |
| 模板 | `lib/template.cjs` | 模板选择和变量填充 |
| Frontmatter | `lib/frontmatter.cjs` | YAML frontmatter 增删改查 |
| Init | `lib/init.cjs` | 所有工作流的复合上下文加载 |
| 里程碑 | `lib/milestone.cjs` | 里程碑归档、需求标记 |
| 命令 | `lib/commands.cjs` | 杂项：slug、时间戳、待办事项、脚手架、统计、网页搜索 |
| 模型配置文件 | `lib/model-profiles.cjs` | 配置文件解析表 |
| UAT | `lib/uat.cjs` | 跨阶段 UAT/验证审计 |
| 配置文件输出 | `lib/profile-output.cjs` | 开发者配置文件格式化 |
| 配置文件流水线 | `lib/profile-pipeline.cjs` | 会话分析流水线 |
| Graphify | `lib/graphify.cjs` | 知识图谱构建/查询/状态/差异/快照（支撑 `/msd-graphify`） |
| 学习记录 | `lib/learnings.cjs` | 从阶段/SUMMARY 制品中提取学习记录（支撑 `/msd-extract-learnings`） |
| 审计 | `lib/audit.cjs` | 阶段/里程碑审计队列处理器；`audit-open` 助手 |
| MSD2 导入 | `lib/gsd2-import.cjs` | 从 GSD-2 项目反向迁移导入（支撑 `/msd-import --from-gsd2`） |
| Intel | `lib/intel.cjs` | 可查询的代码库智能索引（支撑 `/msd-map-codebase --query`） |

---

## 审阅器 CLI 路由

`review.models.<cli>` 将审阅器类型映射到代码审查工作流调用的 shell 命令。通过 [`/msd-config --integrations`](COMMANDS.md#msd-config) 或直接设置：

```bash
node msd-tools.cjs config-set review.models.codex    "codex exec --model gpt-5"
node msd-tools.cjs config-set review.models.agy      "gemini-3.1-pro-preview"
node msd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node msd-tools.cjs config-set review.models.claude   ""   # 清除——回退到会话模型
```

Slug 将针对 `[a-zA-Z0-9_-]+` 进行验证；空或包含路径的 slug 将被拒绝。完整字段参考请参见 [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing)。

## 密钥处理

通过 `/msd-settings` 配置的 API 密钥（`brave_search`、`firecrawl`、`exa_search`）以明文形式写入 `.planning/config.json`，但在所有 `config-set` / `config-get` 输出、确认表格和交互式提示中均会被遮蔽（`****<last-4>`）。遮蔽实现请参见 `msd-core/bin/lib/secrets.cjs`。`config.json` 文件本身是安全边界——请通过文件系统权限保护它，并将其排除在 git 之外（`.planning/` 默认已被 gitignore）。

---

## 相关文档

- [命令](COMMANDS.md)
- [配置](CONFIGURATION.md)
- [架构](ARCHITECTURE.md)
- [文档索引](README.md)