FormatMsg 渲染通用单行日志条目：[prefix] msg。

String 返回人类可读的模式名称，主要用于调试日志输出。

newTestModel 返回适合单元测试的 tuiModel（nil engine/skills，固定尺寸）。

Add 写入一条新记忆。内容签名已存在（未删除）时视为去重命中： 刷新 updated_at + 自增 use_count，返回既有条目，不插入新行。

WriteFile 写入文件，自动创建父目录。

Close 关闭传输层并释放资源。

applyUpdate 调用 m.Update(msg)，返回更新后的 tuiModel。 丢弃返回的 tea.Cmd（单元测试中不执行 Cmd）。

NewAgentEngine 创建新的 AgentEngine。默认值：maxTurns=500, toolTimeout=60s, generateRetries=3（base 1s）—— 对瞬时 LLM/流式错误具备基础韧性。

MakeToolCall 构造 schema.ToolCall 的辅助函数，简化测试数据准备。 args 应为合法的 JSON 字符串（如 `{"command":"ls"}`），直接转为 json.RawMessage。 不做 JSON 合法性验证（eval 场景传入的 args 均为字面量，省略

ReadFile 读取文件内容。

--- TokenBudgetCompactor tests ---

NewScriptedProvider 构造一个预设了响应序列的 ScriptedProvider。

Run 按序运行所有 Case，返回结果列表（长度与 Cases 相同，顺序对应）。 每个 Case 使用独立的工作目录，失败不影响后续 Case 的运行。

Err 返回 Failed 状态的错误原因（其他状态返回 nil）。

NewBashTool 创建绑定到指定工作目录的 Bash 工具实例。

Run 执行单个用户 prompt 的阻塞式主循环，文本输出到 stdout。

Name 返回工具的唯一标识符，用于 LLM 在 ToolCall 中引用此工具。 例如 "bash"、"read_file"、"edit" 等。

NewRegistry 创建并返回一个空的工具注册表实例。

NewTodoStore 创建空的 TodoStore，无任何初始任务。

Get 按 ID 返回条目（含已软删除的，便于审计）。不存在时返回错误。

Register 将一个 BaseTool 实现注册到工具表中。 若已存在同名工具，返回 error；原有工具保持不变。 调用方需根据 error 决定是替换、忽略还是终止启动。

Execute 处理 todo_write 工具调用： - 写操作（todos 非空）：执行防作弊校验后全量替换 TodoStore，返回写入后的列表 JSON。 - 读操作（todos 为空/省略）：直接返回当前 TodoStore 的列表 JSON，不修改状态。 防作弊校验逻辑： 1. 遍历新

NewReadFileTool 创建绑定到指定工作区的文件读取工具。

NewMockWithCallback 创建每次 Generate 调用都执行 fn 的 Mock Provider。

newTestStore 创建一个内存 SQLite Store，now 固定为可控时间。

Execute 执行工具逻辑。args 为 LLM 传递的原始 JSON 参数， 由具体工具实现负责反序列化和校验。 返回工具执行的文本输出，或失败时的错误信息。

fuzzyReplace 对文件内容执行多级模糊匹配替换（Multi-Level Fuzzy Matching）。 四级容错机制（Four-Level Fallback Pipeline）： L1 — 精确匹配（Exact Match）：sourceText 在原始内容中精确出现一次，直接替换

Create 为一个 Agent 创建独立 Sandbox，返回可用的 Environment。

NewTodoWriteTool 创建绑定到指定 TodoStore 的工具实例。 store 不得为 nil，否则 Execute 调用时会发生 panic。 opts 为可选配置，当前支持 WithPlanWriter 注入计划文件写入器。

Start 初始化传输层（如启动子进程）。返回 error 表示连接失败。

NewEditFileTool 创建绑定到指定工作区的文件编辑工具。 workDir 会被 filepath.Clean 清洗，确保路径规范化（Path Normalization）。

NewHookRegistry 创建包装 inner 的 HookRegistry，依次应用给定的拦截器。

NewRules 返回空规则集。

Run 同步执行一个子代理：构建隔离子引擎，调用 RunStream，消费事件流， 转发进度、桥接审批、累积最终文本。background 控制审批策略与执行 context。

AddRule 追加一批规则（相同 action，多个 pattern）。

NewRegistry 创建空的子代理定义注册表。

RunStream 是 Run 的流式对应方法，通过 Go channel 逐事件输出 agent loop 的运行状态。 内部启动独立 goroutine 运行共享 runLoop，channel 在循环结束后自动关闭。

Close 关闭数据库连接。

Execute 执行文件读取操作，支持行号模式（start_line/end_line）和字节偏移模式（offset/limit）。 设置了 start_line 时优先走行号模式。

FormatTokenCount 将 token 数格式化为人类可读字符串。 示例：45200 → "45.2K"，1200000 → "1.2M"，500 → "500"。

List 返回未删除、未过期的记忆，按 importance 降序、updated_at 降序排列，至多 limit 条。 供 Precis 渲染精华视图使用。limit<=0 时不限制。

NewManager 打开（或创建）指定路径的 SQLite 数据库，初始化 Schema。 父目录不存在时自动创建。

NewMemorySession 创建指定 ID 的内存会话。

NewSession 生成 UUID，在数据库中创建新会话记录，返回绑定该会话的 Session。

NewWriteFileTool 创建绑定到指定工作区的文件写入工具。 workDir 会被 filepath.Clean 清洗，确保路径规范化（Path Normalization）。

Next 返回 Shift+Tab 循环中的下一个模式：Default→Plan→AutoEdit→Default。 通过整数取模实现三值循环，新增模式时需同步更新取模数。

Read 读取 MEMORY.md 内容；文件不存在时返回空串（不报错）。

truncateUTF8 按字节截断 s 到 maxBytes 以内，同时保证不在多字节 UTF-8 字符中间截断。 实现策略：先强制截断到 maxBytes 字节，再从末尾反向逐字节扫描： - utf8.DecodeLastRuneInString 返回 (RuneError, 1) 表示末尾字

Evaluate 返回工具调用对应的第一条匹配规则动作，无匹配时返回 RuleAsk。

LoadSkills 扫描 skillsDir 下各子目录，在每个子目录中读取 SKILL.md 构建 Index。 skillsDir 不存在时返回空 Index（不报错），保证零配置可运行。 子目录缺少 SKILL.md、或 SKILL.md 的 frontmatter 缺少必填字段时跳过并记录

NewMock 构造并返回一个新的 mockProvider 实例。 turn 计数器从 0 开始，确保首次 Action 阶段调用触发 ToolCall 响应。 每个测试用例都应独立创建实例，避免状态污染。

NewNoopProviders 返回零开销的 noop 实现，供测试使用。

WithSession 绑定 Session，使 runLoop 在启动时加载历史、结束时保存新消息。

newClient 创建 Client，transport 由 Manager 根据 ServerConfig 构建。

readNextEvent 返回一个 tea.Cmd，该 Cmd 阻塞直到 ch 中有一个 Event， 然后以 eventMsg 形式递交给 Update。ch 关闭时递交 EventDone。

Allow 返回默认允许决策。

EstimateTokens 估算消息列表的总 token 数（字符数÷4）。 计算范围包含消息文本内容、工具调用参数（Arguments）和工具调用 ID（ToolCallID）。

DoneCount 返回已结束（完成+失败）任务数。

Execute 按洋葱模型依次执行 hook 链，中间调用内层 Registry.Execute。 决策优先级（每个 hook 依次评估）： - error → 立即短路，返回 IsError=true - HookActionDeny → 立即拒绝，跳过后续 hook 和

GetModelLimits 返回指定模型名称的上下文窗口限制。 查找前自动剥离 provider 前缀（如 "openai/gpt-4o" → "gpt-4o"）。 未知模型返回 256K 保守回退值。

RLockPath 对指定路径获取读锁（共享锁）。 多个读操作可以同时持有该锁，写操作会等待所有读锁释放。 返回一个解锁函数，典型用法： unlock := RLockPath(path) defer unlock()

Register 注册一个子代理定义。定义非法或重名时返回 error。

SetupHermeticEnv 配置标准 Hermetic（密封隔离）测试环境。 Hermetic testing 是软件工程中的标准实践：将测试与外部依赖完全隔断，确保测试结果 只取决于代码变更，不受网络状态、API 配额或密钥有效性影响。 具体操作： - 清除所有 _API_KEY / _

collectEvents drains a stream channel and returns all received events.

Ask 返回审批决策，携带原因和风险级别。

Compact 对 msgs 进行滑动窗口裁剪，返回裁剪后的切片。 边界修正：若窗口第一条消息是工具执行结果（ToolCallID != ""）， 向前回溯直到找到配对的 assistant 工具请求消息，保证上下文完整。

Generate 按序列返回预设 Turn 的回复；超出序列时返回默认终止回复。

NewTaskTracker 创建空 tracker。

State 返回当前容器状态（线程安全）。

WithApprovalFn 将 ApprovalFunc 注入 context，供 HookRegistry 在 BeforeExecute 后调用。

WithMaxTurns 设置单次 Run 允许的最大 Turn 数，0 或负数表示不限制。

newTestRunner 构造一个使用 mock provider、最小工具集的 Runner。

start 在流式响应首次出现某工具调用时记录 ID 和 Name。 重复调用相同 idx 会覆盖旧值（理论上不会发生，由 Provider 保证只在 *_start 时调用）。

DefaultConfig 从环境变量读取配置，未设置时使用内置安全默认值。

Execute 执行文件编辑操作。流程如下： 1. 反序列化 JSON 参数，提取路径、源文本和目标文本 2. 通过 safePath 校验并解析为绝对路径（含沙箱边界检查） 3. 读取源文件内容 4. 通过 fuzzyReplace 多级模糊匹配执行替换 5. 将结果写回文件

List 返回所有子代理定义，按 Name 升序稳定排序。

LockPath 对指定路径获取写锁（排他锁）。 写锁会阻塞所有其他读锁和写锁，确保原子性。 返回一个解锁函数，典型用法： unlock := LockPath(path) defer unlock()

NewPromptBuilder 创建绑定到指定工作目录和 Skills Index 的 PromptBuilder。 skillsIndex 为 nil 时，跳过 skills 段落注入。

Read 返回当前任务列表的副本（线程安全）。

SaveTodos 原子性保存任务列表（write-replace 语义）。items 为空时清空列表。

Search 用 FTS5 检索未删除、未过期的记忆，按相关度返回至多 limit 条。 命中条目执行强化：自增 use_count、更新 last_used_at。

Start 注册一个 Running 任务，返回唯一 id。

WithEnvironment 注入 sandbox.Environment，命令将路由到容器内执行。 env 为 nil 时无效（等同于不注入）。

WithSubAgentProgress 将 SubAgentProgressFunc 注入 context。

Write 原子性全量替换任务列表，返回替换后的列表副本。 先将入参复制到内部 slice，再返回内部 slice 的第二份副本： 双重复制确保调用方、内部存储与入参三者各自独立，互不影响。