dsh-jira-tasks 1.0.0 → 1.0.2

package/README.en.md

@@ -0,0 +1,134 @@
+# JIRA Open Tasks Panel (DeepSeek Harness Plugin)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[中文](README.md) · **English**
+
+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 read from credentials; the project key and JQL are **configured per workspace** and persisted.
+
+## Features
+
+- 📋 Panel shown below the composer in both new and active sessions (aligned with the input width in new sessions)
+- 👤 Defaults to the current user (`assignee = currentUser()`) with status `开启 / 重新开启` (Open / Reopened)
+- ⚙️ Project key and JQL are saved per workspace; unconfigured workspaces show "unconfigured"
+- 🔄 Auto-query on every new session, with a one-click refresh (⟳)
+- 🔗 Click an issue to open its JIRA detail in a new tab
+- 🎨 Uses DSH theme tokens; adapts to light / dark themes
+
+## Install
+
+Published to npm:
+
+```bash
+dsh plugin --profile desktop add dsh-jira-tasks
+```
+
+**Restart DSH** to activate.
+
+<details>
+<summary>Manual install (without npm)</summary>
+
+1. Copy the repo's `profile-package/` to `~/.dsh/profiles/desktop/packages/dsh-jira-tasks/`
+2. Edit `~/.dsh/profiles/desktop/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
+
+> 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>
+
+<details>
+<summary>Dynamic plugin (temporary, lost on restart)</summary>
+
+In a DSH session, use the Cordis tools: `cordis_define` (`kind: new`, `idPrefix: "jira"`, sources in `plugin/host.js` / `plugin/client.js`) → `cordis_run` to activate. Dynamic plugins live only in process memory and **disappear on restart** — for trial use only.
+</details>
+
+## Configuration
+
+### 1. JIRA base URL and token
+
+Write to `$DSH_HOME/.credentials.yaml` (recommended, hot-reloaded), or export environment variables before launching DSH:
+
+```yaml
+JIRA_BASE_URL: "http://jira.example.com/"
+JIRA_API_TOKEN: "<PAT or user:token>"
+```
+
+- Base URL aliases: `JIRA_BASE_URL` / `JIRA_URL`
+- Token aliases: `JIRA_API_TOKEN` / `JIRA_TOKEN`
+- Auth is auto-detected: tokens containing `:` use Basic, otherwise Bearer (JIRA PAT)
+
+### 2. Project key and JQL (per workspace)
+
+- Click **⚙** on the panel header to open settings (the form shows the target workspace)
+- **Project key**: e.g. `HCPFYH1` — saved and queried immediately; auto-loaded for new sessions in that workspace
+- **JQL**: leave empty for the default, or write a custom JQL where `{projectKey}` (or `{key}`) is replaced by the project key
+
+Default query:
+
+```jql
+project = "{projectKey}" AND status in ("开启", "重新开启") AND assignee = currentUser() ORDER BY updated DESC
+```
+
+> The status names follow the Chinese workflow (`开启`/`重新开启`). For English statuses (Open/Reopened), set a custom JQL in ⚙.
+
+## Uninstall
+
+```bash
+dsh plugin --profile desktop remove dsh-jira-tasks
+```
+
+## Troubleshooting
+
+<details>
+<summary>Panel shows "query failed"</summary>
+
+| Message | Fix |
+|---|---|
+| JIRA_BASE_URL not configured | Credentials missing — see "Configuration 1" above |
+| 401 … | Invalid token or wrong auth scheme; verify with `curl -H "Authorization: Bearer <token>" <base>/rest/api/2/myself` |
+| Cannot parse JIRA response | Network / proxy issue, curl produced no output |
+</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
+</details>
+
+## Architecture & Implementation Details
+
+<details>
+<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            │      │ credentials.resolve(JIRA_*)     │
+│ render: list / error / unconfigured        │      │ subprocess.spawn(curl …)        │
+│ localStorage per-workspace config          │      │   ↓ stdout JSON                 │
+└────────────────────────────────────────────┘      │ parse issues → {ok,issues}      │
+                                                    └────────────────────────────────┘
+```
+
+- **Host**: registers a `webServer` route `POST /jira/api/search`; credentials resolved via the `credentials` service (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).
+- **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".
+
+**Differences from the dynamic version**
+
+| Aspect | Dynamic plugin | Persistent install (this package) |
+|---|---|---|
+| Persistence | Lost on restart | Survives restart |
+| Client→Host | `host.call` / `harness.handle` | `webServer` route + `fetch` |
+| Client bundle | Injected per session | `/plugins/dsh-jira-tasks/client.js` |
+| Config / credentials | Same `localStorage` key, same `.credentials.yaml` | Identical |
+</details>
+
+## License
+
+MIT

package/README.md

@@ -1,37 +1,81 @@
-# dsh-jira-tasks
+# JIRA 开启任务面板（DeepSeek Harness 插件）
 
-JIRA 开启任务面板 —— DeepSeek Harness（DSH）持久化插件（profile bundle）。
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-在 DSH 会话**输入框下方**展示当前 JIRA 项目**指派给当前用户**的「开启 / 重新开启」任务列表。项目 Key 与 JQL **按工作区配置**并持久化，重启 DSH 不丢失。
+**中文** · [English](README.en.md)
+
+在 DSH 会话**输入框下方**展示当前 JIRA 项目**指派给当前用户**的「开启 / 重新开启」任务列表。JIRA 地址与令牌从凭据读取；项目 Key 与 JQL **按工作区配置**并持久化。
+
+## 功能
+
+- 📋 新会话与活跃会话的输入框下方均展示任务面板（新会话时与输入框等宽）
+
+<img width="1898" height="886" alt="image" src="https://github.com/user-attachments/assets/d14d0bd4-4f9f-4aa8-9af8-b8a02a2b7296" />
+<img width="1972" height="746" alt="image" src="https://github.com/user-attachments/assets/9f543e04-a5ad-4b86-85c8-baa2de26f44e" />
+
+- 👤 默认仅显示当前用户（`assignee = currentUser()`）的「开启 / 重新开启」任务
+- ⚙️ 项目 Key 与 JQL 按工作区保存；未配置的工作区显示"未配置"
+- 🔄 打开新会话自动查询，面板内支持一键刷新（⟳）
+- 🔗 任务可点击，在新标签页打开 JIRA 详情
+- 🎨 颜色使用 DSH 主题令牌，浅色 / 深色主题自适应
 
 ## 安装
 
+包已发布到 npm：
+
 ```bash
 dsh plugin --profile desktop add dsh-jira-tasks
-# 或手动安装：见仓库 README「注册方式二：正式安装」
 ```
 
-重启 DSH 后生效。
+**重启 DSH** 后生效。
+
+<details>
+<summary>手动安装（不使用 npm）</summary>
+
+1. 将仓库 `profile-package/` 复制为 `~/.dsh/profiles/desktop/packages/dsh-jira-tasks/`
+2. 编辑 `~/.dsh/profiles/desktop/package.json`：
+   - `dependencies` 增加：`"dsh-jira-tasks": "file:./packages/dsh-jira-tasks"`
+   - `dsh.profile.bundles` 追加：`"dsh-jira-tasks"`
+3. 在 profile 目录执行 `pnpm install`
+4. 重启 DSH
+
+> 注：`pnpm install` 会把包**复制**到 `node_modules/`（非符号链接），改动源码后需同步 `node_modules/dsh-jira-tasks` 或重跑 install。
+</details>
+
+<details>
+<summary>动态插件方式（临时，重启后消失）</summary>
+
+在 DSH 会话中用 Cordis 工具执行：`cordis_define`（`kind: new`，`idPrefix: "jira"`，源码见仓库 `plugin/host.js` / `plugin/client.js`）→ `cordis_run` 激活。动态插件只存在于进程内存，**重启后消失**，仅适合临时试用。
+</details>
 
 ## 配置
 
-1. **JIRA 地址与令牌**：写入 `$DSH_HOME/.credentials.yaml`（或导出环境变量）：
+### 1. JIRA 地址与令牌
 
-   ```yaml
-   JIRA_BASE_URL: "http://jira.example.com/"
-   JIRA_API_TOKEN: "<PAT 或 user:token>"
-   ```
+写入 `$DSH_HOME/.credentials.yaml`（推荐，热加载无需重启），或启动 DSH 前导出环境变量：
 
-2. **项目 Key / JQL**：点击面板 ⚙ 按工作区配置；JQL 留空使用默认查询：
+```yaml
+JIRA_BASE_URL: "http://jira.example.com/"
+JIRA_API_TOKEN: "<PAT 或 user:token>"
+```
 
-   ```jql
-   project = "{projectKey}" AND status in ("开启", "重新开启") AND assignee = currentUser() ORDER BY updated DESC
-   ```
+- 地址别名：`JIRA_BASE_URL` / `JIRA_URL`
+- 令牌别名：`JIRA_API_TOKEN` / `JIRA_TOKEN`
+- 认证自动识别：令牌含 `:` 用 Basic，否则用 Bearer（JIRA PAT）
 
-## 架构
+### 2. 项目 Key 与 JQL（按工作区）
 
-- **Host**：`webServer` 路由 `POST /jira/api/search`，凭据走 `credentials` 服务，查询经 `subprocess` + curl（认证头经 stdin `--config -` 传入）。
-- **Client**：`window.__ModuleLoader__.load({ id, factory })` web bundle，注册 `conversation.composer.dock`（活跃会话）与 `conversation.input.dock`（新会话，`order:99` 置于输入框下方、等宽）。
+- 点击面板标题右侧 **⚙** 打开设置（表单顶部提示当前配置归属的工作区）
+- **项目 Key**：如 `HCPFYH1`，保存后立即查询，该工作区后续新会话自动加载
+- **JQL**：留空使用默认查询；也可填写自定义 JQL，`{projectKey}`（或 `{key}`）会被替换为项目 Key
+
+默认查询：
+
+```jql
+project = "{projectKey}" AND status in ("开启", "重新开启") AND assignee = currentUser() ORDER BY updated DESC
+```
+
+> 状态名按中文工作流（"开启"/"重新开启"）配置；若 JIRA 用英文状态（Open/Reopened），在 ⚙ 中填写自定义 JQL 即可。
 
 ## 卸载
 
@@ -39,6 +83,56 @@ dsh plugin --profile desktop add dsh-jira-tasks
 dsh plugin --profile desktop remove dsh-jira-tasks
 ```
 
+## 常见问题
+
+<details>
+<summary>面板显示「查询失败」</summary>
+
+| 提示 | 处理 |
+|---|---|
+| 未配置环境变量 JIRA_BASE_URL | 凭据未写入，见上文「配置 1」 |
+| 401 … | 令牌无效或认证方式不对；先 `curl -H "Authorization: Bearer <token>" <base>/rest/api/2/myself` 验证 |
+| 无法解析 JIRA 响应 | 网络 / 代理问题，curl 无输出 |
+</details>
+
+<details>
+<summary>面板不显示</summary>
+
+- 确认已安装并**重启 DSH**；新会话面板位于输入框下方
+- 检查 DSH 启动日志中 profile 插件是否加载成功
+</details>
+
+## 架构与实现细节
+
+<details>
+<summary>点击展开</summary>
+
+```
+┌─────────── 浏览器（Client） ───────────┐      ┌──────────── Host ──────────────┐
+│ conversation.composer.dock（活跃会话）      │      │ webServer 路由 /jira/api/search │
+│ conversation.input.dock（新会话, order:99）│      │   ↓                            │
+│   ↓ 挂载时/刷新时 fetch POST               │      │ credentials.resolve(JIRA_*)     │
+│ 渲染：任务列表 / 错误 / 未配置               │      │ subprocess.spawn(curl …)        │
+│ localStorage 按工作区存取配置                │      │   ↓ stdout JSON                 │
+└────────────────────────────────────────────┘      │ 解析 issues → 返回 {ok,issues}  │
+                                                    └────────────────────────────────┘
+```
+
+- **Host**：注册 `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`（活跃会话）与 `conversation.input.dock`（新会话，flex `order: 99` 置于输入框下方、与输入框等宽）。
+- **为什么不用 `shell` 服务**：`shell` 会套 `sandbox-exec`，部分 macOS 上不可用（`sandbox_apply: Operation not permitted`）；`subprocess` 是原始进程缝，无此问题。
+- **新会话显示**：DSH 壳在 hero（空白会话）阶段不渲染 `composer.dock`，故额外注册 `input.dock`，并用「会话是否已有消息」去重，避免双份面板。
+
+**与动态插件版的差异**
+
+| 维度 | 动态插件 | 正式安装（本包） |
+|---|---|---|
+| 持久性 | 重启丢失 | 重启保留 |
+| Client→Host 通信 | `host.call` / `harness.handle` | `webServer` 路由 + `fetch` |
+| 客户端 bundle | 会话内注入 | `/plugins/dsh-jira-tasks/client.js` |
+| 配置 / 凭据 | 同一 `localStorage` 键、同一 `.credentials.yaml` | 完全相同 |
+</details>
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-jira-tasks",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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.",
   "type": "module",
   "main": "lib/index.js",
@@ -13,7 +13,8 @@
     "lib",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "README.en.md"
   ],
   "keywords": [
     "dsh",
@@ -39,4 +40,4 @@
       ]
     }
   }
-}
+}