Claude Code Router 中的 Claude Design 代理画像：App-only 接入、路由规则与请求验证实战

Claude Design 是 Anthropic 推出的设计类 Agent，在 Claude Code Router（CCR）中被注册为 App-only 的桌面应用画像（profile）——它不能通过终端命令启动，只能从 CCR Desktop 打开，其 Design API 流量会被插件代理到 CCR 网关，从而复用统一的 Provider/模型路由能力。本文以仓库文档 docs/src/content/docs/en/configuration/agents/claude-design.md 为主线，结合 packages/electron/bundled-plugins/claude-design 插件源码与 UI/核心层实现，完整讲解如何创建 Claude Design 画像、配置其路由规则、理解底层插件托管机制，并验证请求确实经过 CCR 网关。

一、Claude Design 在 CCR 中的定位：为什么是 "App only"

文档开篇即明确了适用范围：Claude Design 以桌面应用形态运行，在 CCR 中是 App only，且只能从 CCR Desktop 打开。这一约束不是文档的口头声明，而是贯穿源码的硬性设计：

1. 插件形态：Claude Design 在 CCR 中是一个内置网关插件，位于 claude-design 插件目录。其 plugin.json 声明了它的三个"表面"（surfaces）：

   字段	值	含义
   surfaces.apps	true	会向 CCR Desktop 注册一个可打开的应用入口（Claude Design 窗口）
   surfaces.gateway	true	会注册网关路由/代理路由，接管 Design 相关流量
   surfaces.provider	false	不会伪装成一个 Provider

   插件申请的权限为 trusted-code、apps、gateway-routes、proxy-routes、http-backends、sqlite-store，即"注册应用入口 + 接管网关/代理路由 + 本地存储"三件套，与"App-only、由 CCR 托管"的产品形态完全对应。核心层在 contracts/app.ts 中以 CLAUDE_DESIGN_PLUGIN_ID = "claude-design" 和 DEFAULT_CLAUDE_DESIGN_APP（名称 "Claude Design"、图标 palette）固化了该应用的默认注册信息，并在 KNOWN_GATEWAY_PLUGIN_DEFAULTS 中为它预置了与 plugin.json 一致的权限与 surfaces 默认值。

2. 启动约束：核心层的画像启动服务在 launch-service.ts 中显式检查 profile.agent === "claude-design" 时是否处于桌面应用运行时（isDesktopAppRuntime()），非桌面环境下不走常规 CLI 启动路径。UI 层同样把 claude-design 归入 "app" 类画像：profiles.ts 中 createProfileDraft 对 workbuddy、zcode、claude-design 统一置 surface: "app"。这就是文档"Common issues"里第一条——终端里打不开 Claude Design 是预期行为——的实现依据。

如果你是 CCR 新手，请先配置好至少一个 Provider 与模型。可参考 Provider 添加指南目录 与 Agent 配置文档目录。

二、前置条件

文档列出的三个前置条件，逐条对照 CCR 的实际要求：

1. CCR Desktop 正在运行，且已配置至少一个 Provider + 模型。Claude Design 自身不携带模型凭证，它的请求最终要落到 CCR 网关，再由网关转发到某个已配置的上游。插件实现中，Design 流量默认指向 CCR 网关 http://127.0.0.1:3456（index.cjs 中 DEFAULT_GATEWAY_URL），并带一个默认网关模型名 claude-sonnet-4-20250514（DEFAULT_GATEWAY_MODEL）。
2. Claude Design 通过 CCR Desktop 可用。插件默认的应用入口 URL 为 https://claude-design.ccrdesk.top/design（见 plugin.json 与 contracts/app.ts 中 DEFAULT_CLAUDE_DESIGN_APP.url），窗口由插件注册后从 CCR Desktop 打开。
3. 处于 Agent Config 页面并已点击 Add profile，下文给出具体操作步骤。

三、创建 Claude Design 画像：操作步骤与字段裁剪逻辑

文档给出的操作步骤是：

1. 在 Agent Config 页点击 Add profile，Agent 选择 Claude Design；
2. 填写 Config name（例如 Claude Design）；
3. 可选地添加路由规则（见第五节）；
4. 点击 Save，然后从 CCR Desktop 打开 Claude Design。

UI 层的画像草稿逻辑可以解释"为什么只有名字和路由两类输入"：

• createProfileDraft("claude-design") 生成草稿时 surface 固定为 "app"（profiles.ts）；
• 提交校验 isProfileDraftSubmittable 对 claude-design 直接返回 true（profiles.ts）——即不需要模型、不需要 Provider 选择，只需名字非空；
• 草稿落库时 profileConfigFromDraft 强制 env 为空对象、model 为空串（profiles.ts）；
• 归一化函数 normalizeProfileItem 对 claude-design 的分支最终产出结构为：agent: "claude-design"、surface: "app"、scope: "ccr"、env: {}、model: ""，仅保留 name、enabled 与可选的 routing（profiles.ts）。

因此文档"Configuration reference"一节的结论——Claude Design 固定为 App only、Only opened from CCR，多数 Agent 字段不适用——在源码层面就是画像归一化时被裁掉的结果。文档给出的字段对照表完整继承如下：

字段	如何设置	效果
Agent	选择 Claude Design	注册一个 App-only、由 CCR 管理的画像
Config name	自由文本，如 Claude Design	在 CCR 中标识该画像
Enabled	开/关开关	禁用的画像不会被应用，也不会出现在启动入口
Routing	可选的路由规则	影响该画像请求如何被路由，详见路由文档

落盘后的画像配置大致形如（字段语义以上述 normalizeProfileItem 分支为准，路由示例为演示用途）：

{
  "agent": "claude-design",
  "enabled": true,
  "name": "Claude Design",
  "scope": "ccr",
  "surface": "app",
  "env": {},
  "model": "",
  "routing": {
    "enabled": true,
    "enhancedRoute": true,
    "rules": [
      {
        "id": "claude-design-route-0",
        "name": "pin-design-requests",
        "enabled": true,
        "type": "model-prefix",
        "pattern": "claude-",
        "target": "openrouter/anthropic/claude-sonnet-4",
        "fallback": { "mode": "retry", "models": [], "retryCount": 1 }
      }
    ]
  }
}

四、路由规则：enhanced-route 恒为开，只有显式规则生效

文档"Routing"一节的原意：可以给 Claude Design 画像挂载路由规则，控制它的请求由哪个 Provider/模型处理（例如钉住某个 Provider 或加入 failover）；enhanced-route 开关对 Claude Design 不适用（恒为开启），只有显式规则起作用。

源码中有两处直接印证：

1. enhancedRoute 被强制为 true。UI 的 profileRoutingConfigFromDraft 中，supportsEnhancedRoute 仅对 claude-code 与 codex 为真，其余 Agent 一律写入 enhancedRoute: true（profiles.ts）。也就是说 Claude Design 的画像永远以"增强路由"姿态进入路由管线，用户侧没有开关可关。
2. 脚本型规则被过滤。画像路由规则的收集逻辑会 filter((rule) => rule.type !== "script")（profiles.ts 与 L448），因此 Claude Design 画像可用的是 condition 与 model-prefix 两类规则（脚本规则 script 不入画像路由）。

规则的数据结构定义在 contracts/app.ts：

• RouterRule：包含 id、name、enabled、type（condition | model-prefix | script）、pattern、condition（left / operator / right 三元组）、target（命中的 Provider/模型目标）、rewrite(s)（对请求体的改写）以及可选 fallback；
• RouterFallbackConfig：mode 取 off | retry | model-chain，retryCount 上限由常量 ROUTER_FALLBACK_MAX_RETRY_COUNT = 9999 约束（contracts/app.ts）。这对应文档中"add failover"的场景：为 Design 请求配置主模型 + 重试或模型链回退。

完整规则语义与 UI 操作以 Routing 文档 为准。

五、插件实现纵深：CCR 如何托管 Claude Design 的流量

理解"为什么请求必然经过 CCR"，需要看 index.cjs 的 setup 流程（L530-L820）：

1. 注册 HTTP 后端（claude-design-mock）：一个本地 mock/包装后端，负责 Design 前端页面、Omelette RPC（/design/anthropic.omelette.api.v1alpha.OmeletteService 前缀）、Design REST API、bootstrap 与隐私同意探测等路径，并把真正的模型请求改写发往 CCR 网关；
2. 注册代理路由：claude-design-proxy 把路由主机（默认 claude.ai）上的 /v1/design、组织接口、bootstrap 等路径代理到上述后端；若前端资源来自独立源站，还会追加 claude-design-frontend-assets-proxy；对 claude.com、www.anthropic.com 等回退主机注册 fallback 路由（claude-design-fallback-*）；
3. 注册管理路由：/plugins/claude-design 前缀的网关管理路由（claude-design-admin），提供插件自身的配置读取/更新接口；
4. 注册应用入口：registerClaudeProductBrowserApp 调用 ctx.registerApp 向 CCR Desktop 暴露 "Claude Design" 应用项，点击即在独立 Electron 窗口中打开（L824-L843）。

存储与可观测方面，插件通过 ctx.openSqliteStore 打开 claude-design.sqlite，建表包括 claude_design_requests（方法、路径、请求/响应头与正文、状态码）、claude_design_assets、claude_design_items（项目/设计系统/会话）、claude_design_files（项目文件内容）等（L627-L693）。其中 claude_design_requests 与请求日志开关（requestLogging，默认关闭，requestLogLimit 默认 500 条、保留 24 小时）配合，可在插件层留存 Design 请求明细。

插件还支持一段内部路由配置 routing，其路由类型为 always、image、long-context、model、model-prefix、thinking、web-search（CLAUDE_DESIGN_ROUTE_TYPES，index.cjs），用于在 Design 请求进入 CCR 网关之前决定映射到哪个网关模型；它与第五节画像级 RouterRule 是两层互补的控制点：前者作用于 Design 流量入口，后者作用于 CCR 网关的 Provider/模型选择。

插件 README（packages/electron/bundled-plugins/claude-design/README.md）还补充了两个实操要点：

• 插件可通过 CCR Desktop 的 Extensions 页面安装：Install → Choose folder 选择 claude-design 插件目录并启用；Claude Design 与 Claude Ship 是两个独立插件，互不替代；
• 当打包应用拥有 ccr:// 协议处理器时，可用 open 'ccr://plugin/claude-design/open' 打开窗口；
• README 给出了健康判据：Claude Design 能打开、能创建项目、能列出项目、能发送一条 agent 消息。

相关实现有对应测试覆盖：claude-design 窗口测试、claude-design 插件资产测试、插件权限测试，可作为行为验证的参考用例。

六、打开、使用与验证

文档"Open and use / Verify"章节的操作与验证路径如下：

打开：从 CCR Desktop 打开 Claude Design。再次强调：它不能用终端 profile 命令启动（对应 launch-service.ts 的桌面运行时检查与 UI 层 profileOpenCommandFallback 对 claude-design 的特殊处理，profiles.ts）。

验证三步：

1. 从 CCR Desktop 打开 Claude Design；
2. 发送一条请求并确认完成；
3. 在 CCR 中打开 Request logs，确认该请求经过了网关。

第 3 步的原理：Design 的模型请求经插件代理改写后进入 CCR 网关（默认 127.0.0.1:3456），与 Claude Code、Codex 等画像共享同一套请求日志与可观测管线，因此在 CCR 的请求日志中看到 Design 请求记录，即证明"画像 → 插件 → 网关 → 上游 Provider"链路成立。

七、常见问题（含源码依据）

现象	文档给出的处理	源码层面的解释
终端里无法打开 Claude Design	预期行为，它是 App-only，只能从 CCR Desktop 打开	launch-service.ts 要求桌面应用运行时；画像 surface 归一化为 "app"
请求绕过了 CCR	确认画像为 Enabled，并且确实是从 CCR Desktop 打开的 Claude Design	只有插件注册的应用入口（ctx.registerApp）才会加载走 CCR 网关的页面与代理路由；直接访问线上地址不会经过本地插件
路由规则不生效	只有显式规则生效；enhanced-route 对 Claude Design 恒为开	profileRoutingConfigFromDraft 强制 enhancedRoute: true 并过滤 script 规则（profiles.ts）；画像未配置任何规则时 routing 字段本身不写入

八、小结

Claude Design 画像在 CCR 中是一类极简但完整的接入形态：画像层只需"名字 + 启用开关 + 可选路由规则"，App-only 的窗口托管、流量劫持（/v1/design、Omelette RPC、bootstrap 等路径）、本地 SQLite 请求留存与 ccr:// 深链打开能力全部由 claude-design 插件 承担。掌握本文内容后，你可以：完成 Claude Design 画像的创建与字段裁剪逻辑的理解；为其编写 condition / model-prefix 路由规则与 failover 回退；借助 Request logs 与插件 sqlite 请求表验证请求确实穿过 CCR 网关；并区分"画像级路由规则"与"插件级 routing 路由类型"两层控制点的适用位置。