assess

评估

与宿主无关的工作流。使用技能名称（assess）调用。Claude Code 斜杠路由、YAML 钩子加载器和 .claude/chain 见 references/claude-code.md。

全面的评估技能，用于回答“这好吗？”并提供结构化评估、评分和可执行的建议。

🎯 快速开始

assess backend/app/services/auth.py
assess our caching strategy
assess --model=opus the current database schema
assess frontend/src/components/Dashboard

工作量级别（CC 2.1.111+ 新增 xhigh）

工作量	行为
low / medium	评估部分维度，更快完成
high（默认）	评估全部六个维度，并提供优缺点
xhigh	评估全部六个维度 + 额外进行一轮评估，重点关注不确定性和注意事项；为每个维度输出 confidence

对于不支持 xhigh 的模型，该级别会静默回退到 high：不会报错，也不会写入日志。doctor 第 14 类会报告此情况，但仅当能够确切确认当前模型不支持该级别时才会报告。

---

参数解析

步骤 0：先解析代词指向的目标

$ARGUMENTS 通常不是路径。加载 Read("../../shared/rules/target-resolution.md") 并遵循其中的内联部分：如果目标是单独出现的代词或指示语（them、this、the above）， 或目标为空，则根据对话内容将其回指到最近的具体对象，用一行说明后进行评估。 只有在对话为空时才提问。

TARGET = "$ARGUMENTS"  # Full argument string, e.g., "backend/app/services/auth.py"
# $ARGUMENTS[0] is the first token (CC 2.1.59 indexed access)

# Model override detection (CC 2.1.72)
MODEL_OVERRIDE = None
for token in "$ARGUMENTS".split():
    if token.startswith("--model="):
        MODEL_OVERRIDE = token.split("=", 1)[1]  # "opus", "sonnet", "haiku", "fable"
        TARGET = TARGET.replace(token, "").strip()

如果设置了 MODEL_OVERRIDE，则通过 model=MODEL_OVERRIDE 将其传递给所有 Agent() 调用。可接受符号名称（opus、sonnet、haiku，以及 Agent 工具列表中包含 fable 的运行环境；请注意，2026-07-12 之后，fable 会产生高级 API 费用）或完整 ID（claude-opus-5-5），具体取决于 CC 2.1.74。

通过 /model 切换到 Opus（CC 2.1.144+）： /model 现在只会更改当前会话的模型，因此在评估过程中选择 Opus 不会再影响后续会话。仅当要为新会话设置默认模型时，才在选择器中按 d。

工作量检测（CC 2.1.120+）

$CLAUDE_EFFORT 是主要信号。CC 2.1.120 会根据 /effort 或模型选择器设置此环境变量。$ARGUMENTS 中的 --effort= 标记是显式覆盖的备用方式（也兼容较旧版本的 CC）。

# Read env first (CC 2.1.120+), then check explicit override
EFFORT = os.environ.get("CLAUDE_EFFORT")  # "low" | "medium" | "high" | "xhigh" | None
for token in "$ARGUMENTS".split():
    if token.startswith("--effort="):
        EFFORT = token.split("=", 1)[1]   # explicit override wins
        TARGET = TARGET.replace(token, "").strip()
EFFORT = EFFORT or "high"  # default when CC < 2.1.120 and no flag

使用 EFFORT 控制维度数量、Agent 数量以及可选的 xhigh 不确定性评估轮次——见上方“工作量级别”表。在 CC < 2.1.120 中，环境变量未设置；唯一可用的方式是显式使用 --effort= 覆盖。doctor 第 14 类会报告可确切确认不受支持的 xhigh 请求。

---

步骤 -1：MCP 探测 + 恢复检查

加载：Read("../chain-patterns/references/mcp-detection.md")

# 1. Probe MCP servers (once at skill start)
# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")

# 2. Store capabilities
Write(".claude/chain/capabilities.json", {
  "memory": probe_memory.found,
  "skill": "assess",
  "timestamp": now()
})

# 3. Check for resume
state = Read(".claude/chain/state.json")  # may not exist
if state.skill == "assess" and state.status == "in_progress":
    last_handoff = Read(f".claude/chain/{state.last_handoff}")

阶段交接

阶段	交接文件	内容
0	00-intent.json	维度、目标、模式
1	01-baseline.json	初始代码库扫描结果
2	02-evaluation.json	各维度评分 + 证据
3	03-report.json	最终报告、等级、建议

---

步骤 0：使用 AskUserQuestion 确认用户意图

创建任务之前，先明确评估维度：

AskUserQuestion(
  questions=[{
    "question": "What dimensions to assess?",
    "header": "Dimensions",
    "options": [
      {"label": "Full assessment (Recommended)", "description": "All dimensions: quality, maintainability, security, performance"},
      {"label": "Code quality only", "description": "Readability, complexity, best practices"},
      {"label": "Security focus", "description": "Vulnerabilities, attack surface, compliance"},
      {"label": "Quick score", "description": "Just give me a 0-10 score with brief notes"}
    ],
    "multiSelect": false
  }]
)

根据回答调整工作流（作为 focus 传递到阶段 2）：

• 全面评估（full）：运行全部 7 个阶段，使用并行 Agent，按工作量级别调整维度子集
• 仅代码质量（quality）：跳过安全和性能阶段
• 安全重点（security）：优先使用安全审计 Agent
• 快速评分（quick）：使用相同的 Workflow 调用并设置 focus: quick；执行器运行一个评估器并输出简要结果

---

步骤 0b：选择编排模式

加载详细信息：Read("references/orchestration-mode.md")，了解环境变量检查逻辑、Agent Teams 与 Agent Tool 的比较，以及模式选择规则。

---

🚨 任务管理（CC 2.1.16）

# 1. Create main task IMMEDIATELY
TaskCreate(
  subject="Assess: {target}",
  description="Comprehensive evaluation with quality scores and recommendations",
  activeForm="Assessing {target}"
)

# 2. Create subtasks for each assessment phase
TaskCreate(subject="Understand target and gather context", activeForm="Understanding target")   # id=2
TaskCreate(subject="Discover scope and build file list", activeForm="Discovering scope")        # id=3
TaskCreate(subject="Rate quality across 6 dimensions", activeForm="Rating quality")             # id=4
TaskCreate(subject="Analyze pros and cons", activeForm="Analyzing pros/cons")                   # id=5
TaskCreate(subject="Compare alternatives", activeForm="Comparing alternatives")                 # id=6
TaskCreate(subject="Generate improvement suggestions", activeForm="Generating suggestions")     # id=7
TaskCreate(subject="Compile assessment report", activeForm="Compiling report")                  # id=8

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Scope needs target understanding
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Rating needs scoped file list
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Pros/cons needs quality scores
TaskUpdate(taskId="6", addBlockedBy=["4"])  # Alternatives need quality scores
TaskUpdate(taskId="7", addBlockedBy=["5", "6"])  # Suggestions need analysis
TaskUpdate(taskId="8", addBlockedBy=["7"])  # Report needs suggestions

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

---

🔄 工作流概览

阶段	活动	输出
1. 目标理解	阅读代码/设计，确定范围	上下文摘要
1.5. 范围发现	建立有界文件列表	范围内文件列表
2. 质量评级	6 维度评分（0-10）	分数及理由
3. 优缺点分析	优势与不足	平衡评估
4. 替代方案比较	为替代方案评分	比较矩阵
5. 改进建议	可执行的建议	优先级列表
6. 工作量估算	时间和复杂度估算	工作量明细
7. 评估报告	汇总发现	最终报告

---

阶段 1：目标理解

确定评估对象并收集上下文。此处的 TARGET 是步骤 0 已解析出的值，不一定是用户输入的内容。

# PARALLEL - Gather context
Read(file_path=TARGET)                                   # only when TARGET is a path
Grep(pattern=TARGET, output_mode="files_with_matches")   # topic or symbol
mcp__memory__search_nodes(query=TARGET)                  # past decisions

Read 失败不是停止的理由。根据对话解析出的目标通常是一个主题，而不是文件名（例如“那三个 pretool guard”“今天的 hook 修复”），因此读取会失败，而 Grep 和对话内容则承载着上下文。将读取失败视为“这是一个主题，而不是路径”，然后继续进入阶段 1.5；该阶段无论如何都会发现实际文件列表。

---

阶段 1.5：范围发现

加载 Read("references/scope-discovery.md")，了解完整的文件发现流程、限制应用（最多 30 个文件）和抽样优先级逻辑。每个 Agent 提示词中都必须包含范围内文件列表。

渐进式输出（CC 2.1.76）

每完成一个评估阶段，就逐步输出结果：

阶段结束后	向用户展示
1. 目标理解	范围摘要、文件列表、上下文
1.5. 范围发现	有界文件列表（最多 30 个文件）
2. 质量评级	评估 Agent 返回时，展示各维度的分数
3. 优缺点	平衡评估摘要

阶段 2 工作流只返回一次，因此要展示其结果中的每个维度分数，并优先列出 priorityConcerns（任何低于 4/10 的维度），作为需要用户关注的问题。仅在回退到 Agent 工具时，才适用逐 Agent 流式输出。

---

阶段 2：质量评级（6 个维度）

为每个维度评定 0-10 分，并计算加权综合分数。加载 Read("../quality-gates/references/unified-scoring-framework.md")，了解维度、权重、等级解读和各维度标准。加载 Read("references/quality-model.md")，了解评估专用的覆盖规则。

不要手动编写评估器。运行执行器，由它负责阶段 2 和阶段 2.5：

result = Workflow(
  scriptPath="${CLAUDE_SKILL_DIR}/workflows/assess-fanout.js",
  args={"target": TARGET, "effort": EFFORT, "focus": FOCUS,   # FOCUS from STEP 0
        "mode": "comparison" if COMPARING else "default",     # quality-model.md
        "domain": "frontend" or "backend",                     # picks the performance engineer
        "scopeFiles": SCOPE_FILES,                             # Phase 1.5 list
        "projectContext": MEMORY_CONTEXT,                      # Phase 1 memory search
        "rubric": Read("rubric.json"), "modelOverride": MODEL_OVERRIDE,
        "feature": FEATURE})
Write(".claude/chain/02-evaluation.json", result)

脚本负责执行机制，而不是撰写文字。 它根据 focus 和 effort 选择评估器（优先考虑安全性），为每个评估器提供要求给出 file:line 证据的评分架构，将每个影响决策的分数发送给盲审复核者（阶段 2.5），并计算加权综合分数、等级、评分标准结论和阻塞项。没有 file:line 证据的分数将视为未评分；重复的维度只保留第一次记录；如果某个选定维度带有 min_blocker，但无人为其评分，则该维度会成为阻塞项。它会返回 composite、grade、verdict、blockers（生成方依据）、postRefutation、chainVerdict、chainVerdictIfConfirmed、revisions、confirmationNeeded、manualReview、advisory、priorityConcerns、quickWins、unscored、rejectedDimensions、unassessed、dimensions、ledger 和 reasons。它既不会提问，也不会写入：这些工作仍由当前 shell 负责。

回退方式（没有 Workflow 工具、设置了 ORCHESTKIT_FORCE_TASK_TOOL=1，或使用下文的跨模型通道）：读取 Read("references/agent-spawn-definitions.md")，了解 Agent 工具和 Agent Teams 的启动方式，然后手动运行阶段 2.5。

扇出规则： 当所选 focus 会运行阶段 2 时，单次执行绝不能作为回退方案。阶段 2 必须通过 Workflow 调用或 Agent 工具回退来运行；如果两者都没有启动评估器，则以 BLOCKED 状态结束此次运行，并说明原因。

综合分数： 已评分维度的加权平均值（参见 quality-model.md）。

---

Phase 2.5：对抗式反驳（按投入程度启用）

为某个维度评分的评估者也是该维度唯一的评判者，这会导致自我偏袒。单独的盲审反驳者会为每个影响决策的评分独立确定一个档位。投入门槛：low/medium 跳过；high 最多运行 4 个单独的建议型反驳者（不会自动调整评分）；xhigh 运行 3 个反驳者进行多数表决，并将评分调整到相邻档位的边界。在 Workflow 路径中，脚本已运行此流程；shell 需要完成以下步骤：

1. 将返回的 ledger 写入 .claude/chain/02b-refutation.json（引擎第 10 节）。
2. 重新打开 revisions 中引用的每个 file:line（引擎第 3 节）。若引用不成立，则将该维度恢复为其产出者评分；使用返回的 weights 重新计算综合评分。
3. 如果 confirmationNeeded 不为空，则在使用 chainVerdictIfConfirmed 前调用 AskUserQuestion；否则使用 chainVerdict。反驳本身绝不会提高评分，也不会将失败改判为通过（引擎第 7 节）。
4. 将 manualReview 中的维度列为“未经过独立反驳”，并在高投入程度下列出所有建议性改判。

协议和评估绑定：Read("references/adversarial-refutation.md")（加载共享引擎 ../../shared/rules/adversarial-refutation.md）。产出者的发现必须先通过证据重放门槛，才能用于任何评分或判定：Read("../../shared/rules/evidence-replay.md")。

跨模型反驳者（可选，标注来源，按成本门槛启用）

配置了 ORK_ALT_MODEL_CMD 且投入程度为 high/xhigh 时，每个高权重或接近边界的维度评分可将一个法定名额路由给非 Claude 模型（Codex/GPT），以覆盖多样的失效模式。默认关闭；会替换一个同模型名额，以 refuter_model 标记来源，不能在无提示的情况下提高评分（引擎 §7），不持有凭据/不负责外部访问（通过 ORK_ALT_MODEL_CMD 调用 shell，符合外部访问防护 #2533）；若未配置命令，则退化为使用同模型。与 review-pr 的操作文档共用：Read("../review-pr/references/cross-model-refuter.md")。

Workflow 不会运行此流程（脚本无法调用 shell）。用户需要时，应在 Phase 2 之前选择 Agent 工具备用方案，并在那里运行 Phase 2 和 2.5。

反驳者始终以隔离的方式启动，不设置 team_name，且只接收维度信息和限定范围内的文件：不接收产出者的评分、身份或文字说明。保留基于产出者的评分，并保留标明为反驳后评分的结果。

---

Phases 3-7：分析、比较与报告

加载 Read("references/phase-templates.md")，以获取优缺点、替代方案、改进项、投入程度和最终报告的输出模板。

另请参阅：Read("references/alternative-analysis.md") | Read("references/improvement-prioritization.md")

---

阶段 7b：生成仪表板规范（json-render）

从 $ARGUMENTS 解析 --render=。默认值为 both。

模式	行为
markdown	当前行为 — 仅生成 Markdown 评估报告。不生成规范。
json-render	仅生成 .claude/chain/assess-dashboard.json。跳过 Markdown 报告。
both	生成规范和 Markdown。默认值 — 人类阅读报告，下游技能解析规范。

生成规范时：

1. 加载格式和目录：Read("references/dashboard-spec.md")。示例：references/dashboard-example.json。
2. 仅使用目录中的类型构建规范：Card、StatGrid、DataTable、StatusBadge、BarMeter、Markdown。对于评估规范，顶层字段 composite（数字）和 grade（字符串）为必填项。
3. 每个评分维度对应一个 BarMeter。verdict 元素是一个 StatusBadge，其状态根据等级映射为 success/warning/error（A/B → success，C → warning，D/F → error）。
4. 使用精简 JSON 写入 .claude/chain/assess-dashboard.json。
5. 声明成功前进行验证：

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/assess-dashboard.json --check

如果验证失败，则回退到仅生成 Markdown，并显示错误。绝不写入不完整的规范。

6. 对于 --render=both，从规范渲染 Markdown 视图：

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/assess-dashboard.json

这样可确保 JSON 规范和 Markdown 报告保持同步。

**xhigh 工作量：**当 effort=xhigh 生效时，为每个维度添加一个并列的 Markdown 元素，其中包含不确定性分析中的 confidence 和 caveats。在 dimensions Card 的子项中，连同 BarMeter 一起引用它。具体模式请参阅 references/dashboard-spec.md。

下游使用：implement 会读取 .claude/chain/assess-dashboard.json，提取得分最低的维度和高优先级改进项（effort ≤ 2 且 impact ≥ 4），而无需解析 Markdown 表格。实测：评估规范约为 830 个 token，同样内容的 Markdown 约为 3500 个 token。

---

阶段 7c：记忆回写（信号触发，可选）

评估得出综合评分后，可选择将评分和摘要作为类型化实体持久化到 memory MCP 知识图谱中。未来的 memory 查询便可呈现评估沿革（例如，这个代码库在哪些测试性决策上得了 9/10？安全性何时跌破了 7.0？）。

python3 ${CLAUDE_SKILL_DIR}/scripts/memory_writeback.py "<assessment-dir>"

<assessment-dir> 是包含 assessment.json 的目录（通常是会话的 .claude/chain/）。脚本会在其旁边写入 memory-writeback.json 交接文件。

自动跳过条件（均以 0 退出，且均记录 WARN 日志）：

跳过原因	触发条件
no composite score	assessment.json 没有顶层数值字段 composite
yg-mcp-core not importable	未安装 yg-mcp-core>=0.3.0（orchestkit 是公开的；yg-mcp-core 位于私有源 pypi.yonyon.ai — 仅限总部）
memory MCP unreachable	memory MCP 服务已关闭，或 .mcp.json 未定义 memory

创建的实体包含：

• name：<slug-or-dir>@<timestamp>（在重复运行间保持稳定 — 重复运行会创建新实体）
• entityType：assessment（使用 --entity-type <type> 覆盖）
• observations：composite=X.XX、每个评分维度对应一项 <dim>=X.XX，以及可选的 summary: ... 和 topic: ...

此模式参考了 Yonatan-HQ/hq-ext-plugin#194（audio_podcast handler）和 orchestkit#1886（post-synthesis podcast）。由 Yonatan-HQ/core#993（yg-mcp-core 0.3.0）解除阻塞。

---

阶段 7d：生成链路判定（停止门控）

在综合得分和等级确定后（反驳之后，阶段 2.5），始终写入机器可读的判定结果：这是 implement 在阶段 1 之前读取的停止门。对于 Workflow 路径，它是返回的 chainVerdict（或在阶段 2.5 中回答“是”之后的 chainVerdictIfConfirmed）。遵循阶段 7b 的规范生成模式：写入紧凑 JSON，绝不写入不完整文件。

// .claude/chain/assess-verdict.json
{
  "rubric": "ork-rubric/1.0",
  "skill": "assess",
  "verdict": "fail",
  "composite": 5.1,
  "dimension_scores": {"correctness": 7.0, "maintainability": 6.5, "performance": 5.5, "security": 3.2, "scalability": 6.0, "testability": 4.8, "compliance": 6.2},
  "blockers": [
    {"dimension": "security", "score": 3.2, "reason": "Unparameterized SQL in auth path (src/api/auth.ts:42)"}
  ],
  "feature": "<assessment topic, e.g. first non-flag token of $ARGUMENTS>"
}

判定规则——阈值来自 rubric.json（架构：../../shared/rubric.schema.json）：

• 当 composite < min_pass（5.5）或任一维度得分低于其 min_blocker 时，verdict = "fail"。否则为 "pass"。
• 每个得分低于其 min_blocker 的维度都要在 blockers[] 中添加一项——包括维度、得分和一条有证据支持的原因。通过时，blockers 为 []。
• 使用反驳后的得分——与报告中的得分相同。反驳绝不会悄悄将失败改为通过。

使用方：implement 的步骤 -0.5 会在 verdict == "fail" 时阻止阶段 1（用户必须先修复，或明确覆盖）；阶段 7c 的记忆回写会将判定结果和维度得分持久化到记忆图（添加 verdict=pass|fail 观察记录），以供跨会话学习。

---

自报告不确定性（xhigh 工作强度）

当前一代模型比旧一代模型更能准确报告自身局限。当启用 xhigh 工作强度时，为每个维度的评级补充 confidence 置信度等级和 caveats 列表——记录模型无法验证的事项、依赖的假设或未测试的情况。

每个维度的输出架构（JSON）：

{
  "dimension": "security",
  "score": 7.2,
  "confidence": "medium",              // "low" | "medium" | "high"
  "caveats": [
    "Didn't execute the SQL queries against a real DB to confirm parameterization",
    "Assumed NODE_ENV=production in deployment; didn't verify CI config",
    "Reviewed 12 of 15 handlers; remaining 3 deferred by scope filter"
  ],
  "evidence": ["src/api/auth.ts:42", "src/middleware/guard.ts:88"]
}

规则：

• 不要将 confidence 用作自动门控条件。 它是供人类读者参考的信号，而不是通过/失败阈值。
• caveats 必须具体。 “未检查 X”，并注明文件路径，比“对安全性不确定”更好。
• 如果某条注意事项可以轻松解决，就直接解决，而不是记录下来。注意事项适用于确实无法在技能范围内验证的事项（例如生产环境中的运行时行为、未来的输入模式）。
• 综合得分仍只根据 score 计算——不按置信度加权，以保持不同运行结果之间的可比性。

---

💡 等级解读

加载 Read("../quality-gates/references/unified-scoring-framework.md")，了解等级阈值和评分标准。

---

关键决策

决策	选择	理由
6 个维度	全面覆盖	涵盖所有质量方面，又不会令人应接不暇
0-10 分制	行业标准	易于理解和比较
并行评估	workflows/assess-fanout.js，最多 4 名评估者	得分、反驳和判定结果保存在代码中，而非散文中
工作量/影响评分	1-5 分制	优先级计算简单

---

规则速查

规则	影响	涵盖内容
complexity-metrics（加载 rules/complexity-metrics.md）	高	7 项标准评分（1-5）、复杂度级别、阈值
complexity-breakdown（加载 rules/complexity-breakdown.md）	高	任务分解策略、风险评估

质量标准

满足以下所有条件即为完成：

• 对范围内的每个维度按 0-10 分评分，并以证据（文件:行号）支撑得分，而非凭感觉
• 综合得分为已评分维度的加权平均值，等级根据该综合得分确定
• 在 high/xhigh 工作强度下，作为决策依据的得分在纳入综合得分前通过对抗性反驳流程
• 已写入 .claude/chain/assess-verdict.json，包含 pass/fail 判定结果，并为每个低于其 min_blocker 的维度添加 blockers[] 条目
• 任何低于 4/10 的维度得分都立即标记为优先关注事项
• 如果生成了 json-render 规范，则该规范通过 render-spec.mjs --check，并包含必需的综合得分和等级字段

📜 相关技能

• ork:verify - 实施后的验证
• ork:code-review-playbook - 代码审查模式
• ork:quality-gates - 任务复杂度评估、关卡模式

---

版本： 1.9.0（2026 年 9 月）：阶段 2 和 2.5 通过工作流脚本（workflows/assess-fanout.js）运行