# Phase 1: Prompt Engineering — 方案设计

> 定稿日期：2026-06-02

## 背景与目标

AG Core Phase 0（Foundation）已完成 LLM 调用周期的全部基础设施。Phase 1 的目标是补齐**提示词工程**能力，提供提示词的组合、模板化与优化能力，使其能直接服务于 Phase 2（工具系统）和 Phase 4（Agent 运行时）。

**目标**：实现 `PromptTemplate`（模板引擎）和 `PromptComposer`（提示词组合器）两个核心组件，覆盖变量插值、条件渲染、多消息序列拼接等场景。

---

## 需求分析

### 功能需求

| 模块 | 需求 | 验收条件 |
|------|------|---------|
| `PromptTemplate` | 支持变量插值 `{{ var }}` | 渲染后正确替换所有变量 |
| `PromptTemplate` | 支持条件渲染 `{{#if var}}...{{/if}}` | 变量非空/非 false 时渲染块 |
| `PromptTemplate` | 支持列表循环 `{{#each list}}...{{/each}}` | 遍历渲染集合元素 |
| `PromptTemplate` | 支持嵌套模板引用 `{{> template_name }}` | 引用已注册的模板片段 |
| `PromptTemplate` | 支持部分转义（原样输出 `{{ literal }}`） | 提供 raw block 语法 |
| `PromptComposer` | 按角色拼接 system/user/assistant 消息序列 | 输出 `Vec<OpenaiChatMessage>` |
| `PromptComposer` | 支持插入预编译的 PromptTemplate | 组合器中混合使用静态文本和模板 |
| `PromptComposer` | 支持从已有消息列表扩展 | 接收 `Vec<OpenaiChatMessage>` 作为初始状态 |
| `PromptComposer` | 支持多模态 ContentPart 构建（图片/音频/文件） | `user_content()`/`system_content()` 等接受 `OpenaiContentPart` |
| `PromptComposer` | 支持 Developer 角色（o1 系列模型） | `developer()` / `developer_template()` / `developer_content()` |
| `PromptComposer` | 支持 Tool 角色（工具执行结果回传） | `tool()` / `tool_content()` 接受 `tool_call_id` |
| `PromptComposer` | 支持 `name` 字段设置（多角色区分） | `with_name()` 链式方法为上一消息设置名称 |
| `PromptComposer` | 支持消息序列合法性验证 | `validate_messages()` 检查顺序约束与角色交替 |
| `PromptTemplateRegistry` | 模板注册表：按名称注册、查找、文件加载 | 从字符串/文件注册模板，按名称渲染 |
| `PromptTemplateRegistry` | 支持延迟编译模式 | `register_lazy()` 存储原始字符串，首次渲染时编译 |
| `PromptTemplate` | 实现 `Display` trait | 输出原始模板字符串（用于日志和调试） |
| `TemplateContext` | 支持从 JSON 构造 | `from_json()` 递归转换 `serde_json::Value` 为 `TemplateValue` |

### 非功能需求

- 所有公开 API 必须带 `///` 文档注释
- 无新增 `unwrap()` 调用
- **零运行时依赖**（不使用 tera、askama 等模板引擎 crate）
- 模板引擎失败时返回结构化错误（`PromptError`）
- 与现有 `OpenaiChatMessage` / `ChatRequest` 类型自然集成

---

## 方案设计

### 模块结构

```
src/
  prompt.rs                # prompt 模块根：声明子模块 + 重导出公共 API
  prompt/
    template.rs            # PromptTemplate — 模板引擎
    template/
      registry.rs          # PromptTemplateRegistry — 模板注册表
    composer.rs            # PromptComposer — 提示词组合器
    error.rs               # PromptError — 错误类型
```

`prompt.rs` 根模块声明:

```rust
// prompt.rs
pub mod composer;
pub mod error;
pub mod template;

pub use composer::PromptComposer;
pub use error::PromptError;
pub use template::{PromptTemplate, PromptTemplateRegistry};
```

`lib.rs` 添加：

```diff
 pub mod llm;
+pub mod prompt;
```

### 1. 模板引擎选择：自建轻量

**决策**：不使用 `tera` / `askama` / `maud` / `minijinja` 等第三方模板 crate。

**理由**：
- Phase 1 模板需求极其简单（变量插值 + 条件 + 列表循环），不需要 Jinja2/Handlebars 全能力
- 无依赖 = 编译更快、无安全面、版本冲突为 0
- 自建 50-80 行核心逻辑即可覆盖所有需求
- Roadmap 估算 400 行总代码，60 行模板引擎足够

**语法设计**（参考 Handlebars 子集）：

```
{{ variable_name }}           → 变量插值
{{#if var}}...{{/if}}         → 条件渲染（var 存在且非空）
{{#if var}}...{{else}}...{{/if}} → 条件 + 否则
{{#each list}} {{item}} {{/each}} → 列表循环
{{#raw}} {{literal}} {{/raw}}  → 原始块（不解析内部模板语法）
{{> template_name}}           → 引用已注册的嵌套模板
```

### 2. PromptTemplate — 模板引擎

```rust
// prompt/template.rs

use std::collections::HashMap;
use crate::prompt::error::PromptError;

/// 渲染上下文中使用的值类型。
pub enum TemplateValue {
    String(String),
    Bool(bool),
    Array(Vec<TemplateValue>),
    Object(HashMap<String, TemplateValue>),
}

/// `TemplateValue` 自动转换（提升 `ctx.insert("name", "Alice")` 的易用性）。
impl From<String> for TemplateValue { ... }
impl From<&str> for TemplateValue { ... }
impl From<bool> for TemplateValue { ... }

/// 模板变量上下文。
pub struct TemplateContext {
    vars: HashMap<String, TemplateValue>,
}

impl TemplateContext {
    pub fn new() -> Self;

    /// 插入变量（支持 `&str` / `String` / `bool` 自动转换）。
    pub fn insert(&mut self, key: impl Into<String>, value: impl Into<TemplateValue>);

    pub fn get(&self, key: &str) -> Option<&TemplateValue>;

    /// 从 `serde_json::Value` 递归构造（支持嵌套 Object/Array）。
    pub fn from_json(value: &serde_json::Value) -> Result<Self, PromptError>;

    /// 从 `HashMap` 构造（适用于配置加载场景）。
    pub fn from_map(map: HashMap<String, TemplateValue>) -> Self;
}

/// 预编译的模板。
pub struct PromptTemplate {
    /// 原始模板字符串（用于 debug）。
    raw: String,
    /// 编译后的 AST 片段。
    fragments: Vec<Fragment>,
}

/// 编译后的 AST 节点（内部枚举）。
enum Fragment {
    Literal(String),
    Variable { name: String },
    If { condition: String, body: Vec<Fragment>, else_body: Vec<Fragment> },
    Each { variable: String, body: Vec<Fragment> },
    Raw(String),
    Include(String),
}

impl PromptTemplate {
    /// 从模板字符串编译。
    pub fn compile(template: &str) -> Result<Self, PromptError>;

    /// 使用上下文渲染。
    pub fn render(&self, ctx: &TemplateContext) -> Result<String, PromptError>;

    /// 注册可引用的子模板。
    pub fn register_partial(&mut self, name: &str, template: PromptTemplate);
}

/// `Display` 输出原始模板字符串，便于日志和调试。
impl fmt::Display for PromptTemplate {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.raw)
    }
}
```

**编译流程**：
1. 逐字符扫描模板字符串
2. 遇到 `{{` 时解析指令类型（variable/if/each/raw/include）
3. 生成 `Fragment` AST 列表
4. 返回 `PromptTemplate { raw, fragments }`

**渲染流程**：
1. 遍历 `fragments`
2. `Literal` → 直接追加
3. `Variable { name }` → `ctx.get(name)` → 追加字符串值
4. `If { condition, body, else_body }` → 判断 `ctx.get(condition)` 是否存在且真 → 递归渲染 body/else_body
5. `Each { variable, body }` → `ctx.get(variable)` 转为数组 → 为每个元素设置 `item` 变量 → 递归渲染 body
6. `Raw(text)` → 原样追加（不解析 `{{ }}`）
7. `Include(name)` → 查找已注册的 partials → 递归渲染

### 3. PromptTemplateRegistry — 模板注册表

提供轻量的模板管理能力，按名称注册、查找、从文件加载，适用于管理多个 Agent 的提示词模板。

```rust
// prompt/template/registry.rs

use std::collections::HashMap;
use std::path::Path;
use crate::prompt::error::PromptError;
use crate::prompt::template::{PromptTemplate, TemplateContext};

/// 内部存储的模板（支持延迟编译）。
enum StoredTemplate {
    Compiled(PromptTemplate),
    Raw(String),
}

/// 模板注册表——管理多模板实例。
pub struct PromptTemplateRegistry {
    templates: HashMap<String, StoredTemplate>,
}

impl PromptTemplateRegistry {
    pub fn new() -> Self;

    /// 从模板字符串编译并注册（立即编译）。
    pub fn register(&mut self, name: &str, template: &str) -> Result<(), PromptError>;

    /// 延迟编译注册：只存储原始字符串，首次渲染时编译。
    /// 适合模板数量多但并非全部立即使用的场景。
    pub fn register_lazy(&mut self, name: &str, template: &str);

    /// 从文件读取并编译注册。
    pub fn register_file(&mut self, name: &str, path: &Path) -> Result<(), PromptError>;

    /// 获取已注册的模板（延迟编译的模板在此首次编译）。
    pub fn get(&mut self, name: &str) -> Result<&PromptTemplate, PromptError>;

    /// 按名称渲染（`{{> name }}` 引用时自动查找）。
    pub fn render(&mut self, name: &str, ctx: &TemplateContext) -> Result<String, PromptError>;
}
```

**设计约束**：
- 不设全局单例，用户自行创建和持有
- 不引入文件系统监听、热加载、序列化等复杂能力
- 注册表内部模板可用于解析 `{{> partial_name }}` 子模板引用
- 用户仍可单独持有 `PromptTemplate` 实例，不强制使用注册表

### 4. PromptComposer — 提示词组合器

```rust
// prompt/composer.rs

use crate::llm::types::message::{OpenaiChatMessage, OpenaiContentPart, ContentField};
use crate::prompt::error::PromptError;
use crate::prompt::template::{PromptTemplate, TemplateContext};

/// 提示词组合器——构建多角色消息序列。
pub struct PromptComposer {
    messages: Vec<OpenaiChatMessage>,
    pending_name: Option<String>,
}

impl PromptComposer {
    /// 创建一个空的组合器。
    pub fn new() -> Self;

    /// 从已有的消息列表初始化。
    pub fn from_messages(messages: Vec<OpenaiChatMessage>) -> Self;

    // ===== 纯文本消息 =====

    /// 添加一条纯文本 system 消息。
    pub fn system(mut self, text: impl Into<String>) -> Self;

    /// 添加一条纯文本 user 消息。
    pub fn user(mut self, text: impl Into<String>) -> Self;

    /// 添加一条纯文本 assistant 消息。
    pub fn assistant(mut self, text: impl Into<String>) -> Self;

    /// 添加一条纯文本 developer 消息（o1 系列模型使用）。
    pub fn developer(mut self, text: impl Into<String>) -> Self;

    /// 添加一条 Tool 消息（工具执行结果回传）。
    pub fn tool(mut self, tool_call_id: impl Into<String>, content: impl Into<String>) -> Self;

    // ===== 模板消息 =====

    /// 使用模板和上下文渲染后添加为 user 消息。
    pub fn user_template(
        mut self,
        template: &PromptTemplate,
        ctx: &TemplateContext,
    ) -> Result<Self, PromptError>;

    /// 使用模板和上下文渲染后添加为 system 消息。
    pub fn system_template(
        mut self,
        template: &PromptTemplate,
        ctx: &TemplateContext,
    ) -> Result<Self, PromptError>;

    /// 使用模板和上下文渲染后添加为 assistant 消息。
    pub fn assistant_template(
        mut self,
        template: &PromptTemplate,
        ctx: &TemplateContext,
    ) -> Result<Self, PromptError>;

    /// 使用模板和上下文渲染后添加为 developer 消息。
    pub fn developer_template(
        mut self,
        template: &PromptTemplate,
        ctx: &TemplateContext,
    ) -> Result<Self, PromptError>;

    // ===== 多模态 ContentPart =====

    /// 添加一条含指定 ContentPart 的 system 消息。
    pub fn system_content(mut self, part: OpenaiContentPart) -> Self;

    /// 添加一条含指定 ContentPart 的 user 消息。
    pub fn user_content(mut self, part: OpenaiContentPart) -> Self;

    /// 添加一条含指定 ContentPart 的 assistant 消息。
    pub fn assistant_content(mut self, part: OpenaiContentPart) -> Self;

    /// 添加一条含指定 ContentPart 的 developer 消息。
    pub fn developer_content(mut self, part: OpenaiContentPart) -> Self;

    /// 添加一条含指定 ContentPart 的 Tool 消息。
    pub fn tool_content(mut self, tool_call_id: impl Into<String>, part: OpenaiContentPart) -> Self;

    /// 批量添加 ContentPart 作为 user 消息。
    pub fn user_contents(mut self, parts: Vec<OpenaiContentPart>) -> Self;

    /// 批量添加 ContentPart 作为 system 消息。
    pub fn system_contents(mut self, parts: Vec<OpenaiContentPart>) -> Self;

    /// 批量添加 ContentPart 作为 assistant 消息。
    pub fn assistant_contents(mut self, parts: Vec<OpenaiContentPart>) -> Self;

    /// 批量添加 ContentPart 作为 developer 消息。
    pub fn developer_contents(mut self, parts: Vec<OpenaiContentPart>) -> Self;

    // ===== 角色标识 =====

    /// 为上一条添加的消息设置 `name` 字段（多 agent 系统中区分同角色实体）。
    pub fn with_name(mut self, name: impl Into<String>) -> Self;

    // ===== 构建 =====

    /// 构建最终的消息列表。
    pub fn build(self) -> Vec<OpenaiChatMessage>;

    /// 构建并直接创建 ChatRequest（需搭配 model 参数）。
    /// 返回的 `OpenaiChatRequest` 中 `tools`、`temperature`、`max_tokens` 等字段均为 `None`，
    /// 可通过结构体更新语法补全：`OpenaiChatRequest { tools: Some(...), ..req }`。
    pub fn build_request(
        self,
        model: impl Into<String>,
    ) -> crate::llm::types::request::OpenaiChatRequest;
}

/// 验证消息序列是否符合 OpenAI API 要求。
/// 检查项：Tool 消息必须紧跟在匹配的 Assistant 消息后、角色交替规则等。
pub fn validate_messages(messages: &[OpenaiChatMessage]) -> Result<(), PromptError>;
```

**Builder 模式设计**：
- `PromptComposer` 采用链式调用（builder pattern），与 Rust 生态的主流风格一致
- 每个 `system()` / `user()` / `assistant()` / `developer()` / `tool()` 方法返回 `Self`，支持连续调用
- `with_name()` 作用于上一条消息，内部通过 `pending_name: Option<String>` 暂存，push 消息时消费
- `build()` 返回 `Vec<OpenaiChatMessage>`，`build_request()` 创建完整的 `OpenaiChatRequest`
- **`ContentField` 类型约定**：所有纯文本消息（`system()` / `user()` / `assistant()` / `developer()`）统一使用 `ContentField::Array(vec![OpenaiContentPart::Text{...}])`，与 OpenAI API 非流式响应的标准格式一致

**`validate_messages()` 校验规则**：
1. `Tool` 角色的消息必须跟在 `Assistant` 角色且含 `tool_calls` 的消息之后
2. 禁止连续出现两条同角色的非 Tool 消息（system 除外）
3. 消息列表不能为空

### 5. PromptError — 错误类型

```rust
// prompt/error.rs

use thiserror::Error;

#[derive(Error, Debug)]
pub enum PromptError {
    #[error("模板解析错误: {0}")]
    Parse(String),

    #[error("渲染错误: 变量 '{0}' 未找到")]
    VariableNotFound(String),

    #[error("渲染错误: 引用的子模板 '{0}' 未注册")]
    PartialNotFound(String),

    #[error("渲染错误: '{0}' 不是数组，无法遍历")]
    NotAnArray(String),

    #[error("渲染递归超过最大深度限制 ({0})")]
    MaxDepthReached(u8),

    #[error("渲染错误: {0}")]
    Render(String),

    #[error("消息序列校验失败: {0}")]
    InvalidSequence(String),

    #[error("文件读取错误: {0}")]
    Io(#[from] std::io::Error),
}
```

### 6. 使用示例

```rust
use agcore::prompt::{PromptComposer, PromptTemplate, TemplateContext};

// 编译模板
let tpl = PromptTemplate::compile(
    "你是{{role}}。请回答以下问题：\n{{#if context}}参考背景：{{context}}\n{{/if}}提问：{{question}}"
)?;

// 构建上下文
let mut ctx = TemplateContext::new();
ctx.insert("role", "资深工程师");
ctx.insert("question", "Rust 的所有权规则是什么？");
ctx.insert("context", "用户有 Java 背景");

// 使用组合器构建消息序列
let messages = PromptComposer::new()
    .system("你是一个专业的 Rust 助手")
    .user_template(&tpl, &ctx)?
    .build();

// 可选：直接构建 ChatRequest
let request = PromptComposer::new()
    .system("你是一个翻译助手")
    .user("Hello, world!")
    .build_request("gpt-4o");
```

### 7. 与 LlmCycle 的集成

`PromptComposer::build()` 输出 `Vec<OpenaiChatMessage>`，但 **`LlmCycle.messages` 是私有字段**，无法直接赋值。因此**需要对 `LlmCycle` 进行扩展**，提供消息注入入口，使 Composer 能和 `LlmCycle` 的多轮对话循环协同工作。

**方案**：在 `LlmCycle` 上新增 3 个方法：

```rust
// llm/cycle.rs

impl LlmCycle {
    /// 直接设置消息历史（覆盖已有消息），支持 Builder 链式调用。
    pub fn with_messages(mut self, messages: Vec<Message>) -> Self;

    /// 追加消息到历史尾部。
    pub fn extend_messages(&mut self, messages: Vec<Message>);

    /// 使用预构建消息提交（跳过自动 push user prompt）。
    /// 与 submit() 不同，不自动添加 user_text(prompt)。
    pub async fn submit_messages(
        &mut self,
        messages: Vec<Message>,
        tools: Vec<ToolDefinition>,
    ) -> Result<ChatResponse, LlmError>;
}
```

**`submit_messages()` 与 `submit()` 的区别**：

| 维度 | `submit()` | `submit_messages()` |
|------|-----------|-------------------|
| 输入 | `prompt: String` + `tools` | `messages: Vec<Message>` + `tools` |
| 内部操作 | 自动 push `user_text(prompt)` | 不自动添加任何消息 |
| 适用场景 | 简单单轮对话 | 多轮/预构建消息序列 |
| system_prompt 处理 | 自动插入（如果无 System 消息） | 完全由调用方控制 |

**`system_prompt` 冲突处理**：`submit_messages()` 关闭 `LlmCycle` 的自动 system prompt 插入逻辑，避免与 `PromptComposer` 已构建的 System/Developer 消息重复。由调用方全权控制消息序列内容。

**使用示例**：
```rust
let messages = PromptComposer::new()
    .system("你是一个专业的 Rust 助手")
    .user_template(&query_tpl, &ctx)?
    .build();

let mut cycle = LlmCycle::new(provider, config)
    .with_messages(messages);

let resp = cycle.submit_messages(vec![], tools).await?;
```

`PromptComposer::build_request()` 直接创建 `OpenaiChatRequest`，可用于绕过 `LlmCycle` 直接调用 `LlmProvider` 的场景。

**注意**：`PromptComposer` 模块 **不** 直接依赖 `LlmCycle`（避免 `prompt → cycle` 的强耦合）。集成方法全部在 `LlmCycle` 侧实现，保持单一职责。

---

## 实现计划

### Step 1: 创建方案文档

创建 `docs/4-prompt-engineering.md`（即本文档）。

### Step 2: PromptError

- 创建 `src/prompt/error.rs`
- 定义 `PromptError` 枚举（Parse / Render / VariableNotFound / PartialNotFound）

### Step 3: PromptTemplate

- 创建 `src/prompt.rs`（模块根）
- 创建 `src/prompt/template.rs`
- 实现编译（`compile()`）：逐字符扫描 → 生成 `Vec<Fragment>`
  - 注意处理：嵌套 `#if` 栈匹配、`{{` 字面量转义、未闭合标签检测
- 实现渲染（`render()`）：递归遍历 Fragment → 拼接字符串
  - 定义非字符串值渲染格式：`Bool`→`"true"`/`"false"`、`Array`→JSON、`Object`→JSON
  - 递归加深度限制（16 层）防止循环引用
- 支持功能：变量插值、条件渲染、列表循环、原始块、子模板引用
- 实现 `Display for PromptTemplate`（输出原始模板字符串）
- 编写 20+ 边界测试覆盖：嵌套 if/each、未闭合标签、空变量、空数组 each、递归深度超限
- 运行 `cargo test + cargo check` 验证

### Step 4: PromptTemplateRegistry

- 推荐选项：`template` 保持单文件，`PromptTemplateRegistry` 合并同文件（~40 行不值得单独目录）
- 内部存储使用 `StoredTemplate` 枚举（支持 `Compiled` 和 `Raw` 两种状态）
- 实现：`register()` 立即编译、`register_lazy()` 延迟编译、`register_file()` 文件加载
- 实现 `get()` / `render()`（延迟编译的模板首次渲染时编译）
- 运行 `cargo check` 验证

### Step 5: PromptComposer

- 创建 `src/prompt/composer.rs`
- 实现 Builder 链式 API，内部维护 `messages: Vec<OpenaiChatMessage>` + `pending_name: Option<String>`
- 角色方法：`system()` / `user()` / `assistant()` / `developer()` / `tool()`
  - 纯文本消息统一使用 `ContentField::Array([Text])`
  - `tool()` 需传入 `tool_call_id` 和 `content`
- 模板方法：`system_template()` / `user_template()` / `assistant_template()` / `developer_template()`
- 多模态方法：`*_content()`（单个 ContentPart）和 `*_contents()`（批量）
- `with_name()`：作用于上一条消息的 `name` 字段
- `build()` / `build_request()`
- `validate_messages()`：独立的纯函数，校验 Tool→Assistant 顺序、角色交替、非空
- 运行 `cargo check` 验证

### Step 6: LlmCycle 扩展

- `cycle.rs` 新增 3 个方法：
  - `with_messages(self, messages: Vec<Message>) -> Self` — 链式设置消息历史
  - `extend_messages(&mut self, messages: Vec<Message>)` — 追加消息
  - `submit_messages(&mut self, messages: Vec<Message>, tools: Vec<ToolDefinition>) -> Result<...>` — 预构建消息提交
- `submit_messages()` 关闭自动 system_prompt 插入（避免与 Composer 的 System/Developer 消息重复）
- 运行 `cargo check` 验证

### Step 7: lib.rs 注册

- `lib.rs` 添加 `pub mod prompt;`
- 运行 `cargo check` 验证

### Step 8: 收尾

- `cargo clippy` — 无警告
- `cargo build` — 完整构建
- 检查所有新公开 API 有 `///` 文档注释

---

## 术语表

| 术语 | 说明 |
|------|------|
| `TemplateValue` | 模板渲染上下文中使用的值类型枚举 |
| `TemplateContext` | 模板变量上下文，持有所有变量 |
| `PromptTemplate` | 预编译的模板，持有 AST 片段列表 |
| `Fragment` | 编译后的 AST 节点（内部枚举） |
| `PromptComposer` | 提示词组合器，构建多角色消息序列 |
| `PromptError` | 提示词工程专属错误类型 |

---

## 风险评估

| 风险 | 概率 | 缓解措施 |
|------|------|---------|
| 模板语法不支持复杂场景（如嵌套 each） | 低 | 当前需求不涉及；后续可引入 tera 替换 |
| 自定义模板引擎解析有 bug | 中 | 编写单元测试覆盖所有语法分支 |
| 与未来 Prompt Optimizer 冲突 | 低 | PromptOptimizer 只修改模板/上下文，不改模板引擎接口 |
| 条件语义不明确（什么是"假"值） | 低 | 明确定义：None / false / 空字符串 / 空数组 均为假 |
| 子模板循环引用导致栈溢出 | 低 | 渲染时加递归深度限制（16 层）或已注册集合去重检测 |

---

## 验收标准

1. `cargo check` 编译通过
2. `cargo clippy` 无警告
3. 模块文件路径正确：`src/prompt.rs` + `src/prompt/{template,composer,error}.rs`
4. `PromptTemplate::compile()` 能解析含变量/条件/循环的模板
5. `PromptTemplate::render()` 正确渲染所有语法
6. `PromptTemplate` 实现 `Display` trait，输出原始模板字符串
7. `TemplateContext` 提供 `from_json()` / `from_map()` 构造方式，支持 `From<&str>` 自动转换
8. `PromptTemplateRegistry` 支持立即编译（`register()`）、延迟编译（`register_lazy()`）、文件加载（`register_file()`）
9. `PromptComposer` 支持链式调用，覆盖 System / User / Assistant / Developer / Tool 五种角色
10. `PromptComposer` 支持 `user_content()` / `system_content()` / `assistant_content()` / `developer_content()` / `tool_content()` 多模态方法
11. `PromptComposer` 支持 `with_name()` 设置消息角色标识
12. `PromptComposer::build_request()` 能创建 `OpenaiChatRequest`
13. `validate_messages()` 能校验消息序列合法性
14. `LlmCycle` 新增 `with_messages()` / `extend_messages()` / `submit_messages()` 支持 Composer 集成
15. `lib.rs` 包含 `pub mod prompt;`
16. 所有新公开 API 有文档注释