用途
pre-push 用于让分支达到可推送状态：先识别本次改动涉及哪些区域，自动修复可机械修复的问题，再运行 CI 合并门禁对这些区域执行的同类检查，并与开发者一起分类处理剩余问题。
该技能位于 strands-agents/harness-sdk 仓库的 .agents/skills/pre-push/ 下。仓库 CI（.github/workflows/ci.yml）会检测三个区域中哪些发生变化并只运行对应检查：python（strands-py/）、typescript（strands-ts/）和 docs（site/）。本技能在本地镜像这一路由逻辑。
主要能力
- 区域检测：使用与 CI 相同的路径过滤器，比较最近的 main/master 基准（本地或任意远程，支持 fork 上的 upstream/main），并结合已暂存、未暂存和未跟踪的改动，判断涉及的区域。
- 第一阶段自动修复：格式化、lint --fix 和锁文件同步，仅作用于本次改动触及的文件，写入工作区文件，不会导致运行失败。
- 第二阶段检查：构建、lint 检查、格式检查、类型检查、测试、审计，在整个代码树上运行以获得与 CI 对等的效果，并决定通过或失败。
- 失败摘要：运行失败时，脚本在结尾列出每个失败步骤及其错误输出的最后 20 行。
- 可通过参数控制范围：--list 只显示检测到的区域和触发文件；--all 运行全部区域；--base <ref> 指定比较基准；--heavy 额外运行默认跳过的较慢 CI 对等步骤（浏览器测试、test:package、完整 Python 版本矩阵）；也可显式指定 python、typescript、docs 覆盖自动检测。
使用方式
在仓库内运行：
bash .agents/skills/pre-push/run-checks.sh 2>&1
在子目录中运行时：
bash "$(git rev-parse --show-toplevel)/.agents/skills/pre-push/run-checks.sh"
非零退出码表示存在失败。建议先使用 --list 确认检测范围。准备创建 PR 时，先运行本技能，再使用 pr-create / pr-writer 技能起草并创建 PR。
失败后的处理
脚本退出码为 0 即完成。非零时按失败项分类：
- 机械且无歧义的问题：如缺失类型标注、linter 提示但未移除的未使用导入、需要提交的锁文件，直接修复后重新运行脚本。
- 存在歧义的问题：应带着失败输出回到开发者处再改动。典型是测试失败——可能改动破坏了真实行为（修代码），也可能是预期行为变化导致测试过时（修测试），不应猜测，也不应仅为让测试通过而重写测试。
- 自动修复器无法解决的 lint/类型错误：通常为机械问题，修复代码后重跑。
- npm audit 的高危告警：可能是与本次改动无关的既有传递依赖问题，应告知用户而非阻塞其工作。
- 缺少工具（如未找到 hatch/npm）：脚本会提示安装方式，应如实报告，不要静默绕过。
适用场景
在即将推送分支或打开 PR 前使用。它是手动调用的检查，不是 git 钩子，只在被请求时运行，因此不会妨碍增量提交。
限制与注意事项
- 应始终运行脚本，而非手工拼凑命令，以保持路径过滤器和检查清单与 CI 同步。
- 全部通过只清除确定性的单平台失败，并不复现 CI 的操作系统/版本矩阵或 npm-pack 冒烟测试，因此应报告“本地检查已通过”，而非“CI 将通过”。
- 第一阶段会写入工作区文件（格式化器、锁文件），用户可在提交前用 git diff 查看。
- 若未检测到任何区域（例如改动仅涉及 python/typescript/docs 之外的文件，如顶层文档或 .agents/），说明合并门禁没有对应检查，应如实说明。