timeoutBanner 返回一条清晰、机器可读的超时提示，供 LLM 调整策略。

truncateUTF8 将 s 截断到不超过 maxBytes 字节，保证不切断多字节 rune， 截断时追加省略标记。

verifySHA256 从 SHA256SUMS 文件中找到 tarballName 对应的期望摘要，与实际文件比对。

waitMCPUpdate 返回一个 tea.Cmd，阻塞等待 mcpCh 发来更新后触发 mcpUpdateMsg。

waitSandboxUpdate 返回一个 tea.Cmd，阻塞等待 sandboxCh 发来更新后触发 sandboxUpdateMsg。

writeSummary 将运行摘要写入 cfg.OutputDir/run_summary.md，记录 RunID 与 seed 以支持复现。

ActiveCount 返回 (active, total) 两个计数： - active：pending 和 in_progress 状态的任务数（即尚未完成的任务） - total：TodoStore 中的全部任务数 TUI 续跑逻辑（autoExecuting）使用此方法判断是否仍有待执行的

AfterExecute 是空操作，原样返回结果。

AfterExecute 对 DangerHook 是空操作，原样返回结果。

BeforeExecute 对 OffloadHook 是空操作。

Close 对 HTTP 传输无需额外清理。

ConfigFromEnv 从环境变量读取 OTEL 配置，返回 Config 实例。 环境变量： - OTEL_ENABLED = "true" 启用（其他值视为关闭） - OTEL_SERVICE_NAME = "harness9"（默认） -

Definition 返回工具元信息，包含描述和 JSON Schema 参数定义。

Definition 返回工具的元信息，包含描述和 JSON Schema 参数定义。 LLM 会根据此定义决定何时调用该工具以及如何构造参数。

Definition 返回工具的元信息，包含描述和 JSON Schema 参数定义。 LLM 会根据此定义决定何时调用该工具以及如何构造参数。

Definition 返回工具定义，供 LLM Provider 了解工具的用途和参数格式。

Execute 调用 MCP Server 的对应工具，透传 LLM 提供的 JSON 参数。

FormatObservation 渲染工具执行结束后的 Observation 注入日志。

FormatParallelTools 渲染并行工具执行开始日志。

FormatTurnDone 渲染 Turn 无工具调用时的任务完成日志。

GetAvailableTools 直接委托给内层 Registry。

NewNoopProvider 返回一个无操作的 Provider。

NewStdioTransport 创建 StdioTransport。command/args 指定子进程命令；env 为额外环境变量。

OnInteractionEnd 在 runLoop 退出时调用（defer 保证执行）。turns 是实际执行的轮数。

OnInteractionStart 在 runLoop 入口调用，返回可携带 Span 的增强 ctx。

OnPreCompress 在上下文压缩前从待压缩消息中提取记忆。

OnSessionEnd 在会话结束时执行收尾固化。

OnTurnStart 在每个 Turn 开始时调用，返回本 Turn 的增强 ctx（LLM 调用和工具调用均继承此 ctx）。

Prefetch 在每个 turn 前按 query 预取相关记忆（语义检索）。

ReadFile 从本地文件系统读取文件内容。

Register 直接委托给内层 Registry。

RunCLI 启动交互式 REPL，从 os.Stdin 读取用户输入。 idx 不为 nil 时，支持 /skill-name 斜杠命令直接加载技能正文。 直到 ctx 取消、用户输入 exit/quit 或 EOF 时返回。

RunTUI 以 AltScreen 模式启动 Bubbletea 程序。 用户按 Ctrl-C/Ctrl-D（空闲时）退出后返回。

RunUpgrade 检查并升级 harness9 到最新版本。 currentVersion 由编译时 ldflags 注入（如 "0.0.2"）；本地开发构建为 "dev"。

Send 发送 HTTP POST JSON-RPC 请求并等待响应。

Setup 根据 cfg 初始化 OTEL tracer 和 meter。 若 cfg.Enabled=false 或 cfg.Exporter=noop，返回零开销的 noop 实现。 对 OTLP exporter： - endpoint 和 headers 均由 cfg 显式传入（不依赖 SD

StaleCandidates 识别清理候选：importance<=1 且 use_count=0 且 60 天未更新的未删除条目。 当前为 Phase 3 接缝——供未来的 Consolidator（Dreaming 巩固）消费，主流程暂未调用。

Start 对 HTTP 传输无需特殊初始化（HTTP 是无状态的）。

Start 并发连接所有已配置的 MCP Server，超时时间为每个 server 30 秒。 所有连接结果（成功或失败）均在方法返回前完成（wg.Wait），结果写入 m.status。 设计原则（fail-soft）：单个 Server 连接失败不影响其他 Server，也不导致整体启动失败

Stop 关闭所有活跃的 MCP Server 连接。

String 返回状态的可读名称，供 TUI 展示。

String 返回 PermissionMode 的可读名称。

Sync 在每个 turn 结束后同步对话数据给提供者。

WithIncludeReasoning 在每次请求中注入 include_reasoning=true， 使 OpenRouter 在流式响应的 delta.reasoning 字段中返回推理内容。 对不支持此参数的后端无副作用（参数被忽略）。

WithMaxConcurrentTools 设置同一 Turn 内最大并发工具数，0 或负数表示不限制。

WithNotify 注册状态变更回调（用于 TUI 实时更新）。调用线程不限。

WithOffloadEnabled 在 system prompt 中添加 context offload 检索指引。 仅在 OffloadHook 已配置时调用。

WithPermissionMode 设置 AgentEngine 的权限模式。

WithPreviewLines 设置 context 中保留的预览行数（默认 20）。

WithSandboxContext 启用 Sandbox 执行环境提示。 当启用时，在 system prompt 中添加 Sandbox 特定指引，说明可用的环境能力。

WithTodoEnabled 在 system prompt 中添加 todo_write 工具的使用指引。 仅在 todo_write 已注册时调用。

WriteJSON 将报告序列化为 JSON，写入 path。 自动创建父目录（权限 0755），使用 MarshalIndent 保证可读性。

WriteMarkdown 将报告渲染为 Markdown，写入 path。 包含：总计行、按类别统计表格、每个 Case 的详细结果（含失败消息和效率警告）。 分类统计按名称字母序排列，确保输出稳定可 diff。

activeStatusBarStyle 返回当前模式下的状态栏容器背景样式。 三种背景色通过不同色调给用户强烈的视觉区分信号： - shellMode=true → 深绿底（shellStatusBarStyle, bg #22 / fg #120） - Plan/AutoEdit 模

applyCompactionWith 对消息列表应用压缩策略。comp 为 nil 时原样返回。

bannerContent 返回欢迎页的完整 Banner 内容（ASCII Art + 副标题 + 快捷键提示 + 分隔线）。 width 为终端宽度，用于居中 ASCII Art 和计算分隔线长度。

baseURLEnablesReasoning 判断给定的 base URL 是否为需要 include_reasoning=true 才会暴露推理内容的 OpenAI 兼容网关（OpenRouter、Requesty）。 baseURLEnablesReasoning reports whethe

buildChildRegistry 构造子代理的隔离工具注册表：仅注册定义允许的基础工具 （永不含 task），再包权限派生 hook + denyTaskHook + sharedHooks（danger/offload）。 baseTools 参数允许调用方传入经 sandbox 包装后的工具

buildMentionHint 为 @ 前缀生成子代理建议提示：列出名称匹配的子代理及其截断描述。 与 buildCompletionHint 的 / 分支同构：Tab 循环中用缓存列表（高亮选中项），否则按前缀实时匹配。

buildTarGz 在内存中构造一个包含单个文件的 .tar.gz，返回其字节内容。

commonStringPrefix 返回 a 与 b 的最长公共前缀。

connect 根据 ServerConfig 构建 Transport 并执行连接握手。

convertToFunctionParameters 将 JSON Schema interface{} 转换为 OpenAI SDK 的 FunctionParameters 类型。 优先路径：若 input 已是 map[string]interface{}，直接类型断言（无内存分配）。 回退

cycleCompletion 处理 Tab 键：首次进入补全模式，或在匹配列表中循环切换。 补全顺序：内置命令优先，其次 Skills。

dispatchShellCommand 处理用户侧 "!<cmd>" Shell 命令执行。 执行流程： 1. 空命令直接返回（重新聚焦输入框） 2. 追加 "$ cmd" 行到 Scrollback（先于执行结果显示，提供即时反馈） 3. isInteractiveCmd 检测：命中则追加错误

duckDuckGoSearch 向 DDG HTML 端点发送 POST 请求并解析结果。

executeTools 并发执行所有工具调用，每个工具带有独立的超时控制。 通过预分配切片 + 索引写入保证结果顺序与 ToolCalls 一致。

extractArgString 为规则匹配提取可读的参数字符串。 bash 工具提取 command 字段；其他工具使用原始 JSON 字节。

extractDDGResult 从单个 result div 节点中提取标题、URL 和摘要。

extractFinalOutput 从 ScriptedProvider 的脚本序列中提取最终文本输出。 从末尾向前遍历，返回第一个满足"无工具调用且有文本"的 Turn 的 Text。 若脚本序列全为工具调用（无纯文本 Turn），返回通用终止文案"任务完成。"。 这反映了 ReAct 循环的

extractMessage 从 Anthropic SDK 的 ContentBlockUnion 切片中提取 schema.Message。 遍历所有 Content Block，合并 text 类型的文本和 tool_use 类型的工具调用。

extractMessage 从 OpenAI SDK 的 ChatCompletionMessage 中提取 schema.Message。 过滤非 function 类型的 ToolCalls，统一转换为 schema.ToolCall。