@zhin.js/adapter-github 1.0.1 → 1.1.0

package/src/endpoint.ts

@@ -1,174 +1,169 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * GitHub Endpoint 实现（基于 gh CLI）
+ * GithubEndpoint — lifecycle, outbound send, inbound admit.
  */
-import { formatCompact, Endpoint, Message, segment, SendContent, SendOptions, type MessageSegment } from 'zhin.js';
-import type {
-  GitHubEndpointConfig,
-  IssueCommentPayload,
-  PRReviewCommentPayload,
-  PRReviewPayload,
-} from './types.js';
-import { buildChannelId, parseChannelId } from './types.js';
-import type { GitHubAdapter } from './adapter.js';
+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';
 import { GhClient } from './gh-client.js';
-
-export function parseMarkdown(md: string): MessageSegment[] {
-  const segments: MessageSegment[] = [];
-  const mentionRe = /@(\w[-\w]*)/g;
-  let lastIdx = 0;
-  let match: RegExpExecArray | null;
-  while ((match = mentionRe.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 {
+  enrichInboundContent,
+  formatInboundContent,
+  formatOutboundBody,
+  githubInboundConversation,
+  parseChannelId,
+  type GithubInboundComment,
+  type ResolvedGithubConfig,
+} from './protocol.js';
+import { registerGithubWebhookRoutes } from './webhook.js';
+import { GithubClient } from './client.js';
+
+export interface GithubEndpointOptions {
+  readonly id: CapabilityId;
+  readonly http?: HttpHost;
+  readonly database?: PluginDatabaseHost;
+  readonly config: ResolvedGithubConfig;
+  readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
 
-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 '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}]`;
-    }
-  }).join('');
-}
-
-export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueCommentPayload> {
-  $connected = false;
-  gh: GhClient;
-
-  get $id() { return this.$config.name; }
-
-  get logger() {
-    return this.adapter.plugin.logger;
-  }
-
-  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 });
+/**
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class GithubEndpoint extends Endpoint<GithubClient> {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: GithubEndpointOptions;
+  readonly client: GithubClient;
+  #routeReleases: HttpRouteRegistration[] = [];
+  #open = false;
+  #started = false;
+
+  constructor(options: GithubEndpointOptions) {
+    super();
+    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);
   }
 
-  async $connect(): Promise<void> {
-    const result = await this.gh.verifyAuth();
-    if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
-    this.$connected = true;
-    this.logger.info(formatCompact({ endpoint: this.$id }));
+  get config(): ResolvedGithubConfig {
+    return this.client.config;
   }
 
-  async $disconnect(): Promise<void> {
-    this.$connected = false;
-    this.logger.debug(formatCompact({ endpoint: this.$id, disconnect: true }));
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    try {
+      const result = await this.client.api.verifyAuth();
+      if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
+      if (this.client.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,
+          op: 'webhook',
+          path: this.client.config.webhookPath,
+        }));
+      } else {
+        this.#logger.debug(formatCompact({
+          endpoint: this.client.name,
+          op: 'connect',
+          mode: 'api-only',
+          bot: this.client.api.authenticatedUser,
+        }));
+      }
+    } catch (error) {
+      await this.stop();
+      this.#logger.error('Failed to connect GitHub endpoint:', error);
+      throw error;
+    }
   }
 
-  $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: 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;
+  open(): void {
+    this.#open = true;
   }
 
-  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: 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() : '';
-      },
-    });
+  close(): void {
+    this.#open = false;
   }
 
-  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: 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() : '';
-      },
-    });
+  async stop(): Promise<void> {
+    this.#open = false;
+    for (const release of this.#routeReleases.splice(0)) release();
+    this.#started = false;
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async $sendMessage(options: SendOptions): Promise<string> {
-    const parsed = parseChannelId(options.id);
-    if (!parsed) throw new Error(`无效的 GitHub channel ID: ${options.id}`);
-
-    const text = toMarkdown(options.content);
+  async send({ conversation, payload }: 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.gh.createIssueComment(parsed.repo, parsed.number, text)
-      : await this.gh.createPRComment(parsed.repo, parsed.number, text);
+      ? await this.client.api.createIssueComment(parsed.repo, parsed.number, text)
+      : await this.client.api.createPRComment(parsed.repo, parsed.number, text);
     if (!r.ok) throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
+    this.#logger.debug(formatCompact({
+      op: 'github_send',
+      endpoint: this.client.name,
+      target: `${conversation.kind}:${conversation.id}`,
+      messageId: r.data.id,
+    }));
+    return String(r.data.id);
+  }
 
-    this.logger.debug(`${this.$id} send → ${options.id}: ${text.slice(0, 80)}...`);
-    return r.data.id.toString();
+  /** Test / internal: admit a parsed comment when open. */
+  admit(comment: GithubInboundComment): void {
+    if (!this.#open) return;
+    const botUser = this.client.config.botLogin
+      || this.client.api.getBotLogin()
+      || this.client.api.authenticatedUser;
+    if (botUser && comment.sender === botUser) return;
+    const conversation = githubInboundConversation(String(this.#options.id), comment);
+    const content = enrichInboundContent(
+      formatInboundContent(comment.content),
+      this.client.config,
+      botUser ?? undefined,
+      comment.repo,
+    );
+    void this.emit('message.receive', {
+      conversation,
+      message: { conversation, id: comment.id },
+      content,
+      sender: { id: comment.sender, name: comment.sender },
+      endpointId: this.client.name,
+      metadata: Object.freeze({
+        repo: comment.repo,
+        kind: comment.kind,
+        createdAt: comment.createdAt,
+      }),
+    }).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'github_gateway_receive_failed',
+        target: `${conversation.kind}:${conversation.id}`,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
   }
 
-  async $recallMessage(id: string): Promise<void> {
-    this.logger.warn(formatCompact( { op: 'recall', ok: false, error: 'use message.$recall()' }));
+  admitPlatform(name: string, event: unknown): void {
+    if (!this.#open) return;
+    void this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'github_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
   }
 }
+
+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

@@ -21,6 +21,19 @@ export interface AppAuth {
   privateKey: string;
 }
 
+export interface GitHubBotIdentity {
+  login: string;
+  email: string;
+  slug: string;
+  userId: number;
+}
+
+export interface GitHubCommitAuthor {
+  name: string;
+  email: string;
+  date?: string;
+}
+
 export interface GhClientOptions {
   /** GitHub Enterprise 主机名（默认 github.com） */
   host?: string;
@@ -201,6 +214,7 @@ export class GhClient {
           this._user = name;
           this._appSlug = appData.slug || null;
           if (appData.client_id) this._clientId = appData.client_id;
+          await this.resolveBotUserId();
           const repos = this._repoToInstallation.size;
           return { ok: true, user: name, message: `GitHub App: ${name} (${this._allInstallations.length} 安装, ${repos} 仓库)` };
         }
@@ -313,6 +327,114 @@ export class GhClient {
     return this.del(`/repos/${repo}/pulls/comments/${commentId}`);
   }
 
+  // ── Contents / Pulls（Bot 写操作）──────────────────────────────────
+
+  async getFileContent(repo: string, path: string, ref?: string) {
+    let apiPath = `/repos/${repo}/contents/${path.split('/').map(encodeURIComponent).join('/')}`;
+    if (ref) apiPath += `?ref=${encodeURIComponent(ref)}`;
+    return this.get<{ content: string; sha: string; encoding: string }>(apiPath);
+  }
+
+  async createOrUpdateFile(
+    repo: string,
+    path: string,
+    content: string,
+    message: string,
+    options?: { branch?: string; sha?: string },
+  ) {
+    const body: Record<string, unknown> = {
+      message,
+      content: Buffer.from(content, 'utf-8').toString('base64'),
+    };
+    if (options?.branch) body.branch = options.branch;
+    if (options?.sha) body.sha = options.sha;
+    const apiPath = `/repos/${repo}/contents/${path.split('/').map(encodeURIComponent).join('/')}`;
+    return this.put<{ commit: { sha: string; html_url?: string }; content: { html_url?: string } }>(
+      apiPath,
+      body,
+    );
+  }
+
+  async getRef(repo: string, ref: string) {
+    return this.get<{ ref: string; object: { sha: string; type: string } }>(
+      `/repos/${repo}/git/ref/${encodeURIComponent(ref)}`,
+    );
+  }
+
+  async createRef(repo: string, ref: string, sha: string) {
+    return this.post(`/repos/${repo}/git/refs`, { ref, sha });
+  }
+
+  async createPullRequest(
+    repo: string,
+    title: string,
+    head: string,
+    base: string,
+    body?: string,
+  ) {
+    return this.post<{ number: number; html_url: string; head: { ref: string } }>(
+      `/repos/${repo}/pulls`,
+      { title, head, base, body: body ?? '' },
+    );
+  }
+
+  getBotLogin(): string | null {
+    if (this._user) return this._user;
+    if (this._appSlug) return `${this._appSlug}[bot]`;
+    return null;
+  }
+
+  getCommitAuthor(): GitHubCommitAuthor | null {
+    const identity = this.getBotIdentitySync();
+    if (!identity) return null;
+    return { name: identity.login, email: identity.email, date: new Date().toISOString() };
+  }
+
+  getBotIdentitySync(): GitHubBotIdentity | null {
+    const slug = this._appSlug;
+    const login = this.getBotLogin();
+    if (!slug || !login || this._botUserId == null) return null;
+    return {
+      login,
+      slug,
+      userId: this._botUserId,
+      email: `${this._botUserId}+${login}@users.noreply.github.com`,
+    };
+  }
+
+  async getBotIdentity(): Promise<GitHubBotIdentity | null> {
+    if (!this._appAuth) return null;
+    if (this._botUserId == null) await this.resolveBotUserId();
+    return this.getBotIdentitySync();
+  }
+
+  buildCloneUrl(repo: string, token: string): string {
+    const host = this.host || 'github.com';
+    return `https://x-access-token:${encodeURIComponent(token)}@${host}/${repo}.git`;
+  }
+
+  async resolveBotUserId(): Promise<number | null> {
+    if (this._botUserId != null) return this._botUserId;
+    const slug = this._appSlug;
+    if (!slug) return null;
+    const login = `${slug}[bot]`;
+    const baseUrl = this.host ? `https://${this.host}/api/v3` : 'https://api.github.com';
+    try {
+      const res = await fetch(`${baseUrl}/users/${encodeURIComponent(login)}`, {
+        headers: { Accept: 'application/vnd.github+json' },
+      });
+      if (!res.ok) return null;
+      const data = (await res.json()) as { id?: number };
+      if (typeof data.id === 'number') {
+        this._botUserId = data.id;
+        return data.id;
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  }
+
   // ── Star ─────────────────────────────────────────────────────────
 
   async starRepo(repo: string) {
@@ -445,6 +567,15 @@ export class GhClient {
 
   /** App 的 client_id（verifyAuth 后从 /app 获取，用于 Device Flow） */
   private _clientId: string | null = null;
+  /** Bot 机器用户 numeric id（/users/{slug}[bot]） */
+  private _botUserId: number | null = null;
+
+  /** 确保 App 认证的 Installation Token 对指定 repo 有效，并返回 token */
+  async ensureInstallationTokenForRepo(repo: string): Promise<string | undefined> {
+    if (!this._appAuth) return this.token;
+    await this.ensureTokenForRepo(repo);
+    return this.token;
+  }
   get clientId(): string | null { return this._clientId; }
 
   // ── 事件轮询 ─────────────────────────────────────────────────────

package/src/github-bot-handlers.ts

@@ -0,0 +1,113 @@
+/**
+ * GitHub App Bot workflow handlers (Installation Token identity).
+ */
+import type { Message } from 'zhin.js';
+import { getCurrentCommMessage } from '@zhin.js/agent/security';
+import type { GithubClient } from './client.js';
+import {
+  parseMessageChannel,
+  resolveWorkspaceBranch,
+  formatChannelContext,
+} from './github-channel-context.js';
+
+function requireBotGh(client: GithubClient) {
+  const gh = client.api;
+  if (!gh?.isAppAuth) {
+    throw new Error('需要 GitHub App 认证（app_id + private_key），Bot 写操作不可用');
+  }
+  return gh;
+}
+
+function resolveCommMessage(commMessage?: Message): Message {
+  const msg = commMessage ?? getCurrentCommMessage();
+  if (!msg) throw new Error('无 IM 上下文，请在 Issue/PR 评论线程内调用');
+  return msg;
+}
+
+function resolveChannel(msg: Message, repo?: string) {
+  const ctx = parseMessageChannel(msg);
+  if (ctx) return ctx;
+  if (repo) {
+    throw new Error(`请从 GitHub Issue/PR 频道调用，或提供完整 channel（当前仅 repo=${repo}）`);
+  }
+  throw new Error('无法解析 GitHub 频道（需要 Issue/PR 评论上下文）');
+}
+
+export async function executeGithubPrepareWorkspace(
+  args: { repo?: string },
+  client: GithubClient,
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh(client);
+  const wm = client.workspaceManager;
+  const { branch, base } = await resolveWorkspaceBranch(gh, ctx);
+  const repoPath = await wm.checkoutBranch(ctx.repo, branch, base);
+  return [
+    `✅ 工作区就绪`,
+    `📁 ${repoPath}`,
+    `🌿 分支 \`${branch}\`（base: \`${base}\`）`,
+    `📍 ${formatChannelContext(ctx)}`,
+  ].join('\n');
+}
+
+export async function executeGithubPatchFile(
+  args: { repo?: string; path: string; content: string; message: string; branch?: string },
+  client: GithubClient,
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh(client);
+  const { branch } = args.branch
+    ? { branch: args.branch }
+    : await resolveWorkspaceBranch(gh, ctx);
+
+  const existing = await gh.getFileContent(ctx.repo, args.path, branch);
+  const sha = existing.ok ? existing.data.sha : undefined;
+  const r = await gh.createOrUpdateFile(
+    ctx.repo,
+    args.path,
+    args.content,
+    args.message,
+    { branch, sha },
+  );
+  if (!r.ok) {
+    return `❌ 更新文件失败: ${JSON.stringify(r.data)}`;
+  }
+  const url = r.data.content?.html_url ?? r.data.commit?.html_url ?? '';
+  return `✅ 已更新 \`${args.path}\` @ \`${branch}\`${url ? `\n🔗 ${url}` : ''}`;
+}
+
+export async function executeGithubPushBranch(
+  args: { repo?: string; branch?: string; message: string },
+  client: GithubClient,
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh(client);
+  const wm = client.workspaceManager;
+  const branch = args.branch ?? (await resolveWorkspaceBranch(gh, ctx)).branch;
+  const result = await wm.commitAndPush(ctx.repo, branch, args.message);
+  return `✅ ${result}\n📍 ${ctx.repo} @ \`${branch}\``;
+}
+
+export async function executeGithubCreatePr(
+  args: { repo?: string; title: string; body?: string; head?: string; base?: string },
+  client: GithubClient,
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh(client);
+  const resolved = await resolveWorkspaceBranch(gh, ctx);
+  const head = args.head ?? resolved.branch;
+  const base = args.base ?? resolved.base;
+  const r = await gh.createPullRequest(ctx.repo, args.title, head, base, args.body);
+  if (!r.ok) {
+    return `❌ 创建 PR 失败: ${JSON.stringify(r.data)}`;
+  }
+  return `✅ PR #${r.data.number} 已创建\n🔗 ${r.data.html_url}`;
+}

package/src/github-channel-context.ts

@@ -0,0 +1,46 @@
+/**
+ * Parse GitHub Issue/PR channel context from IM messages.
+ */
+import type { Message } from 'zhin.js';
+import { buildChannelId, parseChannelId, type ParsedChannel } from './types.js';
+import type { GhClient } from './gh-client.js';
+
+export interface GitHubChannelContext extends ParsedChannel {
+  channelId: string;
+}
+
+export function parseMessageChannel(message: Message): GitHubChannelContext | null {
+  const channelId = message.$channel?.id;
+  if (!channelId) return null;
+  const parsed = parseChannelId(channelId);
+  if (!parsed) return null;
+  return { ...parsed, channelId };
+}
+
+export function issueBranchName(number: number): string {
+  return `zhin/bot/issue-${number}`;
+}
+
+export async function resolveWorkspaceBranch(
+  gh: GhClient,
+  ctx: GitHubChannelContext,
+): Promise<{ branch: string; base: string }> {
+  if (ctx.type === 'pr') {
+    const pr = await gh.getPR(ctx.repo, ctx.number);
+    if (pr.ok && pr.data?.head?.ref) {
+      const base = pr.data.base?.ref ?? 'main';
+      return { branch: pr.data.head.ref, base };
+    }
+    throw new Error(`无法读取 PR #${ctx.number} 的 head 分支`);
+  }
+
+  const repoInfo = await gh.getRepo(ctx.repo);
+  const base = repoInfo.ok && repoInfo.data?.default_branch
+    ? String(repoInfo.data.default_branch)
+    : 'main';
+  return { branch: issueBranchName(ctx.number), base };
+}
+
+export function formatChannelContext(ctx: GitHubChannelContext): string {
+  return buildChannelId(ctx.repo, ctx.type, ctx.number);
+}

package/src/github-endpoint-commands.ts

@@ -0,0 +1,23 @@
+/**
+ * `github.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ *
+ * 字段说明：private_key 内容长且含换行，不适合 kv 直传——运行时（gh-client
+ * resolvePrivateKey）本就支持 PEM 内容或文件路径，故 add 采用**内联路径**形式：
+ * `github.endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
+ */
+import { createEndpointCommands } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { githubRuntimeStateToken } from './github-runtime-state.js';
+
+export const githubEndpointCommands = createEndpointCommands({
+  adapterKey: 'github',
+  adapterDisplayName: 'GitHub',
+  fields: [
+    { key: 'app_id', required: true, env: true, description: 'GitHub App ID' },
+    { key: 'private_key', required: true, description: 'PEM 文件路径（推荐，如 ./data/xxx.pem）或 PEM 内容' },
+    { key: 'webhook_secret', env: true, description: 'webhook 签名密钥（不配则 API-only）' },
+  ],
+  running: (use) => use(githubRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `app_id: ${String(entry.app_id ?? entry.appId)}`,
+}, defineCommand);

package/src/github-runtime-state.ts

@@ -0,0 +1,7 @@
+/**
+ * GitHub 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `github.endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
+
+export const githubRuntimeStateToken = defineEndpointRuntimeStateToken('github');