Definition 返回工具的元信息（ToolDefinition），包含名称、描述和参数 JSON Schema。 此信息会被转发给 LLM Provider，使模型了解工具的用途和参数格式。

Destroy 停止并移除指定 Sandbox。ID 不存在时静默返回 nil。

DockerID 返回 Docker container ID（线程安全）。

Execute 处理 memory_search 调用，返回命中条目的 JSON 数组（无命中返回 "[]"）。

Expired 报告条目相对 now 是否已超过 TTL。TTLDays<=0 视为永不过期。

FormatLoopEnd 渲染 agent loop 正常结束日志。

FormatLoopStart 渲染 agent loop 启动日志（含配置参数）。

FormatTurnStart 渲染每个 Turn 的头部日志。

GenerateStream 流式 LLM 调用，Span 在 channel 关闭后结束。 langfuse.input 在流开始前写入；langfuse.output 在 StreamChunkDone 后写入。

List 返回所有任务的快照（创建顺序）。

Name 返回工具标识符 "todo_write"。

Name 返回适配器的工具名（mcp__{server}__{tool} 格式）。

Name 返回工具标识符 "use_skill"。

NewFileHook 创建从文件按需加载规则的 PermissionHook。 每次工具调用时重新读取文件，使 writeApprovalToConfig 写入的白名单立即生效。

NewMemoryWriteTool 创建写入工具。precis 可为 nil。

NewTaskTool 创建 task 工具。

Notify 发送 JSON-RPC 通知（无 ID，不等待响应）。

OnTurnEnd 在每个 Turn 结束时调用（工具执行完毕后）。

ReapOrphans 清理上次进程崩溃遗留的孤儿容器（label=harness9=1，全部状态）。 原实现只清理 status=exited 的容器；进程被 SIGKILL 强杀时 defer 不运行， 容器会以 Running 状态残留——持有已删除 tmpDir 的 bind mount，

ResolveTools 给定全部可用工具名集合，返回子代理实际可用的工具名集合： 1. Tools 非空 → 取 Tools∩all；Tools 为空 → 取 all 2. 移除 DisallowedTools 3. 永远移除 "task"（防递归，无论是否在白名单）

RunBash 在本地以子进程方式执行 bash 命令。

SaveRules 将当前规则集写回 JSON 配置文件（覆写）。 用于"总是允许"动态更新白名单。 注意：序列化后重新加载时，规则顺序重置为 deny→allow→ask（LoadRules 固定顺序）， 与原始插入顺序无关。若业务逻辑依赖精确的跨类型顺序，应避免使用 SaveRules 后再

SetNotify 设置完成通知回调（TUI 注入），Finish 时触发。

SetSession 替换当前绑定的 Session，供 TUI /new、/resume 命令切换会话时调用。 线程安全：可从任意 goroutine 调用（如 TUI goroutine），内部以写锁保护。 注意：修改对当前正在运行的 runLoop 无影响（runLoop 在入口快照 sess

Statuses 返回所有 Server 的状态快照（线程安全）。

Update 实现 tea.Model——处理所有消息。

WithEngineObserver 注册引擎生命周期观察者，供可观测层（OpenTelemetry 等）无侵入接入。

WithMemoryExtractor 注入长期记忆提取器，在每次压缩摘要前从 head 消息提取持久事实。

WithPlanMode 设置 Agent 的初始执行模式。 runLoop 在启动时会快照此值，循环内不会受后续 SetPlanMode 调用影响。

WithTodoInjector 在摘要末尾注入活跃任务列表，防止 LLM 在上下文压缩后遗忘未完成任务。

WithTodoStore 绑定 TodoStore，使引擎在 runLoop 生命周期中自动执行以下操作： - 启动时：从 Session 恢复 TodoStore 状态（跨会话续接未完成任务） - 结束时：通过 defer 将 TodoStore 保存到 Session（所有路径均执行）

WithToolResultsDir 设置工具输出 offload 文件的根目录。 设置后，DeleteSession 会删除对应 session 的 offload 子目录。

WithToolTimeout 设置单个工具执行的超时时间，0 表示使用 context 原始截止时间。

WithUpdateNotify 设置状态变更通知回调，供 TUI 通过 channel 接收更新。 必须在首次 Create 调用之前设置。内部用 m.mu 保护，并发安全。

WriteFile 向本地文件系统写入文件，自动创建父目录。

appendSubAgentUpdate 把一条子代理进度更新合并/追加到 subAgentLines（delta 合并、tool_start 带参数、错误提示）。 由 EventSubAgent（主引擎转发的后台/Task 工具进度）与 subAgentDirectMsg（@agent 前台直跑进

appendUserNudge 返回在历史副本末尾追加一条 user nudge 消息的新切片。 不修改入参、不持久化——nudge 仅对当轮发送给 LLM 的临时副本可见。

assemblePage 组装最终输出字符串，超出 maxChars 时追加截断标记。 截断点优先对齐到最后一个换行符（保证段落完整），并在 UTF-8 rune 边界处截断， 避免切断多字节字符（如中文、emoji）产生无效 UTF-8。

buildCompactedResult 将 system 消息、LLM 摘要文本和尾部消息组合为压缩后的消息列表。 Compact 和 CompactForce 共用此方法，避免重复拼装逻辑。

buildSystemPrompt 返回 system prompt 字符串。 若设置了 PromptBuilder 则委托给它，否则回退到内置默认文案。

confirmPlanReview 处理审查对话框的确认操作，cursor 0-3 对应四个选项。 由 Enter 键（光标位置）和 Esc 键（强制选项 3）调用。

convertMessages 将内部 schema.Message 转换为 Anthropic SDK 的消息参数格式。 Generate 和 GenerateStream 共享此方法。 转换规则： - schema.RoleSystem → 提取为独立的 systemPrompt 返回值（

convertMessages 将内部 schema.Message 转换为 OpenAI SDK 的消息参数格式。 Generate 和 GenerateStream 共享此方法，避免重复的转换逻辑。 转换规则： - schema.RoleSystem → openai.SystemMess

convertTools 将内部 schema.ToolDefinition 转换为 Anthropic SDK 的工具参数格式。 通过 extractSchemaFields 提取 properties 和 required 字段。 返回 nil 表示无工具可用（用于 Phase 1 Thinki

convertTools 将内部 schema.ToolDefinition 转换为 OpenAI SDK 的工具参数格式。 返回 nil 表示无工具可用（用于 Phase 1 Thinking 的 nil tools 场景）。

copy 返回 s.items 的副本。调用方必须持有读锁或写锁后才能调用此方法。 空列表时返回 nil（而非空切片），与 json.Marshal 的行为兼容（nil → "null"，[]{} → "[]"）。 注意：TodoItem 是值类型（无指针字段），浅拷贝即为完整独立副本。

decodeUDDG 从 DuckDuckGo 重定向 href 中提取真实目标 URL。 DDG 的链接格式：/l/?uddg=ENCODED_URL&rut=...

defaultBootstrapCmd 返回"可配置·默认自举"路线下的默认依赖安装命令（接通 sandbox.BootstrapCmd 接缝）： 恢复 pip（精简镜像可能无 pip）→ 以 editable 模式安装当前仓库及其依赖 → 确保 pytest 存在。 全程 best-effort（

encodeJSONNoEscape 使用 json.Encoder 重新编码原始 JSON，关闭 HTML 字符转义 （SetEscapeHTML(false)），可选启用 indent。indent=true 时使用两个空格缩进。

extractBinary 从 .tar.gz 中提取名为 binaryName 的文件到 destPath。

extractPlainText 是 go-readability 失败时的兜底实现。 使用 golang.org/x/net/html tokenizer 跳过 script/style，提取可见文本。

flushPendingReply 将 pendingReply 用 glamour 渲染并替换 lines 中的原始文本。

formatTaskLog 把任务全过程日志格式化为展示行（与 subAgentLines 风格一致）。

ftsQuery 把用户查询转换为安全的 FTS5 MATCH 表达式： 按空白分词，每个 token 作为双引号短语（内部双引号翻倍转义），以 OR 连接。 无有效 token 时返回空串。

get 返回 idx 对应的累积器，不存在时按需创建并写入集合。

getOrCreatePathLock 获取或创建指定路径的 pathLock，并将引用计数 +1。 调用方必须在操作完成后调用 releasePathLock。

dispatch 以指定 prompt 启动一次 agent 推理流（RunStream）。 调用时 running 必须为 false；若已有推理在进行（running == true）则静默返回， 防止多路 goroutine 并发驱动同一个 AgentEngine。 autoExecuti

isInteractiveCmd 检查命令行的首个 token 是否为已知交互式程序。 对绝对路径命令（如 /usr/bin/vim）使用 filepath.Base 提取文件名后再匹配， 防止因路径前缀导致的漏判。

leadingWhitespace 返回字符串开头的空白前缀（空格 / Tab）。

looksLikeTestRun 用启发式判断 cmd 是否在运行测试套件，用于验证关卡。 这是宽松启发式：先排除明显的安装语境（pip install，其中也含 pytest）与只读探索命令 （grep/cat/ls/find/head/tail 开头），再匹配测试运行特征子串。偏向"宁可少判"—

makeTestIndex 在临时目录创建子目录结构的 skill 并返回 Index。

moveOrCopy 尝试 os.Rename；若跨设备则回退到 copy + 显式 close（确保写入完整）。

newTUIModel 构造已初始化的 tuiModel：输入框聚焦，spinner 使用 Dot 样式。

nullTTL 将 0 映射为 NULL（永不过期），否则返回天数。

panelRowCount 统计字符串在终端中实际占用的行数。 末尾无 \n 时最后一行也计入（与终端渲染一致）。

parseLine 解析单行 KEY=VALUE 格式，返回键、值和是否有效。 支持：去除引号、去除前后空白、跳过无等号的行。

providerEnvInt 读取整型环境变量，缺省/非法时返回 def。

providerMaxRetries 返回 SDK 内置重试次数（默认 5，高于 SDK 默认 2）。 覆盖批量评测下常见的 429 限流；SDK 会自动遵循 Retry-After。env: LLM_MAX_RETRIES。 注意：SDK 重试仅覆盖首字节到达前的错误，流式中途断连由引擎层 Wit

providerRequestTimeout 返回单次 LLM 请求的超时（默认 600s）。 用于防止"连接已建立但服务端中途挂起、字节不再流动"的请求吞掉整个实例预算； 取值需远小于实例级超时、又足够长以容纳一次完整生成。env: LLM_REQUEST_TIMEOUT_SECS。

queryEntries 是 List/StaleCandidates 共享的多行查询执行器。

readFileCallMock 返回一个 mock：第 1 个 turn 发起一次 read_file 工具调用， 之后的 turn 返回最终文本。用于驱动子代理实际执行一次工具，触发权限审批链。

readNextSubAgentDirect 读取一条直跑消息并投递给 Update；ch 关闭时投递终止 done。

realCmdRunner 调用真实的 docker CLI，返回 stdout+stderr 合并输出（去首尾空白）。

recordMetrics 将耗时、token 用量写入 Span 属性和 OTEL Metrics。 token 用量同时写入 harness9 自定义属性和 GenAI 语义约定属性，确保 Langfuse 正确识别。

releasePathLock 将指定路径的引用计数 -1，减到 0 时从全局 map 中删除。

renderThinkingLines 将推理文本按段落分割并在 width 内 word-wrap，每行加 " │ " 前缀并应用暗色样式。 width 为终端列数（m.width）；0 时回退为不折行。

runLoop 是 Run 与 RunStream 共享的主循环内核。

sampleByRepo 按 repo 分组，每组随机取最多 n 条，打乱后返回。

serializeOutput 将 LLM 响应消息序列化为字符串，供 langfuse.output 属性使用。 若响应包含工具调用则序列化工具调用列表；否则返回文本内容。

setInputAttrs 在 Span 上写入 langfuse.observation.input 和模型相关属性。 Langfuse v4 要求 observation 级别的 input 使用 langfuse.observation.input。

shortDockerID 截取 Docker container ID 前 12 位供展示使用。

simulateResponse 根据 tools 参数和内部 turn 计数器生成确定性响应。 行为： - tools 为空（Thinking 阶段）：返回深度思考文本 - tools 非空，turn==1：返回 bash 工具调用请求 - tools 非空，turn>1：返回纯文本最终回复（触发

splitLines 按换行符分割，去除末尾空行后返回切片。

streamOnce 驱动一次 RunStream，把所有事件以可读格式写入 w，并返回本次是否运行过测试。 ranTest 通过对 bash 工具调用的 command 应用 looksLikeTestRun 启发式判定。

summarize 调用 LLM 对 head 消息生成结构化摘要字符串。 若 head 中已包含上次摘要（summaryMarker），则执行增量更新。

textContent 递归提取节点下所有文本内容。