Mino 章节规划与完成状态

本教程使用 Go 和 OpenAI Responses API，从零实现一个终端 Agent。OpenAI 官方 Go SDK 负责 API 通信，Mino 实现交互流程，以及第 03 章引入的 Agent 循环。每章追踪一次交互：模型收到什么，程序怎样处理响应，控制或上下文如何进入下一步。准备与安装集中说明安装和 API 设置。

第 01–15 章均已发布，具备代码、双语说明和验证。最新发布的第 15 章随 chapter-15 发布，程序版本为 0.15.0，发布于 2026-10-29。十章的规划于 2026-10-21 取代了此前的九章编号，chapter-10 于 2026-10-26 以权限模式重新发布，见重新发布的版本。

序号	完成状态	章节名称	本章回答的问题
01	已发布	你的第一次终端对话	一行输入怎样变成流式 Responses 请求和终端里的回答？为什么相互独立的请求没有记忆？发布标签 chapter-01（版本 0.1.0）。
02	已发布	用 JSONL 对话历史延续对话	哪些保存的记录能在重启后作为上下文回到模型面前？写到一半的最后一条记录怎么处理？唯一的一段对话保存为 ~/.mino/sessions/ 下的会话文件。发布标签 chapter-02（版本 0.2.0）。
03	已发布	用工具调用与 Bash 构建第一个 Agent 循环	一次工具调用怎样变成经过批准、受限的 Bash 执行，并把配对的结果交回模型？每一步都先保存再继续，所以重启绝不会重跑命令；只有已完成的问答会作为上下文返回。发布标签 chapter-03（版本 0.3.0）。
04	已发布	如实恢复中断的工具调用	命令可能已经执行、结果却从未保存时，模型怎样得知？失败、取消或中断的工具问答会连同配对结果和运行时提示一起重放，不自动重试任何操作；出现 unknown 结果时，必须由你确认后才能继续聊天。发布标签 chapter-04（版本 0.4.0）。
05	已发布	用 JSONL 会话管理多段对话	怎样选择由哪段对话提供上下文，让其他会话保持隔离，并有意识地清空其中一段？前几章留下的对话会被原地选中。发布标签 chapter-05（版本 0.5.0）。
06	已发布	用手动命令与自动触发压缩上下文	/compact 与每次请求前的自动检查，怎样让上下文留在预算内，同时保留近期问答和原始历史？发布标签 chapter-06（版本 0.6.0）。
07	已发布	用 Skills 按需加载任务知识	每个会话固定的一份项目技能目录，怎样让模型只在需要时用 skill_view 读取完整的任务指引？发布标签 chapter-07（版本 0.7.0）。
08	已发布	用文件工具读写项目文件	结构化的 read_file、write_file 和 edit_file 怎样给模型精确的项目文件访问，并让程序真正限定范围？路径通过 os.Root 限定在启动时的项目目录内，拒绝符号链接、特殊文件和多硬链接文件。读取与 skill_view 一样标记为只读；每次写入或编辑先经实时检查展示有界预览，再需要单独的默认拒绝批准，批准绑定到检查时的文件内容。Bash 保留原有的批准方式。发布标签 chapter-08（版本 0.8.0）。
09	已发布	用 MCP 接入外部工具	由另一个进程提供的工具，怎样加入同一个 Agent 循环？支持 Context7 这类远端 Streamable HTTP 服务和本地 stdio 服务，使用 MCP 的 tools 能力。mino mcp add、list、remove 管理私有的 ~/.mino/mcp.json，从不读取项目内配置；API 密钥等静态请求头以隐藏方式输入，不会进入模型请求、日志或确认界面。远端地址必须使用 HTTPS。每次工具调用都需要批准（默认拒绝），并显示参数将发往何处；工具映射为唯一的本地名称，schema 转换为 Responses 工具，描述和结果都视为不可信的外部内容。调用发出后超时或断开，记为未知结果，不自动重试。OAuth、旧版 SSE 传输、MCP resources/prompts 不在本章范围内。发布标签 chapter-09（版本 0.9.0）。
10	已发布	用安全防护让 Agent 在授权范围内行动	第 02–09 章分散的控制，怎样统一成由代码执行的一套策略？每次实时工具调用在执行前都经过同一个允许、询问或拒绝的决定：先是内置的受保护路径，如 .env、密钥、.git/，文件工具在任何模式下都不能读写；再是每个会话各自的、只有用户能用 /mode 改变的权限模式。每个会话开始时的 manual 模式在每次写入、Bash 和 MCP 调用前询问；accept-edits 另外让项目文件的写入和编辑不经询问运行；bypass 让所有调用都不经询问运行。放宽模式需要交互式确认，/new 从 manual 开始，/resume 恢复该会话的模式，模式从不保存，不经询问的调用仍会显示。批准仍只绑定这一次经过检查的调用，注入文本、摘要或工具输出都无法授予权限。本章不做操作系统沙箱，并解释 Bash 和 MCP 进程为何仍不受路径规则约束。用模拟服务验证注入、符号链接、模式和 /mode 场景。发布标签 chapter-10（版本 0.10.0）。
11	已发布	用评测衡量 Agent	怎样可重复地检查 SOUL、工具描述或循环的一处改动是否改变了 Agent 的行为？mino eval 让 YAML 用例经过真实的 Agent 循环，每份用例声明提示、批准什么、可选的脚本化模型和确定性的评分器。回放模式用脚本化的本机 Responses 服务驱动循环：不需要密钥和网络，从不读取 ~/.mino，并在 scripts/check.sh 中运行。--live 对已配置的模型重复运行每份用例，报告 pass@k、pass^k 和 token 用量。每次运行都使用全新的临时工作区和主目录、manual 权限模式，且不连接 MCP 服务。没有裁判模型，也没有沙箱；历史记录仍为版本 4。发布标签 chapter-11（版本 0.11.0）。
12	已发布	在操作系统沙箱中运行 Bash	第 10、11 章说明策略只限定文件工具，不约束 Bash 和 MCP 启动的进程。怎样让执行环境而不是对命令意图的猜测，去限定一条命令能触及什么？在 macOS 上，每条 Bash 命令都在 Seatbelt 配置（sandbox-exec）下运行：允许读取，写入限定在项目目录、临时目录和用户缓存目录，拒绝内置受保护路径（.git/ 可读不可写），并阻断网络。确认界面显示一行 Sandbox；模型可以为需要更多权限的命令设置 sandbox: false，这在除 bypass 外的每种模式下都会询问；accept-edits 不经询问运行受限命令。mino mcp add --sandbox 让 stdio 服务在允许网络的前提下受限运行。没有 sandbox-exec 的系统上，Bash 的行为与第 11 章相同并会明确说明。历史记录仍为版本 4。发布标签 chapter-12（版本 0.12.0）。
13	已发布	跨会话记住用户	Mino 应该跨会话、跨项目记住什么，放在哪里，模型写下的文字又怎样进入上下文而不变成指令？每条记忆是 ~/.mino/memory/ 中的一个文件，包含 name、type（user、feedback、project、reference）和一行 summary，以及可选的细节。没有索引文件：每一轮开始时，Mino 从这些文件渲染出全部摘要组成的索引，作为输入的第一项发送；它是一条标明“数据而非指令”的助手消息，与压缩摘要合并，从不写入历史。摘要就是事实本身；memory_view 不经询问读取一条记忆的细节，memory_save 在 manual 和 accept-edits 下经批准后创建或覆盖一条记忆，只有 bypass 下不询问。索引最多 200 条、16 KiB；无法使用的文件会被跳过并给出提示。没有删除工具，没有项目本地记忆，没有自动提取。历史记录仍为版本 4。发布标签 chapter-13（版本 0.13.0）。
14	已发布	把工作委派给子 Agent	一次大规模探索怎样不挤占主循环的上下文，子循环又继承什么？一次 spawn_agent 调用接收 1 到 10 个任务，把每个任务作为一个子 Agent 运行：它有自己的上下文、位于 ~/.mino/sessions/<session-id>.agents/ 下的自己的日志、自己的请求与工具调用上限和自己的压缩，默认同时运行 3 个（max_concurrent_subagents，取 1 到 10）。子 Agent 收到启动时的 SOUL、会话的技能目录、这一轮的记忆索引，以及除 spawn_agent 和 memory_save 外的同样工具；它们共享会话的权限模式，需要询问时带着 Subagent 标签逐个询问。spawn_agent 本身在 manual 和 accept-edits 下会询问，一轮最多启动 16 个子 Agent。父级等待全部完成，收到一个工具结果，其中每个任务的状态和最终文本共享 48 KiB 的预算，所以父级历史中每个调用仍只有一条开始记录和一个结果，记录版本仍为 4。沙箱现在也封住 ~/.mino。发布标签 chapter-14（版本 0.14.0）。
15	已发布	为子 Agent 定义项目角色	项目怎样给模型提供可复用的专门助手，却不交给它们权限？.agents/agents/<name>.md 中的定义为角色命名、说明何时使用它，可以用 tools 列表缩小它的工具范围，并保存角色文本。它们的元数据像技能目录一样，每个会话保存一次，写入新的 session_agents 记录，并列在父级的指令中；spawn_agent 的任务变为 {agent, task} 对象，未知角色在确认之前就被拒绝。角色子 Agent 在第一条消息中收到定义的当前文本，作为带标签的项目数据，而从不作为指令，并且只拿到列表中可用的工具；定义不能增加工具、改变模型或权限模式，也不能授予批准。内置的 create-subagent 技能引导模型编写定义，skill_view 的结果现在会写明技能所在的目录。历史记录升级到版本 5。计划发布标签 chapter-15（版本 0.15.0）。

基础保护随相应能力一起引入：第 03 章逐条批准 Bash 命令，第 04 章拒绝把结果未知的操作当作成功，第 08 章通过构造限定文件访问范围，第 09 章逐次批准外部工具调用，并让服务凭证远离模型。第 10 章统一已有控制，而不是补上第一批控制；第 11 章则让这些控制对模型的效果可以衡量：同样的用例经过同一个循环和同一个决定，SOUL 或工具描述的一处改动靠重复运行来检查，而不是凭一次印象。提示词和注入检测只能降低风险，实际权限必须由程序与执行环境约束；不能只凭 rm 等命令关键词判断安全性，通用 Bash 也无法仅靠路径规则限定。正因为这种对照，结构化文件工具安排在安全防护之前。