gbrain Exec 输出惯例用缓冲区与有界读取驯服命令输出的截断陷阱【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain命令执行exec是 AI Agent 最常用的工具之一而大输出被静默截断则是 Agent 编程中最隐蔽的故障源。gbrain 的编码专用变体gbrain-coding persona在其惯例集中固化了一条规则把命令输出缓冲到文件再读取一个有界的切片空的 exec 结果通常意味着截断而不是 shell 坏了或进程崩溃了。本文以 exec-output.md 为主线结合该惯例在主仓库中的姊妹版本 skills/conventions/exec-output.md 与周边惯例完整讲解这一规则的应用场景、五个可复制的命令模式、四步诊断阶梯以及必须规避的反模式帮助你避免在循环、表格、长管道等场景下被看似失败的输出误导并据此高效定位真实问题。背景工具返回预算与截断的真相Agent 执行命令后harness执行框架对每次工具调用的返回内容有预算限制。当命令输出超过该预算时输出会被截断。截断在 Agent 眼中常常表现为空结果或不完整结果从而诱导出错误的根因判断——shell 坏了进程崩溃了某次重启杀掉了 exec。该惯例在 gbrain 编码变体中的定位是跨技能的输出纪律gbrain-coding 是面向在仓库内部进行检索、路由、摄入与修正的编码 Agent persona见 plugin-variants/gbrain-coding/README.md其惯例集中还有 path-discipline.md路径纪律、regex-discipline.md正则纪律、test-before-bulk.md批量前先测试等exec-output 负责的是命令输出如何被安全地消费。有趣的是有界读取本身也是 gbrain 源码中普遍采用的防御模式在 Claude CLI 语言模型适配器 src/core/ai/providers/claude-cli-language-model.ts 中解析失败时对原始 stdout 也只截取前 500 字符放入错误信息stdout.slice(0, 500)避免错误信息自身膨胀失控——从源码结构看这正是输出必须被边界化这一原则在库内部的体现。失败特征如何识别截断伪装成的故障并非所有空输出都是截断但截断有非常典型的特征组合echo alive这类琐碎命令执行正常任何多行循环、表格或长管道返回空结果故障看起来是间歇性的——工具似乎在抖动flap部分 harness 会附带截断提示另一些则什么都不返回。判断核心在于一个死掉的 shell 不会选择性杀掉长命令。如果琐碎命令成功而长命令返回空那是大小上限size ceiling问题而不是进程故障。这个特征组合本身就给出了方向——先怀疑输出体积再怀疑基础设施。规则永不向 stdout 倾倒大输出核心规则只有一条cmd /tmp/out.txt 21; tail -40 /tmp/out.txt把命令完整重定向到文件同时捕获 stdout 与 stderr再通过tail读取有界的切片。凡是可能超过一屏文本的输出都应套用此规则包括超过少数几个条目的for循环按条目或按天统计的计数结果未加限制的ps、du、find、git log任何打印表格的脚本调用API 响应curl不接head -c时测试与类型检查运行——必须先重定向保存因为退出码和完整失败列表都会留在文件里如果直接用管道接到tail两者都会丢失。最后一条尤其值得强调测试失败的诊断价值完全依赖完整失败列表 退出码把它们交给一个会被截断的 stdout 管道等于在还没看结果之前就扔掉了关键证据。五个可复制的实战模式惯例给出了覆盖典型场景的五个模式均遵循缓冲 → 有界切片的总原则# 1. 循环——先缓冲再切片 for d in $(seq 1 30); do ...; done /tmp/loop.txt 21 tail -40 /tmp/loop.txt # 2. 计数——在脚本内聚合只打印摘要 python3 -c ... /tmp/counts.txt 21; tail -40 /tmp/counts.txt # 3. API——在行内限制字节数 curl -s $URL | head -c 600 # 4. 大 JSON——解析出小摘要绝不 cat 整个文件 python3 -c import json; djson.load(open(big.json)); print(len(d[items])) # 5. 长任务——后台运行轮询日志 nohup cmd /tmp/job.log 21 tail -20 /tmp/job.log各模式针对的痛点各不相同循环条目一多输出必然超限缓冲后只读尾部最有效计数在脚本内部完成聚合把 N 行明细压成一行摘要天然把输出控制在预算内APIhead -c 600在数据源头限制字节数适合只需要确认响应形态的场景大 JSON用 Python 解析出关键字段如条目数再打印避免把整个 JSON 灌进工具返回长任务nohup ... 后台运行后轮询日志尾部进程退出与否不影响你随时查看进度。诊断阶梯空 exec 结果的四步定位法当命令返回空结果时按顺序执行以下步骤在第一个能解释现象的步骤停下echo alive——如果这条能成功exec 本身没问题问题出在输出体积用| head -20重跑——如果输出出现了那就是截断确认完毕缓冲到文件并检查文件大小——wc -c /tmp/out.txt。一个大文件配上空的工具结果是截断的决定性证据只有 1–3 都失败后才考虑进程、权限或基础设施层面的原因。这套阶梯的价值在于证据顺序先用最廉价的手段排除输出体积这一最可能的解释再向上层原因推进。惯例明确要求没有走完诊断阶梯就报告任务被阻塞属于反模式——因为答案往往已经静静躺在那个文件里你离成功只差一条tail -40。为什么这条规则值得坚持截断会伪装成故障而误读它的代价是真实且可累加的浪费时间重复执行同一个超大的命令寄希望于下次会有不同结果凭空发明机制——某次重启破坏了 exec——而没有任何证据把原因和症状联系起来把任务报告为受阻尽管它只差一个有界读取就能完成。这正是该惯例与 gbrain 其他输出纪律的呼应之处gbrain 的 输出规则 要求 Agent 输出具体事实、短段落、可验证依据而 摩擦协议 要求把命令失败但错误信息无法指导下一步这类摩擦记录下来供维护者改进——被截断误导的误诊恰恰是典型的需要按协议上报的摩擦。有界读取胜过重跑答案通常已经在那里你要做的是以可控的代价把它读出来。反模式这五种做法应该被避免长命令返回空后直接诊断工具坏了把锅甩给一个无关的近期事件重启、部署却没有证据把该事件与症状联系起来重复执行同一个超大的命令指望换个结果把测试运行通过管道接到tail而不是先重定向到文件没走诊断阶梯就把任务报告为受阻。与其他惯例的关系exec-output 不是孤立的一条规则它与 gbrain 惯例集中的其他条目互为支撑test-before-bulk.md批量操作前先小规模试跑并用执行前后计数对比验证输出真实存在——而批量脚本的输出正是 exec-output 中必须先缓冲再读取的典型对象path-discipline.md读取与写入的文件路径必须是裸路径这决定了你在tail /tmp/out.txt时应使用不带任何链接标记的裸路径regex-discipline.md当循环/统计类输出必须压缩时优先在脚本内做确定性聚合如python3 -c解析 JSON 摘要而不是依赖正则去猜测输出形态。在实际的 gbrain 编码工作流中建议将大输出 → 文件缓冲 有界读取固化为肌肉记忆凡是for、ps、du、find、git log、curl或测试运行先问一句这个输出会不会超过一屏会就先重定向。遇到空结果从echo alive开始走完四步诊断阶梯确认是体积问题后再放心地用tail拿回答案。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考