# Posoco 101 — 课程大纲

> 用 Posoco 从零构建 LLM Agent 的入门系列。
> 每篇一个观点，可独立在小红书 / B 站分享。

## 设计参考

本系列章节主题锚定主流 **Agentic Design Patterns**（Andrew Ng 四模式 +
Google 扩展集），让读者能把 posoco 的端口/扩展机制和业界通用说法对应起来：

- **Reflection** — agent 审视并修正自己的输出
- **Tool Use** — agent 调用外部工具扩展能力
- **Planning** — agent 拆解任务、分步执行
- **Multi-Agent** — 多个角色化 agent 协作
- **Routing** — 按任务类型选择不同模型/路径
- **Parallelization** — 多任务/多工具并发
- **Memory** — 跨会话的长期记忆

---

## A. 章节列表

每篇 ~1500-2500 字，可独立单发。代码全部可执行（`.mbt.md` doc-test）。

| # | 标题 | 一句话观点 | 对应模式 | 状态 |
|---|------|-----------|---------|------|
| 01 | [Agent Loop 原理：怎么自己写一个 Agent](./01-agent-loop-principles.mbt.md) | LLM 不会自己循环，循环是程序的责任 | — | ✅ 已有 |
| 02 | [用 Posoco 写你的第一个 Agent（10 行）](./02-first-agent-with-posoco.mbt.md) | 你填端口，Agent 负责循环 | — | ✅ 已有 |
| 03 | Extension 组合模型：为什么不是 `model=, tools=` | 自报告 manifest 是 ports-and-adapters 的核心 | — | 🆕 待写 |
| 04 | Tool Use：给 Agent 装手 | 写一个 `read` 工具，看 Agent 主动调用它 | **Tool Use** | 🆕 待写 |
| 05 | Routing：一个 Agent 多个模型 | `posoco-ext-llm` 路由器，按任务选模型 | **Routing** | 🆕 待写 |
| 06 | Reflection：让 Agent 自检 | `Hook::before_model` 重写消息，让模型批判自己 | **Reflection** | 🆕 待写 |
| 07 | Parallelization：多工具并发 | `ExecutionPolicy::Parallel` 的 wave 调度 | **Parallelization** | 🆕 待写 |
| 08 | Planning：Reasoning + 多步工具链 | `reasoning_content` + 多轮工具调用 | **Planning** | 🆕 待写 |
| 09 | Memory：跨会话记忆 | `MemoryPort` + `posoco-ext-session-memory` | **Memory** | 🆕 待写 |
| 10 | Observer + Hook 调试术 | 出错时怎么用事件流定位问题 | — | 🆕 待写 |
| 11 | 失败透明：typed error 比 try/catch 好在哪 | `ModelError`/`RuntimeError`/`SessionError` 的边界 | — | 🆕 待写 |
| 12 | 垂直 Agent capstone：组装一个 mini coding agent | 把 ch03-11 串成一个领域 agent | **Multi-Agent** | 🆕 待写 |

---

## B. Agentic Design Patterns 对应矩阵

| Andrew Ng / Google 模式 | posoco 实现 | 对应章节 |
|---|---|---|
| Reflection | `Hook::before_model` 重写 messages | ch06 |
| Tool Use | `ToolProvider` + `ToolDef` | ch04 |
| Planning | `reasoning_content` + 多轮 `run_turn` | ch08 |
| Multi-Agent | 多 `Agent` 实例 + 共享 SessionStore | ch12 |
| Routing | `posoco-ext-llm` RouterModelPort | ch05 |
| Parallelization | kernel `ExecutionPlan` waves / `ExecutionPolicy` | ch07 |
| Memory | `MemoryPort` + session tree | ch09 |

---

## C. 写作约束

延续 [README.md](./README.md) 已有约束，新增 2 条：

- ✅ 一篇文章只回答一个中心问题
- ✅ 先给最小机制，再解释生产系统多出的保护层
- ✅ 可执行示例必须由当前工具链验证，不能复制过时 API
- ✅ 代码写在 `.mbt.md` 的 ` ```mbt check` 块里，不使用 `nocheck` 伪代码
- ✅ 示例中的失败必须可见，禁止用空值或假成功简化错误处理
- ✅ MoonBit 语法不确定时先验证；未确认的问题记录到 `docs/questions.md`
- 🆕 **每篇明确点出对应的 Agentic Design Pattern 名字**（提升可搜索性，让读者能和业界说法对应）
- 🆕 **每篇结尾留 1 个「转发金句」+ 1 个可运行代码块**（小红书/B 站封面友好）

---

## D. 章节详细规划（待写篇章）

### ch03 — Extension 组合模型：为什么不是 `model=, tools=`

**核心问题**：为什么 posoco 用 `Agent(exts=[…], config=…)` 而不是
`Agent(model=…, tools=…)`？

**教学点**：
- 从 ch02 的手写 `Extension` impl 出发，引入 `tk_ext` 捷径
- manifest 的 14 个槽位逐一过一遍（哪些必填、哪些可选）
- 组合诊断：`ToolCollision` / `MissingModel` / `EmptyPort` 的 fail-fast 语义
- 顺序无关性的价值：扩展数组怎么排都不影响结果

**金句候选**：「扩展不靠参数位置认领职责，靠 manifest 自报告。」

### ch04 — Tool Use：给 Agent 装手

**对应模式**：Tool Use（Andrew Ng）

**核心问题**：怎么让 Agent 主动调用一个工具？

**教学点**：
- 实现 `ToolProvider`：`list_tools` + `execute` 两个方法
- `ToolDef` 的 schema（JSON Schema 子集）让模型知道参数形状
- 用 `ScriptedModel` 模拟"模型请求工具 → Agent 执行 → 结果回灌"完整循环
- 对照 `posoco-ext-read` 真实实现

**金句候选**：「工具不是函数调用，是模型发出的、由程序兑现的承诺。」

### ch05 — Routing：一个 Agent 多个模型

**对应模式**：Routing（Google）

**核心问题**：简单问题用便宜模型、复杂问题用强模型，怎么自动选？

**教学点**：
- `posoco-ext-llm` RouterModelPort 的角色
- ModelSlot 概念：一个 router 持有多个 provider adapter
- host 注入 vs 扩展自建的路由策略

### ch06 — Reflection：让 Agent 自检

**对应模式**：Reflection（Andrew Ng）

**核心问题**：怎么让 Agent 在回答前审视自己的输出？

**教学点**：
- `Hook::before_model`：拦截 + 重写 messages
- 注入"批判视角"系统提示，让模型二次审视草稿
- `HookAbort`：何时应该中止而不是继续

### ch07 — Parallelization：多工具并发

**对应模式**：Parallelization（Google）

**核心问题**：模型一次请求 3 个工具，怎么并发执行？

**教学点**：
- `ExecutionPolicy`：`Sequential` / `Parallel` / `Exclusive`
- kernel 的 wave 调度：同一 wave 内并行，wave 间顺序
- 什么时候该用 Exclusive（如写文件）

### ch08 — Planning：Reasoning + 多步工具链

**对应模式**：Planning / ReAct（Andrew Ng）

**核心问题**：Agent 怎么拆解复杂任务并分步完成？

**教学点**：
- `reasoning_content`：模型的思维链
- 多轮工具调用的状态机视角（ReadyForModel ↔ AwaitingTools）
- 何时该用 Planning、何时直接 Tool Use 就够

### ch09 — Memory：跨会话记忆

**对应模式**：Memory（Google）

**核心问题**：Agent 怎么记住用户上次的偏好？

**教学点**：
- `MemoryPort`：store / search / delete
- `MemoryRetrievalHook`：自动在 before_model 注入相关记忆
- session tree：NewThread 压缩时的 parent_session_id 血缘

### ch10 — Observer + Hook 调试术

**核心问题**：Agent 行为异常时，怎么定位是模型、工具还是 hook 的问题？

**教学点**：
- `Observer::on_event`：事件流是 Agent 的黑匣子
- `TurnEvent` 全集：TurnStarted → ToolCallPending → ToolCallResult → TurnCompleted/Failed
- `Hook::before_tool` 的 `Defer`/`Reject`：危险工具的人工确认

### ch11 — 失败透明：typed error 比 try/catch 好在哪

**核心问题**：为什么 posoco 用 typed error 而不是异常？

**教学点**：
- `ModelError` vs `RuntimeError` vs `SessionError` 的边界
- 模型失败终止 turn；工具失败喂回模型（non-fatal）
- `TurnFailed` 的单 terminal event 不变量

### ch12 — 垂直 Agent capstone：组装一个 mini coding agent

**对应模式**：Multi-Agent（Andrew Ng）

**核心问题**：把 ch03-11 串起来，能做出什么？

**教学点**：
- 参考 `external/examples/cetas-core` 的真实组装
- 系统提示 + read/edit/bash 工具 + session 持久化 + observer
- 从"能跑"到"可靠"还差什么（boundary commit、capability declaration）

---

## E. 与现有文档的关系

| 现有文档 | 角色 | 状态 |
|---------|------|------|
| `docs/01-quickstart.md` | ch02 的精简版双子 | ✅ 本轮已同步当前 API |
| `docs/02-architecture.md` | 架构参考（非教程） | 现行 |
| `docs/03-trait-recipes.md` | ch03-11 的深度参考 | ✅ 本轮已同步当前 API |
| `docs/EXTENSIONS.md` | ch03/ch04 的扩展开发参考 | ✅ 本轮已同步当前 API |
| `docs/05-streaming-guide.md` | 流式进阶参考 | 现行 |
| `blog/puppetry-vs-agent-loop.md` | ch01 的"为什么重构成 Puppetry"背景阅读 | 现行 |

**不重复原则**：101 系列做"端到端叙事教程"；`docs/` 做"深度参考手册"。
两者交叉引用，不互相替代。