把 FAILED / BLOCKED 任务恢复为 PENDING，并清空执行痕迹。 这是显式恢复动作，不是偷偷重跑。恢复原因会被保留下来，便于后续 Prompt 参考。

执行工具自身的具体逻辑。

执行一次 Generator-Agent 决策。 这里会根据当前已经走到第几步，动态调整 `execution_status`， 用 Prompt 明确告诉模型“现在应该继续取证，还是必须收口”。

运行顶层 Plan-Agent 循环。 这是全系统的最外层预算控制器： - 控制最大规划轮数； - 控制总运行时间； - 在任务全部 DONE 时提前结束； - 在预算耗尽时把未完成任务统一标成 BLOCKED。

执行一次 Plan-Agent 决策。 这个函数内部其实包含两种模式： 1. 还没有任务时：只能直接初始化任务或回复用户。 2. 已经有任务时：允许做少量只读侦察，再返回控制动作。

执行单个任务，内部串起 Generator 与 Validate。 这是第二层循环的入口。最外层的 Planner 只负责决定“该不该执行这个任务”， 真正怎样执行、失败后怎样重试，都在这里处理。

循环执行 Validate-Agent，并返回是否通过以及对应反馈。 这层循环的一个设计重点是“最后一步强制收口”： 验证器到了最后一步后，不再允许继续 read/glob/grep/bash，只能直接调用 `validate_tool` 给出判定，防止验证阶段无限拖延。

把 SKILL.md 拆成 frontmatter 和 markdown 正文。

打印阶段标题分隔线。

把可能很大的工具结果压缩成适合控制台展示的预览对象。

把 `inspect-codebase` 这类名字转成更适合标题展示的形式。

按任务名定位任务，并委托状态机完成合法性检查。

更新任务结论。 结论由 Executor 生成，但是否真正“完成”还要交给 Validator 判断。

按照 ToolSpec 中声明的简化 schema 做运行前校验。

根据策略检查已解析出的动作载荷是否合法。 这里会重点确认三件事：第一，`tool`、`parameters` 等字段本身格式 是否正确；第二，当前动作是否属于允许动作；第三，如果该动作定义了 schema，参数内容是否满足最基本的类型与枚举约束。只有全部通过， 才会

对动作参数做一层轻量级 schema 校验。 这里没有引入完整 JSON Schema 库，而是只实现教学示例当前真正需要的 几类校验：必填字段、字段类型、枚举值，以及可选的额外字段限制。 这样代码更容易读懂，也足够支撑 miniMaster 当前的动作协议。

挂载共享上下文，例如工作目录和系统信息。

构造统一的验证阶段未收口反馈。

执行指定工具，并把常见失败统一收敛成结构化结果。

按名称查找单个 skill；命中后返回带正文 instructions 的完整对象。

返回工具的结构化静态定义。

标记当前对象是否已经加载了 SKILL.md 正文。 这样 `load_all()` 可以只加载元数据，而 `find()` 在真正命中后再加载正文， 避免一次性把所有指令全文都塞进上下文。

清空最近动作记录。

读取指定文件；若未指定完整范围，则默认返回一个分段。 这里会先把相对路径解析到 workspace，再检查文件是否存在并执行读取。 这样模型在调用 `read` 时，无论当前进程从哪里启动，都能稳定读取到 预期目录中的文件。

在共享工作目录中执行命令，并返回标准化结果。 这里会先根据当前操作系统选择合适的底层 shell，再执行传入命令。 对 Windows 下最常见的一些 Unix 风格列表命令，还会做一层轻量 兼容转换，尽量避免因为命令习惯差异导致原本简单的任务失败。

根据 mode 选择写入策略，并返回写入字节数。 写入前会先把目标路径解析到 workspace，并在需要时自动创建父目录。 这样 Agent 可以直接写 `notes/result.md` 这类相对路径，而不用自己 先推断进程当前目录到底落在哪。

先读完整文件，再依次执行替换并一次性回写。 这里同样会先把相对路径解析到 workspace，保证编辑操作和读取、 搜索、写入工具对同一个相对路径指向同一个文件，不会因为启动目录 不同而改错位置。

执行 glob 匹配，并根据是否隐藏文件进行二次过滤。 相对模式会统一基于 workspace 解析，这样模型在不同工具之间使用 `.`、`*`、`src/**/*.py` 这类写法时，看到的都是同一个“当前目录”。 返回结果时再尽量转回相对路径，便

搜索文本模式；若可用，优先走 rg 后端以复用 ignore 规则。 设计成“两级后端”是这个工具最关键的教学点： - 有 rg 时：优先获得更快速度和更接近开发者习惯的 ignore 语义 - 没 rg 时：仍能用 Python 保底，保证项目可运