@zhin.js/adapter-github 1.0.1 → 1.1.2

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 工具**：按账号、订阅和仓库操作拆分在 `agents/github/skills/github-*/tools/`，只激活当前任务所需的一组
 
 ## 安装
 
@@ -21,66 +16,58 @@
 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
-endpoints:
-  - 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:
+      - id: my-github-bot
+        app_id: "${GITHUB_APP_ID}"
+        private_key: ./data/github-app.pem
+        webhook_secret: "${GITHUB_WEBHOOK_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
-```
+`private_key` 支持文件路径或 PEM 内容。未配置 `webhook_secret` 时仅 API 出站 / agent 工具可用（无入站）。
 
-或在 `zhin.config.yml` 中设置 `ai.githubMcp.token`（优先于环境变量）。
+`AdapterIndex` 会先合并插件实例默认值与 endpoint 覆盖值，再把一份完整配置交给
+GitHub adapter。协议层只接受这份展开后的 endpoint 配置，不读取环境变量、不解析嵌套
+`endpoints`，也不接受 camelCase 配置别名。`${...}` 由 composition root 在加载配置时展开。
 
-`private_key` 支持两种写法：
-- 文件路径：`./data/github-app.pem`
-- 直接内容：`"-----BEGIN RSA PRIVATE KEY-----\n..."`
+多 App：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段；`id`、`app_id`、`private_key` 必填）：
 
-## Channel ID 格式
+```yaml
+plugins:
+  github:
+    endpoints:
+      - id: app-a
+        app_id: 123456
+        private_key: ./data/app-a.pem
+      - id: app-b
+        app_id: 234567
+        private_key: ./data/app-b.pem
+```
+
+## 已移除的能力
 
-GitHub adapter 将 Issue/PR 映射为聊天频道：
+- **`ai.githubMcp.enabled` / `ai.githubMcp.token`**：Plugin Runtime 迁移后 `register-github-mcp`（stdio `@modelcontextprotocol/server-github`，PAT 人身份）已移除，该配置不再生效。如需 MCP 工具，请按 `mcps/<name>/index.ts`（`@zhin.js/mcp-feature`）约定自行装配。
+- 轮询降级已删除，入站只通过 Webhook；没有保留无效的轮询配置字段。
+
+## Channel ID
 
 | 类型 | Channel ID | 示例 |
 |------|-----------|------|
@@ -89,141 +76,32 @@ GitHub adapter 将 Issue/PR 映射为聊天频道：
 
 ## AI 工具
 
-### 适配器内置（Zhin 专有）
-
-| 工具 | 说明 |
-|------|------|
-| `github_star` | Star / Unstar / 检查（per-user OAuth 或 Endpoint 默认） |
-| `github_bind` / `github_unbind` / `github_whoami` | 用户 GitHub 账号绑定 |
-| `github_install` | GitHub App 安装链接 |
-| `github_subscribe` / `github_unsubscribe` / `github_subscriptions` | 频道级 Webhook 订阅 |
+见 `agents/github/skills/github-*/tools/`：账号绑定、订阅管理和仓库写入分别按需披露。
 
-### 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. Endpoint 返回 **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()`），**无需**在 Endpoint 配置里写 `client_id` / `client_secret`。
-
-### 前置条件
-
-- 需要 **`database`** 插件（`github_oauth_users` 模型）
-- Device Flow 在 IM 内完成，**不依赖** `/pub/github/oauth` HTTP 路由
-
-## 数据库表
-
-### github_subscriptions
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| id | integer | 主键 |
-| repo | text | 仓库名 (owner/repo) |
-| events | json | 订阅的事件列表 |
-| target_id | text | 目标频道 ID |
-| target_type | text | 类型 (private/group/channel) |
-| adapter | text | 适配器名称 |
-| endpoint | 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
-│   ├── endpoint.ts                # GitHubEndpoint（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              # EndpointConfig、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/index.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/index.js

@@ -0,0 +1,51 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/github/index.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/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Convention entry: discover `adapters/github/index.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 GithubEndpointConfig,
+} 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<GithubEndpointConfig>({
+  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/agents/github/agent.json

@@ -0,0 +1,20 @@
+{
+  "name": "GITHUB Platform Agent",
+  "version": "1.0.0",
+  "description": "Handles github platform-specific operations and progressively loads only the required platform Skill.",
+  "trigger_rules": {
+    "file_patterns": [],
+    "keywords": [
+      "github",
+      "adapter:github"
+    ]
+  },
+  "entry_points": [
+    "system.md",
+    "boundaries.md",
+    "conventions.md"
+  ],
+  "platforms": [
+    "github"
+  ]
+}

package/agents/github/boundaries.md

@@ -0,0 +1,3 @@
+# Boundaries
+
+Operate only on the active github endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.

package/agents/github/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.

package/agents/github/skills/github-account/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: github-account
+platforms:
+  - github
+description: GitHub 账号绑定、安装状态和身份查询能力。
+keywords:
+  - "github"
+  - "账号"
+  - "绑定"
+  - "安装"
+tools:
+  - "bind"
+  - "install"
+  - "unbind"
+  - "whoami"
+---
+
+# github-account
+
+处理 GitHub 身份与绑定状态时加载。`bind` 使用 Device Flow 绑定用户 OAuth 身份；`install` 返回 GitHub App 安装入口；`whoami` 用于确认当前绑定。用户想用自己的账号执行操作时先绑定。解绑和安装相关操作遵守 Tool 审批，不回显 Token、Device Code 或其他凭据。

package/agents/github/skills/github-account/handlers.js

@@ -0,0 +1,116 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { formatCompact } from '@zhin.js/logger';
+import { getCurrentCommMessage } from '@zhin.js/agent/security';
+import { GhClient } from "../../../../lib/gh-client.js";
+function oauthModel(client) {
+    const db = client.database;
+    return db?.models?.get('github_oauth_users');
+}
+function depsLogger() {
+    return {
+        debug: (...args) => console.debug(...args),
+        warn: (...args) => console.warn(...args),
+        error: (...args) => console.error(...args),
+    };
+}
+export async function executeGithubBind(_args, client, commMessage) {
+    const log = depsLogger();
+    const msg = commMessage ?? getCurrentCommMessage();
+    if (!msg?.$adapter || !msg?.$sender?.id)
+        return '❌ 无法获取当前用户信息';
+    const clientId = client.clientId;
+    if (!clientId)
+        return '❌ Endpoint 未配置 GitHub App 或 App 无 client_id，无法进行账号绑定';
+    const model = oauthModel(client);
+    if (!model)
+        return '❌ 数据库未就绪';
+    const [existing] = await model.select().where({ platform: msg.$adapter, platform_uid: msg.$sender.id });
+    if (existing) {
+        return `⚠️ 你已绑定 GitHub 账号: ${existing.github_login}\n如需重新绑定，请先执行 github_unbind`;
+    }
+    try {
+        const host = client.host;
+        const codeResp = await GhClient.deviceFlowRequestCode(clientId, host);
+        const tokenPromise = GhClient.deviceFlowPollToken(clientId, codeResp.device_code, codeResp.interval, codeResp.expires_in, host);
+        const replyMsg = [
+            '🔗 请在浏览器中打开以下链接进行授权：',
+            `   ${codeResp.verification_uri}`,
+            '',
+            `📋 输入验证码: **${codeResp.user_code}**`,
+            '',
+            `⏳ 等待授权中…（${Math.floor(codeResp.expires_in / 60)} 分钟内有效）`,
+        ].join('\n');
+        tokenPromise.then(async (tokenData) => {
+            if (!tokenData) {
+                log.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.$adapter, sender: msg.$sender.id }));
+                return;
+            }
+            const userGh = new GhClient({ host, token: tokenData.access_token });
+            const authResult = await userGh.verifyAuth();
+            const login = authResult.ok ? authResult.user : 'unknown';
+            await model.insert({
+                id: Date.now(),
+                platform: msg.$adapter,
+                platform_uid: msg.$sender.id,
+                github_login: login,
+                access_token: tokenData.access_token,
+                created_at: Date.now(),
+            });
+            log.debug(formatCompact({ op: 'bind', platform: msg.$adapter, sender: msg.$sender.id, login }));
+            if (msg?.$reply) {
+                await msg.$reply(`✅ GitHub 账号绑定成功！\n👤 ${login}`);
+            }
+        }).catch((err) => {
+            log.error('GitHub Device Flow 错误:', err);
+        });
+        return replyMsg;
+    }
+    catch (e) {
+        return `❌ Device Flow 启动失败: ${e instanceof Error ? e.message : String(e)}`;
+    }
+}
+export async function executeGithubUnbind(_args, client, commMessage) {
+    const msg = commMessage ?? getCurrentCommMessage();
+    if (!msg?.$adapter || !msg?.$sender?.id)
+        return '❌ 无法获取当前用户信息';
+    const model = oauthModel(client);
+    if (!model)
+        return '❌ 数据库未就绪';
+    const [existing] = await model.select().where({ platform: msg.$adapter, platform_uid: msg.$sender.id });
+    if (!existing)
+        return '📭 你尚未绑定 GitHub 账号';
+    await model.delete().where({ id: existing.id });
+    return `✅ 已解除 GitHub 账号绑定: ${existing.github_login}`;
+}
+export async function executeGithubWhoami(_args, client, commMessage) {
+    const msg = commMessage ?? getCurrentCommMessage();
+    if (!msg?.$adapter || !msg?.$sender?.id)
+        return '❌ 无法获取当前用户信息';
+    const model = oauthModel(client);
+    if (!model)
+        return '❌ 数据库未就绪';
+    const [existing] = await model.select().where({ platform: msg.$adapter, platform_uid: msg.$sender.id });
+    if (!existing)
+        return '📭 你尚未绑定 GitHub 账号\n🔗 使用 github_bind 绑定你的账号';
+    const userGh = new GhClient({ host: client.host, token: existing.access_token });
+    const auth = await userGh.verifyAuth();
+    if (auth.ok) {
+        return `👤 已绑定 GitHub 账号: ${auth.user}\n📅 绑定时间: ${new Date(existing.created_at).toLocaleString('zh-CN')}`;
+    }
+    return `⚠️ 已绑定账号 ${existing.github_login}，但 Token 已失效\n🔗 请执行 github_unbind 后重新 github_bind`;
+}
+export async function executeGithubInstall(client) {
+    const slug = client.appSlug;
+    if (!slug)
+        return '❌ Endpoint 未配置 GitHub App';
+    const host = client.host || 'github.com';
+    const installations = client.installations;
+    let msg = `🔗 请点击以下链接安装 GitHub App 到你的仓库：\n   https://${host}/apps/${slug}/installations/new`;
+    if (installations.length) {
+        msg += `\n\n📋 当前已安装 (${installations.length}):`;
+        for (const inst of installations) {
+            msg += `\n  • ${inst.account.login} (${inst.account.type})`;
+        }
+    }
+    return msg;
+}