From 7577ca9572c86c5ee50f8ecebfa1dabac9f7090e Mon Sep 17 00:00:00 2001 From: Jason Date: Mon, 12 Oct 2026 17:34:31 +0800 Subject: [PATCH] docs(deeplink): rework the link generator and document iconUrl deplink.html becomes a generator for site owners instead of a test page: a sidebar layout with light and dark themes, tabs for provider, MCP, prompt and Skill links, per-app `apiFormat` choices, usage script templates, and examples that follow the v4.0.10 rules (Pi providers, the activation toggle, `apiFormat`). iconUrl: - The generator gets an `iconUrl` field and checks it with the same shape rules as the app (https, a domain, default port, no credentials), so a link is never generated with an address CC Switch would drop. Built-in `icon` names are checked against the same whitelist as the parser. - The parser marks `icon` and `iconUrl` values that would be dropped. - New example and FAQ entry for a site's own icon. - The integration guide adds `iconUrl` to the Node.js sample and a debugging step pointing at the log line. The zh and ja manuals list `iconUrl` and say what `icon` accepts. --- deplink.html | 3202 +++++++++-------- .../deeplink-site-integration-guide-zh.md | 31 +- docs/user-manual/ja/5-faq/5.3-deeplink.md | 3 +- docs/user-manual/zh/5-faq/5.3-deeplink.md | 3 +- 4 files changed, 1641 insertions(+), 1598 deletions(-) diff --git a/deplink.html b/deplink.html index 2c4dd788a..d9b830251 100644 --- a/deplink.html +++ b/deplink.html @@ -4,651 +4,636 @@ - CC Switch 深链接测试 + CC Switch 深链接生成器 + + -
-
-

🔗 CC Switch 深链接测试

-

点击下方链接测试深链接导入功能

-
+ -
- - -
-

📦 配置文件导入示例 v3.8+

- - -
-

- Claude - 完整 JSON 配置导入 -

-

- 通过 Base64 编码的 JSON 配置文件导入完整配置，包含所有四种模型和端点信息。 -

-
- 必需 resource=provider, app=claude, name
- 可选 config (Base64 JSON), - configFormat=json -
-
- - 📥 导入完整配置 - - -
-
-
// 解码后的配置内容:
- {
-   "env": {
-     "ANTHROPIC_AUTH_TOKEN": "sk-ant-test-key123",
-     "ANTHROPIC_BASE_URL": "https://api.anthropic.com/v1",
-     "ANTHROPIC_MODEL": "claude-sonnet-4.5",
-     "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4.1",
-     "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4.5",
-     "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4"
-   }
- } -
+
+ - -
-

🔌 MCP Servers 导入 v3.8+

- -
-

📦📦 JSON 配置示例 - 批量导入多个 MCP Servers

-

- 一次性导入多个 MCP 服务器 (Context7 + Sequential-thinking)。 -

-
- 必需 resource=mcp, apps, config (Base64)
- 可选 enabled +
+
+
ccswitch://v1/import
+

深链接生成器

+

生成 CC Switch 的导入链接：用户点一下，就能把供应商、MCP、提示词或 Skill 仓库导入 CC Switch。也可以把收到的链接贴进解析器，看看里面写了什么。

+
+ +
+
    +
  • 本页按 CC Switch v4.0.10 的规则生成链接。apiFormat、iconUrl 参数和 app=pi 需要 v4.0.10 及以上：更早的版本会忽略 apiFormat（一律用应用的默认格式）和 iconUrl，并拒绝导入 Pi 供应商。
    • +
  • 「导入后立即切换 / 添加 / 启用」由用户在确认框里的开关决定，链接里的 enabled 只是开关的初始值，一般不用写。
    • +
  • 完整说明见 站长深链接接入指南。示例里的域名和 Key 都是假的，导入后无法实际使用。
    • +
- +
+ + +
+

生成器

+

填好表单生成链接。点「在 CC Switch 中打开」可以在本机直接试导入。

+ +
+ + + + +
+ + +
+
+

基本信息

+
+
+ + + Claude Desktop、MiniMax Code 的供应商暂不支持深链接导入 +
+
+ + + +
+
+ + + 必填。地址和 API Key 也必须给出，写在 URL 参数或配置文件里都行。 +
+
+ 填写方式 +
+
+ + +
+
+ + URL 参数：地址、Key 直接写在链接里。配置文件：放一份 Base64 编码的 JSON 或 TOML，适合要带额外设置的情况。 +
+
- -
-
📦 批量 MCP 配置 JSON:
- 
{
-  "mcpServers": {
-    "context7": {
-      "command": "bunx",
-      "args": [
-        "-y",
-        "@upstash/context7-mcp",
-        "--api-key",
-        "ctx7sk-4ddd4f66-e752-4022-b1f6-c8cf6279b80d"
-      ],
-      "env": {}
-    },
-    "sequential-thinking": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-sequential-thinking"
-      ],
-      "env": {}
-    }
-  }
-}
-
- 💡 批量导入说明: 一次性导入 2 个 MCP 服务器
- 📦 服务器 1: context7 - Upstash Context7 MCP 服务器
- 📦 服务器 2: sequential-thinking - 结构化思维推理服务器
- 🎯 目标应用: Claude 和 Codex
- 🔄 智能合并: 如果服务器已存在，只更新应用启用状态，不覆盖配置 +
+

连接

+ +
+
+
+ + + Anthropic 格式在 Claude Code 里不带 /v1，OpenAI 两种格式一般带 /v1；OpenCode、OpenClaw、Hermes、Pi 以在该应用里实测能通的写法为准。 +
+
+ + +
+
+ + + 导入后加为自定义端点 +
+
+ + +
+
+
+ + + +
+ +
+

模型

+
+
+ + + +
+
+
+
+

Claude Code 三档模型。中转站提供的是原版 Claude 模型时全部留空，Claude Code 会用自带的模型列表；只有 DeepSeek、Kimi 这类非原生模型才需要写上。

+
+
+ + + ANTHROPIC_DEFAULT_HAIKU_MODEL +
+
+ + + ANTHROPIC_DEFAULT_SONNET_MODEL +
+
+ + + ANTHROPIC_DEFAULT_OPUS_MODEL +
+
+
+
+
+ +
+

展示与确认

+
+
+ + + CC Switch 内置的图标名，只能是小写字母、数字和 . _ - +
+
+ + + 内置图标里没有你的品牌时用。下载失败退回上面的内置图标 +
+

iconUrl 要求：https、域名（不能是 IP）、默认端口；公开可访问（不带 Cookie 和 Referer）；5 秒内下完、不超过 256 KB；Content-Type 是 PNG、JPEG、WebP 或 SVG 且与文件一致。建议用方形图。

+
+ + +
+

确认框里有「导入后立即切换 / 添加到应用配置」开关，用户可以改。Claude Code、Codex、Gemini CLI、Grok Build 默认关闭；OpenCode、OpenClaw、Hermes、Pi 默认打开。

+
+ + +
+
+
+ +
+

用量查询 可选

+

带上查询脚本，导入后供应商卡片上会直接显示余额。写法见下方用量查询脚本示例。

+
+
+ 查询脚本 +
+ + +
+ + 占位符：{{baseUrl}} {{apiKey}} {{accessToken}} {{userId}} +
+
+ + +
+
+ + + 0 表示不自动查询 +
+
+ + + 脚本里的请求必须与它同源 +
+
+ + +
+
+ + +
+
+ + +
+
+
+ +
+ +
-
- -
-

💬 Prompt 导入 v3.8+

- -
-

Claude 代码审查专家

-

为 Claude 导入代码审查提示词。

-
- 📥 导入 - -
- - -
-
📝 Prompt 内容:
-
# 代码审查专家 - - 你是一位有经验的代码审查员，请在代码审查回复的时候做启下。
-
- • 应用: Claude
- • 描述: 专注代码质量
- • 状态: 导入后立即启用 -
-
-
-
- - -
-

🛠️ Skill 仓库导入 v3.8+

- -
-

添加 Claude Skill 仓库

-

- 从 GitHub 仓库导入 Claude Skills，支持指定分支和子目录路径。 -

-
- 必需 resource=skill, repo (owner/name)
- 可选 branch, skills_path, directory -
-
- - 📥 导入 Skill 仓库示例 - - -
- - -
-
🗂️ 将添加以下 Skill 仓库:
-
• GitHub 仓库: - example/claude-skills
-
• 分支: main (默认分支)
-
• Skills 路径: skills - (仓库中技能文件所在的子目录)
-
• 本地目录: my-skills (克隆到本地的目录名) -
-
- 💡 说明: 此操作会把仓库添加到 Skill 列表中。添加后，您可以在 Skills 管理界面选择安装具体的技能文件。
- 🔧 应用: Claude (Skills 功能仅支持 Claude) -
-
-
-
- - -
-

🚀 深链接生成器

-

- 填写参数信息，自动生成深链接并导入到 CC Switch -

- -
-

🔌 MCP Servers 导入生成器

- -
- - - 多个应用用逗号分隔 -
- -
- - - 完整的 MCP 配置 JSON + 导入即写入所选应用的配置文件；已存在同 ID 的服务器只勾上新的应用，不覆盖配置。 +
+
- -
- - -
- - - -
- -
-

🔐 Base64 编解码器

- -
-

编码器 (UTF-8 → Base64)

-
- - + +
+

解析器

+

贴一条 ccswitch:// 链接，查看它会导入什么。会被 CC Switch 拒绝或忽略的参数会标出来。

+
+
+ +
- - +
-
-

解码器 (Base64 → UTF-8)

-
- - + +
+

Base64 编解码

+

按 UTF-8 编码，中文没问题。编码结果可以直接放进链接的 config 或 content 参数（生成器会自动做这一步）；解码用来检查链接里的配置对不对。

+
+
+

编码

+ +
+
- -
-
-

💡 使用建议

-
    -
  • 编码配置文件：将 JSON 或 TOML 内容编码后用于 config 参数
    • -
  • 编码 Prompt：将 Markdown 提示词内容编码后用于 content 参数
    • -
  • 验证深链接：解码验证深链接中的配置内容是否正确
    • -
  • UTF-8 支持：完整支持中文及其他 Unicode 字符
    • -
+ +
+

供应商示例

+

每条都能直接点开试导入。链接都按规则做过 URL 转义，可以照着改。

+
+
+
Claude Code

完整 JSON 配置（非原生模型）

+

通过 Base64 编码的 JSON 配置导入。中转站提供的是原版 Claude 模型时，模型字段全部留空即可；只有 DeepSeek、Kimi 这类非原生模型才需要像这样写上四档模型。

+
+
必需
resource=provider app=claude name，地址和 Key（URL 参数或 config 里）
+
可选
config（Base64 JSON）configFormat=json
+
+
+
解码后的 config
+ 
{
+  "env": {
+    "ANTHROPIC_AUTH_TOKEN": "sk-test-key123",
+    "ANTHROPIC_BASE_URL": "https://api.example.com",
+    "ANTHROPIC_MODEL": "example-chat",
+    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "example-fast",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "example-chat",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "example-pro"
+  }
+}
+
+
+ 在 CC Switch 中打开 + +
+
+ +
+
Claude Code

配置文件 + URL 参数覆盖

+

配置文件放地址和额外的环境变量，Key 用 URL 参数给出。两边都有时以 URL 参数为准。

+
+
必需
name config
+
可选
apiKey（覆盖配置文件里的值）
+
+
+
解码后的 config
+ 
{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.example.com",
+    "API_TIMEOUT_MS": "600000"
+  }
+}
+
URL 参数：apiKey=sk-test-key123
+
+
+ 在 CC Switch 中打开 + +
+
+ +
+
Codex

附带 config.toml

+

Codex 的 config 是 {"auth": {...}, "config": "<config.toml 原文>"}。CC Switch 只收选中的那张 [model_providers.<id>] 表和顶层的模型相关字段，导入后表名统一改成 custom。

+
+
必需
name config
+
可选
configFormat=json（也可以用 configFormat=toml 直接放 config.toml 原文）
+
+
+
auth
+ 
{
+  "OPENAI_API_KEY": "sk-test-key123"
+}
+
config（TOML）
+ 
model_provider = "example"
+model = "example-coder"
+
+[model_providers.example]
+name = "Example AI"
+base_url = "https://api.example.com/v1"
+wire_api = "responses"
+
+
+ 在 CC Switch 中打开 + +
+
+ +
+
Gemini CLI

Gemini 配置

+

Gemini 的 config 是扁平的键值对，只读 GEMINI_API_KEY、GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL 三个键。

+
+
必需
name config
+
可选
configFormat=json
+
+
+
解码后的 config
+ 
{
+  "GEMINI_API_KEY": "AIzaSy-test-key123",
+  "GOOGLE_GEMINI_BASE_URL": "https://api.example.com"
+}
+
+
+ 在 CC Switch 中打开 + +
+
+ +
+
OpenCode

用 apiFormat 声明 Anthropic 格式

+

OpenCode、OpenClaw、Hermes、Pi 自己支持多种接口格式，apiFormat 会换算成它们配置里的协议字段，客户端直接用这种格式请求接口。不写时用 OpenAI Chat Completions。

+
+
必需
name endpoint apiKey
+
可选
apiFormat model（OpenCode / OpenClaw / Hermes 不写就没有可选的模型）
+
+
+
链接参数
+ 
app=opencode
+endpoint=https://api.example.com/v1
+apiFormat=anthropic    → OpenCode 的 npm = @ai-sdk/anthropic
+model=example-chat
+
+

需要 v4.0.10 及以上。更早的版本会忽略 apiFormat，按 Chat Completions 导入。

+
+ 在 CC Switch 中打开 + +
+
+ +
+
Pi

Pi 供应商（必须写模型）

+

Pi 的供应商节点必须带模型，链接里没写 model 会被拒绝。apiFormat 换算成 Pi 的 api 字段。

+
+
必需
name endpoint apiKey model
+
可选
apiFormat
+
+
+
链接参数
+ 
app=pi
+endpoint=https://api.example.com/v1
+apiFormat=openai_chat  → Pi 的 api = openai-completions
+model=example-chat
+
+

需要 v4.0.10 及以上，更早的版本会拒绝导入。

+
+ 在 CC Switch 中打开 + +
+
+
+
Claude Code

带上自己的图标

+

内置图标里没有你的品牌时，用 iconUrl 给一个图片地址。确认框一打开就下载，导入后作为卡片图标；下载失败时退回 icon，没写 icon 就显示名称首字母。这条示例借用 CC Switch 自己的图标。

+
+
必需
name endpoint apiKey
+
可选
iconUrl icon（下载失败时的退路）
+
+
+
链接参数
+ 
iconUrl=https://raw.githubusercontent.com/farion1231/cc-switch/main/src-tauri/icons/128x128.png
+
+

需要 v4.0.10 及以上，更早的版本会忽略 iconUrl。图片会被重新画成 96×96 的 PNG 存进 CC Switch，之后不再访问这个地址。

+
+ 在 CC Switch 中打开 + +
+
-
+ - -
-

⚠️ 使用注意事项

-
    -
  • 首次点击：浏览器会询问是否允许打开 CC Switch，请点击"允许"或"打开"
    • -
  • macOS 用户：可能需要在"系统设置" → "隐私与安全性"中允许应用
    • -
  • 测试 API Key：示例中的 API Key 仅用于测试格式，无法实际使用
    • -
  • 导入确认：点击链接后会弹出确认对话框，API Key 会被掩码显示（前4位+****）
    • -
  • 编辑配置：导入后可以在 CC Switch 中随时编辑或删除配置
    • + +
    +

    用量查询脚本示例

    +

    让用户导入后，直接在供应商卡片上看到余额。

    +
      +
    • 脚本是一段 JavaScript 表达式，返回 { request, extractor }：request 描述发什么请求，extractor(response) 从响应 JSON 里取数。请求由 CC Switch 代发，脚本本身没有网络能力。
      • +
    • 占位符：{{apiKey}}（usageApiKey，没给时用供应商 Key）、{{baseUrl}}（usageBaseUrl，没给时用供应商地址）、{{accessToken}}、{{userId}}。
      • +
    • 每次只发一个请求，必须是 HTTPS，且与 {{baseUrl}} 同源；响应必须是 JSON。余额接口在另一个域名时，用 usageBaseUrl 指过去。
      • +
    • extractor 返回对象或对象数组，字段都可选：remaining、used、total（数字）、unit、planName、extra（字符串）、isValid（布尔）、invalidMessage（字符串）。数字字段如果接口返回的是字符串，要先用 Number() 转。
      • +
    • 带了 usageScript 就默认启用（v4.0.10 起）；要兼容更早的版本，同时写上 usageEnabled=true。usageAutoInterval 是自动查询间隔（分钟），别设得太短。
    -
- - -
-

🔍 深链接解析器

-

粘贴深链接 URL，查看解析结果

- -
- - -
- - - - - -
- - -
-

🛠️ 深链接生成器

-

填写下方表单，生成您自己的深链接

- - -
- - - - URL 参数模式：直接在 URL 中传递参数 | 配置文件模式：使用 Base64 编码的 JSON/TOML - -
- -
- - -
- -
- - - - ⚠️ 唯一必填项 - -
- - -
-
- - -
- -
- - - - 主 API 端点地址 - -
- -
- - - - 多个备用端点用逗号分隔，导入后自动添加为自定义端点 - -
- -
- - -
-
- - - - -
- - - - 通用模型字段，适用于所有应用类型 - -
- - -
-
-

- 📋 Claude 专用模型字段（可选） -

-

- 可以根据需要设置特定的模型字段，这些字段仅在 Claude 应用中生效 -

- -
- - - - 对应环境变量：ANTHROPIC_DEFAULT_HAIKU_MODEL - -
- -
- - - - 对应环境变量：ANTHROPIC_DEFAULT_SONNET_MODEL - -
- -
- - - - 对应环境变量：ANTHROPIC_DEFAULT_OPUS_MODEL - -
-
-
- -
- - - - 图标名称，用于在界面中显示 - -
- -
- - -
- -
- - -
- - -
-

- 📊 用量查询配置（v3.9+，可选） -

-

- 配置用量查询脚本，可自动查询 API 余额 -

- -
- - -
- -
- - - - 用量查询接口的基础地址，必须与脚本中的请求 URL 同源 - -
- -
- - -
- -
- - - - 支持模板变量：{{baseUrl}}、{{apiKey}}、{{accessToken}}、{{userId}} - -
+}) +
假设接口返回 {"balance": 12.5}，卡片显示剩余 12.5 USD。{{baseUrl}} 是供应商地址原样，地址带 /v1 时拼出来也带。
+ +
+ 在 CC Switch 中打开 + +
+ -
- - - - 0 表示禁用自动查询 - -
- -
- - -
- -
- - -
+
+
Codex

NewAPI / OneAPI 系的站

+

这类站的余额接口用系统访问令牌和用户 ID，不用 API Key。供应商地址带 /v1，余额接口在根路径下，所以用 usageBaseUrl 指向根地址。

+
+
必需
usageScript usageAccessToken usageUserId
+
可选
usageBaseUrl（这里是 https://api.example.com）usageAutoInterval（这里是 30）
+
+
+
查询脚本（链接里是它的 Base64）
+ 
({
+  request: {
+    url: "{{baseUrl}}/api/user/self",
+    method: "GET",
+    headers: {
+      "Authorization": "Bearer {{accessToken}}",
+      "New-Api-User": "{{userId}}"
+    }
+  },
+  extractor: function (response) {
+    if (response.success && response.data) {
+      return {
+        planName: response.data.group,
+        remaining: response.data.quota / 500000,
+        used: response.data.used_quota / 500000,
+        unit: "USD"
+      };
+    }
+    return { isValid: false, invalidMessage: String(response.message || "查询失败") };
+  }
+})
+
500000 是 NewAPI 默认的额度换算比例，改过的话按自己的值写。系统访问令牌的权限比 API Key 大，只在用户本人登录后生成的链接里放。
+
+
+ 在 CC Switch 中打开 + +
+
+ - - - -
+ + + +
+

提示词示例

+
+
+
Claude Code

代码审查专家

+

为 Claude Code 导入一条提示词。确认框里有「导入后立即启用」开关，默认关闭；用户打开后会替换当前的提示词文件（如 CLAUDE.md）。

+
+
必需
resource=prompt app name content（Base64 Markdown）
+
可选
description enabled（开关的初始值，一般不要写）
+
+
+
解码后的 content
+ 
# 代码审查专家
+
+你是一位有经验的代码审查员。审查代码时，先指出会导致错误的问题，再给出修改建议。
+
+
+ 在 CC Switch 中打开 + +
+
+
+
+ + +
+

Skill 仓库示例

+
+
+
Skills

添加 Skill 仓库

+

把一个 GitHub 公开仓库加进 Skill 仓库列表。添加的是仓库，用户还要在 Skills 管理界面自己选择安装哪些 Skill。

+
+
必需
resource=skill repo（owner/name）
+
可选
branch（默认 main）
+
+
+
链接参数
+ 
repo=example/claude-skills
+branch=main
+
+
+ 在 CC Switch 中打开 + +
+
+
+
+ + +
+

常见问题

+
+
点了没反应
+
第一次点击时浏览器会询问是否打开 CC Switch，选「允许」或「打开」。macOS 上如果仍然打不开，到「系统设置 → 隐私与安全性」里允许 CC Switch。
+
导入时会发生什么
+
CC Switch 弹出确认框，API Key 打码显示。「导入后立即切换 / 添加 / 启用」由用户在确认框里的开关决定，链接只给初始值。
+
导入之后
+
可以在 CC Switch 里随时编辑或删除导入的内容。
+
iconUrl 的图标没显示
+
CC Switch 下载失败时不报错，直接退回内置图标或名称首字母。常见原因：地址要登录或开了防盗链、响应头 Content-Type 写成了 application/octet-stream、图片超过 256 KB、域名解析到内网地址。用 curl -I 看一下响应头，或者在 CC Switch 的日志里搜 Skipped deep link icon。
+
示例能直接用吗
+
不能。示例里的域名和 Key 都是假的，只用来演示格式。
+
+
+
+
+ diff --git a/docs/guides/deeplink-site-integration-guide-zh.md b/docs/guides/deeplink-site-integration-guide-zh.md index d705bd488..6f55e2aa0 100644 --- a/docs/guides/deeplink-site-integration-guide-zh.md +++ b/docs/guides/deeplink-site-integration-guide-zh.md @@ -1,5 +1,7 @@ # 在你的网站上放「一键导入 CC Switch」按钮：站长接入指南 +如果你是站长，可以通过 CC Switch 让你的用户一键把你的供应商导入到 Claude Code、Codex 等 Agent 应用中使用。 + > 适用版本：CC Switch v4.0.10 及以上。文中标了「v4.0.10 起」的行为在更早的版本上不同，差异见文末「兼容旧版本」。本文根据当前代码整理，示例里的域名和 Key 都是假的。 ## 这篇写给谁 @@ -102,13 +104,36 @@ Claude Desktop、MiniMax Code 的供应商暂不支持深链接导入，链接 | `model` | 默认模型。Claude Code 用原版 Claude 模型时留空；Codex 不写会用 `gpt-5-codex`，Grok Build 不写会用 `grok-4.5`；Pi 必填 | | `haikuModel` / `sonnetModel` / `opusModel` | 仅 Claude Code：三档模型别名对应的真实模型名，非原生模型才需要 | | `homepage` | 官网。不写时从地址推断（去掉 `api.` 前缀） | -| `icon` | CC Switch 内置图标的名字（小写），不认识的名字显示名称首字母。你的品牌没有内置图标时不用写 | +| `icon` | CC Switch 内置图标的名字，只能是小写字母、数字和 `. _ -`，其他写法会被丢掉；不认识的名字显示名称首字母。你的品牌没有内置图标时不用写 | +| `iconUrl` | 你自己的图标图片地址，见下文「带上你的图标」。下载失败时退回 `icon` | | `notes` | 备注，显示在供应商卡片上 | | `enabled` | 确认框里「导入后立即切换 / 添加」开关的初始值，用户可以改。一般不用写 | | `config` + `configFormat` | 附带配置原文，Base64。`configFormat` 取 `json`（默认）或 `toml` | `configUrl`（远程配置）还没实现，带了这个参数的链接会被直接拒绝。 +### 带上你的图标：iconUrl + +CC Switch 内置图标里没有你的品牌时，用 `iconUrl` 给一个图片地址。确认框一打开，CC Switch 就下载这张图并显示在顶部，用户导入后它就是卡片图标，不需要用户再点什么。 + +图片会被重新画成 96×96 的 PNG 存进 CC Switch，之后不再访问这个地址。你以后换了图标，已经导入的用户不会跟着变。 + +地址和图片要满足下面的条件，任何一条不满足，确认框不报错，图标退回 `icon` 指定的内置图标，没写 `icon` 就显示名称首字母： + +- `https://` 开头，主机是域名（不能是 IP），默认端口，不带账号密码。形状不对的地址在解析链接时就被丢掉，链接其余部分照常导入。 +- 公开可访问：CC Switch 下载时不带 Cookie 和 Referer，也不走用户的系统代理。需要登录、开了防盗链的地址都会失败。 +- 域名解析到的地址必须是公网地址，指向内网、本机的一律不下载。 +- 5 秒内下载完，最多跟 3 次重定向，每次重定向的目标也要满足上面这些条件。 +- 不超过 256 KB。 +- 响应头 `Content-Type` 是 `image/png`、`image/jpeg`、`image/webp` 或 `image/svg+xml` 之一，并且和文件实际格式一致。`application/octet-stream` 之类的通用类型不行。 +- 位图宽高不超过 4096 像素。 + +图片本身的建议： + +- 用方形图。四角不透明的方图会铺满整个图标框；四角透明的 logo 会缩到中间，四周留白，和内置图标的样子一致。 +- SVG 只当图片显示，里面的脚本不执行，引用的外部字体、图片也不加载，文字请转成路径。 +- 每个用户打开确认框时都会请求一次这个地址，放在 CDN 上即可。 + ### Claude Code：附带环境变量 需要额外环境变量的站（自定义请求头、超时、关闭实验特性等），把它们放进 `config`： @@ -346,6 +371,8 @@ function claudeImportLink(user) { // 提供原版 Claude 模型时模型全部留空；DeepSeek、Kimi 这类非原生模型才写 // model / haikuModel / sonnetModel / opusModel homepage: "https://example.com", + // 内置图标里没有你的品牌时，给一个自己的图标地址，见「带上你的图标」 + iconUrl: "https://example.com/static/logo.png", usageScript: b64(usageScript), usageEnabled: "true", }); @@ -427,6 +454,7 @@ function b64(text) { 2. 确认框直接报错时，错误信息就是原因，对照上面「会被拒绝的链接」排查。 3. 导入成功但余额不显示：在供应商卡片上打开「配置用量查询」，点「测试脚本」看报什么错。最常见的是请求地址不同源、余额接口返回的不是 JSON、`extractor` 里取错了字段。 4. 导入成功但切过去后请求失败：多半是接口格式不对（见「支持哪些应用」），或模型名不对。 +5. `iconUrl` 的图标没显示：下载失败不会报错，原因写在 CC Switch 的日志里（`~/.cc-switch/logs/cc-switch.log`，搜 `Skipped deep link icon`）。最常见的是 `Content-Type` 不对、图片超过 256 KB、地址要登录或开了防盗链，用 `curl -I` 看一下响应头。 ## 兼容旧版本 @@ -440,6 +468,7 @@ function b64(text) { | CC Switch 没开着时点链接 | 启动后弹出确认框 | 偶尔丢失，要再点一次 | | `apiFormat` | 按应用换算 | 忽略，一律用默认格式 | | `app=pi` | 支持 | 拒绝导入 | +| `iconUrl` | 下载并作为卡片图标 | 忽略，显示 `icon` 或名称首字母 | | 「导入后立即切换 / 启用」 | 确认框里的开关，`enabled` 是初始值 | 直接按链接的 `enabled` 执行；OpenCode / OpenClaw / Hermes 总是写进应用配置 | 想让各个版本表现一致：用量查询显式写 `usageEnabled=true`；Codex / Grok Build 的关键信息（地址、Key、模型）同时写进 URL 参数，不要只放在 `config` 里。你的接口不是应用的默认格式时，旧版本导入的卡片格式会不对，可以在按钮旁提示用户升级 CC Switch。 diff --git a/docs/user-manual/ja/5-faq/5.3-deeplink.md b/docs/user-manual/ja/5-faq/5.3-deeplink.md index 6108af3fc..a4304557e 100644 --- a/docs/user-manual/ja/5-faq/5.3-deeplink.md +++ b/docs/user-manual/ja/5-faq/5.3-deeplink.md @@ -55,7 +55,8 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&... | `sonnetModel` | いいえ | Sonnet モデル（Claude のみ） | | `opusModel` | いいえ | Opus モデル（Claude のみ） | | `notes` | いいえ | メモ | -| `icon` | いいえ | アイコン | +| `icon` | いいえ | CC Switch 内蔵アイコン名。英小文字・数字と `. _ -` のみ使用でき、それ以外は無視されます | +| `iconUrl` | いいえ | 独自アイコン画像の URL（v4.0.10 以降）。確認ダイアログを開いた時点でダウンロードし、インポート後はカードのアイコンになります。https・ドメイン名・デフォルトポートであること、公開アクセス可能であること、256 KB 以下で `Content-Type` が PNG / JPEG / WebP / SVG のいずれかかつ実際の形式と一致していることが条件です。ダウンロードに失敗してもエラーにはならず、`icon` または名前の頭文字が表示されます | | `config` | いいえ | Base64 エンコードされた設定内容。Codex は `{"auth": {...}, "config": ""}` の形式、または `configFormat=toml` で config.toml 全体を渡します。選択された `[model_providers.*]` テーブルの接続・認証フィールド（`wire_api`、`http_headers`、`supports_websockets`、エンドポイントと同一オリジンの `model_catalog_url` など）と、トップレベルのモデル・推論レベル・`web_search` などのみをインポートし、ルートは常に `custom` に変更されます。`[features]`、MCP、権限などのグローバル設定はインポートされません。テーブルに `auth`、`aws`、`gateway_oauth`、`env_http_headers` を含むリンクは拒否され、`env_key` は無視されます（リンク自身のキーを使用） | | `configFormat` | いいえ | 設定形式：`json` / `toml` | | `configUrl` | いいえ | 未対応です。指定したリンクは拒否されるため、`config` でインライン指定してください | diff --git a/docs/user-manual/zh/5-faq/5.3-deeplink.md b/docs/user-manual/zh/5-faq/5.3-deeplink.md index e165c88e2..a101a2a5f 100644 --- a/docs/user-manual/zh/5-faq/5.3-deeplink.md +++ b/docs/user-manual/zh/5-faq/5.3-deeplink.md @@ -55,7 +55,8 @@ ccswitch://v1/import?resource={type}&app={app}&name={name}&... | `sonnetModel` | 否 | Sonnet 模型（仅 Claude） | | `opusModel` | 否 | Opus 模型（仅 Claude） | | `notes` | 否 | 备注 | -| `icon` | 否 | 图标 | +| `icon` | 否 | CC Switch 内置图标名，只能是小写字母、数字和 `. _ -`，其他写法会被丢掉 | +| `iconUrl` | 否 | 自己的图标图片地址（v4.0.10 起）。确认框打开时下载，导入后作为卡片图标；必须是 https、域名、默认端口，公开可访问，不超过 256 KB，`Content-Type` 为 PNG / JPEG / WebP / SVG 且与文件一致。下载失败时退回 `icon` 或名称首字母，不报错 | | `config` | 否 | Base64 编码的配置内容。Codex 写成 `{"auth": {...}, "config": ""}`，或用 `configFormat=toml` 直接给整份 config.toml；只导入选中的 `[model_providers.*]` 表里的连接和鉴权字段（如 `wire_api`、`http_headers`、`supports_websockets`、与地址同源的 `model_catalog_url`）以及顶层的模型、推理强度、`web_search` 等，选路统一改成 `custom`；`[features]`、MCP、权限等全局设置不导入；表里带 `auth`、`aws`、`gateway_oauth`、`env_http_headers` 的链接会被拒绝，`env_key` 会被忽略（Key 用链接给的） | | `configFormat` | 否 | 配置格式：`json` / `toml` | | `configUrl` | 否 | 暂不支持，带了会被拒绝；请改用 `config` 内联 |