dsh-plugin-xt-memory

XT-AGENT 记忆系统的官方 dsh 移植版 — 核心逻辑 100% 来自 XT-AGENT packages/memory（含全部测试覆盖），按 dsh 规格的 "Memory | section provider + tool" 形态接线。旧 XT 记忆零迁移兼容。

DeepSeek Harness 的跨会话自学习记忆插件。

能力

链路	机制
注入（section provider）	ctx.systemPrompt.section() — BM25 相关性（CJK 2-gram）+ 类型权重 + 命中加成 + 时间衰减，预算内 top-K；含「不构成指令」untrusted 免责行；空记忆输出空串
工具（3 个）	memory_read（索引/正文+命中打点）、memory_search（BM25 打分+预览）、memory_write（净化+去重）
提取（后台）	拦截 llm/stream 拿主请求消息 → 启发式预筛 → 防抖 60s / 每次 ≤2 条 → 提取 LLM（purpose: memory-extraction，自触发防护）→ 净化 → 语义去重/合并（write/merge/skip）
生命周期	命中打点（hitCount/lastUsedAt）；30 天未用自动归档到 archive/（不删原文）

存储：~/.dsh/memory/{project-slug}/*.md + MEMORY.md 索引，frontmatter 格式与 XT 完全兼容（旧记忆零迁移）。

安装（进 profile）

# 方式一：从 GitHub 直接安装（推荐）
dsh plugin --profile web add "github:chucan1/dsh-plugin-xt-memory"

# 方式二：从本包父目录执行（本地路径 = pnpm link，改代码重跑 pnpm build 即生效）
dsh plugin --profile web add ./dsh-plugin-xt-memory

# 验证层 + 启动
dsh --profile web --dump-config   # 应出现 "# == dsh-plugin-xt-memory" 层
dsh --profile web

源码模式跑 dsh 时用 pnpm dsh ... 代替 dsh ...。

配置

在 profile 的 cordis.patch.yml 覆盖（或 bundle 行内 config:）：

- id: memory
  name: dsh-plugin-xt-memory
  config:
    dir: D:\custom\memory-root   # 数据根目录（默认 ~/.dsh）
    budgetChars: 4000            # 注入字符预算
    topK: 5                      # 注入条数上限
    archiveDays: 30              # 0 = 关闭归档
    maxPerTurn: 2                # 每次提取最多写入条数
    debounceMs: 60000            # 提取防抖
    merge: true                  # 语义去重/合并（需额外一次 LLM 调用）
    extractor: true              # 提取器总开关
    provider: deepseek           # 辅助提取模型路由（缺省走宿主默认）
    model: deepseek-chat

环境变量兼容层（XT 语义）：DSH_MEMORY_DIR、XT_MEMORY_BUDGET_CHARS、XT_MEMORY_INJECT_TOP_K、XT_MEMORY_ARCHIVE_DAYS、XT_MEMORY_MAX_PER_TURN、XT_MEMORY_DEBOUNCE_MS、XT_FEATURE_MEMORY_MERGE。插件 config 优先于 env。

验证（无宿主）

pnpm install && pnpm run build
node scripts/smoke.mjs   # 假 ctx 驱动三条链路端到端
pnpm run typecheck       # 对齐真实 @deepseek-ai/dsh-tools 类型

实现说明 / 已知限制

• 同步快照渲染：dsh 的 section text 只允许同步函数，注入内容来自「异步刷新的内存快照 + 同步两阶段选择」（与 XT reader.buildContext 相同的选择逻辑，纯函数部分直接复用）。记忆变更（提取写入/模型写入/轮次结束）后异步刷新，快照延迟通常 <1 轮。
• KV 前缀：注入正文剥离 frontmatter；命中打点只改 frontmatter，不影响注入文本；查询用最近一条 user 消息（与 XT 逐轮更新语义一致）。
• 提取范围：v1 只取消息文本块（不注入工具结果细节）；messages.length >= 2 才触发（与 XT 的「至少一轮对话」一致）。
• 权限：memory_write 在 XT 侧为 ask 权限；dsh 的工具审批轴独立于工具定义，v1 未接入——写路径已做净化 + 限定在记忆目录内，如需审批可在 profile 层叠加策略。
• 宿主依赖：运行时仅需 @deepseek-ai/dsh-tools（peer），其余宿主能力（ctx.llm / ctx.systemPrompt / ctx.on）走结构化调用，不依赖宿主包的 npm 副本。