oh-my-pi 编码代理 GitHub 工具深度指南op 操作、pr:// 协议与 Actions 监控实战【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本篇技术指南围绕 oh-my-pi⌥ Coding agent with the IDE wired in编码代理内置的github工具展开完整讲解其基于ghCLI 的 op 操作封装仓库/文件访问、PR 创建与 worktree 检出、多维度搜索、Actions 运行监控、issue:///pr://内部 URL 协议以及配套的搜索时间语法与安全边界。读完本文你将掌握如何让 Agent 在不触碰工作树的前提下安全地读写 GitHub 仓库、审阅 PR diff、推送分支并实时观察 CI 结果并理解每一层设计背后的源码依据。一、工具定位与能力总览github是 oh-my-pi 编码代理中通过 github.md 定义能力边界的工具描述文档其实现位于 gh.ts 的GithubTool类。它是一层薄薄的ghCLI op 包装器ghop wrapper覆盖六大能力域仓库与文件repo_view、file_read拉取请求pr_create、pr_checkout、pr_push搜索search_issues、search_prs、search_commits、search_repos、search_codeActions 监控run_watchIssue/PR 读取通过issue://N、pr://N内部 URLPR 差异审阅pr://N/diff、pr://N/diff/i、pr://N/diff/all工具通过op参数分派执行schema 定义在 gh.ts全部入参如下参数类型说明op字符串字面量11 种操作之一见下repostring?owner/repo可带host/前缀branchstring?目标分支pathstring?仓库相对路径file_read用prstring | string[]PR 编号、URL 或分支名数组可批量 checkoutforceboolean?重置已存在的本地分支pr_checkoutforceWithLeaseboolean?--force-with-lease推送pr_pushtitle/body/base/head/draft/fillstring/boolean?pr_create参数fill为 true 时从 commits 自动填充标题与正文reviewer/assignee/labelstring[]?创建 PR 时附加的评审者、指派者、标签querystring?搜索查询search_code必填since/untilstring?时间下界 / 上界过滤dateFieldcreated | updated?按创建时间或更新时间过滤limitnumber?结果条数上限runstring?Actions run ID 或完整 URLtailnumber?每个失败 job 抓取的日志行数从源码结构看execute()是一个纯switch分派器gh.ts每个 op 对应一个独立的执行模块repo_view→ gh-view.ts、file_read→ gh.ts、pr_*→ gh-pr-checkout.ts、search_*→ gh-search.ts、run_watch→ gh-run-watch.ts。二、issue://与pr://内部 URL 协议github.md明确声明读取 Issue 与 PR 使用issue://N/pr://N形式的内部 URLPR 差异则使用pr://N/diff家族。这套协议的解析器位于 issue-pr-protocol.ts其注释L9-L21完整定义了 URL 形状URL 形状含义issue:///pr://列出当前默认仓库最近的条目issue://owner/repo/pr://owner/repo列出指定仓库的条目issue://123/pr://123读取单个条目仓库从会话 cwd 推导issue://owner/repo/123/pr://owner/repo/123完整限定单个条目pr://ghe.example.com/owner/repo/123GitHub Enterprise 主机上的条目任意形状都可带host/前缀issue://owner/repo/123?comments0单条目、隐藏评论issue://owner/repo?stateclosedlimit20列表选项透传给gh2.1 diff 家族/diff、/diff/i、/diff/allPR 差异读取有三种模式issue-pr-protocol.tspr://N/diff列出PR 变更的文件清单每个文件带增 -删统计与变更类型add/modify/delete/rename/binary并给出可直接跳转的pr://repo/N/diff/i子链接pr://N/diff/i读取第 i 个文件的 diff 切片索引从 1 开始越界会明确报错并提示合法范围L467-L476pr://N/diff/all读取完整 unified diff。切片实现基于 gh-pr-diff.ts 解析出的文件偏移区间从完整 unified diff 中精确截取L478。协议层对格式校验非常严格issue://上出现/diff会被拒绝Issue 没有 diff提示改用pr://非法子路径既不是all也不是正整数会直接报错而不是静默回退L196-L207。2.2 默认仓库解析与会话隔离短格式issue://N/pr://N的仓库归属按顺序解析L248-L255调用方context.cwd→ 已注册会话的 cwd →process.cwd()。这保证了多会话并发时短格式读取不会串到错误的仓库。列表与单条目读取均经由 SQLite 背书的github-cache缓存跨会话共享渲染结果列表则是实时gh issue list/gh pr list。相关协议行为有完整测试覆盖见 issue-pr-protocol.test.ts。三、仓库与文件访问repo_view与file_readrepo_view与file_read的repo缺省语义一致省略repo即作用于当前 checkoutfile_read省略branch时读取默认分支github.mdL6-7。repo_view通过gh repo view --json拉取名称、描述、默认分支、Star/Fork 数、主题标签、归档状态、可见性、当前用户权限等字段gh-view.ts。file_read的实现gh.ts值得注意的细节路径必须是仓库相对路径以/开头的绝对路径会被拒绝L268-L270走gh api /repos/{owner}/{repo}/contents/{path}base64 解码后做三级内容探测L315-L349图片解析元数据后以图像附件注入遵循images.autoResize等设置、二进制嗅探前若干字节非 UTF-8/含 NUL 则提示用浏览器打开、最后才是严格 UTF-8 文本解码github.md的critical段落特别强调GitHub 托管仓库的文件必须用file_read读取严禁curl/wget。这既保证鉴权与缓存正确性也避免绕过工具自身的类型探测与超链接sourceUrl注入。四、PR 全生命周期创建、worktree 检出与推送4.1 创建 PRpr_createhead缺省为当前分支github.mdL8。除title/body/base/head/draft外schema 还支持reviewer/assignee/label数组以及fill从提交自动生成标题正文。校验规则gh-pr-checkout.tsfill与显式title/body互斥fillfalse且无title时直接报错。body 通过临时文件传入--body-file以规避 argv 长度与 shell 转义问题无 body 时显式传空串防止gh落入交互式编辑器L631-L645。创建成功后返回 PR 号、状态、base/head、作者、标签与完整正文等摘要。4.2 检出 PRpr_checkout与 dedicated worktreepr_checkout是整套工具中最讲究安全性的设计PR 检出永远落在独立的 git worktree绝不触碰工作树github.mdL9。这意味着 Agent 可以并行检出一个或多个 PR 而不会干扰正在编辑的主工作区。实现要点gh-pr-checkout.tspr接受 PR 编号、URL 或分支名传数组时一次调用批量检出多个 PRprRefs.map(checkoutPullRequest)支持部分成功——失败项与成功项会分开汇报L324-L352本地分支命名pr-numberworktree 目录基于getWorktreeDir(number-hashPath)生成若pr-N分支已存在且指向不同提交默认报错需显式forcetrue重置L453-L472跨仓库forkPR会自动为 head 仓库添加fork-owner形式的 remote若 URL 重复则复用已有 remote名称冲突自动加后缀再从该 remote fetch head 分支L146-L206检出后把branch.name.ompPrHeadRef、ompPrUrl、ompPrIsCrossRepository、ompPrMaintainerCanModify等元数据写入 git config作为后续pr_push的凭据L475-L490所有 git 变更在 per-repo 锁withRepoLock内执行避免并发 checkout 对共享的.git/config、packed-refs等文件的锁竞争L427-L435worktree 路径冲突时会尝试-2、-3…后缀直到WORKTREE_PATH_MAX_SUFFIX100L96-L117。worktree 默认是否克隆由设置worktree.clone控制后端由isolation.backend决定L497-L506克隆失败会回退为普通 checkout 并告警。4.3 推送回 PRpr_push的前置依赖pr_push必须先在pr_checkout中检出过对应分支github.mdL10因为推送目标信息全部来自 checkout 时写入的branch.name.ompPrHeadRef等元数据没有元数据的分支会被明确拒绝check it out via op: pr_checkout firstgh-pr-checkout.ts。推送支持forceWithLease成功后会使对应pr://N与pr://N/diff的缓存失效保证推送 → 重读 diff链路看到的是新数据L571-L577。五、多维搜索search_*与时间语法5.1 五种搜索与各自约束opquerysince/until默认 scopesearch_issues可选支持当前 checkout 的owner/reposearch_prs可选支持同上search_commits可选支持同上search_repos可选支持忽略repo参数全站用org:/language:限定search_code必填拒绝GitHub 代码搜索无日期限定符当前 checkout 的owner/repo省略query仅保留since/until时退化为纯日期过滤github.mdL11搜索结果条数上限默认 10、最大 50gh-search.ts想搜索其他范围直接在query内使用repo:/org:/user:限定符即可工具检测到显式 scope 限定符后不会再叠加默认repo:L261-L280企业版主机则以独立--hostname传给gh apiL287-L291。5.2since/until时间语法github.mdL13时间边界支持三种写法解析实现见 gh-search.ts相对时长n 单位m分钟/h小时/d天/w周/mo月/y年例如3d、2wISO 日期YYYY-MM-DDISO 日期时间完整 datetime会自动剥离毫秒因为 GitHub 搜索限定符只接受秒级精度。dateField决定按哪个时间过滤L131-L143默认created按创建时间指定updatedissues/PRs 按更新时间repos 按推送时间pushedcommits 恒用committer-date关键语义github.mdL13dateField: updated时永远不是创建时间。限定符最终组合为created:2026-09-01、created:...或区间created:start..endL111-L129。search_code使用Accept: application/vnd.github.text-matchjson额外获取匹配片段输出首个匹配行的片段预览L473-L476。六、Actions 监控run_watchrun_watch用于轮询 GitHub Actions 运行状态github.mdL14省略run时监控当前 HEAD 的所有 workflow runbranch缺省为当前分支且遇到第一个失败 job 立即快速失败fast-fail而不是等整个 run 跑完。6.1 两种监控模式指定 runrun传数字 ID 或完整 Actions run URLgh-run-watch.ts轮询该 run 直至完成按提交监控省略run时以当前 checkout或显式branch的 HEAD SHA 拉取该提交的全部 workflow runs。此处有个反直觉细节只按head_sha过滤、不按分支过滤否则会漏掉 tag 触发或 PR 触发的 run其head_branch与本地分支不一致L593-L604。6.2 轮询策略与失败处理前 60 秒以 3s 间隔快速轮询之后退避到 15s兼顾响应速度与共享鉴权配额的消耗RUN_WATCH_INTERVAL_DEFAULT3/RUN_WATCH_INTERVAL_SLOW15L43-L50检出失败后等待 5s 宽限期grace再抓日志以捕获并发失败如多个 job 同时崩限流rate limit / HTTP 429 / abuse detection会被退避重试而非直接放弃L192-L200失败时按tail默认 15、最大 200 行抓取每个失败 job 的日志尾部完整失败日志会保存为 session artifactgithub.mdL18工具结果同时携带 run/workflow/job 的明细与链接仓库未配置 Actions 或 Actions 被禁用时90 秒内未见到任何 run 会明确给出放弃提示而非无限轮询L1015-L1026。6.3 输出约定每个 op 返回精炼摘要github.mdL17-18run 状态、conclusion、分支、提交、各 job 状态与耗时失败场景下失败日志 tail 以 text 代码块内嵌完整日志进 artifact。七、安全边界与前置条件7.1 只读 vs 执行GithubTool.approval依据 op 归类审批等级gh.tsrepo_view、file_read、五个search_*与run_watch属于只读read直接放行pr_create、pr_checkout、pr_push属于执行exec需要审批确认。配合pr_checkout永不触碰工作树的 worktree 策略构成了读可自动、写须确认、工作区零污染的安全模型。7.2 运行前提机器上需安装并认证GitHub CLIgh工具在gh不可用时不会注册GithubTool.createIf返回 nullgh.ts未认证时gh auth login/ not logged into any GitHub hosts会得到明确的认证指引见 utils/github.ts多实例部署时可用GH_HOST等环境变量指定默认主机repo参数支持[host/]owner/repo形式——对于不在当前 checkout 所属 GitHub 实例上的仓库必须显式限定 hostgithub.mdL5解析逻辑见 gh-common.ts。7.3 已知限制以当前仓库为准search_code不支持since/untilGitHub 代码搜索本身没有日期限定符search_repos忽略repo参数只能靠query中的org:/language:等限定符圈定范围搜索limit上限 50、列表limit上限 100issue-pr-protocol.ts、tail上限 200。八、小结oh-my-pi 的github工具把日常 GitHub 操作收敛为 11 个 op 加上issue:///pr://内部 URL 协议读取仓库文件有统一的类型探测与缓存PR 审阅有清单 → 单文件切片 → 全文三档 diff 入口PR 协作有 worktree 隔离 元数据驱动的安全推送CI 观察有 fast-fail 与 artifact 日志兜底。其全部行为都可回溯到 github.md 的定义与 gh.ts、gh-pr-checkout.ts、gh-search.ts、gh-run-watch.ts、issue-pr-protocol.ts 等源码模块是一套Agent 友好、可验证、可审计的 GitHub 操作范式。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考