@zhin.js/adapter-github 3.0.2 → 3.0.3

package/src/endpoint.ts

@@ -1,210 +1,201 @@
 /**
- * GitHub Endpoint 实现（基于 gh CLI）
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
  */
-import { formatCompact, Endpoint, Message, segment, SendContent, SendOptions, type MessageSegment,
-  coerceQrcodeSegmentsToText,
-  expandInteractiveSegmentsInContent,
-} from 'zhin.js';
-import { buildChannelId, parseChannelId, type GitHubEndpointConfig, type IssueCommentPayload, type PRReviewCommentPayload, type PRReviewPayload } from './types.js';
-
-import type { GitHubAdapter } from './adapter.js';
+import path from 'node:path';
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { CapabilityId, DatabaseHost } from '@zhin.js/plugin-runtime';
 import { GhClient } from './gh-client.js';
-import { fromCanonicalSegments, toCanonicalSegments } from './segment-mapper.js';
-
-/** GitHub @mention：支持 zhin-ai[bot] 等 App bot 用户名 */
-const GITHUB_MENTION_RE = /@([^\s@]+(?:\[bot\])?)/g;
-
-export function parseMarkdown(md: string): MessageSegment[] {
-  const segments: MessageSegment[] = [];
-  let lastIdx = 0;
-  let match: RegExpExecArray | null;
-  while ((match = GITHUB_MENTION_RE.exec(md)) !== null) {
-    if (match.index > lastIdx) segments.push({ type: 'text', data: { text: md.slice(lastIdx, match.index) } });
-    segments.push({ type: 'at', data: { id: match[1], name: match[1], text: match[0] } });
-    lastIdx = match.index + match[0].length;
-  }
-  if (lastIdx < md.length) segments.push({ type: 'text', data: { text: md.slice(lastIdx) } });
-  return segments.length ? segments : [{ type: 'text', data: { text: md } }];
+import { registerGithubAgentEndpoint } from './github-agent-deps.js';
+import { lookupGithubOauthAccessToken } from './oauth-users.js';
+import {
+  enrichInboundContent,
+  formatInboundContent,
+  formatOutboundBody,
+  parseChannelId,
+  type GithubInboundComment,
+  type ResolvedGithubConfig,
+} from './protocol.js';
+import { registerGithubWebhookRoutes } from './webhook.js';
+import { WorkspaceManager } from './workspace-manager.js';
+
+const logger = getLogger('github');
+
+export interface GithubEndpointOptions {
+  readonly id: CapabilityId;
+  readonly gateway: MessageGateway;
+  readonly http?: HttpHost;
+  readonly database?: DatabaseHost;
+  readonly config: ResolvedGithubConfig;
+  readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
 
-export function shouldAutoReplyRepo(config: GitHubEndpointConfig, repo: string): boolean {
-  const list = config.auto_reply_repos;
-  if (!list?.length) return false;
-  const key = repo.toLowerCase();
-  return list.some((r) => r.toLowerCase() === key);
-}
+export class GithubEndpoint implements EndpointInstance {
+  readonly #options: GithubEndpointOptions;
+  readonly gh: GhClient;
+  readonly config: ResolvedGithubConfig;
+  readonly name: string;
+  #workspaceManager: WorkspaceManager | null = null;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #open = false;
+  #started = false;
+  #unregisterAgent?: () => void;
+
+  constructor(options: GithubEndpointOptions) {
+    this.#options = options;
+    this.config = options.config;
+    this.name = options.config.name;
+    this.gh = options.createClient?.(options.config) ?? defaultCreateClient(options.config);
+  }
 
-export function enrichGithubInboundMessage<T extends object>(
-  message: Message<T>,
-  config: GitHubEndpointConfig,
-  gh: GhClient,
-  repo: string,
-): Message<T> {
-  const botLogin = config.bot_login || gh.getBotLogin();
-  if (botLogin && shouldAutoReplyRepo(config, repo)) {
-    const hasBotAt = message.$content.some(
-      (seg) => (seg.type === 'at' || seg.type === 'mention') && seg.data?.id === botLogin,
-    );
-    if (!hasBotAt) {
-      message.$content = [
-        { type: 'at', data: { id: botLogin, name: botLogin, text: `@${botLogin}` } },
-        ...message.$content,
-      ];
-    }
+  getAPI(): GhClient {
+    return this.gh;
   }
-  return message;
-}
 
-export function toMarkdown(content: SendContent): string {
-  if (!Array.isArray(content)) content = [content];
-  return content.map(seg => {
-    if (typeof seg === 'string') return seg;
-    switch (seg.type) {
-      case 'text': return seg.data.text || '';
-      case 'mention': return `@${seg.data.name || seg.data.target}`;
-      case 'at': return `@${seg.data.name || seg.data.id}`;
-      case 'image': return seg.data.url ? `![image](${seg.data.url})` : '[image]';
-      case 'link': return `[${seg.data.text || seg.data.url}](${seg.data.url})`;
-      default: return seg.data?.text || `[${seg.type}]`;
+  async getUserOrDefaultAPI(platform?: string, platformUid?: string): Promise<GhClient | null> {
+    if (platform && platformUid) {
+      const token = await lookupGithubOauthAccessToken(
+        this.#options.database,
+        platform,
+        platformUid,
+      );
+      if (token) return this.gh.withToken(token);
     }
-  }).join('');
-}
+    return this.gh;
+  }
 
-export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueCommentPayload> {
-  $connected = false;
-  gh: GhClient;
-  /** App bot 登录名，供 @ 触发匹配 */
-  $platformUserId?: string;
+  getClientId(): string | null {
+    return this.gh.clientId || null;
+  }
 
-  get $id() { return this.$config.name; }
+  getHost(): string | undefined {
+    return this.config.host;
+  }
 
-  get logger() {
-    return this.adapter.plugin.logger;
+  getAppSlug(): string | null {
+    return this.gh.appSlug || null;
   }
 
-  constructor(public adapter: GitHubAdapter, public $config: GitHubEndpointConfig) {
-    const { host, app_id, private_key } = $config;
-    const appAuth = app_id && private_key
-      ? { appId: app_id, privateKey: private_key }
-      : undefined;
-    this.gh = new GhClient({ host, appAuth });
+  getInstallations() {
+    return this.gh.installations || [];
   }
 
-  async $connect(): Promise<void> {
-    const result = await this.gh.verifyAuth();
-    if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
-    this.$platformUserId = this.$config.bot_login || this.gh.getBotLogin() || undefined;
-    this.$connected = true;
-    this.logger.debug(formatCompact({ endpoint: this.$id, bot: this.$platformUserId }));
+  getWorkspaceManager(): WorkspaceManager {
+    if (this.#workspaceManager) return this.#workspaceManager;
+    const workspaceRoot = this.config.workspaceRoot
+      ?? path.join(process.cwd(), 'data', 'github-workspaces');
+    this.#workspaceManager = new WorkspaceManager(this.gh, workspaceRoot);
+    return this.#workspaceManager;
   }
 
-  async $disconnect(): Promise<void> {
-    this.$connected = false;
-    this.logger.debug(formatCompact({ endpoint: this.$id, disconnect: true }));
+  getDatabase(): DatabaseHost | undefined {
+    return this.#options.database;
   }
 
-  $formatMessage(payload: IssueCommentPayload): Message<IssueCommentPayload> {
-    const repo = payload.repository.full_name;
-    const number = payload.issue.number;
-    const isPR = 'pull_request' in (payload.issue as any);
-    const channelId = buildChannelId(repo, isPR ? 'pr' : 'issue', number);
-    const gh = this.gh;
-
-    const result = Message.from(payload, {
-      $id: payload.comment.id.toString(),
-      $adapter: 'github',
-      $endpoint: this.$config.name,
-      $sender: { id: payload.sender.login, name: payload.sender.login },
-      $channel: { id: channelId, type: 'group' },
-      $content: toCanonicalSegments(parseMarkdown(payload.comment.body)),
-      $raw: payload.comment.body,
-      $timestamp: new Date(payload.comment.created_at).getTime(),
-      $recall: async () => { await gh.deleteIssueComment(repo, payload.comment.id); },
-      $reply: async (content: SendContent, quote?: boolean | string): Promise<string> => {
-        const text = toMarkdown(content);
-        const finalBody = quote ? `> ${payload.comment.body.split('\n')[0]}\n\n${text}` : text;
-        const r = await gh.createIssueComment(repo, number, finalBody);
-        return r.ok ? r.data.id.toString() : '';
-      },
-    });
-    return result;
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    try {
+      const result = await this.gh.verifyAuth();
+      if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
+      this.#unregisterAgent = registerGithubAgentEndpoint(this.name, this);
+      if (this.config.webhookSecret) {
+        if (!this.#options.http) {
+          throw new TypeError('GitHub webhook_secret requires httpHostToken');
+        }
+        this.#routeReleases.push(...registerGithubWebhookRoutes(this.#options.http, this));
+        logger.debug(formatCompact({
+          endpoint: this.name,
+          op: 'webhook',
+          path: this.config.webhookPath,
+        }));
+      } else {
+        logger.debug(formatCompact({
+          endpoint: this.name,
+          op: 'connect',
+          mode: 'api-only',
+          bot: this.gh.authenticatedUser,
+        }));
+      }
+    } catch (error) {
+      await this.stop();
+      logger.error('Failed to connect GitHub endpoint:', error);
+      throw error;
+    }
   }
 
-  formatPRReviewComment(payload: PRReviewCommentPayload): Message<PRReviewCommentPayload> {
-    const repo = payload.repository.full_name;
-    const number = payload.pull_request.number;
-    const channelId = buildChannelId(repo, 'pr', number);
-    const gh = this.gh;
-
-    const body = payload.comment.path
-      ? `**${payload.comment.path}**\n${payload.comment.diff_hunk ? '```diff\n' + payload.comment.diff_hunk + '\n```\n' : ''}${payload.comment.body}`
-      : payload.comment.body;
-
-    return Message.from(payload, {
-      $id: payload.comment.id.toString(),
-      $adapter: 'github',
-      $endpoint: this.$config.name,
-      $sender: { id: payload.sender.login, name: payload.sender.login },
-      $channel: { id: channelId, type: 'group' },
-      $content: toCanonicalSegments(parseMarkdown(body)),
-      $raw: body,
-      $timestamp: new Date(payload.comment.created_at).getTime(),
-      $recall: async () => { await gh.deletePRReviewComment(repo, payload.comment.id); },
-      $reply: async (content: SendContent): Promise<string> => {
-        const r = await gh.createPRComment(repo, number, toMarkdown(content));
-        return r.ok ? r.data.id.toString() : '';
-      },
-    });
+  open(): void {
+    this.#open = true;
   }
 
-  formatPRReview(payload: PRReviewPayload): Message<PRReviewPayload> | null {
-    if (!payload.review.body) return null;
-    const repo = payload.repository.full_name;
-    const number = payload.pull_request.number;
-    const channelId = buildChannelId(repo, 'pr', number);
-    const gh = this.gh;
-
-    const stateLabel: Record<string, string> = {
-      approved: '✅ APPROVED', changes_requested: '🔄 CHANGES REQUESTED',
-      commented: '💬 COMMENTED', dismissed: '❌ DISMISSED',
-    };
-    const body = `**[${stateLabel[payload.review.state] || payload.review.state}]**\n${payload.review.body}`;
-
-    return Message.from(payload, {
-      $id: payload.review.id.toString(),
-      $adapter: 'github',
-      $endpoint: this.$config.name,
-      $sender: { id: payload.sender.login, name: payload.sender.login },
-      $channel: { id: channelId, type: 'group' },
-      $content: toCanonicalSegments(parseMarkdown(body)),
-      $raw: body,
-      $timestamp: new Date(payload.review.submitted_at).getTime(),
-      $recall: async () => {},
-      $reply: async (content: SendContent): Promise<string> => {
-        const r = await gh.createPRComment(repo, number, toMarkdown(content));
-        return r.ok ? r.data.id.toString() : '';
-      },
-    });
+  close(): void {
+    this.#open = false;
   }
 
-  async $sendMessage(options: SendOptions): Promise<string> {
-    const parsed = parseChannelId(options.id);
-    if (!parsed) throw new Error(`无效的 GitHub channel ID: ${options.id}`);
+  async stop(): Promise<void> {
+    this.#open = false;
+    for (const release of this.#routeReleases.splice(0)) release();
+    this.#unregisterAgent?.();
+    this.#unregisterAgent = undefined;
+    this.#started = false;
+    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+  }
 
-    const expanded = expandInteractiveSegmentsInContent(coerceQrcodeSegmentsToText(options.content ?? ''));
-    const arr = Array.isArray(expanded) ? expanded : [expanded];
-    const canonical = arr.map((s) => (typeof s === 'string' ? { type: 'text' as const, data: { text: s } } : s));
-    const text = toMarkdown(fromCanonicalSegments(canonical));
+  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+    const parsed = parseChannelId(target);
+    if (!parsed) throw new Error(`无效的 GitHub channel ID: ${target}`);
+    const text = formatOutboundBody(payload);
     const r = parsed.type === 'issue'
       ? await this.gh.createIssueComment(parsed.repo, parsed.number, text)
       : await this.gh.createPRComment(parsed.repo, parsed.number, text);
     if (!r.ok) throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
-
-    this.logger.debug(`${this.$id} send → ${options.id}: ${text.slice(0, 80)}...`);
-    return r.data.id.toString();
+    logger.debug(formatCompact({
+      op: 'github_send',
+      endpoint: this.name,
+      target,
+      messageId: r.data.id,
+    }));
+    return String(r.data.id);
   }
 
-  async $recallMessage(id: string): Promise<void> {
-    this.logger.warn(formatCompact( { op: 'recall', ok: false, error: 'use message.$recall()' }));
+  /** Test / internal: admit a parsed comment when open. */
+  admit(comment: GithubInboundComment): void {
+    if (!this.#open) return;
+    const botUser = this.config.botLogin || this.gh.getBotLogin() || this.gh.authenticatedUser;
+    if (botUser && comment.sender === botUser) return;
+    const content = enrichInboundContent(
+      formatInboundContent(comment.content),
+      this.config,
+      botUser ?? undefined,
+      comment.repo,
+    );
+    void this.#options.gateway.receive({
+      adapter: this.#options.id,
+      target: comment.channelId,
+      content,
+      sender: comment.sender,
+      id: comment.id,
+      metadata: Object.freeze({
+        endpoint: this.name,
+        repo: comment.repo,
+        kind: comment.kind,
+        createdAt: comment.createdAt,
+      }),
+    }).catch((err) => {
+      logger.warn(formatCompact({
+        op: 'github_gateway_receive_failed',
+        target: comment.channelId,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
   }
 }
+
+export function defaultCreateClient(config: ResolvedGithubConfig): GhClient {
+  const appAuth = config.appId && config.privateKey
+    ? { appId: config.appId, privateKey: config.privateKey }
+    : undefined;
+  return new GhClient({ host: config.host, appAuth });
+}

package/src/gh-client.ts

@@ -410,7 +410,7 @@ export class GhClient {
 
   buildCloneUrl(repo: string, token: string): string {
     const host = this.host || 'github.com';
-    return `https://x-access-token:${token}@${host}/${repo}.git`;
+    return `https://x-access-token:${encodeURIComponent(token)}@${host}/${repo}.git`;
   }
 
   async resolveBotUserId(): Promise<number | null> {

package/src/github-agent-deps.ts

@@ -1,27 +1,82 @@
 /**
- * Shared runtime deps for github agent/ authoring tools.
+ * Agent tool deps for github.
+ * Endpoints register themselves on start; tools look up by config name / endpoint id.
  */
-import type { Plugin } from 'zhin.js';
-import type { GitHubAdapter } from './adapter.js';
+
+import type { GhClient } from './gh-client.js';
+import type { ResolvedGithubConfig } from './protocol.js';
 import type { WorkspaceManager } from './workspace-manager.js';
 
+export interface GithubAgentEndpoint {
+  readonly name: string;
+  readonly gh: GhClient;
+  readonly config: ResolvedGithubConfig;
+  getAPI(): GhClient;
+  getUserOrDefaultAPI(platform?: string, platformUid?: string): Promise<GhClient | null>;
+  getClientId(): string | null;
+  getHost(): string | undefined;
+  getAppSlug(): string | null;
+  getInstallations(): Array<{ id: number; account: { login: string; type: string }; target_type: string }>;
+  getWorkspaceManager(): WorkspaceManager;
+  /** DatabaseHost wired at endpoint creation (optional). */
+  getDatabase?(): unknown;
+}
+
 export interface GithubAgentDeps {
-  getAdapter: () => GitHubAdapter;
+  getEndpoint: (endpointId?: string) => GithubAgentEndpoint;
+  /** Alias kept for existing agent handlers that call getAdapter(). */
+  getAdapter: () => GithubAgentEndpoint;
   getWorkspaceManager: () => WorkspaceManager;
-  plugin: Plugin;
+  getDatabase?: () => { models?: Map<string, unknown> } | null | undefined;
+  logger?: {
+    debug: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
 }
 
-let _deps: GithubAgentDeps | null = null;
+const endpoints = new Map<string, GithubAgentEndpoint>();
+let override: GithubAgentDeps | null = null;
+
+export function registerGithubAgentEndpoint(
+  endpointId: string,
+  endpoint: GithubAgentEndpoint,
+): () => void {
+  endpoints.set(endpointId, endpoint);
+  return () => {
+    if (endpoints.get(endpointId) === endpoint) {
+      endpoints.delete(endpointId);
+    }
+  };
+}
+
+/** Optional override used by tests / transitional callers. Pass `null` to clear. */
+export function setGithubAgentDeps(deps: GithubAgentDeps | null): void {
+  override = deps;
+}
 
-export function setGithubAgentDeps(deps: GithubAgentDeps): void {
-  _deps = deps;
+function lookup(endpointId?: string): GithubAgentEndpoint {
+  if (endpointId) {
+    const registered = endpoints.get(endpointId);
+    if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+    return registered;
+  }
+  const first = endpoints.values().next().value;
+  if (!first) throw new Error('github agent deps not initialized');
+  return first;
 }
 
 export function getGithubAgentDeps(): GithubAgentDeps {
-  if (!_deps) throw new Error('github agent deps not initialized');
-  return _deps;
+  if (override) return override;
+  return {
+    getEndpoint: lookup,
+    getAdapter: () => lookup(),
+    getWorkspaceManager: () => lookup().getWorkspaceManager(),
+    getDatabase: () => lookup().getDatabase?.() as
+      { models?: Map<string, unknown> } | null | undefined,
+  };
 }
 
-export function getAdapter(): GitHubAdapter {
+export function getAdapter(): GithubAgentEndpoint {
   return getGithubAgentDeps().getAdapter();
 }

package/src/github-tool-handlers.ts

@@ -1,11 +1,14 @@
-import { formatCompact, type Message } from 'zhin.js';
+import { formatCompact } from '@zhin.js/logger';
+import type { Message } from 'zhin.js';
 import { getCurrentCommMessage } from '@zhin.js/agent/security';
 import { GhClient } from './gh-client.js';
 import type { EventType } from './types.js';
 import { getAdapter, getGithubAgentDeps } from './github-agent-deps.js';
 
 function oauthModel() {
-  const db = getGithubAgentDeps().plugin.root?.inject('database') as any;
+  const db = getGithubAgentDeps().getDatabase?.() as {
+    models?: Map<string, unknown>;
+  } | null | undefined;
   return db?.models?.get('github_oauth_users') as {
     select: () => { where: (q: object) => Promise<any[]> };
     insert: (row: object) => Promise<void>;
@@ -14,7 +17,9 @@ function oauthModel() {
 }
 
 function subscriptionsModel() {
-  const db = getGithubAgentDeps().plugin.root?.inject('database') as any;
+  const db = getGithubAgentDeps().getDatabase?.() as {
+    models?: Map<string, unknown>;
+  } | null | undefined;
   return db?.models?.get('github_subscriptions') as {
     select: () => { where: (q: object) => Promise<any[]> };
     insert: (row: object) => Promise<void>;
@@ -23,6 +28,14 @@ function subscriptionsModel() {
   } | undefined;
 }
 
+function depsLogger() {
+  return getGithubAgentDeps().logger ?? {
+    debug: (...args: unknown[]) => console.debug(...args),
+    warn: (...args: unknown[]) => console.warn(...args),
+    error: (...args: unknown[]) => console.error(...args),
+  };
+}
+
 export async function executeGithubStar(args: { action: 'star' | 'unstar' | 'check'; repo: string }, commMessage?: Message) {
   const adapter = getAdapter();
   const msg = commMessage ?? getCurrentCommMessage();
@@ -48,7 +61,7 @@ export async function executeGithubStar(args: { action: 'star' | 'unstar' | 'che
 
 export async function executeGithubBind(_args: Record<string, never>, commMessage?: Message) {
   const adapter = getAdapter();
-  const { plugin } = getGithubAgentDeps();
+  const log = depsLogger();
   const msg = commMessage ?? getCurrentCommMessage();
   if (!msg?.$adapter || !msg?.$sender?.id) return '❌ 无法获取当前用户信息';
 
@@ -81,7 +94,7 @@ export async function executeGithubBind(_args: Record<string, never>, commMessag
 
     tokenPromise.then(async (tokenData) => {
       if (!tokenData) {
-        plugin.logger.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.$adapter, sender: msg.$sender.id }));
+        log.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.$adapter, sender: msg.$sender.id }));
         return;
       }
 
@@ -97,13 +110,13 @@ export async function executeGithubBind(_args: Record<string, never>, commMessag
         access_token: tokenData.access_token,
         created_at: Date.now(),
       });
-      plugin.logger.debug(formatCompact({ op: 'bind', platform: msg.$adapter, sender: msg.$sender.id, login }));
+      log.debug(formatCompact({ op: 'bind', platform: msg.$adapter, sender: msg.$sender.id, login }));
 
       if (msg?.$reply) {
         await msg.$reply(`✅ GitHub 账号绑定成功！\n👤 ${login}`);
       }
     }).catch((err) => {
-      plugin.logger.error('GitHub Device Flow 错误:', err);
+      log.error('GitHub Device Flow 错误:', err);
     });
 
     return replyMsg;