前言¶
在 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 三选一配置即可开工。
