桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载Trellis channel 是本地多 Agent 协作运行时Agent 通过持久化事件日志events.jsonl互相通信worker 作为独立子进程claude / codex被拉起、调度与打断。本指南聚焦于 channel 的进度观测与排障如何区分给操作者看的与用于审计的两种输出、如何从截断的进度行还原模型真实流式文本、如何按固定顺序诊断活着但沉默的卡死 worker以及为什么events.jsonl应该永远交给子命令而不是手工grep。读完本文你将掌握一套可直接照搬的 channel 排障工作流并理解wait、messages、forum等子命令背后的审计语义与退出码约定。在 EcoPaste 仓库中这份排障知识被沉淀为 trellis-channel 技能 的引用文档之一SKILL.md 的路由表 明确规定当用户反馈 channel 卡住了 / 没输出 / progress 被截断 / worker stalled 时应读取本排障指南。一、核心心智模型Pretty 输出给操作者--raw输出是审计日志channel 中同一份事件流存在两种视图用途完全不同Pretty 输出默认messages子命令渲染的紧凑人读视图包含时间戳、身份、事件 kind 与简短正文。它是给操作者扫描 channel 用的仪表盘不是诊断工具。Raw 输出--raw逐行输出与events.jsonl中完全一致的 JSON 事件一个字节都不丢失是排障时的审计日志。Pretty 输出可以且会截断以下内容progress-debugging.md 明确列出长进度增量text_delta、部分工具参数工具名与命令行多行状态字段和结构化detail对象超出列宽预算的 forum 线程标题因此当某个东西看起来不对——worker 似乎卡住、进度行断在半截、action 字段显示...——第一反应应该是切换到--raw重新看。两条经验规则值得记住绝不要从一个被截断的进度行去诊断 worker原文 Rule of thumb。这正是 SKILL.md 核心规则 所述Prettymessagesoutput is an operator dashboard and may truncate progress. Use--rawfor audit.标准用法如下# Pretty操作者视图—— 只扫最近 10 条 done / error 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关于--kind的取值边界可以对照 command-reference.md--kind是唯一的事件类型过滤器且被限制在 Trellis 自发出的白名单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传入白名单以外的值会直接抛错。messages只接受单个--kind值CSV 语义只存在于wait一侧。二、重建流式文本从detail.text_delta还原模型输出当一条消息断在半截或你想知道模型在某个回合里实际流式输出了什么而不只是最终落盘的消息可以拼接所有 progress 事件的detail.text_deltatrellis 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()]这段命令的含义拆解如下--raw保证每行恰好是一个完整 JSON 事件可直接喂给json.loads--kind progress只筛选进度事件过滤掉message/done等终态事件--last 80限定回看范围避免输出过长Python 侧对每行取detail.text_delta并不带换行拼接end从而在终端上还原出模型实际流式产生的原文序列。这利用了 progress 事件的结构化设计detail下承载的字段决定了进行中的工作的形状其中text_delta就是增量模型输出。关于detail内字段的完整语义见下文第四节。三、卡死 Worker 诊断四步标准处置流程症状trellis channel list显示 worker 处于 running 状态但messages中没有新事件wait一直超时。面对活着但沉默alive but silent的 worker按以下顺序排查progress-debugging.md步骤 1定位 channel 文件不确定 channel 属于哪个 bucket 时用全量扫描定位trellis channel list --all --all-projects CHAN~/.trellis/channels/bucket/channel--all-projects会扫描每一个项目 bucket默认--scope project只扫当前 cwd 对应的 bucket--scope global才扫跨项目共享桶。这一点在 command-reference.md 有明确说明每个子命令都接受--scope project|globalproject是默认值按当前 cwd 解析项目 bucket。步骤 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)这两个 PID 文件由spawn写入kill会清理pid/worker-pid/config/spawnlock侧车文件而保留log/session-id/thread-id用于取证与恢复见 workers.md。关键分支如果 supervisor PID 已经不存在但channel list仍显示该 worker这就是幽灵条目ghost entry——supervisor 死亡时没有完成清理。用强制 kill 清理trellis channel kill name --as worker --force步骤 3tail worker 日志worker 日志是查看 provider / MCP / 工具启动输出的规范位置——这些输出永远不会出现在 channel 事件流上tail -f $CHAN/worker.log步骤 4检查最后一批 raw 事件一个发出了progress却没有message/done的 worker通常正处于流式进行中或阻塞在某个工具调用上trellis channel messages channel --raw --last 50活着但沉默的常见成因成因观察特征Provider 冷启动首 token 前有较长静默但最终会继续推进不是真卡死启动期间阻塞的 MCP server在worker.log中可见Worker 等待一个子进程挂起的工具结果工具调用一直没有返回Prompt 过大 / 模型被限流在 worker 日志中检查 provider 侧错误四、Progress 事件解读detail字段才是承载信息的地方一个progress事件代表一项进行中的工作。其形状随action字段变化但承重字段始终在detail之下detail.text_delta— 增量模型输出。跨事件拼接可重建流式回复见第二节。detail.tool_name、detail.tool_input— 即将运行或正在运行的工具调用。detail.status— 长时运行动作使用的短状态字符串starting、running、flushing、done。detail.action— 语义标签例如线程心跳事件使用status。两个实操要点progress 事件天生是嘈杂的。wait默认忽略它们除非显式传入--include-progress。想观察时优先用trellis channel messages channel --raw --kind progress --last 80节奏判断一个以稳定节奏发出 progress、却始终不以done/error/message收尾的流是工具调用挂起的经典形态——去 worker 日志里检查那个子进程。对应地wait/messages在未指定--kind时默认可见的是MEANINGFUL_EVENT_KINDS子集create、join、leave、message、thread、context、channel、spawned、killed、respawned、done、errorprogress、waiting、awake、supervisor_warning与turn_*/interrupt*一类的非意义 kind 仍会写入存储但需要显式--kind或--include-progress才会被看到command-reference.md。五、wait语义速查从 EOF 处盯住事件文件channel wait从events.jsonl的 EOF 处开始监听以下事件会唤醒它messagedoneerrorkilledprogress——仅当传入--include-progress常用过滤组合# 等待单一 worker 的 done trellis channel wait T --as main --from check --kind done --timeout 15m # 等待多个 worker 全部完成--all 要求每个 --from 都匹配 trellis channel wait T --as main --from check,check-cx --kind done --all --timeout 15m # worker 侧监听 interrupt 事件最长 1 小时 trellis channel wait T --as worker --tag interrupt --timeout 1h # 按线程与 action 过滤forum 通道 trellis channel wait T --as main --thread release-note --action status --timeout 10m退出码约定排障时必须知道0— 匹配到事件正常返回124— 超时。若使用了--allstderr 会列出仍然缺失的 worker 名称格式为timeout: still waiting on ...1/2— 出错这个退出码体系在 command-reference.md 中被再次确认Errors go through chalk.red to stderr and exit 1; wait timeout specifically exits 124。用脚本包装wait时请务必显式处理124而不是当作普通错误吞掉。wait的默认--to过滤器是调用者自己的 agent 身份广播事件仍然命中因为广播 广播 显式发给我--all需要--from且会阻塞到所有列出的 agent 都产出匹配事件。六、审计events.jsonl用子命令不要用grep每个 channel 的完整历史都持久化在$CHAN/events.jsonl。排障时很容易想直接tail/grep/jq这个文件——不要养成这个习惯且永远不要在 forum 通道上这样做progress-debugging.md。为什么子命令优先messages已经做了全部重放工作它按--kind、--from、--last、--tag、--thread、--action过滤并提供--raw输出精确 JSON。任何你想用一行 shell 脚本实现的事messages都已经实现了。wait消费同一文件但带 EOF 语义用tail -f | jq重新实现会在高负载下丢事件、在日志轮转时打乱顺序。context物化 worker 的收件箱视图含游标状态手写过滤器不会尊重worker.inbox-cursor文件——你会看到worker 已经消费掉的事件然后误以为它们还挂着。Forum 通道永远不要直接解析events.jsonlForum 通道把许多逻辑线程复用multiplex到单一events.jsonl上。每个事件携带thread、action和 tag 字段只有 forum 子命令知道如何把它们折叠为线程视图。手工解析会导致线程混在一起看起来毫无条理错过open/status/close等线程生命周期事件——它们会改变后续事件的解释方式忽略 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对应地forum.md 明确了 forum 通道的默认读取路径是forum 摘要 → 单个线程时间线 → 当前 context三者恰好对应上述三个命令的职责。而 command-reference.md 还补充了messages会自动检测 forum 通道——不带过滤器时渲染线程看板而不是事件流--thread/--action是 forum 专属参数对 chat 通道会报错。唯一允许直接读events.jsonl的情形怀疑 CLI 本身有问题——例如确认某个事件确实被持久化了或在与worker.inbox-cursor做 diff 调试 supervisor 时。七、常见故障速查表排障过程中最常遇到的八类问题一表对照progress-debugging.md症状原因修复trellis: command not foundCLI 未全局安装npm install -g mindfoldhq/trelliswait立即退出过滤器错误或身份冲突使用不同的--as查看 raw 消息zsh 对消息文本报错shell 解析了标点符号使用--stdin或--text-file进度行被切断pretty 输出截断用messages --raw --kind progressworker 从不发言provider 启动 / prompt / MCP 延迟检查worker.log、ps、raw 事件在另一个 cwd 找不到 channel项目 bucket 不匹配cd到项目目录使用--scope global或list --all-projects列表里出现幽灵 workersupervisor 死亡未清理trellis channel kill name --as worker --forceforum 线程看起来混乱直接解析了events.jsonl改用forum、thread、messages --thread两个值得展开的补充点wait立即退出且身份冲突--as在send/wait/interrupt中是发言者身份在spawn中是 worker 句柄其他 agent 用--to寻址的目标。多个 agent 或会话共用一个 channel 时必须使用显式、稳定的名字SKILL.md。长正文必须走--stdin或--text-file既避免 shell 解析标点导致 zsh 报错也符合 SKILL.md 核心规则——不要把中英混排的长文本放进位置参数。标准写法为trellis channel send T --as A --stdin /tmp/message.md或trellis channel send T --as A --text-file /tmp/message.md。八、存储布局侧车文件图谱每个 channel 目录下的全部文件及其职责如下progress-debugging.md~/.trellis/channels/ └── bucket/ └── channel-name/ ├── events.jsonl # 完整事件历史审计日志 ├── channel.lock # channel 级锁 ├── worker.log # worker 进程日志provider/MCP/工具启动输出 ├── worker.pid # supervisor PID ├── worker.worker-pid # 实际 CLI 子进程 PID ├── worker.config # worker 配置 ├── worker.session-id # 会话 ID供 --resume 恢复 ├── worker.thread-id # 线程 ID ├── worker.inbox-cursor # worker 收件箱游标 └── worker.spawnlock # 生成锁这张图谱与前面各节一一对应第三节的进程存活检查读的就是worker.pid/worker.worker-pid第三节的tail 日志读的是worker.log第六节的不尊重 inbox-cursor 的手工过滤对应worker.inbox-cursor恢复中断 worker 时spawn --resume $(cat .../worker.session-id)读的是worker.session-idworkers.md。通用原则Agent 的正常工作方式是使用 CLI而不是直接读文件。直接读文件仅限CLI 视图不足以诊断的调试场景——即使如此也永远不要去读 forum 通道的events.jsonl。九、实战排障决策清单把整篇指南压缩为一条可执行的排障路径现象确认trellis channel list看 worker 状态messages --kind done/error --last 10确认最近是否收敛。怀疑截断换messages --raw --kind progress --last 80看原始事件拼接detail.text_delta还原流式文本。怀疑卡死list --all --all-projects定位CHAN→ 检查pid/worker-pid与ps→tail -f $CHAN/worker.log看 provider/MCP/工具输出 →messages --raw --last 50确认是否停在 progress 而无终态。判定幽灵supervisor PID 消失但列表仍显示 worker →channel kill --force。等待收尾用wait --as self --from worker --kind done --timeout dur多 worker 加--all记住124是超时而非错误stderr 会点名缺失的 worker。审计历史一律走messages/wait/context子命令forum 通道用forum list→thread show→messages --thread→context --as的组合视图绝不直接解析events.jsonl。这套方法在 EcoPaste 仓库中的落地形态可见于 SKILL.md 的意图路由表、完整命令参考 以及 worker 管理 与 forum 通道 两份配套文档。当项目通过 session-start 钩子 注入上下文、由 AGENTS.md 中的 Trellis 指令块 引导 Agent 工作流时这套 channel 排障能力就是多 Agent 协作发生故障时的最后一道防线。赞分享桌面应用【免费下载链接】EcoPaste跨平台的剪贴板管理工具 | Cross-platform clipboard management tool项目地址https://gitcode.com/ayangweb/EcoPaste点击查看免费下载相关推荐Trellis 平台接入指南hooks 与 settings 的职责、注册与故障排查EcoPaste 仓库实例Trellis 平台接入指南hooks 与 settings 的职责、注册与故障排查EcoPaste 仓库实例 本文以 hooks and setting桌面应用Ceph OSD 与 Placement GroupPG监控与故障排查实战指南Ceph OSD 与 Placement GroupPG监控与故障排查实战指南 Ceph 是一个分布式对象、块与文件存储平台其高可用与高可靠性建立在容错式存储分布式文件系统对象存储后端高可用一个 Skill 文件、33 类模式Humanizer 一次改写去掉 AI 写作痕迹一个 Skill 文件、33 类模式Humanizer 一次改写去掉 AI 写作痕迹 Humanizer 是给用 AI 写初稿的人准备的写作去 AI 化 agAI 技能AI 写作上一篇7个顶级AI绘画工作流ComfyUI-Workflows-ZHO从入门到精通的完整指南下一篇揭秘mecab-ipadic-neologd从Web资源到新语词典的完整构建指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考