dsh-topic-split 0.0.0-stage → 0.12.0

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
@@ -1,3 +1,418 @@
1
- # Temporary Holding Version
1
+ # dsh-topic-split
2
2
 
3
- 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.
3
+ 从长会话中按主题或任意轮次挑选内容,导出为可继续的独立会话;支持覆盖率核对、导出后剪除并归档。控件在输入框上方,不是分屏插件。
4
+
5
+ ## 能力
6
+
7
+ | 位置 | 名称 | 说明 |
8
+ |---|---|---|
9
+ | Host | `session_topics` | 自动分主题(`mode=auto/model/keyword`),输出轮次区间 + 字数 + 覆盖率校验 |
10
+ | Host | `session_export` | 按轮次导出成「一问一答」结构的独立会话;`ranges` 连续区间(`0-51,52-87`)或 `turns` 任意轮次集合(`3,7-9,20`);`dryRun=true` 只预览不写盘;`cut=true` 导出后把选中轮次从源会话剪掉 |
11
+ | Host | `session_coverage` | 核对「选中 + 排除」是否等于原会话总量(轮次与字数双维度) |
12
+ | Host | `session_diag` | 自检:路径、配置、缓存、判断模型与开关状态 |
13
+ | Host | `session_cut` | 把选中轮次从会话中剪掉:用剩余轮次重建新会话;`ranges` 或 `turns`;默认预览,`archive=true` 归档原会话 |
14
+ | Client | 「拆分 / Split」控件 | 注册在 `conversation.input.dock`(输入框上方);React 组件 + `ctx.locale` + 主题 token;点击打开六步面板:选会话 → 分段 → 勾选 → 手输区间/轮次 → 分组 → 预览/导出(可剪除) |
15
+ | HTTP | `/dsh-topic-split/*` | 面板接口:默认启用,需令牌、仅限本机、带限流;`httpRoutes: 'off'` 可完全关闭 |
16
+
17
+ ## 安装
18
+
19
+ 在 DSH 中打开 **Plugins → Add plugin**,选择本目录(本地开发)或包名 `dsh-topic-split`。
20
+ 官方安装路径会完成依赖、bundle 选择、兼容性检查与 build 审批,**不要手工改 profile 的 `package.json`**。
21
+
22
+ 安装并重启后,会话输入框上方会出现「拆分 / Split」控件。
23
+
24
+ > 仓库里的 `scripts/install.ps1` / `uninstall.ps1` 只用于本地开发调试,**不随 npm 包发布**,也不建议普通用户使用。
25
+
26
+ ## 配置
27
+
28
+ `apply(ctx, config)` 接受配置对象,与默认值合并后校验;非法值启动即报错并跳过注册。
29
+
30
+ | 键 | 默认 | 说明 |
31
+ |---|---|---|
32
+ | `maxCompressedBytes` | 80 MB | 会话文件压缩态上限 |
33
+ | `maxInflatedBytes` | 300 MB | 解析后内存上限 |
34
+ | `cacheEntries` | 8 | 解析缓存条数 |
35
+ | `minSegmentTurns` / `minSegmentChars` | 3 / 4000 | 主题平滑阈值 |
36
+ | `maxRanges` | 50 | 单次导出区间上限 |
37
+ | `topics` | 内置 7 组 | `[[标签, 正则字符串], …]`,模型不可用时的回退规则 |
38
+ | `semantic.backend` | `auto` | `auto` / `kernel` / `http` / `off` |
39
+ | `semantic.provider` / `model` | `deepseek-official` / `deepseek-flash` | kernel 后端用的路由 |
40
+ | `semantic.timeoutMs` | 25000 | 单次判断超时 |
41
+ | `semantic.retries` | 1 | 校验失败后的重试次数 |
42
+ | `semantic.summaryChars` | 120 | 每轮摘要字数预算 |
43
+ | `semantic.httpBaseUrl` / `httpModel` | 空 | OpenAI 兼容端点(`/chat/completions`) |
44
+ | `semantic.httpKeyEnv` | `DSH_SESSION_SPLIT_JUDGE_KEY` | 存放密钥的环境变量名 |
45
+ | `httpRoutes` | `token` | `token` / `off`:面板 HTTP 路由;`off` 时完全不注册接口 |
46
+ | `httpToken` | 空 | 面板访问令牌;留空则进程内随机生成并注入页面(推荐) |
47
+ | `httpRateLimitPerMin` | 60 | 普通请求每分钟上限 |
48
+ | `httpExportPerMin` | 6 | 导出请求每分钟上限 |
49
+ | `exposeTitles` | `true` | 面板会话列表是否返回标题(仅在令牌通过后可见) |
50
+
51
+ ## 安全模式(HTTP 面板)
52
+
53
+ **默认启用,但需要令牌**:令牌默认由进程随机生成(不写盘、不写日志、不进配置),
54
+ 只在通过 DSH 鉴权的 `index.html` 里以 `<meta name="dsh-split-token">` 注入,
55
+ 客户端读取后附加 `x-dsh-split-token` 请求头。
56
+
57
+ 因此默认体验是:面板开箱可用;未授权请求一律 `401`;非本机来源一律 `403`。
58
+
59
+ 想完全关闭面板(只留 5 个 agent 工具):
60
+
61
+ ```json
62
+ { "httpRoutes": "off" }
63
+ ```
64
+
65
+ 或环境变量:
66
+
67
+ ```powershell
68
+ $env:DSH_SESSION_SPLIT_HTTP = 'off'
69
+ ```
70
+
71
+ 想固定令牌(例如某些代理场景):
72
+
73
+ ```powershell
74
+ $env:DSH_SESSION_SPLIT_HTTP_TOKEN = '自己的一串随机字符'
75
+ ```
76
+
77
+ 保护层次(全部默认生效):
78
+
79
+ | 保护 | 行为 |
80
+ |---|---|
81
+ | 令牌 | 缺失/错误 → `401`;常量时间比较;支持 `x-dsh-split-token` 与 `Bearer` |
82
+ | Host | 只接受 `127.0.0.1` / `localhost` / `::1`,其余 `403`(防 DNS rebinding) |
83
+ | 连接来源 | 只接受本机 socket 地址,`PEER_NOT_ALLOWED` 拒绝局域网连接 |
84
+ | Origin | 只接受本机来源,跨站 `403` |
85
+ | `Sec-Fetch-Site` | `cross-site` / `same-site` → `403` |
86
+ | 限流 | 普通 60 次/分,导出 6 次/分,超出 `429` |
87
+ | 标题 | 默认返回,但只在令牌通过后可见;可 `exposeTitles: false` 关闭 |
88
+ | 诊断 | HTTP 接口返回的诊断隐藏主机名与本机路径 |
89
+ | 网络边界 | 只监听 DSH 自身绑定地址;不要用 `--host` 把 DSH 暴露到局域网/公网 |
90
+
91
+ **令牌怎么给到页面**:服务端在 `index.html` 的 `</head>` 前注入 meta,
92
+ 只有通过 DSH 自身鉴权的页面(`/` 与 `/index.html` 无 token 均为 401)才能拿到它。
93
+ 若宿主版本不支持 `tapIndex`,可手动在控制台执行:
94
+
95
+ ```js
96
+ localStorage.setItem('dsh-split-token', '你的令牌')
97
+ ```
98
+
99
+ ## 会话登记
100
+
101
+ 新建会话后需要登记到 DSH 的 workspace,才会出现在侧边栏:
102
+
103
+ - 优先调用 DSH 的 `workspaceRegistry` 服务(`attachSession` / `detachSession`)
104
+ - 服务不可用时回退文件写入,但会**先备份、后回读校验、失败回滚**,且只增删目标 id
105
+ - 不整份覆盖 `workspace.json`,避免与 DSH 内存快照互相覆盖
106
+
107
+ ## 剪除(session_cut)
108
+
109
+ DSH 会话是 append-only 事件日志,**不能从中间物理删除事件**。因此「剪掉」的实现是:
110
+
111
+ 1. 读取源会话的全部轮次
112
+ 2. 用**剩余轮次**重建一个新会话(文字内容)
113
+ 3. 可选 `archive: true`:把原会话登记进 DSH 的归档集合(`archivedSessionIds`),从列表消失,
114
+ 会话文件原地不动,随时可取消归档
115
+
116
+ > **为什么不改目录名**:DSH 读取会话列表时,会用每个会话文件头里的 `id` 与 `cwd` 重新推导
117
+ > 它应该所在的路径,并要求与实际路径一致。目录一旦被改名成 `.archived-*`,这条校验失败,
118
+ > **整份** `session/list` 报错,侧边栏的会话列表会整块消失,而且重启也不会恢复
119
+ > (0.9.1 及更早版本就踩了这个坑;插件启动时会把遗留的 `.archived-*` 目录自动改回来)。
120
+
121
+ ```json
122
+ { "sessionId": "2c609ca0", "ranges": "78-92", "dryRun": false, "archive": true }
123
+ ```
124
+
125
+ 也可以一步完成「导出 + 剪除」:
126
+
127
+ ```json
128
+ { "sessionId": "2c609ca0", "ranges": "78-92", "dryRun": false, "cut": true }
129
+ ```
130
+
131
+ `cut: true` 时:先导出独立会话,再用剩余轮次重建主会话,最后归档原会话——主会话只剩非独立部分。
132
+
133
+ | 参数 | 默认 | 说明 |
134
+ |---|---|---|
135
+ | `dryRun` | `true` | 只返回计划,不写文件 |
136
+ | `archive` | `false` | 归档原会话(登记归档集合,目录不改名) |
137
+ | `title` | 自动 | 重建会话的标题 |
138
+
139
+ 注意:
140
+
141
+ - 重建的会话**只保留文字**,工具调用记录不会带入
142
+ - 归档走 DSH 的 `workspaceRegistry.archiveSession`:会话正在运行(还有回合/子代理在跑)时
143
+ 归档会被拒绝,工具会明确告诉你「原会话未归档」,会话与目录都不受影响
144
+ - 原会话归档后仍在磁盘(`session-<id>` 下),可在列表的归档视图里取消归档或手动删除
145
+
146
+ ## 精确挑选(turns)
147
+
148
+ 主题在会话里往往是交错的:同一主题可能散落在几十个位置。只用连续区间(`ranges`)时,
149
+ 要么漏掉同主题的散点,要么把中间的无关轮次一起带出去。
150
+
151
+ 用 `turns` 可以精确挑选任意轮次:
152
+
153
+ ```json
154
+ { "sessionId": "2c609ca0", "turns": "3,7-9,20", "dryRun": true }
155
+ ```
156
+
157
+ | 参数 | 说明 |
158
+ |---|---|
159
+ | `turns` | 逗号分隔,每项为单轮 `N` 或区间 `A-B`;与 `ranges` 互斥 |
160
+ | `ranges` | 连续区间(`0-51,52-87`、`78-end`);保留不变 |
161
+
162
+ `session_export` / `session_cut` / `session_coverage` 都支持:
163
+
164
+ - 预览显示「选中 N 轮 / 多少字 / 几个连续块」与「排除 …」,并核对
165
+ **选中 + 排除 = 源会话**(轮次与字数两个维度)
166
+ - 选中轮次不连续时会提示:导出的会话**缺少中间上下文**(物理限制,无法用代码消除)
167
+ - 重叠或相邻的输入项会自动合并,不会重复计数
168
+
169
+ > 一轮是原子单位:如果同一轮里前后半段属于不同主题,只能整轮归类。
170
+
171
+ ## 判断模型(语义分段)
172
+
173
+ `mode=auto` 时优先调用判断模型给主题边界,失败自动回退关键词规则(并在输出里标注失败原因)。
174
+
175
+ - **kernel 后端**:走宿主 `ctx.llm`,复用用户已配置的模型与额度,**不需要额外密钥**
176
+ - **http 后端**:任意 OpenAI 兼容端点,密钥只从环境变量读取,不写入配置
177
+
178
+ 提示词只包含每轮摘要(用户首句 + 助手首句),所以一次 200 轮会话约 2 万 token,而不是 30 万。
179
+ 模型输出后由代码硬校验「从 0 开始、首尾相接、不重叠、全覆盖」;校验失败重试一次,仍失败则回退。
180
+
181
+ 环境变量覆盖:
182
+
183
+ ```powershell
184
+ $env:DSH_SESSION_SPLIT_JUDGE = 'off' # 关闭模型,只用关键词
185
+ $env:DSH_SESSION_SPLIT_JUDGE = 'kernel' # 强制内核模型
186
+ $env:DSH_SESSION_SPLIT_JUDGE_URL = 'https://api.deepseek.com/v1'
187
+ $env:DSH_SESSION_SPLIT_JUDGE_HTTP_MODEL = 'deepseek-chat'
188
+ $env:DSH_SESSION_SPLIT_JUDGE_KEY = '<key>' # 变量名可由 httpKeyEnv 改
189
+ ```
190
+
191
+ ## 急停开关
192
+
193
+ | 开关 | 用法 |
194
+ |---|---|
195
+ | Host | 环境变量 `DSH_SESSION_SPLIT_DISABLE=1`,重启后不注册工具 |
196
+ | Client | `localStorage.setItem('dsh-split-disabled','1')` 后刷新 |
197
+ | Client | `window.__DSH_SESSION_SPLIT_DISABLE__ = true` |
198
+
199
+ ## 测试
200
+
201
+ ```powershell
202
+ npm test # 或 node --test
203
+ ```
204
+
205
+ 覆盖:多帧 zstd 编解码、截断容错、分段/覆盖率、配置校验、工具成功与错误路径、前缀匹配、缓存命中、任意轮次选择(`turns` 解析/合并/互斥/越界),以及语义分段(提示词、校验、重试、回退、dryRun)。
206
+
207
+ ## 目录结构
208
+
209
+ ```
210
+ src/
211
+ index.js 插件入口(配置校验 + 注册)
212
+ config.js 默认值 + 校验
213
+ errors.js 错误码
214
+ log.js 分级日志(DSH_SESSION_SPLIT_DEBUG=1)
215
+ zstd.js 多帧编解码
216
+ store.js 路径/注册表/扫描/缓存
217
+ topics.js 关键词分段规则与平滑
218
+ selection.js ranges / turns 统一成轮次集合 + 二维覆盖率
219
+ judge.js 判断模型适配(kernel / http)+ 输出校验
220
+ semantic.js 语义分段:模型边界 → 平滑 → 字数
221
+ exporter.js 构造并原子写入会话
222
+ tools.js 五个工具
223
+ client/
224
+ index.js React 组件,注册 conversation.input.dock
225
+ locale/ zh.json / en.json(Plugin Manager 标题与描述)
226
+ icon.svg 插件图标
227
+ test/ node:test 用例
228
+ ```
229
+
230
+ ## 安全设计
231
+
232
+ - 客户端通过 `conversation.input.dock` slot 注册 React 组件:不读写宿主 DOM、不 append `document.body`
233
+ - 固定浮层按宿主文档用 `createPortal`;文案走 `ctx.locale`,颜色走 `--dsw-alias-*`
234
+ - 组件内监听与定时器在卸载/关闭时清理;请求进行中禁用按钮防重复写
235
+ - HTTP 面板默认启用但强制令牌;令牌为进程内随机且只注入受鉴权的页面
236
+ - Host / 连接来源 / Origin / Sec-Fetch-Site 四重校验 + 双档限流(见上节)
237
+ - 诊断接口默认脱敏(隐藏主机名与本机路径)
238
+ - 缓存:解析结果按 mtime 缓存;压缩/解压双上限;工具异常转为 `错误[CODE]:…`
239
+ - 会话 id 白名单校验;导出路径必须落在 `~/.dsh/sessions` 内
240
+ - 新会话原子写(.tmp → rename)
241
+ - 无遥测、无外部网络请求;只有把判断模型显式配成 `http` 后端才会访问指定端点
242
+
243
+ ## 已知限制
244
+
245
+ - 主题划分默认走判断模型;模型不可用时退回关键词规则,粒度较粗
246
+ - 判断模型只读每轮摘要,极短或高度混杂的段落仍可能判错,`dryRun` 可先预览再决定
247
+ - 导出的会话只含用户提问与助手回复正文,不含工具调用
248
+ - 导出结果是快照:可继续对话,但新消息不会同步回源会话
249
+ - `turns` 精确挑选会产生不连续片段:导出会话缺少中间上下文(预览会提前提示)
250
+ - 一轮是原子单位:同一轮内前后半段属于不同主题时只能整轮归类
251
+ - DSH 的会话日志是多帧 zstd,Node 的 `zstdDecompressSync` 只解第一帧,本包已按帧魔数逐段解压
252
+
253
+ ## 兼容性
254
+
255
+ - Node ≥ 22(依赖 `node:zlib` 的 zstd)
256
+ - `engines.dsh`: `>=0.2.2-rc.5 <0.3.0`(当前实测运行的 DSH 版本)
257
+ - 已在 Windows + DSH `0.2.2-rc.5` 上完成:插件注册、工具调用、HTTP 鉴权、导出/剪除的宿主侧测试
258
+ - 会话目录键已与 DSH 的 `projectKey` 对齐(含 `~XXXX` 转义、251 截断);
259
+ Linux/macOS 的路径逻辑兼容,但**尚未在真机验证**
260
+ - **UI 渲染未验证**:当前环境无法启动浏览器(DSH 沙盒禁止命名管道),见「验证边界」
261
+
262
+
263
+ ## 诊断
264
+
265
+ 新会话里调用 `session_diag`,或直接看返回,包含:
266
+
267
+ - 运行环境(Node 版本、主机名)
268
+ - 路径(DSH_HOME、会话目录、注册表)及是否存在
269
+ - 已注册工具清单
270
+ - 配置摘要(上限、缓存、分段阈值、主题规则数)
271
+ - 缓存命中 / 未命中 / 最近解析耗时
272
+ - 急停开关状态
273
+ - 会话目录里是否残留 `.archived-*`(会破坏 DSH 会话列表的目录名)
274
+
275
+ ### 侧边栏会话列表整块消失怎么办
276
+
277
+ 先看 `~/.dsh/sessions/<工作区>/` 里有没有 `.archived-session-*` 目录:
278
+
279
+ ```powershell
280
+ Get-ChildItem $env:USERPROFILE\.dsh\sessions\*\ -Directory | Where-Object Name -like '.archived-*'
281
+ ```
282
+
283
+ 有的话改回 `session-<id>` 即可(插件 0.9.2+ 启动时会自动改回,并打一条 `归档目录自愈` 日志)。
284
+ DSH 的 `session/list` 对每个会话文件都做「头里的 id + cwd → 期望路径」校验,
285
+ 一条不通过就整份列表报错,所以侧边栏会空、重启也不恢复。
286
+
287
+ ## 超时与取消
288
+
289
+ - 每个工具声明 `timeoutMs = 60000`(语义分段需要等模型,含重试)
290
+ - 工具执行接收 `AbortSignal`;已取消的调用直接返回 `错误[ABORTED]:调用已取消`
291
+ - 判断模型单次调用另有 `semantic.timeoutMs` 超时,超时记为 `JUDGE_TIMEOUT` 并回退
292
+
293
+ ## 本地开发脚本(不随包发布)
294
+
295
+ ```powershell
296
+ # 仅本地调试:安装(会改 profile;正式安装请用 Plugins → Add plugin)
297
+ powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1 -Profile web
298
+
299
+ # 卸载(幂等)
300
+ powershell -NoProfile -ExecutionPolicy Bypass -File scripts/uninstall.ps1 -Profile web
301
+ ```
302
+
303
+ `package.json` 的 `files` 已排除 `scripts/` 与 `test/`,发布包只含运行文件、locale、图标与文档。
304
+
305
+ ## 测试与 CI
306
+
307
+ ```powershell
308
+ npm test # 114 个用例:单元 + 集成 + 安全 + 客户端注册契约
309
+ npm run validate # manifest / locale / icon 静态校验
310
+ node scripts/sandbox-turns.mjs # 临时 DSH_HOME 沙盒:连跑 3 遍也不写真实会话
311
+ npm run lint # 代码规范(9 条规则)
312
+ npm run check # lint + validate + test
313
+ ```
314
+
315
+ `npm test` 走 `scripts/test-all.mjs`:逐个文件独立进程运行,汇总退出码。
316
+ CI 里仍可用 `node --test`(`npm run test:node`)。
317
+
318
+ ## 验证边界
319
+
320
+ **已用证据(可复现)**
321
+
322
+ - 语法:全部 `.js/.mjs` 通过 `node --check`
323
+ - Manifest:`dsh.bundle.patch`、`./client`、`locale/*.json`、`icon.svg` 均存在且可解析
324
+ - 宿主侧:114 个测试(HTTP 401/403/429、turns/cut、seq 连续、源会话只读、性能预算)
325
+ - 数据不变量:源会话 SHA256 不变;写入限定在 DSH_HOME 内;原子写
326
+ - 客户端契约:`inject: ['slots','locale']`、注册 `conversation.input.dock`、zh/en 字典键一致、
327
+ 源码不含宿主 DOM 探查与 `document.body.append`
328
+
329
+ **未验证(不要据此声称可用)**
330
+
331
+ - 面板在真实浏览器中的渲染、主题明暗、390px 窄屏、键盘交互与提示语
332
+ - live slot 是否被宿主正确挂载(环境无 `cordis_inspect_query`)
333
+ - 安装后的 Plugin Manager 详情页与图标显示
334
+ - Linux/macOS 真机
335
+
336
+ > 本仓库不使用 DOM 模拟来替代浏览器验证;DOM 沙盒不能算 UI 验证。
337
+
338
+ 性能预算(800 轮 / 6405 事件,实测):冷读 138ms、缓存读 1ms、分段 23ms。
339
+
340
+ CI:`.github/workflows/ci.yml`,Windows + Ubuntu × Node 22/24,跑规范检查与测试。
341
+
342
+ ## 目录结构(更新)
343
+
344
+ ```
345
+ src/
346
+ config.js errors.js log.js zstd.js store.js
347
+ topics.js judge.js semantic.js exporter.js tools.js diagnostics.js index.js
348
+ client/index.js
349
+ test/ helpers.js zstd.test.js topics.test.js tools.test.js
350
+ semantic.test.js integration.test.js perf.test.js
351
+ scripts/ install.ps1 uninstall.ps1 profile-manifest.mjs test-all.mjs style-check.mjs
352
+ .github/workflows/ci.yml
353
+ ```
354
+
355
+
356
+ ## 代码规范
357
+
358
+ 零依赖检查器(`npm run lint`),9 条规则:
359
+
360
+ | 规则 | 内容 |
361
+ |---|---|
362
+ | R1 | 禁止 `var` |
363
+ | R2 | 禁止 `==` / `!=` |
364
+ | R3 | 禁止 `debugger` |
365
+ | R4 | 禁行尾空白、Tab 缩进、CRLF |
366
+ | R5 | 文件以单个换行结尾 |
367
+ | R6 | 单行 ≤ 120 字符 |
368
+ | R7 | `src/`、`client/` 禁止 `console.log`(统一走 `log.js`) |
369
+ | R8 | `src/` 中导出必须有 JSDoc |
370
+ | R9 | 文件名 kebab-case |
371
+
372
+ 编辑器约定见 `.editorconfig`(UTF-8 / LF / 2 空格 / 去行尾空白)。
373
+
374
+ 提交前建议执行:
375
+
376
+ ```powershell
377
+ npm run check # = lint + test
378
+ ```
379
+
380
+
381
+ ## 可视化面板
382
+
383
+ 控件注册在 `conversation.input.dock`(会话输入框上方),点击「拆分 / Split」打开面板。
384
+ 面板按 6 步组织;文案走 `ctx.locale`(中文环境显示中英双语,英文环境显示英文):
385
+
386
+ | 步骤 | 中文 | English |
387
+ |---|---|---|
388
+ | 1 | 选择会话,可刷新 | Choose a session, refresh |
389
+ | 2 | 选分段方式(auto / keyword / model)并获取分段 | Segmentation mode, load segments |
390
+ | 3 | 勾选分段;全选/清空;合并或各成一组 | Select segments; all/clear; merge or split |
391
+ | 4 | 手动添加:连续区间(`0-51,52-96`)或精确轮次(`3,7-9,20`) | Add ranges or exact turns |
392
+ | 5 | 查看导出分组,可删除 | Review groups, remove |
393
+ | 6 | 可勾选「导出后剪除并归档」;**必须先预览**,再导出 | Optionally remove & archive; preview is required first |
394
+
395
+ 安全与交互约束:
396
+
397
+ - 切换会话会清空旧分组,避免把 A 的区间套到 B 上
398
+ - 请求进行中禁用按钮,防止双击重复创建会话
399
+ - 剪除模式必须先预览才允许导出;预览显示「剪除后主会话保留多少轮/字」
400
+ - 面板内错误按错误码显示中英提示;状态条 `role="status" aria-live="polite"`
401
+ - 焦点进入面板、Esc 关闭、关闭后焦点回到入口;固定浮层用 `createPortal` 挂到 body
402
+
403
+ 面板通过 HTTP 路由工作,不依赖对话:
404
+
405
+ ```
406
+ GET /dsh-topic-split/sessions
407
+ GET /dsh-topic-split/topics?sessionId=&mode=
408
+ POST /dsh-topic-split/preview { sessionId, groups:[{title, ranges|turns}], cut? }
409
+ POST /dsh-topic-split/export { sessionId, groups:[{title, ranges|turns}], dryRun?, cut? }
410
+ GET /dsh-topic-split/diag
411
+ ```
412
+
413
+ 路由只读源会话;导出走原子写;参数全部校验;单次最多 10 组。
414
+ `cut: true` 时先导出各分组,再用**剩余轮次**重建主会话并归档原会话。
415
+
416
+ ## 许可证
417
+
418
+ GPL-3.0-only,见 [LICENSE](LICENSE)。
package/SECURITY.md ADDED
@@ -0,0 +1,68 @@
1
+ # 安全说明(dsh-topic-split)
2
+
3
+ ## 这份插件碰什么数据
4
+
5
+ | 数据 | 读 | 写 | 出本机 |
6
+ |---|---|---|---|
7
+ | `~/.dsh/sessions/**/session.v4.jsonl.zstd` | 是(只读源会话) | 新建独立会话文件 | 否 |
8
+ | `~/.dsh/storages/workspace.json` | 是 | 登记新会话 | 否 |
9
+ | 会话正文 | 是 | 导出时复制进新会话 | 否 |
10
+ | 会话摘要(判断模型) | 是 | 否 | 默认走 DSH 内核模型;只有显式配置 `http` 后端才发到你指定的端点 |
11
+
12
+ 插件**没有遥测、没有回传通道**;`fetch` 只出现在两处:面板调用本机相对路径
13
+ `/dsh-topic-split/*`,以及你显式配置的 `semantic.httpBaseUrl`。
14
+
15
+ ## 默认安全姿态
16
+
17
+ | 项 | 默认 |
18
+ |---|---|
19
+ | HTTP 面板路由 | **启用,但强制令牌**(进程内随机,只注入受鉴权页面) |
20
+ | 会话标题对外 | 返回,但仅在令牌通过后可见(`exposeTitles: false` 可关闭) |
21
+ | 诊断中的主机名/路径 | HTTP 接口返回时脱敏 |
22
+ | 监听范围 | 跟随 DSH 自身绑定(默认 `127.0.0.1`) |
23
+ | 来源校验 | Host + 连接来源 + Origin + Sec-Fetch-Site 四重校验 |
24
+ | 限流 | 普通 60 次/分,导出 6 次/分 |
25
+
26
+ 想彻底不暴露 HTTP 接口:`httpRoutes: 'off'`(或 `DSH_SESSION_SPLIT_HTTP=off`)。
27
+
28
+ ## 为什么自己实现鉴权
29
+
30
+ DSH 的 `webServer.register()` 注册的路由**不经过宿主自身的 token 鉴权**
31
+ (实测:`/` 与 `/api/*` 无 token 返回 401,而插件注册的路由返回 200)。
32
+ 因此本插件在 `httpRoutes: 'token'` 模式下自行实现:
33
+
34
+ 1. 令牌比较(常量时间),令牌可配置或进程内随机;
35
+ 2. `Host` 白名单,只允许 loopback,阻断 DNS rebinding;
36
+ 3. 连接对端地址校验,拒绝非本机 socket;
37
+ 4. `Origin` 与 `Sec-Fetch-Site` 校验,阻断跨站请求;
38
+ 5. 普通/导出两档限流;
39
+ 6. 令牌通过 index.html 的 meta 注入,只有通过宿主鉴权的页面才能取得。
40
+
41
+ ## 已知边界
42
+
43
+ - 若你把 `dsh web` 绑定到非 loopback 地址(`--host 0.0.0.0`、反代、隧道),
44
+ 面板路由会拒绝所有非本机 `Host`,功能不可用——这是刻意的安全取舍。
45
+ - 面板只暴露「会话元数据 + 主题标签」,**不返回消息正文**;`/export` 能创建会话文件,
46
+ 但响应只给 id。
47
+ - 判断模型若配置为 `http` 后端,会话摘要会离开本机,去向你指定的端点;
48
+ 默认 `auto` 优先用 DSH 内核模型。
49
+ - 插件运行在宿主进程内,**无法防御宿主本身被攻破**。
50
+
51
+ ## 报告问题
52
+
53
+ 发现安全问题请私下联系维护者(不要先开公开 issue),附:
54
+
55
+ - 插件版本、DSH 版本
56
+ - 复现步骤(能最小化最好)
57
+ - 影响:能读到什么 / 能改什么
58
+
59
+ ## 发布前检查清单(给发布者)
60
+
61
+ - [ ] `npm run check` 全绿(规范 + 测试)
62
+ - [ ] 包内无本机路径、无会话 id、无 token(`grep -r "C:\\\\Users" .`)
63
+ - [ ] `package.json` 不含私人 `author`/`repository` 邮箱(或使用专用邮箱)
64
+ - [ ] npm 账号开启 2FA,发布使用 `npm publish --provenance`(如支持)
65
+ - [ ] Git 提交邮箱使用公开身份,避免真实邮箱进历史
66
+ - [ ] 截图/录屏里会话标题、URL token、文件路径已脱敏
67
+ - [ ] 默认配置保持 `httpRoutes: 'off'`
68
+ - [ ] 发布物与仓库 commit 一致(附校验和)