企业官网建设流程全解析

CC-Viewer 是 Claude Code 的请求监控系统，它能实时捕获并可视化所有 API 请求与响应。而它内置的**代理热重载（proxy hot-reload）与按角色路由（per-role routing）**两大能力，可以让你不再依赖 claude-code-router、claude-code-switch 这类第三方代理工具——主 Agent、子 Agent、Teammate 各走各的通道，改配置秒级生效，无需重启。

🚀 本文将从配置存储、文件监听、请求分类三个层面拆解这套机制的原理。

为什么不再需要 claude-code-router？

Claude Code 本身支持ANTHROPIC_BASE_URL指向第三方代理，很多用户因此叠加 claude-code-router 做"按角色换供应商"。但官方文档早已提示：这类工具和 cc-viewer 存在代理端口争用问题，必须二选一。而 CC-Viewer 的内置方案直接在拦截层完成同样的事：

• 热重载：切换供应商/Key/模型，下一个请求立即生效；
• 按角色分流：subagent（子代理）与teammate（团队智能体）可以各自绑定独立代理源；
• 零冲突：拦截发生在 Claude Code 的 fetch 调用层，不额外占用代理端口。

相关说明见 README.md。

内置代理热重载：改配置不用重启

两层配置文件结构

热重载的数据模型只有两个文件，定义在 interceptor.js：

active-profile.json的结构长这样：

{ "activeId": "my-relay", "roles": { "subagent": "follow", "teammate": "cheap-relay" } }

其中roles的取值有三种：follow（跟随主 Agent，默认）、max（内置 Default，即不改写）、或直接填某个 profile id。

watchFile 实现 1.5 秒跨进程同步

热重载的关键是文件监听。CC-Viewer 用 Node 的watchFile以 1500ms 轮询这两个文件：

• interceptor.js 中挂载 profile.json 监听：任何 ccv 进程修改了 profiles 列表，其他进程（多窗口、teammate 子进程）在 1.5 秒内自动重新加载；
• 工作区 active-profile.json 的独立 watcher：角色分配只存在这个文件里，所以单独监听。

重试配置retry-config.json也走同样的热刷新通道——proxy.js 中每个请求都实时读取最新重试配置，UI 改完下个请求即生效，无需重启。

写入侧同样讲究：工作区文件采用tmp + rename 原子写（interceptor.js），防止其他进程经轮询读到写一半的撕裂内容；合并语义则保证"只改 activeId"不会覆盖已存的角色分配。

按角色路由原理：主 Agent/子 Agent 各走各的通道

第一步：如何判断一个请求的角色

每个 fetch 请求经过拦截钩子时，先做一次"角色分类"，核心是 classifyProxyRole 这个纯函数，判据按优先级排列：

1. x-claude-code-agent-id请求头——最高优先级硬判据，见 interceptor.js：带命名队友（name@…）→teammate，匿名子代理 →subagent。它不依赖 system 文本，最可靠；
2. teammate 进程——独立的 OS 进程带--agent-name参数，进程内一切请求恒为teammate；
3. cc_is_subagent=true计费标记——CC 2.1.181+ 的 CLI 会在 billing header 显式标注子代理，这是subagent的唯一阳性依据；
4. 兜底为main——count_tokens、heartbeat 等工具端点跟随进程主角色，避免老版本 CC 的子代理请求被误分流。

第二步：角色到 Profile 的解析

分类完成后，resolveRoleProfile 把角色解析成实际生效的 profile 对象：

• follow/ 缺省 / 悬空 id（profile 已被删）→ 回落主 Agent 的 profile；
• max→null，即显式不改写；
• 具体 profile id → 对应的 baseURL、apiKey、模型替换规则。

随后拦截器会做两件事：URL 重写（用 profile 的 baseURL 替换 origin，并智能去重/v1路径重叠）与Auth 替换（同时覆盖x-api-key和Authorization两种鉴权），改写逻辑见 interceptor.js。

几个值得注意的兼容细节

• 休眠机制：当主 Agent 使用内置 Default 且指向官方端点时，角色分配保持存储但请求时不生效，UI 里分配区也会隐藏；
• Fail-closed 安全策略：一个 profile 若要改写 URL 到第三方 baseURL，但其 apiKey 无法从凭据库解密，该 profile 会被直接排除出路由（interceptor.js）——否则会拿着你本人的 Anthropic 凭证打到第三方地址；
• 零成本短路：未配置任何 profile 时，分类被整体跳过，不做 system 文本提取，对普通用户零开销（interceptor.js）。

在 UI 里如何设置按角色路由

前端入口是 ProxyModal.jsx：在代理弹窗中，主 Agent 走列表 radio 切换，subagent与teammate各有独立下拉框（默认follow），被分配到的 profile 会显示角色徽章。

提交走POST /api/proxy-profiles，服务端处理在 preferences.js：

• 只发送变更的 role key，避免多窗口陈旧值互相覆盖；
• 删除 profile 时，引用它的角色自动归回follow；
• 非法值归follow、杂键丢弃、悬空 id 读取时回落，容错逻辑见 normalizeRoles。

小结

一句话：把 claude-code-router 关掉，用 CC-Viewer 的代理弹窗配置好角色分配，主 Agent、子 Agent、Teammate 从此各走各的通道——配置即改即生效，这正是开源项目做工具链一体化的价值所在。

核心源码索引：拦截器主逻辑、角色分类纯函数、代理转发与重试、角色路由测试契约。