extractSchemaFields 从 JSON Schema map 中提取 properties 和 required 字段。 同时兼容 []string 和 []interface{} 两种 required 数组类型， 后者在 JSON 反序列化为 interface{} 时常见。

filterReadOnlyTools 从工具定义列表中过滤出 planModeWhitelist 中的子集， 在 Plan Mode 下替代完整工具列表传递给 LLM。 使用工具层硬约束而非 prompt 层软约束，确保 LLM 无论在何种上下文状态下都无法访问被过滤的工具。

generateID 生成 16 位 hex 格式的随机 Sandbox UUID（crypto/rand，无冲突）。

generateWithRetry 在 em.generate 之上叠加有界指数退避重试。 重试策略： - 成功立即返回； - context 已取消/超时（ctx.Err()!=nil）不重试，原样返回（会话级终止信号）； - 其余错误视为可能瞬时，退避后重试，直到耗尽 attempts； -

getenvIntOr 从环境变量读取整型 key，未设置/非法时返回 fallback。

handleApprovalKey 处理审批对话框的键盘输入。

handleEvent 处理单个 engine.Event，返回更新后的模型和下一个 tea.Cmd。

handleNewSession 创建新会话，替换引擎绑定，刷新状态栏。

handleResumeList 列出历史会话供用户选择。

handleResumeSelection 处理用户在 resume 选择模式下的输入。

hasProgressTool 判断本轮工具调用中是否包含进展工具。

hintsSection 在存在 hints_text 时返回带标题的注入段，否则返回空串（省略整段）。

isApproved 报告当前工具调用是否已在前置 hook 中获得人类审批。

isExplicitlyAllowed 报告当前工具调用是否已被前置 hook 规则显式放行。

isGitRepo 检测 workDir 是否包含 .git 目录/文件。

isSafeURL 校验 rawURL 是否允许发起 HTTP 请求。 检查链：scheme → userinfo → DNS 解析 → IP 段检查。 DNS 解析失败时 fail-closed（拒绝请求），防止 DNS rebinding 攻击。

isSensitivePath 检查绝对路径是否落在硬编码敏感目录下。

isValidUTF8 检查字符串是否是合法 UTF-8 序列。

isValidUTF8 报告 s 是否是合法的 UTF-8 编码字符串。

killProcessGroup 向以 pid 为 pgid 的整个进程组发送 SIGKILL。 要求 setPgid 已在 Start() 时被调用（pgid == 启动进程的 PID）。

lineByLineReplace 将文本按行切割，去除首尾空白后进行滑动窗口匹配（Sliding Window Matching）。 应用场景：LLM 提供的 source_text 与文件中实际内容的缩进不一致时， 通过逐行去缩进实现模糊匹配（Indent-Agnostic Matching）

loadHistoryWith 从 sess 加载历史消息，注入 system prompt 和当前用户输入。 sess 为 nil 时退化为原有行为（全新 contextHistory）。 返回完整历史切片和新消息的起始索引（用于 saveHistoryWith）。

mcpPanelLineCount 计算 renderMCPPanel 的滚动内容区实际行数，用于滚动上界控制。 必须与 renderMCPPanel 的实际输出保持一致：仅当 t.Description != "" 时才计描述行。

newProvider 根据模型名创建 LLM provider。 优先级：cfg.Model > LLM_MODEL 环境变量 > 默认值 openai/gpt-4o-mini。

newUUID 生成随机 UUID v4。

normalize 折叠空白、小写化、去除首尾空白，得到稳定的去重基准串。

openMCPConfigCmd 暂停 TUI 并打开 .mcp.json 配置文件供用户手动编辑。 优先使用 $EDITOR（终端编辑器，TUI 挂起等待退出），否则使用系统关联程序打开（后台）。

parseFacts 解析 LLM 输出的 JSON 数组，容忍 ```json ``` 代码围栏包裹。

parseInputSchema 将 json.RawMessage 转换为 map[string]any，供 LLM Provider 使用。 若解析失败，返回空 schema，不阻断工具注册。

parseOTLPHeaders 解析 "key1=val1,key2=val2" 格式的 header 字符串。 按 OTEL 规范：每对以 "," 分隔，key/value 以第一个 "=" 分隔（value 中可含 "="）。

parseTestIDs 把 SWE-bench 中"JSON 编码为字符串的测试 ID 数组"（如 `["a::b","c::d"]`） 解析为 []string。空字符串、空数组或非法 JSON 均返回 nil（容错，调用方据空判断不可用）。

preflight 在启动前验证必要条件，任一失败则终止程序。

readFileByLines 按行号读取文件内容（1-based，含两端）。 endLine 为 0 表示读到文件末尾，但最多读 maxLineRead 行。

readLoop 在后台持续读取子进程 stdout，按 ID 将响应路由到对应的 pending channel。

reindentBlock 将多行 target 重新缩进到 baseIndent 基准。 算法：先求所有非空行的最长公共空白前缀（target 自身的基准缩进）， 逐行剥离该公共前缀后改用 baseIndent，从而保留行间相对缩进、把整体对齐到文件中 被替换块的缩进层级。纯空白行归一化为空行。

renderApprovalDialog 渲染工具执行审批对话框。 在 approvalPending == true 时由 View() 插入 StatusBar 之前。

renderCompactProgress 渲染 /compact 命令执行期间的 spinner 进度行。 与 renderToolProgress 风格一致：spinner + 动词 + 操作名称。

renderConversation 将消息扁平化为文本，供提取 prompt 使用。

renderConversation 渲染对话历史区（Scrollback）。 scrollH 为可显示行数（由 scrollHeight() 计算）。

renderMCPBar 渲染 MCP Server 状态栏，仅在有 MCP Server 时显示。 格式: [MCP] context7 ● 2 tools │ other-server ✗ failed

renderMD 通过 glamour 将 Markdown 文本渲染为终端 ANSI 格式。 降级策略：任何错误均原样返回原文。 故意不使用 glamour.WithAutoStyle()：该选项会发送 OSC 11 终端颜色查询， 终端将响应写回 stdin，Bubbletea 的 texti

renderPlanReviewDialog 渲染 Plan Mode 完成后的审查选择对话框（带圆角边框）。 对话框在 planReviewing == true 时由 View() 插入到 StatusBar 之前， ↑↓ 移动光标，Enter 确认，Esc 取消。

renderPrecis 将条目渲染为 markdown，并在 maxBytes 处按 UTF-8 边界截断。

renderSandboxBar 渲染 Sandbox 状态栏，仅在有活跃 Sandbox 时显示。 格式: [Sandbox] 3a2f (main) Running │ 7b1c (sub-1) Running

renderSubAgentProgress 渲染当前活跃子代理的流式进度块（暗青色缩进行）。 仅在 len(m.subAgentLines) > 0 时由 View() 调用；每行已在 EventSubAgent 处理时带上 [agent] 前缀。

renderTaskPanel 渲染后台任务面板：taskDetailID 为空渲染列表，否则渲染该任务详情日志。

renderTodoLines 将 TodoItem 列表渲染为结构化多行文本，追加到 Scrollback（m.lines）。 输出格式：标题行（图标 + "Tasks" + 进度统计 + 活跃任务数）+ 分隔线 + 各任务行。 每个任务行包含：序号、状态图标（✔/▶/○/⊘）和内容文本。 状

renderToolProgress 渲染工具执行进度行。 仅在 phaseChat && running && currentTool != "" 时调用。

runBootstrap 在独立的 BootstrapTimeout 预算内执行一次性初始化命令（fail-open）。

runInSandbox 通过注入的 Environment 在容器内执行命令。 超时处理说明：DockerEnvironment.RunBash 内部将 docker exec 的失败（含 ctx 取消/超时） 转换为错误字符串返回（err==nil）。这里显式检查 ctx 是否因超时取消， 追

runInstance 对单个 SWE-bench instance 执行完整的 clone → sandbox → engine → patch 流程。 任何环境错误都返回 RunResult.Error，不 panic。

runLocal 在本地进程中执行命令（Sandbox 关闭时的原有路径）。

runShellCmd 返回异步执行 Shell 命令的 tea.Cmd。 Bubbletea 运行时会在独立 goroutine 中调用此函数返回的闭包，不阻塞主消息循环。 执行结果以 shellResultMsg 形式发回主消息队列，由 Update() 处理。 实现细节： - 通过 bas

runWithVerificationGate 执行 agent loop 并将完整 trajectory 写入 logPath， 在 Agent 自然结束却"全程未运行过任何测试"时，注入一次续跑提示要求真实验证（验证关卡， 轨迹分析 R2）。续跑复用同一引擎 + 内存会话（历史完整延续），且至多

saveHistoryWith 将本次 Run 新增的消息（msgs[startLen:]）写回 sess。 sess 为 nil 时为 no-op；失败仅打 warning 日志，不中断主流程。

serializeMessages 将消息列表序列化为 JSON 字符串，供 langfuse.input 属性使用。 保留 role、content 和 tool_calls，截断超长内容。

setPgid 将子进程放入独立进程组（pgid == child pid）。 配合 killProcessGroup 可一次性终止 npx 及其所有后代进程（如 node）。

shortPath 将绝对路径中的 $HOME 替换为 "~"。

streamGenerate 驱动 Provider.GenerateStream，将 text_delta 转发为 EventActionDelta， 最终返回 StreamChunkDone 中的完整 Message 和实际 token 用量供 runLoop 消费。

trimToValidUTF8Prefix 去掉字符串开头可能被切碎的不完整 UTF-8 字节。

trimToValidUTF8Suffix 去掉字符串末尾可能被切碎的不完整 UTF-8 字节。

truncate 截断字符串，超出 maxLen 字节时追加 "..."。 截断位置对齐合法 UTF-8 字符边界，避免截断多字节字符中间位置。

unquote 去除值两端成对的单引号或双引号。

unquote 去除值两端成对匹配的引号。仅当首尾引号字符一致（同为 " 或同为 '）时才去除， 避免误删除不匹配的引号。

updateTodoBlock 在对话流末尾追加最新 todo 快照。 每次 todo_write 完成后调用，快照追加在工具完成行之后，呈现实时进度。

utf8RuneStart 报告字节 b 是否是一个 UTF-8 rune 的起始字节。

withApproved 在 context 中标记当前工具调用已由前置 hook 经过人类审批（用户点击"允许"）。 后续的 HookActionAsk hook 检查到此标记后直接跳过，避免对同一次工具调用重复弹出审批对话框。

withExplicitlyAllowed 在 context 中标记当前工具调用已被前置 hook 规则显式放行（如白名单命中）。 语义上区别于 withApproved（人类实时审批）：此处是规则系统的静默放行，无需人类介入。 后续 HookActionAsk hook 遇到此标记同样跳过审批，

wrapToolsWithSandbox 为标准工具注入 sandbox.Environment，非标准工具原样返回。 工具名字符串（"bash"/"read_file" 等）与各 Tool.Name() 方法返回值耦合； 若工具名变更，此处需同步维护。

writeApprovalToConfig 将审批的工具调用写入白名单配置文件（"总是允许"持久化）。

AddMessages 在事务中批量插入消息，并更新会话的 updated_at。

AfterExecute 透传工具执行结果，不做任何修改。

BeforeExecute 记录工具调用名称，始终返回 HookActionAllow（不拦截任何工具）。

Build 组装子代理的完整 system prompt。

Build 组装并返回完整的 System Prompt 字符串。