# @hy-sde-org/dsh-memory-extraction 中文文档

规范地址：https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/

版本：0\.2\.1-rc\.5
npm 元数据更新时间：2026-11-01T04:25:32.089Z
中文译文更新时间：2026-11-01T09:17:31.977Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40hy-sde-org/dsh-memory-extraction
原文对照：https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/?lang=original
项目主页：https://github.com/hy-sde/dsh-memory-extraction#readme
源码仓库：https://github.com/hy-sde/dsh-memory-extraction

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：223 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ~4\.0\.5，@deepseek-ai/dsh-llm ^0\.2\.1-rc\.5，@hy-sde-org/dsh-memory ^0\.2\.1-rc\.5，@deepseek-ai/dsh-session ^0\.2\.1-rc\.5，@deepseek-ai/dsh-storage ^0\.2\.1-rc\.5，@deepseek-ai/dsh-compaction ^0\.2\.1-rc\.5
- 首次发布：2026-09-10T04:17:01.145Z
- 最新版本发布：2026-11-01T04:25:31.934Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

在压缩检查点自动提取长期记忆：证据投影，建议/规范化管道，门控ctx。内存提交，以及持久游标/收据/故障分类账。

## 安装

```sh
npm install @hy-sde-org/dsh-memory-extraction
```

也可以使用：`pnpm add @hy-sde-org/dsh-memory-extraction`、`yarn add @hy-sde-org/dsh-memory-extraction`、`bun add @hy-sde-org/dsh-memory-extraction`

## README

# @hy-sde-org dsh-memory-extraction

英语| [中文](https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/README.zh.md)

## 总结

`dsh-memory-extraction` 是玛卡自动提取记忆的DSH端口吗 触发：每次之后 `compaction/summary` 事件（检查点边界） 有界的、失败打开的管道项目 **user-authored** 的文本 检查点范围，用辅助提出和规范化持久事实 建模调用，并将承认的事实提交到同一个项目内存库中 `retain`/`learn` 写。严格来说 **添加剂** 到DSH的外显记忆 表面: `retain`/`learn`/`memory_edit` 工具保持面向模型的路径 港口有意保留（不保留）马卡的葡萄酒 `memory_remember`/`memory_extract` 动词。

这个包裹是一个 **host-plane** Cordis插件(`inject: ['memory', 'llm']`， 不发布任何内容)：一个进程打开 `memory_extraction` 控制单元一次 并通过一个无作用域的 `ctx.on('session/event')` 侦听器（范围筛选器全局允许未限定范围的侦听器）。运行 按会话序列化并且从不阻塞压缩侦听器。

### 承重规则（从Maka港运）

1.  **证据仅为用户撰写的文本** - - - - - -项目 `user/message` 事件的 `source.kind === 'user'`;辅助文本仅用于解释；工具 调用/结果、推理和插件检查点是不透明的。证据是 （12000个字符JSON /每条记录4000个字符/ 64条记录）和 **fail-closed** 在溢出。
2.  **确认入场** -提案→录取（逐字报价检查） 反对有限的证据+秘密拒绝)→规范化→ 最多是重新录取 **3辅助模型调用** 每个范围60秒 超时;包含故障（在运行时边界处打开故障）。
3.  **光标只移动到已提交的边界** -空范围仍然存在 预付款（无订单收据，无模型呼叫）；一个失败的范围变成一个挂起的范围 记录由下一个触发器重试，然后丢弃。写入顺序为 项目→光标→收据，因此光标和收据之间永远不会崩溃 double-process。
4.  **幂等是确定的** - operation id = `memory_` + sha256 of `{sessionId, trigger, boundarySeq}`;收据使重播无操作和 委员会侧重复探测修复项目和收据之间的崩溃。
5.  **子代理除外** -闸门在每次模型调用后重新检查 默认拒绝子会话(`excludeSubagents: true`）。
6.  **跨会议证据厅（E1）** ——一个事实只犯一次 `minGapEvidence` **截然不同的** 会话(默认为2个；一个会话永远不会计数 两次，甚至在其自身的压缩中，都提出了相同的持久事实。 未经证实的事实变成 `gaps` 在账簿上看到的，稍后给大家看 提案被视为悬而未决的事实(该模型引用了a `gapId` 而不是 创造释义)；标识返回到规范化的内容散列。 当事实被提交或已经在银行中被发现时，事实就会退出（承保）。 更早的目击事件 `gapLedgerMaxAgeMs` （默认90天）过期。延期货 仍然移动光标并结算收据；读/写分类帐 取配置值为 `0` 完全关闭（e1之前的行为）。

## 目录表

-   [使用这个包](https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/#readme-use-this-package)
-   [理解实现](https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/#readme-understand-the-implementation)
-   [进一步的探索](https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/#readme-further-exploration)
-   [模型经验](https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/#readme-model-experience)
-   [已知的限制和延迟的工作](https://npmcn.com/package/%40hy-sde-org/dsh-memory-extraction/#readme-known-limitations-and-deferred-work)

## 使用这个包

这一行属于 **主机组成** -它注入主机服务 （`memory`， `llm`)，每个过程打开一次控制单元，并且必须观察 每个会话的事件。没有代理预设贡献，也没有工具。

```yaml
# host composition (loaded before any session)
- id: memory-extraction
  name: '@hy-sde-org/dsh-memory-extraction'
  config:
    backend: sqlite           # storage backend hosting the control unit (default sqlite)
    enabled: true             # master switch (default true)
    excludeSubagents: true    # child-agent compactions never extract (default true)
    # provider: <cheap provider id>  # optional; unset uses the session's routed model config
    # model: <cheap model id>        # optional; unset uses the session's routed model config
    importance: 0.5           # bank importance for auto-extracted facts (default 0.5)
    dedupe: true              # probe the bank before committing duplicates (default true)
    timeoutMs: 60000          # auxiliary call timeout (default 60000)
    minGapEvidence: 2         # distinct sessions before a fact commits (default 2; 0 disables the floor)
    gapLedgerMaxAgeMs: 7776000000   # sightings older than this stop counting (default 90 d in ms)
```

它的存储后端必须公开 `kv` 面（运来的） `sqlite` 后端 做; `storage-json` 不)-上面一行是完整的主机布线。 这个引擎本身是纯粹的，可以测试的，不需要cordis。

```ts
import { MemoryExtractionEngine } from '@hy-sde-org/dsh-memory-extraction'

const engine = new MemoryExtractionEngine(ports) // readGate/readEvents/read+write cursor+receipt+failure/commitItems/generate
const result = await engine.execute(snapshot)   // never throws; idempotent by operation id
```

### 布线

插件异步启动：一个效果通过打开控制单元 `storage.backend.<backend>.kv.open(MemoryExtractionControlStore.descriptor)` （`memory_extraction`，版本1，表 `cursors`/`receipts`/`failures`/`gaps` - gap表是附加的，版本保持1，因为storage-sqlite 后端拒绝现有媒体上的版本颠簸； `CREATE TABLE IF NOT EXISTS` 在升级时实现它)和 注册 `session/event` 侦听器。丢失的后端记录日志并离开 插件惰性，而不是失败的组合。

## 理解实现

-   `src/evidence.ts` -有限证据投影，覆盖规划 （二进制搜索收缩，失败关闭溢出），同一会话本地化 搜索，报价验证。
-   `src/proposal.ts` -严格的手动JSON解析器(complete / `search_required` / `cannot_resolve` /规范化)，提示构建器 将证据诬陷为 **不可信的数据**，入场（逐字引用，最少4个字符） 秘密拒绝，NFC +注入中和，2000字符含量上限)。
-   `src/control.ts` -持久游标/收据/故障/缺口存储超过一个 `KvUnit` （单写链；打开后修复；写顺序记录）。
-   `src/engine.ts` -状态机：幂等接收，门，空范围 提前，一次重试-然后丢弃，三呼叫预算，提交排序。
-   `src/events.ts` -有损的DSH事件投影（仅限用户/辅助文本）； 旋转跟踪定位分组)。
-   `src/memory-adapter.ts` -提交表面结束 `ctx.memory`：双重探针； 然后 `save` 与 `source: 'memory_extract'`，加上闸门工厂。
-   `src/runtime.ts` -主机接线：每个会话顺序队列，生成适配器 （`BlockAssembler`， `AbortSignal.timeout`（路由提供商/模型覆盖）， 实时服务上的同步/异步端口实现。

## 进一步的探索

-   这是从Maka源移植的： [`memory-extraction.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/memory-extraction.ts).
-   发出边界事件的压缩生命周期： `@deepseek-ai/dsh-compaction`.

## 模型经验

管道为每个检查点范围添加了3个辅助模型调用 用户撰写的文本（建议、可选的本地化、规范化） 有界的 `timeoutMs`。配置 `provider`/`model` 给一个廉价的辅助 模型适用于大型部署；当取消设置时，会话被路由 使用了请求头。模型永远不会看到原始日志或工具结果 有限的、用户编写的证据加上简短的本地化上下文。

## 已知的限制和延迟的工作

-   **每个会话有一个挂起的失败** （重试一次，然后丢弃）- Maka保持 更丰富的失败状态（例如证据增长重试），稍后作为单个移植 重试。
-   **没有持续的再提取** 关于证据增长：一个失败的检查点 重试一次，然后丢弃。
-   **间隙标识是模型引用或精确散列的** ——对建议的释义 Pass不链接到一个打开的未决事实通道 `gapId` 又回到 规范化的内容散列并保持挂起，直到字节相同的发现(或 一个明确的引用)证实了这一点。没有完成词法/语义匹配。
-   **延迟的事实不是重复探测的** ——已经有人这么做了 `retain`埃德说，提取建议永远不要通过银行支票退休；它 当第二个会话引用它或它的查看过期时退出。
-   **Maka facet没有被移植** (/时间/范围/标签);每个提取 事实是 `source: 'memory_extract'` 以及配置的重要性。
-   **没有谓词工具**： `memory_remember`/`memory_extract` 是保留名称； 显式DSH内存工具仍然是面向模型的路径。
-   重复数据删除探测依赖于本地内存库 `search` 看到以前 已提交的行（同进程语义）。

## 常见问题

### @hy-sde-org/dsh-memory-extraction 是什么？

在压缩检查点自动提取长期记忆：证据投影，建议/规范化管道，门控ctx。内存提交，以及持久游标/收据/故障分类账。

### 如何安装 @hy-sde-org/dsh-memory-extraction？

在项目目录运行 npm install @hy-sde-org/dsh-memory-extraction，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（~4\.0\.5）、@deepseek-ai/dsh-llm（^0\.2\.1-rc\.5）、@hy-sde-org/dsh-memory（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-session（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-storage（^0\.2\.1-rc\.5）、@deepseek-ai/dsh-compaction（^0\.2\.1-rc\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hy-sde-org/dsh-memory-extraction 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @hy-sde-org/dsh-memory-extraction 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @hy-sde-org/dsh-memory-extraction 可以商用吗？

@hy-sde-org/dsh-memory-extraction 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @hy-sde-org/dsh-memory-extraction 还在维护吗？

最新版本 0\.2\.1-rc\.5 发布于 2026/11/01（2 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。