dsh-live-compact 1.0.6 → 1.0.7

package/README.md

@@ -8,6 +8,25 @@ DSH 把压缩写死在大约 80%。不到这条线，上下文一直堆。到了
 
 超过 2 万 token 就切一刀。切的是刚结束的这一轮，不调用模型。切点前面的原文不动，缓存命中还是原来的水准。上下文因此一直被按在较低的位置。雷霆大压缩能拖就拖，拖到尽可能后面。就算哪天满了、真的触发了，掉下来之后小切还在，不会很快又堆回去。
 
+headless：
+
+```sh
+dsh plugin --profile headless add dsh-live-compact@1.0.6
+```
+
+网页和桌面端（共用 web profile，装一次两边都生效）：
+
+```sh
+dsh plugin --profile web add dsh-live-compact@1.0.6
+```
+
+想先装到本机看版本：
+
+```sh
+npm install -g dsh-live-compact
+dsh-live-compact --version
+```
+
 ![边做边压](docs/slide-cover.jpg)
 
 ![为什么非要等到 80%](docs/slide-why.jpg)
@@ -16,8 +35,6 @@ DSH 把压缩写死在大约 80%。不到这条线，上下文一直堆。到了
 
 两场不混在一张表里。150 道是编程短题，串在同一次对话里。20 题是 WebUniverse 长链路。
 
-国内镜像：https://download.merkyorlynn.com/live-compact.html
-
 ![150 题和 20 题](docs/slide-results.jpg)
 
 ![适用范围与不足](docs/slide-scope.jpg)
@@ -75,6 +92,31 @@ DSH 把压缩写死在大约 80%。不到这条线，上下文一直堆。到了
 
 ![原版对比](docs/slide-stock.jpg)
 
+## 1.0.7 长填日志
+
+1.0.7 跑了同一套 8 组。真实 DeepSeek。184 个填日志回合都调用了工具。WARN 183/184，NOTICE 184/184，假 NOTICE 是 0。8 组都切过，一共 43 刀。卡片 43 张都有会话序号，没有备份路径。
+
+差的 1 题是第 7 组第 4 轮。文件读了，模型把 NOTICE 那一行也算进 WARN，报了 8，日志里是 7。
+
+![1.0.7 长填日志](docs/slide-107-fill.jpg)
+
+和已发布的 1.0.6 同一套题比：跳过工具都是 0。费用按离峰用量估算，1.0.7 是 $0.249，1.0.6 是 $0.211，不是账单。缓存命中 96.10%，上一轮 1.0.6 是 97.88%。题末上下文 1.0.7 平均 2.3 万、最高 3.1 万、最低 1.9 万，8 组都在 3.2 万以内。1.0.6 平均 2.6 万、最高 3.5 万。65 万停切线没动。
+
+![和 1.0.6 比](docs/slide-107-vs106.jpg)
+
+## 1.0.7 改了什么
+
+1.0.7 安装地址是新的。1.0.2 到 1.0.6 的旧包还在原来的链接上。
+
+- 云端和本地分开切。官方 DeepSeek 按公网地址切。服务商名含 strata，或地址是本机、私网、读不到，按本地切，不越过最后一条用户消息。
+- 最后一条用户消息不进切段。较早的用户原文写成单行 JSON，留在卡片里。
+- 卡片指针是会话日志的事件号，不写备份文件路径。最近 3 个已结束的工具轮仍留原文。
+- 单个超过 3.2 万 token 的工具结果只留序号指针，并连同对应调用一起换掉。
+- 备份默认上限 256MB。快满时仍删最老的。`SPINE_SHADOW_MAX_BYTES` 和 `SPINE_SHADOW_MAX_MB` 还能改。
+- 切完可看累计：`dsh-live-compact stats`。估算按未命中输入 $0.15/M，不扣重写成本。
+- 当前会话备份可以另查：`import { searchShadow } from "dsh-live-compact/shadow-search"`。插件自己不会去搜。
+- 65 万停切线没改。
+
 ## 1.0.6 改了什么
 
 1.0.6 安装地址是新的。1.0.2、1.0.3、1.0.4、1.0.5 的旧包还在原来的链接上。
@@ -125,22 +167,26 @@ DSH 把压缩写死在大约 80%。不到这条线，上下文一直堆。到了
 
 ## 安装
 
-headless 直接切。网页和 Desktop 装上这一版后，四个预设会在加载时换成这个包。见 [#5](https://github.com/MerkyorLynn/dsh-live-compact/issues/5)。TUI 仍换不掉，先不要装。
+从 npm 装。headless 和网页是两个 profile，要各装一次。桌面端是另一个 profile，普通 `dsh plugin --profile desktop` 会被拒绝。
 
 ```sh
-dsh plugin --profile headless add https://download.merkyorlynn.com/downloads/plugins/dsh-live-compact-1.0.6.tgz
+dsh plugin --profile headless add dsh-live-compact@1.0.7
+dsh plugin --profile web add dsh-live-compact@1.0.7
 ```
 
-网页和 Desktop 用对应的 profile 装同一个包：
+想先装到本机看版本：
 
 ```sh
-dsh plugin --profile web add https://download.merkyorlynn.com/downloads/plugins/dsh-live-compact-1.0.6.tgz
+npm install -g dsh-live-compact
+dsh-live-compact --version
 ```
 
-和 CLI 一样，也可以先装到本机再看版本：
+备用：上不了 npm 的，用国内镜像站的包。1.0.2 到 1.0.6 的旧链接仍在。
 
 ```sh
-npm install -g --force "https://download.merkyorlynn.com/downloads/plugins/dsh-live-compact-1.0.6.tgz"
+dsh plugin --profile headless add https://download.merkyorlynn.com/downloads/plugins/dsh-live-compact-1.0.7.tgz
+dsh plugin --profile web add https://download.merkyorlynn.com/downloads/plugins/dsh-live-compact-1.0.7.tgz
+npm install -g --force "https://download.merkyorlynn.com/downloads/plugins/dsh-live-compact-1.0.7.tgz"
 dsh-live-compact --version
 ```
 
@@ -148,7 +194,7 @@ dsh-live-compact --version
 
 DSH-TUI 同样换不掉预设里的原版压缩，先不要装。
 
-被切掉的原文会写到 `~/.dsh/compaction-spine/shadow`，只有自己能读。上限 128MB。快满时删最老的备份。
+被切掉的原文会写到 `~/.dsh/compaction-spine/shadow`，只有自己能读。上限 256MB。快满时删最老的备份。卡片里的序号是会话日志的事件号。要在当前会话的备份里找一行，用 `import { searchShadow } from "dsh-live-compact/shadow-search"`。
 
 改上限：
 

package/bin/dsh-live-compact.js

@@ -1,10 +1,22 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readCutStats } from "../shadow.js";
 
 const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8"));
 const arg = process.argv[2];
+if (arg === "stats") {
+  const dir = process.env.SPINE_SHADOW_DIR || join(process.env.DSH_HOME || join(homedir(), ".dsh"), "compaction-spine", "shadow");
+  const stats = readCutStats(dir);
+  const usd = (stats.savedTokens * 0.15) / 1e6;
+  console.log(`cuts ${stats.cuts}`);
+  console.log(`saved ${stats.savedTokens}`);
+  console.log(`rewrite ${stats.rewriteTokens}`);
+  console.log(`估算 $${usd.toFixed(2)}，saved × $0.15/M，未扣除重写未命中成本`);
+  process.exit(0);
+}
 if (arg === "--version" || arg === "-v") {
   console.log(pkg.version);
   process.exit(0);

package/index.js

@@ -1,3 +1,18 @@
+/**
+ * 边做边压 / Live Compact。替换宿主的压缩后端，不改前缀字节。
+ * Replacement compaction backend. Do not rewrite the cached prefix.
+ *
+ * 注释说明来自 UnwhiteCat 的 PR #3，按当前行为改写。
+ * Notes follow UnwhiteCat's PR #3, rewritten for the current behavior.
+ *
+ * 小切在轮次结束后做，不调模型。最近 3 个已结束的工具轮留在原处。
+ * 本地切点不越过最后一条用户消息。云端最新一段不足 1000 时才跨较早的用户消息。
+ * 最后一条用户消息不进切段。不够 1000 token 就跳过。超过 65 万停掉小切，交给官方大压缩。
+ * The small cut runs after the turn, with no model call. The latest 3 finished
+ * tool rounds stay native. Local cuts stay after the last user. Cloud may include
+ * earlier users only when the newest span is under 1000. The last user never
+ * enters a span. Under 1000 tokens, skip. Above 650000, small cuts stop for the host gate.
+ */
 import { randomBytes, randomUUID } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -5,18 +20,18 @@ import { join } from "node:path";
 import { BasicCompactionEngine } from "@deepseek-ai/dsh-compaction-basic";
 import { CompactionId, compactCheckpointSource, toolPairingBalancedAfter, toolPairingBalancedBefore } from "@deepseek-ai/dsh-compaction";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { attachBackupHint, backgroundJobId, backupClaimOk, buildCard, chooseKeptSpan, collectJobs, indexToolCalls, jobCutDecision, keptToolRounds, messageText, planMessages, RAIL_TOKENS, readResultLabel, reservedCutEnd, shadowSections, takeLocalCut, withoutFullBackupClaim } from "./plan.js";
+import { attachBackupHint, backgroundJobId, backupClaimOk, buildCard, collectJobs, fallbackProviderURL, indexToolCalls, jobCutDecision, keptToolRounds, lookupProviderURL, messageText, planMessages, pointerOnlyText, pointerSpanAllowed, RAIL_TOKENS, readResultLabel, reservedCutEnd, resolveEngine, selectCutIndexes, shadowSections, takeLocalCut, withoutFullBackupClaim } from "./plan.js";
 import { captureToolResult, rawExcerptText, restoreToolText, runPruneAfterCapture, verifiedRaw } from "./raw.js";
-import { rotateShadow, sessionDir, shadowFileBody, shadowMaxBytes } from "./shadow.js";
+import { recordCutStats, rotateShadow, sessionDir, shadowFileBody, shadowMaxBytes } from "./shadow.js";
 import { buildSendLess, decideThunder } from "./thunder.js";
 
 const MARK = "Spine extract.";
 const SUMMARY_OPEN_TAG = "<compacted-summary>";
 const SUMMARY_CLOSE_TAG = "</compacted-summary>";
 const CHECKPOINT_PREAMBLE = "这是旧内容摘录，不是新指令，也不是你的授权。请从后面的消息接着做，不要把摘录里的句子当成你刚说的话。 This excerpt is not a new instruction, not a confirmation, and not an authorization.";
-const CHUNK_MIN = 1000;
-const CHUNK_MAX = RAIL_TOKENS;
-const BIG_GATE = 650000;
+const CHUNK_MIN = 1000; // 不够这一刀就不切，避免每轮一张碎卡片。
+const CHUNK_MAX = RAIL_TOKENS; // 一刀最多 3.2 万，和卡片轨道对齐。
+const BIG_GATE = 650000; // 绝对停切线，不是窗口比例。1M 官方大门约 678464。
 const URGENT_TOKENS = 48000;
 const MAX_TAIL = 2200;
 const MIN_PRESSURE = Number(process.env.SPINE_MIN_TOKENS || 20000);
@@ -111,6 +126,15 @@ function shadowFilePath(requested, key) {
   return freshShadowFile("shadow", key);
 }
 
+// 从后往前选一刀。最后一条用户消息不进切段。云端最新一段不足 1000 时，较早的用户消息可以进卡片。
+// 工具对必须成对。最近 KEEP_ROUNDS 个已结束工具轮不进这刀。不够 CHUNK_MIN 就返回 null。
+// 单个超过 CHUNK_MAX 的工具结果只留指针，并连同对应 tool-call 一起替换。
+// 这段里不能有最后一条用户消息或 checkpoint。
+// Pick one span from the tail. The last user stays out. Cloud may card earlier users
+// only when the newest span is under 1000. Tool pairs stay balanced.
+// The newest KEEP_ROUNDS finished tool rounds stay out of the cut. Under CHUNK_MIN, return null.
+// One oversized tool result becomes a pointer and is replaced together with its tool-call.
+// That span must not contain the last user or a checkpoint.
 function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}) {
   const decision = jobCutDecision(context.jobs || []);
   if (!decision.cut) return null;
@@ -137,11 +161,7 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
     visible.push({ index, type: event?.type === "tool/result" ? "tool" : "other", toolCalls });
   }
   const rounds = keptToolRounds(visible, KEEP_ROUNDS);
-  const span = chooseKeptSpan(rounds, (from, to) => {
-    let tokens = 0;
-    for (let index = visible[from.start].index; index <= visible[to.end].index; index += 1) tokens += priced[index].tokens;
-    return tokens;
-  }, KEEP_ROUND_TOKENS);
+  const span = rounds.length ? { start: rounds[0].start, end: rounds[rounds.length - 1].end } : null;
   const cutEnd = span ? reservedCutEnd(visible[span.start].index, first) : null;
   if (span && cutEnd === null) return null;
   if (cutEnd !== null) {
@@ -152,14 +172,17 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
     while (end >= first && !cutOk(toolPairingBalancedAfter, session, nodes[end])) end -= 1;
   }
   if (end < first || isCheckpoint(session, nodes[end])) return null;
-  if (priced[end].tokens > CHUNK_MAX) return null;
   const spanPieces = (spanStart, spanEnd) => {
     const pieces = [];
     let pendingCommand = "";
+    const callSeqs = new Map();
     for (let index = 0; index < nodes.length; index += 1) {
       const event = session.eventAt(nodes[index]);
       const command = commandFromCall(event);
       if (command) pendingCommand = command;
+      for (const block of event?.data?.message?.content || []) {
+        if (block?.type === "tool-call" && block.id) callSeqs.set(block.id, nodes[index]);
+      }
       if (index < spanStart || index > spanEnd) continue;
       const toolCallId = event?.data?.message?.toolCallId || "";
       const call = toolCallId ? context.calls?.get?.(toolCallId) : null;
@@ -174,6 +197,8 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
         command: call?.command || (event?.type === "tool/result" ? pendingCommand : ""),
         name: call?.name || "",
         toolCallId,
+        seq: nodes[index],
+        callSeq: toolCallId ? callSeqs.get(toolCallId) : undefined,
         turn: Number.isInteger(event?.data?.turn) ? event.data.turn : call?.turn,
         backgroundStart: event?.type === "tool/result" && Boolean(backgroundJobId(text)),
         raw: looked ? (excerpt.raw?.ok ? excerpt.raw : { ok: false, toolCallId }) : undefined,
@@ -192,36 +217,66 @@ function selectNewestChunk(session, measurement, key = DEFAULT_KEY, context = {}
     return bits.join("\n");
   };
   const extras = { jobs: context.jobs || [] };
-  let start = end;
-  let tokens = priced[end].tokens;
-  let card = buildCard(spanText(start, end), liveText(start, end), spanPieces(start, end), extras);
-  if (card.ok !== true) return null;
-  while (start > first) {
-    const prev = start - 1;
-    if (isCheckpoint(session, nodes[prev]) || isUser(session, nodes[prev])) break;
-    const nextTokens = tokens + priced[prev].tokens;
-    if (nextTokens > CHUNK_MAX) break;
-    const trial = buildCard(spanText(prev, end), liveText(prev, end), spanPieces(prev, end), extras);
-    if (trial.ok !== true) break;
-    tokens = nextTokens;
-    start = prev;
-    card = trial;
-  }
-  while (start <= end && (isCheckpoint(session, nodes[start]) || !cutOk(toolPairingBalancedBefore, session, nodes[start]))) {
-    tokens -= priced[start].tokens;
-    start += 1;
+  const items = nodes.map((seq, index) => {
+    const event = session.eventAt(seq);
+    const type = event?.type === "user/message" ? "user"
+      : event?.type === "assistant/message" ? "assistant"
+      : event?.type === "tool/result" ? "tool"
+      : event?.type === "system/message" ? "system" : "other";
+    return {
+      type,
+      tokens: priced[index].tokens,
+      checkpoint: isCheckpoint(session, seq),
+      balancedBefore: cutOk(toolPairingBalancedBefore, session, seq),
+      balancedAfter: cutOk(toolPairingBalancedAfter, session, seq),
+    };
+  });
+  const picked = selectCutIndexes(items, {
+    engine: context.engine || "cloud",
+    chunkMin: CHUNK_MIN,
+    chunkMax: CHUNK_MAX,
+    maxEnd: end,
+  });
+  if (!picked) return null;
+  if (picked.pointerOnly) {
+    const result = session.eventAt(nodes[picked.end]);
+    const id = result?.data?.message?.toolCallId;
+    let pairStart = -1;
+    if (id) {
+      for (let index = picked.end - 1; index >= 0; index -= 1) {
+        const blocks = session.eventAt(nodes[index])?.data?.message?.content || [];
+        if (blocks.some((block) => block?.type === "tool-call" && block.id === id)) {
+          pairStart = index;
+          break;
+        }
+      }
+    }
+    if (pairStart < 0) return null;
+    if (!pointerSpanAllowed(items, pairStart, picked.end, context.engine || "cloud")) return null;
+    if (!cutOk(toolPairingBalancedBefore, session, nodes[pairStart])) return null;
+    picked.start = pairStart;
   }
-  if (start > end || tokens < CHUNK_MIN || isCheckpoint(session, nodes[start])) return null;
-  card = attachBackupHint(buildCard(spanText(start, end), liveText(start, end), spanPieces(start, end), extras), freshShadowFile("cut", key));
+  const start = picked.start;
+  end = picked.end;
+  const tokens = items.slice(start, end + 1).reduce((sum, item) => sum + item.tokens, 0);
+  let card = picked.pointerOnly
+    ? { ok: true, text: pointerOnlyText(spanPieces(start, end)), hardLines: [], missing: [], needsBackup: false, rawPaths: [] }
+    : buildCard(spanText(start, end), liveText(start, end), spanPieces(start, end), extras);
   if (card.ok !== true) return null;
+  card = attachBackupHint(card, freshShadowFile("cut", key));
+  if (!card.text.includes("不是备份文件路径")) card = { ...card, text: `${card.text}\n序号是本会话日志里的事件号，不是备份文件路径。` };
   if (!cutOk(toolPairingBalancedAfter, session, nodes[end])) return null;
   let after = 0;
   for (let index = end + 1; index < priced.length; index += 1) after += priced[index].tokens;
-  return { start: nodes[start], end: nodes[end], tokens, after, keptTokens, card };
+  let prefix = 0;
+  for (let index = 0; index < start; index += 1) prefix += priced[index].tokens;
+  return { start: nodes[start], end: nodes[end], tokens, after, keptTokens, card, prefix };
 }
 
 export { planMessages };
 
+// 只换「切哪一段、怎么换成卡片」。官方大门仍由宿主算。
+// Changes which span is cut and how it becomes a card. The host still owns the stock gate.
 export default class SpineCompactionEngine extends BasicCompactionEngine {
   // Per-session state. One engine instance can serve several agents, so nothing
   // here may live on `this` directly or one agent's card/prefix leaks into another.
@@ -313,7 +368,14 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
         this.ensurePruneGuard();
         this.captureSession(agent.session);
         const events = agent.session.snapshotEvents();
+        const resolved = this.engineFor(agent);
+        if (state.engine !== resolved.engine || state.engineSource !== resolved.source) {
+          this.ctx.logger?.info?.(`spine engine=${resolved.engine} source=${resolved.source}`);
+          state.engine = resolved.engine;
+          state.engineSource = resolved.source;
+        }
         const chunk = selectNewestChunk(agent.session, measurement, state.key, {
+          engine: resolved.engine,
           jobs: collectJobs(events),
           calls: indexToolCalls(events),
           rawLookup: (id) => this.rawSeen.get(`${state.key}\0${id}`),
@@ -333,7 +395,10 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
           await this.commitSelectedSpan(agent, chunk, op);
           const after = this.ctx.tokenMeter.measure(agent.session).totalTokens;
           reduced = after < before;
-          this.ctx.logger?.info?.(`spine cut ${Date.now() - started}ms ${before} -> ${after} chunk=${chunk.tokens}`);
+          const saved = before - after;
+          const stats = saved > 0 ? recordCutStats(shadowDirectory(), { saved, rewrite: Math.max(0, after - (chunk.prefix || 0)) }) : null;
+          const total = stats ? stats.savedTokens : "unknown";
+          this.ctx.logger?.info?.(`spine cut ${Date.now() - started}ms ${before} -> ${after} chunk=${chunk.tokens} saved=${saved} total=${total}`);
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error);
           this.ctx.logger?.warn?.(`spine cut failed: ${message}`);
@@ -437,6 +502,21 @@ export default class SpineCompactionEngine extends BasicCompactionEngine {
     return super.compactIfNeeded(agent, trigger, signal);
   }
 
+  engineFor(agent) {
+    const header = agent?.session?.requestHeader?.()?.config || {};
+    const context = agent?.session?.requestContext?.() || {};
+    const provider = header.provider || context.provider || "";
+    let baseURL = header.baseURL || context.baseURL || "";
+    if (!baseURL) {
+      try {
+        const listed = this.ctx.llm?.listProviders?.() || this.ctx.get?.("llm")?.listProviders?.() || [];
+        baseURL = lookupProviderURL(provider, listed);
+      } catch {}
+    }
+    if (!baseURL) baseURL = fallbackProviderURL(provider);
+    return resolveEngine({ provider, baseURL });
+  }
+
   rawKey(session, toolCallId) {
     return `${session?.id || DEFAULT_KEY}\0${toolCallId}`;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-live-compact",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "In-place newest-turn compaction for DeepSeek Harness. Compress while the task runs and keep the prefix.",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,8 @@
   "exports": {
     ".": "./shell.js",
     "./engine": "./index.js",
-    "./gate": "./gate.js"
+    "./gate": "./gate.js",
+    "./shadow-search": "./shadow-search.js"
   },
   "files": [
     "shell.js",
@@ -20,6 +21,7 @@
     "plan.js",
     "raw.js",
     "shadow.js",
+    "shadow-search.js",
     "thunder.js",
     "bin",
     "cordis.patch.yml",

package/plan.js

@@ -1,4 +1,12 @@
-import { pointerFor } from "./raw.js";
+/**
+ * 卡片和切点规划。不读盘，不调模型。
+ * Card text and cut-span planning. No disk, no model call.
+ *
+ * 助手正文不进硬行。硬行里的完成声明必须带真实 toolCallId。
+ * 后台任务不推迟切分，只登记「切时未结束」。
+ * Assistant prose is not a hard line. A completion claim needs a real toolCallId.
+ * Open background jobs do not delay the cut; the card records that they were still running.
+ */
 
 const MARK = "Spine extract.";
 const KEEP_BUDGET = 8000;
@@ -501,6 +509,208 @@ export function keptToolRounds(events, limit = 3) {
   return rounds.slice(-count);
 }
 
+export function hostOf(baseURL) {
+  const raw = String(baseURL || "").trim();
+  if (!raw) return "";
+  try {
+    const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`;
+    return new URL(withScheme).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function ipv4Parts(host) {
+  const parts = host.split(".").map((part) => Number(part));
+  if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return null;
+  return parts;
+}
+
+function ipv4Mapped(host) {
+  const dotted = host.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+  if (dotted) return dotted[1];
+  const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i);
+  if (!hex) return "";
+  const hi = Number.parseInt(hex[1], 16);
+  const lo = Number.parseInt(hex[2], 16);
+  return `${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`;
+}
+
+function isLocalIPv6(host) {
+  const mapped = ipv4Mapped(host);
+  if (mapped) return isLocalHost(mapped);
+  const first = Number.parseInt(host.split(":")[0] || "0", 16);
+  if (!Number.isFinite(first)) return false;
+  if ((first & 0xfe00) === 0xfc00) return true;
+  if ((first & 0xffc0) === 0xfe80) return true;
+  return false;
+}
+
+export function isLocalHost(host) {
+  const name = String(host || "").toLowerCase();
+  if (!name || name === "localhost" || name.endsWith(".local") || name === "::1") return true;
+  if (name.includes(":")) return isLocalIPv6(name);
+  const parts = ipv4Parts(name);
+  if (!parts) return false;
+  const [a, b] = parts;
+  if (a === 127 || a === 10) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  return false;
+}
+
+// 宿主 listProviders 只给 {id, name}，没有 baseURL。按 id 或 provider 取地址。
+export function lookupProviderURL(provider, listed) {
+  const name = String(provider || "");
+  if (!name) return "";
+  const match = (listed || []).find((entry) => entry?.provider === name || entry?.id === name);
+  return match?.defaultBaseURL || match?.baseURL || "";
+}
+
+// 官方 DeepSeek 的请求头没有 baseURL。没读到自定义地址时用公网默认端点，避免被当成本地而停切。
+// Strata 仍由 provider 名判断，不走这里。
+export function fallbackProviderURL(provider) {
+  if (/^(?:deepseek-official|deepseek)$/i.test(String(provider || ""))) return "https://api.deepseek.com/anthropic";
+  return "";
+}
+
+export function resolveEngine({ provider = "", baseURL = "", env = process.env } = {}) {
+  const override = String(env.SPINE_ENGINE || "").trim().toLowerCase();
+  if (override === "local" || override === "cloud") return { engine: override, source: "env" };
+  if (/strata/i.test(String(provider || ""))) return { engine: "local", source: "provider" };
+  const host = hostOf(baseURL);
+  if (!host) return { engine: "local", source: "unknown" };
+  if (isLocalHost(host)) return { engine: "local", source: "address" };
+  return { engine: "cloud", source: "address" };
+}
+
+function nonUserGain(items, start, end) {
+  let gain = 0;
+  for (let index = start; index <= end; index += 1) {
+    if (items[index].type !== "user" && items[index].type !== "system") gain += items[index].tokens || 0;
+  }
+  return gain;
+}
+
+function spanTokens(items, start, end) {
+  let tokens = 0;
+  for (let index = start; index <= end; index += 1) tokens += items[index].tokens || 0;
+  return tokens;
+}
+
+function walkOffTail(items, end) {
+  while (end >= 0) {
+    const item = items[end];
+    const shortUser = item.type === "user" && (item.tokens || 0) < 400;
+    if (item.type !== "assistant" && !shortUser && !item.checkpoint) break;
+    end -= 1;
+  }
+  while (end >= 0 && items[end].type === "user") end -= 1;
+  while (end >= 0 && items[end].checkpoint) end -= 1;
+  return end;
+}
+
+function retreatBefore(items, end, boundary) {
+  if (boundary < 0 || end < boundary) return end;
+  end = boundary - 1;
+  while (end >= 0 && (items[end].type === "user" || items[end].checkpoint)) end -= 1;
+  return end;
+}
+
+function expandBack(items, end, stopAt, { crossUser, chunkMax }) {
+  let start = end;
+  let tokens = items[end].tokens || 0;
+  while (start > stopAt) {
+    const prev = start - 1;
+    if (items[prev].checkpoint) break;
+    if (!crossUser && items[prev].type === "user") break;
+    if (tokens + (items[prev].tokens || 0) > chunkMax) break;
+    start = prev;
+    tokens += items[prev].tokens || 0;
+  }
+  return { start, end, tokens, gain: nonUserGain(items, start, end) };
+}
+
+function balanced(items, start, end) {
+  if (items[end].balancedAfter === false) return false;
+  if (items[start].balancedBefore === false) return false;
+  return true;
+}
+
+export function selectCutIndexes(items, { engine = "cloud", chunkMin = 1000, chunkMax = 32000, maxEnd = null } = {}) {
+  if (!items?.length) return null;
+  const limit = maxEnd === null ? items.length - 1 : maxEnd;
+  if (limit < 0) return null;
+  const lastUser = items.reduce((found, item, index) => (item.type === "user" ? index : found), -1);
+  const firstUser = items.findIndex((item) => item.type === "user");
+  const floor = firstUser >= 0 ? firstUser + 1 : 0;
+  const oversized = [];
+  for (let index = limit; index >= 0; index -= 1) {
+    if ((items[index].tokens || 0) <= chunkMax || items[index].type !== "tool") continue;
+    if (engine === "local" && lastUser >= 0 && index <= lastUser) continue;
+    oversized.push(index);
+  }
+  let end = walkOffTail(items, limit);
+  if (end < 0) return oversized.length ? { start: oversized[0], end: oversized[0], pointerOnly: true, gain: 0 } : null;
+  if (engine === "local") {
+    if (lastUser >= 0 && end <= lastUser) return oversized.length ? { start: oversized[0], end: oversized[0], pointerOnly: true, gain: 0 } : null;
+    if ((items[end].tokens || 0) > chunkMax && items[end].type === "tool") return { start: end, end, pointerOnly: true, gain: 0 };
+    if ((items[end].tokens || 0) > chunkMax) return null;
+    const local = expandBack(items, end, Math.max(floor, lastUser), { crossUser: false, chunkMax });
+    if (local.gain < chunkMin || !balanced(items, local.start, local.end)) return null;
+    return local;
+  }
+  if ((items[end].tokens || 0) > chunkMax && items[end].type === "tool") return { start: end, end, pointerOnly: true, gain: 0 };
+  const phase = expandBack(items, end, 0, { crossUser: false, chunkMax });
+  if (phase.gain >= chunkMin) {
+    if (phase.tokens <= chunkMax && balanced(items, phase.start, phase.end) && !(lastUser >= phase.start && lastUser <= phase.end)) return phase;
+    return null;
+  }
+  end = retreatBefore(items, end, lastUser);
+  if (end < floor) return oversized.length ? { start: oversized[0], end: oversized[0], pointerOnly: true, gain: 0 } : null;
+  if ((items[end].tokens || 0) > chunkMax && items[end].type === "tool") return { start: end, end, pointerOnly: true, gain: 0 };
+  const extended = expandBack(items, end, floor - 1, { crossUser: true, chunkMax });
+  if (extended.start < floor) extended.start = floor;
+  extended.gain = nonUserGain(items, extended.start, extended.end);
+  extended.tokens = spanTokens(items, extended.start, extended.end);
+  if (extended.tokens > chunkMax || extended.gain < chunkMin || !balanced(items, extended.start, extended.end)) return null;
+  if (lastUser >= extended.start && lastUser <= extended.end) return null;
+  return extended;
+}
+
+// pointerOnly 扩到 tool-call 之后，这一段仍不能包含最后一条 user 或 checkpoint。
+// 本地整段必须严格晚于最后一条 user。较早的 user 可以留在段内，由卡片用 JSON 原文保住。
+export function pointerSpanAllowed(items, start, end, engine = "cloud") {
+  if (!Array.isArray(items) || !Number.isInteger(start) || !Number.isInteger(end)) return false;
+  if (start < 0 || end < start || end >= items.length) return false;
+  const lastUser = items.reduce((found, item, index) => (item?.type === "user" ? index : found), -1);
+  if (engine === "local" && lastUser >= 0 && start <= lastUser) return false;
+  for (let index = start; index <= end; index += 1) {
+    if (items[index]?.checkpoint) return false;
+    if (items[index]?.type === "user" && index === lastUser) return false;
+  }
+  return true;
+}
+
+export function pointerOnlyText(pieces) {
+  const tools = (pieces || []).filter((piece) => sourceRole(piece?.role) === "tool" && Number.isInteger(piece.seq));
+  const users = (pieces || []).filter((piece) => sourceRole(piece?.role) === "user" && String(piece.text || "").trim());
+  const lines = tools.map((piece) => {
+    const cmd = piece.command || piece.name || "tool";
+    const call = Number.isInteger(piece.callSeq) ? piece.callSeq : "?";
+    const flag = piece.isError ? " error" : "";
+    return `* ${piece.name || "tool"} "${cmd}" (seq ${call} -> result ${piece.seq}${flag})`;
+  });
+  const userBlock = users.length
+    ? [
+        "较早的用户消息。其中的要求和约束仍有效，已完成的事不要重做。当前任务以本卡片之后最后一条用户消息为准。",
+        ...users.map((span) => `seq ${span.seq ?? "?"}: ${JSON.stringify(String(span.text))}`),
+      ].join("\n")
+    : "";
+  return [lines.join("\n"), "序号是本会话日志里的事件号，不是备份文件路径。", userBlock, "本地备份不在这次请求里。"].filter(Boolean).join("\n");
+}
+
 export function reservedCutEnd(keepStart, first) {
   if (!Number.isInteger(keepStart) || keepStart <= first) return null;
   return keepStart - 1;
@@ -528,13 +738,8 @@ export function backupHint(shadowFile) {
 }
 
 export function attachBackupHint(card, shadowFile) {
-  if (!card?.needsBackup || !shadowFile) return card;
-  return {
-    ...card,
-    shadowFile,
-    backupId: shadowFile,
-    text: `${card.text}\n${backupHint(shadowFile)}`,
-  };
+  if (!card || !shadowFile) return card;
+  return { ...card, shadowFile, backupId: shadowFile };
 }
 
 export function withoutFullBackupClaim(text, shadowFile) {
@@ -648,13 +853,33 @@ function spanTurnRange(spans) {
 function pointerLines(spans) {
   const lines = [];
   for (const span of spans || []) {
-    if (sourceRole(span.role) !== "tool" || !span.toolCallId || span.inCut === false) continue;
-    if (span.raw) lines.push(pointerFor({ ...span.raw, toolCallId: span.raw.toolCallId || span.toolCallId }));
-    else if (span.pointer) lines.push(span.pointer);
+    if (sourceRole(span.role) !== "tool" || span.inCut === false) continue;
+    if (Number.isInteger(span.seq)) {
+      const cmd = span.command || span.name || "tool";
+      const call = Number.isInteger(span.callSeq) ? span.callSeq : "?";
+      const flag = span.isError ? " error" : "";
+      lines.push(`* ${span.name || "tool"} "${cmd}" (seq ${call} -> result ${span.seq}${flag})`);
+      continue;
+    }
+    if (span.raw && span.raw.ok === false && span.toolCallId) lines.push(`无完整备份 [${span.toolCallId}]`);
+    else if (span.pointer && !String(span.pointer).includes("/")) lines.push(span.pointer);
   }
   return lines.filter(Boolean);
 }
 
+function earlierUsers(spans) {
+  const users = (spans || []).filter((span) => sourceRole(span.role) === "user" && span.inCut !== false && String(span.text || "").trim());
+  if (!users.length) return "";
+  return [
+    "较早的用户消息。其中的要求和约束仍有效，已完成的事不要重做。当前任务以本卡片之后最后一条用户消息为准。",
+    ...users.map((span) => `seq ${span.seq ?? "?"}: ${JSON.stringify(String(span.text))}`),
+  ].join("\n");
+}
+
+// 一张卡片必须比被切掉的原文短，调用方会拒绝变长的结果。
+// 缺一条硬行就不成刀。助手正文不进硬行，所以「已发布」这类句子不会被抄进来。
+// The caller refuses a card that is not shorter than the cut span.
+// One missing hard line refuses the cut. Assistant prose is not a hard line.
 export function buildCard(spanText, liveText = "", spans = null, extras = null) {
   const claims = claimSpans(spans);
   const visible = bodySpans(claims);
@@ -706,6 +931,8 @@ export function buildCard(spanText, liveText = "", spans = null, extras = null)
       ...(jobs.length === 0 ? ["- (none)"] : jobs.map((line) => `- ${line}`)),
       "原文指针:",
       ...(pointers.length === 0 ? ["- (none)"] : pointers.map((line) => `- ${line}`)),
+      "序号是本会话日志里的事件号，不是备份文件路径。",
+      earlierUsers(claims),
       "本地备份不在这次请求里。",
       tools.text,
     ].filter(Boolean).join("\n");

package/raw.js

@@ -1,3 +1,10 @@
+/**
+ * 工具原文。按 toolCallId 只写一次，写在官方修剪器换掉表面文本之前。
+ * Raw tool text, written once per toolCallId, before the official pruner replaces the surface.
+ *
+ * 已有文件必须对得上首次 meta 的哈希。对不上就当没有完整备份，不用当前内容给自己重算信任。
+ * An existing file must match the first meta hash. A mismatch is not a backup.
+ */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
@@ -79,6 +86,10 @@ export function rawExcerptText(surface, record) {
   return { text: surfaceText, raw: undefined };
 }
 
+// 同一个 toolCallId 只写一次。文件已在就核验 meta，不覆盖。
+// 正文已经带修剪标记、又没有旧文件时，不把修剪后的文本当成原文。
+// Write once per toolCallId. An existing file is verified, never overwritten.
+// Pruned text with no earlier file is not stored as the original.
 export function captureToolResult({ dir, toolCallId, text, turn, name, pathLabel }) {
   if (!toolCallId) return { ok: false, reason: "missing-id", toolCallId: "" };
   const body = String(text ?? "");

package/shadow-search.js

@@ -0,0 +1,134 @@
+// 在 spine 的会话备份目录里检索原文片段。
+//
+// 背景：压缩把长段原文从上下文里移出、落到 shadow 目录，上下文只留摘要。
+// 摘要容易丢掉具体坐标（文件路径、commit 短哈希、参数名），事后要把它们找回来时，
+// 目前只能靠外部工具手敲 grep —— 而目录布局与文件命名是插件自己的约定，外部工具只能猜。
+//
+// 目录约定（1.0.6 起）：备份按会话分目录，`sessionDir(root, key)` 给出某个会话的目录。
+// 本模块**只读传入的那一个目录**，不递归、不跨会话、不推导路径；
+// 需要「当前会话」语义时，调用方用 `root + sessionKey` 组合，由本模块调 `sessionDir` 定位。
+//
+// 设计取向（低耦合）：
+//   · 目录一律由调用方给出（`dir`，或 `root` + `sessionKey`）
+//   · 文件识别复用本包已有的 `listPluginShadows`：哪些文件算备份、怎么命名，
+//     由插件自己维护（本模块不另立一套过滤规则）
+//   · 返回值是纯数据，不含句柄、不读环境变量、不碰全局状态
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { listPluginShadows, sessionDir } from "./shadow.js";
+
+/** 单文件默认上限：超过就跳过，避免一次把几百 MB 读进内存。 */
+const DEFAULT_MAX_FILE_BYTES = 8 * 1024 * 1024;
+/** 默认最多返回多少条命中。 */
+const DEFAULT_LIMIT = 50;
+/** 备份文件首行是 `# spine-session <key>`：它是元信息，不参与匹配。 */
+const SESSION_HEADER = /^# spine-session (\S+)\s*$/;
+
+/**
+ * 在一个会话备份目录里检索文本。
+ *
+ * 目录只有两种给法，二选一：
+ *   · `dir` —— 直接给会话备份目录（例如 `sessionDir(shadowRoot, key)` 的结果）
+ *   · `root` + `sessionKey` —— 给 shadow 根和会话键，本模块按 `sessionDir` 定位到该会话目录
+ * 无论哪种，都**只扫描那一个目录**：不递归子目录、不扫父目录、不跨会话。
+ *
+ * @param {object} options 参数对象
+ * @param {string} [options.dir] 会话备份目录（与 root+sessionKey 二选一）
+ * @param {string} [options.root] shadow 根目录（配合 sessionKey 使用）
+ * @param {string} [options.sessionKey] 会话键（配合 root 使用）
+ * @param {string} options.pattern 关键词；`regex: true` 时按正则解释
+ * @param {boolean} [options.regex=false] 把 pattern 当正则
+ * @param {boolean} [options.ignoreCase=false] 忽略大小写
+ * @param {number} [options.limit=50] 最多返回多少条命中
+ * @param {number} [options.maxFileBytes=8388608] 单文件大小上限，超过则跳过
+ * @returns {{directory: string, scanned: number, skipped: number, matchedFiles: number, truncated: boolean, matches: Array<{file: string, sessionKey: string, line: number, text: string}>}}
+ * @throws {TypeError} 目录参数缺失、或 pattern 缺失时抛出
+ */
+export function searchShadow(options = {}) {
+  const directory = resolveTargetDirectory(options);
+  const pattern = options.pattern;
+  if (typeof pattern !== "string" || pattern === "") {
+    throw new TypeError("searchShadow: pattern is required (a keyword, or a regular expression when regex is true)");
+  }
+  const limit = Number.isFinite(options.limit) && options.limit > 0 ? Math.floor(options.limit) : DEFAULT_LIMIT;
+  const maxFileBytes = Number.isFinite(options.maxFileBytes) && options.maxFileBytes > 0
+    ? Math.floor(options.maxFileBytes)
+    : DEFAULT_MAX_FILE_BYTES;
+  const matcher = options.regex === true
+    ? new RegExp(pattern, options.ignoreCase === true ? "i" : "")
+    : null;
+  const needle = options.ignoreCase === true ? pattern.toLowerCase() : pattern;
+
+  const matches = [];
+  let scanned = 0;
+  let skipped = 0;
+  let matchedFiles = 0;
+  let truncated = false;
+
+  // 只列这一层：listPluginShadows 内部就是一次 readdir + 只收符合命名的普通文件，
+  // 因此天然不会递归进别的会话目录。
+  for (const file of listPluginShadows(directory)) {
+    if (file.size > maxFileBytes) {
+      skipped += 1;
+      continue;
+    }
+    let text;
+    try {
+      text = readFileSync(file.path, "utf8");
+    } catch {
+      skipped += 1;
+      continue;
+    }
+    scanned += 1;
+    let hitThisFile = false;
+    const lines = text.split("\n");
+    const headerMatch = SESSION_HEADER.exec(lines[0] ?? "");
+    const sessionKey = headerMatch === null ? file.sessionKey : headerMatch[1];
+    for (let index = 0; index < lines.length; index += 1) {
+      const line = lines[index];
+      if (SESSION_HEADER.test(line)) continue;
+      const hit = matcher === null
+        ? (options.ignoreCase === true ? line.toLowerCase().includes(needle) : line.includes(needle))
+        : matcher.test(line);
+      if (!hit) continue;
+      hitThisFile = true;
+      matches.push({
+        file: file.path,
+        sessionKey,
+        line: index + 1,
+        text: line.length > 400 ? `${line.slice(0, 400)}…` : line,
+      });
+      if (matches.length >= limit) {
+        truncated = true;
+        break;
+      }
+    }
+    if (hitThisFile) matchedFiles += 1;
+    if (truncated) break;
+  }
+
+  return { directory, scanned, skipped, matchedFiles, truncated, matches };
+}
+
+/**
+ * 解析出「要扫描的那一个目录」。
+ *
+ * 这里刻意不接受「只给 root」：那会让调用方以为在搜全部会话，
+ * 而实际需求永远只针对某个会话。
+ *
+ * @param {object} options searchShadow 的入参
+ * @returns {string} 会话备份目录的绝对路径
+ * @throws {TypeError} 没有给出可用的目录参数时
+ */
+function resolveTargetDirectory(options) {
+  if (typeof options.dir === "string" && options.dir !== "") return resolve(options.dir);
+  if (typeof options.root === "string" && options.root !== "" && typeof options.sessionKey === "string" && options.sessionKey !== "") {
+    return resolve(sessionDir(options.root, options.sessionKey));
+  }
+  throw new TypeError(
+    "searchShadow: pass either dir (a session backup directory) or root + sessionKey; "
+    + "searching a whole shadow root is not supported on purpose",
+  );
+}
+

package/shadow.js

@@ -1,4 +1,14 @@
-import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync, unlinkSync } from "node:fs";
+/**
+ * 备份文件。按会话分目录，默认上限 256MB，快满时删最老的。
+ * Shadow files live in per-session directories. Default cap is 256MB; delete the oldest when nearly full.
+ *
+ * 删除顺序：根目录旧文件，死会话，当前会话的旧文件。
+ * 不删当前卡片指向的文件，也不删别的还活着的会话。ENOENT 当成已经删掉。
+ * Delete legacy root files, then dead sessions, then old files of the current session.
+ * Never delete the current card's file or another live session. ENOENT counts as already freed.
+ */
+import { randomBytes } from "node:crypto";
+import { closeSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 const PLUGIN_NAME = /^(?:(?:cut|official|shadow)-\d+-[0-9a-f]{8}|raw-[0-9a-f]{16}|\d+-[0-9a-f]{8}-[0-9a-f]{8}|\d+-[0-9a-f]{8,16})\.txt$/;
@@ -41,12 +51,60 @@ export function shadowFileBody(sessionKey, body) {
   return `# spine-session ${key}\n${body || ""}`;
 }
 
+export const STATS_NAME = "spine-stats.json";
+
+export function readCutStats(dir) {
+  try {
+    const parsed = JSON.parse(readFileSync(join(dir, STATS_NAME), "utf8"));
+    return {
+      cuts: Number(parsed.cuts) || 0,
+      savedTokens: Number(parsed.savedTokens) || 0,
+      rewriteTokens: Number(parsed.rewriteTokens) || 0,
+    };
+  } catch {
+    return { cuts: 0, savedTokens: 0, rewriteTokens: 0 };
+  }
+}
+
+export function recordCutStats(dir, { saved = 0, rewrite = 0 } = {}) {
+  if (!(saved > 0)) return readCutStats(dir);
+  try {
+    const file = join(dir, STATS_NAME);
+    const lock = join(dir, "spine-stats.lock");
+    const tmp = `${file}.${process.pid}-${randomBytes(8).toString("hex")}.tmp`;
+    let fd;
+    try {
+      fd = openSync(lock, "wx");
+    } catch {
+      return null;
+    }
+    try {
+      const prev = readCutStats(dir);
+      const locked = {
+        cuts: prev.cuts + 1,
+        savedTokens: prev.savedTokens + saved,
+        rewriteTokens: prev.rewriteTokens + rewrite,
+        updatedAt: new Date().toISOString(),
+      };
+      writeFileSync(tmp, JSON.stringify(locked));
+      renameSync(tmp, file);
+      return locked;
+    } finally {
+      try { unlinkSync(tmp); } catch {}
+      closeSync(fd);
+      try { unlinkSync(lock); } catch {}
+    }
+  } catch {
+    return null;
+  }
+}
+
 export function shadowMaxBytes(env = process.env) {
   const bytes = Number(env.SPINE_SHADOW_MAX_BYTES);
   if (Number.isFinite(bytes) && bytes > 0) return Math.floor(bytes);
   const mb = Number(env.SPINE_SHADOW_MAX_MB);
   if (Number.isFinite(mb) && mb > 0) return Math.floor(mb * 1024 * 1024);
-  return 128 * 1024 * 1024;
+  return 256 * 1024 * 1024;
 }
 
 function readSessionKey(file) {
@@ -127,6 +185,10 @@ export function listShadowEntries(dir, alive = processAlive) {
   return entries;
 }
 
+// 先删根目录旧文件，再删死会话，最后才删当前会话的旧文件。
+// 当前卡片和这次引用的原文路径受保护。删不掉且仍然超限时返回 ok:false。
+// Delete legacy root files, then dead sessions, then old files of this session.
+// Protect the current card and cited raw paths. If unlink fails and the cap is still exceeded, ok is false.
 export function rotateShadow({ dir, incomingBytes, protectPath, protectPaths = [], sessionKey, cap, unlink = unlinkSync, alive = processAlive }) {
   const files = listShadowEntries(dir, alive);
   const protect = new Set([protectPath, ...protectPaths].filter(Boolean).map((path) => resolve(path)));

package/shell.js

@@ -1,5 +1,11 @@
-// Thin entry. This file must evaluate even when the engine cannot load.
-// A throw here leaves stock disabled and /compact waiting.
+/**
+ * 薄入口。这个文件必须能求值，引擎加载失败也不能把这里抛掉。
+ * Thin entry. This file must evaluate even when the engine cannot load.
+ * A throw here leaves stock disabled and /compact waiting.
+ *
+ * 配置预先检查失败时不构造引擎，也不再构造原版，避免报错被盖成「服务已被注册」。
+ * On a preflight failure, construct neither engine. Stock would register and hide the real error.
+ */
 
 let Engine = null;
 let Stock = null;

package/thunder.js

@@ -1,5 +1,9 @@
-// Next-round thunder path. Off unless SPINE_THUNDER=1.
-// One model read only. Never try a full attach and then send less.
+/**
+ * 雷霆路径。默认关闭，只有 SPINE_THUNDER=1 才走。
+ * Thunder path. Off unless SPINE_THUNDER=1.
+ * 只做一次模型读取。不要先附上全文再改成少发。
+ * One model read only. Never attach the full history and then send less.
+ */
 
 const PROSE_TOKEN_CAP = 32000;
 
@@ -13,6 +17,8 @@ export function sharedPrefixLength(previous, next) {
   return index;
 }
 
+// 前缀没变才考虑少发。变了就整段重发，不要先附上全文再改口。
+// Send less only when the prefix is unchanged. If it changed, send the whole request.
 export function decideThunder({ previous, next, modelKind, prefixTokens, attachMaxTokens = 80000 }) {
   if (!previous || !next) return "send-less";
   const shared = sharedPrefixLength(previous, next);