dsh-retrace 0.4.135 → 0.4.139

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -35,7 +35,7 @@ it cannot dirty the log, and new markers create **no token-meter pairing debt**
35
35
 
36
36
  > Versions: [VERSIONS.md](./VERSIONS.md)
37
37
 
38
- > Until 0.4.135 is published, install/pin `0.4.134` (the current npm latest).
38
+ > 0.4.139 is the current release — install/pin `0.4.139` (the previous npm latest was `0.4.135`; see [VERSIONS.md](./VERSIONS.md)); the `dsh-retrace@0.4.139` examples below apply after that release.
39
39
 
40
40
  ## ⚡ One-minute install
41
41
 
@@ -151,7 +151,7 @@ The same result with plain file edits and `pnpm` — exactly the steps
151
151
  ```json
152
152
  {
153
153
  "dependencies": {
154
- "dsh-retrace": "^0.4.135"
154
+ "dsh-retrace": "^0.4.139"
155
155
  },
156
156
  "dsh": {
157
157
  "profile": {
@@ -351,12 +351,12 @@ Historical details and exact error strings live in [CHANGELOG.md](./CHANGELOG.md
351
351
  ### Upgrading
352
352
 
353
353
  ```bash
354
- dsh plugin --profile desktop add dsh-retrace@0.4.135
354
+ dsh plugin --profile desktop add dsh-retrace@0.4.139
355
355
  # then restart DSH — plugins are not hot-reloaded
356
356
  ```
357
357
 
358
- **`0.4.27` and `0.4.31` were withdrawn** (briefly published, then recalled and marked
359
- deprecated on npm). Their replacements carry every fix they had.
358
+ **`0.4.27` and `0.4.31` are marked deprecated on npm.** Their replacements carry every
359
+ fix they had.
360
360
 
361
361
  **No data migration is required.** The session format is unchanged (v3), no session is
362
362
  re-written, and nothing has to be re-indexed: upgrade, restart, and the symptoms above
@@ -375,7 +375,7 @@ whole tree down, so recover first and diagnose second:
375
375
 
376
376
  ### Pinning
377
377
 
378
- Pin an exact plugin version (`dsh-retrace@0.4.135`) and let `dsh-log-contract` resolve to
378
+ Pin an exact plugin version (`dsh-retrace@0.4.139`) and let `dsh-log-contract` resolve to
379
379
  `>=0.3.18`. Do not rely on `^0.4` across a host upgrade: compatibility here is decided by
380
380
  the **host surface**, not by semver alone.
381
381
 
package/README.zh.md CHANGED
@@ -30,7 +30,7 @@
30
30
 
31
31
  > 版本索引:[VERSIONS.md](./VERSIONS.md)
32
32
 
33
- > 0.4.135 发布前,安装/固定版本请用 `0.4.134`(当前 npm latest)。
33
+ > 0.4.139 **已发布到 npm**——安装/固定版本请用当前 npm latest `0.4.135`(见 [VERSIONS.md](./VERSIONS.md));下文的 `dsh-retrace@0.4.139` 示例在该版本发布后适用。
34
34
 
35
35
  ## ⚡ 一分钟安装
36
36
 
@@ -135,7 +135,7 @@ dsh plugin --profile <name> add dsh-retrace
135
135
  ```json
136
136
  {
137
137
  "dependencies": {
138
- "dsh-retrace": "^0.4.135"
138
+ "dsh-retrace": "^0.4.139"
139
139
  },
140
140
  "dsh": {
141
141
  "profile": {
@@ -305,12 +305,11 @@ Client 半区会依据包内 `dsh.client` 元数据被自动打包进 Web 客户
305
305
  ### 升级
306
306
 
307
307
  ```bash
308
- dsh plugin --profile desktop add dsh-retrace@0.4.135
308
+ dsh plugin --profile desktop add dsh-retrace@0.4.139
309
309
  # 然后重启 DSH —— 插件不会热重载
310
310
  ```
311
311
 
312
- **`0.4.27` 与 `0.4.31` 已撤回**(短暂发布后撤回、npm 上标记 deprecated);它们的替代版本
313
- 包含其全部修复。
312
+ **`0.4.27` 与 `0.4.31` 在 npm 上标记为 deprecated**;它们的替代版本包含其全部修复。
314
313
 
315
314
  **不需要数据迁移。** 会话格式未变(v3),不改写任何会话,也不需要重建索引:升级、重启即可。
316
315
  若宿主仍提供旧成员,兼容访问器会让那些路径继续可用 —— 本构建不丢弃老宿主。
@@ -325,7 +324,7 @@ dsh plugin --profile desktop add dsh-retrace@0.4.135
325
324
 
326
325
  ### 版本固定建议
327
326
 
328
- 请固定到确切版本(`dsh-retrace@0.4.135`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
327
+ 请固定到确切版本(`dsh-retrace@0.4.139`),并让 `dsh-log-contract` 解析到 `>=0.3.18`。
329
328
  **不要在跨宿主升级时依赖 `^0.4` 这种范围**:这里的兼容性由**宿主的面**决定,光看 semver 不够。
330
329
 
331
330
  ---
package/bin/retrace.mjs CHANGED
File without changes
@@ -0,0 +1,92 @@
1
+ /**
2
+ * dsh-retrace — lib/adapter/compaction-backend.js
3
+ *
4
+ * 注册官方 compaction 后端 = **适配器 2**。
5
+ *
6
+ * 分层
7
+ * - 业务核心(fold-summary/fold-boundary/context-level)= 载体无关纯函数,零改动;
8
+ * - 适配器 1 = retrace.fold(DSH foldSurface 主动折叠,已实现);
9
+ * - 适配器 2 = 本文件:官方 BasicCompactionEngine 子类,**自动折叠**(压力/溢出自动触发),
10
+ * 摘要 = 核心确定摘要(非 LLM)——零 LLM 调用 = 零 token 成本 + 确定性;
11
+ * - 未来平台 = 新适配器实现同一 core-contract,核心不动。
12
+ *
13
+ * 官方机制(桌面捆绑 dsh-compaction-basic,源码实读):
14
+ * - BasicCompactionEngine extends CompactionEngine(cordis Service);
15
+ * - `summarize(input, agent, signal)` 是**唯一子类定制钩子**(源码注释明示);
16
+ * - 触发(thresholdRatio 0.8 自动压力 / context-overflow 恢复)、范围(
17
+ * selectCompactableRange)、保尾(retainRatio 0.16)、装配(agent/pre-step 监听)、
18
+ * 落盘(compaction/start…end + checkpoint marker)全部继承官方;
19
+ * - 我们只把「LLM 摘要」换成「核心确定摘要」:输入 input.messages(派生消息,
20
+ * 官方 buildSummarizationInput 已按 surface 序取好)→ buildSummaryFromMessages。
21
+ *
22
+ * 装配:本文件不自动注册——由 register-compaction-backend.js 装配(opt-in)。
23
+ * ⚠️ 标准桌面宿主已装官方 compaction-basic,cordis 同名注册=拒绝,
24
+ * 插件单方不可替换 → 交付口径 = 无官方后端宿主下的确定性自动折叠(见 register 模块头)。
25
+ * 依赖(@deepseek-ai/dsh-compaction-basic)仅桌面宿主存在 → 动态 import + 降级友好:
26
+ * 找不到包/宿主未装配时创建函数返回 null,调用方静默跳过(不崩插件)。
27
+ */
28
+ import { buildSummaryFromMessages } from '../fold-summary.js'
29
+
30
+ /**
31
+ * 创建确定摘要 compaction 后端(官方 BasicCompactionEngine 子类)。
32
+ * @param {object} deps
33
+ * @param {object} deps.basic - @deepseek-ai/dsh-compaction-basic 模块(动态注入,便于测试桩)。
34
+ * @param {object} deps.buildSummary - 核心摘要函数(默认 buildSummaryFromMessages,可注入测试)。
35
+ * @param {string} [deps.summaryKind] - 摘要类型标签(日志用,默认 'retrace-deterministic')。
36
+ * @returns {Function} create(ctx, config) → 后端实例;basic 缺失时 create 返回 null。
37
+ */
38
+ export function createDeterministicCompactionBackend(deps) {
39
+ const { basic, summaryKind = 'retrace-deterministic' } = deps
40
+ if (!basic?.BasicCompactionEngine) {
41
+ return () => null // 宿主无官方 compaction-basic → 不装配(降级)
42
+ }
43
+ const { BasicCompactionEngine } = basic
44
+ // 默认核心确定摘要(消息版);可注入(测试/未来平台复用同一 create)
45
+ const summarize = typeof deps.buildSummary === 'function' ? deps.buildSummary : buildSummaryFromMessages
46
+
47
+ /** 子类:唯一覆写点 = summarize(官方源码注释:sole subclass customization hook)。 */
48
+ class DeterministicCompactionBackend extends BasicCompactionEngine {
49
+ static inject = BasicCompactionEngine.inject
50
+
51
+ /**
52
+ * 用核心确定摘要替代 LLM 摘要:input.messages(派生消息,官方已按 surface 序排好)
53
+ * → buildSummaryFromMessages → 固定模板文本块。零 LLM 调用。
54
+ * @param {object} input - { system?, tools?, messages }(官方 buildSummarizationInput)。
55
+ * @param {object} agent - 官方 agent(未用,兼容签名)。
56
+ * @param {object} signal - 官方取消信号(未用——本地纯函数瞬间完成)。
57
+ * @returns {Promise<{summary: Array<{type:'text',text:string}>, llmStreamCall:boolean, provider:string, model:string, kind:string}>}
58
+ */
59
+ async summarize(input, agent, signal) {
60
+ const messages = Array.isArray(input?.messages) ? input.messages : []
61
+ const text = summarize(messages)
62
+ if (!text || !text.trim()) {
63
+ throw new Error(`retrace deterministic compaction produced empty summary (${messages.length} messages)`)
64
+ }
65
+ return {
66
+ summary: [{ type: 'text', text }],
67
+ // rawOutput 不返回(undefined)→ 官方 commitCompactionBody 的
68
+ // callProvenance = {}(llmStreamCall!==true 且 rawOutput===undefined);空数组会
69
+ // 落盘误导性 rawOutput:[] 事件字段。
70
+ llmStreamCall: false, // 零 LLM:官方据此省略 rawOutput/usage 记账
71
+ provider: 'retrace',
72
+ model: summaryKind,
73
+ kind: summaryKind,
74
+ }
75
+ }
76
+ }
77
+
78
+ /** create(ctx, config):与官方 BasicCompactionEngine 同签名(继承其 Config 校验)。 */
79
+ return (ctx, config = {}) => {
80
+ const instance = new DeterministicCompactionBackend(ctx, {
81
+ ...config,
82
+ auto: config.auto !== false, // 默认开启自动压力触发(与官方默认一致)
83
+ })
84
+ // 实例盖静态标记,register 探测用它(不依赖 constructor.name,
85
+ // 打包压缩/宿主包装后名字不可靠)。
86
+ try { Object.defineProperty(instance, RETRACE_BACKEND_TAG, { value: true, configurable: false, enumerable: false }) } catch { /* 只读宿主实例(理论不可能)忽略 */ }
87
+ return instance
88
+ }
89
+ }
90
+
91
+ /** 实例标记(register 探测 retrace 后端用;压缩安全,不依赖类名)。 */
92
+ export const RETRACE_BACKEND_TAG = Symbol.for('dsh-retrace.compaction-backend')
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * dsh-retrace — lib/adapter/contract.js
3
3
  *
4
- * adapter layer契约——业务层与平台解耦的接口定义。
4
+ * adapter layer 契约——业务层与平台解耦的接口定义。
5
5
  * **契约运行时化**:契约不再只是 JSDoc
6
6
  * 声明——跨层边界处的形状在**运行时**被断言,违反时抛出**指名道姓**的错误
7
7
  * (哪个契约 / 期望什么 / 实际什么),不再"以奇怪方式炸"或静默通过。
@@ -214,15 +214,15 @@ export function createDshMarkerWriter({ validateMarker, log = () => {}, meter, d
214
214
  * @returns {Promise<object>} 第 2 段事件(调用方读 seq/surfaceOp)。
215
215
  */
216
216
  async writeMarker(session, span, meta) {
217
- // ── 自动收起硬阻断(最底层闸,2026-10-23 故障处置)─────────────────────
217
+ // ── 自动折叠默认关闭(最底层闸,需显式开启)─────────────────────────
218
218
  // 判定收敛在 marker-carrier.isAutoFoldSource(op='fold' 且未声明用户发起);
219
219
  // AUTOFOLD_HARD_DISABLED=true ⇒ 拒写并返回显式错误码,零落盘(审计段/载体段
220
220
  // 都不写)。拒写留一行可核日志:走注入的宿主 logger(console.log 进不了宿主
221
- // 日志,事故排障时拿不到证据)。手动 recall / edit / regenerate 与用户显式
221
+ // 日志,排障时拿不到证据)。手动 recall / edit / regenerate 与用户显式
222
222
  // 折叠(userInitiated)不受影响。
223
223
  if (AUTOFOLD_HARD_DISABLED && isAutoFoldSource(meta)) {
224
224
  log(`retrace: HARD-BLOCK 拒写自动触发的折叠 marker(AUTOFOLD_HARD_DISABLED=true):op=${String(meta?.op ?? '')} session=${String(session?.id ?? '')} targetSeq=${String(meta?.targetSeq ?? '')} span=${String(span?.start ?? '?')}..${String(span?.end ?? '?')} — 零写入`)
225
- throw editorError('autofold-hard-disabled', '自动触发的折叠已硬关(AUTOFOLD_HARD_DISABLED=true):本次 marker 零落盘;手动编辑/撤回与用户显式折叠不受影响。')
225
+ throw editorError('autofold-hard-disabled', '自动触发的折叠默认关闭(AUTOFOLD_HARD_DISABLED=true):本次 marker 零落盘;手动编辑/撤回与用户显式折叠不受影响。')
226
226
  }
227
227
  // 契约边界:业务层 → 适配器。span 不合规(空/倒置/非连续段)在这里立刻报错,
228
228
  // 不进入形状翻译——否则会写出 surfaceOp 与 sourceEventSeqs 不一致的载体
@@ -361,9 +361,9 @@ export function createDshMarkerWriter({ validateMarker, log = () => {}, meter, d
361
361
  * ② **成对审计未被绕过,而是不适用**:两段路径的成对纪律(第 1 段
362
362
  * `compaction/prune` = shadow-price claim,与第 2 段紧邻成对,见 writeMarker
363
363
  * 与 assertPairing)原样保留;本路径一条 claim 都不写 —— 回收副本不遮蔽任何
364
- * 节点,写 claim 会留下无人消费的孤儿审计行(真机事故 seq 26032/26033 的同款
364
+ * 节点,写 claim 会留下无人消费的孤儿审计行(真实会话里出现过的
365
365
  * 形态)。单段 append 无第 1 段 ⇒ 无"半对"可言;
366
- * ③ 自动收起硬阻断(AUTOFOLD_HARD_DISABLED + isAutoFoldSource)只判
366
+ * ③ 自动折叠默认关闭的闸(AUTOFOLD_HARD_DISABLED + isAutoFoldSource)只判
367
367
  * `op === 'fold'`:本写入的 op 是回收,不落在该闸上;那道闸的代码一行不动;
368
368
  * ④ 写入前过注入的 `validateMarker`(prewrite-guard 完整契约校验,信封不带 seq
369
369
  * —— 与 unhide 取消标记同规),与 marker 写入共用同一条校验链;