x-cmd score:加权维度评分框架,给 AI Agent 装上可迭代的决策工作流

原创2026-10-13 12:47:501,612 阅读
文章标签:CLI开发工具人工智能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

三条使用纪律贯穿始终:

  1. 先问够,再定标准。 维度搞错了,分数再精确也没用。写 score.yml 之前,先向用户问清楚"选一个 X 时,你最在意什么"。
  2. 抛砖引玉,迭代优于空想。 需求不清楚时,先做一版出来,打分排名给用户看。用户对具体排名有天然反应——"这个权重不对""你漏了 XX"。用 x score refine 调整后重新打分,一轮迭代比十轮空想更高效。
  3. 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,明确注释"这是硬指标——用户有猫时不可降低此因子"。

五、完整实战:宣传口号方案决策

原文档以"协助用户决策宣传口号"为例,完整走一遍流程:

  1. 先与用户商量,得出评价维度与标准,生成 宣传口号.score.yml。
  2. 决策:
    • 如果有 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。
  3. 读取结果,与用户讨论。可调整步骤或者增加候选后重复步骤 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 不适用 不适用

八、评分规则:保证分数可信

  1. 证据锚定 — 每个分数必须有证据。证据是事实:字母数、用户百分比、基准测试结果。"感觉不错""直观""看起来对"不是证据。
  2. 用全范围 — 5 是中间点,不是默认分。0 分和 10 分少见但可以给。
  3. 因子是相对放大器 — 基线=2。因子 4 的影响力是因子 2 的两倍。因子不需要求和。
  4. 目标唯一且不能为空 — **.score.tsv 第一列每行都必须有目标名,不可重复,不可为空(compute.py 检测到重复目标会直接报错退出)。
  5. 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."

十、应用场景:从单次决策到可进化的决策资产

  1. 给 agent 装上决策工作流。 score.yml 是 agent 的决策锚点——不再随上下文左右摇摆。agent 按标准走:提问 → 打分 → compute → 汇报。
  2. 决策有规则可依。 维度 × 因子 × 证据 → 加权总分 → 排名。每个分数锚定在事实上,推理过程透明可复盘。
  3. 随需求灵活微调。 换维度、调因子、加硬过滤——同一个模板适配不同用户,改的是重视什么、有多重视。
  4. 随需求清晰而进化。 初版抛砖引玉 → 用户反馈 → refine → 重新打分 → 越来越准。
  5. 任何 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、挑房子还是选礼物,都可以用这套框架把"感觉"翻译成"分数",再把"分数"翻译成"可复盘的理由"。

登录后查看全文
x-cmd