162 lines
5.7 KiB
Markdown
162 lines
5.7 KiB
Markdown
# 个人规则功能需求文档（方案 A：本地 `.md` 注入）
|
||
|
||
## 1. 文档目标
|
||
|
||
在不改动现有核心对话模式的前提下，实现“个人规则（Personal Rules）”能力：
|
||
用户可在插件内维护个人规则文本，插件保存到本地 `.md` 文件；每次发起对话时自动读取并随请求传递给后端，由后端注入模型上下文，影响回答风格与行为。
|
||
|
||
## 2. 范围定义
|
||
|
||
### 2.1 本期范围（MVP）
|
||
|
||
1. 支持用户编辑、保存、启用/停用个人规则。
|
||
2. 本地落盘为 `.md` 文件。
|
||
3. 发消息时自动加载规则并传给后端。
|
||
4. 后端接收结构化字段并注入提示词。
|
||
5. 基础异常处理和可观测提示。
|
||
|
||
### 2.2 非本期范围
|
||
|
||
1. 云端同步、多设备同步。
|
||
2. 规则版本历史/回滚。
|
||
3. 多规则集合管理（仅单份个人规则文本）。
|
||
4. 团队共享规则。
|
||
|
||
## 3. 术语与核心概念
|
||
|
||
1. `Personal Rules`：用户个人偏好与约束文本。
|
||
2. `Rules File`：本地规则文件，Markdown 格式。
|
||
3. `Rules Enabled`：规则开关；关闭时不注入。
|
||
4. `Rules Injection`：请求时将规则传后端并参与模型上下文构建。
|
||
|
||
## 4. 用户故事
|
||
|
||
1. 作为用户，我希望在插件里写下“回答风格、代码习惯、语言偏好”等个人规则。
|
||
2. 作为用户，我希望规则保存在本地可见文件中。
|
||
3. 作为用户，我希望发消息时自动生效，无需每次重复输入。
|
||
4. 作为用户，我希望可以一键关闭规则，临时不生效。
|
||
|
||
## 5. 功能需求（前端/Webview + 扩展端）
|
||
|
||
### 5.1 规则管理界面
|
||
|
||
1. 提供“个人规则”入口。
|
||
2. 提供多行编辑框（显示当前规则内容）。
|
||
3. 提供“保存”按钮。
|
||
4. 提供“启用/停用”开关。
|
||
5. 显示当前状态：
|
||
6. 规则是否启用。
|
||
7. 规则字数/长度。
|
||
8. 最近保存时间（可选）。
|
||
|
||
### 5.2 本地文件存储
|
||
|
||
1. 规则内容保存到本地 `.md`。
|
||
2. 推荐文件名：`personal-rules.md`。
|
||
3. 推荐路径（优先）：插件全局存储目录下固定子路径。
|
||
4. 文件不存在时可自动创建。
|
||
5. 用户可通过“打开规则文件”查看（可选）。
|
||
|
||
### 5.3 对话发送前处理
|
||
|
||
1. 用户点击发送消息。
|
||
2. 扩展端检查规则开关：
|
||
3. 关闭：不读取规则，不传后端。
|
||
4. 开启：读取 `.md` 内容。
|
||
5. 读取成功且非空时，将规则文本附加到对话请求结构化字段。
|
||
6. 读取失败时：提示告警，但不阻断正常对话。
|
||
|
||
### 5.4 限制与防护
|
||
|
||
1. 规则长度上限（例如 4000 字符，可配置）。
|
||
2. 超限时保存被拒绝，提示用户缩短。
|
||
3. 空白内容视为“无规则”。
|
||
4. 不允许二进制或非文本写入。
|
||
|
||
## 6. 功能需求（后端）
|
||
|
||
### 6.1 请求协议扩展
|
||
|
||
在现有对话请求结构中增加字段：
|
||
|
||
1. `personalRules`：字符串，可选。
|
||
2. `rulesEnabled`：布尔，可选（便于追踪）。
|
||
3. `rulesMeta`：可选元信息（长度、来源）。
|
||
|
||
### 6.2 注入策略
|
||
|
||
1. 后端收到 `personalRules` 后，将其注入系统提示层（而非用户消息层）。
|
||
2. 注入顺序建议：
|
||
3. 系统安全与平台策略。
|
||
4. 产品默认系统提示。
|
||
5. 用户个人规则。
|
||
6. 用户输入。
|
||
7. 若 `personalRules` 为空或开关关闭，则跳过注入。
|
||
|
||
### 6.3 风险控制
|
||
|
||
1. 规则文本不允许覆盖平台安全策略。
|
||
2. 记录本次是否注入规则（日志字段即可）。
|
||
3. 异常不应导致整次对话失败（可降级为无规则对话）。
|
||
|
||
## 7. 前后端对接设计
|
||
|
||
### 7.1 消息链路
|
||
|
||
1. Webview 触发 `sendMessage`。
|
||
2. 扩展端 `messageHandler` 统一处理发送。
|
||
3. `messageHandler` 在调用 `dialogService.sendMessage` 前读取个人规则。
|
||
4. `dialogService` 组装 `DialogRequest`，带上 `personalRules`。
|
||
5. `sseHandler` 发起流式请求。
|
||
6. 后端注入规则后进入模型推理。
|
||
7. 正常走现有 SSE 回传流程。
|
||
|
||
### 7.2 职责边界
|
||
|
||
1. Webview：展示与编辑，不直接拼接最终请求。
|
||
2. 扩展端：规则文件读写、开关状态管理、请求组装。
|
||
3. 后端：规则注入、优先级控制、审计日志。
|
||
|
||
## 8. 数据与状态设计
|
||
|
||
### 8.1 本地文件
|
||
|
||
1. 文件格式：Markdown 纯文本。
|
||
2. 内容约定：无强制模板，允许自由文本。
|
||
3. 编码：UTF-8。
|
||
|
||
### 8.2 本地配置状态
|
||
|
||
1. `personalRulesEnabled`：是否启用。
|
||
2. `personalRulesPath`：规则文件路径（可固定也可配置）。
|
||
3. `lastSavedAt`：最近保存时间（可选）。
|
||
|
||
## 9. 异常与降级
|
||
|
||
1. 文件不存在：自动创建空文件，视为无规则。
|
||
2. 文件读取失败：弹出提示，继续无规则发送。
|
||
3. 文件写入失败：保存失败提示，不更新状态。
|
||
4. 后端字段不识别：请求兼容，后端忽略新字段。
|
||
5. 后端注入失败：降级为普通对话，记录日志。
|
||
|
||
## 10. 安全与合规要求
|
||
|
||
1. 个人规则属于用户本地数据，不主动上传除非发起对话。
|
||
2. 日志中避免完整打印规则正文（最多打印长度和哈希）。
|
||
3. 后端注入时必须确保平台安全策略优先级更高。
|
||
|
||
## 11. 验收标准（UAT）
|
||
|
||
1. 用户保存规则后，本地存在 `personal-rules.md` 且内容一致。
|
||
2. 开启规则发送消息时，请求中可观测到 `personalRules` 字段。
|
||
3. 关闭规则发送消息时，请求中不含该字段或为空。
|
||
4. 规则文件损坏/读取失败时，不影响正常聊天。
|
||
5. 超过长度上限时，前端保存被拒绝且提示明确。
|
||
6. 后端日志可确认“本次是否注入个人规则”。
|
||
|
||
## 12. 迭代建议（下一阶段）
|
||
|
||
1. 规则模板（代码风格、语言风格、测试偏好）。
|
||
2. 项目规则与个人规则合并策略。
|
||
3. 云端同步（按 `userId`），多端一致。
|