基于CoPaw框架构建飞书群聊软件工程师助手：多智能体配置与实战

1. 项目概述

如果你是一个技术团队的负责人，或者是一个经常在飞书、钉钉这类协作工具里泡着的工程师，那你肯定对下面这个场景不陌生：群里有人贴了一段代码问有没有问题，或者甩出一个报错截图求助，然后整个群就陷入了沉默。要么是大家手头都忙，要么是问题太具体，一时半会儿没人能给出靠谱的答案。这种时候，你是不是特别希望有个“懂行”的同事能随时在线，自动帮你把这些问题接过去，给出专业的分析和建议？

今天要聊的这个copaw-multi-agent项目，就是来解决这个痛点的。它不是一个全新的AI框架，而是基于阿里云通义实验室开源的CoPaw框架，深度定制的一套“软件工程师助手”多智能体配置方案。简单来说，CoPaw框架提供了“大脑”和“躯干”，而copaw-multi-agent项目则给它注入了“软件工程师”的灵魂和记忆，让它能像一个真正的技术专家一样，在飞书群聊里自动响应技术问题、审查代码、讨论架构。

这个项目的核心价值在于，它把通用AI助手从一个“什么都能聊但什么都不精”的聊天机器人，变成了一个垂直领域的“专家”。它内置了对技术关键词（如“bug”、“review”、“架构”）的自动识别能力，无需@就能主动响应。更重要的是，它拥有围绕团队协作设计的记忆系统，能记住群里的项目、成员专长、历史技术决策，让每一次回答都更有上下文，更像一个真正的团队成员。

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

2.1 为什么选择“配置即代码”的模式？

初次接触这个项目，你可能会疑惑：为什么不直接开发一个全新的机器人，而是基于CoPaw做配置？这背后其实是一个很务实的工程决策。

2.1.1 避免重复造轮子CoPaw框架本身已经解决了AI Agent最复杂、最通用的部分：大语言模型（LLM）的调用与管理、对话状态维护、工具（Tools）的集成与调度、与外部频道（如飞书、钉钉）的通信适配。如果从零开始，你需要处理网络请求、消息解析、异步处理、错误重试等一系列底层问题，这无疑会分散你解决核心业务问题（即“如何当好一个软件工程师助手”）的精力。copaw-multi-agent项目选择站在巨人的肩膀上，只专注于“角色扮演”和“业务逻辑”的配置。

2.1.2 快速迭代与定制化配置文件（Markdown文件）相比硬编码的程序，修改起来成本极低，且无需重新编译或部署。这意味着产品经理、技术负责人甚至是不太懂代码的团队成员，都可以通过修改SOUL.md（定义角色性格）或AGENTS.md（定义运营策略）来调整机器人的行为。比如，今天发现助手对“K8s”相关的问题响应不够积极，明天你只需要在关键词列表里加上“Kubernetes”、“Pod”、“Deployment”这几个词，重启服务就能生效。这种灵活性是传统开发模式难以比拟的。

2.1.3 清晰的职责分离项目的结构清晰地划分了关注点：

• 框架层（CoPaw）：负责“怎么想”和“怎么动”。即，提供思考的引擎（LLM）和行动的手脚（工具调用、消息发送）。
• 配置层（本项目）：负责“想什么”和“做什么”。即，定义角色的知识领域、响应策略、记忆规则和沟通风格。

这种分离使得框架的升级和配置的优化可以并行不悖。即使未来CoPaw框架版本升级，只要核心配置文件的格式和API保持兼容，copaw-multi-agent的配置大概率只需微小调整就能迁移。

2.2 多智能体（Multi-Agent）系统是如何工作的？

虽然项目名叫“multi-agent”，但在CoPaw V0.0.5的上下文中，它并非指同时运行多个独立的、可互相通信的AI实体。这里的“多智能体”更准确地理解为“单核心智能体的多角色、多策略响应模式”。

2.2.1 核心工作流程拆解整个系统的响应流程可以概括为一个智能路由决策过程：

1. 消息监听：CoPaw框架的飞书频道适配器，实时监听绑定的群聊消息。
2. 意图识别与路由：这是本项目的核心增强点。当一条新消息到达时，系统会执行以下判断：
   • 是否触发关键词？扫描SOUL.md中定义的技术关键词列表（如“代码”、“报错”、“架构”）。如果命中，则进入高优先级处理队列。
   • 是否需要@？根据AGENT_CONFIG.md中的设置，判断该群是否开启了“免@响应”模式。如果开启，即使没有@机器人，只要命中关键词，也会触发响应。
   • 属于哪类问题？根据消息内容，初步归类为“代码审查”、“Bug定位”、“架构咨询”等类型。这一步可能依赖简单的规则匹配，也可能通过调用LLM进行轻量级分类。
3. 上下文构建：系统从memory/目录中加载与该群聊、该用户、当前讨论话题相关的历史记忆。这包括：
   • 近期的对话记录。
   • 该用户曾经提过的问题类型和解决情况。
   • 群内正在进行的项目背景（从MEMORY.md中定义的记忆规则提取）。
4. 生成与执行：将构建好的上下文（用户问题+历史记忆+问题类型）发送给LLM。LLM基于SOUL.md中定义的“软件工程师”角色设定，生成符合该角色专业口吻和知识的回复。如果回复中需要执行某些操作（如调用一个代码分析工具），则由CoPaw框架调度相应的工具执行。
5. 记忆更新与发送：将本次交互的完整记录（问与答）按照MEMORY.md定义的格式，归档到memory/YYYY-MM-DD.md文件中，形成长期记忆。同时，将生成的回复通过飞书频道适配器发送回群聊。

2.2.2 记忆系统的设计哲学普通聊天机器人的记忆往往是短暂且扁平的，只记住最近几轮对话。而作为一个“团队助手”，它的记忆必须是长期、结构化且多维度的。copaw-multi-agent通过文件系统模拟了一个简单的记忆库：

• 对话历史（memory/YYYY-MM-DD.md）：按天存储原始对话，便于回溯。
• 向量记忆（embedding_cache/和file_store/）：这是实现“智能”检索的关键。系统会将重要的对话片段、代码示例、决策结论等，通过嵌入模型（Embedding Model）转化为向量，并存储到向量数据库（如ChromaDB）中。当用户提出一个新问题时，系统会进行向量相似度搜索，从历史中找出最相关的信息作为上下文。例如，当有人问“我们上次怎么解决OOM的？”，系统能快速找到几个月前关于JVM调优的那次讨论。
• 知识档案（PROFILE.md,SOUL.md）：定义了助手的静态知识，如它的技能栈（熟悉Java、微服务）、行事原则（优先给出可落地的方案）、服务边界（不回答与工作无关的问题）。

实操心得：记忆的“冷启动”问题新部署的助手就像一个刚入职的新人，对团队一无所知。为了让它快速“融入”，项目提供了BOOTSTRAP.md文件。我强烈建议你在首次运行前，手动在这里“喂”一些信息：比如团队正在开发的核心项目简介、常用的技术栈、几位核心成员负责的领域。这能极大提升助手早期回答的准确性和相关性，避免它从“零知识”开始瞎猜。

3. 核心配置文件深度解析与实操要点

项目的威力完全体现在几个核心的配置文件中。理解并熟练修改它们，你才能打造出真正贴合自己团队需求的“数字同事”。

3.1SOUL.md：定义角色的“灵魂”

这个文件决定了助手“是谁”以及“如何思考”。它远不止是一个技能列表。

3.1.1 性格与口吻设定你需要在这里明确助手的沟通风格。是严肃认真的技术专家？还是幽默活泼的团队伙伴？例如：

## 核心设定 - **性格**：严谨、务实、乐于助人。回答以解决问题为导向，避免空泛的理论。 - **口吻**：像一位资深的同事。使用“我们”而不是“你”，例如“我们可以这样优化...”、“这里有个坑我们之前踩过...”。 - **边界**：专注于技术问题。对于薪资、八卦、明确要求违法操作等话题，应礼貌拒绝并引导回工作。

这个设定会直接影响LLM生成文本的风格。一个“幽默”的设定可能会在代码审查时加入一些玩笑话，而“严谨”的设定则会让回复看起来更像一份正式的技术报告。

3.1.2 能力范围与知识声明必须清晰地划定助手的知识边界，这既是管理预期，也是防止“幻觉”（即AI瞎编）的重要手段。

## 专业技能 - **精通**：Java后端开发、Spring生态、MySQL、Redis、RESTful API设计。 - **熟悉**：微服务架构（Spring Cloud）、Docker、Kubernetes基础、消息队列（Kafka/RabbitMQ）。 - **了解**：前端基础（Vue/React）、 DevOps流程、基础算法。 - **不擅长**：硬件开发、UI设计、深度机器学习模型调参。

在声明“不擅长”的领域时，可以同时给出引导，比如：“对于UI动效问题，建议直接咨询前端组的XXX同学。”

3.1.3 触发关键词的精细化管理关键词列表是助手从“被动”变为“主动”的开关。设计时需要考虑同义词和场景。

## 响应触发词 ### 高优先级（立即响应） - **错误/故障类**：`报错`， `Exception`, `error`, `bug`, `崩溃`， `不行了`， `出问题了` - **代码审查类**：`review`, `看看代码`， `帮我看看`， `PR`, `merge request`, `代码片段` - **性能类**：`慢`， `卡顿`， `超时`， `CPU高`， `内存泄漏`， `OOM` ### 中优先级（可稍后响应） - **架构设计类**：`架构`， `设计`， `方案`， `选型`， `怎么设计` - **技术讨论类**：`大家觉得`， `有什么想法`， `讨论一下`

你可以通过观察团队群聊的高频词汇，不断丰富这个列表。注意，过于宽泛的词（如“问题”）可能会造成误触发，需要谨慎添加。

3.2AGENT_CONFIG.md与AGENTS.md：定义行为的“规则”

这两个文件共同决定了助手“怎么做”。

3.2.1 频道绑定与响应规则 (AGENT_CONFIG.md)这里是硬件连接层配置，主要绑定具体的飞书群。

# 飞书群聊绑定配置 群聊 ID: "oc_xxxxxxxxxx" # 在飞书群设置中可找到 群聊名称: "技术攻坚小分队" 响应模式: "智能触发" # 可选：智能触发 / 仅@响应 / 静默 免@响应白名单: ["代码", "报错", "bug"] # 在“智能触发”模式下，这些词即使不@也回复 响应延迟范围: [5, 30] # 单位：秒。随机延迟响应，避免显得像机器人

响应延迟范围是一个提升体验的小技巧。立即响应虽然快，但有时会让人感觉“被监视”。加入一个随机延迟（比如5-30秒），会让助手的出现显得更自然，像是真人刚看到消息并思考后回复。

3.2.2 运营策略与话术模板 (AGENTS.md)这个文件是运营手册，规定了在不同场景下应该如何回应。

## 常见场景响应模板 ### 场景：代码审查 - **识别模式**：消息中包含代码块（```）或“review”、“看看”等词。 - **响应流程**： 1. 感谢分享：`收到，我来看看这段代码。` 2. 分段分析：按`功能性`、`可读性`、`性能`、`安全性`几个维度给出意见。 3. 给出具体建议：**必须指出具体行号**和修改方案。 4. 结尾开放：`以上是我的建议，大家怎么看？` ### 场景：报错求助 - **识别模式**：消息中包含“Exception”、“error”、“怎么办”和堆栈信息。 - **响应流程**： 1. 共情与安抚：`这个错误确实挺常见的，别急。` 2. 定位根因：从堆栈信息中提取最相关的错误类和行号，给出**最可能的两到三种原因**。 3. 提供排查步骤：给出可操作的检查清单，例如“1. 检查数据库连接；2. 查看XXX配置项是否为null...”。 4. 引导搜索：`也可以尝试用这个错误信息的关键词在团队知识库/Confluence里搜索一下。`

预先定义好话术模板，不仅能保证回复质量稳定，还能减轻LLM的负担，让它更专注于技术分析部分，而不是组织语言。

3.3MEMORY.md与HEARTBEAT.md：让助手拥有“时间感”

3.3.1 记忆的存储与索引 (MEMORY.md)这里定义了哪些信息值得被长期记住，以及如何存储。

## 记忆归档规则 - **永久记忆（存入向量库）**： - 所有最终被采纳的技术方案和决策理由。 - 经典的代码范例和反模式。 - 线上故障的根因分析和复盘结论。 - 团队成员自我介绍的技能点（如“张三擅长性能调优”）。 - **短期记忆（仅保留30天）**： - 日常的、未形成结论的技术讨论。 - 简单的、一次性的问题解答。 - **不记忆**： - 与工作无关的闲聊。 - 未经确认的、道听途说的信息。

3.3.2 定时任务与主动服务 (HEARTBEAT.md)一个优秀的助手不能只等别人来问。HEARTBEAT.md让它具备了主动服务的能力。

## 定时任务配置 - **每日 10:00**: 晨间同步 - 动作：查询项目管理系统（如Jira），列出**当天到期或即将逾期**的任务，@相关责任人。 - 话术：`大家早！以下是今天需要关注的任务：...` - **每周五 17:00**: 技术周报生成 - 动作：扫描本周 `memory/` 目录，总结讨论最多的三个技术话题、已解决和未解决的Top问题。 - 话术：`本周技术小总结：1. 关于XXX的讨论最多；2. YYY问题已解决；3. ZZZ问题仍需跟进...` - **每月1日 10:00**: 知识库提醒 - 动作：检查是否有“永久记忆”类的内容尚未整理到团队Wiki，提醒相关人。

这些定时任务将助手从一个“问答机”变成了一个“团队协作者”，能有效提升技术团队的运营效率。

4. 从零到一的完整部署与配置实战

理论说得再多，不如亲手搭一个。下面我将以在MacOS/Linux系统上，部署一个连接到真实飞书技术群的“软件工程师助手”为例，展示完整流程。

4.1 前期准备：账号、令牌与环境

4.1.1 创建飞书机器人这是助手与外界沟通的“嘴巴”和“耳朵”。

1. 登录 飞书开发者后台 。
2. 点击“创建企业自建应用”，填写应用名称，如“Tech-Buddy”。
3. 在“权限与能力”中，至少开通以下权限：
   • im:message(接收与发送单聊、群聊消息)
   • im:message.group_at_msg(接收群聊中@机器人的消息)
   • im:message.p2p_msg(接收单聊消息)
4. 在“事件订阅”中，配置请求网址（URL）。这里先空着，等我们本地服务启动并获得公网地址后再来填写。需要订阅的事件包括：
   • im.message.receive_v1(接收消息)
5. 在“凭证与基础信息”页面，拿到至关重要的四件套：
   • App ID
   • App Secret
   • Encrypt Key（如果开启了加密）
   • Verification Token

4.1.2 本地开发环境准备确保你的机器已经安装了Python 3.8+和Git。

# 检查Python版本 python3 --version # 安装虚拟环境管理工具（推荐） pip install virtualenv # 创建一个干净的虚拟环境 virtualenv copaw-env # 激活虚拟环境 # MacOS/Linux: source copaw-env/bin/activate # Windows: # .\copaw-env\Scripts\activate

激活后，命令行提示符前会出现(copaw-env)标识。

4.2 核心框架安装与初始化

4.2.1 安装CoPaw框架在激活的虚拟环境中，执行安装命令。建议指定版本以确保与copaw-multi-agent配置兼容。

pip install copaw==0.0.5

安装完成后，初始化一个工作区。copaw init命令会创建一个默认的配置目录。

copaw init --defaults # 初始化后，通常会提示工作区目录，一般是 ~/.copaw/workspaces/default # 我们将其重命名或直接使用 cd ~/.copaw/workspaces mv default software-engineer-assistant cd software-engineer-assistant

现在，你的software-engineer-assistant目录就是CoPaw框架的工作目录了。

4.2.2 获取并应用Agent配置将copaw-multi-agent的配置克隆到这个工作目录。注意：这会覆盖原有的默认配置。

# 确保你在 ~/.copaw/workspaces/software-engineer-assistant 目录下 # 备份原有文件（如果是全新初始化，可跳过） # cp -r . ../backup_before_multi_agent # 克隆本项目配置 git clone https://github.com/shengshengyi/copaw-multi-agent.git . # 如果提示目录非空，可以先删除所有文件再克隆，或者手动复制文件。 # 更安全的方式是：删除目录内所有文件后克隆 # rm -rf * .[!.]* # 慎用，删除所有文件和隐藏文件 # git clone https://github.com/shengshengyi/copaw-multi-agent.git tmp && mv tmp/* tmp/.[!.]* . && rmdir tmp

克隆完成后，你会看到SOUL.md,AGENT_CONFIG.md等配置文件已经就位。

4.3 关键配置修改与调优

4.3.1 配置飞书连接参数编辑AGENT_CONFIG.md文件，找到飞书配置部分，填入之前获取的凭证。

# 飞书机器人配置 (位于 AGENT_CONFIG.md 中) feishu: app_id: "cli_xxxxxxxxxx" # 替换为你的 App ID app_secret: "xxxxxxxxxxxxxxxxxxxxxxxx" # 替换为你的 App Secret encrypt_key: "" # 如果创建应用时未开启加密，此处留空 verification_token: "xxxxxxxxxxxxxxxxxxxx" # 替换为你的 Verification Token # 群聊绑定 group_id: "oc_xxxxxxxxxxxxxxxxxx" # 替换为你的飞书群聊ID

如何获取群聊ID？在飞书群中，右键点击群头像 -> “设置” -> “群组信息”下拉到底，即可看到“群聊ID”。

4.3.2 个性化你的助手这是最关键的一步，让助手变成“你们团队的”助手。

1. 修改SOUL.md：根据你团队的技术栈，更新“专业技能”部分。如果你们主要用Go和Vue，就把Java/Spring换成Go/Gin和Vue。
2. 修改PROFILE.md：给助手起个名字，比如“小码”，写一段符合团队文化的自我介绍。
3. 修改AGENTS.md中的响应模板：观察团队平时的沟通习惯，是喜欢直接给方案，还是喜欢先讨论？调整话术模板以匹配。
4. 初始化BOOTSTRAP.md：在这里写入团队的基本信息。例如：

   ## 团队知识初始化 - **当前核心项目**：电商平台重构项目，正在将单体应用拆分为用户、商品、订单三个微服务。 - **技术栈**：后端主语言为Go 1.19，使用Gin框架，数据库是PostgreSQL和Redis，部署在K8s上。 - **团队成员专长**： - 张三：擅长数据库性能优化和分布式事务。 - 李四：对K8s和Service Mesh有深入研究。 - **近期技术债务**：订单服务的超时设置不合理，需要调整。

4.3.3 配置环境变量（可选但推荐）为了避免敏感信息硬编码在配置文件里，可以通过环境变量传入。在启动服务前设置：

export COP_FEISHU_APP_ID="cli_xxxxxxxxxx" export COP_FEISHU_APP_SECRET="xxxxxxxxxxxxxxxxxxxxxxxx" export COP_FEISHU_GROUP_ID="oc_xxxxxxxxxxxxxxxxxx" # 然后在 AGENT_CONFIG.md 中，使用变量引用： # feishu: # app_id: "${COP_FEISHU_APP_ID}" # app_secret: "${COP_FEISHU_APP_SECRET}" # group_id: "${COP_FEISHU_GROUP_ID}"

CoPaw框架通常支持这种环境变量替换，具体需查看其文档。

4.4 服务启动与飞书配置闭环

4.4.1 启动本地CoPaw服务在配置好所有文件后，在虚拟环境中启动服务。

copaw run

如果一切正常，你会看到服务启动日志，并监听某个本地端口（如http://localhost:8000）。

4.4.2 暴露本地服务到公网飞书的服务器需要能访问到你的CoPaw服务，才能推送消息。本地地址localhost是不行的。你需要一个内网穿透工具。

• 推荐工具：ngrok。它简单易用。

  # 安装ngrok (需注册账号获取token) # 访问 https://ngrok.com/ 注册并获取你的Authtoken ngrok config add-authtoken YOUR_AUTH_TOKEN # 启动隧道，映射到CoPaw服务的端口（假设是8000） ngrok http 8000

  启动后，ngrok会给你一个随机的公网地址，如https://abc123.ngrok-free.app。

4.4.3 完成飞书事件订阅配置回到飞书开发者后台，找到你创建的应用。

1. 进入“事件订阅”。
2. 在“请求网址”中，填写ngrok给你的地址，并加上CoPaw框架的事件接收路径。通常CoPaw框架的飞书事件接收路径是/feishu/event。所以完整的URL可能是：https://abc123.ngrok-free.app/feishu/event。
3. 点击“保存”，飞书会向这个地址发送一个带有verification_token的验证请求。只要你的本地copaw run服务正常运行且配置正确，验证会自动通过。
4. 在“订阅事件”中，勾选im.message.receive_v1，再次保存。

4.4.4 添加机器人到群聊在飞书开发者后台的应用“版本管理与发布”中，创建一个版本并申请发布。审核通过（或直接在企业内自建应用可用）后，你就可以在飞书里搜索这个应用（如“Tech-Buddy”），并将其添加到你的技术群中。

4.5 验证与测试

完成以上所有步骤后，在你的飞书技术群里：

1. 尝试@机器人并说“你好”。
2. 发送一段包含“bug”关键词的消息，比如“这里好像有个bug”。
3. 发送一段代码片段（用三个反引号包裹）。 观察助手的响应是否符合预期。如果没反应，依次检查：

• copaw run服务日志是否有错误。
• ngrok隧道是否在线。
• 飞书后台的事件订阅状态是否显示“验证成功”。
• 机器人在群里的权限是否足够。

5. 高级调优、问题排查与避坑指南

部署成功只是第一步，要让助手真正好用，还需要持续的“调教”和问题解决。

5.1 性能与成本优化

5.1.1 响应速度优化

• 问题：用户提问后，助手响应太慢（超过1分钟）。
• 排查与解决：
  1. 检查网络与LLM API：最大的延迟通常来自调用OpenAI或通义千问等大模型API。确保你的网络稳定，且使用的API Key没有限速。可以考虑使用响应速度更快的模型（如GPT-3.5-Turbo相比GPT-4速度更快，成本更低）。
  2. 精简上下文（Context）：每次提问，系统都会将相关的历史记忆作为上下文发送给LLM。如果记忆文件过大，会导致请求包巨大，影响速度。在MEMORY.md中严格定义“永久记忆”的筛选标准，避免存储过多无关对话。可以设置上下文Token数上限。
  3. 向量检索优化：如果使用了向量搜索，确保embedding_cache和向量数据库的索引是有效的。对于小规模数据，可以考虑使用更轻量的本地向量库，如FAISS或ChromaDB的轻量模式。

5.1.2 Token使用与成本控制

• 问题：API调用费用增长过快。
• 策略：
  • 设置对话轮次上限：在CoPaw框架或Agent配置中，限制单次对话引用的历史轮次（例如，只引用最近10条相关对话）。
  • 总结式记忆：对于冗长的讨论，不要让助手记忆原始对话，而是配置一个“总结”工具。在对话结束后，自动调用LLM生成一段摘要（如“2024-05-20：团队讨论了A方案与B方案的优劣，最终决定采用A，原因是...”），只将摘要存入长期记忆。这极大减少了未来检索时消耗的Token。
  • 使用更经济的模型：对于简单的关键词匹配、分类任务，可以尝试使用小模型或本地模型，只在需要深度分析和生成时调用大模型。

5.2 效果提升：让回答更准、更智能

5.2.1 解决“幻觉”与胡言乱语

• 现象：助手给出的技术方案听起来合理，但实际上是编造的，或者引用了不存在的库、API。
• 根治方法：
  • 强化角色设定：在SOUL.md的“原则”部分，加入强约束。例如：“严格原则：对于不确定的技术细节，特别是API版本、库的精确用法，必须明确声明‘这一点我不太确定，建议查阅官方文档（附上链接）’。绝对禁止编造不存在的功能或参数。”
  • 提供参考来源：配置“网络搜索”或“知识库查询”工具。当助手需要引用具体信息时，强制它先调用工具获取真实资料，并基于此生成回答。
  • 人工反馈循环：在AGENTS.md中设置，当助手对自己的回答置信度低于某个阈值时，在回复末尾加上一句：“这是我的初步分析，建议再复核一下官方文档。”

5.2.2 提升上下文关联能力

• 现象：助手经常忘记几分钟前刚讨论过的内容，或者无法将当前问题与历史类似问题关联。
• 优化方案：
  • 优化向量检索策略：检查存入向量库的记忆片段质量。确保存入的是有信息量的“事实”或“结论”，而不是“你好”、“在吗”这样的寒暄。可以尝试不同的文本分块（Chunking）策略和嵌入模型。
  • 显式记忆链接：在重要的技术讨论结束后，可以手动或通过定时任务，让助手生成一个“记忆链接”。例如：“关于‘接口超时设置’的讨论，已关联到知识库文档《超时配置规范V2.0》。”并将此链接存入记忆。

5.3 常见问题排查实录

5.3.1 机器人完全无响应

• 检查清单：
  1. 飞书端：机器人是否已成功添加到群？在群成员列表里能看到吗？是否有发言权限？
  2. 网络隧道：ngrok隧道是否还在运行？地址是否变更？去飞书后台更新请求网址。
  3. 服务日志：查看copaw run的日志，是否有启动错误、连接失败或消息解析异常。
  4. 配置校验：确认AGENT_CONFIG.md中的app_id,app_secret,group_id完全正确，尤其是群ID，很容易复制错。

5.3.2 机器人能收到消息但不回复

• 检查清单：
  1. 触发规则：检查消息是否满足SOUL.md中的关键词触发条件，或者是否@了机器人。在AGENT_CONFIG.md中，响应模式是否设置正确？
  2. LLM API：检查CoPaw框架中配置的LLM API Key是否有效、是否有余额。查看日志中是否有“API调用失败”、“认证错误”等信息。
  3. 内容过滤：某些群可能设置了安全策略，阻止机器人发送包含代码块或链接的消息。检查飞书机器人的“安全设置”。

5.3.3 回复内容质量差、答非所问

• 检查清单：
  1. 上下文污染：检查memory/目录下的文件，是否混入了大量无关对话？清理掉非技术讨论的记录。
  2. 角色设定偏差：回顾SOUL.md，角色设定是否足够清晰？尝试将“专业技能”部分写得更具体、更狭窄。
  3. Prompt工程：CoPaw框架在调用LLM前会组合一个系统Prompt。查看框架文档，看是否允许自定义这个系统Prompt。你可以在其中加入更严格的指令，如“你是一名专业的Java后端工程师，只回答技术问题...”。

5.3.4 内存占用过高或进程崩溃

• 检查清单：
  1. 记忆文件膨胀：memory/目录下的Markdown文件是否无限增长？配置一个定时任务（可通过crontab或框架的定时器），定期归档或清理老旧文件（如只保留最近90天的）。
  2. 向量数据库：如果使用了ChromaDB等，其数据文件可能越来越大。定期清理无效的嵌入向量。
  3. 工具调用泄漏：检查是否有工具（如代码执行沙箱）没有正确释放资源。