d73a73d7f3
- Replace fileURLToPath(import.meta.url) with import.meta.dirname across
scripts and extensions
- Rename parsers-legacy.ts → parsers.ts
- Remove deleted plan/spec docs (cicd-pipeline)
- Update package.json engines and deps across workspace packages
- Update web/package-lock.json
💘 Generated with Crush
Assisted-by: GLM-5.1 via Crush <crush@charm.land>
473 lines
12 KiB
Markdown
473 lines
12 KiB
Markdown
# SF 快速开始
|
||
|
||
SF 是一个 AI 编程代理，负责规划、执行、验证和交付，让你可以把注意力放在“要构建什么”上。本指南会带你完成 macOS、Windows 和 Linux 的安装，并启动你的第一个会话。
|
||
|
||
---
|
||
|
||
## 前置条件
|
||
|
||
| 要求 | 最低版本 | 推荐版本 |
|
||
|------|----------|----------|
|
||
| **[Node.js](https://nodejs.org/)** | 24.0.0 | 24 LTS |
|
||
| **[Git](https://git-scm.com/)** | 2.20+ | 最新版 |
|
||
| **LLM API key** | 任意受支持提供商 | Anthropic（Claude） |
|
||
|
||
如果你还没有安装 Node.js 或 Git，请按下面对应操作系统的步骤进行。
|
||
|
||
---
|
||
|
||
## 按操作系统安装
|
||
|
||
### macOS
|
||
|
||
> **下载链接：** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/mac) | [Homebrew](https://brew.sh/)
|
||
|
||
**第 1 步：安装 Homebrew**（如果已安装可跳过）：
|
||
|
||
```bash
|
||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||
```
|
||
|
||
**第 2 步：安装 Node.js 和 Git：**
|
||
|
||
```bash
|
||
brew install node git
|
||
```
|
||
|
||
**第 3 步：验证依赖已安装：**
|
||
|
||
```bash
|
||
node --version # 应输出 v22.x 或更高
|
||
git --version # 应输出 2.20+
|
||
```
|
||
|
||
**第 4 步：安装 SF：**
|
||
|
||
```bash
|
||
npm install -g sf-run
|
||
```
|
||
|
||
**第 5 步：设置你的 LLM provider：**
|
||
|
||
```bash
|
||
# 选项 A：设置环境变量（推荐 Anthropic）
|
||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||
|
||
# 选项 B：使用内置配置向导
|
||
sf config
|
||
```
|
||
|
||
如果想永久保存这个 key，把 export 语句写入 `~/.zshrc`：
|
||
|
||
```bash
|
||
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
|
||
source ~/.zshrc
|
||
```
|
||
|
||
所有 20+ provider 的完整配置方式请见 [提供商设置指南](./providers.md)。
|
||
|
||
**第 6 步：启动 SF：**
|
||
|
||
```bash
|
||
cd ~/my-project # 进入任意项目目录
|
||
sf # 启动一个会话
|
||
```
|
||
|
||
**第 7 步：确认一切正常：**
|
||
|
||
```bash
|
||
sf --version # 输出已安装版本
|
||
```
|
||
|
||
进入会话后，输入 `/model` 以确认你的 LLM 已成功连接。
|
||
|
||
> **Apple Silicon PATH 修复：** 如果安装后找不到 `sf`，可能是 npm 的全局 bin 目录没有加入 PATH：
|
||
> ```bash
|
||
> echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
|
||
> source ~/.zshrc
|
||
> ```
|
||
|
||
> **oh-my-zsh 冲突：** oh-my-zsh 的 git 插件定义了 `alias sf='git svn dcommit'`。可在 `~/.zshrc` 中加入 `unalias sf 2>/dev/null`，或者改用 `sf-cli`。
|
||
|
||
---
|
||
|
||
### Windows
|
||
|
||
> **下载链接：** [Node.js](https://nodejs.org/) | [Git for Windows](https://git-scm.com/download/win) | [Windows Terminal](https://aka.ms/terminal)
|
||
|
||
#### 选项 A：使用 winget（推荐 Windows 10/11）
|
||
|
||
**第 1 步：安装 Node.js 和 Git：**
|
||
|
||
```powershell
|
||
winget install OpenJS.NodeJS.LTS
|
||
winget install Git.Git
|
||
```
|
||
|
||
**第 2 步：重启终端**（关闭并重新打开 PowerShell 或 Windows Terminal）。
|
||
|
||
**第 3 步：验证依赖已安装：**
|
||
|
||
```powershell
|
||
node --version # 应输出 v22.x 或更高
|
||
git --version # 应输出 2.20+
|
||
```
|
||
|
||
**第 4 步：安装 SF：**
|
||
|
||
```powershell
|
||
npm install -g sf-run
|
||
```
|
||
|
||
**第 5 步：设置你的 LLM provider：**
|
||
|
||
```powershell
|
||
# 选项 A：设置环境变量（仅当前会话）
|
||
$env:ANTHROPIC_API_KEY = "sk-ant-..."
|
||
|
||
# 选项 B：使用内置配置向导
|
||
sf config
|
||
```
|
||
|
||
如果要永久保存该 key，可在系统设置的环境变量中添加，或者执行：
|
||
|
||
```powershell
|
||
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-...", "User")
|
||
```
|
||
|
||
所有 20+ provider 的完整配置方式请见 [提供商设置指南](./providers.md)。
|
||
|
||
**第 6 步：启动 SF：**
|
||
|
||
```powershell
|
||
cd C:\Users\you\my-project # 进入任意项目目录
|
||
sf # 启动一个会话
|
||
```
|
||
|
||
**第 7 步：确认一切正常：**
|
||
|
||
```powershell
|
||
sf --version # 输出已安装版本
|
||
```
|
||
|
||
进入会话后，输入 `/model` 以确认你的 LLM 已成功连接。
|
||
|
||
#### 选项 B：手动安装
|
||
|
||
1. 下载并安装 [Node.js LTS](https://nodejs.org/)，安装时勾选 **“Add to PATH”**
|
||
2. 下载并安装 [Git for Windows](https://git-scm.com/download/win)，使用默认选项
|
||
3. 打开一个**新的**终端，然后继续执行上面的第 3-7 步
|
||
|
||
> **Windows 提示：**
|
||
> - 建议使用 **Windows Terminal** 或 **PowerShell**，体验最佳。Command Prompt 也能用，但颜色支持较弱。
|
||
> - 如果 `sf` 无法识别，先重启终端。Windows 需要新开终端才能读取更新后的 PATH。
|
||
> - **WSL2** 也可用，安装 WSL 后，在发行版内部按 Linux 说明继续。
|
||
|
||
---
|
||
|
||
### Linux
|
||
|
||
> **下载链接：** [Node.js](https://nodejs.org/) | [Git](https://git-scm.com/download/linux) | [nvm](https://github.com/nvm-sh/nvm)
|
||
|
||
先确认你的发行版，然后按对应步骤安装。
|
||
|
||
#### Ubuntu / Debian
|
||
|
||
**第 1 步：安装 Node.js 和 Git：**
|
||
|
||
```bash
|
||
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs git
|
||
```
|
||
|
||
#### Fedora / RHEL / CentOS
|
||
|
||
**第 1 步：安装 Node.js 和 Git：**
|
||
|
||
```bash
|
||
curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
|
||
sudo dnf install -y nodejs git
|
||
```
|
||
|
||
#### Arch Linux
|
||
|
||
**第 1 步：安装 Node.js 和 Git：**
|
||
|
||
```bash
|
||
sudo pacman -S nodejs npm git
|
||
```
|
||
|
||
#### 使用 nvm（任意发行版）
|
||
|
||
**第 1 步：先安装 nvm，再安装 Node.js：**
|
||
|
||
```bash
|
||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
|
||
source ~/.bashrc # 或 ~/.zshrc
|
||
nvm install 24
|
||
nvm use 24
|
||
```
|
||
|
||
#### 所有发行版：第 2-7 步
|
||
|
||
**第 2 步：验证依赖已安装：**
|
||
|
||
```bash
|
||
node --version # 应输出 v22.x 或更高
|
||
git --version # 应输出 2.20+
|
||
```
|
||
|
||
**第 3 步：安装 SF：**
|
||
|
||
```bash
|
||
npm install -g sf-run
|
||
```
|
||
|
||
**第 4 步：设置你的 LLM provider：**
|
||
|
||
```bash
|
||
# 选项 A：设置环境变量（推荐 Anthropic）
|
||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||
|
||
# 选项 B：使用内置配置向导
|
||
sf config
|
||
```
|
||
|
||
如果想永久保存这个 key，把 export 语句写到 `~/.bashrc`（或 `~/.zshrc`）中：
|
||
|
||
```bash
|
||
echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
|
||
source ~/.bashrc
|
||
```
|
||
|
||
所有 20+ provider 的完整配置方式请见 [提供商设置指南](./providers.md)。
|
||
|
||
**第 5 步：启动 SF：**
|
||
|
||
```bash
|
||
cd ~/my-project # 进入任意项目目录
|
||
sf # 启动一个会话
|
||
```
|
||
|
||
**第 6 步：确认一切正常：**
|
||
|
||
```bash
|
||
sf --version # 输出已安装版本
|
||
```
|
||
|
||
进入会话后，输入 `/model` 以确认你的 LLM 已成功连接。
|
||
|
||
> **`npm install -g` 遇到权限错误？** 不要用 `sudo npm`。应改为修复 npm 的全局目录：
|
||
> ```bash
|
||
> mkdir -p ~/.npm-global
|
||
> npm config set prefix '~/.npm-global'
|
||
> echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
|
||
> source ~/.bashrc
|
||
> npm install -g sf-run
|
||
> ```
|
||
|
||
---
|
||
|
||
### Docker（任意操作系统）
|
||
|
||
> **下载链接：** [Docker Desktop](https://www.docker.com/products/docker-desktop/)
|
||
|
||
如果你不想在宿主机安装 Node.js，可以在隔离沙箱中运行 SF。
|
||
|
||
**第 1 步：安装 Docker Desktop**（要求 4.58+）。
|
||
|
||
**第 2 步：克隆 SF 仓库：**
|
||
|
||
```bash
|
||
git clone https://github.com/singularity-forge/sf-run.git
|
||
cd sf-2/docker
|
||
```
|
||
|
||
**第 3 步：创建并进入沙箱：**
|
||
|
||
```bash
|
||
docker sandbox create --template . --name sf-sandbox
|
||
docker sandbox exec -it sf-sandbox bash
|
||
```
|
||
|
||
**第 4 步：设置 API key 并运行 SF：**
|
||
|
||
```bash
|
||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||
sf auto "implement the feature described in issue #42"
|
||
```
|
||
|
||
完整的配置、资源限制和 compose 文件请见 [Docker Sandbox 文档](../../../docker/README.md)。
|
||
|
||
---
|
||
|
||
## 安装之后
|
||
|
||
### 选择模型
|
||
|
||
完成 provider 设置后，SF 会自动选择一个默认模型。你可以在会话中随时切换：
|
||
|
||
```
|
||
/model
|
||
```
|
||
|
||
也可以在偏好设置中按阶段配置模型，详见 [配置](./configuration.md)。
|
||
|
||
---
|
||
|
||
## 两种工作方式
|
||
|
||
### 步骤模式 — `/sf`
|
||
|
||
在会话内输入 `/sf`。SF 会一次执行一个工作单元，并在每一步之间暂停，通过向导展示刚完成了什么、下一步是什么。
|
||
|
||
- **没有 `.sf/` 目录**：启动讨论流程，先收集你的项目愿景
|
||
- **已有 milestone，但没有 roadmap**：讨论或研究该 milestone
|
||
- **roadmap 已存在，仍有待完成的 slices**：规划下一个 slice 或执行一个 task
|
||
- **进行到一半的 task**：从上次停下的地方继续
|
||
|
||
步骤模式会让你始终留在回路中，在每一步之间查看和确认输出。
|
||
|
||
### 自动模式 — `/sf auto`
|
||
|
||
输入 `/sf auto` 后就可以离开。SF 会自主完成 research、planning、execution、verification、commit，并持续推进每个 slice，直到 milestone 完成。
|
||
|
||
```
|
||
/sf auto
|
||
```
|
||
|
||
完整细节请见 [自动模式](./auto-mode.md)。
|
||
|
||
---
|
||
|
||
## 推荐工作流：两个终端
|
||
|
||
一个终端跑自动模式，另一个终端负责引导和干预。
|
||
|
||
**终端 1：让它构建**
|
||
|
||
```bash
|
||
sf
|
||
/sf auto
|
||
```
|
||
|
||
**终端 2：在它工作时进行引导**
|
||
|
||
```bash
|
||
sf
|
||
/sf discuss # 讨论架构决策
|
||
/sf status # 查看进度
|
||
/sf queue # 排队下一个 milestone
|
||
```
|
||
|
||
两个终端都会读写同一套 `.sf/` 文件。你在终端 2 里做出的决策，会在下一个阶段边界被自动拾取。
|
||
|
||
---
|
||
|
||
## SF 如何组织工作
|
||
|
||
```
|
||
Milestone → 一个可交付版本（4-10 个 slice）
|
||
Slice → 一个可演示的垂直能力（1-7 个 task）
|
||
Task → 一个适合单个上下文窗口的工作单元
|
||
```
|
||
|
||
铁律是：**一个 task 必须能装进一个上下文窗口。** 装不下，就说明它应该拆成两个 task。
|
||
|
||
所有状态都保存在 `.sf/` 中：
|
||
|
||
```
|
||
.sf/
|
||
PROJECT.md — 项目当前是什么
|
||
REQUIREMENTS.md — 需求契约
|
||
DECISIONS.md — 追加式架构决策记录
|
||
KNOWLEDGE.md — 跨会话规则与模式
|
||
STATE.md — 一眼可见的状态摘要
|
||
milestones/
|
||
M001/
|
||
M001-ROADMAP.md — 带依赖关系的 slice 计划
|
||
slices/
|
||
S01/
|
||
S01-PLAN.md — task 拆解
|
||
S01-SUMMARY.md — 实际发生了什么
|
||
```
|
||
|
||
---
|
||
|
||
## VS Code 扩展
|
||
|
||
SF 也提供 VS Code 扩展。你可以从扩展市场安装（publisher: FluxLabs），或者在 VS Code 扩展面板中直接搜索 “SF”：
|
||
|
||
- **`@sf` 聊天参与者**：在 VS Code Chat 中直接与 agent 对话
|
||
- **侧边栏仪表板**：显示连接状态、模型信息、Token 使用量
|
||
- **完整命令面板**：启动 / 停止 agent、切换模型、导出会话
|
||
|
||
CLI（`sf-run`）需要先安装好，扩展会通过 RPC 与其连接。
|
||
|
||
---
|
||
|
||
## Web 界面
|
||
|
||
SF 也提供一个基于浏览器的可视化项目管理界面：
|
||
|
||
```bash
|
||
sf --web
|
||
```
|
||
|
||
详见 [Web 界面](./web-interface.md)。
|
||
|
||
---
|
||
|
||
## 恢复会话
|
||
|
||
```bash
|
||
sf --continue # 或 sf -c
|
||
```
|
||
|
||
会恢复当前目录最近一次会话。
|
||
|
||
浏览所有保存过的会话：
|
||
|
||
```bash
|
||
sf sessions
|
||
```
|
||
|
||
---
|
||
|
||
## 更新 SF
|
||
|
||
SF 每 24 小时检查一次更新，并在启动时提示。你也可以手动更新：
|
||
|
||
```bash
|
||
npm update -g sf-run
|
||
```
|
||
|
||
或者在会话中执行：
|
||
|
||
```
|
||
/sf update
|
||
```
|
||
|
||
---
|
||
|
||
## 快速排障
|
||
|
||
| 问题 | 解决方式 |
|
||
|------|----------|
|
||
| `command not found: sf` | 把 npm 全局 bin 目录加入 PATH（见上面的系统说明） |
|
||
| `sf` 实际执行了 `git svn dcommit` | oh-my-zsh 冲突，执行 `unalias sf` 或改用 `sf-cli` |
|
||
| `npm install -g sf-run` 权限错误 | 修复 npm prefix（见 Linux 说明）或改用 nvm |
|
||
| 无法连接到 LLM | 用 `sf config` 检查 API key，并确认网络可用 |
|
||
| `sf` 启动时卡住 | 检查 Node.js 版本：`node --version`（需要 22+） |
|
||
|
||
更多问题见 [故障排查](./troubleshooting.md)。
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
- [自动模式](./auto-mode.md)：深入理解自主执行
|
||
- [配置](./configuration.md)：模型选择、超时和预算
|
||
- [命令参考](./commands.md)：所有命令和快捷键
|
||
- [提供商设置](./providers.md)：每个 provider 的详细配置
|
||
- [团队协作](./working-in-teams.md)：多开发者工作流
|