github-fix-action-error

github-fix-action-error

用途

打通从 CI 运行失败到成功的闭环。此技能会找出当前分支上最近一次失败的 GitHub Actions 运行，提取日志，定位代码中的根本问题，在本地修复，并在用户批准后提交和推送修复，以便 CI 重新运行。

适用场景

• 用户说“修复 CI”“修复失败的工作流”“让构建通过”，或使用匈牙利语表达（“javítsd a CI-t”“piros a build, nézd meg”）
• 用户粘贴了失败的 Actions 运行 URL，并希望修复问题
• 用户提到某项检查失败，并要求修复

前置条件

开始任何操作前，先确认环境：

1. 位于 git 仓库中

git rev-parse --show-toplevel

如果不在仓库中，请明确告知并终止。

2. 工作区基本干净

git status --porcelain

如果有未提交的更改，请向用户展示并询问是否继续。将用户正在进行的工作与自动修复混在一起，会导致生成的提交难以审查；最好先暂停，让用户暂存或提交更改。

工作流

步骤 1：安全检查——分支

获取当前分支：

git rev-parse --abbrev-ref HEAD

如果分支是 main、master 或 develop，请拒绝并停止，并给出类似这样的消息：

Refusing to run on protected branch '<name>'.
This skill commits and pushes a fix directly; that's unsafe on shared branches.
Switch to a feature branch (or open one from the failing commit) and try again.

不要继续。不要提供“强制执行”的选项——此保护机制的核心目的，就是确保这些分支通过 PR 审查。

步骤 2：查找最近一次失败的运行

gh run list --branch "$BRANCH" --status failure --limit 1 \
  --json databaseId,displayTitle,workflowName,headSha,conclusion,createdAt

如果命令返回空列表，请告诉用户此分支上没有失败的运行，然后停止。还应检查其他非成功状态——运行可能是 cancelled 或 timed_out，而非 failure。如果找不到有用信息，请停止。

将 databaseId 提取为 RUN_ID。向用户显示一行摘要，让其知道正在检查哪次运行：

Inspecting run <RUN_ID>: <workflowName> — "<displayTitle>" (sha <short-sha>)

步骤 3：下载并扫描日志

gh run view "$RUN_ID" --log

日志可能很大。修复前先缩小到失败部分：

• gh run view "$RUN_ID" --log-failed 只会返回失败步骤的日志——如果可用，优先使用
• 搜索常见的失败标记：FAIL、error:、Error:、✗、failed、AssertionError、Traceback、error TS、error[E、FAILED、npm ERR!

确定：

• 失败的作业/步骤（工作流名称、作业名称、步骤名称）
• 失败类别——测试失败、编译/类型错误、lint/格式违规、依赖安装失败、脚本错误、基础设施偶发故障（网络、运行器）、缺少密钥
• 具体信号——测试名称、文件路径、行号、堆栈帧、规则名称

如果失败看起来是基础设施偶发故障（运行器断开、网络超时、速率限制、缺少密钥），而非代码缺陷，请告知用户，并建议重新运行工作流（gh run rerun <RUN_ID>），而不是修改代码。不要凭空编造修复方案。

步骤 4：在代码中定位问题

将日志信号映射到仓库中的代码：

• 测试失败 → 打开测试文件，理解断言，然后追踪到被测的生产代码
• 编译/类型错误 → 打开报告中的文件和行号
• lint/格式问题 → 打开文件；如果工具支持自动修复（eslint --fix、ruff --fix、cargo fmt、gofmt -w、./gradlew spotlessApply），优先运行自动修复，而不是手动编辑
• 缺少导入/未定义符号/构建脚本失败 → 阅读相关代码及最近的提交（git log -n 5 --oneline），了解发生了哪些变化

如果日志指向本地不存在的文件，或本地提交与 CI 运行时的提交不同（对比步骤 2 中的 headSha 与 git rev-parse HEAD），请告知用户。针对与 CI 运行时不同的代码树进行修复并不可靠。

步骤 5：实施有针对性的修复

以最小改动解决根本原因：

• 不要重新格式化、重命名或重构无关代码
• 不要掩盖真实故障（例如删除断言、添加一概适用的 try/except、对整个文件禁用 lint 规则，或将测试标记为 skip），除非用户明确要求这样做。如果测试确实有误，就修复测试；如果生产代码有误，就修复代码。说明修复了哪一项以及原因。
• 如果修复方式不明显，或存在多种合理解释，请暂停编辑并与用户讨论

步骤 6：条件允许时在本地验证

请求用户批准推送前，如果本地运行相同检查的成本低且可行，请重新运行：

• 测试失败 → 运行特定的测试文件或测试名称
• 类型错误 → npx tsc --noEmit、cargo check、mypy、go build ./... 等
• Lint → 运行 CI 使用的同一 linter

如果本地验证通过，请说明。如果无法在本地复现该检查（需要密钥、特定操作系统或大型服务），也请说明，并指出 CI 才是最终关卡。

步骤 7：总结并请求批准

简要总结：

Failing run: <RUN_ID> — <workflowName> / <jobName> / <stepName>
Root cause: <one-sentence diagnosis>

Files changed:
- <path>  (<what changed, in a few words>)
- <path>  (<what changed, in a few words>)

Local verification: <passed | not runnable — reason>

Commit and push? [Y/n]

等待用户回复。未经明确肯定答复，不要推送。除 y/Y/yes（或匈牙利语 i/igen）之外的任何回复都表示停止——让用户继续迭代或接手。

步骤 8：提交并推送

获得批准后：

git add -- <files you actually edited>
git commit -m "<generated message>"
git push

优先使用 git add -- <path> 添加指定文件；避免使用 git add -A / git add .，以免把无关更改一并加入。不要 amend。不要强制推送。不要使用 --no-verify——如果触发 pre-commit 钩子，应像处理其他故障一样处理：修复根本问题并创建新提交。

提交信息：使用符合 Conventional Commits 风格的主题，描述修复内容，而不是 CI 症状。如果 git log --oneline -n 20 中能看出仓库现有风格，请与之保持一致。

好的示例：

• fix(parser): handle trailing comma in object literal
• fix(ci): pin node to 20 to match lockfile
• test(user-service): correct expected timestamp format

不好的示例（不要使用）：

• fix CI——没有说明具体改了什么
• fix failing test——同上
• attempt 3——没有意义的内容

推送后，报告：

Pushed <short-sha> to origin/<branch>.
Watch the re-run with: gh run watch

除非用户要求，否则不要自行轮询 CI——推送即完成交接。

错误处理

情况	检测方式	操作
未安装 gh	command -v gh 失败	引导用户访问 https://cli.github.com
当前目录不在 git 仓库中	git rev-parse 失败	清楚说明后中止
受保护的分支	分支为 main/master/develop	拒绝并停止（步骤 1）
工作区有未提交更改	git status --porcelain 输出非空	显示更改，并询问是否继续
没有失败的运行记录	gh run list 为空	报告“没有需要修复的内容”并停止
本地 HEAD ≠ CI sha	headSha 与 git rev-parse HEAD 不同	警告用户；基于不同代码树修复并不可靠
基础设施偶发故障	日志显示是运行器、网络或密钥问题，而非代码问题	建议运行 gh run rerun，不要修改代码
根本原因不明确	存在多种合理的修复方式	暂停并询问用户哪种解释正确
无法在本地复现	需要密钥、服务或特定操作系统	在总结中明确说明；CI 才是最终关卡
Pre-commit 钩子失败	git commit 返回非零状态	修复钩子指出的问题并创建新提交（绝不使用 --no-verify）
推送被拒绝（非快进）	git push 返回非零状态	停止并告知用户；不要强制推送

关键约束

这些边界之所以存在，是因为此技能会写入共享历史：

• 绝不在 main、master 或 develop 分支上运行——无例外
• 未在步骤 7 中获得用户明确批准，绝不推送
• 绝不强制推送、修改已发布的提交或跳过钩子
• 绝不通过删除断言、捕获所有异常、跳过测试或禁用 lint 规则来掩盖失败；应解决真正原因，或交由用户处理
• 绝不在同一提交中包含与 CI 修复无关的更改——如果发现其他问题，应单独说明并交由用户决定
• 绝不为基础设施导致的偶发故障臆造修复方案；应建议重新运行
• 只要诊断存在歧义，就停下来询问——错误猜测的代价高于澄清问题