聚合版 Agent 循环。 s01 展示 LLM -> 工具 -> LLM 的闭环，s02 开始把工具查找交给 ToolRegistry； s03 在工具执行前加入 PermissionManager，s04 开始在固定位置触发 hook； s06 新增 maxTurns，让父 Agent 和子

最小 Anthropic Messages HTTP 客户端。 本项目不用 SDK，而是用 Hutool + FastJSON 显式保留请求和响应结构。

把“如何询问用户”从权限规则中拆出来，方便替换成控制台、GUI 或自动审批。

模型返回的 assistant 消息，包含 content blocks 和 stop_reason。

s11 专用 Agent 循环。 在工具执行前判断是否应走后台：模型显式请求 run_in_background 或命令含慢操作关键词时， 启动 daemon 线程执行，先回占位 tool_result 让 Agent 继续思考； 后台完成后以 <task_notification>

后台执行判断逻辑。 两条规则： 1. 模型显式设置 run_in_background=true → 后台 2. 命令含慢操作关键词（install/build/test/deploy/compile 等）→ 后台兜底 只对 bash 工具生效，其他工具永远同步。

一条后台任务的状态快照。 不持久化，只在当前进程生命周期内存在。

后台任务生命周期管理器。 职责：启动 daemon 线程执行慢操作，追踪每个后台任务的状态， 收集已完成任务并格式化为 <task_notification> 通知。 线程安全：使用 ConcurrentHashMap，不加显式锁。

s01 唯一真实工具：执行 shell 命令。 本章故意不做权限判断，只保留“模型请求工具 -> Java 执行工具 -> 结果回给模型”的闭环。

cancel_cron 工具：按 ID 取消一个 cron 任务。

读取当前 Agent 的文件 inbox。

认领可开始的任务。

暴露给模型的 compact 控制工具。 真正压缩需要改写 messages，所以由 CompactingAgentLoop 特殊处理。

s08 专用 Agent 循环。 这个循环只展示上下文压缩相关的插入点，不继承权限、hook、todo 等无关机制。

s08 的四层压缩管线。 压缩按“便宜且保真优先”的顺序执行，最后才调用 LLM 做摘要。

完成任务，并报告刚解锁的下游任务。

连接 mock MCP server 的入口工具。

教学版审批器：直接在控制台询问用户，只有 y/yes 才允许执行。

Anthropic Messages 里的 content block 基类。

创建持久化任务。

s12 cron 任务数据类。 字段对齐参考项目 s14 CronJob dataclass。

s12 cron 调度器。 职责：注册/取消 cron 任务（委托给 Hutool CronUtil）， 管理内存 job map，触发时回调 Consumer。 教学版不引入队列和 queue processor，cron 触发直接在回调中 拿锁调用 Agent。Hutool 负责 cron

s12 cron 持久化存储。 只负责 .scheduled_tasks.json 的读写，不涉及调度逻辑。 只保存 durable=true 的任务。

Hutool Task 包装：触发时从 jobs map 中查找 CronJob 并回调 onFire。

s16 专用动态工具池循环。 connect_mcp 会改变工具集合，所以每轮 LLM 调用前重新 assemble 工具池。

精确替换文件中文本的工具。

读取单个任务的完整 JSON。

在 workdir 内按 glob pattern 查找文件的工具。

一个挂在 AgentLoop 事件点上的扩展函数。

Hook 执行时看到的上下文。 不同事件只填充自己需要的字段，例如 PreToolUse 有 toolUse， Stop 有 messages，UserPromptSubmit 有 userPrompt。

Hook 的返回值。 只有 PRE_TOOL_USE 阶段的 block 会阻止工具执行，其他阶段主要用于观察和记录。

Hook 调度器。 s04 的关键思想是：主循环只在固定位置触发事件， 具体扩展能力挂在 HookManager 上，不继续写进 AgentLoop。

list_crons 工具：列出所有已注册的 cron 任务。

列出任务图里的所有任务。

AgentLoop 依赖的模型接口，隐藏真实 HTTP 调用细节。

按名称加载技能正文的工具。 工具只接受 SkillRegistry 已扫描到的技能名，不接受任意文件路径， 这样可以把“按需加载”和“文件访问边界”放在同一个最小示例里讲清楚。

教学版 MCP client。 真实 MCP client 会通过 transport 发送 tools/list 和 tools/call； 这里用内存 handler 模拟外部 server，突出“发现工具”和“调用工具”两件事。

保存已连接的 MCP server。 真实产品会从配置加载 server；教学版直接按名字连接 mock server。

把 MCP 工具包装成项目已有的 Tool 接口。 主循环只看到普通 Tool；MCP 来源被隔离在这个 adapter 里。

mock MCP server 暴露的工具定义。 字段名保留 inputSchema，模拟 MCP tools/list 的返回形态；转换给模型时再变成 input_schema。

MCP 工具名规范化。 对齐参考实现：mcp__server__tool，非 [a-zA-Z0-9_-] 字符替换为下划线。

每轮把内置工具和已连接 MCP 工具组装成一个工具池。

一条文件系统记忆。 s09 使用普通 Java 类表达纯数据，便于直接对应 .memory/ .md 的 frontmatter。

s09 专用 Agent 循环外壳。 压缩仍交给 s08 的循环处理；这里只标出“本轮结束后提取记忆”的位置。

低频记忆整理。 教学版用数量阈值代替真实系统里的时间、会话、锁等多层门控。

从最近对话提取新记忆。 真实系统会有更复杂的门控；教学版在每轮结束后跑一次，便于观察文件变化。

s09 的记忆入口。 demo 只和这个组合类交互，避免启动入口直接知道筛选、提取、整理的细节。

根据当前问题选择相关记忆。 主路径使用一次 LLM side-query，失败时退回关键词匹配，保证 demo 不因 JSON 波动中断。

`.memory/` 文件仓库。 每条记忆是一个 Markdown 文件，`MEMORY.md` 只是索引，正文按需读取。

发给模型的单条消息，role 只能是 user 或 assistant。

s13 文件邮箱。 发送消息就是追加一行 JSONL；读取 inbox 后删除文件，表示消息已消费。 教学版用 synchronized 覆盖同进程并发，不处理跨进程文件锁。

s08 专用的消息结构检查器。 压缩代码需要频繁判断 tool_use/tool_result 配对，把这些判断集中到一个类里， 可以避免压缩管线到处散落 instanceof 细节。

两个 mock MCP server。 time/weather 都不访问网络；它们只模拟“外部服务暴露工具”的形态。

文件工具的最小路径边界。 s02 还没有权限系统，但文件读写至少要被限制在 workdir 内， 避免模型通过相对路径访问项目目录之外的文件。

权限管线给 AgentLoop 的判断结果。 主循环只关心是否允许执行，以及拒绝时要回传给模型的说明。

工具执行前的权限边界。 s03 把“能不能做、要不要问用户”放在工具真正执行之前， 这样模型即使请求了危险操作，Java 侧也可以拒绝或暂停确认。

Lead 专用 inbox 工具。 读取消息前先走协议路由，避免 response 被消费后 pending 状态没有更新。

s14 协议状态机。 教学版只在进程内保存 pendingRequests；重启后协议状态丢失。

一条协议请求的状态。 requestId 把 request 和 response 串起来；status 只在内存里追踪。

读取 workdir 内 UTF-8 文本文件的工具。

Lead 请求队友先提交计划。

Lead 请求队友体面关机。

Lead 按 request_id 审批队友提交的计划。

s01 启动入口：注册一个 bash 工具，然后把用户输入不断交给 AgentLoop。

s02 启动入口：把多个工具注册进 ToolRegistry，主循环保持不变。

s03 启动入口：复用 s02 的工具池，并在工具执行前挂上权限管线。

s04 启动入口：把权限、日志、输出检查和停止统计都注册成 hook。

s05 启动入口：把“先计划再执行”的约束交给 todo_write 工具和 system prompt。

s06 启动入口：父 Agent 拥有 task 工具，子 Agent 只拥有基础工具。

s07 启动入口：system prompt 只放技能目录，正文通过 load_skill 按需加载。

s08 启动入口：在 LLM 前挂上四层压缩管线，并把 compact 做成控制工具。

s09 启动入口：用文件系统保存记忆，并在每轮开始按需加载相关正文。

s10 启动入口：用 .tasks/ .json 保存任务图，并通过 blockedBy 控制任务顺序。

s11 启动入口：后台执行慢操作，Agent 继续思考。

s12 启动入口：cron 定时触发，不需要人推。 启动时加载 durable cron job，注册到 Hutool CronUtil。 到点后在 cron 回调线程中拿 agentLock，注入 [Scheduled] 消息并运行 Agent。 用户输入同样需要拿 agentLock，避免并发

s13 启动入口：Lead 启动队友线程，并通过文件 inbox 异步通信。

s14 启动入口：在团队邮箱上增加 request_id 协议。

s15 启动入口：队友空闲后自己扫描任务看板并认领任务。

s16 启动入口：把 mock MCP server 接进同一个工具池。

schedule_cron 工具：注册一个 cron 定时任务。

通过文件邮箱给另一个 Agent 发消息。

技能的纯数据对象。 s07 为了便于新手阅读，继续使用普通 Java 类表达数据， 不使用 record 或复杂元数据模型。

技能目录。 启动时只把 name/description 这类便宜信息放进 system prompt， 真正的 SKILL.md 正文等模型调用 load_skill 时再加载。

启动一个队友 Agent 线程。 队友只存在于当前 Java 进程；activeTeammates 对齐参考项目的 active_teammates dict。

队友提交计划给 Lead 审批。

一条持久化任务。 s10 使用普通 Java 类对应 .tasks/{id}.json，字段名保持和参考实现一致。

任务状态机。 TaskStore 只管文件，TaskService 才负责 pending -> in_progress -> completed 和依赖检查。

`.tasks/` 文件仓库。 这里仅负责 JSON 文件读写，任务状态流转放在 TaskService 中，避免存储层知道业务规则。

子 Agent 工具。 父 Agent 调用 task 时，这个工具会创建一段全新的 messages， 让子 Agent 在干净上下文中完成 description 描述的任务。

文件邮箱里的一条消息。 教学版只保留通信所需字段，不设计完整协议；s16 再引入固定请求-回复格式。

普通文本 content block。

模型可能返回的 thinking block，保留 signature 便于后续请求原样带回。

普通数据类，不使用 record，保存任务内容和状态。

计划记录工具。 s05 把“先列计划”做成一个普通工具，而不是写进 AgentLoop。 工具只保存当前 todo 列表，不直接执行任何任务。

所有工具的最小接口：既能描述给模型，也能在 Java 侧真正执行。

暴露给模型的工具定义，对应 Anthropic Messages 的 tools 数组。