@zhin.js/adapter-github 1.1.17 → 1.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -39,25 +39,28 @@
     "directory": "plugins/adapters/github"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.24",
-    "@zhin.js/agent-feature": "1.1.10",
-    "@zhin.js/core": "1.1.52",
-    "@zhin.js/feature-kit": "1.1.9",
-    "@zhin.js/host-http": "1.1.11",
-    "@zhin.js/im-contract": "1.1.8",
+    "@zhin.js/adapter": "1.1.26",
+    "@zhin.js/agent-feature": "1.1.11",
+    "@zhin.js/client": "1.1.22",
+    "@zhin.js/console-contract": "1.1.3",
+    "@zhin.js/core": "1.1.54",
+    "@zhin.js/feature-kit": "1.1.10",
+    "@zhin.js/host-http": "1.1.12",
+    "@zhin.js/im-contract": "1.1.9",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/skill": "1.1.10",
-    "@zhin.js/tool": "1.1.11"
+    "@zhin.js/page": "1.1.11",
+    "@zhin.js/skill": "1.1.11",
+    "@zhin.js/tool": "1.1.13"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.24",
-    "@zhin.js/agent": "^1.1.43",
-    "@zhin.js/command": "^1.1.11",
-    "@zhin.js/core": "^1.1.52",
-    "@zhin.js/host-http": "^1.1.11",
-    "@zhin.js/prompt-section": "^1.1.9",
-    "zhin.js": "^1.1.17"
+    "@zhin.js/adapter": "^1.1.26",
+    "@zhin.js/agent": "^1.1.45",
+    "@zhin.js/command": "^1.1.12",
+    "@zhin.js/core": "^1.1.54",
+    "@zhin.js/host-http": "^1.1.12",
+    "@zhin.js/prompt-section": "^1.1.10",
+    "zhin.js": "^1.1.19"
   },
   "peerDependenciesMeta": {
     "@zhin.js/agent": {
@@ -81,13 +84,14 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.43",
-    "@zhin.js/prompt-section": "1.1.9",
-    "zhin.js": "1.1.17"
+    "@zhin.js/agent": "1.1.45",
+    "@zhin.js/prompt-section": "1.1.10",
+    "zhin.js": "1.1.19"
   },
   "files": [
     "adapters",
     "commands",
+    "pages",
     "plugin.js",
     "schema.json",
     "src",
@@ -113,7 +117,7 @@
     "features": [
       {
         "package": "@zhin.js/adapter",
-        "api": "^1.0.0"
+        "api": "^2.0.0"
       },
       {
         "package": "@zhin.js/command",
@@ -130,6 +134,10 @@
       {
         "package": "@zhin.js/agent-feature",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/page",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/pages/index/index.js

@@ -0,0 +1,15 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+export const meta = definePage({
+    title: 'GitHub',
+    titleI18n: { en: 'GitHub' },
+    icon: 'Github',
+    order: 63,
+    requiredPermissions: ['github:read'],
+});
+/**
+ * Convention page: `pages/index/index.ts` → `/github`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('github');

package/pages/index/index.ts

@@ -0,0 +1,16 @@
+import { definePage } from '@zhin.js/console-contract';
+import { createAdapterConsolePage } from '@zhin.js/client';
+
+export const meta = definePage({
+  title: 'GitHub',
+  titleI18n: { en: 'GitHub' },
+  icon: 'Github',
+  order: 63,
+  requiredPermissions: ['github:read'],
+});
+
+/**
+ * Convention page: `pages/index/index.ts` → `/github`（插件路径）。
+ * 连接状态、连接测试、endpoint 增删；登录待办来自 LoginAssist（ICQQ 等）。
+ */
+export default createAdapterConsolePage('github');

package/plugin.js

@@ -1,8 +1,7 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { createEndpointRuntimeState } from 'zhin.js/adapter';
-import { definePlugin, databaseHostToken } from 'zhin.js';
-import { githubRuntimeStateToken } from "./lib/github-runtime-state.js";
+import { definePlugin, databaseHostToken, pluginConsoleRpcToken } from 'zhin.js';
 import { defineGithubOauthUsersTable } from "./lib/oauth-users.js";
+import { createGithubConsoleRpc } from "./lib/console.js";
 /**
  * github_subscriptions — repo event subscriptions per chat channel
  * (used by github_subscriptions agent tool; schema is registered through DatabaseHost).
@@ -28,7 +27,7 @@ export default definePlugin({
     },
     setup(context) {
         // 运行中 endpoint 注册表（github endpoint list 的"运行中"数据源）
-        context.resources.provide(githubRuntimeStateToken, createEndpointRuntimeState());
+        context.resources.provide(pluginConsoleRpcToken, createGithubConsoleRpc(context.resources, () => context.config.get()));
         if (context.resources.has(databaseHostToken)) {
             const host = context.resources.use(databaseHostToken);
             defineGithubOauthUsersTable(host);

package/src/adapter.ts

@@ -0,0 +1,32 @@
+import { GhClient } from './gh-client.js';
+import { Adapter, type AdapterContext, type EndpointCreationContext } from 'zhin.js/adapter';
+import { GithubEndpoint } from './endpoint.js';
+import { resolveGithubConfig, type GithubEndpointConfig } from './protocol.js';
+import type { GithubClientEventMap } from './client.js';
+import { httpHostToken } from '@zhin.js/host-http';
+import { databaseHostToken } from 'zhin.js';
+
+export class GithubAdapter extends Adapter<GithubEndpoint, GithubEndpointConfig, GithubClientEventMap> {
+  readonly #context: AdapterContext<GithubEndpointConfig>;
+  constructor(context: AdapterContext<GithubEndpointConfig>) { super(); this.#context = context; }
+  override get configurationIdentityFields(): readonly string[] { return ['id', 'app_id', 'host']; }
+  override get configurationUpdateFields(): readonly string[] { return ['private_key', 'webhook_secret', 'webhook_path', 'auto_reply_repos', 'bot_login', 'workspace_root']; }
+  override get configurationIdentityProbeFields(): readonly string[] { return ['private_key']; }
+  protected override async identifyConfiguration(input: GithubEndpointConfig, signal: AbortSignal, _changed: readonly string[]): Promise<string | undefined> {
+    const config = resolveGithubConfig(input), client = new GhClient({ host: config.host, appAuth: { appId: config.appId, privateKey: config.privateKey }, signal });
+    const authenticated = await client.verifyAuth(); signal.throwIfAborted();
+    if (!authenticated.ok) throw new Error('GitHub application identity verification failed');
+    const identity = await client.getBotIdentity(); signal.throwIfAborted();
+    if (!identity?.userId) throw new Error('GitHub identity verification returned no bot userId');
+    return JSON.stringify(['github', config.host ?? 'github.com', identity.userId]);
+  }
+  protected override validateConfiguration(config: GithubEndpointConfig): void { resolveGithubConfig(config); }
+  protected createEndpoint(input: GithubEndpointConfig, execution: EndpointCreationContext): GithubEndpoint {
+    const config = resolveGithubConfig(input);
+    return new GithubEndpoint({ id: execution.canonicalId, config, ...(config.webhookSecret ? { http: this.#context.use(httpHostToken) } : {}), ...(this.#context.has?.(databaseHostToken) ? { database: this.#context.use(databaseHostToken) } : {}) });
+  }
+}
+
+declare module '@zhin.js/feature-kit' {
+  interface AdapterRegistry { readonly 'github': GithubAdapter; }
+}

package/src/client.ts

@@ -1,62 +1 @@
-import type { PluginDatabaseHost } from 'zhin.js';
-import { defineEndpointClient } from 'zhin.js/adapter';
-import { GhClient } from './gh-client.js';
-import { lookupGithubOauthAccessToken } from './oauth-users.js';
-import type { ResolvedGithubConfig } from './protocol.js';
-import { WorkspaceManager } from './workspace-manager.js';
-
-/** GitHub SDK surface exposed to plugin handlers and Agent tools. */
-export class GithubClient {
-  #workspaceManager?: WorkspaceManager;
-
-  constructor(
-    readonly name: string,
-    readonly api: GhClient,
-    readonly config: ResolvedGithubConfig,
-    readonly database?: PluginDatabaseHost,
-  ) {}
-
-  async getUserOrDefaultApi(platform?: string, platformUid?: string): Promise<GhClient> {
-    if (platform && platformUid) {
-      const token = await lookupGithubOauthAccessToken(this.database, platform, platformUid);
-      if (token) return this.api.withToken(token);
-    }
-    return this.api;
-  }
-
-  get clientId(): string | null {
-    return this.api.clientId || null;
-  }
-
-  get host(): string | undefined {
-    return this.config.host;
-  }
-
-  get appSlug(): string | null {
-    return this.api.appSlug || null;
-  }
-
-  get installations() {
-    return this.api.installations || [];
-  }
-
-  get workspaceManager(): WorkspaceManager {
-    if (!this.#workspaceManager) {
-      this.#workspaceManager = new WorkspaceManager(this.api, this.config.workspaceRoot);
-    }
-    return this.#workspaceManager;
-  }
-}
-
 export type GithubClientEventMap = Record<string, unknown>;
-
-declare module '@zhin.js/feature-kit' {
-  interface AdapterClientRegistry {
-    readonly github: {
-      readonly client: GithubClient;
-      readonly events: GithubClientEventMap;
-    };
-  }
-}
-
-export const githubClient = defineEndpointClient<GithubClient, GithubClientEventMap>('github');

package/src/console-spec.ts

@@ -0,0 +1,17 @@
+/**
+ * GitHub Console 页面元数据（浏览器与服务端共享；不要在这里 import 服务端代码）。
+ */
+import type { AdapterConsoleField } from 'zhin.js/adapter';
+
+export const githubConsoleSpec = {
+  adapterKey: 'github',
+  adapterDisplayName: 'GitHub',
+  fields: [
+    { key: 'app_id', required: true, env: true, description: 'GitHub App ID' },
+    { key: 'private_key', required: true, secret: true, description: 'PEM 文件路径（推荐，如 ./data/xxx.pem）或 PEM 内容', descriptionI18n: { en: 'PEM file path (recommended) or PEM content' } },
+    { key: 'webhook_secret', env: true, description: 'webhook 签名密钥（不配则 API-only）', descriptionI18n: { en: 'Webhook signing secret (API-only when omitted)' } },
+  ] as readonly AdapterConsoleField[],
+  docsUrl: 'https://zhin.js.org/adapters/github',
+  readPermission: 'github:read',
+  writePermission: 'github:write',
+} as const;

package/src/console.ts

@@ -0,0 +1,18 @@
+/**
+ * GitHub Console RPC：运行状态 + endpoint 增删（原 `github endpoint` 聊天命令）。
+ *
+ * 页面绑定 `pages/index`，读取 / 写入分别要求 `<adapter>:read` / `<adapter>:write`。
+ */
+import { createAdapterConsoleRpc, type AdapterConsoleResources } from 'zhin.js/adapter';
+import type { PluginConsoleRpc } from 'zhin.js';
+import { githubConsoleSpec } from './console-spec.js';
+
+export function createGithubConsoleRpc(
+  _resources: AdapterConsoleResources,
+  getConfig: () => unknown,
+): PluginConsoleRpc {
+  return createAdapterConsoleRpc({
+    ...githubConsoleSpec,
+    getConfig,
+  });
+}

package/src/endpoint.ts

@@ -1,8 +1,7 @@
-import { Endpoint } from 'zhin.js/adapter';
+import { createEndpointSpecification, endpointSpec, type Endpoint, type EndpointSendRequest } from 'zhin.js/adapter';
 /**
  * GithubEndpoint — lifecycle, outbound send, inbound admit.
  */
-import { type EndpointSendRequest } from 'zhin.js/adapter';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
 import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId, PluginDatabaseHost } from 'zhin.js';
@@ -17,98 +16,110 @@ import {
   type ResolvedGithubConfig,
 } from './protocol.js';
 import { registerGithubWebhookRoutes } from './webhook.js';
-import { GithubClient } from './client.js';
+import { WorkspaceManager } from './workspace-manager.js';
+import { lookupGithubOauthAccessToken } from './oauth-users.js';
 
 export interface GithubEndpointOptions {
   readonly id: CapabilityId;
   readonly http?: HttpHost;
   readonly database?: PluginDatabaseHost;
   readonly config: ResolvedGithubConfig;
-  readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
 
 /**
  * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
-export class GithubEndpoint extends Endpoint<GithubClient> {
+export class GithubEndpoint extends GhClient implements Endpoint {
+  readonly [endpointSpec] = createEndpointSpecification(this, {
+    start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
+    stop: () => this.#stopFramework(), send: request => this.#sendFramework(request),
+  });
+  #workspaceManager?: WorkspaceManager;
+  get database() { return this.#options.database; }
+  get host(): string | undefined { return this.#options.config.host; }
+  async getUserOrDefaultApi(platform?: string, platformUid?: string): Promise<GhClient> {
+    if (platform && platformUid) { const token = await lookupGithubOauthAccessToken(this.database, platform, platformUid); if (token) return this.withToken(token); }
+    return this;
+  }
+  get workspaceManager(): WorkspaceManager { return this.#workspaceManager ??= new WorkspaceManager(this, this.config.workspaceRoot); }
   readonly #logger!: ReturnType<typeof getAdapterLogger>;
 
   readonly #options: GithubEndpointOptions;
-  readonly client: GithubClient;
   #routeReleases: HttpRouteRegistration[] = [];
   #open = false;
   #started = false;
 
   constructor(options: GithubEndpointOptions) {
-    super();
+    super({ host: options.config.host, appAuth: { appId: options.config.appId, privateKey: options.config.privateKey } });
     this.#logger = getAdapterLogger('github', options.config.id);
     this.#options = options;
-    const api = options.createClient?.(options.config) ?? defaultCreateClient(options.config);
-    this.client = new GithubClient(options.config.id, api, options.config, options.database);
+
   }
 
   get config(): ResolvedGithubConfig {
-    return this.client.config;
+    return this.#options.config;
   }
 
-  async start(): Promise<void> {
+  async #startFramework(signal: AbortSignal): Promise<void> {
+    this.bindExecutionSignal(signal); signal.throwIfAborted();
     if (this.#started) return;
     this.#started = true;
     try {
-      const result = await this.client.api.verifyAuth();
+      const result = await this.verifyAuth();
+      signal.throwIfAborted();
       if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
-      if (this.client.config.webhookSecret) {
+      if (this.#options.config.webhookSecret) {
         if (!this.#options.http) {
           throw new TypeError('GitHub webhook_secret requires httpHostToken');
         }
         this.#routeReleases.push(...registerGithubWebhookRoutes(this.#options.http, this));
         this.#logger.debug(formatCompact({
-          endpoint: this.client.name,
+          endpoint: this.#options.config.id,
           op: 'webhook',
-          path: this.client.config.webhookPath,
+          path: this.#options.config.webhookPath,
         }));
       } else {
         this.#logger.debug(formatCompact({
-          endpoint: this.client.name,
+          endpoint: this.#options.config.id,
           op: 'connect',
           mode: 'api-only',
-          bot: this.client.api.authenticatedUser,
+          bot: this.authenticatedUser,
         }));
       }
     } catch (error) {
-      await this.stop();
+      await this.#stopFramework();
       this.#logger.error('Failed to connect GitHub endpoint:', error);
       throw error;
     }
   }
 
-  open(): void {
+  #openFramework(): void {
     this.#open = true;
   }
 
-  close(): void {
+  #closeFramework(): void {
     this.#open = false;
   }
 
-  async stop(): Promise<void> {
+  async #stopFramework(): Promise<void> {
     this.#open = false;
     for (const release of this.#routeReleases.splice(0)) release();
     this.#started = false;
     this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+  async #sendFramework({ conversation, payload, signal }: EndpointSendRequest): Promise<string> {
     const parsed = parseChannelId(conversation.id);
     if (!parsed) throw new Error(`无效的 GitHub conversation ID: ${conversation.id}`);
     const text = formatOutboundBody(payload);
     const r = parsed.type === 'issue'
-      ? await this.client.api.createIssueComment(parsed.repo, parsed.number, text)
-      : await this.client.api.createPRComment(parsed.repo, parsed.number, text);
+      ? await this.createIssueComment({ repo: parsed.repo, number: parsed.number, body: text, signal })
+      : await this.createPRComment({ repo: parsed.repo, number: parsed.number, body: text, signal });
     if (!r.ok) throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
     this.#logger.debug(formatCompact({
       op: 'github_send',
-      endpoint: this.client.name,
+      endpoint: this.#options.config.id,
       target: `${conversation.kind}:${conversation.id}`,
       messageId: r.data.id,
     }));
@@ -116,25 +127,33 @@ export class GithubEndpoint extends Endpoint<GithubClient> {
   }
 
   /** Test / internal: admit a parsed comment when open. */
-  admit(comment: GithubInboundComment): void {
+  admit(comment: GithubInboundComment, nativeEvent: unknown = comment): void {
+    if (!this.#open) return;
+    void this[endpointSpec].events.run(() => this.#admitComment(comment, nativeEvent)).catch(error => {
+      this.#logger.warn(formatCompact({ op: 'github_gateway_receive_failed', error: error instanceof Error ? error.message : String(error) }));
+    });
+  }
+
+  #admitComment(comment: GithubInboundComment, nativeEvent: unknown = comment): void {
     if (!this.#open) return;
-    const botUser = this.client.config.botLogin
-      || this.client.api.getBotLogin()
-      || this.client.api.authenticatedUser;
+    const botUser = this.#options.config.botLogin
+      || this.getBotLogin()
+      || this.authenticatedUser;
     if (botUser && comment.sender === botUser) return;
     const conversation = githubInboundConversation(String(this.#options.id), comment);
     const content = enrichInboundContent(
       formatInboundContent(comment.content),
-      this.client.config,
+      this.#options.config,
       botUser ?? undefined,
       comment.repo,
     );
-    void this.emit('message.receive', {
+    void this[endpointSpec].events.emit('message.receive', {
+      event: nativeEvent,
       conversation,
       message: { conversation, id: comment.id },
       content,
       sender: { id: comment.sender, name: comment.sender },
-      endpointId: this.client.name,
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
         repo: comment.repo,
         kind: comment.kind,
@@ -151,7 +170,7 @@ export class GithubEndpoint extends Endpoint<GithubClient> {
 
   admitPlatform(name: string, event: unknown): void {
     if (!this.#open) return;
-    void this.emitPlatform(name, event).catch((error) => {
+    void this[endpointSpec].events.run(() => this[endpointSpec].events.platform(name, event)).catch((error) => {
       this.#logger.warn(formatCompact({
         op: 'github_platform_event_failed',
         event: name,