x-cmd score:加权维度评分框架,给 AI Agent 装上可迭代的决策工作流
x-cmd score:加权维度评分框架,给 AI Agent 装上可迭代的决策工作流
导读
x-cmd 的 score 模块 是一套为 AI agent 设计的加权维度评分框架,核心理念是 "Don't guess. Score."——面对多候选决策时,不再靠空想和印象,而是把"评价什么、各占多重、打多少分、依据是什么"全部结构化落盘:一份可复用的评分标准 *.score.yml,一份带证据的打分记录 *.score.tsv,再用 x score compute 一键算出加权总分与排名。读完本文,你将掌握该框架的两文件模型、加权公式与输出列含义,学会用 x score assess / compute / iter / refine / init / ls 完成"提问 → 定标准 → 打分 → 核算 → 汇报迭代"的完整闭环,并了解如何借助内置模板与 score-template-writer.md 写出高质量的评分标准。
一、框架定位:让决策有规则可依
score 是 skill0 核心库中的决策子技能,与 rule 形成互补:rule 负责"找问题"(合规检查、通过/失败),score 负责"选最优"(加权打分、排名)。二者的边界在 rule-vs-score.md 中有清晰对照:
| 对比项 | Rule | Score |
|---|---|---|
| 目的 | 发现问题,保证最低质量 | 评估质量,选出最佳选项 |
| 类比 | 质检门 / 检查清单 | 排名 / 排行榜 |
| 输出 | 每条规则的通过/失败 | 加权总分 + 排名 |
| 典型对象 | 单个对象(一个文件、一个仓库) | 多个候选(3 个以上备选方案) |
| 回答的问题 | "这够不够好?" | "哪个最好?" |
| 硬过滤 | rule level: error = 必须通过 |
TSV block 列 = 淘汰,rank 显示 X |
典型组合用法:先用 rule 把不合格候选筛掉(如"对猫有毒 → 出局"),再用 score 给幸存者排序(如"安全植物里哪个最好养、最好看")。score 内部也能表达硬门槛:TSV 的 block 列非空即视为淘汰。这就是 score-template-writer.md 强调的区分——"对猫有毒"是二值门槛,应进 block 列;"养护难"是程度问题,应作为低分维度打分。
二、核心流程:五步决策闭环
原文档给出了标准工作流,五步缺一不可:
① 了解需求 → 问清楚用户要什么,场景是什么
② 制定标准 → 写 score.yml(维度 + 因子 + 评分描述)
③ 打分 → 写 score.tsv(目标列表 + AI 打分 0–10 + 证据)
④ 核算校验 → x score compute <score.yml> <score.tsv>
⑤ 汇报与迭代 → agent 读排序结果,解释结论,根据反馈 refine
三条使用纪律贯穿始终:
- 先问够,再定标准。 维度搞错了,分数再精确也没用。写 score.yml 之前,先向用户问清楚"选一个 X 时,你最在意什么"。
- 抛砖引玉,迭代优于空想。 需求不清楚时,先做一版出来,打分排名给用户看。用户对具体排名有天然反应——"这个权重不对""你漏了 XX"。用
x score refine调整后重新打分,一轮迭代比十轮空想更高效。 - Agent 是分析师,不是计算器。
compute之后读 TSV——解释为什么 A 赢了 B、有什么意外、建议调整什么。排名是对话的开始,不是结束。
三、两文件模型
| 文件 | 内容 | 定位 |
|---|---|---|
*.score.yml |
维度(dimensions)+ 因子(factor)+ 评分描述(desc) | 可复用的评分标准 |
**.score.tsv |
目标(第一列)+ 各维度分数 + evidence | 目标与打分的决策记录 |
如果装了 x-cmd,x score compute <yml> <scores> 与 python compute.py 完全等价——两者都指向 compute.py 这条校验与核算逻辑。
3.1 标准文件 score.yml 的结构
以通用模板 general.score.yml 为例:
title: "General Weighted Scoring"
dimensions:
- name: dim-a
factor: 2
desc: "Describe this dimension. Include what a high score (9-10) and low score (1-2) mean."
- name: dim-b
factor: 2
desc: "Describe this dimension. Include what a high score (9-10) and low score (1-2) mean."
三个字段的含义:
name— 维度标识,必须与 score.tsv 中的列名完全一致(compute.py 会逐列校验,缺失即报错退出)。factor— 因子,整数 1–10,表示该维度的相对重要度。desc— 评分描述,必须给出具体可观察的 0–10 锚点,而不是"质量好"这种空话。
3.2 打分文件 score.tsv 的结构
第一列必须是 target(compute.py 强制校验),之后是各维度列(列名与 yml 的 name 对应),可追加 block、reason 和每维度的 evidence 列。例如:
target 性价比 性价比_evidence 性能 性能_evidence
方案A 8 单价低 30%,口碑榜第一 7 跑分实测 8500
方案B 6 单价中等 9 跑分实测 12000
compute 之后,compute.py 会重组输出列:固定列 target, total, rank, block, reason,接着是带权重百分比的维度列(如 性价比 (45%)),最后是其余输入列(evidence 等)。
四、公式与因子语义
4.1 加权总分公式
total_i = Σ(f_j × score_ij) ÷ Σ(f_j) × 10
- f_j — 维度 j 的因子(整数 1–10)。基线 = 2,越大表示越重要。
- score_ij — 目标 i 在维度 j 上的分数(0–10)。
- total_i — 目标 i 的加权总分(0–100)。
公式在 compute.py 中逐行实现:total = sum(f * s for f, s in zip(factors, scores)) / factor_sum * 10。按总分降序排列,rank = 1 为最高分;block 列非空的候选沉底且 rank 显示 X(compute.py)。
4.2 因子是相对放大器,自动归一化
因子不需要加起来等于任何值——公式会自动归一化。基线 = 2(正常权重),不重要的维度给 1,按倍数上调:
| 因子 | 相对重要度 | 适用场景 |
|---|---|---|
| 1 | 次要考虑 | 可有可无,几乎不影响决策 |
| 2 | 基线 | 正常权重 |
| 4 | 2× | 明显比基线重要 |
| 6 | 3× | 很重要,驱动决策 |
| 8 | 4× | 关键维度 |
| 10 | 5× | 主导因子,留给一票否决级要素 |
每个维度在输出 TSV 的列头会标注权重占比:factor ÷ Σ(factor) × 100。真实模板印证了这条语义——如 laptop.score.yml 中 performance 因子 9、price-value 因子 5,性能约占总权重 9÷(9+7+6+5+5) ≈ 28%;而 plant-cat.score.yml 把"宠物安全"拉满到 10,明确注释"这是硬指标——用户有猫时不可降低此因子"。
五、完整实战:宣传口号方案决策
原文档以"协助用户决策宣传口号"为例,完整走一遍流程:
- 先与用户商量,得出评价维度与标准,生成
宣传口号.score.yml。 - 决策:
- 如果有 x-cmd,执行
x score assess -f "<宣传口号>.score.yml" [...targets-to-assess],会自动生成文件<宣传口号>.<datetime like 260605-194400>.score.tsv; - 或者执行以下等同步骤:
- 2a:将待决策的口号列出放在第一列,让 AI 对每个口号在各维度上打分(0–10,附 evidence),生成
宣传口号.260605-194900.score.tsv,总分和 rank 留白,等待步骤 2c 计算; - 2b:通过
compute.py或x score compute计算 total + rank,补全宣传口号.260605-194900.score.tsv。
- 2a:将待决策的口号列出放在第一列,让 AI 对每个口号在各维度上打分(0–10,附 evidence),生成
- 如果有 x-cmd,执行
- 读取结果,与用户讨论。可调整步骤或者增加候选后重复步骤 2,例如用
x score iter -f "<宣传口号>.score.yml" "宣传口号.260605-194900.score.tsv" "<调整意见,或者增加候选>"。
文件名仅作示意,实际可自行命名。更多场景示例见 EXAMPLE.md,其中给出了功能优先级排序与供应商选型两个可复制的完整用例(含打分前后对照)。
5.1 一个可复现的完整用例
以 EXAMPLE.md 中的供应商选型为例:
vendor.score.yml:
title: "Vendor Evaluation"
dimensions:
- name: D1
label: "Price"
factor: 3
desc: "Annual cost. Lower is better."
- name: D2
label: "Features"
factor: 2
desc: "Must-have feature coverage."
- name: D3
label: "Support"
factor: 1
desc: "Response time and quality."
score.tsv(compute 前,evidence 锚定事实):
target D1 D1_evidence D2 D2_evidence D3 D3_evidence
vendor-alpha 7 $12k/yr, within budget 9 Covers all 5 must-haves 6 48h avg response
vendor-beta 4 $18k/yr, over budget 7 Covers 3 of 5 must-haves 8 4h avg response
运行 python compute.py vendor.score.yml score.tsv 后输出:
target total rank D1 D1_evidence D2 D2_evidence D3 D3_evidence
vendor-alpha 7.17 1 7 $12k/yr, within budget 9 Covers all 5 must-haves 6 48h avg response
vendor-beta 5.67 2 4 $18k/yr, over budget 7 Covers 3 of 5 must-haves 8 4h avg response
可以看到:总分 0–100、按 total 降序、rank=1 最高;维度列头自动标注权重占比;证据列原样保留,推理过程透明可复盘。
六、输出列详解
| 列 | 来源 | 说明 |
|---|---|---|
target |
输入 | 候选名称 |
total |
计算 | 加权总分(0–100) |
rank |
计算 | 排名(1 = 最高)。X = 被 block 淘汰 |
block |
输入 | 可选的硬过滤列。非空 = 该候选被淘汰,排到最后,rank 显示 X |
reason |
输入/输出 | 可选:AI 标注评分的 nuance |
<维度> (X%) |
计算 | 各维度分数,列头显示权重占比 |
证据 |
输入 | 支撑每个分数的事实依据 |
reason 列还承担 agent 间传递备注的职责,block 列的淘汰机制在 compute.py 中实现:被 block 的行即使总分更高也强制沉底,但 total 仍会计算——方便"如果真的必须二选一"时的对比。
七、分数刻度
| 分数 | 标签 | 含义 |
|---|---|---|
| 9–10 | 优秀 | 完全符合维度标准 |
| 7–8 | 良好 | 符合标准,有微小差距 |
| 5–6 | 及格 | 方向正确,有明显不足 |
| 3–4 | 差 | 差距显著 |
| 1–2 | 失败 | 几乎没有达到 |
| 0 | 不适用 | 不适用 |
八、评分规则:保证分数可信
- 证据锚定 — 每个分数必须有证据。证据是事实:字母数、用户百分比、基准测试结果。"感觉不错""直观""看起来对"不是证据。
- 用全范围 — 5 是中间点,不是默认分。0 分和 10 分少见但可以给。
- 因子是相对放大器 — 基线=2。因子 4 的影响力是因子 2 的两倍。因子不需要求和。
- 目标唯一且不能为空 —
**.score.tsv第一列每行都必须有目标名,不可重复,不可为空(compute.py 检测到重复目标会直接报错退出)。 - Agent 读结果、汇报、决策 —
compute后 agent 读取排序 TSV,向用户汇报结论。如果结果有问题,agent 可以重新打分、调整因子、或增减候选。reason列用于传递 agent 间的备注信息。
值得一提的细节:agent 打分时即使某维度的值为空或非数字,compute.py 也会按 0 处理——这提醒我们,打分列务必填满,否则会静默拉低总分。
九、模板体系:35+ 个开箱即用的评分标准
template 目录收录了 35 个以上的现成模板,覆盖命名(naming-*.score.yml)、科技选型(tech-stack)、购房(house-buy)、租房对比(house-rent-vs-buy)、求职(job)、购车(car)、笔记本电脑(laptop)、宠物(pet-*)、植物(plant-*)、送礼(gift-*)、旅行(travel-*)、餐厅、电影等场景。
x score ls— 列出全部模板(首行注释中的英文描述会被解析为 desc 列)。x score init -t <name>— 复制指定模板到当前目录,作为定制起点。
为什么模板能"开箱即用"? 关键在于模板内嵌了两类 comment(格式详见 score-template-writer.md):
- 头部注释块:用"条件 → 动作"的可执行条目引导 agent 按用户实际情况调整,例如 job.score.yml 先列出该问的问题(职业阶段?行业?远程/混合/坐班?是否 relocation?),再指明 block 列用法;plant-cat.score.yml 的头部甚至给出了完整的常见调整清单(有狗?猫不碰植物?多猫?室外?新手?预算紧?)。
- 维度内联注释:标注"什么条件下该调大 factor、拆分子维度或删除维度",例如 job 模板的
ai-replaceability维度注释解释了哪些岗位 AI 替代风险高。
9.1 维度设计原则
- 5–7 个维度是甜区:少于 4 个显单薄,多于 8 个是噪音。
- 每个维度必须能区分候选:如果所有候选在某维度得分都相同,这个维度就是浪费权重。
- 避免维度重叠:"美学"和"好看"是一回事,合并。
- 具体优于抽象:"两周不浇水也能活" > "好养活"。
9.2 写出好的 desc
格式:"<该维度衡量什么>。高分锚点:<描述>;低分锚点:<描述>;0 分:<描述>。"。规则是锚定 9–10 和 1–2 的具体事实、描述可观察事实而非感受、0 分要有明确画面、控制在 200 字符以内。以 laptop.score.yml 的 performance 维度为例:
"Speed for YOUR actual workload — compile times, render speeds, multitasking, not benchmarks. 9-10: effortlessly handles everything you throw at it, zero lag; 7-8: smooth for your workflow; 5-6: adequate, occasional slowdowns; 3-4: struggles with your normal workload; 1-2: frustratingly slow; 0: can't run the software you need."
十、应用场景:从单次决策到可进化的决策资产
- 给 agent 装上决策工作流。 score.yml 是 agent 的决策锚点——不再随上下文左右摇摆。agent 按标准走:提问 → 打分 → compute → 汇报。
- 决策有规则可依。 维度 × 因子 × 证据 → 加权总分 → 排名。每个分数锚定在事实上,推理过程透明可复盘。
- 随需求灵活微调。 换维度、调因子、加硬过滤——同一个模板适配不同用户,改的是重视什么、有多重视。
- 随需求清晰而进化。 初版抛砖引玉 → 用户反馈 → refine → 重新打分 → 越来越准。
- 任何 skill 都能拥有标准文件 + 存档 + 迭代。 score.yml = 决策标准,score.tsv = 决策记录。两份文件存档后可复盘、可分享、可改进。
这种"标准 + 记录 + 迭代"的模式在仓库内部已被实践:core 库的命名模块就是通过 score 框架选出 score 这个模块名,完整的过程记录(含候选打分、misses 与 anchors)见 naming.score-module.yml——一份真实可复盘、可审计的决策存档。
十一、文件清单速览
| 文件 | 作用 |
|---|---|
| SKILL.cn.md | 中文版,自包含的评分引擎,AI 读取后即可运行完整工作流 |
| SKILL.md | 英文版 |
| compute.py | 独立 Python 校验器,python compute.py <yml> <tsv> 校验并计算 total + rank |
| template/*.score.yml | 模板文件,x score ls 列出、x score init -t <name> 复制 |
| rule-vs-score.md | Rule 与 Score 的区别——什么场景用哪个 |
| score-template-writer.md | 模板编写指南——怎么写 comment、选维度、定 factor、写 desc |
小结
x-cmd score 的核心价值不是"算得准",而是让决策过程变得可讨论、可存档、可迭代:以 score.yml 锚定标准、以 score.tsv 沉淀证据、以 compute 保证核算一致、以 assess/iter/refine 驱动迭代。无论你是想让 agent 帮你选技术栈、比offer、挑房子还是选礼物,都可以用这套框架把"感觉"翻译成"分数",再把"分数"翻译成"可复盘的理由"。