claw-score

claw-score

在本仓库中处理 OpenClaw 成熟度评分卡时，请使用此技能。 这是维护者 claw-score 工作流的 openclaw-local 版本： 它保留分类体系和评分卡概念，但排除 discrawl 和旧的 已提交 inventory/ 报告树。

管理范围

本技能负责以下项目的操作工作流：

• taxonomy.yaml
• qa/maturity-scores.yaml
• docs/concepts/qa-e2e-automation.md
• qa/scenarios/index.yaml

不要将人员特定信息、维护者私有信息、Discord 归档和 discrawl 相关事实 放入此仓库。如果评分需要私有证据，请使用由 OpenClaw QA 工作流生成的 已脱敏 qa-evidence.json 产物结构。

源模型

• taxonomy.yaml 是手动编辑的事实来源，涵盖功能面、级别、 QA 配置、类别、功能覆盖 ID、文档引用、LTS 覆盖项和 完整性说明路径。
• 每个功能恰好有一个 coverageIds 条目。确保该证据 ID 对此功能唯一；范围更广的多对多证据映射不属于 当前分类体系模式。
• 覆盖 ID 使用点分隔的 namespace.behavior 形式，各段由小写字母、 数字或连字符组成。配置、功能面和类别 ID 可以继续 使用连字符或点分隔形式。
• 类别和功能名称应保持唯一、以产品为导向，且范围比原始 覆盖 ID 更广。不要将通用 ID 提升为独立的功能名称。
• 避免在同一类别下使用不同的功能名称重复同一组 覆盖 ID。
• qa/maturity-scores.yaml 是已提交的质量、完整性和 LTS 审查状态的汇总事实来源。
• extensions/qa-lab/src/scorecard-taxonomy.ts 导出 readValidatedQaMaturityScoreSources；使用它来验证评分输出。
• 生成的公开文档是 docs/maturity/scorecard.md 和 docs/maturity/taxonomy.md，两者均由 pnpm maturity:render 生成。不要手动编辑生成的 Markdown 来更改评分结果。
• qa-evidence.json 产物提供每次运行的 QA 评分卡证据。发布配置产物是覆盖情况的 事实来源。它们可以为生成的产物文档补充信息，但不会作为清单提交。

命令

在 openclaw 仓库根目录运行。

编辑源文件后，验证分类体系 YAML 结构和成熟度评分模式：

node --import tsx --input-type=module <<'NODE'
import fs from "node:fs";
import YAML from "yaml";
import { readValidatedQaMaturityScoreSources } from "./extensions/qa-lab/src/scorecard-taxonomy.ts";

for (const file of ["taxonomy.yaml", "qa/scenarios/index.yaml"]) {
  YAML.parse(fs.readFileSync(file, "utf8"));
}
readValidatedQaMaturityScoreSources();
NODE

修改文档文案时检查文档：

pnpm check:docs

更改覆盖 ID 或配置成员关系时，运行聚焦的 QA／配置检查：

pnpm openclaw qa coverage --json

全量生成运行

对于直接运行完整评分卡并发布生成文档拉取请求的流程， 默认使用浮动式 main 解析：

gh workflow run maturity-scorecard.yml \
  --repo openclaw/openclaw \
  --ref main \
  -f ref=main \
  -f expected_sha='' \
  -f publish_pull_request=true \
  -f allow_failures=true

不要在本地解析 main，也不要在常规手动生成运行中，将选定提交同时作为 ref 和 expected_sha 传入。OpenClaw 的 main 分支变化 很快，因此调用方选定的提交可能在验证前过时。如果拉取请求的基础分支包含 更新的成熟度输入，工作流会正确拒绝发布，QA 也就不会启动。

当 ref=main 且 expected_sha 为空时，工作流的 floating_default_branch 路径会在验证期间获取并冻结当前远程默认 分支，然后向下游作业传递不可变修订版本。仅当所请求的证据必须绑定到 该确切修订版本时，才使用显式 SHA，例如发布候选工作流调用或 仅针对产物的历史复现。如果该确切修订版本的运行还请求发布，而 main 已发生相关输入变更，则验证将会失败，此时应改为从浮动的 main 重新 调度。

评分工作流

当需要为某个表面评分或刷新评分时：

1. 阅读 taxonomy.yaml 中的表面定义。
2. 阅读 .agents/skills/claw-score/references/completeness/ 下的表面完整度评分标准。
3. 从文档、源代码、测试和 QA 场景元数据中收集公开仓库证据。
4. 对于已执行的验证，优先采用现有发布配置中的 qa-evidence.json 产物。
5. 仅在有公开证据或脱敏产物证据支持时，更新 qa/maturity-scores.yaml 中的 Quality、Completeness 和 LTS 审核状态。
6. 运行此技能提供的架构验证命令。
7. 如果文档正文有变更，运行 pnpm check:docs；如果覆盖 ID 或配置文件成员有变更，运行有针对性的 QA 覆盖检查。

对于主观评分的变更，应做出最小且有依据的调整，并在 PR 或任务摘要中注明证据路径。将手动撰写的说明保留在当前文档中，并将评分数据保留在 qa/maturity-scores.yaml 中。

默认完整度流程

完整度评分依据各类别预期的、用户可见的操作工作流，而非测试广度或实现质量。references/completeness/ 下的完整度参考文件定义了各类别的范围，以及特定表面相较于此默认流程的任何差异。

默认情况下，完整度衡量 OpenClaw 在多大程度上向该表面对应的用户、操作员、作者或维护者角色提供了预期的表面能力集合。评估每个类别是否提供了完整的预期工作流，包括设置、常规使用、状态查看或检查、恢复，以及适用时重要的平台、提供方、渠道、安全性或生命周期变体。

将 Surface-Specific Scoring Questions 和 Surface-Specific Guidance 视为该表面的优先级更高的指引。表面专属指引可以细化、缩小或有意与此处的默认理念相冲突；遇到这种情况时，应遵循表面专属指引，并确保评分理由反映该指引。如果参考文件不包含表面专属问题或指引，则对该表面的 Category Scope 应用此默认流程。

对于每个类别，请询问：

• 预期用户或操作员能否端到端完成该类别的工作流？
• 分类体系中的功能是否作为受支持的能力提供，而非孤立的实现片段？
• 是否涵盖了重要的生命周期阶段：设置、常规运行、状态查看／检查、恢复，以及相关的升级或移除？
• 是否涵盖了该表面所涉及的重要环境、提供方、平台、渠道或安全性分支？
• 已知缺口是否导致重要的用户可见能力分支缺失？

默认指引：

• 如果类别支持分类体系和类别证据所描述的完整用户可见操作工作流，应倾向于给出较高的完整度评分。
• 如果只有理想路径可用、重要变体未记录或未实现，或缺少恢复／状态查看路径，应降低完整度评分。
• 不要因为测试不足而降低完整度；这属于覆盖率。
• 不要因为实现质量脆弱而降低完整度；这属于质量。

默认完整度等级：

• Clawesome（95-100）：涵盖预期工作流、变体和恢复分支，仅存在轻微的完善空间。
• Stable（80-95）：预期工作流整体已具备，仅缺少有限的分支。
• Beta（70-80）：主要工作流已具备，但仍缺少有实质意义的分支或恢复路径。
• Alpha（50-70）：仅具备部分能力；用户可以完成一些核心任务，但无法完成全部预期工作流。
• Experimental（0-50）：该类别仅提供预期能力的零散片段。

决策背景

在表面和类别的 Quality/Completeness 旁边，或在类别 LTS 的 supported 旁边，记录可选的 decision。在 taxonomy.yaml 中，在规范表面 level 旁边使用可选的 level_decision。

每条记录包含 value、rationale、reviewer、evidence_refs 和 revalidate_when。Quality/Completeness 使用 0–100 的整数，LTS 使用布尔值，level_decision 使用已声明的 taxonomy 级别 ID。文本字段不能为空，且至少提供一条证据引用。填写实际审阅者，以及应触发再次审阅的条件。

无法获取的历史记录应保持缺失：这表示未知，而不是邀请你编造审阅者、理由或证据。记录不会覆盖当前分数、支持标记或规范级别。如果其值不同，则保留两者；生成的文档会显示非门控的不一致，包括严格输入验证下也如此。

不要为 Coverage、计算得出的汇总值、表面 LTS 摘要或分数汇总中复制的级别添加决策背景。决策背景不会改变覆盖率标识、分数计算、支持承诺或发布门槛。

分数语义

• Coverage：确定性的发布验证覆盖率，根据发布配置文件 qa-evidence.json.scorecard 的功能满足情况数据得出。
• Quality：该类别的可靠性、可维护性、操作安全性和回归信心。
• Completeness：该类别中预期的、对操作人员可见的工作流已实现的程度。更改此分数前，请使用默认完整性流程以及任何表面特定的差异。
• LTS：根据 Quality、发布证据 Coverage 和 human_lts_override 得出；不要手动编辑生成的 Markdown 来更改 LTS 状态。

级别：

• Clawesome：95-100
• Stable：80-95
• Beta：70-80
• Alpha：50-70
• Experimental：0-50

产物

不要将维护者仓库中的 docs/kevinslin/maturity-scorecard/inventory/ 目录树添加到 openclaw。包含证据的评分卡输出应放在短期产物中，而不是已提交的生成文档中，除非此仓库先添加明确的渲染器/检查工作流。