qwen-code/docs/design/web-shell-github-prs.md

Web Shell GitHub PR 只读列表

问题陈述

Web Shell 已有 Git 能力(状态芯片、/diff、/log 对话框、Git mode popover),但用户想看当前仓库的开放 PR(状态、CI、review)时必须打断会话 问 agent,或切到浏览器。目标是在现有 Git 对话框中增加一个只读 "Pull requests" 标签页,让用户不打断会话即可瞟一眼 PR 状态。

范围边界(已与需求方确认):

• 做:只读开放 PR 列表(标题、分支、作者、review 状态、CI 聚合状态、 更新时间),点击跳转 github.com。
• 不做:Issue 面板、创建 PR / 提交 review 的表单(agent 用 gh 已能 完成,重复建设)、PR 详情展开、分页、自动刷新。

现状

• daemon 有三层路线模式:packages/cli/src/serve/routes/workspace-git*.ts 用 resolveWorkspaceRuntimeFromParam + requireTrustedWorkspaceRuntime 做 workspace 路由与 trust 门控;核心逻辑在 core (packages/core/src/utils/gitDiff.ts 的 fetchGitLog 等,execFile
  • 超时);SDK WorkspaceDaemonClient 经 workspaceJsonRequest 暴露 类型化方法。
• daemon 侧 GitHub 先例只有 POST /workspace/setup-github(写 workflow) 与技能安装(直连 GitHub API,用 GH_TOKEN/GITHUB_TOKEN)。
• Web Shell 的 GitDialog 是 tab 容器('diff' | 'log' 两个 view), 由 /diff、/log 本地命令和侧栏打开;内容组件 (GitDiffContent/GitLogContent)经 client.workspaceByCwd(cwd).workspaceGit*() 取数。
• capability 通过 SERVE_CAPABILITY_REGISTRY 登记,Web Shell 用 capabilities?.features?.includes(tag) 门控 UI。

方案

1. core:packages/core/src/utils/github-prs.ts(新)

fetchGitHubPullRequests(cwd),经 execFile(参数数组,无 shell 插值, windowsHide,10s 超时)执行:

gh pr list --state open --limit 30 --json number,title,url,author,headRefName,isDraft,reviewDecision,statusCheckRollup,updatedAt

设计决定:

• 用 gh CLI 而非直连 REST API。AGENTS.md 规定 GitHub 操作一律走 gh;复用用户已有的 gh auth 登录,无需 token 配置 UI;gh 自动识别 fork 的 upstream remote;statusCheckRollup 一次调用拿到 CI 聚合。
• 先 git rev-parse --is-inside-work-tree 探活:非 git 仓库返回 { kind: 'not_a_repo' },避免把 "not a git repository" 的 gh stderr 当错误。
• 结果判别:
  • ENOENT(gh 未安装)→ { kind: 'cli_unavailable' }
  • gh 非零退出(未登录、无 GitHub remote、网络)→ { kind: 'failed', message }(stderr 截断 512 字符)
  • 成功 → 按 updatedAt 降序排序,逐项归约:
    • state: 'open' | 'draft'(由 isDraft 得出)
    • reviewDecision: 'approved' | 'changes_requested' | 'review_required' | null
    • checks: 'passing' | 'failing' | 'pending' | 'none' —— 在 daemon 侧聚合 statusCheckRollup,面板只渲染一个图标,不下发原始 rollup 数组。failure 结论(CheckRun 的 FAILURE/CANCELLED/TIMED_OUT/ ACTION_REQUIRED/STARTUP_FAILURE/STALE,StatusContext 的 ERROR/FAILURE, 与 gh pr checks 的口径一致:cancelled/stale 同样阻塞合并)优先, 其次未完成(conclusion 为空 / PENDING / EXPECTED),再次成功类 (SUCCESS/NEUTRAL/SKIPPED);空数组为 'none'。
• 返回判别联合,不抛异常;错误语义由路由层翻译。

2. daemon 路由:packages/cli/src/serve/routes/workspace-github-prs.ts(新)

GET /workspaces/:workspace/github/prs

• 严格复用 workspace-git-log.ts 模式:resolveWorkspaceRuntimeFromParam
  • requireTrustedWorkspaceRuntime,只注册 workspace-qualified 形态 (Web Shell 只走 workspaceByCwd;无旧客户端需要单数形态)。
• 响应(均带 applyReadHeaders):
  • 200 { v: 1, workspaceCwd, available: true, pullRequests: [...] }
  • 200 { v: 1, workspaceCwd, available: false, pullRequests: [] }(非 git 仓库;pullRequests 恒在,与 DaemonGitLog.entries 风格一致)
  • 502 { error, code: 'github_cli_unavailable' }(gh 未安装)
  • 502 { error, code: 'github_prs_failed' }(gh 失败;message 中的 workspace 路径替换为 <workspace>,同 setup-github 的 sanitize 先例)
• 不做缓存与轮询;每次打开对话框拉一次。
• capability 登记 workspace_github_prs: { since: 'v1' }(无条件 tag: 路由契约恒存在,运行时可用性由错误码表达——与 workspace_github_setup 一致)。
• server.ts 注册,紧邻 git 路由。

3. SDK:packages/sdk-typescript/src/daemon/

• types.ts:
  • DaemonGitHubPullRequest:{ number, title, url, author, headRefName, state: 'open'|'draft', reviewDecision: ... | null, checks: ..., updatedAt: number }(updatedAt 为 epoch 秒)
  • DaemonGitHubPullRequestList:{ v: 1, workspaceCwd, available: boolean, pullRequests: DaemonGitHubPullRequest[] }(pullRequests 恒在,不可用时为 空数组)
• DaemonClient.ts 的 WorkspaceDaemonClient 增加 workspaceGitHubPullRequests(),走 workspaceJsonRequest(..., '/github/prs', 'GET /workspaces/:workspace/github/prs', { mode: 'rest' })。

4. Web Shell

• client/components/dialogs/GitHubPrsDialog.tsx(新):导出 GitHubPrsContent({ workspaceCwd, onSubtitleChange } 签名与 GitLogContent 一致)。
  • 挂载时经 client.workspaceByCwd(workspaceCwd) .workspaceGitHubPullRequests() 拉取;渲染行:状态图标(open/draft)、 #number 标题、分支、作者、相对更新时间、review 徽标、CI 图标。
  • 行点击 window.open(url, '_blank', 'noopener')。
  • 状态文案:loading / 空列表 / available:false(非 git 仓库)/ github_cli_unavailable(引导安装 gh)/ 其他失败(静态错误文案,重新 打开对话框即重试,与 GitLog 一致)。
  • 副标题上报 N 个开放 PR。
• GitDialog.tsx:view 联合加 'prs',第三个 tab (githubPrs.title,中英文 "Pull requests"/"拉取请求");tab 键盘导航 (ArrowLeft/Right/Home/End)适配三个 tab。
• 入口:
  • 本地命令 /prs(constants/localCommands.ts + App.tsx 分支,仿 /log;无 workspace 时 toast),打开 GitDialog view: 'prs'。
  • capability workspace_github_prs 不存在时隐藏对话框里的 PR tab(旧 daemon 404 防护);/prs 命令仍列出,执行时 toast 提示不支持。
• i18n:githubPrs.*、local.prs、localCommand.prsNoWorkspace 中英文。

5. 测试

层	文件	覆盖
core	utils/github-prs.test.ts	mock execFile:成功解析/排序/checks 聚合/reviewDecision 映射;非 repo;ENOENT;gh 失败
cli	serve/routes/workspace-github-prs.test.ts	mock core 函数:200 两形态、untrusted 403、unknown 400、cli_unavailable 502、failed 502 + 路径脱敏
sdk	DaemonClient 测试	方法命中正确路径与 query
web-shell	GitHubPrsDialog.test.tsx、GitDialog.test.tsx、App 命令测试	各状态渲染、tab 切换、capability 门控、/prs 打开对话框
e2e	.qwen/e2e-tests/web-shell-github-prs.md	真 daemon + 本仓库(真 gh)端到端;mockDaemon 补路由

关键文件

文件	动作
packages/core/src/utils/github-prs.ts	新增
packages/core/src/index.ts(或对应导出面)	导出
packages/cli/src/serve/routes/workspace-github-prs.ts	新增
packages/cli/src/serve/capabilities.ts	登记 tag
packages/cli/src/serve/server.ts	注册路由
packages/sdk-typescript/src/daemon/types.ts / DaemonClient.ts	类型 + 方法
packages/web-shell/client/components/dialogs/GitHubPrsDialog.tsx	新增
packages/web-shell/client/components/dialogs/GitDialog.tsx	第三 tab
packages/web-shell/client/App.tsx / constants/localCommands.ts / i18n.tsx	入口 + 文案

性能优化:daemon 侧 TTL 缓存

gh pr list --json …,statusCheckRollup 是慢点——为 30 个 PR 各拉 CI rollup 要多秒级 GitHub 往返(实测本仓库冷启动 ~8s,CPU 时间仅 ~0.07s,纯网络 I/O)。面板是"瞟一眼"性质,数据 stale 一分钟完全可接受,故在 daemon 路由 加闭包级、按 workspaceCwd 分键的短 TTL 缓存(默认 60s,cacheTtlMs 可注入, 对齐 usage-stats.ts 的既有约定):

• 单飞合并:进行中的 load 无论新旧都复用,并发打开共享一次 gh 拉起 (即使它超过 TTL);TTL 窗口从 load 落定后开始计。
• 仅缓存 ok:cli_unavailable/failed/not_a_repo 落定即清条目, 下次打开重试(用户可能刚装好/登录 gh,或工作区刚变成仓库)。
• 实测:冷启动 8.0s → 缓存命中 ~2ms(约 2500 倍)。

首次打开仍慢(~8s)是 gh 本身的延迟;如需改善首屏,后续可做两阶段加载 (先不带 statusCheckRollup 快速渲染列表,再异步补 CI 图标),不在本次范围。

开放问题

• 无。gh 缺失/未登录、非 git 仓库、旧 daemon 三条降级路径均有明确 UI 语义。