前言¶

用 DeepSeek Harness（DSH）做开发或运维协作时，Jira 往往还在浏览器另一个标签里：查工单要切换上下文，改状态、加评论又要再开一次 Jira。社区插件 dsh-jira（仓库 pimili-app/dsh-jira）把 Jira Cloud 工单嵌进 Harness Web：侧栏入口、多项目与状态筛选、详情与读写操作，API 令牌只留在宿主进程。下面介绍它是什么、怎么装、怎么用，以及安装前应注意的安全边界。

这是什么¶

dsh-jira 是 DSH 的仓外插件（npm 包名 dsh-jira-plugin，当前版本 0.1.0，MIT 许可证），由 pimili-app 维护，在 SkillHub 插件目录 中归类为「联网工具」。

插件在 Harness Web 中提供「Tickets Jira」视图：可在 Cordis patch 里配置可见项目（spaces），支持多项目、多状态筛选、全文搜索、工单详情，以及创建工单、状态流转、评论；右侧边栏另有同内容的标签页。实现上无需单独构建：index.js 在宿主侧承载 Jira REST 客户端、HTTP 路由与偏好；client.js 在浏览器侧注册侧栏图标、主面板与右侧标签。Jira API Token 不会下发到浏览器端。

核心功能¶

依据仓库 README，当前能力包括：

• 可见项目：通过 config.spaces 限制界面与 API 可访问的 Jira 项目键；未配置或空列表时，使用令牌可见的全部项目。
• 筛选与搜索：多选项目、多选状态（来自所选项目真实工作流）；全文搜索使用 Jira text ~ "…"，300 ms 防抖；指派过滤为「我的工单」（assignee = currentUser()）或「全部」。
• 读：列表（单次最多 100 条，超出返回 truncated）、单条详情（描述为文本、评论列表）、可用 transitions。
• 写：创建工单、按 Jira 提供的 transition 改状态、追加评论。
• 界面：左侧栏 Jira 图标打开主面板；右侧栏标签为同视图窄列布局，可放大为全屏。
• 偏好持久化：所选筛选写入包内 .settings.json，下次打开恢复。

HTTP API 前缀为 /jira/api（JSON），供界面使用；README 说明本版本没有面向模型的 tool，视图是唯一入口，但路由已为后续扩展预留。

已知限制：仅针对 Jira Cloud（REST v3、ADF）；Jira Server/Data Center 未测试。不支持附件、子任务或任意字段编辑。

安装与启用¶

前置条件¶

• Harness 版本 ≥ 0.2.0-rc.1（README 注明在 0.2.1-rc.3 上测试）；package.json 中 engines.dsh 为 >=0.2.0-rc.1 <0.3.0-0。
• 一个 Jira Cloud 站点与 API Token（在 Atlassian 账户安全页 创建）。
• 宿主可读的 dotenv 文件，默认路径 ~/.config/dsh-jira/jira.env：

JIRA_BASE=https://mon-site.atlassian.net
JIRA_EMAIL=moi@exemple.fr
JIRA_API_TOKEN=xxxxxxxxxxxxxxxxxxxxx

JIRA_BASE_URL 可作为 JIRA_BASE 的别名。同一键也可来自 cordis.patch.yml 的 config 或宿主进程环境变量；解析顺序为 config → 环境变量 → 文件。

安装命令¶

安装前，桌面版需完全退出 Electron 应用（CLI 在应用打开时会拒绝安装）；若使用应用内置 CLI，需通过菜单「Gérer la commande dsh」→ 安装启用。

# 桌面应用（desktop 配置）
dsh plugin --profile desktop add github:pimili-app/dsh-jira

# 命令行 / Web Harness（web 配置）
dsh plugin --profile web add github:pimili-app/dsh-jira

安装后检查 ~/.dsh/profiles/desktop/package.json（或对应 profile）：dsh.profile.bundles 中应包含 "dsh-jira-plugin"。若包只出现在 dependencies 而未进入 bundles，界面不会出现补丁，启动日志可能出现 patch: entry "jira" not found。

bundle 变更需要重启 Harness（或桌面应用）；cordis.patch.yml 在 web profile 上可热重载，但新增 bundle 后仍需重启，并刷新浏览器以重建 window.__DSH_BOOT__。

Cordis 配置¶

在 cordis.patch.yml 中插入条目（web profile 下 patch 可热重载）：

- insert:
    - id: jira
      name: 'dsh-jira-plugin'
      config:
        spaces: [ABC, OPS]
        envFile: ~/.config/dsh-jira/jira.env
        # baseUrl / email / apiToken：可覆盖，不建议在 patch 里写 apiToken

spaces 中未知项目键会被忽略并在宿主日志警告。API 在调用 Jira 前会拒绝不在 spaces 列表中的项目键。

卸载¶

dsh plugin --profile desktop remove dsh-jira-plugin
# 或 --profile web

然后重启应用。包内 .settings.json 可手动删除，无其他依赖。

典型用法¶

经过安装与 Jira 凭据配置后：

1. 点击侧栏 Jira 图标，打开主面板（或改用右侧边栏 Jira 标签）。
2. 用项目、状态、指派、搜索框缩小列表；点击某行进入详情，查看描述与评论，在 Jira 允许的 transitions 中改状态，或提交评论。
3. 使用「新建 ticket」：选择项目、该项目的可创建类型，填写摘要与描述。

本地开发时可链接目录（修改 package.json bundle 后仍需重启 web 服务）：

dsh plugin --profile web add link:~/dsh-plugins/dsh-jira
dsh --profile web

适用场景与注意¶

适合：已在 DSH Web 或桌面 Harness 中工作、日常依赖 Jira Cloud 做任务跟踪的团队或个人；希望减少浏览器与 Harness 之间切换、并在同一界面完成常见读写操作的使用者。

安全与权限：

• 插件以当前 DSH 宿主进程的权限运行；JIRA_API_TOKEN 与邮件、站点 URL 由宿主持有，浏览器侧仅获知 configured、baseUrl、email。
• 写操作校验 Origin；读响应不提供 CORS，第三方页面无法直接读 API 结果。
• 安装前应自行审阅 源码与 LICENSE，确认令牌文件权限与 spaces 范围符合组织策略。SkillHub 目录为社区站点，与 DeepSeek / 幻方无官方从属关系。

排错摘要（来自 README）：

结尾¶

dsh-jira 把 Jira Cloud 的常见读写在 Harness 内完成，并通过 spaces 与宿主侧凭据控制暴露面。更多信息见 SkillHub 目录页 与 GitHub 仓库 README。