用途
prkit 是一款运行在本地 Mac 上的桌面应用,用于聚合多个 GitHub 账号的 Pull Request 收件箱,并借助代理(Agent)为 PR 差异或本地分支变更生成分章节的走读指南(guide),同时提供一个修复代理将审阅评论转化为提交。这些提交会停留在应用中,等待用户手动点击推送。prkit CLI 是该应用的命令行接口,它会与正在运行的 prkit 应用对话,因此从 CLI 发起的所有操作也会显示在应用内,并标注为“Started from prkit CLI”。CLI 适合让代理或脚本在不直接操作 GitHub 的情况下读取 PR、生成指南、提问以及准备修复改动。
主要能力
- 收件箱查询:通过
prkit inbox --json读取跨账号的 PR 收件箱,支持按原因(review-requested、authored、involved)、仓库、状态、草稿、检查状态、搜索、栈等条件筛选,并可按等待时间或风险排序。 - 读取 PR 与差异:使用
prkit pr read、prkit pr files、prkit pr file、prkit pr threads、prkit pr checks等命令读取 PR 元数据、变更文件与补丁、评论线程及检查状态,并支持分页游标。 - 生成指南:通过
prkit guide generate为 PR 生成代理走读指南,可指定代理实例、模型、选项、栈范围(this/all/编号层)以及版本化的 focus/guidance 设置;使用prkit wait等待完成,再用prkit guide read读取摘要、前后对比、主要风险等。 - 本地变更指南:在仓库内运行
prkit local guide对本地分支变更(含已提交、暂存、未暂存和未跟踪文件)生成快照指南,不修改仓库;支持prkit local wait和prkit local read,并可对指南代理发起只读提问。 - 向指南代理提问:通过
prkit questions ask和prkit questions wait针对 PR 或本地指南提出只读问题,支持按章节或差异行范围提问,回答会引用文件与行号。 - 修复代理:使用
prkit comments add添加本地草稿评论,prkit fix send将草稿发送给修复代理,prkit fix read、prkit fix diff、prkit fix patch查看修复结果,prkit fix change调整修复,prkit fix resolve处理合并冲突。所有修复产生的提交都等待用户在应用中点击推送。 - 状态与账户:
prkit status --json报告应用是否打开、Outside agents 访问级别、账号及其 GitHub 预算、配置目录问题等;prkit accounts --json和prkit agents --json分别列出账号详情和模型选项。
使用方式
CLI 的已安装版本是标志(flags)的权威来源,不确定时应运行 prkit --help 或 prkit <command> --help。建议首先运行 prkit status --json 确认应用状态。退出码用于指示后续操作:0 表示完成;1 表示操作失败(消息说明原因);2 表示用法错误;3 表示 prkit 未打开、Outside agents 关闭或 CLI 无法连接;4 表示需要“Read and start work”权限;130 表示被 SIGINT/SIGTERM 中断。若沙箱阻止回环网络,命令会以退出码 3 失败,需用户允许网络或允许命令在沙箱外运行。
输出方面,需要自行解析结果时使用 --json 获取 prkit MCP 工具返回的结构化答案;向用户直接展示时使用纯文本输出。分页读取使用 --limit(1 到 100)和 --cursor,应保持相同命令、目标和过滤条件,原样传递 nextCursor 直到其为 null。补丁可能跨页,需按偏移顺序拼接同一路径的文本片段直到 complete 为 true。若返回 _tag: "response-fragment",需保持逻辑页游标不变,用 --response-cursor 跟随 nextResponseCursor,按偏移拼接文本后再解析完整 JSON。
命名 PR 时传入 URL 或 owner/repo#123;GitHub Enterprise 主机使用短格式时需加 --host。若 prkit 可通过多个账号读取该 PR,会失败并列出账号,需用 --account 指定。仓库命令使用 owner/repo,收件箱过滤使用 --repo owner/repo。账号以 host/login 形式表示,而不是 token。
适用场景
- 用户想快速了解收件箱中哪些 PR 等待审阅、各仓库分布及等待时长。
- 在正式审阅前,通过代理生成的指南了解 PR 或本地分支变更的摘要、前后对比与风险。
- 对指南未覆盖的内容向编写指南的代理发起只读提问。
- 将审阅评论整理为草稿,并交由修复代理生成待推送的提交。
- 在本地提交 PR 前,对本地变更生成走读指南进行自查。
限制
任何写入 GitHub 的操作都必须在应用内点击完成,包括推送、合并、发表或解决评论与审阅、添加审阅者、标签、关闭 PR 等。账号与代理设置、全局或仓库设置更改、丢弃或回退修复工作、删除本地指南也同样需要在应用中操作。这是有意设计:代理读取 PR 内容时可能被其影响,因此代理的任何输出都不能在用户看到之前到达 GitHub。但存在一个例外:若用户在仓库中同时启用了自动冲突解决和自动推送,prkit 的监视器可在受监视的 PR 上解决并推送冲突。
读取设置是允许的。在“Read and start work”级别下,还可以打开、关闭、聚焦或重排本地标签页,保存应用内收件箱过滤,编辑或移动本地草稿评论,标记文件已审阅,以及保存 PR 范围的指南设置;这些操作仅留在本机。关闭标签页不会关闭 GitHub 上的 PR。当用户要求被排除的操作时,应告知其在 prkit 中等待处理,并可用 prkit pr open <pr> 在应用中打开该 PR;只有用户明确要求时才通过其他方式(如 gh)执行。
指南生成需要几分钟,应使用 prkit wait 等待而不是循环睡眠读取。每个 PR 一次只回答一个问题,冲突时需先等待或停止。本地指南快照会遗漏超过 50 MB 的文件、Git LFS 文件和嵌套仓库,状态中会通过 leftOut 说明。不得为了让命令工作而暂存、提交、切换分支或修改用户文件。