weflow-cli 1.8.2 → 1.10.0

package/src/services/assistantScenes.ts

@@ -0,0 +1,342 @@
+/**
+ * 场景（Scenes）—— 按会话生效的提示词预设。
+ *
+ * 一个场景 = 名称 + 关键词 + 附加指令 + 输出规范 + 所需技能。消息进来时按三档挑一个：
+ * **绑定 → 关键词 → 上次用过的**，都没有就不加场景段（默认行为一字不变）。
+ *
+ * 为什么单独一个文件、不塞进配置键、也不塞进记忆文件：
+ * - 配置键是字符串，多字段结构化内容塞进去就等于让用户手写 JSON；
+ * - 记忆文件会被 `compressIfNeeded`/`extractFactsIfNeeded` 用 LLM 改写，还有 `quarantine()`
+ *   把整个文件搬走的路径 —— **用户手写的场景不该走那条路**（被模型改写或被隔离都不像话）。
+ *
+ * 存取纪律照抄记忆文件：版本号 + 未知版本**留档不猜** + `writeFileAtomic` + 只回写脏数据 +
+ * `loadIssue`/`saveIssue` 不抛但必记。
+ *
+ * **场景不给模型碰**：没有任何模型可调的工具能改场景。配置类的东西只能用户显式改
+ * （同 `隐私` 那条注释的立场）。所以这个类只有 CLI 和内置指令两个调用方。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { writeFileAtomic } from '../utils/atomicWrite.js'
+import { frameLocalData } from './assistantMemory.js'
+import { renderSkillRefs, referencedSkillIds, describeSkill } from './assistantSkills.js'
+
+export const SCENES_FORMAT_VERSION = 1
+const SCENES_FILE = join(homedir(), '.weflow-cli', 'assistant_scenes.json')
+
+/** 保留字：`场景 无` 用来解绑，所以不能拿它当 id */
+export const SCENE_RESERVED_IDS = ['无', 'none', 'off']
+
+export interface Scene {
+  id: string
+  name: string
+  /** 消息里出现任一个就命中（不区分大小写） */
+  keywords: string[]
+  /** 附加指令，可以写 `{{skill:<id>}}` */
+  instruction: string
+  /** 输出规范（可选） */
+  outputSpec: string
+  /** 需要的技能 id —— 与指令里的行内引用取并集 */
+  skills: string[]
+  enabled: boolean
+}
+
+export type MatchHow = 'binding' | 'keyword' | 'lastUsed'
+export interface SceneMatch { scene: Scene; how: MatchHow }
+
+interface ScenesFile {
+  version: number
+  scenes: Scene[]
+  /** 会话（userId）→ 场景 id。微信那条路上 userId 就是 conversationId */
+  bindings: Record<string, string>
+  /** 每个会话上一次实际用了哪个场景（没绑定时的兜底） */
+  lastUsed: Record<string, string>
+}
+
+function normalizeScene(raw: any): Scene | null {
+  if (!raw || typeof raw !== 'object') return null
+  const id = String(raw.id || '').trim()
+  if (!id) return null
+  const asList = (v: any): string[] => Array.isArray(v)
+    ? v.map((x: any) => String(x || '').trim()).filter(Boolean)
+    : []
+  return {
+    id,
+    name: String(raw.name || id).trim() || id,
+    keywords: asList(raw.keywords),
+    instruction: typeof raw.instruction === 'string' ? raw.instruction : '',
+    outputSpec: typeof raw.outputSpec === 'string' ? raw.outputSpec : '',
+    skills: asList(raw.skills),
+    // 缺省是"开"。只有显式 false 才算关（老数据没有这个字段）
+    enabled: raw.enabled === undefined ? true : raw.enabled !== false,
+  }
+}
+
+/**
+ * id 规则：**允许中文**（这是给中文用户用的，`场景 日报` 比 `场景 daily-report` 自然得多），
+ * 但禁掉空白、路径分隔符、以及引号和尖括号。
+ *
+ * 引号尖括号不是洁癖：id 会出现在 `frameLocalData('scene.<id>', …)` 的
+ * `source="…"` 属性里（见 `assistantMemory.frameLocalData`，它只转义**正文**里的框标签，
+ * 不转义标签），带 `"` 的 id 能把属性闭合掉。这里挡住，`safeSceneLabel` 再兜一层。
+ */
+const SCENE_ID_BANNED = /[\s/\\:*?"'<>|]/
+
+export function validateSceneId(id: string): string | null {
+  const v = String(id || '').trim()
+  if (!v) return '场景 id 不能为空'
+  if (v.length > 40) return '场景 id 太长（40 字以内）'
+  if (SCENE_ID_BANNED.test(v)) return '场景 id 不能含空白、路径分隔符、引号或尖括号'
+  if (v.startsWith('.')) return '场景 id 不能以点开头'
+  if (SCENE_RESERVED_IDS.includes(v.toLowerCase())) return `「${v}」是保留字（用来解绑），换一个 id`
+  return null
+}
+
+/** 把 id 放进提示词标签前再洗一遍（纵深防御：校验是一道，这里是第二道） */
+function safeSceneLabel(id: string): string {
+  return String(id || '').replace(/[^0-9A-Za-z\u0080-￿._-]/g, '_').slice(0, 40)
+}
+
+export class AssistantScenes {
+  private scenes: Scene[] = []
+  private bindings: Record<string, string> = {}
+  private lastUsed: Record<string, string> = {}
+  private dirty = false
+  private loadIssue = ''
+  private saveIssue: string | null = null
+
+  constructor() { this.load() }
+
+  get problem(): string { return this.loadIssue }
+  get lastSaveError(): string | null { return this.saveIssue }
+
+  /** 把读不出来的文件改名留档——用户手写的场景，**不许静默丢弃** */
+  private quarantine(reason: string): void {
+    const target = `${SCENES_FILE}.unreadable-${new Date().toISOString().replace(/[:.]/g, '-')}`
+    try {
+      renameSync(SCENES_FILE, target)
+      this.loadIssue = `${reason}；原文件已留档为 ${target.split(/[\\/]/).pop()}`
+    } catch (error: any) {
+      this.loadIssue = `${reason}；留档也失败了（${error?.message ?? error}），未改动原文件`
+    }
+    this.scenes = []
+    this.bindings = {}
+    this.lastUsed = {}
+  }
+
+  private load(): void {
+    if (!existsSync(SCENES_FILE)) return
+    let raw: any
+    try {
+      raw = JSON.parse(readFileSync(SCENES_FILE, 'utf8'))
+    } catch (error: any) {
+      this.quarantine(`场景文件无法解析（${error?.message?.slice(0, 80) ?? error}）`)
+      return
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      this.quarantine('场景文件不是一个对象')
+      return
+    }
+    if (raw.version !== SCENES_FORMAT_VERSION) {
+      // 不猜、不迁移（记忆文件同款纪律）
+      this.quarantine(`场景文件版本是 ${JSON.stringify(raw.version)}，本程序只认 ${SCENES_FORMAT_VERSION}`)
+      return
+    }
+    const list = Array.isArray(raw.scenes) ? raw.scenes : []
+    const seen = new Set<string>()
+    for (const item of list) {
+      const scene = normalizeScene(item)
+      if (!scene) continue
+      if (seen.has(scene.id)) continue   // 文件被手改出重复 id：留第一个，不崩
+      seen.add(scene.id)
+      this.scenes.push(scene)
+    }
+    const asMap = (v: any): Record<string, string> => {
+      if (!v || typeof v !== 'object' || Array.isArray(v)) return {}
+      const out: Record<string, string> = {}
+      for (const [k, val] of Object.entries<any>(v)) {
+        const s = String(val || '').trim()
+        if (s) out[k] = s
+      }
+      return out
+    }
+    this.bindings = asMap(raw.bindings)
+    this.lastUsed = asMap(raw.lastUsed)
+  }
+
+  save(): void {
+    try {
+      const dir = join(homedir(), '.weflow-cli')
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+      const payload: ScenesFile = {
+        version: SCENES_FORMAT_VERSION,
+        scenes: this.scenes,
+        bindings: this.bindings,
+        lastUsed: this.lastUsed,
+      }
+      writeFileAtomic(SCENES_FILE, JSON.stringify(payload, null, 1))
+      this.dirty = false
+      this.saveIssue = null
+    } catch (error: any) {
+      // 不抛：磁盘打嗝不该让一次 CLI 操作炸掉。但也不吭声就不对了 —— 用户以为自己加上了。
+      this.saveIssue = String(error?.message ?? error).slice(0, 120)
+    }
+  }
+
+  // ---------- 读 ----------
+
+  list(): Scene[] { return [...this.scenes] }
+  get(id: string): Scene | undefined { return this.scenes.find(s => s.id === id) }
+  binding(userId: string): string { return this.bindings[userId] || '' }
+  lastUsedFor(userId: string): string { return this.lastUsed[userId] || '' }
+
+  // ---------- 写（都只改内存，由调用方决定何时 save） ----------
+
+  add(scene: Scene): { ok: boolean; reason?: string } {
+    const idError = validateSceneId(scene.id)
+    if (idError) return { ok: false, reason: idError }
+    if (this.get(scene.id)) return { ok: false, reason: `场景「${scene.id}」已经存在（要改就先 remove）` }
+    this.scenes.push({ ...scene, name: scene.name || scene.id, enabled: scene.enabled !== false })
+    this.dirty = true
+    return { ok: true }
+  }
+
+  remove(id: string): boolean {
+    const before = this.scenes.length
+    this.scenes = this.scenes.filter(s => s.id !== id)
+    if (this.scenes.length === before) return false
+    // 顺手清理指向它的绑定/上次记录，免得留下一堆悬空 id
+    for (const [uid, sid] of Object.entries(this.bindings)) if (sid === id) delete this.bindings[uid]
+    for (const [uid, sid] of Object.entries(this.lastUsed)) if (sid === id) delete this.lastUsed[uid]
+    this.dirty = true
+    return true
+  }
+
+  setEnabled(id: string, on: boolean): boolean {
+    const scene = this.get(id)
+    if (!scene) return false
+    scene.enabled = on
+    this.dirty = true
+    return true
+  }
+
+  bind(userId: string, sceneId: string | null): { ok: boolean; reason?: string } {
+    if (sceneId === null) {
+      delete this.bindings[userId]
+      this.dirty = true
+      return { ok: true }
+    }
+    const scene = this.get(sceneId)
+    if (!scene) return { ok: false, reason: `没有场景「${sceneId}」` }
+    if (!scene.enabled) return { ok: false, reason: `场景「${sceneId}」已被停用，先启用再绑` }
+    this.bindings[userId] = sceneId
+    this.dirty = true
+    return { ok: true }
+  }
+
+  noteUsed(userId: string, sceneId: string): void {
+    if (this.lastUsed[userId] === sceneId) return
+    this.lastUsed[userId] = sceneId
+    this.dirty = true
+  }
+
+  // ---------- 三档匹配 ----------
+
+  /**
+   * 挑一个场景。**只认唯一**：多个场景命中同样长的关键词时**拒绝**（返回 null + 理由），
+   * 不猜 —— 与本仓 `resolveUniqueTalker`、`resolvePanelUserId` 是同一条纪律。
+   */
+  resolve(userId: string, text: string, opts: { remember?: boolean } = {}): { match: SceneMatch | null; why?: string } {
+    const enabled = this.scenes.filter(s => s.enabled)
+    if (!enabled.length) return { match: null }
+
+    const boundId = this.bindings[userId]
+    if (boundId) {
+      const scene = enabled.find(s => s.id === boundId)
+      if (scene) return this.land(userId, { scene, how: 'binding' }, opts)
+    }
+
+    const hay = String(text || '').toLowerCase()
+    if (hay) {
+      // 每个场景取它**最长**的那个命中关键词；比长度，不比关键词个数
+      const hits: Array<{ scene: Scene; len: number; keyword: string }> = []
+      for (const scene of enabled) {
+        let best: { len: number; keyword: string } | null = null
+        for (const kw of scene.keywords) {
+          const k = kw.toLowerCase()
+          if (!k || !hay.includes(k)) continue
+          if (!best || k.length > best.len) best = { len: k.length, keyword: kw }
+        }
+        if (best) hits.push({ scene, len: best.len, keyword: best.keyword })
+      }
+      if (hits.length) {
+        const top = Math.max(...hits.map(h => h.len))
+        const winners = hits.filter(h => h.len === top)
+        if (winners.length === 1) {
+          return this.land(userId, { scene: winners[0].scene, how: 'keyword' }, opts)
+        }
+        const names = winners.map(w => `「${w.scene.name}」(关键词 ${w.keyword})`).join('、')
+        return { match: null, why: `有 ${winners.length} 个场景同样匹配：${names} —— 这次不带场景（避免猜错），可用「场景 <id>」固定一个` }
+      }
+    }
+
+    const lastId = this.lastUsed[userId]
+    if (lastId) {
+      const scene = enabled.find(s => s.id === lastId)
+      if (scene) return this.land(userId, { scene, how: 'lastUsed' }, opts)
+    }
+    return { match: null }
+  }
+
+  private land(userId: string, match: SceneMatch, opts: { remember?: boolean }): { match: SceneMatch } {
+    if (opts.remember !== false && this.lastUsed[userId] !== match.scene.id) {
+      this.lastUsed[userId] = match.scene.id
+      this.dirty = true
+    }
+    return { match }
+  }
+}
+
+/**
+ * 渲染一个场景成提示词里的一段。整段用 `frameLocalData` 包住 ——
+ * 指令和技能说明都是**本地磁盘上的内容**，可能含 `</weflow-local-data>` 想越狱。
+ */
+export function renderScene(scene: Scene): string {
+  const parts: string[] = []
+  const instruction = renderSkillRefs(scene.instruction)
+  if (instruction.trim()) parts.push(instruction.trim())
+  if (scene.outputSpec.trim()) parts.push(`输出规范：\n${scene.outputSpec.trim()}`)
+  // 显式声明的技能（行内 {{skill:}} 已经在 instruction 里就地渲染过了，这里只补没提到的那些）
+  const declared = referencedSkillIds('', scene.skills)
+  const inline = referencedSkillIds(scene.instruction, [])
+  const rest = declared.filter(id => !inline.includes(id))
+  if (rest.length) {
+    parts.push(['技能要求：', ...rest.map(id => `· ${describeSkill(id).line}`)].join('\n'))
+  }
+  return frameLocalData(`scene.${safeSceneLabel(scene.id)}`, parts.join('\n\n'))
+}
+
+export interface SceneCommand {
+  kind: 'list' | 'bind' | 'unbind'
+  id?: string
+}
+
+/**
+ * 解析 `场景` 指令。**只有后半段真的是已存在的场景 id 才算指令**，
+ * 否则返回 null 交给模型 —— 不然「场景切换怎么用」这种正常问话会被当成命令吃掉。
+ * （现有内置指令都是全等匹配，这里是唯一一条带参数的，所以这条边界要写死。）
+ */
+export function parseSceneCommand(text: string, scenes: AssistantScenes): SceneCommand | null {
+  const t = String(text || '').trim()
+  if (t === '场景') return { kind: 'list' }
+  const m = /^场景[\s:=]+(.+)$/.exec(t)
+  if (!m) return null
+  const arg = m[1].trim().replace(/^[「"']|[」"']$/g, '')
+  if (SCENE_RESERVED_IDS.includes(arg.toLowerCase())) return { kind: 'unbind' }
+  if (!scenes.get(arg)) return null   // 不是真实场景 id → 不当指令
+  return { kind: 'bind', id: arg }
+}
+
+/** 全局单例：CLI 与助手共用一份（同 `configService`/`assistantMemory` 的做法） */
+export const assistantScenes = new AssistantScenes()

package/src/services/assistantService.ts

@@ -22,6 +22,8 @@ import type { StopReason, TurnTrace } from './assistantTrace.js'
 import { appendLog } from './assistantDaemon.js'
 import type { Message, WechatInboundMessage } from '../types.js'
 import { buildEvidenceReviewInput } from './evidenceService.js'
+import { scanSkills, skillCatalogueLines } from './assistantSkills.js'
+import { assistantScenes, parseSceneCommand, renderScene, type Scene } from './assistantScenes.js'
 import { evaluateAssistantAccess } from './assistantRouting.js'
 import { nowLine } from '../utils/dateRange.js'
 import { resolvePanelUserId, PANEL_FALLBACK_BUCKET } from '../panel/userId.js'
@@ -317,14 +319,16 @@ export class AssistantService {
       + '占位符），可以直接引用，不必声称被屏蔽。'
   }
 
-  /** 组装系统提示: 基础人格 + 隐私状态 + L2 摘要 + L3 事实。
+  /** 组装系统提示: 基础人格 + 隐私状态 + 本机能力 + 本会话场景 + L2 摘要 + L3 事实。
    *
-   *  两个纪律：
+   *  三个纪律：
    *  1. **事实按相关度取一部分**，而不是 30 条全塞——无关的那些是噪声，不只是花钱；
-   *  2. 本地数据（摘要、事实）一律**加帧 + 转义框标签**：它们的内容里完全可能写着
-   *     `</weflow-local-data>` 再跟一段像系统指令的话，不转义就等于让数据自己把框关上。
+   *  2. 本地数据（摘要、事实、场景、技能正文）一律**加帧 + 转义框标签**：它们的内容里完全
+   *     可能写着 `</weflow-local-data>` 再跟一段像系统指令的话，不转义就等于让数据自己把框关上；
+   *  3. **本机装了什么技能要说出来**（同「没启用的能力」那条的理由）——不说，用户问到时
+   *     模型会答"我没有这个能力"，而它其实调 `read_skill` 就能拿到。
    */
-  private buildSystemPrompt(userId: string, question = ''): string {
+  private buildSystemPrompt(userId: string, question = '', scene: Scene | null = null): string {
     // 当前时间：**没有它，任何相对时间都是猜**。"上周三""昨天""这周"要变成工具能用的
     // 日期，模型得先知道今天是几号（`get_messages` 的 since/until 就是这么用的）。
     const parts = [BASE_PROMPT, `[当前时间] ${nowLine()}（本机时区）`, this.privacyStateLine()]
@@ -337,6 +341,19 @@ export class AssistantService {
         + SEP + '（这些工具**不在你的工具表里**，但你调不到的原因只是没配置，**不是这个功能不存在**。'
         + '用户问到时直说"这块还没配置"并给出上面那个配置项，**不要说"我没有这个工具"**。）')
     }
+    // 本机装好的技能包。**只列名字/说明/版本，正文按需 read_skill 读** ——
+    // 27 个技能的正文全塞进每轮提示词，既贵又会把真正的问题挤掉。
+    const skillScan = scanSkills()
+    const skillLines = skillCatalogueLines(skillScan)
+    if (skillLines.length) {
+      parts.push('[本机已安装的技能]' + SEP + skillLines.join(SEP)
+        + SEP + '（技能是一份说明文档。要用某个技能，先用 `read_skill` 读它的正文再照着做；'
+        + '**不要凭名字猜它怎么用**。）')
+    }
+    const sceneLines = scene ? renderScene(scene) : ''
+    if (sceneLines) {
+      parts.push('[本会话的场景]' + SEP + `场景「${scene!.name}」已生效，按它的要求来做。` + SEP + sceneLines)
+    }
     const summary = this.memory.summary(userId)
     if (summary) {
       parts.push('[此前对话摘要]' + SEP + frameLocalData('memory.summary', summary))
@@ -359,6 +376,16 @@ export class AssistantService {
   private lastReasoning = ''
   /** 每个用户最近一轮的轨迹：微信里发「轨迹」看的就是它（跨进程的历史在文件里，见 assistantTrace） */
   private traces = new Map<string, TurnTrace>()
+
+  /**
+   * 最近一轮的轨迹，给**本机面板**用（`/api/ask` 回答完之后，面板把"思考过程"折叠着挂上去）。
+   *
+   * 与微信里那条「轨迹」是**同一个来源**（`this.traces`），所以两处不会各说各话。
+   * 只在本进程内存里：跨进程的历史在 `assistantTrace` 的文件里，面板要的是"刚刚那一轮"。
+   */
+  recentTrace(userId: string): TurnTrace | undefined {
+    return this.traces.get(userId)
+  }
   /**
    * 本轮已经调过的「工具名 + 参数」。同一条消息里重复调用**同样的参数**不会得到新信息，
    * 而实测（评测的 ambiguous-contact 用例）模型会连着调三次 list_sessions。
@@ -645,10 +672,52 @@ export class AssistantService {
       return lines.join('\n')
     }
 
+    // 场景：**命令要认，但只认真的存在的东西**。`parseSceneCommand` 只在后半段是已存在的
+    // 场景 id 时才当指令，所以「场景切换怎么用」这种问话不会被吃掉（见那边的注释）。
+    // 位置在内置指令之后、ReAct 之前：场景是这一轮的上下文，不是要模型去执行的任务。
+    const sceneCmd = parseSceneCommand(t, assistantScenes)
+    if (sceneCmd) {
+      if (sceneCmd.kind === 'list') {
+        const scenes = assistantScenes.list()
+        if (!scenes.length) {
+          return finish('还没有任何场景。用电脑加一个：\n'
+            + 'weflow-cli scene add --id 日报 --keywords 日报,今天推文 --instruction "按主题分组" --dry-run', 'builtin')
+        }
+        const active = assistantScenes.binding(userId)
+        const lines = scenes.map(s => `${s.id === active ? '▶ ' : '  '}${s.id}（${s.name}）${s.enabled ? '' : '[已停用]'}`
+          + (s.keywords.length ? ` 关键词：${s.keywords.join('、')}` : ''))
+        lines.push('', `本会话当前：${active ? `绑定「${active}」` : '未绑定（按关键词或上次用过的挑）'}`)
+        lines.push('绑定：场景 <id>　解绑：场景 无')
+        return finish(lines.join(String.fromCharCode(10)), 'builtin')
+      }
+      if (sceneCmd.kind === 'unbind') {
+        assistantScenes.bind(userId, null)
+        assistantScenes.save()
+        return finish('✓ 已解绑，这个会话回到按关键词自动挑', 'builtin')
+      }
+      const bound = assistantScenes.bind(userId, sceneCmd.id as string)
+      if (!bound.ok) return finish(`✗ ${bound.reason}`, 'builtin')
+      assistantScenes.save()
+      const scene = assistantScenes.get(sceneCmd.id as string)
+      return finish(`✓ 已给这个会话绑定场景「${scene?.name ?? sceneCmd.id}」。之后每轮都按它来做，发「场景 无」解绑。`, 'builtin')
+    }
+
     // === ReAct 主循环 ===
     this.memory.addTurn(userId, 'user', t)
+    // 挑场景：绑定 → 关键词 → 上次用过的（都不中就不加场景段，默认行为一字不变）
+    const picked = assistantScenes.resolve(userId, t)
+    const scene = picked.match?.scene ?? null
+    if (picked.match) {
+      trace.steps.push({ kind: 'note', detail: `场景「${picked.match.scene.name}」· 命中：`
+        + ({ binding: '绑定', keyword: '关键词', lastUsed: '上次用过的' }[picked.match.how]) })
+      // 命中了就记一笔"上次用它"（写盘失败不抛，见 AssistantScenes.save）
+      if (assistantScenes.lastUsedFor(userId) !== picked.match.scene.id) assistantScenes.save()
+    } else if (picked.why) {
+      // **多义要留痕**：不然用户只看到"这次没带场景"，不知道是因为撞车了
+      trace.steps.push({ kind: 'note', detail: picked.why })
+    }
     const messages: ApiMessage[] = [
-      { role: 'system', content: this.buildSystemPrompt(userId, t) },
+      { role: 'system', content: this.buildSystemPrompt(userId, t, scene) },
       ...this.memory.workingWindow(userId).map(turn => ({ role: turn.role, content: turn.content })),
     ]
 
@@ -801,6 +870,12 @@ export class AssistantService {
       privacyGate.audit('MEMORY_LOAD_ISSUE', 0, this.memory.problem.slice(0, 80))
       onLog?.(`⚠ 记忆: ${this.memory.problem}`)
     }
+    // 场景文件同理：读不出来时用户面对的是"我加过的场景全没了"，而原因在被留档的文件名里
+    if (assistantScenes.problem) {
+      appendLog(`[场景] ${assistantScenes.problem}`)
+      privacyGate.audit('SCENES_LOAD_ISSUE', 0, assistantScenes.problem.slice(0, 80))
+      onLog?.(`⚠ 场景: ${assistantScenes.problem}`)
+    }
     const { local } = this.engineConfig()
     // bot 那一段只在真有通道时报：没有通道还报一个 bot 账号，是让人以为它在收消息
     onLog?.('助手已启动 (' + (token ? `bot: ${configService.get('wechatOcAccountId')}, ` : '本机入口模式, ') +
@@ -880,6 +955,32 @@ export class AssistantService {
     return { used: this.dailyCount, limit: DAILY_LIMIT }
   }
 
+  /**
+   * 面板里那个"记忆"按钮要的：**它记住了什么**。只读，且**不经过模型**。
+   *
+   * 为什么不复用微信里那条 `记忆` 指令的文本：聊天那条路给的是"最近 5 条"的摘要（那是给对话用的），
+   * 面板要按时间列全、还要看得出每条是从哪句话来的，所以带上 `sourceQuote`。两边读的是同一份 memory，
+   * 只是呈现不同 —— 不各存一份。
+   *
+   * 桶（`userId`）由**调用方**决定：面板那条路传的是服务端自己那个 `memoryBucket`，不接受客户端指定。
+   */
+  memorySnapshot(userId: string): {
+    facts: { content: string; ts: number; sourceQuote: string }[]
+    summary: string
+    workingTurns: number
+    saveError: string
+  } {
+    return {
+      facts: this.memory.facts(userId).map(f => ({
+        content: f.content, ts: f.ts, sourceQuote: f.sourceQuote ?? '',
+      })),
+      summary: this.memory.summary(userId),
+      workingTurns: this.memory.workingWindow(userId).length,
+      // 落盘失败要传出去：用户问"你记住了什么"时，若上次根本没存上，那份答案就是假的
+      saveError: this.memory.lastSaveError ?? '',
+    }
+  }
+
   stop(): void {
     this.running = false
     this.svc?.stop()