dsh-plugin-om 0.0.4 → 0.0.6

package/README.md

@@ -1,23 +1,30 @@
 # dsh-plugin-om
 
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-om.svg)](https://www.npmjs.com/package/dsh-plugin-om)
+
 在 DSH 里应用 [Observational Memory](https://mastra.ai/research/observational-memory) 风格的上下文管理策略
 
 ## 工作原理
 
-1. 在未压缩消息超过阈值后摘要
-2. 摘要会替换原始消息，并追加至现有摘要
-3. 在摘要超过阈值后，重新摘要
-4. 摘要过程中保留关键的message_id，允许模型精确recall
+1. 在未压缩消息超过阈值后摘要：压缩**尾部之前**的消息并用摘要替换（尾部 `tailMessageCount` 条不压缩、不被替换、不进日志）
+2. 摘要替换原始消息，并以**多个 `<om-history>` 块按序拼接**的方式追加至现有摘要（旧块原样保留，新块追加在末尾）
+3. 摘要超过阈值后重新摘要（反思：精简合并现有日志块）
+4. 摘要输出为**合法 XML 日志**（`<om-history>` 内 `<user_message id>` 完整保留用户原文、`<assistant last_id>` 聚合 AI 模块）；插件不信任 AI 输出，取首个 `<om-history>` 到最后一个 `</om-history>`（含首尾）切为日志，找不到或中间内容过短视为不合法并按失败重试；产出后插入格式说明注释
+5. 摘要过程中保留 message_id（`<user_message id>` / `<assistant last_id>`），允许模型精确 recall
+6. 压缩在 `agent/pre-step` 触发（**turn 中间即可**，无需等待轮次结束）：摘要直连 LLM，模式见[摘要模式](#摘要模式)——`fork`（缺省）复用主会话请求前缀（系统提示词 + 截至尾部前的消息 + 末尾指令），充分利用 provider 前缀缓存；`new` 只注入被压缩消息（XML 包裹）；`disable` 关闭自动压缩
+7. 提供语义召回（recall-semantic）：按自然语言在全部消息日志中检索，被压缩/遮蔽的消息也可按语义找回
 
 ### 注意
 
 - recall 不截断，建议保留 `tool-result-pruner`
 - 默认上下文压缩插件 `compaction-basic` 到达阈值后会自动摘要，不建议和此插件一起使用
+- recall-semantic 使用本地多语言嵌入模型（paraphrase-multilingual-MiniLM-L12-v2，量化 ONNX），完全离线；首次调用时加载模型，之后复用。模型二进制（~113MB）不进入 git 仓库，改为**运行时按需下载**：启用 recall-semantic 且模型缺失时，插件启动即后台自动下载（不阻塞），未就绪时工具会告知模型（见[依赖策略](#依赖策略)）
 
 ### 依赖策略
 
-- 以type-only的方式引用第三方库
 - 复用dsh宿主提供的依赖，如 cordis / dsh-tools / zod 等
+- 例外：recall-semantic 的本地嵌入需要运行时依赖 `@huggingface/transformers`（transformers.js v4 + onnxruntime-node），模型小文件（config/tokenizer 等）随 npm 包分发（`models/`），onnx 二进制不做构建/发布时下载
+- 模型二进制：量化 ONNX 约 113MB，超过 GitHub 单文件 100MB 限制，**不进入 git 仓库**。改为**运行时按需下载**：仅当配置键 `semanticRecallEnabled` 启用且 `models/<id>/onnx/model_quantized.onnx` 缺失时，插件 apply 后台自动从 HuggingFace（[Xenova 转换仓库](https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2)）下载到 `models/`（不阻塞；下载失败仅记日志，下次调用自动重试；未就绪时 `recall-semantic` 工具返回文案告知模型）；本地开发也可用 `pnpm run download:model` 手动预下载（已存在则跳过，`--force` 强制重下）；直连 `huggingface.co` 受限时设置环境变量 `HF_ENDPOINT=https://hf-mirror.com` 走镜像
 
 ## 安装与启用
 
@@ -34,15 +41,26 @@
 dsh plugin --profile <profile> add dsh-plugin-om
 ```
 
-无需重启
+需要重启dsh
 
 可以通过`dsh --profile <profile> --dump-config`审查配置是否正确
 
+如果需要覆盖默认配置，打开 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 删除里面的空数组，加入
+
+```yaml
+- id: dsh-plugin-om
+  config:
+    thresholdRatio: 0.2
+    # 其他配置参考下文
+```
+
+不需要重启 可以热更新
+
 ### 开发插件
 
-运行`pnpm dev`，等待`dist/index.mjs`构筑完毕
+运行`pnpm dev`，等待`dist/index.mjs`构筑完毕（本地嵌入模型可在运行时自动下载；如需提前预下载用`pnpm run download:model`，已存在则跳过）
 
-打开 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 删除里面的空数组，加入
+在 `cordis.patch.yml` 里加入
 
 ```yaml
 - insert:
@@ -58,33 +76,66 @@ dsh的"预设"分为两层，`dsh web`等同于`dsh --profile web`，调用的
 
 而`web-profile`里定义了多个"预设agent"`preset-agent` 这里主要说的是`preset-agent`的问题
 
-`preset-agent`配置里自带一个`compaction-basic`。由于配置注入的顺序是层级低的覆盖层级高的，所以`cordis.patch.yml`对`compaction-basic`的禁用不会生效
+`preset-agent`配置里自带一个`compaction-basic`。由于配置注入的顺序是层级低的覆盖层级高的，所以`cordis.patch.yml`对`compaction-basic`的禁用不会生效。
+
+此外，这个插件位于`preset-agent`的定义而非额外的安装，也无法通过`dsh plugin`卸载。
 
 解决方案：
 
+- 直接改`preset-agent`的定义(不推荐)
 - 定义不含`compaction-basic`的`preset-agent`
 - `compaction-basic`压缩阈值是80%上下文窗口，而只需要确保OM的配置中，`thresholdRatio`+`historyMergeRatio`<0.8，理论上没到强制摘要就会被OM压缩了(默认值满足这一条件)
 
 ## 插件配置项
 
-| 键                  | 默认   | 含义                                         |
-| ------------------- | ------ | -------------------------------------------- |
-| `thresholdRatio`    | `0.5`  | 观察阈值：未压缩消息 ≥ 窗口 × 该比例触发压缩 |
-| `historyMergeRatio` | `0.2`  | 反思阈值：摘要 ≥ 窗口 × 该比例触发精简合并   |
-| `compressMaxTokens` | `4096` | 单次摘要（观察/反思调用）生成上限            |
-| `tailMessageCount`  | `10`   | 压缩后保留的未压缩消息条数                   |
+| 键                  | 默认     | 含义                                                                                                          |
+| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `thresholdRatio`    | `0.5`    | 观察阈值：未压缩消息 ≥ 窗口 × 该比例触发压缩                                                                  |
+| `historyMergeRatio` | `0.2`    | 反思阈值：摘要 ≥ 窗口 × 该比例触发精简合并                                                                    |
+| `compressMaxTokens` | `4096`   | 单次摘要（观察/反思调用）生成上限                                                                             |
+| `tailMessageCount`  | `10`     | 尾部保留的不压缩消息条数（不压缩、不被替换、不进摘要日志）                                                    |
+| `modelDir`          | 打包模型 | recall-semantic 嵌入模型目录（默认插件内打包的本地模型；可指向自定义目录）。onnx 缺失时运行时自动下载到该目录 |
+| `summaryMode`       | `fork`  | 摘要模式：`fork`（缺省）/ `new` / `disable`（关闭自动压缩）；非法值在插件加载时报错（见[摘要模式](#摘要模式)） |
+| `debug`             | dev      | 压缩流程步骤级（debug）日志开关：`true` 强制开启、`false` 强制关闭；缺省按 `NODE_ENV !== 'production'` 判定（dev/test 输出，生产隐藏）。**失败日志不受此开关影响，始终输出** |
+| `recallEnabled`     | `true`  | 是否注册 `recall` 工具（`false` 时禁用，不注册）                                                                               |
+| `semanticRecallEnabled` | `true`  | 是否注册 `recall-semantic` 工具（`false` 时禁用，不注册、不触发模型下载）                                                |
+
+> 数值键（`thresholdRatio` / `historyMergeRatio` / `compressMaxTokens` / `tailMessageCount`）**不做取值区间限制**（如阈值不再限定 0.01–1）：用户提供的值按原样接受（仅校验为有限数，整数键另校验整数性），便于调试时设置任意值。
+
+### 摘要模式
+
+摘要调用由配置键 `summaryMode` 控制（缺省 `fork`；非法值在插件加载时报错）：
+
+- `fork`（缺省）：fork 会话风格——复用主会话请求前缀——`system`/`tools` 取自主会话上次请求，`messages` = 完整派生历史**从尾部之前实际截断**（尾部 `tailMessageCount` 条不注入、不进日志）+ 末尾追加指令 user 消息，充分利用 provider 前缀缓存（与宿主 `compaction-basic` 同款策略）。
+- `new`：新开会话风格——指令（persona + 规则）作为 system 提示词，只注入本次要压缩的消息作为 user 消息输入模型压缩（不注入旧压缩日志、不注入尾部）。
+- `disable`：关闭自动压缩（观察/反思均不触发；recall 工具仍由 `recallEnabled` / `semanticRecallEnabled` 独立控制）。
+
+示例（禁用 recall-semantic，保留 recall；生产环境强制输出步骤日志）：在 `cordis.patch.yml` 的插件配置中加入
+
+```yaml
+- id: dsh-plugin-om
+  config:
+    semanticRecallEnabled: false
+    debug: true
+```
+
+### 日志与摘要重试
+
+- 压缩流程（路由 / 模型容量 / 阈值判定 / 区间计算 / 摘要调用 / 提交各步）逐步输出步骤级日志（`debug` 级，dev 环境默认可见，见配置键 `debug`）。
+- 摘要调用失败（抛异常 / 空输出 / 非 `stop` 结束）均记录日志并**自动重试，总共最多尝试 3 次**；每次失败记录尝试次数与原因，重试耗尽后记录最终失败日志。失败日志不受 dev 开关影响，始终输出。
 
 ## npm 命令
 
-| 命令                        | 作用                                      |
-| --------------------------- | ----------------------------------------- |
-| `pnpm check`                | typecheck + lint + test + build           |
-| `pnpm typecheck`            | TypeScript 类型检查                       |
-| `pnpm lint` / `pnpm format` | 代码检查 / 格式化                         |
-| `pnpm test`                 | vitest 单元测试                           |
-| `pnpm build`                |                                           |
-| `pnpm dev`                  | 自动打包                                  |
-| `pnpm run release`          | CHANGELOG 归档 + 版本号更新 + 打 tag 推送 |
+| 命令                        | 作用                                                                              |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| `pnpm check`                | typecheck + lint + test + build                                                   |
+| `pnpm typecheck`            | TypeScript 类型检查                                                               |
+| `pnpm lint` / `pnpm format` | 代码检查 / 格式化                                                                 |
+| `pnpm test`                 | vitest 单元测试                                                                   |
+| `pnpm run download:model`   | 手动预下载本地嵌入模型 ONNX（已存在跳过，`--force` 重下；运行时也会按需自动下载） |
+| `pnpm build`                |                                                                                   |
+| `pnpm dev`                  | 自动打包                                                                          |
+| `pnpm run release`          | CHANGELOG 归档 + 版本号更新 + 打 tag 推送                                         |
 
 ## 调用链和文件地图
 
@@ -94,25 +145,33 @@ src/
 ├── index.ts                   # 打包入口（tsdown entry），导出 name / inject / apply
 │   apply(ctx, config) 三条主线（标注对应实现文件）：
 │   ├─ ① resolveConfig(config) ──▶ config.ts        # 配置默认值合并 + 逐键校验（留空回退默认，冻结返回）
-│   ├─ ② ctx.tools.register(buildRecallTool(() => ctx.get('toolResultPruner')))
+│   ├─ ② recallEnabled 时 ctx.tools.register(buildRecallTool(() => ctx.get('toolResultPruner')))
 │   │      └─▶ recall.ts                            # recall 工具：按 message_id 回看区间（超大结果由 pruner 裁剪）
-│   └─ ③ 事件接线（仅主会话生效）
-│        └─ ctx.on('agent/pre-step') → compress.ts  # maybeCompress：两级压缩阻塞串行（先反思后观察）
-│              ├─ reflectPass → summarize.ts        # 摘要 ≥ 窗口 × historyMergeRatio：fork 精简合并 <om-history>
-│              └─ observePass  → summarize.ts       # 未压缩消息 ≥ 窗口 × thresholdRatio：fork 观察日志 → 追加 + 替换
-├── constants.ts              # 共享常量（PLUGIN_LABEL / HISTORY_TAG / CLAIM_EVENT）
+│   ├─ ③ semanticRecallEnabled 时 ctx.tools.register(buildSemanticRecallTool({ getPruner, modelStatus, embedder }))
+│   │      └─▶ semantic-recall.ts                   # recall-semantic 工具：本地嵌入按语义检索全部消息日志（含被压缩/遮蔽）
+│   │           └─▶ embedding.ts                    # 本地 ONNX 嵌入：ensureModelReady 运行时按需下载（不阻塞/单飞）+ 懒加载 + 批量 embed + cosine
+│   │                └─▶ model-download.ts          # 模型下载原语（URL/跳过判定/原子落盘；dev CLI 复用）
+│   └─ ④ 事件接线（仅主会话生效）
+│        └─ ctx.on('agent/pre-step') → compress.ts  # maybeCompress：两级压缩阻塞串行（先反思后观察；turn 中间即可触发）
+│              ├─ reflectPass → summarize.ts        # 摘要 ≥ 窗口 × historyMergeRatio：摘要调用精简合并 <om-history>
+│              ├─ observePass  → summarize.ts       # 未压缩消息 ≥ 窗口 × thresholdRatio：摘要调用观察日志 → 追加 + 替换
+│              └─ 提交          → compress.ts        # compaction/start → summary → 替换消息(checkpoint) → end；usage 归入主会话
+├── constants.ts              # 共享常量（PLUGIN_LABEL / HISTORY_TAG / COMPACT_CHECKPOINT_PLUGIN）
 ├── types.ts                  # type-only：宿主类型再导出 + 领域类型（MessageNode / MessageIndex）
-├── config.ts                 # 配置默认值 / 校验（缺省、null、空串回退默认值）
+├── config.ts                 # 配置默认值 / 校验（缺省、null、空串回退默认值；数值键/布尔键/summaryMode/modelDir）
 ├── utils.ts                  # 零依赖工具函数（配置校验 / 文本渲染 / 主会话判定 / 路由解析）
 ├── log-index.ts              # 消息索引（message_id → 消息事件；recall 消费）
-├── summarize.ts              # 观察/反思 persona + 提示词 + fork 摘要子会话
+├── embedding.ts              # 本地 ONNX 嵌入（@huggingface/transformers + 本地模型；运行时按需下载编排 / 懒加载 / 批量 / cosine）
+├── model-download.ts          # 模型下载原语（modelSourceUrl / needsDownload / 原子落盘；运行时与 dev CLI 共用）
+├── summarize.ts              # 观察/反思 persona + 提示词 + 直连 ctx.llm.stream() 摘要（fork/new 双模式；extractSummaryLog 提取校验；流式 usage 归入主会话）
 ├── recall.ts                 # recall 工具
-└── compress.ts               # 两级自动压缩（测量 / 区间计算 / 中断扫描 / 对照表 / 替换 + 影子价格认领）
-scripts/                      # release-archive.mjs（CHANGELOG 归档）
-tests/                        # vitest 单元测试（52 例）
+├── semantic-recall.ts        # recall-semantic 工具（query 语义检索 + 区间限定 + 回退全量 + 匹配说明）
+└── compress.ts               # 两级自动压缩（测量 / mid-turn 区间计算 / 配对平衡回退 / 中断扫描 / 对照表 / source 标记判定摘要消息 / compaction/* 生命周期事件 + checkpoint 替换）
+models/
+└── paraphrase-multilingual-MiniLM-L12-v2/   # 嵌入模型目录（小文件随包分发；onnx 二进制由运行时按需下载到此处，不进 git）
+scripts/                      # release-archive.mjs（CHANGELOG 归档）/ download-model.mjs（开发手动预下载 CLI）
+tests/                        # vitest 单元测试（135 例）
+.dsh/skills/                  # 项目级 skill（feature-defect-workflow：需求/缺陷完成工作流）
 ```
 
-## 开发计划
-
-- 在消息记录/轨迹中添加OM结果
-- 将OM会话的token加入主会话中
+## TODO

package/dist/compress.d.ts

@@ -1,4 +1,5 @@
 import type { Agent, Context, PluginConfig, Session } from './types.ts';
+import { type RoutedTarget } from './utils.ts';
 /** 历史文本 token 估算：4 字符 ≈ 1 token（与宿主 dsh-token-meter 启发式一致）。 */
 export declare function estimateTextTokens(text: string): number;
 /** token 估算器的结构类型（仅需 estimateMessage；避免依赖完整 TokenMeter 接口）。 */
@@ -16,8 +17,17 @@ export declare function findLatestHistory(session: Session): {
     seq: number;
 } | undefined;
 /**
- * 观察压缩区间：尾部保留 tailCount 条消息不压缩，区间封顶在最后一个已结束 turn 的
- * 表层节点（fork seed 截断于最后一个 turn/end，当前 turn 消息不可压缩）。
+ * 判定表层节点 seq 之后的切点是否 tool-call/result 配对平衡（与宿主
+ * dsh-compaction 的 toolPairingBalancedAfter 同语义）：按表层顺序折叠未闭合的
+ * 工具调用数，处理到 seq 后计数为 0 即平衡。pre-step 时日志 call-result 完备，
+ * 该检查作为区间边界的安全网（防止把助手 tool-call 与其结果切到两侧）。
+ */
+export declare function isPairBalancedAfter(session: Session, seq: number): boolean;
+/**
+ * 观察压缩区间：pre-step 触发时日志 call-result 完备，区间不再受 turn/end 封顶——
+ * 头部 → 表层长度-1-tailCount（尾部保留 tailCount 条不压缩），当前 turn 中已完备的
+ * 消息同样可压缩；区间终点回退到 tool-call/result 配对平衡点（不切段）。
+ * lastEndSeq 仅为中断扫描提供最后一个已结束 turn 的边界（无则 -1）。
  */
 export declare function computeCompressRange(session: Session, tailCount: number): {
     start: number;
@@ -41,20 +51,20 @@ export declare function extractHistoryText(session: Session, shadowedSeqs: reado
 } | undefined;
 /**
  * message_id 对照表：遮蔽区间内消息事件按表层顺序产出 id 行（插件自产 user/message
- * 如运行时上下文快照与 <om-history> 不入表；观察子会话据此产出正确的 message_id）。
+ * 如运行时上下文快照与 <om-history> 不入表；观察摘要据此产出正确的 message_id）。
  * 按表层顺序（shadowedSeqs）扫描：与 extractHistoryText 同理，seq 区间扫描会漏。
  */
 export declare function buildMessageIdTable(session: Session, shadowedSeqs: readonly number[]): string[];
 /**
- * 反思：摘要 tokens ≥ 窗口 × historyMergeRatio 时，fork 子会话精简合并摘要，
+ * 反思：摘要 tokens ≥ 窗口 × historyMergeRatio 时，摘要调用精简合并摘要，
  * 替换单个 <om-history> 节点。失败不产生部分替换。
  */
-export declare function reflectPass(ctx: Context, agent: Agent, config: Readonly<PluginConfig>, window: number, signal?: AbortSignal): Promise<void>;
+export declare function reflectPass(ctx: Context, agent: Agent, config: Readonly<PluginConfig>, window: number, target: RoutedTarget, signal?: AbortSignal): Promise<void>;
 /**
- * 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio 时，fork 子会话把未压缩消息压缩为
+ * 观察：未压缩消息 tokens ≥ 窗口 × thresholdRatio 时，摘要调用把未压缩消息压缩为
  * 观察日志，追加到旧摘要并替换被压缩消息区间。失败不产生部分替换。
  */
-export declare function observePass(ctx: Context, agent: Agent, config: Readonly<PluginConfig>, window: number, tailCount: number, signal?: AbortSignal): Promise<void>;
+export declare function observePass(ctx: Context, agent: Agent, config: Readonly<PluginConfig>, window: number, tailCount: number, target: RoutedTarget, signal?: AbortSignal): Promise<void>;
 /**
  * 压力检查 + 两级压缩：先反思（压缩过往摘要，有必要才做），后观察（压缩新消息，
  * 有必要才做）。在 pre-step 阻塞串行执行（避免压缩失败或重复压缩）。仅主会话生效。

package/dist/compress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../src/compress.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAgB,MAAM,YAAY,CAAC;AAGtF,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAYD,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,CAAC;AAE3E;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAYzF;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS7F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CA4BxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS3C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CA6B/F;AA8CD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CA+Cf;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyBf"}
+{"version":3,"file":"compress.d.ts","sourceRoot":"","sources":["../src/compress.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EACV,KAAK,EAEL,OAAO,EACP,YAAY,EACZ,OAAO,EAIR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAgB,KAAK,YAAY,EAAsB,MAAM,YAAY,CAAC;AAEjF,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAsBD,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG;IAAE,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,CAAC;AAE3E;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAYzF;AAED,6DAA6D;AAC7D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS7F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAc1E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAyBxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAS3C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CA6B/F;AAoGD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CA+Ff;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAyIf;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,EAC9B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/dist/config.d.ts

@@ -1,18 +1,41 @@
+/**
+ * 摘要模式：
+ *  - fork（缺省）：fork 会话风格——复用主会话请求前缀（system/tools 与完整派生历史），
+ *    充分利用 provider 前缀缓存；
+ *  - new：新开会话风格——只注入本次要压缩的消息（XML 包裹），指令作为 system；
+ *  - disable：关闭自动压缩（观察/反思均不触发）。
+ */
+export type SummaryMode = 'fork' | 'new' | 'disable';
 /** 插件配置项（全部可选覆盖，未给出或留空的键用默认值）。 */
 export type PluginConfig = {
     /** 压力阈值比例：压力 ≥ 窗口 × 该比例时触发自动压缩。 */
     thresholdRatio: number;
-    /** 反思阈值比例：摘要（<om-history> 内容）≥ 窗口 × 该比例时由反思子会话精简合并。 */
+    /** 反思阈值比例：摘要（<om-history> 内容）≥ 窗口 × 该比例时由反思摘要调用精简合并。 */
     historyMergeRatio: number;
     /** 单次摘要（合并调用）生成上限（LLM maxTokens）。 */
     compressMaxTokens: number;
-    /** 压缩边界：其后不压缩消息数下限（正整数）。 */
+    /** 压缩边界：其后不压缩消息数下限（正整数，尾部保留）。 */
     tailMessageCount: number;
+    /** 摘要模式（缺省 fork；非法值在插件加载时报错）。 */
+    summaryMode: SummaryMode;
+    /** 步骤级（debug）日志开关：true 强制开启、false 强制关闭；缺省按 NODE_ENV !== 'production' 判定。 */
+    debug: boolean;
+    /** 是否注册 recall 工具（缺省 true；false 时不注册）。 */
+    recallEnabled: boolean;
+    /** 是否注册 recall-semantic 工具（缺省 true；false 时不注册、不触发模型下载）。 */
+    semanticRecallEnabled: boolean;
+    /** 语义召回嵌入模型目录（默认插件打包的本地模型；可指向自定义模型目录）。 */
+    modelDir: string;
 };
-/** 默认配置（冻结对象，resolveConfig 合并的基底）。 */
+/** 默认配置（冻结对象，resolveConfig 合并的基底；debug 缺省值在解析时按 NODE_ENV 判定）。 */
 export declare const DEFAULT_CONFIG: Readonly<PluginConfig>;
 /**
- * 解析合并配置：校验未知键与数值类型，返回冻结的完整配置。
+ * 解析摘要模式配置值：缺省 / 空串回退 fork；仅接受 'fork'/'new'/'disable'；
+ * 其余值抛错（配置错误须立即可见）。
+ */
+export declare function resolveSummaryMode(raw: unknown): SummaryMode;
+/**
+ * 解析合并配置：校验未知键与数值/字符串类型，返回冻结的完整配置。
  * 允许所有配置留空——缺省 / null / 空串的键回退默认值，未给出的键亦取默认值。
  */
 export declare function resolveConfig(raw?: unknown): Readonly<PluginConfig>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG;IACzB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,4BAA4B;IAC5B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,sCAAsC;AACtC,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,YAAY,CAKhD,CAAC;AA6BH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,CAiBnE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAErD,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG;IACzB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,WAAW,EAAE,WAAW,CAAC;IACzB,4EAA4E;IAC5E,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,aAAa,EAAE,OAAO,CAAC;IACvB,2DAA2D;IAC3D,qBAAqB,EAAE,OAAO,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,YAAY,CAUhD,CAAC;AAkCH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAK5D;AAUD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC,YAAY,CAAC,CAsCnE"}

package/dist/constants.d.ts

@@ -5,6 +5,6 @@
 export declare const PLUGIN_LABEL = "dsh-plugin-om";
 /** 压缩日志标签名：<om-history>...</om-history> 包裹观察/反思日志块。 */
 export declare const HISTORY_TAG = "om-history";
-/** 影子价格认领事件类型：token-meter 据此识别被替换（遮蔽）的表层节点。 */
-export declare const CLAIM_EVENT = "compaction/prune";
+/** 宿主压缩 checkpoint 标记的 plugin 名（dsh-compaction-basic 的 COMPACT_CHECKPOINT_MARKER.plugin）。 */
+export declare const COMPACT_CHECKPOINT_PLUGIN = "compact";
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,uCAAuC;AACvC,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAE5C,uDAAuD;AACvD,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC,+CAA+C;AAC/C,eAAO,MAAM,WAAW,qBAAqB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,uCAAuC;AACvC,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAE5C,uDAAuD;AACvD,eAAO,MAAM,WAAW,eAAe,CAAC;AAExC,6FAA6F;AAC7F,eAAO,MAAM,yBAAyB,YAAY,CAAC"}

package/dist/embedding.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 本地语义嵌入（recall-semantic 的向量引擎）。
+ *
+ * - 模型：Xenova/paraphrase-multilingual-MiniLM-L12-v2（量化 ONNX，多语言，
+ *   中英 + 代码均可处理），模型文件在 models/ 下，完全离线、零下载。
+ * - 运行时下载：模型 onnx 缺失时由 ensureModelReady 后台下载（不阻塞、单飞、
+ *   失败自动重试），下载逻辑见 model-download.ts；就绪前工具告知模型。
+ * - 懒加载：首次调用才 `import('@huggingface/transformers')` 并加载 pipeline，
+ *   插件启动不阻塞；加载结果单例缓存（resetEmbedder 供测试重置）。
+ * - 批处理：一次推理多条文本（mean pooling + L2 归一化），输出每条的向量。
+ * - 相似度：cosineSimilarity 纯函数（归一化向量点积即余弦）。
+ *
+ * 依赖说明：@huggingface/transformers 为运行时依赖（v4，dtype q8 加载
+ * model_quantized.onnx），node 侧使用 onnxruntime-node 原生绑定。
+ */
+import { EMBEDDING_MODEL_ID, type ModelFetch } from './model-download.ts';
+/** 打包模型目录：<包根>/models/<model-id>/。 */
+export declare const BUNDLED_MODEL_DIR: string;
+export { EMBEDDING_MODEL_ID };
+/** 嵌入函数类型：批量文本 → 每条一个向量（Float32Array）。 */
+export type EmbedFn = (texts: readonly string[]) => Promise<Float32Array[]>;
+/**
+ * 获取（或加载）嵌入函数。首次调用动态 import transformers 并加载本地模型；
+ * 之后复用同一 pipeline。失败时抛出可读错误（调用方自行降级）。
+ */
+export declare function getEmbedder(modelDir?: string): Promise<EmbedFn>;
+/** 重置模型单例（测试用：卸载已加载的 pipeline）。 */
+export declare function resetEmbedder(): void;
+/** 模型就绪状态：ready=本地已就绪可直接加载；downloading=缺失，后台下载中/将自动重试。 */
+export type ModelStatus = 'ready' | 'downloading';
+/**
+ * 确保模型就绪（运行时按需下载编排）。
+ * - 本地 onnx 已存在 → 'ready'（不触发下载）。
+ * - 缺失 → 启动后台下载（不阻塞，单飞）并返回 'downloading'；下载失败仅调用
+ *   warn 记录日志并结束本次尝试，下次调用会重新触发下载（自动重试）。
+ * - warn 可选：下载失败时的日志回调（默认静默；apply 注入 ctx.logger.warn）。
+ * - fetchImpl 可注入（测试传替身，默认全局 fetch）。
+ */
+export declare function ensureModelReady(modelDir?: string, warn?: (message: string) => void, fetchImpl?: ModelFetch): Promise<ModelStatus>;
+/** 重置下载状态（测试用：清空在途下载任务记录）。 */
+export declare function resetModelDownloads(): void;
+/**
+ * 两个向量的余弦相似度（向量已 L2 归一化时点积即余弦；这里兜底再归一化）。
+ * 任一向量为零向量返回 0。
+ */
+export declare function cosineSimilarity(a: Float32Array | readonly number[], b: Float32Array | readonly number[]): number;
+//# sourceMappingURL=embedding.d.ts.map

package/dist/embedding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAEL,kBAAkB,EAClB,KAAK,UAAU,EAGhB,MAAM,qBAAqB,CAAC;AAK7B,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,QAAsD,CAAC;AAErF,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAE9B,0CAA0C;AAC1C,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;AAQ5E;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,GAAE,MAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAkClF;AAED,mCAAmC;AACnC,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,GAAE,MAA0B,EACpC,IAAI,GAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,EAC1C,SAAS,CAAC,EAAE,UAAU,GACrB,OAAO,CAAC,WAAW,CAAC,CAmBtB;AAED,8BAA8B;AAC9B,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,EACnC,CAAC,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,GAClC,MAAM,CAkBR"}

package/dist/index.d.ts

@@ -4,11 +4,15 @@
  *
  * 模块：
  *  - recall.ts  recall({ start_id, end_id?, offset? }) 工具：按 message_id 回看原始会话
+ *  - semantic-recall.ts  recall-semantic({ query, top_k?, start_id?, end_id?, offset? }) 工具：
+ *    按语义在全部消息日志（含被压缩/遮蔽）中检索，返回最匹配的完整消息与匹配说明
+ *    （本地 ONNX embedding，模型随插件打包，懒加载）
  *  - compress.ts 自动压缩（OM 观察/反思两级阈值）：pre-step 阻塞串行执行——
- *    反思（摘要 ≥ 窗口 × historyMergeRatio 时 fork 精简合并 <om-history>）、
- *    观察（未压缩消息 ≥ 窗口 × thresholdRatio 时 fork 压缩为观察日志并追加）
+ *    反思（摘要 ≥ 窗口 × historyMergeRatio 时摘要调用精简合并 <om-history>）、
+ *    观察（未压缩消息 ≥ 窗口 × thresholdRatio 时摘要调用压缩为观察日志并追加）
  *
- * 约束：不引入自定义会话事件类型——压缩复用宿主已知的 'compaction/prune' 影子价格事件。
+ * 约束：不引入自定义会话事件类型——压缩复用宿主已知的 compaction/* 生命周期事件
+ * （start/summary/end）与 checkpoint 标记，结果写入消息记录与轨迹。
  * 仅主会话生效（subagent 不压缩、recall 拒绝）。
  */
 import type { Context } from './types.ts';
@@ -17,7 +21,8 @@ export declare const name = "dsh-plugin-om";
 /** 插件注入的服务依赖（tools/llm/tokenMeter/sessions），由宿主按序注入。 */
 export declare const inject: string[];
 /**
- * 插件激活入口：注册 recall 工具，并在 agent/pre-step 阻塞触发两级自动压缩
+ * 插件激活入口：注册 recall / recall-semantic 工具（由配置键 recallEnabled /
+ * semanticRecallEnabled 控制），并在 agent/pre-step 阻塞触发两级自动压缩
  * （先反思后观察）。仅主会话生效。
  */
 export declare function apply(ctx: Context, config?: unknown): void;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,6BAA6B;AAC7B,eAAO,MAAM,IAAI,kBAAkB,CAAC;AAEpC,wDAAwD;AACxD,eAAO,MAAM,MAAM,UAA6C,CAAC;AAEjE;;;GAGG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAuB1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG1C,6BAA6B;AAC7B,eAAO,MAAM,IAAI,kBAAkB,CAAC;AAEpC,wDAAwD;AACxD,eAAO,MAAM,MAAM,UAA6C,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAkD1D"}