在 PageAgent 仓库中安全提交 PRsubmit-pr-from-current-changes 技能全流程指南【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent导读本文基于 PageAgent 仓库中的.agents/skills/submit-pr-from-current-changes/SKILL.md技能文档完整讲解如何把一段未提交的工作区改动安全地转化为「新分支 规范提交 合规 PR」的完整流程。你将掌握该技能的硬性规则PR 模板保真、复选框管控、禁止虚构信息、前置条件检查、Shell 权限策略、分支命名与提交风格约定、npm run ci验证策略以及 PR 创建后的收尾提醒。文中所有命令与配置均以当前仓库实际内容为准可直接在本仓库或遵循同类协作规则的 monorepo 项目中落地使用。一、技能定位从工作区 Diff 到可审查 PR 的自动化链路submit-pr-from-current-changes是仓库.agents/skills/目录下供 Agent 调用的一个技能Skill。它的目标可以用文档原话概括为一句Turn a working tree diff into a clean branch, commit, and pull request.即把「尚未提交的本地改动」整理成一条干净的提交链并开出 PR其核心动作序列是理解改动读贡献规则、检查 diff健康检查主题统一、提交卫生、作者身份、残留产物、CI建分支遵循仓库type/topic约定暂存并提交conventional commits 风格推送git push -u origin HEAD开 PR严格按.github/PULL_REQUEST_TEMPLATE.md模板汇报结果并给出提交后提醒。该技能并不代表「Agent 可以自主替人类提交一切」——恰恰相反它内置了大量面向人工审查的护栏。这与 CONTRIBUTING.md 中「Vibe Coding with AI」一节的立场完全一致核心库与扩展core lib / extension禁止 vibe coding而 demo、website、UI 与测试则推荐使用 AI 协助且「任何由 AI 写出的内容在提交前都必须经过人类审查提交者是人而不是 AI」。技能中的许多复选框规则正是这条项目政策的落地实现。二、硬性规则Hard Rules合规是技能的第一优先级技能文档开篇就给出了五条不可逾越的硬性规则它们是整个 PR 提交流程的基石严格遵循 PR 模板模板位于 .github/PULL_REQUEST_TEMPLATE.md。必须完整阅读并把它的全部结构原样复制进 PR 正文不得删除、重排或跳过任何章节或复选框。永远不要勾选 Requirements / 要求 复选框这些是只能由人类提交者真实声明的声明——行为准则确认和 AI 作者声明。生成 PR 正文时它们必须保持未勾选状态- [ ]没有任何例外或变通即使人类明确要求也不能代勾。用户需要在 GitHub 上逐条核实后亲自勾选。只勾选真正验证过的 Testing 复选框只有当你确实在本会话中运行过npm run ci且它通过时才可以勾选 npm run cipasses。其余 Testing 复选框浏览器实测、无控制台报错、类型/文档已补充只能由人类手工验证必须保持未勾选。可以在 Testing 区域下方附加一段补充说明列出实际执行过的自动化验证及其结果。绝不虚构信息不得声称测试通过、命令已运行或检查已成功除非你确实在本会话中执行并观察到了输出。没跑过就是没跑过。PR 输出必须简洁PR 标题一行What 部分最多 12 句不要堆砌冗长解释——让 diff 自己说话。这五条规则的本质是把「可被事实核查」放在第一位Agent 能做的自动化验证CI允许如实上报凡是依赖人工感官与主观声明的项目浏览器体验、行为准则承诺、AI 作者声明一律不代勾。这与 AGENTS.md 中「Traceability and predictability is more important than success rate」可追溯性与可预测性比成功率更重要的项目价值观互为表里。2.1 模板结构速览技能要求「完整复制模板结构」因此必须先知道模板长什么样。当前仓库的 .github/PULL_REQUEST_TEMPLATE.md 包含四大区块What简要描述变更以及Closes #(issue)引用行。Type五选一的类型清单——Breaking change/Bug fix/Feature / Improvement/Refactor / Chores/Documentation / Website / Demo / Testing。Testingnpm run cipasses、Tested in modern browsers、Types/doc added。Requirements / 要求两条人工声明——已阅读并遵守行为准则与贡献指南指向 docs/CODE_OF_CONDUCT.md 和 CONTRIBUTING.md、此 PR 非 bot 或 AI 自主生成且人类已亲自编写或充分审查每一处变更。生成 PR 正文时Agent 需根据真实 diff 填写 What 与 Type其余按上文规则处理复选框。三、前置条件Prerequisites环境就绪检查在尝试推送或开 PR 之前必须先确认必要工具可用检查ghCLI 是否已安装并完成认证gh auth status。如果不可用停止并请用户先安装、认证 GitHub CLI而不是绕过或降级处理。如果工作流通过 MCP 工具执行 GitHub 操作则需确认 MCP 服务器可访问。这是技能文档中唯一允许「停下来求助」的场景之一工具链缺失不是可以靠代码技巧绕过的障碍。四、Shell 权限策略Keyring 认证与沙箱陷阱技能文档专门用一节说明了一个容易被忽视的环境细节gh从操作系统 keyring 读取凭据。沙箱化sandboxed的 shell 无法访问 keyring会误报认证失败。因此所有与 GitHub 通信的gh命令gh auth status、gh pr create、gh pr view等以及git push/git fetch第一次尝试就必须以完整权限运行Shell 工具上设置required_permissions: [all]不要在沙箱中先试探。本地只读的 git 检查git status、git diff、git log、git branch可以留在沙箱中执行。这条策略的要点是「一次到位」涉及网络与凭据的命令直接使用完整权限避免因沙箱权限不足产生的假性认证失败干扰判断纯本地只读操作则保持最小权限符合最小授权原则。五、核心流程从 Diff 审查到 PR 创建10 步全解析技能文档给出了完整的 10 步操作流程每一步都有明确的输入、动作与判据5.1 读贡献规则第 1 步阅读 CONTRIBUTING.md 以及与改动文件相关的包级说明例如 packages/website/AGENTS.md。不同子包可能有额外的质量约束——如 website 包要求优先使用 shadcn/ui 组件、不得手改src/components/ui/文件等。在命名分支或撰写 PR 之前先读这些说明属于技能文档「Decision Points」中明确要求的动作。5.2 审查 Diff第 2 步检查改动的文件范围、影响面先真正理解这次变更做了什么再动手写任何内容。理解 diff 是后续所有判断Type 归类、验证范围、风险定级的前提。5.3 调研仓库惯例第 3 步通过三条命令快速对齐仓库习惯git branch -r --sort-committerdate | head -20 # 最近活跃的分支名风格 git log --oneline -20 # 最近的提交信息风格 # 并阅读 PR 模板5.4 提交前健康检查第 4 步正式创建 PR 前必须执行五类检查检查项内容不通过的处理统一主题Unified theme所有改动应服务同一目的混入无关改动时请用户拆分或确认提交卫生Commit hygiene每个新提交遵循仓库 conventional commit 风格需要时 squash 或 reword作者身份Author identity核对git config user.name/user.emailemail 非空且看起来真实非noreply除非有意为之异常则警告用户残留产物No leftover artifacts检查调试日志、测试中的.only、冲突标记、临时文件清理后再提交CI运行npm run ci并确保通过如实记录结果不过则修复5.5 仓促 PR 预警第 5 步满足以下任一条件时必须暂停并先警告用户diff 很大且未提供意图描述改动触及核心库或扩展按 CONTRIBUTING.md 这些区域禁止 vibe coding一个 diff 混杂多个无关关注点完全没有运行任何验证。并提醒用户This project does not accept low-quality or AI-generated PRs without meaningful human review. Please review your changes carefully.本项目不接受未经有意义人工审查的低质量或 AI 生成 PR请仔细审查你的改动。5.6 分支策略第 6 步先查看当前分支若已在符合type/topic约定的非 main 特性分支上直接复用若分支名不符合仓库约定缺前缀、主题含糊询问用户是重命名还是新建若在main或默认分支上则从它新建一个短 kebab-case 分支前缀fix/、feat/、docs/、refactor/、chore/ 具体主题词。5.7 暂存与提交第 7 步只暂存预期要提交的文件提交信息采用type(scope): subject格式主题保持具体且紧凑。关于风格的更多细节见下文「提交风格」一节。5.8 推送第 8 步git push -u origin HEAD5.9 开 PR第 9 步gh pr create使用完整的 PR 模板结构根据真实 diff 填写 What 与 Type仅在npm run ci确实于本会话通过时才勾选该复选框其余 Testing 复选框与全部 Requirements 复选框保持未勾选。5.10 汇报结果第 10 步向用户报告分支名、提交哈希、PR 链接以及实际运行过的验证及其通过/失败结果。六、提交后提醒Post-Submission ReminderPR 成功开出后必须以用户的语言给出简洁、自然但足够清晰的提醒内容覆盖四点用户需要自己在浏览器中测试这些改动用户需要进入 PR 页面逐项核实后才勾选 Testing 与 Requirements 复选框在这些复选框被勾选之前PR 不会进入评审流程项目不接受 AI 自主生成的 PR因此只有声明属实才应勾选 AI 声明项。这既是流程收尾也是把「人类最终把关」的责任正式交还给提交者。七、分支命名与提交风格约定7.1 分支命名技能文档的明确约定优先使用带仓库一致前缀fix/、feat/、docs/、refactor/、chore/的短 kebab-case 名称先匹配变更类型再选择最小且有意义的主题主题用具体的业务词而不是整段 issue 文本的照搬。例如一次网站文档修正可命名为docs/website-api-reference一次核心 bug 修复为fix/core-dom-tree-crash。7.2 提交风格使用仓库主导的 conventional commits 风格改动区域清晰时使用type(scope): subject主题保持具体、紧凑若分支上存在多个提交每个提交都必须独立遵循约定。仓库根目录 package.json 中实际配置了 commitlintextendscommitlint/config-conventional并关闭了subject-case规则lint-staged会在提交前对*.{js,ts,jsx,tsx,css,md}等文件自动执行 Prettier 格式化与 ESLint 检查——这从工具链层面保证了「提交必须符合约定」不是一句空话。八、验证策略用npm run ci为 PR 提供证据技能文档的验证策略要点如下默认选择「足以支撑该 PR」的验证力度而不是绝对最低限度每次开 PR 前都运行npm run cibuild、lint、typecheck、tests且必须通过当 diff 跨包、改动共享代码或影响发布行为时升级为更全面的验证绝不声称未实际运行的检查可以在 PR 正文 Testing 区域下方注明实际运行过的检查及结果但不得勾选模板复选框。8.1npm run ci实际做了什么查看仓库根 package.json 可知ci: node scripts/ci.js而 scripts/ci.js 的执行序列是commitlint非 main 分支上基于git merge-base origin/main HEAD校验--from到HEAD的提交main 分支跳过并行执行四组检查各 120 秒超时npm run lintESLint 全仓扫描npx prettier --check .全仓格式检查npm run typecheck基于tsconfig.typecheck.json与 extension 的 tsconfig 双路类型检查npm testnpm workspaces 下所有包的单元测试buildnpm run build可用--no-build跳过。CI 全流程与 GitHub Actions 中 .github/workflows/ci.yml 的 pull_request 触发行为保持一致actions/checkoutv7 Node 24 npm cinode scripts/ci.js也就是说本地的npm run ci基本复刻了 CI 的判定标准这正是技能允许 Agent 在本地运行并据实上报的原因。8.2 测试的范围约定按 AGENTS.md 的说明当前单元测试集中在packages/llms其他包将逐步跟进真实外部 API 的测试命名为*.live.test.ts并通过test:live脚本暴露永远不会进入npm test或 CI。因此判断npm run ci通过时其「test」环节覆盖的是非 live 的单元测试集合。九、决策点Decision Points与完成检查9.1 关键决策点技能文档列出的分支判断一览场景处置没有本地改动停下如实说明ghCLI 不可用停下请用户安装混入无关文件只暂存预期子集或询问是否拆分仓库存在区域专属说明在命名分支或写 PR 之前先读改动小但高风险倾向于更全面的验证改动范围窄且低风险运行最相关的检查而非任意无关检查模板中有无法如实声明的声明保持未勾选并向用户说明原因9.2 完成检查清单提交结束后逐项核对分支已存在于远端并跟踪上游提交信息符合仓库风格所有提交作者均已配置正确的 name 与 emailPR 标题与提交意图一致PR 正文完整遵循模板结构全部 Requirements 复选框与仅限人类的 Testing 复选框保持- [ ]未勾选唯一可勾选的是 npm run cipasses且仅在确实通过时上报的验证结果准确、无虚构已用用户的语言、简洁准确地送达提交后提醒。十、技能与仓库治理的联动为什么这些规则存在将技能文档与仓库根部的治理文件对照可以更清楚地看到每条规则背后的动机CONTRIBUTING.md 明确「What We Dont Accept」包含Bot or AI-generated pull requests without meaningful human involvement无有意义人工参与的 bot/AI 生成 PR以及无事先讨论的 breaking changes 与大 PR——这正是技能「仓促 PR 预警」与「Requirements 复选框不代勾」规则的出处AGENTS.md 规定核心库与扩展禁止 vibe codingdemo/website/UI/测试推荐 AI 协助但须人工复核——对应技能中「改动触及 core lib 或 extension 时暂停警告」的判据技能要求先读CONTRIBUTING.md与包级 AGENTS 说明如 packages/website/AGENTS.md本质上是把仓库「区域差异化治理」前置到提交流程的第一步。因此submit-pr-from-current-changes并不是一个「替用户省事的自动提交器」而是一个在 AI 辅助编码与人类最终负责之间建立清晰边界的治理型工作流Agent 负责把 diff 整理成规范、可验证、可追溯的 PR人类负责浏览器实测与真实性声明。二者各司其职最终在 PR 页面汇合。十一、FAQ常见疑问速查Q1为什么 npm run cipasses 之外的 Testing 复选框不能勾因为浏览器实测、无控制台报错、类型/文档补充都依赖人工感官与主观判断Agent 无法「亲自验证」。唯一可由 Agent 通过执行命令获得确定性证据的是 CI 检查且必须在本会话中真实运行并通过。Q2用户明确要求勾选 Requirements 复选框怎么办拒绝并解释这是只能由人类提交者作出的真实性声明代勾即构成虚构信息违反技能硬性规则第 2 条。正确做法是让用户去 GitHub PR 页面亲自核实后勾选。Q3gh auth status显示未认证但我确定配置过很可能是沙箱 shell 无法访问 OS keyring 导致的假性失败。按技能的 Shell 权限策略所有gh命令与git push/git fetch首次尝试都应使用完整权限required_permissions: [all]执行本地只读 git 检查才允许留在沙箱。Q4改动跨多个包怎么办按验证策略跨包改动应升级为更全面的验证同时按健康检查混入无关文件时要拆分或请求确认。开 PR 前确认npm run ci全绿并如实上报运行过的检查项。【免费下载链接】page-agentJavaScript in-page GUI agent. Control web interfaces with natural language.项目地址: https://gitcode.com/GitHub_Trending/pa/page-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
