30 KiB
配置
SF 偏好设置保存在 ~/.sf/PREFERENCES.md（全局）或 .sf/PREFERENCES.md（项目级）中。可以通过 /sf prefs 进行交互式管理。
/sf prefs 命令
| 命令 | 说明 |
|---|---|
/sf prefs |
打开全局偏好设置向导（默认） |
/sf prefs global |
全局偏好设置交互向导（~/.sf/PREFERENCES.md） |
/sf prefs project |
项目偏好设置交互向导（.sf/PREFERENCES.md） |
/sf prefs status |
显示当前偏好文件、合并后的值以及 skill 解析状态 |
/sf prefs wizard |
/sf prefs global 的别名 |
/sf prefs setup |
/sf prefs wizard 的别名；若偏好文件不存在会自动创建 |
/sf prefs import-claude |
将 Claude marketplace plugins 和 skills 以命名空间化的 SF 组件形式导入 |
/sf prefs import-claude global |
导入到全局作用域 |
/sf prefs import-claude project |
导入到项目作用域 |
偏好文件格式
偏好设置使用 markdown 文件中的 YAML frontmatter：
---
version: 1
models:
research: claude-sonnet-4-6
planning: claude-opus-4-6
execution: claude-sonnet-4-6
completion: claude-sonnet-4-6
skill_discovery: suggest
auto_supervisor:
soft_timeout_minutes: 20
idle_timeout_minutes: 10
hard_timeout_minutes: 30
budget_ceiling: 50.00
token_profile: balanced
---
全局与项目偏好
| 作用域 | 路径 | 适用范围 |
|---|---|---|
| 全局 | ~/.sf/PREFERENCES.md |
所有项目 |
| 项目 | .sf/PREFERENCES.md |
仅当前项目 |
合并规则：
- 标量字段（
skill_discovery、budget_ceiling）：如果项目级定义了，则项目级优先 - 数组字段（
always_use_skills等）：拼接，顺序为全局在前、项目在后 - 对象字段（
models、git、auto_supervisor）：浅合并，项目级按 key 覆盖
全局 API Keys（/sf config）
工具 API keys 会全局保存在 ~/.sf/agent/auth.json 中，并自动应用到所有项目。只需用 /sf config 配置一次，无需在每个项目里维护 .env。
/sf config
这会打开一个交互式向导，显示哪些 key 已配置、哪些仍缺失。你可以选择一个工具并输入相应的 key。
支持的 keys
| 工具 | 环境变量 | 用途 | 获取地址 |
|---|---|---|---|
| Tavily Search | TAVILY_API_KEY |
为非 Anthropic models 提供 Web 搜索 | tavily.com/app/api-keys |
| Brave Search | BRAVE_API_KEY |
为非 Anthropic models 提供 Web 搜索 | brave.com/search/api |
| Context7 Docs | CONTEXT7_API_KEY |
库文档检索 | context7.com/dashboard |
工作方式
/sf config会把 keys 保存到~/.sf/agent/auth.json- 每次会话启动时，
loadToolApiKeys()都会读取该文件并设置环境变量 - 这些 keys 对所有项目生效，无需单独配置
- 环境变量（例如
export BRAVE_API_KEY=...）优先级高于保存下来的 keys - Anthropic models 不需要 Brave/Tavily，因为它们自带 Web 搜索
MCP Servers
SF 可以连接配置在项目文件中的外部 MCP servers。这适合接入本地工具、内部 API、自托管服务，或者那些未作为 SF 原生扩展内置的集成。
配置文件位置
SF 会从以下项目本地路径读取 MCP client 配置：
.mcp.json.sf/mcp.json
如果两个文件都存在，会按 server 名称做合并，先找到的定义优先。通常建议：
- 把你愿意提交到仓库的共享 MCP 配置放在
.mcp.json - 把仅本机使用、不希望共享的 MCP 配置放在
.sf/mcp.json
支持的 transport
| Transport | 配置形状 | 适用场景 |
|---|---|---|
stdio |
command + 可选 args、env、cwd |
启动本地 MCP server 进程 |
http |
url |
连接到已经运行中的 MCP server |
示例：stdio server
{
"mcpServers": {
"my-server": {
"type": "stdio",
"command": "/absolute/path/to/python3",
"args": ["/absolute/path/to/server.py"],
"env": {
"API_URL": "http://localhost:8000"
}
}
}
}
示例：HTTP server
{
"mcpServers": {
"my-http-server": {
"url": "http://localhost:8080/mcp"
}
}
}
验证一个 server
添加配置后，可以在 SF 会话中这样验证：
mcp_servers
mcp_discover(server="my-server")
mcp_call(server="my-server", tool="<tool_name>", args={...})
推荐验证顺序：
mcp_servers：确认 SF 能看到配置文件并正确解析 server 条目mcp_discover：确认 server 进程能启动，并能响应tools/listmcp_call：确认至少有一个真实 tool 可以成功调用
说明
- 尽量为本地可执行文件和脚本使用绝对路径
- 对于
stdioservers，优先在 MCP 配置里显式设置需要的环境变量，而不是依赖交互式 shell profile - SF 会自动加载保存在
~/.sf/agent/auth.json中的 model / tool keys，因此 MCP 配置可以安全地通过${ENV_VAR}占位符引用这些值，而不必提交原始凭据 - 如果某个 server 是团队共享且适合提交到仓库，通常更适合放在
.mcp.json - 如果某个 server 依赖本机路径、个人服务或本地 secrets，更适合放在
.sf/mcp.json
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
SF_HOME |
~/.sf |
全局 SF 目录。除非单独覆盖，否则其它路径都从这里派生。影响偏好、skills、sessions 以及项目状态。（v2.39） |
SF_PROJECT_ID |
（自动哈希） | 覆盖自动生成的项目身份哈希。这样项目状态会写入 $SF_HOME/projects/<SF_PROJECT_ID>/，而不是计算出的哈希目录。适用于 CI/CD 或多个克隆共享状态。（v2.39） |
SF_STATE_DIR |
$SF_HOME |
项目状态根目录。控制 projects/<repo-hash>/ 的创建位置。对项目状态的优先级高于 SF_HOME。 |
SF_CODING_AGENT_DIR |
$SF_HOME/agent |
agent 目录，包含托管资源、扩展和 auth。对 agent 相关路径的优先级高于 SF_HOME。 |
SF_ALLOWED_COMMAND_PREFIXES |
（内置列表） | 允许用于 !command 值解析的命令前缀，逗号分隔。会覆盖 settings.json 中的 allowedCommandPrefixes。见 自定义模型：命令允许列表。 |
SF_FETCH_ALLOWED_URLS |
（无） | 对 fetch_page URL block 免检的 hostnames，逗号分隔。会覆盖 settings.json 中的 fetchAllowedUrls。见 URL Blocking。 |
全部设置
models
按阶段选择 model。每个 key 都可以是一个 model 字符串，或者是带 fallbacks 的对象。
models:
research: claude-sonnet-4-6
planning:
model: claude-opus-4-6
fallbacks:
- openrouter/z-ai/glm-5
execution: claude-sonnet-4-6
execution_simple: claude-haiku-4-5-20250414
completion: claude-sonnet-4-6
subagent: claude-sonnet-4-6
阶段键： research、planning、execution、execution_simple、completion、subagent
execution_simple：用于被 complexity router 判断为 “simple” 的 tasksubagent：委派给 subagent 的 task 所使用的 model（scout、researcher、worker）- 指定 provider：使用
provider/model格式（例如bedrock/claude-sonnet-4-6），或者在对象格式里额外写provider字段 - 省略某个 key 时，会使用当前 active model
自定义 Model 定义（models.json）
你可以在 ~/.sf/agent/models.json 里定义自定义 models 和 providers。这允许你添加默认注册表里没有的 models，适合自托管 endpoints（Ollama、vLLM、LM Studio）、微调模型、代理，或者刚发布的新 provider。
SF 读取 models.json 的顺序如下：
~/.sf/agent/models.json：主位置（SF）~/.pi/agent/models.json：回退位置（Pi）- 如果两者都不存在，则创建
~/.sf/agent/models.json
本地 models（Ollama）的快速示例：
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"models": [
{ "id": "llama3.1:8b" },
{ "id": "qwen2.5-coder:7b" }
]
}
}
}
每次打开 /model 时，这个文件都会重新加载，无需重启。
关于 provider 配置、model overrides、OpenAI compatibility 和更多高级示例，见 自定义模型指南。
带 fallbacks 的示例：
models:
planning:
model: claude-opus-4-6
fallbacks:
- openrouter/z-ai/glm-5
- openrouter/moonshotai/kimi-k2.5
provider: bedrock # 可选：固定到某个 provider
当某个 model 切换失败（provider 不可用、被限流、额度耗尽）时，SF 会自动尝试 fallbacks 列表中的下一个 model。
Community Provider Extensions
对于 SF 未内置的 providers，社区扩展可以添加完整 provider 支持，包括正确的 model 定义、thinking format 配置以及交互式 API key 设置。
| 扩展 | Provider | Models | 安装命令 |
|---|---|---|---|
pi-dashscope |
Alibaba DashScope（ModelStudio） | Qwen3、GLM-5、MiniMax M2.5、Kimi K2.5 | sf install npm:pi-dashscope |
对于 DashScope models，更推荐使用社区扩展而不是内置的 alibaba-coding-plan provider，因为前者会走正确的 OpenAI-compatible endpoint，并包含适配 thinking mode 的 per-model compatibility flags。
token_profile
负责协调 model 选择、阶段跳过和上下文压缩。详见 Token 优化。
可选值：budget、balanced（默认）、quality
| 配置 | 行为 |
|---|---|
budget |
跳过 research + reassessment 阶段，优先使用便宜模型 |
balanced |
默认行为：所有阶段运行，使用标准模型选择 |
quality |
所有阶段运行，优先更高质量模型 |
phases
对自动模式中哪些阶段运行做细粒度控制：
phases:
skip_research: false # 跳过 milestone 级 research
skip_reassess: false # 在每个 slice 后跳过 roadmap reassessment
skip_slice_research: true # 跳过每个 slice 的 research
reassess_after_slice: true # 每个 slice 后执行 roadmap reassessment（reassessment 的前提）
require_slice_discussion: false # 每个 slice 前暂停，等待讨论
这些值通常由 token_profile 自动设置，但也可以显式覆盖。
注意： Roadmap reassessment 需要显式设置
reassess_after_slice: true。如果没有它，无论skip_reassess怎么配，reassessment 都不会运行。
skill_discovery
控制 SF 在自动模式中如何发现并应用 skills。
| 值 | 行为 |
|---|---|
auto |
自动查找并应用 skills |
suggest |
在 research 阶段识别到 skills，但不自动安装（默认） |
off |
关闭 skill discovery |
auto_supervisor
自动模式监督器使用的超时阈值：
auto_supervisor:
model: claude-sonnet-4-6 # 可选：supervisor 使用的 model（默认当前 active model）
soft_timeout_minutes: 20 # 提醒 LLM 收尾
idle_timeout_minutes: 10 # 检测停滞
hard_timeout_minutes: 30 # 暂停自动模式
budget_ceiling
自动模式期间允许消耗的最大美元金额。不需要 $，直接填数字：
budget_ceiling: 50.00
budget_enforcement
预算上限的执行方式：
| 值 | 行为 |
|---|---|
warn |
记录警告，但继续运行 |
pause |
暂停自动模式（设置 ceiling 时的默认值） |
halt |
彻底停止自动模式 |
context_pause_threshold
上下文窗口使用率达到多少（0-100）时，自动模式会暂停并进行 checkpoint。设为 0 可关闭。
context_pause_threshold: 80 # 在上下文使用达到 80% 时暂停
默认值：0（关闭）
uat_dispatch
在 slice 完成后自动运行 UAT（User Acceptance Test）：
uat_dispatch: true
Verification（v2.26）
配置在每次 task 执行后自动运行的 shell 命令。若失败，会先尝试自动修复重试，再决定是否继续。
verification_commands:
- npm run lint
- npm run test
verification_auto_fix: true # 失败时自动重试修复（默认：true）
verification_max_retries: 2 # 最大重试次数（默认：2）
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
verification_commands |
string[] | [] |
task 执行后要运行的 shell 命令 |
verification_auto_fix |
boolean | true |
verification 失败时是否自动重试 |
verification_max_retries |
number | 2 |
自动修复重试的最大次数 |
URL Blocking（fetch_page）
fetch_page 工具默认会阻止访问私有网络和内部网络地址，以防 SSRF（server-side request forgery）。这能防止 agent 被诱导去访问内部服务、云 metadata endpoint 或本地文件。
默认会被拦截：
| 类别 | 示例 |
|---|---|
| 私有 IP 段 | 10.x.x.x、172.16-31.x.x、192.168.x.x、127.x.x.x |
| Link-local / 云 metadata | 169.254.x.x（AWS/GCP instance metadata） |
| 云 metadata hostname | metadata.google.internal、instance-data |
| Localhost | localhost（任意端口） |
| 非 HTTP 协议 | file://、ftp:// |
| IPv6 私有地址段 | ::1、fc00:、fd、fe80: |
公共 URL（例如 https://example.com、http://8.8.8.8）不受影响。
允许特定内部主机：
如果你确实需要 agent 访问内网 URL（例如自托管文档、VPN 后的内部 API），可以在全局设置 ~/.sf/agent/settings.json 中添加 fetchAllowedUrls：
{
"fetchAllowedUrls": ["internal-docs.company.com", "192.168.1.50"]
}
或者设置 SF_FETCH_ALLOWED_URLS 环境变量（逗号分隔）。环境变量优先级高于 settings.json：
export SF_FETCH_ALLOWED_URLS="internal-docs.company.com,192.168.1.50"
被允许的 hostname 会绕过 blocklist 检查。但协议限制依然有效，也就是说 file:// 和 ftp:// 仍然不能加入 allowlist。
注意： 这是一个仅全局生效的设置。项目级 settings.json 不能覆盖 URL allowlist，以防克隆下来的仓库把
fetch_page指向内部基础设施。
auto_report（v2.26）
在 milestone 完成后自动生成 HTML 报告：
auto_report: true # 默认：true
报告会以自包含 HTML 文件的形式写入 .sf/reports/，所有 CSS / JS 都内嵌。
unique_milestone_ids
为 milestone IDs 添加随机后缀，以避免团队协作中的 ID 冲突：
unique_milestone_ids: true
# 输出示例：M001-eh88as，而不是 M001
git
Git 行为配置。所有字段都是可选的：
git:
auto_push: false # 提交后推送到远程
push_branches: false # 推送 milestone 分支到远程
remote: origin # git remote 名称
snapshots: true # 长 task 执行期间做 WIP snapshot commits
pre_merge_check: auto # worktree merge 前执行检查（true / false / "auto"）
commit_type: feat # 覆盖 conventional commit 前缀
main_branch: main # 主分支名称
merge_strategy: squash # worktree 分支合并方式："squash" 或 "merge"
isolation: worktree # git isolation："worktree"、"branch" 或 "none"
commit_docs: true # 是否把 .sf/ 产物提交到 git（设为 false 时仅保留本地）
manage_gitignore: true # 设为 false 时，SF 不再修改 .gitignore
worktree_post_create: .sf/hooks/post-worktree-create # worktree 创建后执行的脚本
auto_pr: false # milestone 完成时自动创建 PR（要求 push_branches）
pr_target_branch: develop # 自动创建 PR 的目标分支（默认：main branch）
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
auto_push |
boolean | false |
提交后推送到远程 |
push_branches |
boolean | false |
把 milestone 分支推送到远程 |
remote |
string | "origin" |
Git remote 名称 |
snapshots |
boolean | true |
长 task 期间做 WIP snapshot commits |
pre_merge_check |
bool/string | "auto" |
merge 前是否执行检查（true / false / "auto"） |
commit_type |
string | （自动推断） | 覆盖 conventional commit 前缀（feat、fix、refactor、docs、test、chore、perf、ci、build、style） |
main_branch |
string | "main" |
主分支名称 |
merge_strategy |
string | "squash" |
worktree 分支合并方式："squash"（合并为单个提交）或 "merge"（保留单独提交） |
isolation |
string | "worktree" |
自动模式隔离方式："worktree"（独立目录）、"branch"（直接在项目根目录工作，适合子模块多的仓库）、"none"（无隔离，直接提交到当前分支） |
commit_docs |
boolean | true |
是否把 .sf/ planning 产物提交到 git。设为 false 则仅保留本地 |
manage_gitignore |
boolean | true |
设为 false 后，SF 将完全不修改 .gitignore，不会添加基础规则，也不会做自愈 |
worktree_post_create |
string | （无） | worktree 创建后执行的脚本。环境变量中会传入 SOURCE_DIR 和 WORKTREE_DIR |
auto_pr |
boolean | false |
milestone 完成时自动创建 pull request。要求 auto_push: true 且已安装认证 gh CLI |
pr_target_branch |
string | （main branch） | 自动创建 PR 的目标分支，例如 develop、qa。未设置时默认回退到 main_branch |
git.worktree_post_create
在 worktree 创建后执行脚本（自动模式和手动 /worktree 都适用）。适合复制 .env、建立资源目录软链，或者执行那些 worktree 不会继承的 setup 步骤。
git:
worktree_post_create: .sf/hooks/post-worktree-create
脚本会收到两个环境变量：
SOURCE_DIR：原始项目根目录WORKTREE_DIR：新创建的 worktree 路径
示例 hook（.sf/hooks/post-worktree-create）：
#!/bin/bash
# Copy environment files and symlink assets into the new worktree
cp "$SOURCE_DIR/.env" "$WORKTREE_DIR/.env"
cp "$SOURCE_DIR/.env.local" "$WORKTREE_DIR/.env.local" 2>/dev/null || true
ln -sf "$SOURCE_DIR/assets" "$WORKTREE_DIR/assets"
路径既可以是绝对路径，也可以相对项目根目录。脚本有 30 秒超时限制。失败不会中断流程，SF 会记录告警后继续。
git.auto_pr
在 milestone 完成时自动创建 pull request。适用于 Gitflow 或分支工作流团队，在合并到目标分支前通过 PR 做审查。
git:
auto_push: true
auto_pr: true
pr_target_branch: develop # 或 qa、staging 等
要求：
auto_push: true：创建 PR 前必须先把 milestone 分支推送到远程- 已安装并认证
ghCLI（gh auth login）
工作方式：
- milestone 完成后，SF 先把 worktree squash merge 回主分支
- 如果
auto_push: true，把主分支推送到远程 - 把 milestone 分支推送到远程
- 通过
gh pr create从 milestone 分支向pr_target_branch创建 PR
如果没有设置 pr_target_branch，PR 会默认指向 main_branch（或者自动检测出的主分支）。PR 创建失败不会中断流程，SF 会记录日志后继续。
github（v2.39）
GitHub 同步配置。启用后，SF 会自动把 milestones、slices 和 tasks 同步到 GitHub Issues、PRs 和 Milestones。
github:
enabled: true
repo: "owner/repo" # 省略时从 git remote 自动检测
labels: [sf, auto-generated] # 应用到创建出的 issues / PRs 的标签
project: "Project ID" # 可选的 GitHub Project board
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
enabled |
boolean | false |
是否启用 GitHub 同步 |
repo |
string | （自动检测） | owner/repo 格式的 GitHub 仓库名 |
labels |
string[] | [] |
创建的 issues / PRs 要附加的标签 |
project |
string | （无） | GitHub Project ID，用于接入 Project board |
要求：
- 已安装并认证
ghCLI（gh auth login） - 同步映射会保存在
.sf/.github-sync.json - 具备速率限制感知：当 GitHub API rate limit 偏低时会跳过同步
命令：
/github-sync bootstrap：初始化配置并执行同步/github-sync status：显示同步映射数量
notifications
控制 SF 在自动模式中发出哪些通知：
notifications:
enabled: true
on_complete: true # 单元完成时通知
on_error: true # 出错时通知
on_budget: true # 预算阈值通知
on_milestone: true # milestone 完成时通知
on_attention: true # 需要人工介入时通知
macOS 通知方式： SF 会优先使用 terminal-notifier，不可用时回退到 osascript。建议安装 terminal-notifier，获得更稳定的通知体验：
brew install terminal-notifier
原因：osascript display notification 的通知权限是算在你的终端应用（Ghostty、iTerm2 等）上的，而这些应用在 System Settings → Notifications 中未必被允许。terminal-notifier 会注册成独立 App，并在首次使用时主动请求通知权限。如果通知异常，见 故障排查：macOS 上通知不显示。
remote_questions
把交互式问题路由到 Slack 或 Discord，以支持 headless 自动模式：
remote_questions:
channel: slack # 或 discord
channel_id: "C1234567890"
timeout_minutes: 15 # 问题超时（1-30 分钟）
poll_interval_seconds: 10 # 轮询间隔（2-30 秒）
post_unit_hooks
在特定单元完成后触发的自定义 hooks：
post_unit_hooks:
- name: code-review
after: [execute-task]
prompt: "Review the code changes for quality and security issues."
model: claude-opus-4-6 # 可选：覆盖 model
max_cycles: 1 # 每次触发最多执行几轮（1-10，默认 1）
artifact: REVIEW.md # 可选：若该文件已存在则跳过
retry_on: NEEDS-REWORK.md # 可选：若生成该文件，则回退并重跑触发单元
agent: review-agent # 可选：指定使用哪个 agent 定义
enabled: true # 可选：保留配置但临时禁用
after 可识别的 unit types 包括：research-milestone、plan-milestone、research-slice、plan-slice、execute-task、complete-slice、replan-slice、reassess-roadmap、run-uat
Prompt 占位符： {milestoneId}、{sliceId}、{taskId} 会自动替换成当前上下文值。
pre_dispatch_hooks
在 dispatch 前拦截某个单元。支持三种动作：
Modify：在单元 prompt 前后拼接文本
pre_dispatch_hooks:
- name: add-standards
before: [execute-task]
action: modify
prepend: "Follow our coding standards document."
append: "Run linting after changes."
Skip：完全跳过该单元
pre_dispatch_hooks:
- name: skip-research
before: [research-slice]
action: skip
skip_if: RESEARCH.md # 可选：仅当该文件存在时才跳过
Replace：完全替换该单元 prompt
pre_dispatch_hooks:
- name: custom-execute
before: [execute-task]
action: replace
prompt: "Execute the task using TDD methodology."
unit_type: execute-task-tdd # 可选：覆盖 unit type 标签
model: claude-opus-4-6 # 可选：覆盖 model
所有 pre-dispatch hooks 都支持 enabled: true/false，用于开关而不删除配置。
always_use_skills / prefer_skills / avoid_skills
Skill 路由偏好：
always_use_skills:
- debug-like-expert
prefer_skills:
- frontend-design
avoid_skills: []
Skills 既可以写裸名称（去 ~/.agents/skills/ 和 .agents/skills/ 查找），也可以写绝对路径。
skill_rules
基于人类可读触发条件的情景化 skill 路由：
skill_rules:
- when: task involves authentication
use: [clerk]
- when: frontend styling work
prefer: [frontend-design]
- when: working with legacy code
avoid: [aggressive-refactor]
custom_instructions
附加到每个会话上的持久指令：
custom_instructions:
- "Always use TypeScript strict mode"
- "Prefer functional patterns over classes"
如果是项目特有知识（模式、坑点、经验），请优先放到 .sf/KNOWLEDGE.md 中，因为它会自动注入每个 agent prompt。你也可以通过 /sf knowledge rule|pattern|lesson <description> 添加。
RUNTIME.md：运行时上下文（v2.39）
你可以在 .sf/RUNTIME.md 中声明项目级运行时上下文。这个文件会内联进 task execution prompt，让 agent 能准确知道运行环境，而不必靠猜测路径或 URL。
位置： .sf/RUNTIME.md
示例：
# Runtime Context
## API Endpoints
- Main API: https://api.example.com
- Cache: redis://localhost:6379
## Environment Variables
- DEPLOYMENT_ENV: staging
- DB_POOL_SIZE: 20
## Local Services
- PostgreSQL: localhost:5432
- Redis: localhost:6379
适合放在这里的信息，是那些执行时需要知道、但又不属于 DECISIONS.md（架构）或 KNOWLEDGE.md（规则 / 模式）的内容。典型例子包括：API base URL、服务端口、部署目标，以及环境特有配置。
dynamic_routing
基于复杂度的 model 路由。详见 动态模型路由。
dynamic_routing:
enabled: true
capability_routing: true # 按 task capability 评分 models（v2.59）
tier_models:
light: claude-haiku-4-5
standard: claude-sonnet-4-6
heavy: claude-opus-4-6
escalate_on_failure: true
budget_pressure: true
cross_provider: true
context_management（v2.59）
控制自动模式会话中的 observation masking 和 tool result truncation。可在不增加 LLM 开销的前提下，减少 compaction 之间的上下文膨胀。
context_management:
observation_masking: true # 用占位符替换旧 tool result（默认：true）
observation_mask_turns: 8 # 保留最近 N 个 user turn 的结果（1-50，默认：8）
compaction_threshold_percent: 0.70 # 在 70% 上下文使用率处触发 compaction（0.5-0.95，默认：0.70）
tool_result_max_chars: 800 # 单个 tool result 的最大字符数（200-10000，默认：800）
service_tier（v2.42）
OpenAI 支持模型的 service tier 偏好。可通过 /sf fast 切换。
| 值 | 行为 |
|---|---|
"priority" |
Priority tier：2 倍成本，更快响应 |
"flex" |
Flex tier：0.5 倍成本，更慢响应 |
| （未设置） | 默认 tier |
service_tier: priority
forensics_dedup（v2.43）
可选启用：在 /sf forensics 提交 issue 之前，先搜索现有 issues 和 PRs。会额外消耗一些 AI tokens。
forensics_dedup: true # 默认：false
show_token_cost（v2.44）
可选启用：在 footer 中显示每次 prompt 和累计会话的 token 成本。
show_token_cost: true # 默认：false
auto_visualize
在 milestone 完成后自动显示工作流可视化器：
auto_visualize: true
详见 工作流可视化器。
parallel
同时运行多个 milestones。默认关闭。
parallel:
enabled: false # 总开关
max_workers: 2 # 并发 workers 数（1-4）
budget_ceiling: 50.00 # 聚合成本上限（美元）
merge_strategy: "per-milestone" # "per-slice" 或 "per-milestone"
auto_merge: "confirm" # "auto"、"confirm" 或 "manual"
完整细节见 并行编排。
完整示例
---
version: 1
# Model selection
models:
research: openrouter/deepseek/deepseek-r1
planning:
model: claude-opus-4-6
fallbacks:
- openrouter/z-ai/glm-5
execution: claude-sonnet-4-6
execution_simple: claude-haiku-4-5-20250414
completion: claude-sonnet-4-6
# Token optimization
token_profile: balanced
# Dynamic model routing
dynamic_routing:
enabled: true
escalate_on_failure: true
budget_pressure: true
# Budget
budget_ceiling: 25.00
budget_enforcement: pause
context_pause_threshold: 80
# Supervision
auto_supervisor:
soft_timeout_minutes: 15
hard_timeout_minutes: 25
# Git
git:
auto_push: true
merge_strategy: squash
isolation: worktree # "worktree", "branch", or "none"
commit_docs: true
# Skills
skill_discovery: suggest
skill_staleness_days: 60 # Skills unused for N days get deprioritized (0 = disabled)
always_use_skills:
- debug-like-expert
skill_rules:
- when: task involves authentication
use: [clerk]
# Notifications
notifications:
on_complete: false
on_milestone: true
on_attention: true
# Visualizer
auto_visualize: true
# Service tier
service_tier: priority # "priority" or "flex" (for /sf fast)
# Diagnostics
forensics_dedup: true # deduplicate before filing forensics issues
show_token_cost: true # show per-prompt cost in footer
# Hooks
post_unit_hooks:
- name: code-review
after: [execute-task]
prompt: "Review {sliceId}/{taskId} for quality and security."
artifact: REVIEW.md
---