1. 项目概述从零构建AI辅助的飞书工作流最近在折腾一个挺有意思的组合把 Claude Code、CC-Switch、CC-Connect 这几个工具串起来再接入飞书打造一个能在日常办公流里随时调用的AI助手。这听起来可能有点复杂但说白了就是想解决一个痛点——你正在飞书上写文档、看表格或者跟同事讨论问题突然需要查个资料、写段代码、或者润色一段文字这时候你不需要切出飞书去打开网页版或者桌面版的AI工具直接在飞书里就能调用 Claude Code 的能力。Claude Code 是 Anthropic 推出的一个专注于代码和文本生成的AI模型接口你可以把它理解为一个能力很强的“大脑”。CC-Switch 和 CC-Connect 则是围绕这个“大脑”搭建的“神经系统”和“手脚”负责路由请求、管理上下文以及连接到外部应用比如飞书。飞书作为我们日常高频使用的协作平台就成了这个AI能力的“操作界面”。这个组合非常适合开发团队、产品经理、或者任何需要高频处理文本和信息的职场人。我自己作为技术博主经常需要在飞书文档里写技术方案、整理会议纪要有了这个流程很多重复性的文案工作、代码片段生成、甚至是技术名词解释都可以在飞书里一键完成效率提升非常明显。接下来我就把从环境搭建到最终在飞书里成功调用的完整过程以及中间踩过的坑和心得详细拆解一遍。2. 核心工具链解析与选型思路在动手之前我们得先搞清楚手里这几样“工具”到底是干什么的以及为什么是它们组合在一起而不是别的方案。这就像组装一台电脑你得知道CPU、主板、显卡各自的作用。2.1 Claude Code能力核心与接口特性Claude Code 并不是一个独立的软件它本质上是 Claude 模型系列中针对代码生成、技术问答和文本处理优化后的一个API端点。你可以通过向这个API发送符合格式的请求来获取模型生成的代码、解释或文本。它的优势在于对编程语言、技术文档的理解和生成非常精准上下文窗口大能处理复杂的多轮对话。选择 Claude Code 而不是其他开源模型或通用聊天接口主要基于几点考虑生成质量与稳定性在代码建议、技术文案润色方面它的输出格式规整、逻辑清晰减少了后期调整的工作量。API友好性作为商业API其文档、速率限制、错误处理都比较规范适合集成到自动化流程中。上下文管理能够很好地处理长文档的摘要、基于历史对话的连续生成这对于在飞书中处理整个文档或连续的讨论线程非常有用。你需要准备的是一个有效的 Anthropic API Key这是调用所有能力的“门票”。在官网注册账号后通常可以在控制台找到创建API Key的地方。2.2 CC-Switch 与 CC-Connect桥梁与路由控制器这是整个流程中最关键也最容易让人困惑的部分。我们可以这样理解CC-Switch它像一个智能交换机或者路由中心。你的飞书机器人收到用户消息后消息并不是直接发给 Claude API 的。CC-Switch 在这里扮演了中间件的角色它决定了消息应该发给哪个AI模型比如 Claude Code并且负责管理对话的会话Session状态。比如同一个飞书群聊里的连续提问CC-Switch 会维护一个会话ID确保 Claude 模型能理解上下文关联。它还可能集成了一些插件或技能Skill用于处理特定类型的请求如查询天气、执行计算等。CC-Connect它更像一个协议适配器或连接器。飞书官方机器人的消息格式和 Claude API 要求的格式完全不同。CC-Connect 的作用就是接收来自飞书平台的标准webhook事件将其解析、转换成 CC-Switch 能够理解的内部格式然后再把 CC-Switch 处理后的回复转换成飞书机器人要求的格式发送回去。简单说它解决了“语言不通”的问题。为什么需要它们俩理论上你可以写一个复杂的服务器程序直接对接飞书webhook和Claude API。但 CC-Switch CC-Connect 这个组合提供了一个开箱即用、配置化的方案省去了大量协议解析、会话管理、错误重试的底层开发工作让你能更专注于业务逻辑和提示词Prompt的优化。2.3 飞书作为交互前台的天然优势选择飞书作为最终界面是因为它已经是很多团队的日常办公入口。集成在这里意味着AI能力可以无缝嵌入到文档、群聊、任务通知等具体场景中无需改变用户习惯。飞书开放平台提供了完善的机器人Bot和自定义应用App能力支持消息接收、发送以及丰富的卡片交互为AI交互提供了很好的载体。整个数据流可以概括为飞书用户 机器人 或发送消息 - 飞书平台将事件推送到你配置的CC-Connect服务器 -CC-Connect转换格式后发给CC-Switch-CC-Switch调用Claude CodeAPI - 响应按原路返回最终由机器人在飞书中回复用户。3. 基础环境搭建与依赖安装工欲善其事必先利其器。这一部分我们搭建整个系统运行所需的基础软件环境。整个过程我会以 macOS/Linux 环境为主进行说明Windows 用户使用 WSL2 (Windows Subsystem for Linux) 可以获得几乎一致的体验。3.1 Node.js 环境部署版本选择与避坑指南由于 CC-Switch 和 CC-Connect 通常是用 Node.js 编写的所以第一步是安装 Node.js 及其包管理器 npm。版本选择不要盲目安装最新版。一些依赖库可能对新版本 Node.js 兼容不佳。经过实测Node.js 18.x LTS长期支持版是一个稳定且广泛兼容的选择。你可以访问 Node.js 官网下载安装包但我更推荐使用版本管理工具nvm(Node Version Manager)它可以让你轻松切换多个Node版本。使用 nvm 安装推荐# 首先安装或更新 nvm。可以从其 GitHub 仓库获取安装脚本。 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 安装完成后重新打开终端或运行 source ~/.bashrc (或 ~/.zshrc) # 安装 Node.js 18.x 的最新版本 nvm install 18 # 使用刚安装的版本 nvm use 18 # 设置为默认版本 nvm alias default 18验证安装node --version # 应输出 v18.x.x npm --version # 应输出对应的 npm 版本注意如果你在安装过程中遇到类似error installing 24.19.0: node.js v24.19.0 is not yet released的错误这明确提示你指定的版本不存在或不可用。请使用nvm ls-remote命令查看所有远程可用版本并选择一个稳定的 LTS 版本如18.20.0进行安装。另一个常见错误error: no such module: http_parser通常发生在 Node.js 原生模块编译环节往往通过清理 npm 缓存 (npm cache clean -f) 并重新安装即可解决。3.2 获取与配置核心组件假设 CC-Switch 和 CC-Connect 是开源项目我们需要从代码仓库如 GitHub获取它们。克隆代码仓库# 假设项目仓库地址请替换为实际地址 git clone https://github.com/username/cc-switch.git git clone https://github.com/username/cc-connect.git cd cc-switch安装项目依赖npm install这个过程可能会花费一些时间npm 会下载package.json中列出的所有依赖包。如果遇到网络问题可以考虑配置国内镜像源npm config set registry https://registry.npmmirror.com环境变量配置这是关键一步。项目通常需要一个.env文件来存储敏感配置。在cc-switch目录下复制提供的环境变量示例文件并编辑cp .env.example .env # 使用你喜欢的编辑器如 vscode, vim, nano打开 .env 文件 code .env在.env文件中你至少需要配置 Claude 的 API KeyANTHROPIC_API_KEYsk-ant-your-actual-api-key-here # 可能还有其他配置如服务端口、日志级别等 CC_SWITCH_PORT3000 LOG_LEVELinfo重要安全提示务必确保.env文件被添加到.gitignore中避免将你的 API Key 等敏感信息提交到公开仓库。4. CC-Switch 服务部署与深度配置安装好依赖后我们需要让 CC-Switch 服务运行起来并理解其核心配置。4.1 服务启动与验证启动开发服务器在cc-switch目录下运行npm run dev如果package.json中没有dev脚本可以尝试npm start或node index.js具体入口文件请查看项目文档。成功启动后终端会显示类似Server running on port 3000的信息。基础功能测试打开另一个终端使用curl命令测试服务是否正常以及 Claude API 是否连通curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer dummy_internal_token \ -d { model: claude-3-sonnet-20240229, messages: [{role: user, content: Hello, Claude!}], max_tokens: 100 }如果返回一个包含 AI 回复的 JSON 数据说明 CC-Switch 服务本身和背后的 Claude API 配置都是正确的。4.2 核心配置项解读CC-Switch 的配置文件可能是config.js或.env中的变量决定了其行为。你需要关注以下几点模型路由配置默认使用的模型如claude-3-haiku用于快速响应claude-3-opus用于复杂任务。CC-Switch 可能支持根据关键词或渠道自动切换模型。会话管理会话超时时间如30分钟无活动后清除会话、会话存储方式内存或Redis。对于生产环境使用 Redis 可以持久化会话并支持多实例部署。速率限制为了保护你的 API Key 不被滥用务必在 CC-Switch 层面设置速率限制Rate Limiting例如每个用户每分钟最多请求10次。技能Skills配置如果 CC-Switch 支持插件化技能你需要在这里启用或配置它们。例如一个“查询时间”的技能或者一个“执行简单计算”的技能。实操心得在本地测试时可以将日志级别 (LOG_LEVEL) 设置为debug这样可以看到 CC-Switch 与 Claude API 之间详细的请求和响应对于调试提示词Prompt和排查问题非常有帮助。但在生产环境请务必调回info或warn级别避免日志泛滥。5. CC-Connect 配置与飞书平台对接这是连接 CC-Switch 和飞书的关键环节。CC-Connect 需要作为一个独立的服务运行负责协议转换。5.1 飞书开放平台应用创建登录与创建访问飞书开放平台使用你的飞书账号登录。在“开发者后台”点击“创建企业自建应用”。基础信息填写应用名称如“AI工作助手”、描述并上传应用图标。获取凭证在应用的“凭证与基础信息”页面找到App ID和App Secret。请立即保存 App Secret它只显示一次如果丢失需要重置并生成新的。常见坑点很多人在复制App Secret时会因为首尾空格或换行符导致后续配置验证失败。最稳妥的方法是点击“显示”后使用“复制”按钮然后直接粘贴到配置文件中不要手动选中文本复制。如果遇到app secret复制不上去的错觉可能是网页前端问题尝试刷新页面或更换浏览器。5.2 配置 CC-Connect 连接飞书安装与配置进入cc-connect目录运行npm install安装依赖。同样复制并配置.env文件# 飞书应用凭证 FEISHU_APP_IDcli_xxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxx # CC-Switch 服务地址 CC_SWITCH_URLhttp://localhost:3000 # CC-Connect 自身服务地址必须是公网可访问的用于接收飞书事件 CC_CONNECT_PUBLIC_URLhttps://your-public-domain.com CC_CONNECT_PORT3001 # 内部通信令牌需与CC-Switch配置一致 INTERNAL_API_TOKENdummy_internal_token配置事件订阅这是核心步骤。在飞书应用后台的“事件订阅”页面请求地址填写你的CC-Connect的公网访问地址加上回调路径例如https://your-public-domain.com/feishu/event。CC-Connect代码中会定义这个路由。验证令牌和加密密钥飞书会提供这两个字符串用于验证请求来源。你需要将它们也填入CC-Connect的.env文件如FEISHU_VERIFICATION_TOKEN,FEISHU_ENCRYPT_KEY。订阅事件至少需要订阅“接收消息”相关的事件例如im.message.receive_v1。这样当用户在群聊或单聊中 你的机器人时飞书才会把事件推送到你的服务器。配置权限与发布在“权限管理”页面为你的应用添加所需权限例如im:message发送和接收消息、im:chat获取群信息等。根据你的需求添加。配置完成后在“版本管理与发布”中创建一个版本并申请发布。只有发布后应用才能被添加到群聊或工作台中。5.3 使用内网穿透工具暴露本地服务由于飞书的事件订阅需要回调一个公网可访问的 URL而我们的CC-Connect运行在本地电脑上这就需要使用内网穿透工具。ngrok和localtunnel是两款流行的选择。以ngrok为例注册ngrok账号并获取你的 Authtoken。在终端安装并配置ngrok。启动你的CC-Connect服务假设在端口3001。在另一个终端运行ngrok http 3001。ngrok会生成一个随机的公网地址如https://abc123.ngrok-free.app。将这个地址配置到飞书事件订阅的“请求地址”中记得加上/feishu/event等具体路径。现在当飞书有事件发生时它会将请求发送到ngrok提供的地址ngrok会将请求转发到你本机的CC-Connect服务。6. 飞书机器人交互与功能集成当基础设施全部打通后我们就可以在飞书里和机器人对话了。6.1 添加机器人与基础测试添加机器人在飞书群聊中点击群设置 - 添加机器人 - 找到你刚刚创建并发布的“AI工作助手”添加它。首次对话在群聊中 你的机器人并发送“你好”。如果一切配置正确你应该能收到来自 Claude 的回复。理解消息流这个过程是你在飞书发消息 - 飞书服务器 -ngrok公网地址 - 你本机的CC-Connect- 你本机的CC-Switch- 互联网上的 Claude API - 原路返回回复 - 飞书群聊。6.2 实现高级功能与场景化应用基础的问答实现了但要让这个机器人真正有用需要根据场景定制。这主要通过改造CC-Switch或CC-Connect的代码来实现核心是构造不同的系统提示词System Prompt。文档助手当机器人在一个飞书文档的评论中被 时CC-Connect可以获取到文档的标识符和内容片段。我们可以设计一个技能让CC-Switch调用 Claude Code 时附上这样的提示词“你是一个技术文档助手。用户提供了以下文档片段请根据他的问题关于XXX进行修改/补充/解释[文档内容]”。这样Claude 的回复就能基于具体文档上下文生成更精准的建议。群聊摘要可以设计一个定时任务或关键词触发如“总结一下”让机器人获取群聊最近N条消息然后发送给 Claude 并提示“请将以下群聊对话总结为要点并列出待办事项[聊天记录]”。这需要机器人有读取群历史消息的权限。与飞书多维表格联动飞书多维表格提供了API。你可以创建一个机器人指令如“查询本季度销售数据”CC-Connect接收到后先调用飞书API从多维表格获取数据然后将数据表格和问题一起交给CC-Switch/Claude 进行分析最后将分析结果用飞书消息卡片的形式回复出来图表和文字结合体验会非常好。注意事项飞书机器人的消息频率有限制。个人版和免费版企业有严格的调用频率限制超出后会返回错误。在开发测试时务必注意避免短时间内发送大量消息触发限流。生产环境可以考虑使用企业付费版来获得更高的配额。7. 常见问题排查与性能优化在实际部署和使用的过程中你肯定会遇到各种各样的问题。这里我整理了一份常见问题速查表涵盖了从配置到使用的全链路。问题现象可能原因排查步骤与解决方案飞书机器人无响应发送消息后收不到回复。1. 事件订阅URL未正确配置或验证失败。2.CC-Connect服务未运行或崩溃。3. 内网穿透 (ngrok) 隧道断开。4. 飞书应用未发布或机器人未添加到群。1. 检查飞书后台事件订阅状态确保显示“验证成功”。重新保存URL可能触发重新验证。2. 查看CC-Connect服务日志确认是否在运行且无报错。3. 检查ngrok终端界面确认隧道状态为online。重启ngrok。4. 进入飞书开放平台确认应用已发布并在群聊中确认机器人已添加。机器人回复“服务内部错误”或超时。1.CC-Switch服务异常或未连接。2. Claude API Key 无效或余额不足。3. 网络问题导致无法访问 Claude API。1. 检查CC-Switch服务日志。尝试用curl直接测试CC-Switch的本地接口见4.1节。2. 登录 Anthropic 控制台检查 API Key 状态和用量。3. 在服务器上运行curl https://api.anthropic.com测试网络连通性。错误信息包含invalid redirect uri。此错误常出现在飞书OAuth授权场景与机器人消息接收无关。可能是在配置“网页应用”或“移动应用”时的回调地址Redirect URI格式错误。检查飞书开放平台中“安全设置”里的“重定向URL”确保其与你在代码中申请授权时使用的地址完全一致包括协议头http/https和端口。Claude 回复内容不符合预期或丢失上下文。1. 系统提示词System Prompt未正确设置或过于简单。2.CC-Switch的会话管理逻辑有问题上下文未正确传递。3. 消息在CC-Connect转换过程中格式丢失。1. 在CC-Switch的 Claude API 调用处检查并优化附加的系统提示词。2. 检查CC-Switch日志确认每次请求的session_id是否在连续对话中保持一致。3. 在CC-Connect中打印出即将发送给CC-Switch的消息体检查其结构是否完整。服务运行一段时间后内存占用过高或崩溃。1.CC-Switch在内存中存储了大量会话未清理。2. 存在内存泄漏。1. 检查并缩短会话过期时间配置。对于生产环境将会话存储切换到 Redis。2. 使用 Node.js 内存分析工具如node --inspect配合 Chrome DevTools排查内存泄漏点常见于未释放的全局变量或事件监听器。性能优化建议会话缓存对于非敏感信息可以考虑在CC-Switch层面缓存一些常见问题的回答减少对 Claude API 的调用节省成本和延迟。异步处理对于耗时的处理如总结长文档不要让飞书机器人同步等待。可以让CC-Connect先回复一个“正在处理”的提示然后通过异步任务处理完成后使用飞书的“发送消息”API 将结果推送给用户。日志与监控为CC-Switch和CC-Connect添加详细的日志记录特别是请求耗时、错误码。可以集成 Sentry 等工具进行错误监控。这能帮助你在出现问题时快速定位。整个搭建过程就像在组装一个精密的管道系统每一步的严丝合缝决定了最终水流的畅通。从环境配置、服务启动、平台对接到功能打磨每一步都有细节需要注意。一旦跑通你会发现这个自动化的AI工作流能极大地解放生产力让最强大的AI能力在你最熟悉的办公环境里随时待命。
1. 项目概述从零构建AI辅助的飞书工作流最近在折腾一个挺有意思的组合把 Claude Code、CC-Switch、CC-Connect 这几个工具串起来再接入飞书打造一个能在日常办公流里随时调用的AI助手。这听起来可能有点复杂但说白了就是想解决一个痛点——你正在飞书上写文档、看表格或者跟同事讨论问题突然需要查个资料、写段代码、或者润色一段文字这时候你不需要切出飞书去打开网页版或者桌面版的AI工具直接在飞书里就能调用 Claude Code 的能力。Claude Code 是 Anthropic 推出的一个专注于代码和文本生成的AI模型接口你可以把它理解为一个能力很强的“大脑”。CC-Switch 和 CC-Connect 则是围绕这个“大脑”搭建的“神经系统”和“手脚”负责路由请求、管理上下文以及连接到外部应用比如飞书。飞书作为我们日常高频使用的协作平台就成了这个AI能力的“操作界面”。这个组合非常适合开发团队、产品经理、或者任何需要高频处理文本和信息的职场人。我自己作为技术博主经常需要在飞书文档里写技术方案、整理会议纪要有了这个流程很多重复性的文案工作、代码片段生成、甚至是技术名词解释都可以在飞书里一键完成效率提升非常明显。接下来我就把从环境搭建到最终在飞书里成功调用的完整过程以及中间踩过的坑和心得详细拆解一遍。2. 核心工具链解析与选型思路在动手之前我们得先搞清楚手里这几样“工具”到底是干什么的以及为什么是它们组合在一起而不是别的方案。这就像组装一台电脑你得知道CPU、主板、显卡各自的作用。2.1 Claude Code能力核心与接口特性Claude Code 并不是一个独立的软件它本质上是 Claude 模型系列中针对代码生成、技术问答和文本处理优化后的一个API端点。你可以通过向这个API发送符合格式的请求来获取模型生成的代码、解释或文本。它的优势在于对编程语言、技术文档的理解和生成非常精准上下文窗口大能处理复杂的多轮对话。选择 Claude Code 而不是其他开源模型或通用聊天接口主要基于几点考虑生成质量与稳定性在代码建议、技术文案润色方面它的输出格式规整、逻辑清晰减少了后期调整的工作量。API友好性作为商业API其文档、速率限制、错误处理都比较规范适合集成到自动化流程中。上下文管理能够很好地处理长文档的摘要、基于历史对话的连续生成这对于在飞书中处理整个文档或连续的讨论线程非常有用。你需要准备的是一个有效的 Anthropic API Key这是调用所有能力的“门票”。在官网注册账号后通常可以在控制台找到创建API Key的地方。2.2 CC-Switch 与 CC-Connect桥梁与路由控制器这是整个流程中最关键也最容易让人困惑的部分。我们可以这样理解CC-Switch它像一个智能交换机或者路由中心。你的飞书机器人收到用户消息后消息并不是直接发给 Claude API 的。CC-Switch 在这里扮演了中间件的角色它决定了消息应该发给哪个AI模型比如 Claude Code并且负责管理对话的会话Session状态。比如同一个飞书群聊里的连续提问CC-Switch 会维护一个会话ID确保 Claude 模型能理解上下文关联。它还可能集成了一些插件或技能Skill用于处理特定类型的请求如查询天气、执行计算等。CC-Connect它更像一个协议适配器或连接器。飞书官方机器人的消息格式和 Claude API 要求的格式完全不同。CC-Connect 的作用就是接收来自飞书平台的标准webhook事件将其解析、转换成 CC-Switch 能够理解的内部格式然后再把 CC-Switch 处理后的回复转换成飞书机器人要求的格式发送回去。简单说它解决了“语言不通”的问题。为什么需要它们俩理论上你可以写一个复杂的服务器程序直接对接飞书webhook和Claude API。但 CC-Switch CC-Connect 这个组合提供了一个开箱即用、配置化的方案省去了大量协议解析、会话管理、错误重试的底层开发工作让你能更专注于业务逻辑和提示词Prompt的优化。2.3 飞书作为交互前台的天然优势选择飞书作为最终界面是因为它已经是很多团队的日常办公入口。集成在这里意味着AI能力可以无缝嵌入到文档、群聊、任务通知等具体场景中无需改变用户习惯。飞书开放平台提供了完善的机器人Bot和自定义应用App能力支持消息接收、发送以及丰富的卡片交互为AI交互提供了很好的载体。整个数据流可以概括为飞书用户 机器人 或发送消息 - 飞书平台将事件推送到你配置的CC-Connect服务器 -CC-Connect转换格式后发给CC-Switch-CC-Switch调用Claude CodeAPI - 响应按原路返回最终由机器人在飞书中回复用户。3. 基础环境搭建与依赖安装工欲善其事必先利其器。这一部分我们搭建整个系统运行所需的基础软件环境。整个过程我会以 macOS/Linux 环境为主进行说明Windows 用户使用 WSL2 (Windows Subsystem for Linux) 可以获得几乎一致的体验。3.1 Node.js 环境部署版本选择与避坑指南由于 CC-Switch 和 CC-Connect 通常是用 Node.js 编写的所以第一步是安装 Node.js 及其包管理器 npm。版本选择不要盲目安装最新版。一些依赖库可能对新版本 Node.js 兼容不佳。经过实测Node.js 18.x LTS长期支持版是一个稳定且广泛兼容的选择。你可以访问 Node.js 官网下载安装包但我更推荐使用版本管理工具nvm(Node Version Manager)它可以让你轻松切换多个Node版本。使用 nvm 安装推荐# 首先安装或更新 nvm。可以从其 GitHub 仓库获取安装脚本。 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # 安装完成后重新打开终端或运行 source ~/.bashrc (或 ~/.zshrc) # 安装 Node.js 18.x 的最新版本 nvm install 18 # 使用刚安装的版本 nvm use 18 # 设置为默认版本 nvm alias default 18验证安装node --version # 应输出 v18.x.x npm --version # 应输出对应的 npm 版本注意如果你在安装过程中遇到类似error installing 24.19.0: node.js v24.19.0 is not yet released的错误这明确提示你指定的版本不存在或不可用。请使用nvm ls-remote命令查看所有远程可用版本并选择一个稳定的 LTS 版本如18.20.0进行安装。另一个常见错误error: no such module: http_parser通常发生在 Node.js 原生模块编译环节往往通过清理 npm 缓存 (npm cache clean -f) 并重新安装即可解决。3.2 获取与配置核心组件假设 CC-Switch 和 CC-Connect 是开源项目我们需要从代码仓库如 GitHub获取它们。克隆代码仓库# 假设项目仓库地址请替换为实际地址 git clone https://github.com/username/cc-switch.git git clone https://github.com/username/cc-connect.git cd cc-switch安装项目依赖npm install这个过程可能会花费一些时间npm 会下载package.json中列出的所有依赖包。如果遇到网络问题可以考虑配置国内镜像源npm config set registry https://registry.npmmirror.com环境变量配置这是关键一步。项目通常需要一个.env文件来存储敏感配置。在cc-switch目录下复制提供的环境变量示例文件并编辑cp .env.example .env # 使用你喜欢的编辑器如 vscode, vim, nano打开 .env 文件 code .env在.env文件中你至少需要配置 Claude 的 API KeyANTHROPIC_API_KEYsk-ant-your-actual-api-key-here # 可能还有其他配置如服务端口、日志级别等 CC_SWITCH_PORT3000 LOG_LEVELinfo重要安全提示务必确保.env文件被添加到.gitignore中避免将你的 API Key 等敏感信息提交到公开仓库。4. CC-Switch 服务部署与深度配置安装好依赖后我们需要让 CC-Switch 服务运行起来并理解其核心配置。4.1 服务启动与验证启动开发服务器在cc-switch目录下运行npm run dev如果package.json中没有dev脚本可以尝试npm start或node index.js具体入口文件请查看项目文档。成功启动后终端会显示类似Server running on port 3000的信息。基础功能测试打开另一个终端使用curl命令测试服务是否正常以及 Claude API 是否连通curl -X POST http://localhost:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer dummy_internal_token \ -d { model: claude-3-sonnet-20240229, messages: [{role: user, content: Hello, Claude!}], max_tokens: 100 }如果返回一个包含 AI 回复的 JSON 数据说明 CC-Switch 服务本身和背后的 Claude API 配置都是正确的。4.2 核心配置项解读CC-Switch 的配置文件可能是config.js或.env中的变量决定了其行为。你需要关注以下几点模型路由配置默认使用的模型如claude-3-haiku用于快速响应claude-3-opus用于复杂任务。CC-Switch 可能支持根据关键词或渠道自动切换模型。会话管理会话超时时间如30分钟无活动后清除会话、会话存储方式内存或Redis。对于生产环境使用 Redis 可以持久化会话并支持多实例部署。速率限制为了保护你的 API Key 不被滥用务必在 CC-Switch 层面设置速率限制Rate Limiting例如每个用户每分钟最多请求10次。技能Skills配置如果 CC-Switch 支持插件化技能你需要在这里启用或配置它们。例如一个“查询时间”的技能或者一个“执行简单计算”的技能。实操心得在本地测试时可以将日志级别 (LOG_LEVEL) 设置为debug这样可以看到 CC-Switch 与 Claude API 之间详细的请求和响应对于调试提示词Prompt和排查问题非常有帮助。但在生产环境请务必调回info或warn级别避免日志泛滥。5. CC-Connect 配置与飞书平台对接这是连接 CC-Switch 和飞书的关键环节。CC-Connect 需要作为一个独立的服务运行负责协议转换。5.1 飞书开放平台应用创建登录与创建访问飞书开放平台使用你的飞书账号登录。在“开发者后台”点击“创建企业自建应用”。基础信息填写应用名称如“AI工作助手”、描述并上传应用图标。获取凭证在应用的“凭证与基础信息”页面找到App ID和App Secret。请立即保存 App Secret它只显示一次如果丢失需要重置并生成新的。常见坑点很多人在复制App Secret时会因为首尾空格或换行符导致后续配置验证失败。最稳妥的方法是点击“显示”后使用“复制”按钮然后直接粘贴到配置文件中不要手动选中文本复制。如果遇到app secret复制不上去的错觉可能是网页前端问题尝试刷新页面或更换浏览器。5.2 配置 CC-Connect 连接飞书安装与配置进入cc-connect目录运行npm install安装依赖。同样复制并配置.env文件# 飞书应用凭证 FEISHU_APP_IDcli_xxxxxx FEISHU_APP_SECRETxxxxxxxxxxxxxxxx # CC-Switch 服务地址 CC_SWITCH_URLhttp://localhost:3000 # CC-Connect 自身服务地址必须是公网可访问的用于接收飞书事件 CC_CONNECT_PUBLIC_URLhttps://your-public-domain.com CC_CONNECT_PORT3001 # 内部通信令牌需与CC-Switch配置一致 INTERNAL_API_TOKENdummy_internal_token配置事件订阅这是核心步骤。在飞书应用后台的“事件订阅”页面请求地址填写你的CC-Connect的公网访问地址加上回调路径例如https://your-public-domain.com/feishu/event。CC-Connect代码中会定义这个路由。验证令牌和加密密钥飞书会提供这两个字符串用于验证请求来源。你需要将它们也填入CC-Connect的.env文件如FEISHU_VERIFICATION_TOKEN,FEISHU_ENCRYPT_KEY。订阅事件至少需要订阅“接收消息”相关的事件例如im.message.receive_v1。这样当用户在群聊或单聊中 你的机器人时飞书才会把事件推送到你的服务器。配置权限与发布在“权限管理”页面为你的应用添加所需权限例如im:message发送和接收消息、im:chat获取群信息等。根据你的需求添加。配置完成后在“版本管理与发布”中创建一个版本并申请发布。只有发布后应用才能被添加到群聊或工作台中。5.3 使用内网穿透工具暴露本地服务由于飞书的事件订阅需要回调一个公网可访问的 URL而我们的CC-Connect运行在本地电脑上这就需要使用内网穿透工具。ngrok和localtunnel是两款流行的选择。以ngrok为例注册ngrok账号并获取你的 Authtoken。在终端安装并配置ngrok。启动你的CC-Connect服务假设在端口3001。在另一个终端运行ngrok http 3001。ngrok会生成一个随机的公网地址如https://abc123.ngrok-free.app。将这个地址配置到飞书事件订阅的“请求地址”中记得加上/feishu/event等具体路径。现在当飞书有事件发生时它会将请求发送到ngrok提供的地址ngrok会将请求转发到你本机的CC-Connect服务。6. 飞书机器人交互与功能集成当基础设施全部打通后我们就可以在飞书里和机器人对话了。6.1 添加机器人与基础测试添加机器人在飞书群聊中点击群设置 - 添加机器人 - 找到你刚刚创建并发布的“AI工作助手”添加它。首次对话在群聊中 你的机器人并发送“你好”。如果一切配置正确你应该能收到来自 Claude 的回复。理解消息流这个过程是你在飞书发消息 - 飞书服务器 -ngrok公网地址 - 你本机的CC-Connect- 你本机的CC-Switch- 互联网上的 Claude API - 原路返回回复 - 飞书群聊。6.2 实现高级功能与场景化应用基础的问答实现了但要让这个机器人真正有用需要根据场景定制。这主要通过改造CC-Switch或CC-Connect的代码来实现核心是构造不同的系统提示词System Prompt。文档助手当机器人在一个飞书文档的评论中被 时CC-Connect可以获取到文档的标识符和内容片段。我们可以设计一个技能让CC-Switch调用 Claude Code 时附上这样的提示词“你是一个技术文档助手。用户提供了以下文档片段请根据他的问题关于XXX进行修改/补充/解释[文档内容]”。这样Claude 的回复就能基于具体文档上下文生成更精准的建议。群聊摘要可以设计一个定时任务或关键词触发如“总结一下”让机器人获取群聊最近N条消息然后发送给 Claude 并提示“请将以下群聊对话总结为要点并列出待办事项[聊天记录]”。这需要机器人有读取群历史消息的权限。与飞书多维表格联动飞书多维表格提供了API。你可以创建一个机器人指令如“查询本季度销售数据”CC-Connect接收到后先调用飞书API从多维表格获取数据然后将数据表格和问题一起交给CC-Switch/Claude 进行分析最后将分析结果用飞书消息卡片的形式回复出来图表和文字结合体验会非常好。注意事项飞书机器人的消息频率有限制。个人版和免费版企业有严格的调用频率限制超出后会返回错误。在开发测试时务必注意避免短时间内发送大量消息触发限流。生产环境可以考虑使用企业付费版来获得更高的配额。7. 常见问题排查与性能优化在实际部署和使用的过程中你肯定会遇到各种各样的问题。这里我整理了一份常见问题速查表涵盖了从配置到使用的全链路。问题现象可能原因排查步骤与解决方案飞书机器人无响应发送消息后收不到回复。1. 事件订阅URL未正确配置或验证失败。2.CC-Connect服务未运行或崩溃。3. 内网穿透 (ngrok) 隧道断开。4. 飞书应用未发布或机器人未添加到群。1. 检查飞书后台事件订阅状态确保显示“验证成功”。重新保存URL可能触发重新验证。2. 查看CC-Connect服务日志确认是否在运行且无报错。3. 检查ngrok终端界面确认隧道状态为online。重启ngrok。4. 进入飞书开放平台确认应用已发布并在群聊中确认机器人已添加。机器人回复“服务内部错误”或超时。1.CC-Switch服务异常或未连接。2. Claude API Key 无效或余额不足。3. 网络问题导致无法访问 Claude API。1. 检查CC-Switch服务日志。尝试用curl直接测试CC-Switch的本地接口见4.1节。2. 登录 Anthropic 控制台检查 API Key 状态和用量。3. 在服务器上运行curl https://api.anthropic.com测试网络连通性。错误信息包含invalid redirect uri。此错误常出现在飞书OAuth授权场景与机器人消息接收无关。可能是在配置“网页应用”或“移动应用”时的回调地址Redirect URI格式错误。检查飞书开放平台中“安全设置”里的“重定向URL”确保其与你在代码中申请授权时使用的地址完全一致包括协议头http/https和端口。Claude 回复内容不符合预期或丢失上下文。1. 系统提示词System Prompt未正确设置或过于简单。2.CC-Switch的会话管理逻辑有问题上下文未正确传递。3. 消息在CC-Connect转换过程中格式丢失。1. 在CC-Switch的 Claude API 调用处检查并优化附加的系统提示词。2. 检查CC-Switch日志确认每次请求的session_id是否在连续对话中保持一致。3. 在CC-Connect中打印出即将发送给CC-Switch的消息体检查其结构是否完整。服务运行一段时间后内存占用过高或崩溃。1.CC-Switch在内存中存储了大量会话未清理。2. 存在内存泄漏。1. 检查并缩短会话过期时间配置。对于生产环境将会话存储切换到 Redis。2. 使用 Node.js 内存分析工具如node --inspect配合 Chrome DevTools排查内存泄漏点常见于未释放的全局变量或事件监听器。性能优化建议会话缓存对于非敏感信息可以考虑在CC-Switch层面缓存一些常见问题的回答减少对 Claude API 的调用节省成本和延迟。异步处理对于耗时的处理如总结长文档不要让飞书机器人同步等待。可以让CC-Connect先回复一个“正在处理”的提示然后通过异步任务处理完成后使用飞书的“发送消息”API 将结果推送给用户。日志与监控为CC-Switch和CC-Connect添加详细的日志记录特别是请求耗时、错误码。可以集成 Sentry 等工具进行错误监控。这能帮助你在出现问题时快速定位。整个搭建过程就像在组装一个精密的管道系统每一步的严丝合缝决定了最终水流的畅通。从环境配置、服务启动、平台对接到功能打磨每一步都有细节需要注意。一旦跑通你会发现这个自动化的AI工作流能极大地解放生产力让最强大的AI能力在你最熟悉的办公环境里随时待命。
)
