ratel-tune-definitions

/ratel-tune-definitions — 让工具和技能定义更易检索和使用

Ratel 根据工具和技能的定义来检索它们：词法（BM25）索引会优先匹配描述性名称、参数名称、枚举值和精确触发词；在语义／混合模式下，语义索引则会匹配描述的含义。随后，模型会决定调用排名前 K 的结果中的哪些工具。这两个步骤都会受到糟糕定义的影响：描述含糊的定义无法在任何一种索引中脱颖而出；内容冗长的定义会淹没相邻结果；两个近乎重复的工具会分散模型的判断信心；宽松的模式则会让模型错误调用工具。此技能会逐条定义地手动调整这些问题，并提供具体的修改前后示例。

交付内容是一份位于 <repo>/.ratel/ratel-tune-definitions.md 的 Markdown 计划，其中包含逐条定义的修改前后对照表和按优先级排列的修复清单。客户可以据此实施；此技能不会直接修改其工具或技能代码。

这是 /ratel-assessment 中“定义质量”维度所指向的修复方案。它与以下技能配合使用：

• /ratel-decompose-prompt — 该技能从提示词中提取技能；此技能则优化这些技能的 description 和 tags，让它们真正可被检索。在提取完成后，对提取结果运行此技能。
• /ratel-assessment — 前置审计技能，用于标记薄弱定义并指向此技能。

基于 LLM 的建议——自动重写描述、检测缺失参数，以及提出冗余工具合并方案——是 Ratel Cloud 建议引擎（即将推出）的发展方向。该引擎会根据你导出的遥测数据，在服务端生成排名后的建议。此技能是这类调整的手动版本；请在计划中注明客户可以将哪些修复推迟到该引擎上线后再处理。

理念

三条规则。违反任何一条，都会导致你只是让目录更美观，却没有提升可检索性；或者以模型容易困惑为代价优化检索效果。

1. 定义服务于两类读者——索引和模型——修复必须同时满足两者的需求。 词法索引会读取名称、描述、参数名称和枚举值（ADR-0004 的 schema 感知投影会剥离 JSON-Schema 结构）；在语义／混合模式下，语义索引会嵌入描述的含义。模型会根据描述决定何时调用，并根据模式决定如何调用。描述中塞满关键词，却没有“何时使用”的信息，或许能满足词法索引的需求，却会损害语义索引和模型的效果。每次重写都必须同时改善两类读者的体验。
2. 精炼胜过冗长。 糟糕描述的修复方案很少是增加字数。过于单薄的描述需要补上一句“是什么 + 何时使用”，而不是扩写成一段；冗长的描述则需要删减。对于模式，应移除限制最宽松的约束（additionalProperties: true、空 {}），而不是增加更多文字来解释。
3. 不臆造问题。 如果某条定义已经简洁准确，就保留原样并说明原因。不要为了显得更忙而重写清晰的描述；不要拆分并非重复的工具；不要为取值空间确实开放的字段添加枚举。修改前后对照表只列出发生变更的定义。

工作流

步骤 1 — 清点所有工具和技能定义

找到声明工具和技能的所有位置，并记录完整的定义内容：名称、描述、参数名称、枚举值、模式，以及（对于技能）标签。

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

# Tool definition sites
grep -rEn 'defineTool|createTool|registerTool|new Tool|@tool\b|@function_tool\b|tools:\s*\{|tools:\s*\[|inputSchema|parameters:\s*\{|catalog\.register|McpServer\(' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' | head -100

# Skill definition sites + Ratel skills folder
grep -rEn 'new Skill|Skill\(|SkillCatalog|skillCatalog\.register' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' | head -50
ls ~/.ratel/skills/ 2>/dev/null

对于每个工具，记录：ID／名称、描述（及其大致词元长度）、每个参数名称、每个枚举值，以及模式的宽松程度（additionalProperties、空对象、缺少的 required）。对于每项技能，记录：名称、描述、标签。如果没有找到工具或技能，请使用诚实跳过路径。

第 2 步 — 获取最新的 Ratel 文档

Ratel 在 0.4.x 系列中快速迭代——不要凭记忆复述索引规则或数据模型；请在运行时按以下顺序获取当前信息：

1. Context7（首选）——通过 Ratel Local（调用 search_capabilities 查找 Context7 的 resolve-library-id / get-library-docs 工具，然后调用 invoke_tool），或使用直接配置的 Context7 MCP。解析 ratel-ai/ratel，并获取 SDK 与 skills 文档。
2. docs.ratel.sh（备用）——WebFetch https://docs.ratel.sh/llms.txt（页面地图），然后获取 https://docs.ratel.sh/llms-full.txt（完整文本），或者获取特定页面 /docs/core/sdks/typescript、/docs/core/sdks/python、/docs/core/skills-suite。
3. GitHub raw / 已安装的软件包（最后手段）——https://raw.githubusercontent.com/ratel-ai/ratel/main/README.md 和 src/sdk/ts/README.md / src/sdk/python/README.md；或客户固定版本中的 node_modules/@ratel-ai/sdk/README.md / Python ratel_ai 软件包 README。

根据文档确认两点：词法索引会分词哪些内容，以及语义分支如何对含义进行排序（以便重写时针对正确的字段）；还有当前的 Skill 数据模型。如果文档与 references/definition-rubric.md 不一致，请以文档为准，并在计划中标记该文件需要更新。

第 3 步 — 根据故障模式进行诊断

使用 references/definition-rubric.md 中的评估标准检查第 1 步中的每个定义。具体故障模式如下：

故障模式	检测启发式
描述冗长	超过约 300 个 token；包含多段文字；用散文重复说明 schema
描述过于简略	少于约 8 个 token，或只给出工具名称而未描述其功能（“Order 工具”）
缺少“何时使用”	说明了功能，却未说明何时调用；与同类工具冲突
工具近似重复	两个或更多工具的描述/名称高度重叠（例如 get_user、fetch_user、lookup_user）
schema 宽松 / 缺失	additionalProperties: true、空 {}、没有 required、参数未指定类型
参数名称缺乏描述性	arg1、data、input、x——词法索引无法识别，模型也无法理解
缺少枚举	取值有限的字符串字段（status、region、mode）仍使用自由形式的 string
工具输出冗长	工具返回大量不受限制的内容，模型每轮都必须重新读取

对于每个标记的定义，记录故障模式以及证据（实际文本、长度或 schema 片段）。

第 4 步 — 说明每项修复为何重要

对于每项修复，计划都要阐明双重理由，让客户明白这并非表面改动：

• 对检索而言——词法索引会对名称、描述、参数名称和枚举值进行分词（结构会被剥离），而语义索引会嵌入描述的含义。因此，将 arg1 重命名为 customer_email、添加枚举值 ["pending","shipped","delivered"]，以及添加触发短语，都会为词法分支增加可检索词项；清晰的自然语言“功能 + 使用时机”也能让语义分支匹配用户未曾明确使用的同义表达。如果工具的描述既不符合用户的用词，含义也不清晰，就不会被检索出来。
• 对模型选择而言——工具进入 Top-K 后，模型会通过阅读描述中的“何时使用”来选择工具，并通过阅读 schema 正确调用。近似重复的工具会分散置信度；宽松的 schema 容易导致调用格式错误；冗长的描述会占用上下文窗口，而工具选择的“默认替换”策略正是为了让上下文保持精简。

第 5 步 — 给出具体改写

针对每个标记出的问题定义，写出修改前 → 修改后。使用评分标准中的改写方法和“优质描述”模板：

<一句话：说明它的功能。适用于 <一行：说明何时调用它。>

• 描述 — 应用模板；添加不同的触发说法，但不要堆砌关键词。
• 名称 / 参数名称 — 改为描述性术语，以便词法索引进行分词。
• 枚举 — 将自由字符串形式的有限字段替换为明确的枚举值列表（这些值会被索引，并限制模型的选择）。
• 架构 — 设置 additionalProperties: false，添加 required，并为每个参数指定类型。
• 近似重复项 — 提议合并（一个工具 + 一个枚举/参数），或明确“适用场景”，以区分保留的定义。
• 冗长输出 — 提议使用 outputSchema 或投影/摘要，让工具只返回模型所需的内容。

对于 skills，还要按照评分标准调整 description 和 tags，提高可检索性：将作者标签和任务短语都纳入 tags，并应用描述模板。将此与 /ratel-decompose-prompt 交叉关联；其中提取出的 skills 是此处的常见输入。

第 6 步 — 排定优先级

按影响排序修复项：

1. 近似重复工具和内容单薄的描述 — 它们会导致检索错误或无结果；影响最高。
2. 缺少“适用场景”和缺少枚举 — 会导致选择错误和调用格式不正确。
3. 宽松的架构和描述性不足的参数名称 — 影响正确性和可检索性。
4. 冗长的描述和冗长的输出 — 影响上下文效率；紧急程度较低，但规模扩大时影响会累积。

第 7 步 — 编写计划

输出到 <repo>/.ratel/ratel-tune-definitions.md。章节按以下顺序排列：

1. 摘要 — 统计数量：盘点的工具/skills 数量、标记出的问题定义数量、各类问题的数量。最多六条要点。
2. 最新文档参考 — 编写计划时参考的 Ratel 版本和文档来源。
3. 修改前/修改后表格 — 每个已更改定义一行：id、问题类型、修改前、修改后。此部分是计划的核心。
4. 架构收紧 — 按工具列出架构差异（additionalProperties、required、枚举、类型）。
5. 近似重复项处理 — 提议合并或消除歧义。
6. 按优先级排列的修复清单 — 按第 6 步排序，每项一行。
7. 路线图说明 — 说明 Ratel Cloud 的建议引擎（即将推出）未来可以自动化哪些修复。

在聊天中直接列出按优先级排列的修复清单，并告知用户文件路径。不要在聊天中粘贴完整计划正文。

诚实跳过方案

两种跳过情况：

1. 未找到工具或 skills。 如果第 1 步没有发现工具或 skill 定义，就停止。告诉用户你搜索了哪些内容，并请他们指出目录的位置（如果目录位于不常见的位置）。不要调整你看不到的定义。
2. 目录规模很小或已经足够完善。 如果定义只有少数几个，并且已经符合评分标准——描述能清楚说明“功能 + 适用场景”、架构严谨、参数具有描述性且没有重复项——就说明这一点并停止。在规模小且描述完善的目录中，这项技能要解决的检索问题几乎不存在。列出你检查过的内容，让客户确认你并非草率检查，并建议随着目录增长再重新评估。

参考文件

• references/definition-rubric.md — 各类问题的检测启发式、改写方法和修改前/修改后示例；还包括“优质描述”模板，以及结合词法和语义索引读取各字段的方式制定的参数/枚举命名指南。

读取以下内容（不重复其中内容）：

• ../ratel-decompose-prompt/references/decomposition-patterns.md — Skill 数据模型，以及本轮调整的 skills 在各字段中的编写背景。