SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场create-agent-adapter

create-agent-adapter

智能体与模型

查看项目

更新于 10-16 07:51

技能介绍

用途

create-agent-adapter 用于在 Paperclip 中创建或修改 Agent 适配器。适配器是 Paperclip 编排层与具体 AI Agent 运行时之间的桥梁，运行时可以是 Claude Code、Codex CLI、自定义进程或 HTTP 端点等。每个适配器是一个自包含的包，需要为服务端、UI 和 CLI 三个消费方分别提供实现。

架构概览

适配器包位于 packages/adapters/<name>/，典型结构包含：

  • src/index.ts：共享元数据（type、label、models、agentConfigurationDoc）
  • src/server/：服务端导出，包括 execute、sessionCodec、parse 辅助函数
  • src/ui/：UI 导出，包括 parseStdoutLine、buildConfig
  • src/cli/：CLI 导出，包括 formatStdoutEvent
  • package.json、tsconfig.json

三个独立的注册表分别消费适配器模块：服务端注册表位于 server/src/adapters/registry.ts，接口为 ServerAdapterModule；UI 注册表位于 ui/src/adapters/registry.ts，接口为 UIAdapterModule；CLI 注册表位于 cli/src/adapters/registry.ts，接口为 CLIAdapterModule。

共享类型

所有适配器接口位于 packages/adapter-utils/src/types.ts，可从 @paperclipai/adapter-utils（类型）或 @paperclipai/adapter-utils/server-utils（运行时辅助函数）导入。核心接口包括 AdapterExecutionContext、AdapterExecutionResult、AdapterSessionCodec，以及三个模块接口 ServerAdapterModule、UIAdapterModule、CLIAdapterModule。

适配器环境测试契约

每个服务端适配器必须实现 testEnvironment(...)，用于驱动 Agent 配置中的“Test environment”按钮。检查级别分为 info、warn、error，测试状态分为 pass、warn、fail。指南要求：返回结构化诊断，预期内的发现不要抛异常；对无效或不可用的运行时设置使用 error；对非阻塞但重要的情况使用 warn；对成功检查和上下文使用 info。严重性策略是产品关键点：警告不是保存的阻塞项。

创建新适配器的步骤

  1. 创建包：按四导出约定配置 package.json，exports 包含 .、./server、./ui、./cli。
  2. 根 index.ts 提供适配器元数据：type（snake_case、全局唯一）、label、models、agentConfigurationDoc。agentConfigurationDoc 应写成路由逻辑而非营销文案，包含具体的“use when”和“don't use when”指引，以便 LLM 判断该适配器是否适合给定任务。
  3. 服务端模块：server/execute.ts 是核心，接收 AdapterExecutionContext 并返回 AdapterExecutionResult，需完成读取配置、构建环境、解析会话、渲染提示词、调用 onMeta、启动进程、解析输出、处理会话错误、返回结果等行为。server/parse.ts 负责把 Agent 的 stdout 解析为结构化数据，需处理会话识别、用量跟踪、成本跟踪、摘要提取、错误检测、未知会话检测。解析时应把 Agent 输出视为不可信，防御性解析，绝不 eval 或动态执行输出内容。server/index.ts 导出 execute、testEnvironment、解析函数和 sessionCodec。server/test.ts 实现适配器特定的预检检查。
  4. UI 模块：ui/parse-stdout.ts 把单行 stdout 转换为 TranscriptEntry[]，需处理 init、assistant、thinking、tool_call、tool_result、user、result、stdout 等类型。ui/build-config.ts 把表单值转换为 adapterConfig JSON。UI 配置字段组件使用 ui/src/components/agent-config-primitives 中的共享原语，并需同时支持创建模式和编辑模式。
  5. CLI 模块：cli/format-event.ts 为 paperclipai run --watch 美化输出，使用 picocolors 着色。

注册清单

创建适配器包后，需在三个消费方中注册：服务端注册表、UI 注册表、CLI 注册表，分别将适配器模块加入对应的 adaptersByType 映射。

适用场景

适用于需要为 Paperclip 新增对某种 CLI Agent、API Agent、自定义进程或 HTTP 端点的支持，或修改现有适配器在服务端、UI、CLI 三个层面的行为。

限制

资料未提供该技能的具体收费、价格、平台支持范围或效果数据。适配器实现需遵循上述接口契约，输出解析需防御性处理，环境测试的严重性策略需保持一致。