★ FEATURED ARTICLE 桌面应用开发工具【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/gh_mirrors/ec/EcoPaste点击查看免费下载本文基于 EcoPaste 仓库内置的 Trellis 技能文档 .agents/skills/trellis-channel/references/workers.md 展开。Trellis channel 是本地多智能体协作运行时而workerWorker/Agent Card是其中以独立子进程形式存在、通过通道事件日志回报结果的执行单元。读完本文你将掌握如何用trellis channel spawn派生 worker、如何用.trellis/agents/*.md卡片定义角色、如何通过--file/--jsonl注入上下文、如何用软中断interrupt与硬中断kill --resume纠正运行中的智能体以及如何配置 Worker OOM 守护和 Inbox 路由最终搭建出完整的「派发—等待—审计」协作循环。一、Worker 是什么通道中的对等子进程在 Trellis 的通道模型中worker 不是普通消息而是注册在通道上的子进程当前支持claude与codex两种 provider。它的工作方式可以用一句话概括A worker is a registered child process attached to a channel; the supervisor forwards inbox messages to it and translates its output back into channel events.也就是说supervisor由spawn派生的channel __supervisor工作进程承担两层翻译职责把发往该 worker 的收件箱消息inbox message转发给子进程把子进程的输出provider 流式结果翻译回通道事件spawned、progress、done、error、killed等。worker 派生后并不会立即干活而是保持inbox-idle收件箱空闲状态直到收到send --to worker的定向消息或在--inbox-policy broadcastAndExplicit模式下收到广播才会被唤醒。这一设计让派发方可以“先 spawn、再编排”随时把任务喂给空闲的 worker。在 EcoPaste 仓库中这一整套协作技能被收纳在 .agents/skills/trellis-channel/ 目录下其中 SKILL.md 是入口索引而 workers.md 正是 worker 体系的权威参考完整的命令级参考见 command-reference.md。二、Spawn派生 worker 的完整命令与参数表最基础的 worker 生命周期是一条四步链路创建通道 → spawn → 发送任务 → 等待完成。官方文档给出的最小示例对应 workers.md如下trellis channel create impl-task --by dispatcher --cwd /path/to/repo trellis channel spawn impl-task --provider codex --as codex-impl --timeout 30m echo Implement the schema for table X per .trellis/.../prd.md \ | trellis channel send impl-task --as dispatcher --to codex-impl --stdin trellis channel wait impl-task --as dispatcher --from codex-impl --kind done --timeout 30mspawn会 fork 一个channel __supervisor工作进程它负责在派生时发出spawned事件在整个生命周期内持续流式输出progress事件最终以done、error或killed三种结局事件收尾。worker 在收到定向消息之前保持收件箱空闲只有当send --to worker或broadcastAndExplicit策略下的广播到达时才会被唤醒。spawn 的完整参数表参数说明默认值--agent name加载.trellis/agents/name.md读取 provider/model/as/system prompt 等默认值—--provider claude\|codex覆盖 agent 卡片中的 provider并会经过适配器注册表校验取卡片值--as name通道内的 worker 句柄其他智能体用--to寻址它agent 名--cwd pathworker 工作目录同时是--file/--jsonl的越狱jail根当前目录--model id覆盖模型 ID取卡片值--resume id恢复已有的 claude session / codex thread—--timeout duration超时自动杀掉 worker支持30s/2m/1h—--warn-before duration超时前的supervisor_warning预警提前量5m0ms关闭--file path可重复支持 glob把文件内容注入系统提示词—--jsonl path可重复Trellis jsonl 清单每行{file, reason}—--by agentspawned事件的作者$TRELLIS_CHANNEL_AS或main--inbox-policy explicitOnly\|broadcastAndExplicit收件箱唤醒策略explicitOnly--idle-timeout durationOOM 守护的空闲 TTL5m0关闭--max-live-workers nspawn 时的存活 worker 预算60关闭成功事件spawned会完整记录pid、provider、agent、注入的files以及解析后的manifests这样后来的旁观者spectator可以对 worker 实际看到的上下文做审计。该事件模型与 command-reference.md 中CHANNEL_EVENT_KINDS白名单含spawned、killed、respawned、progress、done、error、waiting、awake、undeliverable、turn_started、turn_finished、interrupted、supervisor_warning等一一对应。三、Agent Cards.trellis/agents/name.md角色卡--agent name会解析到.trellis/agents/name.md。卡片名必须匹配正则[A-Za-z0-9._-]。Trellis 默认安装自带两张卡片.trellis/agents/check.md—— 代码质量审查员code-quality reviewer.trellis/agents/implement.md—— 编码 worker用于实现型任务。卡片采用 YAML frontmatter Markdown 正文的结构例如 workers.md 中的check卡片--- name: check description: Code quality check expert. provider: claude ---关键语义有三点frontmatter 字段填充 spawn 默认值provider、model、as都可以在卡片中声明spawn时未显式覆盖即采用卡片值Markdown 正文成为 worker 的系统提示词角色正文就是 worker 的 system-prompt role卡片不会自动附加任务文件上下文必须由每次 spawn 显式注入详见下一节这是最容易踩的坑——仅--agent check是不够的还要配合--file/--jsonl。在 spawn 一个具名 agent 之前官方建议先检查项目里的卡片实际内容ls .trellis/agents sed -n 1,100p .trellis/agents/check.md从 Trellis 本地架构看见 multi-agent-channel.md.trellis/agents/是项目内的“平台无关角色卡”--agent name会从该目录读取新增角色卡只需把name.md放进该目录即可被spawn --agent name识别。同时要注意通道 worker 加载的是.trellis/agents/name.md与各平台的.claude/agents/trellis-*.md、.codex/agents/trellis-*.toml等平台专属 agent 文件是两套独立体系——修改平台目录并不会改变通道 worker 的行为。四、Context Injection--file与--jsonl的上下文注入worker 是独立子进程模型记忆之外的仓库上下文必须显式喂进去。两个 flag 会把内容注入 worker 系统提示词下统一的# CONTEXT FILES块中由context-loader负责装配见 workers.md--file path可重复、支持 glob*、**。每个匹配到的文件都会被读取并拼接。--jsonl path可重复的 Trellis 清单每一行是{file:path,reason:why}。reason会被保留为每份文件内容上方的一条头注释方便 worker 理解“为什么给它看这份文件”。该清单格式与 Trellis 整体上下文注入体系一致——在 context-injection.md 中implement.jsonl/check.jsonl就是同款“每行一个 JSON 对象”的清单且约定只登记 spec/research 类文件不预登记将要被修改的代码文件。加载器强制限制context-loader施加了四个硬性约束超出即报错或告警限制阈值行为单文件硬上限1 MB超出 → 报错单文件警告线200 KB向 stderr 输出警告装配后总上下文警告线500 KB向 stderr 输出警告路径越狱path-traversal jail必须在--cwd之下越界 → 拒绝实战示例对任务目录派发 check worker官方示例workers.md将任务目录下的 PRD、设计、实现文档连同 check 清单一并注入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 30mspawned事件会同时记录字面的files数组和由--jsonl展开得到的manifests从而让审计线索完整还原 worker 真正看到的内容。这一模式与 workflows.md 中的 Pattern BImplement / Check Agent完全同构check.jsonlprd.mddesign.mdimplement.md一次注入--cwd $PWD固定工作根。五、命名与路由--as的双重含义与多 worker 编排--as在不同子命令下有完全不同的语义这是新手最容易混淆的点在send/wait/interrupt中--as是说话者身份作者即所产生事件的 author在spawn中--as是worker 句柄其他智能体用--to来寻址它。当同一通道中有多个 worker 或多个 provider 参与时务必使用显式的、稳定的名字。官方示例workers.md在一个通道上同时跑 claude 与 codex 两个审查员trellis channel spawn cr-feature --agent check --as check-claude trellis channel spawn cr-feature --agent check --provider codex --as check-cx trellis channel wait cr-feature --as main \ --from check-claude,check-cx --kind done --all --timeout 15m--from接受 CSV表示监听多个作者的done事件。--all必须与--from搭配含义是“阻塞直到列出的每一个 worker 都产生了匹配事件”一旦超时进程以退出码124结束并向 stderr 打印timeout: still waiting on ...字样。该语义在 command-reference.md 的wait一节有完全一致的描述且wait超时是 CLI 中唯一以 124 作为约定退出码的路径。这就是 workflows.md 中的 Pattern C并行审查者一个通道 两个不同 worker 名wait --all收齐两边的done才放行。六、软中断interrupt协作式转向channel interrupt是协作式重定向它向事件日志追加一个interrupt事件reason: user并在适配器支持的前提下向 provider 发出一次“轮次级中断”并附带替换指令。适用场景是希望 worker放弃当前回合、立即响应新输入但不丢失会话。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 --stdininterrupt 参数--as agent必填—— 调用者身份--to agent必填—— 目标 worker--scope project|global—— 通道作用域--stdin/--text-file path/[text]—— 替换指令正文。追加的事件kind: interrupt可以被下游过滤wait/messages可用--kind interrupt订阅从而对“重路由”作出反应——例如把转向事件记入日志或让其他 worker 等待协调者的纠正指令。如果只是低优先级的提示、允许 worker 在下一回合再处理就不要用 interrupt而是发送一条带 tag 的普通消息echo Check this when you reach the next turn. \ | trellis channel send impl-task --as dispatcher --to codex-impl \ --stdin --tag question需要特别强调的是通道 CLI 中并不存在--tag过滤器command-reference.md 明确说明send没有--tag/--kindflag--kind只能用于wait与messages且interrupt是唯一被硬编码保留的 tag。因此“完成信号”必须依赖 supervisor 自动发出的系统事件done、turn_finished绝不能依赖 worker LLM 记得去运行命令发送自定义 tag——LLM 常把 tag 字符串写进正文而不是真正执行 CLI这会让等待永远无法结束。七、硬中断kill--resume保证收敛的重定向路径当 worker 必须立即停止时——例如陷入死循环、错误指令已在执行途中、或者适配器不响应软中断——使用kill。supervisor 的默认升级路径是SIGTERM → 8 秒宽限grace→ SIGKILL当确实动用了 SIGKILL 时CLI 会补写一个killed事件保证事件日志保持“诚实”truthful审计者不会误以为进程是正常退出的。完整操作workers.mdtrellis channel kill impl-task --as codex-impl trellis channel spawn impl-task --as codex-impl --provider codex \ --resume $(cat ~/.trellis/channels/bucket/impl-task/worker.session-id) echo STOP — new instructions: ... \ | trellis channel send impl-task --as dispatcher --to codex-impl --stdinkill 参数--as agent必填—— 命名该 worker位置参数name是通道名--scope project|global--force—— 立即 SIGKILL同时杀死内层 worker pid。kill 的副作用kill 会清理pid、worker-pid、config、spawnlock这几个 sidecar 文件同时保留log、session-id、thread-id用于取证与恢复。这正是“kill --resume”闭环能成立的原因杀掉旧进程后用保留的 session-id/thread-id 重新 spawn再发送新指令就完成了保证收敛的重定向。官方结论是当interrupt无法收敛时kill --resume是唯一可靠路径。这套 sidecar 文件布局与 progress-debugging.md 中的存储结构一致~/.trellis/channels/bucket/channel/下同时存在events.jsonl、channel.lock、worker.log、worker.pid、worker.worker-pid、worker.config、worker.session-id、worker.thread-id、worker.inbox-cursor、worker.spawnlock。八、Worker OOM 守护空闲 TTL 与存活预算OOM 守护的作用是防止孤儿/空闲 worker 不断累积、耗尽宿主机资源。它在每次spawn时运行对每个项目 bucket 施加两条策略空闲 TTLIdle TTL清扫“最后活动时间”早于阈值的 worker默认5m设为0可关闭存活 worker 预算Live-worker budget若同一项目 bucket 中已存活的 worker 超过 N则拒绝新的 spawn默认6设为0关闭。配置优先级从高到低CLI flagspawn --idle-timeout、spawn --max-live-workers环境变量TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT、TRELLIS_CHANNEL_MAX_LIVE_WORKERS项目配置.trellis/config.yaml的channel.worker_guard块内置默认值5m、6。spawn 时清扫通知会写入 stderr因此运维人员能直观看到“哪些空闲 worker 被清掉了、为什么新 spawn 被拒绝”。该守护对临时 worker /channel run派生的 worker 一视同仁同样受空闲 TTL 与预算约束此点在 multi-agent-channel.md 的定制表中也有对应配置说明。审计当前状态的方法用channel list查看WORKERS列检查~/.trellis/channels/bucket/channel/下每个 worker 的pid/worker-pidsidecar 文件。九、Worker Inbox API唤醒、路由与派发循环Inbox 是 worker 赖以唤醒的通道表面。路由由两个旋钮共同控制Inbox 策略spawn --inbox-policy取值行为explicitOnly默认worker 只在send --to worker或interrupt --to worker时唤醒broadcastAndExplicit额外允许广播不带--to的send唤醒投递模式send --delivery-mode取值行为appendOnly无论 worker 状态如何直接追加事件requireKnownWorker若--to指定的名字从未有过spawned事件则失败requireRunningWorker若指定 worker 当前不在存活状态则失败更严格的投递模式可以在调用方期待“有一个活着的对等进程”时阻止消息被静默丢失。Inbox 相关子命令速查send channel [text]—— 追加一个message事件--as agent必填作者--to agentsCSV单个 → 字符串多个 → 数组省略则广播--stdin/--text-file path/[text]正文来源--delivery-mode取上述三种之一。interrupt channel [text]—— 软中断重定向见第六节。wait channel—— 阻塞直到匹配事件到达--as agent必填用于过滤上下文--from agentsCSV 作者--kind kind[,kind...]CSV、OR 语义支持interrupt、done、progress等--to target默认自身 agent广播 显式发给我--include-progress也监听 progress 事件--all要求每个--fromagent 都匹配超时退出124--timeout duration如30s/2m/1h/1000ms。messages channel—— 查看/过滤/跟随事件流--follow实时尾随--kind/--from/--to过滤--raw每行一个 JSON--no-progress隐藏 progress 噪声。标准派发循环官方给出的三拍模式workers.md是 dispatcher 的骨架# 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一个重要的脚本化约定所有会产出事件的子命令send、interrupt、post、context add/delete、title set/clear、thread rename都会把追加的事件以单行 JSON 打印到 stdout这让 Inbox 层非常容易被 shell / Python 等脚本消费。配合--raw每行一个 JSON 事件可以进一步做结构化审计。十、可继续深入的仓库资料命令级权威参考.agents/skills/trellis-channel/references/command-reference.md —— 每个子命令、每个 flag、输出约定、事件模型白名单协作模式 A–F.agents/skills/trellis-channel/references/workflows.md —— 头脑风暴、审查派发、并行审查者、一次性 run、forum、接管既有线程进度与排障.agents/skills/trellis-channel/references/progress-debugging.md —— 卡死 worker 诊断、progress 事件字段、存储布局本地架构与定制.agents/skills/trellis-meta/references/local-architecture/multi-agent-channel.md ——~/.trellis/channels/布局、channel.worker_guard配置、自定义点上下文注入体系.agents/skills/trellis-meta/references/local-architecture/context-injection.md —— JSONL 清单格式与读取规则。赞分享桌面应用开发工具【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/gh_mirrors/ec/EcoPaste点击查看免费下载相关推荐Trellis Channel Worker 完全指南spawn、Agent Card、上下文注入与中断恢复实战Trellis Channel Worker 完全指南spawn、Agent Card、上下文注入与中断恢复实战 导读 Trellis Channel 是本地桌面应用开发工具EcoPaste 中的 Trellis Channel Worker 深度指南Spawn、Agent Cards、上下文注入与中断恢复EcoPaste 中的 Trellis Channel Worker 深度指南Spawn、Agent Cards、上下文注入与中断恢复 Trellis 的多智桌面应用Trellis Channel Workers 完整实战指南spawn 派生、Agent Cards、上下文注入与中断控制Trellis Channel Workers 完整实战指南spawn 派生、Agent Cards、上下文注入与中断控制 Trellis 的 channel桌面应用上一篇华为麒麟手机Bootloader解锁Huawei-Unlock-Tool的HISI测试点与Fastboot解锁实战下一篇D2DX源码剖析四Surface ID边缘检测抗锯齿与FXAA混合渲染管线详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
