docs: 添加模板编译器 UTF-8 编码修复方案与需求文档

- 新增 PDD 方案（编号 32），覆盖 6 处逐字节强转修复、测试设计与版本升级计划 - 新增 PRD 需求（编号 2），定位模板编译阶段中文乱码根因并明确验收标准 - 添加 .codegraph 目录忽略规则，避免本地数据文件入库
fix(prompt): 修复模板编译器 UTF-8 编码乱码
2026-08-03 11:21:50 +08:00 · 2026-08-03 11:16:16 +08:00 · 2026-07-27 09:46:52 +08:00 · 2026-07-27 09:34:11 +08:00 · 2026-07-23 05:54:58 +08:00 · 2026-07-23 05:45:53 +08:00
68 changed files with 1620 additions and 57 deletions
@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore
@@ -186,29 +186,64 @@ pub use vector_store::VectorStore;

 ## 文档规范

-### 方案规范 (docs/)
+### 文档编号规范（design/pdd/ + design/prd/）

-**编号规则**：创建新方案前必须先通过 shell 命令确认当前实际最大编号（Unix: `ls docs/` / Windows: `dir docs\`），禁止使用上下文中缓存的编号，如遇冲突自动递增
+`design/pdd/`（方案文档）和 `design/prd/`（需求文档）使用相同的命名格式，但**各自独立编号**：

-**方案文档结构**（6 项）：
-1. **背景与目标** - 问题描述、预期目标
-2. **需求分析** - 功能需求、非功能需求
-3. **方案设计** - 架构设计、模块划分、接口定义
-4. **实现计划** - 任务拆解、优先级、时间估算
-5. **风险评估** - 潜在风险、缓解措施
-6. **验收标准** - 可验证的完成条件
+```
+<序号>-<简短描述>.md
+```

-### 进度同步规范 (docs/roadmap.md)
+规则：
+- 序号使用数字，从 1 开始递增。**创建前必须通过 shell 命令确认目标目录当前实际最大编号再加 1：**
+  ```bash
+  # 查 design/pdd/ 的最大编号
+  ls design/pdd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
+  # 查 design/prd/ 的最大编号
+  ls design/prd/ 2>/dev/null | grep -E '^\d+-' | sort -t- -k1 -n | tail -1 | cut -d- -f1
+  # 无输出则从 1 开始
+  ```
+  禁止使用上下文中缓存的编号。
+- 描述：中文，简短概括主题
+- 两个目录各自独立编号——`design/pdd/` 已有 `3-` 时，`design/prd/` 的新文件仍从当前最大号 +1 开始，互不影响

-完成一项实施后，必须检查 `docs/roadmap.md` 是否存在对应内容；若存在，必须同步标记为完成：
+方案文档（`design/pdd/`）应包含：
+- 背景与目标
+- 需求推演概要（需求拆解、边界识别、关键假设的简要推演）
+- 当前问题分析
+- 架构决策记录（重大技术选型、架构变更的决策过程与理由）
+- 设计方案（含架构图/流程图）
+- 实施步骤
+- 验证标准
+- 回滚方案（如适用）

- **Step / Phase 状态行**：对应 Step 加 ✅ 标记；Phase 章节末尾「状态」行从 ⏳ 改为 ✅ Phase X 全部交付物已完成
- **里程碑表**：更新对应里程碑状态从 ⏳ 改为 ✅ + 完成日期
- **依赖关系图（Mermaid）**：节点 `class` 从 `pending` / `core` 改为 `done`，必要时更新节点摘要
- **文末「已完成 / 进行中阶段」列表**：追加一行 `- ✅ Phase X — 一句话要点`
- **顶部「当前状态」**：补充新完成 Phase，更新「下一步」指向
+示例：
+- `design/pdd/1-ui-components重构方案.md`
+- `design/prd/1-用户认证需求.md`
+- `design/pdd/2-数据库迁移方案.md`

-参考案例：2026-07-05 完成 Phase 7 SqliteStore 时同步更新 6 处（顶部状态 / Phase 章节 / 依赖图 / M3 / 下一步行动 / 已完成列表）。
+---
+
+### 设计目录（design/）
+
+项目根下的 `design/` 目录集中管理所有设计相关的文件，供人类和 agent 共同读写。
+
+| 子目录 | 内容 | 谁写 | 谁读 |
+|--------|------|------|------|
+| `design/pdd/` | 方案设计文档（PDD）→ 架构方案、设计决策、转换方案 | proposal→writer pipeline | Think 参考、Build 实现、Vet 审查 |
+| `design/prd/` | 需求文档（PRD）→ 功能需求、用户故事、验收标准 | 人写 | Think 分析、Proposal 写方案时参考 |
+| `design/prototype/` | **OD 导出的原型 HTML** → 视觉稿、交互原型、页面 layout | OD 桌面版导出 | Think 分析结构、Build 对照实现 |
+| `design/notes/` | 笔记记录 → 零散想法、会议纪要、调研速记 | 人写 | 各 agent 参考 |
+| `design/roadmap/` | 路线图 → 里程碑规划、版本计划、优先级列表 | 人写 | Proposal 排期参考 |
+| `design/DESIGN.md` | 设计系统（品牌规范）→ 色板、字体、间距、语气 | OD 导出 / 人维护 | Think 提取 token、Build 同步到 `src/` |
+| `design/tokens.css` | 设计 Token CSS → 从 DESIGN.md 提取的 CSS 变量 | 人同步 / agent 同步 | 所有 Svelte 组件引用 |
+
+**访问规则：**
+- 读：所有 agent 默认可读（`read_file` 不需要额外权限）
+- 写：writer agent 可通过 `"design/**": allow` 写入 `design/` 下任意子目录
+- 注意：`prototype/` 由 OD 桌面版导出，agent 只读不写；`DESIGN.md` 和 `tokens.css` 建议手动维护或 agent 写入时确认后再改
+
+**兜底规则：** 文档类型不在上表时（如教程、接口文档、临时记录），或目标目录不存在时 → **向用户提问确认路径**。不允许自行推断存放位置。

 ---

@@ -1,6 +1,6 @@
 [package]
 name = "agcore"
-version = "0.3.5"
+version = "0.3.7"
 edition = "2024"

 [features]
@@ -0,0 +1,249 @@
+# PDD：Usage 字段反序列化容错方案
+
+**状态**：Draft
+**作者**：Think Agent
+**日期**：2026-07-27
+
+## 1. 背景与目标
+
+为 `agcore::Usage` 结构体的必填 token 字段添加 `#[serde(default)]` 反序列化容错，使 OpenAI Response API 和 Chat Completions API 的 blocking 调用在火山平台返回不完整的 `usage` 字段时不再崩溃。
+
+### 触发场景
+
+dc-management 项目调用火山引擎 Responses API 时，非流式路径报错：
+
+```
+OpenAI Response 响应解析失败 error=missing field 'prompt_tokens' at line 1 column 1581
+```
+
+根因是 `Usage` 的三个 token 字段（`prompt_tokens`、`completion_tokens`、`total_tokens`）定义为必填 `u32`，而火山平台的 Responses API 返回的 `usage` 对象中这些子字段偶发缺失。
+
+### 影响面
+
+4/5 的 LLM 命令被阻断：
+
+| 功能 | 命令 | 状态 |
+|------|------|------|
+| AI 探索（产品采集） | `llm_collect` → `workflow.rs` `.chat()` | ❌ 不可用 |
+| 普通聊天 | `llm_chat` → `llm.rs` `.chat()` | ❌ 不可用 |
+| 要素值正则化 | `llm_normalize_values` → `normalizer.rs` `.chat()` | ❌ 不可用 |
+| 数据验证 | `validator.rs` `.chat()` | ❌ 不可用 |
+| 连接验证 | `verify_llm_connection` → `chat_stream()` | ✅ 幸免（流式） |
+
+## 2. 需求推演概要
+
+### 需求拆解
+
+- **核心需求**：blocking 路径下 `Usage` 反序列化不因缺失子字段而崩溃
+- **范围边界**：只改 serde 反序列化行为，不改字段类型，不改流式路径
+- **质量属性**：最小变更（±3 行）、零副作用、测试可验证
+
+### 关键假设
+
+| 假设 | 依据 | 验证方式 |
+|------|------|---------|
+| `Usage` 已 derive `Default` | 代码确认 | 编译通过 |
+| 缺失字段默认 0 对所有消费者安全 | `CostTracker::add` 使用 `saturating_add`；流式路径已有 `unwrap_or(0)` 行为 | 代码审查 |
+| `#[serde(default)]` 不影响序列化 | serde 明确语义 | 代码审查（serde 明确语义） |
+| `usage: null` 不会出现 | 当前未观察到，留 `ponytail:` 注释 | 生产观察 |
+| Chat Completions blocking 路径存在同源缺失风险 | 两路径共用火山平台底层 API 基础设施 | 在 §5.4 添加 `#[serde(default)]` 预防性加固（经 PRD 作者推演阶段确认） |
+
+## 3. 当前问题分析
+
+### 根因
+
+- `src/llm/types/usage.rs:4-12`：`Usage` 结构体的 `prompt_tokens`、`completion_tokens`、`total_tokens` 定义为 **必填 `u32`**，非 `Option<u32>`
+- `src/llm/provider/openai_response.rs:207`：`OpenaiResponseBody` 内嵌 `usage: Usage`，也是必填
+- `src/llm/provider/openai.rs:245`：`OpenaiChatResponse` 内嵌 `usage: Usage`，同样必填
+- 火山平台 Responses API 返回的 `usage` 对象中，子字段缺失 → serde 反序列化 `missing field` 错误
+- 流式路径不受影响：其 `PartialUsage` 所有字段均为 `Option<u32>`，缺失时通过 `unwrap_or(0)` 兜底
+
+### 已知线索
+
+- dc-management 的 `verify_llm_connection` 已预见到此问题，注释特意说明使用流式规避
+- 这是已知的设计约束——流式已容错但 blocking 路径未同步加固
+
+## 4. 架构决策记录
+
+| 决策 | 选项 | 选择 | 理由 |
+|------|------|------|------|
+| 容错机制 | `#[serde(default)]` vs 改为 `Option<u32>` vs 自定义 `Deserialize` | `#[serde(default)]` | 最小变更，不改类型语义 |
+| 覆盖范围 | 仅 Responses API vs 同时覆盖 Chat Completions | 同时覆盖 | 增量成本≈0，防患于未然（经 PRD 作者推演阶段确认） |
+| 测试范围 | 2 个场景 vs 4 个场景 | 4 个场景 | 必要的边界覆盖（缺失 key / 缺失字段 / 空对象 / 完整回归） |
+
+## 5. 设计方案
+
+### 5.1 变更概览
+
+**3 行 serde attribute + 4 个测试用例，零逻辑变更。**
+
+### 5.2 变更一：`Usage` 结构体加 struct-level `#[serde(default)]`
+
+**文件**：`src/llm/types/usage.rs:3`
+
+```diff
+- #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+ #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+ #[serde(default)]
+  pub struct Usage {
+      pub prompt_tokens: u32,
+      pub completion_tokens: u32,
+      pub total_tokens: u32,
+      #[serde(skip_serializing_if = "Option::is_none")]
+      pub completion_tokens_details: Option<CompletionTokensDetails>,
+      #[serde(skip_serializing_if = "Option::is_none")]
+      pub prompt_tokens_details: Option<PromptTokensDetails>,
+  }
+```
+
+**作用**：JSON 中缺失 `Usage` 的 **任何** 子字段时，自动使用 `Default::default()` 取值：
+- 三个 token 字段（`u32`）：缺失时默认 `0`
+- 两个 `Option` 详情字段：缺失时默认 `None`
+
+**为什么 struct-level 够用**：struct-level 对子字段统一生效，不需要为每个字段单独标注。
+
+### 5.3 变更二：`OpenaiResponseBody.usage` 加 `#[serde(default)]`
+
+**文件**：`src/llm/provider/openai_response.rs:207`
+
+```diff
+  pub(crate) struct OpenaiResponseBody {
+      pub id: String,
+      pub model: String,
+      pub output: Vec<ResponseOutputItem>,
+     #[serde(default)]
+      pub usage: Usage,
+      pub status: String,
+  }
+```
+
+**作用**：整个 `usage` 键在 JSON 中完全缺失时，自动默认 `Usage::default()`。
+
+### 5.4 变更三：`OpenaiChatResponse.usage` 加 `#[serde(default)]`
+
+**文件**：`src/llm/provider/openai.rs:245`
+
+```diff
+  pub(crate) struct OpenaiChatResponse {
+      pub id: String,
+      pub object: String,
+      pub created: u64,
+      pub model: String,
+      pub choices: Vec<Choice>,
+     #[serde(default)]
+      pub usage: crate::llm::types::usage::Usage,
+      #[serde(skip_serializing_if = "Option::is_none")]
+      pub system_fingerprint: Option<String>,
+      #[serde(skip_serializing_if = "Option::is_none")]
+      pub service_tier: Option<ServiceTier>,
+  }
+```
+
+### 5.5 自动受益路径（无需变更）
+
+| 路径 | 字段 | 为何已安全 |
+|------|------|-----------|
+| `OpenaiChatChunk.usage` | `Option<Usage>` | `Option` 天然兜底 `None`；`Some({不全})` 被 `Usage` struct-level `#[serde(default)]` 兜住。注意：此路径仅用于流式反序列化，API 流式 last chunk 的 usage 通常完整，受益场景概率极低 |
+| `MessageResponse.usage` | `Usage`（IR 层） | IR 层不直接反序列化 JSON，只从 provider 传递已解析的值 |
+
+### 5.6 未覆盖的已知边界
+
+```rust
+// ponytail: #[serde(default)] handles missing key; null usage not observed from API,
+// but if it appears, add deserialize_with to map null → Usage::default()
+```
+
+`"usage": null` 会导致 serde 尝试将 `null` 反序列化为 `Usage` 结构体，当前方案无法兜底。当前未观察到该行为，暂不处理。
+
+### `total_tokens` 缺失时的语义不一致
+
+当 API 返回 `{"prompt_tokens": 10, "completion_tokens": 5}` 但缺失 `total_tokens` 时，struct-level `#[serde(default)]` 使 `total_tokens = 0`，而非 `10 + 5 = 15`。`CostTracker::add` 使用 `saturating_add` 不会崩溃，但聚合统计中 `total_tokens` 可能不等于 `prompt_tokens + completion_tokens` 之和。此行为与流式 `PartialUsage::into_usage()` 的 `unwrap_or(0)` 一致，属于已知的简化取舍。
+
+### Responses API 流式路径 usage 恒为零（pre-existing）
+
+`ResponseSseMeta`（`openai_response.rs:335-340`）不包含 `usage` 字段，导致流式 `response.completed` 事件的 token 用量信息未被捕获，`MessageComplete.full_response.usage` 恒为零。这是一个独立于本次变更的 pre-existing 缺陷。阻塞路径加 `#[serde(default)]` 后，两条路径行为一致（皆为零值），不引入新差异。此问题建议作为后续独立跟踪项处理。
+
+### 5.7 效应链路
+
+```
+Usage struct-level #[serde(default)]
+  ├─ OpenaiResponseBody.usage: Usage         ← 子字段缺失兜住
+  │    └─ field-level #[serde(default)]       ← 整个 key 缺失兜住
+  ├─ OpenaiChatResponse.usage: Usage          ← 子字段缺失兜住（自动受益）
+  │    └─ field-level #[serde(default)]       ← 整个 key 缺失兜住（新增）
+  └─ OpenaiChatChunk.usage: Option<Usage>     ← 子字段缺失兜住（自动受益，无需改动）
+       └─ Option 已有 skip_serializing_if     ← None 时跳过
+```
+
+## 6. 实施步骤
+
+| 步骤 | 文件 | 操作 | 验证 |
+|------|------|------|------|
+| 1 | `src/llm/types/usage.rs:3` | 加 `#[serde(default)]` | `cargo build` |
+| 2 | `src/llm/provider/openai_response.rs:207` | 加 `#[serde(default)]` | `cargo build` |
+| 3 | `src/llm/provider/openai.rs:245` | 加 `#[serde(default)]` | `cargo build` |
+| 4 | `openai_response.rs` tests 模块 | 加 4 个测试用例 | `cargo test` |
+| 5 | 全量检查 | `cargo test && cargo clippy` | 无失败/新增警告 |
+
+**预计时长**：30 分钟（含测试编写与验证）。
+
+## 7. 验证标准
+
+- [ ] `Usage` 结构体三个 token 字段在 JSON 缺失时不报错，默认值为 `0`
+- [ ] `OpenaiResponseBody.usage` 键在 JSON 中完全缺失时不报错，默认 `Usage::default()`
+- [ ] `OpenaiChatResponse.usage` 键在 JSON 中完全缺失时不报错，默认 `Usage::default()`
+- [ ] 序列化行为不受影响（输出 JSON 仍包含全部 token 字段）
+- [ ] `cargo test` 全部通过
+- [ ] `cargo clippy` 无新增警告
+- [ ] dc-management 项目 `llm_collect`（AI 探索）命令正常返回结果（agcore 发布后由 dc-management 侧执行）
+- [ ] dc-management 项目 `llm_chat`（普通聊天）命令正常响应（agcore 发布后由 dc-management 侧执行）
+- [ ] 序列化后反序列化 roundtrip 验证字段值不变
+- [ ] `CostTracker` 和 `session.usage()` 的聚合逻辑不依赖 `total_tokens == prompt_tokens + completion_tokens` 恒等式
+
+### 测试清单
+
+| 测试名 | 场景 | 输入 | 断言 |
+|--------|------|------|------|
+| `deserialize_missing_usage_fields` | usage 存在但缺子字段 | `"usage": {"prompt_tokens": 5}` | 缺省字段默认 0 |
+| `deserialize_missing_usage_key` | 整个 usage key 缺失 | 无 `usage` 字段 | `Usage::default()` |
+| `deserialize_empty_usage_object` | `usage: {}` | 空对象 | 全字段默认 0/None |
+| `deserialize_full_usage_with_details` | 完整 usage（含 details） | 含所有字段 | 正确解析，类型不变 |
+| `deserialize_usage_missing_prompt_tokens` | 精确复现报错场景：usage 存在但缺 `prompt_tokens` | `"usage": {"completion_tokens": 5, "total_tokens": 5}` | `prompt_tokens` 默认 0 |
+| `deserialize_response_body_missing_usage_key` | `OpenaiResponseBody` 上下文中 usage key 完全缺失 | 完整 `OpenaiResponseBody` JSON 无 `usage` | `usage == Usage::default()` |
+| `deserialize_chat_response_missing_usage_key` | `OpenaiChatResponse` 上下文中 usage key 完全缺失 | 完整 `OpenaiChatResponse` JSON 无 `usage` | `usage == Usage::default()` |
+| `deserialize_chat_response_missing_usage_fields` | `OpenaiChatResponse` 的 usage 存在但缺子字段 | 完整 `OpenaiChatResponse` JSON，`usage` 仅含 `prompt_tokens` | 缺省字段默认 0 |
+| `serialize_deserialize_roundtrip` | 序列化后反序列化，验证字段值不变 | 完整 `Usage` 结构体 | roundtrip 后字段值一致 |
+
+## 8. 回滚方案
+
+逐个 revert 三个文件中的 `#[serde(default)]` 行，删除对应的测试用例。回滚后功能恢复原状（无数据迁移、无配置变更）。
+
+## 9. 非目标
+
+- 不修改 `Usage` 字段类型（保持 `u32`，不改为 `Option<u32>`）
+- 不修改流式路径（`PartialUsage` / `ResponseSseMeta` 的 usage 捕获问题单独处理）
+- 不修改其他 provider（`Anthropic` / `Ollama`，它们有自己的反序列化逻辑）
+- 不处理 `"usage": null` 边界（未观察到，留 `ponytail:` 注释）
+
+## 10. 风险评估
+
+| 风险 | 影响 | 可能性 | 应对方向 |
+|------|------|--------|---------|
+| `"usage": null` 反序列化失败 | 崩溃 | 低 | 未观察到；留 ponytail 注释 |
+| 零值 Usage 掩盖 API 异常 | 计费数据不全 | 低 | `CostTracker::add` 可加 `warn!` 日志 |
+| `prompt + completion ≠ total` | 聚合语义不一致 | 低 | `PartialUsage` 已有同样行为，接受 |
+| 下游依赖升级后反序列化行为变化 | 无 | 极低 | 类型不变、字段名不变 |
+
+## 11. 术语表
+
+| 术语 | 定义 | 说明 |
+|------|------|------|
+| blocking 路径 | `LlmProvider::chat()` 非流式调用 | 单次 HTTP 请求，完整 JSON 响应后一次性解析 |
+| streaming 路径 | `LlmProvider::chat_stream()` 流式调用 | 通过 SSE 逐事件推送，usage 可选 |
+| `#[serde(default)]` | serde 属性宏 | 反序列化时缺失字段使用类型的 `Default` 实现填充 |
+
+## 12. 历史版本
+
+| 版本 | 日期 | 变更说明 |
+|------|------|---------|
+| v1 | 2026-07-27 | 初始版本，基于 PRD 1 推演 |
@@ -0,0 +1,222 @@
+# 模板编译器 UTF-8 编码修复方案
+
+- 状态：Approved（第 1 轮审查通过，已按审查结论修正）
+- 作者：think
+- 日期：2026-08-03
+- 关联 PRD：`design/prd/2-模板编译器UTF-8编码修复需求.md`
+
+## 1. 背景与目标
+
+agcore 的 `src/prompt/template.rs` 模板编译器有 6 处 `bytes[i] as char`（将 UTF-8 字节逐字节强转为 Unicode 码点，等价 Latin-1 解码），导致含中文等多字节字符的模板经 `compile → render` 后产生 mojibake 乱码，且乱码会原样发送给 LLM。下游 dc-management 的 system 提示词（采集策略 validator / collector）已全部乱码，属静默失败——模型在容忍乱码的情况下继续工作，但提示词中的规则约束已被破坏。
+
+目标（对齐 PRD §1、§4 v1）：
+
+- 统一修复 6 处逐字节强转，非 ASCII 文本逐字符正确保留
+- 补充回归测试（模板编译器首次补测试）
+- 版本 0.3.6 → 0.3.7，patch 发布
+- 公开 API 不变、ASCII 模板行为零变化
+
+## 2. 需求推演概要
+
+### 2.1 需求拆解
+
+v1 必做三项：6 处修复（含 parse_tag 内标签内容）、回归测试、版本号更新。v2 无。
+
+非目标：不重构语法、不加新功能、不改公开 API、不修改其他模块（全库已扫描确认无同类风险点）、不涉及下游回切决策。裸闭合标签（顶层出现 `{{/xxx}}`）的静默截断行为（template.rs L248-249 既有 `tag.starts_with("/") => break`）不在本次修复范围，后续单独评估。
+
+### 2.2 边界识别
+
+- 模板语法标签（`{{`、`}}`、`#if`、`#each`、`#raw`）均为 ASCII，字节比较判断语法安全，保持不变
+- 非 ASCII 文本必须逐字符保留（修复目标是编译输出与模板原文一致）
+- ASCII 模板行为零变化是硬约束（向后兼容，需回归测试保障）
+
+### 2.3 关键假设
+
+1. **UTF-8 结构性保证**：多字节字符的 continuation bytes 恒在 0x80–0xBF，首字节 ≥ 0xC0，而 `{`=0x7B、`}`=0x7D、`#`=0x23——任何多字节字符的任何字节都不可能等于语法字符，故 `bytes[i]` 字节比较永远不会在多字节字符内部误命中
+2. **字符边界不变量**：循环中 i 起始为 0（边界）；`{{`/`}}` 检测命中后 `end = i + 2`（`{`/`}` 各 1 字节，保持边界）；字符推进按 `len_utf8()`（保持边界）。因此 `template[i..]` 切片不会 panic
+3. 6 处 `as char` 是全库唯一编码风险点（grep `as char|char::from` 确认仅 template.rs 6 处）
+4. 模板文件经 `include_str!` 加载有编译期 UTF-8 校验，编码问题不可能存在；日志/发送链路无转码——问题仅存在于模板编译器的内存字符串处理
+
+## 3. 当前问题分析
+
+### 3.1 根因
+
+6 处 `bytes[i] as char` 明细：
+
+| 行号 | 函数 | 破坏内容 |
+|------|------|---------|
+| 255 | `compile_fragments` literal 分支 | 模板纯文本（主要破坏点） |
+| 275 | `parse_tag` | `{{ 标签 }}` 内部内容（当前 ASCII 变量名未触发，中文变量名同样损坏） |
+| 324 | `parse_block` else_body | `#if` else 分支块体 |
+| 326 | `parse_block` body | `#if` 分支块体 |
+| 364 | `parse_each_block` body | `#each` 块体 |
+| 389 | `parse_raw_block` content | `#raw` 块内容 |
+
+中文每字 3 字节（emoji 4 字节）被拆成多个 Latin-1 字符（0xE4→ä、0xBD→½），产生 mojibake。
+
+### 3.2 关键代码结构观察
+
+- `parse_block` / `parse_each_block` / `parse_raw_block` 遇到 `{{` 标签时用 `template[i..end]` 原样字符串切片推回（该路径天然保留 UTF-8），只有逐字节累积路径被破坏
+- `parse_tag` 当前签名 `fn parse_tag(bytes: &[u8], start: usize)` 只收字节切片，无法按字符边界推进，需要改签名
+- 4 个调用点：223（compile_fragments）/ 296（parse_block）/ 344（parse_each_block）/ 380（parse_raw_block），且宿主函数均已持有 `template: &str` 参数，调用点改换为纯机械替换
+- `bytes` 局部变量在各函数中仍被 `{{` 判断使用，不可删除
+
+## 4. 架构决策记录
+
+### ADR-1：采用「字节索引 + 字符边界推进」（方案 A）
+
+| 方案 | 描述 | 结论 |
+|------|------|------|
+| A. 字节索引 + 字符推进（采纳） | 保持 `bytes[i]` ASCII 判断，字符累积改 `template[i..].chars().next()` + `len_utf8()` 推进 | ✅ 改动最小，标签检测、`template[i..end]` 切片、递归编译逻辑零变动，正确性有结构性论证 |
+| B. 整体重构 chars 迭代器（否决） | 编译器是「索引 + 原样子串回填」混合模型，迭代器消费性导致 4 个函数的位置换算全部重写、嵌套 depth 管理重做 | ❌ 回归风险远高于收益 |
+| C. 手写 UTF-8 长度表（否决） | 避免 chars() 解码 | ❌ 引入手写 0xC0/0xE0/0xF0 分支，标准库更可靠，性能差异可忽略 |
+
+### ADR-2：`parse_tag` 签名 `&[u8]` → `&str`
+
+- 理由：类型系统强制 UTF-8 保证，未来维护者想再写 `bytes[i] as char` 必须显式 `as_bytes()`，从类型层面降低复发概率；改动成本几乎为零（1 处签名 + 4 处调用点机械替换）
+- 否决替代：内部 `from_utf8(bytes)` 转换以保持 `&[u8]` 签名——引入不可能触发的错误分支和 O(n) 校验，语义绕
+
+### ADR-3：加 `debug_assert!(template.is_char_boundary(i))`
+
+- 零成本（仅 debug 构建生效）故障信号，防未来索引推进逻辑回归
+
+## 5. 设计方案
+
+### 5.1 修复模式（6 处统一）
+
+保持 `bytes[i]` 对 ASCII 语法字符判断不变；字符累积分支统一改为：
+
+```rust
+} else {
+    debug_assert!(template.is_char_boundary(i));
+    match template[i..].chars().next() {
+        Some(ch) => {
+            // 推入对应 String（literal / content / body / else_body）
+            i += ch.len_utf8();
+        }
+        None => return Err(PromptError::Parse("模板包含非法字符序列".to_string())),
+    }
+}
+```
+
+要点：
+
+- **`None` 分支语义统一为显式失败**：6 处全部返回 `Err(PromptError::Parse("模板包含非法字符序列"))`。特别地，`compile_fragments` 的 `None` 分支**绝不能**写 `break`——顶层循环 break 后会以 `Ok(fragments)` 返回，静默丢弃模板剩余部分；其余 5 处 break 虽会落到函数末尾的 `Err`（非静默），但错误消息为「未闭合」不准确。统一显式 `Err` 使防御失效时可观测，且消息一致准确
+- **None 分支为纯防御，结构性保证下不可达**：`while i < len` + 字符边界不变量保证 `template[i..]` 非空；且 `template[i..]` 在非字符边界处切片会先 panic（str 切片要求字符边界），`chars().next()` 返回 None 实际不会发生。该分支的价值在于：未来维护者若将索引逻辑改写为宽容 API（如 `get(i..)`），防御分支仍能保证显式失败而非静默错误
+- 每字符常数开销约 2–3 倍于原逐字节路径，但模板编译是低频一次性操作（register 时编译 / register_lazy 首次 render），渲染热路径走 Fragment AST 与此无关，无需优化；纯 ASCII 快速路径属于过度设计，明确不做
+
+### 5.2 `parse_tag` 签名变更
+
+```rust
+fn parse_tag(template: &str, start: usize) -> Result<(String, usize), PromptError> {
+    let bytes = template.as_bytes(); // {{ 判断仍用字节比较
+    // ...内容累积同样按 5.1 模式按字符边界推进
+}
+```
+
+- 4 个调用点（223 / 296 / 344 / 380 行）：`parse_tag(bytes, i)` → `parse_tag(template, i)`
+- 改动后 grep `parse_tag(` 复核 4 处调用点无遗漏
+
+### 5.3 测试设计（`#[cfg(test)] mod tests` 新建于 template.rs）
+
+测试清单（对应 PRD §4 清单 + 评审增量，共 16 个用例）：
+
+| # | 测试 | 覆盖点 |
+|---|------|--------|
+| 1 | 纯中文模板 compile+render 与原文逐字符一致 | 主破坏路径 literal 恒等 |
+| 2 | 真实故障素材：PRD §3.1 原文「你是采集策略专家，负责审查已采集的产品编码结果，决策下一轮搜索方向。」及含 ★、→、中文引号「」、全角标点的样本 | 故障现场固化回归（增量 B） |
+| 3 | 中文 + `{{ var }}` 变量插值混合 | 混合渲染 |
+| 4 | 中文位于 `#if` body | 块内中文 |
+| 5 | 中文位于 `#if` else 分支 | 块内中文 |
+| 6 | 中文位于 `#each` body | 块内中文（循环变量固定 `{{item}}`，Array 用 `TemplateContext::from_json(&json!(...))` 构造） |
+| 7 | 中文位于 `#raw` 内容 | 块内中文 |
+| 8 | emoji 等 4 字节字符 | 4 字节字符保留 |
+| 9 | 多字节字符紧邻 `{{` / `}}` 边界 | 边界解析 |
+| 10 | 模板以中文结尾（EOF 边界） | 尾部边界 |
+| 11 | 空模板 | 边界 |
+| 12 | 中文 + 未闭合 `{{` → 返回 Err 且不 panic | 错误路径（增量 A），断言 `matches!(err, PromptError::Parse(_))`；None 防御分支结构性不可达、不单独设用例，本用例确保索引推进边界改动不引入 panic |
+| 13 | 纯 ASCII 模板渲染与修复前一致 | 向后兼容回归：渲染结果等于预定义期望输出（PRD §7 要求，勿做快照对比）；以 composer.rs 既有 4 个 ASCII 测试为硬基线 |
+| 14 | 中文变量名 `{{ 问候 }}` | 标签内非 ASCII 内容（增量，PRD 已有） |
+| 15 | 中文 `#if` 条件 | 标签内非 ASCII 内容（增量，PRD 已有） |
+| 16 | 嵌套块：外层 `#if` 分支内含 `#each` + 中文文本 | 嵌套块中多字节字符正确保留（审查观察补充） |
+
+测试写法约定（增量 D）：
+
+- 错误断言必须用 `matches!`（`PromptError` 只 derive 了 `Error, Debug`，无 `PartialEq`，`assert_eq!` 不可用——本模块首个测试文件最易踩的坑）
+- `#each` 循环变量硬编码为 `item`（渲染器 `child_ctx.vars.insert("item", ...)` 固定）
+- Array 构造沿用 composer.rs 既有模式：`TemplateContext::from_json(&serde_json::json!({...}))`
+- 避免对含 `TemplateValue::Object` 的渲染输出做全等断言（HashMap 无序迭代，Display 输出不稳定）
+- 测试函数签名可用 `-> Result<(), PromptError>` + `?` 或与 composer.rs 一致的 unwrap 风格
+- 测试 12 的未闭合标签错误断言：`tpl.unwrap_err()` 对 compile 返回值合法可调用（要求 `PromptTemplate: Debug`，Ok 时 panic），但 `PromptError` 无 `PartialEq`，拿 err 后无法 `assert_eq!` 比对变体；建议直接 `assert!(PromptTemplate::compile("中文{{未闭合").is_err())` 或 `matches!(tpl.unwrap_err(), PromptError::Parse(_))`
+
+### 5.4 版本号
+
+- `Cargo.toml` version 0.3.6 → 0.3.7
+- 若仓库提交 Cargo.lock，确认 lock 中 agcore 条目随 `cargo build` 更新并一并提交
+
+## 6. 实施步骤
+
+| 步骤 | 操作 | 验证 |
+|------|------|------|
+| 1 | 跑基线：`cargo test` | composer.rs 4 个 ASCII 模板测试通过（硬基线） |
+| 2 | 改 `parse_tag` 签名 + 4 调用点 | `cargo build` 通过 |
+| 3 | 6 处字符推进修复 + debug_assert | `grep -n "as char\|char::from" src/` 无结果 |
+| 4 | 新增 `#[cfg(test)] mod tests`（16 个用例） | `cargo test` 全绿 |
+| 5 | Cargo.toml 0.3.6 → 0.3.7 + Cargo.lock 同步 | 版本号确认 |
+| 6 | `cargo clippy` | 无新增警告 |
+| 7 | 步骤 2–6 的改动合并为一次提交（避免「可编译但含缺陷」的中间态单独提交），打 tag v0.3.7（发布动作由维护者执行） | tag 描述含验证指引 |
+
+## 7. 验证标准
+
+对齐 PRD §7 验收标准，并补充增量 A：
+
+- [ ] 中文模板经 compile + render 后与原文逐字符一致（含纯文本、变量插值混合、真实故障素材）
+- [ ] 中文位于 #if / #each / #raw 块体内时正确保留
+- [ ] emoji 等 4 字节字符正确保留
+- [ ] 多字节字符紧邻 {{ / }} 边界时解析正确
+- [ ] 模板以中文结尾、空模板等边界场景不 panic
+- [ ] 中文 + 未闭合标签 → 返回 Err 且不 panic（增量 A）
+- [ ] 纯 ASCII 模板渲染结果与修复前完全一致（composer.rs 4 个测试为基线全部通过，新测试断言等于预定义期望输出）
+- [ ] 6 处逐字节强转全部消除（grep `as char|char::from` 于 `src/` 无结果）
+- [ ] cargo test 全部通过（含新增 16 个测试）
+- [ ] cargo clippy 无新增警告
+- [ ] Cargo.toml 版本为 0.3.7
+
+## 8. 发布计划
+
+| 阶段 | 范围 | 说明 |
+|------|------|------|
+| v1 | 6 处修复 + 16 个回归测试 + 版本号 0.3.7 | 本方案范围 |
+| 发布 | 打 tag v0.3.7，推送 origin | 实际发布动作由维护者执行 |
+| 发布说明 | `git tag -a v0.3.7` tag 描述（增量 E）： | 不更新 CHANGELOG |
+| 下游升级 | dc-management 升级 agcore 引用至 v0.3.7 | 下游自行评估是否回切模板链路 |
+
+tag 描述建议内容（增量 E，写入发布说明）：
+
+1. 修复说明：模板编译器 UTF-8 编码修复（6 处逐字节强转改为按字符边界推进），中文模板经 compile+render 后与原文一致
+2. 最小验证代码（可复制）：
+
+```rust
+use agcore::prompt::{PromptTemplate, TemplateContext};
+let tpl = PromptTemplate::compile("你是助手：{{msg}}").unwrap();
+let mut ctx = TemplateContext::new();
+ctx.insert("msg", "你好");
+assert_eq!(tpl.render(&ctx).unwrap(), "你是助手：你好");
+```
+
+3. 行为变更提示：修复后 LLM 将从「读乱码提示词」变为「读正确提示词」，此前被破坏的规则约束（编码格式、品牌限定等）恢复生效，模型输出可能明显变化——升级后建议跑一轮真实采集对比验证后再正式切换
+
+## 9. 回滚方案
+
+- 代码回滚：`git revert` 该修复 commit，回到 0.3.6 行为
+- 下游回退：dc-management 将 agcore 依赖回退至 0.3.6 即可恢复原行为（无 API 变更，回退无迁移成本）
+- 注意：回滚即恢复乱码行为，仅作为应急手段；正确路径是验证后继续使用 0.3.7
+- 版本号冲突：`git revert` 后 Cargo.toml 回到 0.3.6，若应急后需重新发布，将撞上已发布的 v0.3.6/v0.3.7 tag，应升级至 0.3.8
+
+## 10. 历史版本
+
+| 版本 | 日期 | 变更说明 |
+|------|------|---------|
+| v1 | 2026-08-03 | 首版方案（基于 PRD v1 + 双顾问评审增量） |
+| v2 | 2026-08-03 | 第 1 轮审查结论修正：None 分支统一显式 Err（消除静默截断）、测试 13 断言措辞对齐 PRD、新增嵌套块测试 16、回滚补版本号冲突说明、grep 范围标注 src/ |
+| v3 | 2026-08-03 | 第 2 轮复审修正：§6 步骤 4 用例数 15→16 全文统一、unwrap_err 断言表述订正、§7 第 7 条补「预定义期望输出」对齐 PRD、§2.1 非目标补充裸闭合标签静默截断不在范围 |
@@ -0,0 +1,181 @@
+# PRD：Usage 字段反序列化容错
+
+**状态**：Draft
+**作者**：proposal
+**日期**：2026-07-27
+
+## 1. 核心目标
+
+为 `agcore::Usage` 结构体的必填 token 字段添加 `#[serde(default)]` 反序列化容错，使 OpenAI Response API 的 blocking（非流式）调用在火山平台返回不完整的 `usage` 字段时不再崩溃。
+
+## 2. 目标用户与场景
+
+| 用户角色 | 使用场景 | 核心诉求 |
+|---------|---------|---------|
+| dc-management 使用者 | AI 探索（产品信息采集） | 点击「AI 探索」后能正常返回结果，不因 usage 缺失而报错 |
+| dc-management 使用者 | LLM 聊天 | 普通聊天功能正常响应 |
+| dc-management 使用者 | 要素值正则化（Phase 2） | 数据归一化流程不因 usage 解析失败而中断 |
+| agcore 下游 crate | 任何使用 `agcore::llm` 且后端可能不返回完整 usage 的项目 | 反序列化鲁棒性提升 |
+
+## 3. 问题描述
+
+### 3.1 报错信息
+
+dc-management 项目调用火山引擎 Responses API 时，非流式路径报错：
+
+```
+OpenAI Response 响应解析失败 error=missing field 'prompt_tokens' at line 1 column 1581
+```
+
+### 3.2 影响面
+
+经排查，以下功能被阻断（4/5 的 LLM 命令受影响）：
+
+| 功能 | 命令 | 状态 |
+|------|------|------|
+| AI 探索（产品采集） | `llm_collect` → `workflow.rs` `.chat()` | ❌ 不可用 |
+| 普通聊天 | `llm_chat` → `llm.rs` `.chat()` | ❌ 不可用 |
+| 要素值正则化 | `llm_normalize_values` → `normalizer.rs` `.chat()` | ❌ 不可用 |
+| 数据验证 | `validator.rs` `.chat()` | ❌ 不可用 |
+| 连接验证 | `verify_llm_connection` → `chat_stream()` | ✅ 幸免（流式） |
+
+### 3.3 根因
+
+- **`llm/types/usage.rs:4-12`**：`Usage` 结构体的 `prompt_tokens`、`completion_tokens`、`total_tokens` 定义为 **必填 `u32`**，非 `Option<u32>`
+- **`llm/provider/openai_response.rs:207`**：`OpenaiResponseBody` 内嵌 `usage: Usage`，也是必填
+- 火山平台的 Responses API 返回的 `usage` 对象中，三个必填 token 子字段**缺失**（`usage` 键存在但子字段不完整），触发了 serde 反序列化的 `missing field` 错误
+- 流式路径不受影响：其 `PartialUsage` 所有字段均为 `Option<u32>`，缺失时通过 `unwrap_or(0)` 兜底
+
+### 3.4 已知线索
+
+- dc-management 的 `verify_llm_connection`（连接验证函数）**已预见到此问题**，注释明确说明特意使用流式来规避（`llm.rs:368-371`）
+- 这是已知的设计约束——流式已容错但 blocking 路径未同步加固
+
+## 4. 功能清单
+
+### v1 必做
+
+- **`Usage` 结构体加 struct-level `#[serde(default)]`**（`src/llm/types/usage.rs:3`）：
+  ```diff
+  - #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+  + #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+  + #[serde(default)]
+    pub struct Usage {
+        pub prompt_tokens: u32,
+        pub completion_tokens: u32,
+        pub total_tokens: u32,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub completion_tokens_details: Option<CompletionTokensDetails>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub prompt_tokens_details: Option<PromptTokensDetails>,
+    }
+  ```
+  - 作用：JSON 中缺失 `Usage` 的**任何**子字段时，自动使用 `Default::default()` 取值
+  - 三个 token 字段：缺失时默认 `0`
+  - 两个 `Option` 详情字段（`completion_tokens_details` / `prompt_tokens_details`）：缺失时默认 `None`
+  - **类型全部保持不动**，不改为 `Option`，不丢失语义
+  - 等效代码行数：1 行
+
+- **`OpenaiResponseBody.usage` 加 `#[serde(default)]`**（`src/llm/provider/openai_response.rs:207`）：
+  ```diff
+    pub(crate) struct OpenaiResponseBody {
+        pub id: String,
+        pub model: String,
+        pub output: Vec<ResponseOutputItem>,
+  +     #[serde(default)]
+        pub usage: Usage,
+        pub status: String,
+    }
+  ```
+  - 作用：整个 `usage` 键在 JSON 中完全缺失时，自动默认 `Usage::default()`
+  - 等效代码行数：1 行
+
+**变更合计：2 行 serde 属性宏，零逻辑变更，零类型变更。**
+
+### v1 可选
+
+- 无（上述两项即可完整修复）
+
+### v2 考虑
+
+- 无——struct-level `#[serde(default)]` 已覆盖所有子字段，`completion_tokens_details` / `prompt_tokens_details` 的 `#[serde(default)]` 需求已在 v1 中一并解决
+- 流式路径的 `ResponseSseMeta` 不包含 `usage` 字段（`src/llm/provider/openai_response.rs:335-340`），`response.completed` 事件的 usage 信息未被捕获。这是一个独立的缺陷，与当前问题无关，建议单独处理
+
+### 非目标
+
+- 不修改 `Usage` 字段类型（保持 `u32`，不改为 `Option<u32>`）
+- 不修改流式路径（`PartialUsage` 的 usage 捕获问题单独处理）
+- 不修改其他 provider（`OpenaiChat` / `Anthropic`），它们有自己的反序列化逻辑
+
+## 5. 边界与假设
+
+| 边界 / 假设 | 来源 | 说明 |
+|-------------|------|------|
+| `Usage` 已 derive `Default` | 代码确认 | `#[serde(default)]` 直接使用 `Default` 实现（全字段 `0`） |
+| 缺失字段默认 0 对所有消费者安全 | 代码审查 | 所有消费方（`CostTracker::add`、`MessageResponse` 使用处）都在做 `saturating_add`，`0` 是安全值。流式路径的 `PartialUsage.into_usage()` 已经 `unwrap_or(0)`，行为一致 |
+| 序列化行为不受影响 | serde 语义 | `#[serde(default)]` 仅在反序列化缺失字段时生效，不影响序列化输出 |
+| 报错提示的 `missing field` 确认是子字段缺失而非整个 usage 缺失 | 错误消息分析 | 错误消息 `missing field 'prompt_tokens'` 说明 JSON 路径 `usage.prompt_tokens` 不存在即键 `usage` 存在但子字段缺失，因此 `#[serde(default)]` 加在子字段上是必要条件 |
+
+## 6. 术语表
+
+| 术语 | 定义 | 说明 |
+|------|------|------|
+| blocking 路径 | `LlmProvider::chat()` 非流式调用 | 发送单个 HTTP 请求，等待完整 JSON 响应后一次性解析 |
+| streaming 路径 | `LlmProvider::chat_stream()` 流式调用 | 通过 SSE 逐事件推送，usage 可选 |
+| `#[serde(default)]` | serde 属性宏 | 反序列化时如果字段缺失，使用类型的 `Default` 实现填充 |
+| Responses API | OpenAI 标准 `POST /responses` 协议 | 区别于 Chat Completions（`POST /chat/completions`） |
+
+## 7. 验收标准
+
+- [ ] `Usage` 结构体三个 token 字段在 JSON 缺失时不报错，默认值为 `0`
+- [ ] `OpenaiResponseBody.usage` 键在 JSON 中完全缺失时也不报错，默认值为 `Usage::default()`
+- [ ] dc-management 的 `llm_collect`（AI 探索）命令正常返回结果
+- [ ] dc-management 的 `llm_chat`（普通聊天）命令正常响应
+- [ ] 已有序列化行为不受影响（输出 JSON 仍包含全部 token 字段）
+- [ ] `cargo test` 全部通过
+- [ ] `cargo clippy` 无新增警告
+- [ ] 补两条反序列化测试：
+  - `response_api_missing_usage_fields` — mock 响应中 `usage` 对象缺失 `prompt_tokens` / `completion_tokens` / `total_tokens`，验证不报错且 usage 字段全为 0
+  - `response_api_missing_usage_key` — mock 响应中完全没有 `usage` 键，验证不报错且默认 `Usage::default()`
+
+## 8. 风险评估
+
+| 风险 | 影响 | 可能性 | 应对方向 |
+|------|------|--------|---------|
+| 下游 crate 升级 agcore 后依赖 usage 字段不缺失 | 无——`#[serde(default)]` 不改变已有行为 | 极低 | 类型不变、字段名不变 |
+| 序列化时 `#[serde(default)]` 影响输出 | 无——`#[serde(default)]` 只影响反序列化 | 极低 | serde 明确语义 |
+| 测试覆盖不足 | 当前 mock 响应均携带完整 usage，不会触发新路径 | 中 | 建议加一条 usage 缺失的测试用例 |
+
+## 9. 发布计划（可选）
+
+| 阶段 | 范围 | 时间 |
+|------|------|------|
+| v1 | 两处变更（usage.rs 3 字段 + openai_response.rs 1 字段） | 即日 |
+| 发布 | 打 tag（如 `v0.3.6` 或 `v0.3.5-usage-fix`），更新 dc-management 引用 | 即日 |
+
+## 10. 历史版本
+
+| 版本 | 日期 | 变更说明 |
+|------|------|---------|
+| v1 | 2026-07-27 | 人工种子（原始） |
+
+### 种子内容
+
+发起方：dc-management 项目 `src/routes/products/ai-explore/` 页面「AI 探索」功能报错
+
+报错信息：
+
+```
+OpenAI Response 响应解析失败 error=missing field 'prompt_tokens' at line 1 column 1581
+```
+
+根因：
+
+- `src/llm/types/usage.rs` 中 `Usage` 结构的 `prompt_tokens`, `completion_tokens`, `total_tokens` 为必填 `u32`
+- `src/llm/provider/openai_response.rs` 的 `OpenaiResponseBody` 内嵌 `usage: Usage`
+- 火山平台 Responses API 返回的 usage 子字段缺失 → serde 反序列化失败
+
+修复方向：
+
+- `Usage` 三字段加 `#[serde(default)]`（缺失时默认 0）
+- `OpenaiResponseBody.usage` 加 `#[serde(default)]`（整个缺失时默认 Usage::default()）
@@ -0,0 +1,172 @@
+# PRD：模板编译器 UTF-8 编码修复
+
+**状态**：Draft
+**作者**：proposal
+**日期**：2026-08-03
+
+## 1. 核心目标
+
+修复 `agcore::prompt::PromptTemplate` 模板编译器（`src/prompt/template.rs`）对非 ASCII（UTF-8）文本的编码破坏问题：当前 6 处 `bytes[i] as char` 将 UTF-8 字节逐字节强转为 Unicode 码点（等价 Latin-1 解码），导致所有含中文等多字节字符的模板经 `compile → render` 后输出乱码（mojibake），且该乱码会原样发送给 LLM。本次修复使模板编译器对非 ASCII 文本逐字符正确保留，同时保持 ASCII 模板行为完全不变。
+
+## 2. 目标用户与场景
+
+| 用户角色 | 使用场景 | 核心诉求 |
+|---------|---------|---------|
+| agcore 下游 crate（如 dc-management） | 使用 `PromptTemplate` 编译中文 system prompt 模板（validator / collector 采集策略） | 模板文本经编译渲染后与原文一致，不产生乱码 |
+| agcore 下游 crate | 使用 `PromptTemplate` 的 `#if` / `#each` / `#raw` 块语法，块体内含中文 | 块内容逐字符正确保留 |
+| agcore 维护者 | 修复后发布 patch 版本，下游可升级 | 公开 API 不变、ASCII 行为不变、有回归测试保障 |
+
+## 3. 问题描述
+
+### 3.1 现象
+
+dc-management 项目的探索调试日志（`log/explore-20260803-013158915066.txt`）显示：发送给 LLM 的 system 提示词全部乱码：
+
+```
+ä½ æ¯éä¾ç¥ç¥ä¸å®¶ï¼è´è´£å®¡æ¥å·²éäº§åç¼ç ç»æï¼å³çä¸ä¸è½®æç´¢æ¹åã
+```
+
+（原文为「你是采集策略专家，负责审查已采集的产品编码结果，决策下一轮搜索方向。」）
+
+日志中的 user 消息与 LLM 响应均为正常中文，证明：乱码发生在**内存字符串**中（模板编译阶段），实际发送给 LLM 的请求体就是损坏文本；日志文件本身（纯 UTF-8 直写）只是如实记录了已损坏的内容。该缺陷为静默失败——模型在容忍乱码的情况下继续工作，但提示词中的规则约束（编码格式、品牌限定等）已被破坏，直接影响下游采集质量。
+
+### 3.2 根因
+
+`src/prompt/template.rs` 共 6 处 `bytes[i] as char`（将 UTF-8 字节逐字节强转为 Unicode 码点，等价 Latin-1 解码）：
+
+| 行号 | 位置 | 破坏内容 |
+|------|------|---------|
+| 255 | `compile_fragments` literal 分支 | 模板纯文本（**主要破坏点**） |
+| 275 | `parse_tag` | `{{ 标签 }}` 内部内容（当前为 ASCII 变量名，未触发；若使用中文变量名同样损坏） |
+| 324 | `parse_block` else_body | `#if` 分支的 else 块体 |
+| 326 | `parse_block` body | `#if` 分支块体 |
+| 364 | `parse_each_block` body | `#each` 块体 |
+| 389 | `parse_raw_block` content | `#raw` 块内容 |
+
+中文 UTF-8 编码每字 3 字节（emoji 等 4 字节），被拆成多个 Latin-1 字符（如 `0xE4 → ä`、`0xBD → ½`），产生 mojibake。所有经 `PromptTemplate::compile → render` 链路的非 ASCII 模板文本均被破坏。
+
+### 3.3 影响面
+
+- 所有使用 `PromptTemplate` 且模板含非 ASCII 文本的 agcore 下游项目
+- dc-management 的采集策略（validator）与产品信息采集（collector）两条 system prompt 链路全部受影响
+- 已确认模板文件本身为合法 UTF-8、日志写出链路无转码、发送链路无转码——问题仅存在于模板编译器
+
+### 3.4 已知线索
+
+- 下游使用 `include_str!` 宏加载模板文件（如 dc-management 的 `src-tauri/src/llm/prompts.rs`），该宏具有编译期 UTF-8 校验：非法编码的模板文件在编译期即报错，故模板文件编码问题不可能存在
+- agcore 仓库 `src/prompt/template.rs` 当前没有任何测试（无 `#[cfg(test)]` 模块），本次为模板编译器首次补测试
+- 模板语法标签（`{{ }}`、`#if`、`#each`、`#raw`）均为 ASCII，字节比较判断语法是安全的，无需改动
+
+## 4. 功能清单
+
+### v1 必做
+
+- **统一修复 6 处 `bytes[i] as char`**（`src/prompt/template.rs` 255 / 275 / 324 / 326 / 364 / 389 行）：
+  - 保持现有 `bytes[i]` 对 ASCII 语法字符（`b'{'` / `b'}'` 等）的字节判断不变
+  - 字符累积改为按 UTF-8 字符边界推进：从当前位置取完整字符（如 `template[i..].chars().next()`），再按该字符的 UTF-8 长度推进索引（`i += ch.len_utf8()`）
+  - 效果：非 ASCII 文本（中文 / emoji / 任意多字节字符）逐字符正确保留；ASCII 文本行为与修复前完全一致
+
+- **补充回归测试**（`src/prompt/template.rs` 新建 `#[cfg(test)] mod tests`）：
+  - 纯中文模板 compile + render 后与原文逐字符一致（主破坏路径 literal）
+  - 中文文本 + `{{ var }}` 变量插值混合渲染正确
+  - 中文文本位于 `#if` / `#each` / `#raw` 块体内时正确保留
+  - emoji 等 4 字节字符正确保留
+  - 多字节字符紧邻 `{{` / `}}` 标签边界的解析正确性
+  - 纯 ASCII 模板渲染结果与修复前一致（向后兼容回归）
+  - 标签内部含非 ASCII 内容（中文变量名如 `{{ 问候 }}`、中文 `#if` 条件）的解析与渲染正确 ← PM Advisor
+
+- **版本号更新**：`Cargo.toml` version `0.3.6` → `0.3.7`
+
+### v1 可选
+
+- 无（上述三项即可完整修复）
+
+### v2 考虑
+
+- 无。CHANGELOG 记录暂不做（本次需求明确暂不记录），后续版本若需要可单独补充
+
+### 非目标
+
+- 不重构模板语法（标签体系、块结构保持现状）
+- 不新增模板功能（新标签、新渲染特性）
+- 不改动公开 API（`PromptTemplate::compile` / `render` 签名与语义不变）
+- 不修改其他模块（已扫描 `as char` / `from_utf8_lossy` 等模式，项目中无同类编码风险点）
+- 不涉及下游 dc-management 是否回切模板链路的决策（由下游另行评估）
+
+## 5. 边界与假设
+
+| 边界 / 假设 | 来源 | 说明 |
+|-------------|------|------|
+| ASCII 语法判断可保留 | 语法分析 | 模板标签均为 ASCII（`{`、`}`、`#`、`/`、`>`），`bytes[i]` 字节比较对 ASCII 安全 |
+| 非 ASCII 文本必须逐字符保留 | 需求确认 | 修复目标是编译输出与模板原文一致 |
+| ASCII 模板行为零变化 | 需求确认 | 向后兼容是硬约束，需回归测试保障 |
+| 公开 API 不变 | 需求确认 | `compile` / `render` 签名不变，下游无需改代码 |
+| 修复范围 6 处统一 | 用户确认 | 「尽可能全面的修复」，包括 parse_tag 内的变量名内容 |
+| 测试纳入本次范围 | 用户确认 | 用户明确要求补充测试 |
+| 版本为 patch（0.3.7） | 用户确认 | bug 修复走 patch 版本，尽快让下游升级 |
+| CHANGELOG 暂不记录 | 用户确认 | 本次发布不更新 CHANGELOG |
+
+## 6. 术语表
+
+| 术语 | 定义 | 说明 |
+|------|------|------|
+| mojibake | 乱码 | 文本因编码解码不匹配产生的字符错乱，此处为 UTF-8 字节被按 Latin-1 逐字节解码 |
+| Latin-1 | ISO-8859-1 单字节编码 | 0x00–0xFF 每个字节对应一个 Unicode 码点；`u8 as char` 等价于该解码 |
+| `len_utf8()` | Rust 标准库方法 | 返回 `char` 的 UTF-8 编码长度（1–4 字节），用于按字符边界推进索引 |
+| `PromptTemplate` | agcore 提示词模板引擎 | 支持变量插值 `{{ var }}`、条件渲染 `#if`、循环 `#each`、原始块 `#raw` |
+
+## 7. 验收标准
+
+- [ ] 中文模板经 `compile` + `render` 后与原文逐字符一致（含纯文本、变量插值混合）
+- [ ] 中文位于 `#if` / `#each` / `#raw` 块体内时正确保留
+- [ ] emoji 等 4 字节字符正确保留
+- [ ] 多字节字符紧邻 `{{` / `}}` 边界时解析正确
+- [ ] 纯 ASCII 模板渲染结果与修复前完全一致（以 `src/prompt/composer.rs` 既有 4 个 ASCII 编译测试为基线全部通过，新测试断言等于预定义期望输出）← PM Advisor
+- [ ] 6 处逐字节强转全部消除（grep 模式 `as char|char::from` 验证）← PM Advisor
+- [ ] `cargo test` 全部通过（含新增测试）
+- [ ] `cargo clippy` 无新增警告
+- [ ] `Cargo.toml` 版本为 0.3.7
+
+## 8. 风险评估
+
+| 风险 | 影响 | 可能性 | 应对方向 |
+|------|------|--------|---------|
+| 索引推进改动引入边界回归（模板尾部、空模板、`{{` 未闭合） | 解析错误或 panic | 中 | 新增测试覆盖边界；保持 ASCII 判断逻辑不变 |
+| parse_tag 内标签内容的解码方式与 literal 不一致 | 中文变量名场景损坏残留 | 低 | 6 处统一采用同一修复模式 |
+| 下游对 0.3.7 的升级未验证中文模板 | 下游继续受影响 | 中 | tag 描述中明确修复内容与最小验证步骤（编译含中文的模板对比输出）← PM Advisor |
+| 未来新增模板代码时再次引入逐字节强转 | 同类 bug 复发 | 低 | 回归测试（中文断言）可捕获此类问题 |
+
+## 9. 发布计划
+
+| 阶段 | 范围 | 说明 |
+|------|------|------|
+| v1 | 6 处修复 + 回归测试 + 版本号 0.3.7 | 本 PRD 范围 |
+| 发布 | 打 tag `v0.3.7`，推送 origin | 实际发布动作由维护者执行 |
+| 发布说明 | 以 `git tag -a v0.3.7` 的 tag 描述作为发布说明载体（附最小验证：编译含中文的模板并对比输出）← PM Advisor | 不更新 CHANGELOG，tag 描述随仓库分发 |
+| 下游升级 | dc-management 升级 agcore 引用至 v0.3.7 | 下游自行评估是否回切模板链路 |
+
+## 10. 历史版本
+
+| 版本 | 日期 | 变更说明 |
+|------|------|---------|
+| v1 | 2026-08-03 | 人工种子（原始） |
+
+### 种子内容
+
+发起方：dc-management 项目排查探索调试日志 `log/explore-20260803-013158915066.txt`，发现发送给 LLM 的 system 提示词乱码。
+
+原始需求描述（一字不改）：
+
+「检查一下当前日志 log 目录中保存的日志文件，似乎现在发送给LLM的提示词存在乱码？」
+
+根因：
+
+- `src/prompt/template.rs` 中 6 处 `bytes[i] as char`（255 / 275 / 324 / 326 / 364 / 389 行）将 UTF-8 字节逐字节强转为 Unicode 码点（等价 Latin-1 解码），非 ASCII 模板文本被破坏
+- 日志文件、发送链路、模板文件编码均无问题，乱码发生在内存字符串（模板编译阶段）
+
+修复方向（用户确认）：
+
+- 6 处统一修复：保持 ASCII 语法判断不变，字符累积按 UTF-8 字符边界推进
+- 补充回归测试（中文模板恒等、混合插值、块内中文、emoji、边界、ASCII 回归）
+- `Cargo.toml` 0.3.6 → 0.3.7，打 tag `v0.3.7`
+- CHANGELOG 暂不记录
@@ -5,7 +5,8 @@
 > **已分版本的内容**：请查阅
 > - [`roadmap-v0.1.0.md`](./roadmap-v0.1.0.md) — Phase 0–4c + v0.1.0 Release
 > - [`roadmap-v0.2.0.md`](./roadmap-v0.2.0.md) — Phase 5–12 + v0.2.0-rc.1
-> - [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) — Phase 13–19（13-18 已完成，19 待实施）
+> - [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) — Phase 13–19（全部完成）
+> - [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) — Phase A-E 多 Agent 编排路线图
 >
 > 返回总入口：[`roadmap.md`](./roadmap.md)

@@ -15,7 +16,7 @@

 AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可插拔的架构，提供大模型调用、提示词工程、工具系统、记忆检索四大核心能力，支持快速组合出符合业务需求的智能体应用。

-**当前状态**：v0.2.0-rc.1 已打标签。Phase 0-18 全部完成。v0.3.0 实施中，Phase 19 共 1 个增量 Phase 待交付。目标是从"LLM 调用工具箱"升级为"能构建多 Agent 协作、RAG、长记忆 Agent 产品的基础系统"。
+**当前状态**：v0.3.5。Phase 0-30 全部完成。v0.4.0 规划已确定，覆盖 5 个增量 Phase（A-E）：Swarm 编排抽象、结果聚合、Human-in-the-loop + 用户 Steering、TokenJuice 语义压缩、自动校正。目标是从"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。

 ---

@@ -35,21 +36,30 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可

 ---

-## v0.4+ 展望
+## v0.4.0 规划

-### 已规划的功能
+v0.4.0 的完整规划已移入独立的 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md)，包含 5 个增量 Phase：

-| 功能 | 说明 | 预计版本 |
-|------|------|---------|
-| Multi-Agent Swarm 编排 | Supervisor/Subgraph 模式，基于 v0.3 dispatch 构建 | v0.4 |
-| Human-in-the-loop 审批 | `interrupt()` + `Command(resume=...)` 异步审批回调 | v0.4 |
-| Agent 自动创生 | LLM 自主决定何时派发子 agent、派发什么角色 | v0.4 |
-| 分布式 session 共享 | SessionManager Redis 后端支持跨进程 | v0.4 |
-| 精确 tokenizer 计数 | 引入 `tiktoken-rs`，绑定模型具体 tokenizer，替换字符估算 | v0.4+ |
-| TokenJuice 语义压缩 | 对工具结果做语义压缩而非字节截断 | v0.4+ |
-| Markdown 技能按需加载 | 技能注册表 + 按 prompt 上下文动态加载 | v0.4+ |
-| 增量 checkpoint | 仅存储变化部分，替换当前全量 JSON 模式 | v0.4+ |
-| RL 轨迹导出 | ShareGPT 格式轨迹、Atropos 集成 | v0.4+ |
+| Phase | 内容 | 状态 |
+|-------|------|------|
+| **Phase A** | Swarm 编排（Star/Sequential/Hierarchical + Subgraph） | 📋 待实施 |
+| **Phase B** | 结果聚合 + 编排模式完善 | 📋 待实施 |
+| **Phase C** | Human-in-the-loop + 用户 Steering | 📋 待实施 |
+| **Phase D** | TokenJuice 语义压缩（工具结果/历史/跨 Agent） | 📋 待实施 |
+| **Phase E** | 自动校正 / Reflection | 📋 待实施 |
+
+### 未来版本（v0.5+）
+
+以下功能已从 v0.4 范围移出：
+
+| 功能 | 说明 |
+|------|------|
+| Agent 自动创生 | LLM 自主决定何时派发子 agent — 设计复杂，v0.4 专注显式声明式编排 |
+| 分布式 session 共享（Redis 后端） | 与编排正交，多数用户单进程即可 |
+| 精确 tokenizer 计数（tiktoken-rs） | 依赖引入，不在 v0.4 核心范围内 |
+| 增量 Checkpoint | 存储优化，当前全量 JSON 够用 |
+| 路线 B（StateGraph 通用图引擎） | 预留为路线 A 的未来升级路径 |
+| RL 轨迹导出 | 专项需求 |

 ### 明确不做（agcore 范围外）

@@ -74,10 +84,10 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可

 ## 下一步行动

-1. **v0.3.0 Phase 19 启动**：KnowledgeGraph + 双通道检索，落地 `docs/note-knowledge-graph-design.md` 中记录的知识图谱设计
-2. **Phase 19 收尾**：完成 v0.3.0 最后一个 Phase 后准备 rc.1 标签 + CHANGELOG
-3. **示例先行**：完成 Phase 19 后立即创建对应的 knowledge_graph_demo 示例，确保 `cargo run --example` 可验证
-4. **里程碑追踪**：以 M13（Phase 17）+ M14（Phase 18）为已达成里程碑，逐 Phase 推进 M15
+1. **v0.4.0 启动**：按 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) 规划，从 Phase A（Swarm 编排）开始实施
+2. **Phase A 实施**：engine/supervisor.rs + tools/builtin.rs + Swarm::star/sequential/hierarchical
+3. **示例先行**：每个 Phase 交付时同步提交对应的示例程序
+4. **里程碑追踪**：以 M16-M20 为目标里程碑，逐 Phase 推进

 ---

@@ -107,3 +117,84 @@ AG Core 定位为构建 AI 智能体的底层工具箱，通过模块化、可
 - ✅ **v0.3.0 Phase 16 完成** — `SummaryConfig` 配置结构体（6 个字段：`trigger_token_ratio=0.75` / `max_context_tokens=32_000` / `summary_prompt` / `debounce_turns=3` / `summary_model=None` / `max_tool_result_chars=500`，默认 `None` 沿用主模型避断裂非 OpenAI 用户）+ `AgentBuilder::summary_config(cfg)` 链式方法 + `AgentConfig.summary_config: Option<SummaryConfig>` 字段；`AgentSession` 新增 `last_summary_turn: Option<u32>` 字段（首次不受防抖约束，`should_summarize` 用 `Option` 哨兵实现）+ `maybe_summarize(current_turn)` 内联检查点（OnTurnEnd 之后 / `turn_index` 之前，对称 `submit_turn` / `finalize_turn` 两个入口，流式路径 `saturating_sub(1)` 修正）+ 关联函数 `generate_summary`（构造独立 `LlmCycle` 调 `submit_messages` 传 `vec![Message::user_text(prompt)]`，`max_tokens=1024`，空消息守卫直接返回空串）+ 公开 API `get_conversation_summary()`；`src/agent/summary.rs`（~240 行，含 8 个 SummaryConfig/`format_messages_as_text` 内联测试——默认值/空输入/系统用户助理/ToolResult（含 `tool_call_id`）/工具调用/Unicode 安全截断/整体 30K 截断保留最新；有效字符数截断多字节安全，droptest 验证保留尾部消息）+ `src/agent/session.rs` 注入 10 个摘要集成测试（默认值不触发 / 超阈值触发 / 防抖阻止重复 / SessionMemory 写入 / Full 模式不注入 / 失败不阻断主流程 / 流式路径触发 / 默认配置零影响 / **Focused `summary_override` 写入正向验证** / **空消息不调用 LLM** / **巨型 `max_context_tokens` 永不触发**）；`format_messages_as_text` 简洁版消息格式化（`[Tool: name]` + `Tool Result [id]:` + ToolResult 字符级 `chars().take(max_tool_result_chars)` 截断 + 整段 30K 总长度截断从头部保留最新）；所有错误静默（失败用 `tracing::error!`，成功用 `tracing::info!(turn, summary_len)`）；`MergeStrategy` 注释中过时 "Summarize 指向"与 `context.rs:78` "v0.3 将支持 Hook 驱动" 过时注释在实施时同步移除/更新；方案文档 `docs/22-phase16-summary-auto-generation.md`（471 行），实施后**两轮审查 PASS**：第一轮 PM/SA 审查 11 项问题修复 + 第二轮实施审查 9 项问题修复（🔴 `generate_summary` 空消息 bug + 🟡 W4 流式路径防抖 + 🟡 W2 模型硬编码 + 🟡 W5 Full 模式无谓 save + 🟡 W3 30K 截断 + 🟡 W6 成功无日志 + 🟡 W1/W7 测试补全 + 💭 注释同步）；零新外部依赖；全量 335 → **353**（+18 新测试，含二次审查增补 4 个），clippy 0 警告，doc 0 warning，`quick_start` 示例正常 exit 0；**M12 里程碑达成** + 第二轮审查门禁 PASS
 - ✅ **v0.3.0 Phase 17 完成** — 新建 `src/engine/` 模块（5 文件：`mod.rs`/`error.rs`/`snapshot.rs`/`checkpointer.rs`/`session_manager.rs`），实现 **SessionManager**（10 个公开方法：`create`/`create_child`/`get`/`recover`/`replace`/`children`/`parent`/`destroy`/`submit_turn`/`submit_turn_stream`/`finalize_turn_stream`，内部 `RwLock<HashMap>` + `Arc<tokio::sync::Mutex<AgentSession>>` + `Checkpointer` 组合）和 **Checkpointer**（5 个公开方法：`checkpoint`/`rollback_load`/`list_checkpoints`/`delete_all`/`latest_snapshot`）；`SessionSnapshot` 独立 struct 避开 `Arc<dyn Agent>` 不可序列化，配套 `SessionMemoryEntry` 保留 metadata/created_at；`AgentSession` 扩展三段式快照（`to_snapshot` async 读 MemoryStore + `from_snapshot` 纯同步构造 + `restore_memory` &mut self async 写回持久层）；`SessionMemory` 新增 `list_entries()` 和 `set_with_meta()` 方法（恢复时保留完整 entry 数据）；存储 key 风格统一为 `session:{id}:meta` / `ckpt:{id}:{ckpt_id}`（与 `slot_data:` 风格一致）；`EngineError` 6 个变体（含 `Memory(#[from] MemoryError)` 透传 + `Agent(#[from] AgentError)`）；`CkptMeta` 加 `created_at_nanos` 字段确保同秒内精确降序排序；ckpt_id 用纳秒+单调计数器生成（零外部依赖，ponytail）；session_id 用纳秒+计数器自动生成（统一策略，UUID v4 备选）；自动 checkpoint 失败 `tracing::error!` 不阻断主流程（不提供强持久化保证）；流式 checkpoint 仅在 `finalize_turn_stream` 创建（不留半成品污染）；孤儿策略：`destroy()` 不递归删除子 session，父被销毁后 `parent()` 返回 `Ok(None)`；3 处 derive 改动（`CostTracker` + `ContextSlot` + `MergeStrategy` 加 serde，`CostTracker` 额外加 `Clone`）；`SessionManager::recover` + `replace` 内部自动 `restore_memory` 写回持久层；零新外部依赖；方案文档 `docs/23-phase17-agent-execution-engine.md`（775 行，经两轮 PM+SA 审查 + 实施后第三轮 PM+SA+Code Reviewer 三方联合审查），实施后**两轮审查门禁 PASS**：第一轮修复 6 🔴 + 第二轮修复 2 🔴（to_snapshot 同步→async + Roadmap 同步）+ 实施后修复 8 个 🟡（restore_memory metadata/created_at 完整恢复 + &mut self 签名 + 死代码清理 + 3 个边界测试 + tracing 补全 + 文档语义统一 + 示例 rollback 一致性 assert）；15 个 `SessionManager` 内联测试（CRUD/recover/replace/树形/孤儿/auto_checkpoint on-off）+ 6 个 `Checkpointer` 内联测试（roundtrip/不存在的 ckpt/同秒降序/delete_all 幂等/latest/隔离）+ 1 个 `snapshot_deserialize_with_minimal_fields` 序列化兼容测试；全量 353 → **374**（+21 新测试），clippy 0 警告，doc 0 warning，`engine_demo` 示例端到端演示 create→submit_turn→checkpoint→rollback→replace→destroy 全链路并验证 rollback 一致性；**M13 里程碑达成** + 两轮审查门禁 PASS
 - ✅ **v0.3.0 Phase 18 完成** — 新增 `src/engine/switch.rs`（222 行）实现 `SessionManager::switch_agent()` 热切换（替换 `Arc<dyn Agent>`，slot 历史 / `turn_index` / `session_memory` / `cost_so_far` 全部保留，同步更新 `SessionMeta.agent_name` 到持久层，`created_at` / `parent_id` 保持原始不可变）+ 新增 `src/engine/sub_agent.rs`（1071 行）实现 4 个公开方法（`dispatch` / `dispatch_all` / `dispatch_stream` 与前述 `switch_agent` 共 4 个 Phase 18 核心 API）+ 3 个公开类型（`DispatchConfig` / `SubTaskResult` / `SubTaskStreamEvent`）；`DispatchConfig` 4 字段（`max_concurrency=10` / `inherit_session_memory=true` / `bridge_keys=None` / `shared_namespace=None`）+ 三态 `bridge_keys` 语义（`None` = 不继承 / `Some(vec![])` = 全部 / `Some(keys)` = 指定 keys）+ 约定式 `shared_namespace` 子↔子共享（`shared:{prefix}:{key}`）不触发自动注入；`dispatch` 流程：`create_child` → `inherit_session_memory`（快照语义）→ `submit_turn` → 返回 `SubTaskResult`；`dispatch_all` `tokio::sync::Semaphore` 并发控制 + `Vec<Result<...>>` 部分成功语义按输入顺序 indexed 收集；`dispatch_stream` `unbounded_channel` + spawn task 消息重建 + `finalize_turn` 后台落库（明确不参与 `auto_checkpoint` 防重复）；`SubTaskStreamEvent` 事件序列：`ChildCreated` → `Stream(StreamEvent) × N` → `Completed(SubTaskResult)` 或 `Error { child_id, error }`；`EngineError` 新增 `DispatchFailed(#[source] String)` 变体 + `CostTracker` 加 `From<Usage>` 转换；`save_session_meta` / `load_session_meta` 改 `pub(crate)` 供 `switch.rs` 调用；4 个端到端示例：`agent_switch_demo`（115 行）+ `sub_agent_dispatch_demo`（141 行）+ `bridge_keys_demo`（197 行）+ `dispatch_stream_demo`（121 行）全部 exit 0；17 个内联测试（4 switch + 5 dispatch + 4 dispatch_all + 4 dispatch_stream）；零新外部依赖；方案文档 `docs/24-phase18-agent-switch-and-dispatch.md`（700 行）；全量 374 → **391**（+17 新测试，0 失败），clippy 0 警告，doc 0 warning；**M14 里程碑达成**
+- ✅ **v0.3.0 Phase 19 完成** — 知识图谱 + 双通道检索，详见 `docs/25-phase19-knowledge-graph-and-retrieval.md`；全量 391 → **427 passed / 0 failed**（+36 新测试）；**M15 里程碑达成**
+- ✅ **v0.3.2 Phase 20-27 全部完成** — Cargo features 拆分（16 模块级 + 5 provider + 4 快捷组合），详见 `docs/roadmap-v0.3.2.md`；全量 427 → **427 passed**（不变，门控验证）
+- ✅ **Phase 28-30 OpenAI Response API Provider 完成** — 独立 feature `provider-openai-response`，全量约 450 passed
+- 📋 **v0.4.0 规划完成** — 5 个增量 Phase（A-E）覆盖多 Agent 编排、HITL + Steering、TokenJuice、自动校正。详见 [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md)
+
+---
+
+## 设计笔记
+
+### Checkpointer 分层存储模型
+
+> 来源：v0.4.0 规划讨论中涉及增量 Checkpoint 的技术推演。当前全量 JSON checkpoint 够用，但为未来优化预留设计方案。
+
+#### 分层叠加模型（OverlayFS 模式）
+
+受容器分层文件系统启发，增量 Checkpoint 可以借鉴 overlayfs 的"底层只读 + 上层可写叠加"设计：
+
+**全量基座（只读）**：
+```rust
+pub struct SnapshotBase {
+    pub checkpoint_id: String,
+    pub session_id: String,
+    pub snapshot: SessionSnapshot,  // 完整 JSON 化状态
+}
+```
+
+**增量层（叠加 diff）**：
+```rust
+pub struct SnapshotLayer {
+    pub base_checkpoint_id: String,
+    pub applies_to_id: String,       // 在哪个 checkpoint 上叠加
+    pub diff: Vec<DiffOp>,           // JSON Patch 操作集合
+}
+
+pub enum DiffOp {
+    MessageAppended { message: Message },
+    SlotChanged { slot_id: String, diff: serde_json::Value },
+    TurnIndexIncremented { from: u32, to: u32 },
+    CostUpdated { diff: CostTracker },
+}
+```
+
+**重建路径**：
+```
+rollback_load("session_x", 6)
+  → 读取 "ckpt:{session_x}:base"（全量）
+  → 读取 "ckpt:{session_x}:layer:1" ~ "ckpt:{session_x}:layer:6"
+  → 依次应用 layer.1 → layer.2 → ... → layer.6
+  → 得到 session_6 的状态
+```
+
+**层折叠（类似 docker squash）**：
+```
+layer.1 → layer.2 → layer.3 → layer.4 → layer.5
+                    ↓ 合并
+base.ckpt'（包含 layer.1-3）→ layer.4 → layer.5
+```
+
+#### Shadow FS 模型（运行中保护）
+
+与分层模型互补，shadow 模型适用于运行中的 session 保护而非长期存储：
+
+```rust
+// submit_turn 在 shadow session 上执行，commit 时才原子切换
+let shadow = current_session.fork();  // 复用 ContextSlot::fork
+let result = shadow.submit_turn(input).await;
+if result.is_ok() {
+    current_session.commit(shadow);   // 原子替换
+} else {
+    drop(shadow);                     // 丢弃，当前 session 完好无损
+}
+```
+
+#### 适用场景对比
+
+| 模型 | 适合场景 | 不适合场景 |
+|------|---------|-----------|
+| **分层叠加（OverlayFS）** | Checkpoint 链长期存储、time-travel、多版本回退 | session 较小（< 10KB/轮）时复杂度不值得 |
+| **Shadow FS（CoW）** | 运行中 session 保护、防止 submit_turn 失败污染 | 不能替代 checkpoint 链、不支持多时间点回退 |
+
+**触发条件**：当单 session checkpoint 超过 500KB 且频繁保存导致性能瓶颈时，考虑实现分层模型。
@@ -0,0 +1,233 @@
+# AG Core Roadmap — v0.4.0
+
+> 本文件聚焦 **v0.4.0 版本** 的规划。Phase A-E 计划中，覆盖多 Agent 编排、Human-in-the-loop 与 Steering、语义压缩、自动校正。
+> 返回总入口：[`roadmap.md`](./roadmap.md)
+
+## v0.4.0 愿景
+
+从 v0.3 的"多 Agent 基础系统"升级为"多 Agent 多职责编排系统"。补齐高层编排抽象（Swarm/Supervisor/Subgraph）、生产级人工干预能力（HITL + Steering）、工具与消息的语义压缩（TokenJuice），以及自动质量校正（Reflection）。为即将开发的多 Agent 协作产品提供完整的编排、干预与质量保证层。
+
+## v0.4.0 总体范围
+
+**总体规模**：5 个增量 Phase（Phase A-E），总新增代码约 1,950 行，零强制新外部依赖，零破坏性变更。
+
+### 架构决策
+
+**路线选择**：采用轻量编排模式（路线 A），不引入通用有向图引擎。通过 `Swarm::star()` / `Swarm::sequential()` / `Swarm::hierarchical()` 等具名模式提供编排能力，底层复用现有 `dispatch` / `create_child` / `SessionManager` 基础设施。预留路线 B（StateGraph 抽象）作为未来版本的升级路径。
+
+**模块位置**：
+- 编排逻辑 → `src/engine/supervisor.rs`（新增）
+- 内建工具 → `src/tools/builtin.rs`（新增）
+- TokenJuice 压缩 → `src/llm/compress.rs`（新增）
+- Steering 机制 → `src/engine/steer.rs`（新增，或并入 supervisor.rs）
+
+### 功能清单
+
+#### P0 — 必须交付
+
+| # | 功能 | 模块 | 方案要点 |
+|---|------|------|---------|
+| 1 | Swarm 编排（Star/Sequential/Hierarchical + Subgraph） | `engine/supervisor` | `Swarm::star().supervisor(A).worker(B)` 声明式 API；`Swarm::sequential().link(A).link(B)` 串联；`Swarm::hierarchical().supervisor(root).group("sub", ...)` 层次嵌套 |
+| 2 | 结果聚合 | `engine/supervisor` | `aggregation_prompt` 模板将子 Agent 结果合并到 Supervisor 上下文；`DispatchConfig` 扩展 `result_key` 字段 |
+| 3 | Human-in-the-loop 审批 | `engine/steer` | `interrupt()` 暂停执行 + `Command(resume=bool)` 恢复；`HookEvent::OnInterrupt` 新变体 |
+| 4 | 用户 Steering（运行中校正） | `engine/steer` | `Command(resume=Correction{...})` 结构化校正；Steer 消息在工具批处理边界注入 |
+| 5 | TokenJuice 语义压缩 | `llm/compress` | `Compressor` trait 统一抽象；覆盖工具结果、对话历史、跨 Agent 消息三层；LLM 摘要压缩 + 确定性兜底 |
+
+#### P1 — 推荐交付
+
+| # | 功能 | 模块 | 方案要点 |
+|---|------|------|---------|
+| 6 | 自动校正 / Reflection | `engine/reflect` | Evaluator-Optimizer 循环；Producer-Critic 角色分离；上限 2-3 轮迭代 |
+
+### 实施计划 — 5 个增量 Phase
+
+> **编号说明**：Phase A-E 为 v0.4.0 专属编号，接续已完成的 Phase 30。
+
+---
+
+#### Phase A: Swarm 编排抽象（Star / Sequential / Hierarchical + Subgraph）
+
+**目标**：在现有 `dispatch` 原语基础上，提供声明式多 Agent 编排 API。Supervisor 作为 `Arc<dyn Agent>`，通过内建工具 `dispatch_sub_agent` 驱动子 Agent 执行。
+
+**交付物**：
+1. `src/engine/supervisor.rs` 新文件：
+   - `Swarm` 枚举/结构体：`Swarm::star()`（星型，一个 Supervisor + N 个 Worker）、`Swarm::sequential()`（顺序链 A→B→C）、`Swarm::hierarchical()`（层次嵌套，Supervisor 下的 Sub-Supervisor）
+   - 各模式的 `build()` 和 `run(input)` 方法
+   - 底层通过 `SessionManager::dispatch()` / `dispatch_all()` 实现
+2. `src/tools/builtin.rs` 新文件：
+   - `dispatch_sub_agent(name, task, config)` 内建工具 — 从 Agent 注册表查找 Agent 工厂 → `SessionManager::dispatch()`
+3. `AgentRegistry`：`HashMap<String, Box<dyn Fn() -> Arc<dyn Agent>>>` 轻量工厂注册表（约 50 行）
+4. Subgraph 嵌套：`Swarm::hierarchical()` 支持 `group(name, inner_swarm)`，内层 Swarm 作为子节点编译后嵌入
+
+**设计要点**：
+- Supervisor 就是 `Arc<dyn Agent>`，不新增 `SupervisorAgent` trait
+- 路由逻辑写在 Supervisor 的 system prompt 中（LLM 决定的动态路由）
+- 三种模式覆盖常见编排拓扑，不引入通用图引擎（路线 B 留作未来）
+- Subgraph 编译为独立的 `SessionManager` 子树（复用 `create_child` 的父子关系）
+
+**依赖**：Phase 18（SubAgent dispatch / SessionManager）
+**优先级**：P0
+**预估规模**：约 500 行
+**状态**：📋 待实施
+
+---
+
+#### Phase B: 结果聚合 + 编排模式完善
+
+**目标**：让 Supervisor 能智能地合并 Worker 结果。完善三种编排模式的容错性和易用性。
+
+**交付物**：
+1. `aggregation_prompt` 模板系统 — 内建 `DEFAULT_AGGREGATION_PROMPT`，用户可自定义聚合逻辑
+2. `DispatchConfig` 扩展：
+   - `result_key: Option<String>` — 将子结果存入 `session_memory` 的指定 key，供后续阶段使用
+   - `aggregate_strategy: AggregateStrategy` — `Concatenate` / `Summarize` / `Custom(Value)`
+3. 编排模式增强：
+   - `Swarm::sequential()` 支持失败时停止 / 跳过 / 重试策略
+   - `Swarm::star()` 支持 Worker 超时
+4. 端到端示例 3 个：
+   - `swarm_star_demo.rs` — 星型编排 + 并发派发 + 结果聚合
+   - `swarm_sequential_demo.rs` — 串联流水线
+   - `swarm_hierarchical_demo.rs` — 层次嵌套（Supervisor → Sub-Supervisor → Worker）
+
+**依赖**：Phase A
+**优先级**：P0
+**预估规模**：约 200 行
+**状态**：📋 待实施
+
+---
+
+#### Phase C: Human-in-the-loop + 用户 Steering
+
+**目标**：生产级多 Agent 系统的关键门禁。提供执行中暂停-审批-恢复机制，以及用户运行中校正方向的能力。
+
+**交付物**：
+1. `src/engine/steer.rs` 新文件：
+   - `interrupt(value)` 函数 — 在工具循环中插入暂停点，持久化当前状态后返回控制权
+   - `Command` 枚举：
+     - `Command::Resume(bool)` — 二元审批（批准/拒绝）
+     - `Command::ResumeWith(Correction)` — 结构化校正（修改工具参数 / 调整方向）
+2. `LlmCycle` 扩展：可中断工具循环模式
+   - `submit_with_tools_interruptible()` — 支持在工具批处理边界检查中断信号
+   - 中断时保存当前 `LlmCycle` 状态到 checkpoint
+3. `HookEvent::OnInterrupt` / `OnSteer` 新变体 — 监听中断和校正事件
+4. `SessionManager::resume_turn(session_id, resume_data)` — 从 checkpoint 恢复并注入审批结果
+5. `tools/builtin.rs` 扩展：
+   - `request_approval(question, context)` — 请求用户审批
+   - `emit_steer(correction)` — 用户校正
+6. Steering 生命周期：
+   - `interrupt` → 用户收到提示 → 用户决定方向 → `Command::ResumeWith(correction)` → Agent 在新方向上继续
+
+**设计要点**：
+- User Steering 不是简单的"批准/拒绝"，而是 `Correction { action, reason, amended_params }` 结构化指令
+- Steering 消息在工具批处理边界（Worker 返回后、Supervisor 决策前）注入，不中断正在执行的工具
+- 继承 `ContextSlot::fork/merge` 模式，steer 前 fork 快照，允许用户回退到 steer 前状态
+
+**依赖**：Phase A（Swarm 编排）
+**优先级**：P0
+**预估规模**：约 500 行
+**状态**：📋 待实施
+
+---
+
+#### Phase D: TokenJuice 语义压缩
+
+**目标**：替代当前字节级截断（`microcompact` 的 `[pruned]`），提供语义级别的压缩。在三层管道中接入：工具结果压缩、对话历史压缩、跨 Agent 消息压缩。
+
+**交付物**：
+1. `src/llm/compress.rs` 新文件：
+   - `Compressor` trait（`async fn compress(&self, input: &str, ctx: &CompressionContext) -> Result<String>`）
+   - `CompressionContext`：`target_tokens` / `preserve_keys` / `strategy`
+   - `CompressionStrategy` 枚举：`Semantic { model }`（LLM 摘要）、`Extractive { ratio }`（抽取式）、`Hybrid { semantic_first }`（混合）
+   - `SemanticCompressor` 实现（复用已有 provider 做 LLM 摘要压缩）
+   - `ExtractiveCompressor` 实现（确定性关键句提取，零 LLM 调用）
+2. 三层接入点：
+   - **工具结果压缩**：在 `run_tool_loop` 中，`tool.execute()` 后插入 `compress_result()`，压缩结果再 `push ToolResult`
+   - **对话历史压缩**：在 `load_messages()` 后插入 `compress_history()`，替代/补充 `microcompact`
+   - **跨 Agent 消息压缩**：在 `inherit_session_memory` 的子 memory 写入前压缩（减少子 Agent 的 context 水位）
+3. `CycleConfig` / `CompactConfig` 扩展：
+   - `token_compression: Option<CompressionConfig>` — 可选语义压缩配置
+   - `fallback_to_microcompact: bool`（默认 `true`）— LLM 压缩失败时退化为字节截断
+4. TokenJuice 与现有 `microcompact` 的关系：
+   - `microcompact` 保留为最轻量级兜底（零 LLM 调用）
+   - TokenJuice 是可选增强层（默认关闭，用户 opt-in）
+
+**设计要点**：
+- 零新外部依赖：LLM 摘要压缩复用已有 provider，抽取式压缩纯 Rust 实现
+- 与现有 `CompactState` 断路器模式兼容（LLM 压缩失败 3 次后自动降级到 `microcompact`）
+- `preserve_keys` 确保关键数据（数字、ID、SQL、代码片段）不被压缩掉
+
+**依赖**：Phase 14（Embedding trait 可选参考）
+**优先级**：P0
+**预估规模**：约 400 行
+**状态**：📋 待实施
+
+---
+
+#### Phase E: 自动校正 / Reflection
+
+**目标**：实现 Agent 输出后的自我质量评估与自动修正循环。基于 `interrupt/resume` 基础设施，构建 Producer-Critic 闭环。
+
+**交付物**：
+1. `src/engine/reflect.rs` 新文件：
+   - `ReflectionConfig`：`max_cycles`（默认 2）/ `critic_agent`（可选不同模型）/ `criteria: Vec<String>`（评估标准）
+   - `Reflectable` trait：`fn reflection_criteria(&self) -> Vec<String>` + `fn needs_refinement(&self, critique: &Critique) -> bool`
+   - `ReflectionLoop`：`evaluate(output) → Critique` → `should_refine? → yes: refine(output, critique) → 循环 / no: 返回`
+2. Swarm 内建 Reflection 模式：
+   - `Swarm::reflect(producer_agent, critic_agent)` — 专用 Reflection Swarm
+   - 可在 Supervisor 流程中嵌入 `reflect_on(worker_result)` — 对 Worker 结果自动过一遍质量检查
+3. `Critique` 结构体：`issues: Vec<Issue>` / `score: f32` / `should_refine: bool` / `suggestions: Vec<String>`
+4. `tools/builtin.rs` 扩展：`verify_output(claim, evidence)` 工具 — 让 Agent 自行验证输出真实性
+
+**设计要点**：
+- Producer 和 Critic 使用**不同模型**（避免同一模型的自我审查盲区 bias）
+- 上限 2-3 轮（第一轮修正捕获 70–80% 改善空间，第 4+ 轮收益递减）
+- 基于已有 `HookEvent::OnTurnEnd` 或扩展 `HookEvent::OnOutputGenerated` 触发反思
+- 失败静默：Reflection 失败不阻断主流程（`tracing::warn!` 后继续交付原始输出）
+
+**依赖**：Phase C（interrupt/resume 基础设施）
+**优先级**：P0
+**预估规模**：约 350 行
+**状态**：📋 待实施
+
+---
+
+### v0.4.0 Phase 依赖关系图
+
+```mermaid
+graph BT
+    PA["<b>Phase A: Swarm 编排</b><br/>Swarm::star/sequential/hierarchical<br/>Subgraph 嵌套<br/>内建 dispatch_sub_agent 工具<br/>~500 行"]:::pending
+    PB["<b>Phase B: 结果聚合</b><br/>aggregation_prompt 模板<br/>DispatchConfig result_key<br/>编排模式完善<br/>3 个端到端示例<br/>~200 行"]:::pending
+    PC["<b>Phase C: HITL + Steering</b><br/>interrupt/resume<br/>Command(ResumeWith Correction)<br/>HookEvent::OnInterrupt<br/>~500 行"]:::pending
+    PD["<b>Phase D: TokenJuice</b><br/>Compressor trait<br/>工具结果/历史/跨 Agent 压缩<br/>Semantic + Extractive 策略<br/>~400 行"]:::pending
+    PE["<b>Phase E: 自动校正</b><br/>ReflectionLoop<br/>Producer-Critic<br/>上限 2-3 轮<br/>~350 行"]:::pending
+
+    PB --> PA
+    PC --> PA
+    PE --> PC
+
+    classDef done fill:#4ade80,stroke:#16a34a,color:#1a1a1a
+    classDef pending fill:#fbbf24,stroke:#d97706,color:#1a1a1a
+    classDef future fill:#94a3b8,stroke:#64748b,color:#1a1a1a
+```
+
+### 关键里程碑
+
+| 里程碑 | Phase 完成条件 | 可验证指标 | 状态 |
+|--------|---------------|-----------|------|
+| **M16** | Phase A | `Swarm::star().supervisor(A).worker(B).run(input)` 端到端验证；`dispatch_sub_agent` 内建工具注册并可用；2 个示例 exit 0 | 📋 待启动 |
+| **M17** | Phase B | `Swarm::sequential()` 串联执行验证；`Swarm::hierarchical()` 层次嵌套验证；结果聚合正确合并；3 个新示例 exit 0 | 📋 待启动 |
+| **M18** | Phase C | `interrupt()` 暂停 + `Command::Resume(bool)` 恢复全链路验证；`Command::ResumeWith(Correction)` 结构化校正验证；HookEvent 触发验证 | 📋 待启动 |
+| **M19** | Phase D | 工具结果经语义压缩后保留关键信息（验证压缩比 ≥ 3:1）；`microcompact` 降级路径验证；对话历史压缩验证 | 📋 待启动 |
+| **M20** | Phase E | ReflectionLoop 正确性验证：已知缺陷的输出被修复、无缺陷的输出不被修改（不变性保证）；2 轮迭代上限验证；Critic 不同模型配置验证 | 📋 待启动 |
+
+### 不做（v0.5+）
+
+| 功能 | 原因 |
+|------|------|
+| Agent 自动创生（LLM 驱动动态分派） | 设计复杂且不确定性高，v0.4 专注显式声明式编排 |
+| 分布式 Session 共享（Redis 后端） | 与编排正交，大多数用户单进程即可 |
+| 精确 tokenizer 计数（tiktoken-rs） | 依赖引入，v0.4 专注编排与压缩能力本身 |
+| 增量 Checkpoint | 存储优化，当前全量 JSON 够用 |
+| 路线 B（StateGraph 通用图引擎） | 当前编排需求在路线 A 范围内，图引擎留给未来版本 |
+| RL 轨迹导出 | 专项需求，非通用 |
+| Markdown 技能按需加载 | 独立功能 |
@@ -1,7 +1,7 @@
 # AG Core Roadmap

 > 拆分式 roadmap：按版本归档 + 未归类内容
-> 最后更新：2026-07-20（Phase 28-30 OpenAI Response API Provider 交付 — 新增独立 feature `provider-openai-response`，450 测试通过）
+> 最后更新：2026-07-21（v0.4.0 规划完成 — Phase A-E 多 Agent 编排路线图制定）

 ## 文件索引

@@ -12,11 +12,12 @@
 | [`roadmap-v0.3.0.md`](./roadmap-v0.3.0.md) | v0.3.0 计划与交付 - Phase 13–19 | ✅ Phase 13-19 全部完成，v0.3.0 交付完毕 |
 | [`roadmap-v0.3.2.md`](./roadmap-v0.3.2.md) | v0.3.2 计划与交付 — Phase 20–27（Cargo features 拆分） | ✅ Phase 20-27 全部完成，v0.3.2 交付完毕 |
 | [`28-phase28-openai-response-api-provider.md`](./28-phase28-openai-response-api-provider.md) | Phase 28-30 OpenAI Response API Provider 实施方案（独立 feature `provider-openai-response`） | ✅ Phase 28-30 已交付 |
+| [`roadmap-v0.4.0.md`](./roadmap-v0.4.0.md) | v0.4.0 计划 — Phase A-E（Swarm 编排、HITL + Steering、TokenJuice 语义压缩、自动校正） | 📋 计划中 |
 | [`roadmap-unsorted.md`](./roadmap-unsorted.md) | 未归到任何版本的内容 — 全局愿景、当前状态、模块完整性、v0.4+ 展望、风险与建议、下一步行动、阶段总回顾 | — |

 ## 阅读建议

- **按版本顺序追溯历史**：v0.1.0 → v0.2.0 → v0.3.0
+- **按版本顺序追溯历史**：v0.1.0 → v0.2.0 → v0.3.0 → v0.4.0
 - **了解产品演进全貌**：从 `roadmap-unsorted.md` 顶部开始读
 - **查找特定 Phase**：每个版本文件内按 Phase 编号顺序排列
 - **了解项目当前关注点**：从 `roadmap-unsorted.md` 的「下一步行动」开始
@@ -242,6 +242,7 @@ pub(crate) struct OpenaiChatResponse {
    pub created: u64,
    pub model: String,
    pub choices: Vec<Choice>,
+    #[serde(default)]
    pub usage: crate::llm::types::usage::Usage,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub system_fingerprint: Option<String>,
@@ -1968,4 +1969,49 @@ data: [DONE]\n\n";
            "非法 header 名应被静默跳过"
        );
    }
+
+    // ===== OpenaiChatResponse Usage 容错（v0.3.6 引入）=====
+
+    /// C1: Chat Completions 响应中 usage 键完全缺失 —— 默认 Usage::default()。
+    #[test]
+    fn deserialize_chat_response_missing_usage_key() {
+        let body: OpenaiChatResponse = serde_json::from_value(json!({
+            "id": "chatcmpl-test",
+            "object": "chat.completion",
+            "created": 1718000000,
+            "model": "gpt-4o",
+            "choices": [{
+                "index": 0,
+                "message": {"role": "assistant", "content": "hi"},
+                "finish_reason": "stop"
+            }]
+        }))
+        .unwrap();
+        assert_eq!(body.usage.prompt_tokens, 0);
+        assert_eq!(body.usage.completion_tokens, 0);
+        assert_eq!(body.usage.total_tokens, 0);
+        assert!(body.usage.completion_tokens_details.is_none());
+        assert!(body.usage.prompt_tokens_details.is_none());
+    }
+
+    /// C2: Chat Completions 响应中 usage 存在但缺子字段 —— 缺省字段默认 0。
+    #[test]
+    fn deserialize_chat_response_missing_usage_fields() {
+        let body: OpenaiChatResponse = serde_json::from_value(json!({
+            "id": "chatcmpl-test",
+            "object": "chat.completion",
+            "created": 1718000000,
+            "model": "gpt-4o",
+            "choices": [{
+                "index": 0,
+                "message": {"role": "assistant", "content": "hi"},
+                "finish_reason": "stop"
+            }],
+            "usage": {"prompt_tokens": 8}
+        }))
+        .unwrap();
+        assert_eq!(body.usage.prompt_tokens, 8);
+        assert_eq!(body.usage.completion_tokens, 0);
+        assert_eq!(body.usage.total_tokens, 0);
+    }
 }
@@ -204,6 +204,7 @@ pub(crate) struct OpenaiResponseBody {
    pub id: String,
    pub model: String,
    pub output: Vec<ResponseOutputItem>,
+    #[serde(default)]
    pub usage: Usage,
    pub status: String,
 }
@@ -2509,4 +2510,92 @@ data: {\"type\":\"response.failed\",\"error\":{\"message\":\"server failed mid-s
        let wire = serde_json::to_value(&tool).unwrap();
        assert_eq!(wire, original);
    }
+
+    // ===== Usage 字段容错（v0.3.6 引入）=====
+
+    /// U1: usage 子字段缺失 —— 缺失字段默认 0/None，结构体反序列化不报错。
+    #[test]
+    fn deserialize_missing_usage_fields() {
+        let body: OpenaiResponseBody = serde_json::from_value(json!({
+            "id": "r_1",
+            "model": "gpt-4o",
+            "output": [],
+            "usage": {"prompt_tokens": 5},
+            "status": "completed"
+        }))
+        .unwrap();
+        assert_eq!(body.usage.prompt_tokens, 5);
+        assert_eq!(body.usage.completion_tokens, 0);
+        assert_eq!(body.usage.total_tokens, 0);
+        assert!(body.usage.completion_tokens_details.is_none());
+        assert!(body.usage.prompt_tokens_details.is_none());
+    }
+
+    /// U2: usage 键完全缺失 —— OpenaiResponseBody.usage 默认 Usage::default()。
+    #[test]
+    fn deserialize_missing_usage_key() {
+        let body: OpenaiResponseBody = serde_json::from_value(json!({
+            "id": "r_1",
+            "model": "gpt-4o",
+            "output": [],
+            "status": "completed"
+        }))
+        .unwrap();
+        assert_eq!(body.usage.prompt_tokens, 0);
+        assert_eq!(body.usage.completion_tokens, 0);
+        assert_eq!(body.usage.total_tokens, 0);
+        assert!(body.usage.completion_tokens_details.is_none());
+        assert!(body.usage.prompt_tokens_details.is_none());
+    }
+
+    /// U3: usage 为空对象 —— 全字段走 Default，无 None panic。
+    #[test]
+    fn deserialize_empty_usage_object() {
+        let body: OpenaiResponseBody = serde_json::from_value(json!({
+            "id": "r_1",
+            "model": "gpt-4o",
+            "output": [],
+            "usage": {},
+            "status": "completed"
+        }))
+        .unwrap();
+        assert_eq!(body.usage.prompt_tokens, 0);
+        assert_eq!(body.usage.completion_tokens, 0);
+        assert_eq!(body.usage.total_tokens, 0);
+    }
+
+    /// U4: 完整 usage（含 details）回归 —— 确保 #[serde(default)] 不破坏正常路径。
+    #[test]
+    fn deserialize_full_usage_with_details() {
+        let body: OpenaiResponseBody = serde_json::from_value(json!({
+            "id": "r_1",
+            "model": "gpt-4o",
+            "output": [],
+            "usage": {
+                "prompt_tokens": 10,
+                "completion_tokens": 20,
+                "total_tokens": 30,
+                "completion_tokens_details": {"reasoning_tokens": 5}
+            },
+            "status": "completed"
+        }))
+        .unwrap();
+        assert_eq!(body.usage.prompt_tokens, 10);
+        assert_eq!(body.usage.completion_tokens, 20);
+        assert_eq!(body.usage.total_tokens, 30);
+        let details = body.usage.completion_tokens_details.unwrap();
+        assert_eq!(details.reasoning_tokens, Some(5));
+    }
+
+    /// U5: OpenaiResponseBody 上下文中 usage key 完全缺失 —— 与 U2 同场景但明确命名。
+    #[test]
+    fn deserialize_response_body_missing_usage_key() {
+        let json_text = r#"{"id":"r_1","model":"gpt-4o","output":[],"status":"completed"}"#;
+        let body: OpenaiResponseBody = serde_json::from_str(json_text).unwrap();
+        assert_eq!(body.usage.prompt_tokens, 0);
+        assert_eq!(body.usage.completion_tokens, 0);
+        assert_eq!(body.usage.total_tokens, 0);
+        assert!(body.usage.completion_tokens_details.is_none());
+        assert!(body.usage.prompt_tokens_details.is_none());
+    }
 }
@@ -1,6 +1,7 @@
 use serde::{Deserialize, Serialize};

 #[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
+#[serde(default)]
 pub struct Usage {
    pub prompt_tokens: u32,
    pub completion_tokens: u32,
@@ -79,3 +80,33 @@ impl Usage {
        }
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn deserialize_usage_missing_prompt_tokens() {
+        let value = json!({
+            "completion_tokens": 5,
+            "total_tokens": 5
+        });
+        let usage: Usage = serde_json::from_value(value).unwrap();
+        assert_eq!(usage.prompt_tokens, 0);
+        assert_eq!(usage.completion_tokens, 5);
+        assert_eq!(usage.total_tokens, 5);
+    }
+
+    #[test]
+    fn serialize_deserialize_roundtrip() {
+        let original = Usage::from_input_output(10, 20);
+        let serialized = serde_json::to_value(original).unwrap();
+        let deserialized: Usage = serde_json::from_value(serialized).unwrap();
+        assert_eq!(deserialized.prompt_tokens, original.prompt_tokens);
+        assert_eq!(deserialized.completion_tokens, original.completion_tokens);
+        assert_eq!(deserialized.total_tokens, original.total_tokens);
+        assert!(deserialized.completion_tokens_details.is_none());
+        assert!(deserialized.prompt_tokens_details.is_none());
+    }
+}
@@ -220,7 +220,7 @@ fn compile_fragments(template: &str) -> Result<Vec<Fragment>, PromptError> {
                fragments.push(Fragment::Literal(literal.clone()));
                literal.clear();
            }
-            let (tag_content, end) = parse_tag(bytes, i)?;
+            let (tag_content, end) = parse_tag(template, i)?;
            i = end;

            let tag = tag_content.trim();
@@ -252,8 +252,16 @@ fn compile_fragments(template: &str) -> Result<Vec<Fragment>, PromptError> {
                fragments.push(Fragment::Variable { name });
            }
        } else {
-            literal.push(bytes[i] as char);
-            i += 1;
+            debug_assert!(template.is_char_boundary(i));
+            match template[i..].chars().next() {
+                Some(ch) => {
+                    literal.push(ch);
+                    i += ch.len_utf8();
+                }
+                None => {
+                    return Err(PromptError::Parse("模板包含非法字符序列".to_string()));
+                }
+            }
        }
    }

@@ -264,7 +272,8 @@ fn compile_fragments(template: &str) -> Result<Vec<Fragment>, PromptError> {
    Ok(fragments)
 }

-fn parse_tag(bytes: &[u8], start: usize) -> Result<(String, usize), PromptError> {
+fn parse_tag(template: &str, start: usize) -> Result<(String, usize), PromptError> {
+    let bytes = template.as_bytes();
    let len = bytes.len();
    let mut i = start + 2;
    let mut content = String::new();
@@ -272,8 +281,16 @@ fn parse_tag(bytes: &[u8], start: usize) -> Result<(String, usize), PromptError>
        if bytes[i] == b'}' && i + 1 < len && bytes[i + 1] == b'}' {
            return Ok((content, i + 2));
        }
-        content.push(bytes[i] as char);
-        i += 1;
+        debug_assert!(template.is_char_boundary(i));
+        match template[i..].chars().next() {
+            Some(ch) => {
+                content.push(ch);
+                i += ch.len_utf8();
+            }
+            None => {
+                return Err(PromptError::Parse("模板包含非法字符序列".to_string()));
+            }
+        }
    }
    Err(PromptError::Parse("未闭合的 {{ 标签".to_string()))
 }
@@ -293,7 +310,7 @@ fn parse_block(

    while i < len && depth > 0 {
        if bytes[i] == b'{' && i + 1 < len && bytes[i + 1] == b'{' {
-            let (tag, end) = parse_tag(bytes, i)?;
+            let (tag, end) = parse_tag(template, i)?;
            let tag = tag.trim().to_string();
            if tag == format!("/{kind}") {
                depth -= 1;
@@ -320,12 +337,20 @@ fn parse_block(
                i = end;
            }
        } else {
-            if is_else {
-                else_body.push(bytes[i] as char);
-            } else {
-                body.push(bytes[i] as char);
+            debug_assert!(template.is_char_boundary(i));
+            match template[i..].chars().next() {
+                Some(ch) => {
+                    if is_else {
+                        else_body.push(ch);
+                    } else {
+                        body.push(ch);
+                    }
+                    i += ch.len_utf8();
+                }
+                None => {
+                    return Err(PromptError::Parse("模板包含非法字符序列".to_string()));
+                }
            }
-            i += 1;
        }
    }

@@ -341,7 +366,7 @@ fn parse_each_block(template: &str, start: usize) -> Result<(Vec<Fragment>, usiz

    while i < len && depth > 0 {
        if bytes[i] == b'{' && i + 1 < len && bytes[i + 1] == b'{' {
-            let (tag, end) = parse_tag(bytes, i)?;
+            let (tag, end) = parse_tag(template, i)?;
            let tag = tag.trim().to_string();
            if tag == "/each" {
                depth -= 1;
@@ -361,8 +386,16 @@ fn parse_each_block(template: &str, start: usize) -> Result<(Vec<Fragment>, usiz
                i = end;
            }
        } else {
-            body.push(bytes[i] as char);
-            i += 1;
+            debug_assert!(template.is_char_boundary(i));
+            match template[i..].chars().next() {
+                Some(ch) => {
+                    body.push(ch);
+                    i += ch.len_utf8();
+                }
+                None => {
+                    return Err(PromptError::Parse("模板包含非法字符序列".to_string()));
+                }
+            }
        }
    }

@@ -377,7 +410,7 @@ fn parse_raw_block(template: &str, start: usize) -> Result<(String, usize), Prom

    while i < len {
        if bytes[i] == b'{' && i + 1 < len && bytes[i + 1] == b'{' {
-            let (tag, end) = parse_tag(bytes, i)?;
+            let (tag, end) = parse_tag(template, i)?;
            let tag = tag.trim().to_string();
            if tag == "/raw" {
                return Ok((content, end));
@@ -386,8 +419,16 @@ fn parse_raw_block(template: &str, start: usize) -> Result<(String, usize), Prom
                i = end;
            }
        } else {
-            content.push(bytes[i] as char);
-            i += 1;
+            debug_assert!(template.is_char_boundary(i));
+            match template[i..].chars().next() {
+                Some(ch) => {
+                    content.push(ch);
+                    i += ch.len_utf8();
+                }
+                None => {
+                    return Err(PromptError::Parse("模板包含非法字符序列".to_string()));
+                }
+            }
        }
    }

@@ -528,3 +569,170 @@ impl PromptTemplateRegistry {
        tpl.render(ctx)
    }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn preserves_chinese_literal() -> Result<(), PromptError> {
+        let source = "这是一个纯中文模板。";
+        let template = PromptTemplate::compile(source)?;
+
+        assert_eq!(template.render(&TemplateContext::new())?, source);
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_real_world_failure_text() -> Result<(), PromptError> {
+        let source = "你是采集策略专家，负责审查已采集的产品编码结果，决策下一轮搜索方向。★ 下一步→「严格校验」，使用全角标点：，；！";
+        let template = PromptTemplate::compile(source)?;
+
+        assert_eq!(template.render(&TemplateContext::new())?, source);
+        Ok(())
+    }
+
+    #[test]
+    fn renders_chinese_with_variable() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("你好，{{ name }}！")?;
+        let mut ctx = TemplateContext::new();
+        ctx.insert("name", "小明");
+
+        assert_eq!(template.render(&ctx)?, "你好，小明！");
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_chinese_in_if_body() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("{{#if enabled}}已启用{{/if}}")?;
+        let mut ctx = TemplateContext::new();
+        ctx.insert("enabled", true);
+
+        assert_eq!(template.render(&ctx)?, "已启用");
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_chinese_in_else_body() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("{{#if enabled}}已启用{{else}}未启用{{/if}}")?;
+        let mut ctx = TemplateContext::new();
+        ctx.insert("enabled", false);
+
+        assert_eq!(template.render(&ctx)?, "未启用");
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_chinese_in_each_body() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("{{#each items}}项目：{{item}}；{{/each}}")?;
+        let ctx = TemplateContext::from_json(&json!({"items": ["甲", "乙"]}))?;
+
+        assert_eq!(template.render(&ctx)?, "项目：甲；项目：乙；");
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_chinese_in_raw_body() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("{{#raw}}原始中文：{{name}}{{/raw}}")?;
+
+        assert_eq!(
+            template.render(&TemplateContext::new())?,
+            "原始中文：{{name}}"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_four_byte_characters() -> Result<(), PromptError> {
+        let source = "你好👋🌍";
+        let template = PromptTemplate::compile(source)?;
+
+        assert_eq!(template.render(&TemplateContext::new())?, source);
+        Ok(())
+    }
+
+    #[test]
+    fn parses_multibyte_characters_next_to_tag_boundaries() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("前{{name}}后")?;
+        let mut ctx = TemplateContext::new();
+        ctx.insert("name", "中");
+
+        assert_eq!(template.render(&ctx)?, "前中后");
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_chinese_at_end_of_template() -> Result<(), PromptError> {
+        let source = "template ends with 中文";
+        let template = PromptTemplate::compile(source)?;
+
+        assert_eq!(template.render(&TemplateContext::new())?, source);
+        Ok(())
+    }
+
+    #[test]
+    fn renders_empty_template() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("")?;
+
+        assert_eq!(template.render(&TemplateContext::new())?, "");
+        Ok(())
+    }
+
+    #[test]
+    fn rejects_unclosed_tag_after_chinese_without_panicking() {
+        assert!(matches!(
+            PromptTemplate::compile("中文{{未闭合"),
+            Err(PromptError::Parse(_))
+        ));
+    }
+
+    #[test]
+    fn preserves_ascii_template_behavior() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile(
+            "Hello {{name}}! {{#if active}}Active{{else}}Inactive{{/if}} {{#each items}}[{{item}}]{{/each}} {{#raw}}{{raw}}{{/raw}}",
+        )?;
+        let ctx = TemplateContext::from_json(&json!({
+            "name": "Alice",
+            "active": true,
+            "items": ["a", "b"]
+        }))?;
+
+        assert_eq!(template.render(&ctx)?, "Hello Alice! Active [a][b] {{raw}}");
+        Ok(())
+    }
+
+    #[test]
+    fn renders_chinese_variable_name() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("{{ 问候 }}，世界！")?;
+        let mut ctx = TemplateContext::new();
+        ctx.insert("问候", "你好");
+
+        assert_eq!(template.render(&ctx)?, "你好，世界！");
+        Ok(())
+    }
+
+    #[test]
+    fn renders_chinese_if_condition() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile("{{#if 已启用}}条件成立{{/if}}")?;
+        let mut ctx = TemplateContext::new();
+        ctx.insert("已启用", true);
+
+        assert_eq!(template.render(&ctx)?, "条件成立");
+        Ok(())
+    }
+
+    #[test]
+    fn preserves_chinese_in_nested_if_and_each_blocks() -> Result<(), PromptError> {
+        let template = PromptTemplate::compile(
+            "{{#if 已启用}}列表：{{#each 项目}}【{{item}}】{{/each}}{{/if}}",
+        )?;
+        let ctx = TemplateContext::from_json(&json!({
+            "已启用": true,
+            "项目": ["甲", "乙"]
+        }))?;
+
+        assert_eq!(template.render(&ctx)?, "列表：【甲】【乙】");
+        Ok(())
+    }
+}
Author	SHA1	Message	Date
徐涛	eb7d23de3d	docs: 添加模板编译器 UTF-8 编码修复方案与需求文档 - 新增 PDD 方案（编号 32），覆盖 6 处逐字节强转修复、测试设计与版本升级计划 - 新增 PRD 需求（编号 2），定位模板编译阶段中文乱码根因并明确验收标准 - 添加 .codegraph 目录忽略规则，避免本地数据文件入库	2026-08-03 11:21:50 +08:00
徐涛	7a215272a9	fix(prompt): 修复模板编译器 UTF-8 编码乱码 - 按字符边界推进模板解析索引 - 补充中文、emoji、块语法与 ASCII 回归测试 - 将版本升级至 0.3.7	2026-08-03 11:16:16 +08:00
徐涛	25238fc357	fix(llm): 为 Usage 字段添加反序列化容错，修复缺失子字段导致的响应解析失败 - Usage 结构体加 struct-level #[serde(default)]：子字段缺失默认 0/None - OpenaiResponseBody.usage 与 OpenaiChatResponse.usage 加 field-level：整 key 缺失默认 Usage::default() - 覆盖 Responses API 与 Chat Completions 两条 blocking 路径 - 补 9 个反序列化测试覆盖缺失/空/完整/roundtrip 边界 - 升级版本号至 0.3.6	2026-07-27 09:46:52 +08:00
徐涛	b7d0a7335f	docs: 添加 Usage 字段反序列化容错方案文档为 Usage 结构体及其内嵌字段添加 `#[serde(default)]` 反序列化容错，使 blocking 调用在火山平台返回不完整 usage 时不再崩溃。 - 新增 PDD：分析问题根因、设计变更方案、验证标准与回滚方案 - 新增 PRD：梳理需求范围、边界假设与验收标准	2026-07-27 09:34:11 +08:00
徐涛	c5afa4b31e	docs(agents): 同步文档规范与 design 目录说明至全局版本 - 替换方案规范为 design/pdd/ + design/prd/ 编号体系 - 移除 docs/roadmap.md 进度同步规则（全局未要求） - 新增 design/ 子目录职责、读写权限与兜底规则	2026-07-23 05:54:58 +08:00
徐涛	28ca43ccb2	chore(docs): 将设计文档从 docs 移至 design 目录将 note、pdd、prd、roadmap 四类文档分别归入 `design/` 下对应子目录中，并新增 `.gitkeep` 占位文件	2026-07-23 05:45:53 +08:00
徐涛	528a17f5fa	docs(roadmap): 更新 v0.4.0 规划状态，归档已完成 Phase	2026-07-21 22:44:01 +08:00
徐涛	d48286a942	docs(v0.4.0): 新增 v0.4.0 版本路线图规划文档涵盖多 Agent 编排、Human-in-the-loop、语义压缩与自动校正等 Phase A-E 共 5 个增量的实施计划、依赖关系与里程碑定义	2026-07-21 22:43:55 +08:00