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 副本。
