# AI功能扩展与开发指导文档

## 📋 概述

本文档基于当前系统的占位符分析和提示词设计原则，为后续功能扩展和新功能开发提供标准化指导。

## 🎯 设计原则

### 1. **提示词设计原则**

#### **系统提示词结构** (除聊天功能外)
```
1. AI角色定义 (专业定位和能力描述)
2. ## 当前任务要求 (参数化要求)
   - **功能参数1**: {{param1}}
   - **功能参数2**: {{param2}}  
   - **具体指令**: {{instructions}}
3. ## 你的核心能力 (数字列表，5-7项)
4. ## [功能名]原则 (操作原则和约束)
5. ## 操作指南 (具体执行步骤)
6. 结尾引导语
```

#### **用户提示词结构** (除聊天功能外)
```markdown
## 需要[动作]的文本
{{input}}

## 小说背景信息
**小说**: 《{{novelTitle}}》
**作者**: {{authorName}}

## 相关上下文
{{context}}

请按照系统要求对以上文本进行[动作]。
```

#### **聊天功能特殊结构**
- **系统提示词**: 角色 + 对话背景 + 指令 + 能力 + 原则 + 上下文信息
- **用户提示词**: `{{message}}` (用户消息内容)

### 2. **占位符系统规范**

#### **核心占位符** (所有功能必须支持)
| 占位符 | 说明 | 来源 | 必需性 |
|--------|------|------|--------|
| `{{input}}` | 用户输入的主要内容 | selectedText/prompt | ✅ 必需 |
| `{{context}}` | 上下文信息 | contextSelections处理 | ✅ 必需 |
| `{{instructions}}` | 用户具体指令 | instructions字段 | ✅ 必需 |
| `{{novelTitle}}` | 小说标题 | 从Novel实体获取 | ✅ 必需 |
| `{{authorName}}` | 作者姓名 | 从Novel实体获取 | ✅ 必需 |

#### **功能特定占位符** (根据功能需求选择)
| 占位符 | 说明 | 适用功能 | 前端传递方式 |
|--------|------|----------|-------------|
| `{{length}}` | 长度要求 | 扩写/总结/重构 | parameters['length'] |
| `{{style}}` | 风格要求 | 扩写/总结/重构 | parameters['style'] |
| `{{message}}` | 聊天消息 | 聊天功能 | prompt字段 |

#### **内容提供器占位符** (可选，按需使用)
| 占位符 | 说明 | 实现状态 |
|--------|------|----------|
| `{{full_novel_text}}` | 完整小说文本 | ✅ 已实现 |
| `{{full_novel_summary}}` | 完整小说摘要 | ✅ 已实现 |
| `{{scene}}` | 场景内容 | ✅ 已实现 |
| `{{chapter}}` | 章节内容 | ✅ 已实现 |
| `{{act}}` | 卷/部内容 | ✅ 已实现 |
| `{{setting}}` | 设定内容 | ✅ 已实现 |
| `{{snippet}}` | 片段内容 | ✅ 已实现 |

## 🛠️ 新功能开发流程

### 步骤1：功能定义和枚举
```java
// 1. 在AIFeatureType中添加新的功能类型
public enum AIFeatureType {
    // 现有功能...
    NEW_FEATURE_NAME,  // 新功能
}
```

### 步骤2：创建Provider实现
```java
// 2. 创建新的Provider类
@Component
public class NewFeaturePromptProvider extends BasePromptProvider {
    
    // 默认系统提示词
    private static final String DEFAULT_SYSTEM_PROMPT = """
            你是[AI角色定义]。

            ## 当前任务要求
            - **参数1**: {{param1}}
            - **参数2**: {{param2}}
            - **具体指令**: {{instructions}}

            ## 你的核心能力
            1. **能力1**：描述
            2. **能力2**：描述
            3. **能力3**：描述
            4. **能力4**：描述
            5. **能力5**：描述

            ## [功能名]原则
            - 原则1
            - 原则2
            - 原则3

            ## 操作指南
            1. 步骤1
            2. 步骤2
            3. 步骤3
            4. 步骤4
            5. 步骤5

            请准备根据用户提供的内容进行[动作]。
            """;

    // 默认用户提示词
    private static final String DEFAULT_USER_PROMPT = """
            ## 需要[动作]的文本
            {{input}}

            ## 小说背景信息
            **小说**: 《{{novelTitle}}》
            **作者**: {{authorName}}

            ## 相关上下文
            {{context}}

            请按照系统要求对以上文本进行[动作]。
            """;

    public NewFeaturePromptProvider() {
        super(AIFeatureType.NEW_FEATURE_NAME);
    }

    @Override
    public String getDefaultSystemPrompt() {
        return DEFAULT_SYSTEM_PROMPT;
    }

    @Override
    public String getDefaultUserPrompt() {
        return DEFAULT_USER_PROMPT;
    }

    @Override
    protected Set<String> initializeSupportedPlaceholders() {
        return Set.of(
            // 核心占位符（必需）
            "input", "context", "instructions",
            "novelTitle", "authorName",
            
            // 功能特定参数（按需添加）
            "param1", "param2",
            
            // 内容提供器占位符（可选）
            "full_novel_text", "full_novel_summary",
            "act", "chapter", "scene", "setting", "snippet"
        );
    }
}
```

### 步骤3：前端集成
```dart
// 3. 前端对话框或界面
class NewFeatureDialog extends StatefulWidget {
  // UI组件收集用户输入
  
  void _submitRequest() {
    final request = UniversalAIRequestDto(
      requestType: 'NEW_FEATURE_NAME',
      selectedText: selectedText,
      instructions: instructions,
      parameters: {
        'param1': userSelectedParam1,
        'param2': userSelectedParam2,
        // 其他参数...
      },
      contextSelections: contextSelections,
    );
    
    // 调用API
    _aiService.processRequest(request);
  }
}
```

### 步骤4：请求类型映射
```java
// 4. 确保UniversalAIServiceImpl中的映射正确
private AIFeatureType mapRequestTypeToFeatureType(String requestType) {
    if (requestType == null) {
        return AIFeatureType.AI_CHAT;
    }
    return AIFeatureType.valueOf(requestType); // 直接映射
}
```

## 📊 功能分类与模板

### 1. **文本处理类功能**
适用于：扩写、总结、重构、翻译、润色等

**特点**：
- 有明确的输入文本(`{{input}}`)
- 需要长度和风格控制
- 输出替代原文本

**模板参考**: `TextExpansionPromptProvider`

### 2. **内容生成类功能**  
适用于：续写、创作、生成大纲等

**特点**：
- 基于上下文生成新内容
- 需要创意和想象力
- 输出补充现有内容

**模板参考**: `NovelGenerationPromptProvider`

### 3. **交互对话类功能**
适用于：聊天、问答、建议等

**特点**：
- 用户消息为主要输入
- 上下文在系统提示词中
- 支持多轮对话

**模板参考**: `AIChatPromptProvider`

## 🔍 测试验证清单

### Provider实现验证
- [ ] 正确继承`BasePromptProvider`
- [ ] 实现所有必需方法
- [ ] 占位符列表准确
- [ ] 提示词格式正确
- [ ] Spring组件注解正确

### 占位符验证
- [ ] 核心占位符全部支持
- [ ] 功能特定占位符正确
- [ ] 不支持的占位符已移除
- [ ] 占位符在模板中正确使用

### 前端集成验证
- [ ] 参数正确传递到`parameters`
- [ ] 请求类型枚举匹配
- [ ] UI界面收集必要参数
- [ ] 错误处理完善

### 系统集成验证
- [ ] PromptProviderFactory自动注册
- [ ] 占位符解析正常工作
- [ ] 预览功能正常显示
- [ ] 流式和非流式都支持

## ⚠️ 常见陷阱与注意事项

### 1. **占位符陷阱**
❌ **错误**：定义大量未实现的占位符
```java
// 不要这样做
return Set.of(
    "input", "context", "instructions",
    "unimplementedFeature1", "unimplementedFeature2", // ❌ 未实现
    "complexFeature", "advancedOption" // ❌ 无对应实现
);
```

✅ **正确**：只定义已实现的占位符
```java
// 这样做
return Set.of(
    // 核心占位符（系统保证实现）
    "input", "context", "instructions", "novelTitle", "authorName",
    // 功能特定参数（前端传递）
    "length", "style",
    // 内容提供器（已验证实现）
    "scene", "chapter", "setting"
);
```

### 2. **提示词设计陷阱**
❌ **错误**：任务要求放在用户提示词
```xml
<!-- 不要这样做 -->
<task>
  <action>扩写</action>
  <requirements>
    <length>{{length}}</length>
    <style>{{style}}</style>
  </requirements>
  <input>{{input}}</input>
</task>
```

✅ **正确**：任务要求放在系统提示词
```
## 当前任务要求
- **扩写长度**: {{length}}
- **扩写风格**: {{style}}
- **具体指令**: {{instructions}}
```

### 3. **前端参数传递陷阱**
❌ **错误**：参数名不一致
```dart
// 前端
parameters: {
  'expansionLength': selectedLength,  // ❌ 参数名不匹配
}
```

```java
// 后端期望
"{{length}}"  // ❌ 不匹配
```

✅ **正确**：保持参数名一致
```dart
// 前端
parameters: {
  'length': selectedLength,  // ✅ 匹配
  'style': selectedStyle,    // ✅ 匹配
}
```

## 🚀 最佳实践

### 1. **提示词设计最佳实践**
- 系统提示词包含角色、能力、原则、指导
- 用户提示词专注于提供内容和背景
- 使用结构化格式，便于AI理解
- 保持提示词简洁但信息完整

### 2. **占位符使用最佳实践**
- 优先使用核心占位符系统
- 功能特定参数通过`parameters`传递
- 避免定义未实现的占位符
- 保持前后端参数名一致

### 3. **代码组织最佳实践**
- 每个功能一个独立的Provider
- 提示词内容使用常量定义
- 占位符列表明确注释
- 遵循现有命名规范

### 4. **测试最佳实践**
- 单独测试Provider的提示词生成
- 验证占位符解析正确性
- 测试前端参数传递
- 端到端功能测试

## 📚 参考示例

完整的功能实现可以参考：
- **文本重构**: `TextRefactorPromptProvider.java`
- **文本总结**: `TextSummaryPromptProvider.java` 
- **文本扩写**: `TextExpansionPromptProvider.java`
- **AI聊天**: `AIChatPromptProvider.java`

## 🔄 版本更新指南

当需要更新现有功能时：
1. 评估是否需要新增占位符
2. 确保向后兼容性
3. 更新测试用例
4. 更新文档

当发现系统性问题时：
1. 优先修复核心占位符系统
2. 统一更新所有Provider
3. 保持设计原则一致性
4. 全面测试影响

---

**文档版本**: v1.0  
**最后更新**: 2024年  
**维护者**: AI系统开发团队