JohnXu22786/ci-runner

English

ci-runner

触发你的 CI，并让它自己给出修复建议——一个 dsh 插件 bundle：触发 GitHub
Actions 工作流与本地测试流水线，回读日志，跟踪运行状态；失败时把日志尾部交给
DeepSeek，生成包含根因与修复步骤的 Markdown 诊断报告。

- 两种来源，同一套接口：GitHub Actions（workflow_dispatch +
check-run API）与本地命令流水线（npm test、pytest 等，走平台 shell）。
- 有界的日志回读：GitHub 任务日志按 job 分段拉取并截取尾部；本地输出按
流设置上限，失控进程也不会撑爆上下文。
- DeepSeek 失败诊断：失败时把日志尾部 + 规则式错误分类交给
harness 的 ctx.llm（或任意配置的 OpenAI 兼容接口），产出包含失败阶段、
错误类型、最可能的根因、建议修复步骤、相关文件的 Markdown 报告。
- 状态跟踪：轮询 queued / in_progress / completed 直至结束，间隔与
超时均可配置。
- 凭据只走环境变量：GitHub token 在调用时刻从环境变量读取，不进日志、
不落盘；所有返回的日志与报告都会对已知密钥做掩码。
- 零运行时依赖：fetch + node:child_process，纯 Node.js ESM，内置
五个工具（ci_trigger、ci_status、ci_logs、ci_watch、
ci_diagnose）与配套 CLI。

工作方式

你的仓库 / 你的机器
│   workflow_dispatch + check-run API         shell（npm test、pytest…）
▼                                             ▼
GitHubApi (fetch)                       LocalRunner (child_process)
│                                             │
└──────────────► CiService ◄──────────────────┘
│   trigger · status · logs · watch · diagnose
├─► dsh adapter：在 ctx.tools 注册五个 ci_* 工具（分析走 ctx.llm）
├─► CLI：       ci-runner trigger|status|logs|watch|diagnose
└─► 报告：      固定五个章节的 Markdown

所有状态（本地运行结果、配置、密钥掩码）都在一个 CiService 实例中，
工具与 CLI 行为完全一致；dsh adapter 与 CLI 只是它的两个薄入口。

环境要求

- Node.js >= 18.17（全局 fetch）
- dsh 集成需要：可用的 DeepSeek Harness（提供 tools 服务；模型诊断还需要
llm 服务）。
- 环境变量中的 GitHub token（默认 GITHUB_TOKEN），dispatch 需要
actions:write，状态/日志需要 actions:read。

接入 dsh

作为 dsh bundle（推荐）

bundle 是以 npm 包形式提供配置层的分发单元。在目标 profile 下执行：

dsh plugin --profile demo add ./path/to/ci-runner

该命令会把本目录链接进 profile 的 bundle 列表（因为 package.json 声明了
dsh.bundle）。验证并启动：

dsh --profile demo --dump-config   # 应看到 "# == dsh-ci-runner" 配置层
dsh --profile demo

bundle 自带的补丁层（cordis.patch.yml）插入一行插件，挂载 adapter 入口
（包子路径，通过 package.json 的 exports 映射解析）：

- insert:
- id: ci-runner
name: dsh-ci-runner/adapter

作为补丁覆盖文件（不打包）

直接把插件行指向 adapter 源码。新建覆盖文件 ci-runner-patch.yml：

- insert:
- id: ci-runner
name: '/src/adapter.js'

然后：

dsh --patch ./ci-runner-patch.yml

插件配置

以 bundle 方式安装后，通过 profile 配置为 bundle 层贡献的字段来配置，所有
字段可选且带默认值：

profile/config.yml
ci-runner:
github:
defaultRepo: acme/app
defaultBranch: main
diagnosis:
llm:
baseUrl: https://api.deepseek.com/v1
apiKey: sk-...
model: deepseek-chat

不配置 diagnosis.llm 时，分析走 harness 的 ctx.llm 服务（推荐，跟随
harness 已配置的供应商）。两者都没有时，诊断仍会输出确定性报告（失败阶段 +
错误分类 + 日志尾部），并注明缺少模型。

配置项

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| github.tokenEnv | GITHUB_TOKEN | 存放 GitHub token 的环境变量（调用时读取，绝不记录） |
| github.defaultRepo | '' | 默认 owner/repo |
| github.defaultBranch | main | 未指定 ref 时使用的分支 |
| github.apiBase | https://api.github.com | REST 基址（企业版可覆盖） |
| github.pollIntervalMs | 5000 | 状态轮询间隔 |
| github.pollTimeoutMs | 600000 | 等待运行结束的硬上限 |
| github.dispatchWindowMs | 20000 | dispatch 后等待 run id 出现的时间 |
| github.requestTimeoutMs | 30000 | 单次 HTTP 请求超时 |
| github.readLogChars | 30000 | ci_logs 默认尾部截断字符数 |
| local.cwd | . | 命令运行目录 |
| local.timeoutMs | 120000 | 单条命令硬超时 |
| local.maxOutputChars | 40000 | 每流输出上限 |
| local.templates | [{name:'npm test',command:'npm test'},{name:'pytest',command:'pytest'}] | 命名命令模板 |
| diagnosis.llm | null | OpenAI 兼容端点覆盖 {baseUrl, apiKey, model} |
| diagnosis.provider | '' | ctx.llm 供应商路由（'' = 自动） |
| diagnosis.model | '' | ctx.llm 模型（'' = 自动） |
| diagnosis.maxTailChars | 12000 | 交给模型的日志尾部字符数 |
| diagnosis.timeoutMs | 120000 | 分析调用硬预算 |
| diagnosis.temperature | 0.2 | 采样温度 |
| diagnosis.providerLabel | OpenAI-compatible | 使用端点覆盖时记录在报告中的提供方标签 |

模板让模型与 CLI 能按名字引用流水线（ci_trigger {source: local,
command: 'npm test'}）；不以模板名匹配的值会被当作原始 shell 命令行执行。

工具

| 工具 | 用途 |
| --- | --- |
| ci_trigger | 触发 GitHub workflow_dispatch（返回 run id）或跑完一条本地流水线 |
| ci_status | 单次轮询：状态、结论、失败阶段、job 与 step |
| ci_logs | 回读日志（掩码 + 尾部截断），job 可选单个 job |
| ci_watch | （可选先触发并）等待运行结束；失败时附带日志尾部 |
| ci_diagnose | 端到端：运行/等待后，把失败尾部交给分析方并返回 Markdown 报告 |

报告结构

ci_diagnose（与 CLI 的 diagnose）总是输出固定章节：

CI Failure Report
Failure Stage           ← 首个失败的 job/step（未知则为 Unknown）
Error Classification    ← 规则式预分类
Most Likely Root Cause  ← 模型分析（无模型时注明）
Suggested Fix Steps     ← 模型分析
Related Files           ← 模型分析（"None identifiable from the log"）
Timeline                ← 已知的开始/结束/耗时
Failure Log Tail        ← 掩码 + 尾部截断

有模型时，模型产出的自由格式 Markdown 会被解析回上述章节后再渲染，保证结构
稳定，不随模型措辞变化。

CLI

ci-runner trigger  [--source github|local] [--repo owner/repo] [--workflow F]
[--ref R] [--inputs k=v ...] [--command CMD] [--template T]
[--cwd DIR]
ci-runner status   [--source s] --run ID [--repo r]
ci-runner logs     [--source s] --run ID [--job J] [--tail N] [--repo r]
ci-runner watch    [--source s] [--run ID | 触发参数] [--timeout-ms N]
[--interval-ms N] [--no-logs] [--json]
ci-runner diagnose [--source s] [--run ID | 触发参数] [--save PATH]
[--llm-base-url URL] [--llm-model M] [--llm-api-key K]

全局：--config PATH（JSON 配置文件）、--json、--help、--version。

不使用配置文件做 diagnose 时，传 --llm-base-url（可加 --llm-model 与
--llm-api-key；密钥也可来自 CI_RUNNER_LLM_API_KEY 或
OPENAI_API_KEY）。

本地 run id 是进程内状态：status/logs 只能引用同一次调用中捕获的本地
run id。跨 CLI 调用时，用 watch/diagnose + --command 直接驱动本地
流水线（或使用状态存于服务端的 GitHub run）。在 dsh 内五个工具共享同一
进程，捕获的 run id 在插件生命周期内一直有效。

示例

GitHub：在 main 上触发 ci.yml 并带 inputs，打印 run id
ci-runner trigger --workflow ci.yml --repo acme/app --ref main --inputs env=prod

本地：跑 "pytest" 模板（也可以是任意原始命令）
ci-runner trigger --source local --template pytest --cwd ./api

等待 run 123456789，失败则显示日志尾部
ci-runner watch --run 123456789 --repo acme/app --timeout-ms 600000

本地失败 → DeepSeek 诊断（Markdown 报告，同时存盘）
ci-runner diagnose --source local --command "npm test" \
--llm-base-url https://api.deepseek.com/v1 --llm-model deepseek-chat \
--save report.md

安全说明

- GitHub token 在每次调用时从 process.env[github.tokenEnv] 读取，仅存在于
内存，绝不写入日志、报告或磁盘。
- 所有返回的日志文本都会对 GitHub token 与配置的分析 API key 做掩码
（** 替换）。
- 本地命令只在配置的 cwd 下运行，超时按进程树整体杀死，不会留下孤儿孙
进程。
- 诊断载荷只包含日志尾部，token 永远不会到达模型。

目录结构

bin/ci-runner.mjs        CLI 启动器
cordis.patch.yml         bundle 补丁层（挂载 adapter 行）
src/
adapter.js             Cordis 插件入口：name / inject / Config / apply
index.js               公开包面（零 harness 依赖）
config.js              规范配置、默认值、校验
github.js              GitHub REST 客户端（dispatch、runs、jobs、logs、checks）
local.js               child_process 运行器（超时、进程树杀死、上限捕获）
logs.js                有界缓冲、尾部截取、ANSI 清理、密钥掩码
classify.js            规则式失败分类
llm.js                 提示词构建 + OpenAI 兼容客户端（零 harness 依赖）
dsh-llm.js             ctx.llm 流适配（harness 侧）
diagnose.js            运行元数据 + Markdown 报告组装
service.js             跨来源编排（工具与 CLI 共用）
tools.js               五个 ci_ 工具定义
cli.js                 CLI 实现
test/                    node:test 测试（mock GitHub API、临时脚本、诊断流程）
examples/                配置与 profile 覆盖示例

测试

npm install   # 安装 peer 依赖（schemastery、dsh-llm）供 adapter 测试使用
npm test      # node --test

License

MIT