@zhin.js/adapter-github 3.0.1 → 3.0.3

package/plugin.ts

@@ -0,0 +1,52 @@
+import { definePlugin, databaseHostToken } from '@zhin.js/plugin-runtime';
+import { defineGithubOauthUsersTable } from './src/oauth-users.js';
+
+/**
+ * github_subscriptions — repo event subscriptions per chat channel
+ * (used by github_subscriptions agent tool; schema matches legacy defineModel).
+ */
+const GITHUB_SUBSCRIPTIONS_SCHEMA = {
+  id: { type: 'integer', primary: true },
+  repo: { type: 'text', nullable: false },
+  events: { type: 'json', default: [] },
+  target_id: { type: 'text', nullable: false },
+  target_type: { type: 'text', nullable: false },
+  adapter: { type: 'text', nullable: false },
+  endpoint: { type: 'text', nullable: false },
+} as const;
+
+/**
+ * Plugin Runtime GitHub adapter.
+ * - Endpoint: `adapters/github.ts`
+ * - OAuth user tokens: define `github_oauth_users` when DatabaseHost is present
+ */
+export default definePlugin({
+  name: 'github',
+  metadata: {
+    displayName: 'GitHub Adapter',
+  },
+  setup(context) {
+    if (context.resources.has(databaseHostToken)) {
+      const host = context.resources.use(databaseHostToken);
+      defineGithubOauthUsersTable(host);
+      host.define('github_subscriptions', { ...GITHUB_SUBSCRIPTIONS_SCHEMA });
+    }
+
+    // Agent prompt contributor (orchestrator/deferred-worker GitHub guidance).
+    // `zhin.js/agent` is an optional peer — skip silently on IM-only installs.
+    let cancelled = false;
+    let unregister: (() => void) | undefined;
+    void Promise.all([
+      import('zhin.js/agent'),
+      import('./src/agent-prompt.js'),
+    ]).then(([agent, prompt]) => {
+      if (cancelled) return;
+      agent.registerAgentPromptContributor(prompt.createGithubAgentPromptContributor());
+      unregister = () => agent.unregisterAgentPromptContributor('github');
+    }).catch(() => { /* optional peer not installed */ });
+    return () => {
+      cancelled = true;
+      unregister?.();
+    };
+  },
+});

package/schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "default": "github-bot"
+    },
+    "host": {
+      "type": "string",
+      "description": "GitHub Enterprise hostname (default github.com)"
+    },
+    "app_id": {
+      "type": ["string", "number"],
+      "description": "GitHub App ID"
+    },
+    "appId": {
+      "type": ["string", "number"],
+      "description": "GitHub App ID (camelCase alias)"
+    },
+    "private_key": {
+      "type": "string",
+      "description": "GitHub App private key (PEM content or file path)"
+    },
+    "privateKey": {
+      "type": "string",
+      "description": "GitHub App private key (camelCase alias)"
+    },
+    "webhook_secret": {
+      "type": "string",
+      "description": "Webhook HMAC secret; enables httpHostToken POST route"
+    },
+    "webhookSecret": {
+      "type": "string",
+      "description": "Webhook HMAC secret (camelCase alias)"
+    },
+    "webhook_path": {
+      "type": "string",
+      "default": "/github/webhook"
+    },
+    "webhookPath": {
+      "type": "string",
+      "default": "/github/webhook"
+    },
+    "poll_interval": {
+      "type": "number",
+      "default": 60,
+      "description": "Deferred: polling fallback was removed in the Plugin Runtime migration; currently parsed but unused"
+    },
+    "auto_reply_repos": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Repos whose Issue/PR comments auto-trigger AI without @bot"
+    },
+    "bot_login": {
+      "type": "string",
+      "description": "Override App bot login (default {slug}[bot])"
+    },
+    "workspace_root": {
+      "type": "string",
+      "description": "Managed git workspace root"
+    }
+  }
+}

package/src/agent-prompt.ts

@@ -4,8 +4,7 @@ import type {
   AgentPromptSection,
   DeferredToolCatalogItem,
 } from 'zhin.js';
-import type { AgentTool } from 'zhin.js/ai';
-import { filterTools } from 'zhin.js/ai';
+import { filterTools, type AgentTool } from 'zhin.js/ai';
 
 function selectGithubDeferredTools(
   query: string,
@@ -21,8 +20,8 @@ function selectGithubDeferredTools(
   if (bash) pinned.push(bash);
 
   const preferNames = [
-    ...pool.filter(t => t.name.startsWith('mcp_github_')).map(t => t.name),
     ...pool.filter(t => t.name.startsWith('github_')).map(t => t.name),
+    ...pool.filter(t => t.name.startsWith('mcp_github_')).map(t => t.name),
   ];
   for (const name of preferNames) {
     if (pinned.length >= maxTools) break;
@@ -47,16 +46,18 @@ function isGithubDelegatedTask(query: string, goal: string): boolean {
 }
 
 const ORCHESTRATOR_GITHUB = [
-  'On GitHub: use run_deferred_task with tool_query "github_" or "mcp_github_" or "gh issue"/"gh pr".',
-  'Discuss issues/PRs in chat context; do not call github_* or mcp_github_* tools on this orchestrator.',
-  'Skip tool_search when the user clearly names a repo, issue number, or PR.',
+  'On GitHub: use run_deferred_task with tool_query "github_".',
+  'Discuss issues/PRs in chat context; do not call github_* tools on this orchestrator.',
+  'Bot write operations use github_* tools (Installation Token), not mcp_github_*.',
 ].join('\n');
 
 const WORKER_GITHUB = [
-  'Prefer `gh` via bash for repo operations when bash is available.',
-  'Use mcp_github_* or github_* plugin tools for structured API actions.',
-  'Do not use mcp_filesystem_* or unrelated MCP servers to "discover" GitHub.',
-  'Summarize outcomes (issue link, PR state) for the orchestrator.',
+  'Use github_prepare_workspace before multi-file edits in a repo.',
+  'Small single-file change: github_patch_file (Contents API).',
+  'Multi-file / tests: workspace + bash, then github_push_branch (requires approval) and github_create_pr for Issues.',
+  'Issue thread: new branch + new PR. PR thread: push to existing PR head branch.',
+  'Do NOT use mcp_github_* for writes — PAT acts as human, not Bot.',
+  'Summarize outcomes (PR link, branch) for the orchestrator.',
 ].map(line => `- ${line}`).join('\n');
 
 export function createGithubAgentPromptContributor(): AgentPromptContributor {

package/src/endpoint.ts

@@ -1,182 +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 type {
-  GitHubEndpointConfig,
-  IssueCommentPayload,
-  PRReviewCommentPayload,
-  PRReviewPayload,
-} from './types.js';
-import { buildChannelId, parseChannelId } 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';
-
-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 { 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 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}]`;
+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);
+  }
+
+  getAPI(): GhClient {
+    return this.gh;
+  }
+
+  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;
+  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.$connected = true;
-    this.logger.info(formatCompact({ endpoint: this.$id }));
+  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 });
+}