singularity-forge/docs/zh-CN/user-docs/auto-mode.md

自动模式

自动模式是 SF 的自主执行引擎。运行 /sf autonomous，然后离开；回来时你会看到已经构建好的软件，以及干净的 git 历史。

工作原理

自动模式本质上是一个由磁盘文件驱动的状态机。它会读取 .sf/STATE.md，确定下一个工作单元，创建一个新的 agent 会话，把所有相关上下文预先内联到一个聚焦 prompt 中，再让 LLM 执行。LLM 完成后，自动模式会再次读取磁盘状态，并派发下一个工作单元。

执行循环

每个 slice 都会自动经历以下阶段：

Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice
                                                                                      ↓ (all slices done)
                                                                              Validate Milestone → Complete Milestone

• Plan：巡检代码库、研究相关文档，把 slice 分解成带 must-have 的 task
• Execute：在新的上下文窗口中逐个执行 task
• Complete：写 summary、UAT 脚本、标记 roadmap、提交代码
• Reassess：检查 roadmap 是否仍然合理
• Validate Milestone：在所有 slices 完成后做一致性校验，把 roadmap 的成功标准与实际结果对照，避免在封板前漏掉关键缺口

关键特性

每个单元都用全新会话

每个 task、research 阶段和 planning 步骤都会得到一个干净的上下文窗口。没有历史垃圾堆积，也不会因为上下文膨胀导致质量下降。派发 prompt 中已经包含 task plan、历史 summary、依赖上下文、决策记录等必要信息，因此 LLM 一开始就能对齐，而不必先花工具调用去读文件。

预加载上下文

派发 prompt 会精心组装以下内容：

内联产物	用途
Task plan	告诉 agent 要构建什么
Slice plan	说明当前 task 在整体中的位置
历史 task summaries	告诉 agent 已经完成了什么
依赖 summary	提供跨 slice 上下文
Roadmap 摘要	说明整体方向
Decisions register	提供架构上下文

具体内联多少内容由你的 token profile 控制。budget 模式只内联最少上下文，quality 模式则把所有内容都内联进去。

Git 隔离

SF 支持三种 milestone 隔离模式（通过偏好设置中的 git.isolation 配置）：

• worktree（默认）：每个 milestone 都运行在 .sf/worktrees/<MID>/ 下自己的 git worktree 中，分支名为 milestone/<MID>。所有 slice 工作都顺序提交，不需要切分支，也不会在 milestone 内部产生合并冲突。milestone 完成后，再整体 squash merge 回主分支，形成一个干净提交。
• branch：工作发生在项目根目录下的 milestone/<MID> 分支上。适合子模块较多、worktree 表现不佳的仓库。
• none：直接在当前分支工作。没有 worktree，也没有 milestone 分支。适合文件隔离会破坏开发工具的热重载场景。

详见 Git 策略。

并行执行

当项目里存在彼此独立的 milestones 时，可以同时运行它们。每个 milestone 都拥有自己的 worker 进程和 worktree。配置与用法见 并行编排。

崩溃恢复

自动模式会用锁文件跟踪当前工作单元。如果会话中途退出，下一次执行 /sf autonomous 时，会读取残留的会话文件，从所有已经落盘的工具调用中综合生成一份恢复简报，然后带着完整上下文继续执行。

Headless 自动重启（v2.26）： 当运行 sf headless autonomous 时，崩溃会触发带指数退避的自动重启（5s → 10s → 30s 上限，默认最多 3 次）。通过 --max-restarts N 配置。SIGINT/SIGTERM 不会触发重启。结合崩溃恢复机制，这让真正的“跑一夜直到完成”成为可能。

Provider 错误恢复

SF 会对 provider 错误分类，并在安全时自动恢复：

错误类型	示例	动作
限流	429、too many requests	按 retry-after 头等待，或默认 60 秒后自动恢复
服务端错误	500、502、503、overloaded、api_error	30 秒后自动恢复
永久错误	unauthorized、invalid key、billing	无限期暂停，等待人工恢复

对临时性错误通常不需要人工介入，系统会短暂暂停后自动继续。

增量记忆（v2.26）

SF 会维护一个 KNOWLEDGE.md 文件，作为项目特有规则、模式和经验的追加式记录。agent 在每个工作单元开始时都会读取它；当发现反复出现的问题、非显而易见的模式或未来会话需要遵循的规则时，也会把内容追加进去。这样一来，自动模式就有了跨会话、跨上下文窗口的持久记忆。

上下文压力监视器（v2.26）

当上下文使用达到 70% 时，SF 会向 agent 发送收尾信号，提醒它优先完成可持久化的输出（例如提交、写 summary），避免在 task 中途因为上下文打满而什么都没来得及落盘。

有意义的提交信息（v2.26）

提交信息不是通用的 “complete task”，而是从 task summary 生成的。每条提交消息都反映了真正完成了什么，因此 git log 看起来更像一份高质量的变更日志。

卡死检测（v2.39）

SF 使用滑动窗口分析来检测卡死循环。它不只是简单地统计“同一单元是否重复派发两次”，而是会分析近期派发历史中的重复模式，因此既能发现单点重复，也能发现 A→B→A→B 这样的循环。一旦检测到，SF 会先带着更深的诊断 prompt 重试一次；如果仍然失败，自动模式就会停止，并指出它原本期待的具体文件，便于你介入。

这种滑动窗口方法能降低合法重试场景（例如可自动修复的 verification 失败）的误报，同时更快抓到真正的卡死循环。

事后取证（v2.40）

/sf forensics 是一个面向自动模式失败分析的全访问 SF 调试器，提供：

• 异常检测：对卡死循环、成本尖峰、超时、产物缺失和崩溃做结构化识别，并标注严重级别
• 单元追踪：最近 10 次单元执行，包含错误细节和执行时长
• 指标分析：成本、token 数量和执行时间拆分
• Doctor 集成：把 /sf doctor 中的结构性健康问题一起纳入
• LLM 引导调查：启动一个拥有完整工具访问权限的 agent 会话来调查根因

/sf forensics [optional problem description]

更多诊断方式见 故障排查。

超时监管

三层超时机制可以防止会话失控：

超时类型	默认值	行为
Soft	20 分钟	警告 LLM 应该开始收尾
Idle	10 分钟	检测停滞并介入
Hard	30 分钟	暂停自动模式

恢复引导会提醒 LLM 在真正超时前尽量完成可持久化输出。配置方式如下：

auto_supervisor:
  soft_timeout_minutes: 20
  idle_timeout_minutes: 10
  hard_timeout_minutes: 30

成本跟踪

每个工作单元的 token 使用量和成本都会被记录，并按阶段、slice 和模型拆分。仪表板会显示运行总量和预测值。预算上限可以在超支前主动暂停自动模式。

详见 成本管理。

自适应重规划

每完成一个 slice，roadmap 都会重新评估。如果最新工作暴露出会改变计划的新信息，后续 slices 就会在继续前被重新排序、添加或删除。balanced 和 budget token profile 可以跳过这一阶段。

验证强制执行（v2.26）

你可以配置 shell 命令，让它们在每个 task 执行后自动运行：

verification_commands:
  - npm run lint
  - npm run test
verification_auto_fix: true    # 默认开启自动重试修复
verification_max_retries: 2    # 最大重试次数（默认 2）

一旦失败，agent 会看到 verification 输出并尝试自动修复后重试，再决定是否继续。这意味着代码质量门禁是靠机制强制执行，而不是靠 LLM“自觉遵守”。

Slice 讨论门（v2.26）

如果你希望每个 slice 开始前都先经过人工确认：

require_slice_discussion: true

自动模式会在每个 slice 开始前暂停，并把 slice 上下文展示出来供你讨论。确认后才继续执行。适用于高风险项目，尤其是你希望 agent 开始构建前先复核计划的时候。

HTML 报告（v2.26）

每当 milestone 完成后，SF 都会在 .sf/reports/ 中自动生成一个自包含的 HTML 报告。报告包括项目摘要、进度树、slice 依赖图（SVG DAG）、成本 / Token 柱状图、执行时间线、变更日志和知识库。没有外部依赖，所有 CSS 和 JS 都会内联。

auto_report: true    # 默认开启

你也可以随时手动执行 /sf export --html 生成报告，或通过 /sf export --html --all（v2.28）为所有 milestones 一次性生成报告。

故障恢复强化（v2.28）

v2.28 通过多项机制强化了自动模式的可靠性：原子文件写入可避免崩溃时损坏文件；OAuth 拉取超时（30 秒）避免无限挂起；RPC 子进程退出能被检测并报告；blob 垃圾回收可防止磁盘无限增长。结合已有的崩溃恢复和 headless 自动重启，自动模式可以真正支持“扔在那里跑一晚上”的场景。

流水线架构（v2.40）

自动循环采用的是线性阶段流水线，而非递归派发。每轮迭代都经过明确的阶段：

1. Pre-Dispatch：校验状态、检查守卫、解析模型偏好
2. Dispatch：使用聚焦 prompt 执行当前单元
3. Post-Unit：关闭该单元、更新缓存、执行清理
4. Verification：可选验证门（lint、test 等）
5. Stuck Detection：滑动窗口模式分析

这种线性流程更容易调试，占用更少内存（没有递归调用栈），也使错误恢复更清晰，因为每个阶段都有明确的入口和出口条件。

实时健康可见性（v2.40）

/sf doctor 发现的问题现在会实时出现在三个地方：

• Dashboard widget：健康指示器，显示问题数量和严重级别
• Workflow visualizer：状态面板中展示问题
• HTML reports：生成报告时带出完整健康信息

问题按严重程度分为：error（阻塞自动模式）、warning（不阻塞）和 info（提示性质）。自动模式会在派发时检查健康状态，并可在关键问题出现时主动暂停。

Prompt 中的技能激活（v2.39）

配置好的技能会被自动解析并注入派发 prompt。agent 会收到一个 “Available Skills” 区块，列出当前上下文匹配的技能，来源包括：

• always_use_skills：始终注入
• prefer_skills：以偏好形式注入
• skill_rules：根据 when 条件做条件激活

技能路由偏好详见 配置。

控制自动模式

启动

/sf autonomous

暂停

按 Escape。对话会被保留，你可以继续和 agent 交互、查看状态，或者稍后恢复。

恢复

/sf autonomous

自动模式会读取磁盘状态，并从中断处继续。

停止

/sf stop

优雅地停止自动模式。这个命令也可以从另一个终端执行。

引导

/sf steer

在不中断流水线的情况下，强制修改计划文档。修改会在下一个阶段边界生效。

捕获

/sf capture "add rate limiting to API endpoints"

随手记录想法，不打断当前执行。Captures 会在 tasks 之间自动 triage。详见 捕获与分流。

可视化

/sf visualize

打开工作流可视化器，交互式查看进度、依赖、指标和时间线。详见 工作流可视化器。

仪表板

Ctrl+Alt+G 或 /sf status 会显示实时进度：

• 当前 milestone、slice 和 task
• 自动模式的已运行时间和当前阶段
• 每个单元的成本与 token 拆分
• 成本预测
• 已完成和进行中的单元
• 待 triage 的 capture 数量（如果存在）
• 并行 worker 状态（运行并行 milestones 时显示，也包含 80% 预算预警）

跳过阶段

Token profile 可以通过跳过某些阶段来降低成本：

阶段	budget	balanced	quality
Milestone Research	跳过	执行	执行
Slice Research	跳过	跳过	执行
Reassess Roadmap	跳过	执行	执行

更多细节见 Token 优化。

动态模型路由

启用后，自动模式会为简单工作单元（例如 slice completion、UAT）自动选择更便宜的模型，并把昂贵模型保留给复杂工作（例如重规划或架构 task）。详见 动态模型路由。

响应式 Task 执行（v2.38）

当在偏好中设置 reactive_execution: true 时，SF 会从 task plan 中的 IO 注解推导依赖图。互不冲突的 tasks（没有共享文件读写）会通过 subagents 并行派发，而存在依赖的 tasks 则等待前驱完成。

reactive_execution: true    # 默认关闭

依赖图推导是纯函数且确定性的：它会解析 ready-set、检测冲突和死锁，并做相应防护。并行批次中的 verification 结果会被沿用，因此某些 tasks 如果已经通过验证，后续同一 slice 中其他 tasks 完成时就不需要再次验证。

这套实现位于 reactive-graph.ts（负责图推导、ready-set 解析、冲突 / 死锁检测），并集成到了 auto-dispatch.ts 和 auto-prompts.ts。