@240xu/dsh-message-ops 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 240xu
+
+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

@@ -0,0 +1,132 @@
+# @240xu/dsh-message-ops
+
+DSH web 插件：**消息回滚 + 消息删除 + 消息分支** 三合一。在会话头部添加分支图标按钮，
+侧栏会话行 "..." 菜单注入「消息操作」项，打开统一操作对话框：
+
+- **回滚（Revert）**：遮蔽所选消息及其后的全部可见内容（DSH 原生 surface replace 语义）。
+  日志 append-only，原事件完整保留，语境可通过重新发送恢复。
+- **删除（Delete）**：仅遮蔽所选的那一条消息，其余内容不变（同样是 surface replace）。
+- **分支（Branch）**：把所选消息（含）之前的全部事件复制为一个**新会话**，
+  新会话 header 携带 `parentSession=<原会话 id>`，原会话一个字节都不动 —— 唯一的非破坏操作。
+
+## 安装
+
+零 npm 依赖（只用 `node:fs` / `node:zlib` / `node:path` / `node:url`；zstd 压缩走
+Node 内建 `zlib.zstdCompressSync`，需 **Node ≥ 23.5**，Termux 与 Windows 通用）。
+
+```sh
+# Termux / Linux
+dsh plugin --profile web add @240xu/dsh-message-ops
+
+# Windows
+dsh plugin --profile web add @240xu/dsh-message-ops
+# 或本地目录：
+dsh plugin --profile web add file:C:/path/to/dsh-message-ops
+```
+
+重启 DSH web 实例后生效。
+
+## 安全设计
+
+- 回滚/删除不重写日志：通过一条承载 `surfaceOp: replace` 的 system 事件实现，
+  约束由 DSH 引擎 `assertProvenance` 校验，违规如实上报（HTTP 409）。
+- 回滚/删除前必须勾选风险确认；运行中的会话一律拒绝（提示先停止）。
+- 分支先写临时文件再原子 rename，半写日志不会被会话扫描读到。
+
+## 端点
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET  | `/api/message-ops/messages?sessionId=<id>` | 消息级列表（磁盘真相 + 可见性标注 + running 状态） |
+| POST | `/api/message-ops/revert`  | `{sessionId, seq}` 回滚到该条（含） |
+| POST | `/api/message-ops/delete`  | `{sessionId, seq}` 仅遮蔽该条 |
+| POST | `/api/message-ops/branch`  | `{sessionId, upToSeq}` 分支新会话，返回 `{newId, dir, keptEvents}` |
+| GET  | `/api/message-ops/export?sessionId=<id>&seq=<可选>` | 导出 Markdown（seq ≤ 上界，缺省全部），附件下载 |
+| POST | `/api/message-ops/restore` | `{sessionId, seq}` 回滚恢复：seq 为某次 revert/delete 标记事件的 seq |
+
+## 0.2.2 前端收尾（评审 M1/M2）
+
+- **M2 观察范围收窄**：侧栏行菜单注入的 `MutationObserver` 仍观察
+  `document.body`（菜单由宿主 React 动态渲染，安装期无稳定锚点），但回调改为
+  精确过滤——只有新增节点本身是（或包含）`[role=menu]` 时才调度探测；聊天流
+  渲染、流式 chunk 等海量 mutation 零探测成本；同帧多次命中合并为一次探测。
+- **M1 分批渲染**：消息列表先渲 50 条，顶部「显示更多（剩余 N 条）」按钮每次
+  渐进展开 50 条（上限仍为最近 200 条），避免 200 行单选列表一次性进 DOM；
+  打开新会话时分页重置。
+
+## 0.2.1 评审修复（架构评审 arch-review）
+
+- **P0 信任围栏**：全部 6 条 `/api/message-ops/*` 路由接入三层信任判定
+  （回环 Host 挡 DNS rebinding + `sec-fetch-site: cross-site` 拒绝 + Origin
+  同源校验），非回环/跨站请求一律 403。写操作（revert/delete/branch/restore）
+  另要求 `Content-Type: application/json`（text/plain 绕预检的洞 → 415）。
+  **为何不引入一次性 CSRF token**：浏览器对所有 POST（含 text/plain）都附带
+  Origin 头，Origin 同源校验已覆盖跨站 POST；自定义头天然触发预检、与 Origin
+  校验等价——token 只增加握手复杂度而不增加安全性，围栏已足够（论证见
+  `src/ops-core.js` 的 `isJsonContentType` 注释）。
+- **P1 写端 replace 拼写前向兼容**：`applySurfaceReplace` 写入时先按当前
+  运行时 `{startSeq,endSeq}` 形状写；若引擎报 `invalid replace surfaceOp`
+  （validateNext 在事件入 log 前抛出，无半写风险）自动降级 `{start,end}`
+  重试并记住拼写。当前与未来 dsh cohort 都不炸；读端双拼写兼容已统一收敛到
+  `session-file.readReplaceOp` 单点（computeShadowed / planRestore 共用）。
+- **P1 大日志让出**：新增 `readSessionFileAsync`，逐帧解压每 8 帧
+  `setImmediate` 让出事件循环；messages/export/restore 路由改走该路径。
+  帧数超过 500 阈值的 export 在 Markdown 末尾追加耗时提示（partial 语义，
+  内容完整无截断）。
+- **P2**：`readJsonBody` 加 1MB 上限（超限 413）；`findSessionDirs` 多
+  project slug 命中同一 id 时显式报 409 歧义而非静默取第一个；branch 产物
+  不进会话注册表——需刷新会话列表后才可见（此为宿主扫描行为，见 branch 命令
+  返回后请刷新列表）。
+
+## 0.2.0 新增
+
+### Agent 工具 `message_ops`
+
+模型侧可直接调用五操作：`action: list | revert | delete | branch | restore | export`，参数
+`sessionId`（必填）、`seq`、`upToSeq`。工具与 HTTP 路由共用同一套核心逻辑
+（`src/ops-core.js`），行为与错误语义完全一致；失败以文本形式返回，不中断回合。
+
+工具注册是**容错**的：本插件 `inject` 保持为空（tools 是可选增强而非硬依赖，
+cordis 的 inject 是硬依赖声明，缺服务会让整个插件永不加载）。apply 时探测
+`ctx.get('tools')`，有则注册；没有则通过 `ctx.inject(['tools'], …)` 等它出现；
+`@deepseek-ai/dsh-tools` 包不可解析时静默跳过工具，HTTP 面完全不受影响。
+因此 `@deepseek-ai/dsh-tools` 以 peerDependencies 形式声明（`^0.1.0-rc.6`）。
+
+### 导出 Markdown
+
+`GET /api/message-ops/export?sessionId=<id>&seq=<可选上界（含）>`，`Content-Disposition`
+附件下载。user/assistant/system 消息按角色小节展开（`## [seq N] role`），工具调用折叠为
+单行引用（含 80 字符参数摘要）；带 `parentSession` 的分支会话在头部标注来源。
+
+### 回滚恢复（restore，重放语义）
+
+`POST /api/message-ops/restore` 传 `{sessionId, seq}`，seq 指向一次 revert/delete 落定的
+标记事件（`surfaceOp: replace`、携带 `sourceEventSeqs`）。
+
+**引擎能力查证结论**（见 `src/ops-core.js` 头部注释）：安装的运行时
+`@deepseek-ai/dsh-session` 的 SurfaceOp 只有 `append` 与 `replace` 两个变体，
+**不存在「解除遮蔽」操作**——surface replace 是 append-only 的永久遮蔽。因此恢复实现为
+**重放（replay）而非解除遮蔽**：把被遮蔽区间的 user/assistant 消息文本重新 append 为新
+事件，文本加 `[恢复]` 前缀，并先 append 一条 system 说明；tool/call 等不可安全重放的事件
+跳过并在结果中计数。原遮蔽区间保持不可见（磁盘日志原样保留）。
+
+**语义差异须知**：恢复出来的消息 seq 是新的、时间戳是新的、措辞带 `[恢复]` 标记，且不是
+「回到当时」——后续上下文（中间隔着的其他对话）不会被抹掉。若想「干净地回到某点」，
+请用 branch 从该 seq 分叉。
+
+**兼容性备注**：运行时引擎当前 replace 形状为 `{op:'replace', startSeq, endSeq}`；
+dsh-src 仓库较新副本已改名为 `start`/`end`。本插件写入用 `startSeq/endSeq`（对齐安装的
+运行时），restore 读取端两种拼写都兼容，前向迁移无需改动。
+
+### 开发
+
+```sh
+npm test            # 20 个零依赖测试（node --test，Node 26 起目录参数已弃用，改用 glob）
+node --check src/*.js
+```
+
+格式兼容性已对真实会话日志验证（多帧 v3 格式；旧单帧 `session.jsonl.zstd` 读取走同一帧扫描路径）。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-message-ops bundle layer: inserts the plugin row. Row id stays stable so
+# re-adds and profile patches can target it.
+- insert:
+    - id: dsh-message-ops
+      name: '@240xu/dsh-message-ops'

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@240xu/dsh-message-ops",
+  "version": "0.2.2",
+  "description": "Roll back, branch, and export any DSH conversation — from the UI or straight from the agent via a message_ops tool. Non-destructive: logs stay append-only and recoverable. 消息回滚/删除/分支/导出四合一，内置 message_ops agent 工具；非破坏语义，日志只追加可恢复。",
+  "type": "module",
+  "license": "MIT",
+  "author": "240xu",
+  "keywords": [
+    "dsh-plugin"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/240xu/dsh-message-ops.git"
+  },
+  "files": [
+    "src/",
+    "test/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./session-file": "./src/session-file.js",
+    "./branch": "./src/branch.js",
+    "./package.json": "./package.json",
+    "./ops-core": "./src/ops-core.js"
+  },
+  "engines": {
+    "node": ">=23.5"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+  }
+}

package/src/branch.js

@@ -0,0 +1,54 @@
+/**
+ * dsh-message-ops — 消息分支（fork）：把会话从某条消息处派生为新会话。
+ *
+ * 磁盘级、零破坏：读原日志 → 过滤 seq<=upToSeq 的事件 → 以新 session id
+ * 写入同 project 目录下的新会话目录。原会话日志一个字节都不动。
+ * 新 header 携带 parentSession=<原 id>，保留 cwd / agentPreset / version，
+ * 便于溯源与 UI 关联展示。分支是本插件唯一的非破坏操作，无需风险确认。
+ * @module dsh-message-ops/branch
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { readSessionFile, encodeSessionFile, newSessionId } from "./session-file.js";
+
+/**
+ * 纯函数：从 {header, events} 规划分支产物（不碰磁盘，便于测试）。
+ * @param {{id:string, version?:number, cwd?:string, agentPreset?:string, delegationDepth?:number}} header
+ * @param {object[]} events 全部事件（含 seq）
+ * @param {number} upToSeq 保留到哪条（含）
+ * @returns {{header: object, events: object[]}} 新会话的 header 与事件
+ */
+export function planBranch(header, events, upToSeq) {
+  if (!header || header.type !== "session") throw new Error("invalid session header");
+  if (!Number.isSafeInteger(upToSeq) || upToSeq < 0) throw new Error("invalid upToSeq");
+  const kept = events.filter((e) => e && typeof e.seq === "number" && e.seq <= upToSeq);
+  if (kept.length === 0) throw new Error("no events at or before upToSeq");
+  const newHeader = {
+    ...header,
+    id: newSessionId(),
+    createdAt: Date.now(),
+    parentSession: header.id,
+  };
+  delete newHeader.isSeeded;
+  return { header: newHeader, events: kept };
+}
+
+/**
+ * 落盘：在同 project 目录下创建 <newId>/session.v3.jsonl.zstd。
+ * @returns {{newId: string, dir: string, logPath: string, keptEvents: number}}
+ */
+export function applyBranch(logPath, upToSeq) {
+  const { header, events } = readSessionFile(logPath);
+  const { header: newHeader, events: kept } = planBranch(header, events, upToSeq);
+  const dir = path.dirname(path.resolve(logPath));
+  const newDir = path.join(path.dirname(dir), newHeader.id);
+  fs.mkdirSync(newDir, { recursive: true });
+  const newLogPath = path.join(newDir, "session.v3.jsonl.zstd");
+  const buf = encodeSessionFile(newHeader, kept);
+  // 原子写：先写临时名再 rename，避免半写日志被会话扫描读到。
+  const tmpPath = newLogPath + ".tmp-messageops";
+  fs.writeFileSync(tmpPath, buf);
+  fs.renameSync(tmpPath, newLogPath);
+  return { newId: newHeader.id, dir: newDir, logPath: newLogPath, keptEvents: kept.length };
+}