github-tools

github-tools

面向编码 Agent 的 GitHub 工具：议题、看板、拉取请求、仓库、发行版和 Actions。

这些工具通过 GitHub CLI，涵盖议题、项目看板、拉取请求和原生堆栈、仓库、发行版及 Actions。一套实现，以最适合每种 Agent 运行环境的形式交付。

运行环境	交付方式	固定版本依据
OpenCode V2	原生插件（npm 包，含技能）	包中的版本
OpenCode V1	原生插件（npm 包，不含技能）	包中的版本
Claude Code	插件：MCP 服务和技能	发行版标签，作为 ref
Codex	插件：MCP 服务和技能	发行版标签，作为 ref
Grok Build	插件：MCP 服务和技能	发行版标签，作为 @ref
Antigravity	插件：MCP 服务和技能	发行版标签的树 URL
Hermes Agent	原生插件（Python，调用命令行）	发行版提交，作为 SHA
其他 MCP 主机	来自 npm 的 MCP 服务	包中的版本

0.3.0 将包从 craftsamo/agent-github 移至 craft-agent/github-tools 并重命名：npm 包为 @craftsamo/github-tools（原为 @craftsamo/agent-github，现已从 npm 移除），插件和 MCP 服务名为 github-tools，程序名为 github-tools 和 github-tools-cli，设置项为 GITHUB_TOOLS_*。为 0.2.0 编写的允许规则、插件安装配置和 MCP 配置需要更改；工具 ID 不变。

这些工具需要 Node.js 24 或更高版本，以及经过身份验证的 GitHub CLI。 docs/conventions.md 介绍了工具的命名方式 及其行为。

安装

请从发行版安装，切勿从默认分支安装：发行版是一个标签，其提交包含构建好的 dist/，而默认分支不包含。在 以下命令中，<version> 是发行版的版本号（1.2.3），<sha> 是其标签所指向的 提交：

gh api repos/craft-agent/github-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 在 opencode.json 中接受包及其选项：

{
  "plugins": [
    {
      "package": "@craftsamo/github-tools@<version>",
      "options": { "toolsets": ["issues", "pull_requests", "projects"] }
    }
  ],
  "permissions": [{ "action": "github_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 接受字符串形式的包，也接受包含其选项的一对值：

{
  "plugin": [["@craftsamo/github-tools@<version>", { "toolsets": ["issues", "pull_requests", "projects"] }]],
  "permission": { "github_*": "ask" }
}

OpenCode 允许任何操作，且不需要规则名称，因此除非规则设为 ask，否则插件请求会被静默批准。读取工具不会询问，因此 github_* 通配符是安全的。

V1 不注册技能。解压包并将其 skills/* 文件夹复制到 ~/.config/opencode/skills/：

npm pack @craftsamo/github-tools@<version>
tar -xzf craftsamo-github-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-github-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/github-tools#v<version>
claude plugin install github-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/github-tools --ref v<version>
codex plugin add github-tools@craft-agent

Codex 会将服务器名称中的 - 转换为 _，因此工具会显示为 mcp__github_tools__github_issue_*。它会在插件的 安装目录中启动 MCP 服务，不传入根目录，因此服务会从 Codex 随调用发送的内容中获取每次调用的目录：优先使用服务请求的沙盒状态，否则使用它指定的唯一工作区。

该插件声明了 default_tools_approval_mode = "writes"：对于每个未标记为只读的工具，Codex 都会先询问用户。用户的 [plugins."<plugin>".mcp_servers.<server>] 设置只能收紧审批规则。在该处设为 auto 会得到 prompt（读取操作也会询问），因为 Codex 将 auto 和 writes 视为不可比较。

Grok Build

grok plugin install craft-agent/github-tools@v<version> --trust

Grok 会在会话的工作目录中启动 MCP 服务，因此在克隆目录中，单独的议题编号会指向该仓库中的议题。

Antigravity

请从发行版标签的树安装，切勿从默认分支安装，因为默认分支不包含构建好的 dist/；Antigravity 会将该标签克隆到 ~/.gemini/config/plugins/github-tools。

agy plugin install https://github.com/craft-agent/github-tools/tree/v<version>

Hermes Agent

Hermes 安装的是一个提交，而不是标签，且插件安装后处于禁用状态：

hermes plugins install craft-agent/github-tools --ref <sha>
hermes plugins enable github-tools

如果 Hermes 网关已在运行，请重启它（hermes gateway restart）以加载插件。

插件会运行 Hermes 启动时找到的 Node。如果版本管理器在 Hermes 运行期间移除了该版本，调用时会再次查找 Node；如果找不到，请在 node 可运行的 shell 中重启 Hermes。

任何其他 MCP 宿主

将服务添加到宿主的 MCP 配置中。标志放在 args 中：

{
  "mcpServers": {
    "github-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/github-tools@<version>", "--toolsets", "issues,pull_requests,projects"]
    }
  }
}

工具和技能

每个工具集都附带一项技能，告诉 Agent 如何使用其中的工具。技能会在其 frontmatter 的 metadata 下声明所属工具集（metadata: { toolset: issues }，以块的形式编写）。OpenCode V2 和 Hermes 仅在设置中至少注册了该工具集的一个工具时才会注册这项技能，因此，关闭该工具集或移除了其中所有工具的配置文件都无法看到这项技能；未指定工具集的技能始终会注册。Claude Code、Codex、Grok Build 和 Antigravity 会安装整个技能文件夹，并仅将设置传递给 MCP 服务，因此无论设置选择了什么，它们都会列出所有技能。OpenCode V1 不会注册技能，其复制的技能也都会列出。

Issues（issues）

工具	功能	类别
github_issue_read	view 完整查看某个议题，或 list 某个仓库的议题或某个父议题的子议题及其议题字段	读取
github_issue_create	创建议题，并设置其类型、标签、受理人、里程碑、父议题和阻塞议题、议题字段及看板	添加
github_issue_edit	更改标题、正文（或追加内容）、类型、标签、受理人、里程碑或议题字段	覆盖
github_issue_comment	对议题发表评论	添加
github_issue_close	关闭议题并说明原因（completed、not_planned、duplicate）	覆盖
github_issue_reopen	重新打开已关闭的议题	覆盖
github_issue_relate	设置父议题、子议题、阻塞和被阻塞的议题，仅发送有变化的内容	幂等
github_issue_develop	在 GitHub 上创建与议题关联的分支，或返回已关联的分支	幂等

该技能位于 github-issues，在 Claude Code 中显示为 github-tools:github-issues，在 Hermes 中显示为 github-tools:issues。议题类型是组织定义的同名 Issue Type（如果有），否则为 type:<kind> 标签。议题字段（Priority、Effort、Start date、Target date 及其他字段）由组织自行定义，因此只有组织的仓库才有这些字段；list 可在 query 中使用 field.<name>:<value> 按字段筛选。

拉取请求和堆叠（pull_requests）

工具	功能	类别
github_pr_read	完整查看一个拉取请求、列出仓库的拉取请求、读取其检查（最多等待 45 秒，并包含失败作业的日志）或其差异	读取
github_pr_create	从已推送的分支创建拉取请求，并设置标签、受理人、审阅者、里程碑、要关闭的问题、看板和附件	添加
github_pr_edit	修改标题、正文（或在正文后追加内容）、目标分支、标签、受理人、审阅者、里程碑或要关闭的问题	覆盖
github_pr_comment	发表评论并附加附件	添加
github_pr_review	批准、请求修改或发表评论，并添加行内评论	添加
github_pr_ready	将拉取请求标记为可供审阅，或将其恢复为草稿	幂等
github_pr_close	关闭	覆盖
github_pr_reopen	重新打开已关闭的拉取请求	覆盖
github_pr_merge	合并；收到请求时，也会合并堆叠中位于其下方的未合并层	管理
github_stack_read	按编号或其中的拉取请求查看原生堆叠，或列出仓库的堆叠	读取
github_stack_link	将拉取请求加入同一个堆叠，或将它们添加到某个堆叠的顶部	幂等
github_stack_unlink	解散堆叠，同时保留其中的拉取请求为打开状态	覆盖

此技能为 github-pull-requests，在 Claude Code 中显示为 github-tools:github-pull-requests，在 Hermes 中显示为 github-tools:pull-requests。这些工具不会推送：请先推送分支，并将推送的提交作为 head_sha 传入，这样拉取请求就会基于完全相同的提交创建、接受审阅或合并。要关闭的问题会以 Closes #N 行的形式保留在正文中，因为 GitHub 没有其他关联方式。堆叠使用 GitHub 的 REST 堆叠端点，因此无需安装 gh stack 扩展。 附件需要 gh 2.99 或更高版本。

项目看板（projects）

工具	功能说明	类别
github_project_read	view 查看包含字段和视图的看板，list 列出看板，或 item_list 列出看板上的项目	读取
github_project_create	创建看板，或复用同名看板，并添加标准字段和视图	幂等
github_project_field_ensure	添加字段，或添加单选字段中缺失的选项	幂等
github_project_view_ensure	添加已保存的视图，并设置其字段、列、分组和排序	幂等
github_project_link	将看板关联到同一所有者的仓库	幂等
github_project_unlink	取消看板与仓库的关联	幂等
github_project_item_add	将议题或拉取请求添加到看板，或返回其项目及字段值	幂等
github_project_item_create	创建草稿项目并设置字段值	添加
github_project_item_edit	设置或清除字段值，并更改草稿的标题和正文	覆盖
github_project_item_archive	归档项目	覆盖
github_project_item_unarchive	恢复已归档的项目	覆盖
github_project_item_convert	将草稿转换为议题，并指定其类型、标签和里程碑	添加

该技能为 github-projects，在 Claude Code 中显示为 github-tools:github-projects，在 Hermes 中显示为 github-tools:projects。看板可通过编号、owner/N、URL 或标题指定（未提供时为 Roadmap），查找顺序为关联到仓库的看板、所属组织的看板，然后是查看者的看板。令牌需要 project 作用域（gh auth refresh -s project）。没有 API 可以设置路线图视图的日期字段，因此在执行 github_project_create 后，请在网页界面中将路线图视图的“日期字段”设为开始和 目标。镜像组织议题字段的列可像其他列一样读取，但其值属于议题本身：看板工具拒绝设置 或清除此类值，而 github_issue_edit 可以执行这两项操作。 github_project_field_ensure 使用 issue_field: true 时会添加此类列；组织看板的 github_project_create 使用 dates: "issue_fields" 时，会将议题字段“开始日期”和“目标日期”用作看板日期。

仓库（repos）

工具	功能说明	类别
github_repo_read	view 仓库设置、功能、合并设置和查看者的权限，或 list 某位所有者的仓库	读取
github_repo_create	创建仓库，可以为空仓库或从模板创建	管理
github_repo_edit	更改描述、主页、默认分支、主题、功能或合并设置	覆盖
github_repo_visibility	将仓库设为公开、私有或内部可见	管理
github_repo_archive	归档仓库	管理
github_repo_unarchive	取消归档仓库	覆盖
github_label_read	list 仓库标签	读取
github_label_create	创建标签	添加
github_label_edit	重命名标签、更改标签颜色或描述	覆盖
github_label_delete	删除标签，并将其从所有议题和拉取请求中移除	管理
github_milestone_read	list 仓库里程碑及其进度	读取
github_milestone_create	创建里程碑	添加
github_milestone_edit	更改里程碑标题、截止日期或描述，或关闭、重新打开里程碑	覆盖
github_ruleset_read	list 规则集和经典分支保护设置，或 view 某个规则集	读取
github_ruleset_create	创建规则集，并设置其 refs、规则和可绕过规则的角色	管理
github_ruleset_edit	替换规则集的部分内容；如果规则集自读取后发生更改，则以 stale 状态停止	管理
github_ruleset_delete	删除规则集	管理

此工具集默认关闭：将 repos 添加到 toolsets。技能为 github-repos，在 Claude Code 中显示为 github-tools:github-repos，在 Hermes 中显示为 github-tools:repos。 大多数设置更改都需要仓库管理员权限；私有仓库的规则集则需要付费计划。删除、重命名、转移或复刻仓库的操作留给用户处理。

Releases（releases）

工具	功能说明	类别
github_release_read	list 仓库的发布版本（包括草稿），或按标签 view 一个版本及其说明和提交	读取
github_release_create	创建草稿发布版本，可选择生成说明	添加
github_release_edit	更改标题、说明、预发布标记、最新状态或草稿的目标	覆盖
github_release_publish	发布草稿；当其提交与 head_sha 不同时，停止并标记为 stale	管理
github_release_delete	删除发布版本及其资源文件，但保留其标签	管理

此工具集默认关闭：将 releases 添加到 toolsets。对应的技能是 github-releases，在 Claude Code 中显示为 github-tools:github-releases，在 Hermes 中显示为 github-tools:releases。新建的发布版本始终是草稿；目前尚不支持资源文件。

Actions（actions）

工具	功能说明	类别
github_workflow_read	list 仓库的工作流（包括已禁用的工作流），或 view 一个工作流及其在某个分支或标签上的文件	读取
github_run_read	按分支、工作流、状态、事件或提交 list 工作流运行记录，或 view 一条记录及其任务和失败日志；运行期间会等待	读取
github_workflow_run	手动启动工作流并传入输入；当引用与 head_sha 不同时，停止并标记为 stale	管理
github_run_rerun	重新运行已完成记录中的失败任务、所有任务或单个任务	管理
github_run_cancel	取消排队中或正在运行的记录	管理

此工具集默认关闭：将 actions 添加到 toolsets。对应的技能是 github-actions，在 Claude Code 中显示为 github-tools:github-actions，在 Hermes 中显示为 github-tools:actions。每次写入 Actions 都会逐次询问，因为工作流可能会执行名称所示的部署或发布操作。目前尚不支持启用或禁用工作流、删除运行记录和下载构件。

Planning

github-planning 不会添加工具。它说明了如何使用议题和看板工具进行规划：何时将工作安排为单个议题或包含子议题的父议题，如何估算子议题的规模，如何将仓库外的步骤（例如审批或等待供应商答复）纳入计划，每个正文采用何种格式、按什么顺序创建，以及后续变更时如何改写正文或在评论中说明。它在 Claude Code 中显示为 github-tools:github-planning，在 Hermes 中显示为 github-tools:planning。它关联到 issues 工具集，必须依赖该工具集才能工作，并说明看板工具关闭时应跳过哪些内容。

添加工具

1. 使用 defineTool 在 src/core/<domain>/<verb>.ts 中编写规范：包含 ID <prefix>_<domain>_<verb>、标题和描述、Zod 参数与输出架构、所属工具集和写入类别，以及 execute(args, context)。写入工具还需提供 targets(args, context)：说明调用会写入哪些 目标，以便权限规则能够据此命名目标。
2. 在规范旁边编写测试（<verb>.test.ts），像各入口点一样通过 invoke 调用工具。运行程序的 工具需针对 PATH 中该程序的模拟版本进行测试；任何测试都不会访问真实服务。
3. 在 src/tools.ts 中列出该工具。将新工具集添加到 src/project.ts 中的 toolsets（如果默认 启用，也要添加到 defaultToolsets）；将包自身的设置添加到 options（并在 project.py 中 添加到 OPTIONS，同时在 plugin.yaml 中添加 config_schema）；将工具读取的、设置之外的 变量添加到 toolVariables。
4. 添加或更新工具集的技能文件 skills/<prefix>-<toolset>/SKILL.md，其 frontmatter 需在 metadata 下列出该工具集。
5. 运行 pnpm run build && pnpm run manifests，将工具列入 plugin.yaml，并将其变量列入 Codex 的清单，然后在“工具和技能”下进行说明。

docs/conventions.md 列出了每个步骤需遵循的规则。

读取与写入

每个读取工具都命名为 <prefix>_<domain>_read。读取操作可以不经询问直接执行； 写入操作会由宿主确认。

宿主	无需询问即可读取
OpenCode	始终如此；插件仅在写入前询问
Claude Code	~/.claude/settings.json 中 permissions.allow 的规则 mcp__plugin_github-tools_github-tools__*_read
Codex	始终如此；Codex 会对声明了 readOnlyHint 的工具（如读取工具）免询问直接执行
Grok Build	grok --allow 'MCPTool(github-tools__*_read)' --allow 'MCPTool(github_*_read)'（两条规则；见下文）
Antigravity	permissions.allow 中的规则 mcp(github-tools_github-tools/<tool id>)，每个读取工具各一条
Hermes	始终如此；插件仅在写入前询问

以下说明哪些情况下会询问写入操作，哪些情况下不会：

• OpenCode 不会针对任何操作授予无规则名称的权限，因此除非有规则要求确认，否则写入会免询问直接执行：添加 OpenCode 下所示的 github_* 规则。
• Codex 由于插件的审批模式，会在每次写入前询问。 在 codex exec 下，它会以 "MCP tool call requires approval, but approval policy is never" 拒绝执行。
• Grok Build 在 grok -p 下无法询问的写入操作会被拒绝，除非事先已获准。
• Grok Build 通过其 use_tool 工具调用插件工具，且 Agent 经常不带服务名称来指定工具。Grok 会按给定名称检查规则，因此仅有带服务名称的规则无法匹配首次调用。第二条规则会匹配简短名称；写入操作仍不会匹配任何一条规则。
• Antigravity 会在调用任何未被规则允许的 MCP 工具前询问，包括读取操作；它将插件的服务命名为 github-tools_github-tools（先是插件，再是服务）。agy -p 会拒绝执行无法询问的工具。
• Hermes 在 hermes chat -q 下会拒绝执行无法询问的写入操作；hermes -z 和 --yolo 会跳过审批，因此写入操作会免询问直接执行。

设置

每个入口点都使用相同的设置。命令行标志优先于其环境变量；选项或设置也优先于该变量。

设置	标志	变量	含义
toolsets	--toolsets	GITHUB_TOOLS_TOOLSETS	issues、pull_requests、projects、repos、releases、actions 或 all；默认值为 issues、pull_requests 和 projects
read_only	--read-only	GITHUB_TOOLS_READ_ONLY	不注册任何会写入的工具；优先级高于其他所有设置
tools	--tools	GITHUB_TOOLS_TOOLS	按 ID 添加单个工具，无论它属于哪个工具集
exclude_tools	--exclude-tools	GITHUB_TOOLS_EXCLUDE_TOOLS	按 ID 移除单个工具；优先级高于 tools 和 toolsets
confirm	--confirm	GITHUB_TOOLS_CONFIRM	仅限 MCP 服务：根据约定，使用 harness（默认值）或 elicitation
language	--language	GITHUB_TOOLS_LANGUAGE	仅限原生插件：审批提示词的语言，例如 ja
emoji	—	—	仅限 Hermes：按工具集名称设置显示在每个工具集旁的表情符号（不显示则设为 ""）

列表在标志或变量中以逗号分隔。每个软件包自身的设置（列在 src/project.ts 的 options 中）在此表中各占一行，并以相同方式读取。GitHub Actions 不允许将密钥或配置变量命名为 GITHUB_*，因此在工作流中，请通过 env: 将值从其他名称的密钥传入，例如 GITHUB_TOOLS_READ_ONLY: ${{ secrets.TOOLS_READ_ONLY }} （允许在 env: 中设置此类环境变量）。各运行环境读取这些设置的方式如下：

• OpenCode 使用上面所示的插件 options，列表采用数组形式，read_only 采用布尔值，并在未设置时回退到变量。V2 在后台服务中运行插件，该服务会保留启动时的环境：在 opencode run 启动时设置的变量不会生效，除非在该环境中重启服务（opencode service restart）。V1 在自身进程中运行插件。

• Hermes 使用 config.yaml 中的 plugins.entries.github-tools.settings：

  plugins:
    entries:
      github-tools:
        settings:
          toolsets: [issues, pull_requests, projects]
          read_only: false
          exclude_tools: [github_pr_merge]
  

  如果未设置 language，审批卡片将使用 Hermes 自身的 display.language（或 HERMES_LANGUAGE），也就是审批按钮的语言；否则将使用英语。插件会将自身的环境传递给它运行的命令行，因此变量也有效。运行中的网关会保留启动时的环境；更改其中一项后，请重启网关（hermes gateway restart）。

• Claude Code、Grok Build 和 Antigravity 会在不带标志的情况下启动插件的服务，并将客户端的环境传递给它，因此请在运行该运行环境的环境中设置变量。

• Codex 只会向插件的 MCP 服务传递少数基本变量（例如 PATH 和 HOME），以及插件清单中列出的变量，也就是上文提到的变量：请在运行 Codex 的环境中设置它们。工具除设置项之外还会读取的变量，应添加到 src/project.ts 中的 toolVariables；pnpm run manifests 会在设置项的变量之后将其添加到清单中。若要传递标志，或向服务提供程序未列出的变量，请在 Codex 的 config.toml 中将该服务添加到 [mcp_servers]，而不要使用插件：标志放在 args 中，env_vars 用于指定要从 Codex 的环境转发的变量名称，env 用于设置固定值。

  [mcp_servers.github-tools]
  command = "npx"
  args = ["-y", "@craftsamo/github-tools@<version>", "--toolsets", "issues,pull_requests,projects"]
  env_vars = ["GITHUB_TOOLS_READ_ONLY"]
  

布局

• src/project.ts — 程序包名称、工具 ID 前缀、设置前缀、工具集、工具选项，以及工具会读取的其他变量。
• src/core/ — 工具契约和工具，不包含任何运行环境相关内容或项目名称。
• src/tools.ts — 所有工具的列表，每个入口点都会注册这些工具。
• src/words.ts — 各语言中工具词语的翻译，原生插件会在批准提示词中使用这些翻译。
• src/mcp/ — MCP 服务，构建为 dist/mcp.js，由 github-tools 运行。
• src/opencode/ — OpenCode 插件，构建为 dist/opencode.js。
• src/cli/ — Hermes 插件调用的命令行，构建为 dist/cli.js，由 github-tools-cli 运行。
• src/hermes/、plugin.yaml 和 __init__.py — Hermes 插件。
• skills/ — 每个工具集各有一个技能，另有一个用于规划的技能，路径为 skills/<name>/SKILL.md。所有支持加载技能的运行环境都会从程序包或插件根目录加载这些技能；原生插件只会加载已启用工具集的技能。
• .claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、.antigravity-plugin/ 和 mcp_config.json — 其他运行环境的插件清单。Codex 会读取 .codex-plugin/plugin.json；根目录中的 plugin.json 会使它将插件作为 Agent Plugin 加载，而其工具预算会隐藏超出固定数量的工具。根目录的 .mcp.json 是 Grok Build 读取的配置文件（其中使用 ${CLAUDE_PLUGIN_ROOT}，这是 Grok Build 和 Claude Code 都会展开的变量）；在 Claude Code 中处理此代码库时，请拒绝它通过该文件提供的项目 MCP 服务。

发布流程见 RELEASING.md。

许可证

AGPL-3.0 with Commons Clause