---
name: sotogoal-loop
description: 按 SotoGoal（所及）里的任务依赖或目标子树，批量推进一组任务：取工作集、定顺序、逐条实现、验收、关闭并留下总结。当用户要「落地/执行/推进」给定的任务短号（#T12,#T15）、目标短号（#G7），或一条取入口的规则（「做引力序 top 3」）时使用。
---

# SotoGoal 执行 Loop

纯编排层：从 SotoGoal 取一组任务，在**当前代码仓库**里逐条实现、验收，再把结果写回 SotoGoal。

**适用环境**：能执行 shell 与 git 的 coding agent。本 skill 会对真实数据做写操作：改任务状态、关闭任务、新建任务、加依赖边、发评论、回填 KR。

**所需 scope**：`tasks:read` + `tasks:write` + `goals:read` + `comments:read` + `comments:write`；目标模式回填 KR 另需 `goals:write`；待决策文档写入知识库并核对引用另需 `notes:read` + `notes:write`。

**接入方式，两种择一**：

- **MCP**：已连接 SotoGoal 的 MCP 服务器即可。字段口径见各工具的说明。
- **CLI**：装好 `sotogoal` skill，用它随附的 `sotogoal.mjs`；API 契约以那份 skill 为准。CLI 打到 stderr 的版本提示要看。

两种都有时用 MCP，一轮之内不混用。本轮要用的某个动作只有 CLI 做得到时才改用 CLI；改用之前比对两边 `whoami` 的账号与空间，不一致就停下来问用户。

两种都没有时，停下来请用户连接或安装，不要自己拼 REST 调用顶替。

## 参数

| 参数 | 值域 |
| --- | --- |
| 工作集 | 实体短号，可给多个、逗号分隔：任务 `#T101` / `#T101,#T102`，或目标 `#G7` / `#G7,#G8`。**必填，无默认值** |
| 并行度 | 正整数，默认 1 |
| 任务委派 | `auto`（默认） / `off` |
| 执行位置 | `新建 worktree`（默认） / `当前工作区` |
| 默认模型 | 模型标识，默认：不指定 |
| 任务模型 | 模型标识，默认：继承默认模型 |
| 审查模型 | 模型标识，默认：继承默认模型 |
| 依赖深度上限 | 正整数，默认 10 |
| 新建任务上限 | 正整数，默认 20 |
| 工作集上限 | 正整数，默认 30 |
| 单任务验收轮次上限 | 正整数，默认 3 |

- 「工作集」没给就停下来问，不要自行选定。用户给的是一条取入口的规则时，见「入口是一条规则」。
- 类型字母决定模式：`#T…` 为**任务模式**，`#G…` 为**目标模式**。
- 多个入口必须同一类型字母，混给（`#T101,#G7`）时请用户拆成两次调用。
- 下文标「仅任务模式」「仅目标模式」的条目只在对应模式下执行，其余通用；「入口」指给出的每一个入口。
- 「并行度」是同一时刻最多同时在实现中的任务条数。大于 1 时的规则见「5. 逐条执行」的「并行度大于 1 时」。任务委派为 `off`、或环境开不了 sub agent 时按 1 执行，并在汇总里说明。
- 「任务委派」决定谁来实现任务，与「并行度」相互独立：`auto` 按「agent 复用与交接」选择当前会话、已有或新建的 sub agent；`off` 一律由当前会话实现。环境开不了 sub agent 时由当前会话实现，不报错。独立代码审查不受此参数控制，见「6. 验收」。
- 「默认模型」「任务模型」「审查模型」都是模型标识：不含空白字符的字符串，最多 120 个字符，按宿主接受的写法原样给（宿主用 `provider:model` 之类写法时照写），不补厂商前缀。取值顺序见「5. 逐条执行」的「模型选择」。
- 用户明确指定了「当前工作区」、又要并行度大于 1：停下来问。

## 通道对照

| 动作 | CLI（`sotogoal.mjs`） | MCP |
| --- | --- | --- |
| 按短号定位、确定空间 | `list task --space all --seq T101,T102`（目标用 `list goal`） | `find_items refs="T101,T102" space="all"`（目标加 `type="goal"`） |
| 读任务详情与依赖 | `get task <短号或 id> --space <空间>` | `get_item ref=<短号> space=<空间>`；用 uuid 读时加 `type="task"` |
| 取目标子树下的任务 | `list task --goal G7 --subtree --space <空间>` | `find_items goal="G7" subtree=true space=<空间>` |
| 同上，归档目标下的 | 加 `--archived` | 加 `archived=true` |
| 列目标树与 KR | `list goal --space <空间>`，按 `parentId` 推出子树 | `find_items type="goal" parent=<目标> space=<空间>`，只回直接子目标，逐层往下取 |
| 按引力序排一组任务 | `list task --seq <短号,…> --gravity --space <空间>` | `what_next refs="<短号,…>" space=<空间>` |
| 开工、推进阶段 | `start <id>`；有阶段时 `move <id> --stage <阶段>` | `advance_task action=start`；有阶段时 `action=move stage=<阶段>` |
| 暂停、恢复 | `hold <id> --onHoldReason …` / `resume <id>` | `advance_task action=hold note=…` / `action=resume` |
| 关闭 | `close <id> --resolution completed\|dropped` | `advance_task action=close resolution=completed\|dropped` |
| 以重复关闭 | `close <id> --resolution duplicate --duplicateOfId <被重复任务的短号或 uuid>` | `advance_task action=close resolution=duplicate duplicateOf=<短号>` |
| 新建任务并挂目标 | `create task … --json '{"goalId":"<目标 uuid>"}'` | `create_task … goal=<目标短号>` |
| 加依赖边 | `link add <任务> depends <前置>` | `link_tasks ref=<任务> action=add relation=depends to=<前置>` |
| 回填 KR | `kr set <目标> <krId> --current …` | `set_key_result goal=<目标> krId=… current=…` |
| 发评论 | `comment <短号> --md …` | `add_comment ref=<短号> bodyMarkdown=…` |
| 写入知识库文档 | `create note --spaceId <任务空间 id> --title … --json '{"bodyMarkdown":"…"}'` | `create_note spaceId=<任务空间 id> title=… bodyMarkdown=…` |

**两边字段名不同的地方**：

| 含义 | CLI | MCP |
| --- | --- | --- |
| 短号 | 列表行 `seq`（数字），关联条目与 `goalChain` 里是 `shortId` | `ref`；`goalChain` 里是 `shortId` |
| 合法阶段 | 详情 `ladder.stages`（无阶段时 `ladder` 为 `null`） | 详情 `stages.available`（无阶段时没有 `stages`） |
| 被重复的任务 | 详情 `task.duplicateOfId` | 详情顶层 `duplicateOfId` |
| 暂停状态与恢复日期 | `activity`、`onHoldUntil`；详情里在 `task` 下 | `activity`、`onHoldUntil`；详情里在 `item` 下 |
| 已关闭或暂停的任务 | 引力序里 `rank.tier` 为 `99` | 不进 `tasks`；传了 `refs` 时列在 `inactive` |

`missing`、`links`（含 `relation` / `dir` / `done`）、`blocked`、`rank.blocked`、`goalChain` 两边同名。

**分页**：两边的列表都分页，MCP 默认每页条数更少。`hasMore` 为 `true` 时，带上返回的 cursor 接着翻，直到 `hasMore` 为 `false`。

## 1. 准备

1. **定空间**：用「按短号定位」一次查全部入口。入口带空间前缀时（如 `#myspace:T101`，网页多选复制出来就是这种格式），前缀就是空间：去掉 `#` 与前缀再查，空间直接取前缀。
   - `missing` 非空，说明有入口不存在：停下来把缺失的短号报给用户。
   - 同一个短号在多个空间都有：请用户指明是哪一个。
   - 入口落在不同空间：请用户拆成每个空间各跑一轮。
   - 定下的空间 id 记进台账，之后每次调用都显式带上。
2. **取工作集**，按「2. 工作集」。去重后的条数超过「工作集上限」时，把清单交给用户确认范围，再开工。
3. **确定执行位置**：默认取「新建 worktree」：从主干建本轮的集成 worktree，全程在其中提交。建好之后、动第一处改动之前，立即告知用户三件事，不等确认：worktree 的路径、集成分支名、从哪个分支拉出；并说明当前工作区里未提交的改动不会带过去，工作区有未提交的改动时点名提一句。取「当前工作区」时，不建 worktree、不切分支。
4. **确定实测方式**：在当前仓库里找怎么起本地环境、凭据从哪来（`CLAUDE.md` / `AGENTS.md`、`README`、`scripts/`、已有的 e2e 夹具）。找不到就问用户。开工前必须有答案。
5. **建台账**，按「3. 台账」。
6. **一次提交任务集关联**：有本地 `comment_collaboration_prepare_workset` 时，提交完整工作集的真实任务 id（`taskIds`，按计划执行顺序）与 `expiresAt`，由插件验证当前会话、持久化清单并逐项准备。用 `comment_collaboration_workset_status` 检查覆盖，区分已登记、通道就绪、待恢复、拒绝及结果未知。工作集按本流程扩张或调整后，重新声明完整清单；省略旧项不自动解除其关联。缺少本地工具时，说明未启用批量协同，不声称已覆盖全部任务。关联或通道准备失败只记录协同状态，继续执行任务及其 MCP 操作。

### 入口是一条规则

用户说「做引力序 top 3」这类话时，先把规则落成具体短号，再按任务模式执行：

- 取该空间的引力序：CLI `list task --gravity --space <空间>`，MCP `what_next space=<空间>`。从头往下取 N 条。
  - 跳过已关闭或暂停的（见字段对照表）。
  - `rank.blocked` 为 `true` 的不跳过，它的前置会随闭包一起纳入。
- 空间要和用户确认，不要用默认空间代替。
- N 是入口数，不是工作集大小。
- 取到的短号立即写进台账的 `entries`，之后以台账为准，不要重取。
- 「随便挑几条」「你看着办」这类说法不算规则，停下来问。
- 规则落成短号之后按任务入口执行，交付边界与扩张规则都按「2. 工作集」。

## 2. 工作集

工作集一经锚定就是**本轮快照**。执行中只有「7. 派生问题」的前两档能扩张它。

**本轮交付**在开工时冻结，是执行中判断「这项该不该纳入」的依据；能不能真纳入，还要看授权与各项上限：

- 任务入口：这条任务自己的验收要求，连同它未清前置的闭包。
- 目标入口：开工时取到的子树任务（未关闭、未暂停）作为固定清单，连同这组任务的验收判据。后来出现的子树任务不自动纳入，只按「7. 派生问题」判断是否在补齐已定的交付。
- 规则入口：规则解析出的那组入口任务。

交付判据和初始清单一起记进台账。之后新出现的任务只有补齐**已定的交付**才可能入集，不能扩大交付本身；写不清交付时在准备阶段问用户，执行中不自行承诺。

三种入口在扩张规则、依赖判定和上限上一视同仁；模式只影响初始集合怎么取，以及收尾对入口做什么。

**暂停中的任务不进工作集。** 暂停中：`activity` 为 `paused`，且 `onHoldUntil` 为空、缺省或晚于当前时间（字段位置见字段对照表）。恢复日期已过的，按未暂停处理。

- 入口暂停中：停下来问用户是否 `resume`。不要自行恢复，也不要跳过。用户不恢复的，把它从 `entries` 去掉，记进「未纳入（暂停中）」。
- 其余暂停中的任务记进台账的「未纳入（暂停中）」，不计入「依赖深度上限」与「工作集上限」。

**仅任务模式**

1. **依赖闭包**：读入口详情，在 `links` 里取 `relation` 为 `depends`、`dir` 为 `out`、`done` 为 `false` 的条目，这些是未清的前置。再对每条前置做同样的事，直到没有新条目。
   - 前置暂停中：不纳入，也不展开它的前置。依赖它的任务照常纳入。
   - 前置以 `duplicate` 关闭、`done` 却为 `false`，说明它重复的那条还没做完：读这条前置的详情，拿到被重复任务的 id；那条也是以 `duplicate` 关闭的，就继续往下找，直到一条未关闭的。把它当作这条前置纳入（同一层），照常展开它的前置。沿途已关闭的重复项不进工作集。
2. **工作集** = 各入口的闭包取并集，再加上入口自身，按任务 id 去重。展开时维护一张「已展开」集合，同一条只展开一次。
3. **记归属**：记下每条任务是被哪个（些）入口拉进来的。收尾时要按入口逐个判断。

**仅目标模式**

1. 用「取目标子树下的任务」取每个入口目标的子树，把未关闭（`state` 为 `open`）且未暂停中的任务取并集，就是工作集。归档目标下的任务不在默认结果里；确实要一并处理的，补一次「归档目标下的」查询，结果只含归档的那部分。
2. 工作集内任务的前置在工作集之外的，按任务模式第 1 条展开并纳入。

**深度上限（三种入口通用）**

- 起点：任务入口、以及规则入口解析出的每条任务，各自是第 0 层；目标入口的每条初始子树任务是第 0 层。
- 每沿一条 `depends` 边往下加一层；按每个起点各自算，取最长路径。
- 「7. 派生问题」第二档里没有依赖边的纳入项是新的根：它自身是第 0 层，仍要把它的未清前置逐条展开，每沿一条 `depends` 边加一层，一起检查深度。
- 准备阶段取集就超过上限：停下来报告，不带着超限的快照开工。
- 执行中拟纳入的项（含它的前置）会超过工作集或深度上限：只停这一项纳入，把缺口记进台账与收尾报告，其余额度内的任务照常做。

## 3. 台账

在执行位置的工作树根目录写 `.sotogoal-loop.local.md`，记录快照边界、各条任务的归属和各项上限的已用量。对话上下文可能被压缩，收尾对账只以这份文件为准。台账只有这一份，只由编排者写，不放进 worker 的 worktree。执行位置为「新建 worktree」时，它写在**本轮集成 worktree** 的根目录，**不写入原工作区**；为「当前工作区」时写在那里。

- 写之前确认它被 git 忽略（`git check-ignore -q .sotogoal-loop.local.md`）。没被忽略时，把它追加进 `$(git rev-parse --git-common-dir)/info/exclude`（`info` 目录不存在就先建），不要改 `.gitignore`。
- 开工时文件已存在：`session` 与本会话一致才接着用；不一致、或者任一方取不到会话标识，停下来问用户，不要覆盖。
- 不写入任何凭据。

```markdown
---
session: <本会话的标识，取不到就留空>
mode: task
entries: T101,T102
space: <空间 id>
started_at: <ISO 时间>
---

## 本轮交付

| 入口 | 初始清单 | 交付判据 |
| --- | --- | --- |
| T101 | T101（+前置 T96、T97） | T101 自身验收通过、依赖清空 |
| G7 | T201,T202 | 逐条满足开工时约定的验收要求；移出或受阻的记为交付缺口，不算完成 |

## 上限与已用

| 上限 | 本轮取值 | 已用 |
| --- | --- | --- |
| 并行度 | 2 | 在途 1 |
| 依赖深度上限 | 10 | 3 |
| 新建任务上限 | 20 | 2（T110、T120） |
| 工作集上限 | 30 | 8 |
| 单任务验收轮次上限 | 3 | 逐条计，见快照表 |

## 快照

| 短号 | 归属入口 | 来源 | 状态 | 验收轮次 | 分支 / worktree | 备注 |
| --- | --- | --- | --- | --- | --- | --- |
| T96 | T101 | 初始 | closed | 1 | | |
| T97 | T101,T102 | 初始 | 待合入 | 2 | <分支> · <worktree 路径> | |
| T110 | T102 | 扩张·新建 | todo | 0 | | 扩张：挡 T102 的验收 |

## 未纳入（暂停中）

- T98 挡住 T101；暂停理由：等设计稿

## 快照外（只报告）

每条写：任务短号（或拟建事项）· 归属入口 · 本轮新建/既有 · 阻塞哪项交付 · 未纳入原因。

- T120 · 归属 T102 · 本轮新建 · 不阻塞本轮交付：顺手发现的清理项
- T121 · 归属 G7 · 既有 · 不阻塞已定交付：落在子树内，本轮不动
- （拟建）缓存失效后重试无退避 · 归属 T102 · 阻塞 T102 本轮交付 · 新建额度已满，未建

## 实测入口

<怎么起本地环境、凭据在哪个环境变量里>
```

按任务另记简短索引：实现与审查 agent 标识、交接摘要位置、已审版本、已验版本及覆盖范围、证据位置、已发布评论引用。版本须能定位实际受验内容，含未提交改动；长日志与截图保存在证据中。

维护规则：

- 名称与参数表一致，不缩写。
- 每关闭一条任务，当场更新对应行。
- 日常只更新变化行与索引；任务详情和已归档证据按需读取。压缩台账时保留边界、预算已用、失败轮次、有效裁决及未解决事项。
- 「状态」取任务状态，另有一档「待合入」：worker 已交回、尚未合入集成分支（见「并行度大于 1 时」）。
- 派出 worker 时登记它的分支与 worktree 路径，合入后清空。
- 每次验收没通过，该条的「验收轮次」加一。
- 「来源」写 `初始`、`扩张·新建` 或 `扩张·既有`；备注写清它挡住哪条交付（「挡 T96 的验收」「挡 G7 本轮交付：缺 X」）。
- 快照扩张时追加一行，同步更新「已用」。
- **建单就记**：每次成功新建任务，立刻把「新建任务上限」的已用加一，并把这条任务登记到快照或「快照外」，不论是否纳入——压缩上下文后，只有台账能证明它存在。既有任务转入快照不增加新建已用。
- 移出工作集的任务保留原行，状态写 `paused`，备注写「移出：缺条件」并写明缺什么，或「移出：验收到顶」。
- 被移出或暂停中的任务挡住的，备注写「被 Txx 挡住」。
- 各项上限一律按台账上的「已用」判断。

## 4. 执行顺序

两种模式都用「按引力序排一组任务」，把台账里快照内未关闭的任务一次全部传进去。

- **只做可执行的**：跳过 `rank.blocked` 为 `true` 的，以及已关闭或暂停的（见字段对照表）。`tier` 的其他取值不用来判断能否开工。
- **每关闭一条，就重新取一次候选**（并行度大于 1 时为每合入一条）。原先被挡住的会自然浮上来。
- 调度取排序与阻塞状态，收尾取状态与关闭方式；用现有工具可提供的精简结果，分页取全。正文与讨论在开工前读最新；接口不提供所需字段时补读详情，不用缓存推断远端状态。

在可执行的候选里，按下面三档依次判定，命中即用：

1. **入口正文指定了顺序**（编号步骤、「先…再…」）：按正文排。一份正文只管它自己拉进来的那些任务。
2. **引力序**：按返回的顺序做。不要按入口分组各排各的。
3. **都没有**：前置先清完的先做。

不要按入口串行，即做完一个入口的整条链再开下一个。工作集是一张去重后的平表。

并行度大于 1 时，同时在做的任务两两之间还须满足：

- 彼此之间没有 `depends` 路径；
- 不受入口正文指定的顺序约束：第 1 档的「先…再…」在并行下是硬序。

「可能改到同一处代码」不作为能否并行的判据，只作挑选时的偏好：尽量不与在途任务同域（同一标签、同一模块）同时做。

入口任务不在这里关闭（仅任务模式），见「8. 收尾」。入口自己有实作内容时照常实现、验收；没有就跳过。

## 5. 逐条执行

- **开工前重新读一次这条任务的详情**，不要用取工作集时读到的那份。正文、讨论和依赖边都可能已经变了。评论与正文矛盾时怎么取舍，按 SotoGoal 的使用说明执行（CLI：`sotogoal` skill 的「评论」一节；MCP：`get_item` 的工具描述）。
- **推进状态**：
  - 任务没有阶段：开工时 `start`。
  - 任务有阶段：开工时 `move` 到表示「进行中」的那一档（如 `developing`、`fixing`），进入验收时 `move` 到表示「待验收」的那一档（如 `accept_pending`、`verify_pending`）。`move` 本身就会把任务置为进行中，不必先 `start`。
  - 阶段名一律从合法阶段字段里取，不要猜。
- **声明当前工作任务**：有本地 `comment_collaboration_select_task_context` 时，在实际执行该任务前用真实 `taskId` 和可选 `taskContext` 声明当前工作，不以关联或通道就绪为前提。批量准备、通道修复和后台恢复不替代此声明，也不自动切换任务。声明失败时说明协同不可用，仍继续任务和普通 MCP 操作；提问改用显式任务评论，不依赖原生自动归属。
- **登记与维护协同**：有本地插件时由其核实当前会话，不从台账或历史会话 ID 手工登记。无插件时，仅在能从当前应用独立取得真实当前会话 ID 的情况下，按 SotoGoal 使用说明「任务会话」通过 `task_session` 登记；取不到就说明未关联，不猜测。执行情况已知时用 `report` 上报；`unknown` 不解除关联。误登记须核实具体关联后用 `unregister` 解除，不影响其他会话和历史。普通执行和后台重试不得自动启用 `replaceChannel: true` 或 `allowReassociate: true`；这些选项只用于用户明确要求的新替换或重新关联。
- **发表评论与提问**：普通进度评论仍用 MCP `add_comment`。业务提问统一调用 `comment_question_publish`，固定本题 `taskId`、稳定 `requestKey`、完整问题、`mode` 与有效期；授权、通道检查、原通道修复和安全降级由插件处理。按返回的 `interactive`、`comment_only`、`unknown`、`not_published` 区分结果，不把普通评论或发布回执说成回复已提交。`comment_only` 且 `replyDelivery: waiting_channel` 时可回复原问题并等待原通道恢复；`unavailable` 时在原应用回答。原生确认仍须核对原交互，不因回退获得执行权限。`unknown` 保留同一问题键核对原任务，不重发、不换工具。只有明确返回 `notExecuted: true` 及 `sessionFallback`，且原 MCP `add_comment` 的参数定义明确包含 `questionPublication` 时，才把该完整对象原样交给它做最后的普通评论降级；不自行拼会话或使用历史会话。缺少可信发送前失败与当前会话凭据时在当前应用提问。继续独立工作，必须取得决策才等待。支持的原生提问与确认、归属及回复路由按 SotoGoal 使用说明「任务评论协同」执行；任意最终文本不受自动拦截。
- **多任务提问归属**：先选定本题对应的任务，再使 `comment_question_publish` 的 `taskId` 与它一致。尽量在可编辑的问题标题或正文中写明所选任务短号，如 `#T12`；需区分空间时使用限定短号。发起原生提问前，有本地工具时立即用 `comment_collaboration_select_task_context` 重新声明所选 `taskId`，并在 `taskContext` 中写明短号。短号供人核对问题归属，偶发误投时可据此识别；它不会自动决定或覆盖插件路由。当前任务声明是会话上下文，原生推断仍可能与当前任务不一致。需要明确发布位置时，使用逐题固定任务的统一提问入口。
- **批次级提问**：优先选择入口总任务；没有适用总任务时，在工作集中选择合适任务并写明所选短号。当前交互通道不支持目标页路由，不向只收任务的工具传目标引用。
- **答复投递评论**：普通投递的当前真人评论包含问题时，用 SotoGoal `add_comment`（`ref: taskId`、`type: "task"`、`replyTo: replyToCommentId`、`bodyMarkdown: 实际答案`）直接回复。目标取当前投递提供的 `replyToCommentId`，不从历史上下文挑选。只在当前应用回答或自动接纳反馈都不算评论答复；发送失败如实说明。不要自动复制私有会话内容或最终输出到评论。历史答复与操作确认仅作上下文，不续授权。
- **按「任务委派」决定谁来实现**，见「agent 复用与交接」。并行度为 1 时 worker 在编排者的执行位置里实现，交回后由编排者提交、验收；并行度大于 1 时每个在途 worker 自带分支与 worktree，见「并行度大于 1 时」。
- **TDD 优先**。
- **提交粒度**：每条任务至少一笔提交，不同任务的改动不混在同一笔里。判定放弃的与移出工作集的任务除外。
- **单任务验收轮次上限**：同一条任务连续验收不通过、达到上限后，不再开下一轮，三选一：
  - 从整体架构重新审视方案。确实换了方案的，轮次可以重置，但整轮只准重置一次，并在台账备注里写明。
  - `hold` 住并写明卡在哪里，即移出工作集（见「移出工作集」）；需要调查的，按「7. 派生问题」建一条调查任务。
  - 停下来交给用户。

  同一条任务第二次到顶，只能 `hold` 或交给用户。

### agent 复用与交接

- `auto`：串行小任务若范围明确、当前会话已有所需上下文，由当前会话实现；需要委派时，同一轮同模块的后续任务与修复优先交回原 worker。并行任务各用独立 worker；模块跨度大、上下文混淆或需要新的独立视角时新建。每条任务仍单独提交、验收和记账。
- 独立 reviewer 可连续审查本轮相关任务及修复；它不得参与所审代码的实现或修复，发现问题交回实现者。承担过相关实现的 agent 不作为该部分的独立 reviewer。
- UI 审查与验收优先复用已掌握上下文且具备所需工具的 agent；有必要独立委派较大范围的视觉或交互检查时再新建。角色变化本身不要求新开 agent。
- 先判断委派需要，再按「模型选择」核对模型。用户通过「任务模型」或「默认模型」指定实现模型且当前会话不匹配时，`auto` 必须委派；`off` 时说明冲突，请用户裁决，不擅自开 agent 或忽略模型要求。复用前确认角色、模型与执行位置符合要求；模型不符且宿主不能切换时新建。
- 派发只给本任务所需的：空间与任务标识、最新要求和有效裁决、验收判据、工作目录与基准版本、修改职责、相关代码入口、实测入口与凭据环境变量名、已知阻碍。复用时补当前任务边界及相对上次交接的变化，确认上一任务已交回；并行时提醒共享代码库中其他执行者的修改边界。
- worker 交回：改动与版本、自测范围和结果及证据位置、未解决问题与派生问题建议。reviewer 交回：所审版本与范围、问题及依据、未验证项。编排者复用证据充分且仍有效的结果；缺失、过期或矛盾时再补查。
- 新 agent 按宿主支持的方式传递上述交接内容，不默认复制整段对话；worker 只加载本任务适用的仓库规范，不承担整轮台账与关单编排。

### 模型选择

- 「默认模型」是本轮新建 sub agent 时的默认模型，不改变编排者自身的模型。
- 「任务模型」只作用于实现任务的 sub agent，「审查模型」只作用于做代码审查的 sub agent。UI 审查与验收的新 agent 按用户指定或仓库模型规则选择。
- 取值逐级回落，两个角色互不串：某个角色按「该角色的模型 → 默认模型 → 仓库适用的模型规则 → 宿主的当前模型或默认选择」取，另一角色给了什么不影响它。没有适用规则时不猜模型名，走宿主选择。
- 模型标识原样传给 sub agent，不做改写。
- 宿主支持推理强度时，按用户要求或适用的仓库规则显式设置；没有要求时按任务复杂度选择，不将模型单价等同于整轮 token 用量。
- 环境开不了 sub agent 时允许回退；用户明确指定了模型却用不了的，不要静默换成别的模型：说明是哪个模型不可用，让用户决定是否回退。
- 没有真正按某个模型执行时（没开对应的 sub agent，或回退到了别的模型），在汇总里写明，不要说成已按该模型执行。

### 单写者

单 Agent 执行时，执行者同时承担编排者职责。任务状态、评论、新建任务、依赖边与台账只由编排者写；任务委派为 `auto`、并行度为 1 时也一样。worker 不推进状态、不关闭任务、不读写台账；审查 sub agent 只交回审查结论。

worker 碰到「7. 派生问题」里按判据**不能就地修、需要独立一条任务**且挡住当前任务的情况，或判定缺条件时，停下并上报，不再占并行度。改动怎么交回看并行度：并行度为 1 时留在执行位置，不提交、不建分支；并行度大于 1 时提交到自己的分支并交回分支名。之后的处置看上报的是哪一档：挡住当前任务的，由编排者按「7. 派生问题」建任务、加依赖边；判定缺条件的，由编排者按「移出工作集」处理。已有改动都不进集成分支：串行时由编排者另存到单独分支，并行时留在 worker 自己的分支上。

### 进展评论

以下事件发生时，由编排者及时在对应任务评论区记录，不能只在当前会话反馈。worker 与审查 sub agent 只向编排者报告，由编排者汇总发布。

| 事件 | 评论内容 |
| --- | --- |
| 形成实质执行计划 | 执行范围、主要步骤与验证方式 |
| 完成关键里程碑 | 已完成事项及证据、剩余事项 |
| 遇到阻碍 | 阻碍事实、影响及下一步 |
| 需要用户决策 | 待裁决问题、可选方案及影响、建议与依据 |
| 验收结束 | 验收结果及证据、未通过项或剩余事项 |

按事件选择必要内容，不要求每条包含表中所有字段。短任务没有独立里程碑时不另发里程碑评论；验收与总结可合并一次记录。阻碍和待决策项及时记录，不逐条复制聊天进展、工具调用或思考过程。

待决策项涉及方案、计划文档等材料时，先将文档写入对应任务空间的 SotoGoal 知识库，再在评论中引用知识短号。引用已有其他空间的材料时，使用明确指向该材料的云端可访问平台链接，不用短号或仅补空间前缀代替。发布前核对引用目标正确、裁决用户有权读取，确保用户能在 SotoGoal 平台上依据评论及其引用材料作出裁决；不能仅引用代码仓库路径或本地文件路径。

同一事件只记录一次。验收、关单与收尾需要的总结，已有评论覆盖时复用该评论；有新结果时只补充变化，不重复发布相同结论。

### 退出 Working 前提醒

主会话准备结束本轮、进入 Ready、等待用户回答或操作确认、因阻碍或额度上限停止，以及完成任务集时，编排者必须先在对应任务发布一条能生成消息中心提及提醒的评论。写明当前结果、停止或等待原因、用户下一步；不要只在会话最终回复里提问或告知停止。

- **有问题待回答**：按「发表评论与提问」使用协同提问入口；即将结束本轮等待答复时，传 `notifyOnExit: true`，将问题与本次退出提醒关联。仍会继续独立工作的提问不设置此项。已发布并关联的问题同时承担本次等待提醒，不另发相同通知；操作确认仍须原生交互，不以普通评论代替。
- **结束或总结**：有 `comment_collaboration_notify` 时，用真实 `taskId` 和 `text` 发布本次结果，默认 `kind: ready`；确属停止时使用 `kind: stopped`。核对返回的提醒状态及有效收件人，不能只检查正文有 `@`。任务集完成可将提醒并入总结，不重复发一条空通知。
- **确定任务**：单任务通知该任务；多任务的局部等待通知对应任务，整个工作集收尾选择入口任务，无单一入口时选声明顺序中的第一个入口，并说明整体结果。发布前重新声明该任务为当前工作任务。不能向工作集全部任务广播同一提醒。
- **避免重复**：本次转换已有成功提醒时复用；早先的里程碑评论不抵消本次停止提醒。子 agent 只向编排者报告；工具等待或主会话仍在执行的异步提问不另作停止通知。
- **不可用时**：提醒失败如实报告，保留已返回的事件标识核对，不换身份重发；不能因提醒失败继续未经授权的工作，也不能阻止用户停止。缺少支持提醒的工具时，在任务评论与当前会话说明需要跟进，但不声称已生成消息中心提醒。

插件在已授权的原会话观察到状态转换后核对遗漏，可稍后补发提醒；它不通过长时间无输出推断停止。断网、插件停用或崩溃时不保证即时补发。流程要求仍由编排者执行，不能依赖自动兜底省略结果或待决策问题。

### 移出工作集

任务缺条件、本轮落不了地时，移出工作集，接着做其余任务，收尾时汇报。

缺条件只指按本 skill 的规则拿不到的东西：

- 凭据或账号（见「6. 验收」里实测的通用规则）；
- 需要用户做的判断，如产品取舍、法务口径；
- 未就绪的外部前置，如第三方开通、审批、真机或硬件、只能在生产环境做的操作；
- 写不出验收判据的需求，如正文为空、标题能读出两种做法。

不算缺条件、按「单任务验收轮次上限」处理的：测试红、验收不通过、「环境问题」、实现难度。缺的是整轮共用的条件（如实测方式）时不移出，按「1. 准备」停下来问。

做法：

1. 在开工前重读详情时判定。实现中途才发现的，已有改动**另存**：提交到一条以该任务短号命名的单独分支，执行位置恢复到改动前，分支名登记进台账「分支 / worktree」列。
2. `hold` 这条任务，理由写明缺什么、谁能补；有另存分支的写上分支名。
3. 不删它的依赖边。被它挡住的任务留在工作集里，`rank.blocked` 为 `true`，不会被选中。
4. 移出的任务仍留在快照里，只是不再执行；各项上限的「已用」不减。按「3. 台账」的维护规则更新台账。
5. 移出的条数超过工作集的一半，或者每个入口都已被移出、或被移出与暂停中的任务直接或间接挡住时，停下来问用户。

### 并行度大于 1 时

执行者分两种：**编排者**（本会话）与 **worker**（每条在途任务一个 sub agent）。已交回的 worker 可按「agent 复用与交接」接下一条任务。任务委派为 `off` 时并行度按 1 执行，本节不适用。

**隔离与合入**：

- 编排者执行位置所在的分支是本轮的**集成分支**。每个 worker 从集成分支的当前头拉出自己的 worktree 与分支，在其中实现、跑测试、做代码审查。
- worker 按交接要求交回，并附分支名。
- 合入由编排者串行处理，一次一条：rebase 到集成分支最新头 → 核对证据、按「验证证据复用」完成集成后的验证 → 合入集成分支 → 清理该 worker 的 worktree。复用 worker 接下一条并行任务时，从集成分支最新头重新准备隔离位置。
- rebase 冲突或重验不通过：退回修，计入该任务的验收轮次。
- 整轮只该递增一次的全局编号（发布版本号之类）：worker 不改，由编排者在合入时统一处理。

**实测串行**：实现、单测、代码审查可以并行；本地环境上的实测同一时刻只有一条在跑，由编排者排队。认证仍是一轮一次，由编排者做。

**关闭时机**：任务合入集成分支、且合入后验收通过，才关闭。

## 6. 验收

每条任务都要验收，通过了才能关闭。验收包括三项，缺一不可：

- 跑测试用例；
- 做一次代码审查：优先交给独立的 sub agent，用「审查模型」，按「agent 复用与交接」复用；环境开不了 sub agent 时在当前会话里审查，并说明未做独立审查。
- 在本地环境上实测：按需造测试数据，覆盖增删改查与反例，不只验正常路径。

**验收不通过，一条都不许关闭。** 以下都不算通过：

- 测试没跑、没有实测、测试红着；
- 「剩下的是环境问题」；
- 「核心逻辑已经对了」；
- 「下一条任务会顺手带上」；
- 「先关掉免得挡住别人」。

关闭方式：

- 通过后以 `completed` 关闭；验收结果按「进展评论」记录，任务入口的关闭条件见「8. 收尾」。
- 判定放弃时，以 `dropped` 或 `duplicate` 关闭并写明原因，不要用 `completed` 顶替。
- 「工作集已清空」是收尾的判据，不是本轮的目标。跑不完就照实报告。

实测的通用规则（与具体仓库无关）：

- 凭据只从环境变量读，不拼进命令行。要发请求就写个小脚本，在脚本里读环境变量、拼请求体。
- 不绕过凭据的取得：不翻 `.env`、不新注册账号、不改鉴权放行。
- 一轮只认证一次，复用到底。
- 要验的行为涉及权限收窄时，用那一档权限的凭据，不要用更高权限的代替。

界面改动还要做视觉验收：用浏览器走完实际流程，截图并把截图作为图像输入交给模型读图，检查布局、文字、遮挡、溢出和响应式问题，同时检查控制台。模型或工具不支持图像输入、只保存截图而未读图、只看 DOM/CSS/源码推断效果，都不算视觉验收通过；必须标为未验证，不得以功能实测或模型自称多模态代替。

### 验证证据复用

- 每项证据记录对应版本、覆盖的验收判据、命令或实际操作、参数及相关环境条件、结果与证据位置；凭据只记环境变量名。通过的结果仅在受验源码、依赖、配置、相关环境与前提未变时有效；版本号或缓存存在本身不证明有效。
- 修复后由原 reviewer 复查原问题、修复差量及受影响范围；方案、公共契约或共享状态改变，以及出现新风险时扩大审查。实现者完成相应重验，未受影响且仍有效的证据继续使用。
- rebase、冲突处理或其他任务改变了受验输入时，按影响重跑测试与本地实测；涉及跨任务交互时执行集成回归。影响无法界定时扩大到相关完整验证范围，不能仅凭无冲突或 diff 未变认定有效。
- 关闭前由编排者核对最终集成版本上的三项验收覆盖及界面读图证据；有效证据可复用，缺项须补齐。减少重复执行不减少验收判据，不把未执行或失败的结果记为通过。

## 7. 派生问题

执行中暴露出别的问题时，先按下面的判据决定就地修还是新建；需要新建的，按它挡住了谁分三档。

新建任务时：

- 打上合适的标签。
- 挂到所属目标下。默认挂当前任务所属的目标，即详情里 `goalChain` 第一层的 `id`；确实不属于任何目标才留空。

**新建不等于纳入。** 编排者可以在既有授权与「新建任务上限」额度内新建，不必逐条请用户批准；worker 不建单，按下面三档上报，由编排者决定。新建与纳入都不扩大空间、仓库或操作权限。

先判断能不能就地修：属于当前任务的实现或验收范围、不需要独立交付的，就地修并在关单评论里说明。需要独立成一条任务的，才进下面三档——worker 只报告问题与建议档位，由编排者分档、建单、加边和纳入。

三档处理：

| 它挡住了谁 | 判据 | 处置 | 纳入本轮 |
| --- | --- | --- | --- |
| 当前任务 | 不做它，当前任务就无法验收通过；或者它是当前改动带出的安全、数据正确性问题 | 给当前任务加 `depends` 边指向它；当前任务已有的改动按「移出工作集」第 1 条另存，不 `hold`；先做它，当前任务回到候选后从另存的分支接着做 | 是 |
| 本轮交付 | 当前任务能验收通过，但缺了它，对某个入口已冻结的交付就不完整（交付怎么界定见「2. 工作集」） | 能指出具体受阻任务时，给那条任务加 `depends` 边；指不出时不给目标或规则硬套依赖边，在台账里记「扩张：挡住 <入口> 的本轮交付」 | 是 |
| 不阻塞本轮交付 | — | 不建依赖边 | 否，记进「快照外（只报告）」 |

第二档不打断当前任务：先记进快照、更新台账，按「4. 执行顺序」重新取候选即可。

已经存在、但不是本轮创建的任务被发现时，同样按上表判断，纳入时来源记 `扩张·既有`。

上限的计法，按「这次操作会不会超过」判断，恰好用完还算允许：

- 新建：每建一条都用「新建任务上限」的额度。触顶后不再建单，把拟建的条目记下来，收尾时一并报告。
- 纳入：纳入一项要同时看「工作集上限」；带依赖边沿 `depends` 展开时还要看「依赖深度上限」。额度不足就停这一项纳入，不因此压缩已经定下的交付，把缺口交给用户。
- 任一上限触顶都停止对应扩张，把清单交给用户，不要自行缩小范围。

## 8. 收尾

1. **对账**：以台账里的快照行为主表，逐条读最新状态——台账项一条都不删，重取结果也不替它增删。
   - 快照内仍未关闭、未移出、且 `rank.blocked` 为 `false` 的，继续执行。
   - 移出的与被挡住的，不再执行，列进汇总。
   - 重走闭包（任务模式）或重取子树（目标模式）只用来**发现新增项**：落在台账之外的，一律记进「快照外（只报告）」，不因为这次查询就纳入。无边扩张的任务可能不在任何重取结果里，只有台账能证明它在快照内。
   - 哪些算快照内、哪些算快照外，以台账为准：目标模式重取子树时，已记进快照的本轮新建任务仍在快照内，台账之外的查询新增项才只报告。
2. **整体代码审查**：覆盖本轮全部改动，优先复用符合独立性与「审查模型」要求的 reviewer。逐任务审查检查实现正确性和边界，整体审查重点检查跨任务交互、共享状态、公共契约、集成行为及交付缺口；已有有效结论作为输入，风险涉及其他部分时仍须展开检查。仅一条任务、最终受审输入未变且已通过的独立审查覆盖全部改动时，记录其同时覆盖整体审查，不重复派发。执行位置为「新建 worktree」时，审查通过后合回主干；合入改变了受验输入时按「验证证据复用」重验，再清理 worktree。并行度大于 1 时合回主干的是集成分支，主干在此之前不动。
3. **补评论**：按「进展评论」补充尚未记录的结论变化。
4. **复查关闭方式**：逐条看 `resolution`。不是 `completed` 的，在报告里列出并写明原因。
5. **回填 KR**（仅目标模式）：覆盖入口目标及其子树里未归档的目标。
   - 只回填手动型 KR，且只填本轮工作能直接测出的读数。测不出的，列进报告交给用户。
   - `mode` 为 `task` 的 KR 由任务推导，不要写。
6. **每个入口收一次尾**。总结评论的复用与补充按「进展评论」执行。对每个入口分别记「本轮交付是否完成」和「实体是否关闭」，两者不是一回事：
   - **任务入口**：自身验收通过、且闭包已清空（`depends` 出边全部 `done` 为 `true`）、自身未被移出时，确认总结评论已记录后关闭它。评论里写明哪些前置以 `dropped` 或 `duplicate` 关闭。任一条不满足就不关闭，在报告里写明原因：某个上限触顶、入口或其前置被移出工作集或暂停中，或用户叫停。
   - **目标入口**：在目标上发评论，写明回填的读数、剩余未做的任务、快照外新出现的任务。不关闭、不归档目标。
   - **规则入口**：规则本身不是实体，不向规则发评论、也不关闭规则；评论与关闭落在它解析出的那些入口任务上，按任务入口逐条处理，规则整体结果写进汇总。
   - 逐条检查台账里所有挡住本轮交付、却还没解决的事项——包括已纳入但没做完的扩张项，以及因上限没纳入、记在「快照外」的项。有未解决项时，即使入口任务已满足关闭条件，这条入口的**本轮交付也不算完成**；报告里单列，不要把「入口任务关闭」说成本轮交付完成。
7. **给用户一份跨入口汇总**，包括：
   - 每个入口的两项结局：本轮交付完成没有、实体关闭没有，以及没完成/没关闭的原因；
   - 本轮扩张纳入的任务：挡住了哪条交付、为什么纳入、完成了没有；
   - 多个入口共用的任务；
   - 移出工作集的任务：缺什么、谁能补；补齐后 `resume`，再以同一入口重跑；
   - 未纳入（暂停中）的任务，附原有的暂停理由；
   - 被挡住的任务，及挡住它的是哪一条；
   - 快照外新出现的任务；
   - 拟建但没建的任务。
8. **删除台账**：先确认台账里的每一条都已写进评论或汇总，再删。
