📦 @goodandready/dsh-issue-reporter

⚡ 概览与核心定位

在 DeepSeek Harness 中进行自动化任务或开发时，用户经常会遇到已安装插件的异常。传统情况下提交 Bug 报告既繁琐又容易泄露机密：用户需要手动查找目标仓库，组织复现步骤，并极易无意泄露 API Key、内网地址或本地隐私路径。

@goodandready/dsh-issue-reporter 实现了从发现插件故障到向上游提交高质量规范报告的自动化闭环：

• 运行时插件探测：自动读取当前 DSH 组合，提取具备公开 GitHub 仓库的插件。
• 双列表智能分组：将原生 @deepseek-ai/ 核心插件与第三方生态插件归类为两个独立折叠面板。
• 隐私脱敏与安全边界：自动过滤并脱敏 API Token、凭据参数、绝对文件路径与邮件地址。
• 重复 Issue 实时检索：自动检索目标仓库现有 Issue，防止重复提单。
• 截图附件安全上传：通过官方 GitHub CLI (gh issue create --attach) 支持最多 5 张截图上传，并在完成后自动清理临时目录。
• 严格的用户确认控制：在执行任何 GitHub 写入操作前，均需用户亲自预览脱敏内容并勾选确认 (confirm: true)。

🏗️ 架构设计

graph LR
  A[DSH 插件清单] --> B[lib/index.js]
  B --> C[lib/domain.js<br/>校验、分组、脱敏]
  B --> D[lib/github.js<br/>OAuth 与 REST 客户端]
  B --> E[lib/attachments.js<br/>有上限的截图上传]
  C --> F[lib/client.js<br/>设置卡片]
  F --> G[脱敏预览与重复候选]
  G --> H{明确确认}
  H -->|无截图| I[GitHub REST issue API]
  H -->|带截图| J[gh issue create --attach]
  D --> K[DSH Credentials]

✨ 核心功能

1. 插件目录与独立分组

插件在加载时自动检查当前 DSH 运行环境中的所有插件。自动过滤无公开 GitHub 仓库的内部包，将可用目标整理为两组：

• 原生 DSH 插件：包名以 @deepseek-ai/ 开头的核心组件。
• 第三方生态插件：所有其他由社区或第三方开发的扩展。

点击任意支持插件的整行即可快速展开报告编辑器。

2. GitHub OAuth Device Flow 授权

采用 GitHub 官方标准设备码流（Device Flow），支持一键授权：

• 点击“使用 GitHub 登录”，系统提供 8 位验证码并引导用户在 GitHub 验证页面批准。
• 申请 repo 权限以支持创建 Issue 及读取现有 Issue 进行重复比对。
• OAuth Token 安全托管于 DSH Credentials（tokenEnv: GITHUB_ISSUE_REPORTER_TOKEN），绝不硬编码。
• 提供“退出登录”按钮，一键从凭据中心吊销并支持切换其他账号。

3. 报告编辑器与隐私边界

表单规范化采集问题标题、实际表现、复现步骤、期望结果及环境说明。后端在生成草稿时自动对敏感信息（API Token、密码、私有路径如 /home/...、邮箱）进行脱敏遮蔽，并在界面列出脱敏项摘要。

未登录状态下，支持一键生成带预填参数的 GitHub Issue 网页链接供用户手动提交。

5. 自主 Agent 报告工具 (report_issue)

在 Cordis ctx.tools 中注册官方工具，允许自主编程 Agent 与任务编排器在插件发生异常时自动提炼并起草规范的 Issue。

6. AI 润色与复现步骤生成器

通过 POST /dsh-issue-reporter/ai/optimize 与 ctx.llm 联动，一键将零散的报错描述转化为清晰专业的复现步骤与精准标题。

7. 实时会话日志与片段选择器

通过 GET /dsh-issue-reporter/logs 检索最近的宿主会话日志，经过自动脱敏后支持勾选插入到诊断报告中。

8. Issue 追踪器与状态同步

“我的报告”标签页记录提交记录并支持批量刷新 (POST /dsh-issue-reporter/issues/batch-status)，实时展示 open/closed 状态与评论数。

9. 智能标签推荐与组件识别

通过 POST /dsh-issue-reporter/labels 查询远端仓库可用标签，并智能推荐匹配分类 (bug, ui, performance, auth)。

10. 设置卡片一键更新

遵循 DSH 规范的原生 npm 更新机制：自动检查版本并在设置卡片中提供一键更新按钮，支持同一来源及回环地址安全保护。

4. 重复 Issue 智能检索

在提交前，插件根据标题和正文关键词向目标仓库发起只读检索，按相关度推荐前 5 个最相似的候选 Issue，避免重复提单干扰开源项目维护者。

5. 截图附件安全上传

支持上传最多 5 张图片（PNG、JPG、GIF、WebP；单张上限 8 MiB，总计上限 20 MiB）：

• 截图在用户点击确认前仅保存在浏览器内存中。
• 确认后通过 DSH 主机上的官方 gh issue create --attach 在临时隔离目录完成上传，命令退出时在 finally 块中立即销毁临时文件。
• 纯文本报告则直接通过 GitHub REST API 快速创建。

6. 剪贴板粘贴 (Ctrl+V) 与拖放支持 (v0.1.1)

支持直接从系统剪贴板粘贴截图（使用截图工具后按 Ctrl+V），或将图片拖放到交互式拖放区中，带有缩略图卡片与大小提示。

7. 自动化环境诊断与故障快速反馈 (v0.1.1)

自动收集已脱敏的运行时环境信息（Node.js、操作系统、架构与版本）。发生运行时崩溃的插件提供一键快速反馈功能并预填捕获的堆栈。

8. 标签页导航与即时搜索 (v0.1.1)

采用 dsh-clinebot 统一设计系统，提供清晰的标签页（插件目录、问题编辑器、已提交报告、授权设置）以及针对已安装插件的实时搜索过滤功能。

9. Issue 生命周期跟踪 (v0.1.1)

“我的报告”标签页保留已提交 issue 的本地记录，并支持一键刷新当前状态（开启 / 已关闭）。

10. 多代码平台支持 (Gitea / Forgejo) (v0.1.1)

除 GitHub 外，插件还能识别本地与自建的 Gitea/Forgejo 仓库，并支持通过 Gitea REST API 创建 issue 和搜索重复项。

📦 安装指南

安装至 DeepSeek Harness Web 配置文件：

dsh plugin --profile web add @goodandready/dsh-issue-reporter

重启 DSH 实例，在左侧导航进入 设置 → 插件设置 → GitHub Issue Reporter。

⚙️ GitHub OAuth App 配置

1. 在 GitHub 个人设置进入 Developer settings → OAuth Apps 创建新应用。
2. 勾选 Enable Device Flow 选项。
3. 将生成的 Client ID 填入 DSH 的 settings.yaml 配置项 appClientId 中。
4. 打开 DSH 设置卡片，点击 Sign in with GitHub，完成设备绑定。

🔧 配置项 (settings.yaml)

# settings.yaml
dsh-issue-reporter:
  # 启用了 Device Flow 的 GitHub OAuth App 公开 Client ID
  appClientId: "YOUR_GITHUB_OAUTH_CLIENT_ID"
  # 存放 OAuth 令牌的 DSH Credentials 引用名称
  tokenEnv: "GITHUB_ISSUE_REPORTER_TOKEN"
  # GitHub REST API 地址 (默认 https://api.github.com)
  apiBaseUrl: "https://api.github.com"
  # 网络请求与 CLI 附件上传超时时间 (毫秒)
  timeoutMs: 30000
  # 主机上的 gh 命令行可执行文件路径
  ghPath: "gh"

| 参数 | 类型 | 默认值 | 说明 | |:---|:---|:---|:---| | appClientId | string | "" | 启用了 Device Flow 的公开 GitHub OAuth App Client ID | | tokenEnv | string | "GITHUB_ISSUE_REPORTER_TOKEN" | 保存 OAuth 凭据的 DSH Credentials 引用名 | | apiBaseUrl | string | "https://api.github.com" | GitHub REST API 基础端点 | | timeoutMs | number | 30000 | HTTP 请求与 CLI 执行的超时时间（毫秒） | | ghPath | string | "gh" | 主机上的 GitHub CLI (gh) 路径 |

🔌 HTTP API 路由

所有接口均受 DSH 身份校验及同源安全策略保护。

| 请求方法与路由 | 用途 | 外部写操作 | |:---|:---|:---| | GET /dsh-issue-reporter/status | 获取配置状态与已检测到的插件目录 | 否 | | POST /dsh-issue-reporter/device/start | 发起 Device Flow 并获取用户验证码 | 否 | | POST /dsh-issue-reporter/device/poll | 轮询授权结果并持久化凭据 | DSH Credentials | | POST /dsh-issue-reporter/device/logout | 退出登录并删除存储的凭据 | DSH Credentials | | POST /dsh-issue-reporter/draft | 生成脱敏后的报告草稿及脱敏摘要 | 否 | | POST /dsh-issue-reporter/duplicates | 搜索目标仓库潜在的重复 Issue | 否 (只读 GitHub) | | POST /dsh-issue-reporter/create | 提交已确认的 Issue (通过 REST 或 gh) | GitHub Issue 写入 |

🛠️ 限制与排错

| 异常现象 | 原因与解决方案 | |:---|:---| | GitHub sign-in is not configured | 请在 settings.yaml 中配置 appClientId。 | | 登录时提示 404 Not Found | 请求设备码需指向 github.com，而非 api.github.com。 | | Resource not accessible by integration | 当前授权账号没有该仓库的写权限，或缓存了旧 Token。请点击 Sign out 并重新登录。 | | 截图附件上传失败 | 确保 DSH 运行主机已安装 GitHub CLI (gh 2.99 或更高版本)。 | | 某个已安装插件没有报错操作 | 该插件的 package.json 中未配置有效的公开 GitHub 仓库地址。 |

🔒 安全规范

• 凭据隔离：OAuth Token 仅存于 DSH Credentials，绝不在 UI、URL、日志或 Issue 正文中明文暴露。
• 数据脱敏：自动过滤鉴权令牌、密码、内网地址、私有文件路径及邮箱。
• 临时文件生命周期：截图文件仅在临时目录暂存，gh 命令执行结束后立即物理删除。
• 明确确认保护：所有提交操作均需用户显式勾选确认，杜绝未经授权的隐式提交。

📄 许可证

MIT © GooDAnDReaDY