AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载本篇技术指南聚焦 Ekko Agent 工具执行层的输出边界机制当terminal_exec等工具产生超大 stdout/stderr 时如何在不把多 MB 文本塞进模型请求、又不让无界产物耗尽本地磁盘的前提下既保留可分页访问的完整输出又维持 provider 请求的安全性。读者将掌握三层输出限制预览边界、产物持久化边界、请求安全限制的默认值、配置方式、底层实现原理以及产物落盘后的read_file分页检索与进度文本规范化等实战要点。背景为什么工具输出必须被“关进笼子”Ekko Agent 在直接聊天direct chat场景中执行terminal_exec、code_exec等工具时工具结果会作为上下文进入下一次模型请求。一旦命令输出失控会引发两个问题模型请求膨胀多 MB 的文本工具结果直接进入请求既浪费 token 预算也可能超出 provider 的请求体限制磁盘空间风险如果为保留完整输出而无限落盘长时间运行或高频工具调用可能让无界产物逐渐耗尽本地磁盘。2026-09-02 的变更见 变更记录给出的解法是三层组合为terminal_exec的 stdout/stderr 预览分别设置字节上限将超过预览上限的完整输出以受安全上限约束的产物artifact持久化到被 git 忽略的工作区临时目录对所有文本型工具结果追加一层 provider 请求级安全限制且当产物持久化失败时仍然返回预览。整体架构三层输出边界从源码结构看输出边界在 Ekko Agent 内部分布于三个模块层负责模块核心职责预览边界tools/terminal.ts 的BoundedOutputCapture内存中保留 stdout/stderr 的头尾片段超出即标记截断产物持久化边界tools/terminal.ts 的ArtifactByteLimit与 tools/workspace-temp.ts将完整流写入.ekko-tmp/tool-assets单流上限默认 25 MB超限继续排空但不落盘请求安全限制tools/tool-result-sanitizer.ts 的sanitizeAgentToolResult对所有工具结果做文本裁剪默认 256 KB必要时再落盘一份 25 MB 上限的产物运行时的执行路径位于 runtime.ts工具执行完原始结果后统一经过sanitizeAgentToolResult(validatedResult, { tempRoot: workspaceToolAssetDirectory(context) })再发出tool.completed/tool.failed事件因此即使单个工具自身没有实现产物机制最终进入模型上下文的文本也必然受请求级限制约束。terminal_exec 预览边界头尾保留 截断标记TerminalExecTool是terminal_exec工具的实现类其预览捕获逻辑由BoundedOutputCapture完成见 terminal.ts。它的关键设计是并非只截断尾部保留开头maxBytes - maxBytes/3字节头部额外保留最后maxBytes/3字节尾部当总输出超过上限时在头尾之间插入截断标记[terminal_exec output truncated: N bytes total, M bytes omitted. The first K bytes were saved to path; the artifact reached its safety limit. Inspect it with read_file using offsets or a bounded search.]如果产物完整保存未触发产物上限标记则改为Full output saved to path; inspect it with read_file using offsets or a bounded search.。这意味着即使预览只有 100 KB模型也能同时看到命令输出的开头和结尾并通过标记中的路径引导后续read_file分页读取。默认阈值TerminalExecTool的默认值定义在 terminal.ts常量默认值含义DEFAULT_TERMINAL_EXEC_MAX_OUTPUT_BYTES100,000stdout 预览字节上限DEFAULT_TERMINAL_EXEC_MAX_STDERR_BYTES25,000stderr 预览字节上限DEFAULT_TERMINAL_EXEC_MAX_ARTIFACT_BYTES25 × 1024 × 102425 MB每条流落盘产物的安全上限超时默认值30,000 ms命令执行超时超时发送SIGTERM所有阈值均通过构造参数注入maxOutputBytes、maxStderrBytes、maxArtifactBytes、timeoutMs便于宿主按需调整positiveInteger会丢弃非正数并回退默认值terminal.ts。结果元数据执行结果不仅返回截断后的content还在data中携带完整诊断信息terminal.tsstdoutBytes/stderrBytes实际总字节数stdoutTruncated/stderrTruncated是否发生预览截断stdoutArtifactPath/stderrArtifactPath产物落盘路径仅当保留产物时存在stdoutArtifactBytes/stdoutArtifactTruncated产物实际写入字节数与是否触顶exitCode、timedOut、aborted命令执行结果状态。超大流产物持久化.ekko-tmp/tool-assets 的完整链路当输出超过预览上限时完整流会持续写入产物文件产物目录遵循“被忽略的工作区临时目录”约定见 workspace-temp.ts临时根目录固定为工作区下的.ekko-tmp常量EKKO_WORKSPACE_TEMP_DIRECTORY无工作区时回退到系统临时目录下的ekko-agent产物统一存放在.ekko-tmp/tool-assets/ensureWorkspaceTempRoot会以wx独占模式在.ekko-tmp下写入内容为*\n的.gitignore确保临时产物不会被 git 跟踪子进程环境中的TMPDIR、TMP、TEMP被重定向到该临时目录workspaceTempEnvironment命令产生的临时文件同样落在工作区临时目录内便于工作区作用域的文件工具检查。产物文件命名与权限产物文件名为${safeArtifactName(runId)}-${Date.now()}-${randomUUID()}.stdout.log/.stderr.logterminal.ts其中safeArtifactName会把非法字符替换为-并截断到 80 字符terminal.ts。文件以wx独占创建和0o600仅属主可读写权限写入避免覆盖他人文件、防止其他用户读取命令输出。有界产物写入与磁盘保护产物流写入由ArtifactByteLimit一个Transform流把关terminal.ts只向文件流转发前maxArtifactBytes字节超过后置truncated true并继续从上游排空数据不丢弃管道、不挂死子进程。pipeOutputArtifact在产物流报错时会主动unpipe并 resume保证磁盘故障不会拖垮命令执行本身。产物清理策略预览未截断时命令关闭后立即删除已写入的产物文件terminal.ts因此输出在限制内的命令不会在tool-assets留下任何文件产物达到上限时文件保留标记中注明“artifact reached its safety limit”供用户用read_file分页或受限搜索继续取回兜底清理cleanupExpiredToolAssets会按 TTL默认 24 小时清理过期产物见 tool-result-sanitizer.ts。provider 请求安全限制所有工具结果的最后防线terminal_exec自身只管预览与产物但进入模型请求的文本还要再过一道sanitizeAgentToolResulttool-result-sanitizer.ts。这一层对每一个工具结果生效包括没有自带产物机制的工具DEFAULT_TOOL_RESULT_MAX_TEXT_BYTES 256_000文本结果超过 256 KB 即裁剪为“头部 截断标记 尾部”尾部同样约占 1/3DEFAULT_TOOL_RESULT_MAX_TEXT_ARTIFACT_BYTES 25 MB裁剪出的完整文本以 sha256 摘要命名tool-result-digest.txt写入产物目录供后续read_file取回持久化失败仍返回预览产物写入失败时如磁盘不可写标记会明确提示Full output could not be saved; use a narrower tool query to retrieve the omitted section.预览照常可用绝不因落盘失败而丢失截断信息该层还负责把结果中内嵌的 base64 / data URL图片、音频等物化为文件并以file://URL 替换避免二进制数据进入模型上下文tool-result-sanitizer.ts。运行时的tool.completed事件发出前统一调用此函数runtime.ts因此无论工具是terminal_exec还是其他文本型工具模型请求都受 256 KB 上限保护。read_file 分页取回截断标记与 offset 协同文档强调“large command output remains available for pagedread_fileaccess or bounded searches”。这条链路是闭环的命令输出超限terminal_exec返回带路径的截断标记模型调用read_file读取产物文件read_file自身支持offset分页——测试中的行为是返回[read_file truncated: returned bytes 0-N of M; call again with offsetN]并在data.nextOffset中给出下一次偏移见 tests/ekko-agent/tools.test.ts模型按offset多次调用即可完整消费数 MB 级别的命令输出而无需一次性装入请求。terminal_exec的工具描述也为此提供了指引Large stdout and stderr are returned as bounded previews; output artifacts are saved under .ekko-tmp/tool-assets up to a per-stream safety limit for paged read_file access or bounded searchesterminal.ts。code_exec 的输出策略只留预览、不进上下文与terminal_exec不同code_exec采用独立且更保守的策略见 code-exec.tsCapturedOutput只保留前maxBytes字节超限时追加[OUTPUT TRUNCATED: N bytes omitted]标记不落盘完整产物code-exec.ts默认阈值见 config.tsDEFAULT_CODE_EXEC_MAX_OUTPUT_BYTES 50_000、DEFAULT_CODE_EXEC_MAX_STDERR_BYTES 10_000、DEFAULT_CODE_EXEC_MAX_SOURCE_BYTES 200_000、DEFAULT_CODE_EXEC_MAX_TOOL_CALLS 50脚本内的嵌套工具调用read_file/write_file/terminal_exec通过本地 RPC 完成且中间结果不进入模型上下文Only the script output is returned; intermediate nested tool results stay outside model contextcode-exec.tsRPC 请求/响应各限 2 MBRPC_MAX_REQUEST_BYTES超限返回明确错误。这些配置可通过EkkoToolsConfig.codeExec结构持久化调整config.ts。UX 规范工具调用进度文本必须是完整句子本次变更同步规范了工具调用的呈现体验见 system-prompt.tsWhen accompanying a tool call with progress text, write a complete standalone sentence. Do not end tool-call preambles with : or as though the tool result will complete the sentence; omit the preamble when it adds no value.即进度文本必须是一个完整、自洽的句子不得以:/结尾制造“悬空前导”因为工具结果不会自动补齐冒号后的内容——这类悬空前导在持久化或作为模型上下文复用前会被规范化。这条规则同时约束了多语言中文冒号场景保证聊天记录与模型上下文的可读性。配置与验证配置入口输出相关的可调参数分布在两处终端工具TerminalExecTool构造参数maxOutputBytes、maxStderrBytes、maxArtifactBytes、timeoutMs宿主集成时通过createTerminalTools(options)注入terminal.ts代码执行持久化配置tools.codeExec下的maxOutputBytes/maxStderrBytes/maxSourceBytes/maxToolCalls/timeoutMsconfig.ts。测试印证tests/ekko-agent/tools.test.ts 对本机制覆盖较全bounds terminal output and saves the complete streams for paged inspection验证预览截断与产物保留caps persisted terminal artifacts while continuing to drain command output验证产物到达安全上限后文件只含前 64 字节且命令仍正常排空removes terminal artifacts when output stays within the context limit验证输出在限制内时tool-assets最终为空目录清理逻辑生效文本结果的请求级截断、read_file分页偏移、.ekko-tmp/.gitignore写入等均有对应断言。结语Ekko Studio 通过“预览有界、产物有上限、请求有兜底”的三层设计为 Agent 工具执行划定了一条清晰的资源边界命令输出再大模型请求中的文本始终被限制在 256 KB 内完整输出则以 25 MB/流的产物形式保存在被忽略的.ekko-tmp/tool-assets目录中配合read_file的offset分页随时可取磁盘故障或写入失败时预览与截断标记依然可用不会让整个工具调用失效。理解这一机制有助于在集成 Ekko Agent 时正确设置阈值、排查“输出被截断”类问题并为多 Agent 聊天与编码工作流中的长输出场景设计出可预期的资源模型。赞分享AI 应用人工智能AI Agent本地部署前端后端工作流自动化【免费下载链接】ekko-studioEkko Studio is a local-first AI workspace for multi-agent chat, coding, and visual workflows, available on desktop and the web.项目地址https://gitcode.com/gh_mirrors/he/ekko-studio点击查看免费下载相关推荐DeepSeek Harness 工具输出 spill 机制超大工具结果的有界预览与可检索落盘策略DeepSeek Harness 工具输出 spill 机制超大工具结果的有界预览与可检索落盘策略 工具输出需要在模型可见的上下文中保持有界但部分超大结果人工智能AI AgentAgent 框架DeepSeekKaTeX 安全模型解析从输出净化到 untrusted 输入的信任边界控制KaTeX 安全模型解析从输出净化到 untrusted 输入的信任边界控制 KaTeX 在浏览器与服务端将 LaTeX 渲染为 HTML 与 MathML前端Conductor Agent Guardrails 实战指南在输入、输出与工具边界构建可持久化的安全护栏Conductor Agent Guardrails 实战指南在输入、输出与工具边界构建可持久化的安全护栏 导读 Agent Guardrails护栏是后端流程编排工作流自动化微服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
