singularity-forge/docs/zh-CN/user-docs/parallel-orchestration.md

# 并行 Milestone 编排

在隔离的 git worktrees 中同时运行多个 milestones。每个 milestone 都拥有自己的 worker 进程、自己的分支和自己的上下文窗口；同时还会有一个 coordinator 跟踪进度、执行预算限制并保持整体同步。

> **状态：** 该功能默认处于 `parallel.enabled: false`。属于显式 opt-in，对现有用户零影响。

## 快速开始

1. 在偏好设置中开启并行模式：

```yaml
---
parallel:
  enabled: true
  max_workers: 2
---
```

2. 启动并行执行：

```
/sf parallel start
```

SF 会扫描所有 milestones，检查依赖与文件重叠，给出一份可并行性报告，并为符合条件的 milestones 启动 workers。

3. 监控进度：

```
/sf parallel status
```

4. 完成后停止：

```
/sf parallel stop
```

## 工作原理

### 架构

```
┌─────────────────────────────────────────────────────────┐
│  Coordinator（你的 SF 会话）                           │
│                                                         │
│  职责：                                                 │
│  - 可并行性分析（依赖 + 文件重叠）                      │
│  - Worker 启动与生命周期管理                            │
│  - 全部 workers 的预算跟踪                              │
│  - 派发控制信号（pause / resume / stop）                │
│  - 会话状态监控                                         │
│  - Merge 对账                                           │
│                                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ Worker 1 │  │ Worker 2 │  │ Worker 3 │  ...          │
│  │ M001     │  │ M003     │  │ M005     │              │
│  └──────────┘  └──────────┘  └──────────┘              │
│       │              │              │                   │
│       ▼              ▼              ▼                   │
│  .sf/worktrees/ .sf/worktrees/ .sf/worktrees/       │
│  M001/           M003/           M005/                  │
│  (milestone/     (milestone/     (milestone/            │
│   M001 branch)    M003 branch)    M005 branch)          │
└─────────────────────────────────────────────────────────┘
```

### Worker 隔离

每个 worker 都是一个完全隔离的独立 `sf` 进程：

| 资源 | 隔离方式 |
|------|----------|
| **文件系统** | Git worktree：每个 worker 都有自己的 checkout |
| **Git 分支** | `milestone/<MID>`：每个 milestone 一条分支 |
| **状态推导** | 通过 `SF_MILESTONE_LOCK` 环境变量，让 `deriveState()` 只看到被分配的 milestone |
| **上下文窗口** | 独立进程：每个 worker 都有自己的 agent sessions |
| **指标** | 每个 worktree 都有自己的 `.sf/metrics.json` |
| **崩溃恢复** | 每个 worktree 都有自己的 `.sf/auto.lock` |

### 协调方式

Workers 和 coordinator 通过基于文件的 IPC 通信：

- **会话状态文件**（`.sf/parallel/<MID>.status.json`）：worker 写入 heartbeat，coordinator 读取
- **信号文件**（`.sf/parallel/<MID>.signal.json`）：coordinator 写信号，worker 消费
- **原子写入**：使用写临时文件再 rename 的方式，避免读到半成品

## 可并行性分析

在真正启动并行执行之前，SF 会先检查哪些 milestones 可以安全并发运行。

### 规则

1. **未完成**：已完成的 milestones 会被跳过
2. **依赖满足**：所有 `dependsOn` 指向的 milestones 都必须已处于 `complete`
3. **文件重叠检查**：如果多个 milestones 会触碰同一批文件，会给出警告（但仍可执行）

### 示例报告

```
# Parallel Eligibility Report

## Eligible for Parallel Execution (2)

- **M002** — Auth System
  All dependencies satisfied.
- **M003** — Dashboard UI
  All dependencies satisfied.

## Ineligible (2)

- **M001** — Core Types
  Already complete.
- **M004** — API Integration
  Blocked by incomplete dependencies: M002.

## File Overlap Warnings (1)

- **M002** <-> **M003** — 2 shared file(s):
  - `src/types.ts`
  - `src/middleware.ts`
```

文件重叠只是警告，不是阻断条件。因为两个 milestones 会运行在各自独立的 worktree 中，它们不会在文件系统层面互相干扰。真正的冲突会在 merge 阶段被检测和处理。

## 配置

把下面内容加到 `~/.sf/PREFERENCES.md` 或 `.sf/PREFERENCES.md`：

```yaml
---
parallel:
  enabled: false            # 总开关（默认：false）
  max_workers: 2            # 并发 workers 数（1-4，默认：2）
  budget_ceiling: 50.00     # 聚合成本上限（美元，可选）
  merge_strategy: "per-milestone"  # 何时 merge："per-slice" 或 "per-milestone"
  auto_merge: "confirm"            # "auto"、"confirm" 或 "manual"
---
```

### 配置参考

| Key | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `enabled` | boolean | `false` | 总开关。只有设为 `true`，`/sf parallel` 命令才可用。 |
| `max_workers` | number（1-4） | `2` | 最大并发 worker 进程数。值越高，内存与 API 预算消耗也越高。 |
| `budget_ceiling` | number | 无 | 所有 workers 的聚合美元预算上限。达到后不会再派发新单元。 |
| `merge_strategy` | `"per-slice"` 或 `"per-milestone"` | `"per-milestone"` | worktree 变更何时回合并到主分支。Per-milestone 会等整个 milestone 完成后再合并。 |
| `auto_merge` | `"auto"`、`"confirm"`、`"manual"` | `"confirm"` | merge-back 策略。`confirm` 会在合并前询问；`manual` 要求显式执行 `/sf parallel merge`。 |

## 命令

| 命令 | 说明 |
|------|------|
| `/sf parallel start` | 分析可并行性、确认并启动 workers |
| `/sf parallel status` | 显示所有 workers 的状态、已完成单元和成本 |
| `/sf parallel stop` | 停止所有 workers（发送 SIGTERM） |
| `/sf parallel stop M002` | 停止某个指定 milestone 的 worker |
| `/sf parallel pause` | 暂停所有 workers（完成当前单元后等待） |
| `/sf parallel pause M002` | 暂停某个指定 worker |
| `/sf parallel resume` | 恢复所有已暂停 workers |
| `/sf parallel resume M002` | 恢复某个指定 worker |
| `/sf parallel merge` | 把所有已完成 milestones 合并回 main |
| `/sf parallel merge M002` | 只把某个指定 milestone 合并回 main |

## 信号生命周期

Coordinator 通过信号和 workers 通信：

```
Coordinator                    Worker
    │                            │
    ├── sendSignal("pause") ──→  │
    │                            ├── consumeSignal()
    │                            ├── pauseAuto()
    │                            │   (完成当前单元后等待)
    │                            │
    ├── sendSignal("resume") ─→  │
    │                            ├── consumeSignal()
    │                            ├── 继续 dispatch loop
    │                            │
    ├── sendSignal("stop") ───→  │
    │   + SIGTERM ────────────→  │
    │                            ├── consumeSignal() or SIGTERM handler
    │                            ├── stopAuto()
    │                            └── 进程退出
```

Workers 会在单元之间检查信号（位于 `handleAgentEnd`）。在 stop 场景下，coordinator 还会额外发送 `SIGTERM` 来提高响应速度。

## Merge 对账

当 milestones 完成后，它们在 worktree 中的改动需要 merge 回主分支。

### Merge 顺序

- **顺序合并**（默认）：按 milestone ID 顺序合并（M001 在 M002 之前）
- **按完成顺序合并**：按照 milestones 实际完成的先后顺序合并

### 冲突处理

1. `.sf/` 状态文件（如 `STATE.md`、`metrics.json`）会**自动解决**，默认接受 milestone 分支版本
2. 代码冲突则会**停止并报告**。合并会暂停，并显示哪些文件冲突。你需要手动解决后，再执行 `/sf parallel merge <MID>` 重试

### 示例

```
/sf parallel merge

# Merge Results

- **M002** — merged successfully (pushed)
- **M003** — CONFLICT (2 file(s)):
  - `src/types.ts`
  - `src/middleware.ts`
  Resolve conflicts manually and run `/sf parallel merge M003` to retry.
```

## 预算管理

当设置了 `budget_ceiling` 时，coordinator 会跟踪所有 workers 的聚合成本：

- 成本会从每个 worker 的 session status 中汇总
- 达到上限后，coordinator 会向 workers 发出停止信号
- 每个 worker 仍会独立遵守项目级 `budget_ceiling` 偏好

## 健康监控

### Doctor 集成

`/sf doctor` 能检测并行会话相关问题：

- **过期的并行会话**：worker 进程已经死亡，但没有清理干净。Doctor 会检查 `.sf/parallel/*.status.json` 中记录的 PID 和 heartbeat，发现失效后自动清理。

可以执行 `/sf doctor --fix` 自动清理。

### 过期检测

满足以下任一条件时，会话会被视为 stale：

- Worker PID 已经不存在（通过 `process.kill(pid, 0)` 检查）
- 最近一次 heartbeat 超过 30 秒

Coordinator 会在 `refreshWorkerStatuses()` 中执行 stale detection，并自动移除已经死亡的会话。

## 安全模型

| 安全层 | 保护内容 |
|--------|----------|
| **Feature flag** | 默认 `parallel.enabled: false`，不影响现有用户 |
| **可并行性分析** | 启动前检查依赖和文件重叠 |
| **Worker 隔离** | 独立进程、worktrees、分支、上下文窗口 |
| **`SF_MILESTONE_LOCK`** | 每个 worker 在状态推导时只能看到自己的 milestone |
| **`SF_PARALLEL_WORKER`** | Worker 不能再嵌套启动新的并行会话 |
| **预算上限** | 跨所有 workers 执行聚合成本限制 |
| **信号式关闭** | 通过文件信号 + SIGTERM 优雅停止 |
| **Doctor 集成** | 检测并清理孤儿会话 |
| **冲突感知 merge** | 遇到代码冲突时停止；`.sf/` 状态冲突自动解决 |

## 文件布局

```
.sf/
├── parallel/                    # Coordinator ↔ worker IPC
│   ├── M002.status.json         # Worker heartbeat + progress
│   ├── M002.signal.json         # Coordinator → worker signals
│   ├── M003.status.json
│   └── M003.signal.json
├── worktrees/                   # Git worktrees（每个 milestone 一个）
│   ├── M002/                    # M002 的隔离 checkout
│   │   ├── .sf/                # M002 自己的状态文件
│   │   │   ├── auto.lock
│   │   │   ├── metrics.json
│   │   │   └── milestones/
│   │   └── src/                 # M002 的工作副本
│   └── M003/
│       └── ...
└── ...
```

`.sf/parallel/` 和 `.sf/worktrees/` 都会被 gitignore，因为它们只是运行时协调文件，永远不会提交。

## 故障排查

### “Parallel mode is not enabled”

在偏好设置里加入 `parallel.enabled: true`。

### “No milestones are eligible for parallel execution”

说明所有 milestones 要么已完成，要么被依赖阻塞。可通过 `/sf queue` 查看 milestone 状态和依赖链。

### Worker 崩溃后如何恢复

Workers 会自动把状态持久化到磁盘。如果某个 worker 进程死亡，coordinator 会通过 heartbeat 超时检测到死掉的 PID，并把该 worker 标记为 crashed。重启后，worker 会从磁盘状态继续：崩溃恢复、worktree 重入和 completed-unit 跟踪都会延续之前的状态。

1. 执行 `/sf doctor --fix` 清理 stale sessions
2. 执行 `/sf parallel status` 查看当前状态
3. 重新执行 `/sf parallel start`，为剩余 milestones 启动新的 workers

### 并行执行完成后发生 merge 冲突

1. 执行 `/sf parallel merge` 查看哪些 milestones 存在冲突
2. 在 `.sf/worktrees/<MID>/` 对应的 worktree 中手动解决冲突
3. 执行 `/sf parallel merge <MID>` 重试

### Workers 看起来卡住了

先检查是否触达了预算上限：`/sf parallel status` 会显示每个 worker 的成本。继续执行的话，提升 `parallel.budget_ceiling` 或直接移除它。