企业官网建设流程全解析

1. 项目概述：一个能操作你电脑的飞书AI助手

最近在折腾一个挺有意思的东西，我把Claude Code，就是那个能直接在你本地电脑上执行命令、读写文件的AI，给接进了飞书。现在，我和我的团队成员在飞书里@一下机器人，就能让它帮忙创建文件、运行脚本、管理Git仓库，甚至打开个音乐软件。这玩意儿本质上是一个AI Agent，它打通了飞书聊天窗口和你本地操作系统之间的壁垒，让对话式的指令直接变成了可执行的操作。

这个项目特别适合需要频繁在本地进行开发、测试或文件操作的团队。想象一下，你正在飞书群里讨论一个Bug，有人提到“看看日志里有没有ERROR”，你不再需要切出聊天窗口去打开终端敲命令，直接@机器人一句“查看当前目录下的app.log文件最后10行”，它就能把结果贴回群里。每个私聊窗口或群聊都是一个独立的会话，上下文互不干扰，数据用SQLite存着，重启了对话也能接着聊。

市面上类似的工具，比如对接Slack的ClawdBot，更多是纯对话助手。而我们这个项目的核心特色在于“本地操作能力”和“精细的会话隔离”。它不调用遥远的云端API来生成文本，而是驱动你本机安装的Claude Code CLI工具去实干。下面，我就来拆解一下我是怎么把它搞定的，以及中间趟过哪些坑。

2. 核心设计思路与架构拆解

2.1 为什么选择“飞书长连接” + “Claude Code本地CLI”这个组合？

做这个项目，首要解决两个问题：通信和执行。

通信层面，常见的有Webhook和WebSocket长连接两种方式。Webhook需要你有一个公网域名和SSL证书，让飞书服务器能回调你的服务，这对于个人开发者或内网环境是个门槛。而飞书开放平台提供的“长连接”模式，允许你的服务主动与飞书服务器建立并维持一个WebSocket连接，事件通过这个连接推送过来。这意味着你可以在完全没有公网IP的电脑上运行这个机器人，极大降低了部署复杂度。这是我们选择长连接的核心原因。

执行层面，目标是操作本地电脑。我们评估过几种方案：

1. 直接调用系统API/命令：灵活，但需要自己处理所有安全边界和上下文管理，复杂度高。
2. 通过OpenAI的Assistants API：功能强大，但需要网络，且无法直接无限制操作本地文件。
3. Claude Code：它是Anthropic官方出的一个命令行工具，安装后就在本地运行。它本身就是一个为操作本地环境而设计的AI Agent，天然支持文件读写、Shell命令执行等。我们只需要“驱动”它即可，相当于站在了巨人的肩膀上，避免了重复造轮子。

因此，飞书长连接负责稳定、低门槛的消息收发，Claude Code负责安全、可靠地执行本地操作，这个组合在实现难度、功能性和便利性上取得了很好的平衡。

2.2 会话管理：如何实现“一人一窗，一窗一会”？

多用户上下文隔离是企业级机器人的基本要求。我们的设计目标是：张三在私聊窗口里让机器人修改A.py，李四在另一个私聊窗口里查询B.log，他们的操作历史和上下文完全独立，互不影响。甚至在同一个项目群里，所有成员共享同一个会话上下文，这样大家都能看到机器人之前执行了哪些操作，对话具有连续性。

实现的关键是session_id的设计。这个ID需要唯一标识一个“对话场景”。最直接的方式就是用飞书提供的chat_id。在飞书的事件中，私聊和群聊都有唯一的chat_id。

• 私聊：session_id = chat_id。这个ID只对应你和机器人，完美隔离。
• 群聊：session_id = chat_id。这个ID对应这个群，所有群成员共享。

这样，架构就清晰了：

1. 飞书消息事件到来，解析出chat_id作为session_id。
2. 用这个session_id去查询数据库，找回历史对话记录（上下文）。
3. 将历史记录和当前用户问题，一并发送给Claude Code。
4. Claude Code基于完整的上下文给出回复并执行操作。
5. 将Claude Code的回复和新的对话历史，以session_id为键，存回数据库。

我们用SQLite来实现这个会话存储，轻量且无需额外服务。表结构大致如下：

CREATE TABLE sessions ( session_id TEXT PRIMARY KEY, history TEXT, -- 存储序列化的对话历史列表 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

history字段通常存储一个JSON字符串，包含了多轮对话的[{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]这样的列表。

注意：这里有一个细节，Claude Code本身是否支持外部传入上下文？根据我的实测，Claude Code的Python SDK (claude-agent-sdk) 在创建会话时，可以传入conversation_history参数。但更常见的做法是，我们在应用层维护这个历史，每次都将完整的历史拼接成提示词（Prompt）的一部分发送给AI。本项目采用的是后一种方式，灵活性更高。

2.3 安全边界思考：让AI操作电脑，如何不“翻车”？

这是本项目最重要的注意事项。赋予一个AI在本地执行命令的能力，风险是显而易见的。我们采取了多层防护：

1. 进程沙箱（最核心）：机器人进程本身不应以高权限（如root/Administrator）运行。创建一个专用的、权限受限的系统用户来运行此服务。
2. 命令过滤（白名单机制）：在将用户指令转发给Claude Code前，可以进行一层简单的关键词过滤。例如，拦截包含rm -rf /、format、dd等危险命令的请求。但要注意，过滤是辅助，不能完全依赖，因为AI的回复可能绕开过滤。
3. 文件系统访问限制：通过运行环境的权限控制，将机器人限制在特定的工作目录下。比如，使用chroot或容器技术，或者简单地在启动脚本中cd到一个指定目录再运行程序。
4. 人工确认（对于高风险操作）：可以在逻辑中设计，当AI试图执行删除文件、安装系统包等操作时，先回复“将要执行XXX，请回复‘确认’以继续”。这增加了安全阀。
5. 审计日志：所有执行过的命令、访问过的文件，都必须详细记录在日志中，方便事后追溯。

在我的实现中，主要依赖第1点和第3点。我强烈建议你在实际部署时，至少在沙箱环境中测试。不要直接在存有重要生产资料的主机上以管理员身份贸然运行。

3. 环境准备与详细配置指南

3.1 基础软件环境搭建

首先，你需要一个Python环境。我推荐使用Python 3.10或以上版本，稳定性更好。使用虚拟环境是一个好习惯。

# 1. 创建并进入项目目录 mkdir remote-claude-code && cd remote-claude-code # 2. 创建虚拟环境（以venv为例） python3 -m venv venv # 3. 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate # 4. 克隆项目代码（假设已有仓库） git clone <项目仓库地址> . # 或者，如果你是从零开始，可以手动创建文件结构

接下来安装项目依赖。核心依赖是飞书的Python SDKlark-oapi和 Claude Code的SDKclaude-agent-sdk。

# 创建requirements.txt文件，内容如下： # lark-oapi>=1.2.0 # claude-agent-sdk # python-dotenv # 然后安装 pip install -r requirements.txt

如果claude-agent-sdk安装遇到问题，可能是因为它还在早期阶段。你可以尝试直接从GitHub安装或关注Anthropic的官方发布。

# 备选方案：从GitHub仓库安装（请确认最新仓库地址） # pip install git+https://github.com/anthropics/claude-agent-sdk-python.git

3.2 飞书应用创建与配置详解

这是配置环节最容易出错的地方，请一步步跟着来。

1. 登录开放平台：访问 飞书开放平台 ，用你的飞书账号登录。
2. 创建企业自建应用：
   • 点击“创建应用”，选择“企业自建应用”。
   • 填写应用名称，如“我的Claude助手”，上传一个图标。
3. 获取凭证：在应用的“凭证与基础信息”页面，你会看到App ID和App Secret。这就是你的机器人的身份证。把它们记下来，稍后填入环境变量。
4. 配置事件订阅（关键步骤）：
   • 进入“事件订阅”页面。
   • 在“请求地址”部分，选择“使用长连接接收事件”。这是本项目与Webhook模式不同的关键，它会让飞书显示一个WebSocket连接地址，我们不需要填写回调URL。
   • 在“订阅事件”部分，点击“添加事件”。
   • 在弹出框中，搜索并添加im.message.receive_v1（接收消息v1.0）这个事件。这意味着机器人将接收用户发给它的消息。
5. 配置权限：
   • 进入“权限管理”页面。
   • 搜索并添加以下权限：
     • im:message（获取用户发给机器人的单聊、群组消息）
     • im:message:send_as_bot（以机器人身份发送消息）
     • 根据是否需要获取发送者信息，决定是否添加im:message.p2p_msg:readonly（读取用户发给机器人的单聊消息）等。
   • 添加权限后，记得在页面底部点击“申请发布版本”。通常开发测试阶段，这些权限可以自动通过。

3.3 Claude Code的安装与登录

Claude Code是执行核心，必须在运行机器人的电脑上安装好。

# 对于macOS和Linux用户，使用官方安装脚本是最简单的 curl -fsSL https://claude.ai/install.sh | bash # 安装后，Claude Code的命令行工具 `claude` 应该就被添加到PATH了。 # 对于Windows用户，需要通过npm安装（请确保已安装Node.js） npm install -g @anthropic-ai/claude-code

安装完成后，需要进行登录认证，将你的Claude账号与本地工具绑定。

claude login

执行这个命令会打开一个浏览器窗口，引导你完成Claude账号的授权。请确保你登录的Claude账号有权限使用Claude Code功能（目前可能需要加入等待列表或拥有特定权限）。

登录成功后，你可以测试一下：

claude “你好”

如果它能回应，说明安装和登录都成功了。

3.4 项目配置与启动

回到我们的项目目录，进行最终配置。

1. 配置环境变量：项目根目录下应该有一个.env.example文件，复制它并重命名为.env。

   cp .env.example .env

   编辑.env文件，填入你在飞书开放平台获取的凭证。

   # .env 文件内容示例 APP_ID=cli_xxxxxxxxxxxx APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx # 你可以添加其他配置，比如日志级别、工作目录限制等 LOG_LEVEL=INFO # WORKSPACE=/path/to/safe/directory (可选，用于限制文件访问范围)

2. 理解启动脚本：项目提供了start.sh和stop.sh方便管理。

   • start.sh：通常做的事情是激活虚拟环境，以后台方式运行主程序src/main_websocket.py，并将日志输出到log.log文件。
   • stop.sh：查找并终止主程序的进程。

   你可以查看start.sh的内容，理解其原理，对于Windows用户，可能需要将其转换为.bat脚本或直接使用Python命令运行。

3. 首次启动与连接：

   # 前台运行，方便查看日志和调试 python -m src.main_websocket

   如果一切配置正确，程序会启动并尝试与飞书的长连接地址建立WebSocket连接。控制台会打印连接日志。此时，回到飞书开放平台应用的“事件订阅”页面，你可能会看到“长连接状态”变为“已连接”。

4. 添加机器人到飞书：

   • 在飞书开放平台应用详情页，找到“版本管理与发布”。
   • 创建一个测试版本并申请发布。
   • 发布后，在“添加能力”中，将机器人添加到你的聊天界面。你可以搜索应用名称，将其添加为好友或拉入群聊。

现在，尝试在飞书中@你的机器人并发送消息吧！

4. 核心模块源码深度解析

4.1 飞书长连接主程序 (main_websocket.py)

这个文件是整个机器人的大脑，负责处理飞书的网络连接、消息路由和会话管理。我们来拆解它的核心流程。

# src/main_websocket.py (核心逻辑摘录与解析) import asyncio import json from lark_oapi import Websocket from src.claude_code import chat_sync # Claude Code 客户端 from src.data_base_utils.session_store import SessionStore # 会话数据库 # 初始化会话存储 session_store = SessionStore('data/sessions.db') async def on_message(websocket, message): """处理飞书WebSocket推送的消息""" try: event_data = json.loads(message) # 1. 解析事件类型和消息内容 if event_data.get('type') == 'event_callback': event = event_data.get('event') if event.get('type') == 'im.message.receive_v1': message_event = event.get('message') chat_id = message_event.get('chat_id') content = json.loads(message_event.get('content', '{}')).get('text', '') # 过滤掉机器人自己的消息和空消息 if message_event.get('sender', {}).get('sender_type') == 'bot' or not content.strip(): return # 2. 获取或创建会话历史 session_history = session_store.get_history(chat_id) or [] # 3. 调用Claude Code获取回复 # 注意：这里需要把历史会话也传给Claude Code的上下文 full_prompt = build_prompt_with_history(session_history, content) reply_text, _ = chat_sync(full_prompt, chat_id) # 使用chat_id作为会话标识 # 4. 更新会话历史 session_history.append({"role": "user", "content": content}) session_history.append({"role": "assistant", "content": reply_text}) # 控制历史长度，防止无限增长消耗token if len(session_history) > 20: # 保留最近10轮对话 session_history = session_history[-20:] session_store.save_history(chat_id, session_history) # 5. 将回复发送回飞书 await send_feishu_reply(chat_id, reply_text) except Exception as e: logging.error(f"处理消息时出错: {e}") def build_prompt_with_history(history, new_message): """将历史对话和当前消息构建成给Claude的提示词""" prompt = "" for turn in history: role = turn["role"] content = turn["content"] prompt += f"{role}: {content}\n" prompt += f"user: {new_message}\nassistant: " return prompt

关键点解析：

• 消息去重：代码中通过判断sender_type来过滤机器人自己发出的消息，避免形成消息循环。
• 历史管理：session_store.get_history/save_history是封装好的数据库操作，用于读写SQLite。这里我设置了一个历史长度上限（如20条消息，即10轮对话），这是一个重要的性能与成本权衡。Claude Code虽然本地运行，但过长的上下文仍可能影响响应速度，并消耗更多资源。
• 提示词构建：build_prompt_with_history函数简单地将历史拼接起来。在实际使用中，你可能需要更精细的模板，比如加入系统指令（System Prompt）来约束AI的行为，例如“你是一个帮助操作电脑的助手，可以执行文件操作和命令，但必须确保安全...”。

4.2 Claude Code客户端封装 (conversation.py)

这个模块封装了与Claude Code交互的细节。Claude Code SDK的使用方式是核心。

# src/claude_code/conversation.py import subprocess import json import logging from typing import Optional, Tuple class ClaudeCodeClient: def __init__(self): # 这里可以初始化一些配置，比如Claude Code的路径、默认参数等 # 默认假设 `claude` 命令已在PATH中 self.claude_cmd = "claude" def chat_sync(self, message: str, session_id: Optional[str] = None) -> Tuple[str, str]: """ 同步方式调用Claude Code进行对话。 Args: message: 用户输入的消息，已经包含了历史上下文。 session_id: 会话ID，用于Claude Code内部维持会话（如果支持）。 目前Claude Code CLI可能更依赖外部维护历史。 Returns: (回复内容, 新的session_id或原session_id) """ try: # 构建命令 # 注意：Claude Code CLI的具体参数可能随版本变化，请以官方文档为准 # 一种常见模式是使用 `--conversation` 或 `--session` 参数传递会话标识 # 但更通用的方式是将整个上下文作为单次提示输入 cmd = [self.claude_cmd, "chat", "--message", message] # 如果Claude Code支持会话ID，可以加上 if session_id: cmd.extend(["--session-id", session_id]) # 执行命令 logging.info(f"执行Claude命令: {' '.join(cmd)}") result = subprocess.run( cmd, capture_output=True, text=True, timeout=60, # 设置超时，防止长时间无响应 shell=False # 安全考虑，避免shell注入 ) if result.returncode == 0: reply = result.stdout.strip() # 可能需要从输出中解析出纯文本回复，移除可能的格式标记 # 例如，Claude Code的输出可能包含一些前缀或JSON格式 # 这里假设stdout就是直接回复 return reply, session_id or "" else: error_msg = f"Claude Code执行失败: {result.stderr}" logging.error(error_msg) return f"抱歉，执行时出现错误: {error_msg}", session_id or "" except subprocess.TimeoutExpired: logging.error("Claude Code响应超时") return "请求超时，请稍后再试或简化您的请求。", session_id or "" except FileNotFoundError: logging.error("未找到Claude Code命令，请检查安装") return "Claude Code未正确安装或配置，请检查系统路径。", session_id or "" except Exception as e: logging.error(f"调用Claude Code时发生未知错误: {e}") return f"系统内部错误: {str(e)}", session_id or "" # 提供简化接口 _client = ClaudeCodeClient() def chat_sync(message: str, session_id: Optional[str] = None) -> Tuple[str, str]: return _client.chat_sync(message, session_id)

实操心得与避坑指南：

1. 子进程超时：subprocess.run的timeout参数至关重要。AI生成代码或执行复杂命令可能耗时很长，必须设置一个合理的超时（如60秒），防止线程被永远挂起。
2. 错误处理：必须全面捕获subprocess可能抛出的异常（TimeoutExpired,FileNotFoundError等），并返回友好的错误信息给用户，而不是让机器人沉默或崩溃。
3. 输出解析：Claude Code CLI的输出格式可能会更新。你需要实际运行一下claude chat --message "你好"，观察其输出是纯文本、JSON还是其他格式，并相应调整解析逻辑。上述代码做了简化处理。
4. 会话保持：session_id参数是否传递给Claude Code，取决于Claude Code CLI是否支持会话保持。如果支持，那么Claude Code内部会维护状态；如果不支持（或我们选择不用），则完全由我们上层的session_store来管理历史，每次调用都传递完整上下文。后者更可控。

4.3 会话存储层 (session_store.py)

用SQLite实现一个简单的键值存储，用于保存对话历史。

# src/data_base_utils/session_store.py import sqlite3 import json import logging from typing import List, Dict, Any, Optional class SessionStore: def __init__(self, db_path: str = "data/sessions.db"): self.db_path = db_path self._init_db() def _init_db(self): """初始化数据库和表""" conn = sqlite3.connect(self.db_path) cursor = conn.cursor() cursor.execute(''' CREATE TABLE IF NOT EXISTS sessions ( session_id TEXT PRIMARY KEY, history TEXT, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ) ''') # 创建索引以提高查询速度 cursor.execute('CREATE INDEX IF NOT EXISTS idx_updated_at ON sessions(updated_at)') conn.commit() conn.close() def get_history(self, session_id: str) -> Optional[List[Dict[str, Any]]]: """获取指定会话的历史记录""" try: conn = sqlite3.connect(self.db_path) cursor = conn.cursor() cursor.execute('SELECT history FROM sessions WHERE session_id = ?', (session_id,)) row = cursor.fetchone() conn.close() if row and row[0]: return json.loads(row[0]) return None except Exception as e: logging.error(f"从数据库获取历史失败 {session_id}: {e}") return None def save_history(self, session_id: str, history: List[Dict[str, Any]]): """保存或更新会话历史""" try: history_json = json.dumps(history, ensure_ascii=False) conn = sqlite3.connect(self.db_path) cursor = conn.cursor() cursor.execute(''' INSERT OR REPLACE INTO sessions (session_id, history, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP) ''', (session_id, history_json)) conn.commit() conn.close() except Exception as e: logging.error(f"保存历史到数据库失败 {session_id}: {e}") def cleanup_old_sessions(self, days: int = 30): """清理超过指定天数的旧会话，避免数据库无限膨胀""" try: conn = sqlite3.connect(self.db_path) cursor = conn.cursor() cursor.execute(''' DELETE FROM sessions WHERE julianday('now') - julianday(updated_at) > ? ''', (days,)) deleted_count = cursor.rowcount conn.commit() conn.close() logging.info(f"清理了 {deleted_count} 个超过{days}天的旧会话") except Exception as e: logging.error(f"清理旧会话失败: {e}")

注意事项：

• 数据库连接管理：上述示例在每次操作时都打开和关闭连接，对于低频操作可以接受。如果消息量很大，应考虑使用连接池或更高效的ORM（如SQLAlchemy）。
• 历史序列化：使用json.dumps保存列表。确保对话内容中没有会导致JSON序列化失败的字符。
• 定期清理：cleanup_old_sessions方法非常重要。如果不清理，SQLite文件会越来越大。可以设置一个定时任务（如Cron或系统定时器）定期调用此方法。

5. 扩展与定制：如何接入其他AI Agent

本项目的架构优势在于其清晰的解耦。飞书消息处理 (main_websocket.py) 和 AI 后端执行 (claude_code/) 之间通过一个简单的chat_sync函数接口连接。这意味着替换Claude Code为其他AI Agent非常容易。

5.1 接口规范

任何想要接入的后端，只需要提供一个符合以下签名的函数：

def chat_sync(message: str, session_id: str = None) -> tuple[str, str]: """ 同步处理消息。 Args: message: 用户输入，通常已包含历史上下文。 session_id: 会话标识符，用于后端维持会话状态（可选）。 Returns: (reply_text, new_session_id) 回复内容和会话ID。 """ # 你的AI逻辑 pass

5.2 扩展示例：接入OpenAI Assistants API

假设你想用OpenAI的GPT-4加上代码解释器（Code Interpreter）能力来替代Claude Code，实现类似但基于云端的文件操作（注意：Code Interpreter是在沙箱中运行，并非直接操作你的本地文件）。

1. 创建新的模块：在src/下创建openai_assistant/目录。
2. 实现客户端：

   # src/openai_assistant/client.py import openai import os from typing import Optional, Tuple class OpenAIAssistantClient: def __init__(self, api_key: str, assistant_id: str): openai.api_key = api_key self.client = openai.OpenAI() self.assistant_id = assistant_id # 维护一个 thread_id 到 session_id 的映射（可选） self.thread_map = {} def chat_sync(self, message: str, session_id: Optional[str] = None) -> Tuple[str, str]: try: # 1. 获取或创建Thread（OpenAI的会话概念） if session_id and session_id in self.thread_map: thread_id = self.thread_map[session_id] else: thread = self.client.beta.threads.create() thread_id = thread.id if session_id: self.thread_map[session_id] = thread_id # 2. 向Thread添加用户消息 self.client.beta.threads.messages.create( thread_id=thread_id, role="user", content=message ) # 3. 运行Assistant run = self.client.beta.threads.runs.create( thread_id=thread_id, assistant_id=self.assistant_id ) # 4. 轮询直到运行完成 while run.status in ["queued", "in_progress"]: time.sleep(0.5) run = self.client.beta.threads.runs.retrieve( thread_id=thread_id, run_id=run.id ) # 5. 获取Assistant的最新回复 if run.status == "completed": messages = self.client.beta.threads.messages.list( thread_id=thread_id ) # 获取最后一条助手的消息 for msg in messages.data: if msg.role == "assistant": reply_text = msg.content[0].text.value return reply_text, session_id or "" else: return f"运行失败，状态: {run.status}", session_id or "" except Exception as e: return f"调用OpenAI API出错: {str(e)}", session_id or "" # 初始化（从环境变量读取配置） import os client = OpenAIAssistantClient( api_key=os.getenv("OPENAI_API_KEY"), assistant_id=os.getenv("OPENAI_ASSISTANT_ID") ) def chat_sync(message: str, session_id: str = None) -> tuple[str, str]: return client.chat_sync(message, session_id)

3. 修改主程序导入：在main_websocket.py中，将from src.claude_code import chat_sync替换为from src.openai_assistant import chat_sync。

5.3 扩展示例：接入本地Ollama模型

如果你希望完全私有化部署，可以使用本地运行的Ollama来提供大模型能力。注意，本地模型通常不具备直接执行命令的功能，但可以通过额外的工具调用框架（如LangChain）来实现。

# src/ollama_agent/client.py import requests import json OLLAMA_API_URL = "http://localhost:11434/api/generate" # Ollama默认地址 def chat_sync(message: str, session_id: str = None) -> tuple[str, str]: """ 调用本地Ollama模型。 注意：这是一个简单示例，未维护复杂上下文。 """ payload = { "model": "qwen2.5:7b", # 替换成你本地安装的模型 "prompt": message, "stream": False } try: response = requests.post(OLLAMA_API_URL, json=payload, timeout=60) response.raise_for_status() result = response.json() reply = result.get("response", "").strip() return reply, session_id or "" except requests.exceptions.RequestException as e: return f"请求Ollama API失败: {e}", session_id or ""

扩展建议：对于Ollama或任何纯对话模型，要实现文件操作，你需要引入一个“工具调用”层。例如，使用LangChain来定义“读取文件”、“执行命令”等工具，让模型通过LangChain来间接操作本地系统。这比直接使用Claude Code复杂，但定制性更强。

5.4 可扩展的Agent选型对比

选择哪种扩展方案，取决于你的具体需求：是追求强大的本地操作（Claude Code），还是需要复杂的推理和云端能力（OpenAI），或是要求完全内网私有化（Ollama+LangChain）。

6. 部署、运维与问题排查实录

6.1 生产环境部署建议

在开发机上跑通只是第一步，要稳定服务团队，需要考虑生产部署。

1. 进程守护：使用start.sh后台运行不够健壮，进程挂了无法自动重启。推荐使用系统级进程管理工具：

   • Linux (Systemd): 创建一个.service文件，用systemctl管理，可以设置自动重启、日志轮转等。
   • macOS (Launchd): 使用.plist文件配置守护进程。
   • 通用工具 (PM2): 如果你熟悉Node.js生态，PM2管理Python进程也非常优秀。pm2 start src/main_websocket.py --interpreter python --name feishu-bot

2. 日志管理：当前的log.log文件会无限增长。需要配置日志轮转（Log Rotation）。使用Python的logging.handlers.RotatingFileHandler可以轻松实现。

   # 在代码中配置日志 import logging from logging.handlers import RotatingFileHandler handler = RotatingFileHandler('app.log', maxBytes=10*1024*1024, backupCount=5) # 每个文件10MB，保留5个备份 logging.basicConfig(level=logging.INFO, handlers=[handler])

3. 资源监控：监控机器人的CPU和内存使用情况。Claude Code进程可能会在处理复杂任务时消耗较多资源。可以写一个简单的监控脚本，或者使用现有的监控系统。

4. 网络考虑：虽然长连接不需要公网IP，但需要确保运行机器人的服务器能稳定访问飞书的服务器（open.feishu.cn）。在公司网络环境下，注意代理或防火墙设置。

6.2 常见问题与排查技巧

以下是我在开发和运行过程中遇到的一些典型问题及解决方法，整理成表方便你快速查阅。

6.3 性能优化小技巧

• 数据库连接池：如果并发量稍高，频繁开关SQLite连接会有开销。可以考虑使用sqlite3的:memory:模式（数据全在内存，重启丢失）或引入一个轻量级连接池。
• 历史上下文长度：这是影响响应速度和AI表现的关键参数。太短，AI可能忘记之前的事；太长，每次请求的Prompt会巨大，导致Claude Code响应变慢。建议根据场景动态调整：对于执行具体任务的对话（如“帮我改这个文件”），保留5-10轮历史足够；对于开放聊天，可以保留更多。可以在session_store.save_history里实现一个更智能的截断策略。
• 异步处理：当前chat_sync是同步调用，如果AI处理耗时久，会阻塞处理新消息。对于高并发场景，可以考虑将耗时的AI调用放入线程池或使用异步函数，但需要注意会话状态的并发安全。

这个项目从构思到能稳定运行，花了不少时间调试飞书的长连接和Claude Code的调用方式。最大的体会是，安全和权限管理必须从一开始就作为最高优先级来设计。先在一个无关紧要的虚拟机或容器里充分测试，再考虑放到日常环境中。现在，它已经成为我们团队内部一个提升效率的利器，希望这份详细的拆解也能帮助你构建属于自己的那个“数字助手”。