Aether CI

Aether CI 状态查询与诊断 (aether-ci)

版本: 2.1.0 | 优先级: P1

快速开始

使用场景

• 查看最近 CI runs 的状态列表（表格化输出）
• CI 失败后自动诊断原因（15 种失败模式识别）
• 读取远程 CI 日志（SSH 策略链，授权开发机）
• 本地复现 CI 失败的测试/lint/docker 错误
• push 后主动检查 CI 结果

命令参数

执行流程

Step 1: 检测仓库信息

从 git remote 自动提取 owner/repo：

REMOTE_URL=$(git remote get-url origin)
# 支持格式:
#   ssh://forgejo@host/OWNER/REPO.git
#   git@host:OWNER/REPO.git
#   https://host/OWNER/REPO.git
OWNER_REPO=$(echo "$REMOTE_URL" | sed 's/\.git$//' | sed -E 's#.*/([^/]+/[^/]+)$#\1#')

Step 2: 查询 CI 状态

优先方式 — 使用 aether ci CLI（v1.5.0+，自动处理 API 调用和认证）：

# 结构化 JSON 输出
aether ci status --json

# 按分支过滤
aether ci status --json --branch master

JSON 返回字段：

Run list 格式化输出

将 JSON 渲染为对齐表格，便于快速扫读：

aether ci status --json | jq -r '
  ["Run ID", "Status", "Branch", "Commit", "Duration", "Triggered"],
  (.data.runs[] | [
    .id, .status, .branch, (.commit_sha[:8]),
    (if .duration_seconds then "\(.duration_seconds)s" else "-" end),
    .name
  ]) | @tsv' | column -t -s $'\t'

示例输出：

Run ID  Status   Branch   Commit    Duration  Triggered
1042    success  master   a3f9c12b  192s      test
1041    failure  master   a3f9c12b  47s       lint
1039    success  feat/x   9d1b4e7a  210s      test

Fallback — CLI 未安装时，直接调 commit status API：

SHA="${1:-$(git rev-parse HEAD)}"
forgejo GET "/repos/${OWNER_REPO}/commits/${SHA}/status"

Step 2a: 日志获取策略链

CI 失败时，按以下优先级获取日志，任一层成功即停止：

Tier 1: Forgejo API 原生日志（Phase 2/3，API 就绪后启用）
         → 无机器限制，任何环境均可用
         → 当前状态: 等待上游 API 支持 (Aether#8)

Tier 2: SSH via `aether ci logs`（Phase 1，当前实现）
         → 通过配置的 ci.ssh_host 读取服务端日志
         → 受限于授权开发机；CLI 内部处理 SSH 连接和超时

Tier 3: 本地复现（最终回退）
         → 在本地执行相同命令复现 CI 环境
         → 详见 Step 4

Tier 2 执行流程（当前优先路径）：

2a-1. 探测 CLI 可用性

aether ci status --json

命令成功（exit 0）→ CLI 可用，继续 2a-2。失败或未安装 → 跳至 Step 4（本地复现）。

2a-2. 读取日志

# 从 Step 2 获取失败 run 的 task ID
TASK_ID=$(aether ci status --json | jq -r '.data.runs[] | select(.status=="failure") | .id' | head -1)

# 读取完整日志
aether ci logs $TASK_ID

# 读取最近 200 行（通常足够定位错误）
aether ci logs $TASK_ID -n 200

# 快速定位错误行（推荐先用此命令缩小范围）
aether ci logs $TASK_ID --search "ERROR"
aether ci logs $TASK_ID --search "FAIL:"

约束:

• Skill 不得自行构造日志路径（路径规则封装在服务端）
• SSH 超时由 CLI 内部控制（默认 5s），Skill 无需额外超时设置
• 日志解压（zstd）在服务端完成，客户端不需要 zstd 二进制
• API 返回 500/429 或网络超时，统一视为"不可用"

2a-3. 降级行为

当 aether ci logs 返回非零退出码时，输出提示（非错误）："完整日志需在授权开发机上查看。当前进行本地复现..."，然后继续 Step 4，不中断诊断流程。

Step 3: 状态判断与响应

state == "success"  → 输出简短成功消息，结束
state == "pending"  → 输出等待消息；如有 --watch 则进入 Step 3a (轮询)
state == "failure"  → 进入 Step 4 (失败诊断)
state == "error"    → 提示 CI 系统错误，给出 Web UI 链接
total_count == 0    → 该 commit 无 CI 运行记录（可能未触发或 SHA 错误）

Step 3a: 持续监控 (--watch)

当 CI 仍在 pending 时，循环轮询：

• 轮询间隔: 45 秒
• 最大次数: 20 次 (~15 分钟)
• 每次轮询: 查询 /commits/${SHA}/status，检查 state
• 终止条件: state 变为 success/failure/error，或超过最大次数

超时后提示可能原因：

• Runner 队列积压
• Job 卡死
• 建议直接查看 Web UI

Step 4: 失败诊断 — 本地复现

本地复现作为 Tier 3 回退: 当策略链的 Tier 1/2 均不可用（API 未就绪、SSH 未配置、连接失败）时执行。也可通过 --reproduce 参数直接触发，跳过日志读取。

4.1 识别失败 Job

从 statuses 数组过滤 status == "failure" 的条目，获取 context 字段。

4.2 执行对应复现命令

# 示例: test 失败时
cd aether-cli && go test -v -race ./... 2>&1

# 示例: lint 失败时
cd aether-cli && golangci-lint run --timeout=5m 2>&1

4.3 注意事项:

• CI 使用 Go 1.22，确保本地版本一致
• CI 使用 -race flag，本地复现也应加上
• 如果本地通过但 CI 失败，可能是环境差异 — 提示用户检查

Step 5: 错误分析与修复建议

解析本地复现输出，匹配错误模式：

输出格式

成功

CI 状态: ✓ 通过
Commit: abc1234 — "feat: add volume backup"
Jobs: 2/2 passed (test: 3m12s, lint: 1m45s)
链接: https://forgejo.10cg.pub/10CG/Aether/actions/runs/161

失败 (含诊断)

CI 诊断报告
Commit: abc1234 — "feat: add volume backup"
状态: ✗ 失败 (1/2 jobs failed)
失败 Job: CI / test (push) | 耗时: 12m27s | 类别: test failure

--- FAIL: TestVolumeCreate (0.05s)
    manager_test.go:45: expected volume "data" to exist, got nil

修复建议: 检查 internal/volume/manager.go 中 volume 创建逻辑

补充信息: Actions Tasks API (CLI Fallback)

当 aether ci CLI 不可用时，直接调用 actions/tasks 端点并渲染 run list：

TASKS=$(forgejo GET "/repos/${OWNER_REPO}/actions/tasks?limit=5&page=1")
STATUS=$?

if [ $STATUS -ne 0 ] || echo "$TASKS" | jq -e '.workflow_runs == null' > /dev/null 2>&1; then
  echo "CI run list 不可用: API 返回异常 (可能是 500/429/超时)"
  echo "请检查 forgejo 连通性或直接访问 Web UI"
fi

echo "$TASKS" | jq -r '
  ["Run ID", "Status", "Branch", "Commit", "Duration", "Triggered"],
  (.workflow_runs[] | [
    (.run_number | tostring), .status,
    (.head_branch // "-"), (.head_sha[:8]),
    (if .duration then "\(.duration)s" else "-" end), .name
  ]) | @tsv' | column -t -s $'\t'

错误处理规则:

注意: 必须同时提供 limit 和 page 参数，否则返回全部记录。

返回的 workflow_runs 字段：

前置条件: API 配置

# 必需的环境变量（forgejo CLI wrapper 自动使用）
FORGEJO_API=https://forgejo.10cg.pub/api/v1    # Forgejo API 基地址
FORGEJO_TOKEN=<your-token>                      # API 认证 token
CF_ACCESS_CLIENT_ID=<cloudflare-access-id>      # Cloudflare Access 认证
CF_ACCESS_CLIENT_SECRET=<cloudflare-access-secret>

检测：如果环境变量未设置，提示用户参考 /aether:aether-setup 配置。

验证连通性：

forgejo GET "/repos/10CG/Aether" | jq '.full_name'
# 预期输出: "10CG/Aether"

与其他 Skills 的关系

aether-ci (CI 状态层)
    │
    ├── → aether-deploy (部署前检查 CI 状态)
    ├── → aether-deploy-watch (部署后监控 — 互补关系)
    └── ← aether-doctor (诊断 CI 配置问题)

与 deploy-watch 的区别:

• aether-ci: 关注 CI Pipeline 本身 (构建/测试/lint)
• aether-deploy-watch: 关注部署后的 Nomad 运行状态

故障处理

Aether 环境特有的 CI 故障模式 (TLS cert / EIDLETIMEOUT / operation not supported / docker.1ms.run tag 缺失 / invalid pkt-len) 见 ${CLAUDE_PLUGIN_ROOT}/references/forgejo-ci-optimization.md § Troubleshooting decision tree。

自动触发: Push 后自动监控

PostToolUse Hook (ci-watch-hook.sh)

scripts/ci-watch-hook.sh 检测 git push → 写入 .aether/ci-watch.state → systemMessage 触发 CronCreate 轮询。

git push → Hook 检测 → CronCreate (每 60s 轮询)
  → success: 通知 + CronDelete + /aether:deploy-watch
  → failure: 诊断 + CronDelete
  → 15 次超时: 警告 + CronDelete

轮询使用 aether ci status --json 查询状态，终态时 CronDelete 清理。 多次 push 自动 CronDelete 旧任务并启动新轮询。会话结束时 cron 自动销毁。

Related Issues

• aether-plugin#7 — CI 日志读取 (Phase 1: SSH via CLI 完成; Phase 2/3: Forgejo API 待就绪)
• Aether#8 — Forgejo API 上游跟踪（Tier 1 日志策略的前置依赖）
• US-024 — aether ci CLI 命令

Skill 版本: 2.1.0 最后更新: 2026-04-08 维护者: 10CG Infrastructure Team