IC-Coder-Plugin/docs/personal-rules-backend-integration.md

# 个人规则功能 - 后端对接文档

## 1. 功能概述

个人规则功能允许用户创建多条自定义规则，这些规则会在每次对话时自动传递给后端，由后端注入到 AI 的系统提示词中，从而影响 AI 的回答风格和行为。

## 2. 前端实现说明

### 2.1 用户界面
- 用户可以在设置页面创建、修改、删除多条规则
- 每条规则包含：规则名称 + 规则内容
- 全局开关：启用/禁用所有规则

### 2.2 规则存储
- 存储位置：`C:\Users\{用户名}\.iccoder\rules\`
- 文件格式：每条规则一个独立的 `.md` 文件
- 文件命名：`rule-{时间戳}.md`
- 文件内容格式：
  ```markdown
  # 规则名称

  规则内容详细描述...
  ```

### 2.3 规则传输逻辑
- **开关开启**：所有规则内容合并后通过 `personalRules` 字段传给后端
- **开关关闭**：`personalRules` 字段为 `undefined`，不传给后端

## 3. 后端接口变更

### 3.1 DialogRequest 接口新增字段

在现有的 `DialogRequest` 接口中新增 `personalRules` 字段：

```typescript
export interface DialogRequest {
  taskId: string;
  message: string;
  userId: string;
  mode: RunMode;
  serviceTier?: ServiceTier;
  token?: string;
  compactedData?: CompactedMemory;
  newMessages?: CompactedMessage[];
  knowledgeData?: string;
  personalRules?: string;  // 新增：个人规则内容
}
```

### 3.2 字段说明

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `personalRules` | `string` | 否 | 用户的个人规则内容，多条规则用 `\n\n` 分隔 |

### 3.3 字段示例

**单条规则：**
```json
{
  "message": "帮我写一个排序函数",
  "personalRules": "始终使用中文回复，代码注释要详细"
}
```

**多条规则（合并后）：**
```json
{
  "message": "帮我写一个排序函数",
  "personalRules": "始终使用中文回复，代码注释要详细\n\n使用 TypeScript 严格模式\n\n遵循项目编码规范"
}
```

**规则关闭：**
```json
{
  "message": "帮我写一个排序函数",
  "personalRules": undefined
}
```

## 4. 后端处理要求

### 4.1 接收处理

```typescript
// 伪代码示例
function handleDialogRequest(request: DialogRequest) {
  const { message, personalRules, ...otherFields } = request;

  // 检查是否有个人规则
  if (personalRules && personalRules.trim()) {
    // 有规则：注入到系统提示词
    return processWithRules(message, personalRules, otherFields);
  } else {
    // 无规则：正常处理
    return processNormal(message, otherFields);
  }
}
```

### 4.2 规则注入策略

**重要：规则必须注入到系统提示词层，而不是用户消息层**

推荐的注入顺序（优先级从高到低）：

1. **平台安全策略**（最高优先级，不可被覆盖）
2. **产品默认系统提示**
3. **用户个人规则** ← 在这里注入
4. **用户输入消息**

### 4.3 注入示例

```typescript
// 伪代码示例
function buildSystemPrompt(personalRules?: string): string {
  let systemPrompt = `
你是一个专业的 AI 助手。
遵循以下基本原则：
- 安全第一
- 准确回答
- 友好交流
`;

  // 如果有个人规则，追加到系统提示词
  if (personalRules && personalRules.trim()) {
    systemPrompt += `\n\n用户的个人偏好和规则：\n${personalRules}`;
  }

  return systemPrompt;
}

function processWithRules(
  userMessage: string,
  personalRules: string,
  otherFields: any
) {
  const systemPrompt = buildSystemPrompt(personalRules);

  // 调用 AI 模型
  return callAIModel({
    system: systemPrompt,
    user: userMessage,
    ...otherFields
  });
}
```

## 5. 注意事项

### 5.1 安全性
- ⚠️ **个人规则不能覆盖平台安全策略**
- ⚠️ **需要对规则内容进行基本的安全检查**
- ⚠️ **防止注入攻击（如提示词注入）**

### 5.2 长度限制
- 前端已限制单条规则内容，但多条规则合并后可能较长
- 建议后端设置总长度上限（如 10000 字符）
- 超限时可以截断或返回错误提示

### 5.3 兼容性
- `personalRules` 字段为可选字段
- 旧版本前端不传此字段时，后端应正常处理（向后兼容）
- 字段为 `undefined` 或空字符串时，视为无规则

### 5.4 日志记录
建议在日志中记录：
- 本次请求是否包含个人规则
- 规则内容的长度（不要记录完整内容，避免隐私泄露）
- 规则注入是否成功

示例日志：
```
[INFO] Dialog request received
  - taskId: abc123
  - userId: user456
  - hasPersonalRules: true
  - rulesLength: 156
  - rulesInjected: success
```

## 6. 测试建议

### 6.1 功能测试
1. **无规则场景**：`personalRules` 为 `undefined`，正常对话
2. **单条规则**：传入一条规则，验证 AI 是否遵循
3. **多条规则**：传入多条规则，验证 AI 是否同时遵循
4. **规则冲突**：传入相互矛盾的规则，观察 AI 行为
5. **超长规则**：传入超长内容，验证截断或错误处理

### 6.2 安全测试
1. **提示词注入**：尝试在规则中注入恶意提示词
2. **覆盖安全策略**：尝试用规则覆盖平台安全限制
3. **特殊字符**：测试规则中包含特殊字符的情况

### 6.3 性能测试
1. **大量规则**：测试 10+ 条规则的性能影响
2. **高频请求**：测试规则注入对响应时间的影响

## 7. 错误处理

### 7.1 可能的错误场景

| 错误场景 | 处理方式 |
|---------|---------|
| 规则内容为空字符串 | 视为无规则，正常处理 |
| 规则内容超长 | 截断或返回错误 |
| 规则包含非法内容 | 过滤或拒绝请求 |
| 规则注入失败 | 降级为无规则对话 |

### 7.2 错误响应示例

```json
{
  "error": {
    "code": "RULES_TOO_LONG",
    "message": "个人规则内容超过长度限制（最大 10000 字符）"
  }
}
```

## 8. 验收标准

### 8.1 基本功能
- [ ] 能正确接收 `personalRules` 字段
- [ ] 规则能正确注入到系统提示词
- [ ] 规则关闭时不影响正常对话
- [ ] 多条规则能同时生效

### 8.2 安全性
- [ ] 规则不能覆盖平台安全策略
- [ ] 有基本的内容安全检查
- [ ] 日志中不记录完整规则内容

### 8.3 兼容性
- [ ] 旧版本前端（无此字段）能正常工作
- [ ] 字段为 `undefined` 时正常处理

## 9. 联系方式

如有疑问，请联系前端开发团队。

---

**文档版本**：v1.0
**最后更新**：2026-03-07