dsh-memento 0.2.0

package/lib/strings.mjs

@@ -0,0 +1,43 @@
+// lib/strings.mjs — 模型可见/命令面文案（零 DSH 依赖，纯数据）。
+//
+// 语言词表：en 为源文（冻结现状），zh 为本次新写的对应译文。渲染函数用
+// pick(strings, language) 选表；语言词汇本身在 index.mjs 的 Config.language
+// （默认 en，非法值加载期响亮失败）。
+
+/** 快照冻结说明头。 */
+export const SNAPSHOT_HEADER = {
+  en: '[dsh-memento: frozen memory snapshot — captured at session start; memory changes during this session do not update this block. To change memory, use the memory tool.]',
+  zh: '[dsh-memento：冻结记忆快照——会话启动时捕获；本会话内的记忆变更不更新此块。要修改记忆，请使用 memory 工具。]',
+}
+
+/** 快照分组标题（模型可见；en 与 DSH 核心提示一致，zh 为对应译文）。 */
+export const GROUP_TITLES = {
+  en: {
+    'user/user-global': 'User profile (global preferences, communication style, landmines)',
+    'user/workspace': 'User preferences for this workspace',
+    'agent/user-global': 'Environment facts and conventions (cross-workspace)',
+    'agent/workspace': 'Workspace facts, conventions, and lessons',
+  },
+  zh: {
+    'user/user-global': '用户画像（全局偏好、沟通风格、雷区）',
+    'user/workspace': '本工作区的用户偏好',
+    'agent/user-global': '环境事实与约定（跨工作区）',
+    'agent/workspace': '本工作区的事实、约定与教训',
+  },
+}
+
+/** 快照待审批提案块标题。 */
+export const PROPOSAL_HEADER = {
+  en: 'Pending memory proposals (reviewed by the user; approve or dismiss via the /memory proposals command)',
+  zh: '待审批记忆提案（由用户裁决；用 /memory proposals 命令 approve 或 dismiss）',
+}
+
+/**
+ * 按语言选文案表（未知语言回退 en；调用方已在加载期校验词汇）。
+ * @param {Record<string, unknown>} table - 语言键 → 文案。
+ * @param {string} language - 'en' | 'zh'。
+ * @returns {unknown} 所选文案。
+ */
+export function pick(table, language) {
+  return table[language] ?? table.en
+}

package/lib/workspace.mjs

@@ -0,0 +1,31 @@
+// lib/workspace.mjs — 工作区键与 agent 键（零 DSH 依赖）。
+//
+// workspace 层按会话 cwd 隔离：写时与快照时用同一个规范化函数生成键，
+// Windows 下大小写不敏感（盘符/路径大小写差异不产生两个隔离层）。
+// agent 键按 SessionHeader.agentPreset 隔离：'' = 共享层（未按 preset 组合的
+// 部署全部落在同一层，行为与无此维度时一致）。
+
+import path from 'node:path'
+
+/**
+ * 把会话 cwd 规范化为 workspaceKey。空/非法 cwd 得到 ''（共享"无工作区"层，
+ * 仅测试与无 cwd 会话可达；正常 DSH 会话 cwd 必为绝对路径）。
+ * @param {string|undefined|null} cwd - 会话 cwd。
+ * @returns {string} 规范化键。
+ */
+export function workspaceKeyOf(cwd) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return ''
+  const resolved = path.resolve(cwd)
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved
+}
+
+/**
+ * 把会话的 agentPreset 规范化为 agentKey。空/缺失得到 ''（共享层）。
+ * @param {string|undefined|null} agentPreset - SessionHeader.agentPreset。
+ * @returns {string} 规范化键。
+ */
+export function agentKeyOf(agentPreset) {
+  if (typeof agentPreset !== 'string' || agentPreset.length === 0) return ''
+  const trimmed = agentPreset.trim()
+  return process.platform === 'win32' ? trimmed.toLowerCase() : trimmed
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "dsh-memento",
+  "description": "Bounded, layered, approval-gated, auditable cross-session memory for DeepSeek Harness — a capability seam (ctx.memory service + local SQLite provider + memory tool + frozen snapshot injection), not another memory warehouse",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./index.mjs",
+  "types": "./types.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types.d.ts",
+      "default": "./index.mjs"
+    },
+    "./client": {
+      "types": "./client/client.d.ts",
+      "default": "./client/client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "types.d.ts",
+    "lib",
+    "client",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "README.es.md",
+    "README.pt.md",
+    "README.hi.md",
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-memento.git"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-memento#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-memento/issues"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6",
+    "@deepseek-ai/schemastery": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6",
+    "@deepseek-ai/schemastery": ">=3.0.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "coverage": "node --test --experimental-test-coverage \"test/*.test.mjs\"",
+    "check:coverage": "node scripts/check-coverage.mjs",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "check:readmes": "node scripts/verify-readmes.mjs"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "memory",
+    "agent-memory",
+    "approval",
+    "audit",
+    "sqlite",
+    "cordis",
+    "llm"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}

package/types.d.ts

@@ -0,0 +1,191 @@
+// types.d.ts — dsh-memento 类型契约（声明合并）。
+//
+// 本插件入口是纯 ESM JavaScript；类型契约集中在本文件：
+// - `declare module '@deepseek-ai/cordis'`：ctx.memory 服务（F1，三角色 seam 的
+//   Service Definition 面）。
+// - `declare module '@deepseek-ai/dsh-session'`：memory/* 会话事件词汇（F7）。
+//   注意 rc.6 尚无插件事件注册面（KNOWN_SESSION_EVENT_TYPES 不含 memory/*，
+//   且 Session.append 无法标记 ignorable），运行时按已知集合自适应派发——
+//   未被 harness 收录时跳过 append，审计由审批审计对 + 插件审计表承担；
+//   词汇与载荷形状在本文件定死，harness 收录后即自动启用。
+
+export type MemoryTrack = 'user' | 'agent'
+
+export type MemoryScope = 'user-global' | 'workspace'
+
+export type MemoryWritePolicy = 'ask' | 'auto' | 'off'
+
+export type MemoryAction = 'add' | 'replace' | 'remove' | 'consolidate' | 'query' | 'seed'
+
+/** 落盘条目（审计/会话事件的载荷形状）。 */
+export interface MemoryEntry {
+  /** 条目 id（本插件生成，跨会话稳定）。 */
+  id: string
+  /** 轨道：user=用户画像，agent=环境事实/约定/教训。 */
+  track: MemoryTrack
+  /** 作用域：user-global 跨工作区，workspace 按会话 cwd。 */
+  scope: MemoryScope
+  /** workspace 条目的规范化 cwd 键；user-global 条目为空串。 */
+  workspaceKey: string
+  /** 规范化 agentPreset 键；'' = 共享层（所有 preset 可见）。 */
+  agentKey: string
+  /** 条目文本（预算计数字符 = JS 字符串长度）。 */
+  text: string
+  /** 来源标注（dsh-memento / memory-tool / claude 等）。 */
+  source: string
+  /** 创建时间（epoch ms）。 */
+  createdAt: number
+  /** 最近更新时间（epoch ms）。 */
+  updatedAt: number
+  /** 最近召回时间（epoch ms）；从未命中为 null。 */
+  lastRecalled: number | null
+  /** 召回次数（query 排序用：高频即重要）。 */
+  recallCount: number
+  /** 最近一次写它的会话 id；无则 null。 */
+  sessionId: string | null
+}
+
+/** 写入输入（add/seed 用）。 */
+export interface MemoryEntryInput {
+  track: MemoryTrack
+  scope: MemoryScope
+  text: string
+  source?: string
+  /** 显式 workspaceKey；省略时取写方会话 cwd。 */
+  workspaceKey?: string
+  /** 显式 agentKey；省略时取写方会话 agentPreset。 */
+  agentKey?: string
+}
+
+/** 会话最小形状（插件只读这些面；字段宽类型以兼容真实 Session/Agent）。 */
+export interface MemorySessionLike {
+  id?: unknown
+  header?: { cwd?: unknown; agentPreset?: unknown }
+  append?: (type: string, data: unknown) => unknown
+}
+
+/** 审批服务最小形状（插件消费的 seam 面）。 */
+export interface MemoryApprovalLike {
+  request(req: { agent?: unknown; toolName?: string; reason?: string; callId?: unknown; signal?: AbortSignal }): Promise<string>
+  overrideOf?(session: unknown): string | undefined
+  config?: { policy?: string }
+}
+
+/** 写上下文：审批路由与审计归属所必需。agent 缺失时写失败封闭。 */
+export interface MemoryWriteContext {
+  /** 发起写的 agent（其 session 承载审批审计对）。 */
+  agent: { session?: MemorySessionLike | null } | null | undefined
+  /** 发起写的工具 callId（供 UI answerer 挂靠已流式化的工具调用）。 */
+  callId?: unknown
+  /** 取消信号：中止即 cancelled，不写任何东西。 */
+  signal?: AbortSignal
+  /** 可选自定义审批传输（turn 外命令路径注入；payload 携带完整写载荷）。 */
+  gate?: (payload: { action: string; track: string; scope: string; text: string; count?: number }, write: MemoryWriteContext) => Promise<string>
+}
+
+/** query 结果。 */
+export interface MemoryQueryResult {
+  entries: MemoryEntry[]
+  total: number
+  truncated: boolean
+}
+
+/** 预算行。 */
+export interface MemoryBudgetRow {
+  track: MemoryTrack
+  scope: MemoryScope
+  used: number
+  limit: number
+}
+
+/** 写成功后的用量（模型据此整合/删除后重试）。 */
+export interface MemoryUsage {
+  track: MemoryTrack
+  scope: MemoryScope
+  used: number
+  limit: number
+}
+
+/** ctx.memory 服务：写方法内部强制过审批门，读方法无审批。 */
+export interface MemoryService {
+  /** 模型可见文案与命令输出的语言（Config.language，'en' | 'zh'）。 */
+  language: 'en' | 'zh'
+
+  /** 每轨每层当前用量与上限。 */
+  budgets(): MemoryBudgetRow[]
+
+  /** 子串查询（无审批）；带 sessionId 时记 recalled 审计，带 session 时按已知事件类型自适应派发 memory/recalled。 */
+  query(filter?: { track?: MemoryTrack; scope?: MemoryScope; text?: string; limit?: number }, opts?: { sessionId?: string; session?: MemorySessionLike | null }): MemoryQueryResult
+
+  /** 新增条目（审批门 + 预算门）。 */
+  add(input: MemoryEntryInput, write: MemoryWriteContext): Promise<{ entry: MemoryEntry; usage: MemoryUsage }>
+
+  /** 按唯一子串替换（审批门 + 预算门；零/多命中报错）。 */
+  replace(input: { track: MemoryTrack; scope: MemoryScope; match: string; text: string; source?: string }, write: MemoryWriteContext): Promise<{ previous: MemoryEntry; entry: MemoryEntry; usage: MemoryUsage }>
+
+  /** 按唯一子串删除（审批门；零/多命中报错）。 */
+  remove(input: { track: MemoryTrack; scope: MemoryScope; match: string }, write: MemoryWriteContext): Promise<{ entry: MemoryEntry; usage: MemoryUsage }>
+
+  /** 整合多条为一条（一次审批 + Provider 单事务原子执行；零/多命中或超预算响亮失败）。 */
+  consolidate(input: { track: MemoryTrack; scope: MemoryScope; matches: string[]; text: string; source?: string; workspaceKey?: string; agentKey?: string }, write: MemoryWriteContext): Promise<{ removed: MemoryEntry[]; entry: MemoryEntry; usage: MemoryUsage }>
+
+  /** 批量种子（一次 ask 审批整批；任一条超预算整批拒绝）。 */
+  seed(inputs: MemoryEntryInput[], write: MemoryWriteContext): Promise<{ added: number; entries: MemoryEntry[] }>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** dsh-memento 记忆服务（本插件提供；其它插件可读写同一 store）。 */
+    memory: MemoryService
+    /** 审批 seam（本插件消费的最小面；由 DSH interaction 能力提供）。 */
+    approval: MemoryApprovalLike
+  }
+  interface Events {
+    /** 审批 waterfall（本插件 answerer 挂链）。 */
+    'approval/request'(req: unknown, next: () => Promise<string>): Promise<string>
+    /** 可选服务就绪通知（withService 用）。 */
+    'internal/service'(name: string): void
+    /** 会话事件桥（auto-capture 等观察面用）。 */
+    'session/event'(session: unknown, event: unknown): void
+  }
+}
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * 一条记忆条目已落盘（审批通过后的写成功）。日志只读事件，非 surface；
+     * 审计链 = approval/asked + approval/decided + 本事件 + 插件审计表。
+     * rc.6 无插件事件注册面时运行时跳过 append（见 types.d.ts 头注）。
+     */
+    'memory/added': {
+      entry: MemoryEntry
+      source: string
+      sessionId: string
+    }
+    /** 一条记忆条目被 replace 改写（previous 为改写前内容）。 */
+    'memory/updated': {
+      previous: MemoryEntry
+      entry: MemoryEntry
+      source: string
+      sessionId: string
+    }
+    /** 一条记忆条目被 remove 删除。 */
+    'memory/removed': {
+      entry: MemoryEntry
+      source: string
+      sessionId: string
+    }
+    /** 一次 query 召回（记录过滤条件与命中数）。 */
+    'memory/recalled': {
+      query: string
+      matches: number
+      sessionId: string
+    }
+    /** 会话启动时注入的冻结快照（text 与模型所见 systemPrompt 段逐字一致，S2）。 */
+    'memory/snapshot': {
+      text: string
+      workspaceKey: string
+      at: number
+    }
+  }
+}