[Proposal] 在 forge 面板中展示宿主端的 review 评论正文

[choleraehyq]

[Proposal] 在 forge 面板中展示宿主端的 review 评论正文

现状

forge 面板能显示变更请求有多少条未解决讨论，但显示不出讨论说了什么。当前渲染效果：

Review required · 3 unresolved threads

要读这三条评论，用户必须离开 Session 去打开宿主的网页。

这不是某一个 provider 的问题。ChangeRequestSnapshot 只带 unresolvedThreads: number，没有任何评论内容字段；GitHub provider 也只读 resolved 标志、不读正文。所以每个 provider 都会撞同一堵墙。

实际代价是 review 闭环断了：Session 里的 agent 能看到变更请求被讨论阻塞，但读不到讨论内容，也就无法据此修改。它只能被人在外部告知 reviewer 说了什么。

关键观察：UI 其实已经有渲染能力

ReviewThread.tsx 已经在渲染 comment.body，但只渲染本客户端自己写的评论——ReviewThread union 只有 pending | agent | published 三种，全是本地草稿和发布回执，存在浏览器 storage 里。

渲染路径已存在，缺的只是让宿主评论进入这条路径。

希望补齐的接口

1. 扩展中立类型

/** 一条评论。 */
export interface ChangeRequestComment {
  /** 宿主分配的评论 id，线程内唯一。 */
  readonly id: string
  /** 作者登录名，宿主隐藏时为 null。 */
  readonly author: string | null
  /** 作者写下的正文，宿主标记语言原样保留。 */
  readonly body: string
  /** 发布的 ISO 8601 时间。 */
  readonly createdAt: string
}

/** 变更请求上的一条 review 线程。 */
export interface ChangeRequestThread {
  /** 宿主分配的线程 id。 */
  readonly id: string
  /** 线程是否已解决。 */
  readonly resolved: boolean
  /** 线程是否已过期：其行号不再匹配 head commit。 */
  readonly outdated: boolean
  /** 线程附着的文件与行范围；整体讨论为 null。 */
  readonly position: {
    readonly path: string
    readonly side: 'L' | 'R'
    readonly startLine: number
    readonly endLine: number
  } | null
  /** 线程内的评论，宿主顺序，最早在前。 */
  readonly comments: readonly ChangeRequestComment[]
}

ChangeRequestSnapshot 增加一个字段：

/**
 * 变更请求上的 review 线程；provider 未读取时为 null。
 * `unresolvedThreads` 仍是计数的权威来源，因此 provider 可以只报计数不带线程，
 * 截断的读取也不会低估计数。
 */
readonly threads: readonly ChangeRequestThread[] | null

用 null 而不是 [] 是关键：它区分「这个 provider 读不了线程」和「确实没有线程」，面板才能提示「去宿主查看讨论」，而不是谎称无人讨论。现有 provider 全部保持编译通过、行为不变。

2. 走可选能力，不新增必需方法

线程复用现有 fetch，不需要新的必需方法。按需路径沿用 fetchChecks? 的现成模式：

/** 按需读取全部 review 线程；省略表示只提供轮询预览。 */
fetchThreads?(ref: ChangeRequestRef, signal: AbortSignal): Promise<readonly ChangeRequestThread[] | ForgeFailure>

3. 轮询成本——这是需要谨慎设计的部分

也是 GitHub provider 当初没这么做的原因。读正文会把一个廉价字段变成带分页的嵌套连接，而注册表按 activeIntervalMs（默认 30s）定时轮询。直接把正文加进轮询会让每个被观察的变更请求在每轮都付出更高代价。

建议：轮询只数，正文按需读。 fetch 维持现状只读 unresolvedThreads；fetchThreads 在用户展开线程列表时才读正文——与 fetchChecks 在用户展开 checks 列表时才读完整详情完全一致。轮询快照里的 threads 保持 null。这是仓库里已有的既定模式，不需要新的调度逻辑。

4. 面板

• ChangeRequestCard 的 review 行在 threads !== null 或 provider 支持 fetchThreads 时可展开线程列表；否则维持现在的计数展示。
• diff 视图里给 ReviewThread union 增加 host 变体，携带 ChangeRequestThread 而非 ReviewSelection，复用现有组件渲染。该组件已能渲染正文、已区分 pending/published 状态；宿主线程是第四种状态，禁用编辑与删除。
• 过期线程折叠，已解决线程标记，使面板计数与列表一致。

兼容性

全部为增量、可选：threads 可空、fetchThreads 可选，forge-github 与所有社区 provider 无需改动即可继续工作；unresolvedThreads 不变，因此即使读不到正文，计数依然正确。

可参考的既有实现

fetchChecks / ChecksRow 解决的是 checks 上完全相同的问题：轮询摘要、按需读完整列表、在可展开行中渲染。线程可以照搬这个形态，diff 小、行为可预期。

分步实施

如果维护者希望更小的第一步：仅 threads 字段（第 1 步，加 forge-github 在 fetchThreads 中读正文）就已独立有用——即使面板还没渲染，也能让 agent 读到讨论内容。

---

改动范围：forge（类型 + 服务）、forge-github（GraphQL + 映射）、client-ui-forge（卡片 + 线程列表）。按 CONTRIBUTING，我没有直接提 PR，先在这里提出。