dsh-jira-tasks 1.0.7 → 1.1.0

package/README.en.md

@@ -6,6 +6,8 @@
 
 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 → Plugins → JIRA** (`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`, 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.
+
 ## Features
 
 - 📋 Panel shown below the composer in both new and active sessions (aligned with the input width in new sessions)
@@ -33,6 +35,10 @@ 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.
+
+> 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>
 
@@ -58,12 +64,18 @@ In a DSH session, use the Cordis tools: `cordis_define` (`kind: new`, `idPrefix:
 
 Open **Settings → Plugins → Plugin configuration → JIRA** and fill in:
 
-- **JIRA base URL**: e.g. `http://jira.example.com/` (stored in the user settings document and read back by the form)
-- **Access token / PAT**: written to the credential store (`$DSH_HOME/.credentials.yaml`); the browser only ever sees "configured", never the token itself
+- **JIRA base URL**: e.g. `http://jira.example.com/` (written to this plugin entry's `Config.baseUrl` — the `jira-tasks` row in the profile's `cordis.patch.yml` — and read back by the form; a host-refused write now surfaces as an error instead of failing silently)
+- **Access token / PAT**: written to the credential store (`$DSH_HOME/.credentials.yaml`) under the plugin-owned ref `JIRA_TASKS_TOKEN`; the browser only ever sees "configured", never the token itself
 
-Leaving the token blank on save keeps the existing one; clearing the address on save removes the override and falls back to the environment. Auth is auto-detected: tokens containing `:` use Basic, otherwise Bearer (JIRA PAT).
+Leaving the token blank on save keeps the existing one; clearing the address on save removes the override and falls back to the credential store / environment. Auth is auto-detected: tokens containing `:` use Basic, otherwise Bearer (JIRA PAT).
 
-> **A token supplied by the environment cannot be overwritten from this card.** If the environment that launched DSH already defines `JIRA_API_TOKEN` (a Windows *user-level* variable counts), DSH treats that reference as read-only: the card disables the token field and explains why. The panel already uses that variable, so **no save is needed**; to manage the token from settings instead, remove the variable first (Windows: System Properties → Environment Variables, or PowerShell `[Environment]::SetEnvironmentVariable('JIRA_API_TOKEN', $null, 'User')`) and restart DSH.
+> **The settings-page token takes precedence over the environment.** When the environment that launched DSH already defines `JIRA_API_TOKEN` (a Windows *user-level* variable counts), the card is still editable: it stores the token in its own ref `JIRA_TASKS_TOKEN`, which DSH accepts (it only refuses to write a ref the launching environment shadows), and the Host resolves tokens in this order:
+>
+> ```
+> JIRA_TASKS_TOKEN (settings card) > JIRA_API_TOKEN > JIRA_TOKEN
+> ```
+>
+> Click **Clear settings token** in the card to fall back to the environment variable again.
 
 #### Connection test
 
@@ -73,7 +85,7 @@ The card's footer carries a status light and a **Test connection** button:
 - **Green** = address and token work (the current user is shown); **red** = unusable (JIRA's reason, e.g. 401, is shown); **grey** = address or token not configured
 - **Test connection** probes what is currently in the fields, saved or not, so you can check before saving
 
-Environment variables / credentials still work as a **fallback** (used when the settings card is empty), hot-reloaded without a restart:
+Environment variables / credentials still work as a **fallback** (used when the settings card leaves `baseUrl` empty), hot-reloaded without a restart. Address precedence is `Config.baseUrl` > `JIRA_BASE_URL` > `JIRA_URL`, and `JIRA_BASE_URL` may live in the launching environment or in `.credentials.yaml` — note that a stale record (e.g. an old domain left in the credential file) becomes effective again as soon as the settings page clears the address:
 
 ```yaml
 JIRA_BASE_URL: "http://jira.example.com/"
@@ -81,7 +93,7 @@ JIRA_API_TOKEN: "<PAT or user:token>"
 ```
 
 - Base URL aliases: `JIRA_BASE_URL` / `JIRA_URL`
-- Token aliases: `JIRA_API_TOKEN` / `JIRA_TOKEN`
+- Token resolution order: `JIRA_TASKS_TOKEN` (written by the settings card) → `JIRA_API_TOKEN` → `JIRA_TOKEN`; the first match wins
 
 ### 2. Project key and JQL (per workspace)
 
@@ -117,24 +129,26 @@ dsh plugin --profile web remove dsh-jira-tasks
 </details>
 
 <details>
-<summary>Saving the token fails with "is supplied read-only by the launching environment"</summary>
+<summary>Can the settings card override the token from the environment?</summary>
 
-`JIRA_API_TOKEN` (or `JIRA_TOKEN`) is supplied by the environment that launched DSH, and DSH treats that reference as read-only: a write would be shadowed by the variable, so it is refused. The panel already uses that variable and queries fine, so **there is nothing to save**.
+**Yes.** The card stores the token under the plugin-owned ref `JIRA_TASKS_TOKEN` instead of writing the environment's `JIRA_API_TOKEN`. DSH only refuses to write a ref the launching environment *shadows*, so its own ref is always writable: even with `JIRA_API_TOKEN` exported by the shell or the OS, the field accepts input, the save succeeds, and the Host prefers it:
 
-To manage the token from the settings card instead, remove the variable and restart DSH:
-
-- Windows (PowerShell): `[Environment]::SetEnvironmentVariable('JIRA_API_TOKEN', $null, 'User')`, then reopen the terminal
-- Windows (GUI): System Properties → Advanced → Environment Variables, delete the user variable
-- macOS / Linux: remove the export from `~/.zshrc` / `~/.bashrc` (or equivalent) and reopen the terminal
+```
+JIRA_TASKS_TOKEN (settings card) > JIRA_API_TOKEN > JIRA_TOKEN
+```
 
-Since v1.0.7 the card detects a read-only token, disables the field, and shows this guidance inline instead of failing on save.
+- The card names the effective source: with a saved token it says "overrides environment variable JIRA_API_TOKEN"; without one it says "currently using environment variable JIRA_API_TOKEN — fill in and save to override"
+- Saving re-probes the connection; **Clear settings token (fall back to environment)** removes the override
+- The one remaining case that reports `is supplied read-only by the launching environment` is someone exporting `JIRA_TASKS_TOKEN` itself — that ref really is read-only then; remove it (Windows: System Properties → Environment Variables, or PowerShell `[Environment]::SetEnvironmentVariable('JIRA_TASKS_TOKEN', $null, 'User')`) and restart DSH
 </details>
 
 <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 the DSH startup log for profile plugin load errors
+- 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`
 </details>
 
 ## Architecture & Implementation Details
@@ -143,21 +157,21 @@ Since v1.0.7 the card detects a read-only token, disables the field, and shows t
 <summary>Expand</summary>
 
 ```
-┌─────────── Browser (Client) ───────────┐      ┌──────────── Host ──────────────┐
-│ conversation.composer.dock (active)        │      │ webServer route /jira/api/search │
-│ conversation.input.dock (new, order:99)    │      │   ↓                            │
-│   ↓ on mount/refresh fetch POST            │      │ settings.get("jira-tasks")      │
-│ render: list / error / unconfigured        │      │ credentials.resolve(JIRA_*)     │
-│ localStorage per-workspace key/JQL         │      │ subprocess.spawn(curl …)        │
-│ settings.plugin.item (Settings card)       │      │   ↓ stdout JSON                 │
-└────────────────────────────────────────────┘      │ parse issues → {ok,issues}      │
+┌────────────── Browser (Client) ──────────────┐      ┌─────────────── Host ───────────────┐
+│ conversation.input.dock (both states)        │      │ webServer route /jira/api/search   │
+│ CSS order:99 -> below the input, full width  │      │ entry Config.baseUrl (volatile)    │
+│ on mount/refresh: fetch POST                 │      │ credentials.resolve(TOKEN_REFS)    │
+│ render: list / error / unconfigured          │      │ subprocess.spawn(curl ...)         │
+│ localStorage: per-workspace key/JQL          │      │ parse stdout JSON                  │
+│ plugins.item (Settings card)                 │      │ return {ok, issues}                │
+└──────────────────────────────────────────────┘      └────────────────────────────────────┘
                                                     └────────────────────────────────┘
 ```
 
-- **Host**: registers the `jira-tasks` settings namespace (`baseUrl`, readable) and a `webServer` route `POST /jira/api/search`; the address comes from the settings document, the token from the `credentials` service (Settings card / env / `$DSH_HOME/.credentials.yaml`, hot-reloaded); 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; registers `conversation.composer.dock` (active sessions) and `conversation.input.dock` (new sessions, flex `order: 99` below the input, aligned width), plus `settings.plugin.item` (`key: "jira-tasks"`) for the Settings card — the address is written through `settingsScope` and the token through `remote.credentials`.
+- **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. Also registers the plugin configuration card on `plugins.item` (`id: "jira-tasks"`) — the address 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. 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.
-- **New-session display**: the DSH shell does not render `composer.dock` during the hero (blank session) phase, so the plugin also registers `input.dock` and de-duplicates by "session has messages".
+- **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,6 +6,8 @@
 
 在 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`、设置服务 `ctx.configForms`（命名空间 = profile 条目 id `jira-tasks`）、`ctx.effect` / `configForms.whileServed` 的注销契约均按 0.1.7 的接口实现；0.1.6 及更早版本的 `settingsScope` / `settings.register` / `settings.plugin.item` 已不再使用。
+
 ## 功能
 
 - 📋 新会话与活跃会话的输入框下方均展示任务面板（新会话时与输入框等宽）
@@ -42,6 +44,8 @@ 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"` 即可。
+
 > 若改用 GitHub Packages 源：先在 profile 的 `.npmrc` 配置 `@liu3734:registry=https://npm.pkg.github.com/` 及读取令牌，再执行 `dsh plugin --profile web add @liu3734/dsh-jira-tasks`。
 
 <details>
@@ -69,12 +73,18 @@ dsh plugin --profile web add github:liu3734/jira-tasks-dsh-plugin
 
 打开 **设置 → 插件 → 插件配置 → JIRA**，填写：
 
-- **JIRA 地址**：如 `http://jira.example.com/`（存入用户设置文档，可在界面回读）
-- **访问令牌 / PAT**：写入凭据存储（`$DSH_HOME/.credentials.yaml`），前端只显示"已配置"，不回传令牌本身
+- **JIRA 地址**：如 `http://jira.example.com/`（写入本插件 profile 条目 `jira-tasks` 的 `Config.baseUrl`，即 profile 的 `cordis.patch.yml`，可在界面回读；保存被宿主拒绝时会直接报错，不会静默失败）
+- **访问令牌 / PAT**：写入凭据存储（`$DSH_HOME/.credentials.yaml`，引用名是插件自有的 `JIRA_TASKS_TOKEN`），前端只显示"已配置"，不回传令牌本身
 
-留空并保存会保持已有令牌不变；地址留空并保存则清除设置项，回退到环境变量。认证自动识别：令牌含 `:` 用 Basic，否则用 Bearer（JIRA PAT）。
+留空并保存会保持已有令牌不变；地址留空并保存则清除设置项，回退到凭据存储 / 环境变量。认证自动识别：令牌含 `:` 用 Basic，否则用 Bearer（JIRA PAT）。
 
-> **令牌已由环境变量提供时，设置页无法改写它**：若启动 DSH 的环境里已设置 `JIRA_API_TOKEN`（Windows 用户级环境变量也算），DSH 会将该引用视为只读，卡片会禁用令牌输入并说明原因。此时面板已直接使用该环境变量，**无需保存**；要改由设置页管理，请先移除环境变量（Windows：系统属性 → 环境变量，或 PowerShell `[Environment]::SetEnvironmentVariable('JIRA_API_TOKEN', $null, 'User')`）后重启 DSH。
+> **设置页令牌优先于环境变量**：启动 DSH 的环境里已有 `JIRA_API_TOKEN`（Windows 用户级环境变量也算）时，卡片照常可以输入并保存——保存的是插件自有引用 `JIRA_TASKS_TOKEN`，DSH 不会拒绝（它只拒绝写入会被环境遮蔽的同名引用），Host 解析时也把它排在环境变量之前：
+>
+> ```
+> JIRA_TASKS_TOKEN（设置页） > JIRA_API_TOKEN > JIRA_TOKEN
+> ```
+>
+> 想改回用环境变量，点卡片里的「清除设置页令牌」即可。
 
 #### 连接测试
 
@@ -84,7 +94,7 @@ dsh plugin --profile web add github:liu3734/jira-tasks-dsh-plugin
 - **绿** = 地址与令牌可用（并显示当前登录用户）；**红** = 不可用（显示 JIRA 返回的原因，如 401 认证失败）；**灰** = 地址或令牌未配置
 - 点 **测试连接** 会用**当前输入框里的内容**（未保存也可）立即测试，方便改完再存
 
-以下环境变量 / 凭据仍作为**回退**（设置页未配置时生效，兼容旧部署），热加载无需重启：
+以下环境变量 / 凭据仍作为**回退**（设置页未配置 `baseUrl` 时生效，兼容旧部署），热加载无需重启。注意地址的优先级是 `Config.baseUrl` > `JIRA_BASE_URL` > `JIRA_URL`，而 `JIRA_BASE_URL` 既可以从启动环境读，也可以像下面这样存在 `.credentials.yaml` 里——旧域名的记录留在凭据文件里时，设置页一旦清空地址就会回退到它：
 
 ```yaml
 JIRA_BASE_URL: "http://jira.example.com/"
@@ -92,7 +102,7 @@ JIRA_API_TOKEN: "<PAT 或 user:token>"
 ```
 
 - 地址别名：`JIRA_BASE_URL` / `JIRA_URL`
-- 令牌别名：`JIRA_API_TOKEN` / `JIRA_TOKEN`
+- 令牌解析顺序：`JIRA_TASKS_TOKEN`（设置页写入）→ `JIRA_API_TOKEN` → `JIRA_TOKEN`，前者优先
 
 ### 2. 项目 Key 与 JQL（按工作区）
 
@@ -131,24 +141,26 @@ dsh plugin --profile web remove dsh-jira-tasks
 </details>
 
 <details>
-<summary>保存令牌报 “is supplied read-only by the launching environment”</summary>
-
-`JIRA_API_TOKEN`（或 `JIRA_TOKEN`）已由启动 DSH 的环境提供，DSH 判定该引用只读：写入会被环境变量遮蔽，因此拒绝保存。此时面板已经直接使用该环境变量，能正常查询，**无需在设置页保存**。
+<summary>环境变量里的令牌，能不能在设置页覆盖？</summary>
 
-如需改由设置页管理令牌，先移除环境变量再重启 DSH：
+**能。** 卡片把令牌保存到插件自有引用 `JIRA_TASKS_TOKEN`，而不是直接写环境变量用的 `JIRA_API_TOKEN`。DSH 只拒绝写入「会被启动环境遮蔽的同名引用」，插件自有引用不受影响，所以哪怕 shell / 系统里已导出 `JIRA_API_TOKEN`，设置页也能正常输入并保存，并且 Host 解析时优先用它：
 
-- Windows（PowerShell）：`[Environment]::SetEnvironmentVariable('JIRA_API_TOKEN', $null, 'User')`，然后重开终端
-- Windows（图形界面）：系统属性 → 高级 → 环境变量，删除对应用户变量
-- macOS / Linux：从 `~/.zshrc` / `~/.bashrc` 等启动脚本中移除后重开终端
+```
+JIRA_TASKS_TOKEN（设置页） > JIRA_API_TOKEN > JIRA_TOKEN
+```
 
-v1.0.7 起卡片会检测只读令牌并直接禁用输入框、在卡片内给出上述提示，不再等到保存才报英文错误。
+- 卡片会显示当前生效来源：已保存设置页令牌时提示「优先于环境变量 JIRA_API_TOKEN」；未保存时提示「当前使用环境变量 JIRA_API_TOKEN，填写并保存即可覆盖」
+- 保存后自动重测连接；点「清除设置页令牌（回退到环境变量）」可删除覆盖值
+- 唯一仍会报 `is supplied read-only by the launching environment` 的情况：有人把 `JIRA_TASKS_TOKEN` 本身也导出到了启动环境——那种情况下该引用确实只读，需先移除它（Windows：系统属性 → 环境变量，或 PowerShell `[Environment]::SetEnvironmentVariable('JIRA_TASKS_TOKEN', $null, 'User')`）并重启 DSH
 </details>
 
 <details>
 <summary>面板不显示</summary>
 
 - 确认已安装并**重启 DSH**；新会话面板位于输入框下方
-- 检查 DSH 启动日志中 profile 插件是否加载成功
+- 检查 `~/.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`
 </details>
 
 ## 架构与实现细节
@@ -158,20 +170,19 @@ v1.0.7 起卡片会检测只读令牌并直接禁用输入框、在卡片内给
 
 ```
 ┌────────────────────────────────────────┐   ┌────────────────────────────────────┐
-│ conversation.composer.dock（活跃会话）  │   │ webServer 路由 /jira/api/search     │
-│ conversation.input.dock（新会话）       │   │ ↓                                   │
-│   面板 hero 布局（flex order:99）       │   │ settings.get("jira-tasks").baseUrl   │
-│   ↓ 挂载 / 刷新时 fetch POST            │   │ credentials.resolve(JIRA_API_TOKEN) │
+│ conversation.input.dock（两种会话）     │   │ webServer 路由 /jira/api/search     │
+│   CSS order:99 → 输入框下方、整宽       │   │ 条目 Config.baseUrl（volatile 引用） │
+│   ↓ 挂载 / 刷新时 fetch POST            │   │ credentials.resolve(TOKEN_REFS)     │
 │ 渲染：任务列表 / 错误 / 未配置          │   │ subprocess.spawn(curl …)            │
 │ localStorage 按工作区存取项目 Key/JQL   │   │ ↓ stdout JSON                       │
-│ settings.plugin.item（设置页卡片）      │   │ 解析 issues → 返回 {ok,issues}      │
+│ plugins.item（设置页卡片）              │   │ 解析 issues → 返回 {ok,issues}      │
 └────────────────────────────────────────┘   └────────────────────────────────────┘
 ```
 
-- **Host**：注册 `settings` 命名空间 `jira-tasks`（`baseUrl`，可读）与 `webServer` 路由 `POST /jira/api/search`；地址优先读设置文档，令牌经 `credentials` 服务解析（设置页写入 / 环境变量 / `$DSH_HOME/.credentials.yaml`，热加载）；查询用 `subprocess` 直接 `spawn curl`，认证头经 stdin（`--config -`）传入，令牌不进入命令行参数。
-- **Client**：`window.__ModuleLoader__.load({ id, factory })` 标准 web bundle；注册 `conversation.composer.dock`（活跃会话，注册 `order: 5`）与 `conversation.input.dock`（新会话，注册 `order: 10`）。新会话面板走 hero 布局：面板元素自身 `flex order: 99` 排在输入框之后下方，并以 `--dsh-composer-side-clearance` / `--dsh-composer-card-max-width` 与输入卡等宽。另注册 `settings.plugin.item`（`key: "jira-tasks"`）作为设置页卡片：地址经 `settingsScope` 写入命名空间，令牌经 `remote.credentials` 写入凭据存储。
+- **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 行，与上下文占用环并排，整宽面板会被占用环压住右侧内容。插件配置卡片注册到 `plugins.item`（`id: "jira-tasks"`），表单来自 `ctx.configForms.get("jira-tasks")`（地址）与 `remote.credentials`（令牌写入 `JIRA_TASKS_TOKEN`），并用 `configForms.whileServed` 保证宿主未提供该命名空间时不显示；`plugins.item` 的摘要位由一个**不调用任何 hook** 的分发组件负责，表单在独立的 `JiraSettingsPage` 里，避免同一实例在 `view` 切换时改变 hook 数量。
 - **为什么不用 `shell` 服务**：`shell` 会套 `sandbox-exec`，部分 macOS 上不可用（`sandbox_apply: Operation not permitted`）；`subprocess` 是原始进程缝，无此问题。
-- **新会话显示**：DSH 壳在 hero（空白会话）阶段不渲染 `composer.dock`，故额外注册 `input.dock`，并用「会话是否已有消息」去重（新版 DSH 依据 `SessionSnapshot.blank`），避免双份面板。
+- **一处注册覆盖两种会话**：`conversation.input.dock` 只要有 session + input 就会渲染，新会话与活跃会话无需分别注册（旧版曾用 `composer.dock` + 空白判定去重，0.1.7 下既不必要、又会与占用环抢同一行）。
 
 **与动态插件版的差异**
 

package/lib/client.js

@@ -8,6 +8,7 @@ window.__ModuleLoader__.load({
     var h = React.createElement;
 
     var CSS = ".jt-root{box-sizing:border-box;width:100%;padding:2px 0 6px;flex:none;display:flex;flex-direction:column}"
+      + "/* composerStack 是 flex-direction:column：order:99 把面板排到输入卡之后，即输入框下方。 */"
       + ".jt-hero{order:99;padding:0 var(--dsh-composer-side-clearance, 16px)}"
       + ".jt-panel{box-sizing:border-box;width:100%;max-width:var(--dsh-composer-card-max-width, 780px);margin:0 auto;border:1px solid var(--dsw-alias-border-l1, rgba(127,127,127,.28));background:var(--dsw-alias-bg-layer-1, rgba(127,127,127,.07));border-radius:10px;overflow:hidden}"
       + ".jt-header{display:flex;align-items:center;gap:8px;min-height:30px;padding:2px 6px 2px 4px}"
@@ -95,15 +96,6 @@ window.__ModuleLoader__.load({
       persistAll(all);
     }
 
-    // 新版 DSH：SessionSnapshot.blank 是“会话日志为空”的规范标记；旧版 DSH：消息位于 chat.timeline / chat.legacy.nodes。
-    function hasMessages(session) {
-      if (!session) return false;
-      if (typeof session.blank === "boolean") return !session.blank;
-      if (session.chat && session.chat.timeline && session.chat.timeline.length > 0) return true;
-      if (session.chat && session.chat.legacy && session.chat.legacy.nodes && session.chat.legacy.nodes.length > 0) return true;
-      return false;
-    }
-
     function query(projectKey, jql) {
       return fetch("/jira/api/search", {
         method: "POST",
@@ -122,7 +114,6 @@ window.__ModuleLoader__.load({
     }
 
     function JiraTasksDock(props) {
-      var blankOnly = !!(props && props.blankOnly === true);
       var useWorkspaces = props && typeof props.useWorkspaces === "function" ? props.useWorkspaces : null;
       var sessionId = props && props.sessionId;
       var wsState = useWorkspaces ? useWorkspaces(function (s) { return s; }) : null;
@@ -173,8 +164,9 @@ window.__ModuleLoader__.load({
         return function () { cancelled = true; };
       }, [config, tick]);
 
-      if (blankOnly && hasMessages(props.session)) return null;
-
+      // 面板只注册 conversation.input.dock 一处（见 apply 里的说明）：
+      // 该槽位在“新会话”和“活跃会话”下都会渲染，且是整行纵向排布的元素，
+      // 因此这里没有“仅空白会话显示”的分支，也不需要去重。
       function openEditor() {
         setDraftKey(config.projectKey);
         setDraftJql(config.jql || defaultJql(config.projectKey));
@@ -187,10 +179,8 @@ window.__ModuleLoader__.load({
         setEditing(false);
       }
 
-      var heroLayout = blankOnly;
-
       if (editing) {
-        return h("div", { className: heroLayout ? "jt-root jt-hero" : "jt-root" },
+        return h("div", { className: "jt-root jt-hero" },
           h("div", { className: "jt-panel" },
             h("div", { className: "jt-header" }, h("span", { className: "jt-title" }, "JIRA 任务设置")),
             h("div", { className: "jt-body" },
@@ -260,7 +250,7 @@ window.__ModuleLoader__.load({
         body = h("div", { className: "jt-hint" }, "未设置 JIRA 项目 Key，", h("button", { className: "jt-linklike", onClick: openEditor }, "点击配置"));
       }
 
-      return h("div", { className: heroLayout ? "jt-root jt-hero" : "jt-root" },
+      return h("div", { className: "jt-root jt-hero" },
         h("div", { className: "jt-panel" },
           h("div", { className: "jt-header" },
             h("button", {
@@ -285,8 +275,13 @@ window.__ModuleLoader__.load({
     // ---- 设置页卡片：设置 → 插件 → JIRA ----
     // 地址存 settings 命名空间（可读）；令牌写 credentials（永不随响应回传）。
     var SETTINGS_NS = "jira-tasks";
-    var TOKEN_REF = "JIRA_API_TOKEN";
-    var TOKEN_REFS = ["JIRA_API_TOKEN", "JIRA_TOKEN"];
+    // 令牌写入插件自有引用，而不是直接写 JIRA_API_TOKEN：启动环境里导出的
+    // JIRA_API_TOKEN 会让那个引用只读（DSH 拒绝写入会被环境遮蔽的引用），而
+    // 插件自有引用不受影响，因此设置页保存的值可以覆盖环境变量——优先级由
+    // Host 的解析顺序保证（JIRA_TASKS_TOKEN → JIRA_API_TOKEN → JIRA_TOKEN）。
+    var TOKEN_REF = "JIRA_TASKS_TOKEN";
+    var ENV_TOKEN_REFS = ["JIRA_API_TOKEN", "JIRA_TOKEN"];
+    var TOKEN_REFS = [TOKEN_REF].concat(ENV_TOKEN_REFS);
 
     // credentials-local 拒绝写入“由启动环境提供”的引用时，原始信息是英文的；这里取出引用名并给出可操作的中文说明。
     function shadowedTokenRef(message) {
@@ -295,9 +290,9 @@ window.__ModuleLoader__.load({
     }
     function tokenReadOnlyHint(ref) {
       var name = ref || TOKEN_REF;
-      return "令牌由启动 DSH 的环境变量 " + name + " 提供（只读），面板已直接使用，无需在此保存。"
-        + "如需改由设置页管理，请先移除该环境变量并重启 DSH；Windows 可在 PowerShell 执行 "
-        + "[Environment]::SetEnvironmentVariable('" + name + "', $null, 'User') 后重开终端。";
+      return "环境变量 " + name + " 由启动 DSH 的终端提供且只读，无法写入该引用。"
+        + "请先移除它（Windows：系统属性 → 环境变量，或 PowerShell "
+        + "[Environment]::SetEnvironmentVariable('" + name + "', $null, 'User')）并重启 DSH。";
     }
 
     function useScopeSnapshot(scope) {
@@ -316,23 +311,37 @@ window.__ModuleLoader__.load({
       function readTokenInfo() {
         return credentials.describe(TOKEN_REFS).then(function (res) {
           if (!res || !res.ok || !res.value) return { configured: false, writable: true };
-          for (var i = 0; i < TOKEN_REFS.length; i++) {
-            var ref = TOKEN_REFS[i];
-            var info = res.value[ref];
-            // 命中的第一个引用即生效来源；writable 为 false 表示只读（由启动环境提供），写不进去。
+          var value = res.value;
+          var override = value[TOKEN_REF];
+          var overridden = !!(override && override.configured);
+          var fallbackRef = "", fallbackSource = "";
+          for (var i = 0; i < ENV_TOKEN_REFS.length; i++) {
+            var info = value[ENV_TOKEN_REFS[i]];
             if (info && info.configured) {
-              return { configured: true, writable: info.writable !== false, ref: ref };
+              fallbackRef = ENV_TOKEN_REFS[i];
+              fallbackSource = info.source || "";
+              break;
             }
           }
-          var primary = res.value[TOKEN_REF];
-          return { configured: false, writable: primary ? primary.writable !== false : true, ref: TOKEN_REF };
+          return {
+            configured: overridden || fallbackRef !== "",
+            overridden: overridden,
+            // 只有插件自有引用可能被环境遮蔽；JIRA_API_TOKEN 只读不影响这里的写入。
+            writable: !override || override.writable !== false,
+            // 仅当回退值确实来自启动环境时才称它为“环境变量”（旧版本可能把它存在凭据文件里）。
+            envRef: fallbackSource === "env" ? fallbackRef : ""
+          };
         }).catch(function () {
           // 状态读取失败不阻断保存，交由写入路径给出真实错误。
           return { configured: false, writable: true };
         });
       }
 
-      return function JiraSettingsCard() {
+      // plugins.item 的两个渲染位：列表里的卡片摘要（view="summary"）与点开后的
+      // 详情面板（view="page"）。分发组件自身不调用任何 hook，钩子全部留在
+      // JiraSettingsPage 里，这样同一个实例的 hook 数量与 view 取值无关——
+      // 这是 React 的硬性要求，早期版本把摘要提前 return 写在 hook 之前会踩这条规则。
+      function JiraSettingsPage() {
         var snapshot = useScopeSnapshot(scope);
         var tokenInfoState = React.useState(null);
         var tokenInfo = tokenInfoState[0], setTokenInfo = tokenInfoState[1];
@@ -362,31 +371,37 @@ window.__ModuleLoader__.load({
 
         var storedBase = snapshot.value && typeof snapshot.value.baseUrl === "string" ? snapshot.value.baseUrl : "";
         var baseValue = baseEdit === undefined ? storedBase : baseEdit;
-        var dirty = (baseEdit !== undefined && baseEdit !== storedBase) || (tokenDraft || "").length > 0;
+        var baseDirty = baseEdit !== undefined && baseEdit !== storedBase;
+        var tokenDraftText = (tokenDraft || "").trim();
+        var tokenDirty = tokenDraftText.length > 0;
+        var dirty = baseDirty || tokenDirty;
         var writable = snapshot.writable !== false;
-        // 令牌可能来自启动环境（只读）：此时禁用输入并说明原因，而不是等到保存才报 DSH 的英文错误。
+        // 插件自有引用通常可写；只有 JIRA_TASKS_TOKEN 本身也被导出到启动环境时才会只读。
         var tokenWritable = !tokenInfo || tokenInfo.writable !== false;
-        var tokenReadOnly = !!(tokenInfo && tokenInfo.configured && tokenInfo.writable === false);
+        var tokenOverridden = !!(tokenInfo && tokenInfo.overridden);
+        var envTokenRef = tokenInfo && tokenInfo.envRef ? tokenInfo.envRef : "";
 
         // 命名空间未挂载时不显示，避免留下一张无法操作的卡片。
         if (snapshot.status === "unavailable") return null;
 
         function save() {
           if (busy || !dirty) return;
+          if (tokenDirty && !tokenWritable) {
+            setFailed(tokenReadOnlyHint(TOKEN_REF));
+            return;
+          }
           setBusy(true);
           setFailed("");
           var tasks = [];
-          if (baseEdit !== undefined && baseEdit !== storedBase) {
-            tasks.push(baseEdit === "" ? scope.unset("baseUrl") : scope.set("baseUrl", baseEdit));
-          }
-          var token = (tokenDraft || "").trim();
-          if (token && !tokenWritable) {
-            setBusy(false);
-            setFailed(tokenReadOnlyHint(tokenInfo && tokenInfo.ref));
-            return;
+          if (baseDirty) {
+            // ConfigForm.set/unset 解析为 boolean：false = 宿主拒绝写入或连接处于
+            // memory 模式。以前忽略返回值会让面板“看起来保存了”，实际没落盘。
+            tasks.push((baseEdit === "" ? scope.unset("baseUrl") : scope.set("baseUrl", baseEdit)).then(function (accepted) {
+              if (accepted === false) throw new Error("JIRA 地址保存被宿主拒绝（该命名空间只读，或连接处于 memory 模式）");
+            }));
           }
-          if (token) {
-            tasks.push(credentials.set(TOKEN_REF, token).then(function (res) {
+          if (tokenDirty) {
+            tasks.push(credentials.set(TOKEN_REF, tokenDraftText).then(function (res) {
               if (res && res.ok === false) {
                 var err = res.error;
                 throw new Error((err && (err.message || err.code)) || "令牌保存失败");
@@ -400,6 +415,31 @@ window.__ModuleLoader__.load({
             setBaseEdit(undefined);
             setTokenDraft("");
             setBusy(false);
+            // baseUrl 变更会经 snapshot.revision 触发自动重测；仅保存令牌时手动补一次。
+            if (!baseDirty) runProbe({});
+          }).catch(function (err) {
+            setBusy(false);
+            var shadowed = shadowedTokenRef(err && err.message);
+            setFailed(shadowed ? tokenReadOnlyHint(shadowed) : String((err && err.message) || err));
+          });
+        }
+
+        // 清除设置页保存的令牌，回退到环境变量 / 凭据文件中的旧值。
+        function clearOverride() {
+          if (busy) return;
+          setBusy(true);
+          setFailed("");
+          credentials.unset(TOKEN_REF).then(function (res) {
+            if (res && res.ok === false) {
+              var err = res.error;
+              throw new Error((err && (err.message || err.code)) || "清除令牌失败");
+            }
+            return readTokenInfo();
+          }).then(function (info) {
+            setTokenInfo(info);
+            setTokenDraft("");
+            setBusy(false);
+            runProbe({});
           }).catch(function (err) {
             setBusy(false);
             var shadowed = shadowedTokenRef(err && err.message);
@@ -430,9 +470,11 @@ window.__ModuleLoader__.load({
 
         var tokenHint = tokenInfo === null
           ? "正在读取令牌状态…"
-          : (tokenReadOnly
-            ? tokenReadOnlyHint(tokenInfo.ref)
-            : (tokenInfo.configured ? "令牌已配置；留空并保存可保持不变。" : "令牌未配置。含 “:” 时用 Basic，否则用 Bearer。"));
+          : (tokenOverridden
+            ? "设置页令牌已保存" + (envTokenRef ? "，优先于环境变量 " + envTokenRef : "") + "；留空并保存可保持不变。"
+            : (envTokenRef
+              ? "当前使用环境变量 " + envTokenRef + "；在下方填写并保存即可覆盖它。"
+              : (tokenInfo.configured ? "令牌已配置；留空并保存可保持不变。" : "令牌未配置。含 “:” 时用 Basic，否则用 Bearer。")));
         var dotClass = probe.phase === "ok" ? "jt-dot jt-dot-ok"
           : probe.phase === "fail" ? "jt-dot jt-dot-fail"
             : probe.phase === "testing" ? "jt-dot jt-dot-testing" : "jt-dot";
@@ -461,14 +503,18 @@ window.__ModuleLoader__.load({
               className: "jt-input",
               type: "password",
               value: tokenDraft,
-              placeholder: tokenReadOnly ? "由环境变量提供（只读）" : (tokenInfo && tokenInfo.configured ? "已配置，留空保持不变" : "粘贴令牌"),
+              placeholder: tokenOverridden ? "已保存，留空保持不变" : (envTokenRef ? "填写以覆盖环境变量" : (tokenInfo && tokenInfo.configured ? "已配置，留空保持不变" : "粘贴令牌")),
               autoComplete: "off",
-              disabled: !writable || busy || !tokenWritable,
+              disabled: busy || !tokenWritable,
               onChange: function (e) { setTokenDraft(e.target.value); },
               onKeyDown: function (e) { if (e.key === "Enter") save(); }
             })
           ),
           h("div", { className: "jt-hint", style: { marginBottom: "8px" } }, tokenHint),
+          tokenOverridden && tokenWritable
+            ? h("div", { className: "jt-hint", style: { margin: "-4px 0 8px" } },
+              h("button", { className: "jt-linklike", disabled: busy, onClick: clearOverride }, "清除设置页令牌（回退到环境变量）"))
+            : null,
           h("div", { className: "jt-probe", role: "status" },
             h("span", { className: dotClass, "aria-hidden": "true" }),
             h("span", null, probe.message || "未测试")
@@ -483,50 +529,61 @@ window.__ModuleLoader__.load({
               onClick: function () { runProbe({ baseUrl: baseValue, token: (tokenDraft || "").trim() }); }
             }, probe.phase === "testing" ? "测试中…" : "测试连接"),
             h("button", { className: "jt-btn", disabled: !dirty || busy, onClick: discard }, "放弃"),
-            h("button", { className: "jt-btn jt-btn-primary", disabled: !dirty || busy || !writable || ((tokenDraft || "").trim().length > 0 && !tokenWritable), onClick: save }, busy ? "保存中…" : "保存")
+            h("button", { className: "jt-btn jt-btn-primary", disabled: !dirty || busy || (baseDirty && !writable) || (tokenDirty && !tokenWritable), onClick: save }, busy ? "保存中…" : "保存")
           )
         );
+      }
+
+      // 槽位组件：摘要位只回一行文字，详情位挂载真正的表单。
+      return function JiraSettingsCard(props) {
+        if (props && props.view === "summary") return "JIRA 地址、令牌与连接状态";
+        return h(JiraSettingsPage, null);
       };
     }
 
     function apply(ctx) {
       // ctx.effect(cb) 会立即执行 cb 并把其返回值作为卸载时的清理函数，
       // 所以样式注入必须放在回调内、返回移除函数，否则标签刚插入就被删除。
-      if (ctx && typeof ctx.effect === "function") {
-        ctx.effect(function () {
-          var styleTag = document.createElement("style");
-          styleTag.textContent = CSS;
-          document.head.appendChild(styleTag);
-          return function () { try { styleTag.remove(); } catch (e) {} };
-        });
-      } else {
+      ctx.effect(function () {
         var styleTag = document.createElement("style");
         styleTag.textContent = CSS;
         document.head.appendChild(styleTag);
-      }
+        return function () { try { styleTag.remove(); } catch (e) {} };
+      }, "jira-tasks: styles");
       var slots = ctx.get("slots");
       if (!slots) return;
-      slots.inject("conversation.composer.dock", function () {
-        return slots.register({ name: "conversation.composer.dock", id: "jira-open-tasks", order: 5 }, JiraTasksDock);
-      });
+      // 只注册 conversation.input.dock 一处。
+      //
+      // 为什么不用 conversation.composer.dock：该槽位在 DSH 0.1.7 里渲染进
+      // InputBar 的 .dock 行——一个 justify-content:center 的**横向** flex 行，
+      // 与右侧的上下文占用环（ContextMeter）并排。整宽任务面板放进那一行，会和
+      // 占用环抢同一条 flex line，面板右侧内容被环压住。
+      //
+      // conversation.input.dock 属于 composerStack（flex-direction:column），
+      // 在新会话与活跃会话下都会渲染（只要有 session + input），是整宽纵向行；
+      // 面板自身用 CSS order:99 排到输入卡之后，即“输入框下方”。
       slots.inject("conversation.input.dock", function () {
-        return slots.register({ name: "conversation.input.dock", id: "jira-open-tasks-hero", order: 10 }, function (props) {
-          return h(JiraTasksDock, Object.assign({}, props, { blankOnly: true }));
-        });
+        return slots.register({ name: "conversation.input.dock", id: "jira-open-tasks", order: 10 }, JiraTasksDock);
       });
 
-      // 设置页卡片：宿主注册了 jira-tasks 命名空间时，由插件配置 Tab 分发到本卡片。
-      var settingsScope = ctx.get("settingsScope");
+      // 设置页卡片。DSH 0.1.5+ ：设置表单的服务是 configForms，命名空间就是本插件
+      // 的 profile 条目 id（jira-tasks）；卡片注册到“插件”页的 plugins.item 槽，
+      // 并且只在宿主确实提供了该命名空间时才出现（whileServed 的 disposer 交回 effect）。
+      var configForms = ctx.get("configForms");
       var remote = ctx.get("remote");
-      if (settingsScope && remote && remote.credentials) {
-        var card = createJiraSettingsCard(settingsScope.bind({ namespace: SETTINGS_NS }), remote.credentials);
-        slots.inject("settings.plugin.item", function () {
-          return slots.register({ name: "settings.plugin.item", key: SETTINGS_NS }, card);
-        });
+      if (configForms && remote && remote.credentials) {
+        var card = createJiraSettingsCard(configForms.get(SETTINGS_NS), remote.credentials);
+        ctx.effect(function () {
+          return configForms.whileServed([SETTINGS_NS], function () {
+            return slots.inject("plugins.item", function () {
+              return slots.register({ name: "plugins.item", id: SETTINGS_NS, order: 41, label: "JIRA" }, card);
+            });
+          });
+        }, "jira-tasks: plugins page card");
       }
     }
 
-    exports.inject = ["slots", "settingsScope", "remote", "remote.credentials"];
+    exports.inject = ["slots", "configForms", "remote", "remote.credentials"];
     exports.apply = apply;
     return module.exports;
   }

package/lib/index.js

@@ -1,10 +1,11 @@
 /**
  * dsh-jira-tasks — HOST half (persistent profile plugin).
- * Serves POST /jira/api/search: reads the JIRA base URL from the `jira-tasks`
- * settings namespace and the token from the credentials service (falling back
- * to JIRA_BASE_URL / JIRA_API_TOKEN for existing setups), queries JIRA
- * /rest/api/2/search through subprocess+curl (auth header via stdin
- * --config -), returns normalized issue JSON.
+ * Serves POST /jira/api/search: reads the JIRA base URL from this entry's own
+ * Config (the `jira-tasks` profile entry, editable on the Plugins settings
+ * page) and the token from the credentials service — the settings-page
+ * JIRA_TASKS_TOKEN first, so it overrides an exported JIRA_API_TOKEN /
+ * JIRA_TOKEN — then queries JIRA /rest/api/2/search through subprocess+curl
+ * (auth header via stdin --config -), returning normalized issue JSON.
  */
 import z from '@deepseek-ai/schemastery';
 
@@ -12,17 +13,59 @@ import z from '@deepseek-ai/schemastery';
 const SETTINGS_NS = 'jira-tasks';
 
 /**
- * Durable connection schema. `baseUrl` is a plain readable field; the token is
- * deliberately NOT stored here — it stays in the credentials store (write-only
- * from the client) so no secret ever lands in settings.yaml.
+ * Diagnostics name for this plugin instance. Deliberately the same string as
+ * {@link SETTINGS_NS} (= the profile entry id, `jira-tasks`): that id — not this
+ * name and not the package name `dsh-jira-tasks` — is the settings namespace the
+ * client card edits, so deriving one from the other removes a whole class of
+ * confusion when reading loader logs.
  */
-const JiraSettingsSchema = z.object({
-  baseUrl: z.string().default('').description('JIRA 地址，例如 http://jira.example.com/')
+const name = SETTINGS_NS;
+
+/**
+ * Token references in precedence order. `JIRA_TASKS_TOKEN` is the plugin-owned
+ * ref the settings card writes to: unlike `JIRA_API_TOKEN`, the credentials
+ * provider can always store it, because the launching environment does not
+ * supply it. Listing it first is what makes a saved token override an exported
+ * `JIRA_API_TOKEN` / `JIRA_TOKEN`.
+ */
+const TOKEN_REFS = ['JIRA_TASKS_TOKEN', 'JIRA_API_TOKEN', 'JIRA_TOKEN'];
+
+/**
+ * Durable connection schema. Since DSH 0.1.5 the settings service no longer
+ * takes a `register(ns, schema)` call: a plugin's OWN Config IS the form its
+ * settings page is built from, keyed by the profile entry id (`jira-tasks`).
+ * `baseUrl` is volatile, so a saved change reaches the running plugin without
+ * remounting it. The token is deliberately NOT here — it stays in the
+ * credentials store (write-only from the client), so no secret ever lands in
+ * the profile configuration document.
+ */
+const Config = z.object({
+  baseUrl: z.string().default('').volatile().description('JIRA 地址，例如 http://jira.example.com/')
 });
 
-export default {
-  inject: ['subprocess', 'credentials', 'sandboxPolicy', 'webServer'],
-  apply(ctx) {
+const inject = ['subprocess', 'credentials', 'sandboxPolicy', 'webServer'];
+
+/**
+ * Answer a non-POST request with 405. `webServer.register` dispatches on the
+ * pathname only, so without this guard a stray GET would run a real JIRA
+ * query. Returns true when the caller may handle the request.
+ * @param req - the HTTP request.
+ * @param res - the response the guard writes to on refusal.
+ * @returns true for POST, false after answering 405.
+ */
+function methodIsPost(req, res) {
+  if (req.method === 'POST') return true;
+  res.writeHead(405, { 'Content-Type': 'text/plain; charset=utf-8', 'Cache-Control': 'no-store', Allow: 'POST' });
+  res.end('method not allowed');
+  return false;
+}
+
+/**
+ * Mount the host half: the /jira/api/* routes and the settings-page policy.
+ * @param ctx - plugin context.
+ * @param config - this entry's live Config (profile entry `jira-tasks`).
+ */
+function apply(ctx, config) {
     const sendJson = (res, obj) => {
       res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
       res.end(JSON.stringify(obj));
@@ -55,19 +98,32 @@ export default {
       return undefined;
     }
 
-    // Register the GUI-editable section when the optional settings service is
-    // composed; without it the plugin keeps working from the composition/env.
+    // DSH 0.1.5+ ：设置页的表单直接来自本条目自己的 Config，settings 服务不再有
+    // register(ns, schema)。这里把本实例的“自动生成页”关掉，改由客户端注册的
+    // 自定义卡片（地址 + 令牌 + 连通性测试）接管。
+    // 两个易错点：1) configure 的第二个参数必须是**本插件实例**的 fiber——默认值是
+    // settings 服务自己的 fiber，而 describe() 是按 entry.fiber 查策略的，传错不生效；
+    // 2) 返回值是注销函数，必须交回 effect，否则卸载后策略会一直挂在死 fiber 上。
     ctx.inject(['settings'], (settingsCtx) => {
-      settingsCtx.settings.register(SETTINGS_NS, JiraSettingsSchema);
+      settingsCtx.effect(() => {
+        try {
+          return settingsCtx.settings.configure({ auto: false }, ctx.fiber);
+        } catch (e) {
+          // 同一实例重复配置等情况下不阻断插件加载，但要留下可诊断的日志。
+          if (ctx.logger && typeof ctx.logger.warn === 'function') {
+            ctx.logger.warn('jira-tasks: settings page policy not applied: %s', (e && e.message) || e);
+          }
+          return undefined;
+        }
+      }, 'jira-tasks: settings page policy');
     });
 
-    /** Base URL from the settings document, or '' when unset/unavailable. */
+    /** 本条目 Config 里的 JIRA 地址（volatile 引用），未配置时返回 ''。 */
     function settingsBaseUrl() {
       try {
-        const settings = ctx.get('settings');
-        if (!settings) return '';
-        const section = settings.get(SETTINGS_NS);
-        return section && typeof section.baseUrl === 'string' ? section.baseUrl.trim() : '';
+        const ref = config && config.baseUrl;
+        const value = ref && typeof ref.get === 'function' ? ref.get() : ref;
+        return typeof value === 'string' ? value.trim() : '';
       } catch (e) {
         return '';
       }
@@ -166,7 +222,7 @@ export default {
       try {
         const baseUrl = settingsBaseUrl() || await resolveFirst(['JIRA_BASE_URL', 'JIRA_URL']);
         if (!baseUrl) return { ok: false, error: '未配置 JIRA 地址（设置 → 插件 → JIRA，或环境变量 JIRA_BASE_URL）' };
-        const token = await resolveFirst(['JIRA_API_TOKEN', 'JIRA_TOKEN']);
+        const token = await resolveFirst(TOKEN_REFS);
         if (!token) return { ok: false, error: '未配置 JIRA 令牌（设置 → 插件 → JIRA，或环境变量 JIRA_API_TOKEN）' };
 
         const jql = buildJql(args && args.jql ? String(args.jql) : '', projectKey);
@@ -213,7 +269,7 @@ export default {
         const draftToken = args && typeof args.token === 'string' ? args.token.trim() : '';
         const baseUrl = draftBase || settingsBaseUrl() || await resolveFirst(['JIRA_BASE_URL', 'JIRA_URL']);
         if (!baseUrl) return { ok: false, code: 'unconfigured', error: '未配置 JIRA 地址' };
-        const token = draftToken || await resolveFirst(['JIRA_API_TOKEN', 'JIRA_TOKEN']);
+        const token = draftToken || await resolveFirst(TOKEN_REFS);
         if (!token) return { ok: false, code: 'unconfigured', error: '未配置 JIRA 令牌' };
 
         const raw = await probeJira(baseUrl, token);
@@ -244,28 +300,33 @@ export default {
     }
 
     if (webServer && typeof webServer.register === 'function') {
-      webServer.register({
+      // 每条路由都必须挂在自己的 effect 上：register 返回注销函数，卸载/重载时先释放，
+      // 否则重挂载会因为“同一 (kind, path) 只允许一条路由”直接抛错，整个插件激活失败。
+      ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/jira/api/search',
         handler: async (req, res) => {
+          if (!methodIsPost(req, res)) return;
           try {
             sendJson(res, await handleSearch(await readBody(req)));
           } catch (e) {
             sendJson(res, { ok: false, error: String((e && e.message) || e) });
           }
         }
-      });
-      webServer.register({
+      }), 'jira-tasks: /jira/api/search');
+      ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/jira/api/test',
         handler: async (req, res) => {
+          if (!methodIsPost(req, res)) return;
           try {
             sendJson(res, await handleTest(await readBody(req)));
           } catch (e) {
             sendJson(res, { ok: false, code: 'error', error: String((e && e.message) || e) });
           }
         }
-      });
+      }), 'jira-tasks: /jira/api/test');
     }
-  }
-};
+}
+
+export { Config, apply, inject, name };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-jira-tasks",
-  "version": "1.0.7",
-  "description": "JIRA open tasks panel for DeepSeek Harness (DSH): shows the current user's open/reopened issues below the composer, per-workspace project key, persistent profile bundle.",
+  "version": "1.1.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.",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -40,7 +40,10 @@
       "platform": "web",
       "inject": [
         "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-workspace",
         "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-plugin-manager",
         "@deepseek-ai/dsh-api-remotes"
       ]
     }