RouteLint / 能力路由体检器

把 Table-GitHub-Capability-Router 的软规则，变成确定性、可测试的硬检查。

A deterministic validator that turns the capability-router project's soft rules into hard, testable checks.

English | 中文

📖 新读者推荐先看 INTRODUCTION.md —— 从真实痛点（token 黑洞、skill 滥用、agent 变慢）讲起，诊断根因，最后推出本解法。

---

What it is

RouteLint is a zero-dependency Node CLI that audits a "capability vault" — a folder of routing tables and capability manifests used by coding agents (Codex / Claude Code / others). It is the missing inspector for the capability-router workflow.

The capability-router project specifies many correctness rules (idempotency, truncation-safety, evidence gates, status classes) but enforces none of them — everything is trust-the-agent. This project is the enforcement layer. It complements the router project's own audit.mjs:

audit.mjs        looks OUTWARD  → what clients/skills are installed?
RouteLint looks INWARD  → are your own routing records correct?

It is read-only: it never edits files or changes client config.

Why it exists (the one-paragraph thesis)

When an agent's discovery layer gets crowded, descriptions compete and clients truncate them to fit the budget. A restriction written at the end of a line ("...only for X. Do not use for Y" → "...only for X. Do not") gets deleted, and the capability then triggers more, not less. The router project warns about this in prose. RouteLint measures it: it simulates the truncation and asserts the restriction survives the budget — turning advice into a pass/fail test.

The three check families

Family	What it checks	Example codes
1. Truncation-safety simulator	simulates client truncation; flags restrictions that fall beyond the char budget or get crammed at the line end	restriction-beyond-budget, restriction-at-end, catch-all-phrasing
2. Structural validation	reads YAML front-matter; checks ID uniqueness, enum validity, state combos, link integrity, placeholders, manager-type governance	duplicate-id, active-but-broken, manager-not-allowlisted, broken-link, placeholder-leak, bad-enum
3. Drift reconciliation	compares your registry's claims against the actually-installed environment	drift-missing, untracked-installed

Quick start

# requirements: Node.js >= 18 (tested on 26). No install step, no dependencies.

node scripts/routelint.mjs <vault-dir>                 # human report
node scripts/routelint.mjs <vault-dir> --json          # machine output (CI)
node scripts/routelint.mjs <vault-dir> --env audit.json  # + drift vs installed env

• Exit code 0 = no errors (warnings may remain). 1 = errors found. 2 = path missing.
• --env audit.json is the JSON output of the router project's own node integrations/.../audit.mjs --json. If omitted, RouteLint scans local skill roots (~/hub/skills, ~/.agents/skills, ~/.claude/skills, ~/.codex/skills).

See it work on the bundled fixtures:

node scripts/routelint.mjs tests/fixtures/clean   # → 0 errors
node scripts/routelint.mjs tests/fixtures/dirty   # → 13 errors
node tests/routelint.test.mjs                     # → full test suite

Try it without a vault

The truncation engine is exported and unit-tested:

node -e 'import("./scripts/routelint.mjs").then(m=>console.log(m.truncationSafety(
  "用途…（很长）…注意不要用于付费内容", {label:"x",budget:60})))'

Project layout

RouteLint/
├─ README.md                 ← you are here (intro + quick start)
├─ DEPLOY.md                 ← deployment guide (agent-friendly)
├─ AGENTS.md                 ← instructions for any agent that opens this repo
├─ docs/
│  ├─ how-it-works.md        ← architecture & rationale (L0–L4, soft→hard)
│  ├─ checks.md              ← full check reference (every code, severity)
│  ├─ soft-rules.md          ← which soft rule became which hard check
│  └─ manifest-schema.md     ← the YAML front-matter schema (the enabler)
├─ scripts/
│  └─ routelint.mjs             ← the validator (zero-dep Node ESM)
└─ tests/
   ├─ routelint.test.mjs
   └─ fixtures/{clean,dirty}/  ← passing + failing example vaults

What it deliberately does NOT do

• It never rewrites your descriptions — only the exposed layer needs truncation-safety; router-discovered capabilities are left alone.
• It never changes L0 client config. Visibility/isolation stays a user-approved configuration change.
• It never executes tools to prove runtime health — health is your declared value; RouteLint reasons over it.

Deploy as an opencode skill

Drop the folder into your opencode skills path and add its directory to ~/.config/opencode/opencode.jsonc → skills.paths. Then trigger it by saying "体检一下能力库" / "run RouteLint". See DEPLOY.md.

License

MIT — see LICENSE.

---

中文

这是什么

RouteLint 是一个零依赖的 Node 命令行工具，用来给"能力库"（coding agent 用的路由表 + 能力卡目录）做体检。它是 capability-router 工作流里缺失的那个"检查员"。

capability-router 项目规定了非常多正确性规矩（幂等、截断安全、证据门槛、状态分类），但一条都不强制，全靠 agent 自觉。本项目就是那层强制执行。它和原项目自带的 audit.mjs 互补：

• audit.mjs 看外面 → 装了哪些客户端/技能？
• RouteLint 看里面 → 你自己记的路由表对不对？

它是只读的：不改任何文件、不改客户端配置。

三大检查族

检查族	检查什么	示例 code
1. 截断安全模拟器	模拟客户端裁剪，标出超预算或挤在末尾的限制句	restriction-beyond-budget、restriction-at-end、catch-all-phrasing
2. 结构校验	读 YAML 标签，查 ID 唯一、枚举合法、状态组合、断链、占位符、总管型授权	duplicate-id、active-but-broken、manager-not-allowlisted、broken-link、placeholder-leak、bad-enum
3. 漂移对账	把你登记的状态和实际安装环境做对比	drift-missing、untracked-installed

快速开始

node scripts/routelint.mjs <vault目录>                  # 人类可读
node scripts/routelint.mjs <vault目录> --json           # 机器输出（CI 用）
node scripts/routelint.mjs <vault目录> --env audit.json # + 漂移对账

退出码：0 无错误（可能有 warning）；1 有错误；2 路径不存在。

完整中文讲解见 docs/ 与 DEPLOY.md。