dsh-plugin-memos-code-retrospect

Readme

# dsh-plugin-memos-code-retrospect

> 复刻 mneme 编码对话复盘蒸馏业务逻辑的 DSH（DeepSeek-Harness / Cordis）插件。
> **不引入 mneme 二进制、不创建独立数据库**；所有记忆存储、向量检索、归档淘汰、记忆生命周期全部复用 MemOS 记忆底座。

![version](https://img.shields.io/badge/version-0.2.0--beta.1-blue)
![license](https://img.shields.io/badge/license-MIT-green)
![tests](https://img.shields.io/badge/tests-14%2F14%20passed-brightgreen)

## 业务目标

解决 AI 编码任务**重复踩坑**、**遗忘被否决实现方案**、**丢失项目工程约束**的问题；支持论文消融实验（插件开启/关闭对照），可演进为生产可用组件。

## 版本说明

| 版本 | 状态 | 能力 |
| --- | --- | --- |
| v1 最小科研版 | 已实现 | 插件脚手架 + turn/end 蒸馏 + agent/pre-step 加权召回 + 标签写入 + 基础验证；允许短板：JSON 解析失败直接丢弃、无去重、无价值过滤、日志极简 |
| v2 健壮版 | 已实现（当前） | v1 全部能力 + LLM JSON 解析降级重试（≤1 次）、写入前相似度去重（dedupeThreshold 0.82）、低价值内容过滤、完整日志埋点、边界截断保护、单元测试 |
| 可选扩展 | 预留 | TencentDB-Agent-Memory 同步（`sync_to_tencentdb`），默认关闭；失败只打日志不阻塞主链路（MemOS 本地插件已内置 `captureToTencentMemory` 现成底座，扩展时直接复用） |

## 核心业务流程

### 写入链路：回合结束蒸馏（`turn/end`）

一轮完整交互（用户输入 → DSH 调度 → Worker 执行 → 返回结果）结束后触发：

1. 从 `session.events` 过滤本回合事件（用户消息、助手思考/回答、工具调用与结果、代码执行），组装完整对话上下文；
2. 超长上下文按 `max_distill_context` 截断，避免蒸馏 Prompt 溢出；
3. 调用 LLM 蒸馏，输出固定格式 JSON，提取三类实体：
   - `rejected_solution`：被否决/废弃的实现方案
   - `pitfall`：调试踩坑记录、报错、问题根因
   - `constraint`：项目工程约束、架构约定、编码规范
4. 价值过滤 → 去重比对（写入前检索相似度）→ 打标签 `type:rejected_solution` 调用 MemOS 接口写入记忆；
5. 业务特性：本轮蒸馏产出的记忆，本轮会话不可用，下一轮会话才会被召回。

### 读取链路：推理前加权召回（`agent/pre-step`）

Agent 每一轮大模型推理执行之前触发：

1. 判断当前会话任务是否为编码类任务（关键词识别，`codingKeywords` 可配）；
2. 编码任务：调用 MemOS 检索接口，对命中 `type:rejected_solution` 标签的记忆按 `boostFactor` 提升权重，重排后注入提示词，再执行 LLM 推理；
3. 非编码任务（量化、GUI 操作等）：不注入 `type:rejected_solution` 记忆，防止编码记忆对其他业务造成噪声污染。

## 能力复用说明

- **不实现** mneme 的 hot/warm/cold 冷热分层；
- **不实现** HNSW 向量索引；
- 向量检索、记忆合并、归档、淘汰、软删除**全部交给 MemOS**；
- 插件内部**不保存任何记忆数据**，持久化全部调用 MemOS 接口；
- 插件自持独立 MemoryCore 实例（`autoRecovery:false`、`initLogging:false`），与主 `memos-local-memory` 插件共用同一 home/config（同一 SQLite 库与向量文件），不抢占恢复任务与日志通道。

## 安装

### 方式 A：从 GitHub 仓库安装（社区公测推荐）

```powershell
dsh plugin --profile web install https://github.com/<your-github-name>/dsh-plugin-memos-code-retrospect
```

### 方式 B：本地目录安装（开发调试）

把仓库克隆/拷贝到 `<profile>/plugins/dsh-plugin-memos-code-retrospect/`，再按下方「注册到 DSH」配置 `cordis.patch.yml`。

## 依赖前提

- 已安装 DSH（DeepSeek Harness）并初始化 `web` profile；
- 已安装 MemOS 本地插件（`@memtensor/memos-local-plugin`），本插件所有记忆读写依赖其接口；
- 蒸馏 LLM 可经由 DSH LlmRuntime 路由（或显式配置 `distillModel`）；集成测试需要本地 ollama（`qwen3:14b` 或同类指令模型）；
- Node.js >= 18。

## 部署说明

### 1. 文件位置

```
<profile>/plugins/dsh-plugin-memos-code-retrospect/
├── package.json
├── dist\
│   └── index.js          # v2 健壮版主实现
├── test\
│   ├── retrospect.test.mjs   # 单元测试（14 用例）
│   └── integration.mjs       # 集成测试（真实 MemOS + LLM，参数化）
└── README.md
```

### 2. 依赖链接

插件通过 junction 复用 DSH 全局安装内的 `@deepseek-ai/dsh-llm`（profile node_modules 顶层可能未暴露该包）：

```powershell
$plugin = "<profile>\plugins\dsh-plugin-memos-code-retrospect"
$nm = "$plugin\node_modules\@deepseek-ai"
New-Item -ItemType Directory -Force -Path $nm | Out-Null
New-Item -ItemType Junction -Path "$nm\dsh-llm" -Target "<dsh-global>\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai\dsh-llm" | Out-Null
```

`schemastery` 与 `@memtensor/memos-local-plugin` 通常由 profile `node_modules` 顶层解析；如缺失，同样以 junction 方式链接。

### 3. 注册到 DSH

向 profile 的 `cordis.patch.yml` 追加：

```yaml
- insert:
    - id: dsh-plugin-memos-code-retrospect
      name: './plugins/dsh-plugin-memos-code-retrospect/dist/index.js'
      config:
        enabled: true
        profileId: default
        recallEnabled: true
        captureEnabled: true
        boostFactor: 2
        recallTopK: 6
        contextMaxChars: 3000
        maxDistillContextChars: 8192
        distillMaxTokens: 2048
        distillRetries: 1
        dedupeEnabled: true
        dedupeThreshold: 0.82
        valueFilterEnabled: true
        sync_to_tencentdb: false
```

然后重启 DSH：

```powershell
Stop-Process -Name dsh -Force
dsh web --port 3080
```

启动后可通过 `dsh --profile web --dump-config` 确认插件进入组合树；运行日志中出现 `[retrospect]` 前缀即加载成功。

### 4. 单元测试

```powershell
cd <plugin-dir>
npm test
# 或直接
node test/retrospect.test.mjs
```

预期输出：`14 passed, 0 failed`（覆盖：JSON 解析、价值过滤、编码任务识别、相似度、JSON 解析失败重试、去重命中跳过写入、编码失败蒸馏写入等链路）。

### 5. 集成测试（真实闭环）

需要本地 ollama 与 `qwen3:14b` 模型，验证「蒸馏写入 → 下一轮加权召回注入」闭环：

```powershell
cd <plugin-dir>
$env:MEMOS_IT_HOME = "$env:TEMP\memos-it-data"   # 可选，默认仓库下 .it-data/
$env:OLLAMA_BASE = "http://127.0.0.1:11434"     # 可选，默认同上
node test/integration.mjs
```

预期输出：`4 passed, 0 failed`。测试使用独立临时记忆库，不影响生产数据。

## 配置说明

| 配置项 | 默认 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 插件总开关，一键启停（对照实验用） |
| `home` | `""` | MemOS 数据目录（空则用 resolveHome 默认值，与主插件一致） |
| `profileId` | `"default"` | 记忆命名空间 profile |
| `recallEnabled` | `true` | 读取链路（pre-step 加权检索）开关 |
| `recallTimeoutMs` | `3000` | 检索 deadline |
| `recallTopK` | `6` | 最终注入条数 |
| `boostFactor` | `2` | `type:rejected_solution` 命中 score 倍率（`enable_weight`） |
| `contextMaxChars` | `3000` | `<retrospect_context>` 最大长度 |
| `codingKeywords` | 内置词表 | 编码任务识别关键词 |
| `captureEnabled` | `true` | 写入链路（turn/end 蒸馏）开关 |
| `distillModel` | `""` | 蒸馏 LLM 模型（`distill_llm`），留空跟随会话路由 |
| `distillMaxTokens` | `2048` | 蒸馏输出上限 |
| `distillTimeoutMs` | `60000` | 蒸馏超时 |
| `distillMinChars` | `300` | 本轮对话小于该长度跳过蒸馏 |
| `maxDistillContextChars` | `8192` | 蒸馏最大上下文长度（`max_distill_context`），超长自动截断 |
| `distillRetries` | `1` | JSON 解析失败重试次数（v2 降级策略） |
| `dedupeEnabled` | `true` | 写入前去重开关（v2） |
| `dedupeThreshold` | `0.82` | 相似度阈值，超过则视为重复跳过写入 |
| `valueFilterEnabled` | `true` | 低价值内容过滤开关（v2） |
| `sync_to_tencentdb` | `false` | TencentDB-Agent-Memory 可选同步（预留，默认关闭） |

## 验证闭环

构造多轮编码失败场景，验证「踩坑 → 蒸馏写入 → 下一轮召回生效」完整闭环：

1. 编码任务中报错/否决方案，turn/end 后日志出现 `[retrospect] distilled trace=...`；
2. MemOS viewer 检索 `tags: type:rejected_solution` 应看到新 trace；
3. 下一轮发起相关编码任务，pre-step 日志出现 `injected rejected_solution recall`，模型上下文包含 `<retrospect_context>`。

## 已知限制

- 蒸馏质量依赖所选 LLM 的指令跟随能力；qwen3 系默认思考模式会占用输出 token，建议 `distillMaxTokens >= 2048` 或关闭 think；
- 记忆写入发生在 `turn/end`，本轮写入的记忆下一轮才可被召回（有意设计，非缺陷）；
- 非编码任务默认不注入 `type:rejected_solution` 记忆，防止噪声污染（`codingKeywords` 可配）；
- `sync_to_tencentdb` 为预留扩展，本次未实现；
- MemOS 不可用时插件 fail-open（可加载但记忆读写失效）。

## 约束与注意事项

- 插件只做逻辑处理，所有持久化操作全部调用 MemOS 接口，内部不保存任何记忆数据；
- 禁止拉起 mneme 子进程，禁止读写 mneme 数据库；
- 任务类型识别（编码/非编码）在插件内部实现，用于控制 `rejected_solution` 标签权重。

## 贡献

欢迎提交 Issue / PR。开发约定：

- 修改 `dist/index.js` 后同步跑 `node test/retrospect.test.mjs`，保持 14/14 通过；
- 涉及记忆读写行为变更时，补充/更新 `test/integration.mjs` 的闭环用例。

## License

[MIT](./LICENSE)
*（内容由AI生成，仅供参考）*
*（内容由AI生成，仅供参考）*