# 命令参考

## 会话命令

| 命令 | 说明 |
|------|------|
| `/sf` | Step mode：一次执行一个工作单元，并在每步之间暂停 |
| `/sf next` | 显式 Step mode（与 `/sf` 相同） |
| `/sf autonomous` | 自动模式：research、plan、execute、commit，然后重复 |
| `/sf quick` | 在不经过完整 planning 开销的情况下，执行一个带 SF 保证的 quick task（原子提交、状态跟踪） |
| `/sf stop` | 优雅地停止自动模式 |
| `/sf pause` | 暂停自动模式（保留状态，可用 `/sf autonomous` 恢复） |
| `/sf steer` | 在执行过程中强制修改 plan 文档 |
| `/sf discuss` | 讨论架构和决策（可与自动模式并行使用） |
| `/sf status` | 进度仪表板 |
| `/sf widget` | 循环切换仪表板组件：full / small / min / off |
| `/sf queue` | 给未来 milestones 排队和重排（自动模式中也安全） |
| `/sf capture` | 随手记录一个想法，不打断当前流程（自动模式中可用） |
| `/sf triage` | 手动触发待处理 captures 的 triage |
| `/sf dispatch` | 直接派发一个指定阶段（research、plan、execute、complete、reassess、uat、replan） |
| `/sf history` | 查看执行历史（支持 `--cost`、`--phase`、`--model` 过滤） |
| `/sf forensics` | 全访问 SF 调试器：用于分析自动模式失败，支持结构化异常检测、单元追踪和 LLM 引导的根因分析 |
| `/sf cleanup` | 清理 SF 状态文件和过期 worktrees |
| `/sf visualize` | 打开工作流可视化器（进度、依赖、指标、时间线） |
| `/sf export --html` | 为当前或已完成的 milestone 生成自包含 HTML 报告 |
| `/sf export --html --all` | 一次性为所有 milestones 生成回顾报告 |
| `/sf update` | 在会话内更新到最新版本 |
| `/sf knowledge` | 添加持久化项目知识（规则、模式或经验） |
| `/sf fast` | 为支持的模型切换 service tier（优先级 API 路由） |
| `/sf rate` | 评价上一个单元所用模型层级（over / ok / under），帮助改进自适应路由 |
| `/sf changelog` | 查看分类后的发行说明 |
| `/sf logs` | 浏览活动日志、调试日志和指标 |
| `/sf remote` | 控制远程自动模式 |
| `/sf help` | 查看所有 SF 子命令的分类参考及说明 |

## 配置与诊断

| 命令 | 说明 |
|------|------|
| `/sf prefs` | 模型选择、超时和预算上限 |
| `/sf mode` | 切换工作流模式（solo / team），同时应用与 milestone ID、git 提交行为和文档相关的协调默认值 |
| `/sf config` | 重新运行 provider 配置向导（LLM provider + 工具 key） |
| `/sf keys` | API key 管理器：列出、添加、移除、测试、轮换、doctor |
| `/sf doctor` | 运行时健康检查与自动修复；问题会实时显示在 widget、visualizer 和 HTML reports 中（v2.40） |
| `/sf inspect` | 查看 SQLite DB 诊断信息 |
| `/sf init` | 项目初始化向导：检测、配置并 bootstrap `.sf/` |
| `/sf setup` | 查看全局 setup 状态和配置 |
| `/sf skill-health` | 技能生命周期仪表板：使用统计、成功率、token 趋势、过期告警 |
| `/sf skill-health <name>` | 查看某个 skill 的详细信息 |
| `/sf skill-health --declining` | 只显示被标记为表现下降的 skills |
| `/sf skill-health --stale N` | 显示 N 天以上未使用的 skills |
| `/sf hooks` | 查看已配置的 post-unit 和 pre-dispatch hooks |
| `/sf run-hook` | 手动触发一个指定 hook |
| `/sf migrate` | 将 v1 的 `.planning` 目录迁移到 `.sf` 格式 |

## Milestone 管理

| 命令 | 说明 |
|------|------|
| `/sf new-milestone` | 创建一个新的 milestone |
| `/sf skip` | 阻止某个工作单元被自动模式派发 |
| `/sf undo` | 回退上一个已完成单元 |
| `/sf undo-task` | 重置某个特定 task 的完成状态（DB + markdown） |
| `/sf reset-slice` | 重置某个 slice 及其所有 tasks（DB + markdown） |
| `/sf park` | Park 一个 milestone，不删除，只跳过 |
| `/sf unpark` | 重新激活一个已 park 的 milestone |
| Discard milestone | 在 `/sf` 向导的 “Milestone actions” → “Discard” 中可用 |

## 并行编排

| 命令 | 说明 |
|------|------|
| `/sf parallel start` | 分析可并行性、确认后启动 workers |
| `/sf parallel status` | 显示所有 workers 的状态、进度和成本 |
| `/sf parallel stop [MID]` | 停止所有 workers，或停止某个指定 milestone 的 worker |
| `/sf parallel pause [MID]` | 暂停所有 workers，或暂停某个指定 worker |
| `/sf parallel resume [MID]` | 恢复已暂停的 workers |
| `/sf parallel merge [MID]` | 把已完成的 milestones 合并回 main |

完整文档见 [并行编排](./parallel-orchestration.md)。

## Workflow Templates（v2.42）

| 命令 | 说明 |
|------|------|
| `/sf start` | 启动一个 workflow template（bugfix、spike、feature、hotfix、refactor、security-audit、dep-upgrade、full-project） |
| `/sf start resume` | 恢复一个进行中的 workflow |
| `/sf templates` | 列出可用 workflow templates |
| `/sf templates info <name>` | 查看某个 template 的详细信息 |

## 自定义 Workflows（v2.42）

| 命令 | 说明 |
|------|------|
| `/sf workflow new` | 创建一个新的 workflow definition（通过 skill） |
| `/sf workflow run <name>` | 创建一个 run 并启动自动模式 |
| `/sf workflow list` | 列出 workflow runs |
| `/sf workflow validate <name>` | 校验一个 workflow YAML definition |
| `/sf workflow pause` | 暂停自定义 workflow 的自动模式 |
| `/sf workflow resume` | 恢复已暂停的自定义 workflow 自动模式 |

## 扩展

| 命令 | 说明 |
|------|------|
| `/sf extensions list` | 列出所有扩展及其状态 |
| `/sf extensions enable <id>` | 启用一个被禁用的扩展 |
| `/sf extensions disable <id>` | 禁用一个扩展 |
| `/sf extensions info <id>` | 查看扩展详情 |

## cmux 集成

| 命令 | 说明 |
|------|------|
| `/sf cmux status` | 显示 cmux 检测结果、prefs 和能力 |
| `/sf cmux on` | 启用 cmux 集成 |
| `/sf cmux off` | 禁用 cmux 集成 |
| `/sf cmux notifications on/off` | 切换 cmux 桌面通知 |
| `/sf cmux sidebar on/off` | 切换 cmux 侧边栏元数据 |
| `/sf cmux splits on/off` | 切换 cmux subagent 可视化分屏 |

## GitHub Sync（v2.39）

| 命令 | 说明 |
|------|------|
| `/github-sync bootstrap` | 初始配置：根据当前 `.sf/` 状态创建 GitHub Milestones、Issues 和 draft PRs |
| `/github-sync status` | 显示同步映射数量（milestones、slices、tasks） |

在偏好设置里启用 `github.enabled: true`。要求已安装并认证 `gh` CLI。同步映射会保存在 `.sf/.github-sync.json`。

## Git 命令

| 命令 | 说明 |
|------|------|
| `/worktree`（`/wt`） | Git worktree 生命周期管理：create、switch、merge、remove |

## 会话管理

| 命令 | 说明 |
|------|------|
| `/clear` | 启动一个新会话（`/new` 的别名） |
| `/exit` | 优雅退出，会在退出前保存会话状态 |
| `/kill` | 立即终止 SF 进程 |
| `/model` | 切换当前 active model |
| `/login` | 登录一个 LLM provider |
| `/thinking` | 在会话中切换 thinking level |
| `/voice` | 切换实时语音转文字（macOS、Linux） |

## 键盘快捷键

| 快捷键 | 动作 |
|--------|------|
| `Ctrl+Alt+G` | 切换 dashboard overlay |
| `Ctrl+Alt+V` | 切换语音转录 |
| `Ctrl+Alt+B` | 显示后台 shell 进程 |
| `Ctrl+V` / `Alt+V` | 从剪贴板粘贴图片（截图 → vision 输入） |
| `Escape` | 暂停自动模式（保留对话） |

> **注意：** 在不支持 Kitty keyboard protocol 的终端中（如 macOS Terminal.app、JetBrains IDEs），界面会显示 slash-command 形式的回退命令，而不是 `Ctrl+Alt` 快捷键。
>
> **提示：** 如果 `Ctrl+V` 被终端拦截（例如 Warp），可改用 `Alt+V` 粘贴剪贴板图片。

## CLI 参数

| 参数 | 说明 |
|------|------|
| `sf` | 启动新的交互式会话 |
| `sf --continue`（`-c`） | 恢复当前目录最近一次会话 |
| `sf --model <id>` | 为当前会话覆盖默认模型 |
| `sf --print "msg"`（`-p`） | 单次 prompt 模式（无 TUI） |
| `sf --mode <text\|json\|rpc\|mcp>` | 非交互使用时的输出模式 |
| `sf --list-models [search]` | 列出可用模型并退出 |
| `sf --web [path]` | 启动基于浏览器的 Web 界面（可选项目路径） |
| `sf --worktree`（`-w`）[name] | 在 git worktree 中启动会话（未指定时自动生成名称） |
| `sf --no-session` | 禁用会话持久化 |
| `sf --extension <path>` | 加载一个额外扩展（可重复） |
| `sf --append-system-prompt <text>` | 向 system prompt 末尾追加文本 |
| `sf --tools <list>` | 启用的工具列表，逗号分隔 |
| `sf --version`（`-v`） | 输出版本并退出 |
| `sf --help`（`-h`） | 输出帮助并退出 |
| `sf sessions` | 交互式会话选择器：列出当前目录所有保存的会话并选择一个恢复 |
| `sf --debug` | 启用结构化 JSONL 诊断日志，用于排查 dispatch 和 state 问题 |
| `sf config` | 配置搜索和文档工具所需的全局 API keys（保存到 `~/.sf/agent/auth.json`，对所有项目生效）。见 [Global API Keys](./configuration.md#global-api-keys-sf-config)。 |
| `sf update` | 更新到最新版本 |
| `sf headless new-milestone` | 根据上下文文件创建新的 milestone（headless，无需 TUI） |

## Headless 模式

`sf headless` 可在无 TUI 的情况下运行 `/sf` 命令，适合 CI、cron job 和脚本自动化。它会在 RPC 模式下启动一个子进程，自动回应交互式提示、检测完成状态，并用有意义的退出码退出。

```bash
# 运行自动模式（默认）
sf headless

# 运行一个单元
sf headless next

# 即时 JSON 快照，无需 LLM，约 50ms
sf headless query

# 用于 CI 的超时参数
sf headless --timeout 600000 auto

# 强制指定一个 phase
sf headless dispatch plan

# 根据上下文文件创建新 milestone，并启动自动模式
sf headless new-milestone --context brief.md --auto

# 用内联文本创建 milestone
sf headless new-milestone --context-text "Build a REST API with auth"

# 从 stdin 管道输入上下文
echo "Build a CLI tool" | sf headless new-milestone --context -
```

| 参数 | 说明 |
|------|------|
| `--timeout N` | 总超时（毫秒），默认 `300000` / 5 分钟 |
| `--max-restarts N` | 崩溃时自动重启并指数退避（默认 3）。设为 0 可关闭 |
| `--json` | 以 JSONL 形式把所有事件流式输出到 stdout |
| `--model ID` | 覆盖 headless 会话使用的模型 |
| `--context <file>` | 给 `new-milestone` 提供上下文文件（用 `-` 表示 stdin） |
| `--context-text <text>` | 给 `new-milestone` 提供内联上下文文本 |
| `--auto` | 在创建 milestone 后直接接续自动模式 |

**退出码：** `0` 表示完成，`1` 表示错误或超时，`2` 表示被阻塞。

任何 `/sf` 子命令都可以作为位置参数使用，例如：`sf headless status`、`sf headless doctor`、`sf headless dispatch execute` 等。

### `sf headless query`

它会返回单个 JSON 对象，包含完整项目快照，无需 LLM 会话，也无需 RPC 子进程，响应几乎即时（约 50ms）。这是 orchestration 工具和脚本检查 SF 状态的推荐方式。

```bash
sf headless query | jq '.state.phase'
# "executing"

sf headless query | jq '.next'
# {"action":"dispatch","unitType":"execute-task","unitId":"M001/S01/T03"}

sf headless query | jq '.cost.total'
# 4.25
```

**输出结构：**

```json
{
  "state": {
    "phase": "executing",
    "activeMilestone": { "id": "M001", "title": "..." },
    "activeSlice": { "id": "S01", "title": "..." },
    "activeTask": { "id": "T01", "title": "..." },
    "registry": [{ "id": "M001", "status": "active" }, ...],
    "progress": { "milestones": { "done": 0, "total": 2 }, "slices": { "done": 1, "total": 3 } },
    "blockers": []
  },
  "next": {
    "action": "dispatch",
    "unitType": "execute-task",
    "unitId": "M001/S01/T01"
  },
  "cost": {
    "workers": [{ "milestoneId": "M001", "cost": 1.50, "state": "running", ... }],
    "total": 1.50
  }
}
```

## MCP 集成

`/sf mcp` 只显示外部 MCP 工具 server 的状态。SF 不会把自己的 workflow 暴露成 MCP server；请直接运行 `sf` 或 `/sf autonomous`。

## 会话内更新

`/sf update` 会检查 npm 上是否有更新版本，并在不离开当前会话的情况下完成安装。

```bash
/sf update
# Current version: v2.36.0
# Checking npm registry...
# Updated to v2.37.0. Restart SF to use the new version.
```

如果已经是最新版本，它会给出提示且不做任何操作。

## 导出

`/sf export` 用于导出 milestone 工作报告。

```bash
# 为当前 active milestone 生成 HTML 报告
/sf export --html

# 一次性为所有 milestones 生成回顾报告
/sf export --html --all
```

报告会保存到 `.sf/reports/`，并生成一个可浏览的 `index.html`，链接到所有已生成的快照。