dsh-jira-tasks 1.2.0 → 1.3.0

package/README.en.md

@@ -6,7 +6,9 @@
 
 Shows the current JIRA project's **open / reopened** issues **assigned to the current user** below the DSH composer input. The JIRA base URL and token are configured in **Settings → JIRA 配置** (the settings dialog's left navigation) (`JIRA_BASE_URL` / `JIRA_API_TOKEN` act as fallback); the project key and JQL are **configured per workspace** and persisted.
 
-> **DSH version targeted: 0.1.7 (verified on `0.1.7-rc.2`).** The client slots `conversation.input.dock` / `plugins.item` / `settings.section`, the settings service `ctx.configForms` (namespace = profile entry id `jira-tasks`), and the `ctx.effect` / `configForms.whileServed` disposal contracts all follow the 0.1.7 interfaces; the 0.1.6-era `settingsScope` / `settings.register` / `settings.plugin.item` APIs are gone and no longer used.
+> **DSH versions targeted: 0.1.7 and 0.2.0 (verified on `0.1.7-rc.2` and `0.2.0-rc.2`), on both the browser (web profile) and the Desktop app (the Electron-owned desktop profile).**
+> The client slots `conversation.input.dock` / `plugins.item` / `settings.section`, the settings service `ctx.configForms` (namespace = profile entry id `jira-tasks`), and the `ctx.effect` / `configForms.whileServed` disposal contracts are unchanged between 0.1.7 and 0.2.0 (verified package by package), so one `lib/` covers both; the 0.1.6-era `settingsScope` / `settings.register` / `settings.plugin.item` APIs are gone and no longer used.
+> The package declares its DSH range as `>=0.1.7-rc.2 <0.3.0-0` (`engines.dsh` plus an optional `@deepseek-ai/dsh` peer): since 0.2.0 DSH checks that range **on install and on profile startup**, skipping a mismatched bundle and offering the exact-version `allow-version` exemption in the plugin manager. The peer is marked `optional` so `pnpm` never pulls the whole `@deepseek-ai/dsh` tree into the profile.
 
 ## Features
 
@@ -21,7 +23,7 @@ Shows the current JIRA project's **open / reopened** issues **assigned to the cu
 
 ## Install
 
-Published to npm:
+Published to npm. For the **browser (web profile)**:
 
 ```bash
 dsh plugin --profile web add dsh-jira-tasks
@@ -35,19 +37,35 @@ dsh plugin --profile web add github:liu3734/jira-tasks-dsh-plugin
 
 **Restart DSH** to activate.
 
-> **Nothing shows up? Check `dsh.profile.bundles` first.** DSH mounts this package as a profile layer only when `"dsh-jira-tasks"` is listed in `dsh.profile.bundles` of `~/.dsh/profiles/web/package.json`; being in `dependencies` alone is not enough — the startup log then prints `patch: entry "jira-tasks" not found` and the plugin silently never loads. `dsh plugin --profile web add` normally appends that row, but it will not re-append when the package is already a dependency; add `"dsh-jira-tasks"` to `dsh.profile.bundles` by hand.
+### Desktop app (DeepSeek Harness.app)
+
+The Desktop app does not use the `web` profile; it boots the Electron-owned **`desktop` profile** (`~/.dsh/profiles/desktop/`). That profile name is reserved: an npm-installed `dsh` **refuses** both boot and plugin operations for `--profile desktop` (`profile "desktop" is managed exclusively by the Electron application`). Use the Desktop-provided command instead:
+
+1. Open the Desktop app once (it initializes the desktop profile), then **quit it completely**
+2. In the app menu, open **Manage dsh Command** → Install (puts the Desktop's own `dsh` on your PATH)
+3. Install the plugin:
+
+   ```bash
+   dsh plugin --profile desktop add dsh-jira-tasks
+   ```
+
+4. Confirm `"dsh-jira-tasks"` is listed in `dsh.profile.bundles` of `~/.dsh/profiles/desktop/package.json`, then start the Desktop app
+
+> The renderer's origin is `dsh-app://app`. Electron forwards every non-static request to the local Host with its cookie, so the plugin's absolute-path `fetch("/jira/api/search")` keeps working; `target="_blank"` issue links are handed to the system browser. The project key / JQL live in that origin's localStorage, so **they are separate from the browser configuration at `http://127.0.0.1:<port>`** — configure each surface once.
+
+> **Nothing shows up? Check `dsh.profile.bundles` first.** DSH mounts this package as a profile layer only when `"dsh-jira-tasks"` is listed in `dsh.profile.bundles` of that profile's `package.json` (`~/.dsh/profiles/web/package.json` or `~/.dsh/profiles/desktop/package.json`); being in `dependencies` alone is not enough — the startup log then prints `patch: entry "jira-tasks" not found` and the plugin silently never loads. `dsh plugin --profile <name> add` normally appends that row, but it will not re-append when the package is already a dependency; add `"dsh-jira-tasks"` to `dsh.profile.bundles` by hand.
 
 > Using GitHub Packages instead: configure `@liu3734:registry=https://npm.pkg.github.com/` plus a read token in the profile's `.npmrc`, then run `dsh plugin --profile web add @liu3734/dsh-jira-tasks`.
 
 <details>
 <summary>Manual install (without npm)</summary>
 
-1. Copy this repository (its root is the package directory) to `~/.dsh/profiles/web/packages/dsh-jira-tasks/` (skip `.git/`)
-2. Edit `~/.dsh/profiles/web/package.json`:
+1. Copy this repository (its root is the package directory) into the profile's `packages/dsh-jira-tasks/` (`~/.dsh/profiles/web/` for the browser, `~/.dsh/profiles/desktop/` for the Desktop app; skip `.git/`)
+2. Edit that profile's `package.json`:
    - Add to `dependencies`: `"dsh-jira-tasks": "file:./packages/dsh-jira-tasks"`
    - Append to `dsh.profile.bundles`: `"dsh-jira-tasks"`
 3. Run `pnpm install` in the profile directory
-4. Restart DSH
+4. Restart DSH (the Desktop app must be fully quit and reopened)
 
 > Note: `pnpm install` **copies** the package into `node_modules/` (not a symlink) — after editing sources, sync `node_modules/dsh-jira-tasks` or re-run install.
 </details>
@@ -109,10 +127,33 @@ project = "{projectKey}" AND status in ("开启", "重新开启") AND assignee =
 
 > The status names follow the Chinese workflow (`开启`/`重新开启`). For English statuses (Open/Reopened), set a custom JQL in ⚙.
 
+## Compatibility & verification
+
+| Dimension | Coverage |
+|---|---|
+| DSH versions | `0.1.7-rc.2` and `0.2.0-rc.2` (verified); declared range `>=0.1.7-rc.2 <0.3.0-0` — the 0.1.7 and 0.2.x lines, excluding 0.3.0 and its prereleases |
+| Surfaces | Browser (`dsh web` / web profile) and the Desktop app (Electron, desktop profile, renderer origin `dsh-app://app`) |
+| Host APIs | `Config` / `webServer.register` / `subprocess.spawn` / `credentials.resolve` / `settings.configure` — signatures unchanged from 0.1.7 to 0.2.0 |
+| Client APIs | `window.__ModuleLoader__.load`, `slots.inject/register`, `configForms.get/whileServed`, `remote.credentials`, slots `conversation.input.dock` / `plugins.item` / `settings.section` — contracts unchanged from 0.1.7 to 0.2.0 |
+
+How it was verified (a throwaway `DSH_HOME`, the user's own profile untouched):
+
+```bash
+# Boot the target dsh in isolation; the profile's dsh.profile.bundles lists dsh-jira-tasks
+DSH_HOME=/tmp/dsh-check node <dsh-0.2.0-rc.2>/lib/bin.js --profile web --no-open --port 19399
+
+curl -sX POST http://127.0.0.1:19399/jira/api/test   -d '{}'                      # connectivity / auth
+curl -sX POST http://127.0.0.1:19399/jira/api/search -d '{"projectKey":"<KEY>"}'  # issue query
+curl -s "http://127.0.0.1:19399/?token=<token from the startup log>" | grep -o dsh-jira-tasks  # client bundle in __DSH_BOOT__
+```
+
+For the Desktop app additionally confirm the client bundle appears in the app's `Code Cache` (the renderer loaded and executed it) and that `dsh.jiraTasks.config.v1` exists in its `localStorage` (the panel works and writes per workspace).
+
 ## Uninstall
 
 ```bash
-dsh plugin --profile web remove dsh-jira-tasks
+dsh plugin --profile web remove dsh-jira-tasks        # browser
+dsh plugin --profile desktop remove dsh-jira-tasks    # Desktop app (needs the Desktop-provided dsh)
 ```
 
 ## Troubleshooting
@@ -145,10 +186,11 @@ JIRA_TASKS_TOKEN (settings card) > JIRA_API_TOKEN > JIRA_TOKEN
 <details>
 <summary>Panel does not appear</summary>
 
-- Make sure it is installed and DSH was **restarted**; in new sessions the panel sits below the input
-- Check that `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json` lists `"dsh-jira-tasks"` (the most common cause of a silent no-show — see the Install note)
-- Check the DSH startup log: `patch: entry "jira-tasks" not found` means the profile layer was never composed; `webserver: duplicate exact route` means a route was registered twice (the plugin releases its routes through `ctx.effect`, so this points at a second copy)
-- A browser console error `client-modules: could not load "dsh-jira-tasks"` means `/plugins/dsh-jira-tasks/client.js` was not served — confirm `exports["./client"]` resolves to the built `lib/client.js`
+- Make sure it is installed and DSH was **restarted** (the Desktop app must be fully quit and reopened); in new sessions the panel sits below the input
+- Check `dsh.profile.bundles` in the right profile: `~/.dsh/profiles/web/package.json` for the browser, **`~/.dsh/profiles/desktop/package.json` for the Desktop app** (the most common cause of a silent no-show — see the Install note; that profile can only be edited with the Desktop-provided `dsh`)
+- Check the DSH startup log: `patch: entry "jira-tasks" not found` means the profile layer was never composed; `Plugin dsh-jira-tasks@<version> is incompatible with dsh <runtime>` means the running version falls outside the declared `>=0.1.7-rc.2 <0.3.0-0` range, so the bundle is skipped (follow the message, using `dsh plugin allow-version` or the plugin manager, to grant the exact-version exemption); `webserver: duplicate exact route` means a route was registered twice (the plugin releases its routes through `ctx.effect`, so this points at a second copy)
+- A console error `client-modules: could not load "dsh-jira-tasks"` means `/plugins/dsh-jira-tasks/client.js` was not served — confirm `exports["./client"]` resolves to the built `lib/client.js`
+- The Desktop panel says "unconfigured" although you configured it: project key / JQL are stored per **origin**, so `dsh-app://app` (the built-in window) and `http://127.0.0.1:<port>` (a browser) hold two independent configurations
 </details>
 
 ## Architecture & Implementation Details
@@ -168,8 +210,9 @@ JIRA_TASKS_TOKEN (settings card) > JIRA_API_TOKEN > JIRA_TOKEN
 └──────────────────────────────────────────────┘      └────────────────────────────────────┘
 
 - **Host**: declares the entry's own `Config` (`baseUrl`, `volatile` — since DSH 0.1.5 a settings page is built from it; `settings.configure({ auto: false }, ctx.fiber)` turns the auto-generated page off and hands its disposer back to `ctx.effect`) plus `webServer` routes `POST /jira/api/search` and `POST /jira/api/test`, each wrapped in its own `ctx.effect` (a reload otherwise hits "duplicate route" and fails activation; non-POST requests get 405); the token comes from the `credentials` service resolved in the order `JIRA_TASKS_TOKEN` (written by the Settings card) → `JIRA_API_TOKEN` → `JIRA_TOKEN` (`$DSH_HOME/.credentials.yaml` / environment, hot-reloaded), so a saved card token overrides the environment; queries run through `subprocess` spawning `curl` directly, with the auth header passed via stdin (`--config -`) so the token never appears in argv.
-- **Client**: a standard `window.__ModuleLoader__.load({ id, factory })` web bundle requiring only `"react"`; registers **only `conversation.input.dock`** (`order: 10`) — that seat renders in both new and active sessions and is a full-width row of `composerStack` (`flex-direction: column`), where the panel's own CSS `order: 99` places it below the input card at the card's width. `conversation.composer.dock` is deliberately NOT used: in 0.1.7 it renders into InputBar's `.dock` **row**, side by side with the context meter, so a full-width panel there gets its right-hand content covered by the meter. The address/token form comes from `ctx.configForms.get("jira-tasks")` and the token is written through `remote.credentials` to `JIRA_TASKS_TOKEN`; `configForms.whileServed` keeps it hidden when the host serves no such namespace. It is registered in **two places**: the Plugins-panel card `plugins.item` (`id: "jira-tasks"`, `order: 41`) and a Settings-navigation section `settings.section` (`id: "jira-tasks"`, `order: 30` — above Agent presets' 20, so it sits below it; `label: "JIRA 配置"`; ids outside the shell's `navIcon` allow-list fall back to the default gear icon). Both share one `JiraSettingsPage`, whose outer container is chosen by the external `variant: "page"` prop (`li.jt-set-card` card vs `div.jt-set-page` page) while the field block is the same array. The card's `summary` view is rendered by a dispatcher that calls **no hooks**, while the form lives in a separate `JiraSettingsPage`, so flipping `view` on one mounted instance never changes its hook count.
+- **Client**: a standard `window.__ModuleLoader__.load({ id, factory })` web bundle requiring only `"react"`; registers **only `conversation.input.dock`** (`order: 10`) — that seat renders in both new and active sessions and is a full-width row of `composerStack` (`flex-direction: column`), where the panel's own CSS `order: 99` places it below the input card at the card's width. `conversation.composer.dock` is deliberately NOT used: in 0.1.7 and 0.2.0 alike that seat renders into InputBar's `.dock` **row**, side by side with the context meter, so a full-width panel there gets its right-hand content covered by the meter. The address/token form comes from `ctx.configForms.get("jira-tasks")` and the token is written through `remote.credentials` to `JIRA_TASKS_TOKEN`; `configForms.whileServed` keeps it hidden when the host serves no such namespace. It is registered in **two places**: the Plugins-panel card `plugins.item` (`id: "jira-tasks"`, `order: 41`) and a Settings-navigation section `settings.section` (`id: "jira-tasks"`, `order: 30` — above Agent presets' 20, so it sits below it; `label: "JIRA 配置"`; ids outside the shell's `navIcon` allow-list fall back to the default gear icon). Both share one `JiraSettingsPage`, whose outer container is chosen by the external `variant: "page"` prop (`li.jt-set-card` card vs `div.jt-set-page` page) while the field block is the same array. The card's `summary` view is rendered by a dispatcher that calls **no hooks**, while the form lives in a separate `JiraSettingsPage`, so flipping `view` on one mounted instance never changes its hook count.
 - **Why not the `shell` service**: `shell` wraps commands with `sandbox-exec`, which is broken on some macOS versions (`sandbox_apply: Operation not permitted`); `subprocess` is the raw process seam without this issue.
+- **Why the Desktop app needs no code branch**: its Host is the same DSH as the web profile (same `@deepseek-ai/dsh-web-app` + `dsh-host-webserver`); only the renderer origin differs (`dsh-app://app`), and Electron's `protocol.handle` forwards every non-static request to the local Host with its cookie, so both `fetch("/jira/api/*")` and `/plugins/...` work. `http(s)` `target="_blank"` links are handed to the system browser by the main window's `setWindowOpenHandler`. The only difference that matters is origin-scoped localStorage, so each surface keeps its own project key / JQL.
 - **One registration covers both states**: `conversation.input.dock` renders whenever a session and its input exist, so new and active sessions need no separate registrations (the older `composer.dock` + blank-session de-duplication was both unnecessary under 0.1.7 and the cause of the meter-row collision).
 
 **Differences from the dynamic version**

package/README.md

@@ -6,7 +6,9 @@
 
 在 DSH 会话**输入框下方**展示当前 JIRA 项目**指派给当前用户**的「开启 / 重新开启」任务列表。JIRA 地址与令牌在**设置 → JIRA 配置**（设置对话框左侧导航）中配置（`JIRA_BASE_URL` / `JIRA_API_TOKEN` 作为回退）；项目 Key 与 JQL **按工作区配置**并持久化。
 
-> **适配的 DSH 版本：0.1.7（`0.1.7-rc.2` 实测）。** 客户端槽位 `conversation.input.dock` / `plugins.item` / `settings.section`、设置服务 `ctx.configForms`（命名空间 = profile 条目 id `jira-tasks`）、`ctx.effect` / `configForms.whileServed` 的注销契约均按 0.1.7 的接口实现；0.1.6 及更早版本的 `settingsScope` / `settings.register` / `settings.plugin.item` 已不再使用。
+> **适配的 DSH 版本：0.1.7 与 0.2.0（`0.1.7-rc.2`、`0.2.0-rc.2` 实测），浏览器（web profile）与桌面端（Electron 独占的 desktop profile）通用。**
+> 客户端槽位 `conversation.input.dock` / `plugins.item` / `settings.section`、设置服务 `ctx.configForms`（命名空间 = profile 条目 id `jira-tasks`）、`ctx.effect` / `configForms.whileServed` 的注销契约在 0.1.7 → 0.2.0 之间没有变化（逐包 diff 过），所以同一份 `lib/` 同时覆盖两版；0.1.6 及更早版本的 `settingsScope` / `settings.register` / `settings.plugin.item` 已不再使用。
+> 包内声明了 DSH 兼容范围 `>=0.1.7-rc.2 <0.3.0-0`（`engines.dsh` + 可选 peer `@deepseek-ai/dsh`）：0.2.0 起 DSH 会在**安装与启动**时校验该范围，不满足的版本会被跳过并在插件管理器里给出 `allow-version` 精确豁免入口（peer 标了 `optional`，`pnpm` 不会把整套 `@deepseek-ai/dsh` 装进 profile）。
 
 ## 功能
 
@@ -30,7 +32,7 @@
 
 ## 安装
 
-包已发布到公共 npm（`dsh-jira-tasks`）；仓库的发布工作流同时把同一版本发布到 GitHub Packages（作用域包名 `@liu3734/dsh-jira-tasks`）。从 npm 安装（推荐）：
+包已发布到公共 npm（`dsh-jira-tasks`）；仓库的发布工作流同时把同一版本发布到 GitHub Packages（作用域包名 `@liu3734/dsh-jira-tasks`）。**浏览器（web profile）**从 npm 安装（推荐）：
 
 ```bash
 dsh plugin --profile web add dsh-jira-tasks
@@ -44,19 +46,35 @@ dsh plugin --profile web add github:liu3734/jira-tasks-dsh-plugin
 
 **重启 DSH** 后生效。
 
-> **装完没反应？先查 `dsh.profile.bundles`。** DSH 只有当 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 里列了 `"dsh-jira-tasks"` 时才把本包当作 profile 层挂载；只出现在 `dependencies` 里不够——此时启动日志会打 `patch: entry "jira-tasks" not found`，插件静默不加载。`dsh plugin --profile web add` 一般会补上这一行，但该包已在 `dependencies` 中时重装不会重新补，手动往 `dsh.profile.bundles` 追加 `"dsh-jira-tasks"` 即可。
+### 桌面端（DeepSeek Harness.app）
+
+桌面端不用 `web` profile，而是 Electron 独占的 **`desktop` profile**（`~/.dsh/profiles/desktop/`）。该 profile 名被应用保留：**npm 全局安装的 `dsh` 会直接拒绝** `--profile desktop` 的 boot 与 plugin 操作（`profile "desktop" is managed exclusively by the Electron application`），必须用桌面端自带的命令：
+
+1. 先打开一次桌面端（由应用初始化 desktop profile），然后**完全退出桌面端**
+2. 应用内菜单 → **管理 dsh 命令 / Manage dsh Command** → Install，把桌面端自带的 `dsh` 装进 PATH
+3. 安装插件：
+
+   ```bash
+   dsh plugin --profile desktop add dsh-jira-tasks
+   ```
+
+4. 确认 `~/.dsh/profiles/desktop/package.json` 的 `dsh.profile.bundles` 里有 `"dsh-jira-tasks"`，再启动桌面端
+
+> 桌面端渲染进程的 origin 是 `dsh-app://app`。非静态资源的请求由 Electron 转发到本机 Host，所以插件的 `fetch("/jira/api/search")` 这类绝对路径照常可用；任务链接的 `target="_blank"` 由 Electron 交给系统浏览器打开。项目 Key / JQL 存在该 origin 的 localStorage 里，**与浏览器访问 `http://127.0.0.1:<port>` 时的配置互不相通**，两边各配一次即可。
+
+> **装完没反应？先查 `dsh.profile.bundles`。** DSH 只有当对应 profile 的 `package.json`（`~/.dsh/profiles/web/package.json` 或 `~/.dsh/profiles/desktop/package.json`）里的 `dsh.profile.bundles` 列了 `"dsh-jira-tasks"` 时才把本包当作 profile 层挂载；只出现在 `dependencies` 里不够——此时启动日志会打 `patch: entry "jira-tasks" not found`，插件静默不加载。`dsh plugin --profile <name> add` 一般会补上这一行，但该包已在 `dependencies` 中时重装不会重新补，手动往 `dsh.profile.bundles` 追加 `"dsh-jira-tasks"` 即可。
 
 > 若改用 GitHub Packages 源：先在 profile 的 `.npmrc` 配置 `@liu3734:registry=https://npm.pkg.github.com/` 及读取令牌，再执行 `dsh plugin --profile web add @liu3734/dsh-jira-tasks`。
 
 <details>
 <summary>手动安装（不使用 npm）</summary>
 
-1. 将本仓库（仓库根目录即包目录）复制为 `~/.dsh/profiles/web/packages/dsh-jira-tasks/`（可忽略 `.git/`）
-2. 编辑 `~/.dsh/profiles/web/package.json`：
+1. 将本仓库（仓库根目录即包目录）复制为 profile 内的 `packages/dsh-jira-tasks/`（可忽略 `.git/`）——web 用 `~/.dsh/profiles/web/`，桌面端用 `~/.dsh/profiles/desktop/`
+2. 编辑该 profile 的 `package.json`：
    - `dependencies` 增加：`"dsh-jira-tasks": "file:./packages/dsh-jira-tasks"`
    - `dsh.profile.bundles` 追加：`"dsh-jira-tasks"`
 3. 在 profile 目录执行 `pnpm install`
-4. 重启 DSH
+4. 重启 DSH（桌面端需完全退出后重新打开）
 
 > 注：`pnpm install` 会把包**复制**到 `node_modules/`（非符号链接），改动源码后需同步 `node_modules/dsh-jira-tasks` 或重跑 install。
 </details>
@@ -118,10 +136,33 @@ project = "{projectKey}" AND status in ("开启", "重新开启") AND assignee =
 
 > 状态名按中文工作流（"开启"/"重新开启"）配置；若 JIRA 用英文状态（Open/Reopened），在 ⚙ 中填写自定义 JQL 即可。
 
+## 兼容性与验证
+
+| 维度 | 覆盖 |
+|---|---|
+| DSH 版本 | `0.1.7-rc.2`、`0.2.0-rc.2`（实测）；声明范围 `>=0.1.7-rc.2 <0.3.0-0`，即 0.1.7 与 0.2.x，不含 0.3.0 及其预发布 |
+| 运行形态 | 浏览器（`dsh web` / web profile）、桌面端 DeepSeek Harness.app（Electron，desktop profile，渲染进程 origin `dsh-app://app`） |
+| 宿主侧 | `Config` / `webServer.register` / `subprocess.spawn` / `credentials.resolve` / `settings.configure`：0.1.7 → 0.2.0 签名未变 |
+| 客户端 | `window.__ModuleLoader__.load`、`slots.inject/register`、`configForms.get/whileServed`、`remote.credentials`、槽位 `conversation.input.dock` / `plugins.item` / `settings.section`：0.1.7 → 0.2.0 契约未变 |
+
+验证方式（不改动用户 profile，临时 `DSH_HOME` 起真实服务）：
+
+```bash
+# 用目标版本的 dsh 起一个隔离实例，profile 的 dsh.profile.bundles 含 dsh-jira-tasks
+DSH_HOME=/tmp/dsh-check node <dsh-0.2.0-rc.2>/lib/bin.js --profile web --no-open --port 19399
+
+curl -sX POST http://127.0.0.1:19399/jira/api/test   -d '{}'                      # 连通性 / 鉴权
+curl -sX POST http://127.0.0.1:19399/jira/api/search -d '{"projectKey":"<KEY>"}'  # 任务查询
+curl -s "http://127.0.0.1:19399/?token=<启动日志里的 token>" | grep -o dsh-jira-tasks  # 客户端进入 __DSH_BOOT__ 模块图
+```
+
+桌面端另需确认：客户端 bundle 出现在应用 `Code Cache`（说明浏览器端已加载执行）、`localStorage` 里存在 `dsh.jiraTasks.config.v1`（说明面板可用且按工作区写入）。
+
 ## 卸载
 
 ```bash
-dsh plugin --profile web remove dsh-jira-tasks
+dsh plugin --profile web remove dsh-jira-tasks        # 浏览器
+dsh plugin --profile desktop remove dsh-jira-tasks    # 桌面端（需桌面端自带的 dsh 命令）
 ```
 
 ## 常见问题
@@ -157,10 +198,11 @@ JIRA_TASKS_TOKEN（设置页） > JIRA_API_TOKEN > JIRA_TOKEN
 <details>
 <summary>面板不显示</summary>
 
-- 确认已安装并**重启 DSH**；新会话面板位于输入框下方
-- 检查 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 是否包含 `"dsh-jira-tasks"`（这是最常见的漏装原因，见「安装」一节的提示）
-- 检查 DSH 启动日志：出现 `patch: entry "jira-tasks" not found` 即为 profile 层未挂载；出现 `webserver: duplicate exact route` 说明同一路由被注册了两次（插件自身已用 `ctx.effect` 释放旧路由，若仍有说明有第二份副本）
-- 浏览器控制台若报 `client-modules: could not load "dsh-jira-tasks"`，说明 `/plugins/dsh-jira-tasks/client.js` 没取到——确认 `package.json` 的 `exports["./client"]` 指向已构建的 `lib/client.js`
+- 确认已安装并**重启 DSH**（桌面端要完全退出应用再打开）；新会话面板位于输入框下方
+- 检查对应 profile 的 `dsh.profile.bundles` 是否包含 `"dsh-jira-tasks"`：浏览器看 `~/.dsh/profiles/web/package.json`，**桌面端看 `~/.dsh/profiles/desktop/package.json`**（最常见的漏装原因，见「安装」一节的提示；桌面端该 profile 只能用应用自带的 dsh 命令改）
+- 检查 DSH 启动日志：出现 `patch: entry "jira-tasks" not found` 即为 profile 层未挂载；出现 `Plugin dsh-jira-tasks@<版本> is incompatible with dsh <运行版本>` 说明运行版本落在声明范围 `>=0.1.7-rc.2 <0.3.0-0` 之外，该包会被跳过（可按提示用 `dsh plugin allow-version` 或插件管理器授精确版本豁免）；出现 `webserver: duplicate exact route` 说明同一路由被注册了两次（插件自身已用 `ctx.effect` 释放旧路由，若仍有说明有第二份副本）
+- 浏览器 / 桌面端控制台若报 `client-modules: could not load "dsh-jira-tasks"`，说明 `/plugins/dsh-jira-tasks/client.js` 没取到——确认 `package.json` 的 `exports["./client"]` 指向已构建的 `lib/client.js`
+- 桌面端面板显示「未配置」但你记得配过：项目 Key / JQL 按 **origin** 存 localStorage，`dsh-app://app`（桌面端内置窗口）与 `http://127.0.0.1:<port>`（浏览器）是两份独立配置
 </details>
 
 ## 架构与实现细节
@@ -181,8 +223,9 @@ JIRA_TASKS_TOKEN（设置页） > JIRA_API_TOKEN > JIRA_TOKEN
 ```
 
 - **Host**：声明条目自身的 `Config`（`baseUrl`，`volatile`，DSH 0.1.5 起设置页的表单直接来自它；`settings.configure({ auto: false }, ctx.fiber)` 关掉自动生成页，并把返回的注销函数交回 `ctx.effect`）与 `webServer` 路由 `POST /jira/api/search`、`POST /jira/api/test`（两条路由各自包在 `ctx.effect` 里，卸载/重载时先释放，否则重挂载会撞上「重复路由」直接抛错；非 POST 返回 405）；令牌经 `credentials` 服务按 `JIRA_TASKS_TOKEN`（设置页写入）→ `JIRA_API_TOKEN` → `JIRA_TOKEN` 的顺序解析（`$DSH_HOME/.credentials.yaml` / 环境变量，热加载），因此设置页保存的令牌能覆盖环境变量；查询用 `subprocess` 直接 `spawn curl`，认证头经 stdin（`--config -`）传入，令牌不进入命令行参数。
-- **Client**：`window.__ModuleLoader__.load({ id, factory })` 标准 web bundle，仅 `require("react")`；**只注册 `conversation.input.dock` 一处**（`order: 10`）。该槽位在新会话与活跃会话下都会渲染，属于 `composerStack`（`flex-direction: column`）的整宽纵向行；面板元素自身 `flex order: 99` 排到输入卡之后，即输入框下方，并以 `--dsh-composer-side-clearance` / `--dsh-composer-card-max-width` 与输入卡等宽。之所以不用 `conversation.composer.dock`：0.1.7 里那一槽位渲染进 InputBar 的 `.dock`**横向** flex 行，与上下文占用环并排，整宽面板会被占用环压住右侧内容。插件地址与令牌的表单来自 `ctx.configForms.get("jira-tasks")`（地址）与 `remote.credentials`（令牌写入 `JIRA_TASKS_TOKEN`），并用 `configForms.whileServed` 保证宿主未提供该命名空间时不显示。表单**注册在两处**：插件面板卡片 `plugins.item`（`id: "jira-tasks"`，`order: 41`，原入口保留）与设置对话框左侧导航项 `settings.section`（`id: "jira-tasks"`，`order: 30` —— 大于「Agent 预设」的 20，所以显示在它下方；`label: "JIRA 配置"`；未在 `navIcon` 白名单里的 id 由设置外壳回退成默认齿轮图标）。两者共用同一个 `JiraSettingsPage`：由外部 prop `variant: "page"` 决定外层容器（`li.jt-set-card` 卡片 / `div.jt-set-page` 整页），字段区是同一份数组。`plugins.item` 的摘要位由一个**不调用任何 hook** 的分发组件负责，表单在独立的 `JiraSettingsPage` 里，避免同一实例在 `view` 切换时改变 hook 数量。
+- **Client**：`window.__ModuleLoader__.load({ id, factory })` 标准 web bundle，仅 `require("react")`；**只注册 `conversation.input.dock` 一处**（`order: 10`）。该槽位在新会话与活跃会话下都会渲染，属于 `composerStack`（`flex-direction: column`）的整宽纵向行；面板元素自身 `flex order: 99` 排到输入卡之后，即输入框下方，并以 `--dsh-composer-side-clearance` / `--dsh-composer-card-max-width` 与输入卡等宽。之所以不用 `conversation.composer.dock`：0.1.7 / 0.2.0 里那一槽位都渲染进 InputBar 的 `.dock`**横向** flex 行，与上下文占用环并排，整宽面板会被占用环压住右侧内容。插件地址与令牌的表单来自 `ctx.configForms.get("jira-tasks")`（地址）与 `remote.credentials`（令牌写入 `JIRA_TASKS_TOKEN`），并用 `configForms.whileServed` 保证宿主未提供该命名空间时不显示。表单**注册在两处**：插件面板卡片 `plugins.item`（`id: "jira-tasks"`，`order: 41`，原入口保留）与设置对话框左侧导航项 `settings.section`（`id: "jira-tasks"`，`order: 30` —— 大于「Agent 预设」的 20，所以显示在它下方；`label: "JIRA 配置"`；未在 `navIcon` 白名单里的 id 由设置外壳回退成默认齿轮图标）。两者共用同一个 `JiraSettingsPage`：由外部 prop `variant: "page"` 决定外层容器（`li.jt-set-card` 卡片 / `div.jt-set-page` 整页），字段区是同一份数组。`plugins.item` 的摘要位由一个**不调用任何 hook** 的分发组件负责，表单在独立的 `JiraSettingsPage` 里，避免同一实例在 `view` 切换时改变 hook 数量。
 - **为什么不用 `shell` 服务**：`shell` 会套 `sandbox-exec`，部分 macOS 上不可用（`sandbox_apply: Operation not permitted`）；`subprocess` 是原始进程缝，无此问题。
+- **桌面端为什么不用改代码**：桌面端 Host 与 web profile 是同一套 DSH（同样是 `@deepseek-ai/dsh-web-app` + `dsh-host-webserver`），渲染进程 origin 是 `dsh-app://app`，非静态资源请求由 Electron 的 `protocol.handle` 带上 Host cookie 转发到本机 Host，所以 `fetch("/jira/api/*")` 与 `/plugins/...` 都照常工作；`http(s)` 的 `target="_blank"` 由主窗口的 `setWindowOpenHandler` 交给系统浏览器。唯一差异是 localStorage 按 origin 隔离，配置需在桌面端与浏览器各存一份。
 - **一处注册覆盖两种会话**：`conversation.input.dock` 只要有 session + input 就会渲染，新会话与活跃会话无需分别注册（旧版曾用 `composer.dock` + 空白判定去重，0.1.7 下既不必要、又会与占用环抢同一行）。
 
 **与动态插件版的差异**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-jira-tasks",
-  "version": "1.2.0",
-  "description": "JIRA open tasks panel for DeepSeek Harness (DSH) 0.1.7: shows the current user's open/reopened issues below the composer, per-workspace project key, persistent profile bundle.",
+  "version": "1.3.0",
+  "description": "JIRA open tasks panel for DeepSeek Harness (DSH) 0.1.7 and 0.2.0, web and Desktop: shows the current user's open/reopened issues below the composer, per-workspace project key, persistent profile bundle.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -9,6 +9,17 @@
     "./client": "./lib/client.js",
     "./package.json": "./package.json"
   },
+  "engines": {
+    "dsh": ">=0.1.7-rc.2 <0.3.0-0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh": ">=0.1.7-rc.2 <0.3.0-0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.2"
   },