lina-community-fix-ci

name	lina-community-fix-ci
description	排查并修复给定的 LinaPro GitHub Actions 失败问题；修复完成后保留本地改动， 禁止自动提交、推送或创建 PR。 必须用户手动触发，禁止自动触发该技能。
compatibility	需要 GitHub CLI `gh` 已登录且具备读取 Actions run/log 权限；需要 `git` 与本地可执行的 make/测试命令。

Lina Community Fix CI

手动排查并修复 LinaPro 仓库中指定的 GitHub Actions 失败。该技能负责收集失败证据、定位根因、实施最小必要修复，并在本地尽量复现对应校验；修复完成后不得自动提交代码。

核心规则

1. 只手动触发：用户必须明确要求排查或修复 CI 失败；不得因看到 CI 红、PR 检查失败或对话中出现 Actions 链接而自动启动本技能。
2. 默认仓库：linaproai/linapro。用户指定其他仓库时使用用户指定值。
3. 目标明确：优先处理用户给出的 run URL、run ID、job 名、PR 编号或 workflow 名；未给出时先列出最近失败 run，让用户确认目标，不得盲修所有失败。
4. 先证据后改码：必须先读失败 job 日志、失败步骤、相关 workflow 定义和本地对应代码，再判断根因；禁止在未说明根因或合理假设前直接改代码。
5. 最小必要修复：只改与本次 CI 失败直接相关的文件；禁止顺手重构、格式化无关文件、升级无关依赖或扩大修复范围。
6. 禁止自动提交：修复完成后不得执行 git add、git commit、git push、gh pr create、gh pr edit，也不得调用 lina-community-commit-push-and-pr。本地改动保留给用户审查。
7. 禁止静默改写历史：不得 git reset --hard、git checkout --、git clean、--force 推送或丢弃用户已有未提交改动。
8. 尊重工作区：执行前检查 git status；若存在无关未提交改动，只修改本次修复相关路径，不还原、不混入无关变更。
9. 规则门禁：修改代码前按 AGENTS.md 判断命中的规则域，读取对应 .agents/rules/*.md；未读取命中规则不得改生产代码、测试或 workflow。
10. 本地验证优先：能本地复现的失败必须本地复现并验证修复；无法本地复现时明确说明原因、已做检查和下一步建议。
11. 不伪造通过：本地验证未覆盖到失败步骤时，不得声称“CI 已修复”或“下次 run 一定通过”；只能报告已确认的本地结果和剩余风险。

输入识别

自然识别以下用户请求：

• lina-community-fix-ci
• 修复 CI 失败
• 排查 GitHub Actions 失败
• fix this failing action
• 处理 PR #123 的 CI
• 修复 run 1234567890
• 粘贴的 Actions run URL、job URL 或失败日志片段

目标解析优先级

按顺序尽量解析出以下信息：

| 优先级 | 输入 | 解析方式 | | --- | --- | | 1 | Actions run URL / job URL | 提取 owner/repo、run_id，必要时提取 job_id | | 2 | run ID | 在默认或指定仓库查询该 run | | 3 | PR 编号 | 查询该 PR 最新失败 check run / workflow run | | 4 | workflow 名 + 分支 | 查询该 workflow 在指定分支上最近失败 run | | 5 | 仅说“修 CI” | 列出最近失败 run，请用户确认后再修 |

示例命令：

# run URL 示例：https://github.com/linaproai/linapro/actions/runs/1234567890
# job URL 示例：.../actions/runs/1234567890/job/9876543210

gh run view "$RUN_ID" -R "$REPO" --json databaseId,workflowName,displayTitle,headBranch,headSha,event,status,conclusion,url,jobs
gh pr checks "$PR_NUMBER" -R "$REPO"
gh run list -R "$REPO" --status failure --limit 10 \
  --json databaseId,workflowName,displayTitle,headBranch,headSha,event,status,conclusion,url,createdAt

前置检查

在修改任何文件前先做只读检查：

gh auth status
git rev-parse --show-toplevel
git remote -v
git status --short --branch
git branch --show-current
git rev-parse HEAD

确认：

1. 当前工作区是目标仓库可信检出，或用户明确允许在当前检出中修复。
2. gh 能读取目标仓库 Actions。
3. 当前分支/提交与失败 run 的关系清楚：
   • 同分支同提交：可直接修。
   • 同分支但本地已领先/落后：先报告差异，再决定基于当前工作区修复还是先对齐失败 SHA。
   • 完全无关分支：停止并说明需要切换到失败分支/检出对应提交，除非用户要求在当前分支前向移植修复。

如果权限不足、不在可信仓库、工作区有高风险脏状态且无法安全隔离修复，停止并报告阻断原因。

失败证据收集

1. 定位失败 run 与 job

gh run view "$RUN_ID" -R "$REPO" \
  --json databaseId,workflowName,displayTitle,headBranch,headSha,event,status,conclusion,url,jobs,createdAt,updatedAt

gh run view "$RUN_ID" -R "$REPO" --log-failed

日志过大时：

gh run view "$RUN_ID" -R "$REPO" --job "$JOB_ID" --log
# 或下载完整日志后本地检索
gh api "repos/$REPO/actions/runs/$RUN_ID/logs" > "/tmp/ci-run-$RUN_ID.zip"

必须提取：

• workflow 名称与文件路径（如 .github/workflows/main-ci.yml）
• 失败 job 名称
• 失败 step 名称
• 关键错误行、断言失败、编译错误、lint 结果、超时信息
• 触发事件（push / pull_request / workflow_dispatch / schedule）
• 失败提交 headSha 与分支 headBranch
• 是否 matrix 中的部分组合失败

2. 读取 workflow 定义

根据失败 workflow 读取本地或失败 SHA 对应定义：

# 优先本地当前工作区
sed -n '1,200p' .github/workflows/<workflow>.yml

# 需要对照失败提交时
git show "$HEAD_SHA:.github/workflows/<workflow>.yml"

重点确认：

• 实际执行了哪些 reusable workflow / composite action
• 关键输入参数（如是否开启 E2E、OpenSpec、Windows smoke）
• 使用的 make 目标、脚本路径、工作目录、环境变量
• 缓存、依赖安装、数据库/Redis 等外部依赖假设

3. 映射到本地验证命令

将失败步骤映射为可本地执行的等价命令。常见映射：

CI 信号	优先本地验证
Go 编译/单测失败	对应包 go test 或项目约定 make 目标
Go lint 失败	与 workflow 相同的 lint 命令
前端单测失败	对应前端测试命令
i18n check 失败	i18n 校验命令
make command smoke 失败	失败日志中的具体 make 命令
OpenSpec 完成性检查失败	openspec 相关校验
插件相关 job 失败	插件目录内对应测试/命令
Redis/集成测试失败	确认本地依赖后运行对应测试
E2E 失败	按 lina-e2e 与项目测试规范运行相关用例
仅 CI 环境问题（runner、权限、secrets、配额）	不改业务代码；报告为环境/配置问题

不得猜测命令；以 workflow YAML、composite action 和失败日志中的实际命令为准。

根因分析

在改代码前输出简短根因分析：

### CI 失败根因分析
- 目标：run <id> / job <name> / step <name>
- 仓库与引用：<repo> @ <branch> (<sha>)
- 失败摘要：<一句话>
- 根因判断：<代码缺陷 / 测试脆弱 / 工作流配置 / 环境依赖 / 权限或密钥 / flaky / 信息不足>
- 证据：<日志关键行、源码路径、workflow 路径>
- 拟修复范围：<文件或模块列表>
- 本地复现计划：<命令>
- 是否需要改 workflow：是/否（默认否；只有证据表明 workflow 本身错误才改）

分类处理：

1. 代码/测试缺陷：修复源码或测试，补齐必要断言或稳定化测试。
2. workflow/脚本配置错误：最小修改 .github/workflows/、.github/actions/ 或 hack/ 脚本；同时读取 dev-tooling 等命中规则。
3. 依赖/环境假设错误：优先让本地与 CI 假设对齐；确需改安装/启动逻辑时做最小修复。
4. Flaky / 竞态 / 超时：先证明是稳定性问题，再做确定性修复（等待条件、隔离、重试边界、超时调整需有依据）。
5. 外部系统或权限问题：不改业务代码冒充修复；报告所需权限、secret、runner 或上游服务问题。
6. 信息不足：继续收集日志/工件；仍不足时停止并向用户要补充信息，不进行猜测式大改。

修复实施

1. 读取命中规则

根据拟修改路径读取 AGENTS.md 与命中的 .agents/rules/*.md。常见映射：

• Go 后端：backend-go.md
• API/DTO：api-contract.md
• SQL/DAO：database.md
• 前端：frontend-ui.md
• 测试：testing.md
• i18n：i18n.md
• 插件：plugin.md
• 工具脚本/Makefile/CI 脚本：dev-tooling.md
• OpenSpec 文档/任务：openspec.md
• 文档：documentation.md

插件目录变更前，还要检查并遵守 apps/lina-plugins/<plugin-id>/AGENTS.md（若存在）。

2. 实施最小修复

• 只改消除失败所必需的代码、测试、脚本或 workflow。
• 保持现有风格和项目约定。
• 不把“让 CI 变绿”建立在删除有效测试、削弱断言、盲目 skip、或忽略错误之上，除非有充分证据证明该检查本身错误且修复检查定义更合适。
• 若失败暴露的是真实产品缺陷，按缺陷修复，而不是只改测试来迁就错误行为。
• 若修复触及用户可观察行为，评估是否需要补充或更新测试。

3. 本地验证

按映射命令验证：

1. 先跑与失败步骤最接近的最小命令，确认原失败点已消失。
2. 再跑直接相邻的回归检查（同包测试、同 workflow job 内前置步骤对应命令）。
3. 有明确相关的 lint/format/i18n/编译门禁时一并验证。

验证记录必须包含命令、退出码和关键输出摘要。失败则继续分析，不得在红的情况下宣布完成。

4. 明确禁止的收尾动作

修复与验证结束后，停止。以下动作全部禁止，除非用户在本技能之外另行明确要求：

• git add / git commit / git commit --amend
• git push / git push --force / git push --force-with-lease
• gh pr create / gh pr comment / gh pr edit / gh workflow run
• 自动调用 lina-community-commit-push-and-pr
• 删除或还原用户已有的无关本地改动

可以向用户说明“修复已完成，本地未提交；如需提交和开 PR，可手动触发 lina-community-commit-push-and-pr”，但不得自行执行。

特殊场景

PR 来自外部 fork

• 可以基于失败日志分析，并在当前可写工作区准备修复。
• 不得把密钥写入日志、代码或报告。
• 不运行不可信 PR 分支中来路不明的安装脚本；优先使用仓库既有 make/测试入口。

多 job 失败

• 先按日志判断是否同一根因。
• 同一根因：一次修复后分别验证相关命令。
• 不同根因：分项列出，按阻塞优先级逐个修；中途向用户同步进度。
• 不要只修第一个失败就宣称全部完成。

仅 schedule / nightly 失败

• 确认是否与主 CI 路径不同（E2E、镜像构建、发布步骤等）。
• 本地无法承担的长时任务要说明，并给出尽可能接近的替代验证。

失败已在后续提交修复

• 对比失败 SHA 与当前分支是否已包含修复。
• 若已修复：报告证据，不再重复改码。
• 若未完全修复：只补剩余缺口。

最终报告

处理结束后用简洁结构汇报：

## CI 修复结果

- 目标仓库：
- 失败 run：
- workflow / job / step：
- 失败提交与分支：
- 根因：
- 修改文件：
- 本地验证：
  - 命令与结果：
- 未覆盖风险：
- Git 状态：仍有未提交改动 / 工作区干净
- 提交状态：**未提交**（本技能禁止自动提交）

### 建议下一步
- 用户审查 diff
- 如需提交/推送/开 PR：手动触发 `lina-community-commit-push-and-pr` 或自行提交
- 如需重跑 Actions：由用户在 GitHub 重跑，或用户明确要求后再执行 `gh run rerun`

最终报告不得包含密钥、token、完整敏感日志或无关大段 diff。

护栏规则

• 先日志后改码 — 没有失败证据不改文件
• 先根因后方案 — 不靠删测试或 skip 换绿灯
• 最小 diff — 不修无关问题
• 遵守 AGENTS.md — 命中规则必须先读
• 本地能验则必验 — 验证失败不得宣称完成
• 永不自动提交 — 修完即停，等待用户决定是否提交
• 永不自动推送/开 PR — 与提交同样禁止
• 不破坏用户工作区 — 不丢弃、不混入无关改动 )