ratel-integrate

/ratel-integrate — 通过 Ratel 加载 Agent 的工具和技能

将现有 Agent 仓库转变为可运行的 Ratel 集成。首先了解这些 Agent 及其已有能力；然后以最小的框架原生改动，通过 Ratel 接入相同的工具和技能。

交付内容是在客户仓库中进行代码、依赖项和测试变更。除非用户明确要求，否则不要创建 .ratel/ratel-integrate.md 计划。

范围

将此集成严格限定在以下范围内：

• 发现 Agent、工具、技能及其当前的所有权边界。
• 向 Ratel 注册可执行工具和技能正文。
• 为每个 Agent 提供 Ratel 的稳定能力工具；如果宿主适配器支持，还要提供逐轮召回。
• 对于 Vercel AI SDK Agent，使用 @ratel-ai/vercel-ai-sdk；对于 Mastra Agent，使用 @ratel-ai/mastra。
• 对于其他受支持的宿主，直接使用核心 SDK；不要臆造适配器包。
• 保留提示词、模型、执行器、架构、中间件、记忆和请求上下文，除非确实需要进行小幅接线改动。
• 不要添加遥测、实验、功能开关、试点逻辑、仪表板、A/B 测试或发布管理机制。

可观测性不是前提条件。如果用户明确要求集成 Ratel，那么小型工具目录或仅包含技能的 Agent 也有效。

原则

1. 先梳理，再接线。 包的存在不代表 Agent 拓扑结构。找到实际的 Agent 构造、模型调用、工具注册表、技能来源和历史记录生命周期。
2. 保留能力边界。 一个 ratel() 实例拥有一个共享的工具和技能目录。只有当多个 Agent 有意共享相同能力时才共用该实例；否则应创建单独的实例。联合目录可能导致授权漏洞。
3. 优先使用宿主适配器。 AI SDK 和 Mastra 适配器能够保留原生架构、执行上下文、透传工具和召回消息格式。手写转换会重新引入已有解决方案处理过的边缘情况。
4. 在组合根集成。 复用现有工具和技能定义。不要仅为了满足 Ratel 而重写单个实现。
5. 保持面向模型的工具稳定。 在注册透传工具后，为每个 Agent 获取一次 modelTools() 并重复使用。之后，实时目录仍可接收常规可执行工具和技能。

工作流

步骤 1 — 安全地检查仓库

更改任何内容前，先阅读仓库说明并检查工作树状态。根据锁文件和清单确定包管理器及工作区。

使用 rg 查找：

• Agent 构造器、工厂、监督器、子 Agent、模型调用和工具循环入口。
• Vercel AI SDK 导入，例如 generateText、streamText 和 ToolLoopAgent。
• Mastra Agent 构造和 createTool 定义。
• 自定义 TypeScript/Python 模型循环和框架封装。
• 静态工具对象、动态注册表、工具工厂、分发器和 MCP 客户端。
• 运行时技能注册，以及 .agents/skills、.claude/skills、.codex/skills 或仓库专用目录下的项目级 SKILL.md 文件。
• 现有 Ratel 依赖和部分集成代码。

忽略供应商提供的依赖项、生成的输出、构建产物和用户全局技能目录，除非仓库明确加载这些内容。

Step 2 — 构建每个 Agent 的能力映射

对于每个面向模型的 Agent，记录：

字段	需要识别的内容
Agent	稳定名称，以及构造和调用文件
宿主	AI SDK、Mastra、自定义 TypeScript、Python 或其他框架
工具	定义来源、注册表结构、分发器，以及确切分配的 ID
技能	定义／文件系统来源、加载器，以及确切分配的 ID
范围	共享、Agent 专属、租户专属或请求专属
历史记录	无状态、短暂的工具循环，或持久的多轮消息
验证	最相关的单元／集成测试和构建命令

沿着数据流追踪，而不要依赖命名惯例。依赖 ai 并不能证明应用直接使用了 Vercel AI SDK——Mastra 可能是间接引入它的。Markdown 文件也不会自动成为 Agent 技能。

如果能力归属涉及安全，且无法从代码或配置中确认，请先提出一个有针对性的问题，再合并目录。在等待回复期间，继续处理所有归属明确的 Agent。

Step 3 — 验证当前 SDK 接口

Ratel 更新很快。编辑前请查阅文档：

1. 如可用，请使用 Context7 解析 ratel-ai/ratel。
2. 检查清单和锁文件中已固定的版本，并在已安装的软件包中查阅其 README。
3. 对于新安装或 main 上新增的 API，请查阅 ratel-ai/ratel 中的官方 SDK 和适配器 README。

确认稳定的软件包版本、异步注册 API、技能数据模型、适配器兼容性以及召回用法。优先选择稳定版；除非用户提出要求，否则不要选择预发布版或实验性软件包。

Context7 可能无法及时反映近期的适配器改动。如果其内容与已发布软件包的 README 或当前官方源码冲突，请以代码库实际会安装的版本为准。阅读 references/integration-patterns.md，了解适配器选择和代码结构，然后结合最新文档进行核对。

Step 4 — 为每个 Agent 选择受支持的路径

检测到的宿主	集成方式
直接导入兼容的 Vercel AI SDK API 的 TypeScript	@ratel-ai/sdk + @ratel-ai/vercel-ai-sdk；ratel(...).adaptTo(aiSdk())
使用兼容版 Mastra 的 TypeScript	@ratel-ai/sdk + @ratel-ai/mastra；ratel(...).adaptTo(mastra())
自定义或其他 TypeScript 宿主	@ratel-ai/sdk；仅在现有模型边界适配其原生能力工具
Python 宿主	ratel-ai；将核心能力工具封装为该框架文档所述的工具格式
不受支持的语言／框架	如果当前 SDK 的结构适用，则使用文档所述的轻量封装；否则说明具体阻碍

选择适配器前，请检查当前的 peer 和 Node.js 版本范围。如果需要升级框架或运行时，不要擅自扩大任务范围：只有在能保留语义时才使用文档所述的核心路径，否则说明阻碍。不要推荐不存在的适配器，也不要用 Ratel Local 或 MCP 网关替换进程内集成。

第 5 步 — 实现能力加载

使用仓库的包管理器，在拥有该 Agent 的包中安装依赖。

对于每个能力边界：

1. 在 Agent 的组合根中，为每个不可变授权集构建或缓存一个 Ratel 核心。对于租户级或请求级能力，使用每请求核心或精确范围缓存；绝不要将请求专属工具注册到进程级全局核心中。默认使用 BM25 和较小的召回预算，除非仓库已有明确的检索配置。
2. 通过适配后的视图注册 Agent 现有的框架原生工具。保留 ID、描述、架构、执行器、审批行为和实时执行上下文。
3. 仅当 Agent 已使用上游 MCP 工具时，才将其接入同一目录。不要扩大其 MCP 访问范围。
4. 将分配的技能作为一个批次注册到 r.skills。Ratel 不会扫描目录：复用现有加载器，或添加最精简的加载器，将获准的项目技能转换为 { id, name, description, tags?, tools?, metadata?, body? }。
5. 确保每个技能的 tools 字段与已注册工具的确切 ID 一致。不要注册任意仓库 Markdown 文件或用户全局技能。
6. 将 Agent 面向模型的完整可执行目录替换为 r.modelTools()，并保留适配器透传项。
7. 添加宿主支持的召回／发现路径：
   • AI SDK：无状态／即插即用调用使用 prepareStep；当应用会持久化多轮响应消息时，使用 appendRecall。
   • Mastra：将 r.recallProcessor() 追加到现有输入处理器中。
   • 自定义 TypeScript：仅当宿主有明确的消息注入边界时，使用核心的 r.recall(query)。
   • Python 和其他宿主：以框架原生格式公开能力工具。仅当当前官方示例记录了相应路径时，才添加 Top-K 筛选或消息注入。

如果仓库中已有 Ratel，应扩展或迁移现有集成，而不是创建第二个目录。再次运行此技能时，不应产生更多更改。

第 6 步 — 验证行为

对于新的加载器或能力映射逻辑，先编写针对性失败测试。然后验证：

• 每个 Agent 都公开 search_capabilities、invoke_tool 和 get_skill_content，以及仅限合法的透传工具。
• 具有代表性的查询能够通过 Ratel 发现并调用已分配的工具。
• 具有代表性的查询能够发现已分配的技能并加载其完整正文。
• 技能声明的工具 ID 能在同一目录中解析。
• 能力范围不同的 Agent 无法发现彼此的工具或技能。
• 在所选适配器提供召回功能时，每个用户轮次只注入一次适配器召回，且现有对话持久化仍正常工作。

先运行范围最窄的测试，然后根据情况运行受影响包的类型检查、测试套件、lint 和构建。不要修复无关的既有失败；应单独报告。

第 7 步 — 报告已完成的集成

总结：

1. 找到的 Agent，以及每个 Agent 使用的 Ratel 接入路径。
2. 接入每个 Agent 的工具和技能来源。
3. 依赖项和已更改的文件。
4. 验证命令及其结果。
5. 不受支持或有意未触及的部分。

不要包含上线指标或未来的遥测计划。

诚实的停止路径

• 不存在 Agent 接入点： 如果不存在面向模型的 Agent 或工具／技能加载路径，不要安装 Ratel。报告你检查过的位置，并询问非标准位置。
• 没有能力： 如果 Agent 既没有工具也没有技能，则保持不变并说明原因。
• 所有权边界不明确且存在风险： 如果合并目录可能扩大 Agent 的访问范围，就不要合并。请对方明确缺失的边界决策。
• 适配器不受支持： 绝不要捏造包或悄然削弱框架语义。使用当前文档记录的包装器路径，或说明无法安全集成的原因。

参考

• references/integration-patterns.md — 当前稳定的 TypeScript 适配器形式、与框架无关的回退方案、技能注册和多 Agent 边界