@zhin.js/adapter-github 6.0.0 → 6.0.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @zhin.js/adapter-github
 
+## 6.0.1
+
+### Patch Changes
+
+- 54bfd6b: Introduce Prompt Sections as a generation-owned Plugin Runtime Feature. Projects can declare typed context under `agent/prompt-sections/`, select interactive or scheduled profiles and IM platforms, and govern presentation order separately from required/preferred/opportunistic budget retention. In-flight turns remain pinned to their original generation across hot reloads, required policy fails explicitly when it cannot fit, duplicate identities are rejected, and the previous mutable Agent-local discovery and platform contributor APIs are removed. ICQQ and GitHub platform guidance now use the same Feature instead of a module-global registry.
+
+  Expose a content-free Prompt Section catalog through Console introspection, including owner, source, generation, profiles, and budget policy without disclosing prompt text. New AI projects mount the Feature automatically, and the full-bot example plus Chinese and English product documentation demonstrate the supported configuration.
+
+- 1fc78bc: Unify native platform Client access behind the literal `adapter` discriminant. Handlers infer both native events and Clients, while command, inbound/outbound middleware, and both Agent tool authoring surfaces expose the exact operation-scoped Client through a lazy `$client` getter. Definitions without `adapter` keep `$client` typed as `unknown`, and runtime dispatch rejects adapter mismatches before resolving the Client. Bundled platform tools now use this single path instead of model-provided endpoint ids and adapter-specific dependency wrappers. Every adapter registers one Client/EventMap contract, and protocol adapters including NapCat, Milky, OneBot and Satori now produce transport-independent Client objects rather than letting Endpoint instances impersonate Clients.
+- Updated dependencies [e9c6a73]
+- Updated dependencies [4e8117c]
+- Updated dependencies [902fa35]
+- Updated dependencies [54bfd6b]
+- Updated dependencies [12025ee]
+- Updated dependencies [09b14d6]
+- Updated dependencies [1fc78bc]
+  - @zhin.js/agent@1.1.16
+  - @zhin.js/adapter@1.2.1
+  - @zhin.js/prompt-section@0.0.1
+  - @zhin.js/core@1.5.14
+  - @zhin.js/host-http@1.0.13
+  - @zhin.js/command@1.0.16
+  - @zhin.js/logger@1.0.77
+  - zhin.js@6.0.14
+  - @zhin.js/feature-kit@1.0.13
+
 ## 6.0.0
 
 ### Patch Changes

package/README.md

@@ -5,7 +5,7 @@ GitHub Plugin Runtime 适配器 — Issue/PR 评论区即聊天通道，GitHub A
 ## 功能特性
 
 - **聊天通道**：Issue/PR 评论区映射为群聊，支持收发消息
-- **Webhook 入站**：HMAC-SHA256 验签 → `messageGatewayToken`
+- **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 等保留
@@ -18,6 +18,13 @@ pnpm add @zhin.js/adapter-github
 
 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
@@ -84,9 +91,18 @@ plugins:
 | `src/protocol.ts` | 协议纯函数（channel / payload） |
 | `src/gh-client.ts` | GitHub API 客户端 |
 
-- 入站：`httpHostToken` POST → `messageGatewayToken.receive`
+- 入站：`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

@@ -4,7 +4,6 @@
  * Implementation lives under `src/` (endpoint / webhook / oauth / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import { databaseHostToken, } from 'zhin.js';
 import { GithubEndpoint } from "../lib/endpoint.js";
@@ -28,8 +27,6 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveGithubConfig(context.config);
-        const gateway = context.use(messageGatewayToken);
-        const sideEvents = context.use(sideEventGatewayToken);
         const database = optionalDatabase(context);
         // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
         context.use(githubRuntimeStateToken).endpoints.set(config.id, {
@@ -39,8 +36,6 @@ export default defineAdapter({
         if (config.webhookSecret) {
             return new GithubEndpoint({
                 id: context.id,
-                gateway,
-                sideEvents,
                 http: context.use(httpHostToken),
                 database,
                 config,
@@ -49,8 +44,6 @@ export default defineAdapter({
         // API-only: Issue/PR send + agent tools without webhook.
         return new GithubEndpoint({
             id: context.id,
-            gateway,
-            sideEvents,
             database,
             config,
         });

package/adapters/github.ts

@@ -3,7 +3,6 @@
  * Implementation lives under `src/` (endpoint / webhook / oauth / protocol).
  */
 import { defineAdapter, type AdapterContext } from 'zhin.js/adapter';
-import { messageGatewayToken, sideEventGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   databaseHostToken,
@@ -36,8 +35,6 @@ export default defineAdapter<GithubAdapterConfig>({
   },
   create(context) {
     const config = resolveGithubConfig(context.config);
-    const gateway = context.use(messageGatewayToken);
-    const sideEvents = context.use(sideEventGatewayToken);
     const database = optionalDatabase(context);
     // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
     context.use(githubRuntimeStateToken).endpoints.set(config.id, {
@@ -47,8 +44,6 @@ export default defineAdapter<GithubAdapterConfig>({
     if (config.webhookSecret) {
       return new GithubEndpoint({
         id: context.id,
-        gateway,
-        sideEvents,
         http: context.use(httpHostToken),
         database,
         config,
@@ -57,8 +52,6 @@ export default defineAdapter<GithubAdapterConfig>({
     // API-only: Issue/PR send + agent tools without webhook.
     return new GithubEndpoint({
       id: context.id,
-      gateway,
-      sideEvents,
       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/agent/tools/bind.ts

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

package/agent/tools/create_pr.ts

@@ -4,6 +4,7 @@ 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 标题'),
@@ -13,7 +14,7 @@ export default defineAgentTool<{ repo?: string; title: string; body?: string; he
   }),
   tags: ['github'],
   approval: 'always',
-  async execute(input) {
-    return executeGithubCreatePr(input);
+  async execute(input, context) {
+    return executeGithubCreatePr(input, context.$client, context.message);
   },
 });

package/agent/tools/install.ts

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

package/agent/tools/patch_file.ts

@@ -4,6 +4,7 @@ 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('仓库内文件路径'),
@@ -12,7 +13,7 @@ export default defineAgentTool<{ repo?: string; path: string; content: string; m
     branch: z.string().optional().describe('目标分支，缺省从 Issue/PR 上下文推断'),
   }),
   tags: ['github'],
-  async execute(input) {
-    return executeGithubPatchFile(input);
+  async execute(input, context) {
+    return executeGithubPatchFile(input, context.$client, context.message);
   },
 });

package/agent/tools/prepare_workspace.ts

@@ -4,11 +4,12 @@ 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) {
-    return executeGithubPrepareWorkspace(input);
+  async execute(input, context) {
+    return executeGithubPrepareWorkspace(input, context.$client, context.message);
   },
 });

package/agent/tools/push_branch.ts

@@ -4,6 +4,7 @@ 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('分支名，缺省从上下文推断'),
@@ -11,7 +12,7 @@ export default defineAgentTool<{ repo?: string; branch?: string; message: string
   }),
   tags: ['github'],
   approval: 'always',
-  async execute(input) {
-    return executeGithubPushBranch(input);
+  async execute(input, context) {
+    return executeGithubPushBranch(input, context.$client, context.message);
   },
 });

package/agent/tools/star.ts

@@ -4,12 +4,13 @@ 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) {
-    return executeGithubStar(input);
+  async execute(input, context) {
+    return executeGithubStar(input, context.$client, context.message);
   },
 });

package/agent/tools/subscribe.ts

@@ -8,9 +8,9 @@ export default defineAgentTool<{ repo: string; events?: string }>({
     repo: z.string().min(1),
     events: z.string().optional(),
   }),
-  platforms: ['github'],
+  adapter: 'github',
   tags: ['github'],
-  async execute(input) {
-    return executeGithubSubscribe(input);
+  async execute(input, context) {
+    return executeGithubSubscribe(input, context.$client, context.message);
   },
 });

package/agent/tools/subscriptions.ts

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

package/agent/tools/unbind.ts

@@ -2,11 +2,12 @@ import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubUnbind } from '../../src/github-tool-handlers.js';
 
-export default defineAgentTool({
+export default defineAgentTool<{}>({
   description: '解除你绑定的 GitHub 账号',
+  adapter: 'github',
   inputSchema: z.object({}),
   tags: ['github'],
-  async execute() {
-    return executeGithubUnbind({});
+  async execute(input, context) {
+    return executeGithubUnbind({}, context.$client, context.message);
   },
 });

package/agent/tools/unsubscribe.ts

@@ -7,9 +7,9 @@ export default defineAgentTool<{ repo: string }>({
   inputSchema: z.object({
     repo: z.string().min(1),
   }),
-  platforms: ['github'],
+  adapter: 'github',
   tags: ['github'],
-  async execute(input) {
-    return executeGithubUnsubscribe(input);
+  async execute(input, context) {
+    return executeGithubUnsubscribe(input, context.$client, context.message);
   },
 });

package/agent/tools/whoami.ts

@@ -2,11 +2,12 @@ import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { executeGithubWhoami } from '../../src/github-tool-handlers.js';
 
-export default defineAgentTool({
+export default defineAgentTool<{}>({
   description: '查看你绑定的 GitHub 账号信息',
+  adapter: 'github',
   inputSchema: z.object({}),
   tags: ['github'],
-  async execute() {
-    return executeGithubWhoami({});
+  async execute(input, context) {
+    return executeGithubWhoami({}, context.$client, context.message);
   },
 });

package/lib/client.d.ts

@@ -0,0 +1,36 @@
+import type { PluginDatabaseHost } from 'zhin.js';
+import { GhClient } from './gh-client.js';
+import type { ResolvedGithubConfig } from './protocol.js';
+import { WorkspaceManager } from './workspace-manager.js';
+/** GitHub SDK surface exposed to plugin handlers and Agent tools. */
+export declare class GithubClient {
+    #private;
+    readonly name: string;
+    readonly api: GhClient;
+    readonly config: ResolvedGithubConfig;
+    readonly database?: PluginDatabaseHost | undefined;
+    constructor(name: string, api: GhClient, config: ResolvedGithubConfig, database?: PluginDatabaseHost | undefined);
+    getUserOrDefaultApi(platform?: string, platformUid?: string): Promise<GhClient>;
+    get clientId(): string | null;
+    get host(): string | undefined;
+    get appSlug(): string | null;
+    get installations(): {
+        id: number;
+        account: {
+            login: string;
+            type: string;
+        };
+        target_type: string;
+    }[];
+    get workspaceManager(): WorkspaceManager;
+}
+export type GithubClientEventMap = Record<string, unknown>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly github: {
+            readonly client: GithubClient;
+            readonly events: GithubClientEventMap;
+        };
+    }
+}
+export declare const githubClient: import("@zhin.js/adapter").EndpointClientToken<GithubClient, GithubClientEventMap>;

package/lib/client.js

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import { defineEndpointClient } from 'zhin.js/adapter';
+import { lookupGithubOauthAccessToken } from './oauth-users.js';
+import { WorkspaceManager } from './workspace-manager.js';
+/** GitHub SDK surface exposed to plugin handlers and Agent tools. */
+export class GithubClient {
+    name;
+    api;
+    config;
+    database;
+    #workspaceManager;
+    constructor(name, api, config, database) {
+        this.name = name;
+        this.api = api;
+        this.config = config;
+        this.database = database;
+    }
+    async getUserOrDefaultApi(platform, platformUid) {
+        if (platform && platformUid) {
+            const token = await lookupGithubOauthAccessToken(this.database, platform, platformUid);
+            if (token)
+                return this.api.withToken(token);
+        }
+        return this.api;
+    }
+    get clientId() {
+        return this.api.clientId || null;
+    }
+    get host() {
+        return this.config.host;
+    }
+    get appSlug() {
+        return this.api.appSlug || null;
+    }
+    get installations() {
+        return this.api.installations || [];
+    }
+    get workspaceManager() {
+        if (!this.#workspaceManager) {
+            const root = this.config.workspaceRoot
+                ?? path.join(process.cwd(), 'data', 'github-workspaces');
+            this.#workspaceManager = new WorkspaceManager(this.api, root);
+        }
+        return this.#workspaceManager;
+    }
+}
+export const githubClient = defineEndpointClient('github');

package/lib/endpoint.d.ts

@@ -1,14 +1,15 @@
-import type { EndpointInstance, EndpointSendRequest } from 'zhin.js/adapter';
-import type { MessageGateway, SideEventGateway } from '@zhin.js/core/runtime';
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
+ */
+import { type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId, PluginDatabaseHost } from 'zhin.js';
 import { GhClient } from './gh-client.js';
 import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
-import { WorkspaceManager } from './workspace-manager.js';
+import { GithubClient } from './client.js';
 export interface GithubEndpointOptions {
     readonly id: CapabilityId;
-    readonly gateway: MessageGateway;
-    readonly sideEvents?: SideEventGateway;
     readonly http?: HttpHost;
     readonly database?: PluginDatabaseHost;
     readonly config: ResolvedGithubConfig;
@@ -18,27 +19,11 @@ export interface GithubEndpointOptions {
  * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export declare class GithubEndpoint implements EndpointInstance {
+export declare class GithubEndpoint extends Endpoint<GithubClient> {
     #private;
-    readonly gh: GhClient;
-    readonly config: ResolvedGithubConfig;
-    readonly name: string;
+    readonly client: GithubClient;
     constructor(options: GithubEndpointOptions);
-    getAPI(): GhClient;
-    getUserOrDefaultAPI(platform?: string, platformUid?: string): Promise<GhClient | null>;
-    getClientId(): string | null;
-    getHost(): string | undefined;
-    getAppSlug(): string | null;
-    getInstallations(): {
-        id: number;
-        account: {
-            login: string;
-            type: string;
-        };
-        target_type: string;
-    }[];
-    getWorkspaceManager(): WorkspaceManager;
-    getDatabase(): PluginDatabaseHost | undefined;
+    get config(): ResolvedGithubConfig;
     start(): Promise<void>;
     open(): void;
     close(): void;
@@ -46,5 +31,6 @@ export declare class GithubEndpoint implements EndpointInstance {
     send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed comment when open. */
     admit(comment: GithubInboundComment): void;
+    admitPlatform(name: string, event: unknown): void;
 }
 export declare function defaultCreateClient(config: ResolvedGithubConfig): GhClient;