diag-harness
GitHub检测本地 @metaharness/kernel 版本与脚手架 manifest 是否一致，判断兼容性及退出状态码。支持指定路径、CI 机器可读输出及自动脱敏的故障排查 Bundle 功能。
触发场景
安装
npx skills add ruvnet/metaharness --skill diag-harness -g -y
SKILL.md
Frontmatter
{
"name": "diag-harness",
"description": "Kernel-version skew check (ADR-027). Reports manifest surface + manifest kernel + installed kernel + verdict (match\/patch-diff\/minor-diff\/major-diff). Exits 1 on minor\/major skew with a copy-pasteable `npm install @metaharness\/kernel@X.Y.Z` next step. Exits 2 if no .harness\/manifest.json at path."
}
diag-harness
Codex skill: kernel-version skew check for a scaffolded harness — the ADR-027 diagnostic UX loop.
What it does
Single-question check: does my local @metaharness/kernel match what this harness was scaffolded against? That's the cross-machine compatibility question almost every "this harness doesn't work" support ticket turns out to be.
Reads .harness/manifest.json:
| Field | Source | Meaning |
|---|---|---|
meta.surface |
iter 56 | Which surface produced the harness (cli or web-ui) |
meta.kernel_version |
iter 58 | The @metaharness/kernel version stamped at scaffold time |
Resolves the local @metaharness/kernel via createRequire rooted at the harness's own package.json (real Node resolution). Computes the skew verdict and prints a copy-pasteable next step.
| Verdict | Exit | Message |
|---|---|---|
match |
0 | PASS kernel versions match exactly |
patch-diff |
0 | WARN patch-level skew (usually safe; may include bugfixes) |
minor-diff |
1 | WARN minor-level skew (new kernel features may be missing) + Run: npm install @metaharness/kernel@X.Y.Z |
major-diff |
1 | FAIL MAJOR skew — APIs may have changed; expect breakage + Run: npm install @metaharness/kernel@X.Y.Z |
no .harness/manifest.json at path |
2 | FAIL no .harness/manifest.json found at this path |
Usage from Codex
/diag-harness # cwd
/diag-harness path=./my-harness
Equivalent CLI
harness diag # cwd
harness diag ./my-harness # explicit path
harness diag ./my-harness --json # machine-readable for CI
harness diag ./my-harness --bundle # support-ticket JSON (iter 90)
The --bundle form (iter 90) emits a single JSON snapshot of the diag report + sanitised manifest + @metaharness/* deps + Node/platform info — everything a maintainer needs to triage a bug report. Object keys matching secret|token|key|password|api_key are redacted so the bundle is safe to paste into a public GitHub issue.
Sample output
harness diag — checking /tmp/my-harness
surface: cli
manifest kernel: 0.1.0
installed kernel: 0.1.0
PASS kernel versions match exactly
When to run
- After cloning someone else's harness — first thing
- After bumping
@metaharness/kernelin a harness'spackage.json - When
harness doctorfails with cryptic shape errors (skew is the usual cause) - In CI before any other harness subcommand — fail fast
Lifecycle position
scaffold (create-agent-harness)
↓
your code lives in the harness
↓
diag (this skill) <- before anything else, check compatibility
↓
doctor / validate / sign / publish
Related
- ADR-027 — CLI ↔ Web-UI integration (the parity contract diag enforces)
- iter 56 —
manifest.meta.surfaceadded - iter 58 —
manifest.meta.kernel_versionstamped at scaffold time - iter 66 —
harness diagsubcommand
版本历史
- 6e1902b 当前 2026-07-05 11:03
