桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载导读Trellis 的本地多 Agent 协作运行时代码在通道channel中把每个事件以 JSON 形式落盘到events.jsonl但不同的阅读者需要完全不同的视图操作者要的是紧凑可读的 pretty 输出排障者要的是逐行精确的--raw审计视图。本文以 Trellis 官方进度调试手册为主体原文档位于 .claude/skills/trellis-channel/references/progress-debugging.md同目录下另有 command-reference.md、workers.md、forum.md、workflows.md 可互为印证讲解如何区分 pretty 与 raw 输出、如何从text_delta重建流式文本、如何按四步排查存活但沉默的 stalled worker、如何解读progress事件、wait的精确语义、以及为什么审计events.jsonl必须走子命令而不是手写grep。读完你将掌握一套可复制的通道级排障流程并理解事件存储布局与各 sidecar 文件的用途。Pretty 与--raw两套视图的分工trellis channel messages channel渲染的是紧凑的人类可读视图时间戳、身份、事件种类和一段短正文。它服务的是扫一眼通道里发生了什么的操作者场景不是诊断场景。Pretty 输出可以且一定会截断以下内容都可能被裁剪较长的 progress 增量text_delta、部分工具参数工具名称和完整命令行多行的状态字段与结构化detail数据块超出列宽的 forum 线程标题。因此当某个东西看起来不对劲——worker 似乎卡住、progress 行停在单词中间、action 字段显示为...——立即切换到--raw。raw 模式逐行输出events.jsonl中原样保存的 JSON 事件什么都不丢弃。# Pretty操作者视图 trellis channel messages channel --kind done --last 10 trellis channel messages channel --kind error --last 10 # Raw诊断视图—— 每行一个 JSON trellis channel messages channel --raw --kind progress --last 20 trellis channel messages channel --raw --last 50经验法则永远不要根据一条被截断的 progress 行去诊断 worker。重建流式文本Rebuild Streaming Text要还原模型在某个回合实际流式输出的内容把 progress 事件里的detail.text_delta逐段拼接起来即可trellis channel messages channel --raw --kind progress --last 80 \ | python3 -c import json,sys; [print((json.loads(l).get(detail) or {}).get(text_delta,), end) for l in sys.stdin if l.strip()]这条管道是诊断输出到底生成到了哪里的最快手段messages --raw --kind progress负责把流式增量原样取出Python 单行脚本负责逐行解析并累加text_delta。与之对应--raw模式可配合--follow持续跟踪新事件、--last N限定最近 N 条、--since seq按序列号过滤详见 command-reference.md 中messages子命令的完整参数清单。Stalled Worker 诊断四步排查法典型症状trellis channel list显示 worker 处于 running 状态但messages中不再出现新事件wait也持续超时。按以下顺序排查第 1 步定位通道文件。如果不确定通道落在哪个 bucket用list --all --all-projects扫描所有项目桶。trellis channel list --all --all-projects CHAN~/.trellis/channels/bucket/channel第 2 步确认 supervisor 与 worker 的 PID 都还活着。cat $CHAN/worker.pid # supervisor PID cat $CHAN/worker.worker-pid # 实际 CLI 子进程 PID ps -p $(cat $CHAN/worker.pid) ps -p $(cat $CHAN/worker.worker-pid)如果 supervisor PID 已消失但通道列表里仍有该 worker说明存在ghost entry幽灵条目——supervisor 死亡时没来得及清理。用trellis channel kill name --as worker --force清理它kill的--force路径会立即 SIGKILL并写出killed事件保持日志可信见 workers.md。第 3 步tail worker 日志。这是观察 provider / MCP / 工具启动输出的权威位置——这些输出永远不会出现在通道上tail -f $CHAN/worker.log第 4 步检查最近的原始事件。一个发出了progress但没有message/done的 worker通常正处于流式输出中途或阻塞在某个工具调用上trellis channel messages channel --raw --last 50常见的存活但沉默alive but silent原因Provider 在第一个 token 之前的冷启动很慢但最终会动阻塞的 MCP 服务器在启动阶段卡住——在 worker 日志中可见Worker 在等待一个子进程挂掉的工具结果Prompt 过大 / 模型被限流——检查 worker 日志里的 provider 侧错误。Progress 事件解读progress事件代表一项进行中的工作。它的具体形状随action字段变化但承重字段永远在detail之下detail.text_delta— 模型增量输出跨事件拼接可重建流式回复detail.tool_name、detail.tool_input— 即将执行或正在执行的工具调用detail.status— 长耗时动作使用的短状态字符串starting、running、flushing、donedetail.action— 语义标签例如线程心跳用status。Progress 事件天生就是嘈杂的。wait默认忽略它们除非传入--include-progress。当你确实要观察时优先这样用trellis channel messages channel --raw --kind progress --last 80一个以稳定节奏持续发出 progress、却从不以done/error/message收尾的流是挂起的工具调用的经典形态——去 worker 日志里查对应的子进程。值得补充的是progress属于非 meaningful 事件种类MEANINGFUL_EVENT_KINDSwait/messages在未显式传--kind时默认可见的集合只包含create、join、leave、message、thread、context、channel、spawned、killed、respawned、done、errorprogress、waiting、awake、supervisor_warning以及turn_*/interrupt*系列仍会落库但必须通过--kind或--include-progress显式订阅详见 command-reference.md 的 Event Model 一节。Wait 语义速查channel wait从events.jsonl的 EOF 处开始监听并在以下事件到达时唤醒messagedoneerrorkilled仅在带--include-progress时的progress常用过滤组合trellis channel wait T --as main --from check --kind done --timeout 15m trellis channel wait T --as main --from check,check-cx --kind done --all --timeout 15m trellis channel wait T --as worker --tag interrupt --timeout 1h trellis channel wait T --as main --thread release-note --action status --timeout 10m退出码约定0表示匹配到124表示超时1/2表示错误。当wait --all超时时stderr 会点名仍然缺席的 worker。需要强调的细节来自 command-reference.md 的 tag-vs-kind 一节--kind是唯一的按事件类型过滤手段且被约束在CHANNEL_EVENT_KINDS白名单内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传入其他值会直接报错wait侧的--kind接受 CSV 且是 OR 语义而messages侧只接受单值。wait与send都没有--tag过滤器——不要让 worker 靠把某个 tag 字符串写进正文来充当完成信号那只是message事件里的一段普通文本wait无法匹配它完成信号应该用 supervisor 自动发出的系统事件--kind done/--kind turn_finished。审计events.jsonl用子命令不要用grep每个通道把完整历史持久化在$CHAN/events.jsonl。排障时很容易想直接对这个文件tail/grep/jq——但不要养成这个习惯在 forum 通道上永远不要这样做。为什么优先用子命令messages已经用过滤器--kind、--from、--last、--tag、--thread、--action重放了整个文件并提供了--raw输出精确 JSON。任何你想写单行脚本完成的事messages都已经内置了。wait以 EOF 语义消费同一个文件——用tail -f | jq自己重造这一套会在高负载下丢事件、在轮转时打乱顺序。context可以物化 worker 的收件箱视图包括游标状态。手写的过滤器不会尊重worker.inbox-cursor。Forum 通道绝不要直接解析events.jsonlForum 通道把多条逻辑线程复用到一个events.jsonl上。每个事件携带thread、action和 tag 字段forum 子命令知道如何把它们折叠在一起。手工解析这个文件会把线程混在一起使单个线程看起来支离破碎漏掉改变后续事件解读方式的线程生命周期事件open / status / close无视 worker 收件箱游标于是你会看到worker 已经消费过的事件误以为它们仍是待处理状态。使用 forum 感知视图# 列出 forum 通道内的逻辑线程 trellis channel forum list channel # 端到端检视一个线程 trellis channel thread show channel thread # 重放某线程的消息支持 --raw、--kind、--last trellis channel messages channel --thread thread --raw --last 100 # 某个特定 worker 还有哪些待处理项 trellis channel context channel --as worker直接读events.jsonl只保留给CLI 本身可疑的场景——例如确认某事件确实被持久化了或在调试 supervisor 时与worker.inbox-cursor做对比。forum 的完整线程模型opened、comment、status、summary、--thread键约定、thread rename纠错路径见 forum.md。常见失败速查表症状原因修复trellis: command not foundCLI 未全局安装npm install -g mindfoldhq/trelliswait立即退出过滤器错误或身份冲突使用互不相同的--as检查 raw 消息zsh 在消息文本上报错shell 解释了标点符号使用--stdin或--text-fileprogress 行被截断pretty 输出截断使用messages --raw --kind progressworker 从不说话provider 启动 / prompt / MCP 延迟检查worker.log、ps、raw 事件在其他 cwd 下找不到通道项目 bucket 不匹配cd到项目使用--scope global或list --all-projects列表中出现幽灵 workersupervisor 死亡后未清理trellis channel kill name --as worker --forceforum 线程看起来错乱直接解析了events.jsonl使用forum、thread、messages --thread补充两点与上表密切相关的机制见 workers.mdkill的默认路径是 SIGTERM → 8 秒宽限 → SIGKILL 升级CLI 在确实动用 SIGKILL 时会补写killed事件保持事件日志真实kill会清理pid、worker-pid、config、spawnlock等 sidecar 文件但保留log、session-id、thread-id用于取证与--resume恢复。存储布局~/.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各 sidecar 文件的分工一目了然events.jsonl是全部事件的持久化审计日志channel.lock防止并发写同一通道worker.log是 worker 的完整运行日志provider / MCP / 工具启动输出.pid与.worker-pid分别记录 supervisor 与实际 CLI 子进程 PID正好对应前面 stalled worker 排查第 2 步.config、.session-id、.thread-id服务于 worker 会话与--resume.inbox-cursor是 worker 收件箱游标context子命令会尊重它.spawnlock防止重复 spawn。最后一条原则Agent 通常使用 CLI 而不是直接读文件。直接读文件只用于 CLI 视图不够用时的排障——而且即便如此也永远不要在 forum 通道上直接读events.jsonl。在 EcoPaste 仓库中的实践位置本手册以 skill 的形式沉淀在本仓库中用于指导 EcoPaste 项目内多 Agent 协作的排障.claude/skills/trellis-channel/SKILL.md 是 trellis-channel skill 的索引入口负责按用户意图路由到对应的 reference 文件——当用户报告channel 卡住了 / 没输出 / progress 被截断时路由目标正是本手册.claude/skills/trellis-channel/references/progress-debugging.md 为本文主体配套的 command-reference.md 提供全部子命令与参数的权威定义仓库级协作约定记录在 AGENTS.md其中明确指出项目的 Trellis 工作知识workflow、spec、workspace 日志、tasks都位于.trellis/目录下.claude/commands/trellis/下的 continue.md 与 finish-work.md 演示了如何通过python3 ./.trellis/scripts/get_context.py恢复任务上下文与归档任务——这些流程同样依赖.trellis/目录中的持久化状态。当你在 EcoPaste 的开发流程中遇到 worker 卡死、progress 截断或事件对不上号时按本文的排查顺序执行先--raw看真相再验 PID、tail 日志、查最后一条 raw 事件凡是涉及 forum 线程的解读一律交给forum/thread/messages --thread子命令。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐EcoPaste 项目中的 Trellis Channel 进度调试指南从截断输出到事件级审计的完整排查手册EcoPaste 项目中的 Trellis Channel 进度调试指南从截断输出到事件级审计的完整排查手册 本文面向在 EcoPasteRust Firs桌面应用EcoPaste 中的 Trellis Channel Worker 深度指南Spawn、Agent Cards、上下文注入与中断恢复EcoPaste 中的 Trellis Channel Worker 深度指南Spawn、Agent Cards、上下文注入与中断恢复 Trellis 的多智桌面应用解决Vite项目Chrome 131调试卡死从断点到页面无响应的深度排查解决Vite项目Chrome 131调试卡死从断点到页面无响应的深度排查 你是否在Chrome 131中调试Vite项目时遇到过这样的情况设置断点后页面突然前端前端构建上一篇AlphaFold模型保存与加载终极指南训练中断后快速恢复的完整教程下一篇微服务日志聚合新范式SpringCloud脚手架集成ELK/EFK实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考