x-cmd Rule 与 Score:质量门禁与加权排名的双框架选型指南
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
有些决策需要两者配合:
- Rule 淘汰不可行的候选("这植物有毒 → 出局")
- 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 列用于二进制门禁等)。
延伸阅读
- mod/skill0/lib/skill0/core/rule/SKILL.md — 基于规则的合规检查技能(本框架的完整说明)
- mod/skill0/lib/skill0/core/score/SKILL.md — 加权维度评分框架(Rule 的配套搭档)
- mod/skill0/lib/skill0/core/devloop/SKILL.md — rule.yml 作为目标驱动开发循环中的验证产物
- mod/skill0/lib/skill0/core/naming/SKILL.md — 命名候选先经 rule 校验、再经 score 评分的工作流实例