EcoPaste 背后的 Trellis 多智能体协作运行时：`trellis channel` 命令权威参考与实战指南

• 桌面应用
• 开发工具

导读

trellis channel是 Trellis 工作流中负责多智能体协作的本地运行时：多个 Agent（claude / codex）通过一份持久化事件日志events.jsonl进行通信、调度、中断与审计。在 EcoPaste 这类以 Trellis 管理的项目中（见 AGENTS.md 中的 Trellis 指令块），任务分阶段进入.trellis/tasks/，实现/检查类工作常需派生 worker 智能体并跨智能体评审。本文以仓库内权威命令参考 command-reference.md 为主体，结合 SKILL.md、workers.md、forum.md 与 progress-debugging.md，完整梳理每个子命令、每个参数、事件模型与输出约定，读完即可独立完成“创建频道 → 派生 worker → 派发任务 → 等待结果 → 中断/回收”的完整协作闭环。

一、命令总览与全局约定

1.1 顶层语法

所有子命令统一入口为：

trellis channel <subcommand>

官方定位是Multi-agent collaboration runtime—— 通过共享事件日志来生成、协调、中断 worker 智能体。

1.2 两个全局维度：--scope与--type

• --scope project|global：所有子命令默认接受，默认值为project（解析当前 cwd 所属的项目 bucket）。--scope global操作共享的__global__bucket。
  • 关键坑点：全局 board 在项目视角的列表中不可见，除非显式传--scope global（见 SKILL.md Core Rules）。
• --type chat|forum：只在create时设置且不可变，无法事后在 forum 与 chat 之间互相转换。chat 是扁平消息流，forum 是线程化结构。

1.3 定位原则

从 SKILL.md 的 Route By User Intent 表可知，trellis channel不是万能工具：单次静态 review、普通工具调用替代、长期记忆检索都不属于它的职责。它适合“Agent 之间通过持久事件日志对话、以独立进程派生 worker、对进行中的 worker 做中断/调试、在--type forum频道上沉淀反馈”。

二、频道的创建与列举：create/list

2.1create <name>—— 创建频道

trellis channel create <name> [--scope project|global] # 默认: project [--type chat|forum] # 默认: chat [--task <path>] # 关联的 Trellis task 目录 [--project <slug>] [--labels a,b,c] [--description <text>] # 稳定的频道描述 [--context-file <abs-path>] ... # 可重复 [--context-raw <text>] ... # 可重复 [--linked-context-file <abs-path>] # [已废弃别名] [--linked-context-raw <text>] # [已废弃别名] [--cwd <path>] # 记录在 create 事件中 [--by <agent>] # 默认: main [--force] # 覆盖已存在的频道 [--ephemeral] # 从默认列表隐藏，可被清理

行为要点：

• 追加一个create事件；type不可变（forum↔chat 无法互转）。
• --ephemeral频道默认从channel list隐藏，是channel prune --ephemeral的清扫目标。
• --linked-context-*会被折叠进--context-*，使用时会输出废弃提示。

2.2list—— 列举频道

trellis channel list [--scope project|global] [--json] [--project <slug>] # 对 task 字段做子串匹配 [--all] # 包含 ephemeral（带 '*' 后缀） [--all-projects] # 扫描每一个项目 bucket

• 默认 scope 是当前 cwd 的项目；--all-projects扫描所有 bucket。
• 美观模式（pretty）输出NAME WORKERS EVENTS LAST KIND TYPE TASK表，按最近活动排序，页脚提示被隐藏的 ephemeral 数量。
• --json切换为 JSON 数组。
• WORKERS列可用于快速审计某个项目下正在运行的 worker 数量（配合 workers.md 的 OOM guard 审计）。

三、消息通信：send/messages/wait

3.1send <name> [text]—— 追加消息事件

trellis channel send <name> [text] --as <agent> # 必填 — 作者 [--scope project|global] [--to <agents,csv>] # 默认: 广播 [--stdin | --text-file <path>] # body 从 stdin 或文件读取 [--delivery-mode appendOnly|requireKnownWorker|requireRunningWorker]

行为要点：

• 正文优先级：位置参数[text]→--stdin→--text-file。
• --to只有一个条目时存为字符串，多个存为数组；省略即广播。
• --delivery-mode选择定向投递校验：
  • appendOnly（接近默认）——只记录；
  • requireKnownWorker——--to命名的目标必须存在过spawned事件；
  • requireRunningWorker——目标 worker 必须当前存活。
• 输出：追加的事件以一行 JSON 打印到 stdout。

3.2messages <name>—— 查看 / 过滤事件流

trellis channel messages <name> [--scope project|global] [--raw] # 每行一个 JSON 事件 [--follow] # 流式跟进新事件 [--last <N>] # 最近 N 个匹配事件 [--since <seq>] # seq > N [--kind <kind>] # 取 CHANNEL_EVENT_KINDS 之一 [--from <csv>] # 作者过滤 [--to <target>] # 路由目标过滤 [--thread <key>] # 仅 forum [--action <thread-action>] # 仅 forum [--no-progress] # 隐藏 progress 事件

行为要点：

• 自动识别 forum 频道：无过滤时渲染线程看板（thread board）而非事件流；--thread/--action仅限 forum，对 chat 频道使用会报错。
• --kind校验范围是CHANNEL_EVENT_KINDS（单值，不是 CSV——CSV 是wait那一侧的语义）。

3.3wait <name>—— 阻塞等待匹配事件

trellis channel wait <name> --as <agent> # 必填 — self，用于过滤上下文 [--scope project|global] [--timeout <Ns|Nm|Nh|Nms>] # 由 parseDuration 解析 [--from <a,b>] # 作者 CSV [--kind <k1,k2>] # CSV，OR 语义 [--thread <key>] # forum 过滤 [--action <thread-action>] # forum 过滤 [--to <target>] # 默认: 自己的 agent（广播 + 显式给我） [--include-progress] # progress 事件也唤醒 [--all] # 要求每个 --from 都匹配

行为要点：

• 流式输出匹配事件，每行一个 JSON。
• 默认--to过滤是调用者自己的 agent（广播事件仍会匹配——广播 + 显式给我）。
• --all要求--from，且阻塞到列出的每个 agent 都产生匹配事件为止。
• 超时退出码 124，且当--all生效时向 stderr 打印timeout: still waiting on ...。

3.4 完整派发循环（Dispatchers）

结合 workers.md 的典型派发循环，一个可复制的完整流程是：

# 1. 唤醒 worker echo "Run the failing test and report." \ | trellis channel send impl-task --as dispatcher --to codex-impl --stdin \ --delivery-mode requireRunningWorker # 2. 阻塞直到完成 trellis channel wait impl-task --as dispatcher \ --from codex-impl --kind done,error --timeout 30m # 3. 读取最终回答 trellis channel messages impl-task --from codex-impl --last 1 --raw

四、tag vs kind：事件形态到底由谁控制

这是 command-reference.md 中专门辟出一节强调的核心议题，也是对新手最容易产生误解的地方：

v0.6.0 的 channel CLI 中任何地方都没有--tag标志；--kind不是任何--tag标志的遗留别名。

当前源码中的具体模型：

• --kind是唯一的事件类型过滤器，且被约束在 trellis 自己发出的事件白名单（上游源码位于packages/core/src/channel/internal/store/events.ts，属于@mindfoldhq/trellis-core包，不在本仓库内）：create, join, leave, message, thread, context, channel, spawned, killed, respawned, progress, done, error, waiting, awake, undeliverable, interrupt_requested, turn_started, turn_finished, interrupted, supervisor_warning
  • 传入其他值会抛出Invalid --kind '<x>'. Must be one of: …。
• --kind存在于wait（CSV，OR 语义）和messages（单值）。send和run不能发出自定义 kind——每次send写入的都是message事件。
• 回合中途中止 worker不是tag，而是专门的channel interrupt命令，它会追加一对interrupt_requested/interrupted事件，并在 provider 层面中断 worker。

4.1 面向派发者的实操规则

• 用--kind done,turn_finished表示“worker 完成了一个回合”——这是 supervisor 自动触发的系统事件。不要依赖 worker LLM 记得发出任何自定义信号。
• 只在确实需要中途中止行为时，才用trellis channel interrupt命令。
• 不要发明用户侧 tag 作为完成信号：没有--tag过滤器；worker 在最终消息里写自定义字符串只是message事件内的文本，wait无法匹配它。

补充佐证：尽管 SKILL.md 提示 CLI help 中--tag有phase_done/question示例，但那属于帮助文案的历史遗留；其中只有interrupt是带硬编码行为的保留 tag，其余都是不透明的用户标签。依赖 worker 执行send --tag <my_signal>并不可靠——LLM worker 常把 tag 字符串写进正文而不是真正执行 CLI 命令。

4.2 长正文的正确姿势

trellis channel send T --as A --stdin < /tmp/message.md trellis channel send T --as A --text-file /tmp/message.md

SKILL.md 特别强调：不要在位置参数里放长的中英混合文本，统一走--stdin或--text-file。

五、中断与回收：interrupt/kill/rm/prune

5.1interrupt <name> [text]—— 软中断（协作式重定向）

trellis channel interrupt <name> [text] --as <agent> # 必填 — 调用者 --to <agent> # 必填 — 目标 worker [--scope project|global] [--stdin | --text-file <path>]

• 追加一个reason: "user"的interrupt事件和替换指令正文；supervisor 在支持的 provider 上执行 provider 级中断（Claude/interrupt、Codex turn cancel）。
• stdout 打印追加的事件 JSON。
• 下游wait/messages可以用--kind interrupt订阅重定向事件。

典型用法（来自 workers.md）：

echo "Stop refactoring the parser — switch to fixing the failing test in src/foo.ts" \ | trellis channel interrupt impl-task --as dispatcher --to codex-impl --stdin

5.2kill <name>—— 硬中断

trellis channel kill <name> --as <agent> # 必填 — worker agent 名 [--scope project|global] [--force] # 立即 SIGKILL

• 默认路径：SIGTERM → 8 秒宽限 → SIGKILL 升级；需要 SIGKILL 时 CLI 写入killed事件，让日志保持真实。
• 清理pid、worker-pid、config、spawnlock边车文件；保留log、session-id、thread-id用于取证和恢复。
• 配合spawn --resume可构成“杀后恢复”的保证重定向路径（见 workers.md Hard Interrupt 一节）。

5.3rm <name>—— 删除频道

trellis channel rm <name> [--scope project|global]

先杀掉存活 worker，再删除整个频道目录，打印Removed channel '<name>'。

5.4prune—— 批量清理

trellis channel prune [--scope project|global] # 省略: 扫描每个项目 [--all | --empty | --idle <Ns|Nm|Nh|Nd> | --ephemeral] # 互斥 [--yes] # 真正删除（默认是 dry-run） [--dry-run] # 默认 true; 与默认行为冗余 [--keep <names,csv>] # 排除列表

• 过滤标志互斥，否则报错。
• 默认 dry-run；--yes才真正删除。
• 不传--scope时扫描每个项目 bucket（有意的仓库级清理）；传了则限定在该 bucket。
• 无论何种过滤，有存活 worker 的频道始终跳过。
• 输出：每个候选一行name last-ts (reason)，外加最终汇总。

六、Worker 全生命周期：spawn/run/ 守护 / OOM 防护

6.1spawn <name>—— 派生持久 worker

trellis channel spawn <name> [--scope project|global] [--agent <agent-name>] # 加载 .trellis/agents/<name>.md [--provider claude|codex] # 覆盖 agent 文件 [--as <worker-name>] # 默认: agent 名 [--cwd <path>] [--model <id>] [--resume <id>] # 恢复 session/thread id [--timeout <Ns|Nm|Nh>] # 超时自动杀死 [--warn-before <Ns|Nm|Nh>] # supervisor_warning 提前量 # 默认 5m, 0ms 禁用 [--file <path>] ... # glob, 可重复; 注入内容 [--jsonl <path>] ... # Trellis manifest, 可重复 [--by <agent>] # spawn 事件作者 # 默认: TRELLIS_CHANNEL_AS 环境变量或 'main' [--inbox-policy explicitOnly|broadcastAndExplicit] # 默认 explicitOnly [--idle-timeout <Ns|Nm|Nh>] # OOM-guard 空闲 TTL # 默认 5m, 0 禁用 [--max-live-workers <n>] # spawn 时的存活 worker 预算 # 默认 6, 0 禁用

行为要点：

• Provider 会按适配器注册表校验（上游packages/cli/src/commands/channel/adapters/）；当前为claude、codex。
• worker 保持 inbox 空闲，直到首次send --to <worker>被唤醒。
• spawned事件记录pid、provider、agent、files、manifests。
• OOM-guard 优先级：CLI 标志 → 环境变量（TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT、TRELLIS_CHANNEL_MAX_LIVE_WORKERS）→.trellis/config.yaml#channel.worker_guard→ 内置默认值。

6.2 Agent 卡片与上下文注入

--agent <name>解析到.trellis/agents/<name>.md，卡片名须匹配[A-Za-z0-9._-]+。默认安装自带check.md（代码质量评审者）与implement.md（实现 worker）。卡片 frontmatter 的provider、model、as会成为spawn的默认值；markdown 正文作为 worker 的 system-prompt 角色。卡片不会自动附加 task 文件——上下文必须在每次 spawn 时显式注入。

上下文注入有两个标志（workers.md）：

• --file <path>：可重复、支持 glob，每个匹配文件读取后拼入# CONTEXT FILES块。
• --jsonl <path>：Trellis manifest，每行{"file":"<path>","reason":"<why>"}，reason 保留为每个文件内容上方的头注释。

加载器强制限制：单文件 1 MB 硬上限（超限报错）、200 KB 单文件警告到 stderr、500 KB 总装配上下文警告、以及--cwd路径遍历监狱（所有解析路径必须留在--cwd之下）。

一个针对 task 目录派生 check agent 的完整示例：

TASK=.trellis/tasks/05-13-example trellis channel spawn cr-example --agent check --provider codex --as check-cx \ --file "$TASK/prd.md" \ --file "$TASK/design.md" \ --file "$TASK/implement.md" \ --jsonl "$TASK/check.jsonl" \ --cwd "$PWD" --timeout 30m

spawned事件同时记录字面files数组和从--jsonl展开的manifests，审计轨迹能还原 worker 实际看到的内容。

6.3run [name]—— 一次性 worker

trellis channel run [name?] [--agent <name>] [--provider claude|codex] [--as <worker-name>] [--cwd <path>] [--model <id>] [--file <path>] ... # 可重复, glob [--jsonl <path>] ... # 可重复 [--message <text> | --message-file <path> | --stdin] [--timeout <Ns|Nm|Nh>] # 默认 5m

• 一次性语义：省略name时自动生成run-<hex>。
• 创建 ephemeral 频道（createMode=run），派生单个 worker，发送 prompt，等待done，把最终 assistant 文本打印到 stdout，成功即移除频道；失败则保留频道供检查并退出码 1。
• run同样没有--tag标志——完成态靠 supervisor 发出的done事件判定。

6.4 Worker OOM Guard

OOM guard 在每个spawn时运行，按项目 bucket 强制两条策略：

• Idle TTL：清扫最后活动早于阈值（默认5m；0禁用）的 worker。
• Live-worker budget：同 bucket 存活 worker 超过 N（默认6；0禁用）时拒绝新 spawn。

清理通知在 spawn 时写到 stderr；guard 对 ephemeral /channel runworker 一视同仁。审计当前状态用channel list的WORKERS列，或检查~/.trellis/channels/<bucket>/<channel>/下的pid/worker-pid边车文件。

6.5 Inbox 路由双旋钮

• Inbox policy（spawn --inbox-policy）：explicitOnly（默认）只在send --to <worker>或interrupt --to <worker>时唤醒；broadcastAndExplicit也会被广播（无--to的send）唤醒。
• Delivery mode（send --delivery-mode）：appendOnly无论 worker 状态都追加；requireKnownWorker若--to目标从未 spawn 过则失败；requireRunningWorker若目标当前不存活则失败。

更严格的投递模式能在调用方期待存活对等体时防止静默丢消息。

七、Forum 频道：post/forum/thread

Forum 是持久化、话题式的频道，创建时用--type forum，之后不可变。默认阅读路径是forum 摘要 → 单个 thread 时间线 → 当前 context。

7.1post <name> <action>—— 线程操作

trellis channel post <name> <action> --as <agent> # 必填 [--scope project|global] [--thread <key>] # 除 action=opened 外必填 [--title <text>] [--text <text> | --stdin | --text-file <path>] [--description <text>] # 稳定的线程描述 [--status <status>] [--labels a,b] # 替换线程 labels [--assignees a,b] # 替换 assignees [--summary <text>] [--context-file <abs-path>] ... [--context-raw <text>] ... [--linked-context-file <abs-path>] # [已废弃别名] [--linked-context-raw <text>] # [已废弃别名]

• <action>在 CLI 表面是自由文本；惯用值包括opened、comment、status、labels、assignees、summary、processed。
• action=rename会被拒绝——用thread rename。
• --labels/--assignees是替换语义，不是追加。
• 输出：stdout 打印追加的事件 JSON。

7.2forum <name>—— 线程看板

trellis channel forum <name> [--scope project|global] [--status <status>] [--raw]

列出线程（精简状态）。--status按当前线程状态过滤；--raw每个线程一行 JSON。

7.3thread <name> <thread>/thread rename

trellis channel thread <name> <thread-key> [--scope project|global] [--raw] trellis channel thread rename <name> <old-thread> <new-thread> --as <agent> # 必填 [--scope project|global]

• thread <name> <key>展示单个线程时间线：头部<thread> [<status>] <title>，然后是 description / labels / assignees / summary / timeline 行。--raw切换为原始事件。
• thread rename是唯一变更操作；post --action rename被拒绝。

7.4 Forum 使用要点（来自 forum.md）

• --description是持久线程描述（“这个线程是关于什么的”的答案），在opened时设置、重跑post --description可编辑。
• --text/--stdin/--text-file是事件正文——挂在具体时间线条目上的评论或载荷。
• --summary是滚动线程摘要；在status closed上设置 summary 是标记线程已解决的标准做法。
• --thread除opened外的每个 action 都必填（opened实际上也要求——没有匿名线程）。
• 常见用例是内部 changelog：一个全局 forum 频道、每个显著变更一个线程（如release-2026-q1），保持历史可检索。
• 删除纪律：forum 线程是 append-only 协作历史，不要建模单条评论删除或硬删除线程；用status/summary/--labels/thread rename修正状态。

八、Context 与 Title

8.1context add/context delete/context list

trellis channel context add <name> [--as <agent>] # 默认: main [--scope project|global] [--thread <key>] # 线程级而非频道级 [--file <abs-path>] ... # 可重复 [--raw <text>] ... # 可重复 # --file 或 --raw 至少其一 trellis channel context delete <name> [--as <agent>] # 默认: main [--scope project|global] [--thread <key>] [--file <abs-path>] ... [--raw <text>] ... trellis channel context list <name> [--scope project|global] [--thread <key>] [--raw] # 每行一个 JSON 条目

• add/delete追加context事件并打印事件 JSON。
• list投影当前 context 条目；美观输出为file <path>/raw <截断文本>行，空时为(no context)。
• 按值删除：传回当初添加的相同--file或--raw值，而不是按 id；重复该标志一次删除多条。
• --file路径必须是绝对路径，相对路径被拒绝（见 forum.md）。
• Context 不是时间线事件，而是为每个读者单独投影、重放的可持久背景信息；--linked-context-*是废弃别名。

8.2title set <name>/title clear <name>

trellis channel title set <name> --title <text> # 必填 [--as <agent>] # 默认: main [--scope project|global] trellis channel title clear <name> [--as <agent>] # 默认: main [--scope project|global]

• 追加title事件，把稳定的显示标题投影到频道上，不改变存储地址——所有命令继续使用原频道 name。
• 这是纯展示层变更；脚本与工具继续用原始频道名。

九、内部命令（Hidden / Internal）

十、事件模型：白名单与默认可见子集

CHANNEL_EVENT_KINDS（由parseChannelKind强制的白名单）：

create,join,leave,message,thread,context,channel,spawned,killed,respawned,progress,done,error,waiting,awake,undeliverable,interrupt_requested,turn_started,turn_finished,interrupted,supervisor_warning

MEANINGFUL_EVENT_KINDS（wait/messages在未显式给--kind时默认可见的子集）：

create,join,leave,message,thread,context,channel,spawned,killed,respawned,done,error

非 meaningful 的 kind（如progress、waiting、awake、supervisor_warning、turn_*/interrupt*系列）仍会流入 store；通过--kind或--include-progress选择参与。

Forum 频道是事件溯源的；请用 CLI 的 reducer（forum、thread、context list）做状态投影，而不是手工解析events.jsonl。进度事件解读的补充细节见 progress-debugging.md：progress事件形态随action字段变化，但承重字段始终在detail下（detail.text_delta、detail.tool_name、detail.status、detail.action）；detail.text_delta跨事件拼接即可重建模型流式输出。

十一、输出约定与退出码

• 变更类（send、interrupt、post、context add/delete、title set/clear、thread rename）：把追加的事件作为一行 JSON 打印到stdout。
• 流式读取类（wait、messages --follow）：stdout 每行一个 JSON 事件。
• 美观读取类（list、messages、forum、thread、context list）：打印带颜色、补白的表格 / 时间线。
• run：stdout 只打印最终 assistant 文本（方便管道），诊断信息走 stderr。
• 错误：经chalk.red("Error:")走 stderr，退出码1。
• wait超时：专门退出码124（--all生效时 stderr 会点名缺失的 worker）。

诊断纪律（progress-debugging.md）：Pretty 输出面向操作员且可能截断（长 progress delta、工具名/命令行、多行状态、超预算线程标题）；任何“看起来不对”的情况（worker 疑似卡住、进度行断在词中、action 字段出现...）都切到--raw——raw 模式每行一个 JSON，与events.jsonl中的原始形态完全一致，不丢任何内容。绝不要用截断的进度行诊断 worker。排查“存活但沉默”的 worker 时，按顺序检查<worker>.pid/<worker>.worker-pid是否存活、tail -f <worker>.log、以及messages --raw --last 50的末尾事件。

存储布局（每个频道一个目录）：

~/.trellis/channels/ └── <bucket>/ └── <channel-name>/ ├── events.jsonl ├── <channel>.lock ├── <worker>.log ├── <worker>.pid ├── <worker>.worker-pid ├── <worker>.config ├── <worker>.session-id ├── <worker>.thread-id ├── <worker>.inbox-cursor └── <worker>.spawnlock

十二、在 EcoPaste 仓库中的落点

回到本仓库本身：EcoPaste 的 AGENTS.md 中明确写着“This project is managed by Trellis”——工作知识位于.trellis/workflow.md（阶段划分、何时建任务、技能路由）、.trellis/spec/（分层编码规范）、.trellis/workspace/（开发者日志与会话痕迹）、.trellis/tasks/（活跃与归档任务的 PRD、研究资料、jsonl 上下文）。仓库内置的.kiro/目录还提供 trellis-check.json（代码质量检查子代理）等 agent 配置与 hook，其中 check 子代理的职责就是“对照 spec 检查代码变更并自修复”。

因此，当你在本仓库中进行“和 codex/claude 讨论”、“派生 implement/check worker”、“开 issue 板 / changelog forum”、“排查卡住的 channel”等工作时，SKILL.md 提供了意图路由表，而本文所依托的 command-reference.md 是所有“具体命令怎么写”问题的最终答案。结合 workflows.md 的六大协作模式（多轮 brainstorm、implement/check 派发、并行评审、一次性 run、forum 沉淀、接管既有线程），你可以把trellis channel从“一组命令”升级为“一套可重复、可审计、可中断的多智能体研发流水线”。

• 桌面应用
• 开发工具