前言¶

用 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。