cc-agent-router

为 Claude Code 按任务角色路由不同 API、凭据与模型，同时保留你已经配置好的 MCP、Skill、Plugin、hooks、memory 和项目 CLAUDE.md。

cc-agent-router 是一个面向 Claude Code 的多 provider / 多模型子代理路由器。它让主 Claude 可以把调研、设计、实现、审查和测试交给不同角色，每个角色使用独立的 API、API key、base URL、model 和权限策略。

项目提供三种接入方式：

• Claude Code Plugin（推荐）：MCP 负责执行，Skill 负责告诉 Claude 何时和如何委派；

• CLI：手动列出角色、运行代理、打开可见终端、导入 CC Switch；

• Node API：嵌入自定义编排器。

如果只想尽快跑起来，请先看 快速使用教程。

目录

• 为什么需要它

• 核心能力

• 工作原理

• 要求

• 安装

• 配置

• 从 CC Switch 导入

• CLI 使用

• 安装为 Claude Code Plugin

• 仅配置 MCP

• headless 与 terminal

• 配置继承与隔离边界

• 权限与安全

• Node API

• 故障排查

• 开发与测试

• 设计来源

• 当前限制

• 开源协议

Related MCP server: Claude Code Orchestrator MCP

为什么需要它

CC Switch 的 provider 切换适合改变“当前 Claude Code 使用哪个 API”，但如果多个子代理同时工作，反复覆写同一份 live 配置会带来竞态：

主 Claude
├── research  想用 API A / 模型 A
├── implement 想用 API B / 模型 B
└── review    想用 API C / 模型 C

若三个进程共享同一个正在被覆写的 provider 配置，就可能出现凭据或模型串用。

cc-agent-router 不修改当前用户的 live provider 配置。每次调用都创建独立进程，并只在该进程环境里注入目标 provider 的：

• ANTHROPIC_BASE_URL；

• ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN；

• 该 provider 明确声明的其他环境变量；

• 角色指定的 model、tools、permission 和 prompt。

与此同时，它不会使用 --bare，也不会另建空白 CLAUDE_CONFIG_DIR，所以子代理能继续使用你现有的 Claude Code 工具配置。

核心能力

• 按 role → provider → model 路由任务；

• 不同角色使用不同 API key 和 base URL；

• 多个角色可以并发运行，不覆写用户当前 Claude Code 配置；

• 继承现有 MCP、Skill、Plugin、hooks、memory、用户设置及项目 CLAUDE.md；

• 支持 headless 后台执行并把结果返回主代理；

• 支持 terminal 打开独立可见窗口，让用户实时观察和继续交互；

• 支持用户指定运行文件目录，目录不存在时自动创建；

• 支持从 CC Switch SQLite 数据库只读导入 provider/model；

• CC Switch 凭据不会复制进路由 YAML，每次运行读取最新值；

• 支持 CLI、stdio MCP server、Claude Code Plugin 和 Node API；

• API key 不进入 prompt、命令行、YAML 或返回结果；

• 对子进程输出中的已知凭据执行脱敏；

• 默认仅继承必要环境变量，降低无关业务 secret 泄漏风险；

• Windows 超时终止整个进程树，POSIX 终止独立进程组。

工作原理

┌─────────────────────────────┐
│ 主 Claude Code              │
│ 已有 MCP / Skill / Plugin   │
└──────────────┬──────────────┘
               │ MCP delegate(role, prompt)
               ▼
┌─────────────────────────────┐
│ cc-agent-router             │
│ 1. 解析 role                │
│ 2. 解析 provider/model      │
│ 3. 读取目标凭据             │
│ 4. 构造最小子进程环境       │
└──────┬──────────┬───────────┘
       │          │
       ▼          ▼
  headless      terminal
  后台 JSON     新可见窗口
       │          │
       ▼          ▼
 Claude Code   Claude Code
 API A/model A API B/model B

Provider 与 Agent 分层

providers:
  api-a:
    baseUrl: https://api-a.example.com
    authTokenEnv: API_A_KEY

agents:
  research:
    provider: api-a
    model: model-a
    permissionMode: plan

• provider 管连接方式和凭据来源；

• agent/role 管 model、工具、权限、预算和任务用途；

• 同一 provider 可对应多个模型角色；

• 同一模型也可因权限或 system prompt 不同而配置多个角色。

要求

• Node.js 22.12.0 或更高版本；

• Claude Code CLI，且 claude --version 可运行；

• 目标 provider 能接受 Claude Code 使用的 Anthropic Messages API；

• 使用 CC Switch 导入功能时，需要系统中有 python 和标准库 sqlite3；

• Windows 可见终端默认优先使用 Windows Terminal，缺少时自动回退到 PowerShell。

检查环境：

node --version
claude --version
python --version

安装

从源码安装

git clone https://github.com/CjQkJ/cc-agent-router.git
cd cc-agent-router
npm install
npm run build

直接使用构建后的 CLI：

node dist/cli.js --help

可选：注册全局命令：

npm link
ccar --help

cc-agent-router 和 ccar 是同一个 CLI 的两个命令名。

目前仓库提供源码安装。若未来发布到 npm，可改用 npm install -g cc-agent-router。

配置

生成示例：

ccar init

或不使用全局 link：

node dist/cli.js init

默认生成：

cc-agent-router.yaml

配置查找顺序

1. CLI --config <path>；

2. 环境变量 CC_AGENT_ROUTER_CONFIG；

3. 当前目录 .cc-agent-router.yaml；

4. 当前目录 cc-agent-router.yaml；

5. ~/.config/cc-agent-router/config.yaml。

显式指定的配置不存在时会直接报错，不会静默回退到其他文件。

完整结构

version: 1

defaults:
  claudeExecutable: claude
  # Windows 只有 claude.cmd 时，可使用 node.exe + CLI JS：
  # claudeExecutable: C:/Program Files/nodejs/node.exe
  # claudeExecutableArgs: [C:/path/to/@anthropic-ai/claude-code/cli.js]

  cwd: .
  artifactsDir: E:/claude-agent-runs
  timeoutMs: 1800000
  permissionMode: dontAsk
  maxOutputChars: 8000000
  keepArtifacts: false

  # 默认只继承运行必需环境。工具链确实需要其他非敏感变量时显式加入：
  # inheritEnv: [HTTP_PROXY, HTTPS_PROXY]

providers:
  api-a:
    baseUrl: https://api-a.example.com
    authTokenEnv: API_A_KEY

  api-b:
    baseUrl: https://api-b.example.com
    apiKeyEnv: API_B_KEY

  # 也可将其他子进程变量映射到父进程环境变量：
  # bedrock-a:
  #   env:
  #     CLAUDE_CODE_USE_BEDROCK: "1"
  #     AWS_REGION: us-east-1
  #   envFrom:
  #     AWS_ACCESS_KEY_ID: BEDROCK_A_ACCESS_KEY_ID
  #     AWS_SECRET_ACCESS_KEY: BEDROCK_A_SECRET_ACCESS_KEY
  #     AWS_SESSION_TOKEN: BEDROCK_A_SESSION_TOKEN

agents:
  research:
    provider: api-a
    model: model-a
    effort: high
    description: 调研代码、文档和外部资料；只读
    permissionMode: plan
    tools: [Read, Glob, Grep, WebSearch, WebFetch]
    maxBudgetUsd: 3
    appendSystemPrompt: 只调研并给出有来源的结论，不修改文件。

  implement:
    provider: api-b
    model: model-b
    effort: high
    description: 按明确方案修改代码并测试
    permissionMode: acceptEdits
    tools: [Read, Glob, Grep, Edit, Write, Bash]
    maxBudgetUsd: 5

Defaults 字段

Provider 字段

apiKeyEnv 与 authTokenEnv 只能配置一个。不要把真实 key 写进 env 或 YAML。

设置凭据示例：

PowerShell：

$env:API_A_KEY = "your-api-key"
$env:API_B_KEY = "your-api-key"

Bash：

export API_A_KEY='your-api-key'
export API_B_KEY='your-api-key'

应在启动主 Claude Code 的同一环境中设置变量，让 MCP server 可以读取它们。

启动参数如何对应

每次运行先选择一个 agents 角色，再由该角色组合 provider、模型、权限模式和思考强度。Terminal 模式生成的核心命令类似：

claude --model opus --permission-mode plan --effort high --tools=Read,Glob,Grep -- "任务"

Windows 外层使用：

wt.exe -w new powershell.exe -NoLogo -NoExit -File run-agent.ps1

Headless 模式不会打开窗口，并额外传入：

--no-session-persistence --print --output-format json

配置与命令行的对应关系：

权限模式可配置为 plan、acceptEdits、manual、dontAsk、auto 或 bypassPermissions。推荐只读角色使用 plan，实现角色使用 acceptEdits；不要默认使用 bypassPermissions。角色级 permissionMode 优先于 defaults.permissionMode。

例如，让新窗口第一次启动时处于 Plan 模式并使用高思考强度：

agents:
  research:
    provider: api-a
    model: model-a
    permissionMode: plan
    effort: high

对于手动 provider，apiKeyEnv/authTokenEnv 填写的是父进程环境变量名，不是密钥本身。路由器读取该变量后，仅向目标 Claude 子进程设置 ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN。对于 CC Switch provider，路由器在每次调用时只读数据库，取得目标 provider 的最新 Base URL、凭据和模型档位映射。

Agent 字段

从 CC Switch 导入

如果已经用 CC Switch 管理 Claude provider，可以自动生成路由配置：

node dist/cli.js import-cc-switch -o cc-agent-router.yaml

指定数据库：

node dist/cli.js import-cc-switch \
  --database /path/to/.cc-switch/cc-switch.db \
  --output cc-agent-router.yaml

导入器会：

1. 以 SQLite read-only 模式读取 providers；

2. 只处理 app_type = 'claude'；

3. 为 provider 生成稳定名称；

4. 按 Claude 模型档位（default / fable / opus / sonnet / haiku）生成角色，而不是上游模型名；

5. 把数据库路径和 provider ID 写进 YAML；

6. 不把 API key/token 复制到 YAML。

生成结构示例：

providers:
  cc-switch-example:
    ccSwitch:
      database: /home/user/.cc-switch/cc-switch.db
      providerId: provider-uuid
    baseUrl: https://api.example.com

agents:
  cc-switch-example-opus:
    provider: cc-switch-example
    model: opus
    effort: high
    description: 从 CC Switch provider “example” 自动导入；opus 档映射到 example-opus-model
    permissionMode: dontAsk

CC Switch 模型档位语义（重要）

CC Switch 的模型映射按 Claude 档位工作：

对 CC Switch provider，角色的 model 字段应写档位（default / fable / opus / sonnet / haiku），而不是上游模型名。运行时路由器会执行：

claude --model opus

并把 CC Switch 的 ANTHROPIC_DEFAULT_*_MODEL 映射注入子进程，由 Claude Code 按档位选用对应的上游模型。不要写 model: gpt-5.6-sol 这类上游模型名作为 --model 参数——它绕过了档位映射，上游通常无法识别，会返回 503。

• model: default 时不传 --model，Claude Code 直接使用 ANTHROPIC_MODEL；

• 为兼容旧配置，如果 model 值恰好等于某个档位的映射目标（例如 gpt-5.6-sol），运行时会自动反解为对应档位（例如 opus）；

• 非 CC Switch provider（手写 apiKeyEnv/authTokenEnv/env）不受影响，model 仍直接作为 --model 传递。

每次执行时会重新读取该 provider 的最新 settings_config.env。因此：

• 更新 key：不需要重新导入；

• 更新 base URL：运行时也会读取最新值；

• 更新某档位的上游模型：运行时也会读取最新映射；

• 新增/删除 provider 或 model 档位：需要重新导入以更新角色列表。

导入依赖系统 Python 的 sqlite3 标准库，不需要安装原生 Node SQLite 扩展。

CLI 使用

查看帮助

ccar --help
ccar run --help

列出角色

ccar --config cc-agent-router.yaml list

后台执行

ccar --config cc-agent-router.yaml run \
  --role research \
  --cwd /path/to/project \
  --prompt "分析认证流程，列出关键文件、调用链和风险"

从 stdin 读取任务：

printf '%s' '审查当前实现，只报告可复现问题' | \
  ccar --config cc-agent-router.yaml run --role review

打开可见终端

ccar --config cc-agent-router.yaml run \
  --role implement \
  --mode terminal \
  --cwd /path/to/project \
  --artifacts-dir /path/to/agent-runs \
  --prompt "按项目计划实现功能并运行测试"

Windows PowerShell：

ccar --config E:/configs/cc-agent-router.yaml run `
  --role implement `
  --mode terminal `
  --terminal auto `
  --cwd E:/projects/my-app `
  --artifacts-dir E:/claude-agent-runs `
  --prompt "实现当前任务"

--terminal 可选：

• auto：Windows Terminal → PowerShell 回退；

• windows-terminal：只使用 Windows Terminal；

• powershell：直接打开 PowerShell；

• cmd：通过 cmd 新窗口承载 PowerShell 启动脚本。

Dry run

仅检查将使用的角色、provider、model 和参数，不读取真实凭据、不调用 API：

ccar --config cc-agent-router.yaml run \
  --role implement \
  --prompt "实现功能" \
  --dry-run

结构化输出

ccar --config cc-agent-router.yaml run \
  --role review \
  --prompt "审查当前改动" \
  --schema review.schema.json \
  --json

命令总览

安装为 Claude Code Plugin

这是推荐方式。安装器会生成：

~/.claude/skills/cc-agent-router/
├── .claude-plugin/
│   └── plugin.json
├── .mcp.json
└── SKILL.md

• .mcp.json 启动本项目的 stdio MCP server；

• SKILL.md 告诉主 Claude 在大型任务中如何选择和编排角色；

• API key 不会写入插件。

使用已有路由配置

npm run build
node dist/cli.js install-claude \
  --router-config /absolute/path/to/cc-agent-router.yaml

Windows：

node dist/cli.js install-claude `
  --router-config E:/configs/cc-agent-router.yaml

自动从 CC Switch 导入并安装

node dist/cli.js install-claude

默认在当前目录生成 cc-agent-router.yaml，然后安装 Plugin。

指定数据库：

node dist/cli.js install-claude \
  --cc-switch-database /path/to/.cc-switch/cc-switch.db

安装后重启 Claude Code，或执行：

/reload-plugins

然后可以对 Claude 说：

使用 cc-agent-router，让不同角色完成这个任务：先调研和设计，再实现，最后独立审查和测试。

覆盖升级与卸载

如果 Plugin 的 .mcp.json 指向独立的长期安装目录（例如 Windows 上的 C:/Users/you/cc-agent-router），应直接在该目录拉取更新、构建并重装。不要只更新另一个开发副本，否则当前 Claude Code 仍会运行旧代码。

升级前先确认本地修改和实际配置已备份：

git status
git diff
git pull --ff-only
npm install
npm run build
node dist/cli.js install-claude \
  --router-config /absolute/path/to/cc-agent-router.yaml \
  --force

安装后必须重启 Claude Code，或执行：

/reload-plugins

MCP server 是常驻进程；仅替换 src/ 或 dist/ 文件不会让已启动的会话自动加载新版本。

卸载：

node dist/cli.js uninstall-claude

.mcp.json 指向安装时本项目的绝对 dist/cli.js 路径。安装后不要移动或删除项目目录，否则需重新安装 Plugin。建议只保留一个长期运行副本，避免“开发目录已更新、Plugin 仍指向旧目录”的版本漂移。

仅配置 MCP

如果不想安装自动编排 Skill，只注册 MCP：

claude mcp add --scope user cc-agent-router -- \
  node /absolute/path/to/cc-agent-router/dist/cli.js \
  --config /absolute/path/to/cc-agent-router.yaml \
  mcp

主 Claude 会获得两个工具：

• delegate：选择角色并启动子代理；

• list_agents：查看角色、provider、model、effort 和描述，不返回凭据。

delegate 的主要参数：

{
  "role": "implement",
  "prompt": "完整、自包含的任务说明",
  "cwd": "/path/to/project",
  "artifactsDir": "/path/to/agent-runs",
  "timeoutMs": 1800000,
  "mode": "headless",
  "terminal": "auto"
}

如果仅注册 MCP，建议在项目 CLAUDE.md 添加：

## 多模型委派

处理大型任务时：
1. 调研使用 cc-agent-router 的 research 角色。
2. 架构和计划使用 design。
3. 边界明确后使用 implement。
4. 实现后分别使用 review 和 test，二者不得修改代码。
5. 主代理整合结果、解决冲突并最终验证。
6. 委派 prompt 必须包含 cwd、目标、边界、已有结论和验收标准。

headless 与 terminal

推荐：

• 自动执行 research → design → implement → review/test：用 headless；

• 想实时查看或中途干预：用 terminal。

运行文件目录

通过以下任一方式指定：

defaults:
  artifactsDir: /path/to/agent-runs

ccar run --artifacts-dir /path/to/agent-runs ...

{ "artifactsDir": "/path/to/agent-runs" }

优先级：

本次调用参数 > defaults.artifactsDir > 系统临时目录

根目录不存在时自动创建。每次调用创建：

cc-agent-router-<UUID>/

terminal 脚本不会包含 provider 凭据；凭据只通过新终端进程环境传递。

配置继承与隔离边界

会继承的内容

子代理不会使用 --bare，也不会设置新的 CLAUDE_CONFIG_DIR，因此可加载：

• 用户 Claude Code settings；

• MCP servers；

• Skills；

• Plugins；

• hooks；

• memory；

• 当前项目的 CLAUDE.md；

• Claude Code 正常发现的其他项目配置。

不会继承的内容

每次调用仍是新的、无持久化 Claude Code 进程，不会自动知道：

• 主会话当前对话；

• 尚未写入文件的设计决定；

• 上一个子代理只在回复中给出的结论；

• 主会话临时获得但未保存的资料。

所以委派 prompt 应自包含，例如：

在 /path/to/project 中实现登录限流。

背景：
- Express + PostgreSQL。
- 已决定每个 IP 每分钟 10 次。
- 不修改数据库结构。

要求：
1. 修改 src/auth/login.ts。
2. 添加单元测试。
3. 运行 npm test。

限制：
- 不修改 generated/。
- 保持 API 响应兼容。
- 不提交 Git commit。

返回：修改文件、设计说明、测试结果和遗留问题。

角色 settings

默认完全使用用户配置。只有角色显式声明 settings 时，才创建本次覆盖文件：

agents:
  review:
    provider: api-c
    model: model-c
    settings:
      permissions:
        deny: [Edit, Write]

该文件通过 Claude Code 的 --settings 参数加载，不会创建空白用户配置目录。

权限与安全

推荐角色权限

agents:
  research:
    permissionMode: plan
    tools: [Read, Glob, Grep, WebSearch, WebFetch]

  design:
    permissionMode: plan
    tools: [Read, Glob, Grep]

  implement:
    permissionMode: acceptEdits
    tools: [Read, Glob, Grep, Edit, Write, Bash]

  review:
    permissionMode: plan
    tools: [Read, Glob, Grep, Bash]
    disallowedTools: [Edit, Write]

  test:
    permissionMode: dontAsk
    tools: [Read, Glob, Grep, Bash]
    disallowedTools: [Edit, Write]

不要默认给所有角色使用 bypassPermissions。

凭据处理

• YAML 只记录凭据来源环境变量名，不记录值；

• CC Switch 导入只记录数据库路径和 provider ID；

• API key 不进入命令行；

• headless prompt 通过 stdin 传递；

• terminal 启动脚本不写入凭据；

• 已知凭据若出现在子进程输出中，会替换为 [REDACTED]；

• 父环境采用 allowlist 继承；

• 所有 provider 声明的凭据来源变量都从普通继承列表中排除。

这不是 OS sandbox

配置和进程隔离不能限制当前系统用户本身的文件权限。允许 Bash/Edit/Write 的子代理仍可能读写该账户可访问的文件、运行项目脚本和访问网络。

处理不可信仓库或程序时，请额外使用：

• Docker；

• Windows Sandbox；

• 虚拟机；

• 受限系统账户；

• 只读文件挂载。

Plugin 继承带来的信任边界

继承现有 Plugin、MCP 和 hooks 是本项目有意提供的效率特性，也意味着子代理会执行这些组件。只安装和启用你信任的扩展，并了解它们可能访问的数据和网络。

Node API

import { delegate, loadConfig } from "cc-agent-router";

const { config } = await loadConfig("cc-agent-router.yaml");

const result = await delegate(config, {
  role: "review",
  cwd: process.cwd(),
  artifactsDir: "./agent-runs",
  prompt: "审查当前实现，只报告可复现问题",
  mode: "headless",
});

if (!result.ok) {
  throw new Error(result.stderr || result.text);
}

console.log(result.text);

主要导出：

export { delegate } from "./runner.js";
export { findConfig, loadConfig } from "./config.js";
export { installClaudePlugin, uninstallClaudePlugin } from "./install.js";
export { importCcSwitch } from "./cc-switch.js";
export { RouterError } from "./errors.js";

故障排查

找不到配置文件

显式传入绝对路径：

ccar --config /absolute/path/to/cc-agent-router.yaml list

或设置：

export CC_AGENT_ROUTER_CONFIG=/absolute/path/to/cc-agent-router.yaml

CREDENTIAL_MISSING

确保凭据环境变量存在于启动主 Claude / MCP server 的进程环境：

$env:API_A_KEY = "..."
claude

修改已经运行中的父终端之外的系统环境变量，通常不会自动注入现有 MCP server；请重启 Claude Code。

Windows 无法运行 claude

Node 的 spawn(..., shell: false) 不一定直接启动 .cmd。建议：

defaults:
  claudeExecutable: C:/Program Files/nodejs/node.exe
  claudeExecutableArgs:
    - C:/Users/you/AppData/Roaming/npm/node_modules/@anthropic-ai/claude-code/cli.js

请按本机实际安装路径调整。

terminal 打不开

尝试明确指定：

ccar run --mode terminal --terminal powershell ...

Linux 需要可用的图形终端之一：

• x-terminal-emulator；

• gnome-terminal；

• konsole。

Provider 在 CC Switch 能看到但调用失败（503）

最常见的原因是模型映射方式不对。CC Switch 的模型映射按 Claude 档位工作：

--model opus   → ANTHROPIC_DEFAULT_OPUS_MODEL
--model sonnet → ANTHROPIC_DEFAULT_SONNET_MODEL

如果角色的 model 写成了上游模型名（例如 gpt-5.6-sol），Claude Code 会把它当成档位名去匹配映射，匹配不到就回退到 ANTHROPIC_MODEL，上游往往因此返回 503。

正确做法是对 CC Switch provider 使用档位：

agents:
  research:
    provider: cc-switch-example
    model: opus          # 不是 gpt-5.6-sol

重新导入即可自动按档位生成：

node dist/cli.js import-cc-switch --output cc-agent-router.yaml --force

如果 provider 只支持 OpenAI 的 /v1/chat/completions 而不兼容 Anthropic /v1/messages，路由器无法自动转换协议，需要在中间部署协议转换代理。

terminal 窗口报 0x80070002 或 系统找不到指定的文件

早期版本错误使用了 wt.exe new-window ...，Windows Terminal 不识别 new-window 子命令。当前版本已修复为：

wt.exe -w new powershell.exe -NoLogo -NoExit -File run-agent.ps1

确认 Plugin 已更新并执行 /reload-plugins。仍失败时可显式指定：

ccar run --mode terminal --terminal powershell ...

terminal 报 PowerShell ParserError（中文乱码）

早期版本生成的 run-agent.ps1 是无 BOM 的 UTF-8，Windows PowerShell 5.1 会按本地 ANSI/GBK 读取，中文 system prompt 因此变成乱码并破坏引号。当前版本写入时添加了 UTF-8 BOM（EF BB BF），PowerShell 5.1 可正确解析中文。

terminal 报 --no-session-persistence can only be used with --print mode

--no-session-persistence 仅 headless 支持。当前版本已将该参数限定为 headless 模式，terminal 不再携带它。确认 Plugin 已更新并执行 /reload-plugins。

子代理看不到主会话刚才的结论

这是正常行为。它继承工具配置和项目文件，不继承主会话聊天记录。让主 Claude 将即时背景写进 delegate.prompt。

terminal 目录越来越多

terminal 进程启动后脱离路由器，路由器无法可靠判断用户何时结束交互。关闭对应窗口后，手动删除 cc-agent-router-<UUID> 子目录。

MCP 或 Skill 修改后未生效

重启 Claude Code，或执行：

/reload-plugins

开发与测试

npm install
npm run check
npm test
npm run build

当前测试覆盖：

• Claude CLI 参数构造、prompt 脱敏和 terminal/headless 参数分离；

• CC Switch 档位模型语义（opus 等档位、上游模型名反解、default 不传 --model）；

• 配置查找、schema 校验和相对路径解析；

• 子进程环境 allowlist 和凭据替换；

• dry-run；

• 自定义运行目录创建；

• terminal 脚本不落盘凭据；

• Windows Terminal wt.exe -w new 启动语法与 PowerShell/cmd 路径；

• Windows PowerShell 5.1 中文脚本 UTF-8 BOM 解析；

• MCP 真实握手和工具调用；

• Plugin 文件生成及 Claude 官方严格校验；

• CC Switch 只读导入、按档位生成角色且不复制凭据。

打包预览：

npm pack --dry-run

项目使用 TypeScript ESM，编译产物位于 dist/，不提交到 Git。

贡献

欢迎提交 Issue 和 Pull Request。提交前请确保：

npm run check
npm test
npm run build

不要在 issue、测试 fixture、日志或提交中包含真实 API key、token、CC Switch 数据库或本机私有配置。

设计来源

CC Switch

• 仓库：https://github.com/farion1231/cc-switch（MIT）

• src-tauri/src/provider.rs：provider 保存 settings_config；

• src-tauri/src/services/provider/live.rs：Claude provider live switch；

• src-tauri/src/config.rs：Claude 配置路径解析。

本项目借鉴 provider/settings 数据模型，但不采用并发进程共享 live 配置的方式。

OpenCode

• 仓库：https://github.com/anomalyco/opencode（MIT）

• packages/core/src/v1/config/provider.ts：provider 管理 key、base URL、models 和 options；

• packages/core/src/v1/config/agent.ts：agent 独立选择 model、prompt 和 permission；

• packages/opencode/src/agent/agent.ts：运行时解析 provider/model；

• packages/opencode/src/config/config.ts：进程级配置注入。

当前限制

• backend 是 Claude Code CLI，不直接运行 OpenCode、Codex 或 Gemini CLI；

• provider 必须兼容 Claude Code 使用的 Anthropic Messages API；

• 这是静态角色路由器，主 Claude/MCP 调用方负责选择角色；

• 子代理继承 Claude Code 配置，但不继承主会话对话；

• terminal 最终回复不会自动回填主会话；

• terminal 运行目录需要用户在关闭窗口后清理；

• 配置和进程隔离不是 OS sandbox；

• CC Switch 导入依赖本机 Python sqlite3；

• Plugin MCP 配置指向安装时的项目绝对路径，移动项目后需重装。

开源协议

本项目使用 MIT License。

本项目与 Anthropic、Claude Code、CC Switch 和 OpenCode 的原作者/维护者无隶属关系。Claude 和 Claude Code 是 Anthropic 的相关商标或产品名称。