228 lines
7.1 KiB
Markdown
228 lines
7.1 KiB
Markdown
|
# 自动化记忆任务设计方案（v1）
|
|||
|
|
|
|||
|
|
## 1. 背景与目标
|
|||
|
|
|
|||
|
|
本方案用于落地后端自动化记忆任务：
|
|||
|
|
|
|||
|
|
- 提供每日/每周自动执行能力；
|
|||
|
|
- 自动提取用户近期对话中的可沉淀记忆并写入 `memories`；
|
|||
|
|
- 支持“忘记”操作；
|
|||
|
|
- 复用现有 Agent 运行链路，避免并行维护两套运行时；
|
|||
|
|
- 保证可审计、可追溯，同时对用户界面隐藏自动输入提示词。
|
|||
|
|
|
|||
|
|
## 2. 范围与非目标
|
|||
|
|
|
|||
|
|
### 2.1 范围
|
|||
|
|
|
|||
|
|
- `automation_jobs` 增加 `config`（JSONB，强约束）；
|
|||
|
|
- 调度器执行 `automation_jobs`，按用户本地时区计算执行时间；
|
|||
|
|
- 自动任务复用现有 `router -> agent` 运行策略；
|
|||
|
|
- 自动输入落库但对用户不可见；
|
|||
|
|
- 工具集按任务配置分发，仅允许白名单工具；
|
|||
|
|
- 正式启用 `memory_prompt`，将 `memories` 注入系统提示词。
|
|||
|
|
|
|||
|
|
### 2.2 非目标
|
|||
|
|
|
|||
|
|
- 不开放复杂 DSL 编排；
|
|||
|
|
- 不开放细粒度策略配置（如 `execution_profile/history_window_days/memory_policy`）；
|
|||
|
|
- 不引入第二套独立 Agent 运行框架。
|
|||
|
|
|
|||
|
|
## 3. 关键决策
|
|||
|
|
|
|||
|
|
1. **调度与执行分离**
|
|||
|
|
- `run_at/next_run_at/timezone` 负责“何时执行”；
|
|||
|
|
- `config` 负责“如何执行”（提示词与工具集）。
|
|||
|
|
|
|||
|
|
2. **配置最小化**
|
|||
|
|
- `automation_jobs.config` 仅保留：
|
|||
|
|
- `prompt: string`
|
|||
|
|
- `tools: string[]`
|
|||
|
|
|
|||
|
|
3. **自动输入可审计但用户不可见**
|
|||
|
|
- 自动任务提示词作为“用户消息”写入 `messages`；
|
|||
|
|
- 在 metadata 加可见性标记并在用户历史接口中默认过滤；
|
|||
|
|
- 审计路径可查询完整消息链路。
|
|||
|
|
|
|||
|
|
4. **时区策略**
|
|||
|
|
- 调度语义采用“用户本地时区 10:00”；
|
|||
|
|
- 存储执行时间统一为 UTC 的 `next_run_at`；
|
|||
|
|
- 调度器仅按 UTC 扫描，降低运维复杂度。
|
|||
|
|
|
|||
|
|
## 4. 数据模型设计
|
|||
|
|
|
|||
|
|
## 4.1 `automation_jobs` 调整
|
|||
|
|
|
|||
|
|
- 保留字段：`id`, `owner_id`, `title`, `schedule_type`, `run_at`, `next_run_at`, `timezone`, `last_run_at`, `status` 等；
|
|||
|
|
- 新增字段：`config JSONB NOT NULL`；
|
|||
|
|
- 迁移策略：
|
|||
|
|
- 将历史 `prompt` 迁移到 `config.prompt`；
|
|||
|
|
- 切换业务代码后删除旧 `prompt` 字段（可分两步灰度）。
|
|||
|
|
|
|||
|
|
### 4.2 `config` 强约束 schema
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"prompt": "提取最近对话中的稳定记忆并写入",
|
|||
|
|
"tools": ["memory_write", "memory_forget"]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
约束要求：
|
|||
|
|
|
|||
|
|
- `prompt`：必填、非空、长度受限（建议 <= 2000）；
|
|||
|
|
- `tools`：必填数组，元素为注册工具名；
|
|||
|
|
- `extra="forbid"`，拒绝未知字段；
|
|||
|
|
- 执行前二次校验：`tools` 必须与后端 allowlist 取交集，禁止越权。
|
|||
|
|
|
|||
|
|
### 4.3 `messages.metadata` 扩展
|
|||
|
|
|
|||
|
|
新增建议字段：
|
|||
|
|
|
|||
|
|
- `hidden_from_user: bool`
|
|||
|
|
- `origin: "chat" | "automation"`
|
|||
|
|
|
|||
|
|
用途：
|
|||
|
|
|
|||
|
|
- `hidden_from_user=true` 的消息在用户历史默认不可见；
|
|||
|
|
- 审计查询可读取全量。
|
|||
|
|
|
|||
|
|
## 5. 运行时架构
|
|||
|
|
|
|||
|
|
## 5.1 复用现有 Agent 链路
|
|||
|
|
|
|||
|
|
自动任务不新建运行时，沿用现有 `router -> orchestrator -> worker` 流程：
|
|||
|
|
|
|||
|
|
- 输入：来自 `automation_jobs.config.prompt` 的合成“用户输入”；
|
|||
|
|
- 上下文：默认加载“今天 + 昨天”历史；
|
|||
|
|
- 工具：仅启用 `config.tools` 且通过 allowlist 校验。
|
|||
|
|
|
|||
|
|
## 5.2 会话与消息策略
|
|||
|
|
|
|||
|
|
- 自动任务写入独立 `session_type=automation` 会话，并关联 `job_id`；
|
|||
|
|
- 普通对话维持 `session_type=chat`；
|
|||
|
|
- 自动输入消息：`role=user` 但 `hidden_from_user=true`；
|
|||
|
|
- Assistant 输出消息：默认可见。
|
|||
|
|
|
|||
|
|
## 6. 调度器设计
|
|||
|
|
|
|||
|
|
## 6.1 扫描与触发
|
|||
|
|
|
|||
|
|
- 周期扫描条件：
|
|||
|
|
- `status='active'`
|
|||
|
|
- `next_run_at <= now_utc`
|
|||
|
|
- 命中后入队执行命令（复用现有任务队列）。
|
|||
|
|
|
|||
|
|
## 6.2 幂等与并发控制
|
|||
|
|
|
|||
|
|
- 使用任务槽位去重键：`job_id + scheduled_slot`；
|
|||
|
|
- 使用行级抢占或原子更新防止并发重复执行；
|
|||
|
|
- 失败可重试并记录错误上下文。
|
|||
|
|
|
|||
|
|
## 6.3 下次执行时间计算
|
|||
|
|
|
|||
|
|
- 每次执行完成后按 `schedule_type + timezone` 计算下一次触发时间；
|
|||
|
|
- 保存到 `next_run_at`（UTC）；
|
|||
|
|
- `last_run_at` 记录实际执行时间。
|
|||
|
|
|
|||
|
|
## 7. 默认任务创建
|
|||
|
|
|
|||
|
|
用户创建后自动创建一条默认 daily 记忆任务：
|
|||
|
|
|
|||
|
|
- `schedule_type = 'daily'`
|
|||
|
|
- 本地时区目标时间：10:00
|
|||
|
|
- `timezone`：优先用户设置时区，缺省 `Asia/Shanghai`
|
|||
|
|
- `config.prompt`：内置记忆提取提示词模板
|
|||
|
|
- `config.tools = ["memory_write", "memory_forget"]`
|
|||
|
|
|
|||
|
|
## 8. 记忆工具设计
|
|||
|
|
|
|||
|
|
## 8.1 `memory_write`
|
|||
|
|
|
|||
|
|
- 用途：写入/更新用户记忆；
|
|||
|
|
- 输入：受 schema 限制（标题、内容、来源等）；
|
|||
|
|
- 安全：owner 作用域强制绑定，不信任模型输入的 owner 信息。
|
|||
|
|
|
|||
|
|
## 8.2 `memory_forget`
|
|||
|
|
|
|||
|
|
- 用途：失效或删除用户记忆；
|
|||
|
|
- 输入：`memory_id` 或受限条件；
|
|||
|
|
- 安全：仅允许当前 owner 范围内操作。
|
|||
|
|
|
|||
|
|
## 8.3 工具授权
|
|||
|
|
|
|||
|
|
- 任务声明工具集来自 `config.tools`；
|
|||
|
|
- 运行时执行 `declared_tools ∩ allowlist`；
|
|||
|
|
- 非白名单工具直接拒绝并记录审计日志。
|
|||
|
|
|
|||
|
|
## 9. `memory_prompt` 启用策略
|
|||
|
|
|
|||
|
|
- 从数据库读取当前用户可用 `memories`；
|
|||
|
|
- 组装为系统提示词 memory section；
|
|||
|
|
- 设置条数与长度上限，避免 token 膨胀；
|
|||
|
|
- 自动任务与普通对话统一使用该注入机制。
|
|||
|
|
|
|||
|
|
## 10. 前端展示策略
|
|||
|
|
|
|||
|
|
- 历史消息接口默认过滤 `hidden_from_user=true`；
|
|||
|
|
- 用户仅看到 assistant 输出（以及可选系统摘要，不包含原始自动 prompt）；
|
|||
|
|
- 前端无需大量工具分支 if/else，可统一按 metadata 标记处理。
|
|||
|
|
|
|||
|
|
## 11. 安全与审计
|
|||
|
|
|
|||
|
|
- 关键要求：
|
|||
|
|
- 禁止越权工具调用；
|
|||
|
|
- 禁止跨用户 memory 读写；
|
|||
|
|
- 日志不输出敏感数据和完整私密上下文。
|
|||
|
|
- 审计能力：
|
|||
|
|
- 自动输入、工具调用、输出全链路可追踪；
|
|||
|
|
- 用户界面只显示允许可见内容。
|
|||
|
|
|
|||
|
|
## 12. 迁移与发布步骤
|
|||
|
|
|
|||
|
|
1. 新增 `config` 字段与 schema 代码；
|
|||
|
|
2. 数据迁移：旧 `prompt -> config.prompt`；
|
|||
|
|
3. 运行时切换到 `config.prompt/config.tools`；
|
|||
|
|
4. 灰度验证后移除旧 `prompt`；
|
|||
|
|
5. 上线调度器与默认任务创建；
|
|||
|
|
6. 启用 `memory_prompt` 并完成联调。
|
|||
|
|
|
|||
|
|
## 13. 测试与验收
|
|||
|
|
|
|||
|
|
### 13.1 单元测试
|
|||
|
|
|
|||
|
|
- `config` schema 校验（非法字段、非法工具、空 prompt）；
|
|||
|
|
- `next_run_at` 计算（跨时区、边界时间）；
|
|||
|
|
- 隐藏消息过滤逻辑；
|
|||
|
|
- `memory_write/memory_forget` owner 边界。
|
|||
|
|
|
|||
|
|
### 13.2 集成测试
|
|||
|
|
|
|||
|
|
- 用户创建触发默认 daily 任务创建；
|
|||
|
|
- 调度触发 -> Agent 执行 -> memory 写入 -> `next_run_at` 更新；
|
|||
|
|
- 自动输入在审计可见、在用户历史不可见。
|
|||
|
|
|
|||
|
|
### 13.3 验收标准
|
|||
|
|
|
|||
|
|
- 每日 10:00（用户本地时区）稳定执行；
|
|||
|
|
- 自动化链路有完整审计；
|
|||
|
|
- 工具授权边界有效；
|
|||
|
|
- 前端历史展示符合“隐藏自动输入、展示输出”的预期。
|
|||
|
|
|
|||
|
|
## 14. 实施顺序建议
|
|||
|
|
|
|||
|
|
1. 先更新协议文档（`docs/protocols`）明确契约；
|
|||
|
|
2. 数据库与 schema 改造（`automation_jobs.config`）；
|
|||
|
|
3. 工具集与授权边界实现；
|
|||
|
|
4. 调度器与默认任务创建；
|
|||
|
|
5. `memory_prompt` 注入与端到端验证；
|
|||
|
|
6. 前端过滤逻辑收口。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
本方案是最小可行版本（MVP）设计，重点保障：
|
|||
|
|
|
|||
|
|
- 复用现有架构；
|
|||
|
|
- 低配置复杂度；
|
|||
|
|
- 可审计与可维护并存；
|
|||
|
|
- 为后续扩展保留演进空间。
|