@zhin.js/adapter-github 1.0.1 → 1.1.2

package/src/protocol.ts

@@ -0,0 +1,372 @@
+/**
+ * GitHub webhook / comment helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('github');
+import {
+  buildChannelId,
+  type GenericWebhookPayload,
+  type IssueCommentPayload,
+  type PRReviewCommentPayload,
+  type PRReviewPayload,
+} from './types.js';
+
+export type {
+  EventType,
+  GenericWebhookPayload,
+  GitHubComment,
+  GitHubIssue,
+  GitHubOAuthUser,
+  GitHubPR,
+  GitHubRepo,
+  GitHubUser,
+  IssueCommentPayload,
+  ParsedChannel,
+  PRReviewCommentPayload,
+  PRReviewPayload,
+  Subscription,
+} from './types.js';
+
+export { buildChannelId, parseChannelId } from './types.js';
+
+/** One expanded GitHub endpoint configuration produced by AdapterIndex. */
+export interface GithubEndpointConfig {
+  readonly id: string;
+  readonly host?: string;
+  readonly app_id: string | number;
+  readonly private_key: string;
+  readonly webhook_secret?: string;
+  readonly webhook_path?: string;
+  readonly auto_reply_repos?: readonly string[];
+  readonly bot_login?: string;
+  readonly workspace_root?: string;
+}
+
+export interface ResolvedGithubConfig {
+  readonly context: 'github';
+  readonly id: string;
+  readonly host?: string;
+  readonly appId: string | number;
+  readonly privateKey: string;
+  readonly webhookSecret?: string;
+  readonly webhookPath: string;
+  readonly autoReplyRepos: readonly string[];
+  readonly botLogin?: string;
+  readonly workspaceRoot: string;
+}
+
+export interface GithubWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface GithubInboundComment {
+  readonly id: string;
+  readonly channelId: string;
+  readonly sender: string;
+  readonly content: string;
+  readonly repo: string;
+  readonly kind: 'issue_comment' | 'pr_review_comment' | 'pr_review';
+  readonly createdAt: number;
+}
+
+/**
+ * 入站归一化 → ConversationRef：Issue/PR 评论区即仓库容器内的 channel 会话，
+ * 仓库（owner/repo）进 `parent`。出站侧用 `parseChannelId(conversation.id)`
+ * 在平台边界还原 repo/type/number。
+ */
+export function githubInboundConversation(
+  endpointKey: string,
+  comment: GithubInboundComment,
+): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: 'channel',
+    id: comment.channelId,
+    parent: { kind: 'channel', id: comment.repo },
+  };
+}
+
+export function resolveGithubConfig(config: GithubEndpointConfig): ResolvedGithubConfig {
+  const id = typeof config.id === 'string' ? config.id.trim() : '';
+  if (!id) throw new TypeError('GitHub endpoint requires a non-empty id');
+  const appIdRaw = config.app_id != null ? String(config.app_id).trim() : '';
+  const appId = appIdRaw ? (Number(appIdRaw) || appIdRaw) : undefined;
+  const privateKey = typeof config.private_key === 'string'
+    ? config.private_key.trim()
+    : '';
+  if (!appId || !privateKey) {
+    throw new TypeError('GitHub endpoint requires app_id and private_key');
+  }
+  const webhookSecret = config.webhook_secret;
+  const host = config.host;
+  const webhookPath = normalizeWebhookPath(config.webhook_path ?? '/github/webhook');
+  const autoReplyRepos = [...(config.auto_reply_repos ?? [])];
+  const botLogin = config.bot_login;
+  const workspaceRoot = config.workspace_root ?? 'data/github-workspaces';
+
+  return {
+    context: 'github',
+    id,
+    ...(host ? { host } : {}),
+    appId,
+    privateKey,
+    ...(webhookSecret ? { webhookSecret } : {}),
+    webhookPath,
+    autoReplyRepos,
+    ...(botLogin ? { botLogin } : {}),
+    workspaceRoot,
+  };
+}
+
+export function normalizeWebhookPath(path: string): string {
+  const trimmed = path.trim() || '/github/webhook';
+  return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+
+export function shouldAutoReplyRepo(
+  config: Pick<ResolvedGithubConfig, 'autoReplyRepos'>,
+  repo: string,
+): boolean {
+  const list = config.autoReplyRepos;
+  if (!list.length) return false;
+  const key = repo.toLowerCase();
+  return list.some((r) => r.toLowerCase() === key);
+}
+
+/** Prepend synthetic @bot for auto_reply repos (gateway text path). */
+export function enrichInboundContent(
+  content: string,
+  config: Pick<ResolvedGithubConfig, 'autoReplyRepos' | 'botLogin'>,
+  botLogin: string | undefined,
+  repo: string,
+): string {
+  const login = config.botLogin || botLogin;
+  if (!login || !shouldAutoReplyRepo(config, repo)) return content;
+  if (content.includes(`@${login}`)) return content;
+  return `@${login} ${content}`;
+}
+
+/** Build inbound text for OutboundMessageService.receive from markdown/comment body. */
+export function formatInboundContent(body: string): string {
+  return body;
+}
+
+/** Build markdown body for Issue/PR comment send. */
+export function formatOutboundBody(payload: unknown): string {
+  if (typeof payload === 'string') return payload;
+  if (payload == null) return '';
+  if (!Array.isArray(payload)) {
+    if (typeof payload === 'object' && payload !== null && 'text' in payload) {
+      return String((payload as { text?: unknown }).text ?? '');
+    }
+    return String(payload);
+  }
+  return payload.map((seg) => {
+    if (typeof seg === 'string') return seg;
+    const item = seg as GithubWireSegment;
+    switch (item.type) {
+      case 'text':
+        return String(item.data?.text ?? '');
+      case 'mention':
+      case 'at':
+        return `@${item.data?.name || item.data?.id || item.data?.target || ''}`;
+      case 'image':
+      case 'audio':
+      case 'video':
+      case 'file':
+        return formatMediaSegment(item);
+      case 'link':
+        return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
+      default:
+        return String(item.data?.text ?? `[${item.type}]`);
+    }
+  }).join('');
+}
+
+/**
+ * 媒体段 → GitHub markdown（canonical MediaRef 唯一来源）。
+ * GitHub 评论只能消费远程 URL（无上传面），kind=url 直发；
+ * base64 / path / file 不可投递，warn + 丢弃。
+ */
+function formatMediaSegment(seg: GithubWireSegment): string {
+  const media = seg.data?.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'github_outbound_media_dropped',
+      type: seg.type,
+      reason: 'missing_media_ref',
+    }));
+    return '';
+  }
+  if (media.kind !== 'url') {
+    logger.warn(formatCompact({
+      op: 'github_outbound_media_dropped',
+      type: seg.type,
+      reason: `unsupported_kind:${media.kind}`,
+    }));
+    return '';
+  }
+  if (seg.type === 'image') {
+    const alt = typeof seg.data?.alt === 'string' && seg.data.alt
+      ? seg.data.alt
+      : media.file_name || 'image';
+    return `![${alt}](${media.value})`;
+  }
+  const label = media.file_name || seg.type;
+  return `[${label}](${media.value})`;
+}
+
+export function verifyWebhookSignature(
+  secret: string,
+  rawBody: string,
+  signatureHeader: string | undefined,
+): boolean {
+  if (!signatureHeader?.startsWith('sha256=')) return false;
+  const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
+  try {
+    const a = Buffer.from(signatureHeader);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  } catch {
+    return false;
+  }
+}
+
+export function headerValue(
+  headers: IncomingMessage['headers'],
+  name: string,
+): string {
+  const raw = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0] ?? '';
+  return raw ?? '';
+}
+
+export async function readTextBody(
+  request: IncomingMessage,
+  options: { readonly limit?: number } = {},
+): Promise<string> {
+  const limit = options.limit ?? 1_048_576;
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > limit) {
+      request.destroy();
+      throw new Error(`Request body exceeds ${limit} bytes`);
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export function parseIssueCommentInbound(payload: IssueCommentPayload): GithubInboundComment | null {
+  if (payload.action !== 'created' || !payload.comment) return null;
+  const repo = payload.repository.full_name;
+  const isPR = 'pull_request' in (payload.issue as object);
+  return {
+    id: String(payload.comment.id),
+    channelId: buildChannelId(repo, isPR ? 'pr' : 'issue', payload.issue.number),
+    sender: payload.sender.login,
+    content: payload.comment.body,
+    repo,
+    kind: 'issue_comment',
+    createdAt: new Date(payload.comment.created_at).getTime(),
+  };
+}
+
+export function parsePrReviewCommentInbound(payload: PRReviewCommentPayload): GithubInboundComment | null {
+  if (payload.action !== 'created' || !payload.comment) return null;
+  const repo = payload.repository.full_name;
+  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 {
+    id: String(payload.comment.id),
+    channelId: buildChannelId(repo, 'pr', payload.pull_request.number),
+    sender: payload.sender.login,
+    content: body,
+    repo,
+    kind: 'pr_review_comment',
+    createdAt: new Date(payload.comment.created_at).getTime(),
+  };
+}
+
+export function parsePrReviewInbound(payload: PRReviewPayload): GithubInboundComment | null {
+  if (payload.action !== 'submitted' || !payload.review.body) return null;
+  const repo = payload.repository.full_name;
+  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 {
+    id: String(payload.review.id),
+    channelId: buildChannelId(repo, 'pr', payload.pull_request.number),
+    sender: payload.sender.login,
+    content: body,
+    repo,
+    kind: 'pr_review',
+    createdAt: new Date(payload.review.submitted_at).getTime(),
+  };
+}
+
+export function formatNotification(event: string, p: GenericWebhookPayload): string {
+  const repo = p.repository.full_name;
+  const sender = p.sender.login;
+  const repoUrl = p.repository.html_url;
+  switch (event) {
+    case 'push': {
+      const branch = p.ref?.replace('refs/heads/', '') || '?';
+      const commits = p.commits || [];
+      const compareUrl = commits.length >= 2
+        ? `${repoUrl}/compare/${commits[0].id.substring(0, 12)}...${commits[commits.length - 1].id.substring(0, 12)}`
+        : commits.length === 1 ? `${repoUrl}/commit/${commits[0].id}` : '';
+      let msg = `📦 ${repo}\n🌿 ${sender} pushed ${commits.length} commit(s) to \`${branch}\`\n`;
+      if (commits.length) {
+        msg += '\n';
+        msg += commits.slice(0, 5).map((c) =>
+          `  • [\`${c.id.substring(0, 7)}\`](${repoUrl}/commit/${c.id}) ${c.message.split('\n')[0]}`,
+        ).join('\n');
+        if (commits.length > 5) msg += `\n  ... +${commits.length - 5} more`;
+      }
+      if (compareUrl) msg += `\n\n🔗 ${compareUrl}`;
+      return msg;
+    }
+    case 'issues': {
+      const i = p.issue!;
+      const act = p.action === 'opened' ? '📝 opened' : p.action === 'closed' ? '✅ closed' : `🔄 ${p.action || 'updated'}`;
+      return `🐛 ${repo}\n👤 ${sender} ${act} issue #${i.number}\n📌 ${i.title}\n🔗 ${i.html_url}`;
+    }
+    case 'star': {
+      const starred = p.action !== 'deleted';
+      return `${starred ? '⭐' : '💔'} ${repo}\n👤 ${sender} ${starred ? 'starred' : 'unstarred'}\n🔗 ${repoUrl}`;
+    }
+    case 'fork':
+      return `🍴 ${repo}\n👤 ${sender} forked → ${p.forkee!.full_name}\n🔗 ${p.forkee!.html_url}`;
+    case 'pull_request': {
+      const pr = p.pull_request!;
+      const act = p.action === 'opened' ? '📝 opened'
+        : p.action === 'closed' ? (pr.state === 'closed' ? '❌ closed' : '✅ merged')
+        : `🔄 ${p.action || 'updated'}`;
+      return `🔀 ${repo}\n👤 ${sender} ${act} PR #${pr.number}\n📌 ${pr.title}\n🌿 ${pr.head.ref} → ${pr.base.ref}\n🔗 ${pr.html_url}`;
+    }
+    default:
+      return `📬 ${repo}\n📡 ${event}${p.action ? ` (${p.action})` : ''} by ${sender}\n🔗 ${repoUrl}`;
+  }
+}
+
+/** Parse @mentions in markdown into a flat display string (gateway text path). */
+export function parseMarkdownMentions(md: string): string {
+  return md;
+}

package/src/types.ts

@@ -1,25 +1,3 @@
-// ── Endpoint 配置 ─────────────────────────────────────────────────────────
-//  基于 gh CLI 认证：需要系统已安装并认证 gh CLI
-//  认证方式：gh auth login
-
-export interface GitHubEndpointConfig {
-  context: 'github';
-  /** Endpoint 标识名称 */
-  name: string;
-  /** GitHub Enterprise 主机名（默认 github.com） */
-  host?: string;
-  /** GitHub App ID */
-  app_id?: string | number;
-  /** GitHub App 私钥（PEM 内容或文件路径） */
-  private_key?: string;
-  /** Webhook Secret（配置后启用 Webhook 接收事件，不配置则使用轮询） */
-  webhook_secret?: string;
-  /** Webhook 路由路径（默认 /github/webhook） */
-  webhook_path?: string;
-  /** 事件轮询间隔（秒，默认 60，Webhook 模式下作为降级备选） */
-  poll_interval?: number;
-}
-
 // ── Channel ID ───────────────────────────────────────────────────────
 //  格式: {owner}/{repo}/issues/{number} 或 {owner}/{repo}/pull/{number}
 

package/src/webhook.ts

@@ -0,0 +1,130 @@
+/**
+ * GitHub webhook HTTP: verify → parse → admit inbound comments.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import {
+  headerValue,
+  parseIssueCommentInbound,
+  parsePrReviewCommentInbound,
+  parsePrReviewInbound,
+  readTextBody,
+  verifyWebhookSignature,
+  type GithubInboundComment,
+  type IssueCommentPayload,
+  type PRReviewCommentPayload,
+  type PRReviewPayload,
+  type ResolvedGithubConfig,
+} from './protocol.js';
+
+const logger = getLogger('github');
+
+export interface GithubWebhookHandler {
+  readonly config: ResolvedGithubConfig;
+  admitPlatform(name: string, event: unknown): void;
+  admit(comment: GithubInboundComment): void;
+}
+
+export function registerGithubWebhookRoutes(
+  http: HttpHost,
+  handler: GithubWebhookHandler,
+): HttpRouteRegistration[] {
+  const routePath = handler.config.webhookPath;
+  return [
+    http.route('POST', routePath, async (request, response) => {
+      await handleGithubWebhookRequest(request, response, handler);
+    }, { summary: 'GitHub webhook', tags: ['github'] }),
+  ];
+}
+
+export async function handleGithubWebhookRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  handler: GithubWebhookHandler,
+): Promise<void> {
+  const secret = handler.config.webhookSecret;
+  if (!secret) {
+    response.writeHead(503, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify({ error: 'Webhook not configured' }));
+    return;
+  }
+
+  const signature = headerValue(request.headers, 'x-hub-signature-256');
+  const event = headerValue(request.headers, 'x-github-event');
+  const deliveryId = headerValue(request.headers, 'x-github-delivery');
+
+  if (!signature || !event) {
+    response.writeHead(400, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify({ error: 'Missing signature or event header' }));
+    return;
+  }
+
+  try {
+    const rawBody = await readTextBody(request);
+    if (!verifyWebhookSignature(secret, rawBody, signature)) {
+      logger.warn(formatCompact({
+        op: 'webhook',
+        ok: false,
+        error: 'invalid signature',
+        delivery: deliveryId,
+      }));
+      response.writeHead(401, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ error: 'Invalid signature' }));
+      return;
+    }
+
+    let payload: unknown;
+    try {
+      payload = rawBody ? JSON.parse(rawBody) : {};
+    } catch {
+      response.writeHead(400, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ error: 'Invalid JSON' }));
+      return;
+    }
+
+    response.writeHead(200, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify({ ok: true }));
+
+    void dispatchGithubWebhookPayload(event, payload, handler).catch((e) => {
+      logger.error(`Webhook 事件处理失败 (${event}):`, e);
+    });
+  } catch (error) {
+    logger.error('Webhook error:', error);
+    if (!response.headersSent) {
+      response.writeHead(500, { 'Content-Type': 'application/json' });
+      response.end(JSON.stringify({ error: 'Internal Server Error' }));
+    }
+  }
+}
+
+export async function dispatchGithubWebhookPayload(
+  event: string,
+  payload: unknown,
+  handler: GithubWebhookHandler,
+): Promise<void> {
+  if (!payload || typeof payload !== 'object') return;
+  const body = payload as Record<string, unknown>;
+  const repo = (body.repository as { full_name?: string } | undefined)?.full_name;
+  logger.debug(`Webhook: ${event}${(body.action as string) ? `.${body.action}` : ''} ${repo || ''}`);
+  handler.admitPlatform(
+    typeof body.action === 'string' && body.action ? `${event}.${body.action}` : event,
+    payload,
+  );
+
+  if (event === 'issue_comment') {
+    const inbound = parseIssueCommentInbound(payload as IssueCommentPayload);
+    if (inbound) handler.admit(inbound);
+    return;
+  }
+  if (event === 'pull_request_review_comment') {
+    const inbound = parsePrReviewCommentInbound(payload as PRReviewCommentPayload);
+    if (inbound) handler.admit(inbound);
+    return;
+  }
+  if (event === 'pull_request_review') {
+    const inbound = parsePrReviewInbound(payload as PRReviewPayload);
+    if (inbound) handler.admit(inbound);
+  }
+  // Cross-adapter subscription fan-out deferred (needs multi-adapter send in Runtime).
+}

package/src/workspace-manager.ts

@@ -0,0 +1,168 @@
+/**
+ * Managed git workspaces for GitHub App Bot development flow.
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { GhClient, GitHubBotIdentity } from './gh-client.js';
+
+const REPO_FULL_NAME_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const GIT_REF_ILLEGAL_CHARS = new Set('~^:?*[\\`;');
+
+function containsIllegalGitRefCharacter(ref: string): boolean {
+  return [...ref].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31
+      || code === 127
+      || /\s/u.test(character)
+      || GIT_REF_ILLEGAL_CHARS.has(character);
+  });
+}
+
+/**
+ * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
+ * 返回通过校验的原值，便于调用方直接使用「已消毒」的变量。
+ */
+export function assertRepoFullName(repo: string): string {
+  if (
+    typeof repo !== 'string' ||
+    !REPO_FULL_NAME_RE.test(repo) ||
+    repo.split('/').some((seg) => seg === '' || seg.startsWith('-') || /^\.+$/.test(seg))
+  ) {
+    throw new TypeError(`非法的仓库全名: ${JSON.stringify(repo)}`);
+  }
+  return repo;
+}
+
+/**
+ * 校验 git ref 名称，拒绝选项注入（`-` 前缀）与 git 非法字符。
+ */
+export function assertGitRefName(ref: string): string {
+  if (typeof ref !== 'string' || ref.length === 0) {
+    throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);
+  }
+  if (
+    ref.startsWith('-') ||
+    ref.includes('..') ||
+    containsIllegalGitRefCharacter(ref) ||
+    ref.endsWith('/') ||
+    ref.endsWith('.')
+  ) {
+    throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);
+  }
+  return ref;
+}
+
+export class WorkspaceManager {
+  constructor(
+    private readonly gh: GhClient,
+    private readonly rootDir: string,
+  ) {}
+
+  getRepoPath(repo: string): string {
+    repo = assertRepoFullName(repo);
+    const [owner, name] = repo.split('/');
+    return path.join(this.rootDir, owner, name);
+  }
+
+  private runGit(cwd: string, args: string[], env?: NodeJS.ProcessEnv): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const proc = spawn('git', args, {
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, ...env },
+      });
+      let stdout = '';
+      let stderr = '';
+      proc.stdout.on('data', (d: Buffer) => { stdout += d.toString(); });
+      proc.stderr.on('data', (d: Buffer) => { stderr += d.toString(); });
+      proc.on('error', (err: NodeJS.ErrnoException) => {
+        if (err.code === 'ENOENT') reject(new Error('git 未安装'));
+        else reject(err);
+      });
+      proc.on('close', (code) => {
+        if (code === 0) resolve(stdout);
+        else reject(new Error(stderr.trim() || `git ${args.join(' ')} failed (${code})`));
+      });
+    });
+  }
+
+  configureBotGit(repoPath: string, identity: GitHubBotIdentity): Promise<void> {
+    return Promise.all([
+      this.runGit(repoPath, ['config', 'user.name', identity.login]),
+      this.runGit(repoPath, ['config', 'user.email', identity.email]),
+    ]).then(() => undefined);
+  }
+
+  async ensureRepo(repo: string): Promise<string> {
+    repo = assertRepoFullName(repo);
+    if (!this.gh.isAppAuth) {
+      throw new Error('GitHub App 认证未配置，无法托管工作区');
+    }
+    const token = await this.gh.ensureInstallationTokenForRepo(repo);
+    if (!token) throw new Error(`无法获取 ${repo} 的 Installation Token`);
+
+    const repoPath = this.getRepoPath(repo);
+    fs.mkdirSync(path.dirname(repoPath), { recursive: true });
+
+    const identity = await this.gh.getBotIdentity();
+    if (!identity) throw new Error('无法解析 GitHub App Bot 身份');
+
+    const cloneUrl = this.gh.buildCloneUrl(repo, token);
+    if (!fs.existsSync(path.join(repoPath, '.git'))) {
+      await this.runGit(path.dirname(repoPath), ['clone', cloneUrl, path.basename(repoPath)]);
+    } else {
+      await this.runGit(repoPath, ['remote', 'set-url', 'origin', cloneUrl]);
+      await this.runGit(repoPath, ['fetch', 'origin', '--prune']);
+    }
+
+    await this.configureBotGit(repoPath, identity);
+    return repoPath;
+  }
+
+  async checkoutBranch(repo: string, branch: string, baseRef: string): Promise<string> {
+    repo = assertRepoFullName(repo);
+    branch = assertGitRefName(branch);
+    baseRef = assertGitRefName(baseRef);
+    const repoPath = await this.ensureRepo(repo);
+    const localBranches = await this.runGit(repoPath, ['branch', '--list', branch]);
+    if (localBranches.trim()) {
+      await this.runGit(repoPath, ['checkout', branch]);
+      await this.runGit(repoPath, ['pull', '--rebase', 'origin', branch]).catch(async () => {
+        await this.runGit(repoPath, ['fetch', 'origin', branch]);
+      });
+      return repoPath;
+    }
+
+    const remoteBranch = await this.runGit(repoPath, ['ls-remote', '--heads', 'origin', branch]);
+    if (remoteBranch.trim()) {
+      await this.runGit(repoPath, ['checkout', '-B', branch, `origin/${branch}`]);
+      return repoPath;
+    }
+
+    await this.runGit(repoPath, ['fetch', 'origin', baseRef]);
+    await this.runGit(repoPath, ['checkout', '-B', branch, `origin/${baseRef}`]);
+    return repoPath;
+  }
+
+  async commitAndPush(repo: string, branch: string, message: string): Promise<string> {
+    repo = assertRepoFullName(repo);
+    branch = assertGitRefName(branch);
+    const repoPath = this.getRepoPath(repo);
+    if (!fs.existsSync(repoPath)) {
+      throw new Error(`工作区不存在: ${repoPath}，请先 github_prepare_workspace`);
+    }
+
+    const token = await this.gh.ensureInstallationTokenForRepo(repo);
+    if (!token) throw new Error('Installation Token 不可用');
+    await this.runGit(repoPath, ['remote', 'set-url', 'origin', this.gh.buildCloneUrl(repo, token)]);
+
+    const status = await this.runGit(repoPath, ['status', '--porcelain']);
+    if (!status.trim()) return '没有可提交的变更';
+
+    await this.runGit(repoPath, ['add', '-A']);
+    await this.runGit(repoPath, ['commit', '-m', message]);
+    await this.runGit(repoPath, ['push', '-u', 'origin', branch]);
+    return `已 push 到 origin/${branch}`;
+  }
+}