feat: 添加个人规则功能
- 新增个人规则管理模块 (personalRulesManager.ts) - 支持创建、编辑、删除多条规则 - 规则存储在用户目录 ~/.iccoder/rules/ - 对话时自动将规则传递给后端 - 添加后端对接文档和 webpack 优化指南
This commit is contained in:
Roe-xin
247
docs/personal-rules-backend-integration.md
Normal file
247
docs/personal-rules-backend-integration.md
Normal file
@ -0,0 +1,247 @@
|
||||
# 个人规则功能 - 后端对接文档
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user