From 4312b248a7d7dc2ac79e80b8738c2551bf260712 Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Wed, 1 Apr 2026 03:32:27 +0800
Subject: [PATCH] docs: add master-agent prompts and memory design

---
 ...-master-agent-prompts-and-memory-design.md | 440 ++++++++++++++++++
 1 file changed, 440 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-04-01-master-agent-prompts-and-memory-design.md

diff --git a/docs/superpowers/specs/2026-04-01-master-agent-prompts-and-memory-design.md b/docs/superpowers/specs/2026-04-01-master-agent-prompts-and-memory-design.md
new file mode 100644
index 0000000..19c58f4
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-01-master-agent-prompts-and-memory-design.md
@@ -0,0 +1,440 @@
+# 主 Agent 提示词与记忆分层设计
+
+## 背景
+
+当前 `master-agent` 会话已经具备这些能力：
+
+- 真实对话链路：`APP / Web -> boss-web -> master-agent -> local-agent / OpenAI API -> 回写账本`
+- 当前对话模型选择
+- 当前对话推理强度选择
+- 微信式右上角三点菜单
+
+但还有两个关键能力缺失：
+
+1. 主 Agent 没有一套显式可管理的提示词体系
+2. 主 Agent 没有一套可见、可编辑、可沉淀的记忆体系
+
+在当前产品形态下，这两个能力不能再停留在“代码里写死一段 prompt”或“隐性记忆”的阶段。因为实际使用中已经出现两类长期信息：
+
+- 系统级规则和风格约束
+- 用户在大量对话、长期研发、项目推进过程中沉淀下来的偏好、进度、阻塞、结论
+
+同时，项目是多租户结构：
+
+- 管理员需要定义系统级主 Agent 规则
+- 每个用户又需要维护自己私有的长期上下文
+- 单个当前会话还可能需要额外临时约束
+
+## 目标
+
+1. 为主 Agent 建立分层提示词体系
+2. 为主 Agent 建立用户级记忆体系，并支持自动沉淀
+3. 在主 Agent 聊天页右上角三点菜单中增加：
+   - `提示词`
+   - `记忆`
+4. 支持在前台对记忆进行：
+   - 新增
+   - 编辑
+   - 删除
+5. 支持在前台对提示词进行：
+   - 查看管理员全局主提示词（只读）
+   - 编辑用户私有主提示词
+   - 编辑当前对话附加提示词
+6. 主 Agent 每次执行时，真实使用这些提示词和记忆，而不是只存不读
+
+## 非目标
+
+- 本轮不做向量数据库
+- 本轮不做复杂语义聚类
+- 本轮不做管理员全局记忆
+- 本轮不做提示词版本对比和历史回滚
+- 本轮不把提示词/记忆扩展到普通线程会话
+
+## 设计总览
+
+### 1. 提示词分层
+
+主 Agent 提示词分三层：
+
+1. `管理员全局主提示词`
+2. `用户私有主提示词`
+3. `当前对话附加提示词`
+
+这三层不是互相覆盖，而是固定顺序叠加：
+
+```text
+管理员全局主提示词
++ 用户私有主提示词
++ 当前对话附加提示词
+```
+
+约束如下：
+
+- 管理员全局主提示词：
+  - 由管理员在 Web 后台配置
+  - 全局唯一
+  - 所有主 Agent 对话都会继承
+  - 不可被用户层和对话层覆盖
+- 用户私有主提示词：
+  - 每个用户独立维护
+  - 用来表达长期偏好、表达方式、工作方式
+- 当前对话附加提示词：
+  - 只作用于当前 `master-agent` 会话
+  - 用来表达本轮对话的临时约束和上下文
+
+### 2. 记忆分层
+
+记忆只保留用户层，不做管理员全局记忆。
+
+但用户记忆再分两类：
+
+1. `用户通用记忆`
+2. `项目记忆`
+
+#### 2.1 用户通用记忆
+
+适合保存：
+
+- 用户长期偏好
+- 常用语言/表达要求
+- 长期研究方向
+- 长期稳定的工作约束
+
+例如：
+
+- 用户偏好微信式交互
+- 用户偏好中文直接回复
+- 用户倾向先打通主链再做 UI 精修
+
+#### 2.2 项目记忆
+
+默认绑定到具体 `projectId`。
+
+适合保存：
+
+- 项目目标变化
+- 决策结论
+- 阻塞点
+- 风险
+- 重要进度结论
+- 关键线程/设备职责
+
+例如：
+
+- `boss` 项目服务器固定是 `106.53.170.158`
+- `wenshenapp` 当前真实线程导入规则已切到项目聚合 + 线程下钻
+- 某个设备上的某个线程负责某类任务
+
+### 3. 前台呈现方式
+
+前台不直接暴露复杂结构，而是保持轻量卡片式体验：
+
+- 提示词页：按分层 section 展示
+- 记忆页：按列表卡片展示
+
+但底层必须是结构化存储，以支撑未来的大量记忆沉淀、检索、过滤和去重。
+
+## 数据模型
+
+### 1. 管理员全局主提示词
+
+建议增加一条系统配置记录，例如：
+
+```ts
+interface MasterAgentPromptPolicy {
+  globalPrompt: string;
+  updatedAt: string;
+  updatedBy?: string;
+}
+```
+
+特点：
+
+- 全局唯一
+- 不跟项目绑定
+- 只允许管理员修改
+
+### 2. 用户私有主提示词
+
+```ts
+interface UserMasterPrompt {
+  account: string;
+  content: string;
+  updatedAt: string;
+}
+```
+
+### 3. 当前对话附加提示词
+
+当前这层建议直接复用 `master-agent` 对话控制思路，挂在 `project` 上：
+
+```ts
+interface ProjectAgentControls {
+  modelOverride?: string;
+  reasoningEffortOverride?: "low" | "medium" | "high";
+  promptOverride?: string;
+  updatedAt: string;
+}
+```
+
+本轮新增：
+
+- `promptOverride`
+
+### 4. 用户记忆
+
+```ts
+type MasterMemoryScope = "global" | "project";
+type MasterMemoryType =
+  | "user_preference"
+  | "project_progress"
+  | "decision"
+  | "risk"
+  | "blocking_issue"
+  | "research_note"
+  | "workflow_rule";
+
+interface MasterAgentMemory {
+  memoryId: string;
+  account: string;
+  scope: MasterMemoryScope;
+  projectId?: string;
+  title: string;
+  content: string;
+  memoryType: MasterMemoryType;
+  tags: string[];
+  sourceMessageId?: string;
+  createdAt: string;
+  updatedAt: string;
+  lastUsedAt?: string;
+  archived: boolean;
+}
+```
+
+## 主 Agent 执行链合成规则
+
+主 Agent 每次真正执行时，统一按下面顺序拼装上下文：
+
+1. 管理员全局主提示词
+2. 用户私有主提示词
+3. 当前对话附加提示词
+4. 当前项目相关的项目记忆
+5. 用户通用记忆
+6. 当前运行时上下文
+7. 当前消息
+
+### 记忆筛选原则
+
+不是把所有记忆都塞进去，而是按相关性选一批：
+
+- 当前项目命中的项目记忆优先
+- 最近使用过的用户通用记忆优先
+- 标签命中的记忆优先
+- 已归档的不参与默认拼装
+
+### 管理员全局主提示词不可覆盖
+
+这条是硬规则：
+
+- 用户私有主提示词只能追加
+- 当前对话附加提示词也只能追加
+- 不允许声明“忽略管理员规则”
+- 不允许用户端删除或修改管理员全局主提示词
+
+## 自动记忆沉淀规则
+
+默认自动沉淀，但不是“所有聊天都入库”。
+
+### 1. 允许自动写入的内容
+
+只有满足“未来仍有使用价值”的信息才进入记忆：
+
+- 对项目推进有持续价值
+- 对用户长期偏好有持续价值
+- 对系统后续调度和回答有稳定帮助
+
+### 2. 自动分类
+
+自动写入时分两类：
+
+- 项目进度、决策、阻塞、风险：
+  - 写为 `project` scope
+- 用户长期偏好、风格、研究方向：
+  - 写为 `global` scope
+
+### 3. 默认不写入的内容
+
+这些内容默认不进入记忆：
+
+- 打招呼
+- 一次性口头确认
+- 临时、马上会过期的状态
+- 未确认的猜测
+- 重复且没有新增信息的催促或抱怨
+- 纯操作性瞬时提示
+
+### 4. 去重与合并
+
+自动沉淀必须带基础去重：
+
+- 如果识别到表达的是同一条长期事实
+- 优先更新已有记忆，而不是新增重复条目
+- 只刷新：
+  - `updatedAt`
+  - `lastUsedAt`
+  - 必要时更新标题/内容
+
+## 前台页面与入口
+
+### 1. 主 Agent 聊天页右上角三点菜单
+
+新增并调整为：
+
+1. `提示词`
+2. `记忆`
+3. `模型`
+4. `推理强度`
+5. `会话信息`
+6. `刷新`
+
+### 2. 提示词页
+
+这是一个新的轻量编辑页。
+
+包含三个 section：
+
+1. `管理员全局主提示词`
+   - 只读
+   - 明确标注“不可覆盖”
+2. `我的主提示词`
+   - 可编辑
+3. `当前对话附加提示词`
+   - 可编辑
+
+页面还需要提供：
+
+- `查看组合结果`
+
+目的是让用户知道当前主 Agent 真正看到的提示词是什么。
+
+### 3. 记忆页
+
+这是一个新的记忆管理页。
+
+分两个 section：
+
+1. `项目记忆`
+2. `我的通用记忆`
+
+每条记忆卡片支持：
+
+- 编辑
+- 删除
+
+页面支持：
+
+- 新增记忆
+
+自动写入后的记忆也会直接出现在这里，而不是只存在后端。
+
+## Web 后台
+
+本轮需要补一个管理员可用的 Web 配置页，用来管理：
+
+- `管理员全局主提示词`
+
+这页只做一件事：
+
+- 编辑和保存全局主提示词
+
+本轮不扩展成复杂控制台，不加入记忆管理，不做多级配置中心。
+
+## API 设计
+
+本轮建议至少新增这些能力：
+
+### 1. 管理员全局主提示词
+
+- `GET /api/v1/master-agent/prompt-policy`
+- `POST /api/v1/master-agent/prompt-policy`
+
+### 2. 用户私有主提示词
+
+- `GET /api/v1/master-agent/user-prompt`
+- `POST /api/v1/master-agent/user-prompt`
+
+### 3. 当前对话附加提示词
+
+沿用现有：
+
+- `GET /api/v1/projects/[projectId]/agent-controls`
+- `POST /api/v1/projects/[projectId]/agent-controls`
+
+本轮在 payload 中加入：
+
+- `promptOverride`
+
+### 4. 用户记忆
+
+- `GET /api/v1/master-agent/memories`
+- `POST /api/v1/master-agent/memories`
+- `POST /api/v1/master-agent/memories/[memoryId]`
+- `DELETE /api/v1/master-agent/memories/[memoryId]`
+
+并支持：
+
+- `scope=global|project`
+- `projectId`
+- `memoryType`
+
+## 验收标准
+
+本轮完成后，至少要满足：
+
+1. 主 Agent 聊天页右上角三点菜单能看到 `提示词` 和 `记忆`
+2. `提示词` 页能：
+   - 查看管理员全局主提示词
+   - 编辑用户私有主提示词
+   - 编辑当前对话附加提示词
+   - 查看最终组合结果
+3. `记忆` 页能：
+   - 查看项目记忆
+   - 查看用户通用记忆
+   - 新增、编辑、删除
+4. 主 Agent 实际执行时会读取：
+   - 管理员全局主提示词
+   - 用户私有主提示词
+   - 当前对话附加提示词
+   - 用户记忆
+5. 自动沉淀出的记忆会真实出现在记忆页
+6. 项目进度类记忆默认挂到 `projectId`
+7. 用户长期偏好类记忆默认挂到用户全局
+8. 管理员全局主提示词不能被用户端覆盖
+
+## 风险与约束
+
+### 1. 记忆膨胀
+
+如果自动沉淀规则太宽，记忆会迅速变脏。  
+因此本轮必须至少带上：
+
+- 自动分类
+- 基础去重
+- 归档能力
+
+### 2. prompt 过长
+
+提示词和记忆叠加后，最终 prompt 不能无限增长。  
+因此本轮虽然先不做复杂向量检索，但必须做最基础的筛选：
+
+- 当前项目优先
+- 最近使用优先
+- 归档排除
+
+### 3. 多租户边界
+
+用户记忆必须严格按用户隔离：
+
+- 用户 A 的记忆不能进入用户 B 的主 Agent
+- 项目记忆也必须同时受 `account + projectId` 约束
+