企业官网建设流程全解析

• 桌面应用

本文是trellis channel子命令体系的权威命令参考，内容以 command-reference.md 为主体骨架，并补充了 SKILL.md 中的路由规则与实战约束。trellis channel是本地多智能体协作运行时（multi-agent collaboration runtime）：通过共享事件日志（durable event log）派生（spawn）、协调（coordinate）、中断（interrupt）worker agent，并支持基于--type forum的持久化议题频道。读完本文，你将掌握每一个子命令的完整参数、默认值、行为语义、事件模型与输出约定，能够在派发-等待、跨智能体评审、论坛议题、worker 调试等真实场景中正确写出可复现的trellis channel命令。

本文所有命令均面向 v0.6.0 的 channel CLI，参数解析与行为与源码packages/cli/src/commands/channel/下的 Commander 接线及各子命令 handler 保持一致。

顶层命令与 scope 模型

trellis channel <subcommand>

每个子命令（除非另有说明）都接受--scope <project|global>：

• project（默认）：解析当前 cwd 所在的项目 bucket；
• global：操作共享的__global__bucket。

scope 的选择必须刻意为之：全局频道在项目列表中是看不见的，除非显式传入--scope global。这也是协作时最常见的踩坑点——"为什么我开的 forum 别人看不到"，多半就是 scope 不一致。

创建与列出频道

create <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-*，使用时会发出弃用提示。新代码一律使用--context-file/--context-raw（SKILL.md 明确要求）。

list

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

行为要点：

• 默认 scope 为当前 cwd 的项目；--all-projects扫描全部 bucket；
• 漂亮模式（pretty mode）打印NAME WORKERS EVENTS LAST KIND TYPE TASK，按最近活跃排序，页脚标注被隐藏的 ephemeral 数量；
• --json切换为 JSON 数组输出。

实战提醒：排查"某个全局频道去哪了"，第一反应应是trellis channel list --scope global --all（这正是 SKILL.md 里列出的 First Commands 之一）。

聊天消息：send / messages / wait

send <name> [text]

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

行为要点：

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

注意：send没有--tag、也没有--kind标志。详见下文 tag-vs-kind。

长正文必须走 stdin 或文件，不要把长文本直接塞进位置参数（尤其混合中英文的文本）：

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

messages <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侧的）。

调试提醒：漂亮的messages输出是"操作员仪表盘"，可能截断 progress；审计场景请用--raw（逐行 JSON）。

wait <name>

trellis channel wait <name> --as <agent> # 必填 — 自身，用于过滤上下文 [--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 ...。

tag-vs-kind —— 事件形态实际上由什么控制

这是 channel CLI 中最容易误解的一个点：v0.6.0 的 channel CLI 中根本没有--tag标志，--kind也不是任何--tag标志的历史别名。

当前源码中的具体模型：

• --kind是唯一的事件类型过滤，且被限制在 trellis 自带发射的白名单（CHANNEL_EVENT_KINDS，定义于packages/core/src/channel/internal/store/events.ts）内，共 21 种：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。

给派发者（dispatcher）的实战规则

• 用--kind done,turn_finished表达"worker 完成了一个回合"——这是 supervisor 自动发射的系统事件，不要依赖 worker LLM 记得发射自定义信号；
• 只有真正想要回合中段中止行为时，才使用trellis channel interrupt命令；
• 不要发明用户侧 tag 作为完成信号：没有--tag过滤器；worker 把自定义字符串写进它的最终消息，那只是message事件里的普通文本，wait无法匹配它。

一句话总结（SKILL.md 也反复强调）：--kind done/--kind turn_finished是唯一可靠的完成信号；CLI help 里提到的phase_done/question之类--tag示例只是不透明的用户标签，除了interrupt这个硬编码保留 tag 外都不构成任何行为。

中断 worker：interrupt <name> [text]

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

行为要点：

• 追加一个interrupt事件，携带reason: "user"和替换指令正文；supervisor 在支持的 provider 上执行 provider 级中断（Claude 的/interrupt、Codex 的 turn cancel）；
• 追加的事件 JSON 打印到 stdout。

这是"channel 卡住了 / worker 无输出"时的标准处置手段（见 progress-debugging.md 的排查路由）。

Workers：spawn / run / kill / rm / prune

spawn <name>

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 防护的空闲 TTL # 默认 5m，0 禁用 [--max-live-workers <n>] # spawn 时的存活 worker 预算 # 默认 6，0 禁用

行为要点：

• provider 会对照适配器注册表校验（packages/cli/src/commands/channel/adapters/）；当前支持claude、codex；
• worker 保持收件箱空闲（inbox-idle），直到第一次send --to <worker>才真正启动干活；
• 记录一个spawned事件，携带pid、provider、agent、files、manifests；
• OOM 防护优先级：CLI 标志 → 环境变量（TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT、TRELLIS_CHANNEL_MAX_LIVE_WORKERS）→.trellis/config.yaml#channel.worker_guard→ 内置默认值。

run [name]

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

行为要点：

• 一次性（one-shot）。省略name时自动生成run-<hex>；
• 创建 ephemeral 频道（createMode=run）、派生出单个 worker、发送 prompt、等待done、把最终 assistant 文本打印到 stdout，成功后移除频道；失败时频道保留以供检查，退出码为 1。

run没有--tag标志。完成检测依赖 supervisor 发射的done事件。

由于run只在 stdout 打印最终 assistant 文本，它天然适合管道（pipe）调用——这是 SKILL.md 协作模式中的"one-shot run"。

kill <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供取证与 resume。

rm <name>

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

行为要点：

• 先杀掉所有存活 worker，然后删除整个频道目录；
• 打印Removed channel '<name>'。

prune

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（有意的、仓库级清理）；带--scope project|global时限定在该 bucket；
• 无论过滤条件如何，存活 worker 的频道总是跳过；
• 输出：每个候选频道一行name last-ts (reason)，外加最终汇总。

Forum 频道：post / forum / thread

post <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] # 替换线程标签 [--assignees a,b] # 替换 assignee [--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是替换语义，不是追加；
• 输出：追加的事件 JSON 到 stdout。

forum <name>

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

行为要点：

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

thread <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 / 时间线行；--raw切换为原始事件；
• thread rename是唯一的变更操作；post --action rename被拒绝。

Forum 频道是事件溯源（event-sourced）的：不要先去解析events.jsonl，直接用forum、thread、messages --thread、context list这些 CLI 归约器做状态投影（这也是 SKILL.md 的硬性规则）。

Context 与 Title

context 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)。

title 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事件，把稳定的显示标题投影到频道上；输出为事件 JSON。

隐藏 / 内部命令

__前缀表明这些是内部实现细节，命令参考明确警告"do not invoke directly"，日常使用中请忽略它们。

事件模型

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 的事件类型（如progress、waiting、awake、supervisor_warning、turn_*/interrupt*系列）仍然会流入 store；需要通过--kind或--include-progress显式选择才能看到。

理解这套分层对派发工作流至关重要：wait默认只匹配 meaningful 子集，因此"等 worker 完成"应显式--kind done,turn_finished；而监控类事件（progress、supervisor_warning、turn_*）需要 opt-in。

输出约定（Output Conventions）

掌握输出约定才能正确消费命令结果、安全地在脚本中管道化：

• 变更类命令（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：只把最终 assistant 文本打印到 stdout（以便调用方管道化）；诊断信息走 stderr；
• 错误：通过chalk.red("Error:")输出到 stderr，退出码1；
• wait超时：退出码专门是 124（这也是为什么派发脚本通常以124区分"仍在等待"与"真正失败"）。

一图流：在实战中如何选择命令

两条贯穿始终的纪律：

1. 完成信号只用系统事件：--kind done,turn_finished（supervisor 自动发射），不要依赖 worker 记得执行send来打自定义标记——LLM worker 经常把 tag 字符串写进散文而不是真的执行命令；
2. 长文本走 stdin /--text-file：不要将长（尤其中英文混合的）文本放进位置 shell 参数；
3. 刻意选择 scope：项目内协作用默认project，跨项目共享用--scope global，并且每次列出时都带着匹配的 scope。

• 桌面应用