@zhin.js/adapter-github 1.1.26 → 1.1.27

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # @zhin.js/adapter-github
 
+## 1.1.27
+
+### Patch Changes
+
+- e1fda87: fix: 按审计待审清单处理（安全、功能、清理）
+
+  **行为变更（升级前请阅读）**
+
+  - kernel / core / zhin.js：出站文本中的 `${…}` 不再用 `vm` 求值，只替换 `TemplateContext` 上能解析到值的属性路径（如 `${sender.name}`）；表达式、函数调用、未知名字原样保留。整套 vm 沙箱（`evaluate` / `execute` / `compiler` / `getValueWithRuntime`）已移除。
+  - kernel / core / zhin.js：移除零引用的遗留导出——`Scheduler`、错误管理器与 `ZhinError` 子类、`compose`、`segment.from/toString`、AI 触发/准入函数、`@zhin.js/core/queue-im-field-contract`、`zhin.js/contexts`。
+  - agent：readonly 执行预设不再放行重定向、后台 `&`、进程替换、`find -delete/-exec`、`sed -i`、`sort -o`、`tee`、`xargs`、awk；curl/wget 校验每个 URL 与裸主机并识别更多上传参数；自定义 `execAllowlist` 中的只读命令带写入风险时改走审批。沙箱超时/取消会杀掉进程组或具名容器，默认镜像改为 `node:22-bookworm-slim` + `bash`。移除无生产调用的 `AuditLogger`、`AnomalyDetector`、旧 vision 回合等导出。
+  - ai：移除 `storage`、`FileStateCache`、`CostTracker`、`model-name-utils`、`./agent-step-checkpoint` 子路径、`ContextManager` 及旧压缩管线；延迟工具快照改为有界 LRU。
+  - cli：`zhin send` / `watch` / `schedule` 改为与运行中的 Host 通信（新增 `POST /message/send` 与 `/assistant/jobs` 写接口），`schedule` 不再支持离线改文件；移除 `zhin uninstall service`（用 `zhin service uninstall`）、`build --analyze`、`install -S`；`zhin stop` 杀不掉进程时保留 pid 文件并以非零退出；`runtime migrate` 新增 `verify`；未设置 `TZ` 时调度默认时区改为系统时区；不带 `ZHIN_SUPERVISOR_PID` 的进程被 init 接管后不再自行退出。
+  - schedule：后台 reconcile 出错不再产生未处理 rejection（新增 `onStoreError`）；启动途中 `stop()` 不再遗留定时器。
+  - schema：元组校验与 `safeParse`、JSON Schema 一致（空数组不通过，缺省的可选元组为 `undefined`）。
+  - client / contract：删除无后端路由的 agent-stream API、未使用的 `definePage` 与旧 PageManager 类型；`@zhin.js/contract` 不再依赖 `@zhin.js/ai`；客户端收到 401 会清除已保存的凭据；安装/更新/卸载 RPC 默认超时 120 秒。
+  - a2a：流式响应中途出错写入 SSE error 并结束；未配置 token 的非生产环境只接受本机请求；任务存储有上限与过期；Mailbox 凭据回退与生产环境缺密钥检查修复。
+  - speech：`provider: openai` 不再套用 Ollama 的默认 host/model；识别语言改为可配置，不再写死 `zh`。
+  - adapter-lark：支持 `encryptKey` 加密事件解密。adapter-github：Device Flow 可取消、带超时并回复失败原因。adapter-wecom / dingtalk：请求加超时并校验 HTTP 状态。adapter-weixin-ilink：输入关闭期间暂停轮询。adapter-milky：SSE 支持 CRLF、缓冲上限与空闲重连。adapter-onebot-events：好友删除通知改为 `notice.friend.decrease`。
+  - plugin-group-suite：`teachAllowRegex` 默认关闭，正则安全检查更严格。plugin-qrcode：改为本地生成，回复 data URL 图片。plugin-rss / short-url / link-poster：拒绝解析到内网的地址；rss 修复条目每周重复推送；short-url 的 Console 创建改为真实调用 is.gd。plugin-lottery：按 `historyLimit` 同步。
+
+  **其余**
+
+  - host-http：插件市场详情加缓存与包名校验，SSE 回放容忍背压。host-http-contract：新增 `readTextBody()`，九个适配器改用它。
+  - pagemanager：页面外壳 importmap 升级到 React 19.2.8 / react-router 7.12.0。console-contract：`definePage` 接受 `description` / `group` / `parent` / `fullWidth`。
+  - command：进度提示本地化，匹配不再重复拷贝消息段。runtime：源码监听降级后退避重试原生监听。
+  - html-renderer：删除未接线的 `aiTextAsImage`。create-zhin-app / scaffold-wizard：移除不起作用的"全局安装 CLI"与运行时选择提示。
+  - 依赖声明清理、发布清单不再携带解析不到的 `src` 目录、移除未使用的 Skill 挂载、README 与示例配置按当前实现更正。
+
+- 120e225: 聊天角色（ADR 0056，2026-11-12 修订）：zhin 角色 owner / admin / trusted 分四级、只来自授予；发言者的平台身份与机器人自身的平台身份是独立维度，命令、Agent 工具 / 技能、中间件与按钮按三条维度共用一个评估器过滤。升级说明见 docs/migrations/chat-roles.md。
+
+  - zhin.js：实例首次启动把适配器 `master` / `trusted`、`endpoints[i].master|trusted` 与 `ai.trigger.masters|trusted` 迁入项目数据库 `chat_roles`（先记入 `.zhin/chat-roles-migration.json`，再从配置移除并记日志）；之后配置再出现这些字段时启动报错并指向升级指南。平台身份不再映射为 zhin 角色：删除 `roles.mappings`（适配器块与 `endpoints[i].roles` 出现即启动报错）、`chat_role_mappings` 表与 Console `chat-roles.mappings` / `chat-roles.set-mappings`；`features.selfService.platformAdmins|roles|allowUsers` 删除；群内「功能」「角色」命令只认 zhin 角色，平台群主不再自动具备；聊天改配置、聊天重启、Agent 主人审批按 zhin `owner` 判断。
+  - @zhin.js/core（minor，破坏性）：角色模型与解析移入 core（`ChatRoleService`、`createChatRoleSenderEnricher`），入站消息带 `sender.chatRole` 与归一的 `sender.platform`；删除 `SenderRole`、`senderRolesFromMessage`、`roleSatisfies` 等，`master` 改名 `owner`；删除映射规则 API（`createMappingChatRoleSource`、`DEFAULT_CHAT_ROLE_MAPPINGS` 等）与 `ChatRoleSource`；`createSenderEnricher` / `createConfigurationChatAuthorizer` 改为基于聊天角色。IM Runtime 为 PermissionHost 提供机器人自身身份（经 Adapter 索引缓存），机器人的角色变化事件使缓存失效；命令拒绝回复说明缺少的平台 / 机器人条件；`<Button permit>` 按点击者鉴权；场景治理工具工厂同时要求 `platform:*` 与 `bot:*`；`ai.trigger.masters|trusted` 删除。
+  - @zhin.js/permission（minor，破坏性）：permit 语法 `owner` / `admin` / `trusted` / `role(...)`（zhin 角色）、`platform:owner|admin`、`platform-role:<id>`、`platform-permission:<name>`（发言者平台身份），新增 `bot:owner|admin`、`bot-role:<id>`、`bot-permission:<name>`（机器人自身平台身份，`PermissionSubject.bot`）；`PermissionHost` 新增 `setBotStandingResolver`、`withBotStanding`、`firstDenied`，`checkAll` 可带 `source` 解析机器人身份；新增 `describeDeniedPermit`、`permitsNeedBotStanding`。删除 `role(master)`、`scene_admin`、`scene_owner`、`platform(adapter,perm)` 及 `registerPlatform`、`createSceneRolePlatformChecker`、`platformPermission`、`definePlatformPermission`，定义时报错并给出替代写法。
+  - @zhin.js/command（minor，破坏性）：命令会话的发送者改为 `chatRole` / `platform`，不再从 metadata 读角色；`CONVERSATION_MANAGER_PERMIT` 改为 `admin`（平台群主不再自动满足）；分发结果 `denied` 带 `denial`（第一条不满足的规则与原因）；指令菜单只列出当前发送者在本会话可用的命令。
+  - @zhin.js/agent（minor，破坏性）：危险工具、文件 / exec 策略、主人审批、Agent 回合主体只读 zhin 角色（`principal.roles` 只含展开的聊天角色，平台地位在 `principal.platform`）；`SenderRole` → `PrincipalRole`，`SELF_CHANGE_MASTER_ROLE` → `SELF_CHANGE_OWNER_ROLE`；回合开始时读取机器人自身身份（`contextState.bot.platform`），按三条维度过滤 tool / skill / Agent 包后才披露，执行工具时再校验一次；群规「群主和管理员豁免」改为平台群主 / 管理员与 zhin `owner`。
+  - @zhin.js/feature-kit：`OperationSession.sender` 改为 `chatRole` / `platform`。
+  - @zhin.js/im-contract：新增 `PlatformStanding`、`SelfStandingRequest`、`standingFromMemberRole`。
+  - @zhin.js/adapter：入站 sender 可带 `platform`；账号管理命令需要聊天角色 `owner`；`EndpointManagement` 新增可选 `inspectSelfStanding`，能力画像新增 `scene.selfStanding`（声明即须实现），`AdapterIndex.selfStanding` / `invalidateSelfStanding` 按会话缓存机器人自身身份。
+  - @zhin.js/middleware：入站中间件可声明 `permit`，不满足时跳过该中间件（机器人身份只读缓存）。
+  - @zhin.js/tool：定义工具时拒绝已移除的 permit 写法。
+  - @zhin.js/ai：注释更新。
+  - @zhin.js/console-protocol：`chat-roles.list|grant|revoke`（`iam.manage`）；`ConsoleChatRoleSource` 只有 `grant`。
+  - @zhin.js/runtime：Host 配置 Schema 删除 `features.selfService.platformAdmins|roles|allowUsers`。
+  - @zhin.js/testing：伪造消息与 `PluginTestKit` 用 `sender.chatRole` 声明测试身份。
+  - @zhin.js/scaffold-wizard：ICQQ 向导不再写 `master`，完成后提示在 Console 账号「角色」页签或聊天 `角色 授予` 设置 owner。
+  - 适配器：配置 Schema 删除 `master` / `trusted`（以及预览版的 `roles`）；群管理类工具同时声明发言者条件与机器人条件（如 `platform:admin` + `bot:admin`、`bot-permission:manage_roles`），NapCat / OneBot11 工具不再使用已移除的 `platform(adapter,…)` 写法。
+  - 插件：内容审核以 `inbound.bypass`（permit 列表，默认 `owner` 或 `platform:admin`）取代 `masters` / `inbound.bypassMasters`；群管、音乐、日历、地震、B 站、轮盘赌的权限改用 zhin 角色，订阅类命令只认 zhin `admin` / `owner`。
+
+- 5cd9d3d: HTTP 路由契约改为 Web 标准 `Request` / `Response`（ADR 0054 §2，B1.0）
+
+  - host-http-contract：路由处理函数签名改为 `(request, context) => Response`，`context` 提供 `url`、`params`、`principal`、`remoteAddress`；新增 `readBodyBytes` / `readTextBody` / `readJsonBody`（带大小上限，超限先读完再报 413）、`jsonResponse` / `emptyResponse`、带背压的 `createResponseStream`（SSE、大文件下载）与 `WsConnection`。契约不再引用 `node:http` / `ws`。
+  - host-http：Node 服务器移到 `@zhin.js/host-http/node`（`createHttpHost`），负责 Node 请求与 `Request` / `Response` 的互转；认证结果经 `context.principal` 传给路由，删除旧的按请求取主体的辅助函数；未预期的异常只返回通用错误信息，细节写日志。
+  - runtime、mcp、a2a、gateway、zhin.js、calendar 插件与各适配器的 Webhook / 反向 WebSocket 路由迁移到新契约，行为不变。
+
+- 68659cd: `zod` 改为运行时依赖（原为可选对等依赖）：插件运行时在启动时就会加载这些包的约定目录（Agent 工具、命令等），其中静态导入了 `zod`；生成的项目里没有安装可选对等依赖，启动会报 `Cannot find package 'zod'`。范围为 `^4.6.7`（已修复的版本）。
+- Updated dependencies [53932e5]
+- Updated dependencies [57c6cdc]
+- Updated dependencies [e1fda87]
+- Updated dependencies [4e8ba38]
+- Updated dependencies [a9c7a13]
+- Updated dependencies [120e225]
+- Updated dependencies [c2bbdcf]
+- Updated dependencies [c2bbdcf]
+- Updated dependencies [63595fc]
+- Updated dependencies [fd055d2]
+- Updated dependencies [4e8ba38]
+- Updated dependencies [cc7a5f9]
+- Updated dependencies [4e8ba38]
+- Updated dependencies [f8bf684]
+- Updated dependencies [e0bc008]
+- Updated dependencies [5cd9d3d]
+- Updated dependencies [5cd9d3d]
+- Updated dependencies [c2bbdcf]
+- Updated dependencies [f8bf684]
+- Updated dependencies [663473b]
+- Updated dependencies [c606d51]
+- Updated dependencies [5cd9d3d]
+- Updated dependencies [d655ef0]
+- Updated dependencies [1e54b1e]
+  - @zhin.js/adapter@1.1.33
+  - @zhin.js/core@1.2.0
+  - @zhin.js/logger@1.1.3
+  - @zhin.js/host-http@1.2.0
+  - @zhin.js/feature-kit@1.1.16
+  - @zhin.js/agent-feature@1.1.17
+  - @zhin.js/console-contract@1.1.6
+  - @zhin.js/host-http-contract@1.2.0
+  - @zhin.js/skill@1.1.17
+  - @zhin.js/tool@1.1.19
+  - @zhin.js/im-contract@1.1.14
+  - @zhin.js/page@1.1.18
+
 ## 1.1.26
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -16,14 +16,14 @@ GitHub Plugin Runtime 适配器 — Issue/PR 评论区即聊天通道，GitHub A
 pnpm add @zhin.js/adapter-github
 ```
 
-Webhook 需要 Root 提供 `@zhin.js/host-http`（`zhin runtime start` 默认装配）。
+Webhook 需要 Root 提供 `@zhin.js/host-http`（`zhin start` 拉起的实例默认装配，HTTP 由管理网关承载）。
 
 ## 前置条件
 
 1. 创建 GitHub App，记录 App ID、私钥与 Webhook Secret。
 2. 授予目标仓库所需的 Issues、Pull requests 与 Contents 权限。
 3. 将 Webhook 指向公网 HTTPS 的 `/github/webhook`，并订阅 Issue、PR 与评论事件。
-4. 把 App 安装到目标仓库；仓库 Workroom 使用稳定的 `owner/repo` 地址匹配。
+4. 把 App 安装到目标仓库；仓库会话按稳定的 `owner/repo` 地址匹配。
 
 ## 配置（Plugin Runtime）
 
@@ -103,7 +103,7 @@ github:
 
 新增仅保存，需手动启动；运行账号的普通配置更新只重连该账号。身份变化走明确替换，新账号不会继承旧 Session 或登录状态。账号凭据变化先按平台实际只读接口核验；平台无法核验时需明确替换。空白或遮蔽的密码不会覆盖既有密码。
 
-读取需要 `github:read`，写入需要 `github:write`；首次迁移还需管理员身份。无持久化存储时管理操作不可用，提交结果未知时先刷新核实，不重复提交。
+读取需要 `github:read`（`read` 级别，内置角色 `viewer` 及以上都有），写入需要 `github:write`（`operate` 级别，`operator` 及以上都有，绑定到本适配器的角色也算）；首次迁移还需管理员身份，见[插件权限的级别](https://zhin.js.org/console/#插件权限的级别)。无持久化存储时管理操作不可用，提交结果未知时先刷新核实，不重复提交。
 
 ## 故障排查
 
@@ -111,7 +111,7 @@ github:
 | --- | --- |
 | Webhook 401 | 检查 Secret、`X-Hub-Signature-256` 与原始请求体 |
 | App 鉴权失败 | 检查 App ID、私钥 PEM/文件路径与服务器时钟 |
-| 评论没有进入 Workroom | 先查 Endpoint 收件箱，再核对 Catalog 的 Endpoint 与 `owner/repo` |
+| 评论没有到达 Bot | 先查 Endpoint 收件箱，再核对 Endpoint 配置与规范的 `owner/repo` |
 | 能收事件但不能回复 | 检查 installation 与仓库权限；PAT MCP 不替代 App 出站 |
 
 ## License

package/agents/github/messages.js

@@ -33,6 +33,26 @@ export const messages = createMessages({
         "zh-CN": "✅ GitHub 账号绑定成功！\n👤 {login}",
         "en": "✅ GitHub account linked!\n👤 {login}"
     },
+    "bindInProgress": {
+        "zh-CN": "⏳ 已有一个 GitHub 账号绑定正在等待授权，请先完成或等待其过期。",
+        "en": "⏳ A GitHub account link is already waiting for authorization. Finish it or wait for it to expire."
+    },
+    "bindExpired": {
+        "zh-CN": "⌛ GitHub 授权已超时，账号未绑定。请重新发起账号绑定。",
+        "en": "⌛ GitHub authorization timed out; no account was linked. Start account linking again."
+    },
+    "bindDenied": {
+        "zh-CN": "🚫 GitHub 授权被拒绝，账号未绑定。",
+        "en": "🚫 GitHub authorization was denied; no account was linked."
+    },
+    "bindFailed": {
+        "zh-CN": "❌ GitHub 账号绑定失败: {error}",
+        "en": "❌ GitHub account linking failed: {error}"
+    },
+    "bindVerifyFailed": {
+        "zh-CN": "❌ 已获得授权，但无法确认 GitHub 账号身份，账号未绑定。请重新发起账号绑定。",
+        "en": "❌ Authorization succeeded, but the GitHub account could not be verified; no account was linked. Start account linking again."
+    },
     "flowFailed": {
         "zh-CN": "❌ Device Flow 启动失败: {error}",
         "en": "❌ Could not start Device Flow: {error}"

package/agents/github/messages.ts

@@ -33,6 +33,26 @@ export const messages = createMessages({
     "zh-CN": "✅ GitHub 账号绑定成功！\n👤 {login}",
     "en": "✅ GitHub account linked!\n👤 {login}"
   },
+  "bindInProgress": {
+    "zh-CN": "⏳ 已有一个 GitHub 账号绑定正在等待授权，请先完成或等待其过期。",
+    "en": "⏳ A GitHub account link is already waiting for authorization. Finish it or wait for it to expire."
+  },
+  "bindExpired": {
+    "zh-CN": "⌛ GitHub 授权已超时，账号未绑定。请重新发起账号绑定。",
+    "en": "⌛ GitHub authorization timed out; no account was linked. Start account linking again."
+  },
+  "bindDenied": {
+    "zh-CN": "🚫 GitHub 授权被拒绝，账号未绑定。",
+    "en": "🚫 GitHub authorization was denied; no account was linked."
+  },
+  "bindFailed": {
+    "zh-CN": "❌ GitHub 账号绑定失败: {error}",
+    "en": "❌ GitHub account linking failed: {error}"
+  },
+  "bindVerifyFailed": {
+    "zh-CN": "❌ 已获得授权，但无法确认 GitHub 账号身份，账号未绑定。请重新发起账号绑定。",
+    "en": "❌ Authorization succeeded, but the GitHub account could not be verified; no account was linked. Start account linking again."
+  },
   "flowFailed": {
     "zh-CN": "❌ Device Flow 启动失败: {error}",
     "en": "❌ Could not start Device Flow: {error}"

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

@@ -8,6 +8,8 @@ function oauthModel(client) {
     const db = client.database;
     return db?.models?.get('github_oauth_users');
 }
+/** `platform\u0000uid` keys with a device flow still polling. */
+const pendingBinds = new Set();
 function depsLogger() {
     return {
         debug: (...args) => console.debug(...args),
@@ -31,10 +33,24 @@ export async function executeGithubBind(_args, client, commMessage, preference)
     if (existing) {
         return t(locale, 'alreadyBound', { login: existing.github_login });
     }
+    // One device flow per user: a second request would race the first one's insert.
+    const flowKey = `${msg.clientAdapter}\u0000${msg.sender.id}`;
+    if (pendingBinds.has(flowKey))
+        return t(locale, 'bindInProgress');
+    pendingBinds.add(flowKey);
+    const platform = msg.clientAdapter;
+    const senderId = msg.sender.id;
+    const reply = async (text) => {
+        try {
+            await msg.$reply?.(text);
+        }
+        catch (err) {
+            log.warn(formatCompact({ op: 'device_flow_reply', ok: false, platform, sender: senderId, error: err instanceof Error ? err.message : String(err) }));
+        }
+    };
     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 = [
             t(locale, 'openDeviceLink'),
             `   ${codeResp.verification_uri}`,
@@ -43,32 +59,61 @@ export async function executeGithubBind(_args, client, commMessage, preference)
             '',
             t(locale, 'waiting', { minutes: Math.floor(codeResp.expires_in / 60) }),
         ].join('\n');
-        tokenPromise.then(async (tokenData) => {
-            if (!tokenData) {
-                log.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.clientAdapter, sender: msg.sender.id }));
-                return;
+        void (async () => {
+            try {
+                const result = await GhClient.deviceFlowPollToken({
+                    clientId,
+                    deviceCode: codeResp.device_code,
+                    interval: codeResp.interval,
+                    expiresIn: codeResp.expires_in,
+                    host,
+                    signal: client.lifecycleSignal,
+                });
+                // Endpoint stopped: nothing to tell the user through a closed endpoint.
+                if (result.status === 'aborted')
+                    return;
+                if (result.status !== 'authorized') {
+                    log.warn(formatCompact({ op: 'device_flow', ok: false, status: result.status, platform, sender: senderId }));
+                    await reply(result.status === 'error'
+                        ? t(locale, 'bindFailed', { error: result.error })
+                        : result.status === 'expired'
+                            ? t(locale, 'bindExpired')
+                            : t(locale, 'bindDenied'));
+                    return;
+                }
+                const userGh = new GhClient({ host, token: result.access_token, signal: client.lifecycleSignal });
+                const authResult = await userGh.verifyAuth();
+                if (!authResult.ok || !authResult.user) {
+                    log.warn(formatCompact({ op: 'device_flow', ok: false, status: 'verify_failed', platform, sender: senderId }));
+                    await reply(t(locale, 'bindVerifyFailed'));
+                    return;
+                }
+                const login = authResult.user;
+                await model.insert({
+                    id: Date.now(),
+                    platform,
+                    platform_uid: senderId,
+                    github_login: login,
+                    access_token: result.access_token,
+                    created_at: Date.now(),
+                });
+                log.debug(formatCompact({ op: 'bind', platform, sender: senderId, login }));
+                await reply(t(locale, 'bound', { login }));
+            }
+            catch (err) {
+                log.error('GitHub Device Flow 错误:', err);
+                if (!client.lifecycleSignal?.aborted) {
+                    await reply(t(locale, 'bindFailed', { error: err instanceof Error ? err.message : String(err) }));
+                }
             }
-            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.clientAdapter,
-                platform_uid: msg.sender.id,
-                github_login: login,
-                access_token: tokenData.access_token,
-                created_at: Date.now(),
-            });
-            log.debug(formatCompact({ op: 'bind', platform: msg.clientAdapter, sender: msg.sender.id, login }));
-            if (msg?.$reply) {
-                await msg.$reply(t(locale, 'bound', { login }));
+            finally {
+                pendingBinds.delete(flowKey);
             }
-        }).catch((err) => {
-            log.error('GitHub Device Flow 错误:', err);
-        });
+        })();
         return replyMsg;
     }
     catch (e) {
+        pendingBinds.delete(flowKey);
         return t(locale, 'flowFailed', { error: e instanceof Error ? e.message : String(e) });
     }
 }

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

@@ -17,6 +17,9 @@ function oauthModel(client: GithubEndpoint) {
   } | undefined;
 }
 
+/** `platform\u0000uid` keys with a device flow still polling. */
+const pendingBinds = new Set<string>();
+
 function depsLogger() {
   return {
     debug: (...args: unknown[]) => console.debug(...args),
@@ -42,12 +45,24 @@ export async function executeGithubBind(_args: Record<string, never>, client: Gi
     return t(locale, 'alreadyBound', { login: existing.github_login });
   }
 
+  // One device flow per user: a second request would race the first one's insert.
+  const flowKey = `${msg.clientAdapter}\u0000${msg.sender.id}`;
+  if (pendingBinds.has(flowKey)) return t(locale, 'bindInProgress');
+  pendingBinds.add(flowKey);
+
+  const platform = msg.clientAdapter;
+  const senderId = msg.sender.id;
+  const reply = async (text: string): Promise<void> => {
+    try {
+      await msg.$reply?.(text);
+    } catch (err) {
+      log.warn(formatCompact({ op: 'device_flow_reply', ok: false, platform, sender: senderId, error: err instanceof Error ? err.message : String(err) }));
+    }
+  };
+
   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 = [
       t(locale, 'openDeviceLink'),
@@ -58,35 +73,60 @@ export async function executeGithubBind(_args: Record<string, never>, client: Gi
       t(locale, 'waiting', { minutes: Math.floor(codeResp.expires_in / 60) }),
     ].join('\n');
 
-    tokenPromise.then(async (tokenData) => {
-      if (!tokenData) {
-        log.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.clientAdapter, 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.clientAdapter,
-        platform_uid: msg.sender!.id,
-        github_login: login,
-        access_token: tokenData.access_token,
-        created_at: Date.now(),
-      });
-      log.debug(formatCompact({ op: 'bind', platform: msg.clientAdapter, sender: msg.sender!.id, login }));
-
-      if (msg?.$reply) {
-        await msg.$reply(t(locale, 'bound', { login }));
+    void (async () => {
+      try {
+        const result = await GhClient.deviceFlowPollToken({
+          clientId,
+          deviceCode: codeResp.device_code,
+          interval: codeResp.interval,
+          expiresIn: codeResp.expires_in,
+          host,
+          signal: client.lifecycleSignal,
+        });
+        // Endpoint stopped: nothing to tell the user through a closed endpoint.
+        if (result.status === 'aborted') return;
+        if (result.status !== 'authorized') {
+          log.warn(formatCompact({ op: 'device_flow', ok: false, status: result.status, platform, sender: senderId }));
+          await reply(result.status === 'error'
+            ? t(locale, 'bindFailed', { error: result.error })
+            : result.status === 'expired'
+              ? t(locale, 'bindExpired')
+              : t(locale, 'bindDenied'));
+          return;
+        }
+
+        const userGh = new GhClient({ host, token: result.access_token, signal: client.lifecycleSignal });
+        const authResult = await userGh.verifyAuth();
+        if (!authResult.ok || !authResult.user) {
+          log.warn(formatCompact({ op: 'device_flow', ok: false, status: 'verify_failed', platform, sender: senderId }));
+          await reply(t(locale, 'bindVerifyFailed'));
+          return;
+        }
+        const login = authResult.user;
+
+        await model.insert({
+          id: Date.now(),
+          platform,
+          platform_uid: senderId,
+          github_login: login,
+          access_token: result.access_token,
+          created_at: Date.now(),
+        });
+        log.debug(formatCompact({ op: 'bind', platform, sender: senderId, login }));
+        await reply(t(locale, 'bound', { login }));
+      } catch (err) {
+        log.error('GitHub Device Flow 错误:', err);
+        if (!client.lifecycleSignal?.aborted) {
+          await reply(t(locale, 'bindFailed', { error: err instanceof Error ? err.message : String(err) }));
+        }
+      } finally {
+        pendingBinds.delete(flowKey);
       }
-    }).catch((err) => {
-      log.error('GitHub Device Flow 错误:', err);
-    });
+    })();
 
     return replyMsg;
   } catch (e: unknown) {
+    pendingBinds.delete(flowKey);
     return t(locale, 'flowFailed', { error: e instanceof Error ? e.message : String(e) });
   }
 }

package/lib/gh-client.d.ts

@@ -54,6 +54,8 @@ export declare class GhClient {
     protected apiHost?: string;
     protected executionSignal?: AbortSignal;
     protected bindExecutionSignal(signal: AbortSignal): void;
+    /** Aborted when the owning endpoint stops; long-running background work should observe it. */
+    get lifecycleSignal(): AbortSignal | undefined;
     private token?;
     private _appAuth?;
     private _resolvedKey?;
@@ -310,12 +312,30 @@ export declare class GhClient {
         interval: number;
     }>;
     /**
-     * 第二步：轮询等待用户授权
-     * @returns access_token 或 null（超时/拒绝）
+     * 第二步：轮询等待用户授权。
+     * 可通过 `signal` 取消；单次请求有超时；网络/JSON 等瞬时错误会重试到设备码过期为止。
      */
-    static deviceFlowPollToken(clientId: string, deviceCode: string, interval?: number, expiresIn?: number, host?: string): Promise<{
-        access_token: string;
-        token_type: string;
-        scope: string;
-    } | null>;
+    static deviceFlowPollToken({ clientId, deviceCode, interval, expiresIn, host, signal, requestTimeoutMs, }: GhDeviceFlowPollRequest): Promise<GhDeviceFlowPollResult>;
 }
+export interface GhDeviceFlowPollRequest {
+    readonly clientId: string;
+    readonly deviceCode: string;
+    /** Seconds between polls (GitHub default 5). */
+    readonly interval?: number;
+    /** Seconds until the device code expires (GitHub default 900). */
+    readonly expiresIn?: number;
+    readonly host?: string;
+    readonly signal?: AbortSignal;
+    readonly requestTimeoutMs?: number;
+}
+export type GhDeviceFlowPollResult = {
+    readonly status: 'authorized';
+    readonly access_token: string;
+    readonly token_type: string;
+    readonly scope: string;
+} | {
+    readonly status: 'expired' | 'denied' | 'aborted';
+} | {
+    readonly status: 'error';
+    readonly error: string;
+};

package/lib/gh-client.js

@@ -17,6 +17,8 @@ export class GhClient {
     apiHost;
     executionSignal;
     bindExecutionSignal(signal) { this.executionSignal = signal; }
+    /** Aborted when the owning endpoint stops; long-running background work should observe it. */
+    get lifecycleSignal() { return this.executionSignal; }
     token;
     _appAuth;
     _resolvedKey;
@@ -582,40 +584,84 @@ export class GhClient {
         return res.json();
     }
     /**
-     * 第二步：轮询等待用户授权
-     * @returns access_token 或 null（超时/拒绝）
+     * 第二步：轮询等待用户授权。
+     * 可通过 `signal` 取消；单次请求有超时；网络/JSON 等瞬时错误会重试到设备码过期为止。
      */
-    static async deviceFlowPollToken(clientId, deviceCode, interval = 5, expiresIn = 900, host) {
+    static async deviceFlowPollToken({ clientId, deviceCode, interval = 5, expiresIn = 900, host, signal, requestTimeoutMs = 15_000, }) {
         const baseUrl = host ? `https://${host}` : 'https://github.com';
         const deadline = Date.now() + expiresIn * 1000;
         let pollInterval = interval * 1000;
-        while (Date.now() < deadline) {
-            await new Promise(r => setTimeout(r, pollInterval));
-            const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Accept': 'application/json',
-                },
-                body: JSON.stringify({
-                    client_id: clientId,
-                    device_code: deviceCode,
-                    grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-                }),
-            });
-            const data = await res.json();
-            if (data.access_token) {
-                return { access_token: data.access_token, token_type: data.token_type, scope: data.scope };
+        while (true) {
+            if (signal?.aborted)
+                return { status: 'aborted' };
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return { status: 'expired' };
+            if (!await abortableDelay(Math.min(pollInterval, remaining), signal))
+                return { status: 'aborted' };
+            if (Date.now() >= deadline)
+                return { status: 'expired' };
+            let data;
+            try {
+                const timeout = AbortSignal.timeout(requestTimeoutMs);
+                const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Accept': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        client_id: clientId,
+                        device_code: deviceCode,
+                        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                    }),
+                    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+                });
+                data = await res.json();
             }
-            if (data.error === 'slow_down') {
-                pollInterval = (data.interval || interval + 5) * 1000;
+            catch {
+                if (signal?.aborted)
+                    return { status: 'aborted' };
+                // Transient network / timeout / non-JSON response: keep polling until the deadline.
                 continue;
             }
+            if (!data || typeof data !== 'object')
+                continue;
+            if (typeof data.access_token === 'string' && data.access_token) {
+                return {
+                    status: 'authorized',
+                    access_token: data.access_token,
+                    token_type: typeof data.token_type === 'string' ? data.token_type : 'bearer',
+                    scope: typeof data.scope === 'string' ? data.scope : '',
+                };
+            }
             if (data.error === 'authorization_pending')
                 continue;
-            // expired_token / access_denied / 其他错误
-            return null;
+            if (data.error === 'slow_down') {
+                const next = Number(data.interval);
+                pollInterval = (Number.isFinite(next) && next > 0 ? next : pollInterval / 1000 + 5) * 1000;
+                continue;
+            }
+            if (data.error === 'expired_token')
+                return { status: 'expired' };
+            if (data.error === 'access_denied')
+                return { status: 'denied' };
+            if (typeof data.error === 'string') {
+                return { status: 'error', error: typeof data.error_description === 'string' ? data.error_description : data.error };
+            }
+            // No token and no error (e.g. a 5xx JSON body): treat as transient.
         }
-        return null;
     }
 }
+/** Resolves true after `ms`, or false as soon as `signal` aborts. */
+function abortableDelay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve(false);
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); resolve(false); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(true); }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/lib/protocol.d.ts

@@ -1,5 +1,4 @@
 import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
-import type { IncomingMessage } from 'node:http';
 import { type ConversationRef } from '@zhin.js/im-contract';
 import { type GenericWebhookPayload, type IssueCommentPayload, type PRReviewCommentPayload, type PRReviewPayload } from './types.js';
 export type { EventType, GenericWebhookPayload, GitHubComment, GitHubIssue, GitHubOAuthUser, GitHubPR, GitHubRepo, GitHubUser, IssueCommentPayload, ParsedChannel, PRReviewCommentPayload, PRReviewPayload, Subscription, } from './types.js';
@@ -57,13 +56,8 @@ export declare function formatInboundContent(body: string): string;
 /** Build markdown body for Issue/PR comment send. */
 export declare function formatOutboundBody(payload: unknown): string;
 export declare function verifyWebhookSignature(secret: string, rawBody: string, signatureHeader: string | undefined): boolean;
-export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;
-export declare function readTextBody(request: IncomingMessage, options?: {
-    readonly limit?: number;
-}): Promise<string>;
+export declare function headerValue(headers: Headers, name: string): string;
 export declare function parseIssueCommentInbound(payload: IssueCommentPayload): GithubInboundComment | null;
 export declare function parsePrReviewCommentInbound(payload: PRReviewCommentPayload): GithubInboundComment | null;
 export declare function parsePrReviewInbound(payload: PRReviewPayload): GithubInboundComment | null;
 export declare function formatNotification(event: string, p: GenericWebhookPayload): string;
-/** Parse @mentions in markdown into a flat display string (gateway text path). */
-export declare function parseMarkdownMentions(md: string): string;

package/lib/protocol.js

@@ -158,25 +158,7 @@ export function verifyWebhookSignature(secret, rawBody, signatureHeader) {
     }
 }
 export function headerValue(headers, name) {
-    const raw = headers[name] ?? headers[name.toLowerCase()];
-    if (Array.isArray(raw))
-        return raw[0] ?? '';
-    return raw ?? '';
-}
-export async function readTextBody(request, options = {}) {
-    const limit = options.limit ?? 1_048_576;
-    const chunks = [];
-    let size = 0;
-    for await (const chunk of request) {
-        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        size += buffer.length;
-        if (size > limit) {
-            request.destroy();
-            throw new Error(`Request body exceeds ${limit} bytes`);
-        }
-        chunks.push(buffer);
-    }
-    return Buffer.concat(chunks).toString('utf8');
+    return headers.get(name) ?? '';
 }
 export function parseIssueCommentInbound(payload) {
     if (payload.action !== 'created' || !payload.comment)
@@ -275,7 +257,3 @@ export function formatNotification(event, p) {
             return `📬 ${repo}\n📡 ${event}${p.action ? ` (${p.action})` : ''} by ${sender}\n🔗 ${repoUrl}`;
     }
 }
-/** Parse @mentions in markdown into a flat display string (gateway text path). */
-export function parseMarkdownMentions(md) {
-    return md;
-}

package/lib/webhook.d.ts

@@ -1,7 +1,6 @@
 /**
  * GitHub webhook HTTP: verify → parse → admit inbound comments.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
 export interface GithubWebhookHandler {
@@ -10,5 +9,5 @@ export interface GithubWebhookHandler {
     admit(comment: GithubInboundComment, nativeEvent?: unknown): void;
 }
 export declare function registerGithubWebhookRoutes(http: HttpHost, handler: GithubWebhookHandler): HttpRouteRegistration[];
-export declare function handleGithubWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: GithubWebhookHandler): Promise<void>;
+export declare function handleGithubWebhookRequest(request: Request, handler: GithubWebhookHandler): Promise<Response>;
 export declare function dispatchGithubWebhookPayload(event: string, payload: unknown, handler: GithubWebhookHandler): Promise<void>;

package/lib/webhook.js

@@ -1,28 +1,23 @@
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import { headerValue, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, readTextBody, verifyWebhookSignature, } from './protocol.js';
+import { headerValue, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, verifyWebhookSignature, } from './protocol.js';
 const logger = getLogger('github');
 export function registerGithubWebhookRoutes(http, handler) {
     const routePath = handler.config.webhookPath;
     return [
-        http.route('POST', routePath, async (request, response) => {
-            await handleGithubWebhookRequest(request, response, handler);
-        }, { summary: 'GitHub webhook', tags: ['github'] }),
+        http.route('POST', routePath, (request) => handleGithubWebhookRequest(request, handler), { summary: 'GitHub webhook', tags: ['github'] }),
     ];
 }
-export async function handleGithubWebhookRequest(request, response, handler) {
+export async function handleGithubWebhookRequest(request, handler) {
     const secret = handler.config.webhookSecret;
     if (!secret) {
-        response.writeHead(503, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ error: 'Webhook not configured' }));
-        return;
+        return new Response(JSON.stringify({ error: 'Webhook not configured' }), { status: 503, headers: { 'Content-Type': 'application/json' } });
     }
     const signature = headerValue(request.headers, 'x-hub-signature-256');
     const event = headerValue(request.headers, 'x-github-event');
     const deliveryId = headerValue(request.headers, 'x-github-delivery');
     if (!signature || !event) {
-        response.writeHead(400, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ error: 'Missing signature or event header' }));
-        return;
+        return new Response(JSON.stringify({ error: 'Missing signature or event header' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
     }
     try {
         const rawBody = await readTextBody(request);
@@ -33,31 +28,23 @@ export async function handleGithubWebhookRequest(request, response, handler) {
                 error: 'invalid signature',
                 delivery: deliveryId,
             }));
-            response.writeHead(401, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ error: 'Invalid signature' }));
-            return;
+            return new Response(JSON.stringify({ error: 'Invalid signature' }), { status: 401, headers: { 'Content-Type': 'application/json' } });
         }
         let payload;
         try {
             payload = rawBody ? JSON.parse(rawBody) : {};
         }
         catch {
-            response.writeHead(400, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ error: 'Invalid JSON' }));
-            return;
+            return new Response(JSON.stringify({ error: 'Invalid JSON' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
         }
-        response.writeHead(200, { 'Content-Type': 'application/json' });
-        response.end(JSON.stringify({ ok: true }));
         void dispatchGithubWebhookPayload(event, payload, handler).catch((e) => {
             logger.error(`Webhook 事件处理失败 (${event}):`, e);
         });
+        return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { 'Content-Type': 'application/json' } });
     }
     catch (error) {
         logger.error('Webhook error:', error);
-        if (!response.headersSent) {
-            response.writeHead(500, { 'Content-Type': 'application/json' });
-            response.end(JSON.stringify({ error: 'Internal Server Error' }));
-        }
+        return new Response(JSON.stringify({ error: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
     }
 }
 export async function dispatchGithubWebhookPayload(event, payload, handler) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "1.1.26",
+  "version": "1.1.27",
   "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,27 +39,28 @@
     "directory": "plugins/adapters/github"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.32",
-    "@zhin.js/agent-feature": "1.1.16",
-    "@zhin.js/console-contract": "1.1.5",
-    "@zhin.js/core": "1.1.60",
-    "@zhin.js/feature-kit": "1.1.15",
-    "@zhin.js/host-http": "1.1.17",
-    "@zhin.js/im-contract": "1.1.13",
-    "@zhin.js/logger": "1.1.2",
-    "@zhin.js/page": "1.1.17",
-    "@zhin.js/skill": "1.1.16",
-    "@zhin.js/tool": "1.1.18"
+    "zod": "^4.6.7",
+    "@zhin.js/adapter": "1.1.33",
+    "@zhin.js/agent-feature": "1.1.17",
+    "@zhin.js/console-contract": "1.1.6",
+    "@zhin.js/core": "1.2.0",
+    "@zhin.js/feature-kit": "1.1.16",
+    "@zhin.js/host-http": "1.2.0",
+    "@zhin.js/host-http-contract": "1.2.0",
+    "@zhin.js/im-contract": "1.1.14",
+    "@zhin.js/logger": "1.1.3",
+    "@zhin.js/page": "1.1.18",
+    "@zhin.js/skill": "1.1.17",
+    "@zhin.js/tool": "1.1.19"
   },
   "peerDependencies": {
-    "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.32",
-    "@zhin.js/agent": "^1.1.51",
-    "@zhin.js/command": "^1.1.17",
-    "@zhin.js/core": "^1.1.60",
-    "@zhin.js/host-http": "^1.1.17",
-    "@zhin.js/prompt-section": "^1.1.15",
-    "zhin.js": "^1.1.25"
+    "@zhin.js/adapter": "^1.1.33",
+    "@zhin.js/agent": "^1.2.0",
+    "@zhin.js/command": "^1.2.0",
+    "@zhin.js/core": "^1.2.0",
+    "@zhin.js/host-http": "^1.2.0",
+    "@zhin.js/prompt-section": "^1.1.16",
+    "zhin.js": "^1.1.26"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -73,19 +74,15 @@
     },
     "zhin.js": {
       "optional": true
-    },
-    "zod": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
-    "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.51",
-    "@zhin.js/prompt-section": "1.1.15",
-    "zhin.js": "1.1.25"
+    "@zhin.js/agent": "1.2.0",
+    "@zhin.js/prompt-section": "1.1.16",
+    "zhin.js": "1.1.26"
   },
   "files": [
     "adapters",
@@ -137,6 +134,11 @@
       {
         "package": "@zhin.js/page",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/prompt-section",
+        "api": "^1.0.0",
+        "optional": true
       }
     ],
     "plugins": []
@@ -144,6 +146,6 @@
   "scripts": {
     "build": "tsc",
     "clean": "rimraf lib",
-    "test": "NODE_OPTIONS=--experimental-strip-types vitest run --root ../../.. plugins/adapters/github/tests"
+    "test": "vitest run --root ../../.. plugins/adapters/github/tests"
   }
 }

package/schema.json

@@ -26,34 +26,6 @@
       "type": "string",
       "description": "Managed git workspace root"
     },
-    "master": {
-      "type": [
-        "string",
-        "number"
-      ],
-      "description": "框架 master（GitHub user login or id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖",
-      "x-i18n": {
-        "en": {
-          "description": "Framework masters (GitHub user login or id; AI/tool permissions and endpoint management). endpoints[i].master can override this value."
-        }
-      }
-    },
-    "trusted": {
-      "type": "array",
-      "items": {
-        "type": [
-          "string",
-          "number"
-        ],
-        "description": "Trusted GitHub user login or id"
-      },
-      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加",
-      "x-i18n": {
-        "en": {
-          "description": "Framework trusted users, below master authority. endpoints[i].trusted can add users."
-        }
-      }
-    },
     "endpoints": {
       "type": "array",
       "minItems": 1,
@@ -62,34 +34,6 @@
         "type": "object",
         "additionalProperties": false,
         "properties": {
-          "master": {
-            "type": [
-              "string",
-              "number"
-            ],
-            "description": "本 endpoint 的框架 master（GitHub user login or id）；覆盖顶层 master",
-            "x-i18n": {
-              "en": {
-                "description": "Framework masters for this endpoint (GitHub user login or id), overriding the top-level master list."
-              }
-            }
-          },
-          "trusted": {
-            "type": "array",
-            "items": {
-              "type": [
-                "string",
-                "number"
-              ],
-              "description": "Trusted GitHub user login or id"
-            },
-            "description": "本 endpoint 的 trusted 列表",
-            "x-i18n": {
-              "en": {
-                "description": "Trusted users for this endpoint."
-              }
-            }
-          },
           "app_id": {
             "type": [
               "string",

package/src/gh-client.ts

@@ -67,6 +67,8 @@ export class GhClient {
   protected apiHost?: string;
   protected executionSignal?: AbortSignal;
   protected bindExecutionSignal(signal: AbortSignal): void { this.executionSignal = signal; }
+  /** Aborted when the owning endpoint stops; long-running background work should observe it. */
+  get lifecycleSignal(): AbortSignal | undefined { return this.executionSignal; }
   private token?: string;
   private _appAuth?: AppAuth;
   private _resolvedKey?: string;
@@ -691,46 +693,99 @@ export class GhClient {
   }
 
   /**
-   * 第二步：轮询等待用户授权
-   * @returns access_token 或 null（超时/拒绝）
+   * 第二步：轮询等待用户授权。
+   * 可通过 `signal` 取消；单次请求有超时；网络/JSON 等瞬时错误会重试到设备码过期为止。
    */
-  static async deviceFlowPollToken(
-    clientId: string,
-    deviceCode: string,
-    interval: number = 5,
-    expiresIn: number = 900,
-    host?: string,
-  ): Promise<{ access_token: string; token_type: string; scope: string } | null> {
+  static async deviceFlowPollToken({
+    clientId,
+    deviceCode,
+    interval = 5,
+    expiresIn = 900,
+    host,
+    signal,
+    requestTimeoutMs = 15_000,
+  }: GhDeviceFlowPollRequest): Promise<GhDeviceFlowPollResult> {
     const baseUrl = host ? `https://${host}` : 'https://github.com';
     const deadline = Date.now() + expiresIn * 1000;
     let pollInterval = interval * 1000;
 
-    while (Date.now() < deadline) {
-      await new Promise(r => setTimeout(r, pollInterval));
-      const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'Accept': 'application/json',
-        },
-        body: JSON.stringify({
-          client_id: clientId,
-          device_code: deviceCode,
-          grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
-        }),
-      });
-      const data = await res.json() as Record<string, any>;
-      if (data.access_token) {
-        return { access_token: data.access_token, token_type: data.token_type, scope: data.scope };
+    while (true) {
+      if (signal?.aborted) return { status: 'aborted' };
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) return { status: 'expired' };
+      if (!await abortableDelay(Math.min(pollInterval, remaining), signal)) return { status: 'aborted' };
+      if (Date.now() >= deadline) return { status: 'expired' };
+
+      let data: Record<string, unknown>;
+      try {
+        const timeout = AbortSignal.timeout(requestTimeoutMs);
+        const res = await fetch(`${baseUrl}/login/oauth/access_token`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+          },
+          body: JSON.stringify({
+            client_id: clientId,
+            device_code: deviceCode,
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+          }),
+          signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+        });
+        data = await res.json() as Record<string, unknown>;
+      } catch {
+        if (signal?.aborted) return { status: 'aborted' };
+        // Transient network / timeout / non-JSON response: keep polling until the deadline.
+        continue;
       }
+      if (!data || typeof data !== 'object') continue;
+      if (typeof data.access_token === 'string' && data.access_token) {
+        return {
+          status: 'authorized',
+          access_token: data.access_token,
+          token_type: typeof data.token_type === 'string' ? data.token_type : 'bearer',
+          scope: typeof data.scope === 'string' ? data.scope : '',
+        };
+      }
+      if (data.error === 'authorization_pending') continue;
       if (data.error === 'slow_down') {
-        pollInterval = (data.interval || interval + 5) * 1000;
+        const next = Number(data.interval);
+        pollInterval = (Number.isFinite(next) && next > 0 ? next : pollInterval / 1000 + 5) * 1000;
         continue;
       }
-      if (data.error === 'authorization_pending') continue;
-      // expired_token / access_denied / 其他错误
-      return null;
+      if (data.error === 'expired_token') return { status: 'expired' };
+      if (data.error === 'access_denied') return { status: 'denied' };
+      if (typeof data.error === 'string') {
+        return { status: 'error', error: typeof data.error_description === 'string' ? data.error_description : data.error };
+      }
+      // No token and no error (e.g. a 5xx JSON body): treat as transient.
     }
-    return null;
   }
 }
+
+export interface GhDeviceFlowPollRequest {
+  readonly clientId: string;
+  readonly deviceCode: string;
+  /** Seconds between polls (GitHub default 5). */
+  readonly interval?: number;
+  /** Seconds until the device code expires (GitHub default 900). */
+  readonly expiresIn?: number;
+  readonly host?: string;
+  readonly signal?: AbortSignal;
+  readonly requestTimeoutMs?: number;
+}
+
+export type GhDeviceFlowPollResult =
+  | { readonly status: 'authorized'; readonly access_token: string; readonly token_type: string; readonly scope: string }
+  | { readonly status: 'expired' | 'denied' | 'aborted' }
+  | { readonly status: 'error'; readonly error: string };
+
+/** Resolves true after `ms`, or false as soon as `signal` aborts. */
+function abortableDelay(ms: number, signal?: AbortSignal): Promise<boolean> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) { resolve(false); return; }
+    const onAbort = () => { clearTimeout(timer); resolve(false); };
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(true); }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}

package/src/protocol.ts

@@ -5,7 +5,6 @@ import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
  */
 
 import { createHmac, timingSafeEqual } from 'node:crypto';
-import type { IncomingMessage } from 'node:http';
 import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
@@ -242,32 +241,12 @@ export function verifyWebhookSignature(
 }
 
 export function headerValue(
-  headers: IncomingMessage['headers'],
+  headers: Headers,
   name: string,
 ): string {
-  const raw = headers[name] ?? headers[name.toLowerCase()];
-  if (Array.isArray(raw)) return raw[0] ?? '';
-  return raw ?? '';
+  return headers.get(name) ?? '';
 }
 
-export async function readTextBody(
-  request: IncomingMessage,
-  options: { readonly limit?: number } = {},
-): Promise<string> {
-  const limit = options.limit ?? 1_048_576;
-  const chunks: Buffer[] = [];
-  let size = 0;
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > limit) {
-      request.destroy();
-      throw new Error(`Request body exceeds ${limit} bytes`);
-    }
-    chunks.push(buffer);
-  }
-  return Buffer.concat(chunks).toString('utf8');
-}
 
 export function parseIssueCommentInbound(payload: IssueCommentPayload): GithubInboundComment | null {
   if (payload.action !== 'created' || !payload.comment) return null;
@@ -366,8 +345,3 @@ export function formatNotification(event: string, p: GenericWebhookPayload): str
       return `📬 ${repo}\n📡 ${event}${p.action ? ` (${p.action})` : ''} by ${sender}\n🔗 ${repoUrl}`;
   }
 }
-
-/** Parse @mentions in markdown into a flat display string (gateway text path). */
-export function parseMarkdownMentions(md: string): string {
-  return md;
-}

package/src/webhook.ts

@@ -1,15 +1,14 @@
 /**
  * GitHub webhook HTTP: verify → parse → admit inbound comments.
  */
-import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { readTextBody } from '@zhin.js/host-http-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import {
   headerValue,
   parseIssueCommentInbound,
   parsePrReviewCommentInbound,
   parsePrReviewInbound,
-  readTextBody,
   verifyWebhookSignature,
   type GithubInboundComment,
   type IssueCommentPayload,
@@ -32,22 +31,17 @@ export function registerGithubWebhookRoutes(
 ): HttpRouteRegistration[] {
   const routePath = handler.config.webhookPath;
   return [
-    http.route('POST', routePath, async (request, response) => {
-      await handleGithubWebhookRequest(request, response, handler);
-    }, { summary: 'GitHub webhook', tags: ['github'] }),
+    http.route('POST', routePath, (request) => handleGithubWebhookRequest(request, handler), { summary: 'GitHub webhook', tags: ['github'] }),
   ];
 }
 
 export async function handleGithubWebhookRequest(
-  request: IncomingMessage,
-  response: ServerResponse,
+  request: Request,
   handler: GithubWebhookHandler,
-): Promise<void> {
+): Promise<Response> {
   const secret = handler.config.webhookSecret;
   if (!secret) {
-    response.writeHead(503, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ error: 'Webhook not configured' }));
-    return;
+    return new Response(JSON.stringify({ error: 'Webhook not configured' }), { status: 503, headers: { 'Content-Type': 'application/json' } });
   }
 
   const signature = headerValue(request.headers, 'x-hub-signature-256');
@@ -55,9 +49,7 @@ export async function handleGithubWebhookRequest(
   const deliveryId = headerValue(request.headers, 'x-github-delivery');
 
   if (!signature || !event) {
-    response.writeHead(400, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ error: 'Missing signature or event header' }));
-    return;
+    return new Response(JSON.stringify({ error: 'Missing signature or event header' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
   }
 
   try {
@@ -69,32 +61,23 @@ export async function handleGithubWebhookRequest(
         error: 'invalid signature',
         delivery: deliveryId,
       }));
-      response.writeHead(401, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ error: 'Invalid signature' }));
-      return;
+      return new Response(JSON.stringify({ error: 'Invalid signature' }), { status: 401, headers: { 'Content-Type': 'application/json' } });
     }
 
     let payload: unknown;
     try {
       payload = rawBody ? JSON.parse(rawBody) : {};
     } catch {
-      response.writeHead(400, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ error: 'Invalid JSON' }));
-      return;
+      return new Response(JSON.stringify({ error: 'Invalid JSON' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
     }
 
-    response.writeHead(200, { 'Content-Type': 'application/json' });
-    response.end(JSON.stringify({ ok: true }));
-
     void dispatchGithubWebhookPayload(event, payload, handler).catch((e) => {
       logger.error(`Webhook 事件处理失败 (${event}):`, e);
     });
+    return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { 'Content-Type': 'application/json' } });
   } catch (error) {
     logger.error('Webhook error:', error);
-    if (!response.headersSent) {
-      response.writeHead(500, { 'Content-Type': 'application/json' });
-      response.end(JSON.stringify({ error: 'Internal Server Error' }));
-    }
+    return new Response(JSON.stringify({ error: 'Internal Server Error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
   }
 }