Orca Internals

Appearance

第 10 章：Git、代码审查与任务 Provider ​

目标：理解 Orca 如何把本地 Git 事实、托管平台数据与 Agent 生成能力组合成一条 review 工作流。

1. 三层 source control ​

Git 负责 working tree 和 commit graph；GitHub/GitLab 负责 PR/MR、review、checks 和 Issue。两者不能混为一个 provider。

2. Git runner 是执行路由器 ​

git/runner.ts 不只是 execFile('git') 的薄封装。它处理：

  • native、WSL 与 SSH 命令路由；
  • path 参数转换；
  • timeout、AbortSignal 与 process tree kill；
  • maxBuffer 和 streaming；
  • 非交互环境、credential prompt guard；
  • locale 固定，保证错误解析稳定；
  • Git optional locks；
  • gh / glab host 与 rate limit；
  • transient read-only retry。

非幂等 gh 写操作不会因为网络错误自动重放，避免重复 comment/merge。

3. Status 不是 git status --short 的字符串 ​

Orca 需要 staged/unstaged/untracked、rename、冲突、行数、ahead/behind、branch、upstream 等结构化信息。status parser 还要处理：

  • porcelain 版本差异；
  • 文件名编码与 NUL 分隔；
  • 大量文件的性能；
  • SSH output；
  • watcher 触发的增量刷新；
  • repo 暂时不可用。

结果进入 SourceControl sidebar、worktree card、memory collector 和 review UI。

4. Diff 与编辑器 ​

renderer 支持：

  • 单文件 diff；
  • combined diff；
  • staged / unstaged；
  • 文件树虚拟化；
  • 行级 comment；
  • open original/modified；
  • markdown/image/PDF 预览。

diff comment 是 Orca 自己的 review note，可被组装成 prompt 发回 Agent。它与 GitHub review comment 不必同时存在。

5. SourceControl 事务 ​

典型操作：

  • stage/unstage/discard；
  • commit；
  • pull/fetch/push；
  • branch rename / switch；
  • resolve conflict；
  • create PR/MR；
  • merge/rebase；
  • fork sync。

每个操作都要考虑当前 execution host 和 Git capability。错误面向 Agent 修复时，会保留结构化上下文，但对 secret、remote URL credential 进行脱敏。

6. Fork、origin 与 upstream ​

Repo 保存 upstream identity 和 issueSourcePreference：

  • auto：有 upstream 则优先 upstream，否则 origin；
  • upstream：用户明确选择；
  • origin：用户明确选择。

为什么有三态而不是布尔值？因为“当前 heuristic 恰好选 upstream”不同于“用户明确要求 upstream”。远端拓扑变化不能悄悄改变用户选择。

7. GitHub/GitLab client ​

平台 client 提供：

  • repo/issue/PR/MR 定位；
  • comments、labels、assignee；
  • project views 和字段；
  • checks、review threads；
  • create/close/merge；
  • avatar 与 metadata cache。

优先使用 gh/glab 复用用户认证，同时做 hostname qualification 和 rate-limit scope。对于远程 repo，CLI 需要在正确 host 或通过明确 fallback 执行。

8. Tasks 是多 provider 聚合 ​

Task page 可汇总：

  • GitHub Issue / PR；
  • GitLab Issue / MR；
  • Linear issue；
  • Jira issue。

TaskSourceContext 携带 provider、project/repo/team 等上下文，避免只用一个 number 造成跨 repo/provider 冲突。

从任务创建 workspace 时，linked item 被写入 WorktreeMeta 或 FolderWorkspace，后续 card、branch name、PR 和状态同步都可使用。

9. Hosted review cache ​

PR/MR 页面需要同时展示：

  • 远端 diff 与本地 working tree；
  • checks 与 review state；
  • comments 和 thread；
  • branch 是否已经 checkout；
  • repo host identity。

cache key 必须包含 provider/host/repo/item，不可只按 PR number。后台 refresh 还要防止一个旧请求覆盖用户刚切换到的新 item。

10. AI 辅助 commit 与 PR ​

commit message / PR generation 不是 renderer 直接调外部模型，而是通过 main 的 text-generation 环境选择：

  • 读取 diff，设置大小边界；
  • 选择可用 Agent/account/runtime；
  • 生成建议；
  • renderer 允许用户编辑；
  • 最终 Git/平台写操作仍独立确认执行。

AI 文本和副作用分离，能避免一次生成失败或幻觉直接改变仓库。

11. Push 失败的恢复 ​

push 失败可能来自：

  • non-fast-forward；
  • auth；
  • branch protection；
  • fork/upstream target；
  • remote hooks；
  • 网络或 SSH。

Orca 可把结构化失败交给 Agent 做恢复建议，但不会把所有错误都盲目重试。尤其 push 是副作用，网络不确定时需要先重新读取 remote 状态。

12. 大仓库性能 ​

SourceControl 是大仓库的热点。策略包括：

  • streaming 与 maxBuffer；
  • file count / diff size 上限；
  • watcher coalescing；
  • virtualized file list；
  • worktree/status scan 并发限制；
  • changed-only code quality scripts；
  • 专门的 source-control scale E2E。

13. 源码导航 ​