把 Agent 动作定义统一成 ToolSpec。 这样“控制动作”和“真实工具”都能复用同一种结构描述，便于后续统一渲染成 Prompt 文本和 OpenAI tools schema。

把超长文本裁成适合放进 Prompt 记忆的预览片段。

把多行文本压缩成适合单行展示的摘要。

把单条记忆渲染成统一的一行摘要。

返回任务列表副本，避免调用方直接改写内部列表。

把若干行文本渲染成 bullet 列表。

保存最近一次失败、阻塞或重试提示。

抛出统一格式的解析错误，便于上层直接展示。

按任务名查找单个任务。

把反馈写入 Generator 工作记忆，供下一轮直接读取。

记录一步新记忆，并先对参数/结果做面向 Prompt 的压缩。

把多行或过长文本压缩成便于控制台展示的单行摘要。

返回最近的系统反馈记忆。

尽量把绝对路径还原成相对 workspace 的展示路径。 工具内部通常会把路径解析成绝对路径，便于稳定访问文件系统； 但返回给 Agent 时，过长的绝对路径不够直观。因此这里会在路径位于 workspace 内部时，尽量转回相对路径，便于模型阅读

把路径参数解析成基于 workspace 的绝对路径。 工具层允许模型传入相对路径，例如 `main.py`、`./docs`、`logs/*.txt`。 同时也允许更贴近用户习惯的 `~/Desktop/test.txt`、`%USERPROFILE%\\Desk

稳定地把对象序列化成字符串。

保留一个更直观的别名，方便上层调用。

统一压缩任务文本字段里的多余空白。

打印 Agent 本轮选择的动作及参数。

把单条记忆结果压成适合 prompt 阅读的一行摘要。

按不同视图渲染 prompt 上下文。

返回最近的非反馈执行记忆。

从单个 skill 目录加载 skill package。

完成“调用模型并拿到合法动作”这一整套流程。

用统一编码写文本文件。

构造单个固定阶段的静态上下文。 `uses_runtime_tool_specs=True` 的含义是： 如果某个动作名同时也是实际运行时工具（例如 `read` / `grep`）， 那么它的输入 schema 应优先复用工具层定义，避免 Prompt 协议和工具实现脱节

收集 skill 目录下某类资源文件的相对路径。

从 rg JSON 输出里提取 text/bytes 字段。

对 Planner 输出做最小必要清洗，不再注入隐式任务。 这个函数只做“收口格式”的工作，不偷偷补全业务含义。 这样便于教学时区分： - 哪些内容来自模型的明确决策； - 哪些内容只是本地代码做的格式规范化。

把 validate_tool 返回的条目列表压成去重后的标准文本。

压缩多余空白，便于去重和比较。

解析 frontmatter 中的标量文本。

判断路径是否应该在 Python 回退搜索里被忽略。

把文本压成适合 Prompt 摘要展示的长度。

向任务列表尾部追加单个任务。

把动作策略转换成 OpenAI Chat Completions 可直接使用的 tools 定义。 对于像 `respond_to_user`、`validate_tool` 这样的内部控制动作，schema 直接来自动作定义；对于 `read`、`grep` 这类真实运行时工具，

生成统一的重复动作反馈。

清空当前工作记忆。

执行真正的运行时工具。 控制动作（如 `init_tasks`、`subagent_tool`）不应该混入工具执行链； 只有真正访问文件系统/命令行的动作才会走到这里。

返回记忆对象副本。

返回最近一条系统反馈。

返回当前工具系统共享的工作目录。 相对路径解析、命令执行 cwd 以及“当前目录”语义都依赖这一路径。 因此由 ToolService 统一对外暴露，比让上层模块各自维护更稳妥。

检查总运行时长预算是否还有剩余。

判断某条记忆是否属于系统反馈。

判断当前动作在最近若干步内是否已经重复出现。

记录最近若干次动作签名。

把动作列表渲染成适合放进 Prompt 的文本。

打印任务终态报告。

若总运行预算已耗尽，则把当前任务标为 BLOCKED 并返回 True。

集中封装 Task 构造，确保所有入口生成的字段格式一致。

从字符串或对象任务里提取并清洗 task_name。

读取当前任务；若任务意外丢失则记录告警。

区分“显式 schema”与默认空对象 schema。 空对象 schema 在这里被视为“未声明参数结构”，这样上层就还有机会去工具注册表里补全。

遍历 library 根目录下合法的 skill 子目录。

读取 frontmatter 必填字符串字段，并做空值校验。

把任务状态统一归一成大写字符串。

尽量把绝对路径转换成相对 workspace 的展示路径。

尽量从自然语言要求中切出更细的完成项。 它会依次处理： - 多行文本 - 行首列表符号 - 行内序号 - 过长逗号串联句子的再次拆分

把参数稳定序列化成适合签名比较的字符串。

打印单步执行标题。

构造 Agent 动作签名。

把任务完成条件归一成便于逐项核对的清单。

构造 Planner-Agent 的 user prompt。 这份 Prompt 的重点不是告诉 Planner 如何写代码，而是告诉它： - 当前任务面板是什么样 - 目前掌握了哪些项目理解 - 是否还允许继续侦察 - 每个控制动作的边界是什么

构造 Planner 需要的 prompt 上下文。

把任意工具输入/输出压缩成更适合放进工作记忆的结构。 这里不是简单截断，而是按数据类型做差异化压缩： - dict: 只保留前若干字段，并对关键字段单独裁剪 - list: 只保留前若干项 - str: 截成预览片段

在上下文超限时，把较早步骤压成确定性摘要。 压缩策略是“保留最近若干步原文 + 把更早内容总结成摘要”， 这比简单丢弃旧步骤更适合长时运行场景。

把任务列表转成更适合日志和 Prompt 的字典结构。

返回当前平台下 `bash` 工具实际使用的底层命令 shell 名称。 这个信息本质上属于 BashTool 自身的运行知识，因此应由工具层维护， 而不是由主循环去猜测。这样无论后续底层实现改成 PowerShell、cmd、 bash 还是其他

判断任务是否已经进入终态。

把所有未进入终态的任务标记为阻塞。

按任务卡片结构打印关键信息。

把 checklist 渲染成可直接塞进 Prompt 的 bullet 文本。

把本轮记忆压成适合下次 retry 复用的摘要。

把较长列表压成有限的 bullet 预览。

渲染工具说明文本，供 Prompt 直接复用。

把单个任务安全地转成 payload；空任务直接返回 None。

对单个任务执行受控状态迁移。 这个函数是状态变更的唯一入口。谁想改任务状态，都应该通过它先过一遍规则检查。

批量校验多个 skill 目录，并汇总退出码。

验证单个 skill 目录是否符合 MVP skill package 结构。

把阶段名统一映射成日志和 Prompt 中使用的 agent 名。

把剩余侦察预算翻译成更明确的 Prompt 约束文本。

在验证器分类不完整时，生成发回 Generator 的纠偏提示。

统一生成总预算耗尽时的提示文案。

尽量把搜索目标转成相对 workspace 的路径，方便 rg 继承 ignore 规则。

根据当前平台构造底层 shell 调用参数。 Windows 使用 PowerShell，是为了让 `ls`、`dir`、`Get-ChildItem` 这类常见命令都能按用户直觉工作；类 Unix 环境则使用 bash， 继续保持原先“执行一段 s

把 add_task 动作参数整理成和 init_tasks 同构的任务对象。

集中声明合法状态迁移规则。 这里最重要的教学点是：不是所有模块都能任意改状态。 例如： - planner 只负责调度，不直接改任务状态； - retry 只能把 FAILED/BLOCKED 拉回 PENDING； - runner 才负责真正的执行态推进

根据递归开关、include_pattern 和 ignore 规则收集待搜索文件。

在验证通过后，把任务收束到 DONE 并清空阶段性记忆。

先统计总行数，便于后续按稳定范围分段读取。

先统计文件总行数，再按块扫描，避免一次性把全文装入内存。

隐藏仅用于占位的空对象 schema。

返回 bash 工具实际使用的底层命令 shell 名称。

处理 Executor 提交的结论，并立即触发 Validator 复核。