dsh-rea-mcp-toggle

Name: VioletEverGarden-zc/dsh-rea-mcp-toggle
Author: VioletEverGarden-zc

一个 DeepSeek Harness（DSH）bundle 插件：在 Harness Web UI 里一键开关 REA MCP 服务器，并把同一个开关交给模型（工具 rea_mcp_toggle）。选择按 profile 保存，重启后依然生效。

适用：DSH 0.2.1-alpha.2（web profile）。零运行时依赖（只用 Node 内置模块 + dsh 宿主服务）。

1. 项目解决什么问题

REA（Reverse Engineer Anything）通过 MCP 以 stdio 方式接入 DSH。它的工具集非常大：开启时是 170 个 mcp__rea__* 工具，这些工具的 schema 会随每一次请求一起发给模型。

实测同一实例、同一时刻，Tool.listTools 的返回体大小：

REA 状态	工具数	tools payload
开启	251	722,353 字节
关闭	81	94,807 字节

差价 627 KB 全部是那 170 个工具的定义。它们每次都进请求，于是产生两种浪费：

token 费用：不管这一轮到底用不用逆向工具，都在为这 627 KB 付费（长会话里反复累积）；
进程与内存：REA 的 MCP 子进程常驻（单进程约 240 MB），只有关掉才会退出。

而 DSH 自带的「插件开关」（Plugin Manager 里把 rea-mcp 行禁用）对这一行无效——原因见第 6 节，这不是配置问题，是 patch 层的机制决定的。所以本项目提供了能真正生效、且能持久化的开关。

典型场景：平时关着，等真要分析二进制 / APK 时再打开；或者反过来，只在需要省 token 时临时关闭。

2. 主要功能

2.1 UI 开关（主入口）

会话标题栏（Session header）里的一个小按钮，与「费用明细」等控件并列：

显示 REA 开 / REA 关，绿点表示当前状态；
点一下切换：即时生效，不需要重启 Harness；
切换失败时按钮直接变成 REA 失败（红框），鼠标悬停显示具体原因 —— 不会静默无效；
鼠标悬停还会显示当前工具数与配置行 id。

2.2 模型工具 `rea_mcp_toggle`

action	作用
`status`	读当前开关状态、工具数、是否已持久化、状态文件路径
`set`	切换（需 `enabled: true/false`）；幂等，重复同向不发写、不产生副作用
`probe`	诊断：Loader 行状态、REA 工具数、缝是否在位、服务可用性、Remote endpoint 解析情况
`selftest`	用 Web UI 调用的同一条 Remote 网关路径自检本插件（用来区分「UI 坏了」还是「Host 坏了」）

UI 按钮与这个工具共用同一套实现（同一 service 的同一个方法），不存在两份逻辑。

2.3 状态持久化

选择保存在插件自己的状态文件里：

%DSH_PROFILE_DIR%\.rea-mcp-toggle.state.json     例如 {"enabled": false, "savedAt": "..."}

写入是原子的（临时文件 + rename）。重启后由家目录层的一行 !!js 缝读取该文件，开机即按选择生效（关闭状态下开机根本不会拉起 REA）。

2.4 工具可见性真正变化

关闭时 170 个 mcp__rea__* 工具从模型可调用工具列表中消失（不只是「不执行」）；开启时全部回来。

2.5 进程生命周期

开启：拉起 REA 的 stdio 子进程（每次切换恰好 1 个）；
关闭：dispose 该行，回收子进程、注销工具；
关闭后不会自己复活（曾有一个「关闭后子进程又起来」的缺陷，已修并可复现验证）。

3. 安装方法

3.1 前置条件

已安装 DSH，且 REA 已作为 MCP server 注册在家目录层 %DSH_HOME%\cordis.patch.yml，形如：

- insert:
    - id: rea-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: rea
        transport: stdio
        command: '<HARNESS_ROOT>\node\bin\node.exe'
        args: ['<NPM_GLOBAL>\node_modules\rea-agents\scripts\rea.mjs', 'mcp']
        env: { REA_MCP_INPUT_SCHEMA_PROFILE: compact }
        toolCallTimeoutMs: 900000
        failOnStartupError: false        # 硬约束：REA 坏了也不能让 harness 起不来

该行 id 必须是 rea-mcp（本插件按这个 id 定位；其它 id 会被明确拒绝，不会误伤）。

3.2 安装本 bundle

本插件以路径链接方式安装，因此包目录内需要有指向 DSH 安装的 node_modules 链接（Node 从包的真实目录解析 bare import；本插件运行时只 import node:fs，但编译/探针脚本需要）：

cd plugins\dsh-rea-mcp-toggle
node scripts/link-deps.mjs
# 通常不需要参数：脚本会自己找 harness（见下），失败时才需要显式给根目录
# node scripts/link-deps.mjs "<HARNESS_ROOT>"

脚本如何找到 harness（按顺序，每个候选都会被 marker 校验，错的目录不会静默胜出）：

顺序	来源	说明
1	命令行参数	`node scripts/link-deps.mjs "<root>"`
2	`<repo>/.harness-root`	一行写根目录；模板见 `.harness-root.example`；已被 git 忽略。标准位置都描述不了的布局用这个
3	`DSH_HARNESS_ROOT`	环境变量
4	平台标准安装位置	Windows：`%LOCALAPPDATA%\Programs`、`%ProgramFiles%`、`%ProgramFiles(x86)%`、`%LOCALAPPDATA%` 下的 `dsh-desktop` / `DeepSeek Harness` / `deepseek-harness`，并在其 `resources/harness` 与 `harness` 处探测；macOS：`/Applications`、`~/Applications`；Linux：`/opt`、`/usr/local/lib`、`/usr/lib`
5	正在运行的 Harness	由进程的 `node.exe` 路径反推安装根，因此装在非标准目录也能找到

判定「是 harness 根」的条件：同时存在 node_modules/@deepseek-ai/{cordis,dsh,dsh-tools} 与 node_modules/js-yaml。本仓库自身被显式排除（它的 node_modules 是链接，否则会自我链接）。

然后在会话里让模型执行（需要 danger-full-access 或当次审批）：

plugin_manager → install_bundle → <本目录绝对路径>

安装后必须重启一次 dsh-desktop。 Host 半边的模块是进程启动时导入的；不重启时插件行会处于 failed to import 或停在旧版本。

3.3 安装家目录层的「开关缝」（必须，一次）

这是唯一需要手改家目录层的地方。在你已有的 rea-mcp 行里加一个行级 disabled（不要放进 config 里面）：

      - id: rea-mcp
        name: '@deepseek-ai/dsh-mcp-client'
        config:
          # ...原有内容保持不动...
        # ── 开关缝：由 dsh-rea-mcp-toggle 插件读取 ──
        disabled: !!js >-
          Boolean(ctx.get('profileContext')?.dir) && (() => { try { return process.getBuiltinModule('node:fs').readFileSync(process.getBuiltinModule('node:path').join(ctx.get('profileContext').dir, '.rea-mcp-toggle.state.json'), 'utf8') && JSON.parse(process.getBuiltinModule('node:fs').readFileSync(process.getBuiltinModule('node:path').join(ctx.get('profileContext').dir, '.rea-mcp-toggle.state.json'), 'utf8')).enabled === false } catch { return false } })()

改前先备份：Copy-Item .dsh\cordis.patch.yml .dsh\cordis.patch.yml.bak-<时间戳>

这段表达式是安全降级的：状态文件不存在 / JSON 损坏 / profileContext 不可用（例如离线 dsh --dump-config）时一律返回 false＝保持启用，不会让 harness 起不来。

3.4 安装后自检

node scripts/acceptance.mjs        # 校验缝与状态文件在同一口径上

再在会话里执行 rea_mcp_toggle {action:"selftest"} —— 它走的就是 Web UI 的 Remote 网关路径。

4. 使用方法

4.1 日常：点按钮

标题栏的 REA 开 / REA 关 按钮，点一下即可。不需要重启。

4.2 让模型帮你切

把 REA 关掉，我在省钱          → 模型调用 rea_mcp_toggle {action:"set", enabled:false}
REA 现在开着吗？               → 模型调用 rea_mcp_toggle {action:"status"}
UI 按钮点了没反应，帮我看看     → 模型调用 rea_mcp_toggle {action:"selftest"}

4.3 关闭 / 禁用的几种情况

临时关：点按钮。状态文件写 enabled:false，当前进程立即生效（工具消失、子进程回收）。
永久不再启用：把手改的那段 disabled: !!js 缝从家目录层删掉（保留其余内容），该行即恢复为无条件启用。
彻底卸载：见第 8 节。

5. 输入输出示例

以下均为真实运行结果（本机实测，compact schema profile）。

5.1 查询状态

输入：

{ "action": "status" }

输出（REA 关闭时）：

REA MCP (rea-mcp) is OFF: the mcp__rea__* tools are not callable; the choice is saved.
entry=rea-mcp module=@deepseek-ai/dsh-mcp-client
enabled=false persisted=false tools=0 seam=true
stateFile=<PROFILE_DIR>\.rea-mcp-toggle.state.json

输出（REA 开启时）：

REA MCP (rea-mcp) is ON: 170 tool(s); the choice is saved.
entry=rea-mcp module=@deepseek-ai/dsh-mcp-client
enabled=true persisted=true tools=170 seam=false
stateFile=<PROFILE_DIR>\.rea-mcp-toggle.state.json

seam=false 是正常的：即时开启会清掉该行进程内的 disabled 键（probe 里显示 rawDisabled=null），开机时缝会重新求值（那时是 seam=true）。

5.2 关闭 REA

输入：

{ "action": "set", "enabled": false }

输出：

REA MCP (rea-mcp) is OFF: the mcp__rea__* tools are not callable; the choice is saved.
entry=rea-mcp module=@deepseek-ai/dsh-mcp-client
enabled=false persisted=false tools=0 seam=false

同时 %DSH_PROFILE_DIR%\.rea-mcp-toggle.state.json 变为：

{ "enabled": false, "savedAt": "2026-10-13T17:59:27.803Z" }

5.3 开启 REA

输入：

{ "action": "set", "enabled": true }

输出（子进程握手完成后）：

REA MCP (rea-mcp) is ON: 170 tool(s); the choice is saved.
enabled=true persisted=true tools=170 seam=false

5.4 幂等：重复同向不发写

连续两次 { "action": "set", "enabled": false }，第二次不会重写状态文件（实测文件 LastWriteTime 与内容完全不变），也不会新增 patch 行。

5.5 诊断

输入：

{ "action": "probe" }

输出（节选）：

seam=false reaTools=0 stateFile=...\.rea-mcp-toggle.state.json
stateFileExists=true stateFileValue=false services={"loader":true,"tools":true,"typert":true,"pluginManager":true,"typertGateway":true}
row id=rea-mcp-toggle composite=include:rea-mcp-toggle module=dsh-rea-mcp-toggle rawDisabled=false effectiveDisabled=false fiberState=2 parentTree=include
row id=rea-mcp composite=include:rea-mcp module=@deepseek-ai/dsh-mcp-client rawDisabled=true effectiveDisabled=true fiberState=4 parentTree=include

读数要点：effectiveDisabled=true 且 fiberState=4（disposed）＝该行确实已停； reaTools=0 ＝模型侧看不到 REA 工具。

5.6 UI 自检（判断是 UI 坏还是 Host 坏）

输入：

{ "action": "selftest" }

输出：

gateway reaMcp/getState ok -> {...}
gateway reaMcp/setEnabled ok -> {...}
restoredTo=false

selftest 会先记住你的选择，结束后原样恢复（诊断不改变开关）。

5.7 安装后的效果对照

观察点	关闭	开启
`Tool.listTools` 里 `mcp__rea__*`	0 个	170 个
`listTools` payload	≈ 94.8 KB	≈ 722.4 KB
该实例的 REA 子进程	0 个	1 个
开销最大的部分	—	170 个工具 schema 进每次请求

6. 为什么不能用 profile 层的 `disabled`（关键设计决定）

DSH 的 patch 分层是：bundle 层 → profile 层（%DSH_PROFILE_DIR%\cordis.patch.yml）→ 家目录层（%DSH_HOME%\cordis.patch.yml）→ --patch 覆盖，后者覆盖前者。

rea-mcp 行是家目录层用 insert 声明的，而家目录层最后应用，insert 推入的是新的行对象。后果（用 Harness 自身的 readProfilePatches / composeEntries 复现，见 scripts/probe-layer-order.mjs）：

profile 层写 { id: rea-mcp, disabled: true } → 组合结果里 rea-mcp 从不带 disabled；
运行时 Entry.disabled 恒为 false；
连官方 plugin_manager 对该行也只能返回 application: "overridden"。

所以本插件的做法是：状态放自己的文件，家目录层只承担一个「缝」（!!js 表达式）。表达式在读取 disabled 时才求值，因此不会被家目录层自己的 insert 盖掉。

7. 项目结构、已知限制与开发笔记

7.1 结构

dsh-rea-mcp-toggle/
├─ package.json          # bundle 清单（dsh.bundle.patch / dsh.client）
├─ cordis.patch.yml      # 只插入本插件自己的行；不碰 rea-mcp 行
├─ index.js              # Host 半边：唯一实现（Remote reaMcp + 工具 rea_mcp_toggle）
├─ state.js              # 状态文件的唯一读写者（原子写）
├─ client.js             # 浏览器半边：标题栏开关按钮
├─ locale/{zh,en}.json   # 插件在插件列表里的显示名与描述
├─ icon.svg              # 图标
├─ .gitignore            # 排除 node_modules 链接、状态文件、机器本地的 .harness-root
├─ .harness-root.example # 「harness 装在哪」的模板（真实文件 .harness-root 由使用者创建）
└─ scripts/              # 安装辅助与验证脚本（不属于运行时，不随包发布）
   └─ lib/harness-paths.mjs   # 定位 harness / profile：多级兜底，不硬编码任何本机路径

运行时零依赖：Host 半边只 import Node 内置模块（node:fs、node:path、node:url）与自身文件；scripts/ 里的脚本才需要 DSH 安装提供的包。

7.2 已知限制

作用域是「实例」：开关作用于承载它的那个 Harness 进程。若机器上残留了旧的 Harness 守护进程（桌面应用重启时偶尔不退出），那些实例不受影响 —— 用任务管理器确认 node.exe 中带 dsh\lib\bin.js 的条目数量，多于 1 个即需清理。
disabled 行必须放在行级，写成 config 的子字段会导致该行永不生效（--dump-config 可看出层级）。
上游遗留（不在本项目内）：@deepseek-ai/dsh-mcp-client 的 dispose() 先取子进程句柄快照再 await；若拆卸时正好有连接在飞，那次连接会在快照之后写入新句柄，其子进程不会被关闭（每关一次可能残留一个孤儿 REA 进程）。该行本身确实是停的（fiber 已 dispose、工具为 0），残留进程只占内存、不向模型暴露工具，Harness 退出时回收。
selftest 需要一次重启后才可用（Host 模块按进程加载）。

7.3 三个踩过的坑（写给后来者）

工具 parameters 必须是「干净」的 JSON Schema：ctx.tools.register() 收的是 raw JSON Schema，会被原样发给 provider。若把作者侧的 required: true 标记写进属性里（defineTool() 那种写法），provider 会直接报 Invalid schema for function 'rea_mcp_toggle': true is not of type 'array'，每一轮都在调用工具之前就失败。正确写法是可选属性不加标记、必填项放进对象级的 required: ["action"] 数组。仓库里保留了门禁脚本 scripts/check-tool-schema.mjs：它从 index.js 抽出 parameters 字面量，用 Harness 自己的 assertSupportedJsonSchema + 8 个参数用例（接受/拒绝各半）校验，防止再次漂移。
不要继承 TypertRemoteService。它的构造器用 bindTypertRemote(this, this.name) 绑定，而 Cordis 的 Service.name 是 symbol 而非服务键字符串，导致网关校验失败：Receiver must be an instance of class ...。正确做法是普通类 + 显式绑定：
```
this.typertRemote = Object.freeze({ service: this, serviceKey: 'reaMcp', namespace: 'reaMcp' })
```
Remote 调用返回的是 { ok, value } 信封，客户端必须 if (!result || result.ok !== true) throw ... 后取 result.value；只判断 ok === false 会把信封当成结果，表现为「按钮点了没反应」。
无参端点要用空对象调用：gateway.invoke() 的入参不能省略 args，要传 args: {}。省略时参数校验会抛 Cannot convert undefined or null to object（浏览器侧的 Remote 调用方始终发 {}，所以只有 Host 自检脚本会踩到）。

7.4 验证脚本

先跑一次 node scripts/link-deps.mjs '<HARNESS_ROOT>'：这些脚本用 Harness 自己的实现来验证（组合算法、YAML 方言、JSON Schema 检查器），依赖包通过本包自己的 node_modules 链接解析，不硬编码任何本机路径。之后在 profile 启动的 shell 里（有 DSH_PROFILE_DIR / DSH_HOME）可以不带参数直接跑：

node --check index.js; node --check client.js; node --check state.js   # 语法
node scripts/check-tool-schema.mjs   # 工具 schema 门禁（Harness 自己的检查器 + 8 个用例）
node scripts/probe-layer-order.mjs   # 分层覆盖机制：profile 层 disabled 为何无效
node scripts/probe-composition.mjs   # 组合结果中该行是否带 disabled
node scripts/probe-seam.mjs          # 缝表达式 × Harness 真实 YAML 方言与求值器
node scripts/probe-roundtrip.mjs     # 真实写/读 × 缝读取，含「损坏文件」降级分支
node scripts/acceptance.mjs          # 缝与状态文件口径一致性

不在 profile shell 里时，用参数显式给路径：

node scripts/acceptance.mjs '<PROFILE_DIR>' '<DSH_HOME>'

8. 卸载 / 回滚

plugin_manager → remove_bundle → dsh-rea-mcp-toggle；
删除家目录层里的 disabled: !!js >- ... 缝（保留该行其余内容），REA 即恢复为无条件启用；
可选：删除 %DSH_PROFILE_DIR%\.rea-mcp-toggle.state.json。

9. 许可

LICENSE 使用 MIT 标准文本，版权人为 VioletEverGarden-zc；package.json 的 license 字段同样是 MIT，三者口径一致。

10. 作者与仓库

作者：VioletEverGarden-zc — https://github.com/VioletEverGarden-zc
仓库：https://github.com/VioletEverGarden-zc/dsh-rea-mcp-toggle
上游项目：REA（Reverse Engineer Anything）— https://github.com/morluto/rea。本插件只提供「开关」，REA 本体及其 mcp__rea__* 工具集由上游项目提供与维护（MIT）。

仓库 URL 按包名 dsh-rea-mcp-toggle 填写。若你实际建仓时用了别的名字，请同步替换 package.json 里的 repository / homepage / bugs 三处与本节链接。

11. 致谢

感谢 REA（Reverse Engineer Anything）的作者与贡献者。本插件只是替它加了一只开关，逆向能力全部来自上游；没有 REA，这个项目没有存在的理由。

dsh-rea-mcp-toggle

适用：DSH 0.2.1-alpha.2（web profile）。零运行时依赖（只用 Node 内置模块 + dsh 宿主服务）。

1. 项目解决什么问题

实测同一实例、同一时刻，Tool.listTools 的返回体大小：

REA 状态	工具数	tools payload
开启	251	722,353 字节
关闭	81	94,807 字节

差价 627 KB 全部是那 170 个工具的定义。它们每次都进请求，于是产生两种浪费：

token 费用：不管这一轮到底用不用逆向工具，都在为这 627 KB 付费（长会话里反复累积）；
进程与内存：REA 的 MCP 子进程常驻（单进程约 240 MB），只有关掉才会退出。

典型场景：平时关着，等真要分析二进制 / APK 时再打开；或者反过来，只在需要省 token 时临时关闭。

2. 主要功能

2.1 UI 开关（主入口）

会话标题栏（Session header）里的一个小按钮，与「费用明细」等控件并列：

显示 REA 开 / REA 关，绿点表示当前状态；
点一下切换：即时生效，不需要重启 Harness；
切换失败时按钮直接变成 REA 失败（红框），鼠标悬停显示具体原因 —— 不会静默无效；
鼠标悬停还会显示当前工具数与配置行 id。

2.2 模型工具 `rea_mcp_toggle`

action	作用
`status`	读当前开关状态、工具数、是否已持久化、状态文件路径
`set`	切换（需 `enabled: true/false`）；幂等，重复同向不发写、不产生副作用
`probe`	诊断：Loader 行状态、REA 工具数、缝是否在位、服务可用性、Remote endpoint 解析情况
`selftest`	用 Web UI 调用的同一条 Remote 网关路径自检本插件（用来区分「UI 坏了」还是「Host 坏了」）

UI 按钮与这个工具共用同一套实现（同一 service 的同一个方法），不存在两份逻辑。

2.3 状态持久化

选择保存在插件自己的状态文件里：

%DSH_PROFILE_DIR%\.rea-mcp-toggle.state.json     例如 {"enabled": false, "savedAt": "..."}

写入是原子的（临时文件 + rename）。重启后由家目录层的一行 !!js 缝读取该文件，开机即按选择生效（关闭状态下开机根本不会拉起 REA）。

2.4 工具可见性真正变化

关闭时 170 个 mcp__rea__* 工具从模型可调用工具列表中消失（不只是「不执行」）；开启时全部回来。

2.5 进程生命周期

开启：拉起 REA 的 stdio 子进程（每次切换恰好 1 个）；
关闭：dispose 该行，回收子进程、注销工具；
关闭后不会自己复活（曾有一个「关闭后子进程又起来」的缺陷，已修并可复现验证）。

3. 安装方法

3.1 前置条件

已安装 DSH，且 REA 已作为 MCP server 注册在家目录层 %DSH_HOME%\cordis.patch.yml，形如：

- insert:
    - id: rea-mcp
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: rea
        transport: stdio
        command: '<HARNESS_ROOT>\node\bin\node.exe'
        args: ['<NPM_GLOBAL>\node_modules\rea-agents\scripts\rea.mjs', 'mcp']
        env: { REA_MCP_INPUT_SCHEMA_PROFILE: compact }
        toolCallTimeoutMs: 900000
        failOnStartupError: false        # 硬约束：REA 坏了也不能让 harness 起不来

该行 id 必须是 rea-mcp（本插件按这个 id 定位；其它 id 会被明确拒绝，不会误伤）。

3.2 安装本 bundle

cd plugins\dsh-rea-mcp-toggle
node scripts/link-deps.mjs
# 通常不需要参数：脚本会自己找 harness（见下），失败时才需要显式给根目录
# node scripts/link-deps.mjs "<HARNESS_ROOT>"

脚本如何找到 harness（按顺序，每个候选都会被 marker 校验，错的目录不会静默胜出）：

顺序	来源	说明
1	命令行参数	`node scripts/link-deps.mjs "<root>"`
2	`<repo>/.harness-root`	一行写根目录；模板见 `.harness-root.example`；已被 git 忽略。标准位置都描述不了的布局用这个
3	`DSH_HARNESS_ROOT`	环境变量
4	平台标准安装位置	Windows：`%LOCALAPPDATA%\Programs`、`%ProgramFiles%`、`%ProgramFiles(x86)%`、`%LOCALAPPDATA%` 下的 `dsh-desktop` / `DeepSeek Harness` / `deepseek-harness`，并在其 `resources/harness` 与 `harness` 处探测；macOS：`/Applications`、`~/Applications`；Linux：`/opt`、`/usr/local/lib`、`/usr/lib`
5	正在运行的 Harness	由进程的 `node.exe` 路径反推安装根，因此装在非标准目录也能找到

然后在会话里让模型执行（需要 danger-full-access 或当次审批）：

plugin_manager → install_bundle → <本目录绝对路径>

安装后必须重启一次 dsh-desktop。 Host 半边的模块是进程启动时导入的；不重启时插件行会处于 failed to import 或停在旧版本。

3.3 安装家目录层的「开关缝」（必须，一次）

这是唯一需要手改家目录层的地方。在你已有的 rea-mcp 行里加一个行级 disabled（不要放进 config 里面）：

      - id: rea-mcp
        name: '@deepseek-ai/dsh-mcp-client'
        config:
          # ...原有内容保持不动...
        # ── 开关缝：由 dsh-rea-mcp-toggle 插件读取 ──
        disabled: !!js >-
          Boolean(ctx.get('profileContext')?.dir) && (() => { try { return process.getBuiltinModule('node:fs').readFileSync(process.getBuiltinModule('node:path').join(ctx.get('profileContext').dir, '.rea-mcp-toggle.state.json'), 'utf8') && JSON.parse(process.getBuiltinModule('node:fs').readFileSync(process.getBuiltinModule('node:path').join(ctx.get('profileContext').dir, '.rea-mcp-toggle.state.json'), 'utf8')).enabled === false } catch { return false } })()

改前先备份：Copy-Item .dsh\cordis.patch.yml .dsh\cordis.patch.yml.bak-<时间戳>

3.4 安装后自检

node scripts/acceptance.mjs        # 校验缝与状态文件在同一口径上

再在会话里执行 rea_mcp_toggle {action:"selftest"} —— 它走的就是 Web UI 的 Remote 网关路径。

4. 使用方法

4.1 日常：点按钮

标题栏的 REA 开 / REA 关 按钮，点一下即可。不需要重启。

4.2 让模型帮你切

把 REA 关掉，我在省钱          → 模型调用 rea_mcp_toggle {action:"set", enabled:false}
REA 现在开着吗？               → 模型调用 rea_mcp_toggle {action:"status"}
UI 按钮点了没反应，帮我看看     → 模型调用 rea_mcp_toggle {action:"selftest"}

4.3 关闭 / 禁用的几种情况

临时关：点按钮。状态文件写 enabled:false，当前进程立即生效（工具消失、子进程回收）。
永久不再启用：把手改的那段 disabled: !!js 缝从家目录层删掉（保留其余内容），该行即恢复为无条件启用。
彻底卸载：见第 8 节。

5. 输入输出示例

以下均为真实运行结果（本机实测，compact schema profile）。

5.1 查询状态

输入：

{ "action": "status" }

输出（REA 关闭时）：

REA MCP (rea-mcp) is OFF: the mcp__rea__* tools are not callable; the choice is saved.
entry=rea-mcp module=@deepseek-ai/dsh-mcp-client
enabled=false persisted=false tools=0 seam=true
stateFile=<PROFILE_DIR>\.rea-mcp-toggle.state.json

输出（REA 开启时）：

REA MCP (rea-mcp) is ON: 170 tool(s); the choice is saved.
entry=rea-mcp module=@deepseek-ai/dsh-mcp-client
enabled=true persisted=true tools=170 seam=false
stateFile=<PROFILE_DIR>\.rea-mcp-toggle.state.json

seam=false 是正常的：即时开启会清掉该行进程内的 disabled 键（probe 里显示 rawDisabled=null），开机时缝会重新求值（那时是 seam=true）。

5.2 关闭 REA

输入：

{ "action": "set", "enabled": false }

输出：

REA MCP (rea-mcp) is OFF: the mcp__rea__* tools are not callable; the choice is saved.
entry=rea-mcp module=@deepseek-ai/dsh-mcp-client
enabled=false persisted=false tools=0 seam=false

同时 %DSH_PROFILE_DIR%\.rea-mcp-toggle.state.json 变为：

{ "enabled": false, "savedAt": "2026-10-13T17:59:27.803Z" }

5.3 开启 REA

输入：

{ "action": "set", "enabled": true }

输出（子进程握手完成后）：

REA MCP (rea-mcp) is ON: 170 tool(s); the choice is saved.
enabled=true persisted=true tools=170 seam=false

5.4 幂等：重复同向不发写

连续两次 { "action": "set", "enabled": false }，第二次不会重写状态文件（实测文件 LastWriteTime 与内容完全不变），也不会新增 patch 行。

5.5 诊断

输入：

{ "action": "probe" }

输出（节选）：

seam=false reaTools=0 stateFile=...\.rea-mcp-toggle.state.json
stateFileExists=true stateFileValue=false services={"loader":true,"tools":true,"typert":true,"pluginManager":true,"typertGateway":true}
row id=rea-mcp-toggle composite=include:rea-mcp-toggle module=dsh-rea-mcp-toggle rawDisabled=false effectiveDisabled=false fiberState=2 parentTree=include
row id=rea-mcp composite=include:rea-mcp module=@deepseek-ai/dsh-mcp-client rawDisabled=true effectiveDisabled=true fiberState=4 parentTree=include

读数要点：effectiveDisabled=true 且 fiberState=4（disposed）＝该行确实已停； reaTools=0 ＝模型侧看不到 REA 工具。

5.6 UI 自检（判断是 UI 坏还是 Host 坏）

输入：

{ "action": "selftest" }

输出：

gateway reaMcp/getState ok -> {...}
gateway reaMcp/setEnabled ok -> {...}
restoredTo=false

selftest 会先记住你的选择，结束后原样恢复（诊断不改变开关）。

5.7 安装后的效果对照

观察点	关闭	开启
`Tool.listTools` 里 `mcp__rea__*`	0 个	170 个
`listTools` payload	≈ 94.8 KB	≈ 722.4 KB
该实例的 REA 子进程	0 个	1 个
开销最大的部分	—	170 个工具 schema 进每次请求

6. 为什么不能用 profile 层的 `disabled`（关键设计决定）

DSH 的 patch 分层是：bundle 层 → profile 层（%DSH_PROFILE_DIR%\cordis.patch.yml）→ 家目录层（%DSH_HOME%\cordis.patch.yml）→ --patch 覆盖，后者覆盖前者。

profile 层写 { id: rea-mcp, disabled: true } → 组合结果里 rea-mcp 从不带 disabled；
运行时 Entry.disabled 恒为 false；
连官方 plugin_manager 对该行也只能返回 application: "overridden"。

7. 项目结构、已知限制与开发笔记

7.1 结构

dsh-rea-mcp-toggle/
├─ package.json          # bundle 清单（dsh.bundle.patch / dsh.client）
├─ cordis.patch.yml      # 只插入本插件自己的行；不碰 rea-mcp 行
├─ index.js              # Host 半边：唯一实现（Remote reaMcp + 工具 rea_mcp_toggle）
├─ state.js              # 状态文件的唯一读写者（原子写）
├─ client.js             # 浏览器半边：标题栏开关按钮
├─ locale/{zh,en}.json   # 插件在插件列表里的显示名与描述
├─ icon.svg              # 图标
├─ .gitignore            # 排除 node_modules 链接、状态文件、机器本地的 .harness-root
├─ .harness-root.example # 「harness 装在哪」的模板（真实文件 .harness-root 由使用者创建）
└─ scripts/              # 安装辅助与验证脚本（不属于运行时，不随包发布）
   └─ lib/harness-paths.mjs   # 定位 harness / profile：多级兜底，不硬编码任何本机路径

运行时零依赖：Host 半边只 import Node 内置模块（node:fs、node:path、node:url）与自身文件；scripts/ 里的脚本才需要 DSH 安装提供的包。

7.2 已知限制

作用域是「实例」：开关作用于承载它的那个 Harness 进程。若机器上残留了旧的 Harness 守护进程（桌面应用重启时偶尔不退出），那些实例不受影响 —— 用任务管理器确认 node.exe 中带 dsh\lib\bin.js 的条目数量，多于 1 个即需清理。
disabled 行必须放在行级，写成 config 的子字段会导致该行永不生效（--dump-config 可看出层级）。
上游遗留（不在本项目内）：@deepseek-ai/dsh-mcp-client 的 dispose() 先取子进程句柄快照再 await；若拆卸时正好有连接在飞，那次连接会在快照之后写入新句柄，其子进程不会被关闭（每关一次可能残留一个孤儿 REA 进程）。该行本身确实是停的（fiber 已 dispose、工具为 0），残留进程只占内存、不向模型暴露工具，Harness 退出时回收。
selftest 需要一次重启后才可用（Host 模块按进程加载）。

7.3 三个踩过的坑（写给后来者）

工具 parameters 必须是「干净」的 JSON Schema：ctx.tools.register() 收的是 raw JSON Schema，会被原样发给 provider。若把作者侧的 required: true 标记写进属性里（defineTool() 那种写法），provider 会直接报 Invalid schema for function 'rea_mcp_toggle': true is not of type 'array'，每一轮都在调用工具之前就失败。正确写法是可选属性不加标记、必填项放进对象级的 required: ["action"] 数组。仓库里保留了门禁脚本 scripts/check-tool-schema.mjs：它从 index.js 抽出 parameters 字面量，用 Harness 自己的 assertSupportedJsonSchema + 8 个参数用例（接受/拒绝各半）校验，防止再次漂移。
不要继承 TypertRemoteService。它的构造器用 bindTypertRemote(this, this.name) 绑定，而 Cordis 的 Service.name 是 symbol 而非服务键字符串，导致网关校验失败：Receiver must be an instance of class ...。正确做法是普通类 + 显式绑定：
```
this.typertRemote = Object.freeze({ service: this, serviceKey: 'reaMcp', namespace: 'reaMcp' })
```
Remote 调用返回的是 { ok, value } 信封，客户端必须 if (!result || result.ok !== true) throw ... 后取 result.value；只判断 ok === false 会把信封当成结果，表现为「按钮点了没反应」。
无参端点要用空对象调用：gateway.invoke() 的入参不能省略 args，要传 args: {}。省略时参数校验会抛 Cannot convert undefined or null to object（浏览器侧的 Remote 调用方始终发 {}，所以只有 Host 自检脚本会踩到）。

7.4 验证脚本

node --check index.js; node --check client.js; node --check state.js   # 语法
node scripts/check-tool-schema.mjs   # 工具 schema 门禁（Harness 自己的检查器 + 8 个用例）
node scripts/probe-layer-order.mjs   # 分层覆盖机制：profile 层 disabled 为何无效
node scripts/probe-composition.mjs   # 组合结果中该行是否带 disabled
node scripts/probe-seam.mjs          # 缝表达式 × Harness 真实 YAML 方言与求值器
node scripts/probe-roundtrip.mjs     # 真实写/读 × 缝读取，含「损坏文件」降级分支
node scripts/acceptance.mjs          # 缝与状态文件口径一致性

不在 profile shell 里时，用参数显式给路径：

node scripts/acceptance.mjs '<PROFILE_DIR>' '<DSH_HOME>'

8. 卸载 / 回滚

plugin_manager → remove_bundle → dsh-rea-mcp-toggle；
删除家目录层里的 disabled: !!js >- ... 缝（保留该行其余内容），REA 即恢复为无条件启用；
可选：删除 %DSH_PROFILE_DIR%\.rea-mcp-toggle.state.json。

9. 许可

LICENSE 使用 MIT 标准文本，版权人为 VioletEverGarden-zc；package.json 的 license 字段同样是 MIT，三者口径一致。

10. 作者与仓库

作者：VioletEverGarden-zc — https://github.com/VioletEverGarden-zc
仓库：https://github.com/VioletEverGarden-zc/dsh-rea-mcp-toggle
上游项目：REA（Reverse Engineer Anything）— https://github.com/morluto/rea。本插件只提供「开关」，REA 本体及其 mcp__rea__* 工具集由上游项目提供与维护（MIT）。

仓库 URL 按包名 dsh-rea-mcp-toggle 填写。若你实际建仓时用了别的名字，请同步替换 package.json 里的 repository / homepage / bugs 三处与本节链接。

11. 致谢

感谢 REA（Reverse Engineer Anything）的作者与贡献者。本插件只是替它加了一只开关，逆向能力全部来自上游；没有 REA，这个项目没有存在的理由。

VioletEverGarden-zc/dsh-rea-mcp-toggle

dsh-rea-mcp-toggle

1. 项目解决什么问题

2. 主要功能

2.1 UI 开关（主入口）

2.2 模型工具 rea_mcp_toggle

2.3 状态持久化

2.4 工具可见性真正变化

2.5 进程生命周期

3. 安装方法

3.1 前置条件

3.2 安装本 bundle

3.3 安装家目录层的「开关缝」（必须，一次）

3.4 安装后自检

4. 使用方法

4.1 日常：点按钮

4.2 让模型帮你切

4.3 关闭 / 禁用的几种情况

5. 输入输出示例

5.1 查询状态

5.2 关闭 REA

5.3 开启 REA

5.4 幂等：重复同向不发写

5.5 诊断

5.6 UI 自检（判断是 UI 坏还是 Host 坏）

5.7 安装后的效果对照

6. 为什么不能用 profile 层的 disabled（关键设计决定）

7. 项目结构、已知限制与开发笔记

7.1 结构

7.2 已知限制

7.3 三个踩过的坑（写给后来者）

7.4 验证脚本

8. 卸载 / 回滚

9. 许可

10. 作者与仓库

11. 致谢

Community comments

VioletEverGarden-zc/dsh-rea-mcp-toggle

dsh-rea-mcp-toggle

1. 项目解决什么问题

2. 主要功能

2.1 UI 开关（主入口）

2.2 模型工具 rea_mcp_toggle

2.3 状态持久化

2.4 工具可见性真正变化

2.5 进程生命周期

3. 安装方法

3.1 前置条件

3.2 安装本 bundle

3.3 安装家目录层的「开关缝」（必须，一次）

3.4 安装后自检

4. 使用方法

4.1 日常：点按钮

4.2 让模型帮你切

4.3 关闭 / 禁用的几种情况

5. 输入输出示例

5.1 查询状态

5.2 关闭 REA

5.3 开启 REA

5.4 幂等：重复同向不发写

5.5 诊断

5.6 UI 自检（判断是 UI 坏还是 Host 坏）

5.7 安装后的效果对照

6. 为什么不能用 profile 层的 disabled（关键设计决定）

7. 项目结构、已知限制与开发笔记

7.1 结构

7.2 已知限制

7.3 三个踩过的坑（写给后来者）

7.4 验证脚本

8. 卸载 / 回滚

9. 许可

10. 作者与仓库

11. 致谢

Community comments

2.2 模型工具 `rea_mcp_toggle`

6. 为什么不能用 profile 层的 `disabled`（关键设计决定）

2.2 模型工具 `rea_mcp_toggle`

6. 为什么不能用 profile 层的 `disabled`（关键设计决定）