agcore/design/prd/2-模板编译器UTF-8编码修复需求.md

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 暂不记录