@zhin.js/adapter-github 3.0.0 → 3.0.2

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

@@ -3,23 +3,22 @@
  */
 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 { buildChannelId, parseChannelId, type GitHubEndpointConfig, type IssueCommentPayload, type PRReviewCommentPayload, type PRReviewPayload } from './types.js';
+
 import type { GitHubAdapter } from './adapter.js';
 import { GhClient } from './gh-client.js';
+import { fromCanonicalSegments, toCanonicalSegments } from './segment-mapper.js';
+
+/** GitHub @mention：支持 zhin-ai[bot] 等 App bot 用户名 */
+const GITHUB_MENTION_RE = /@([^\s@]+(?:\[bot\])?)/g;
 
 export function parseMarkdown(md: string): MessageSegment[] {
   const segments: MessageSegment[] = [];
-  const mentionRe = /@(\w[-\w]*)/g;
   let lastIdx = 0;
   let match: RegExpExecArray | null;
-  while ((match = mentionRe.exec(md)) !== null) {
+  while ((match = GITHUB_MENTION_RE.exec(md)) !== null) {
     if (match.index > lastIdx) segments.push({ type: 'text', data: { text: md.slice(lastIdx, match.index) } });
     segments.push({ type: 'at', data: { id: match[1], name: match[1], text: match[0] } });
     lastIdx = match.index + match[0].length;
@@ -28,12 +27,41 @@ export function parseMarkdown(md: string): MessageSegment[] {
   return segments.length ? segments : [{ type: 'text', data: { text: md } }];
 }
 
+export function shouldAutoReplyRepo(config: GitHubEndpointConfig, repo: string): boolean {
+  const list = config.auto_reply_repos;
+  if (!list?.length) return false;
+  const key = repo.toLowerCase();
+  return list.some((r) => r.toLowerCase() === key);
+}
+
+export function enrichGithubInboundMessage<T extends object>(
+  message: Message<T>,
+  config: GitHubEndpointConfig,
+  gh: GhClient,
+  repo: string,
+): Message<T> {
+  const botLogin = config.bot_login || gh.getBotLogin();
+  if (botLogin && shouldAutoReplyRepo(config, repo)) {
+    const hasBotAt = message.$content.some(
+      (seg) => (seg.type === 'at' || seg.type === 'mention') && seg.data?.id === botLogin,
+    );
+    if (!hasBotAt) {
+      message.$content = [
+        { type: 'at', data: { id: botLogin, name: botLogin, text: `@${botLogin}` } },
+        ...message.$content,
+      ];
+    }
+  }
+  return message;
+}
+
 export function toMarkdown(content: SendContent): string {
   if (!Array.isArray(content)) content = [content];
   return content.map(seg => {
     if (typeof seg === 'string') return seg;
     switch (seg.type) {
       case 'text': return seg.data.text || '';
+      case 'mention': return `@${seg.data.name || seg.data.target}`;
       case 'at': return `@${seg.data.name || seg.data.id}`;
       case 'image': return seg.data.url ? `![image](${seg.data.url})` : '[image]';
       case 'link': return `[${seg.data.text || seg.data.url}](${seg.data.url})`;
@@ -45,6 +73,8 @@ export function toMarkdown(content: SendContent): string {
 export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueCommentPayload> {
   $connected = false;
   gh: GhClient;
+  /** App bot 登录名，供 @ 触发匹配 */
+  $platformUserId?: string;
 
   get $id() { return this.$config.name; }
 
@@ -63,8 +93,9 @@ export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueComme
   async $connect(): Promise<void> {
     const result = await this.gh.verifyAuth();
     if (!result.ok) throw new Error(`GitHub 认证失败: ${result.message}`);
+    this.$platformUserId = this.$config.bot_login || this.gh.getBotLogin() || undefined;
     this.$connected = true;
-    this.logger.info(formatCompact({ endpoint: this.$id }));
+    this.logger.debug(formatCompact({ endpoint: this.$id, bot: this.$platformUserId }));
   }
 
   async $disconnect(): Promise<void> {
@@ -85,7 +116,7 @@ export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueComme
       $endpoint: this.$config.name,
       $sender: { id: payload.sender.login, name: payload.sender.login },
       $channel: { id: channelId, type: 'group' },
-      $content: parseMarkdown(payload.comment.body),
+      $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); },
@@ -115,7 +146,7 @@ export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueComme
       $endpoint: this.$config.name,
       $sender: { id: payload.sender.login, name: payload.sender.login },
       $channel: { id: channelId, type: 'group' },
-      $content: parseMarkdown(body),
+      $content: toCanonicalSegments(parseMarkdown(body)),
       $raw: body,
       $timestamp: new Date(payload.comment.created_at).getTime(),
       $recall: async () => { await gh.deletePRReviewComment(repo, payload.comment.id); },
@@ -145,7 +176,7 @@ export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueComme
       $endpoint: this.$config.name,
       $sender: { id: payload.sender.login, name: payload.sender.login },
       $channel: { id: channelId, type: 'group' },
-      $content: parseMarkdown(body),
+      $content: toCanonicalSegments(parseMarkdown(body)),
       $raw: body,
       $timestamp: new Date(payload.review.submitted_at).getTime(),
       $recall: async () => {},
@@ -160,7 +191,10 @@ export class GitHubEndpoint implements Endpoint<GitHubEndpointConfig, IssueComme
     const parsed = parseChannelId(options.id);
     if (!parsed) throw new Error(`无效的 GitHub channel ID: ${options.id}`);
 
-    const text = toMarkdown(coerceQrcodeSegmentsToText(options.content ?? ''));
+    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));
     const r = parsed.type === 'issue'
       ? await this.gh.createIssueComment(parsed.repo, parsed.number, text)
       : await this.gh.createPRComment(parsed.repo, parsed.number, text);

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:${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-agent-deps.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared runtime deps for github agent/ authoring tools.
+ */
+import type { Plugin } from 'zhin.js';
+import type { GitHubAdapter } from './adapter.js';
+import type { WorkspaceManager } from './workspace-manager.js';
+
+export interface GithubAgentDeps {
+  getAdapter: () => GitHubAdapter;
+  getWorkspaceManager: () => WorkspaceManager;
+  plugin: Plugin;
+}
+
+let _deps: GithubAgentDeps | null = null;
+
+export function setGithubAgentDeps(deps: GithubAgentDeps): void {
+  _deps = deps;
+}
+
+export function getGithubAgentDeps(): GithubAgentDeps {
+  if (!_deps) throw new Error('github agent deps not initialized');
+  return _deps;
+}
+
+export function getAdapter(): GitHubAdapter {
+  return getGithubAgentDeps().getAdapter();
+}

package/src/github-bot-handlers.ts

@@ -0,0 +1,109 @@
+/**
+ * GitHub App Bot workflow handlers (Installation Token identity).
+ */
+import type { Message } from 'zhin.js';
+import { getCurrentCommMessage } from '@zhin.js/agent/security';
+import { getAdapter, getGithubAgentDeps } from './github-agent-deps.js';
+import {
+  parseMessageChannel,
+  resolveWorkspaceBranch,
+  formatChannelContext,
+} from './github-channel-context.js';
+
+function requireBotGh() {
+  const gh = getAdapter().getAPI();
+  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 },
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh();
+  const wm = getGithubAgentDeps().getWorkspaceManager();
+  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 },
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh();
+  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 },
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh();
+  const wm = getGithubAgentDeps().getWorkspaceManager();
+  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 },
+  commMessage?: Message,
+) {
+  const msg = resolveCommMessage(commMessage);
+  const ctx = resolveChannel(msg, args.repo);
+  const gh = requireBotGh();
+  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);
+}