十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

Claude Code Router(CCR)Fusion 自定义 MCP 工具与文生图/视频生成实战指南

Claude Code Router(CCR)Fusion 自定义 MCP 工具与文生图/视频生成实战指南 Claude Code RouterCCRFusion 自定义 MCP 工具与文生图/视频生成实战指南【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router导读在 CCR 的 Fusion 模型中你不仅可以让模型看图视觉与联网检索Web Search还能挂接任意 MCP 工具——从本地命令行脚本stdio到远程 MCP 服务streamable-http / SSE甚至直接把图像生成、视频生成这类媒体能力变成模型的普通工具。读完本文你将掌握 Fusion 自定义 MCP 的接入入口、图像/视频生成工具的参数与模型选择机制、其底层媒体协议与安全策略以及如何在业务路由中验证使用这类能力增强的 Fusion 模型。本文依据官方配置文档 docs/src/content/docs/en/configuration/fusion-mcp-tool.md 展开并结合仓库源码深入讲解其内部实现。若要了解 Fusion 的整体理念基础文本模型 能力层 增强模型可先阅读 Fusion models 文档。Fusion 能力层与 MCP 工具定位Fusion 的设计是保留基础模型的推理、写作与编码行为仅在需要时追加缺失的能力层。fusion.md中明确列出了五类能力内置视觉、内置联网搜索、图像生成工具、视频生成工具以及自定义 MCP 工具fusion.md。本文聚焦其中 MCP 相关部分覆盖两类场景自定义 MCP 工具把本地脚本、内部系统或远程服务包装成模型可调用的工具内置媒体工具把图像生成 / 图像编辑 / 文生视频等能力作为 Fusion 的内置工具暴露给模型。与 ToolHub 不同媒体工具像内置搜索工具一样工作不属于 ToolHub也不会在 Fusion 页面创建独立分区。接入入口从内置工具到自定义 MCP在 Fusion UI 中选择工具配置入口在 Fusion 模型编辑页的Tools区域选择内置工具直接在 Tools 下选择 Image generation图像生成、Video generation视频生成等内置项Add custom MCP点击按钮连接自定义服务。文档明确自定义 MCP 支持以下能力fusion-mcp-tool.md能力说明stdio本地命令行型 MCP 服务适合本地脚本 / 内部进程streamable-http / sse远程 MCP 服务适合跨主机接入内部系统Discover tools读取 MCP 服务器暴露的工具列表一个 Fusion 模型 一个可复用新模型保存后该 Fusion 模型会像一个普通模型一样出现在路由routing与 Agent Profiles 中可以被用作 Agent 模型或路由目标routing target。例如General model custom MCP tool Agent model that can access internal systems通用模型 自定义 MCP 可访问内部系统的 Agent 模型General model image/video generation tools Agent model that can produce media assets通用模型 媒体工具 可产出媒体资产的 Agent 模型。图像与视频生成工具详解工具循环限制Fusion 工具循环没有轮数上限也没有工具调用次数上限请求超时request timeout与客户端取消client cancellation仍然生效。这意味着模型可以反复调用媒体工具迭代生成而不需要担心工具循环被提前掐断。每个工具一个主模型选择器每个媒体工具都有一个主模型选择器primary model selector并可配置可选的重试次数与回退模型选择器fallback model selectors。选择模型后需保存 Fusion 模型之后便可将该模型用作 Agent 模型或路由目标。关键的请求路径事实原文档说明选择Provider/model后请求会走ai-gateway自动应用该 Provider 上配置的 endpoint、激活凭据active credential、额外请求头与额外请求体媒体工具永远不会向你索要独立的 xAI API key导入的 Grok Agent会自动贡献grok-imagine-image-quality与grok-imagine-video两个模型。ai-gateway 复用其已有 OAuth 登录来访问api.x.ai不会启动 Grok CLI这一点在源码中也有印证GROK_CLI_MEDIA_MODEL_SELECTOR仅作为兼容旧配置的哨兵值保留见 contracts/app.ts 中GROK_API_MEDIA_BASE_URL https://api.x.ai/v1、GROK_API_DEFAULT_IMAGE_MODEL grok-imagine-image-quality与GROK_API_DEFAULT_VIDEO_MODEL grok-imagine-video等常量定义图像与视频模型相互独立重试次数、回退模型彼此独立不同的 Fusion Profile 可以绑定不同的媒体模型。配置媒体的四步流程原文档给出了完整的配置步骤在Providers页面添加支持图像/视频生成协议的 Provider 与模型或者导入一个已登录的 Grok Agent在某个 Fusion 模型的Tools下添加Image generation、Video generation可同时添加在对应工具下方选择模型然后保存 Fusion 模型把该 Fusion 模型用作 Agent 模型或路由目标。底层媒体协议CCR 通过 ai-gateway 的通用媒体协议调用 Provider文档列出图像images/generations生成、images/edits编辑视频videos/generations提交任务、videos/{id}查询/管理任务。模型选择器只展示声明或检测到具备匹配媒体能力的 Provider 模型Grok API 是当前受支持的一种实现。运行时工具Profile 专属工具名与能力矩阵为避免不同 Fusion Profile 之间的模型绑定相互冲突保存 Fusion 模型时CCR 会生成带 Profile 标识的运行时工具名profile-specific runtime tool names。其能力由下表概括Fusion 工具运行时能力Image generation生成图像编辑 1~3 张本地图像Video generation提交文本/图像/参考图视频任务随后可查询或取消异步任务从源码可见媒体绑定会从 Fusion Profile 的metadata.fusionMedia读取主要字段包括图像与视频各自的模型选择器imageModelSelector/videoModelSelector、回退模型列表imageFallbackModelSelectors/videoFallbackModelSelectors、重试次数imageRetryCount/videoRetryCount以及各工具名见 media/tools.ts 中mediaToolBindingsForConfig与readFusionMediaConfig的实现。工具定义集中在mediaMcpToolDefinition例如图像生成的入参 schema 为prompt必填最长 20000 字符、可选的aspect_ratio如1:1、16:9、9:16、4:3、3:2以及idempotency_key图像编辑则要求images1~3 个本地图片绝对路径prompt。视频生成则额外暴露duration、resolution、images最多 7 张等与所选协议约束相关的参数。幂等键与计费安全付费类提交接受可选的idempotency_key幂等键。为同一个用户意图复用同一个稳定 key可以避免网络重试期间产生重复计费。视频提交会立即返回一个 job ID供后续查询与取消使用。支持的媒体后端能力文档说明后端 API 完整支持以下操作图像生成image generation图像编辑image editing文本转视频text-to-video图像转视频image-to-video参考图转视频reference-to-video一个值得注意的实现约束是媒体执行永远不会启动嵌套的 Agent 或 CLI 子进程——它只与 Provider 的 HTTP API 通信这也解释了为什么 Grok Agent 场景下仅复用其 OAuth 凭据而不拉起 Grok CLI。Artifacts 与安全策略产物的存储与访问生成的媒体产物Artifact存放在CCR 的私有数据目录中每个产物记录以下元数据本地路径local pathMIME 类型MIME type大小sizeSHA-256 摘要带过期时间的 URLexpiring URL视频的 URL 额外支持 HTTP Range 请求便于分段播放/下载。源码侧的类型定义见 media/contracts.tsMediaArtifact结构包含localPath、mimeType、sizeBytes、sha256、expiresAt与accessTokenMediaJob结构则记录了statusqueued/running/succeeded/failed/canceled、operation、modelSelector、可选的usage成本信息等字段。文档特别强调产物的保留时间Retention、并发数Concurrency、超时Timeout都属于 CCR 内部安全策略不会在 Fusion UI 上请求用户配置。本地图片输入的文件系统防护当模型提交本地图片作为输入图像编辑、图生视频、参考图转视频时会经过三类检查规范路径检查canonical-path路径会先经过realpathSync解析为真实路径文件签名检查file-signature大小检查size。在 media/service.ts 的输入校验实现中可以看到图片根目录media input roots默认只包含以下集合外加用户显式配置的allowedInputRoots作用域内的当前工作目录需满足安全的隐式工作目录判定系统临时目录CCR 配置目录。而文件系统根目录、用户主目录以及主目录以上的目录永远不会被隐式信任。若确实需要更广泛的访问必须显式地在策略中加入allowedInputRoots条目。UI 不暴露Allowed image roots字段也就是说这些安全边界主要面向高级/编程化配置场景。直接连接 MCP 客户端的端点若想绕过 Fusion UI、直接用 MCP 客户端连接可以使用http://127.0.0.1:3456/__ccr/media/mcp Authorization: Bearer CCR API Key端点的鉴权使用CCR API Key而产物 URL 则使用独立的过期 tokenexpiring tokens两者相互隔离。源码常量可在 mcp/grok-media-config.ts 中找到MEDIA_TOOLS_MCP_PATH /__ccr/media/mcp、MEDIA_ARTIFACT_PATH_PREFIX /__ccr/media/artifacts/。为兼容迁移旧的/__ccr/grok-media/*路由LEGACY_GROK_MEDIA_MCP_PATH与LEGACY_GROK_MEDIA_ARTIFACT_PATH_PREFIX仍可用。内部 stdio MCP 代理机制理解媒体工具的注册机制有助于排查工具缺失类问题。Fusion 在内部通过一个基于 Core 配置生成的stdioMCP 代理来注册这些工具该代理直接返回 Profile 的确定性工具目录deterministic tool catalog实际的工具调用被转发到上述私有 HTTP 端点。采用这一设计是为了避免因 HTTP MCP 发现discovery或启动顺序问题导致工具缺失。真正的代理实现见 mcp/media-tools-proxy-mcp.ts它是一个 JSON-RPC 2.0 over stdioContent-Length消息帧的小型服务器处理initialize、tools/list、tools/call并把tools/call通过 HTTP POST 转发到CCR_MEDIA_MCP_URLBearer 认证使用CCR_MEDIA_MCP_API_KEY请求超时则根据CCR_MEDIA_MCP_REQUEST_TIMEOUT_MS控制。代理进程的环境由 grok-media-config.ts 组装CCR_MEDIA_MCP_TOOLS_JSON携带绑定的工具定义请求超时被钳制在 60s 与 60min 之间具体为jobTimeoutMs 30000的上下限截断MCP 协议版本为2024-11-05。内部策略示例以下 JSON 是文档给出的内部策略示例通常无需手动修改{ mediaTools: { enabled: true, artifactTtlHours: 24, jobTimeoutMs: 600000, maxImageConcurrency: 2, maxVideoConcurrency: 1, allowedInputRoots: [] } }对应到源码中的MediaToolsConfig类型contracts/app.ts字段语义为字段语义默认示例值enabled是否启用媒体工具trueartifactTtlHours产物保留时长24小时jobTimeoutMs媒体任务超时600000ms即 10 分钟maxImageConcurrency图像任务并发上限2maxVideoConcurrency视频任务并发上限1allowedInputRoots额外允许的本地输入根目录默认空数组旧配置迁移为兼容第一代 Grok 专用实现配置加载时会将旧的grokMedia输入迁移到mediaTools。另外若旧配置中绑定了grok-cli媒体模型legacygrok-climedia binding系统会把它解析为已导入的 Grok Agent 或已配置的 Grok API 模型绝不会启动 Grok CLI。旧版工具名如grok_media_image_generate、grok_media_video_start等在源码 contracts/app.ts 中被明确标注为仅为迁移旧配置而保留并通过 media/tools.ts 中migrateLegacyGrokMediaModelSelector等逻辑解析到可用模型。验证Verification在生产路由中正式使用之前请先按以下建议验证Verify that the selected provider implements the relevant media endpoints with a test Fusion profile before using it in production routing.具体做法是先用一个测试 Fusion Profile 验证所选 Provider 是否真正实现了相关媒体端点确认图像/视频请求能成功返回产物后再把它接入正式的生产路由目标。这一步能在早期暴露 Provider 媒体能力声明与真实实现不一致、凭据缺失或端点不兼容等问题。小结接入方式Fusion 模型的 Tools 区域既可选用内置的 Image/Video generation 工具也可通过 Add custom MCP 接入 stdio、streamable-http/SSE 类型的自定义服务模型绑定每个媒体工具独立配置主模型、重试次数与回退模型请求统一走 ai-gateway复用 Provider 凭据导入的 Grok Agent 复用 OAuth 且不启动 CLI协议与执行媒体工具经由images/generations、images/edits、videos/generations、videos/{id}协议工作绝不派生嵌套 Agent/CLI视频任务立即返回 job ID付费提交建议携带idempotency_key安全边界产物存放于私有数据目录并附 SHA-256 与过期 URL本地图片输入受规范路径、文件签名与大小检查约束根目录/主目录默认不被信任需要时显式添加allowedInputRoots排错与迁移内部通过 stdio MCP 代理提供确定性工具目录以避免 HTTP 发现导致的工具缺失旧grokMedia/grok-cli配置会在加载时自动迁移到通用mediaTools机制。【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表