confirmApproval 处理审批确认，cursor 0-4 对应五个选项： 0 = 允许（仅本次） 1 = 允许（本会话不再提示） 2 = 总是允许（写入白名单） 3 = 拒绝 4 = 拒绝并提供反馈

renderMCPPanel 渲染 MCP 工具管理面板（模态）。 contentH 是滚动内容区可用的行数，由调用方根据终端高度计算，以确保面板撑满屏幕。

safePath 将用户输入的相对路径解析为绝对路径，并校验是否在工作区范围内。 这是防止路径遍历攻击（Path Traversal Attack）的核心安全屏障： 任何试图通过 "../" 逃逸工作区的路径都会被拒绝。 参数： - workDir: 工具允许访问的根目录（Sandbox B

summarizeTool 根据工具名对参数进行智能截断摘要，用于 ToolProgress 展示。

Compact 压缩消息历史至 MaxTokens 预算内，始终保留 system 消息和最近 MinTailMessages 条消息。

Finish 标记任务完成（isErr 决定 Done/Failed），记录最终文本，并触发完成通知。

IsEmpty 报告 Index 中是否不包含任何 skill。

NewOffloadHook 创建写入 workDir/.harness9/tool_results/sessionID/ 的 OffloadHook。

NewUseSkillTool 创建绑定到指定 Index 的 use_skill 工具。

Signature 计算内容的去重指纹：SHA256(normalize(content))。

Summary 返回 skills 索引的纯文本摘要，格式为每行 "- name: description\n"。 供 PromptBuilder 注入到 System Prompt，实现 Progressive Disclosure。

WithCompactor 绑定上下文压缩策略，在每次 LLM 调用前裁剪历史消息。

extractReasoningContent 从 OpenAI 兼容流式 chunk 的原始 JSON 中提取推理内容。 两种字段格式均支持： - choices.0.delta.reasoning_content — DeepSeek-R1 原生格式 - choices.0.delta.rea

handleTaskPanelKey 处理任务面板模态按键：列表态 ↑↓ 选择 / Enter 进详情 / Esc 关闭； 详情态 ↑↓ 滚动 / Esc 回列表 / Ctrl+T 关闭。

newContainer 构造处于 Pending 状态的容器实例，run 可注入 mock 便于测试。

newPromptBuilder 创建子代理 PromptBuilder。loader 为 nil 时不加载 skills。

newTransport 根据 ServerConfig 创建对应的 Transport 实例。

parseFrontmatter 解析 Markdown 文件开头的 YAML frontmatter 块。 返回 name、description、trigger 和 frontmatter 之后的 body。 文件不以 "---\n" 开头或缺少闭合分隔符时，视为无 frontmatter，bo

renderStatusBar 渲染常驻状态栏（model 名 + mode + workdir + session 信息）。 宽度充足时展示完整 session ID；窄终端（< 120 列）时截断为前 8 位加 "…"。

resolvePrompt 处理斜杠命令和普通输入，返回最终传给 LLM 的 prompt。 返回 false 表示本次输入已处理完毕（如斜杠命令找不到技能），不需要调用 LLM。

scrollHeight 返回对话区域可显示的行数。 运行中且有活跃工具时额外保留 1 行给 ToolProgress。

sendEvent 向 Event channel 发送事件，同时感知 context 取消。 返回 false 表示 context 已取消，调用方应立即退出。 终止事件（EventDone / EventError）应使用直接 ch <- 而非本函数，以确保消费者收到。

sendStreamChunk 向 StreamChunk channel 发送 chunk，同时感知 context 取消。 使用 select 监听 ctx.Done()，确保在 context 被取消时（如超时或手动中断） 不会阻塞在 channel 发送上，避免 goroutine 泄漏。

Compact 在 token 超出预算时调用 LLM 摘要旧消息，返回压缩后的消息列表。

Execute 执行文件写入操作。流程如下： 1. 反序列化 JSON 参数，提取目标路径与文件内容 2. 通过 safePath 校验并解析为绝对路径（含沙箱边界检查） 3. 自动创建父级目录（若不存在） 4. 以 0644 权限覆盖写入文件

Execute 根据 ToolCall 中的工具名称查找并执行对应工具， 返回封装后的 ToolResult（包含输出或错误信息）。

FormatOutput 将任意字符串渲染为多行块状文本（Block-Style）： 超出 MaxOutputLen 时截断；每行以 "│ " 起头并对齐到 Indent，便于扫读。 参数： - s: 原始字符串内容（如工具 stdout、文件片段等）。 返回值： - body: 格式

Generate 将对话历史和可用工具定义发送给 LLM，返回模型的完整响应 Message 和 token 用量。 参数: - ctx: 控制底层 HTTP 调用的取消和超时 - messages: 完整的对话上下文，包含 system prompt、之前的 user/assistant 消息、

GenerateStream 以流式方式调用 LLM，通过 channel 逐 chunk 返回响应增量。 参数与 Generate 完全一致。返回的 channel 中每个 chunk 代表 LLM 的一次增量产出： - StreamChunkTextDelta: 文本增量（逐 toke

Get 按名称查找子代理定义。

GetAvailableTools 返回所有已注册工具的 ToolDefinition 列表， 供 LLM 在 Generate 调用时了解可用工具集。

GetTodos 返回该会话已持久化的任务列表。无任务时返回 nil, nil。

ListAll 返回所有活跃 Sandbox 的只读快照（线程安全）。

Load 从指定路径的 .env 文件读取配置并设置为环境变量。 只有在进程环境中完全未定义的变量才会被设置；已存在的变量（包括值为空字符串的变量）不会被覆盖。 如果文件不存在，返回 nil（非错误），使程序可以在没有 .env 文件时仍正常运行。

LoadFromDir 扫描 dir 下的 *.md 文件，解析为子代理定义并注册。 语义： - 目录不存在：静默返回 nil（零配置可运行） - 单文件解析失败 / 缺必填字段：跳过并记录 warning，不中断 - 缺 name：回退用文件名（去 .md） - 文件定义覆盖同名编程式定义（记录日

LoadRules 从 JSON 配置文件加载规则。文件不存在时返回空规则集（非错误）。 评估顺序：deny 优先 → allow → ask。

NewLocalEnvironment 创建本地进程执行环境。

NewOTELEngineObserver 构造 OTELEngineObserver，初始化 turns 计数器。 ForceFlush 直接从 Providers 获取，不经过全局 provider wrapper，确保 100% 可用。

NewOpenAIProvider 创建并返回 OpenAIProvider 实例。 从环境变量读取 OPENAI_API_KEY 和 OPENAI_BASE_URL 完成认证配置。 当 OPENAI_BASE_URL 中包含 "openrouter" 时自动启用 includeReasoning，

NewTokenBudgetCompactor 创建针对指定 context window 大小的 TokenBudgetCompactor。 MaxTokens 自动设为 contextWindow 的 80%。

NewTracingProvider 构造 TracingProvider，初始化三个 metrics 仪器。 modelName 对应 gen_ai.request.model 属性，用于 Langfuse 模型展示。

Reset 重置 provider 状态（可复用于多次运行）。

appendArgs 把参数 JSON 的部分片段追加到 idx 对应累积器的缓冲区。

buildEditSummary 根据编辑前后的内容构建带改动上下文的成功提示， 帮助 Agent 无需额外 read_file 调用即可直接验证改动是否正确。 使用公共前缀/后缀算法（不依赖外部库）定位变更区域，并以 unified diff 风格输出： - 改动前的 3 行上下文（无前缀） -

finalize 按 Index 升序重组累积结果为 ToolCall 列表，供 StreamChunkDone 携带。 返回 nil 表示流中没有工具调用（不应作为错误处理）。 关键修正：先收集实际存在的 key 再升序遍历，而非假设 key 从 0 连续。 Anthropic 流中 index

newTestManager 创建使用 mock runner 的 Manager，不真实启动 Docker。

newToolCallAccumulators 创建空的累积器集合。

runCLI 是 RunCLI 的可测试内核，允许注入任意 io.Reader 作为输入源。

truncateAttr 净化并截断字符串，确保满足 OTEL/protobuf string 字段的两个约束： 1. 必须是合法的 UTF-8（工具输出可能含有 binary 数据） 2. 长度不超过 maxSpanAttrLen 字节

AfterExecute 检测输出大小，超阈值时写入文件并替换 result.Output 为摘要引用。 文件路径在 workDir 内，摘要中展示相对路径，LLM 可直接用 read_file 工具读取。 写入失败时 fail-open：原样返回原始结果，不中断 agent loop。

Connect 执行 MCP 握手（initialize → notifications/initialized → tools/list）。 超时由调用者通过 ctx 控制（建议 30s）。

FormatToolDone 渲染"工具完成 / 工具失败"日志条目。 参数： - logPrefix: 调用方日志前缀。 - turn: 当前 Turn 编号。 - tc: 原始工具调用请求。 - result: 工具执行结果（含 Output、IsError）。

GetFullContent 按名称懒加载指定 skill 的全文内容（frontmatter 之后的 body）。 skill 不存在时返回包含可用名称列表的可读错误信息，供 LLM 自愈。

Names 返回所有已加载技能的名称列表，按 LoadSkills 扫描时的目录顺序排列。 主要用途：TUI Tab 补全（`/skill-name` 输入时枚举候选项）。 每次调用返回新切片，调用方可安全修改（不影响 Index 内部状态）。

NewDangerHook 创建使用默认高危模式列表的 DangerHook。

NewFilePlanWriter 计算 plan 文件路径，创建目录，并返回 FilePlanWriter。 通过检测 workDir/.git 判断是否为 git 项目。 若目录无法创建则立即返回错误，实现启动时快速失败。

NewManager 创建 Sandbox 管理器。

NewPrecis 创建绑定到指定 Store 与文件路径的 Precis。maxBytes<=0 时默认 5120。

NewStore 在给定连接上初始化 LTM schema（幂等），返回 Store。

NewSummarizationCompactor 创建针对指定 context window 大小的 SummarizationCompactor。 MaxTokens 自动设为 contextWindow 的 80%；MinTailMessages 默认 6。

OnInteractionEnd 结束 interaction Span，记录总 turns 数。 随后立即调用 ForceFlush，确保本次 interaction 的所有 span 在等待 batcher 定时前就被推送。

OnTurnEnd 结束 turn Span，增加 turns 计数。

RunBash 执行 bash 命令，返回合并的 stdout+stderr。 命令执行失败（非零退出）时返回 (errorString, nil)，保持 Self-Correction Loopback 语义。

RunningCount 返回运行中任务数。

SanitizeMCPName 将工具或服务器名中的非字母数字字符替换为下划线， 确保生成的工具名（mcp__{server}__{tool}）在 Registry 中合法且唯一。 该函数同时被 mcp.Manager（构建 ToolDetails）复用，两侧保证命名一致。

SetPlanMode 线程安全地更新当前执行模式。TUI Shift+Tab 键调用此方法。 注意：修改对当前正在运行的 runLoop 无影响（runLoop 在入口快照 planMode 值）， 仅在下一次 Run/RunStream 调用时生效。

SoftDelete 将条目标记为 disabled（不物理删除，保留审计），并移出 FTS 索引。 同时将 signature 置为 NULL，释放唯一约束槽位，使相同内容可在未来重新被添加。

TurnIndex 返回当前已消耗的 Turn 数量（线程安全）。

View 实现 tea.Model——根据当前 phase 渲染完整 TUI 帧。

WithSandboxContext 在子代理 system prompt 末尾注入 Sandbox 执行环境说明。

WithStallNudge 配置停滞 nudge：当连续 window 个"使用了工具但未调用任何进展工具 （edit_file/write_file）"的 turn 后，向发送给 LLM 的历史副本注入一次 text 提示， 然后重置计数。用于打断"反复静态重读却不收敛"的空转（SWE-benc

WithThreshold 设置触发 offload 的字符数阈值（默认 10000）。

Write 将 todos 序列化为 markdown 并覆写计划文件。 写入失败时返回 error（调用方决定是否记录日志，不中断主流程）。 目录已在构造时由 NewFilePlanWriter 创建，此处无需再次检查。

accentStyle 返回当前执行模式对应的强调色样式（accent style）。 优先级（高→低）：Shell 模式 > Plan Mode > Default。 Shell 模式优先级高于 Plan Mode 的原因：用户激活 Shell 模式时需要即时视觉反馈， 即使当前是 Plan M

buildCompletionHint 根据当前输入生成状态栏的补全提示文字。 空输入、非斜杠命令、或处于 resume 选择模式时返回 ""。 内置命令附带描述，Skills 仅显示名称。

effectiveTimeout 返回本次执行采用的超时：单次 timeout_secs（钳制到 maxBashTimeout）优先， 否则用工具配置的 timeout，最后回退到 defaultBashTimeout。

newMockTransport 创建预填 initialize 和 tools/list 响应的 mockTransport。

repairOrphanedToolPairs 在压缩后执行双向工具对完整性修复（HermesAgent 模式）： 1. 删除无对应 tool_call 的孤立 user tool_result 消息 2. 为缺少响应的 assistant tool_call 插入占位 user tool_resu

setState 线程安全地更新状态与错误原因。

thinkingWordWrap 将 text 按 width rune 数折行，保留词边界。 超过 width 的单个词（如 URL）会被强制截断，避免溢出终端宽度。 width <= 0 时不折行，整段作为单行返回。

truncateOutput 在输出超过 maxOutputLen 时同时保留头部与尾部（UTF-8 安全）。 关键设计：测试运行器（pytest / go test 等）的 verbose 进度在前、而最关键的 FAILED/AssertionError/traceback 与 "=== N f

--- LoadSkills tests --- writeSkillFile 在 dir/<name>/SKILL.md 路径写入 skill 文件内容的测试辅助函数。

AppendLog 向指定任务追加一条进度日志。任务不存在时静默忽略。

ApprovalFnFromContext 从 context 中提取 ApprovalFunc，未设置时返回 nil。

Build 返回注入了 problem statement、maintainer hints 和 workDir 的完整 system prompt。 HintsText（维护者讨论）此前被 dataset 解析却从未注入——而它常含决定性的最终 API 设计 （如 flask 选 `text=T

CallTool 调用指定工具，返回文本输出。 args 是 LLM 传入的原始 JSON 参数，直接透传给 MCP Server（无需二次解析）。

Deny 返回拒绝决策，携带原因。