x-cmd Rule 与 Score:质量门禁与加权排名的双框架选型指南

原创2026-10-13 12:44:191,823 阅读
文章标签:CLI开发工具人工智能AI Agent

x-cmd Rule 与 Score:质量门禁与加权排名的双框架选型指南

本文基于 rule-vs-score.md 展开。Rule(规则检查)与 Score(加权评分)是 x-cmd 的 skill0 体系中互补的两套评估框架:前者回答「这个东西合格吗」,后者回答「这些候选里哪个最好」。本文先给出两者的定位对比与计分原理,再结合 x rule 命令族 与 score 计算引擎 的源码实现,说明各自的典型场景、组合用法与选型依据,帮助你(或 AI Agent)在具体任务中正确选择框架,并可直接上手使用。

Rule 与 Score:一张表看懂定位差异

两个框架解决的是不同类型的问题,不是同一问题的两种解法。核心差异如下表:

Rule Score
目的 找出问题——确保最低质量 评估质量——选出最佳选项
类比 质量门禁 / 检查清单 排名 / 排行榜
输出 每条规则的通过 / 不通过 加权总分 + 排名
典型目标 单一对象(一个文件、一个仓库、一个系统) 多个候选(3 个以上备选做对比)
动作 修复违规项 做出决策
回答的问题 "这个够好了吗?" "哪个最好?"
硬过滤 Rule level: error = 必须通过 TSV 的 block 列 = 淘汰,排名 X

从源码角度看,这两个框架在 x-cmd 中各有独立的命令与文件体系:Rule 对应 mod/rule/lib/ 下的 x rule 子命令与 *.rule.yml 规则集文件;Score 对应 mod/skill0/lib/skill0/core/score/ 下的 *.score.yml 标准文件与 *.score.tsv 评分报告文件。

计分原理:加权总分 vs 逐条判定

Score:按因子加权的 100 分制

Score 的总分公式为:

total = Σ(factor × score) ÷ Σ(factor) × 10   →   0–100

每个维度(dimension)有一个 0–10 的得分 score 和一个因子 factor(1–10,基线为 2)。维度表头会显示权重百分比。因子起放大作用——factor 8 的维度权重是 factor 2 的 4 倍。公式会自动归一化,因子总和不需要凑成任何固定值。

因子语义(见 score/SKILL.md 与 score-template-writer.md):

Factor 含义 使用时机
1 次要考虑 锦上添花,几乎不影响决策
2 基线 常规权重,各维度平级
4 2 倍重要 明显比基线重要
6 3 倍重要 非常重要,主导决策
8 4 倍重要 关键维度
10 5 倍重要 支配性因子——很少用,留给一票否决项

0–10 的评分刻度也有明确锚点(同见 score/SKILL.md):9–10 优秀(完全达标)、7–8 良好(有轻微缺口)、5–6 合格(方向对但明显缺失)、3–4 薄弱、1–2 失败、0 不适用。

实现层验证:total = Σ(factor × score) ÷ Σ(factor) × 10 正是 score/compute.py 中的计算逻辑 total = sum(f * s for f, s in zip(factors, scores)) / factor_sum * 10;维度权重百分比则在该文件 L80 由 factor_i / factor_sum * 100 算出。

Rule:逐条独立判定,不做加权聚合

Rule 按规则计数,没有权重、没有聚合。一个对象用 N 条规则检查,得到 N 个相互独立的结果。每条规则自己给出一个 0–100 的分数——100 = 通过,低于 100 = 违规。这些结果不做平均:10 条规则里有 3 条失败,那就是 3 个需要修复的问题。

pass_count = 规则中 score = 100 的数量
fail_count = 规则中 score < 100 的数量

实现层验证:在 x rule check 的批量检查提示词中(mod/rule/lib/check),Agent 只输出违规行(score 0–80)与说明,全部通过则只输出表头——这正是"逐条判定、问题即输出"的体现;而 x rule scan(mod/rule/lib/scan)则是贪心模式,只抓 1–5 个最严重的问题,适合快速内循环。

典型场景:什么情况下用哪一套

Rule 场景——"这里有没有问题?"

领域 示例规则 检查内容
代码质量 no-console-log 生产代码不得出现 console.log
文档 doc-orphan-010 每个 .md 都必须被某个 SKILL.md 引用
配置安全 no-hardcoded-secrets 提交的文件中不得有 API 密钥或密码
结构 rule-struct-010 每个 rule.yml 必须有 desc 字段
命名 file-naming-convention 文件必须遵循命名模式
Git 卫生 no-merge-commit-to-main main 分支只接受 squash/rebase

这类场景的问题永远是:"这个对象是否违反了该规则?"答案永远是:"违反(score < 100,以下是违规详情)"或"未违反(score = 100)"。

仓库内的真实规则集可以直接参考:ssh/config.rule.yml(如 ssh-root-login 检查 PermitRootLogin、ssh-password-auth 检查 PasswordAuthentication,均带 wrong/right 对照的 tldr 说明)与 os/general.rule.yml(磁盘使用率、内存压力、负载均值、僵尸进程四项检查)。

Score 场景——"我该选哪个?"

领域 示例模板 你在比较什么
技术选型 tech-stack 新服务用 Python vs Go vs Rust
生活 house 上周末看的三套公寓
职业 job 手头的 2 份录用通知
消费 car SUV vs 轿车 vs 电动车
植物 plant-cat 12 种对猫安全的植物
宠物 pet-office 办公室养什么宠物
礼物 gift 女朋友生日买什么
旅行 travel 下一个假期去哪里

这类场景的问题永远是:"这些候选里哪个最好?"答案永远是带分数的排名列表——而且用户可能不同意,会想调整因子。

仓库内可直接复用的模板参见 score/template/:例如 tech-stack.score.yml 用 6 个维度(项目契合度 factor 8、团队能力 6、生态成熟度 6、性能规模 4、维护性 6、集成成本 4)比较技术栈;job.score.yml 用薪酬、成长空间、AI 可替代性、文化与工作生活平衡、地点通勤、稳定性来比较录用通知。

组合场景——先 Rule 后 Score

有些决策需要两者配合:

  1. Rule 淘汰不可行的候选("这植物有毒 → 出局")
  2. Score 给幸存者排名("在安全的植物里,哪个最好养又最好看?")

更多例子:

  • 求职:rule 过滤掉不提供签证担保的公司 → score 按薪酬、成长、文化给剩余 offer 排名
  • 找房:rule 过滤掉超预算 / 不允许养宠物的楼 → score 按通勤、面积、街区排名
  • 选库:rule 过滤掉无人维护的库 → score 按 API 设计、性能、社区排名

这条"硬门禁 + 加权比较"的流水线在仓库中的落地形态是:rule 侧用 level: error 实现硬门禁(见 ror.rule.yml 中 rule-struct-005 等规则:error/must 规则阻断 CI,warn/info 仅作建议);score 侧用 TSV 的 block 列实现同等语义——block 非空即淘汰、排到底部、排名显示 X,该逻辑在 score/compute.py 中通过把 blocked 行与 passed 行分开排序实现。一个典型模板示例见 plant-cat.score.yml:对猫有毒的植物填 block → toxic to cats,compute 自动将其沉底——这跟 rule 的 error 一样,命中即出局,而不是罚几分。

边界是软的

  • 一条 rule 可以检查多个文件;一个 score 也可以只评估单个候选。
  • 两者的区分本质是意图(intent),而不是对象数量。
  • 如果问题是"这能通过吗?"→ 用 rule。
  • 如果问题是"跟其他选项比,这个有多好?"→ 用 score。

何时用哪个:选型决策速查

用 rule,当:

  • 你有明确的通过/失败标准(字段必须存在、值必须在范围内)
  • 你要在代码库中强制执行标准
  • 违规是可操作的——你确切知道要修什么
  • 例子:"每个 .rule.yml 必须要有 desc 字段"(对应仓库中的 rule-struct-010 规则,见 ror.rule.yml)

用 score,当:

  • 你在比较多个选项、需要做出决策
  • 标准是偏好而非绝对(权衡取舍)
  • 答案取决于用户的优先级(因子调优)
  • 例子:"这个项目该用哪个框架?"

两者都用,当:

  • 先用 rule 过滤掉不可行的候选(硬门禁)
  • 再用 score 给幸存者排名(加权比较)
  • 例子:rule 拦掉有毒植物 → score 按养护难度和美观度给安全植物排名

仓库落地:两套框架的完整工作流

Rule 的命令链与文件格式

Rule 侧通过 x rule 命令族使用,子命令包括 ls refine audit check scan fix evolve preset lint info test trial init(见 mod/rule/lib/main)。典型用法:

x rule lint <file>           # 纯静态校验(无需 LLM),检查 YAML 语法、规则 ID 格式、必填 desc、level 枚举等
x rule scan <files>          # 快速扫描,抓 1-5 个最严重问题(约 1 分钟,适合内循环)
x rule check <files>         # 全面合规检查(约 10 分钟)
x rule audit <files>         # 完整报告(约 30 分钟)
x rule init :ror             # 初始化规则集(devloop 流程的标准入口)
x rule preset ls             # 列出可用预设(如 :os、:ssh、:ror)

x rule lint 的实现见 mod/rule/lib/lint:先做 YAML→JSON 解析(顺带校验语法),再用 jq 过滤器做结构化校验,发现 error 级别问题即返回非零退出码——这正是"error 规则必须通过"的程序化体现。规则本身的元校验规则定义在 mod/rule/lib/meta.rule.yml。

一个规则条目(rule.yml)的标准字段为 name、apply、level(error/must/warn/info/debug)、desc(可操作的具体标准列表)、tldr(wrong/right 对照),并可带 testcase 用 shell 命令做确定性验证,完整示例见 ror.rule.yml。

Score 的双文件模型与计算命令

Score 侧采用"标准文件 + 结果文件"的双文件模型:

  • *.score.yml——可复用的评分标准:维度、因子、描述(示例见 tech-stack.score.yml)
  • *.score.tsv——被评对象 + 各维度得分 + 证据;第 1 列必须是 target

核心流程(见 score/SKILL.md):

① 理解需求 → ② 定义 score.yml → ③ 填 score.tsv → ④ x score compute → ⑤ 汇报与迭代
x score compute <standard.yml> <report.tsv>
# 等价于 python compute.py <standard.yml> <report.tsv>

输出列为 target, total, rank, block, reason, <dim> (X%), evidence:total 0–100 降序排列,rank=1 最优,block 非空者沉底且 rank 显示 X。x score compute 与 score/compute.py 等价——它会校验维度列存在、target 唯一且非空,计算加权总分与排名,并在输出表头标注每个维度的权重百分比。此外 x score iter 可基于用户反馈直接迭代重算。

配套的模板生态:x score ls 可列出 35+ 个模板,x score init -t <name> 复制使用,模板文件见 score/template/;如何编写高质量模板的规范见 score-template-writer.md(维度 5–7 个为宜、desc 必须给出 9-10 与 1-2 的具体锚点、block 列用于二进制门禁等)。

延伸阅读

登录后查看全文
x-cmd