@zhin.js/adapter-github 3.0.1 → 3.0.3

package/src/protocol.ts

@@ -0,0 +1,367 @@
+/**
+ * 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 { pickCredential } from '@zhin.js/adapter';
+import {
+  buildChannelId,
+  type GenericWebhookPayload,
+  type IssueCommentPayload,
+  type PRReviewCommentPayload,
+  type PRReviewPayload,
+} from './types.js';
+
+export type {
+  EventType,
+  GenericWebhookPayload,
+  GitHubComment,
+  GitHubEndpointConfig,
+  GitHubIssue,
+  GitHubOAuthUser,
+  GitHubPR,
+  GitHubRepo,
+  GitHubUser,
+  IssueCommentPayload,
+  ParsedChannel,
+  PRReviewCommentPayload,
+  PRReviewPayload,
+  Subscription,
+} from './types.js';
+
+export { buildChannelId, parseChannelId } from './types.js';
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface GithubAdapterConfig {
+  readonly name?: string;
+  readonly host?: string;
+  readonly app_id?: string | number;
+  readonly appId?: string | number;
+  readonly private_key?: string;
+  readonly privateKey?: string;
+  readonly webhook_secret?: string;
+  readonly webhookSecret?: string;
+  readonly webhook_path?: string;
+  readonly webhookPath?: string;
+  readonly poll_interval?: number;
+  readonly pollInterval?: number;
+  readonly auto_reply_repos?: readonly string[];
+  readonly autoReplyRepos?: readonly string[];
+  readonly bot_login?: string;
+  readonly botLogin?: string;
+  readonly workspace_root?: string;
+  readonly workspaceRoot?: string;
+  /** Transitional: legacy root `endpoints[]` with `context: github`. */
+  readonly endpoints?: ReadonlyArray<Partial<ResolvedGithubConfig> & {
+    readonly context?: string;
+    readonly app_id?: string | number;
+    readonly private_key?: string;
+    readonly webhook_secret?: string;
+    readonly webhook_path?: string;
+    readonly poll_interval?: number;
+    readonly auto_reply_repos?: readonly string[];
+    readonly bot_login?: string;
+    readonly workspace_root?: string;
+  }>;
+}
+
+export interface ResolvedGithubConfig {
+  readonly context: 'github';
+  readonly name: string;
+  readonly host?: string;
+  readonly appId?: string | number;
+  readonly privateKey?: string;
+  readonly webhookSecret?: string;
+  readonly webhookPath: string;
+  readonly pollInterval: number;
+  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;
+}
+
+export function resolveGithubConfig(config: GithubAdapterConfig = {}): ResolvedGithubConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'github');
+  const appIdRaw = pickCredential(
+    config.appId != null ? String(config.appId) : undefined,
+    config.app_id != null ? String(config.app_id) : undefined,
+    entry?.appId != null ? String(entry.appId) : undefined,
+    entry?.app_id != null ? String(entry.app_id) : undefined,
+    process.env.GITHUB_APP_ID,
+  );
+  const appId = appIdRaw ? (Number(appIdRaw) || appIdRaw) : undefined;
+  const privateKey = pickCredential(
+    config.privateKey,
+    config.private_key,
+    entry?.privateKey,
+    entry?.private_key,
+  ) || undefined;
+  if (!appId || !privateKey) {
+    throw new TypeError(
+      'GitHub adapter requires app_id + private_key (plugins.<key> or GITHUB_APP_ID)',
+    );
+  }
+  const name = (typeof config.name === 'string' && config.name)
+    || (typeof entry?.name === 'string' && entry.name)
+    || process.env.GITHUB_BOT_NAME
+    || 'github-bot';
+  const webhookSecret = config.webhookSecret ?? config.webhook_secret
+    ?? entry?.webhookSecret ?? entry?.webhook_secret
+    ?? process.env.GITHUB_WEBHOOK_SECRET
+    ?? undefined;
+  const host = config.host ?? entry?.host;
+  const webhookPath = normalizeWebhookPath(
+    config.webhookPath ?? config.webhook_path ?? entry?.webhookPath ?? entry?.webhook_path
+    ?? '/github/webhook',
+  );
+  const pollInterval = Number(
+    config.pollInterval ?? config.poll_interval ?? entry?.pollInterval ?? entry?.poll_interval ?? 60,
+  ) || 60;
+  const autoReplyRepos = [
+    ...(config.autoReplyRepos ?? config.auto_reply_repos
+      ?? entry?.autoReplyRepos ?? entry?.auto_reply_repos ?? []),
+  ];
+  const botLogin = config.botLogin ?? config.bot_login ?? entry?.botLogin ?? entry?.bot_login;
+  const workspaceRoot = config.workspaceRoot ?? config.workspace_root
+    ?? entry?.workspaceRoot ?? entry?.workspace_root;
+
+  return {
+    context: 'github',
+    name,
+    ...(host ? { host } : {}),
+    ...(appId != null ? { appId } : {}),
+    ...(privateKey ? { privateKey } : {}),
+    ...(webhookSecret ? { webhookSecret } : {}),
+    webhookPath,
+    pollInterval,
+    autoReplyRepos,
+    ...(botLogin ? { botLogin } : {}),
+    ...(workspaceRoot ? { 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 MessageGateway.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':
+        return item.data?.url ? `![image](${item.data.url})` : '[image]';
+      case 'link':
+        return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
+      default:
+        return String(item.data?.text ?? `[${item.type}]`);
+    }
+  }).join('');
+}
+
+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

@@ -18,6 +18,12 @@ export interface GitHubEndpointConfig {
   webhook_path?: string;
   /** 事件轮询间隔（秒，默认 60，Webhook 模式下作为降级备选） */
   poll_interval?: number;
+  /** 这些仓库的人类 Issue/PR 评论自动触发 AI（无需 @bot） */
+  auto_reply_repos?: string[];
+  /** 覆盖 App bot 登录名（默认 {slug}[bot]） */
+  bot_login?: string;
+  /** 托管 git 工作区根目录（默认 {cwd}/data/github-workspaces） */
+  workspace_root?: string;
 }
 
 // ── Channel ID ───────────────────────────────────────────────────────

package/src/webhook.ts

@@ -0,0 +1,125 @@
+/**
+ * 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;
+  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 || ''}`);
+
+  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,158 @@
+/**
+ * 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_RE = /[\s\x00-\x1f\x7f~^:?*[\\`;]/;
+
+/**
+ * 校验 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('..') ||
+    GIT_REF_ILLEGAL_RE.test(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}`;
+  }
+}