dsh-plugin-xt-memory

Readme

# 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）

```sh
# 方式一：从 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:`）：

```yaml
- 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。

## 验证（无宿主）

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