# @goodandready/dsh-github-ops 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-github-ops/

版本：0\.6\.19
npm 元数据更新时间：2026-11-12T12:55:37.708Z
中文译文更新时间：2026-11-16T19:19:24.425Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-github-ops
原文对照：https://npmcn.com/package/%40goodandready/dsh-github-ops/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-github-ops#readme
源码仓库：https://github.com/GooDAnDReaDY/dsh-github-ops

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：873 kB，57 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-tools ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-settings ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/dsh-credentials ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1
- 首次发布：2026-09-20T16:31:45.739Z
- 最新版本发布：2026-11-12T12:55:37.470Z
- 近 30 天下载量：3565（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 41 个）

## 中文简介

GitHub操作DeepSeek Harness:发布,标记,一个被守护的通用API通关,工作流程运行,秘密和已消毒的镜像出版物.

## 安装

```sh
npm install @goodandready/dsh-github-ops
```

也可以使用：`pnpm add @goodandready/dsh-github-ops`、`yarn add @goodandready/dsh-github-ops`、`bun add @goodandready/dsh-github-ops`

## README

# 📦 @goodandready/dsh-github-ops

### 面向 DeepSeek Harness 的高级 GitHub 操作、发布、CI 运行、密钥与净化镜像套件

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-github-ops.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-github-ops) [![license](https://img.shields.io/github/license/GooDAnDReaDY/dsh-github-ops.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-github-ops/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者全部项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-github-ops/README.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-github-ops/README.zh.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-github-ops/README.ru.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

面向 [DeepSeek Harness](https://github.com/topics/dsh-plugin) 的 GitHub 操作插件：发布（release）、 标签（tag）、受保护的通用 API 直通、工作流运行、密钥，以及经过净化的镜像发布。

插件的存在理由：发布流水线需要现有 GitHub 插件没有提供的能力——首先是 release 和 tag， 其次是只发布**产品**、而不是整个开发树的 GitHub 镜像。

> **状态：开发中，尚未发布。** 只有在插件具备完整工具集之后才会公开发布（见[路线图](https://npmcn.com/package/%40goodandready/dsh-github-ops/#readme-%E8%B7%AF%E7%BA%BF%E5%9B%BE)）。

## 安装

```bash
dsh plugin --profile web add @goodandready/dsh-github-ops
```

需要在 DSH 凭据服务中保存 GitHub token。默认凭据名为 `GITHUB_TOKEN`，插件设置里只保存 这个**名称**。

## 设置

| 设置 | 默认值 | 含义 |
| --- | --- | --- |
| `tokenEnv` | `GITHUB_TOKEN` | 依次在 DSH 凭据、环境变量与 `gh` CLI 中查找该名称；取值本身不写入设置。 |
| `tokenSource` | `auto` | 访问来源：`auto` 依次尝试 DSH 凭据、环境变量与 `gh` CLI 会话；可固定为 `credentials`、`env` 或 `gh`。 |
| `defaultRepository` | 空 | 未传 `repository` 时使用的 `owner/repo`。 |
| `baseUrl` | `https://api.github.com` | API 地址，GitHub Enterprise 时修改。 |
| `timeoutMs` | `30000` | 单次请求超时。 |
| `maxRetries` | `2` | 读取失败时的重试次数（写入不重试）。 |
| `reviewRulesJson` | 空 | 以 JSON 覆盖评审规则：`sensitivePaths`、`sensitiveSeverity`、`attentionPaths`、`migrationPaths`、`testsRequired`、`sourcePatterns`、`testPatterns`、`largeDiffLines`。 |
| `reviewJobTimeoutMs` | `120000` | 后台评审任务的最长运行时间。 |
| `cacheTtlMs` | `60000` | 读取结果在内存缓存中的存活时间。写入始终访问网络并清空缓存；设为 `0` 关闭缓存。 |
| `interceptLinks` | `false` | 允许会话中点击的 `github.com` 链接记录仓库，供 Source Control 标签页与侧边栏面板跟随。无论如何链接都会在浏览器中打开。 |
| `guidance` | `true` | 在系统提示中加入一段关于本插件的简短说明。 |
| `guidanceText` | _(空)_ | 用自定义文本替换该说明。 |
| `oauthClientId` | 公开的 `gh` CLI 应用 | `gh_auth_login` 使用的 OAuth 应用。 |
| `oauthScope` | `repo workflow gist read:org` | `gh_auth_login` 请求的权限范围。 |
| `oauthClientSecretRef` | _(空)_ | 可选的、保存 OAuth 客户端密钥的凭据名称。 |
| `accessFile` | `$DSH_HOME/github-ops-auth.json` | `gh_auth_login` 保存登录信息的位置（权限 `0600`）。 |

## 工具

### Release

| 工具 | 作用 |
| --- | --- |
| `gh_release_list` | 按时间倒序列出 release（只读）。 |
| `gh_release_view` | 按 tag 读取单个 release：标记、说明、附件（只读）。 |
| `gh_release_create` | 为 tag 创建 release，可指定 commit。 |
| `gh_release_edit` | 修改标题、说明、draft/prerelease，以及**哪个 release 是 latest**。 |
| `gh_release_delete` | 删除 release（需要 `confirm: true`）。 |
| `gh_release_asset_list` | 列出 release 关联的资源附件（大小与下载量）（只读）。 |
| `gh_release_asset_upload` | 上传文件附件（.tgz、二进制等）至已有 release（需要 `confirm: true`）。 |
| `gh_release_asset_delete` | 按资源 ID 删除 release 附件（需要 `confirm: true`）。 |
| `gh_release_notes_generate` | 根据 PR 与提交自动生成 release notes（只读）。 |

`gh_release_edit` 配合 `makeLatest: true` 是保持仓库徽章指向当前版本的关键一步：之后再创建 旧版本的 release 会把 “Latest” 移回旧版本。

### Tag

| 工具 | 作用 |
| --- | --- |
| `gh_tag_list` | 列出 tag 及其 commit SHA（只读）。 |
| `gh_tag_create` | 创建 tag；带 `message` 时创建附带注释的 tag。 |
| `gh_tag_delete` | 删除 tag（需要 `confirm: true`）。 |

### 通用 API

`gh_api` 用于覆盖类型化工具未涉及的接口（refs、rulesets、organization、gist）。读取无需确认； `POST`/`PATCH`/`PUT`/`DELETE` 需要 `confirm: true`。删除仓库、转移仓库、删除组织会被直接拒绝—— 这类操作无法靠一次确认变得安全。

### Issue 与 Pull Request

| 工具 | 作用 |
| --- | --- |
| `gh_issue` | 列出或读取 issue（`action: list/get/comments`）；PR 以 `kind: "pr"` 返回。 |
| `issue_open`、`issue_comment`、`issue_close` | 创建 issue、评论、关闭（可带原因）。 |
| `gh_search` | 使用 GitHub 搜索语法检索 issue 与 PR（独立配额）。 |
| `pr_create`、`pr_update` | 从 head 分支创建 PR；修改标题、正文、状态或目标分支。 |
| `pr_merge` | 合并 PR（merge/squash/rebase），可选择删除 head 分支。 |
| `gh_review` | 一个完整评审包：元数据、涉及范围、限量 diff、评论、CI 汇总与确定性发现（密钥、迁移、CI 配置、改源码未改测试、超大 diff）。 |
| `review_post` | 发布评审：一条汇总评论，或按行内联评论。 |
| `gh_checks` | 某个提交的 check runs、旧式状态与统一结论。 |
| `ci_run` | 对 PR 做一次性评审并给出基于规则的结论。 |
| `pr_review_threads` | 列出代码审查讨论主题及其评论与解决状态（只读）。 |
| `pr_thread_reply` | 按 threadId 或 commentId 回复审查主题评论（需要 `confirm: true`）。 |
| `pr_thread_resolve` | 标记代码审查主题为已解决或重新打开（需要 `confirm: true`）。 |

### 镜像发布

| 工具 | 作用 |
| --- | --- |
| `gh_mirror_check` | 只读计划：哪些产品文件会进入镜像、多少文件会留在原地、以及为何必须拒绝发布。 |
| `gh_mirror_publish` | 发布净化后的树：在镜像分支之上一个提交，fast-forward，**绝不 force**。`dryRun: true` 仅预览；写入需要 `confirm: true`。 |

白名单取自包清单自身的 `files`，加上 `.gitignore`、`LICENSE`、README 三件套、 `CHANGELOG.md` 和 `cordis.patch.yml`。即使清单里列了 `docs/**` 与代理说明文件也会被禁止； 像 `scripts/**` 这种随包发布的工具则会进入镜像，因为它属于包内容。

### 工作流运行

| 工具 | 作用 |
| --- | --- |
| `gh_run_list`、`gh_run_view` | 列出运行（可按分支、工作流、状态过滤）与读取单个运行。 |
| `gh_run_jobs` | 作业及其步骤，并单独列出失败的步骤——通常足以定位失败原因。 |
| `gh_run_rerun`、`gh_run_cancel` | 重跑全部或仅失败作业；取消进行中的运行（需要 `confirm: true`）。 |
| `gh_run_logs` | 返回日志压缩包地址：GitHub 以 302 指向 zip，不会把二进制拉进对话。 |
| `gh_run_dispatch` | 触发附带输入参数的 workflow\_dispatch 工作流（需要 `confirm: true`）。 |
| `gh_run_log_summary` | 提取失败步骤的精简日志摘要（去除 ANSI 代码并脱敏令牌）（只读）。 |

### 仓库设置

| 工具 | 作用 |
| --- | --- |
| `gh_variable_list/set/delete` | Actions 变量，仓库级或按环境。 |
| `gh_secret_list/set/delete` | Actions 密钥。写入使用 sealed-box 加密，需要可选的 `tweetnacl`；缺失时会明确说明需要安装什么，而不是写入无效值。 |
| `gh_ruleset_list/view/apply/delete` | 仓库 ruleset：读取、创建、更新、删除。 |
| `gh_branch_protection_get/set/delete` | 经典分支保护：必需评审、状态检查、管理员强制、force push 与删除开关。 |

### 插件设置卡片

设置在插件自己的页面上（插件列表座位 `plugins.item`，并保留行座位与旧版 `settings.plugin.item`）：凭据名称、默认仓库、API 地址、请求超时。卡片会检查设置快照的 **状态**，在设置服务不可用时明确说明，而不是画出一个看似可用的表单。

### 报告

| 工具 | 作用 |
| --- | --- |
| `gh_repo_report` | 一次调用给出仓库全貌：概览、最新 Release、打开的 Issue、近期提交、主要贡献者。某一部分失败只影响该部分，不会让整份报告失败。 |
| `gh_weekly_digest` | 时间窗口内发生了什么：Release、新 Issue、已合并或关闭的 PR、提交。PR 单独统计，不会被当作“新 Issue”。 |
| `gh_notifications` | 账号的关注队列——提及、评审请求、指派——按原因分组。 |
| `gh_repo_health` | 透明的维护评分：五个加权维度，每项都带证据，另有风险与具体下一步。它是基于公开信号的启发式判断，不是安全审计。 |
| `gh_compare` | 两个仓库并排比较，给出星标、Fork、打开 Issue 的数值差异。 |
| `gh_contributors` | 按提交数排列的主要贡献者。 |
| `gh_user_repos` | 用户或组织的仓库，按星标排序。 |
| `gh_trending` | 近期创建的热门仓库，可按语言筛选（消耗搜索配额）。 |
| `gh_commits` | 近期提交，可按时间与分支过滤。 |
| `gh_help` | 本插件的全部工具，按领域分组，由注册表生成，不会过期。 |

### 文件与分支

无需本地检出即可发布内容：提交按 git 的方式组装。

| 工具 | 作用 |
| --- | --- |
| `gh_repo_tree` | 指定 ref 的文件树，默认递归，并给出截断标志——比逐层遍历目录便宜得多。 |
| `gh_push_files` | 向分支提交文件：blob → 基于分支树的 tree → commit → 移动 ref。分支不存在会创建。`force` 绝不隐含，且需要 `confirm: true`。 |
| `gh_upload_project` | 创建仓库、发布文件并可选地打开 PR——一次调用。仓库已存在时直接使用，而不是失败。 |
| `gh_delete_file` | 删除单个文件（先解析 blob sha）。需要 `confirm: true`。 |
| `gh_delete_branch` | 删除分支。需要 `confirm: true`。 |

### 账号与登录

| 工具 | 作用 |
| --- | --- |
| `gh_auth_login` | 启动 GitHub device flow 登录：返回短码与供人工确认的网址。 |
| `gh_auth_finish` | 收取已启动的登录。授权值写入本插件自己的文件（权限 `0600`），绝不会出现在工具结果里。 |
| `gh_auth_status` | 访问来源（凭据、环境变量、本插件登录、`gh` CLI）、账号、已授权范围与剩余速率限制。 |
| `gh_auth_logout` | 忘记本插件保存的登录；其他来源不受影响。需要 `confirm: true`。 |

## 后台评审与斜杠命令

`gh_review_job` 立即返回任务 id，`gh_review_job_status` 读取结果。宿主提供任务注册表时， 任务可在界面中查看与取消；否则在插件内部运行。

斜杠命令是人类的快捷入口：`/pr create [title]`、`/review [number]`、 `/issue new <title> | list | show <number>`、`/gh [分组|工具]`。命令本身**不会**写入 GitHub， 只是把指令交给模型，因此写入仍然经过审批关卡。

## 可靠性

-   读取结果按 `cacheTtlMs` 缓存，因此组合报告或重复列表不会重复消耗速率限制。写入始终访问网络并清空缓存。
-   被取消的回合会取消在途请求，错误会如实说明，而不是伪装成超时。
-   读取会在网络失败、超时或服务端错误时重试；写入从不重试——重复写入是决策，不是意外。
-   每个列表同时会在本地截断，因为 API 有时会忽略请求的分页大小。
-   失败会说明下一步该做什么：缺少凭据、权限范围不足、对象不可见（草稿 Release 只能按 id 访问）、需要重新读取的冲突、需要修正的载荷、可以重试的超时；网络不可达时还会指出 `/etc/hosts` 被写坏。

## 界面

插件提供四个小界面，除两处明确确认外均为只读：

-   **插件卡片中的访问状态。** 来源、账号、权限范围、剩余速率限制与缓存状态。数据来自仅本机可访问的宿主路由，访问值不会进入对话。状态：加载中、未配置（附指引）、正常、错误。
-   **Source Control 标签页**（会话视图环）：仓库路径与分支的 ahead/behind、变更分组（冲突、已暂存、已修改、未跟踪）、所选文件的差异面板、进行中的 merge/rebase 提示，以及分支、标签与 stash。目前只读：提交栏与分支/stash 操作是下一步。
-   **侧边栏 GitHub 面板**——同时注册到 better-sidebar 与内置右侧栏。带公开搜索的仓库切换器、带文件预览的 Code 树，以及 Issues、Pull requests、Actions、Inbox 四个标签。
-   **输入框上方的 Pull Request 条**。当分支存在上游没有的提交时出现；其按钮把指令复制到剪贴板而不是直接写入——调用仍走正常的审批链路。

系统提示中会加入一段关于本插件的简短说明（`guidance`）；会话中点击的 `github.com` 链接可以记录要跟随的仓库（`interceptLinks`，默认关闭）。

## 安全边界

-   token 只存在于 DSH 凭据服务，设置中只有名称；
-   读取操作不改变状态；写入需要显式 `confirm` 参数，删除仓库、转移仓库、删除组织会被直接拒绝。是否显示确认提示由宿主的审批机制决定——本插件不自行运行审批关卡；
-   客户端不会输出 token，失败以返回值形式报告（`ok: false` 及 `status`、`code`、`rateLimit`）， 不会中断整个回合；
-   `gh_review` 的发现是确定性规则：指出需要关注的地方，绝不冒充正确性结论。

## 路线图

按顺序的发布阻塞项：

1.  **功能对齐** —— `pr_create`、`pr_update`、`pr_merge`、`gh_review`、`review_post`、 `gh_issue`、`issue_open`、`issue_comment`、`issue_close`、`gh_search`、 `gh_repo_search`、`gh_repo`、`gh_file`、`gh_checks`、`ci_run`。
2.  **镜像** —— `gh_mirror_check`、`gh_mirror_publish`：净化后的产品树（白名单取自 `package.json → files`），在镜像分支之上一个提交，fast-forward，绝不 force。
3.  **工作流运行** —— `gh_run_list/view/rerun/cancel/logs`。
4.  **仓库设置** —— secrets、variables、rulesets、分支保护、`gh_repo_create`、`gh_repo_edit`。
5.  插件页设置卡片、`en`/`zh` 语言包、设计契约。

## 开发

```bash
npm test        # node --test，不需要 harness，也不访问网络：fetch 是注入的
```

## 许可证

MIT —— 见 [LICENSE](https://npmcn.com/package/%40goodandready/dsh-github-ops/LICENSE)。

## 常见问题

### @goodandready/dsh-github-ops 是什么？

GitHub操作DeepSeek Harness:发布,标记,一个被守护的通用API通关,工作流程运行,秘密和已消毒的镜像出版物\.

### 如何安装 @goodandready/dsh-github-ops？

在项目目录运行 npm install @goodandready/dsh-github-ops，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-tools（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-settings（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/dsh-credentials（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-github-ops 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-github-ops 是否存在。

### @goodandready/dsh-github-ops 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-github-ops 可以商用吗？

@goodandready/dsh-github-ops 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-github-ops 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-github-ops 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,565 次，日均约 119 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-github-ops 还在维护吗？

最新版本 0\.6\.19 发布于 2026/11/12（4 天前）；至今共发布 41 个版本，其中过去 12 个月发布了 41 个；首次发布于 2026/09/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

