dsh-ctx-trim 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlexSh1ne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# dsh-ctx-trim
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）的手动上下文压缩：**会话头部一个「上下文」按钮，两档压缩，本地摘要不调模型。**
+
+长会话涨到二十几万 token 以后，自动压缩只会把最后那条消息留下，前面全丢；你想自己决定「切到哪、留多少」，又没有入口。这个插件补的就是那个入口。
+
+![两档](icon.svg)
+
+## 装
+
+```bash
+dsh plugin --profile <你的profile> add dsh-ctx-trim
+```
+
+装完刷新页面，会话标题右边多一个「上下文」按钮。
+
+## 用
+
+点按钮 → 面板里两行数字 → 点一档 → 等它跑完。
+
+| 档位 | 保留 | 下限 | 多余的动作 |
+| --- | --- | --- | --- |
+| 正常压缩 | 最近 30% token 的原文 | 至少 6k | — |
+| 深度压缩 | 最近 10% token 的原文 | 至少 2.5k | 切下的原文打包进 `~/.dsh/im/ctxpacks/` |
+
+切点两端都收在结构边界上（不切在工具调用中间、不切在压缩标记中间），所以压完的会话还是合法的对话。
+
+## 摘要从哪来
+
+- 优先用同 profile 里 `dsh-live-compact/plan.js` 的本地摘要器（有这个插件就用，没有就跳过）；
+- 都没有时用内置摘录：每条留开头、保留硬性条款行；
+- **全程不调模型**，所以不花钱、不等生成。
+
+摘要如果没比切掉的原文更小，这次直接放弃不落盘——宁可不动，不给你写一条更长的上下文。
+
+## 它怎么做到「空闲才能压」
+
+走的是 DSH 公开的压缩事务：
+
+```
+compaction/start → compaction/summary → user/message(replace) → compaction/end → flush
+```
+
+外层套 `agent.runMaintenance`，跟正在跑的回合互斥。所以点的时候如果这一轮还没结束，会明确告诉你「这个会话正在跑…等这一轮结束再压」，不会把日志写坏。
+
+## 限制
+
+- 只在会话**空闲**时能压；回合进行中会被拒绝（这是故意的）。
+- 没有撤销按钮。被折叠的原文还在 session log 里，但界面上看不见了。
+- 只有 Web 端有按钮；保留比例是写死的两档，暂不支持自定义。
+- 不用 `ctx.compaction.compactRegion`：它写死 `owner:'current-turn'`，空闲会话上必抛 `no open turn`。
+
+## 接口
+
+宿主挂了两个路由（客户端用它，你也可以自己 curl）：
+
+```bash
+# 看一眼这个会话现在多少条、两档各会切多少
+curl "http://<host>:<port>/dsh-ctx-trim/status?sessionId=session-xxx"
+
+# 试跑（不落盘），看会切多少、摘要多大
+curl -X POST http://<host>:<port>/dsh-ctx-trim/run \
+  -H 'content-type: application/json' \
+  -d '{"sessionId":"session-xxx","mode":"normal","dry":true}'
+
+# 真压
+curl -X POST http://<host>:<port>/dsh-ctx-trim/run \
+  -H 'content-type: application/json' \
+  -d '{"sessionId":"session-xxx","mode":"deep"}'
+```
+
+只收 `application/json`，浏览器从别的站发来的跨站请求（`sec-fetch-site: cross-site`）直接 403。
+
+## 兼容
+
+- DSH `>=0.2.0-rc.2 <0.3.0-0`
+- Node `>=22.13.0`
+- 已实测：DSH 0.2.1-rc.5 + Web profile，真跑一次把 353 条 / 263k token 压到 194 条 / 127.8k token。
+
+## 许可
+
+MIT

package/client.js

@@ -0,0 +1,264 @@
+/**
+ * dsh-ctx-trim — 客户端半边。
+ *
+ * 会话头部一个「上下文」按钮，点开是两档手动压缩：正常 / 深度。
+ * 客户端这边不碰任何宿主服务（服务表里没有 commands / remote），
+ * 只做两件事：fetch 宿主路由 + 把返回的文字显示出来。
+ */
+window.__ModuleLoader__.load({
+  id: "dsh-ctx-trim",
+  factory(require) {
+    const React = require("react");
+    const h = React.createElement;
+    const NS = "dsh-ctx-trim";
+
+    const zh = {
+      button: "上下文",
+      title: "手动压缩",
+      sub: "本地摘要，不调模型",
+      loading: "读取中…",
+      now: "现在",
+      items: "条",
+      running: "这个会话正在跑，等这一轮结束再压。",
+      normal: "正常压缩",
+      normalDesc: "切掉较早一段，保留最近三成近文；切点落在结构边界上。",
+      deep: "深度压缩",
+      deepDesc: "切更大范围，只留最近一成；切下的原文打包进 im/ctxpacks/。",
+      working: "处理中…",
+      close: "关闭",
+      hint: "压缩不可撤销；会话里会留下一段压缩标记。",
+      unavailable: "读不到这个会话的状态。",
+    };
+    const en = {
+      button: "Context",
+      title: "Manual compaction",
+      sub: "Local summary, no model call",
+      loading: "Loading…",
+      now: "Now",
+      items: "items",
+      running: "This session is running — trim after the turn ends.",
+      normal: "Normal",
+      normalDesc: "Cut the older span, keep the recent third; cuts land on structural boundaries.",
+      deep: "Deep",
+      deepDesc: "Cut more, keep the last tenth; the cut text is packed into im/ctxpacks/.",
+      working: "Working…",
+      close: "Close",
+      hint: "Compaction cannot be undone; it leaves a checkpoint in the session.",
+      unavailable: "Cannot read this session's state.",
+    };
+
+    const T = {
+      wrap: { position: "relative", display: "inline-flex" },
+      trigger: {
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        height: 26,
+        padding: "0 10px",
+        borderRadius: 8,
+        border: "1px solid var(--dsw-alias-border-l2)",
+        background: "transparent",
+        color: "var(--dsw-alias-label-secondary)",
+        fontSize: 12,
+        lineHeight: 1,
+        cursor: "pointer",
+      },
+      dot: {
+        width: 6,
+        height: 6,
+        borderRadius: 999,
+        background: "var(--dsw-alias-state-business-primary, #3964fe)",
+      },
+      panel: {
+        position: "absolute",
+        left: 0,
+        top: "calc(100% + 8px)",
+        zIndex: 60,
+        width: 340,
+        padding: 16,
+        borderRadius: 14,
+        border: "1px solid var(--dsw-alias-border-l2)",
+        background: "var(--dsw-alias-bg-layer-2, #1c1c1f)",
+        boxShadow: "0 18px 48px rgba(0,0,0,.38)",
+        display: "flex",
+        flexDirection: "column",
+        gap: 10,
+        textAlign: "left",
+      },
+      head: { display: "flex", alignItems: "baseline", gap: 8 },
+      title: { fontSize: 14, fontWeight: 650, color: "var(--dsw-alias-label-primary)" },
+      sub: { fontSize: 11, color: "var(--dsw-alias-label-tertiary)" },
+      meter: { fontSize: 11.5, color: "var(--dsw-alias-label-secondary)" },
+      card: {
+        textAlign: "left",
+        border: "1px solid var(--dsw-alias-border-l2)",
+        background: "transparent",
+        borderRadius: 10,
+        padding: "10px 12px",
+        display: "flex",
+        flexDirection: "column",
+        gap: 3,
+        cursor: "pointer",
+      },
+      cardName: { fontSize: 13, fontWeight: 600, color: "var(--dsw-alias-label-primary)" },
+      cardDesc: { fontSize: 11.5, lineHeight: 1.55, color: "var(--dsw-alias-label-tertiary)" },
+      ok: { fontSize: 11.5, lineHeight: 1.5, color: "var(--dsw-alias-state-success-primary, #2ea043)" },
+      err: { fontSize: 11.5, lineHeight: 1.5, color: "var(--dsw-alias-state-error-primary, #f85149)" },
+      note: { fontSize: 11, lineHeight: 1.5, color: "var(--dsw-alias-label-tertiary)" },
+      foot: { display: "flex", justifyContent: "flex-end" },
+      close: {
+        border: "1px solid var(--dsw-alias-border-l2)",
+        background: "transparent",
+        color: "var(--dsw-alias-label-secondary)",
+        borderRadius: 8,
+        padding: "5px 14px",
+        fontSize: 12,
+        cursor: "pointer",
+      },
+    };
+
+    function formatTokens(value) {
+      if (typeof value !== "number" || !Number.isFinite(value)) return "?";
+      if (value >= 1000) return (value / 1000).toFixed(1) + "k";
+      return String(value);
+    }
+
+    function makeButton(t) {
+      return function TrimButton(props) {
+        const [open, setOpen] = React.useState(false);
+        const [info, setInfo] = React.useState(null);
+        const [loadError, setLoadError] = React.useState("");
+        const [busy, setBusy] = React.useState("");
+        const [message, setMessage] = React.useState(null);
+        const [tick, setTick] = React.useState(0);
+        const wrapRef = React.useRef(null);
+        const sessionId = props.sessionId;
+
+        React.useEffect(() => {
+          if (!open) return undefined;
+          function onDown(event) {
+            if (wrapRef.current && !wrapRef.current.contains(event.target)) setOpen(false);
+          }
+          document.addEventListener("mousedown", onDown);
+          return () => document.removeEventListener("mousedown", onDown);
+        }, [open]);
+
+        React.useEffect(() => {
+          if (!open || !sessionId) return undefined;
+          let cancelled = false;
+          setLoadError("");
+          fetch(`/dsh-ctx-trim/status?sessionId=${encodeURIComponent(sessionId)}`)
+            .then((response) => response.json())
+            .then((data) => {
+              if (cancelled) return;
+              setInfo(data);
+              if (!data || data.ok === false) setLoadError((data && data.message) || t("unavailable"));
+            })
+            .catch((error) => {
+              if (!cancelled) setLoadError(String((error && error.message) || error));
+            });
+          return () => {
+            cancelled = true;
+          };
+        }, [open, sessionId, tick]);
+
+        function run(mode) {
+          if (busy || !sessionId) return;
+          setBusy(mode);
+          setMessage(null);
+          fetch("/dsh-ctx-trim/run", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ sessionId, mode }),
+          })
+            .then((response) => response.json())
+            .then((data) => {
+              setBusy("");
+              if (data && data.ok) {
+                setMessage({ kind: "ok", text: data.message || t("done") });
+                setInfo(null);
+                setLoadError("");
+                // 压完再读一次状态，数字要对得上。
+                setTick((value) => value + 1);
+                return;
+              }
+              setMessage({ kind: "err", text: (data && data.message) || t("failed") });
+            })
+            .catch((error) => {
+              setBusy("");
+              setMessage({ kind: "err", text: String((error && error.message) || error) });
+            });
+        }
+
+        function option(key, mode) {
+          const plan = info && info.modes && info.modes[mode];
+          const line =
+            plan && !plan.error
+              ? `切掉 ${plan.cutNodes} 条 · 约 ${formatTokens(plan.cutTokens)} token`
+              : plan && plan.error
+                ? plan.error
+                : "";
+          return h(
+            "button",
+            {
+              type: "button",
+              style: T.card,
+              disabled: Boolean(busy),
+              onClick: () => run(mode),
+            },
+            h("span", { style: T.cardName }, busy === mode ? `${t(key)} ${t("working")}` : t(key)),
+            h("span", { style: T.cardDesc }, t(key + "Desc")),
+            line ? h("span", { style: T.meter }, line) : null,
+          );
+        }
+
+        const meter =
+          info && info.ok
+            ? `${t("now")} ${info.nodes} ${t("items")} · ${formatTokens(info.tokens)} token`
+            : loadError || t("loading");
+
+        return h(
+          "span",
+          { ref: wrapRef, style: T.wrap },
+          h(
+            "button",
+            {
+              type: "button",
+              style: T.trigger,
+              title: t("title"),
+              onClick: () => setOpen(!open),
+            },
+            h("span", { style: T.dot }),
+            t("button"),
+          ),
+          open
+            ? h(
+                "div",
+                { style: T.panel },
+                h("div", { style: T.head }, h("span", { style: T.title }, t("title")), h("span", { style: T.sub }, t("sub"))),
+                h("div", { style: T.meter }, meter),
+                option("normal", "normal"),
+                option("deep", "deep"),
+                message ? h("div", { style: message.kind === "ok" ? T.ok : T.err }, message.text) : null,
+                h("div", { style: T.note }, t("hint")),
+                h("div", { style: T.foot }, h("button", { type: "button", style: T.close, onClick: () => setOpen(false) }, t("close"))),
+              )
+            : null,
+        );
+      };
+    }
+
+    return {
+      inject: ["slots", "locale"],
+      apply(ctx) {
+        ctx.effect(() => ctx.locale.register(NS, { zh, en }), "ctx-trim: 词典");
+        const t = ctx.locale.bind(NS);
+        const TrimButton = makeButton(t);
+        const render = (props) => h(TrimButton, { sessionId: props.sessionId, key: props.sessionId });
+        ctx.slots.inject("conversation.session.header.actions", () =>
+          ctx.slots.register({ name: "conversation.session.header.actions", id: "ctx-trim", order: 45 }, render),
+        );
+      },
+    };
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# dsh-ctx-trim 只插入一个宿主行；客户端半边由 dsh.client 声明，不写在这个文件里。
+- insert:
+    - id: dsh-ctx-trim
+      name: 'dsh-ctx-trim'

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Context compaction">
+  <rect width="64" height="64" rx="14" fill="#1b2a4a"/>
+  <g fill="none" stroke="#7fb2ff" stroke-width="3" stroke-linecap="round">
+    <path d="M14 22h36"/>
+    <path d="M14 32h26"/>
+    <path d="M14 42h16"/>
+  </g>
+  <g stroke="#3964fe" stroke-width="4" stroke-linecap="round">
+    <path d="M40 38l6 6"/>
+    <path d="M46 38l-6 6"/>
+  </g>
+  <circle cx="52" cy="22" r="4" fill="#9ad0ff"/>
+</svg>

package/index.js

@@ -0,0 +1,540 @@
+/**
+ * dsh-ctx-trim — 宿主半边（v0.2，HTTP 路线）。
+ *
+ * 为什么走 HTTP 路由：客户端半边拿不到宿主服务（客户端服务表里只有
+ * slots / locale / theme / sessions / layout / uiWorkspace / workspaces / timer），
+ * 所以按钮只能 fetch 打一条宿主路由。这条路 dsh-meme 已经跑通。
+ *
+ * 为什么不用 ctx.compaction.compactRegion：
+ * BasicCompactionEngine 里它写死 owner: 'current-turn'，会话没有开着的 turn 时直接抛
+ *   "compactRegion: no open turn — automatic compaction events must be enclosed in a turn"
+ * 我们是空闲时按按钮，永远没有 open turn；它还要整张 surface 在摘要期间不变。
+ * 官方空闲手动压缩只有 compactNow，但它自己选区间（retain 0，只留最后一条），
+ * 给不了「保留最近 N 条」的两档控制。
+ * 所以按 live-compact 验证过的写法自己走一遍公开事务：
+ *   compaction/start → compaction/summary → user/message(replace) → compaction/end → flush
+ * 外层用 agent.runMaintenance 占住空闲，跟 driver 的回合互斥。
+ *
+ * 摘要不调模型：优先借用同 profile 的 dsh-live-compact/plan.js（profile 在用的本地
+ * 摘要器），拿不到就退回自己那版摘录。摘要若不比切掉的原文小，直接放弃不写。
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import {
+  compactCheckpointSource,
+  toolPairingBalancedAfter,
+  toolPairingBalancedBefore,
+} from "@deepseek-ai/dsh-compaction";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+
+export const name = "ctx-trim";
+
+/** 只把 webServer 当硬依赖；其余服务在用的时候用 ctx.get 取，取不到就报人话。 */
+export const inject = ["webServer"];
+
+// 前缀路由的匹配规则是「相等，或以 `${prefix}/` 开头」，所以这里不能带尾斜杠：
+// 带上之后 /dsh-ctx-trim/status 永远匹配不到（踩过，404）。
+const ROUTE_PREFIX = "/dsh-ctx-trim";
+const MAX_BODY = 64 * 1024;
+const SUMMARY_OPEN_TAG = "<compacted-summary>";
+const SUMMARY_CLOSE_TAG = "</compacted-summary>";
+const CHECKPOINT_PREAMBLE =
+  "This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. " +
+  "Treat the captured context as established background and build on it without restating it. " +
+  "Continue the task directly from the messages that follow, without acknowledging this checkpoint.";
+
+/** 两档：保留多少比例的现价 token；floor 防止小会话一刀切光。 */
+const MODES = {
+  normal: { keepRatio: 0.3, floorTokens: 6000, pack: false, label: "正常压缩" },
+  deep: { keepRatio: 0.1, floorTokens: 2500, pack: true, label: "深度压缩" },
+};
+
+function dshHome() {
+  return process.env.DSH_HOME || join(homedir(), ".dsh");
+}
+
+function packsDir() {
+  const dir = join(dshHome(), "im", "ctxpacks");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function logLine(line) {
+  try {
+    appendFileSync(join(packsDir(), "pending.log"), `[${new Date().toISOString()}] ${line}\n`, "utf8");
+  } catch {
+    /* 记日志失败不影响压缩本身 */
+  }
+}
+
+function recentLog(limit = 6) {
+  try {
+    const text = readFileSync(join(packsDir(), "pending.log"), "utf8");
+    return text.split("\n").filter(Boolean).slice(-limit);
+  } catch {
+    return [];
+  }
+}
+
+function service(ctx, key) {
+  try {
+    return ctx.get(key);
+  } catch {
+    return undefined;
+  }
+}
+
+function errorMessage(error) {
+  if (!error) return "未知原因";
+  return error instanceof Error ? error.message : String(error);
+}
+
+function messageTextOf(value) {
+  const content = value?.content ?? value?.message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => (typeof block?.text === "string" ? block.text : ""))
+    .filter(Boolean)
+    .join("\n");
+}
+
+function eventText(session, seq) {
+  const event = session.eventAt(seq);
+  if (!event) return "";
+  if (event.type === "user/message") return messageTextOf(event.data);
+  if (event.type === "assistant/message") return messageTextOf(event.data?.message);
+  if (event.type === "tool/result") return messageTextOf(event.data?.message);
+  if (event.type === "system/message") return messageTextOf(event.data?.message);
+  if (event.type === "developer/message") return messageTextOf(event.data?.message);
+  return messageTextOf(event.data);
+}
+
+function roleOf(session, seq) {
+  const type = session.eventAt(seq)?.type;
+  if (type === "assistant/message") return "assistant";
+  if (type === "tool/result") return "tool";
+  return "user";
+}
+
+function isCheckpoint(session, seq) {
+  const event = session.eventAt(seq);
+  if (!event) return false;
+  if (event.data?.source?.kind === "compact-checkpoint") return true;
+  return eventText(session, seq).includes("Spine extract.");
+}
+
+/** 有没有一次没收尾的 compaction（别的压缩正在跑就不许再下刀）。 */
+function compactionActive(session) {
+  let open = false;
+  try {
+    for (const event of session.snapshotEvents()) {
+      if (event.type === "compaction/start") open = true;
+      else if (event.type === "compaction/end") open = false;
+    }
+  } catch {
+    return false;
+  }
+  return open;
+}
+
+function safe(fn, fallback) {
+  try {
+    return fn();
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * 选区间：从尾部往前攒 token，攒够 keepTokens 就停；两端都收到结构边界上。
+ */
+function plan(session, meter, modeName) {
+  const mode = MODES[modeName] ?? MODES.normal;
+  const nodes = session.surface.nodes;
+  const measurement = meter.measure(session);
+  const priced = measurement.nodes;
+  if (nodes.length !== priced.length) {
+    return { ok: false, message: "拿不到逐条 token 计量，先不压（surface 和计量对不上）。" };
+  }
+  const first = safe(() => session.eventAt(nodes[0])?.type === "system/message", false) ? 1 : 0;
+  if (nodes.length - first < 4) return { ok: false, message: `消息太少（${nodes.length} 条），不值得压。` };
+
+  const total = measurement.totalTokens;
+  const keepTokens = Math.max(mode.floorTokens, Math.floor(total * mode.keepRatio));
+
+  let keepFrom = nodes.length;
+  let accumulated = 0;
+  for (let index = nodes.length - 1; index >= first; index -= 1) {
+    accumulated += priced[index].tokens;
+    keepFrom = index;
+    if (accumulated >= keepTokens) break;
+  }
+
+  let endIdx = keepFrom - 1;
+  let guard = 0;
+  while (endIdx >= first && guard <= nodes.length) {
+    guard += 1;
+    if (isCheckpoint(session, nodes[endIdx])) {
+      endIdx -= 1;
+      continue;
+    }
+    if (!safe(() => toolPairingBalancedAfter(session, nodes[endIdx]), true)) {
+      endIdx -= 1;
+      continue;
+    }
+    break;
+  }
+
+  let startIdx = first;
+  guard = 0;
+  while (startIdx <= endIdx && guard <= nodes.length) {
+    guard += 1;
+    if (isCheckpoint(session, nodes[startIdx])) {
+      startIdx += 1;
+      continue;
+    }
+    if (!safe(() => toolPairingBalancedBefore(session, nodes[startIdx]), true)) {
+      startIdx += 1;
+      continue;
+    }
+    break;
+  }
+
+  if (startIdx > endIdx) {
+    return { ok: false, message: "没找到能安全下刀的区间（不是切在工具调用中间，就是撞上压缩标记）。" };
+  }
+
+  const cutNodes = priced.slice(startIdx, endIdx + 1);
+  const cutSeqs = nodes.slice(startIdx, endIdx + 1);
+  const cutTokens = cutNodes.reduce((sum, node) => sum + (node?.tokens ?? 0), 0);
+  const cutHeuristic = cutNodes.reduce((sum, node) => sum + (node?.heuristicTokens ?? node?.tokens ?? 0), 0);
+
+  return {
+    ok: true,
+    mode,
+    nodes,
+    total,
+    startSeq: nodes[startIdx],
+    endSeq: nodes[endIdx],
+    cutSeqs,
+    cutTokens,
+    cutHeuristic,
+    keepNodes: nodes.length - cutSeqs.length,
+  };
+}
+
+function packSpan(sessionId, selected, spanText) {
+  if (!selected.mode.pack) return null;
+  try {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const file = join(packsDir(), `${String(sessionId).slice(-12)}-${stamp}.md`);
+    writeFileSync(
+      file,
+      `# 深度压缩：切下的原文\n\n- 会话：${sessionId}\n- 时间：${new Date().toISOString()}\n` +
+        `- 区间：${selected.startSeq} → ${selected.endSeq}（${selected.cutSeqs.length} 条，约 ${selected.cutTokens} token）\n\n---\n\n${spanText}\n`,
+      "utf8",
+    );
+    return file;
+  } catch {
+    return null;
+  }
+}
+
+let digestModule;
+async function localDigest(messages, spanText) {
+  if (digestModule === undefined) {
+    try {
+      const module = await import("dsh-live-compact/plan.js");
+      digestModule = typeof module.planMessages === "function" ? module.planMessages : null;
+    } catch {
+      digestModule = null;
+    }
+  }
+  if (digestModule) {
+    try {
+      const card = digestModule(messages);
+      if (card && typeof card.text === "string" && card.text.length > 0) return card.text;
+    } catch {
+      /* 退到自己的摘录 */
+    }
+  }
+  return fallbackDigest(messages, spanText);
+}
+
+function fallbackDigest(messages, spanText) {
+  const lines = [];
+  for (const message of messages) {
+    const text = String(message.content || "").replace(/\s+/g, " ").trim();
+    if (!text) continue;
+    lines.push(`- [${message.role}] ${text.slice(0, 220)}`);
+    if (lines.length >= 60) break;
+  }
+  return [
+    "Local extract (no model).",
+    `Shadowed characters: ${String(spanText || "").length}.`,
+    "Excerpt of the shadowed span:",
+    ...(lines.length ? lines : ["- (empty)"]),
+  ].join("\n");
+}
+
+function frameSummary(digest) {
+  return [
+    { type: "text", text: `${CHECKPOINT_PREAMBLE}\n\n${SUMMARY_OPEN_TAG}` },
+    { type: "text", text: digest },
+    { type: "text", text: SUMMARY_CLOSE_TAG },
+  ];
+}
+
+/** 真下刀：整段 append 不 await，保证 start/summary/replace/end 紧挨着。 */
+function commit(session, selected, compactionId, checkpointMessage) {
+  const lifecycle = { compactionId, turn: null };
+  const startEvent = session.append("compaction/start", lifecycle);
+  const summaryEvent = session.append("compaction/summary", {
+    compactionId,
+    summary: checkpointMessage.content,
+    shadowedRange: { start: selected.startSeq, end: selected.endSeq },
+    shadowedSeqs: [...selected.cutSeqs],
+    shadowedTokenCount: selected.cutHeuristic,
+    provider: "local",
+    model: "ctx-trim-extract",
+  });
+  session.append("user/message", checkpointMessage, {
+    surfaceOp: { op: "replace", startSeq: selected.startSeq, endSeq: selected.endSeq },
+    sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...selected.cutSeqs],
+  });
+  session.append("compaction/end", lifecycle);
+}
+
+async function runTrim(ctx, sessionId, modeName, dry) {
+  const agents = service(ctx, "agents");
+  const sessions = service(ctx, "sessions");
+  const meter = service(ctx, "tokenMeter");
+  if (!agents || typeof agents.get !== "function") return { ok: false, message: "宿主没有 agents 服务，压不了。" };
+  if (!meter || typeof meter.measure !== "function") return { ok: false, message: "宿主没有 tokenMeter 服务，压不了。" };
+
+  const agent = agents.get(sessionId);
+  if (!agent) return { ok: false, message: "这个会话不在运行（可能已归档、或由别的进程持有），压不了。" };
+  const session = agent.session;
+  if (!session) return { ok: false, message: "拿不到会话对象。" };
+  if (typeof agent.runMaintenance !== "function") return { ok: false, message: "这个 agent 不支持空闲维护，压不了。" };
+  if (compactionActive(session)) return { ok: false, message: "已经有一次压缩没收尾，先等它结束。" };
+
+  const mode = MODES[modeName] ? modeName : "normal";
+  const selected = plan(session, meter, mode);
+  if (!selected.ok) return { ok: false, message: selected.message };
+
+  // 摘要必须在事务开始前算好：事务里不能有 await。
+  const messages = selected.cutSeqs.map((seq) => ({ role: roleOf(session, seq), content: eventText(session, seq) }));
+  const spanText = messages.map((message) => message.content).join("\n\n");
+  const packFile = packSpan(sessionId, selected, spanText);
+  let digest = await localDigest(messages, spanText);
+  if (packFile) digest += `\nFull shadowed text saved to: ${packFile}`;
+
+  const compactionId = randomUUID();
+  const checkpointMessage = createUserMessage({
+    content: frameSummary(digest),
+    source: compactCheckpointSource(compactionId),
+  });
+
+  const framed = safe(() => meter.estimateMessage(checkpointMessage), 0);
+  if (framed > 0 && framed >= selected.cutTokens) {
+    return {
+      ok: false,
+      message: `摘要没比切掉的原文小（${framed} ≥ ${selected.cutTokens} token），这一刀不划算，放弃。`,
+    };
+  }
+
+  const before = selected.total;
+  // 试跑：把选区间、取原文、做摘要、估大小全走一遍，只是不落盘。
+  if (dry) {
+    return {
+      ok: true,
+      dry: true,
+      mode,
+      cutNodes: selected.cutSeqs.length,
+      cutTokens: selected.cutTokens,
+      keepNodes: selected.keepNodes,
+      before,
+      framed,
+      digestChars: digest.length,
+      digestHead: digest.slice(0, 400),
+      message: `试跑：会切掉 ${selected.cutSeqs.length} 条（约 ${selected.cutTokens} token），摘要 ${digest.length} 字 / 约 ${framed} token，保留最近 ${selected.keepNodes} 条。`,
+    };
+  }
+
+  let task;
+  try {
+    // runMaintenance 同步抛错 = agent 正忙，这一轮还在跑。
+    task = agent.runMaintenance(async (signal) => {
+      signal?.throwIfAborted?.();
+      if (compactionActive(session)) throw new Error("已经有一次压缩没收尾");
+      commit(session, selected, compactionId, checkpointMessage);
+      if (sessions && typeof sessions.flush === "function") await sessions.flush(session);
+      return true;
+    });
+  } catch (error) {
+    return { ok: false, message: `这个会话正在跑（${errorMessage(error)}），等这一轮结束再压。` };
+  }
+
+  try {
+    await task;
+  } catch (error) {
+    return { ok: false, message: `压缩失败：${errorMessage(error)}` };
+  }
+
+  const after = safe(() => meter.measure(session).totalTokens, null);
+  const message =
+    `切掉 ${selected.cutSeqs.length} 条（约 ${selected.cutTokens} token），保留最近 ${selected.keepNodes} 条。` +
+    (before != null && after != null ? `上下文 token：${before} → ${after}` : "") +
+    (packFile ? `；原文已存 ${packFile}` : "");
+  logLine(`${mode} 成功：${message}`);
+  return {
+    ok: true,
+    mode,
+    cutNodes: selected.cutSeqs.length,
+    cutTokens: selected.cutTokens,
+    before,
+    after,
+    packFile,
+    message,
+  };
+}
+
+function status(ctx, sessionId) {
+  const agents = service(ctx, "agents");
+  const meter = service(ctx, "tokenMeter");
+  const base = { ok: true, sessionId: sessionId ?? null, recent: recentLog() };
+  if (!agents || typeof agents.get !== "function" || !meter) {
+    return { ...base, ok: false, message: "宿主服务不全（agents / tokenMeter）" };
+  }
+  if (!sessionId) return { ...base, ok: false, message: "缺 sessionId" };
+  const agent = agents.get(sessionId);
+  if (!agent) return { ...base, ok: false, message: "这个会话不在运行" };
+  const session = agent.session;
+  const modes = {};
+  for (const key of Object.keys(MODES)) {
+    const value = plan(session, meter, key);
+    modes[key] = value.ok
+      ? { label: value.mode.label, cutNodes: value.cutSeqs.length, cutTokens: value.cutTokens, keepNodes: value.keepNodes }
+      : { label: MODES[key].label, error: value.message };
+  }
+  return {
+    ...base,
+    ok: true,
+    nodes: session.surface.nodes.length,
+    tokens: safe(() => meter.measure(session).totalTokens, null),
+    compacting: compactionActive(session),
+    modes,
+  };
+}
+
+function sendJson(res, statusCode, payload) {
+  const body = Buffer.from(JSON.stringify(payload), "utf8");
+  res.writeHead(statusCode, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": String(body.length),
+    "cache-control": "no-store",
+  });
+  res.end(body);
+}
+
+async function readJson(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY) throw new Error("请求体太大");
+    chunks.push(chunk);
+  }
+  if (chunks.length === 0) return {};
+  const text = Buffer.concat(chunks).toString("utf8").trim();
+  return text.length === 0 ? {} : JSON.parse(text);
+}
+
+export function apply(ctx) {
+  const webServer = ctx.webServer ?? service(ctx, "webServer");
+  // 留一行落地证据：apply 到底有没有跑、跑的时候看得到哪些服务。
+  logLine(
+    `apply: webServer=${typeof webServer?.register === "function"} agents=${typeof service(ctx, "agents")?.get === "function"} ` +
+      `sessions=${typeof service(ctx, "sessions")?.flush === "function"} meter=${typeof service(ctx, "tokenMeter")?.measure === "function"}`,
+  );
+  if (!webServer || typeof webServer.register !== "function") {
+    ctx.logger?.warn?.("ctx-trim: 没有 webServer，路由没挂上");
+    return;
+  }
+
+  const handler = async (req, res) => {
+    let url;
+    try {
+      url = new URL(req.url || "/", "http://127.0.0.1");
+    } catch {
+      sendJson(res, 400, { ok: false, message: "请求地址解析失败" });
+      return;
+    }
+
+    // 这两个接口能改会话，所以挡掉「别的网页发起的跨站请求」；
+    // 浏览器同源是 same-origin，直接 curl 没有这个头（本机调试要用）。
+    const site = String(req.headers["sec-fetch-site"] || "").toLowerCase();
+    if (site && site !== "same-origin" && site !== "none") {
+      sendJson(res, 403, { ok: false, message: "只接受同源请求" });
+      return;
+    }
+
+    if (url.pathname === `${ROUTE_PREFIX}/status`) {
+      if (req.method !== "GET") {
+        res.writeHead(405, { allow: "GET" });
+        res.end();
+        return;
+      }
+      try {
+        sendJson(res, 200, status(ctx, url.searchParams.get("sessionId") || undefined));
+      } catch (error) {
+        sendJson(res, 500, { ok: false, message: errorMessage(error) });
+      }
+      return;
+    }
+
+    if (url.pathname === `${ROUTE_PREFIX}/run`) {
+      if (req.method !== "POST") {
+        res.writeHead(405, { allow: "POST" });
+        res.end();
+        return;
+      }
+      // 只收 JSON：跨站表单发不出这个 content-type，顺手挡掉一半 CSRF。
+      const contentType = String(req.headers["content-type"] || "").toLowerCase();
+      if (!contentType.startsWith("application/json")) {
+        sendJson(res, 415, { ok: false, message: "只收 application/json" });
+        return;
+      }
+      try {
+        const body = await readJson(req);
+        const sessionId = typeof body.sessionId === "string" ? body.sessionId : "";
+        const mode = typeof body.mode === "string" ? body.mode : "normal";
+        if (!sessionId) {
+          sendJson(res, 400, { ok: false, message: "缺 sessionId" });
+          return;
+        }
+        const result = await runTrim(ctx, sessionId, mode, body.dry === true);
+        sendJson(res, result.ok ? 200 : 409, result);
+      } catch (error) {
+        sendJson(res, 400, { ok: false, message: errorMessage(error) });
+      }
+      return;
+    }
+
+    sendJson(res, 404, { ok: false, message: "没有这个接口" });
+  };
+
+  ctx.effect(
+    () =>
+      webServer.register({
+        kind: "prefix",
+        path: ROUTE_PREFIX,
+        handler,
+      }),
+    "ctx-trim: /dsh-ctx-trim 路由",
+  );
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Manual Context Compaction",
+    "description": "Adds a Context button to the session header: two levels of manual compaction with a local summary, no model call."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "手动上下文压缩",
+    "description": "会话头部加一个「上下文」按钮：两档手动压缩，本地摘要不调模型。"
+  }
+}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "dsh-ctx-trim",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "会话头部一键手动压缩上下文：正常 / 深度两档，本地摘要不调模型，切点落在结构边界上。Manual context compaction for DeepSeek Harness with two levels and a local summary.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "dsh": ">=0.2.0-rc.2 <0.3.0-0",
+    "node": ">=22.13.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-compaction": ">=0.2.0-rc.2 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.2 <0.3.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-compaction": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    }
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "context",
+    "compaction",
+    "context-window",
+    "token",
+    "compress"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexSh1ne/dsh-ctx-trim.git"
+  },
+  "homepage": "https://github.com/AlexSh1ne/dsh-ctx-trim#readme",
+  "bugs": {
+    "url": "https://github.com/AlexSh1ne/dsh-ctx-trim/issues"
+  },
+  "author": "AlexSh1ne",
+  "license": "MIT"
+}