ratel-decompose-prompt

/ratel-decompose-prompt — 将单体系统提示词拆分为精简核心提示词和可检索技能

系统提示词一旦增长到数千个 token，每一轮都要为其中的每项职责付出代价。大部分内容在大多数时候都处于休眠状态：用户询问配送时，退款流程仍占用上下文；用户编辑表单时，SQL 生成指南也会加载。Ratel 的技能机制正是为此而设计：将流程变为可检索的指南，只有当某一轮需要时才将其载入上下文。此技能可以解决这一问题，将一个庞大的提示词拆分为精简且稳定的核心提示词，以及由提取出的技能组成的 SkillCatalog。

交付物是一份 Markdown 计划，路径为 <repo>/.ratel/ratel-decompose-prompt.md：其中包括拟定的精简核心提示词、技能清单表，以及每项技能的 SKILL 定义，可直接放入由 Ratel 管理的技能文件夹。客户可以根据计划自行实施；此技能不会直接改写其提示词。

/ratel-assessment 中的“提示词拆分”维度会将问题路由至此技能。它与以下技能配合使用：

• /ratel-tune-definitions — 提取出的每项技能都需要可检索的 description 和 tags。拆分步骤会生成技能；tune-definitions 会优化其措辞，让 search_capabilities 能够实际找到它们。请在此技能之后，对提取出的技能运行 tune-definitions。
• /ratel-assessment — 前置审计技能，用于识别内容过于臃肿的提示词，并指引用户前往此处。

理念

三条规则。违反其中任何一条，要么只是转移了冗余内容而没有真正删减，要么削弱了提示词中稳定的约定，导致 Agent 变得不可靠。

1. 核心提示词保留每一轮都必须遵守的内容；技能承载视情况而定的内容。 稳定的角色、安全规则和输出格式约定应留在核心提示词中——模型绝不能缺少这些内容。反复使用的流程、特定任务的指南和少样本示例则视情况而定，应放入技能。判断每个部分时，问自己：“如果在无关的一轮中缺少这部分内容，Agent 会变得不安全或违反约定吗？”如果会，就留在核心提示词中；如果不会，就可以考虑将其提取为技能。
2. 技能必须完整自洽，并且值得检索。 提取出的技能会通过 get_skill_content 独立加载，不带任何周边提示词上下文。如果某个部分只有与其他三个部分拼在一起才有意义，那它应该是一项技能，而不是四项。不要将连贯的流程拆成无法独立使用的碎片。
3. 可检索性是设计约束，不是事后补充。 无法被检索到的技能只是目录中的冗余内容，也会造成 Agent 行为上的缺失。每项提取出的技能都必须带有 description 和 tags，并与需要该技能的轮次所表达的自然语言意图相符。如果无法为其编写触发条件，它可能应该留在核心提示词中，或者根本不值得作为技能。

工作流程

第 1 步 — 找出并衡量系统提示词

找出所有系统提示词，并估算它们每轮的成本。提示词可能藏在内联字符串、模板文件、提示词管理服务和各个 Agent 的常量中。

# Manifests (drives stack + where prompts tend to live)
test -f package.json && jq -r '.dependencies // {}, .devDependencies // {} | keys[]' package.json | sort -u
test -f pyproject.toml && head -200 pyproject.toml

# System-prompt surfaces
grep -rEn 'system:|role:\s*["'\'']system|systemPrompt|SYSTEM_PROMPT|system_prompt|instructions:|messages\.create|ChatPromptTemplate|SystemMessage' \
  --include='*.ts' --include='*.tsx' --include='*.js' --include='*.py' --include='*.md' --include='*.txt' \
  | head -100

# Prompt files by convention
find . -type f \( -name '*.prompt' -o -name '*prompt*.md' -o -name '*prompt*.txt' \) -not -path '*/node_modules/*' | head -50

针对找到的每个提示词，估算其 token 数量（大致为字符数 ÷ 4，或 wc -c ÷ 4）。记录哪些提示词最长，以及哪些会在每一轮加载、哪些只会在特定路径中加载。如果完全没有找到系统提示词，请采用如实跳过流程。

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

Ratel 更新很快——不要凭记忆复述 skills API 或 Skill 数据模型；请在运行时按以下顺序获取当前状态：

1. Context7（首选）——通过 Ratel Local（本地 MCP 服务）调用：先调用 search_capabilities 查找 Context7 的 resolve-library-id / get-library-docs 工具，然后调用 invoke_tool；也可以使用直接配置的 Context7 MCP。解析 ratel-ai/ratel，并获取 SDK 和 skills 文档。
2. docs.ratel.sh（备用）——对 https://docs.ratel.sh/llms.txt（页面索引）调用 WebFetch，然后对 https://docs.ratel.sh/llms-full.txt（完整文本）调用 WebFetch；也可以获取以下特定页面：https://docs.ratel.sh/docs/core/agent-skills、https://docs.ratel.sh/docs/core/sdks/typescript、https://docs.ratel.sh/docs/core/sdks/python。
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。

记录三项内容：当前发布的版本、SkillCatalog / Skill / searchCapabilitiesTool / getSkillContentTool API 结构，以及 Skill 数据模型字段。如果获取的文档与 references/decomposition-patterns.md 中的模式不一致，以文档为准，并在计划中标记该文件需要更新。

步骤 3 — 找出拆分界线

阅读提示词，并按职责划分为不同部分。需要查找的拆分界线及其归属如下：

部分类型	处理方式	原因
稳定的角色 / 人设	保留在核心中	必须在每轮对话中保持；开销低；定义 Agent
安全 / 拒绝 / 策略规则	保留在核心中	缺失会导致正确性 / 安全性退化
输出格式约定（架构、语气、结构）	保留在核心中	模型必须在每次响应中遵守
反复出现的多步骤流程	提取为 skill	视情境而定；内容较多；仅在匹配的对话轮次中相关
特定任务的操作手册（退款流程、SQL 生成、分诊）	提取为 skill	每项都是一个独立完整的 skill
少样本示例	提取为 skill	内容较多；将匹配任务的示例提取到该任务的 skill 中
工具使用文档 / 单个工具的使用指南	提取为 skill（或并入工具自身的描述——参见 /ratel-tune-definitions）	工具匹配时，与该工具一同呈现

建立各部分清单：记录每部分的大致 token 数量、处理方式，以及（对于候选提取部分）其服务任务的一句话说明。完整目录和前后对照示例请参阅 references/decomposition-patterns.md。

步骤 4 — 根据数据模型定义每项提取出的技能

对于每个待提取候选项，指定完整的 Ratel Skill 数据模型。只有 name、description 和 tags 会建立索引以供检索——因此它们决定了技能的可检索性。body、tools 和 metadata 不会建立索引。

• id — 稳定的 slug，例如 refund-flow。
• name — 简短的人类可读标签；会建立索引。
• description — 采用直接明确的多短语描述，指出需要该技能的对话轮次所对应的自然语言触发词；会建立索引。这是主要的检索入口。
• tags — 同时纳入作者标签（“billing”“support”）和用户实际输入的任务短语（“issue a refund”“customer wants money back”）；会建立索引。简短的意图提示会与这些标签匹配。
• tools — 技能正文调用的工具 ID。属于有类型的依赖关系：当技能匹配时，search_capabilities 会在工具分类中显示这些工具。不会建立索引。
• metadata — 用于推送路径排序／加权的项目上下文，例如 {"stacks": ["react"]}。不会建立索引。
• body — 从提示词部分提取并整理成独立完整内容的实际操作手册文本。通过 get_skill_content 按需加载的调度载荷。不会建立索引。

字段编写指南以及与 Ratel 混合检索机制相关的说明，请参阅 references/decomposition-patterns.md：词法检索侧会优先考虑描述性名称、标签和精确触发词，语义检索侧则会匹配释义和意图——因此，清晰且包含多个短语的描述有助于两者。请将 description/tags 相关工作交叉关联到 /ratel-tune-definitions。

步骤 5 — 编写精简的核心提示词

将保留在核心中的部分整合到新的核心提示词中。它只应包含角色、安全／政策和输出约定，此外还应简短说明 Agent 可使用技能，并应在对话轮次需要某个流程时检索相应技能。估算新核心的 token 权重，并说明相较原文的缩减幅度。

步骤 6 — 展示注册接线方式

展示如何注册提取出的技能，以及如何接入能力工具（search_capabilities、get_skill_content），分别提供 TS 和 Python 代码形式（根据获取到的 API 进行调整）。

TypeScript（@ratel-ai/sdk）：

import { SkillCatalog, Skill, searchCapabilitiesTool, getSkillContentTool } from "@ratel-ai/sdk";

const skillCatalog = new SkillCatalog();
skillCatalog.register(new Skill({
  id: "refund-flow",
  name: "Refund flow",
  description: "Process a customer refund end to end. Use when the user wants money back, disputes a charge, or asks to cancel and refund an order.",
  tags: ["billing", "support", "issue a refund", "customer wants money back"],
  tools: ["lookup_order", "issue_refund"],
  metadata: { stacks: ["node"] },
  body: "/* the refund playbook lifted from the old prompt, made self-contained */",
}));

// Skills are ranked alongside tools; pass the skill catalog into the capability tools.
const tools = {
  search_capabilities: searchCapabilitiesTool(toolCatalog, skillCatalog),
  get_skill_content: getSkillContentTool(skillCatalog),
  // invoke_tool: invokeToolTool(toolCatalog),
};

Python（ratel-ai）：

from ratel_ai import SkillCatalog, Skill, search_capabilities_tool, get_skill_content_tool

skill_catalog = SkillCatalog()
skill_catalog.register(Skill(
    id="refund-flow",
    name="Refund flow",
    description="Process a customer refund end to end. Use when the user wants money back, disputes a charge, or asks to cancel and refund an order.",
    tags=["billing", "support", "issue a refund", "customer wants money back"],
    tools=["lookup_order", "issue_refund"],
    metadata={"stacks": ["python"]},
    body="""...refund playbook, self-contained...""",
))

tools = {
    "search_capabilities": search_capabilities_tool(tool_catalog, skill_catalog),
    "get_skill_content": get_skill_content_tool(skill_catalog),
}

请在计划中说明两种呈现机制：

• PULL — search_capabilities 会在工具旁返回按排名排列的技能分类；Agent 在执行与工具相关的工作时检索技能，并通过 get_skill_content 加载其正文。这是从使用工具的流程中提取技能时的默认方式。
• PUSH — UserPromptSubmit 预加载钩子会针对无工具意图提示注入明确胜出的技能。这是实验性功能，且受明确胜出规则限制；仅建议用于能清晰映射到无歧义意图的技能，并依靠 metadata 为推送路径加权。

技能存储在 Ratel 管理的文件夹中（默认为 ~/.ratel/skills/）。请说明客户提取出的技能应写入何处。

步骤 7 — 编写计划

输出到 <repo>/.ratel/ratel-decompose-prompt.md。按以下顺序排列各部分：

1. 摘要 — 原始提示词的位置和 token 权重、建议的核心提示词 token 权重、提取的技能数量、预计每轮减少的 token 数。最多六条。
2. 最新文档参考 — 编写计划时依据的 Ratel 版本和文档来源。
3. 建议的精简核心提示词 — 完整改写后的核心提示词，可直接粘贴使用。
4. 技能清单 — 一张表格，列出技能 ID、名称、来源部分、提取的 token 权重、呈现模式（PULL/PUSH）。
5. 逐项技能 SKILL 定义 — 填写每项技能的所有数据模型字段。
6. 注册配置 — 根据客户的技术栈和技能文件夹位置调整后的 TS/Python 代码片段。
7. 下一步 — 指向 /ratel-tune-definitions，以完善提取出的技能描述和标签，提升检索效果。

在聊天中直接打印技能清单表格，并告知用户文件路径。不要在聊天中粘贴完整计划正文。

诚实跳过路径

两种跳过情况：

1. 未找到系统提示词。 如果步骤 1 未能在任何位置找到系统提示词/指令提示词，就停止。告知用户搜索过哪些位置，并请用户指出提示词是否存放在不寻常的位置。不要为看不到的提示词编造分解方案。
2. 提示词已经很短或结构清晰。 如果提示词较短（约低于 800 个 token），或已清晰拆分为精简核心提示词加外置流程，则说明这一点并停止。分解精简的提示词会增加检索开销和维护目录，却不会减少每轮 token 数。说明这个阈值，并建议在提示词增长后重新评估。

参考文件

• references/decomposition-patterns.md — 常见提示词部分的分类、各部分保留在核心提示词中或提取为技能的对应关系、前后对照示例，以及结合 Ratel 混合检索的逐字段技能编写指南。

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

• ../ratel-tune-definitions/references/definition-rubric.md — 用于评估提取出的技能的描述/标签规范。