agentworkshop 0.7.44 → 0.7.47

package/server/services/workshop/runtime/memory/helpers.ts

@@ -0,0 +1,196 @@
+/**
+ * AgentMemory 的模块级纯工具/常量(原 server/services/workshop/runtime/memory.ts 类外声明,含类体之后与类无关的部分)。
+ */
+import type { MemoryRepo } from '../../db/memory.repo'
+import type { MemoryRow } from '../../db/database'
+import type { Part } from '../../types/a2a'
+import type { EmbeddingProvider } from '../embedding-provider'
+import { TEAM_AGENT_ID } from '../../db/memory.repo'
+import { memorySettings } from '../../settings'
+
+export const W_RELEVANCE = 0.5
+export const W_RECENCY = 0.3
+export const W_IMPORTANCE = 0.2
+export const RECENT_FALLBACK = 5
+export const MAX_TERMS = 12
+/** CJK 单字词项上限(单字区分度低,12 个易主题漂移;ascii 词项仍取 MAX_TERMS) */
+export const MAX_CJK_TERMS = 24
+/** FTS 候选池深度(RRF 融合需要比最终引子更深的榜) */
+export const FTS_POOL = 20
+/** Reciprocal Rank Fusion 常数(业界标准 k=60) */
+export const RRF_K = 60
+/** MMR 多样性权重(λ×相关性 − (1−λ)×与已选集的最大相似) */
+export const MMR_LAMBDA = 0.7
+/** 任务关联加权:候选行 taskId ∈ 兄弟/父任务集时终分加成 */
+export const RELATED_TASK_BOOST = 0.3
+/** 策展层 kind(确定性 L0/按 key 直取;不进 L1 排名防双份注入,search_memory 仍可命中) */
+export const CURATED_KINDS = new Set(['brief', 'chronicle', 'reflection'])
+/** kind 感知时近衰减半衰期(天;0 = 不衰减) */
+export const RECENCY_HALF_LIFE_DAYS: Record<string, number> = {
+  'episodic-peer': 3,
+  'episodic-task': 14,
+  'episodic-session': 14,
+  'episodic-team-task': 14,
+  'semantic': 0,
+  'brief': 0,
+  'chronicle': 0,
+  'reflection': 0,
+}
+export const CONTENT_STORE_LIMIT = 800
+
+/** 环境变量安全数值(非有限/非正数 → fallback;防 NaN/0 破坏预算与定时器)。
+ *  @deprecated 配置驱动迁移后仅存量测试使用;新代码读 memorySettings().*
+ */
+export function envNum(name: string, fallback: number): number {
+  const n = Number(process.env[name])
+  return Number.isFinite(n) && n > 0 ? n : fallback
+}
+
+/** memory 组配置(单次解析,进程缓存;env AW_MEMORY_* 经 schema 描述符通用覆盖) */
+export function memoryCfg() {
+  return memorySettings()
+}
+
+export function segmentCJK(text: string): string {
+  return text.replace(/[\u4e00-\u9fff]+/g, run => ` ${run.split('').join(' ')} `)
+}
+
+export function buildMatchQuery(text: string): string | null {
+  const cleaned = text.replace(/["'*().:+-]/g, ' ').toLowerCase()
+  const words = segmentCJK(cleaned).split(/\s+/).filter(Boolean)
+  const cjkTerms: string[] = []
+  const otherTerms: string[] = []
+  for (const t of words) {
+    const isCjk = /[\u4e00-\u9fff]/.test(t)
+    if (!isCjk && (t.length < 2 || ['and', 'or', 'not', 'near'].includes(t))) continue
+    const pool = isCjk ? cjkTerms : otherTerms
+    const cap = isCjk ? MAX_CJK_TERMS : MAX_TERMS
+    if (pool.length >= cap) continue
+    if (!pool.includes(t)) pool.push(t)
+  }
+  const terms = [...otherTerms, ...cjkTerms]
+  // 词项一律引号包裹:残留特殊字符(FTS5 列过滤/短语语法)全部惰性化
+  return terms.length > 0 ? terms.map(t => `"${t}"`).join(' OR ') : null
+}
+
+export function estimateTokens(text: string): number {
+  const cjk = (text.match(/[\u4e00-\u9fff]/g) ?? []).length
+  return Math.ceil((text.length - cjk) / 4) + cjk
+}
+
+/** 切分还原(segmentCJK 的逆变换;工具返回/注入展示用可读原文)。
+ *  ascii↔CJK 边界的多空格收敛为单空格(segmentCJK 会给 CJK run 两侧补空格,
+ *  与原文空格叠加成双空格;无法区分原意,统一收敛)。 */
+export function unsegmentCJK(text: string): string {
+  return text
+    .replace(/(?<=[\u4e00-\u9fff])\s+(?=[\u4e00-\u9fff])/g, '')
+    .replace(/(?<=[\u4e00-\u9fff])\s+([,.;:!?，。；：！？])/g, '$1')
+    .replace(/([,.;:!?，。；：！？])\s+(?=[\u4e00-\u9fff])/g, '$1')
+    .replace(/([A-Za-z0-9])\s+(?=[\u4e00-\u9fff])/g, '$1 ')
+    .replace(/(?<=[\u4e00-\u9fff])\s+(?=[A-Za-z0-9])/g, ' ')
+    .trim()
+}
+
+export function partsText(parts: Part[]): string {
+  return parts.map(p => ('text' in p ? p.text : '')).filter(Boolean).join('\n')
+}
+
+export function humanAgo(iso: string): string {
+  const ms = Date.now() - Date.parse(iso)
+  if (Number.isNaN(ms)) return '?'
+  if (ms < 60_000) return '刚刚'
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}分钟前`
+  if (ms < 86_400_000) return `${Math.floor(ms / 3_600_000)}小时前`
+  return `${Math.floor(ms / 86_400_000)}天前`
+}
+
+export interface MaintenanceResult {
+  deletedExpired: number
+  evicted: number
+  cleanedVec: number
+}
+
+/**
+ * 记忆维护:① episodic 过期删除(now - (lastAccessedAt ?? createdAt) > 过期天数;
+ * kind 分离:episodic-session 14d / 其余 episodic 180d)
+ * ② 每 agent 容量淘汰(仅 episodic 族;effectiveScore = importance + accessCount×0.05 降序保留)
+ * ③ team 域行:episodic-team-task 同样过期+淘汰(防共享域膨胀);chronicle/semantic 策展行豁免
+ * ④ 孤儿 vec 清理。semantic / brief / chronicle / reflection 全程豁免(单行幂等自限)。
+ */
+export function runMemoryMaintenance(
+  repo: MemoryRepo,
+  opts: { expireDays?: number, cap?: number } = {},
+): MaintenanceResult {
+  const expireDays = opts.expireDays ?? memoryCfg().expire_days
+  const sessionExpireDays = memoryCfg().expire_session_days
+  const cap = opts.cap ?? memoryCfg().cap
+  const now = Date.now()
+  let deletedExpired = 0
+  let evicted = 0
+
+  /** 过期天数按 kind 分离(session 摘要短保鲜) */
+  const expireMsFor = (kind: string): number =>
+    (kind === 'episodic-session' ? sessionExpireDays : expireDays) * 86_400_000
+
+  /** 对一组行执行 ①过期 ②容量淘汰(仅传入选定行;调用方负责 kind 圈定) */
+  const expireAndEvict = (rows: Array<MemoryRow & { rowid: number }>): void => {
+    for (const r of rows) {
+      if (now - Date.parse(r.lastAccessedAt ?? r.createdAt) > expireMsFor(r.kind)) {
+        repo.vecDelete(r.rowid)
+        repo.delete(r.id)
+        deletedExpired++
+      }
+    }
+    const remaining = rows.filter(r => repo.getById(r.id) !== null)
+    if (remaining.length > cap) {
+      const sorted = remaining
+        .map(r => ({ r, s: r.importance + r.accessCount * 0.05 }))
+        .sort((a, b) => b.s - a.s)
+      for (const { r } of sorted.slice(cap)) {
+        repo.vecDelete(r.rowid)
+        repo.delete(r.id)
+        evicted++
+      }
+    }
+  }
+
+  // 成员私有域(排除 team)
+  for (const agentId of repo.listMemoryAgentIds()) {
+    expireAndEvict(repo.listByAgentWithRowid(agentId, 1_000_000)
+      .filter(r => r.kind.startsWith('episodic')))
+  }
+  // team 共享域:仅 episodic-team-task 参与过期/淘汰(chronicle/semantic 策展行豁免)
+  expireAndEvict(repo.listByAgentWithRowid(TEAM_AGENT_ID, 1_000_000)
+    .filter(r => r.kind === 'episodic-team-task'))
+  let cleanedVec = 0
+  try {
+    cleanedVec = repo.vecCleanOrphans()
+  }
+  catch { /* vec 未启用 */ }
+  return { deletedExpired, evicted, cleanedVec }
+}
+
+/** 写入后向量化(模块级;任务路径经 AgentMemory.vectorize,策展路径由 manager 直调)。
+ *  ensure-vec → 定位行(dedupKey)→ embed(未切分原文,语义质量优先)→ vecSet;失败静默留 FTS。
+ *
+ *  放在 helpers 而非 facade:分层类要直接调用它,而 facade 依赖整条分层链 ——
+ *  放 facade 会形成 层 → facade → 层 的循环导入。 */
+export async function vectorizeMemory(
+  repo: MemoryRepo,
+  embedder: EmbeddingProvider | null,
+  channelId: string,
+  agentId: string,
+  dedupKey: string,
+  plainContent: string,
+): Promise<void> {
+  if (!embedder) return
+  try {
+    const [vec] = await embedder.embed([plainContent])
+    if (!vec) return
+    const dims = embedder.dims()
+    if (dims && !repo.vecInit(dims)) return // 维度冲突:一次性放弃本次写入(留 FTS)
+    const at = repo.findByAgentDedup(channelId, agentId, dedupKey)
+    if (at) repo.vecSet(at.rowid, agentId, vec)
+  }
+  catch { /* 向量化失败留 FTS */ }
+}

package/server/services/workshop/runtime/memory/index.ts

@@ -0,0 +1,27 @@
+/**
+ * server/services/workshop/runtime/memory.ts 拆分后的门面(目录 index 解析,外部 import 路径不变)。
+ *
+ * 结构:
+ *   types.ts       依赖类型与 DTO
+ *   helpers.ts     模块级纯工具/常量
+ *   contracts.ts   跨层能力契约(3 个抽象方法)
+ *   state.ts       构造与向量索引 / 作用域判定
+ *   recall.ts      检索:命中收集 / 重排 / recall 与 recallRows
+ *   write.ts       写入:save / 任务结果 / peer 交换 / 向量化
+ *   governance.ts  上下文治理与团队历史(P0-3 幂等 upsert)
+ *   score.ts       打分与行格式化
+ *   facade.ts      最终类 + 模块级尾码
+ */
+export { AgentMemory } from './facade'
+export type { AgentMemoryOptions } from './types'
+export type { RecallOptions } from './types'
+export type { MemoryScope } from './types'
+export type { MemorySnippet } from './types'
+export { envNum } from './helpers'
+export { segmentCJK } from './helpers'
+export { buildMatchQuery } from './helpers'
+export { estimateTokens } from './helpers'
+export { unsegmentCJK } from './helpers'
+export { runMemoryMaintenance } from './helpers'
+export { vectorizeMemory } from './helpers'
+export type { MaintenanceResult } from './helpers'

package/server/services/workshop/runtime/memory/recall.ts

@@ -0,0 +1,216 @@
+/**
+ * AgentMemoryRecall —— 检索:命中收集 / 重排 / recall 与 recallRows
+ * (拆分层,承 AgentMemoryState;方法体与原文件逐行一致)
+ */
+import { AgentMemoryState } from './state'
+import type { MemoryRow } from '../../db/database'
+import type { MemoryScope, MemorySnippet, RecallOptions } from './types'
+import { CURATED_KINDS, FTS_POOL, MMR_LAMBDA, RECENT_FALLBACK, RELATED_TASK_BOOST, RRF_K, buildMatchQuery, estimateTokens, memoryCfg, unsegmentCJK } from './helpers'
+import { TEAM_AGENT_ID } from '../../db/memory.repo'
+
+export abstract class AgentMemoryRecall extends AgentMemoryState {
+  /**
+   * 混合检索原始命中(RRF 融合;不排序不 touch)。
+   * FTS 榜与向量榜各按名次贡献 1/(k+rank) 累加,再按榜内最高分归一化到 0-1——
+   * 相比 v1 的 max 距离归一化,弱首命中/两榜分纲不一致时排序依然稳定。
+   */
+  protected async collectHits(query: string, scope: MemoryScope): Promise<Map<string, { row: MemoryRow, relevance: number }>> {
+    const rrf = new Map<string, { row: MemoryRow, score: number }>()
+    const addRank = (row: MemoryRow, rank: number): void => {
+      if (!this.inScope(row, scope)) return
+      const inc = 1 / (RRF_K + rank + 1)
+      const cur = rrf.get(row.id)
+      if (cur) cur.score += inc
+      else rrf.set(row.id, { row, score: inc })
+    }
+    const match = buildMatchQuery(query)
+    if (match) {
+      const found = this.repo.search(this.opts.agentId, match, FTS_POOL)
+      found.forEach((row, i) => addRank(row, i))
+    }
+    // 向量分支:查询向量 + 本人/team 双域 kNN,按距离名次参与 RRF(失败退化纯 FTS)
+    if (this.embedder) {
+      try {
+        const [qv] = await this.embedder.embed([query])
+        if (qv) {
+          this.ensureVec()
+          const ownDomains: string[]
+            = scope === 'shared'
+              ? [TEAM_AGENT_ID]
+              : scope === 'private'
+                ? [this.opts.agentId]
+                : [this.opts.agentId, TEAM_AGENT_ID]
+          const vAll = ownDomains.flatMap(d =>
+            this.repo.vecSearch(d, qv, d === TEAM_AGENT_ID ? 5 : 10))
+          // rowid → 最小距离(agent/team 分区不相交;防御性取 min),保持距离序作名次
+          const distByRowid = new Map<number, number>()
+          for (const { memRowid, distance } of vAll) {
+            const prev = distByRowid.get(memRowid)
+            if (prev === undefined || distance < prev) distByRowid.set(memRowid, distance)
+          }
+          const rowids = [...distByRowid.entries()].sort((a, b) => a[1] - b[1]).map(([rid]) => rid)
+          this.repo.listByRowids(rowids).forEach((row, i) => {
+            // 所有权守卫 + channel 隔离(脏 rowid/rowid 复用反查到他人行一律丢弃)
+            if (row.agentId !== this.opts.agentId && row.agentId !== TEAM_AGENT_ID) return
+            addRank(row, i)
+          })
+        }
+      }
+      catch { /* 向量不可用退化为 FTS */ }
+    }
+    // 时近兜底仅对含私有域的 scope 生效(shared 域无"本人最近"语义);
+    // 兜底行不参与 RRF,固定弱相关度(策展层行排除——brief 恒 L0 注入,不占引子)
+    const hits = new Map<string, { row: MemoryRow, relevance: number }>()
+    let best = 0
+    for (const { score } of rrf.values()) {
+      if (score > best) best = score
+    }
+    for (const { row, score } of rrf.values()) {
+      hits.set(row.id, { row, relevance: best > 0 ? score / best : 0 })
+    }
+    if (scope !== 'shared') {
+      for (const row of this.repo.listRecent(this.opts.agentId, RECENT_FALLBACK)) {
+        if (CURATED_KINDS.has(row.kind)) continue
+        if (!hits.has(row.id)) hits.set(row.id, { row, relevance: 0.15 })
+      }
+    }
+    return hits
+  }
+
+  /** 排序(综合分降序;策展层排除/任务关联加权;不含预算/touch 副作用) */
+  protected async rank(
+    query: string,
+    scope: MemoryScope,
+    opts: { excludeCurated?: boolean, relatedTaskIds?: string[] } = {},
+  ): Promise<Array<{ row: MemoryRow, relevance: number, score: number }>> {
+    const hits = await this.collectHits(query, scope)
+    const related = opts.relatedTaskIds && opts.relatedTaskIds.length > 0 ? new Set(opts.relatedTaskIds) : null
+    return [...hits.values()]
+      .filter(h => !opts.excludeCurated || !CURATED_KINDS.has(h.row.kind))
+      .map((h) => {
+        let score = this.score(h.row, h.relevance)
+        if (related && h.row.taskId && related.has(h.row.taskId)) {
+          score = Math.min(1, score + RELATED_TASK_BOOST)
+        }
+        return { ...h, score }
+      })
+      .sort((a, b) => b.score - a.score)
+  }
+
+  /**
+   * run/supervise 前的记忆注入:三层装配(硬顶 AW_MEMORY_INJECT_TOTAL)。
+   *  - L0 会话简报(brief 行,确定性置顶,不占检索);
+   *  - L1 相关性引子(RRF 混合检索 + MMR 多样性 + 任务关联加权,小预算);
+   *  - 完整内容由 Agent 经 search_memory 工具按需抓取(L2)。
+   * 预算内装配;使用提示计费(防提示挤占正文预算)。
+   */
+  async recall(query: string, recallOpts: RecallOptions = {}): Promise<string | null> {
+    const doTouch = recallOpts.touch !== false
+    // 显式 budgetTokens(实例/调用级)= 整块记忆硬顶(L0 简报+L1 引子+提示全计入);
+    // 未显式设置 = 双预算:L1 引子 ≤ memory.primer_tokens(300),整块 ≤ memory.inject_total(500)
+    const explicit = recallOpts.budgetTokens ?? this.opts.budgetTokens
+    const budget = explicit ?? memoryCfg().primer_tokens
+    const totalBudget = explicit ?? memoryCfg().inject_total
+    const scope = recallOpts.scope ?? 'auto'
+    const scored = await this.rank(query, scope, { excludeCurated: true, relatedTaskIds: recallOpts.relatedTaskIds })
+
+    const lines: string[] = []
+    const touched: string[] = []
+    let usedTotal = 0
+    // L0 会话简报置顶(幂等单行;确定性注入,不依赖检索命中;计费走总预算,不挤占 L1 引子预算)
+    const briefRef = this.repo.findByAgentDedup(this.opts.channelId, this.opts.agentId, `brief:${this.opts.agentId}`)
+    const briefRow = briefRef ? this.repo.getById(briefRef.id) : null
+    if (briefRow) {
+      const briefText = `## 会话简报(自动维护)\n${unsegmentCJK(briefRow.content)}`
+      const briefCost = estimateTokens(briefText)
+      if (usedTotal + briefCost <= totalBudget) {
+        usedTotal += briefCost
+        lines.push(briefText)
+      }
+    }
+    // 使用提示预留计费:正文与提示共享预算,提示永不超卖
+    const tipsText = [
+      `记忆使用提示:`,
+      `- 以上只是线索级摘要。开工前先判断是否需要更多上下文:历史结论/团队约定/相似任务经验 → 调 search_memory(query, scope) 主动检索(覆盖私有+共享域)。`,
+      `- 作业中发现可复用的结论、约定、教训 → 立即 save_memory 沉淀:scope=private 存个人经验,scope=shared 发布到 Channel 公共记忆供全员复用。`,
+    ].join('\n')
+    const tipsCost = estimateTokens(tipsText)
+    // MMR 装配:逐条贪心选 λ×相关性 − (1−λ)×与已选集最大相似 的最大者(多样性,防近重复挤占)
+    const candidates = scored.slice()
+    const tokenSet = (row: MemoryRow): Set<string> =>
+      new Set(unsegmentCJK(`${row.title} ${row.content.slice(0, 200)}`).toLowerCase().split(/\s+/).filter(Boolean))
+    const selectedTokens: Set<string>[] = []
+    let usedPrimer = 0
+    while (candidates.length > 0 && lines.length < 12) {
+      let bestIdx = -1
+      let bestGain = -Infinity
+      let bestTokens: Set<string> | null = null
+      for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i]!
+        const toks = tokenSet(c.row)
+        let maxSim = 0
+        for (const st of selectedTokens) {
+          if (st.size === 0 || toks.size === 0) continue
+          let inter = 0
+          for (const t of toks) if (st.has(t)) inter++
+          const sim = inter / (st.size + toks.size - inter)
+          if (sim > maxSim) maxSim = sim
+        }
+        const gain = MMR_LAMBDA * c.score - (1 - MMR_LAMBDA) * maxSim
+        if (gain > bestGain) {
+          bestGain = gain
+          bestIdx = i
+          bestTokens = toks
+        }
+      }
+      if (bestIdx < 0) break
+      const [c] = candidates.splice(bestIdx, 1)
+      const line = this.formatLine(c!.row)
+      const cost = estimateTokens(line)
+      // 双预算:L1 引子预算(budget)+ 注入总预算(total,含 brief);超预算跳过但继续找更短行
+      if (usedPrimer + tipsCost + cost > budget || usedTotal + cost + tipsCost > totalBudget) continue
+      usedPrimer += cost
+      usedTotal += cost
+      lines.push(line)
+      selectedTokens.push(bestTokens!)
+      if (doTouch) touched.push(c!.row.id)
+    }
+    if (lines.length === 0) return null
+    for (const id of touched) this.repo.touch(id)
+    return [
+      `## 相关记忆(自动召回的高相关/最近线索摘要;与当前任务冲突时,以当前任务为准)`,
+      ...lines,
+      tipsText,
+    ].join('\n')
+  }
+
+  /**
+   * 工具按需抓取(search_memory):结构化片段返回,content 还原为未切分原文。
+   * 触发 touch(access_count 强化后续召回排序);limit 上限防御;
+   * relatedTaskIds 透传任务关联加权(与 recall 同源排序)。
+   */
+  async recallRows(query: string, opts: { scope?: MemoryScope, limit?: number, relatedTaskIds?: string[] } = {}): Promise<MemorySnippet[]> {
+    const scope = opts.scope ?? 'auto'
+    const limit = Math.min(Math.max(opts.limit ?? 5, 1), 20)
+    const scored = (await this.rank(query, scope, { relatedTaskIds: opts.relatedTaskIds })).slice(0, limit)
+    for (const s of scored) this.repo.touch(s.row.id)
+    return scored.map((s) => {
+      const shared = s.row.agentId === TEAM_AGENT_ID
+      return {
+        id: s.row.id,
+        kind: s.row.kind,
+        title: s.row.title,
+        content: unsegmentCJK(s.row.content).slice(0, 500),
+        importance: s.row.importance,
+        createdAt: s.row.createdAt,
+        score: Math.round(s.score * 1000) / 1000,
+        source: shared ? 'shared' as const : 'private' as const,
+        // §7.4 DTO 必带:来源 Channel / task / 可见性。
+        // rootId 由上层(manager 持有 TaskEngine)补齐 —— 记忆层不查任务表。
+        channelId: s.row.channelId,
+        taskId: s.row.taskId ?? null,
+        visibility: shared ? 'channel-shared' as const : 'private' as const,
+      }
+    })
+  }
+}

package/server/services/workshop/runtime/memory/score.ts

@@ -0,0 +1,33 @@
+/**
+ * AgentMemoryScore —— 打分与行格式化
+ * (拆分层,承 AgentMemoryGovernance;方法体与原文件逐行一致)
+ */
+import { AgentMemoryGovernance } from './governance'
+import type { MemoryRow } from '../../db/database'
+import { RECENCY_HALF_LIFE_DAYS, W_IMPORTANCE, W_RECENCY, W_RELEVANCE, humanAgo, unsegmentCJK } from './helpers'
+
+export abstract class AgentMemoryScore extends AgentMemoryGovernance {
+  /** kind 感知综合分:时近衰减按 kind 半衰期(知识/策展层不随时间贬值) */
+  protected score(row: MemoryRow, relevance: number): number {
+    const halfLife = RECENCY_HALF_LIFE_DAYS[row.kind] ?? 7
+    const ageDays = (Date.now() - Date.parse(row.createdAt)) / 86_400_000
+    const recency = halfLife <= 0 ? 1 : Math.exp(-ageDays / halfLife)
+    const importance = Math.min(1, row.importance + row.accessCount * 0.05)
+    return W_RELEVANCE * relevance + W_RECENCY * recency + W_IMPORTANCE * importance
+  }
+
+  protected formatLine(row: MemoryRow): string {
+    const tag = ({
+      'episodic-task': '任务',
+      'episodic-team-task': '团队任务',
+      'episodic-peer': '协作',
+      'episodic-session': '会话',
+      'brief': '简报',
+      'chronicle': '编年史',
+      'reflection': '反思',
+    } as Record<string, string>)[row.kind] ?? '共享'
+    const content = unsegmentCJK(row.content)
+    const short = content.length > 240 ? `${content.slice(0, 240)}…` : content
+    return `- [${humanAgo(row.createdAt)}·${tag}] ${row.title}:${short}`
+  }
+}

package/server/services/workshop/runtime/memory/state.ts

@@ -0,0 +1,40 @@
+/**
+ * AgentMemoryState —— 构造与向量索引 / 作用域判定
+ * (拆分层,承 AgentMemoryContracts;方法体与原文件逐行一致)
+ */
+import { AgentMemoryContracts } from './contracts'
+import type { AgentMemoryOptions, MemoryScope } from './types'
+import type { EmbeddingProvider } from '../embedding-provider'
+import type { MemoryRepo } from '../../db/memory.repo'
+import type { MemoryRow } from '../../db/database'
+import { TEAM_AGENT_ID } from '../../db/memory.repo'
+
+export abstract class AgentMemoryState extends AgentMemoryContracts {
+  protected embedder: EmbeddingProvider | null
+
+  constructor(
+    protected repo: MemoryRepo,
+    protected opts: AgentMemoryOptions,
+  ) {
+    super()
+    this.embedder = opts.embedder ?? null
+  }
+
+  /** 向量层惰性初始化(vecReady 后 no-op;建表失败一次性禁用 embedder) */
+  protected ensureVec(): void {
+    if (this.repo.vecReady) return
+    const dims = this.embedder?.dims()
+    if (dims && !this.repo.vecInit(dims)) this.embedder = null
+  }
+
+  /** scope 过滤:private 仅本人行;shared 仅本 channel 的 team 行;auto 双域 */
+  protected inScope(row: MemoryRow, scope: MemoryScope): boolean {
+    const isTeam = row.agentId === TEAM_AGENT_ID
+    if (isTeam && row.channelId !== this.opts.channelId) return false
+    return scope === 'auto'
+      ? (isTeam || row.agentId === this.opts.agentId)
+      : scope === 'shared'
+        ? isTeam
+        : row.agentId === this.opts.agentId
+  }
+}

package/server/services/workshop/runtime/memory/types.ts

@@ -0,0 +1,44 @@
+/**
+ * AgentMemory 的依赖类型与对外 DTO(原 server/services/workshop/runtime/memory.ts 顶部模块级类型声明)。纯类型。
+ */
+import type { EmbeddingProvider } from '../embedding-provider'
+
+export interface AgentMemoryOptions {
+  channelId: string
+  agentId: string
+  /** 记忆引子(静态注入)预算覆盖;默认 AW_MEMORY_PRIMER_TOKENS(300)。完整内容经 search_memory 工具按需抓取 */
+  budgetTokens?: number
+  /** 注入后 recall 混合检索 + record* 自动向量化;未注入纯 FTS */
+  embedder?: EmbeddingProvider
+}
+
+export interface RecallOptions {
+  /** 默认 true;supervise 每 tick 调用应传 false 防 access_count 通胀 */
+  touch?: boolean
+  /** 本次召回预算覆盖(默认 AW_MEMORY_BUDGET_TOKENS) */
+  budgetTokens?: number
+  /** 检索域:auto=私有+公共(默认) / private=仅私有 / shared=仅 Channel 公共 */
+  scope?: MemoryScope
+  /** 任务关联集(自身+父+兄弟 ≤20):命中行终分 +RELATED_TASK_BOOST(任务需求驱动的相关性) */
+  relatedTaskIds?: string[]
+}
+
+export type MemoryScope = 'auto' | 'private' | 'shared'
+
+/** 结构化记忆片段(工具按需抓取的返回体;content 已还原为未切分原文) */
+export interface MemorySnippet {
+  id: string
+  kind: string
+  title: string
+  content: string
+  importance: number
+  createdAt: string
+  /** 综合得分(0.5×相关性+0.3×时近性+0.2×重要性) */
+  score: number
+  source: 'private' | 'shared'
+  /** §7.4 来源定位:Channel / root / task / 可见性(缺省 = 旧调用方未提供) */
+  channelId?: string
+  taskId?: string | null
+  rootId?: string | null
+  visibility?: 'channel-shared' | 'private' | 'cross-channel'
+}

package/server/services/workshop/runtime/memory/write.ts

@@ -0,0 +1,93 @@
+/**
+ * AgentMemoryWrite —— 写入:save / 任务结果 / peer 交换 / 向量化
+ * (拆分层,承 AgentMemoryRecall;方法体与原文件逐行一致)
+ */
+import { AgentMemoryRecall } from './recall'
+import type { A2AMessage } from '../../types/a2a'
+import type { WorkspaceTask } from '../../types/task'
+import { CONTENT_STORE_LIMIT, partsText, segmentCJK, vectorizeMemory } from './helpers'
+import { TEAM_AGENT_ID } from '../../db/memory.repo'
+import { randomUUID } from 'node:crypto'
+
+export abstract class AgentMemoryWrite extends AgentMemoryRecall {
+  /**
+   * Agent 主动沉淀(save_memory 工具):把作业过程中的可复用结论/经验写入记忆库。
+   * scope='private' → 本人 semantic 域;scope='shared' → Channel 公共域(全员可检索;
+   * dedupKey 按来源 Agent 命名空间隔离,避免多 Agent 同 key 互相覆盖)。写入后自动向量化。
+   */
+  async save(input: { title: string, content: string, importance?: number, scope: 'private' | 'shared', dedupKey?: string }): Promise<{ scope: 'private' | 'shared', dedupKey: string }> {
+    const shared = input.scope === 'shared'
+    const rawKey = input.dedupKey?.trim() || `agent-save:${randomUUID().slice(0, 8)}`
+    // 共享域命名空间:同 channel 多 agent 各自的沉淀互不覆盖
+    const dedupKey = shared ? `agent:${this.opts.agentId}:${rawKey}` : rawKey
+    const owner = shared ? TEAM_AGENT_ID : this.opts.agentId
+    this.repo.upsert({
+      channelId: this.opts.channelId,
+      agentId: owner,
+      kind: 'semantic',
+      title: input.title,
+      titleFts: segmentCJK(input.title),
+      content: segmentCJK(input.content).slice(0, CONTENT_STORE_LIMIT),
+      importance: input.importance ?? (shared ? 0.85 : 0.7),
+      taskId: null,
+      dedupKey,
+    })
+    await vectorizeMemory(this.repo, this.embedder, this.opts.channelId, owner, dedupKey, input.content)
+    // 共享约定进入简报"团队共享约定"行
+    if (shared) await this.updateBrief()
+    return { scope: input.scope, dedupKey }
+  }
+
+  /** run 后(任务路径;仅终态调用):harvest TaskEngine 终态 + deliverable,并刷新 L0 简报 */
+  async recordTaskOutcome(task: WorkspaceTask): Promise<void> {
+    // 优先 deliverable/summary 命名成果;harness 任意命名(如 mock 的 result)兜底取全部成果
+    const preferred = task.artifacts.filter(a => a.name === 'deliverable' || a.name === 'summary')
+    const source = preferred.length > 0 ? preferred : task.artifacts
+    const deliverable = source
+      .flatMap(a => a.parts)
+      .map(p => ('text' in p ? p.text : ''))
+      .join(' ')
+      .trim()
+    const content = deliverable || task.description || task.title
+    this.repo.upsert({
+      channelId: this.opts.channelId,
+      agentId: this.opts.agentId,
+      kind: 'episodic-task',
+      title: task.title,
+      titleFts: segmentCJK(task.title),
+      content: segmentCJK(content).slice(0, CONTENT_STORE_LIMIT),
+      importance: task.state === 'COMPLETED' ? 0.8 : 0.55,
+      taskId: task.id,
+      dedupKey: `task:${task.id}`,
+    })
+    await this.vectorize(content, `task:${task.id}`)
+    await this.updateBrief()
+  }
+
+  /** run 后(点对点路径):请求 + 我方回复摘要 */
+  async recordPeerExchange(msg: A2AMessage, replyText: string): Promise<void> {
+    const ask = partsText(msg.parts).slice(0, 150)
+    const content = replyText ? `问:${ask} 答:${replyText.slice(0, 250)}` : ask
+    const fromId = (msg.metadata?.['x-aw-from-agent'] as string | undefined) ?? 'unknown'
+    const title = `来自 ${fromId} 的消息`
+    this.repo.upsert({
+      channelId: this.opts.channelId,
+      agentId: this.opts.agentId,
+      kind: 'episodic-peer',
+      title,
+      titleFts: segmentCJK(title),
+      content: segmentCJK(content).slice(0, 600),
+      importance: 0.4,
+      taskId: msg.taskId ?? null,
+      dedupKey: `peer:${msg.messageId}`,
+    })
+    await this.vectorize(content, `peer:${msg.messageId}`)
+  }
+
+  /** 写入后向量化(委托模块级 vectorizeMemory;未切分原文,失败静默留 FTS) */
+  protected async vectorize(plainContent: string, dedupKey: string): Promise<void> {
+    await vectorizeMemory(this.repo, this.embedder, this.opts.channelId, this.opts.agentId, dedupKey, plainContent)
+  }
+
+  // ===== 上下文治理/团队历史(P0-3 新增写入面;全部幂等 upsert)=====
+}