执行非结论类动作，并把结果写进 Generator 工作记忆。

处理 Executor 重复动作，把两类反馈都写回 generator memory。

阻止对终态任务直接再次执行。

按 1-based 行号范围惰性返回文件片段。

返回全部内置工具定义；可按分类过滤。

从 workspace 根目录读取简单 ignore 规则。

当重试预算耗尽后，把任务最终标记为 FAILED。

实现一组足够支撑教学示例的 ignore 规则匹配。

判断一个值是否符合简化后的 schema 类型定义。 由于这里只覆盖最常见的 JSON 类型，所以实现保持轻量。单独拆成 私有函数后，`validate_schema` 的主体逻辑会更清楚，学生也更容易看懂 “参数校验”到底是怎么一步步完成的。

实现一套覆盖当前工具系统需求的基础 JSON 类型映射。

统一格式化 rg 后端错误。

把 frontmatter 中的字符串/字符串列表统一成 tuple[str, ...]。

把 actor 统一归一成小写非空字符串。

解析 `tags: [a, b]` 这种内联列表形式。

把 bash 工具结果压成 returncode 与 stdout/stderr 预览。

把 glob 工具结果压成文件/目录计数与少量预览。

把 grep 工具结果压成“命中概览”而不是完整命中列表。

把 read 工具结果压成“文件 + 行号 + 片段”的摘要结构。

读取正整数配置；为空、非法或非正数时都回退到默认值。

按 1-based 行号范围惰性读取文件内容。

提炼最近完成任务的结论，帮助 Planner 建立累计项目理解。

提炼失败/阻塞信号，让 Planner 避免重复踩坑。

从已完成任务中抽取“已经确认过的项目事实”。

把 skill 资源数量渲染成简短文本。

把 rg 返回的路径恢复成稳定绝对路径。

执行单轮尝试，直到任务完成、阻塞、丢失或需要再次重试。

当 rg 不可用时，回退到 Python 搜索，并尽量跳过 ignore 路径。

若 rg 可用，则优先用它执行搜索并继承 ignore 规则。

按最直观的状态顺序选择下一个任务。 当前调度策略非常简单： - 如果有 RUNNING，优先续跑它； - 否则取第一个 PENDING。 这也提醒读者：miniMaster 的重点在 harness 结构，而不是复杂调度算法。

优先执行 Planner 指定的任务；否则回退到默认调度顺序。

把 ChatCompletionMessage 中的关键信息整理成便于排错的字符串。

判断当前报错是否适合从 required 降级到 auto 后重试。 某些模型/模式下，`tool_choice="required"` 可能与服务端约束冲突。 这里做一次有条件降级，是为了提升示例代码在不同后端上的兼容性。

过滤掉教学里通常不值得优先看的噪声目录和缓存文件。

去掉成对包裹的引号，保留其余原文。

校验单个字段的类型和枚举范围。

递归打印目录树。

打印 Planner 级别的轮次标题。

按固定内置工具集完成装配。

完成入口阶段的环境初始化并返回 runtime。

把较早的执行记录压成稳定、可读的本地摘要。 压缩后的摘要仍然区分两类信息： - 已确认的事实 - 失败路径与反馈 这样下一轮模型不仅知道“以前看到了什么”，还知道“哪些路不要再走”。

组装跨角色共享的环境上下文块。

构造 Executor 需要的 prompt 上下文。

构造 Executor-Agent 的 user prompt。 这里会同时把 task、completion checklist、retry history、working memory、 available skills 和可用工具都拼进去，目的是让执行器优先围绕当前任务闭环，

构造统一的执行阶段未收口反馈。

把标题和章节列表渲染成 Markdown 模板。

构造运行期状态容器。 注意这里一次性创建了三套 WorkingMemory： - planner_memory: 记录规划阶段的侦察与反馈 - generator_memory: 记录执行阶段的证据链 - validation_memory: 记录验证阶段的检查过程

把系统和 shell 信息翻译成 Prompt 中可直接消费的操作约束。

构造流程编排阶段需要的静态上下文。 其中 planner 会额外拆出一组 `control_*` 动作集合，用来实现“侦察预算耗尽后， 只能返回控制动作、不能再继续 read/glob/grep”的约束。

构造工具调用签名。 这里把工具名和参数一起纳入签名，而不是只看工具名。 否则 `read(a.py)` 和 `read(b.py)` 会被误判成同一个动作。

生成单条记忆的工具调用摘要。

构造 Validator-Agent 的 user prompt。 相比 Executor，Validator 不关心“怎么完成”，而更关心“是否真的完成”。 因此 Prompt 会突出 checklist、task_history 和 validation_status。

构造 Validator 需要的 prompt 上下文。

把工作目录事实渲染成清晰的 Prompt 小节。

以原生 function call 方式请求 Agent 输出下一步动作。

在 retry 前压缩上一轮执行/验证经验，供下一轮复用。

提交新摘要，并只保留最近未压缩的几步。

在执行阶段需要时压缩旧记忆。

从环境变量读取配置并构造 OpenAI 客户端。 这里把“配置读取”和“client 创建”放在一起，是因为它们天然属于同一阶段： 没有合法配置，就不应该继续进入主循环。

构造目录化 skill package 存储。

构造运行时工具服务。 workspace 取 miniMaster2.0 根目录，这样所有工具对“相对路径”的理解都会一致。

把原生 function call 消息解析成统一动作结构，并按动作列表校验。 当前主循环约定每轮只允许模型选择一个动作，因此这里会要求消息中 恰好存在一个 tool_call。解析出的参数仍会继续复用既有的 schema 校验逻辑，保证从“文本 JSON 协议”迁移到“原

对 skill 目录名做最基本的命名规范校验。

执行标准流程：校验参数 -> 运行工具 -> 归一化结果。 这一步把所有工具执行都收敛成同一控制流，是整个工具系统可维护性的关键。

把工具结果格式化为单条控制台预览文本。

以可序列化形式返回全部记忆。

返回 Prompt 层常用的统一执行上下文字段。 Prompt 需要的并不是孤立的某一个环境值，而是一组彼此配合的事实： 当前工作目录在哪里、系统是什么、命令实际通过什么 shell 执行。 把这组字段在工具系统内部一次性整理好，可以减少上层主循环自

读取当前任务最近几轮失败尝试的压缩摘要。

返回工具实例，供兼容层或高级调用方直接访问。

处理一次 Plan-Agent 返回的控制动作。 返回值语义： - `True`: 顶层主循环应停止（典型场景是 `respond_to_user`） - `False`: 主循环继续

记录当前任务已经尝试过多少轮。

在目标 library 下创建完整 skill 骨架。

用 Planner 给出的初始任务列表填充本地任务面板。 这里支持字符串和对象两种形式，是为了兼容更宽松的模型输出； 但进入系统内部后，都会被规整成统一的 Task 结构。

加载所有 skill 的元数据版本，不加载正文内容。

程序入口。 这里不直接写业务逻辑，而是把“初始化”和“运行循环”两个阶段拆开。 这样一来，学生阅读代码时可以很快看出： - 运行前需要准备哪些共享对象； - 真正的 Agent 行为是从哪里开始接管的。

脚本入口。

脚本入口。

脚本入口。

脚本入口：创建 skill 后立即跑一次结构校验。

把 ToolResult 整理成统一的对外字典格式。

Parse CLI arguments while keeping backward compatibility. Supported forms: 1. `python print_tree.py ROOT --depth 2` 2. `python print_tree

解析命令行参数。

解析命令行参数。

解析 SKILL.md 顶部的极简 frontmatter。 这里没有依赖完整 YAML 库，而是只支持 miniMaster 当前真正需要的最小子集， 目的是让教学代码更短、更容易读懂。

把工具结果裁剪到适合继续喂给模型的大小。

打印 Planner 的简要决策理由。

在重试前高亮下一轮需要直接回应的焦点。

打印简洁的任务面板快照，方便观察 Planner 的最新状态。

打印工具执行前的关键上下文。

打印工具执行耗时。

把反馈写入 Planner 工作记忆，供当前规划轮继续反思。

把反馈写入 Validation 工作记忆，供同一轮验证直接读取。

读取并校验用户输入。 这里依然用最简单的终端输入，是因为 miniMaster 关注点在 harness， 而不是交互界面本身。

把工作记忆渲染成更利于 Generator 决策的上下文视图。 这个视图强调： - 当前最紧急的 system feedback - 最近执行证据 - 更早阶段的摘要

把规划阶段的侦察结果渲染成简洁上下文。

把验证记忆渲染成“验证条件视图”。 相比 Generator 视图，它会额外把最近动作区分成： - 已验证成功的证据 - 暂时失败或暴露缺口的线索

把全部可用 skills 渲染成适合放进 Prompt 的元数据文本。

把一个任务原地替换成多个子任务。 “原地”的意思是尽量保留原任务所在位置，这样任务面板顺序仍大体反映 Planner 的原始意图。

为当前任务重新初始化一份执行记忆。 每轮重试都应该有一份干净的 Generator working memory， 避免把上轮细碎轨迹原封不动带入下一轮。