liu3734/jira-tasks-dsh-plugin#profile-package

中文 · English

在 DSH 会话输入框下方展示当前 JIRA 项目指派给当前用户的「开启 / 重新开启」任务列表。JIRA 地址与令牌在设置 → 插件 → JIRA 中配置（JIRA_BASE_URL / JIRA_API_TOKEN 作为回退）；项目 Key 与 JQL 按工作区配置并持久化。

功能

• 📋 新会话与活跃会话的输入框下方均展示任务面板（新会话时与输入框等宽）

• 👤 默认仅显示当前用户（assignee = currentUser()）的「开启 / 重新开启」任务
• ⚙️ 设置 → 插件 → JIRA 配置 JIRA 地址与访问令牌（令牌写入凭据存储，不回传前端）
• 🟢 设置卡片自动探测连接并显示状态灯：绿=可用、红=不可用、灰=未配置；点「测试连接」可用未保存的草稿值即时验证
• ⚙️ 项目 Key 与 JQL 按工作区保存；未配置的工作区显示"未配置"
• 🔄 打开新会话自动查询，面板内支持一键刷新（⟳）
• 🧭 点击标题可收起 / 展开面板；标题徽标显示查询命中的任务总数（列表最多展示 50 条，按更新时间倒序）
• 🏷️ 每条任务附状态徽章（按状态分类着色：新建 / 进行中 / 其他）、优先级与类型标签
• 🔗 任务可点击，在新标签页打开 JIRA 详情
• 🎨 颜色使用 DSH 主题令牌，浅色 / 深色主题自适应

安装

包已发布到公共 npm（dsh-jira-tasks）；仓库的发布工作流同时把同一版本发布到 GitHub Packages（作用域包名 @liu3734/dsh-jira-tasks）。从 npm 安装（推荐）：

dsh plugin --profile web add dsh-jira-tasks

重启 DSH 后生效。

若改用 GitHub Packages 源：先在 profile 的 .npmrc 配置 @liu3734:registry=https://npm.pkg.github.com/ 及读取令牌，再执行 dsh plugin --profile web add @liu3734/dsh-jira-tasks。

1. 将仓库 profile-package/ 复制为 ~/.dsh/profiles/web/packages/dsh-jira-tasks/
2. 编辑 ~/.dsh/profiles/web/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。

在 DSH 会话中用 Cordis 工具执行：cordis_define（kind: new，idPrefix: "jira"，源码见仓库 plugin/host.js / plugin/client.js）→ cordis_run 激活。动态插件只存在于进程内存，重启后消失，仅适合临时试用。

配置

1. JIRA 地址与令牌

打开 设置 → 插件 → 插件配置 → JIRA，填写：

• JIRA 地址：如 http://jira.example.com/（存入用户设置文档，可在界面回读）
• 访问令牌 / PAT：写入凭据存储（$DSH_HOME/.credentials.yaml），前端只显示"已配置"，不回传令牌本身

留空并保存会保持已有令牌不变；地址留空并保存则清除设置项，回退到环境变量。认证自动识别：令牌含 : 用 Basic，否则用 Bearer（JIRA PAT）。

连接测试

卡片底部有连接状态灯与 测试连接 按钮：

• 打开卡片时会自动探测一次（请求 JIRA /rest/api/2/myself），保存后也会自动重测
• 绿 = 地址与令牌可用（并显示当前登录用户）；红 = 不可用（显示 JIRA 返回的原因，如 401 认证失败）；灰 = 地址或令牌未配置
• 点 测试连接 会用当前输入框里的内容（未保存也可）立即测试，方便改完再存

以下环境变量 / 凭据仍作为回退（设置页未配置时生效，兼容旧部署），热加载无需重启：

JIRA_BASE_URL: "http://jira.example.com/"
JIRA_API_TOKEN: "<PAT 或 user:token>"

• 地址别名：JIRA_BASE_URL / JIRA_URL
• 令牌别名：JIRA_API_TOKEN / JIRA_TOKEN

2. 项目 Key 与 JQL（按工作区）

• 点击面板标题右侧 ⚙ 打开设置（表单顶部提示当前配置归属的工作区）
• 项目 Key：如 HCPFYH1，保存后立即查询，该工作区后续新会话自动加载
• JQL：留空使用默认查询；也可填写自定义 JQL，{projectKey}（或 {key}）会被替换为项目 Key

默认查询：

project = "{projectKey}" AND status in ("开启", "重新开启") AND assignee = currentUser() ORDER BY updated DESC

状态名按中文工作流（"开启"/"重新开启"）配置；若 JIRA 用英文状态（Open/Reopened），在 ⚙ 中填写自定义 JQL 即可。

卸载

dsh plugin --profile web remove dsh-jira-tasks

常见问题

面板中的提示位于「查询失败：」之后，与下列文案对应：

提示	处理
未设置项目 Key	面板未配置项目，点标题右侧 ⚙ 填写项目 Key
未配置 JIRA 地址（设置 → 插件 → JIRA，或环境变量 JIRA_BASE_URL）	地址未写入，见上文「配置 1」
未配置 JIRA 令牌（设置 → 插件 → JIRA，或环境变量 JIRA_API_TOKEN）	令牌未写入，见上文「配置 1」
401 …	令牌无效或认证方式不对；先 curl -H "Authorization: Bearer <token>" <base>/rest/api/2/myself 验证
无法解析 JIRA 响应：…	网络 / 代理问题，curl 无输出

• 确认已安装并重启 DSH；新会话面板位于输入框下方
• 检查 DSH 启动日志中 profile 插件是否加载成功

架构与实现细节

┌────────────────────────────────────────┐   ┌────────────────────────────────────┐
│ 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) │
│ 渲染：任务列表 / 错误 / 未配置          │   │ subprocess.spawn(curl …)            │
│ localStorage 按工作区存取项目 Key/JQL   │   │ ↓ stdout JSON                       │
│ settings.plugin.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 写入凭据存储。
• 为什么不用 shell 服务：shell 会套 sandbox-exec，部分 macOS 上不可用（sandbox_apply: Operation not permitted）；subprocess 是原始进程缝，无此问题。
• 新会话显示：DSH 壳在 hero（空白会话）阶段不渲染 composer.dock，故额外注册 input.dock，并用「会话是否已有消息」去重（新版 DSH 依据 SessionSnapshot.blank），避免双份面板。

与动态插件版的差异

维度	动态插件	正式安装（本包）
持久性	重启丢失	重启保留
Client→Host 通信	host.call / harness.handle	webServer 路由 + fetch
客户端 bundle	会话内注入	/plugins/dsh-jira-tasks/client.js
配置 / 凭据	仅环境变量 / .credentials.yaml（无设置页卡片）	设置页卡片 + 同一 .credentials.yaml 回退

License

MIT