dsh-mode-exchange 0.0.0-stage → 0.1.1

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/CHANGELOG.md ADDED
@@ -0,0 +1,181 @@
1
+ # Changelog
2
+
3
+ 本项目的所有重要变更都会记录在此文件中。
4
+ 格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
5
+ 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
6
+
7
+ ## [Unreleased]
8
+
9
+ ### 开源准备
10
+
11
+ - 新增 `.gitignore`:排除 `node_modules/`、本地取证目录(`.verify/`、`.refs/`、
12
+ `.dsh-vision-router/`,含桌面截图与宿主安装包转储)、运行期数据目录与临时文件。
13
+ - 新增 `LICENSE`(MIT),`package.json` 的 `private` 改为 `false` 并补 `license` 字段。
14
+ - 清除源码与文档中写死的开发机绝对路径:
15
+ `scripts/smoke-seed.mjs` 改为相对导入,`scripts/smoke-host.mjs` 用 `import.meta.url` 解析,
16
+ `scripts/probe.js` 改为优先读 `DSH_APP_ASAR`、否则按 `LOCALAPPDATA` 推断,
17
+ `README.md` / `docs/LOCAL-DEV.md` 的安装示例改为 `<本仓库的绝对路径>` 占位符。
18
+ - 统一面板/设置页名称说明(侧栏与设置页标签是「模式迁移」,插件列表名是「模式交换」)。
19
+ - `package.json` 补 `repository` / `homepage` / `bugs` / `author`,LICENSE 署名对齐仓库所有者。
20
+ - 新增 `scripts/push-git.ps1`:一键 `init → add → commit → branch -M → remote add → push`,
21
+ 自动在 PATH 之外查找 `git.exe`(刚装完 git 没重开终端时也能跑),默认带 `--force`
22
+ (远端 Initial commit 与本地无共同历史),支持 `-DryRun` / `-NoForce` / 身份参数。
23
+ - 新增 `docs/PUBLISH.md`:三条发布路径(REST 推送器 / git 脚本 / 网页上传)、PAT 权限、
24
+ 认证方式与本机特有的 schannel、代理、换行符等报错对照表。
25
+ - 新增 `scripts/publish-npm.ps1`:一键发布到 npm registry。六步(定位 npm → 检查登录 →
26
+ 构建与冒烟 → `npm pack --dry-run --json` 校验真实打包清单与 icon 体积 → 版本查重 →
27
+ `npm publish --access public`),支持 `-Version` / `-Tag` / `-Otp` / `-DryRun` / `-SkipTests`。
28
+ 定位 npm 时优先 `npm.cmd`(避免 `npm.ps1` 包装器的 stderr 噪声),读 JSON 时强制 UTF-8
29
+ (PS 5.1 的 `Get-Content` 会按 ANSI 解码,把中文 description 读成乱码)。
30
+ - `docs/PUBLISH.md` 增补「方案 D:发布到 npm」:`npm login`、脚本六步对照表、手敲版命令、
31
+ 发布后验证、升级版本、发布报错对照表,以及可选的插件索引源(`format: 1` JSON)示例。
32
+ - `README.md` 安装章节区分「从 npm 装」与「从本地目录装」。
33
+ - `scripts/publish-npm.ps1` 修三处首次真发暴露的问题:
34
+ ① npm 的 `notice` 走 stderr,PS 5.1 把 `2>&1` 重定向的每条 stderr 都渲染成
35
+ `NativeCommandError` 刷屏、真实报错被淹没 —— 改为临时 `.cmd` 包裹 + 文件重定向再按 UTF-8 读回,
36
+ 成功时只打印 `+ pkg@version` 之类的关键行;
37
+ ② 失败提示按真实原因分支,把「E403 + 2FA」从「包名被占用」里拆出来,给出验证码与
38
+ bypass-2fa token 两条具体路径;
39
+ ③ 撞上 2FA 错误后当场 `Read-Host` 问 6 位验证码(验证码 30 秒过期,先问再发必然过期),
40
+ 拿到就立即重试一次;
41
+ 另修中文输出在 GBK 控制台显示成「浜х墿鏄渶鏂扮殑」的乱码(`[Console]::OutputEncoding = UTF8`)。
42
+ - `docs/PUBLISH.md` 新增「6.5 开了 2FA 怎么发」:报错原文、办法 A(脚本当场问码 /
43
+ `-Otp`)、办法 B(granular access token 勾 Bypass 2FA 的五步 + 安全提醒),
44
+ 并把报错对照表里 `E403` 拆成「2FA」与「名称/版本冲突」两行。
45
+ - 新增 `scripts/publish-npm.cmd`:`publish-npm.ps1` 的免策略包装器。Windows 默认
46
+ `RemoteSigned` 会拦下未签名的本地 `.ps1`(报「未对文件 … 进行数字签名」),
47
+ 包装器用 `-ExecutionPolicy Bypass` 起一次性子进程,参数原样透传,不改系统策略。
48
+ 文件内容保持纯 ASCII —— cmd.exe 按 OEM 代码页(中文系统是 936)读批处理,
49
+ UTF-8 中文注释会被拆成可执行行的错误输出。
50
+ - `docs/PUBLISH.md` 补「别直接敲 `.\scripts\publish-npm.ps1`」的提示与 `.cmd` 用法,
51
+ 报错对照表新增「未对文件 … 进行数字签名 / `UnauthorizedAccess`」一行。
52
+ - `scripts/publish-npm.ps1` 新增 `-Bump`:当前版本已在 npm 上时自动升一个补丁号
53
+ (`0.1.0 → 0.1.1`,预发布版先落回正式号)再发,省掉「发布→被拦→手动 `npm version`→再发」
54
+ 的一轮往返;不加该开关时仍只打印三选一提示、不改 `package.json`。
55
+ - `docs/PUBLISH.md` 的「升级版本」与参数示例补 `-Bump`,六步表中的 5/6 说明同步。
56
+
57
+ ### 修复
58
+
59
+ - **`scripts/publish-npm.ps1` 编辑后整篇报语法错**:文件原本带 UTF-8 BOM,用文本编辑工具
60
+ 改写时 BOM 被丢掉,PowerShell 5.1 于是按 ANSI(936) 解码中文注释,报出一串
61
+ 「表达式或语句中包含意外的标记 `}`」这类与内容无关的错误。已恢复 BOM,
62
+ 并在文档里记下「改带中文的 `.ps1` 后要检查文件头仍是 `EF BB BF`」。
63
+ - **插件在宿主里被标成「异常」:`cannot get property "connection" without inject`**:
64
+ `src/host/routes.js` 用 `ctx.get('connection') ?? ctx.connection` 取 Web 宿主服务。
65
+ 真实 Cordis 里,服务只要没在本插件的 `inject` 里声明,属性访问就会直接抛
66
+ `cannot get property "connection" without inject`;而 `ctx.get(name)` 默认 strict,
67
+ 服务提供方 fiber 尚未激活时同样返回 `undefined`。Connection 由 Web 组合在启动过程中
68
+ 较晚提供,于是 `??` 走到右侧就抛错,整个 `apply` 失败、插件卡显示「异常」,
69
+ 侧栏面板与命令一起消失。现在:
70
+ - 统一改用 `serviceOf(ctx, name)`(非 strict 读 store + try/catch 包住属性访问),
71
+ `routes.js` 的 `connection` / `configEditor`、`switch.js` 的 `systemPrompt` 都走它;
72
+ - `connection` 还没就绪时交给 `ctx.inject(['connection'], …)`,服务可用后再注册路由;
73
+ 插件本身不等服务,命令照常可用;
74
+ - 新增 `scripts/smoke-inject.mjs`:按真实 Cordis 语义(注入检查 + strict `get`)建模,
75
+ 复现「connection 晚到」并断言 `apply` 不抛错、服务就绪后 10 条路由全量注册。
76
+ - **设置页与面板白屏**:`src/client/ui.js` 里的共享组件原先写成「首参是 React」的工厂签名
77
+ (如 `PanelHead(React, { title })`),而 `panel.js` / `settings.js` 用
78
+ `h(PanelHead, props)` 把它们当普通 React 组件渲染 —— React 调用函数组件只传
79
+ `(props, context)`,第二个形参解构 undefined 直接 TypeError,渲染即崩,
80
+ 宿主错误边界把内容吞掉,于是「设置 → 模式迁移」和侧栏面板都是空白。
81
+ 现在组件改为标准的 `(props)` 签名,React 实例由 `bindUiReact(React)` 在
82
+ `entry.js` 入口处一次性绑定;未绑定时抛明确错误而不是静默白屏。
83
+ - 新增 `scripts/smoke-render.mjs`(`npm test`):像宿主那样加载 `bundle.js`,
84
+ 用最小 React 桩把设置页、中央面板、图标真渲染一遍并断言关键文案,
85
+ 拦住「组件签名与调用方式不匹配」这类构建期发现不了的回归。
86
+
87
+ ## [0.1.0] - 2026-11-19
88
+
89
+ 首个可运行版本:从零实现,能力 A(运行时软切换)与能力 B(迁移重建)全部打通。
90
+
91
+ ### 新增
92
+
93
+ #### 能力 A —— 运行时模式切换
94
+
95
+ - `/switch-mode <模式名>`:在当前会话内软切换 Agent 模式。
96
+ - 通过 `system-prompt/assemble` 瀑布替换系统提示词 section;
97
+ - 通过 `agent.ctx.tools.restrict({ deny })` 把「当前模式有、目标模式没有」的工具
98
+ 从声明与派发两侧一起移除;
99
+ - 通过 `agent.ctx.tools.register()` + `when` 门控补挂「目标模式有、当前没有」的工具;
100
+ - 全部改动挂在会话作用域上,不影响全局 profile 与其它会话。
101
+ - `/switch-mode --revert`:按切换前的入口快照回退(工具限制、补挂、提示词一起撤销)。
102
+ - `/switch-mode --list`:运行时枚举全部可用模式(来自 `agentPresets.list()`,零硬编码),
103
+ 标出当前模式、运行时默认模式与装配失败(broken)的模式。
104
+ - 切换快照落盘到 `<数据目录>/state/switches.json`,因此改设置触发插件重建后
105
+ (`apply` 重新执行)软切换状态会被读回并重建。
106
+ - 会话级 `tools.guard` 兜底:即使有路径绕开 schema 直接派发,也会按会话被拒绝。
107
+ - 对不可切换的会话(不存在、已归档、子代理来源、无活 Agent、无作用域)给出具体中文原因,
108
+ 不静默失败。
109
+
110
+ #### 能力 B —— 迁移重建
111
+
112
+ - `/migrate-session --mode <模式> [--delete-old true|false] [--team on|off] [--note <备注>] [--yes] [--resume]`:
113
+ 严格按七步执行,每步可观测(面板显示当前步骤、耗时与逐步时间线)。
114
+ 1. 导出:`<导出目录>/exports/<YYYYMMDD-HHmmss>-<短ID>.jsonl` + `.meta.json`(含 sha256)。
115
+ 2. 校验:逐行可解析、事件数一致、`seq` 从 0 连续、sha256 匹配;失败即中止并保留现场。
116
+ 3. 创建:以目标模式作为 `agentPreset` 创建新会话,并在 `setup` 里 `agentPresets.mount()`
117
+ 装配该模式的插件组合。
118
+ 4. 导入:把导出的**原生事件序列**作为新会话的 constructor seed 写入
119
+ (`seed = 源事件前缀 + session/end-seed{inherited:true} + 收尾事件`,
120
+ `inheritedEventCount` 只计源事件),未闭合的 turn/step 自动补 `step/end`、`turn/end`,
121
+ 未拿到结果的工具调用补 `isError` 的 `tool/result`(`TOOL_OUTCOME_UNKNOWN` / `TOOL_NOT_STARTED`)。
122
+ 5. 团队:`--team on` 时对新会话的根 Agent 调 `agentTeams.setEnabled(true)` 并回读 `isEnabled` 复核。
123
+ 6. 归档:`--delete-old true` 时先备份再归档旧会话(见「已知限制」——DSH 没有删除会话的 API)。
124
+ 7. 报告:新旧会话 ID、日志路径、消息数、工具调用数、团队状态、旧会话处置结果、耗时、时间线。
125
+ - 幂等:台账 `<数据目录>/migrations/<源会话ID>.json` 按源会话记录进度。
126
+ 同一会话重复执行不会产生第二个新会话,而是返回「续跑 / 放弃」提示。
127
+ - 失败可回滚:新会话已建但导入复核失败时,新会话与日志文件都保留,
128
+ 报告里给出可手动完成的剩余步骤。
129
+ - 来源标记(FR-12):新会话追加一条 user 消息,记录「由会话 X 于时间 T 迁移而来、
130
+ 原模式 A → 新模式 B」,并附带 `--note` 内容。
131
+ - 导出副本保留策略:`keepExportCopy=false` 时,成功结束后删除导出文件;失败时一律保留。
132
+
133
+ #### 界面
134
+
135
+ - 侧栏面板(`sidebar.panellist` + `main`,id/key 均为 `mode-exchange`):
136
+ - 「切换」页签:当前会话、当前生效模式、可否切换、目标模式下拉 + 应用/回退按钮、
137
+ 入口快照卡片、软切换警示;
138
+ - 「迁移」页签:目标模式、归档旧会话开关(默认开)、团队协作开关(不支持时置灰并说明原因)、
139
+ 备注输入、执行按钮、取消按钮、续跑卡片、七步进度与耗时、报告卡片;
140
+ - 「历史」页签:迁移记录列表(时间、源会话、目标会话、结果),可查看报告详情、
141
+ 一键打开目标会话。
142
+ - 归档确认对话框展示旧会话标题、消息数、日志路径,并提供「先备份」开关。
143
+ - 设置页(`settings.section` + `settings.section.icon`):默认目标模式、默认是否归档旧会话、
144
+ 默认是否启用团队协作、日志导出目录、是否保留导出日志副本、是否在迁移前强制确认
145
+ (关闭时二次警告)。
146
+
147
+ #### 命令与接口
148
+
149
+ - `/switch-mode`、`/migrate-session` 两个命令(`ctx.commands.register`)。
150
+ - `/api/mode-exchange/*` 十条 HTTP 路由(`ctx.connection.fetch.register`):
151
+ `GET /state`、`POST /switch`、`POST /revert`、`POST /migrate`、`GET /job`、
152
+ `POST /cancel`、`GET /migrations`、`GET /report`、`POST /archive-old`、`POST /config`。
153
+ 统一 `{ ok: true, value }` / `{ ok: false, error: { code, message } }` 信封,带同源校验。
154
+
155
+ #### 工程
156
+
157
+ - 零依赖客户端打包器 `scripts/build-client.mjs`(`src/client/*.js` → `src/client/bundle.js`),
158
+ 不引入 esbuild,不需要 install 脚本。
159
+ - `scripts/probe.js`:校验 manifest、exports、icon、locale、bundle 产物与 profile 挂载状态。
160
+ - TypeScript 类型声明 `types/index.d.ts`、`types/client.d.ts`。
161
+ - 中英双语 locale(`locale/zh.json`、`locale/en.json`),详情页 `docs/DETAIL.md`、`docs/DETAIL.en.md`。
162
+ - 本地加载与调试说明 `docs/LOCAL-DEV.md`。
163
+
164
+ ### 已知限制
165
+
166
+ - **能力 A 是「软切换」**:插件组合、工具执行器(native / PTC `run_code` 传输层)、
167
+ 子代理与团队都不会随切换改变。目标模式若只差「有哪些工具、提示词怎么写」,软切换够用;
168
+ 若差在工具如何执行(PTC 就是这类),只有能力 B 能给到真行为。
169
+ - **FR-9 的「删除旧会话」实现为归档**:DSH 没有删除会话的 API,
170
+ 只有 `archiveSession` / `unarchiveSession` / `pinSession`;`workspaceRegistry.delete()`
171
+ 删的是工作区而非会话。归档后会话从分组与置顶列表隐藏、活动被停止,
172
+ 但会话日志文件仍在磁盘上,可用 `unarchiveSession` 反悔。
173
+ - **归档可能延后**:`/migrate-session` 跑在旧会话的 Agent 里,当场归档自己会打断工作,
174
+ 因此实现为「先尝试停止活动再归档;若宿主要求当前回合结束后才能停,则排期重试」,
175
+ 报告里标记为「已排期」。
176
+ - **FR-1 的 Tab 补全无法做成结构化候选**:宿主 `CommandInputDescriptor` 只有 `hint` 字符串,
177
+ 没有参数级枚举字段。替代方案是把运行时枚举结果写进 hint、`--list` 与错误文案,
178
+ 交互式选择由侧栏面板的下拉框承担。
179
+ - **团队协作开关有约束**:`agentTeams.setEnabled` 只接受 root Session 的活 Agent,
180
+ 且新值在「下一次 step 准备」时才影响工具可见性。运行时探测不到该能力时,
181
+ 面板置灰并说明原因,报告记「未启用 + 原因」而不伪造成功。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dasuda13
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,301 @@
1
- # Temporary Holding Version
1
+ # Agent模式切换 · dsh-mode-exchange
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
+ > A generic DSH plugin to dynamically switch to any Agent mode (Standard, PTC, Code, etc.)
4
+ > in an existing session. It reconfigures the toolset and system prompt on the fly,
5
+ > eliminating the need to create a new chat.
6
+ >
7
+ > DeepSeek Harness 通用插件,支持在任意现有对话中自由切换至任何内置 Agent 模式
8
+ > (如 Standard、PTC、Code、Research 等)。通过动态重组会话的工具集与系统提示词,
9
+ > 实现无缝切换,无需中断当前任务重新创建会话。
10
+
11
+ 在**已经存在的** DSH 会话里换 Agent 模式,或者把一个会话按目标模式**迁移重建**。
12
+
13
+ DSH 的模式(Standard / PTC / Code / Research …)是会话启动那一刻固化成插件组合的。
14
+ `agentPresets.select()` 只管「第一轮还没开始」的会话,已有消息的会话会被
15
+ `agent-preset/locked` 挡回来;`recompose()` 要求 Agent 是空白的。
16
+ 所以对一个跑了很久的会话,官方路上只有一个选择:新建会话。
17
+
18
+ 这个插件补两条路:
19
+
20
+ ```
21
+ ┌──────────────────────────────────────┐
22
+ │ 现有会话(模式 A,有历史,正在用) │
23
+ └───────────────┬──────────────────────┘
24
+ │
25
+ ┌──────────────────────┴───────────────────────┐
26
+ │ │
27
+ 【能力 A · 软切换】 【能力 B · 迁移重建】
28
+ /switch-mode <模式> /migrate-session --mode <模式>
29
+ │ │
30
+ 同一个会话、同一个 ID,原地改 新会话、真模式、真导入历史
31
+ │ │
32
+ ┌──────────┴──────────┐ ┌──────────┴──────────┐
33
+ │ ① 换系统提示词 │ │ ① 导出日志 │
34
+ │ ② 按会话拒绝旧工具 │ │ ② 校验完整性 │
35
+ │ ③ 补挂目标模式工具 │ │ ③ 按目标模式建会话 │
36
+ └──────────┬──────────┘ │ ④ 导入原生事件序列 │
37
+ │ │ ⑤ 可选:团队协作 │
38
+ /switch-mode --revert 可撤销 │ ⑥ 可选:归档旧会话 │
39
+ │ ⑦ 输出报告 │
40
+ └──────────┬──────────┘
41
+ │
42
+ 失败保留现场 + 可续跑
43
+ ```
44
+
45
+ 一句话选路:**只差工具清单和提示词 → 用 A;连工具怎么执行都要变 → 用 B。**
46
+
47
+ ---
48
+
49
+ ## 功能
50
+
51
+ ### 能力 A:运行时软切换
52
+
53
+ - `/switch-mode <模式名>` —— 在当前会话内切换,作用域只有这一个会话:
54
+ - **换系统提示词**:在 `system-prompt/assemble` 瀑布里摘掉现有 section,
55
+ 换成本插件生成的、描述目标模式(含其工具清单与工作方式)的 section;
56
+ - **卸载旧工具**:`agent.ctx.tools.restrict({ deny })` 把「当前有、目标没有」的工具
57
+ 从**声明和派发两侧**一起去掉 —— 模型看不见,调用也会被拒;
58
+ - **补挂新工具**:`agent.ctx.tools.register()` + `when` 门控,把「目标有、当前没有」的工具
59
+ 注册进会话作用域;
60
+ - 另挂一道 `tools.guard` 兜底,防止绕开 schema 直接派发。
61
+ - `/switch-mode --revert` —— 按入口快照整体回退。
62
+ - `/switch-mode --list` —— 运行时枚举全部模式(**零硬编码**),标出当前、默认、装配失败的。
63
+ - 快照落盘 `state/switches.json`,改设置触发插件重建后会自动读回并重建。
64
+ - 不可切换的会话(不存在 / 已归档 / 子代理 / 无活 Agent / 无作用域)给具体中文原因,
65
+ 不静默失败。
66
+
67
+ ### 能力 B:迁移重建(七步)
68
+
69
+ 1. **导出** → `<导出目录>/exports/<YYYYMMDD-HHmmss>-<短ID>.jsonl` + `.meta.json`(含 sha256)
70
+ 2. **校验** → 逐行可解析 / 事件数一致 / `seq` 从 0 连续 / sha256 匹配;失败即中止、现场保留
71
+ 3. **建会话** → 以目标模式为 `agentPreset` 创建,并在 `setup` 里 `agentPresets.mount()` 真装配
72
+ 4. **导入** → 原生事件序列作为 constructor seed 写入(**不是复述**):
73
+ ```
74
+ 源事件前缀(seq 0..N-1)
75
+ + session/end-seed{inherited:true} ← 正好落在 index = inheritedEventCount
76
+ + 收尾事件:未闭合 turn/step 补 step/end、turn/end;
77
+ 没拿到结果的工具调用补 isError 的 tool/result
78
+ (TOOL_OUTCOME_UNKNOWN / TOOL_NOT_STARTED,附宿主原文的「别盲目重试」提示)
79
+ ```
80
+ 5. **团队** → `--team on` 时对根 Agent 调 `agentTeams.setEnabled(true)`,再回读 `isEnabled` 复核
81
+ 6. **归档** → `--delete-old true` 时先备份再归档旧会话(见「已知限制」)
82
+ 7. **报告** → 新旧会话 ID、日志路径、消息数、工具调用数、团队状态、旧会话处置、耗时、时间线
83
+
84
+ 配套保障:
85
+
86
+ - **幂等**:台账 `migrations/<源会话ID>.json` 按源会话记进度;重复执行不产生第二个新会话,
87
+ 而是让你选「续跑 / 放弃」。
88
+ - **失败不丢东西**:新会话建好但导入复核失败时,新会话与日志都保留,报告列出可手动完成的剩余步骤。
89
+ - **来源标记(FR-12)**:新会话首条追加一条消息,写明「由会话 X 于时间 T 迁移而来、
90
+ 原模式 A → 新模式 B」,并带上 `--note`。
91
+ - **导出副本策略**:`keepExportCopy=false` 时成功结束后删除导出文件;失败一律保留。
92
+
93
+ ### 界面
94
+
95
+ - **侧栏面板**(`sidebar.panellist` + `main`,id/key 都是 `mode-exchange`):
96
+ - 「切换」:当前会话、当前生效模式、可否切换、目标模式下拉 + 应用/回退、入口快照、软切换警示;
97
+ - 「迁移」:目标模式、归档旧会话(默认开)、团队协作(不支持时置灰并说明原因)、备注、
98
+ 执行/取消、续跑卡片、七步进度与耗时、报告;
99
+ - 「历史」:时间 / 源会话 / 目标会话 / 结果,点开看报告,一键打开目标会话。
100
+ - **设置页**(`settings.section` + `settings.section.icon`):默认目标模式、默认是否归档旧会话、
101
+ 默认是否启用团队协作、日志导出目录、是否保留导出副本、是否迁移前强制确认(关掉要二次警告)。
102
+ - 侧栏与设置页共用同一份持久化配置,改完即时同步。
103
+
104
+ ---
105
+
106
+ ## 安装
107
+
108
+ 需要 DSH `>=0.2.2-rc.3 <0.3.0`、Node 22+。**没有 install 脚本,没有构建期依赖。**
109
+
110
+ **从 npm 装(已发布时最简单)**:侧栏 **插件** → **添加插件** → 输入包名 `dsh-mode-exchange`,
111
+ 装完点「立即启用」即可。等价的工具调用:
112
+
113
+ ```
114
+ plugin_manager({ action: "install_bundle", target: "dsh-mode-exchange" })
115
+ ```
116
+
117
+ **从本地目录装(开发期)**:
118
+
119
+ ```
120
+ plugin_manager({ action: "install_bundle", target: "<本仓库的绝对路径>" })
121
+ ```
122
+
123
+ 装完确认:
124
+
125
+ ```
126
+ plugin_manager({ action: "list_plugins" }) // 状态应为 active
127
+ ```
128
+
129
+ > 本地目录安装是**链接整个 checkout**,`files` 不生效 —— 想干净就单独 copy 一份再装。
130
+ > **替换已安装的包必须重启宿主**,不会热换 JS 模块世代。
131
+ > 别手改 profile 的 `cordis.patch.yml`,那是最容易把 profile 弄坏的一步。
132
+
133
+ 开发期想直接挂载、或者要装到别的 profile,见 [docs/LOCAL-DEV.md](docs/LOCAL-DEV.md)。
134
+
135
+ ---
136
+
137
+ ## 使用示例
138
+
139
+ ### 例 1:把一个长会话切成 PTC
140
+
141
+ ```
142
+ /switch-mode --list
143
+ → 可用模式(4 个):
144
+ · standard (标准)(当前)
145
+ · ptc (PTC)(运行时默认) — 通过单次代码执行工具驱动工作
146
+ · code (代码)
147
+ · research (研究)
148
+
149
+ /switch-mode ptc
150
+ → 已切换至「PTC」模式,工具集已变更。
151
+ 已卸载(目标模式不提供):read_file、write_file、list_dir …
152
+ 已补挂(目标模式新增):run_code
153
+ 注意:本次只做了提示词层切换,工具的**执行方式**没有改变;
154
+ 要真正用上 PTC 的代码执行通道,请用 /migrate-session --mode ptc 重建会话。
155
+
156
+ /switch-mode --revert
157
+ → 已回退到切换前的状态:standard 模式。
158
+ ```
159
+
160
+ ### 例 2:把一个会话迁到 PTC,保留旧会话
161
+
162
+ ```
163
+ /migrate-session --mode ptc --delete-old false --note "切到 PTC 继续做重构"
164
+ → 迁移已开始(任务 3f2a1b9c),共 7 步:
165
+ ① 导出会话日志 ② 校验完整性 ③ 以目标模式创建新会话 ④ 导入历史
166
+ ⑤ 团队协作 ⑥ 归档旧会话 ⑦ 报告
167
+ 目标模式:PTC(ptc)
168
+ 旧会话:保留
169
+ 团队协作:不启用
170
+ ```
171
+
172
+ 在侧栏面板看着七步跑完,报告里能看到新会话 ID 与日志路径。
173
+ 打开新会话,历史消息与工具调用都在,直接接着聊。
174
+
175
+ ### 例 3:迁移 + 开团队 + 归档旧会话
176
+
177
+ ```
178
+ /migrate-session --mode ptc --team on --yes
179
+ ```
180
+
181
+ 没带 `--yes` 时,为安全起见**不会**归档旧会话(命令会明说)。
182
+ 带了 `--yes` 就按配置里的「先备份再删除」执行:备份到 `backups/`,然后归档旧会话。
183
+ 面板路径走的是确认对话框,展示旧会话标题、消息数、日志路径,并可选「先备份」。
184
+
185
+ ### 例 4:只想归档一个旧会话
186
+
187
+ 侧栏面板「历史」页签或 `POST /api/mode-exchange/archive-old`,
188
+ 带 `confirm` 与 `backup` 参数。
189
+
190
+ ---
191
+
192
+ ## 已知限制
193
+
194
+ ### 1. 能力 A 是「软切换」,不是真模式
195
+
196
+ | | 真模式装配(新建会话) | 本插件软切换 |
197
+ | --- | --- | --- |
198
+ | 插件组合 | 按预设声明挂载 | **不变**,只改提示词与工具可见性 |
199
+ | 工具执行器 | 由预设决定(native / PTC) | **不变** —— PTC 的 `run_code` 传输层不会因切换出现 |
200
+ | 会话 ID | 新的 | 不变 |
201
+ | 历史 | 复制过去 | 原地保留 |
202
+ | 子代理 / 团队 | 按新预设 | 不变 |
203
+
204
+ **能做到**:目标模式有哪些工具、提示词怎么写、模型看见的工作方式。
205
+ **做不到**:换掉工具的执行通道。软切换后调用被卸载的工具会被拒绝(有明确报错),
206
+ 而不是"看起来能用其实没走对通道"。命令返回和面板都会主动告知这一点。
207
+
208
+ ### 2. FR-9 的「删除旧会话」实现为 **归档**
209
+
210
+ DSH **没有删除会话的 API**:
211
+
212
+ - 工作区服务只有 `archiveSession` / `unarchiveSession` / `pinSession`;
213
+ - `workspaceRegistry.delete()` 删的是**工作区**,不是会话;
214
+ - 会话日志文件是持久层的,插件这一层拿不到删除句柄。
215
+
216
+ 所以这里的「删除」= 归档:
217
+
218
+ - 从所有分组界面隐藏、从置顶列表移除;
219
+ - 按要求停止其活动;
220
+ - **磁盘上的日志文件仍在**,可以用 `unarchiveSession` 反悔。
221
+
222
+ 如果你期待「数据被抹掉」,归档做不到;如果你期待「它别出现在我的列表里」,归档正好。
223
+ 报告里一律写「已归档」,不写「已删除」。
224
+
225
+ 此外归档**可能延后**:`/migrate-session` 跑在旧会话的 Agent 里,当场归档自己会打断工作。
226
+ 实现是「先尝试停掉活动再归档;若宿主要求当前回合结束后才能停,就排到微任务重试」,
227
+ 报告里标「已排期」。
228
+
229
+ ### 3. FR-1 的 Tab 补全做不成结构化候选
230
+
231
+ 宿主 `CommandInputDescriptor` 只有 `hint: string`,**没有参数级枚举字段**,也没有补全回调。
232
+ 所以:
233
+
234
+ - 补全信息写进 `input.hint`;
235
+ - `/switch-mode --list` 与错误文案完整列出运行时枚举结果(零硬编码);
236
+ - 交互式选择交给侧栏面板的下拉框。
237
+
238
+ ### 4. 团队协作开关有前置条件
239
+
240
+ `agentTeams.setEnabled(agent, enabled)` 只接受 **root Session 的活 Agent**,
241
+ 从子代理调用会抛 `TEAM_LEAD_REQUIRED`;新值要等到「下一次 step 准备」才影响工具可见性。
242
+ 运行时探测不到这个能力时,面板开关置灰并说明原因,报告记「未启用 + 原因」,**不伪造成功**。
243
+
244
+ ### 5. 其他
245
+
246
+ - 迁移会换会话 ID:新会话是真正的另一个会话,`parentSession` 不建立父子关系(当前实现)。
247
+ - `--mode` 必填;不填会报错并提示先 `/switch-mode --list`。
248
+ - 跨工作区迁移以源会话的 `cwd` 为准;匹配不到工作区时只是不进工作区分组,不影响迁移。
249
+
250
+ ---
251
+
252
+ ## 目录结构
253
+
254
+ ```
255
+ package.json manifest(dsh.bundle.patch / dsh.client)
256
+ cordis.patch.yml bundle 挂载行与默认配置
257
+ icon.svg 插件图标
258
+ index.js 宿主入口:装配服务、能力探测、注册命令与路由
259
+ src/host/
260
+ config.js 配置 schema 与数据目录布局
261
+ services.js 宿主服务解析、能力探测、会话读取辅助
262
+ modes.js 模式枚举(唯一数据源:agentPresets.list())
263
+ switch.js 软切换核心(restrict / register / 提示词瀑布 / 快照)
264
+ guard.js 会话级 tools.guard
265
+ snapshot.js 切换快照落盘与读回
266
+ export.js 导出、校验、备份
267
+ seed.js constructor seed 构造(prefix + marker + closers)
268
+ ledger.js 迁移台账(幂等与续跑)、报告读写
269
+ migrate.js 七步迁移任务
270
+ routes.js /api/mode-exchange/* 路由
271
+ util.js 参数解析、哈希、时间、文件等纯函数
272
+ src/client/
273
+ entry.js 客户端入口(插槽注册、会话订阅)
274
+ api.js / store.js 路由客户端与状态容器
275
+ ui.js / panel.js 组件库、侧栏面板
276
+ settings.js 设置页
277
+ i18n.js 中英文字典
278
+ bundle.js 构建产物(由 scripts/build-client.mjs 生成)
279
+ types/ TypeScript 声明
280
+ locale/ 插件页标题与描述(zh / en)
281
+ docs/ 详情页、本地调试说明
282
+ scripts/ build-client.mjs(零依赖打包)、probe.js(体检)、smoke-*.mjs(冒烟)
283
+ LICENSE MIT
284
+ .gitignore 依赖、构建产物、本地取证目录
285
+ ```
286
+
287
+ > 开发和排查用的 `.verify/`、`.refs/`、`.dsh-vision-router/` 属于本地取证产物
288
+ > (含桌面截图与从宿主安装包里抽出的参考资料),已在 `.gitignore` 里排除,不入库。
289
+
290
+ ---
291
+
292
+ ## 文档
293
+
294
+ - [docs/DETAIL.md](docs/DETAIL.md) —— 原理、为什么叫「软」切换、七步的细节、安全边界
295
+ - [docs/LOCAL-DEV.md](docs/LOCAL-DEV.md) —— 本地加载、调试、冒烟测试清单、踩坑
296
+ - [docs/PUBLISH.md](docs/PUBLISH.md) —— 发布到 GitHub 的三种方式、PAT 权限、常见报错;发布到 npm registry 供 DSH 用户在线安装
297
+ - [CHANGELOG.md](CHANGELOG.md) —— 变更记录
298
+
299
+ ## 许可
300
+
301
+ [MIT](LICENSE)。插件运行时依赖宿主提供的 `@deepseek-ai/schemastery`,其许可随宿主分发。
@@ -0,0 +1,15 @@
1
+ # dsh-mode-exchange bundle patch
2
+ #
3
+ # 只声明「本 bundle 要往 profile 里插入哪一行插件」。
4
+ # 插件自身的一切可配置项都写在 config 里,并由宿主通过 configEditor 持久化到
5
+ # profile 的 cordis.patch.yml;插件代码永远不直接读写那个文件。
6
+ - insert:
7
+ - id: mode-exchange
8
+ name: dsh-mode-exchange
9
+ config:
10
+ defaultMode: ''
11
+ deleteOldSession: true
12
+ enableTeam: false
13
+ exportDir: ''
14
+ keepExportCopy: true
15
+ confirmBeforeMigrate: true
@@ -0,0 +1,76 @@
1
+ # Mode Exchange (dsh-mode-exchange)
2
+
3
+ ## What this plugin is for
4
+
5
+ In DSH, an Agent mode (Standard / PTC / Code / Research …) is frozen into a plugin composition
6
+ **when the session starts**. `agentPresets.select()` only works before the first turn of a session;
7
+ `agent-presets/locked` stops it afterwards, and `recompose()` requires a blank Agent.
8
+ So for a long-running session, the only official way to change mode is to start a new session.
9
+
10
+ This plugin offers two complementary paths:
11
+
12
+ | Capability | Command | What it really does | Cost |
13
+ | --- | --- | --- | --- |
14
+ | **A. Runtime soft switch** | `/switch-mode <mode>` | Replaces the system prompt, denies the old tools for this session, attaches the new ones | Session ID and history stay; it is **not** a real preset composition |
15
+ | **B. Migrate & rebuild** | `/migrate-session --mode <mode>` | Export the log → create a session with the target preset → import the log as a native event sequence | A real mode; but it is a new session ID, and the old session is archived by default |
16
+
17
+ Both are also reachable from the "Mode Exchange" sidebar panel, and the plugin settings page
18
+ holds the defaults.
19
+
20
+ ## A. What the soft switch actually does
21
+
22
+ Within the current session's scope only, three things happen (all reversible):
23
+
24
+ 1. **Swap the system prompt.** In the `system-prompt/assemble` waterfall, every existing section is
25
+ dropped and replaced by one section describing the target mode (its tool inventory and working
26
+ style).
27
+ 2. **Deny the old tools for this session.** `agent.ctx.tools.restrict({ deny })` removes
28
+ "present now, absent in target" tools from **both declarations and dispatch** — the model stops
29
+ seeing them and calling them is refused. The restriction lives in the session's own scope layer.
30
+ 3. **Attach the new tools.** Tools "absent now, present in target" are registered into the session
31
+ scope with a `when` gate so they are visible only here.
32
+
33
+ A `tools.guard` is installed as a second line of defence. The pre-switch state is snapshotted to
34
+ `<data dir>/state/switches.json`, so it survives a plugin rebuild (changing settings re-runs `apply`),
35
+ and `/switch-mode --revert` undoes everything.
36
+
37
+ ### Why "soft"
38
+
39
+ The plugin composition, the tool *executor* (native vs PTC `run_code` transport), subagents and
40
+ teams do not change. If the target mode differs only in *which tools exist and how the prompt reads*,
41
+ the soft switch is enough. If it differs in *how tools are executed*, only capability B delivers it.
42
+ The panel and the command output always say so instead of pretending success.
43
+
44
+ ## B. The seven migration steps
45
+
46
+ ```
47
+ ① export → <export dir>/exports/<timestamp>-<short id>.jsonl (+ .meta.json with sha256)
48
+ ② verify → parseable lines / event count / seq contiguous from 0 / sha256; abort and keep evidence on failure
49
+ ③ create → create a session with the target mode as its agentPreset and mount that mode's composition
50
+ ④ import → write the exported native event sequence as the new session's constructor seed
51
+ ⑤ team → with --team on, call agentTeams.setEnabled(true) on the new session's root Agent
52
+ ⑥ archive → with --delete-old true, back up and then archive the old session (see below)
53
+ ⑦ report → both session IDs, log path, message counts, team state, old-session outcome, timeline
54
+ ```
55
+
56
+ Step ④ is a **real import**, not a re-telling: the seed is built exactly like the host's own fork path —
57
+ the source event prefix, one `session/end-seed{inherited:true}` marker at index `inheritedEventCount`,
58
+ then synthetic closers for any unclosed turn/step and `TOOL_OUTCOME_UNKNOWN` / `TOOL_NOT_STARTED`
59
+ results for tool calls that never got one.
60
+
61
+ Step ⑥ is an **archive**, not a delete: DSH has no delete-session API (`workspaceRegistry.delete()`
62
+ removes a *workspace*). The session disappears from grouped lists and pinned lists and its activity is
63
+ stopped, but the log file stays on disk and `unarchiveSession` can undo it. Some archiving is
64
+ *scheduled* rather than immediate, because the command runs inside the very Agent being archived.
65
+
66
+ ## Safety
67
+
68
+ - Changes from capability A live in the session scope only; the global profile and other sessions are
69
+ untouched, and everything is disposed when the plugin or the session goes away.
70
+ - Archiving is on by default but always needs confirmation (`--yes` on the CLI, a dialog in the panel).
71
+ Without confirmation the old session is kept and the report says so.
72
+ - A failed import keeps both the new session and the log file, and the report lists the remaining
73
+ manual steps. The ledger at `<data dir>/migrations/<source session id>.json` prevents a second new
74
+ session for the same source, and offers resume or abandon.
75
+ - When team switching cannot be probed at runtime, the toggle is disabled with the reason shown; the
76
+ report records "not enabled + reason" rather than a fake success.