bookmark-research 0.5.0-beta.5 → 0.5.0-beta.6

package/.agents/plugins/marketplace.json

@@ -9,7 +9,7 @@
       "source": {
         "source": "npm",
         "package": "bookmark-research",
-        "version": "0.5.0-beta.4",
+        "version": "0.5.0-beta.5",
         "registry": "https://registry.npmjs.org"
       },
       "policy": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bookmark-research",
-  "version": "0.5.0-beta.5",
+  "version": "0.5.0-beta.6",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "author": {
     "name": "kwenxu"

package/README.md

@@ -22,13 +22,13 @@ Works in **Codex, Claude Code, Pi and DSH (DeepSeek Harness)**.
 
 ## Install
 
-**Current beta (`0.5.0-beta.5`)**, interactive on macOS, Linux and Windows:
+**Current beta (`0.5.0-beta.6`)**, interactive on macOS, Linux and Windows:
 
 ```sh
-npx bookmark-research@0.5.0-beta.5 install --source npm:bookmark-research@0.5.0-beta.5
+npx bookmark-research@0.5.0-beta.6 install --source npm:bookmark-research@0.5.0-beta.6
 ```
 
-This pins both the installer and the content. The `@latest` examples below follow the default channel, which remains `0.5.0-beta.3`; `@beta` currently points to `0.5.0-beta.5`. Changing only the npx selector does not change the installer's default content source.
+This pins both the installer and the content. The `@latest` examples below follow the default channel, which remains `0.5.0-beta.3`; `@beta` currently points to `0.5.0-beta.6`. Changing only the npx selector does not change the installer's default content source.
 
 **Default-channel interactive installation:**
 
@@ -51,6 +51,8 @@ For a permanent `bookmark-research` command: `npm install -g bookmark-research`.
 
 **One release source for all four hosts:** npm contains the shared runtime, Skill and host adapters. The installer downloads the release, prepares the selected host format, then invokes the host’s native commands. Updates retain an npm selector rather than an npx cache path. GitHub hosts source and installation catalogs; unpublished source uses the Python installer. See [distribution policy and official references](docs/distribution.md).
 
+**DSH installs the release directly:** the published package declares `dsh.bundle.patch`, so `dsh plugin --profile <name> add bookmark-research@<version>` — or the DSH plugin manager — installs it with no export first, resolving Python and MCP paths from the installed package. DeepSeek Harness Desktop reserves the `desktop` profile for its own carrier, so install that one with the app's CLI. See the [installation guide](docs/installation.en.md).
+
 **Windows:** the installer writes the detected Python path into each client's MCP config, because Windows often has no working `python3`. Install Codex with `bookmark-research install codex` rather than adding the repository to Codex directly. `bookmark-research status` shows the interpreter in use.
 
 Several at once: `npx bookmark-research@latest install claude dsh --profile web --non-interactive`. Project scope: `--scope project --project /path/to/project` (Claude Code, Pi). All options: [installation guide](docs/installation.en.md).

package/README.zh.md

@@ -22,13 +22,13 @@
 
 ## 安装
 
-**当前测试版（`0.5.0-beta.5`）**，支持 macOS、Linux、Windows 交互安装：
+**当前测试版（`0.5.0-beta.6`）**，支持 macOS、Linux、Windows 交互安装：
 
 ```sh
-npx bookmark-research@0.5.0-beta.5 install --source npm:bookmark-research@0.5.0-beta.5
+npx bookmark-research@0.5.0-beta.6 install --source npm:bookmark-research@0.5.0-beta.6
 ```
 
-这条命令同时固定安装器和插件内容。下面的 `@latest` 示例使用默认渠道，目前仍为 `0.5.0-beta.3`；`@beta` 当前指向 `0.5.0-beta.5`。只改 npx 的版本选择，不会改变安装器默认下载的内容来源。
+这条命令同时固定安装器和插件内容。下面的 `@latest` 示例使用默认渠道，目前仍为 `0.5.0-beta.3`；`@beta` 当前指向 `0.5.0-beta.6`。只改 npx 的版本选择，不会改变安装器默认下载的内容来源。
 
 **默认渠道的交互安装：**
 
@@ -51,6 +51,8 @@ npx bookmark-research@latest install
 
 **四个宿主统一发布来源：** npm 包包含共享运行时、Skill 和宿主适配。安装器下载发布包，生成所选宿主格式，再调用宿主原生命令；更新记录 npm 来源，不依赖 npx 临时缓存。GitHub 提供源码和安装清单，未发布源码用 Python 安装器。见[发布约定与官方依据](docs/distribution.md)。
 
+**DSH 可直接安装发布包：** 发布包声明 `dsh.bundle.patch`，`dsh plugin --profile <名称> add bookmark-research@<版本>`（或 DSH 插件管理界面）无需先导出即可安装，Python 与 MCP 路径按安装位置解析。DeepSeek Harness 桌面版把 `desktop` profile 保留给自身载体，该 profile 请用桌面版自带 CLI 安装。详见[安装说明](docs/installation.md)。
+
 **Windows：** Windows 上常常没有能用的 `python3`，所以安装器会把检测到的 Python 路径写进各宿主的 MCP 配置。Codex 请用 `bookmark-research install codex` 安装，不要直接把仓库加进 Codex。`bookmark-research status` 可以查看实际使用的 Python。
 
 一次装多个：`npx bookmark-research@latest install claude dsh --profile web --non-interactive`。装到指定项目：`--scope project --project /path/to/project`（Claude Code、Pi）。全部参数见[安装说明](docs/installation.md)。

package/bundle.patch.yml

@@ -0,0 +1,18 @@
+# DeepSeek Harness bundle layer. Paths resolve from the installed package through
+# the module's context, so this file is identical in the npm package and in an
+# exported copy; `python` and the forwarded environment come from the module
+# (see hosts/dsh/plugin.js), not from this machine.
+- insert:
+    - id: bookmark-research-skill
+      name: bookmark-research
+    - id: bookmark-research-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      inject: [bookmarkResearchPaths]
+      config:
+        serverName: bookmark-research
+        transport: stdio
+        command: !!js ctx.bookmarkResearchPaths.python.command
+        args: !!js ctx.bookmarkResearchPaths.mcpArgs
+        cwd: !!js ctx.bookmarkResearchPaths.root
+        env: !!js ctx.bookmarkResearchPaths.env
+        failOnStartupError: true

package/docs/distribution.md

@@ -19,7 +19,7 @@
 
 发布顺序：修改源码版本并完成 CI，发布已经验证的 npm 包，确认 registry 可取得该版本，再更新 GitHub marketplace 的固定版本。未发布源码不能通过 npm 入口安装；需要先用源码入口测试。
 
-测试版使用 npm 的 `beta` 标签；若创建 GitHub 版本说明，则标记为预发布。不会自动移动 npm 的 `latest` 标签。安装测试版时同时固定安装器与内容来源，例如 `npx bookmark-research@0.5.0-beta.5 install --source npm:bookmark-research@0.5.0-beta.5`。仅将 npx 改为 `@beta` 不会改变默认内容来源 `latest`；已固定的旧版安装也不会自动换成测试版。
+测试版使用 npm 的 `beta` 标签；若创建 GitHub 版本说明，则标记为预发布。不会自动移动 npm 的 `latest` 标签。安装测试版时同时固定安装器与内容来源，例如 `npx bookmark-research@0.5.0-beta.6 install --source npm:bookmark-research@0.5.0-beta.6`。仅将 npx 改为 `@beta` 不会改变默认内容来源 `latest`；已固定的旧版安装也不会自动换成测试版。
 
 ## 官方资料与项目实例
 

package/docs/harness-compatibility.md

@@ -1,8 +1,8 @@
 # 宿主兼容、工作流与打包
 
-更新日期：2026-09-13。四宿主共用同一 Skill、Python CLI、stdio MCP 和研究档案。当前宿主模型负责规划、搜索／阅读、判断证据、按缺口补查及综合；原生协作支持独立分工。Deep Research 在这条流程上增加持续调查、独立核验、覆盖检查和报告。外部研究 API 可承担具体子问题，缺少它们仍能研究。
+更新日期：2026-10-08。四宿主共用同一 Skill、Python CLI、stdio MCP 和研究档案。当前宿主模型负责规划、搜索／阅读、判断证据、按缺口补查及综合；原生协作支持独立分工。Deep Research 在这条流程上增加持续调查、独立核验、覆盖检查和报告。外部研究 API 可承担具体子问题，缺少它们仍能研究。
 
-**正文依据、文件生成、隔离脚本检查、真实 MCP 调用和宿主端到端研究是不同验证层级。** 本轮没有安装 Pi / DSH、改全局配置或启动付费研究模型。具体脚本调用和研究规则见 [宿主工作流参考](../skills/bookmark-research/references/host-workflows.md)。
+**正文依据、文件生成、隔离脚本检查、真实 MCP 调用和宿主端到端研究是不同验证层级。** 本轮在 DSH 桌面版 profile `desktop` 上完成了一次真实安装，并观察到 Skill 注册与 MCP 工具实际应答；Pi 仍未安装，未改全局配置，未启动付费研究模型。具体脚本调用和研究规则见 [宿主工作流参考](../skills/bookmark-research/references/host-workflows.md)。
 
 | 宿主 | 协作基础与本插件入口 | 生命周期与限制 |
 | --- | --- | --- |
@@ -58,7 +58,7 @@
 | Claude Code 插件 | `.claude-plugin/plugin.json`；当前文档允许省略 manifest 后按约定发现组件 | 根 `skills/`、`.mcp.json` 或 manifest 配置 | 单独保留 Claude manifest／MCP 配置 |
 | Agent Plugins 1.0.0 标准包 | **根 `plugin.json`**，必填 `$schema` 与 `name` | 固定发现根 `skills/`、`mcp.json` | 从同一源码独立导出标准包 |
 | Pi | `package.json` 的 `pi` 字段，或资源目录约定 | 原生 skills／extensions；MCP 要靠扩展 | `pi.skills`＋Skill 调用 CLI；多组任务另登记项目工作流 |
-| DeepSeek Harness（DSH） | `--patch` 加载 Cordis 配置；可发布 bundle 另有 `package.json` 的 `dsh.bundle.patch` | 原生 Skill provider；官方 `dsh-mcp-client` 桥接 MCP tools | 导出使用绝对路径的本机 `cordis.patch.yml` 适配文件 |
+| DeepSeek Harness（DSH） | 包在 `package.json` 声明 `dsh.bundle.patch`，由 `dsh plugin` 或插件管理器安装；`--patch` 仍可手工加载 Cordis 配置 | 原生 Skill provider；官方 `dsh-mcp-client` 桥接 MCP tools | 发布包自带按安装位置解析的 `bundle.patch.yml`，registry 可直接安装；绝对路径 `cordis.patch.yml` 仅作手工适配 |
 
 这些入口不是同一文件的不同别名。符合 Agent Skills 的 `SKILL.md` 和 MCP 协议是主要复用边界；某个客户端能加载 Skill，并不表示它已经支持 Agent Plugins 的根 manifest。[H01][H04][H05][P02][D02]
 
@@ -157,7 +157,9 @@ DSH 的原生运行插件是 Cordis 模块，可导出 `name`、`inject` 和 `ap
 
 `command` 与 `args` 分开传递。不要在这个 DSH 片段里假设 `${PLUGIN_ROOT}` 会像 Codex／Agent Plugins 一样展开；本轮核实的 MCP 客户端并未定义这种插件根占位符约定。绝对路径片段适合本机 checkout；搬迁或重新安装到其他位置后需要重新生成。DSH 的 patch 文件位置也不会改变模块路径解析所依据的 profile 目录。[D03][D05]
 
-本次 DSH 导出是**本机配置适配文件**，不生成声明 `dsh.bundle` 的 `package.json`，也不安装 DSH 或官方 MCP client。后续如果要发布可搬迁 npm bundle，需要增加按安装位置解析源码路径的适配器，并按官方规则声明 `dsh.bundle.patch`；不能发布硬编码本机路径的配置并称其可移植。[D02][D03]
+发布包现在**自带** `bundle.patch.yml` 并在 `package.json` 声明 `dsh.bundle.patch`，因此 `dsh plugin --profile <name> add bookmark-research@<version>`（以及 DSH 插件管理界面）可以直接从 registry 安装；`dsh` 的 bundle 对账逻辑会把声明了 `dsh.bundle` 且 patch 存在的包自动加入 `dsh.profile.bundles`。层内不写死本机路径：`command`、`args`、`cwd` 与转发的环境变量都由入口模块 `hosts/dsh/plugin.js` 在加载时提供（`bookmarkResearchPaths.python/mcpArgs/env`），模块用与 npm 启动器相同的顺序发现 Python 3.9+／SQLite，所以导出副本、registry 安装和 Windows 都不需要重生成 patch。统一安装器仍导出带校验和的固定副本，用于可验证的托管安装；对不含该文件的旧发布包或旧 Git ref，导出器按模块的旧契约生成等价层，安装不回归。[D02][D03]
+
+DSH 桌面版把 profile 名 `desktop` 保留给 Electron 载体：启动器对该名字拒绝一切 boot／dump（`--dump-config` 亦然），只有载体自身可以管理其插件。因此对 `desktop` 的安装须用桌面版自带 CLI（`--dsh "<App>/Contents/Resources/runtime/cli/bin/dsh"`，它自带 pnpm，无需 PATH 中的 pnpm），安装器的验证改为读取持久层：profile 依赖指向该包、`dsh.bundle.patch` 与入口模块按包目录相对解析且文件存在、层内包含 Skill 与 MCP 行。2026-10-08 在本机（macOS、桌面运行时 0.2.0-rc.2、发布包 0.5.0-beta.5）实测：注册后 Skill 出现在宿主目录，`mcp__bookmark-research__*` 工具正常应答，运行中的 MCP 子进程解析到已安装包目录。[D02][D08]
 
 导出及查看合并配置的形式是：
 
@@ -166,7 +168,7 @@ python3 scripts/export_bundle.py --format dsh --output /private/tmp/bookmark-res
 dsh --profile web --patch /private/tmp/bookmark-research-dsh/cordis.patch.yml --dump-config
 ```
 
-实际启动可使用 `dsh web --patch <绝对配置路径>`。这些命令要求 DSH 环境已具备对应 MCP client 依赖，属于待客户端验证的接入说明；本文没有安装或修改 DSH profile。新建任意名称的 profile 默认只有 base bundle；`web` profile 才会按官方模板包含 Web 表面，不应把“创建一个任意 profile”描述成自动创建了完整 Web 应用。[D02][D08]
+实际启动可使用 `dsh web --patch <绝对配置路径>`。该手工路线仍属待客户端验证的接入说明，且不覆盖保留的 `desktop` profile。新建任意名称的 profile 默认只有 base bundle；`web` profile 才会按官方模板包含 Web 表面，不应把“创建一个任意 profile”描述成自动创建了完整 Web 应用。[D02][D08]
 
 `dsh plugin` 在 profile 目录中通过 pnpm 管理依赖，并把声明了 `dsh.bundle` 的包加入 `dsh.profile.bundles`。没有该声明的 npm 包仍能作为普通依赖安装，但不会自动增加插件配置层。后层 patch 会替换命中行的整个 `config`，不做深度合并。[D02][D08]
 

package/docs/host-validation.json

@@ -294,5 +294,36 @@
       "Codex feature state and Claude manifest validation do not prove native tools or account access in an arbitrary session.",
       "Local correlation IDs beginning local: are not native host run IDs."
     ]
+  },
+  "host_install_review": {
+    "checked_on": "2026-10-08",
+    "host": "dsh",
+    "profile": "desktop",
+    "runtime_version": "0.2.0-rc.2",
+    "package_version": "0.5.0-beta.5",
+    "methods": [
+      "scripts/install.py install --host dsh --profile desktop with the managed export from this source tree",
+      "dsh plugin --profile <throwaway> add <packed release tarball> (registry-equivalent spec)"
+    ],
+    "observed": {
+      "bundle_selected_into_profile": true,
+      "skill_registered_in_host": true,
+      "mcp_tools_listed": 37,
+      "mcp_child_resolved_to_installed_package": true,
+      "composed_rows": [
+        "bookmark-research-skill",
+        "bookmark-research-mcp"
+      ],
+      "desktop_profile_dump_refused": true,
+      "managed_receipt_state": "verified",
+      "managed_export_files": 71,
+      "unit_tests_passed": 506,
+      "temporary_test_profile_removed": true
+    },
+    "not_verified": [
+      "a published npm release that carries bundle.patch.yml; the released 0.5.0-beta.5 predates it",
+      "Windows or Pi installation",
+      "the npm cache permission retry on a failing machine (unit-tested only; this machine used npm_config_cache instead)"
+    ]
   }
 }

package/docs/installation.en.md

@@ -181,7 +181,16 @@ python3 scripts/install.py install --host dsh --profile web
 python3 scripts/install.py verify --host dsh --profile web
 ```
 
-The installer exports a relocatable `dsh.bundle` and calls `dsh plugin --profile web add PATH`. `dsh plugin` delegates to pnpm, so install it first (`npm install -g pnpm` or `corepack enable pnpm`); without it the installer stops before creating a profile and the wizard shows DSH as unavailable. The bundle registers the shared Skill and resolves Python/MCP paths from the installed module. The selected profile must provide the Skill registry and official MCP client. For local development, export with `--format dsh` and install the stable export using that native command. The legacy `cordis.patch.yml` still contains absolute paths and requires separate Skill discovery. Workflow execution separately requires the host service/engine; `hosts/dsh/workflow-call.py --research-id RID --run-key KEY` prepares a call without launching it.
+The installer exports a relocatable `dsh.bundle` and calls `dsh plugin --profile web add PATH`. A released package also installs straight from the registry: it declares `dsh.bundle.patch` and ships that layer, so `dsh plugin --profile web add bookmark-research@VERSION` — or the DSH plugin manager — needs no export first. The layer resolves the interpreter, the working directory and the MCP argument list from the installed module, so nothing is tied to the machine that built it; the selected profile must still provide the Skill registry and the official `@deepseek-ai/dsh-mcp-client`.
+
+`dsh plugin` delegates to pnpm. A generic CLI therefore needs pnpm on PATH (`npm install -g pnpm` or `corepack enable pnpm`) and the installer stops before creating a profile without it; the DeepSeek Harness Desktop CLI carries its own pnpm and needs none. DeepSeek Harness Desktop reserves the `desktop` profile — its launcher refuses every boot and dump for that name — so install it with the app's own CLI, and verification reads the persisted layer instead of `--dump-config`:
+
+```sh
+python3 scripts/install.py install --host dsh --profile desktop \
+  --dsh "<DSH app>/Contents/Resources/runtime/cli/bin/dsh"
+```
+
+The legacy `cordis.patch.yml` still contains absolute paths and requires separate Skill discovery. Workflow execution separately requires the host service/engine; `hosts/dsh/workflow-call.py --research-id RID --run-key KEY` prepares a call without launching it.
 
 ### Agent Plugins 1.0.0
 

package/docs/installation.md

@@ -237,14 +237,23 @@ pi_subagent_workflow({action:"run",name:"bookmark-research",args:{research_id:"R
 
 ### DSH / DeepSeek Harness
 
-所选 DSH profile 需提供 Skill registry 和官方 `@deepseek-ai/dsh-mcp-client`。`dsh plugin` 由 pnpm 执行，请先安装（`npm install -g pnpm` 或 `corepack enable pnpm`）；缺少时安装器会在创建 profile 前停止，向导中 DSH 显示为不可选。统一安装器生成可搬移的 `dsh.bundle`，调用原生 `dsh plugin --profile web add PATH`，注册 Skill 并从安装后位置解析 Python／MCP 路径：
+所选 DSH profile 需提供 Skill registry 和官方 `@deepseek-ai/dsh-mcp-client`。发布包自带 `bundle.patch.yml` 并声明 `dsh.bundle.patch`，因此除统一安装器之外，也可以直接从 registry 安装：`dsh plugin --profile <name> add bookmark-research@VERSION`，或在 DSH 插件管理界面按同一个 spec 安装；DSH 会把声明了 `dsh.bundle` 且 patch 存在的包自动加入 `dsh.profile.bundles`。层内不写死本机路径，Python 解释器、工作目录、MCP 参数与环境转发都由入口模块按安装位置解析。
+
+统一安装器生成可搬移的 `dsh.bundle`，调用原生 `dsh plugin --profile web add PATH`，注册 Skill 并从安装后位置解析 Python／MCP 路径：
 
 ```sh
 python3 scripts/install.py install --host dsh --profile web
 python3 scripts/install.py verify --host dsh --profile web
 ```
 
-手动分发时使用 `export_bundle.py --format dsh`，再用上述原生命令安装稳定导出目录。保留的旧 `cordis.patch.yml` 仍含绝对路径，需单独配置 Skill 发现；移动后应重新生成。多组研究另需 workflow service、worker-thread engine 和 `workflow` tool。参见 [官方 MCP client 文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md)。
+`dsh plugin` 由 pnpm 执行：通用 CLI 需要 PATH 中的 pnpm（`npm install -g pnpm` 或 `corepack enable pnpm`），缺少时安装器在创建 profile 前停止；DSH 桌面版 CLI 自带 pnpm，无需另装。桌面版把 profile 名 `desktop` 保留给 Electron 载体，其启动器对该名字拒绝 boot／dump，因此用桌面版自带 CLI 安装，验证改为读取持久层而非 `--dump-config`：
+
+```sh
+python3 scripts/install.py install --host dsh --profile desktop \
+  --dsh "<DSH 应用>/Contents/Resources/runtime/cli/bin/dsh"
+```
+
+手动分发时使用 `export_bundle.py --format dsh`，再用上述原生命令安装稳定导出目录；不含该层的旧发布包或旧 Git ref 仍会按模块的旧契约生成等价层。保留的旧 `cordis.patch.yml` 仍含绝对路径，需单独配置 Skill 发现；移动后应重新生成。多组研究另需 workflow service、worker-thread engine 和 `workflow` tool。参见 [官方 MCP client 文档](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md)。
 
 生成可直接传给宿主 `workflow` 工具的完整 JSON：
 

package/docs/release-notes-0.5.0-beta.6.md

@@ -0,0 +1,30 @@
+# Bookmark Research 0.5.0 beta 6
+
+**Beta / 测试版.** Uses the npm `beta` channel. The npm `latest` tag remains unchanged.
+
+## Install this beta
+
+Pin both the installer and the plugin content:
+
+```sh
+npx bookmark-research@0.5.0-beta.6 install --source npm:bookmark-research@0.5.0-beta.6
+```
+
+Choose Codex, Claude Code, Pi or DSH in the installer. Existing installations retain their recorded source and version selection. The GitHub Codex marketplace advances to this npm version after the registry confirms publication.
+
+## Changes
+
+- **DSH installs the release directly.** The package now declares `dsh.bundle.patch` and ships `bundle.patch.yml`, so `dsh plugin --profile <name> add bookmark-research@0.5.0-beta.6` — or the DSH plugin manager — installs it with no export step first, and DSH selects the bundle into `dsh.profile.bundles` on its own. Nothing in the layer is tied to the building machine: the entry module supplies the interpreter, working directory, MCP arguments and forwarded environment variables at load time.
+- **No `python3` assumption in the DSH layer.** The module discovers Python 3.9+ with SQLite in the same order as the npm launcher (`BOOKMARK_RESEARCH_PYTHON`, `python3`, `python`, `py -3`) and reports a warning instead of failing silently when none is found, so Windows no longer depends on a `python3` alias.
+- **DSH Desktop's reserved profile is installable.** DeepSeek Harness Desktop refuses to boot or dump the profile name `desktop`, so the installer verifies that profile from the persisted layer (dependency target, package-relative `dsh.bundle.patch`, entry module, Skill and MCP rows) instead of `--dump-config`.
+- **A bundled package manager satisfies the DSH prerequisite.** A CLI that carries its own pnpm — the DeepSeek Harness Desktop CLI does — no longer requires `pnpm` on `PATH`; a generic CLI still fails before creating a profile, with instructions.
+- **Unwritable npm caches are diagnosed and retried.** When npm reports a cache permission failure (for example root-owned files from a privileged install), the download retries once in a scratch cache and otherwise reports the `chown` repair command.
+- **The exported DSH bundle is the released layer.** `export_bundle.py --format dsh` copies the committed `bundle.patch.yml` byte for byte; a source tree that predates the layer (an older published package or Git ref) still exports a working equivalent, so pinned installations do not regress.
+
+## Validation and limits
+
+The functional diff passed 506 discovered local tests, including new coverage for the released DSH layer, the offline verification of the reserved `desktop` profile, the bundled package manager, and the npm cache retry. A real installation into the DeepSeek Harness Desktop profile (`desktop`, runtime `0.2.0-rc.2`) registered the Skill, listed 37 MCP tools, and resolved the running MCP child to the installed package; a packed release installed in a throwaway profile was selected into `dsh.profile.bundles` automatically.
+
+Not verified in this release: Windows and Pi installation, and the cache-retry path on a machine whose npm cache is genuinely unwritable. These are covered by unit tests only. No paid research model was started.
+
+Install from [npm](https://www.npmjs.com/package/bookmark-research/v/0.5.0-beta.6). GitHub supplies source, version notes and installation catalogs; npm remains the shared release package for all four hosts.

package/hosts/dsh/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/hosts/dsh/plugin.js

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 
@@ -6,6 +7,7 @@ export const inject = ["skills"];
 
 // The module travels with the Python runtime; no exporting machine's path is embedded.
 const root = fileURLToPath(new URL("../../", import.meta.url));
+const cli = fileURLToPath(new URL("../../src/cli.py", import.meta.url));
 const skillUrl = new URL("../../skills/bookmark-research/SKILL.md", import.meta.url);
 const resourceBase = { kind: "directory", path: fileURLToPath(new URL("./", skillUrl)) };
 const candidate = {
@@ -20,10 +22,56 @@ const candidate = {
   locator: skillUrl,
 };
 
+// The MCP child inherits only these variables, so saved data/config paths and
+// provider keys survive without baking values into a published patch. This list
+// must equal the native manifest's mcpServers env_vars; tests assert that parity.
+const FORWARDED_ENV = [
+  "BOOKMARK_RESEARCH_DATA_DIR",
+  "BOOKMARK_RESEARCH_CONFIG",
+  "BOOKMARK_RESEARCH_CREDENTIALS",
+  "XDG_DATA_HOME",
+  "XDG_CONFIG_HOME",
+  "EXA_API_KEY",
+  "PARALLEL_API_KEY",
+  "TAVILY_API_KEY",
+  "JINA_API_KEY",
+  "OPENAI_API_KEY",
+  "SystemRoot",
+  "windir",
+];
+
+// The same discovery order as the npm launcher: an explicit interpreter, then
+// the platform aliases, each accepted only with Python 3.9+ and SQLite present.
+const PYTHON_PROBE = "import sys, sqlite3; sys.exit(0 if sys.version_info >= (3, 9) else 3)";
+
+function findPython() {
+  const candidates = [];
+  if (process.env.BOOKMARK_RESEARCH_PYTHON) candidates.push([process.env.BOOKMARK_RESEARCH_PYTHON]);
+  candidates.push(["python3"], ["python"]);
+  if (process.platform === "win32") candidates.push(["py", "-3"]);
+  for (const [command, ...args] of candidates) {
+    const probe = spawnSync(command, [...args, "-c", PYTHON_PROBE], { stdio: "ignore", windowsHide: true });
+    if (probe.status === 0) return { command, args };
+  }
+  return undefined;
+}
+
 export function apply(ctx) {
+  let python = findPython();
+  if (python === undefined) {
+    process.stderr.write("bookmark-research: no Python 3.9+ with SQLite was found; the MCP client will try python3. "
+      + "Set BOOKMARK_RESEARCH_PYTHON to select an interpreter.\n");
+    python = { command: "python3", args: [] };
+  }
+  const env = Object.fromEntries(FORWARDED_ENV
+    .filter((key) => process.env[key] !== undefined)
+    .map((key) => [key, process.env[key]]));
   ctx.provide("bookmarkResearchPaths", {
     root,
-    cli: fileURLToPath(new URL("../../src/cli.py", import.meta.url)),
+    cli,
+    python,
+    mcpArgs: [...python.args, cli, "serve"],
+    env,
   });
   ctx.skills.registerProvider(() => ({
     name,

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "bookmark-research",
-  "version": "0.5.0-beta.5",
+  "version": "0.5.0-beta.6",
   "description": "Check bookmark URLs or Canvas packages, compare sources with host-led research, and retain verifiable reports.",
   "license": "GPL-3.0-only",
   "repository": {"type": "git", "url": "git+https://github.com/Browser-bookmark-hub/Bookmark-Research.git"},
   "keywords": ["bookmark-research", "mcp", "claude-code", "codex", "pi-package", "deepseek-harness"],
   "bin": {"bookmark-research": "bin/bookmark-research.js"},
+  "main": "./hosts/dsh/plugin.js",
   "engines": {"node": ">=18"},
-  "files": ["bin", "src", "scripts", "config", "skills", "hosts", "docs", ".codex-plugin/plugin.json", ".agents/plugins/marketplace.json", "install.sh", "LICENSE", "README.md", "README.zh.md", "!**/__pycache__", "!**/*.pyc"],
-  "pi": {"skills": ["./skills"]}
+  "files": ["bin", "src", "scripts", "config", "skills", "hosts", "docs", "bundle.patch.yml", ".codex-plugin/plugin.json", ".agents/plugins/marketplace.json", "install.sh", "LICENSE", "README.md", "README.zh.md", "!**/__pycache__", "!**/*.pyc"],
+  "pi": {"skills": ["./skills"]},
+  "dsh": {"bundle": {"patch": "./bundle.patch.yml"}}
 }

package/scripts/build_zip.py

@@ -43,6 +43,7 @@ EXTRA_FILES = (
     "scripts/launcher.py",
     "bin/bookmark-research.js",
     "package.json",
+    "bundle.patch.yml",
     "docs/details.md",
     "docs/details.en.md",
     "skills/bookmark-research/agents/openai.yaml",

package/scripts/export_bundle.py

@@ -16,6 +16,8 @@ from host_assets import export_host_assets
 SOURCE_ROOT = Path(__file__).resolve().parents[1]
 FORMATS = ("codex", "agent-plugin", "claude", "pi", "dsh")
 NAME = "bookmark-research"
+# The DSH bundle layer a released tree ships and declares in `dsh.bundle.patch`.
+BUNDLE_PATCH = "bundle.patch.yml"
 SCHEMA_ROOT = "https://agent-plugins.org/schemas/1.0.0/"
 SHARED_ROOTS = ("src", "config", "skills")
 SHARED_DOCUMENTS = (
@@ -366,8 +368,34 @@ Reference: https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/
     return introduction + instructions
 
 
-def _write_adapter(stage, format_name, output, manifest, python="python3"):
+def _generated_bundle_patch(python, environment):
+    """The bundle layer for a source tree that does not ship `bundle.patch.yml`.
+
+    Released trees carry the committed patch, which resolves the interpreter and
+    the forwarded environment from the module. An older published package or Git
+    ref only provides `root` and `cli`, so its generated layer must stay on that
+    narrower contract.
+    """
+    return """- insert:
+    - id: bookmark-research-skill
+      name: bookmark-research
+    - id: bookmark-research-mcp
+      name: '@deepseek-ai/dsh-mcp-client'
+      inject: [bookmarkResearchPaths]
+      config:
+        serverName: bookmark-research
+        transport: stdio
+        command: %s
+        args: !!js "[ctx.bookmarkResearchPaths.cli, 'serve']"
+        cwd: !!js ctx.bookmarkResearchPaths.root
+        env: !!js %s
+        failOnStartupError: true
+""" % (json.dumps(python), environment)
+
+
+def _write_adapter(stage, format_name, output, manifest, python="python3", source_root=SOURCE_ROOT):
     metadata = {"name": NAME, "version": manifest["version"], "description": manifest["description"]}
+    adapter = {}
     if format_name == "codex":
         if python != "python3":
             # Codex registers this manifest verbatim; pin the detected interpreter.
@@ -408,27 +436,21 @@ def _write_adapter(stage, format_name, output, manifest, python="python3"):
         _write_json(stage, "package.json", {
             **metadata, "type": "module", "main": "./hosts/dsh/plugin.js",
             "exports": "./hosts/dsh/plugin.js",
-            "files": ["src", "config", "skills", "hosts", "workflows", "docs", "bundle.patch.yml", "LICENSE"],
-            "dsh": {"bundle": {"patch": "./bundle.patch.yml"}},
+            "files": ["src", "config", "skills", "hosts", "workflows", "docs", BUNDLE_PATCH, "LICENSE"],
+            "dsh": {"bundle": {"patch": "./" + BUNDLE_PATCH}},
         })
         forwarded = manifest["mcpServers"][NAME]["env_vars"]
         environment = json.dumps("Object.fromEntries(" + json.dumps(forwarded) +
             ".filter(key => process.env[key] !== undefined).map(key => [key, process.env[key]]))")
-        (stage / "bundle.patch.yml").write_text("""- insert:
-    - id: bookmark-research-skill
-      name: bookmark-research
-    - id: bookmark-research-mcp
-      name: '@deepseek-ai/dsh-mcp-client'
-      inject: [bookmarkResearchPaths]
-      config:
-        serverName: bookmark-research
-        transport: stdio
-        command: %s
-        args: !!js "[ctx.bookmarkResearchPaths.cli, 'serve']"
-        cwd: !!js ctx.bookmarkResearchPaths.root
-        env: !!js %s
-        failOnStartupError: true
-""" % (json.dumps(python), environment), encoding="utf-8")
+        committed = Path(source_root) / BUNDLE_PATCH
+        if not committed.is_symlink() and committed.is_file():
+            # The released tree ships the layer; copying it keeps the npm package
+            # and the exported bundle on byte-identical patch content.
+            (stage / BUNDLE_PATCH).write_bytes(committed.read_bytes())
+            adapter["bundle_patch"] = "committed"
+        else:
+            (stage / BUNDLE_PATCH).write_text(_generated_bundle_patch(python, environment), encoding="utf-8")
+            adapter["bundle_patch"] = "generated"
         # JSON strings are valid YAML scalars, including paths with spaces/quotes.
         cli_path = json.dumps(str(output / "src/cli.py"), ensure_ascii=False)
         patch = """- insert:
@@ -446,6 +468,7 @@ def _write_adapter(stage, format_name, output, manifest, python="python3"):
 """ % (json.dumps(python), cli_path, environment)
         (stage / "cordis.patch.yml").write_text(patch, encoding="utf-8")
     (stage / "README.md").write_text(_readme(format_name, output), encoding="utf-8")
+    return adapter
 
 
 def export_bundle(format_name, output, source_root=SOURCE_ROOT, python="python3"):
@@ -473,13 +496,13 @@ def export_bundle(format_name, output, source_root=SOURCE_ROOT, python="python3"
             destination.parent.mkdir(parents=True, exist_ok=True)
             shutil.copy2(source_root / relative, destination)
         host_files = export_host_assets(source_root, stage, format_name)
-        _write_adapter(stage, format_name, output, manifest, python)
+        adapter = _write_adapter(stage, format_name, output, manifest, python, source_root=source_root)
         _check_destination(output)
         if output.exists():
             output.rmdir()  # Only an empty directory can be removed here.
         stage.rename(output)  # Renaming a directory cannot replace nonempty data.
     return {"format": format_name, "version": manifest["version"], "output": str(output), "shared_files": len(files),
-            "host_files": host_files, "installed": False}
+            "host_files": host_files, "adapter": adapter, "installed": False}
 
 
 def main(argv=None):

package/scripts/host_assets.py

@@ -7,6 +7,7 @@ from pathlib import Path
 HOST_SOURCE_FILES = (
     "hosts/shared/workflow.json", "hosts/shared/research-flow.js", "hosts/shared/research-call.py",
     "hosts/claude/runtime.js", "hosts/dsh/runtime.js", "hosts/dsh/workflow-call.py", "hosts/dsh/plugin.js",
+    "hosts/dsh/package.json",
     "hosts/pi/runtime.js", "hosts/pi/register-workflow.py",
     "hosts/codex/delegate.md", "hosts/codex/prepare.py",
 )
@@ -59,6 +60,9 @@ def export_host_assets(source, stage, host):
                 relative = "hosts/pi/register-workflow.py"
             else:
                 files["hosts/dsh/plugin.js"] = read_asset(source, "hosts/dsh/plugin.js")
+                # Scope ESM to the entry module so a package root may stay CommonJS
+                # (the npm package keeps a CommonJS bin and the pi field).
+                files["hosts/dsh/package.json"] = read_asset(source, "hosts/dsh/package.json")
                 files["workflows/bookmark-research/meta.json"] = (
                     json.dumps(definition["meta"], ensure_ascii=False, indent=2) + "\n").encode("utf-8")
                 relative = "hosts/dsh/workflow-call.py"

package/scripts/host_clients.py

@@ -23,6 +23,28 @@ def executable(binary):
     return found
 
 
+def bundled_pnpm(binary):
+    """The package manager a DSH CLI carries itself, if it ships one.
+
+    DeepSeek Harness Desktop runs `dsh plugin` with its own bundled pnpm, so that
+    carrier needs no `pnpm` on PATH. A generic CLI installs profile plugins by
+    forwarding to the pnpm it finds instead.
+    """
+    found = executable(binary)
+    if not found:
+        return None
+    try:
+        path = Path(found).resolve()
+    except OSError:
+        return None
+    # Desktop layout: <resources>/runtime/cli/bin/dsh beside <resources>/runtime/pnpm.
+    for parent in list(path.parents)[:5]:
+        candidate = parent / "pnpm" / "bin" / "pnpm.mjs"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
 def read_json(path, default=None):
     if not path.exists():
         return default
@@ -81,10 +103,11 @@ class HostClient:
     def require(self):
         if not executable(self.binary):
             raise ValueError(self.host + " CLI was not found: " + self.binary)
-        if self.host == "dsh" and not shutil.which("pnpm"):
-            # dsh plugin forwards to pnpm; fail before creating a profile.
-            raise ValueError("DSH installs profile plugins with pnpm, which was not found on PATH; "
-                             "install it (npm install -g pnpm, or corepack enable pnpm) and retry")
+        if self.host == "dsh" and not shutil.which("pnpm") and bundled_pnpm(self.binary) is None:
+            # A generic dsh forwards `plugin` to pnpm; fail before creating a profile.
+            raise ValueError("DSH installs profile plugins with pnpm, which was not found on PATH and is not bundled with "
+                             + self.binary + "; install it (npm install -g pnpm, or corepack enable pnpm) and retry, "
+                             "or pass the DeepSeek Harness Desktop CLI with --dsh (it carries its own pnpm)")
 
     def run(self, arguments, structured=False, quiet_error=False):
         result = subprocess.run([executable(self.binary) or self.binary, *arguments], cwd=self.cwd, text=True, encoding="utf-8", errors="replace",
@@ -186,11 +209,50 @@ class HostClient:
         if self.host == "dsh":
             if not registration["enabled"]:
                 raise RuntimeError("DSH installed the dependency without enabling its bundle")
-            composition = self.run(["--profile", self.profile, "--dump-config"], quiet_error=True)
-            if not all(name in composition for name in ("bookmark-research-skill", "bookmark-research-mcp", "bookmarkResearchPaths")):
-                raise RuntimeError("DSH composition is missing the Bookmark Research Skill or MCP configuration")
             package = self.settings.parent / "node_modules" / NAME
             if not package.is_dir():
                 raise RuntimeError("DSH did not retain the installed bundle in its profile")
+            if self.profile.casefold() == "desktop":
+                # DeepSeek Harness Desktop reserves this profile name: its launcher
+                # refuses every boot and dump for "desktop" (only the Electron carrier
+                # may manage it), so read the persisted layer the way the launcher does.
+                composition = self.desktop_composition(package)
+            else:
+                composition = self.run(["--profile", self.profile, "--dump-config"], quiet_error=True)
+            if not all(name in composition for name in ("bookmark-research-skill", "bookmark-research-mcp", "bookmarkResearchPaths")):
+                raise RuntimeError("DSH composition is missing the Bookmark Research Skill or MCP configuration")
             return package.resolve()
         return bundle
+
+    def desktop_composition(self, package):
+        """Offline evidence that the reserved desktop profile composes this bundle.
+
+        The installed layer must be exactly what the launcher loads: the profile
+        depends on the package, and the package declares a package-relative patch,
+        an entry module, and the Skill and MCP rows that patch inserts.
+        """
+        settings = read_json(self.settings, {})
+        if not isinstance(settings, dict):
+            raise ValueError("Unexpected DSH profile manifest: " + str(self.settings))
+        dependency = settings.get("dependencies", {}).get(NAME)
+        if not isinstance(dependency, str) or not dependency.strip():
+            raise RuntimeError("The desktop profile does not depend on " + NAME)
+        linked = local_path(dependency, self.settings.parent)
+        if linked is not None and linked != package.resolve():
+            raise RuntimeError("The desktop profile depends on another " + NAME + " source")
+        manifest = read_json(package / "package.json", {})
+        if not isinstance(manifest, dict) or manifest.get("name") != NAME:
+            raise RuntimeError("The installed bundle is not " + NAME)
+        declared = manifest.get("dsh", {})
+        patch = declared.get("bundle", {}).get("patch") if isinstance(declared, dict) else None
+        if not isinstance(patch, str) or not patch or Path(patch).is_absolute():
+            raise RuntimeError("The installed bundle declares no package-relative dsh.bundle.patch")
+        entry = manifest.get("main")
+        if not isinstance(entry, str) or not entry or Path(entry).is_absolute():
+            raise RuntimeError("The installed bundle declares no package-relative entry module")
+        for relative in (patch, entry):
+            resolved = (package / relative).resolve()
+            if package.resolve() not in resolved.parents or not resolved.is_file():
+                raise RuntimeError("The installed bundle is missing " + relative)
+        # The markers below are the same names the composed dump would contain.
+        return entry + "\n" + (package / patch).read_text(encoding="utf-8")

package/scripts/host_install.py

@@ -201,7 +201,7 @@ def _manage(action, client, base, source, ref, dry_run):
         export_bundle(client.host, stage, root, python)
         manifest = read_plugin_manifest(root)
         # Render path-dependent manual instructions for the persistent location.
-        _write_adapter(stage, client.host, bundle, manifest, python)
+        _write_adapter(stage, client.host, bundle, manifest, python, source_root=root)
         content = _files(stage)
         digest = hashlib.sha256(json.dumps(content, sort_keys=True).encode()).hexdigest()
         version = manifest["version"]

package/scripts/npm_source.py

@@ -3,6 +3,7 @@
 from contextlib import contextmanager
 import json
 from pathlib import Path, PurePosixPath
+import re
 import shutil
 import subprocess
 import tarfile
@@ -13,6 +14,16 @@ from export_bundle import NAME, VERSION_PATTERN, read_plugin_manifest
 
 REGISTRY = "https://registry.npmjs.org"
 DEFAULT_SOURCE = "npm:" + NAME
+CACHE_PERMISSION = re.compile(r"EACCES|EPERM")
+CACHE_HINT = ("Hint: npm's cache may contain files owned by another user (a known npm state after a "
+              "privileged install); repair it with `sudo chown -R $(id -u):$(id -g) \"$(npm config get cache)\"` "
+              "or point npm_config_cache at a writable directory.")
+
+
+def _cache_permission_failure(detail):
+    """Whether npm failed because its cache directory is not writable."""
+    text = detail or ""
+    return "cache" in text.casefold() and CACHE_PERMISSION.search(text) is not None
 
 
 def source(value, ref=None):
@@ -35,10 +46,28 @@ def checkout(requested, timeout):
         raise ValueError("npm is required to download Bookmark Research releases")
     with tempfile.TemporaryDirectory(prefix="bookmark-npm-source-") as directory:
         base = Path(directory)
-        result = subprocess.run([
-            npm, "pack", NAME + "@" + selected["ref"], "--ignore-scripts", "--json",
-            "--registry", REGISTRY, "--pack-destination", str(base),
-        ], cwd=base, capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=timeout)
+
+        def pack(cache=None):
+            command = [
+                npm, "pack", NAME + "@" + selected["ref"], "--ignore-scripts", "--json",
+                "--registry", REGISTRY, "--pack-destination", str(base),
+            ]
+            if cache is not None:
+                command += ["--cache", str(cache)]
+            return subprocess.run(command, cwd=base, capture_output=True, text=True,
+                                  encoding="utf-8", errors="replace", timeout=timeout)
+
+        result = pack()
+        if result.returncode and _cache_permission_failure(result.stderr):
+            # One retry in a scratch cache: a machine whose npm cache is unwritable
+            # otherwise cannot install any release, and the failure is not the release's.
+            with tempfile.TemporaryDirectory(prefix="bookmark-npm-cache-") as cache:
+                retry = pack(cache)
+            if retry.returncode == 0:
+                result = retry
+            else:
+                raise RuntimeError("Could not download the npm release: "
+                                   + result.stderr.strip()[-2000:] + "\n" + CACHE_HINT)
         if result.returncode:
             raise RuntimeError("Could not download the npm release: " + result.stderr.strip()[-2000:])
         rows = json.loads(result.stdout)