@zhin.js/adapter-github 1.0.0 → 1.1.0

package/README.md

@@ -1,19 +1,14 @@
 # @zhin.js/adapter-github
 
-把 GitHub 当聊天通道 — Issue/PR 评论区即群聊，通过 GitHub App 认证，纯 REST API 对接，零 CLI 依赖。
-
-查询 · 管理 · 通知 · OAuth 用户绑定 四合一。
+GitHub Plugin Runtime 适配器 — Issue/PR 评论区即聊天通道，GitHub App 认证，Webhook 入站经 `httpHostToken`。
 
 ## 功能特性
 
-- ✅ **聊天通道**：Issue/PR 评论区映射为群聊，支持收发消息
-- ✅ **仓库管理**：PR 合并/创建/Review/关闭、Issue 创建/关闭/评论
-- ✅ **信息查询**：Star、Branch、Release、CI Workflow 等
-- ✅ **事件通知**：Webhook 订阅，跨平台推送到任意聊天
-- ✅ **GitHub App 认证**：JWT → Installation Token，自动刷新
-- ✅ **OAuth 用户绑定**：用户可绑定自己的 GitHub 账号，star/fork 以个人身份执行
-- ✅ **AI Skill**：所有工具自动暴露给 AI 调用
-- ✅ **无 router 也能运行**：核心功能不依赖 HTTP 服务，有 router 时自动注册 Webhook 和 OAuth 路由
+- **聊天通道**：Issue/PR 评论区映射为群聊，支持收发消息
+- **Webhook 入站**：HMAC-SHA256 验签 → `Endpoint.emit(...)`
+- **出站**：`send({ conversation, payload })` → Issue/PR comment（`conversation.id` 为 channel ID）
+- **GitHub App 认证**：JWT → Installation Token
+- **Agent 工具**：`agent/` 下 star/bind/subscribe/workspace 等保留
 
 ## 安装
 
@@ -21,66 +16,59 @@
 pnpm add @zhin.js/adapter-github
 ```
 
-## 依赖
-
-- `@zhin.js/host-router`（可选）— 提供 Webhook 路由，用于接收 GitHub 事件推送
-
-## GitHub App 创建
-
-1. 访问 [GitHub Developer Settings](https://github.com/settings/apps)
-2. 点击 **New GitHub App**
-3. 填写基本信息：
-   - **App name**: 你的 bot 名称
-   - **Homepage URL**: 任意
-   - **Webhook URL**: `http://your-server:port/pub/github/webhook`（有 HTTP 服务时）
-   - **Webhook secret**: 自定义密钥
-4. 权限设置（Permissions）：
-   - **Repository → Issues**: Read & Write
-   - **Repository → Pull requests**: Read & Write
-   - **Repository → Contents**: Read
-   - **Repository → Metadata**: Read
-   - **Repository → Actions**: Read（查看 CI）
-5. 订阅事件（Subscribe to events）：
-   - Issue comment、Pull request、Pull request review、Pull request review comment
-   - Push、Star、Fork（用于通知）
-6. 创建后记录 **App ID**，点击 **Generate a private key** 下载 `.pem` 文件
-7. 安装 App 到目标仓库/组织
-
-## 配置
+Webhook 需要 Root 提供 `@zhin.js/host-http`（`zhin runtime start` 默认装配）。
+
+## 前置条件
+
+1. 创建 GitHub App，记录 App ID、私钥与 Webhook Secret。
+2. 授予目标仓库所需的 Issues、Pull requests 与 Contents 权限。
+3. 将 Webhook 指向公网 HTTPS 的 `/github/webhook`，并订阅 Issue、PR 与评论事件。
+4. 把 App 安装到目标仓库；仓库 Workroom 使用稳定的 `owner/repo` 地址匹配。
+
+## 配置（Plugin Runtime）
 
 ```yaml
 # zhin.config.yml
-bots:
-  - context: github
-    name: my-github-bot
-    app_id: 123456
-    private_key: ./data/github-app.pem   # PEM 文件路径或直接粘贴内容
-    webhook_secret: your-secret          # 可选；配置后启用 Webhook
-    webhook_path: /pub/github/webhook    # 可选；默认 /github/webhook，/pub/* 可绕过 Bearer
-
 plugins:
-  - database
-  - "@zhin.js/adapter-github"
-  - "@zhin.js/host-router"                # Webhook 需要
+  github:
+    webhook_path: /github/webhook
+    auto_reply_repos:
+      - zhinjs/zhin
+    workspace_root: ./data/github-workspaces
+    endpoints:
+      - name: my-github-bot
+        app_id: 123456
+        private_key: ./data/github-app.pem
+        webhook_secret: your-secret
 ```
 
 ```env
 GITHUB_APP_ID=123456
 GITHUB_WEBHOOK_SECRET=your-secret
-# MCP server-github（适配器自动 addMcp，与 App 认证独立）
-GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx
-# 或 ai.githubMcp.token / ai.mcpServers
 ```
 
-或在 `zhin.config.yml` 中设置 `ai.githubMcp.token`（优先于环境变量）。
+`private_key` 支持文件路径或 PEM 内容。未配置 `webhook_secret` 时仅 API 出站 / agent 工具可用（无入站）。
+
+多 App：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
 
-`private_key` 支持两种写法：
-- 文件路径：`./data/github-app.pem`
-- 直接内容：`"-----BEGIN RSA PRIVATE KEY-----\n..."`
+```yaml
+plugins:
+  github:
+    endpoints:
+      - name: app-a
+        app_id: 123456
+        private_key: ./data/app-a.pem
+      - name: app-b
+        app_id: 234567
+        private_key: ./data/app-b.pem
+```
 
-## Channel ID 格式
+## 已移除的配置
 
-GitHub adapter 将 Issue/PR 映射为聊天频道：
+- **`ai.githubMcp.enabled` / `ai.githubMcp.token`**：Plugin Runtime 迁移后 `register-github-mcp`（stdio `@modelcontextprotocol/server-github`，PAT 人身份）已移除，该配置不再生效。如需 MCP 工具，请按新运行时 `mcp/<name>.ts`（`@zhin.js/mcp-feature`）约定自行装配。
+- **`poll_interval`**：轮询降级已删除，仅 webhook 入站；该字段目前解析但不生效（deferred）。
+
+## Channel ID
 
 | 类型 | Channel ID | 示例 |
 |------|-----------|------|
@@ -89,141 +77,32 @@ GitHub adapter 将 Issue/PR 映射为聊天频道：
 
 ## AI 工具
 
-### 适配器内置（Zhin 专有）
-
-| 工具 | 说明 |
-|------|------|
-| `github_star` | Star / Unstar / 检查（per-user OAuth 或 Bot 默认） |
-| `github_bind` / `github_unbind` / `github_whoami` | 用户 GitHub 账号绑定 |
-| `github_install` | GitHub App 安装链接 |
-| `github_subscribe` / `github_unsubscribe` / `github_subscriptions` | 频道级 Webhook 订阅 |
-
-### MCP（`@modelcontextprotocol/server-github`）
-
-配置 `GITHUB_PERSONAL_ACCESS_TOKEN`（或 `ai.githubMcp.token`）后，适配器通过 `orchestrator.addMcp` 注册 `github` server；AI 侧工具名为 `mcp_github_*`（如 `mcp_github_fork_repository`、`mcp_github_create_issue`）。
-
-**BREAKING**：`github_fork` 已移除，请改用 `mcp_github_fork_repository`。
-
-### 使用示例
-
-```
-AI: 列出 zhinjs/zhin 的 PR
-AI: 合并 zhinjs/zhin 的 PR #108
-AI: 查看 zhinjs/zhin 的 star 数
-AI: 订阅 zhinjs/zhin 的 push 和 pr 事件
-AI: 搜索 zhinjs 相关的仓库
-AI: 给 zhinjs/zhin 的 issue #42 加上 bug 标签
-AI: 查看 zhinjs/zhin 的 README.md 文件
-AI: 对比 zhinjs/zhin 的 main 和 dev 分支
-AI: 编辑 zhinjs/zhin 的 issue #42 标题
-AI: 绑定我的 GitHub 账号
-AI: star zhinjs/zhin
-AI: fork zhinjs/zhin   # 使用 mcp_github_fork_repository
-```
-
-## Webhook 事件通知
-
-配置好 Webhook 后，支持以下事件的跨平台推送：
-
-| 事件 | 参数 | 说明 |
-|------|------|------|
-| Push | `push` | 代码推送 |
-| Issue | `issue` | Issue 创建/更新/关闭 |
-| Star | `star` | 仓库被 star |
-| Unstar | `unstar` | 仓库被 unstar |
-| Fork | `fork` | 仓库被 fork |
-| Pull Request | `pr` / `pull_request` | PR 创建/更新/合并 |
-
-### Webhook 端点
-
-```
-POST /pub/github/webhook
-```
-
-Headers:
-- `X-GitHub-Event`: 事件类型
-- `X-Hub-Signature-256`: 签名（配置了 secret 时）
-
-## OAuth 用户绑定（Device Flow）
-
-用户通过工具 **`github_bind`** 绑定 GitHub 账号（[OAuth Device Flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow)），**不是**浏览器 OAuth 回调页面。
-
-### 认证策略
-
-| 操作类型 | 使用的 Token | 原因 |
-|---------|------------|------|
-| 读取 issue/PR/repo 信息 | App JWT | 不涉及用户身份 |
-| 评论（bot 发言） | App JWT | 以机器人身份发言 |
-| star / unstar | User OAuth | 个人行为 |
-| fork | User OAuth | 个人行为 |
-
-### 绑定流程
-
-1. 用户在聊天中触发 `github_bind`（或说「绑定 GitHub」）
-2. Bot 返回 **verification URI** 与 **user code**（GitHub Device Flow）
-3. 用户在浏览器打开链接并输入 code 完成授权
-4. Token 写入 `github_oauth_users` 表；可用 `github_whoami` / `github_unbind` 管理
-
-**Client ID**：从 GitHub App 的 `/app` API 自动获取（`GhClient.getClientId()`），**无需**在 bot 配置里写 `client_id` / `client_secret`。
-
-### 前置条件
-
-- 需要 **`database`** 插件（`github_oauth_users` 模型）
-- Device Flow 在 IM 内完成，**不依赖** `/pub/github/oauth` HTTP 路由
+见 `agent/tools/`：`github_star`、`github_bind`、`github_subscribe`、`github_prepare_workspace` 等。
 
-## 数据库表
+## 架构
 
-### github_subscriptions
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| repo | text | 仓库名 (owner/repo) |
-| events | json | 订阅的事件列表 |
-| target_id | text | 目标频道 ID |
-| target_type | text | 类型 (private/group/channel) |
-| adapter | text | 适配器名称 |
-| bot | text | 机器人名称 |
-
-### github_events
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| repo | text | 仓库名 |
-| event_type | text | 事件类型 |
-| payload | json | 事件载荷 |
-
-### github_oauth_users
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| platform | text | 聊天平台 |
-| platform_uid | text | 平台用户 ID |
-| github_login | text | GitHub 用户名 |
-| access_token | text | Device Flow 获得的 token |
-| created_at | integer | 创建时间戳 |
-
-## 架构说明
-
-```
-adapter-github/
-├── src/
-│   ├── index.ts              # 插件入口：provide、useContext、模型表
-│   ├── adapter.ts            # GitHubAdapter
-│   ├── bot.ts                # GitHubBot（Issue/PR 频道）
-│   ├── gh-client.ts          # GitHub REST（App JWT / Installation Token）
-│   ├── register-github-mcp.ts # orchestrator.addMcp(server-github)
-│   ├── agent-prompt.ts       # 平台 prompt / deferred 工具筛选
-│   └── types.ts              # BotConfig、Webhook payload、Channel ID
-├── package.json
-└── README.md
-```
-
-- **无 `@zhin.js/host-router` 时**：REST 工具与轮询仍可用，但无法注册 Webhook
-- **有 `@zhin.js/host-router` 时**：注册 Webhook；MCP 通过 `orchestrator.addMcp`（需 PAT 或 `ai.githubMcp.token`）
-
-## 许可证
+| 路径 | 职责 |
+|------|------|
+| `plugin.ts` | 插件元数据；有 DatabaseHost 时定义 `github_oauth_users` |
+| `adapters/github.ts` | 薄 `defineAdapter` 入口（发现约定） |
+| `src/endpoint.ts` | Endpoint 生命周期、出站、admit |
+| `src/webhook.ts` | HMAC 验签与事件分发 |
+| `src/oauth-users.ts` | OAuth 表 SSOT + token 查找 |
+| `src/protocol.ts` | 协议纯函数（channel / payload） |
+| `src/gh-client.ts` | GitHub API 客户端 |
+
+- 入站：`httpHostToken` POST → `Endpoint.emit(...)`
+- 出站：`send({ conversation, payload })`
+
+## 故障排查
+
+| 现象 | 排查 |
+| --- | --- |
+| Webhook 401 | 检查 Secret、`X-Hub-Signature-256` 与原始请求体 |
+| App 鉴权失败 | 检查 App ID、私钥 PEM/文件路径与服务器时钟 |
+| 评论没有进入 Workroom | 先查 Endpoint 收件箱，再核对 Catalog 的 Endpoint 与 `owner/repo` |
+| 能收事件但不能回复 | 检查 installation 与仓库权限；PAT MCP 不替代 App 出站 |
+
+## License
 
 MIT

package/adapters/github.js

@@ -0,0 +1,51 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/github.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / oauth / protocol).
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { databaseHostToken, } from 'zhin.js';
+import { GithubEndpoint } from "../lib/endpoint.js";
+import { githubRuntimeStateToken } from "../lib/github-runtime-state.js";
+import { resolveGithubConfig, } from "../lib/protocol.js";
+export { GithubEndpoint } from "../lib/endpoint.js";
+function optionalDatabase(context) {
+    try {
+        return context.use(databaseHostToken);
+    }
+    catch {
+        return undefined;
+    }
+}
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // Issue/PR 评论以 markdown 图片链接消费远程 URL；无交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveGithubConfig(context.config);
+        const database = optionalDatabase(context);
+        // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
+        context.use(githubRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: config.webhookSecret ? 'webhook' : 'api',
+        });
+        if (config.webhookSecret) {
+            return new GithubEndpoint({
+                id: context.id,
+                http: context.use(httpHostToken),
+                database,
+                config,
+            });
+        }
+        // API-only: Issue/PR send + agent tools without webhook.
+        return new GithubEndpoint({
+            id: context.id,
+            database,
+            config,
+        });
+    },
+});

package/adapters/github.ts

@@ -0,0 +1,59 @@
+/**
+ * Convention entry: discover `adapters/github.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / oauth / protocol).
+ */
+import { defineAdapter, type AdapterContext } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  databaseHostToken,
+  type PluginDatabaseHost,
+} from 'zhin.js';
+import { GithubEndpoint } from '../src/endpoint.js';
+import { githubRuntimeStateToken } from '../src/github-runtime-state.js';
+import {
+  resolveGithubConfig,
+  type GithubAdapterConfig,
+} from '../src/protocol.js';
+
+export { GithubEndpoint } from '../src/endpoint.js';
+export type { GithubEndpointOptions } from '../src/endpoint.js';
+
+function optionalDatabase(context: AdapterContext): PluginDatabaseHost | undefined {
+  try {
+    return context.use(databaseHostToken);
+  } catch {
+    return undefined;
+  }
+}
+
+export default defineAdapter<GithubAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  // Issue/PR 评论以 markdown 图片链接消费远程 URL；无交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveGithubConfig(context.config);
+    const database = optionalDatabase(context);
+    // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
+    context.use(githubRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: config.webhookSecret ? 'webhook' : 'api',
+    });
+    if (config.webhookSecret) {
+      return new GithubEndpoint({
+        id: context.id,
+        http: context.use(httpHostToken),
+        database,
+        config,
+      });
+    }
+    // API-only: Issue/PR send + agent tools without webhook.
+    return new GithubEndpoint({
+      id: context.id,
+      database,
+      config,
+    });
+  },
+});

package/agent/prompt-sections/platform.ts

@@ -0,0 +1,16 @@
+import { defineAgentPromptSection } from '@zhin.js/prompt-section';
+
+export default defineAgentPromptSection({
+  title: 'GitHub',
+  content: [
+    'On GitHub, discuss Issues and Pull Requests in their current conversation context.',
+    'Use github_* tools for Bot write operations; do not use mcp_github_* writes that act as a human PAT.',
+    'Use a workspace and branch for multi-file changes, then report the resulting Pull Request or branch.',
+  ].join('\n'),
+  layer: 'tools',
+  order: 70,
+  retention: 'preferred',
+  maxChars: 1200,
+  profiles: ['interactive'],
+  platforms: ['github'],
+});

package/{skills/github/SKILL.md → agent/skills/github.md}

@@ -5,7 +5,7 @@ platforms:
 description: >-
   GitHub 全功能适配器技能：内置工具处理 Star/绑定/订阅；MCP server-github 处理 Fork/PR/Issue 等 API；
   bash + gh CLI 覆盖其余仓库自动化。
-  Bot 操作使用 GitHub App 身份；Star 等可使用用户 OAuth 绑定。
+  Endpoint 操作使用 GitHub App 身份；Star 等可使用用户 OAuth 绑定。
   每个 Zhin 实例通过 GH_TOKEN 环境变量注入身份，支持多实例协同。
   channel ID 格式：owner/repo/issues/N 或 owner/repo/pull/N。
 keywords:
@@ -60,6 +60,10 @@ tools:
   - github_subscribe
   - github_unsubscribe
   - github_subscriptions
+  - github_prepare_workspace
+  - github_patch_file
+  - github_push_branch
+  - github_create_pr
 always: false
 requires:
   bins:
@@ -72,7 +76,8 @@ requires:
 
 本技能提供三种操作方式：
 - **适配器内置工具**（`github_*`）：用户交互类操作，具备账号绑定、Device Flow 授权、频道级订阅等适配器专有逻辑
-- **MCP server-github**（`mcp_github_*`）：Issue/PR/搜索/Fork 等 GitHub API（需 `GITHUB_PERSONAL_ACCESS_TOKEN` 或 `ai.githubMcp.token`）
+- **Bot 写仓库工具**（`github_prepare_workspace` / `github_patch_file` / `github_push_branch` / `github_create_pr`）：Installation Token，UI 显示 **Bot** 身份；push/开 PR 需 HITL
+- **MCP server-github**（`mcp_github_*`，可选）：`ai.githubMcp.*` 配置已随 Plugin Runtime 迁移移除；如需 MCP 工具，按 `mcp/<name>.ts` 约定自行装配（PAT 为**人身份**，勿用于 Bot 写仓库）
 - **bash + gh CLI**：仓库自动化操作，灵活覆盖 GitHub API 全场景
 
 ## 一、适配器内置工具
@@ -86,15 +91,26 @@ requires:
 | `github_bind` | 绑定用户的 GitHub 账号（Device Flow 授权，无需输入密码）。用户想 star/fork 或操作自己的账号时，先引导使用此工具 |
 | `github_unbind` | 解除用户绑定的 GitHub 账号 |
 | `github_whoami` | 查看用户已绑定的 GitHub 账号信息 |
-| `github_install` | 获取安装 GitHub App 的链接，安装后 Bot 可访问用户的仓库 |
+| `github_install` | 获取安装 GitHub App 的链接，安装后 Endpoint 可访问用户的仓库 |
 
 ### 用户操作（使用绑定账号）
 
 | 工具 | 说明 |
 |------|------|
-| `github_star` | Star 或取消 Star 一个仓库。优先使用用户绑定的 GitHub 账号，未绑定则降级为 Bot 默认账号 |
+| `github_star` | Star 或取消 Star 一个仓库。优先使用用户绑定的 GitHub 账号，未绑定则降级为 Endpoint 默认账号 |
 
-### MCP（server-github，单一 PAT）
+### Bot 开发工作流（App 身份）
+
+| 工具 | 说明 |
+|------|------|
+| `github_prepare_workspace` | Clone/fetch 托管工作区并 checkout Issue/PR 对应分支 |
+| `github_patch_file` | Contents API 单文件更新（小改） |
+| `github_push_branch` | git commit + push（**需 HITL**） |
+| `github_create_pr` | 创建 PR（**需 HITL**；Issue 线程常用） |
+
+Issue 线程：新分支 → 开发 → push → 开 PR。PR 线程：push 到现有 head 分支。
+
+### MCP（server-github，可选 PAT）
 
 | 工具 | 说明 |
 |------|------|
@@ -111,10 +127,11 @@ requires:
 
 ### 内置工具执行规则
 
-1. `github_star` 优先使用用户绑定的 GitHub 账号，未绑定则降级为 Bot 默认账号
-2. Fork 与通用 API 使用 `mcp_github_*`（Bot PAT，非 per-user OAuth）
-3. 当用户想操作自己的 GitHub 账号进行 Star 时，先引导用户使用 `github_bind` 绑定
-4. Webhook 订阅关联到当前聊天通道，仅在该通道接收事件通知
+1. `github_star` 优先使用用户绑定的 GitHub 账号，未绑定则降级为 Endpoint 默认账号
+2. Bot 写仓库用 `github_*` 工具，不用 `mcp_github_*` 写操作
+3. MCP（`mcp_github_*`）仅在你按 `mcp/<name>.ts` 约定装配后可用（旧 `ai.githubMcp.enabled` 已移除），PAT 为人身份
+4. 当用户想操作自己的 GitHub 账号进行 Star 时，先引导用户使用 `github_bind` 绑定
+5. Webhook 订阅关联到当前聊天通道，仅在该通道接收事件通知
 
 ---
 

package/agent/tools/bind.ts

@@ -0,0 +1,13 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubBind } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{}>({
+  description: '绑定你的 GitHub 账号 — 使用 Device Flow 授权，无需输入密码',
+  adapter: 'github',
+  inputSchema: z.object({}),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubBind({}, context.$client, context.message);
+  },
+});

package/agent/tools/create_pr.ts

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubCreatePr } from '../../src/github-bot-handlers.js';
+
+export default defineAgentTool<{ repo?: string; title: string; body?: string; head?: string; base?: string }>({
+  description: '以 GitHub App Bot 身份创建 Pull Request（需 HITL 确认；Issue 场景常用）',
+  adapter: 'github',
+  inputSchema: z.object({
+    repo: z.string().optional().describe('owner/repo'),
+    title: z.string().describe('PR 标题'),
+    body: z.string().optional().describe('PR 正文'),
+    head: z.string().optional().describe('head 分支，缺省为工作区分支'),
+    base: z.string().optional().describe('base 分支，缺省为仓库默认分支'),
+  }),
+  tags: ['github'],
+  approval: 'always',
+  async execute(input, context) {
+    return executeGithubCreatePr(input, context.$client, context.message);
+  },
+});

package/agent/tools/install.ts

@@ -0,0 +1,13 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubInstall } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{}>({
+  description: '获取安装 GitHub App 的链接 — 安装后 Endpoint 可以访问你的仓库，你也可以使用更多功能',
+  adapter: 'github',
+  inputSchema: z.object({}),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubInstall(context.$client);
+  },
+});

package/agent/tools/patch_file.ts

@@ -0,0 +1,19 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubPatchFile } from '../../src/github-bot-handlers.js';
+
+export default defineAgentTool<{ repo?: string; path: string; content: string; message: string; branch?: string }>({
+  description: '通过 Contents API 单文件更新（小改；Bot Installation Token 身份）',
+  adapter: 'github',
+  inputSchema: z.object({
+    repo: z.string().optional().describe('owner/repo'),
+    path: z.string().describe('仓库内文件路径'),
+    content: z.string().describe('新文件内容'),
+    message: z.string().describe('commit message'),
+    branch: z.string().optional().describe('目标分支，缺省从 Issue/PR 上下文推断'),
+  }),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubPatchFile(input, context.$client, context.message);
+  },
+});

package/agent/tools/prepare_workspace.ts

@@ -0,0 +1,15 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubPrepareWorkspace } from '../../src/github-bot-handlers.js';
+
+export default defineAgentTool<{ repo?: string }>({
+  description: 'Clone/fetch 托管工作区并 checkout 到 Issue/PR 对应分支（GitHub App Bot 身份）',
+  adapter: 'github',
+  inputSchema: z.object({
+    repo: z.string().optional().describe('owner/repo，缺省从当前 Issue/PR 频道推断'),
+  }),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubPrepareWorkspace(input, context.$client, context.message);
+  },
+});

package/agent/tools/push_branch.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubPushBranch } from '../../src/github-bot-handlers.js';
+
+export default defineAgentTool<{ repo?: string; branch?: string; message: string }>({
+  description: '在托管工作区 git commit 并 push 到远程分支（需 HITL 确认；Bot 身份）',
+  adapter: 'github',
+  inputSchema: z.object({
+    repo: z.string().optional().describe('owner/repo'),
+    branch: z.string().optional().describe('分支名，缺省从上下文推断'),
+    message: z.string().describe('commit message'),
+  }),
+  tags: ['github'],
+  approval: 'always',
+  async execute(input, context) {
+    return executeGithubPushBranch(input, context.$client, context.message);
+  },
+});

package/agent/tools/star.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubStar } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{ action: 'star' | 'unstar' | 'check'; repo: string }>({
+  description: 'Star 或取消 Star 一个 GitHub 仓库（使用你绑定的 GitHub 账号，未绑定则用 Endpoint 默认账号）',
+  adapter: 'github',
+  inputSchema: z.object({
+    action: z.enum(['star', 'unstar', 'check']),
+    repo: z.string().min(1),
+  }),
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubStar(input, context.$client, context.message);
+  },
+});

package/agent/tools/subscribe.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubSubscribe } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{ repo: string; events?: string }>({
+  description: '订阅 GitHub 仓库的 Webhook 事件，事件将推送到当前聊天通道',
+  inputSchema: z.object({
+    repo: z.string().min(1),
+    events: z.string().optional(),
+  }),
+  adapter: 'github',
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubSubscribe(input, context.$client, context.message);
+  },
+});

package/agent/tools/subscriptions.ts

@@ -0,0 +1,13 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { executeGithubSubscriptions } from '../../src/github-tool-handlers.js';
+
+export default defineAgentTool<{}>({
+  description: '查看当前聊天通道的 GitHub 仓库订阅列表',
+  inputSchema: z.object({}),
+  adapter: 'github',
+  tags: ['github'],
+  async execute(input, context) {
+    return executeGithubSubscriptions({}, context.$client, context.message);
+  },
+});