# @coda-console/composer 中文文档

规范地址：https://npmcn.com/package/%40coda-console/composer/

版本：5\.1\.0
npm 元数据更新时间：2026-11-10T04:29:44.307Z
中文译文更新时间：2026-11-10T05:28:00.994Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40coda-console/composer
原文对照：https://npmcn.com/package/%40coda-console/composer/?lang=original
项目主页：https://github.com/coda-console/coda-plugins#readme
源码仓库：https://github.com/coda-console/coda-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：132 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2026-10-31T15:23:58.850Z
- 最新版本发布：2026-11-10T04:29:43.995Z
- 近 30 天下载量：4444（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

交接、子会话、! 命令、Ultra 与循环

## 安装

```sh
npm install @coda-console/composer
```

也可以使用：`pnpm add @coda-console/composer`、`yarn add @coda-console/composer`、`bun add @coda-console/composer`

## README

# 输入框模式

`@coda-console/composer` 把输入框的五种模式放在同一个插件里，插件 ID 为 `composer`；另带入口流程「开工」（`kickoff`）与两个开发流程：监督开发（`develop`）与需求交付（`deliver`）。开发流程由你在会话里开启，或由 Agent 发起「开工」后你在开工卡上确认。

| 模式 | 入口 | 用途 |
| --- | --- | --- |
| 交接到新会话 | `/handoff` | 新会话承接当前上下文，共享工作目录；原会话保留，可继续使用。 |
| 子会话 | `/subagent` | 从任意会话启动子会话，承接近期上下文并沿用工作目录；可选完成后回报父会话或你。 |
| 执行命令 | `!` | 在会话工作目录执行命令，命令与结果作为消息发给 Agent；也可在新任务输入框使用。 |
| Ultra | `/ultra` | 主 Agent 定任务、做决定、审查，不改代码的调研与核实按任务交给名单里的执行者；也可在新任务输入框使用。 |
| 循环 | `/loop` | 按周期把同一句话再发给 Agent，每轮做完才开始计时，7 天后自动结束；仅用于已有会话。 |

五个模式可同时开启，模式 ID 不变。Ultra 开启时，从这个输入框创建的新会话（包括子会话、交接和新任务）继承 Ultra 及当前子 Agent 名单，各自独立保留模式；关闭来源的 Ultra 不会关闭已创建会话的 Ultra。工具栏始终选择输入框自己的执行者；交接与子会话的参数另有可选 Agent，留空沿用输入框执行者。子会话也能创建自己的子会话。

3.0.0 按 [Coda #2063 的接口约定](https://github.com/coda-console/coda/issues/2063) 改为 `submissions` 协议参与者，依赖该 issue 第 2 步的后端支持，以及 [Coda #2085](https://github.com/coda-console/coda/pull/2085) 的新会话模式继承与实际投递计数，不能用于旧版回调宿主。交接、子会话和循环声明 `once: true`，发出的一条被收下后退出该模式；Ultra 保持开启，执行命令的触发词仍是 `!`。

4.0.0 跟随 [Coda #2176](https://github.com/coda-console/coda/issues/2176) 的协议命名：输入的观察与发出的一条的参与者改用 `coda/composer@1`、`coda/submission@1`，需要支持协议名的新版 Coda，不能用于旧版。本插件不定义也不实现协议，只作为参与者登记补充。同一版本还包含 main 上 3.10.0、3.10.1 的改动（[#197](https://github.com/coda-console/coda-plugins/pull/197)、[#199](https://github.com/coda-console/coda-plugins/pull/199)）：develop 的合并前检查挪到批准卡之前，批准、放行后直接合并；合并冲突退回执行者；流程定义去掉了 `coda:handback`，跟上 Coda 的「流程任务每层一轮」。

插件只返回补充，不改正文、附件、引用或输入框的执行者。多个模式的补充由 Coda 合并，`tell` 是字符串数组，按列表追加后随这条发送到每个收到它的会话；只要有一项 `divert: true` 就不发给默认去向，各模式追加的去向仍分别执行。

| 模式 | 发出的一条的补充 |
| --- | --- |
| 交接 | `divert: true`，追加 `thread` 去向，带 `handoffSource`、可选 `agent`、`open: true` |
| 子会话 | `divert: true`，追加 `thread` 去向，带 `handoffSource`、`parentThreadId`、`replyTo`、可选 `agent`、`open: true` |
| Ultra | 首条、参数变化后的首条，以及创建新会话时返回完整开启说明；此后 `sent > 0 && sent % 10 === 0` 时返回仍在说明，其余返回 `null` |
| 循环 | `divert: true`，追加 `loop` 去向，带 `thread`、`every` |
| `!` | `divert: true`，会话中追加 `message` 去向，带 `thread`、`run: true`；新任务中追加 `thread` 去向，带 `run: true`、`open: true` |

新会话去向明确跳转，客户端按每项 `open` 执行。Coda 将非一次性、非触发式且适用于会话的模式和参数写入新会话输入框；各会话只为自己实际收到的模式消息计数，转发到新会话不增加来源的 `sent`。空 Agent 不写入目标，交由 Coda 沿用 `spec.agent`（包括 settings）。

## 循环用法

在已有会话的输入框里打 `/loop`，填写每轮要做的事，选择周期后点「开始循环」。周期默认 30 分钟，可选 5 分钟、10 分钟、15 分钟、30 分钟、1 小时、2 小时、3 小时、6 小时、12 小时或 1 天。

这条消息就是第 1 轮；Coda 收下后创建循环，输入框随即退出循环模式。每轮做完才开始计算下一个周期，不叠着跑；7 天后自动结束，也可提前停止，归档会话同样结束循环。计时与重发由 Coda 后端负责，会话进程被回收后仍会按时恢复。

循环的计时行为沿用 [Coda #2051](https://github.com/coda-console/coda/pull/2051)，3.0.0 通过上述 `loop` 去向提交。

## Ultra 模板设置改名

Ultra 的模板设置由 `ultra.templates` 改为 **`composer.templates`**，模板的数据结构不变。清单的预设只引用新设置名，由 Coda 按输入框所在目录读取。 旧 Ultra 包暂时保留，旧设置迁移和卸载旧插件由 [Coda issue #2050](https://github.com/coda-console/coda/issues/2050) 的第 4 步处理，本插件不自行迁移。

## Ultra 用法

在会话或新任务输入框打 `/ultra`，点模式条选择执行者名单；点 × 退出。单独开启时消息照常发给当前会话，与其他模式一起开启时按各模式的去向发送。 Ultra 只管派活：主 Agent 定任务、处理困难决策、审查别人交回的东西；不改代码的调研、排查和核实用 Coda 的 `spawn` 交给名单里的执行者，按任务挑。 它不规定代码怎么改、走不走开发流程：开发流程由你在会话里开启，或由 Agent 发起「开工」后你在开工卡上确认（见下文），它的规则写在交给主 Agent 的任务里。

`composer.templates` 是执行者模板，一行「模板名、Agent、什么时候派给它」。同一模板名的行是一组，进入时填第一组；默认没有模板。 Ultra 参数仍保存为 `subagents`，预设引用 `{ "from": "composer.templates", "by": "template" }`，选择预设只填入名单一次，之后可修改。 `spawn` 按任务从名单选执行者，传 `agent`、`model`、`effort`、`mode`、`options`；只有名单为空或没有条目覆盖这项工作时，才用当前会话的 Agent 和模型。

`ultra.mjs` 在首条、改参数后的首条、创建新会话时给完整说明，之后每收下 10 条再提醒一次。 并发已满就等名额；spawn 不可用就报告阻塞，不改用原生子 Agent。用户的明确指令优先。 5.0.0 起 Ultra 不再要求「所有代码修改都通过 develop」，也不再讲 develop、deliver 的用法；两个流程改为由你在会话里开启，或由 Agent 发起「开工」后你在开工卡上确认，develop 的执行者从 `agent`、`model`、`effort`、`mode` 四个参数换成一个 `executor`（Coda #2303）。需要支持流程参数 `agent` 类型（协议 3.5.0，Coda #2332）、`coda:wake` 与 `note="required"` 的 Coda，不能用于旧版。

插件声明 `activationEvents: ["onStartupFinished"]`，重启后通过 `coda.watch('coda/composer@1', …)` 恢复观察。 Ultra 消失且此前 `sent > 0` 时用 `coda.tell` 告知关闭一次，恢复通常的执行与委派规则；一条都没发过就不说。 名单连同说明超过 Coda 单次告诉 Agent 的 4000 字上限时，缩短名单再发。这些分工是提示词约束，不在运行时禁用工具。

## 开工

Agent 要把改动合进默认分支时，先发起「开工」（`kickoff`），由你在卡上决定走哪条开发流程。它不声明 `coda:kind`：只是入口，不是一种开发实现。Agent 用 `workflow_run` 发起，传功能名 `title`、目标与范围 `goal`，以及建议的做法 `way`（`simple` 或 `develop`，默认 `develop`）；也可以带 `devices`、`device`、`executor`、`branch`、`base`，默认值与对应的开发流程相同。

| 输入 | 用途 |
| --- | --- |
| `title` | 功能名，必填，也是 PR 标题 |
| `goal` | 目标、范围与完成标准，必填，写成可以照着做的完整描述 |
| `way` | Agent 建议的做法：`simple`（简易开发）或 `develop`（监督开发），默认 `develop` |
| `devices` | 「设备验收」，默认关；卡上两个开工选项的勾选默认取它 |
| `device` | 「验收设备」，如 `duo-testbed`，默认空；验收期间独占它 |
| `executor` | 监督开发的「执行者」，一组 Agent 选择，默认取发起会话的 |
| `branch` | 简易开发提交改动的「分支」，默认是会话所在的分支（`defaultFrom="session.branch"`） |
| `base` | 「目标分支」，留空用仓库默认分支 |

「开工」卡上写功能名、目标与范围、Agent 建议的做法，以及设备验收的建议；选项是「开工：简易开发」「开工：监督开发」和「先别」。两个开工选项各带勾选项「设备验收」，默认取 `devices`；卡上的附言可选。

-   选简易开发：调用 `simple`，传 `branch`、按勾选得到的 `devices`、`device`、`base`。
-   选监督开发：调用 `develop`，传 `title`、`task`（就是 `goal`；你在卡上写了附言时，在 `goal` 后另起一行「用户开工时补充：」接上附言）、按勾选得到的 `devices`、`device`、`executor`、`base`。
-   选「先别」：不调用任何流程，直接结束，结束输出说明用户没有开工；有附言就一并带上。

被调用流程正常结束时的 `pr`、`commit` 原样成为「开工」的输出，`notify` 用来决定是否叫醒发起会话：结束时是否叫醒跟随被调用流程批准卡上「全部完成后通知 Agent」的勾选；「暂不合并」和「先别」都会叫醒。

## 监督开发

和主 Agent 把需求聊清楚后，在会话的流程里开启「监督开发」（`develop`），或让 Agent 发起「开工」并在开工卡上选「开工：监督开发」。它是手动流程，不订阅 PR 事件，也不依赖 review 插件；使用时停用旧的 PR 生命周期，避免同一个 PR 被两条流程处理。

| 输入 | 用途 |
| --- | --- |
| `title`、`task` | 功能名和第一项自足任务（背景、范围与验收要求），默认空。你开启时留空，由主 Agent 写；主 Agent 为需求交付发起成员时传这两项 |
| `devices` | 布尔值「设备验收」，默认关；改了客户端、要在 Mac 或 iPhone 上验收时打开 |
| `device` | 可选文本「验收设备」，如 `duo-testbed`，默认空；开启设备验收且非空时，从安装前到验收结束独占这台设备；留空不占设备 |
| `delivery` | 字符串「所属需求」，填需求运行的 ID；默认空，为独立交付 |
| `executor` | 「执行者」，一组 Agent 选择（Agent、模型、强度、模式与其他选项，流程参数的 `agent` 类型），表单里用 App 的 Agent 选择器；默认取发起会话的，跨目录发起取不到时也用发起会话的。没选的模型、强度、模式用执行者的默认值，其他选项逐个传给 `coda-agent --option` |
| `base` | 留空从 GitHub 读取仓库默认分支 |

0.  没有第一项任务时（你直接在会话里开启的），先交主 Agent「写第一项任务」：这张任务不叫醒它（`coda:wake="false"`），随你在会话里的下一条消息告诉它，说明你开启了监督开发、它要做什么。Agent 经「开工」发起时，`title` 和 `task` 已由开工卡交过来，不经过这张任务。主 Agent 答复时备注必填：第一行是功能名（也是 PR 标题），空一行后是第一项任务；缺一样回到这张任务。
1.  从远端 base 最新提交创建 `lane/<运行 ID>` 并推送，分支名只用 ASCII，不同功能运行各有自己的泳道；PR 标题仍使用功能名。
2.  执行步骤用 `coda-agent --commit <泳道 head> --json` 开执行会话。固定说明要求遵守 AGENTS.md，只做本项、在当前分支提交、不推送、不写防御性或冗余代码、不顺手重构；只跑与改动直接相关的快检查，流程会在审查前自己跑项目检查，构建、全套和界面检查不重复跑，不必再用 run-held 跑整套编译；并报告实际验证。
3.  项目检查通过后，主 Agent 人工任务给出检查运行链接与结果、执行者回答、会话、分支、head 和 `git diff <泳道>...<head>`。退回意见或下一项任务写备注，必填；缺少时返回审查卡。「退回修改」用 `--continue <会话>`；通过后 `git merge --ff-only` 合入泳道并推送，不能快进就失败。「再派一项」从最新泳道提交开新会话。「通过，可以验收」的备注同样必填，是写给用户的改动汇报（做了什么、需要你知道的风险或没做的），每次通过都以最新一份为准。
4.  `devices=false` 时，「通过，可以验收」直接进入开 PR 和检查，不产生安装与设备验收任务。`devices=true` 时，主 Agent 用 `workflow_run` 带泳道的精确 `commit` 只安装改到的那一端（`mac-preview-install`、`ios-preview-install`），发起的安装都成功后答复「已装好」；需要先修改（例如合入最新 `origin/<base>`）时选「回到审查」，必须在备注中写具体意见，缺少时返回安装卡。意见作为待处理反馈交回主 Agent，再用「退回修改」继续最近的执行会话。随后用户答复「设备验收」，「不行」必须附言（写意见或附截图，`note="required"`），意见与截图路径交回主 Agent 审查，修好后重新安装与验收。
5.  设备验收通过或未开启设备验收时，开泳道到 base 的 PR，正文最上面是主 Agent 最近一次「通过，可以验收」写的改动汇报，随后是按区域统计的改动块（见下文「改动区域」），两者合称汇总，批准卡和待交付卡只贴这份汇总；其后的「执行记录」折叠区按「第 N 项」列出各次审查通过的任务：任务原文放在「任务」折叠区，随后列出执行者回答和提交。项目检查已在审查前对执行者 head 执行；本 develop 记录的通过提交与 PR head 相同时复用，不再调用项目检查。随后在 PR head 上跑一次 `kind=premerge`（合并前检查，放每个版本都跑嫌贵的验证），失败回审查，修好后更新 PR 重新检查；通过后核对 PR 的 `headRefOid` 与本轮提交一致，每 10 秒查询一次检查，最多等待 120 秒登记；出现检查后用 `gh pr checks <PR> --watch` 等全部结束，并再次核对 head。连续 120 秒为空才按无 CI 通过，日志明确记录这一判断。选择有界等待是为了兼容 GitHub Actions 和外部 CI，不猜测 workflow 的事件、路径或分支过滤；超过窗口才登记的 CI 不在此判断的保证范围内。审查前项目检查失败时，前两次自动继续同一执行会话，第三次交回主 Agent 并附三次记录；当前内核只能给父运行链接，由执行者用 `workflow_status` 读取失败流程、步骤和日志。GitHub 检查失败仍交回主 Agent。修好后更新同一个 PR 并重跑检查。项目检查、合并前检查和 GitHub 检查都通过后才出批准卡。
6.  用户「批准合并」卡提供「部署」「发布预览版」「发布正式版」，各自仅在项目有 `kind=deploy`、`kind=preview`、`kind=release` 的流程时显示，默认都不勾；选中后运行对应类别的全部流程。「合并」另有「全部完成后通知 Agent」，默认勾选。「暂不合并」必须附言，原因随答复告诉主 Agent。批准后直接合并，不再跑检查。
7.  合并前查询 PR 状态：已合并且 head 与本次运行记录一致时，直接输出原合并提交；已合并但 head 不一致或已关闭未合并时明确报错。合并命令失败后查询一次 PR，仅在仍 OPEN 且 `mergeable=CONFLICTING` 时，带目标分支及修复要求回到主 Agent 审查，由主 Agent「退回修改」让原执行者 fetch 并合入最新目标分支、解冲突、顺延撞号的迁移版本并跑相关测试；流程不自动合入或解冲突。修好后在同一运行中重新走项目检查、审查、更新 PR、合并前检查和 GitHub 检查，再出新的批准卡（归属需求则回到待交付）；部署、发布选项以新卡为准，旧批准不沿用。其余合并失败保留原退出码，不依赖错误文案判断冲突；head 由 `--match-head-commit` 校验。其余未合并情况用 `gh pr merge --repo <host/owner/repo> --squash --match-head-commit <head> --delete-branch` 合并；仓库从 PR URL 取得，gh 只删除远端泳道分支、不操作本地分支，支持分离 HEAD 检出，也兼容 GitHub 合并后自动删除分支。成功后读取合并提交，再在合并提交上按勾选依次运行 deploy、preview、release，每类一次；预览和正式发布均传所选发布说明 `notes`；正式发布另传 `publish: "true"`。

以上安装、验收和批准路径适用于 `delivery` 留空的独立交付。`delivery` 非空时，「通过，可以验收」直接开或更新 PR，跳过安装和设备验收，不受 `devices` 影响。项目检查、合并前检查及 GitHub 检查通过后，进入给主 Agent 的「待交付」任务，不出用户批准卡。任务列出所属需求、PR、head、泳道和各次审查通过的汇总：

-   「退回修改」备注必填，缺少则返回待交付；意见作为待处理反馈交回主 Agent 审查，再退给最近的执行会话。修好后经审查、更新同一 PR、重跑检查，再回到待交付。
-   「放行合并」由主 Agent 按需求运行的顺序选择，随后 squash 合并（合并前检查已在待交付前跑过）；合并成功输出合并提交并结束，仍通知发起会话，不部署。

所属需求通过主 Agent 在各运行的人工任务里协调，不直接向其他运行发消息，也不依赖跨仓库原生子运行。

独立交付的用户设备验收通过后，流程用 `tell-session` 告诉发起运行的会话功能名，以及接下来开 PR、跑检查；验收不通过的备注已随审查任务交回，不重复通知。用户答复批准卡后直接继续流程，不再单独通知选择。3.6.0 起，独立交付的「全部完成后通知 Agent」控制最外层结束事件的 `coda:notify`：取消勾选后，合并及所选部署、发布全部成功时不叫醒发起会话，只在下一轮顺带告知结果；失败仍叫醒。「暂不合并」仍按原规则叫醒，交由主 Agent 跟进。依赖 Coda #2107 的结束通知支持。

每步独立工作区，进度与已通过的改动暂存于 `$CODA_ARTIFACTS/develop.json`；长期结果在泳道提交与 PR 中。执行者的分支/head 必须在本机仓库可读；`coda-agent --json` 标准输出是一行 `{session, branch, head, answer}`，`--continue` 保留同一会话并遵守首次的退出码约定。需要支持这两个接口的 Coda 版本。

### 改动区域

PR 汇总的改动块统计目标分支最新提交与泳道 head 的三点 diff（与 GitHub PR 的 Files changed 一致），按区域列出文件数和增删行数，区域按增删总行数从多到少排。改名按新路径归类，二进制文件计入文件数、行数记 0。

区域由 head 上的 `.coda/areas.json` 声明，格式为 `{ "区域名": ["路径前缀", ...] }`，前缀是普通字符串前缀，如 `iOS/`、`Sources/CodaCore/`、`AGENTS.md`。一个文件归入最长匹配前缀所在的区域；都不匹配时归到它的顶层目录名，根目录下的文件归「根目录」。没有这个文件时全部按顶层目录归类；文件存在但 JSON 写坏时开 PR 步骤直接失败。

### 审查前检查与当前内核限制

执行者交回后，gate 先把 head 推送到本次运行独占的 `composer-check/<运行 ID>` 分支，成功后才输出 head 并调用项目检查；推送失败停在 gate，日志保留 Git 的具体原因。此时 GitHub 已有提交，检查可以写提交状态，PR 复用同一 head 时也能看到这些状态。临时分支每次 gate 更新，不占用只存审查通过提交的泳道；审查通过并推入泳道后立即删除。推送或清理失败留在原步骤，沿用流程原有的恢复行为；取消或放弃运行可能留下检查分支，不另加全局收尾机制。选择每次运行一个分支，是为了隔离并发运行，且不用累计执行者分支。

流程自己用执行者 head 跑 PR 同一组 `coda:kind="check"`，全部成功后才进入正常审查。审查材料列出检查流程、状态和运行链接；没有声明检查时明确显示没有项目检查。执行者只需跑与改动直接相关的快检查，不必再用 run-held 跑整套编译。通过会清零连续失败次数；新任务重新计数。

用户只需在批准卡勾选发布类别。develop 和 deliver 在勾选发布但备注为空时，进入交给主 Agent 的「写发布说明」任务，列出所选类别，由主 Agent 按上次公开版本以来合并的改动写面向用户的说明；备注必填，空白时返回同一 Agent 任务。用户自己填写了备注则直接使用，不再要求主 Agent 编写。说明随 `notes` 传给两类发布流程，审查意见不作为发布说明。

PR 位于同一 develop 运行，按 head 复用已通过的项目检查即可。iOS 编译由项目检查覆盖，composer 自己不构建预览包。

独立交付开了设备验收（`devices=true`、`delivery` 留空）时，gate 推出执行者的 head 后，与项目检查并行调用项目的 `coda:kind="prebuild"`（预编）流程，传同一个 head，填了 `device` 时另传 `device`。它为随后验收要装的客户端先编好，审查和检查不等它；它失败只留在调用记录里，不退回、不挡验收，安装流程到时照常自己构建。每次 gate 调用一次，退回修改后的新 head 另行预编。项目没有这类流程时这一步立即结束。

仍缺少的内核能力只有失败详情输出：错误边界后需要可读取的子运行 ID、失败步骤、错误及日志尾，当前失败批次没有这些 outputs。自动续作目前附父运行和提交，要求执行者读取 `workflow_status`，尚不能直接附日志尾。

填写 `device` 且开启设备验收时，安装前用 `hold-group` 占用 `device:<设备名>`（容量 1），状态显示「等验收设备 <设备名>」。引擎按组归属在整个空间排队；composer 不依赖 testbed 插件。安装与验收共用这一段占用，发起 `ios-preview-install` 时除精确 `commit` 外还传同一个 `device`，安装运行借用本段设备，不另排队。通过、退回审查或确认、取消并收尾后释放；再次进入重新排队。缺少必填意见时仍留在本段补填。未填设备名时沿用原安装与验收行为，不传设备参数、不占设备。

## 需求交付流程

一个需求要多个 `develop` 一起验收、一起批准时才用它；只有一个 `develop` 的需求不挂需求，直接走到合并。在**交付并部署这个需求的项目**的会话里开启「需求交付」（`deliver`）：`title`（需求名）、`goal`（目标与完成标准）默认空，`devices`（是否设备验收）默认关，可选 `device`（验收设备名，如 `duo-testbed`，默认空），与 develop 的设备占用规则相同。

0.  没有目标时（你开启的），先交主 Agent「写需求」，同样不叫醒它、随下一条消息告诉它。主 Agent 答复时备注必填：第一行需求名，空一行后是目标与完成标准。任务里写明之后怎么做：为每个能独立交付的功能，在它改动的仓库用 `workflow_run` 发起 `develop`，传 `title`、`task`、`delivery=<本运行 ID>`、`devices=false`，跨仓库用 `project`；各功能检查通过后停在「待交付」。
    
1.  主 Agent 在「确认达标」选择「开始交付」，备注每行一个成员 PR URL，按合并顺序排列，被依赖的仓库在前。流程记录各 PR 的 URL、head、分支及 base；选择「放弃」结束。
    
2.  开启设备验收时，以最新 `origin/<base>` 创建 `delivery/<运行 ID>`（分支名只用 ASCII），按顺序 `git merge --no-ff` 仅合入本仓库成员的已记录 head 并推送。集成失败经错误边界回到确认，合并冲突的具体 Git 输出作为反馈。新一轮从最新 base 重新集成并替换本运行的预览分支。
    
3.  主 Agent 用集成提交只安装改到的那一端（`mac-preview-install`、`ios-preview-install`），发起的安装都成功后答「已装好」；「回到确认」须附原因。用户统一设备验收一次，「不行」须附意见并回到确认。主 Agent 在相关成员的「待交付」退回修改，改好并重新检查后再集成、安装、验收。`devices=false` 跳过集成、安装及设备验收。
    
4.  主 Agent 写约 15 行以内的交付汇报，备注作为批准卡正文：交付名、用户能感知的 3～5 条变化、结构变化（无则写「无」）、设备与检查结论、部署后真实环境验证计划、风险与未做事项（没有可省略）、PR 链接。不放执行者原文、测试数量、文件清单或代码。
    
5.  用户「批准交付」卡显示汇报和全部成员 PR；「批准合并」提供「部署」「发布预览版」「发布正式版」，各自仅在项目有 `kind=deploy`、`kind=preview`、`kind=release` 的流程时显示，默认都不勾。「暂不合并」必须附言（原因）并返回确认；设备验收的「不行」同样必须附言，可以只附截图，路径随反馈交回主 Agent。批准后，若勾选发布但备注为空，先交主 Agent「写发布说明」，再进入「放行合并」；否则直接进入「放行合并」。由任务叫醒发起会话，不再单独通知选择。
    
6.  主 Agent 按顺序放行成员，被依赖的仓库在前：先放行提供被钉版本的包的成员的「待交付」，等合并并发布新版本；再退回钉这些包的仓库成员，让执行者更新钉定的包版本，经审查、检查回到待交付；最后放行依赖方成员。全部合并后备注写本项目最后一个合并提交，没有本仓库成员时写本项目当前目标分支提交。
    
7.  在该合并提交上按勾选依次调用 `run-workflows` 的 deploy、preview、release 三类，每类一次；每类调用项目的全部对应流程，预览和正式发布均传所选发布说明 `notes`；正式发布另传 `publish: "true"`。随后主 Agent 按 `goal` 走真实环境验证，选「通过」或附具体意见选「有问题」，用 `tell-session` 告知发起会话后结束。未勾部署时仍验证当前真实环境，备注说明未部署造成的未验证部分。
    

必填备注缺少时回原任务补填。成员快照、轮次和反馈保存在 `$CODA_ARTIFACTS/deliver.json`；运行之间只通过主 Agent 答复各自人工任务协调，不直接发消息。此流程不改变成员 develop 的审查、检查与合并路径。

测试在 `test/plugins/composer/`，用临时 Git 仓库及假的 coda-agent、gh 验证，不发真实 PR 或部署。PR 复用测试将实际脚本输出按引擎语义转换（`"true"` / `"false"` 转为布尔值），再用同版本 FEEL 求值真实 BPMN 网关条件，覆盖同提交复用、记录缺失与提交变化；check 包仅校验流程方言，此测试不运行完整 BPMN 引擎。设备验收段测试覆盖有无设备时的分流、占用范围、退出和重入路径。 委派文案的基础采用 [oh-my-claudecode 的委派规则](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/82602887b71a3984e040fac2839ec8d27a7c67b6/docs/CLAUDE.md#L16)，适配 Coda 开发流程与只读 spawn。版权与 MIT 许可见 [THIRD\_PARTY\_NOTICES.md](https://npmcn.com/package/%40coda-console/composer/THIRD_PARTY_NOTICES.md)。

## 常见问题

### @coda-console/composer 是什么？

交接、子会话、\! 命令、Ultra 与循环

### 如何安装 @coda-console/composer？

在项目目录运行 npm install @coda-console/composer，或使用 pnpm add / yarn add / bun add。

### @coda-console/composer 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/coda-console\_\_composer 是否存在。

### @coda-console/composer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @coda-console/composer 可以商用吗？

@coda-console/composer 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @coda-console/composer 的下载量有多少？

根据 npm 官方下载统计，@coda-console/composer 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,444 次，日均约 148 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @coda-console/composer 还在维护吗？

最新版本 5\.1\.0 发布于 2026/11/10（今天）；至今共发布 27 个版本，其中过去 12 个月发布了 27 个；首次发布于 2026/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。