DrainCompleted 返回已完成但尚未注入 LLM 的任务结果，并标记为已注入（幂等，不影响 List）。

Execute 加载并返回指定 skill 的全文内容。

FormatJSON 把原始 JSON 渲染为人类友好的日志字符串。 行为： - 空输入 → "{}" - 短 payload (≤ argInlineThreshold 字节) → 单行内联展示 - 长 payload → pretty-print 多行，每行前补统一 Indent 注意：Go

Get 返回单个任务详情（Log 深拷贝，避免与后台写入竞态）。

ID 返回环境的唯一标识符（UUID 或 "local"）。

InjectTools 将所有已连接 Server 的工具注入 Registry，命名格式为 mcp__{server}__{tool}。 工具冲突时记录警告并跳过，不中断注入流程。返回成功注入的工具总数。

Label 返回 TUI 状态栏展示的模式标签文本。 PlanModeDefault 返回空字符串，不在状态栏显示额外标签（默认模式无需提示）。 非默认模式返回带括号的标签，与状态栏其他字段通过分隔符区分。

LoadConfig 从指定路径读取 .mcp.json。文件不存在时返回空 Config（不报错）。

NewExtractor 创建绑定到指定 Generator 与 Store 的提取器。

NewHTTPTransport 创建 HTTPTransport。

NewHook 创建基于内存规则集的 PermissionHook（用于测试）。

NewMCPToolAdapter 构造 MCPToolAdapter。 - serverName: MCP Server 配置名（如 "context7"） - toolName: MCP 工具原始名称（如 "resolve-library-id"） - description: 工具描述（直接

NewWebFetchTool 创建生产用的 WebFetchTool（含完整 SSRF 检查）。

OnInteractionStart 启动顶层 interaction Span，注入 session.id 和初始 prompt 属性。 同时通过 trace.ContextWithSpan 将 Span 显式写入 OTEL span slot， 确保后续 tracer.Start 调用能正确获取

OnTurnStart 启动 turn-level Span（interaction Span 的子节点），将其存入 ctx。 在调用 tracer.Start 之前，先将 interaction Span 显式恢复到 OTEL slot， 确保 turn Span 的 parent_span_id

OpenSession 打开已有会话；session 不存在时返回错误。

Regenerate 从 Store 拉取 top-N 条目，渲染为 markdown 并写入 MEMORY.md（含父目录创建）。

RunCase 运行单个评估 Case，返回 Result。 内部流程： 1. 确定工作目录（Case.WorkDir 或自动创建临时目录） 2. 构造最小化 AgentEngine：ScriptedProvider + 四个基础工具 + recordingHook 3. 调用 eng.Run 执

Send 发送 JSON-RPC 方法调用并阻塞等待响应（ctx 超时或取消时提前返回）。

Stop 停止并移除容器：docker stop（带宽限期）→ docker rm → StateTerminated。 docker stop 失败不视为致命错误，仍继续执行 docker rm 以确保资源回收。 已处于 Terminated 或 Failed 状态的容器调用 Stop 直接返回

SubAgentProgressFromContext 从 context 提取 SubAgentProgressFunc，未设置时返回 nil。

WithGenerateRetry 配置 LLM 生成调用的应用层重试：最多尝试 attempts 次， 首次重试退避 baseDelay，其后指数增长（上限 maxGenerateRetryDelay）。 这是对 SDK 内置重试的补充：SDK 的重试只覆盖"首字节到达前"的连接错误， 而流式响

WithPlanWriter 注入 PlanWriter，每次写入 TodoStore 成功后调用 Write。 pw 为 nil 时等同于不注入（无操作）。

WithPromptBuilder 设置自定义 PromptBuilder。未设置时使用内置默认文案。

extractContent 从 HTML 流中提取主内容，返回 Markdown 格式字符串，截断至 maxChars。

find 按 id 查找（调用方须持锁）。

hasHTMLClass 检查节点是否包含指定 CSS 类名。

loadDataset 从 JSONL 文件加载所有 instance。

newTestFetchTool 创建绕过 SSRF 检查的 WebFetchTool（专供测试使用）。 生产代码始终使用 NewWebFetchTool()，其中 safetyCheck = isSafeURL。

parseAgentFile 解析一个 agent Markdown 文件内容（YAML frontmatter + 正文）。 frontmatter 之后的正文作为 SystemPrompt。未包含合法 frontmatter 时返回错误。 支持字段：name、description、tools

renderFooter 渲染底部快捷键提示行，提示内容按以下优先级选取： 1. Shell 模式：固定展示 enter/esc/ctrl+c 及"输出自动注入"说明 2. 补全提示（completionHint != ""）：Tab 补全候选列表 3. 手动滚动（viewTop ≥ 0）：含百分

renderInput 渲染底部输入行，根据当前模式切换提示符样式。 - Shell 模式：" [SHELL] $ <textinput>"（深橄榄徽章 + 绿色 $ 提示符） - Plan Mode： " › <textinput>"（琥珀黄 › 提示符） - Default 模式："

scrollBy 将视口向上（delta<0）或向下（delta>0）移动 delta 行。 viewTop=-1 表示自动跟随底部；到达底部时自动切回 -1。

--- Shell 模式 UI 视觉状态测试 --- triggerShellModeDetection 通过一次 KeyRight 消息（不修改输入内容）触发 Update 末尾的 textinput 更新路径，从而激活 shellMode 检测逻辑。 KeyRight 未在 switch msg

BeforeExecute 评估工具调用并返回对应 HookDecision。

BeforeExecute 检查 bash 工具的命令参数，匹配到高危模式时返回 Ask。

BuildReport 从 Results 列表聚合生成 SuiteReport。 自动计算全局和分类通过率，将 Failure/Warning 序列化为字符串列表。

Close 释放环境持有的所有资源。

DB 返回底层 SQLite 连接，供长期记忆（ltm.Store）等共享同一连接复用。 调用方不得关闭该连接——其生命周期由 Manager.Close 统一管理。

DeleteSession 删除指定会话及其所有消息（通过 ON DELETE CASCADE）。 若设置了 toolResultsDir，还会级联清理对应 session 的 offload 子目录。

DestroyAll 并发停止所有活跃 Sandbox，程序退出时调用（defer）。

EditFileWithEnvironment 注入执行环境（当前文件工具通过 bind mount 无需路由，预留扩展）。

EstimateToolTokens 估算工具定义列表的 token 用量（字符数÷4）。 工具 Schema 在工具数量较多时可能消耗 20-30K+ token，预飞检查（preflight）时必须纳入计算。

Execute 解析参数、执行搜索并格式化输出。

Extract 从 msgs 提取持久事实并 upsert 到 Store。任何环节出错仅记日志，不阻断调用方。

FormatForInjection 将 pending 和 in_progress 状态的任务格式化为纯文本， 供 SummarizationCompactor 在上下文压缩后注入摘要消息末尾， 防止 LLM 在长对话压缩后遗忘尚未完成的任务。 实现了 memory.TodoInjector 接

FormatToolStart 渲染"工具启动"日志条目。 参数： - logPrefix: 调用方日志前缀（如 "engine" / "engine-stream"），与所属循环对齐。 - turn: 当前 Turn 编号。 - tc: 工具调用请求（含 Name、ID、

Generate 阻塞式 LLM 调用，用 SpanLLMRequest Span 包裹完整请求周期。 在 Span 上写入： - langfuse.input = 序列化的消息列表（Langfuse Input 字段） - langfuse.output = LLM 响应文本或工具调用（Lang

ListSessions 按 updated_at 降序返回所有会话元数据（含消息条数）。

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

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

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

Name 返回断言的唯一标识名称，用于失败报告和日志。格式惯例：action(arg)，如 tool_called(bash)。

NewManager 创建 Manager，config 来自 LoadConfig。

NewMemorySearchTool 创建检索工具。

NewObservabilityHook 初始化 metrics 仪器，返回可用的 ObservabilityHook。

NewRunner 从配置构造 Runner。

NewWebSearchTool 创建默认使用 DuckDuckGo 的搜索工具实例。

PurgeExpired 将所有已过 TTL 的未删除记忆软删除，返回回收条数。 同时将 signature 置为 NULL（与 SoftDelete 一致），释放唯一约束槽位， 使相同内容在未来可以重新被添加（否则 Add 的签名去重会将其视为既有记录）。

ReadFileWithEnvironment 注入执行环境（当前文件工具通过 bind mount 无需路由，预留扩展）。

String 返回状态可读名（用于 TUI 展示）。

Update 按 e.ID 更新标题/内容/分类/重要度/TTL/标签，重算签名并刷新 updated_at， 同步重建该条目的 FTS 索引。条目不存在时返回错误。

Validate 校验定义合法性。错误信息不以大写开头、不以句号结尾。

WithBashTimeout 设置单条 bash 命令的默认超时（覆盖 defaultBashTimeout）。 用于 SWE-bench 等需要运行较慢测试套件/安装命令的场景（如 300s）。 d <= 0 时忽略，沿用默认值。

WithContextWindow 设置模型的最大 context window（tokens），用于 TUI token 使用率展示。 通常通过 provider.GetModelLimits(modelName).ContextTokens 获取。

WithLongTermMemory 注入长期记忆精华读取器（返回 MEMORY.md 物化视图内容）。 reader 在每次 Build() 时被调用，确保注入的精华始终反映最新写入；返回空串时跳过整段。 仅在 LTM 启用时调用。

WithMemoryNudge 配置长期记忆 nudge：每隔 interval 个 turn 在发送给 LLM 的历史中 注入一行 text 提示（仅注入到临时副本，不持久化）。interval<=0 时关闭。

WithThinkingBudget 启用 Anthropic extended thinking，并设置推理 token 预算上限。 budget 为 0 时禁用 extended thinking。 Anthropic API 要求 budget_tokens ≥ 1024，小于该值时自动提升到

WriteFileWithEnvironment 注入执行环境（当前文件工具通过 bind mount 无需路由，预留扩展）。

appendPrediction 将单条 Prediction 追加写入 predictions.jsonl（立即 flush）。

dispatchMention 解析 @<name> <task> 并前台直跑指定子代理（绕过主 LLM）。

flushPendingThinking 追加 thinking 块结束行，并重置 thinking 缓冲和行索引。 调用后 pendingReplyStart 更新为当前 lines 长度，后续 action 文本从此处开始。

fuzzyReplaceWithLevel 在 fuzzyReplace 基础上额外返回命中的匹配层级（matchExact..matchLineByLine）， 供调用方据此调整结果可信度提示（精确匹配可声明权威，模糊匹配建议复核）。

getenvOr 从环境变量读取 key，未设置或为空时返回 fallback。

handleMCPPanelKey 处理 MCP 工具面板（模态）的键盘输入。 - Esc → 关闭面板，返回对话视图 - e / E → 暂停 TUI，打开 .mcp.json 配置文件（$EDITOR 或系统关联程序） - ↑ / k → 向上滚动工具列表 - ↓ / j → 向下

loadExistingIDs 读取已有的 predictions.jsonl，返回"已成功产出非空 patch"的 instance_id 集合。 文件不存在时返回空 map（不报错），支持首次运行。 仅当 model_patch 非空时才视为"已完成"并在 --resume 时跳过；空 pat

mustJSON 将值序列化为 JSON 字符串，失败时返回空对象。

noopProviders 返回零开销的 noop 实现。 tracer 使用 trace/noop，meter 使用 metric/noop，两者均不依赖全局 OTEL provider， 确保即使在全局 provider 未初始化时也能安全调用。

parseDDGResults 解析 DuckDuckGo HTML 响应，提取搜索结果列表。

resolveModelName 解析最终使用的模型名：cfg.Model > LLM_MODEL 环境变量 > 默认值。 与 newProvider 保持相同的优先级逻辑，用于填写 predictions.jsonl 的 model_name_or_path。

sendNotify 在持有锁之外调用通知回调，避免死锁。

splitList 把逗号分隔的字符串拆为去空白的非空项切片。

transportType 推断传输类型。

AfterExecute 结束 Span，写入工具结果（langfuse.output），记录耗时与次数 metrics。 若 result.IsError 为 true，在 Span 上记录错误属性。 透传 result，不修改工具执行结果。

BeforeExecute 启动工具执行 Span，写入工具名和参数（langfuse.input），注入开始时间。 始终返回 HookActionAllow，不拦截工具执行。

Calls 返回所有已记录的 LLM 调用列表（线程安全）。