ratel-assessment

/ratel-assessment — 对合作伙伴 Agent 代码库进行前期审查

与合作伙伴初创公司的第一次交流，很少是“接入 Ratel”，而是“让我们看看你们是否了解我们的 Agent”。这项技能是前期入口：它会读取代码库，运行评估目录中的所有维度，并生成一份合作伙伴可以（也愿意）在内部分享的 Markdown 报告——无论他们最终是否使用 Ratel。

交付成果是一份精心打磨、以证据为依据的报告，路径为 <repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.md；同时还会生成一份带品牌标识、包含评分的 HTML 版本，路径为 <repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.html（含仪表盘、雷达图和各维度评分条）。报告的可信度来自每条发现都引用文件路径、行号范围或具体数量。报告的叙述脉络则来自将与 Ratel 相关的发现归入“Ratel 的适用场景”一节，并将其关联到已发布的具体功能和路线图版本。报告还会推动后续行动：结尾会根据情况指向套件中适合的后续技能（/ratel-observability-assessment、/ratel-integrate、/ratel-decompose-prompt、/ratel-tune-definitions）。

这项技能与套件中的其他技能互为补充：

• 在其他四项技能之前运行。这是唯一一项可以安全地用于尚未配置、合作伙伴也未做任何准备的全新代码库的技能。
• 引导进入套件中的其他技能。“建议的后续步骤”一节会根据发现指出适合的后续技能。
• 不重复其他技能的目录。Ratel 相关的分析角度指向 ../ratel-observability-assessment/references/ratel-value-map.md；命名参考则指向 ../ratel-observability-assessment/references/semantic-conventions.md。

理念

三条规则。违反任何一条，报告都会变成销售文案，而合作伙伴会立刻看穿。

1. 每条发现都必须引用证据。 可以是带行号范围的文件路径、数量，或代码库中的引文。含糊的说法（“建议改进可观测性”）毫无价值。具体的说法（“在 src/agents/*.ts 中注册了 47 个工具，其中没有一个的 description 超过 12 个单词”）才能促成下一次会议。如果无法引用证据，就删除这条发现。
2. 诚实地跳过，胜过捏造。 如果代码库不是 Agent，就如实说明并停止——不要编造发现。如果某个维度没有问题，就标为 Strong 并继续；不要牵强地找缺陷。合作伙伴察觉到内容空洞的速度，比察觉到内容充实更快。
3. Ratel 是发现类别，而非结论。 只有真正符合 Ratel 范畴（工具过多、检索、分解、可观测性）的发现，才会附上 Ratel 相关分析角度。不要为了充实“Ratel 的适用场景”一节而把它们硬套到每条发现上。如果只有两条发现确实与 Ratel 相关，该节就只列两条，而不是凑成八条。

工作流

步骤 1 — 检测 Agent 代码库

读取清单文件，并搜索 Agent 相关代码。客户使用的技术栈决定了工作流后续步骤要查找哪些模式。

# Manifests
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u
test -f pyproject.toml && head -200 pyproject.toml
test -f requirements.txt && cat requirements.txt
test -f uv.lock && head -50 uv.lock

# Agent surfaces — tool definitions, LLM clients, agent frameworks
grep -rEn 'tools:\s*\{|tools:\s*\[|defineTool|createTool|@tool\b|@function_tool\b|McpServer\(|StdioClientTransport|listTools|streamText|generateText|chat\.completions|messages\.create|invoke_model|graph\.add_node|Agent\(|Crew\(|@agent\b' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' \
  | head -100

使用 references/stack-detection.md 将代码库归类到相应技术栈。技术栈决定了应在哪里查找工具、提示词、子 Agent 和可观测性配置。如果完全没有检测到 Agent 相关代码，则使用诚实跳过路径。

第 2 步 — 梳理 Agent 的组成

启动一个 Explore Agent（小型代码库也可以直接梳理），并提供一个范围明确的提示词。Agent 的任务是填写清单，供评估目录进行评估。请它梳理以下内容：

1. Agent 入口点 — HTTP 处理程序、队列使用方、CLI 动词、聊天平台 Webhook。每个入口点列出一个项目，并附上文件路径。
2. 工具定义 — 声明工具的所有位置（注册表、装饰器、MCP 客户端设置）。工具总数。对每个工具，列出：id、名称、描述长度、是否包含架构，以及定义是内联还是外置。
3. 提示词模板 — 所有系统 / 用户 / 工具提示词。注明它们的位置（内联字符串、单独文件、提示词管理服务）。如果文件便于估算，也请估算其 Token 权重。另外，注明提示词是否混杂多种关注点（角色 + 工具文档 + 输出格式 + 示例 + 重复的多步骤流程 + 安全），以及是否有任何重复的指令块在多个提示词或调用点中重复出现——这会用于维度 11（提示词拆分）。
4. 子 Agent 边界 — 主管 / 工作 Agent / 特定角色 Agent；交接位置；子 Agent 是显式指定（有名称）还是隐式存在（同一循环使用不同提示词）。
5. 会话 / 上下文处理 — 对话线程 / 作业关联 id 的来源；是否有任何机制将其传递给子 Agent。
6. 模型路由 — 不同任务调用哪些模型；路由是按任务区分还是一概而论。
7. 错误处理 — 工具调用周围的 try/except 结构；是否有重试；退避；死信处理。
8. 记忆 / 检索 — 向量存储、RAG 流程、对话记忆、摘要。
9. 可观测性配置 — Ratel SDK 原生 OTLP 遥测 / Langfuse / LangSmith / OTel / OpenInference / OpenLLMetry / Helicone / 自建日志。环境变量、初始化位置。
10. 评估范围 — 评估目录、测试夹具、真实数据集、CI 调用。

请将清单保留在分析上下文中——它不是交付内容。报告会引用它，但不会包含它。

第 3 步 — 检测可观测性，并在可访问时探测后端

Ratel 的遥测基于原生 OpenTelemetry：SDK 会将检索与工具漏斗作为 gen_ai.* spans（semconv v1.42.0）以及 ratel.* 扩展（ratel.search、execute_tool <tool id>、ratel.skill.load）发出，并以标准 OTLP 导出到合作伙伴现有的任意 OTel 后端——Langfuse、LangSmith、自有 collector 或 Ratel Cloud（即将推出）。Ratel 不会发出 LLM 调用 spans；这些仍由合作伙伴自己的 LLM 埋点负责。因此，检测应保持与供应商无关：查找任何遥测入口，而非特定供应商。

两项检查：

1. 静态检查：是否存在以下任一项？Ratel SDK 原生遥测（configureTelemetry / configure_telemetry、ratelSpanProcessor / ratel_span_processor、RATEL_URL 或本地 trace= JSONL 流）；指向某处的 OTel/OTLP 导出器，且该处适用于 Agent；.env* / 示例环境文件 / docker-compose 中的 Langfuse SDK 或环境变量；LangSmith SDK；OpenInference / OpenLLMetry 埋点。
2. 实时检查（尽力而为）：如果已接入且可访问任何遥测后端——凭据齐备，且该后端的 MCP 服务已为此会话配置——尝试执行一次低成本聚合查询（例如，查询最近的 trace/service 名称在过去 24 小时内的 trace 数量）。如果返回数据，则获取少量样本（≤50 条 traces/runs），并用它来补充相关发现（工具面数量、错误率、延迟，以及——Ratel SDK 有发出数据时——检索漏斗：top_k、hit_count、top_hit_score、origin）。如果调用因任何原因失败——认证、网络、没有项目或没有 traces——则静默回退到仅静态检查。不要将失败列为发现；这不是合作伙伴的错误。

目录区分需要实时数据的发现（“未类型化工具观测”——只有 traces 才可观测）与不需要实时数据的发现（“按数量统计的工具蔓延”——可通过静态检查观测）。仅静态检查时，只需跳过需要实时数据的发现；其余部分不受影响。

第 4 步 — 执行评估

逐项检查 references/assessment-catalog.md 中的每个维度。对于每一项：

• 根据第 2 步的清单（以及第 3 步中可用的实时样本）应用检测启发式。
• 按照分级标准确定严重性：Critical / Major / Minor / Info。
• 附上证据：文件路径 + 行范围、数量或引用片段。
• 如果目录条目包含 Ratel 相关说明，则附上一行标签，指向 ../ratel-observability-assessment/references/ratel-value-map.md 中相关的 Ratel 功能/版本。

不要编造目录中没有的维度。如果发现确实新颖的内容，可在行内注明，但须在报告中将其标记为 dimension: ad-hoc，以便之后纳入目录。

第 5 步 — 为评分卡打分

十二个维度中的每一个都必须且只能对应以下一项：

• Strong — 处理得当；没有严重性高于 Info 的发现。
• Adequate — 运作正常；有一到两项 Minor 发现；没有 Major 或更严重的发现。
• Weak — 存在实质性缺口；至少有一项 Major 发现。
• Missing — 该维度缺失或无法运行；至少有一项 Critical 发现。

然后，将每个标签换算为该标签对应分段内的 0–10 分，并按照 references/assessment-catalog.md →“Numeric score”中的评分标准，计算综合总分（十二项的平均值，保留一位小数）。标签是最终依据；数字用于绘制 HTML 仪表盘、雷达图和各维度条形图——每项分数必须保持在其标签对应的分段内，以免二者不一致。

评分卡应置于报告顶部。它是合作伙伴首先看到的内容。务必准确评分；不要淡化问题。

步骤 6 — 生成报告

按照 references/report-template.md 中的结构，将报告输出到 <repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.md。添加日期戳，以便多次运行的结果可以累积，而不会相互覆盖。

按以下顺序排列章节：

1. 执行摘要 — 一段文字，然后是评分卡表格。
2. 发现，按严重程度分组（Critical → Major → Minor → Info）。每项发现包含：标题、维度、严重程度、证据、重要性、建议，以及可选的一行 Ratel 角度。
3. Ratel 的适用之处 — 将各项发现中提到的 Ratel 角度整合为一段叙述。结合价值地图中具体的 Ratel 功能／路线图版本。如果只有一两项发现提到 Ratel 角度，本节可以简短一些。
4. 建议的后续步骤 — 根据发现给出有条件的技能指引。使用项目符号列表，每条指引一行。参见下文的条件指引。

然后生成与 Markdown 配套的品牌化 HTML：

1. 组装一个 JSON 载荷，包含相同内容：partner、date、stack、scope、data_sources、overall_score、summary、十二个 dimensions（按目录顺序排列的 {name, label, score}，以及可选的各维度 why——在每个类别可展开的子维度下拉菜单中显示一行“此评分的原因”）、可选的 category_takeaways（{category name → 一行“所以呢”}映射；渲染器会将十二个维度汇总为四个评分类别——Architecture & orchestration、Context & tools、Reliability & safety、Operations——并用于雷达图分组、主视觉区域的类别迷你条和评分卡片；这是每个类别下方的高层级“改进方向”说明，应指向下方的具体发现）、findings 数组（包含 title、dimension、severity、evidence、rationale、recommendation，以及可选的 ratel_angle），以及可选的 where_ratel_fits、next_steps、appendix。完整的架构定义见 assets/sample-payload.json。内容字段可以使用行内 `code` 和 *强调*；渲染器会转换这些格式，并对其余所有内容进行 HTML 转义。

2. 将载荷写入临时文件，然后运行随附的渲染器（图表几何和色带配色均由渲染器负责——切勿手动计算 SVG）：

   python3 "<skill>/assets/render_report.py" \
     --data "<tmp>/payload.json" \
     --template "<skill>/assets/report-template.html" \
     --out "<repo>/.ratel/ratel-assessment-<YYYY-MM-DD>.html"
   

   <skill> 是此技能的目录。输出是一个独立的 HTML 文件（内含 CSS 和 SVG；字体从 Google Fonts 加载，并提供系统字体回退，因此离线时仍可阅读）。

3. 回退方案 — 如果无法使用 python3，请打开 assets/report-template.html，并直接根据同一载荷填入其中的 {{PLACEHOLDER}} 标记（完整标记列表位于 render_report.py 的文件头中）。无论采用哪种方式，都不会影响 Markdown 报告；切勿因 HTML 而阻塞流程。

步骤 7 — 行内摘要

按以下顺序在聊天中输出：

1. 综合得分（Overall: 6.6 / 10）和评分卡（或精简为一行，例如：“拓扑 强 9.0 · 工具 弱 4.6 · 可观测性 缺失 1.5 · …”）。
2. 排名前 3 的发现，每项各用一行概述。
3. 两个文件路径——.md 和 .html。
4. 建议的后续技能。

不要在聊天中粘贴完整报告正文。报告文件才是交付成果。

最后，切勿跳过这一步。 输出摘要后，明确询问是否要在读者的浏览器中打开品牌化 HTML 报告。此询问必须是聊天输出中最醒目的一行——以一两个引人注意的表情符号开头，确保读者不会错过（这是整个套件唯一有意放宽禁用表情符号规则的地方，因为渲染后的报告很容易被忽略）。用直白的措辞询问是否打开报告；只有读者回答是时，才对 .html 路径运行 open（macOS）／xdg-open（Linux）／start（Windows）。未经询问，绝不要自动打开。品牌化报告是此技能的核心——务必确保读者实际打开并查看报告，而不是只看到一个还得自己去查找的文件路径。

条件式指引

“建议的后续步骤”部分取决于评估结果。绝不要列出不适用的技能。按以下方式将评估结果对应到指引：

如果评估发现……	指向
任何 Observability 发现（Weak 或 Missing），或已具备 observability，且你想引导至后续流程	/ratel-observability-assessment
任何带有 Ratel 角度的工具表面发现	/ratel-integrate
存在分解 / 拓扑方面的 Ratel 角度发现	/ratel-integrate（并注明自动分解支持已列入路线图，即将推出）
提示词分解发现（维度为 Weak 或 Missing）	/ratel-decompose-prompt
定义质量发现（维度为 Weak 或 Missing）	/ratel-tune-definitions
以上均不符合	完全省略此部分

每条指引单独占一行：技能名称 + 本报告中它所跟进的具体发现。不要转述技能描述；合作方可以自行阅读。

语气与证据

• 使用祈使语气，面向读者。 “将工具调用封装为 type: tool 观察结果”——不要说“或许可以考虑……”
• 不使用表情符号，不使用营销形容词。 只有报告少量使用“Critical”一词时，它才有分量。
• 对严重程度不作模糊处理。 如果是 Critical，就写 Critical。如果是 Info，就不要夸大。
• 发现正文以证据为先。 第一段引用证据；第二段解释其重要性；第三段给出建议。Ratel 角度单独放在最后一行，不要穿插其中。
• 报告中不要提及时间。 避免使用“在上个迭代中”或“从今天早上开始”等表述。合作方三个月后还会重新阅读这份报告。

诚实的跳过路径

如果完成步骤 1 后，仍找不到任何大模型客户端导入、工具定义、Agent 框架或模型调用，就停止。不要撰写报告。告诉用户：

未检测到 Agent 表面——已检查 <files looked at>。如果 Agent 位于不常见的位置，请告诉我，我会重新检查。否则，此代码库不适用于 /ratel-assessment。

如果代码库属于 Agent，但目录在全部十二个维度中发现的严重程度都不高于 Info，则仍要撰写报告——评分卡会显示全部为 Strong 或几乎全部为 Strong，发现部分会较短，结论则为“此 Agent 状态良好；与 Ratel 相关的角度有 <one-or-zero items> 项。”这样的报告本身就能建立可信度；不要为了凑内容而扩充。

参考文件

• references/assessment-catalog.md — 十二个维度、检测启发式规则、严重性标准、建议和 Ratel 的切入点。这是核心文件。
• references/stack-detection.md — 用于识别 Agent 技术栈的快速指南；链接到 /ratel-observability-assessment 中针对各技术栈的详细内容，以便深入分析。
• references/report-template.md — 标准报告结构和一个完整示例。

随附资源（HTML 交付物）：

• assets/report-template.html — 独立的 HTML 模板，忠实呈现品牌风格，并包含 {{PLACEHOLDER}} 占位符（Ratel 配色、仪表盘／雷达图／评分条区域、打印样式表）。
• assets/render_report.py — 纯标准库渲染器：计算图表几何数据、填充占位符并生成 .html 文件。
• assets/sample-payload.json — 完整示例的负载文件；也可用作 JSON 模式参考和渲染测试样例。

读取以下文件（不复制）：

• ../ratel-observability-assessment/references/semantic-conventions.md — 通用的供应商无关 span／session／tag／attribute 词汇表
• ../ratel-observability-assessment/references/ratel-value-map.md — Ratel 功能 → 可观测信号 → 版本的唯一事实来源

向合作伙伴介绍 Ratel 自有文档时，请使用 docs.ratel.sh — 工具检索概念见 https://docs.ratel.sh/docs/core/tool-retrieval，原生遥测指南见 https://docs.ratel.sh/docs/core/telemetry。