前言¶
在 DeepSeek Harness（DSH）裏做需求跟蹤或排障時，模型往往需要讀 Issue、改狀態、加評論，而不是隻在對話裏複述工單號。若每次靠人工打開 Linear 網頁再複製粘貼，智能體鏈路會斷在「人肉中轉」上。社區插件 @kb1slnlabs/dsh-linear（倉庫 KB1SLN-Labs/dsh-linear）的做法是：以 Cordis 插件形式向 DSH 註冊一組面向模型的 linear_* 工具，統一走 Linear 官方 GraphQL 端點 https://api.linear.app/graphql，用個人 API Key 鑑權。當前獨立實現版本爲 0.2.5（npm 包名 @kb1slnlabs/dsh-linear，許可證 MIT）；README 明確說明 0.2.x 不包含任何 MCP——不託管 MCP 服務、也不連接 mcp.linear.app（早期 0.1.0 曾帶 hosted MCP bridge，已在 0.2.x 移除）。維護者爲 KB1SLN-Labs；在社區目錄 SkillHub 中分類爲「聯網工具」，與 DeepSeek / 幻方無官方從屬關係，目錄站點是 DSH「一切皆插件」生態的獨立索引。
這是什麼¶
dsh-linear 是一個 Cordis function/namespace 插件（export { name, inject, apply }，無 default export），通過 ctx.tools.register 註冊工具。對外只有 一套工具面：26 個手寫工具，前綴均爲 linear_*。其中 25 個是對 Linear GraphQL 能力的固定子集（Issue、評論、關聯、團隊、狀態、標籤、項目、週期、用戶等）；第 26 個 linear_graphql 作爲逃生口，可把任意 query/mutation 原文轉發到同一 GraphQL 端點。工具集不會自動擴展：附件、Webhook、批量操作等不在表內能力中，超出部分只能依賴 linear_graphql 且受 API Key 權限約束。
核心功能¶
工具一覽（按 README 表）¶
Issue 與評論：linear_issue_list / linear_issue_get / linear_issue_create / linear_issue_update / linear_issue_archive / linear_issue_unarchive；linear_comment_list / linear_comment_add / linear_comment_update / linear_comment_delete（刪除爲破壞性操作）。
關聯與元數據：linear_relation_add（支持 related、blockedBy、blocks、parent、child、duplicate、similar 等類型）；linear_team_list / linear_team_get；linear_state_list；linear_label_list / linear_label_get / linear_label_create；linear_project_list / linear_project_get / linear_project_create / linear_project_update；linear_cycle_list / linear_cycle_get；linear_user_list / linear_user_get。
逃生口：linear_graphql 接收必填 query（GraphQL 文檔）與可選 variables（對象），結果以 { "data": … } 形式 JSON 字符串化返回，不做字段裁剪；mutation 會真實寫入，無只讀模式或 dry-run。
分頁與列表行爲¶
八個列表類工具均支持游標分頁：傳入上一頁 pageInfo.endCursor 作爲 after，返回 pageInfo { hasNextPage, endCursor }。帶 limit 的工具默認 20、上限 50；linear_team_list 固定每頁 100 且無 limit 參數；linear_state_list 與 linear_label_list 僅通過 after 分頁。
安裝與啓用¶
DSH Desktop（README 推薦路徑）¶
- 在 DSH Desktop 中選擇 Plugins > Add plugin，粘貼 release 資源 URL 並安裝、啓用插件。
- 按下一節配置 Linear 個人 API Key（勿把 Key 粘貼進對話）。
- 完全退出 DSH Desktop（含托盤進程）後重新打開，新開一輪對話再調用工具。
安裝用的 0.2.5 固定包地址如下：
https://github.com/KB1SLN-Labs/dsh-linear/releases/download/v0.2.5/kb1slnlabs-dsh-linear.tgz
Windows 上也可通過 Desktop 內置 CLI 寫入 desktop profile（README 給出已驗證路徑，勿依賴 PATH 上可能屬於其他安裝的 dsh）：
& "$env:LOCALAPPDATA\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add https://github.com/KB1SLN-Labs/dsh-linear/releases/download/v0.2.5/kb1slnlabs-dsh-linear.tgz
CLI 與 web profile¶
README 列出四條 web profile 安裝路線；Desktop 與 web 是獨立 profile，裝在一側不會自動出現在另一側。web 側示例（摘自 README）：
# 1. 本地 link（絕對路徑）
dsh plugin --profile web add link:<absolute-path-to-this-directory>
# 2. GitHub 默認分支（未 pin 版本）
dsh plugin --profile web add github:KB1SLN-Labs/dsh-linear
# 3. npm pin 0.2.4
dsh plugin --profile web add @kb1slnlabs/dsh-linear@0.2.4
# 4. 下載 v0.2.5 tarball 後本地 file 安裝
dsh plugin --profile web add file:./kb1slnlabs-dsh-linear.tgz
需要可復現安裝時，README 建議優先 route 4（v0.2.5 的 kb1slnlabs-dsh-linear.tgz），而非跟隨默認分支的 github: 路由。
配置¶
插件配置對象僅一項：apiKey（字符串，默認空）。Linear Key 按固定優先級解析，首個非空來源生效：
- patch 行裏的插件配置
apiKey（非空時） - 環境變量
LINEAR_API_KEY（插件進程可見） - 文件
~/.config/linear/api-key（內容僅爲 Key，trim 後使用）
三者皆空時，任意工具返回 { "error": "Linear API key not configured: …" } 而非拋異常。請求頭爲 Authorization: <key>，不是 Bearer。倉庫自帶的 cordis.patch.yml 插入插件時不寫 config，依賴 LINEAR_API_KEY 或 key 文件。
若在 Desktop 已運行後才設置環境變量，已啓動進程可能讀不到；README 建議完全退出後重啓，或改用 apiKey / key 文件。Windows 可用 Notepad 創建 key 文件；macOS 上 README 提供 zsh 腳本寫入 ~/.config/linear/api-key（不覆蓋已有文件）。
典型用法¶
配置完成並新開對話後，可用自然語言讓模型調用工具。README 給出的只讀自檢示例：
Use linear_issue_get to read TEAM-123 and report its title and status.
將 TEAM-123 換成你有權限查看的 Issue 標識（如 APT-123）。若標題與狀態正確返回，說明插件已加載且 Key 已解析。
列表類查詢可讓模型使用 linear_issue_list，按 team key、狀態名或全文搜索過濾，並用 after 翻頁。超出 25 個封裝工具的能力時，可說明需通過 linear_graphql 提交具體 GraphQL 文檔（及 variables），權限與風險與 Key 在 Linear 中的範圍一致。
適用場景與注意¶
適合：已在團隊中使用 Linear 做 Issue 跟蹤，希望在 DSH 對話裏讓模型查單、改狀態、寫評論、維護項目/標籤/週期元數據，且接受「固定 25 工具 + GraphQL 逃生口」的邊界。
不適合或需知：當前包沒有 MCP；SkillHub 簡介若仍寫「hosted MCP bridge」，應以 GitHub README 0.2.x 說明爲準。25 個命名工具不覆蓋附件、文檔搜索、Webhook、用戶管理等；linear_comment_delete 等操作不可逆。插件以 當前 DSH 進程的身份與網絡權限運行，API Key 等同於你在 Linear 中的操作權限；安裝前請閱讀 源碼與 LICENSE，勿在聊天、截圖或日誌中泄露 Key。
0.2.5 需要完整 DSH host；README 註明 0.2.4 更新 @deepseek-ai/schemastery 以避免與 Ponytail 的 schema 衝突，0.2.5 主要調整 Cordis peer 爲 optional。離線測試以 mock 爲主（npm test → node test.js），在設置 LINEAR_API_KEY 時會做 live schema check。
結尾¶
dsh-linear 把 Linear 工單操作收斂爲 DSH 內可註冊的 GraphQL 工具面，避免在 0.2.x 裏再繞 MCP 一層；安裝以 v0.2.5 release tarball 或 README 列出的 CLI 路由爲準，Key 三選一配置即可開工。
