1. 为什么我要把 Orca 和 GitHub Projects 绑在一起用第一天跑通这套组合的时候我最大的感受是AI 编程工具真正难的不是让 AI 写代码而是让 AI 写的代码有地方去、有状态可查、有历史可回滚。Orca 这个 agent 工具本身能力不弱能读仓库、能改文件、能跑命令但如果你只是把它当成一个会写代码的对话框那用不了两天就会乱成一锅粥——分支互相踩、任务状态全靠脑子记、改完的东西不知道对应哪个需求。GitHub Projects 恰好补上了这块短板它提供的是任务看板 状态流转 与 issue/PR 的天然绑定而 Orca 负责把看板上的卡片真正变成代码改动。两者一结合AI 编程工作流才算闭环。先说清楚这套东西适合谁。如果你满足下面任意一条这篇内容对你就直接有用一是已经在用 Claude Code、Cursor、Aider 这类 agent 工具但总觉得任务管理和代码产出是两张皮二是团队里开始尝试让 AI 参与实际开发需要一套可追溯、可 review 的流程三是你自己一个人做 side project想让 AI 帮你并行推进多个模块又不想把 git 历史搞乱。不适合的场景也很明确如果你只是偶尔让 AI 补个函数、写个正则那完全没必要上这套杀鸡用牛刀。核心关键词我先摆出来后面会反复用到Orcaagent 执行层、GitHub Projects任务状态层、gh CLI打通两层的胶水、git worktree隔离并行工作区。这四个东西各司其职缺一个流程就会漏风。我第一天的目标很朴素让 Projects 看板上的一张卡片能被 Orca 认领、在一个独立的 worktree 里完成改动、最后自动关联回对应的 issue。听起来简单但中间踩的坑足够写一篇长文。提示这套流程对 git 版本有要求worktree 相关的稳定行为建议 git 2.30 以上gh CLI 建议 2.40 以上否则 Projects 的字段操作会缺命令。2. 整体设计思路三层解耦各管一摊2.1 把任务状态和代码状态彻底分开很多人用 AI 编程工具的第一个误区是让 agent 同时管任务和管代码。结果就是 agent 的上下文里塞满了这个任务做完了没下一个该做啥这类元信息真正用来理解代码的 token 被挤占。我的设计原则很直接GitHub Projects 只管做什么、做到哪一步Orca 只管怎么改git worktree 只管在哪改。三层之间通过 gh CLI 和文件系统松耦合任何一层挂了都不影响另外两层继续工作。这么设计的好处我在第一天就体会到了。上午 Orca 在跑一个重构任务时卡住了后面会讲原因但 Projects 看板上的状态是独立的我直接手动把卡片拖回 In Progress换了个 worktree 重新起了一个 agent 会话五分钟就接上了。如果任务状态是存在 agent 上下文里的这一卡就得从头再来。2.2 为什么选 git worktree 而不是反复切分支这是整套方案里我最想强调的一个选型。传统做法是git checkout切来切去但 AI agent 的工作模式是长时间、多文件、可能中途失败你在它干活的时候切分支轻则它改错文件重则直接把未提交的改动带到另一个分支上。git worktree 允许你把同一个仓库的多个分支同时检出到不同目录每个目录是一个独立工作区互不干扰。打个生活化的比方切分支就像一张桌子上反复换桌布换的时候桌上东西得先收走worktree 则是直接给你开了几张不同的桌子每张桌子上摆不同的活儿你走到哪张桌子就干哪张桌子的活。对 AI 编程来说这个差别是决定性的——你可以让 Orca 在../proj-feature-a里改登录逻辑同时在../proj-feature-b里改支付逻辑两个 agent 会话并行跑谁也不碰谁。2.3 gh CLI 是唯一需要写死的胶水层三层解耦之后唯一需要我手动维护的就是胶水用gh命令读 Projects 的卡片、更新卡片状态、把 PR 关联回 issue。我试过用 Projects 的网页界面手动拖卡片也试过用 GraphQL API 自己写脚本最后发现gh CLI 的gh project子命令 gh issue组合是性价比最高的。原因有三一是它天然带认证不用自己管 token二是输出格式稳定方便管道处理三是它和 git 的钩子能配合比如在 pre-push 里自动更新卡片状态。这里有个细节值得说gh project item-list默认返回的是 JSON但字段名是驼峰和短横线混着的直接jq解析容易翻车。我第一天的做法是先gh project item-list number --format json items.json然后用jq慢慢试字段路径把常用的几个字段title、status、content.number固化成一个查询模板。这个模板后面会贴出来。3. 环境准备从零把四个组件装到位3.1 Orca 的安装与首次认证Orca 的安装方式取决于你用的发行渠道我这边走的是官方 CLI 安装路径。装完之后第一件事是认证认证不通过后面所有 agent 调用都会 401。认证流程本身不复杂但有个坑认证信息默认存在用户目录下的隐藏配置里如果你用容器或多用户环境跑记得把配置目录挂载或复制过去否则 agent 会话会莫名其妙地没权限。装完先跑一个最小验证让 Orca 读一个本地文件并输出摘要。这一步能过说明 agent 的执行链路是通的。我第一天的验证命令大概是让它读README.md然后总结三句话返回正常就继续。如果这一步就失败别急着往下走先把认证和网络出口排查清楚。3.2 gh CLI 安装与 Projects 权限确认gh CLI 的安装各平台都有包管理器支持装完跑gh auth login走一遍浏览器授权。这里的关键是授权范围要包含 project 权限。默认的授权 scope 里 project 相关权限有时候是关的导致你能读 issue 但读不了 Projects 卡片。确认方法很简单跑gh project list --owner 你的用户名或组织如果能列出项目就说明权限够了报 403 就是 scope 没给全重新gh auth refresh -s project补一下。3.3 建一个最小可用的 Projects 看板不要一上来就搞复杂的工作流。第一天我建议就建三列Todo、In Progress、Done。字段方面除了默认的 Status再加一个文本字段叫worktree用来记录这张卡片当前对应的 worktree 目录名。这个字段是我踩坑之后加的——当你有五六个 worktree 并行时光靠脑子记哪个卡片对应哪个目录必崩。建看板的命令可以用gh project create也可以直接在网页上点。我倾向网页建因为字段配置在网页上更直观建好之后再用gh project field-list确认字段 ID后面脚本里要用。3.4 worktree 目录规划worktree 的目录命名我建议带上前缀和任务编号比如../wt-142-login-refactor其中 142 是对应 issue 的编号。这样你ls ..一眼就能看出每个目录在干嘛。创建命令是git worktree add ../wt-142-login-refactor -b feat/142-login-refactor注意分支名和目录名保持一致减少心智负担。注意worktree 创建的分支如果基于当前 HEAD记得先确认当前 HEAD 是干净的、且是你想要的基础分支。我第一天就因为在一个半成品分支上创建 worktree导致新任务一开始就带着别人的未完成改动。4. 核心实操让一张卡片真正跑起来4.1 从 Projects 拉取待办卡片先写一个拉取脚本把 Todo 状态的卡片捞出来。核心命令是gh project item-list配合--format json和jq过滤。我固化的查询模板大致是这样gh project item-list PROJECT_NUMBER \ --owner OWNER \ --format json \ | jq -r .items[] | select(.status Todo) | \(.content.number)\t\(.title)跑通这个命令的标志是能稳定输出issue编号 标题的列表。如果输出为空但你明明有 Todo 卡片八成是 status 字段的值和你以为的不一样——Projects 的 status 是选项字段值可能是 Todo 也可能是 待办用gh project field-list看一眼实际选项值。4.2 为卡片创建独立 worktree拿到 issue 编号后创建 worktree。我把它写成一个函数输入编号和简短描述自动拼目录名和分支名new_wt() { local num$1 local slug$2 local dir../wt-${num}-${slug} git worktree add $dir -b feat/${num}-${slug} echo $dir }创建完立刻把目录名写回 Projects 卡片的worktree字段这样看板上就能看到每张卡片对应哪个目录。写回用gh project item-edit需要 item ID 和 field ID这两个都能从前面item-list的 JSON 里拿到。4.3 在 worktree 里启动 Orca 会话这是整个流程的核心动作。进入 worktree 目录启动 Orca把 issue 的描述作为任务上下文喂给它。我第一天的做法是把 issue body 导出成TASK.md放在 worktree 根目录然后让 Orca 读这个文件。这样做的好处是任务描述和代码改动在同一个目录里agent 的上下文天然聚焦不会跑去改别的模块。启动命令大致是让 Orca 以当前目录为工作区、以TASK.md为指令来源。具体参数各版本略有差异核心是确认三件事工作区指向 worktree 目录、指令文件路径正确、agent 有写文件的权限。跑起来之后Orca 会开始读代码、改文件、跑测试你在旁边看着就行。4.4 改动完成后关联回 issueOrca 干完活worktree 里会有一堆未提交的改动。这时候不要直接git commit -m ai did stuff而是先 review。我第一天的 review 流程是git diff --stat看改了哪些文件git diff逐个看关键改动确认没问题再提交。提交信息里带上 issue 编号比如feat: refactor login flow (#142)这样 GitHub 会自动把 commit 关联到 issue。然后推分支、开 PRPR 描述里引用 issue。最后把 Projects 卡片从 In Progress 拖到 Done。这一整套下来一张卡片就完整闭环了。5. 常见问题与排查技巧实录5.1 Orca 在 worktree 里找不到仓库这是第一天最坑的问题。Orca 启动后报not a git repository但git status明明正常。原因是worktree 目录下的.git是一个文件而不是目录里面写着gitdir: /path/to/main/.git/worktrees/xxx。有些工具在判断是不是 git 仓库时只检查.git是不是目录遇到文件就误判。解决办法是升级 Orca 到支持 worktree 的版本或者在启动参数里显式指定仓库根路径。5.2 gh project 命令报权限不足前面提过多半是 auth scope 缺 project。但也有一种情况是组织开启了 SSO你的 token 没有为这个组织授权。这时候gh auth status会显示 token 有效但访问组织资源就是 403。解决方法是gh auth refresh -s project,read:org重新走一遍授权并在浏览器里确认给组织授权。5.3 多个 worktree 并行时端口冲突如果你跑的是 web 项目多个 worktree 同时起 dev server 会抢端口。我第一天的做法是给每个 worktree 分配一个端口偏移比如 issue 编号后两位作为端口尾数142 就用 8142。这个映射写在 worktree 目录下的.env.local里agent 启动 dev server 时自动读。5.4 常见问题速查表现象可能原因排查动作Orca 报 not a git repositoryworktree 的 .git 是文件升级 Orca 或显式指定仓库根gh project 403auth scope 缺 project 或 SSO 未授权gh auth refresh -s project卡片状态更新无效status 选项值不匹配gh project field-list看实际值多 worktree 端口冲突dev server 默认端口相同按 issue 编号分配端口偏移agent 改错文件工作区指向了主仓库确认启动目录是 worktree 路径5.5 我踩过的三个独家坑第一个坑是在 worktree 里跑git worktree add。worktree 目录本身也是仓库你在里面再建 worktree路径会算错最后建到奇怪的地方去。记住 worktree 的创建永远在主仓库目录做。第二个坑是Orca 会话没结束就删 worktree。agent 可能还有后台进程在跑直接git worktree remove会报目录被占用。正确做法是先确认 agent 会话退出再删。删之前记得git worktree prune清理元数据。第三个坑是Projects 卡片和 issue 状态不同步。issue 关了但卡片还在 In Progress看板就失真了。我的做法是加一个定时脚本每天扫一遍已关闭的 issue把对应卡片自动拖到 Done。这个脚本用gh issue list --state closed配合gh project item-edit就能实现。6. 这套流程跑顺之后还能怎么扩展第一天跑通之后我立刻想到几个扩展方向。一是让 Orca 自己更新卡片状态比如它开始干活时自动把卡片拖到 In Progress干完自动拖到 Done这样连手动拖拽都省了。实现方式是在 agent 的启动脚本里包一层 gh 命令。二是把 review 也交给 agent开 PR 后让另一个 Orca 会话专门做 code review把意见以评论形式贴回 PR。三是多 agent 并行一个 worktree 一个 agentProjects 看板就是调度中心你只需要盯着看板哪个卡片卡住了就去那个 worktree 看一眼。我个人在实际操作中的体会是这套组合真正的价值不在于AI 能写多少代码而在于它把 AI 的产出纳入了可管理、可追溯的工程流程。以前用 AI 编程最怕的就是改完不知道改了啥、想回滚找不到点现在每张卡片对应一个 worktree、一个分支、一个 PR历史清清楚楚。最后再分享一个小技巧给每个 worktree 目录放一个NOTES.md让 Orca 在干活过程中把关键决策记进去review 的时候先看这个文件比直接读 diff 快得多。