# 自动化记忆任务设计方案（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）设计，重点保障：

- 复用现有架构；
- 低配置复杂度；
- 可审计与可维护并存；
- 为后续扩展保留演进空间。