Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

65.2 KB
Raw Blame
/**
 * GitHub REST API v3 客户端。
 *
 * 零外部依赖 — 默认用全局 fetch(Node 18+ / Electron 28+),也可经
 * `GithubClientConfig.fetchImpl` 注入自己的实现(desktop 注入代理感知 fetch:Node /
 * Electron 主进程下的全局 fetch 是 undici,不读系统代理)。所有方法均可在 main / server 进程直接调用。
 *
 * 与 @cindy/gitlab-client 接口形状对齐,差异点:
 *   - GitHub 用 `number` 标识 issue/PR(GitLab 是 `iid`)
 *   - GitHub 路径是 `/repos/{owner}/{repo}/...`(GitLab 是 `/projects/{id}/...`)
 *   - 认证 header 是 `Authorization: Bearer <token>`(GitLab 是 `PRIVATE-TOKEN: <token>`)
 *   - GitHub PR 叫 Pull Request(GitLab 叫 Merge Request)
 */

import type {
  GithubClientConfig,
  GithubIssue,
  GithubComment,
  GithubPullRequest,
  GithubPullReview,
  GithubPullReviewComment,
  GithubLabel,
  GithubBranch,
  GithubUser,
  GithubUserFull,
  GithubOrg,
  GithubRepo,
  GithubEvent,
  GithubCommit,
  GithubCompareResult,
  GithubSearchResult,
  GithubWorkflowRun,
  GithubWorkflowJob,
  GithubWorkflow,
  GithubCheckRun,
  GithubDeployment,
  GithubRelease,
  GithubTag,
  GithubReadme,
  GithubContent,
  ListIssuesParams,
  CreateIssueParams,
  CreatePullRequestParams,
  ListPullRequestsParams,
  ListCommitsParams,
  ListEventsParams,
  SearchParams,
  ListWorkflowRunsParams,
  DispatchWorkflowParams,
  ListCheckRunsParams,
  ListDeploymentsParams,
  CreateReleaseParams,
  GithubNotificationThread,
  GithubArtifact,
  GithubTopics,
  GithubContributor,
  GithubLanguages,
  GithubHook,
  GithubBranchProtection,
  GithubTeam,
  GithubGist,
  GithubRequestedReviewers,
  GithubFileCommitResult,
  GithubFileContent,
  RequestReviewersParams,
  CreatePullReviewParams,
  CreatePullReviewCommentParams,
  UpdateIssueParams,
  UpdatePullRequestParams,
  ListNotificationsParams,
  CreateOrUpdateFileContentsParams,
  DeleteFileParams,
  ListForksParams,
  CreateForkParams,
  ListCollaboratorsParams,
  ListOrgMembersParams,
  ListGistsParams,
  GithubReaction,
  GithubReactionContent,
  AddReactionParams,
  GithubGitRef,
  GithubGitTree,
  GithubGitTreeItem,
  GithubGitCommit,
  CreateRefParams,
  CreateTreeParams,
  CreateCommitParams,
  PushFilesParams,
  PushFilesResult,
  CreateRepositoryParams,
  GithubReleaseAsset,
  AddSubIssueParams,
} from './types.js';
import { GithubApiError } from './types.js';
import { assertSafeBaseUrl, fetchWithSafeRedirect } from './http-safety.js';

const DEFAULT_BASE_URL = 'https://api.github.com';

// 去尾部斜杠。不用 /\/+$/ 正则——超长 '/' 串上会 O(n²) 回溯(CodeQL js/polynomial-redos)。
function trimTrailingSlashes(s: string): string {
  let end = s.length;
  while (end > 0 && s.charCodeAt(end - 1) === 0x2f) end -= 1;
  return s.slice(0, end);
}

export class GithubClient {
  private readonly baseUrl: string;
  private readonly token: string;
  /** Raw owner / repo, used by GraphQL queries that need them as separate variables.
   * null when the client was constructed without a repo (user-scope). */
  private readonly owner: string | null;
  private readonly repo: string | null;
  /** URL-encoded `<owner>/<repo>`, or null when the client was constructed
   * without a repo (user-scope / search / graphql). Repo-scoped methods route
   * through {@link requireRepo} which throws a clear error in that case. */
  private readonly repoPath: string | null;
  /**
   * GraphQL 完整 URL。github.com 上是 `${baseUrl}/graphql`(baseUrl 本身就是
   * `api.github.com`);GHE 场景 baseUrl 是 `https://<host>/api/v3`(REST 前缀),
   * 但 GraphQL 走 `/api/graphql` —— 路径前缀不同,必须单独算,不能复用 request()。
   * 见 https://docs.github.com/en/enterprise-server/graphql/guides
   */
  private readonly graphqlUrl: string;
  /** 出网通道(见 GithubClientConfig.fetchImpl)。 */
  private readonly fetchImpl: typeof fetch;

  constructor(config: GithubClientConfig) {
    this.baseUrl = trimTrailingSlashes(config.baseUrl ?? DEFAULT_BASE_URL);
    // GitHub(含 GHE)惯例强制 https(源自已退役的 shared/connectorUrl.ts 的 forceHttps 惯例,该模块已随 lizi_gitlab 于 2026-07-14 退役删除),
    // 故默认拒绝非 loopback 的 http,并拒绝非 http(s) 协议 / userinfo / 不可解析的 baseUrl。
    assertSafeBaseUrl(this.baseUrl);
    this.token = config.token;
    this.owner = config.owner ?? null;
    this.repo = config.repo ?? null;
    this.repoPath =
      config.owner && config.repo
        ? `${encodeURIComponent(config.owner)}/${encodeURIComponent(config.repo)}`
        : null;
    // GHE 的 baseUrl 末尾是 '/api/v3',把它剥掉换成 '/api' 后拼 '/graphql'。
    // github.com 的 baseUrl 是 'https://api.github.com',正则不匹配,直接拼 '/graphql'。
    this.graphqlUrl = `${this.baseUrl.replace(/\/api\/v3$/, '/api')}/graphql`;
    this.fetchImpl = config.fetchImpl ?? fetch;
  }

  /** Return the encoded repo path or fail fast when the caller invoked a
   * repo-scoped endpoint without configuring owner/repo. */
  private requireRepo(): string {
    if (!this.repoPath) {
      throw new Error(
        'GithubClient: owner and repo are required for repo-scoped calls',
      );
    }
    return this.repoPath;
  }

  /** 把 params 对象里非 undefined 的字段拼成 URLSearchParams,统一 querystring 构造。 */
  private qs(params: Record<string, string | number | boolean | undefined>): string {
    const usp = new URLSearchParams();
    for (const [k, v] of Object.entries(params)) {
      if (v === undefined || v === null || v === '') continue;
      usp.set(k, String(v));
    }
    const s = usp.toString();
    return s ? `?${s}` : '';
  }

  // ── Issues ───────────────────────────────────────────────────────────────

  async listIssues(params: ListIssuesParams = {}): Promise<GithubIssue[]> {
    return this.get<GithubIssue[]>(`/repos/${this.requireRepo()}/issues${this.qs({ ...params })}`);
  }

  async getIssue(issueNumber: number): Promise<GithubIssue> {
    return this.get<GithubIssue>(`/repos/${this.requireRepo()}/issues/${issueNumber}`);
  }

  async createIssue(params: CreateIssueParams): Promise<GithubIssue> {
    return this.post<GithubIssue>(`/repos/${this.requireRepo()}/issues`, {
      title: params.title,
      body: params.body,
      labels: params.labels,
      assignees: params.assignees,
    });
  }

  async getIssueComments(issueNumber: number): Promise<GithubComment[]> {
    return this.get<GithubComment[]>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/comments?per_page=100`,
    );
  }

  async addIssueComment(issueNumber: number, body: string): Promise<GithubComment> {
    return this.post<GithubComment>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/comments`,
      { body },
    );
  }

  /** 增删 issue label(GitHub PATCH 不支持增量,需先 GET 拿现有再合并) */
  async updateIssueLabels(
    issueNumber: number,
    addLabels: string[],
    removeLabels: string[],
  ): Promise<GithubIssue> {
    const current = await this.getIssue(issueNumber);
    const currentNames = new Set(current.labels.map((l) => l.name));
    for (const name of addLabels) currentNames.add(name);
    for (const name of removeLabels) currentNames.delete(name);
    return this.patch<GithubIssue>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}`,
      { labels: Array.from(currentNames) },
    );
  }

  // ── Pull Requests ────────────────────────────────────────────────────────

  /** 单条 PR 详情(含 merged / draft / merged_at,用于状态展示)。 */
  async getPullRequest(prNumber: number): Promise<GithubPullRequest> {
    return this.get<GithubPullRequest>(`/repos/${this.requireRepo()}/pulls/${prNumber}`);
  }

  async listPullRequests(params: ListPullRequestsParams = {}): Promise<GithubPullRequest[]> {
    return this.get<GithubPullRequest[]>(
      `/repos/${this.requireRepo()}/pulls${this.qs({ ...params })}`,
    );
  }

  /**
   * 创建 PR。跨 fork 场景 `sourceBranch`(head)必须带 fork owner 前缀
   * `forkOwner:branch`,否则 GitHub 返 422 head invalid;head 与 base 同仓时裸分支名即可。
   */
  async createPullRequest(params: CreatePullRequestParams): Promise<GithubPullRequest> {
    return this.post<GithubPullRequest>(
      `/repos/${this.requireRepo()}/pulls`,
      {
        head: params.sourceBranch,
        base: params.targetBranch,
        title: params.title,
        body: params.body,
        draft: params.draft,
      },
    );
  }

  /** PR 变更文件列表(含 patch)。分页,默认拉第一页 100 条,大 PR 需外部再翻页。 */
  async listPullRequestFiles(
    prNumber: number,
    params: { per_page?: number; page?: number } = {},
  ): Promise<Array<import('./types.js').GithubCommitFile>> {
    return this.get(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/files${this.qs({
        per_page: params.per_page ?? 100,
        page: params.page,
      })}`,
    );
  }

  /** PR 关联的 commit 列表(按顺序)。 */
  async listPullRequestCommits(
    prNumber: number,
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubCommit[]> {
    return this.get<GithubCommit[]>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/commits${this.qs({
        per_page: params.per_page ?? 100,
        page: params.page,
      })}`,
    );
  }

  /** PR reviews(approve / request-changes / comment,不是 conversation comment)。 */
  async listPullRequestReviews(prNumber: number): Promise<GithubPullReview[]> {
    return this.get<GithubPullReview[]>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/reviews?per_page=100`,
    );
  }

  /** PR review 里的 inline code comment。 */
  async listPullRequestReviewComments(prNumber: number): Promise<GithubPullReviewComment[]> {
    return this.get<GithubPullReviewComment[]>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/comments?per_page=100`,
    );
  }

  /** 合并 PR。merge_method: 'merge' | 'squash' | 'rebase'。 */
  async mergePullRequest(
    prNumber: number,
    params: {
      commit_title?: string;
      commit_message?: string;
      sha?: string;
      merge_method?: 'merge' | 'squash' | 'rebase';
    } = {},
  ): Promise<{ sha: string; merged: boolean; message: string }> {
    return this.put(`/repos/${this.requireRepo()}/pulls/${prNumber}/merge`, params);
  }

  // ── Labels ───────────────────────────────────────────────────────────────

  /** 列出仓库所有 label(per_page=100 一页够用) */
  async listLabels(): Promise<GithubLabel[]> {
    return this.get<GithubLabel[]>(`/repos/${this.requireRepo()}/labels?per_page=100`);
  }

  /** 列出仓库所有分支 */
  async listBranches(): Promise<GithubBranch[]> {
    return this.get<GithubBranch[]>(`/repos/${this.requireRepo()}/branches?per_page=100`);
  }

  /** 列出仓库所有 tag(按 commit date 倒序,分页) */
  async listTags(params: { per_page?: number; page?: number } = {}): Promise<GithubTag[]> {
    return this.get<GithubTag[]>(
      `/repos/${this.requireRepo()}/tags${this.qs({ ...params })}`,
    );
  }

  /** 获取仓库 README(base64 content,和 getContents 文件返回结构一致)。 */
  async getReadme(params: { ref?: string } = {}): Promise<GithubReadme> {
    return this.get<GithubReadme>(
      `/repos/${this.requireRepo()}/readme${this.qs({ ref: params.ref })}`,
    );
  }

  /** 确保 label 存在;已存在则忽略(422 → swallow) */
  async ensureLabels(names: string[]): Promise<void> {
    const existing = await this.listLabels();
    const existingNames = new Set(existing.map((l) => l.name));
    for (const name of names) {
      if (existingNames.has(name)) continue;
      try {
        await this.post(`/repos/${this.requireRepo()}/labels`, {
          name,
          color: '428BCA',
        });
      } catch (err) {
        if (err instanceof GithubApiError && err.status === 422) continue;
        throw err;
      }
    }
  }

  // ── Repository ──────────────────────────────────────────────────────────

  /** 单个仓库元信息 */
  async getRepo(): Promise<GithubRepo> {
    return this.get<GithubRepo>(`/repos/${this.requireRepo()}`);
  }

  /**
   * 获取仓库内文件/目录内容。path='' 拿仓库根。
   * ref 可以是 branch / tag / commit sha。默认走仓库默认分支。
   * 返回值:文件 → 单个对象;目录 → 对象数组。
   */
  async getContents(path: string, ref?: string): Promise<GithubContent> {
    const encodedPath = path.split('/').map(encodeURIComponent).join('/');
    return this.get<GithubContent>(
      `/repos/${this.requireRepo()}/contents/${encodedPath}${this.qs({ ref })}`,
    );
  }

  // ── Commits ─────────────────────────────────────────────────────────────

  async listCommits(params: ListCommitsParams = {}): Promise<GithubCommit[]> {
    return this.get<GithubCommit[]>(
      `/repos/${this.requireRepo()}/commits${this.qs({ ...params })}`,
    );
  }

  async getCommit(sha: string): Promise<GithubCommit> {
    return this.get<GithubCommit>(`/repos/${this.requireRepo()}/commits/${sha}`);
  }

  /** compare_commits: /repos/{o}/{r}/compare/{base}...{head} */
  async compareCommits(base: string, head: string): Promise<GithubCompareResult> {
    return this.get<GithubCompareResult>(
      `/repos/${this.requireRepo()}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`,
    );
  }

  // ── Events ──────────────────────────────────────────────────────────────

  /** 认证用户能看到的 events(公开 + 关注的 + 自己的私有)。 */
  async listAuthenticatedUserEvents(
    username: string,
    params: ListEventsParams = {},
  ): Promise<GithubEvent[]> {
    return this.get<GithubEvent[]>(
      `/users/${encodeURIComponent(username)}/events${this.qs({ ...params })}`,
    );
  }

  /**
   * 认证用户在某 org 内能看到的 events(GET /users/:u/events/orgs/:org)。
   * 与 `listOrgEvents` 走的 /orgs/:org/events 公开源不同 —— 这个端点会包含
   * username 在 org 里 access 到的私有 repo 活动,work-collect 类场景该用它。
   */
  async listAuthenticatedUserOrgEvents(
    username: string,
    org: string,
    params: ListEventsParams = {},
  ): Promise<GithubEvent[]> {
    return this.get<GithubEvent[]>(
      `/users/${encodeURIComponent(username)}/events/orgs/${encodeURIComponent(org)}${this.qs({ ...params })}`,
    );
  }

  /** 指定 user 的公开 events(不需要认证,但走认证可提升 rate limit)。 */
  async listUserPublicEvents(
    username: string,
    params: ListEventsParams = {},
  ): Promise<GithubEvent[]> {
    return this.get<GithubEvent[]>(
      `/users/${encodeURIComponent(username)}/events/public${this.qs({ ...params })}`,
    );
  }

  /** org 的 events(需 org 成员权限)。 */
  async listOrgEvents(
    org: string,
    params: ListEventsParams = {},
  ): Promise<GithubEvent[]> {
    return this.get<GithubEvent[]>(
      `/orgs/${encodeURIComponent(org)}/events${this.qs({ ...params })}`,
    );
  }

  /** 仓库的 events。 */
  async listRepoEvents(params: ListEventsParams = {}): Promise<GithubEvent[]> {
    return this.get<GithubEvent[]>(
      `/repos/${this.requireRepo()}/events${this.qs({ ...params })}`,
    );
  }

  // ── Search ──────────────────────────────────────────────────────────────

  /** 搜索仓库。q 语法见 https://docs.github.com/search-github/searching-on-github/searching-for-repositories */
  async searchRepos(params: SearchParams): Promise<GithubSearchResult<GithubRepo>> {
    return this.get(`/search/repositories${this.qs({ ...params })}`);
  }

  /**
   * 搜索 issue / PR(GitHub 把 issue 和 PR 归到同一个 /search/issues endpoint,
   * 通过 q 里的 `is:pr` / `is:issue` 或 `type:pr` / `type:issue` 过滤)。
   */
  async searchIssuesAndPRs(params: SearchParams): Promise<GithubSearchResult<GithubIssue>> {
    return this.get(`/search/issues${this.qs({ ...params })}`);
  }

  async searchCommits(params: SearchParams): Promise<GithubSearchResult<GithubCommit>> {
    return this.get(`/search/commits${this.qs({ ...params })}`);
  }

  async searchCode(params: SearchParams): Promise<
    GithubSearchResult<{
      name: string;
      path: string;
      sha: string;
      html_url: string;
      repository: GithubRepo;
    }>
  > {
    return this.get(`/search/code${this.qs({ ...params })}`);
  }

  async searchUsers(params: SearchParams): Promise<GithubSearchResult<GithubUser>> {
    return this.get(`/search/users${this.qs({ ...params })}`);
  }

  // ── Users / Orgs ────────────────────────────────────────────────────────

  async getUser(username: string): Promise<GithubUserFull> {
    return this.get<GithubUserFull>(`/users/${encodeURIComponent(username)}`);
  }

  async listUserOrgs(username: string): Promise<GithubOrg[]> {
    return this.get<GithubOrg[]>(
      `/users/${encodeURIComponent(username)}/orgs?per_page=100`,
    );
  }

  /** 认证用户能访问的仓库(含私有)。 */
  async listAuthenticatedUserRepos(
    params: {
      visibility?: 'all' | 'public' | 'private';
      affiliation?: string;
      type?: 'all' | 'owner' | 'public' | 'private' | 'member';
      sort?: 'created' | 'updated' | 'pushed' | 'full_name';
      direction?: 'asc' | 'desc';
      per_page?: number;
      page?: number;
    } = {},
  ): Promise<GithubRepo[]> {
    return this.get<GithubRepo[]>(`/user/repos${this.qs({ ...params })}`);
  }

  /** org 的所有仓库(需可见性权限)。 */
  async listOrgRepos(
    org: string,
    params: {
      type?: 'all' | 'public' | 'private' | 'forks' | 'sources' | 'member';
      sort?: 'created' | 'updated' | 'pushed' | 'full_name';
      direction?: 'asc' | 'desc';
      per_page?: number;
      page?: number;
    } = {},
  ): Promise<GithubRepo[]> {
    return this.get<GithubRepo[]>(
      `/orgs/${encodeURIComponent(org)}/repos${this.qs({ ...params })}`,
    );
  }

  // ── Actions (workflows / workflow runs) ─────────────────────────────────

  /** 列出仓库的 workflow 定义(不是 run)。 */
  async listWorkflows(
    params: { per_page?: number; page?: number } = {},
  ): Promise<{ total_count: number; workflows: GithubWorkflow[] }> {
    return this.get(
      `/repos/${this.requireRepo()}/actions/workflows${this.qs({ ...params })}`,
    );
  }

  /**
   * 触发一个 workflow_dispatch 事件。workflowIdOrFileName 可以是数字 id,
   * 也可以是 workflow 文件名(如 'ci.yml')。204 No Content。
   */
  async dispatchWorkflow(
    workflowIdOrFileName: number | string,
    params: DispatchWorkflowParams,
  ): Promise<void> {
    const id = encodeURIComponent(String(workflowIdOrFileName));
    await this.post<void>(
      `/repos/${this.requireRepo()}/actions/workflows/${id}/dispatches`,
      { ref: params.ref, inputs: params.inputs },
    );
  }

  /** 重跑一次 workflow run(与原 run 同一 event、同一 sha)。 */
  async rerunWorkflowRun(runId: number): Promise<void> {
    await this.post<void>(
      `/repos/${this.requireRepo()}/actions/runs/${runId}/rerun`,
      {},
    );
  }

  /** 取消进行中的 workflow run。 */
  async cancelWorkflowRun(runId: number): Promise<void> {
    await this.post<void>(
      `/repos/${this.requireRepo()}/actions/runs/${runId}/cancel`,
      {},
    );
  }

  async listWorkflowRuns(
    params: ListWorkflowRunsParams = {},
  ): Promise<{ total_count: number; workflow_runs: GithubWorkflowRun[] }> {
    return this.get(
      `/repos/${this.requireRepo()}/actions/runs${this.qs({ ...params })}`,
    );
  }

  async getWorkflowRun(runId: number): Promise<GithubWorkflowRun> {
    return this.get<GithubWorkflowRun>(
      `/repos/${this.requireRepo()}/actions/runs/${runId}`,
    );
  }

  async listWorkflowRunJobs(
    runId: number,
    params: { filter?: 'latest' | 'all'; per_page?: number; page?: number } = {},
  ): Promise<{ total_count: number; jobs: GithubWorkflowJob[] }> {
    return this.get(
      `/repos/${this.requireRepo()}/actions/runs/${runId}/jobs${this.qs({ ...params })}`,
    );
  }

  // ── Releases ────────────────────────────────────────────────────────────

  async listReleases(params: { per_page?: number; page?: number } = {}): Promise<GithubRelease[]> {
    return this.get<GithubRelease[]>(
      `/repos/${this.requireRepo()}/releases${this.qs({ ...params })}`,
    );
  }

  async getReleaseByTag(tag: string): Promise<GithubRelease> {
    return this.get<GithubRelease>(
      `/repos/${this.requireRepo()}/releases/tags/${encodeURIComponent(tag)}`,
    );
  }

  /** 创建 release。tag 不存在时 GitHub 会自动在 target_commitish 上打 tag。 */
  async createRelease(params: CreateReleaseParams): Promise<GithubRelease> {
    return this.post<GithubRelease>(`/repos/${this.requireRepo()}/releases`, {
      tag_name: params.tag_name,
      target_commitish: params.target_commitish,
      name: params.name,
      body: params.body,
      draft: params.draft,
      prerelease: params.prerelease,
      generate_release_notes: params.generate_release_notes,
    });
  }

  // ── Checks ──────────────────────────────────────────────────────────────

  /** 列出某 ref(commit sha / branch / tag)上的 check runs。 */
  async listCheckRunsForRef(
    ref: string,
    params: ListCheckRunsParams = {},
  ): Promise<{ total_count: number; check_runs: GithubCheckRun[] }> {
    return this.get(
      `/repos/${this.requireRepo()}/commits/${encodeURIComponent(ref)}/check-runs${this.qs({ ...params })}`,
    );
  }

  // ── Deployments ─────────────────────────────────────────────────────────

  async listDeployments(params: ListDeploymentsParams = {}): Promise<GithubDeployment[]> {
    return this.get<GithubDeployment[]>(
      `/repos/${this.requireRepo()}/deployments${this.qs({ ...params })}`,
    );
  }

  // ── GraphQL ──────────────────────────────────────────────────────────────

  /**
   * 通用 GraphQL 查询。REST 缺口场景用(如 review thread 的 resolved 状态只有
   * GraphQL 暴露)。响应含 errors 时抛 GithubApiError。
   *
   * 不走 request() 是因为 GHE 的 GraphQL 路径(`/api/graphql`)和 REST 路径
   * (`/api/v3/...`)前缀不同 —— request() 一律用 baseUrl 拼,GHE 上会拼成
   * `/api/v3/graphql` 拿到 404。graphqlUrl 在构造时已算好,github.com 场景
   * 直接拼 `${baseUrl}/graphql`。
   */
  async graphql<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
    // 认证请求不跟随跨 host 重定向(同 request())。
    const res = await fetchWithSafeRedirect(this.graphqlUrl, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: 'application/vnd.github+json',
        'Content-Type': 'application/json',
        'X-GitHub-Api-Version': '2022-11-28',
      },
      body: JSON.stringify({ query, variables }),
    }, undefined, this.fetchImpl);
    if (!res.ok) {
      const text = await res.text().catch(() => '');
      throw new GithubApiError(
        `GitHub GraphQL POST failed: ${res.status}`,
        res.status,
        text,
      );
    }
    const body = (await res.json()) as {
      data?: T;
      errors?: Array<{ message: string }>;
    };
    if (body.errors && body.errors.length > 0) {
      throw new GithubApiError(
        `GitHub GraphQL failed: ${body.errors.map((e) => e.message).join('; ')}`,
        200,
        JSON.stringify(body.errors),
      );
    }
    if (body.data === undefined) {
      throw new GithubApiError('GitHub GraphQL returned no data', 200);
    }
    return body.data;
  }

  // ── Auth 验证 ────────────────────────────────────────────────────────────

  /** 验证 token 有效性,返回当前用户信息 */
  async getCurrentUser(): Promise<GithubUser> {
    return this.get<GithubUser>('/user');
  }

  // ── Issues / PR (mutations) ─────────────────────────────────────────────

  /** PATCH /repos/{o}/{r}/issues/{n}:更新 issue title / body / state / labels 等。 */
  async updateIssue(issueNumber: number, params: UpdateIssueParams): Promise<GithubIssue> {
    return this.patch<GithubIssue>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}`,
      {
        title: params.title,
        body: params.body,
        state: params.state,
        state_reason: params.state_reason,
        labels: params.labels,
        assignees: params.assignees,
      },
    );
  }

  /** POST /repos/{o}/{r}/issues/{n}/assignees:批量增加 assignee。 */
  async addIssueAssignees(issueNumber: number, assignees: string[]): Promise<GithubIssue> {
    return this.post<GithubIssue>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/assignees`,
      { assignees },
    );
  }

  /** DELETE /repos/{o}/{r}/issues/{n}/assignees:移除 assignee。 */
  async removeIssueAssignees(issueNumber: number, assignees: string[]): Promise<GithubIssue> {
    return this.request<GithubIssue>(
      'DELETE',
      `/repos/${this.requireRepo()}/issues/${issueNumber}/assignees`,
      { assignees },
    );
  }

  /** POST /repos/{o}/{r}/issues/{n}/labels:批量增加 label(不删除现有)。 */
  async addIssueLabels(issueNumber: number, labels: string[]): Promise<GithubLabel[]> {
    return this.post<GithubLabel[]>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/labels`,
      { labels },
    );
  }

  /** DELETE /repos/{o}/{r}/issues/{n}/labels/{name}:移除单个 label。 */
  async removeIssueLabel(issueNumber: number, name: string): Promise<GithubLabel[]> {
    return this.request<GithubLabel[]>(
      'DELETE',
      `/repos/${this.requireRepo()}/issues/${issueNumber}/labels/${encodeURIComponent(name)}`,
    );
  }

  /** PATCH /repos/{o}/{r}/pulls/{n}:更新 PR title / body / state / base。 */
  async updatePullRequest(
    prNumber: number,
    params: UpdatePullRequestParams,
  ): Promise<GithubPullRequest> {
    return this.patch<GithubPullRequest>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}`,
      {
        title: params.title,
        body: params.body,
        state: params.state,
        base: params.base,
      },
    );
  }

  /** POST /repos/{o}/{r}/pulls/{n}/reviews:提交一次 review(approve / request_changes / comment)。 */
  async createPullRequestReview(
    prNumber: number,
    params: CreatePullReviewParams,
  ): Promise<GithubPullReview> {
    return this.post<GithubPullReview>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/reviews`,
      {
        event: params.event,
        body: params.body,
        commit_id: params.commit_id,
        comments: params.comments,
      },
    );
  }

  /** POST /repos/{o}/{r}/pulls/{n}/comments:新增单条 inline review comment(独立于 review)。 */
  async createPullRequestReviewComment(
    prNumber: number,
    params: CreatePullReviewCommentParams,
  ): Promise<GithubPullReviewComment> {
    return this.post<GithubPullReviewComment>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/comments`,
      {
        body: params.body,
        commit_id: params.commit_id,
        path: params.path,
        line: params.line,
        side: params.side,
        start_line: params.start_line,
        start_side: params.start_side,
      },
    );
  }

  /** GET /repos/{o}/{r}/pulls/comments/{comment_id}:获取单条 review 评论。 */
  async getPullRequestReviewComment(commentId: number): Promise<GithubPullReviewComment> {
    return this.get<GithubPullReviewComment>(
      `/repos/${this.requireRepo()}/pulls/comments/${commentId}`,
    );
  }

  /**
   * POST /repos/{o}/{r}/pulls/{n}/comments/{comment_id}/replies:
   * 回复某条已有 review 评论(挂到同一线程内)。与 createPullRequestReviewComment 不同,
   * 走 replies 专用端点,只需 commentId + body,不需 commit_id/path/line。
   * GitHub API 要求 commentId 必须是线程顶层评论 ID;若传入的是回复评论 ID(有
   * in_reply_to_id),本方法会先解析到顶层 ID 再发请求,避免 404。
   */
  async replyToPullRequestReviewComment(
    prNumber: number,
    commentId: number,
    body: string,
  ): Promise<GithubPullReviewComment> {
    // 若传入的是回复评论(有 in_reply_to_id),解析到顶层 ID(Codex P2)。
    const comment = await this.getPullRequestReviewComment(commentId);
    const topLevelId = comment.in_reply_to_id ?? commentId;
    return this.post<GithubPullReviewComment>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/comments/${topLevelId}/replies`,
      { body },
    );
  }

  /** POST /repos/{o}/{r}/pulls/{n}/requested_reviewers:请求 reviewer。 */
  async requestPullRequestReviewers(
    prNumber: number,
    params: RequestReviewersParams,
  ): Promise<GithubPullRequest> {
    return this.post<GithubPullRequest>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/requested_reviewers`,
      { reviewers: params.reviewers, team_reviewers: params.team_reviewers },
    );
  }

  /** DELETE /repos/{o}/{r}/pulls/{n}/requested_reviewers:移除已请求的 reviewer。 */
  async removePullRequestReviewers(
    prNumber: number,
    params: RequestReviewersParams,
  ): Promise<GithubPullRequest> {
    return this.request<GithubPullRequest>(
      'DELETE',
      `/repos/${this.requireRepo()}/pulls/${prNumber}/requested_reviewers`,
      { reviewers: params.reviewers, team_reviewers: params.team_reviewers },
    );
  }

  /** GET /repos/{o}/{r}/pulls/{n}/requested_reviewers。 */
  async listPullRequestRequestedReviewers(prNumber: number): Promise<GithubRequestedReviewers> {
    return this.get<GithubRequestedReviewers>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/requested_reviewers`,
    );
  }

  // ── Notifications ───────────────────────────────────────────────────────

  /** GET /notifications:当前用户的 notification threads。user-scope。 */
  async listNotifications(params: ListNotificationsParams = {}): Promise<GithubNotificationThread[]> {
    return this.get<GithubNotificationThread[]>(`/notifications${this.qs({ ...params })}`);
  }

  /** PATCH /notifications/threads/{id}:标记一条 notification 已读。 */
  async markNotificationRead(threadId: string): Promise<void> {
    await this.patch<void>(`/notifications/threads/${encodeURIComponent(threadId)}`);
  }

  // ── Actions: artifacts / logs (extended) ────────────────────────────────

  /** GET /repos/{o}/{r}/actions/runs/{run_id}/artifacts */
  async listWorkflowRunArtifacts(
    runId: number,
    params: { per_page?: number; page?: number } = {},
  ): Promise<{ total_count: number; artifacts: GithubArtifact[] }> {
    return this.get(
      `/repos/${this.requireRepo()}/actions/runs/${runId}/artifacts${this.qs({ ...params })}`,
    );
  }

  /**
   * GET /repos/{o}/{r}/actions/artifacts/{id}/zip → 302 redirect。返回 Location URL,
   * 调用方直接下载(URL 时效通常 1 分钟)。
   */
  async getArtifactDownloadUrl(artifactId: number): Promise<string | null> {
    return this.requestRedirectUrl(
      'GET',
      `/repos/${this.requireRepo()}/actions/artifacts/${artifactId}/zip`,
    );
  }

  /**
   * GET /repos/{o}/{r}/actions/runs/{run_id}/logs → 302 redirect。返回 Location URL,
   * 调用方直接下载 zip 格式的日志文件。
   */
  async getWorkflowRunLogsUrl(runId: number): Promise<string | null> {
    return this.requestRedirectUrl(
      'GET',
      `/repos/${this.requireRepo()}/actions/runs/${runId}/logs`,
    );
  }

  // ── Repository (topics / contributors / languages / forks / etc.) ──────

  /** GET /repos/{o}/{r}/topics */
  async listRepoTopics(): Promise<GithubTopics> {
    return this.get<GithubTopics>(`/repos/${this.requireRepo()}/topics`);
  }

  /** PUT /repos/{o}/{r}/topics:整表替换 topics 列表。 */
  async replaceRepoTopics(names: string[]): Promise<GithubTopics> {
    return this.put<GithubTopics>(`/repos/${this.requireRepo()}/topics`, { names });
  }

  /** GET /repos/{o}/{r}/contributors */
  async listRepoContributors(
    params: { anon?: boolean; per_page?: number; page?: number } = {},
  ): Promise<GithubContributor[]> {
    return this.get<GithubContributor[]>(
      `/repos/${this.requireRepo()}/contributors${this.qs({
        anon: params.anon,
        per_page: params.per_page,
        page: params.page,
      })}`,
    );
  }

  /** GET /repos/{o}/{r}/languages:language → bytes。 */
  async listRepoLanguages(): Promise<GithubLanguages> {
    return this.get<GithubLanguages>(`/repos/${this.requireRepo()}/languages`);
  }

  /** GET /repos/{o}/{r}/stargazers */
  async listStargazers(
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubUser[]> {
    return this.get<GithubUser[]>(
      `/repos/${this.requireRepo()}/stargazers${this.qs({ ...params })}`,
    );
  }

  /** GET /repos/{o}/{r}/forks */
  async listForks(params: ListForksParams = {}): Promise<GithubRepo[]> {
    return this.get<GithubRepo[]>(
      `/repos/${this.requireRepo()}/forks${this.qs({ ...params })}`,
    );
  }

  /** POST /repos/{o}/{r}/forks:创建 fork。organization 指定 fork 到某 org。 */
  async createFork(params: CreateForkParams = {}): Promise<GithubRepo> {
    return this.post<GithubRepo>(`/repos/${this.requireRepo()}/forks`, {
      organization: params.organization,
      name: params.name,
      default_branch_only: params.default_branch_only,
    });
  }

  /** GET /repos/{o}/{r}/collaborators */
  async listRepoCollaborators(params: ListCollaboratorsParams = {}): Promise<GithubUser[]> {
    return this.get<GithubUser[]>(
      `/repos/${this.requireRepo()}/collaborators${this.qs({ ...params })}`,
    );
  }

  /** GET /repos/{o}/{r}/hooks */
  async listRepoHooks(): Promise<GithubHook[]> {
    return this.get<GithubHook[]>(`/repos/${this.requireRepo()}/hooks?per_page=100`);
  }

  /**
   * GET /repos/{o}/{r}/branches/{branch}/protection。分支未开启保护时 GitHub
   * 返回 404,由 client 抛 GithubApiError(status=404),caller 应映射为 NOT_FOUND。
   */
  async getBranchProtection(branch: string): Promise<GithubBranchProtection> {
    return this.get<GithubBranchProtection>(
      `/repos/${this.requireRepo()}/branches/${encodeURIComponent(branch)}/protection`,
    );
  }

  // ── Contents: create / update / delete ──────────────────────────────────

  /**
   * PUT /repos/{o}/{r}/contents/{path}:创建或更新单个文件。sha 存在时是 update,
   * 不存在时是 create。content 必须已 base64 编码。
   */
  async createOrUpdateFileContents(
    path: string,
    params: CreateOrUpdateFileContentsParams,
  ): Promise<GithubFileCommitResult> {
    const encPath = path.split('/').map(encodeURIComponent).join('/');
    return this.put<GithubFileCommitResult>(
      `/repos/${this.requireRepo()}/contents/${encPath}`,
      {
        message: params.message,
        content: params.content,
        sha: params.sha,
        branch: params.branch,
        committer: params.committer,
        author: params.author,
      },
    );
  }

  /** DELETE /repos/{o}/{r}/contents/{path}:删除单个文件(必须传当前 blob sha)。 */
  async deleteFile(path: string, params: DeleteFileParams): Promise<GithubFileCommitResult> {
    const encPath = path.split('/').map(encodeURIComponent).join('/');
    return this.request<GithubFileCommitResult>(
      'DELETE',
      `/repos/${this.requireRepo()}/contents/${encPath}`,
      {
        message: params.message,
        sha: params.sha,
        branch: params.branch,
        committer: params.committer,
        author: params.author,
      },
    );
  }

  // ── Orgs / Teams / Gists ────────────────────────────────────────────────

  /** GET /orgs/{org}/members */
  async listOrgMembers(org: string, params: ListOrgMembersParams = {}): Promise<GithubUser[]> {
    return this.get<GithubUser[]>(
      `/orgs/${encodeURIComponent(org)}/members${this.qs({ ...params })}`,
    );
  }

  /** GET /orgs/{org}/teams */
  async listOrgTeams(
    org: string,
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubTeam[]> {
    return this.get<GithubTeam[]>(
      `/orgs/${encodeURIComponent(org)}/teams${this.qs({ ...params })}`,
    );
  }

  /** GET /orgs/{org}/teams/{team_slug}/members */
  async listTeamMembers(
    org: string,
    teamSlug: string,
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubUser[]> {
    return this.get<GithubUser[]>(
      `/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(teamSlug)}/members${this.qs({ ...params })}`,
    );
  }

  /** GET /orgs/{org}/teams/{team_slug}/repos */
  async listTeamRepos(
    org: string,
    teamSlug: string,
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubRepo[]> {
    return this.get<GithubRepo[]>(
      `/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(teamSlug)}/repos${this.qs({ ...params })}`,
    );
  }

  /** GET /gists:当前用户的 gist(user-scope)。 */
  async listGists(params: ListGistsParams = {}): Promise<GithubGist[]> {
    return this.get<GithubGist[]>(`/gists${this.qs({ ...params })}`);
  }

  /** GET /gists/{id} */
  async getGist(id: string): Promise<GithubGist> {
    return this.get<GithubGist>(`/gists/${encodeURIComponent(id)}`);
  }

  // ── Pull Request reviews (pending workflow / dismiss / branch update) ───

  /**
   * 创建 pending review(body 不带 event 字段;GitHub 返回 state=PENDING 的 review)。
   * 与 createPullRequestReview 的差异:后者要求 event ∈ APPROVE/REQUEST_CHANGES/COMMENT
   * 且会立即 submit;这里刻意把 event 省掉,让 review 停留在 pending 状态,方便后续
   * 通过 addPendingPullRequestReviewComment 追加 inline comment,再一次性 submit。
   * Create a pending review (no `event` in body → state=PENDING). Use with
   * addPendingPullRequestReviewComment + submitPendingPullRequestReview.
   */
  async createPendingPullRequestReview(
    prNumber: number,
    params: { body?: string; commit_id?: string } = {},
  ): Promise<GithubPullReview> {
    return this.post<GithubPullReview>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/reviews`,
      {
        body: params.body,
        commit_id: params.commit_id,
      },
    );
  }

  /**
   * 往指定 pending review 追加 inline comment。
   *
   * ⚠️ 不能复用 POST /pulls/{n}/comments —— 那个端点会**立即发布**一条独立
   * review comment,而不是挂到当前 pending review 里。GitHub REST 只在初始
   * POST /pulls/{n}/reviews 的 body.comments 数组里接受 pending 内联评论,
   * 后续追加必须走 GraphQL 的 addPullRequestReviewThread mutation。
   *
   * 需要的 reviewNodeId 是 create pending review 响应里的 node_id
   * (`PRR_...` 前缀),不是 REST 数字 id。
   *
   * Add an inline comment to an existing pending review via GraphQL
   * addPullRequestReviewThread. reviewNodeId must be the node id returned by
   * createPendingPullRequestReview (its `node_id` field), not the numeric id.
   */
  async addPendingPullRequestReviewComment(
    reviewNodeId: string,
    params: {
      body: string;
      path: string;
      line: number;
      side?: 'LEFT' | 'RIGHT';
      startLine?: number;
      startSide?: 'LEFT' | 'RIGHT';
      subjectType?: 'LINE' | 'FILE';
    },
  ): Promise<{ threadId: string; commentId: string; databaseId: number | null }> {
    const input: Record<string, unknown> = {
      pullRequestReviewId: reviewNodeId,
      body: params.body,
      path: params.path,
      line: params.line,
    };
    if (params.side) input.side = params.side;
    if (params.startLine !== undefined) input.startLine = params.startLine;
    if (params.startSide) input.startSide = params.startSide;
    if (params.subjectType) input.subjectType = params.subjectType;
    const res = await this.graphql<{
      addPullRequestReviewThread: {
        thread: {
          id: string;
          comments: { nodes: Array<{ id: string; databaseId: number | null }> };
        };
      };
    }>(
      `mutation AddPendingReviewThread($input: AddPullRequestReviewThreadInput!) {
         addPullRequestReviewThread(input: $input) {
           thread { id comments(first: 1) { nodes { id databaseId } } }
         }
       }`,
      { input },
    );
    const t = res.addPullRequestReviewThread.thread;
    const c = t.comments.nodes[0];
    return { threadId: t.id, commentId: c?.id ?? '', databaseId: c?.databaseId ?? null };
  }

  /**
   * 提交一条 pending review:POST /pulls/{n}/reviews/{review_id}/events。
   * event 取值 APPROVE / REQUEST_CHANGES / COMMENT。
   * Submit a pending review with an approval verdict.
   */
  async submitPendingPullRequestReview(
    prNumber: number,
    reviewId: number,
    params: { event: 'APPROVE' | 'REQUEST_CHANGES' | 'COMMENT'; body?: string },
  ): Promise<GithubPullReview> {
    return this.post<GithubPullReview>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/reviews/${reviewId}/events`,
      { event: params.event, body: params.body },
    );
  }

  /**
   * 删除一条 pending review(未 submit 前可用)。
   * Delete a pending pull request review.
   */
  async deletePendingPullRequestReview(
    prNumber: number,
    reviewId: number,
  ): Promise<GithubPullReview> {
    return this.request<GithubPullReview>(
      'DELETE',
      `/repos/${this.requireRepo()}/pulls/${prNumber}/reviews/${reviewId}`,
    );
  }

  /**
   * dismiss 一条已提交的 review(PUT /reviews/{id}/dismissals)。
   * Dismiss a submitted pull request review.
   */
  async dismissPullRequestReview(
    prNumber: number,
    reviewId: number,
    params: { message: string; event?: 'DISMISS' },
  ): Promise<GithubPullReview> {
    return this.put<GithubPullReview>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/reviews/${reviewId}/dismissals`,
      { message: params.message, event: params.event ?? 'DISMISS' },
    );
  }

  /**
   * resolveReviewThread mutation(GraphQL-only)。thread_id 是 PRRT_... 节点 id。
   * Resolve a PR review thread via GraphQL.
   */
  async resolveReviewThread(threadId: string): Promise<{ thread: { id: string; isResolved: boolean } }> {
    const query = `mutation($threadId: ID!) {
      resolveReviewThread(input: {threadId: $threadId}) {
        thread { id isResolved }
      }
    }`;
    const data = await this.graphql<{ resolveReviewThread: { thread: { id: string; isResolved: boolean } } }>(
      query,
      { threadId },
    );
    return data.resolveReviewThread;
  }

  /**
   * unresolveReviewThread mutation(GraphQL-only)。
   * Unresolve a PR review thread via GraphQL.
   */
  async unresolveReviewThread(threadId: string): Promise<{ thread: { id: string; isResolved: boolean } }> {
    const query = `mutation($threadId: ID!) {
      unresolveReviewThread(input: {threadId: $threadId}) {
        thread { id isResolved }
      }
    }`;
    const data = await this.graphql<{ unresolveReviewThread: { thread: { id: string; isResolved: boolean } } }>(
      query,
      { threadId },
    );
    return data.unresolveReviewThread;
  }

  /**
   * listPullRequestReviewThreads query(GraphQL-only)。REST 不暴露 thread id,
   * 只能通过 GraphQL 拿到 PRRT_... 节点 id,供 resolveReviewThread / unresolveReviewThread 消费。
   *
   * 单页拉取(默认每页 50,GraphQL 上限 100)。PR 的 review thread 多于一页时,
   * 调用方读返回的 `pageInfo`:`hasNextPage` 为 true 时把 `endCursor` 作为 `after`
   * 再次调用继续翻页,直到 `hasNextPage` 为 false —— 保证靠后的 thread 也能拿到 id。
   *
   * 每个 thread 返回完整会话(comments 最多 50 条,含 databaseId 供与 REST 评论关联)
   * 及代码位置(path / line),避免调用方只看到首条评论就 resolve、漏掉后续未处理的追评。
   * commentsTruncated 为 true 时说明该 thread 评论超过 50 条被截断。
   *
   * List one page of PR review threads via GraphQL. When hasNextPage is true,
   * pass endCursor back as `after` to fetch the next page. Each thread includes
   * its full conversation (up to 50 comments, with databaseId for REST joins)
   * plus code location (path / line).
   */
  async listPullRequestReviewThreads(
    prNumber: number,
    params: { first?: number; after?: string } = {},
  ): Promise<{
    threads: Array<{
      id: string;
      isResolved: boolean;
      isOutdated: boolean;
      path: string | null;
      line: number | null;
      commentsTruncated: boolean;
      comments: Array<{
        id: number | null;
        body: string;
        author: { login: string } | null;
        createdAt: string;
      }>;
    }>;
    pageInfo: { hasNextPage: boolean; endCursor: string | null };
  }> {
    // GraphQL 需要 owner / repo 作为独立变量;REST 的 repoPath 是编码后的合并形式,
    // 不能直接复用。client 未配置 owner/repo 时 fail-fast,与 requireRepo() 语义一致。
    if (!this.owner || !this.repo) {
      throw new Error(
        'GithubClient: owner and repo are required for repo-scoped calls',
      );
    }
    const { first = 50, after } = params;
    // 每个 thread 拉取的评论上限。绝大多数 review thread 远不到 50 条;超过则置
    // commentsTruncated 提示调用方还有更多追评,不要仅凭已见评论就 resolve。
    const COMMENTS_PER_THREAD = 50;
    const query = `query($owner: String!, $repo: String!, $prNumber: Int!, $first: Int!, $after: String, $comments: Int!) {
      repository(owner: $owner, name: $repo) {
        pullRequest(number: $prNumber) {
          reviewThreads(first: $first, after: $after) {
            pageInfo { hasNextPage endCursor }
            nodes {
              id
              isResolved
              isOutdated
              path
              line
              comments(first: $comments) {
                totalCount
                nodes {
                  databaseId
                  body
                  createdAt
                  author { login }
                }
              }
            }
          }
        }
      }
    }`;
    const data = await this.graphql<{
      repository: {
        pullRequest: {
          reviewThreads: {
            pageInfo: { hasNextPage: boolean; endCursor: string | null };
            nodes: Array<{
              id: string;
              isResolved: boolean;
              isOutdated: boolean;
              path: string | null;
              line: number | null;
              comments: {
                totalCount: number;
                nodes: Array<{
                  databaseId: number | null;
                  body: string;
                  createdAt: string;
                  author: { login: string } | null;
                }>;
              };
            }>;
          };
        } | null;
      };
    }>(query, {
      owner: this.owner,
      repo: this.repo,
      prNumber,
      first,
      after: after ?? null,
      comments: COMMENTS_PER_THREAD,
    });
    // GitHub GraphQL 对不存在的 PR 编号返回 pullRequest: null(而非 error),
    // 直接访问 .reviewThreads 会抛裸 TypeError。抛 GithubApiError(status=404),
    // 与 REST 404 同路径,让上层 toolCatch 统一映射成 NOT_FOUND(而非 GITHUB_API_ERROR)。
    const pullRequest = data.repository?.pullRequest;
    if (!pullRequest) {
      throw new GithubApiError(
        `PR #${prNumber} not found in ${this.owner}/${this.repo}`,
        404,
      );
    }
    const reviewThreads = pullRequest.reviewThreads;
    return {
      threads: reviewThreads.nodes.map((n) => ({
        id: n.id,
        isResolved: n.isResolved,
        isOutdated: n.isOutdated,
        path: n.path,
        line: n.line,
        commentsTruncated: n.comments.totalCount > n.comments.nodes.length,
        comments: n.comments.nodes.map((c) => ({
          id: c.databaseId,
          body: c.body,
          author: c.author,
          createdAt: c.createdAt,
        })),
      })),
      pageInfo: reviewThreads.pageInfo,
    };
  }

  /**
   * 更新 PR 分支(把 base 上的最新 commit 合到 PR head)。返回 202 + 异步消息。
   * Update the PR branch (merge latest base into head). 202 Accepted.
   */
  async updatePullRequestBranch(
    prNumber: number,
    params: { expected_head_sha?: string } = {},
  ): Promise<{ message?: string; url?: string } | undefined> {
    return this.put<{ message?: string; url?: string } | undefined>(
      `/repos/${this.requireRepo()}/pulls/${prNumber}/update-branch`,
      { expected_head_sha: params.expected_head_sha },
    );
  }

  /**
   * 请求 Copilot 帮 review 一条 PR —— 本质是往 requested_reviewers 里加固定的
   * bot 用户名 `copilot-pull-request-reviewer[bot]`。封装成单独方法是为了让
   * caller 不用记 magic name。
   * Request a Copilot review by adding the copilot bot to requested reviewers.
   */
  async requestCopilotReview(prNumber: number): Promise<GithubPullRequest> {
    return this.requestPullRequestReviewers(prNumber, {
      reviewers: ['copilot-pull-request-reviewer[bot]'],
    });
  }

  // ── Git Data (refs / trees / commits / push_files) ───────────────────────

  /**
   * GET /repos/{o}/{r}/git/ref/{ref}。ref 形如 `heads/main` 或 `tags/v1.0`,
   * 不带 `refs/` 前缀(GitHub 会自动补)。
   * Get a single git ref (heads/<branch> or tags/<tag>).
   */
  async getRef(ref: string): Promise<GithubGitRef> {
    // ref 里的 '/' 是路径分隔符不能整体 encode,按段 encode 每一段
    const encoded = ref.split('/').map(encodeURIComponent).join('/');
    return this.get<GithubGitRef>(`/repos/${this.requireRepo()}/git/ref/${encoded}`);
  }

  /**
   * POST /repos/{o}/{r}/git/refs。ref 必须是完整的 `refs/heads/<name>` 或
   * `refs/tags/<name>`。这是最原始的 create_ref 端点。
   * Create a raw git ref (branch or tag).
   */
  async createRef(params: CreateRefParams): Promise<GithubGitRef> {
    return this.post<GithubGitRef>(
      `/repos/${this.requireRepo()}/git/refs`,
      { ref: params.ref, sha: params.sha },
    );
  }

  /**
   * 便捷方法:基于 base sha 创建新分支(封装 create_ref 的 refs/heads/ 前缀)。
   * Convenience: create a new branch from a base commit sha.
   */
  async createBranch(branch: string, fromSha: string): Promise<GithubGitRef> {
    return this.createRef({ ref: `refs/heads/${branch}`, sha: fromSha });
  }

  /**
   * GET /repos/{o}/{r}/git/trees/{tree_sha}?recursive=1。recursive=true 时把
   * 整个子树一次拉回。truncated=true 说明 GitHub 服务端截断了(> 100k entries)。
   * Get a git tree (recursive=true walks the whole subtree).
   */
  async getTree(treeSha: string, recursive: boolean = false): Promise<GithubGitTree> {
    return this.get<GithubGitTree>(
      `/repos/${this.requireRepo()}/git/trees/${encodeURIComponent(treeSha)}${this.qs({
        recursive: recursive ? 1 : undefined,
      })}`,
    );
  }

  /**
   * POST /repos/{o}/{r}/git/trees。tree entry 里 content(内联 UTF-8)与 sha
   * (指向已存在的 blob)二选一。base_tree 指定基础树 → 增量补丁,不然只包含
   * 传入的这些 entry。
   * Create a git tree (with base_tree for incremental patches).
   */
  async createTree(params: CreateTreeParams): Promise<GithubGitTree> {
    return this.post<GithubGitTree>(
      `/repos/${this.requireRepo()}/git/trees`,
      { tree: params.tree, base_tree: params.base_tree },
    );
  }

  /**
   * POST /repos/{o}/{r}/git/commits。parents 用父 commit sha 数组;merge commit
   * 有 2 个 parent,普通 commit 有 1 个,root commit 传 []。
   * Create a git commit object.
   */
  async createCommit(params: CreateCommitParams): Promise<GithubGitCommit> {
    return this.post<GithubGitCommit>(
      `/repos/${this.requireRepo()}/git/commits`,
      {
        message: params.message,
        tree: params.tree,
        parents: params.parents,
        author: params.author,
        committer: params.committer,
      },
    );
  }

  /**
   * PATCH /repos/{o}/{r}/git/refs/{ref}。ref 传 `heads/<branch>` 或
   * `tags/<name>`(不带 refs/ 前缀)。force=true 时允许非 fast-forward。
   * Update a git ref to point at a new sha.
   */
  async updateRef(
    ref: string,
    sha: string,
    force: boolean = false,
  ): Promise<GithubGitRef> {
    const encoded = ref.split('/').map(encodeURIComponent).join('/');
    return this.patch<GithubGitRef>(
      `/repos/${this.requireRepo()}/git/refs/${encoded}`,
      { sha, force },
    );
  }

  /**
   * POST /repos/{o}/{r}/git/blobs。多用于 push_files 的 base64 分支。
   * Create a blob object. Returns { sha, url }.
   */
  async createBlob(
    content: string,
    encoding: 'utf-8' | 'base64' = 'utf-8',
  ): Promise<{ sha: string; url: string }> {
    return this.post<{ sha: string; url: string }>(
      `/repos/${this.requireRepo()}/git/blobs`,
      { content, encoding },
    );
  }

  /**
   * 一次原子提交多文件:tree/commit/ref 三步走。
   *   1. getRef('heads/<branch>') 拿当前 head sha
   *   2. 拿 head commit 的 tree sha 作 base_tree
   *   3. 对 utf-8 文件走 tree entry 的内联 content;对 base64 文件先 createBlob
   *      再引用 blob sha
   *   4. createTree({ base_tree, tree: entries })
   *   5. createCommit({ message, tree, parents:[headSha] })
   *   6. updateRef('heads/<branch>', newCommitSha) — force=false,保持 fast-forward
   * Atomically push multiple files as a single commit on a branch.
   */
  async pushFiles(params: PushFilesParams): Promise<PushFilesResult> {
    const { branch, message, files } = params;
    if (files.length === 0) {
      throw new Error('pushFiles: files must be non-empty');
    }
    // Step 1: current head
    const headRef = await this.getRef(`heads/${branch}`);
    const headSha = headRef.object.sha;
    // Step 2: base tree sha —— 从 head commit 拿 tree.sha
    const headCommit = await this.get<GithubGitCommit>(
      `/repos/${this.requireRepo()}/git/commits/${encodeURIComponent(headSha)}`,
    );
    const baseTreeSha = headCommit.tree.sha;

    // Step 3: 构造 tree entries;base64 走 blob upload,utf-8 走内联 content。
    const treeEntries: GithubGitTreeItem[] = [];
    for (const f of files) {
      const enc = f.encoding ?? 'utf-8';
      if (enc === 'base64') {
        const blob = await this.createBlob(f.content, 'base64');
        treeEntries.push({
          path: f.path,
          mode: '100644',
          type: 'blob',
          sha: blob.sha,
        });
      } else {
        treeEntries.push({
          path: f.path,
          mode: '100644',
          type: 'blob',
          content: f.content,
        });
      }
    }

    // Step 4-5: tree + commit
    const newTree = await this.createTree({ base_tree: baseTreeSha, tree: treeEntries });
    const newCommit = await this.createCommit({
      message,
      tree: newTree.sha,
      parents: [headSha],
    });

    // Step 6: ref update(fast-forward only,不 force)
    await this.updateRef(`heads/${branch}`, newCommit.sha, false);

    return {
      commit_sha: newCommit.sha,
      tree_sha: newTree.sha,
      ref_updated: true,
      files_pushed: files.length,
    };
  }

  // ── Reactions ────────────────────────────────────────────────────────────

  /**
   * GET /repos/{o}/{r}/issues/{n}/reactions。可选 content filter。
   * List reactions on an issue.
   */
  async listIssueReactions(
    issueNumber: number,
    params: { content?: GithubReactionContent; per_page?: number; page?: number } = {},
  ): Promise<GithubReaction[]> {
    return this.get<GithubReaction[]>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/reactions${this.qs({ ...params })}`,
    );
  }

  /**
   * POST /repos/{o}/{r}/issues/{n}/reactions。已存在同 content 时 GitHub 返回 200
   * (不重复创建),否则 201。
   * Add a reaction to an issue.
   */
  async addIssueReaction(
    issueNumber: number,
    params: AddReactionParams,
  ): Promise<GithubReaction> {
    return this.post<GithubReaction>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/reactions`,
      { content: params.content },
    );
  }

  /**
   * GET /repos/{o}/{r}/issues/comments/{comment_id}/reactions。
   * List reactions on an issue comment.
   */
  async listIssueCommentReactions(
    commentId: number,
    params: { content?: GithubReactionContent; per_page?: number; page?: number } = {},
  ): Promise<GithubReaction[]> {
    return this.get<GithubReaction[]>(
      `/repos/${this.requireRepo()}/issues/comments/${commentId}/reactions${this.qs({ ...params })}`,
    );
  }

  /**
   * POST /repos/{o}/{r}/issues/comments/{comment_id}/reactions。
   * Add a reaction to an issue comment.
   */
  async addIssueCommentReaction(
    commentId: number,
    params: AddReactionParams,
  ): Promise<GithubReaction> {
    return this.post<GithubReaction>(
      `/repos/${this.requireRepo()}/issues/comments/${commentId}/reactions`,
      { content: params.content },
    );
  }

  /**
   * GET /repos/{o}/{r}/pulls/comments/{comment_id}/reactions。
   * List reactions on a PR inline review comment.
   */
  async listPullRequestReviewCommentReactions(
    commentId: number,
    params: { content?: GithubReactionContent; per_page?: number; page?: number } = {},
  ): Promise<GithubReaction[]> {
    return this.get<GithubReaction[]>(
      `/repos/${this.requireRepo()}/pulls/comments/${commentId}/reactions${this.qs({ ...params })}`,
    );
  }

  /**
   * POST /repos/{o}/{r}/pulls/comments/{comment_id}/reactions。
   * Add a reaction to a PR inline review comment.
   */
  async addPullRequestReviewCommentReaction(
    commentId: number,
    params: AddReactionParams,
  ): Promise<GithubReaction> {
    return this.post<GithubReaction>(
      `/repos/${this.requireRepo()}/pulls/comments/${commentId}/reactions`,
      { content: params.content },
    );
  }

  // ── Small writes / gets (create_repo, get_label, get_tag, releases) ─────

  /**
   * 创建仓库。传 org → POST /orgs/{org}/repos;不传 → POST /user/repos。
   * Create a new repository (org-owned when `org` is set, else user-owned).
   */
  async createRepository(params: CreateRepositoryParams): Promise<GithubRepo> {
    const { org, ...body } = params;
    const path = org
      ? `/orgs/${encodeURIComponent(org)}/repos`
      : '/user/repos';
    return this.post<GithubRepo>(path, body);
  }

  /**
   * GET /repos/{o}/{r}/labels/{name}。404 → 该 label 不存在。
   * Get a single label by name.
   */
  async getLabel(name: string): Promise<GithubLabel> {
    return this.get<GithubLabel>(
      `/repos/${this.requireRepo()}/labels/${encodeURIComponent(name)}`,
    );
  }

  /**
   * GET /repos/{o}/{r}/git/ref/tags/{tag}(GitHub 单数 endpoint 是 `git/ref/`;
   * 复数 `git/refs/` 是列表/更新/删除,单条 GET 会 404)。返回 ref(其 object.sha
   * 指向 commit 或 annotated tag object)。annotated tag 需要再 fetch git/tags/
   * {sha} 拿元数据,这里返 ref 已能满足绝大多数场景。
   * Get a tag ref by name (delegates to getRef which uses the correct
   * singular `/git/ref/` endpoint).
   */
  async getTag(tag: string): Promise<GithubGitRef> {
    return this.getRef(`tags/${tag}`);
  }

  /**
   * GET /repos/{o}/{r}/releases/latest。
   * Get the latest published release.
   */
  async getLatestRelease(): Promise<GithubRelease> {
    return this.get<GithubRelease>(
      `/repos/${this.requireRepo()}/releases/latest`,
    );
  }

  /**
   * GET /repos/{o}/{r}/releases/{id}/assets。
   * List assets attached to a release.
   */
  async listReleaseAssets(
    releaseId: number,
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubReleaseAsset[]> {
    return this.get<GithubReleaseAsset[]>(
      `/repos/${this.requireRepo()}/releases/${releaseId}/assets${this.qs({ ...params })}`,
    );
  }

  // ── Sub-issues (2024 feature) ────────────────────────────────────────────

  /**
   * GET /repos/{o}/{r}/issues/{n}/sub_issues。
   * List sub-issues attached to a parent issue.
   */
  async listSubIssues(
    issueNumber: number,
    params: { per_page?: number; page?: number } = {},
  ): Promise<GithubIssue[]> {
    return this.get<GithubIssue[]>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/sub_issues${this.qs({ ...params })}`,
    );
  }

  /**
   * POST /repos/{o}/{r}/issues/{n}/sub_issues。sub_issue_id 是 child 的**全局
   * issue id**(不是 number-in-repo,GitHub API 特意要求这个)。
   * Attach a sub-issue by global issue id (not number-in-repo).
   */
  async addSubIssue(
    issueNumber: number,
    params: AddSubIssueParams,
  ): Promise<GithubIssue> {
    return this.post<GithubIssue>(
      `/repos/${this.requireRepo()}/issues/${issueNumber}/sub_issues`,
      { sub_issue_id: params.sub_issue_id, replace_parent: params.replace_parent },
    );
  }

  // ── HTTP 基础方法 ────────────────────────────────────────────────────────

  private async get<T>(path: string): Promise<T> {
    return this.request<T>('GET', path);
  }

  private async post<T>(path: string, body?: unknown): Promise<T> {
    return this.request<T>('POST', path, body);
  }

  private async put<T>(path: string, body?: unknown): Promise<T> {
    return this.request<T>('PUT', path, body);
  }

  private async patch<T>(path: string, body?: unknown): Promise<T> {
    return this.request<T>('PATCH', path, body);
  }

  private async request<T>(
    method: string,
    path: string,
    body?: unknown,
  ): Promise<T> {
    const url = `${this.baseUrl}${path}`;
    const headers: Record<string, string> = {
      Authorization: `Bearer ${this.token}`,
      Accept: 'application/vnd.github+json',
      'X-GitHub-Api-Version': '2022-11-28',
    };
    const init: RequestInit = { method, headers };

    if (body !== undefined) {
      headers['Content-Type'] = 'application/json';
      init.body = JSON.stringify(body);
    }

    // 认证请求禁止自动跟随跨 host 重定向:Authorization token 绝不重放到另一个 host。
    const res = await fetchWithSafeRedirect(url, init, undefined, this.fetchImpl);

    if (!res.ok) {
      const text = await res.text().catch(() => '');
      throw new GithubApiError(
        `GitHub ${method} ${path} failed: ${res.status}`,
        res.status,
        text,
      );
    }

    // 空 body 的成功响应:除了 204 No Content,GitHub 还会用
    //   201 Created(workflow rerun / repo fork 等)
    //   202 Accepted(workflow cancel、异步任务已入队)
    //   205 Reset Content(notification mark-read)
    // 这些 case 下 res.json() 会抛 SyntaxError,让上层误报 API 失败。
    // 用 Content-Length: 0 或空 body 直接短路,不去解析 JSON。
    if (res.status === 204 || res.status === 205) return undefined as T;
    const contentLength = res.headers.get('content-length');
    if (contentLength === '0') return undefined as T;
    const text = await res.text();
    if (text.length === 0) return undefined as T;
    return JSON.parse(text) as T;
  }

  /**
   * 只跟一次的重定向请求(redirect: 'manual')。GitHub 的 artifact zip /
   * workflow run logs 会 302 到一个短时效的 S3 签名 URL,不适合 fetch 自动跟
   * (会把 auth header 带到 S3 上),这里返 Location 让调用方自己下载。
   * 未拿到 Location(非 3xx 或缺 header)时返 null。
   */
  private async requestRedirectUrl(method: string, path: string): Promise<string | null> {
    const url = `${this.baseUrl}${path}`;
    const res = await this.fetchImpl(url, {
      method,
      redirect: 'manual',
      headers: {
        Authorization: `Bearer ${this.token}`,
        Accept: 'application/vnd.github+json',
        'X-GitHub-Api-Version': '2022-11-28',
      },
    });
    // 3xx 是预期路径;location 由 GitHub 填充。
    if (res.status >= 300 && res.status < 400) {
      return res.headers.get('Location');
    }
    if (!res.ok) {
      const text = await res.text().catch(() => '');
      throw new GithubApiError(
        `GitHub ${method} ${path} failed: ${res.status}`,
        res.status,
        text,
      );
    }
    return null;
  }
}