singularity-forge/docs/zh-CN/user-docs/commands.md

命令参考

会话命令

命令	说明
/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

完整文档见 并行编排。

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。
sf update	更新到最新版本
sf headless new-milestone	根据上下文文件创建新的 milestone（headless，无需 TUI）

Headless 模式

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

# 运行自动模式（默认）
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 状态的推荐方式。

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

输出结构：

{
  "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 上是否有更新版本，并在不离开当前会话的情况下完成安装。

/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 工作报告。

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

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

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