弗兰的悲惨之旅
99.73M · 2026-04-04
我叫王坚，不是阿里的那个王坚，我是飞鱼 Admin 项目的运维负责人。
2026 年 4 月初，我接手了一个棘手的任务：改造我们团队的多 Agent 协作系统。
这个系统由 13 个独立的 AI Agent 组成——有负责技术的、有负责市场的、有负责产品的、有负责测试的。它们通过飞书群协作，但协作效率极低：跨 Bot 消息经常丢失、记忆系统混乱、各 Bot 之间互相"不认识"、代码质量没有保障、技术债务越积越深。
我是运维出身，深知一个道理：系统稳定性高于一切。但协作系统的"稳定性"，不是服务器不宕机，而是信息不丢失、决策可追溯、任务不落空。
整个改造分为两天完成。本文记录第一天的核心工作：iCode 研究部署、PHPStan 质量保障体系建设，以及多 Agent 技能体系的初步搭建。
在改造之前，我们的系统存在以下问题：
问题一：记忆丢失
每天凌晨 00:00，所有 Bot 的会话重置。昨天讨论的 v3 开发计划、团队分工、技术决策，全部丢失。新会话开始时，Bot 不记得任何事情，一切从零开始。
这意味着：每次新会话都要重新解释背景、重新确认分工、重新讨论已经确定的事项。团队花时间讨论的东西，因为技术限制，全部被遗忘。
问题二：跨 Bot 通信失效
飞书群里 @ 某个 Bot 发消息，有时候能收到，有时候石沉大海。经过排查，发现是 open_id 配置和实际不符——Bot 的飞书 open_id 早就变了，但配置里还是旧的。
更糟糕的是：这种失效是隐性的，消息发出去没有报错，但对方就是收不到。直到对方主动在群里说"我没收到"才发现问题。
问题三：代码质量无保障
飞鱼 Admin 项目是一个有相当规模的 PHP 项目（ThinkPHP 8），随着功能迭代，代码里积累了大量的历史包袱。没有静态检查、没有质量门槛、每次上线都像踩雷。
问题四：技能不成体系
当需要 Bot 完成特定任务时，没有标准化的流程和规范。同样的任务，不同的 Bot 可能用完全不同的方式处理，导致结果参差不齐。
目标一：记忆不丢失 —— 跨日会话可追溯
目标二：通信必达 —— 跨 Bot 消息可靠路由
目标三：质量前置 —— 代码改动必过检查
目标四：技能标准化 —— 每个 Bot 都有专业能力
iCode 是 Claude Code 的进阶工具包。最初我以为它只是一个"更强的 AI 编程工具"，但在研究其源码结构之后，我发现它的价值不在于"能做什么"，而在于"怎么做的设计思想"。
iCode 的源码结构极其干净，所有能力以独立 skill 形式组织在 src/skills/bundled/ 目录下。这意味着我们可以直接阅读源码、理解其设计思想，然后迁移到自己的系统。
这一点是很多"工具"做不到的——它们黑箱化，用户只知道怎么用，不知道为什么这样设计。而 iCode 是完全透明的。
环境信息：
部署路径：/www/wwwroot/icode/iCode-main/
API：MiniMax-M2.7-highspeed
端点：
部署过程中的关键 patch 涉及三个文件：
// preflightChecks.tsx — 预检逻辑
// oauth.ts — 认证流程
// client.ts — 自定义 baseURL 支持（这是让 iCode 使用 MiniMax API 的关键）
配置完成后，在服务器上通过 SSH 登录，运行 ./icode 即可交互使用。
这是最有价值的部分。iCode 的 skills 目录里藏着 14 个技能，每一个都是精心设计的 prompt 模板。让我详细介绍我认为最有价值的三个。
传统的 AI 辅助是串行的：
问问题 A → 等回答 → 问问题 B → 等回答 → 问问题 C → ...
这种模式的问题：当有 30 个相互独立的子任务时，串行处理需要等待 30 次，效率极低。
batch 的核心思想是同时启动 5-30 个独立的分析 Agent，并行工作，最后汇总。
// batch 的简化逻辑模型
const forks = tasks.map(task => ({
name: task.name,
description: task.description,
prompt: `针对 ${task.target}，执行以下任务：${task.instruction}`
}))
// 所有 fork 共享 prompt cache，零额外开销
这对大型代码重构意义重大。比如我们需要重构 30 个 PHP 文件，传统方式要串行处理 30 次；batch 模式下，30 个任务同时进行，总耗时等于最慢的那一个，效率提升几十倍。
适用场景：
传统 code review 是这样的：一个人从头看到尾，看完给出一份综合报告。
问题是：一个人的视角是有限的。技术大牛可能忽略安全风险，安全专家可能忽略性能问题。
simplify 的创新在于同时启动三个 Agent，分别从不同视角审查代码：
Agent1（复用视角）：有没有重复代码？有没有可以抽象成公共函数的？
Agent2（质量视角）：有没有 hack、冗余、安全泄漏、边界条件缺失？
Agent3（效率视角）：有没有 N+1 查询、重复计算、内存泄漏、阻塞操作？
三个 Agent 独立工作，最后汇总成一份完整的改进报告。这比任何单一视角的 review 都要全面。
这是最朴素也最容易被忽视的原则。
verify 的设计就是为了解决这个问题。它内置了四种验证模式：
模式一：CLI 验证
适用场景：命令改动、脚本修复、工具升级
# 验证 PHP 文件语法
php -l /path/to/file.php
# 验证 Docker 配置
docker ps
# 验证 nginx 配置
nginx -t
# 检查退出码
command && echo "SUCCESS" || echo "FAILED"
模式二：HTTP 验证
适用场景：API 改动、登录流程、接口修复
# 获取 token
TOKEN=$(curl -s -X POST
-d '{"username":"admin","password":"admin123"}'
| jq -r '.data.token')
# 验证用户列表接口
curl -s
-H "Authorization: Bearer $TOKEN" | jq .
# NL2SQL 接口验证
curl -s -X POST
-H "Authorization: Bearer $TOKEN"
-d '{"question":"用户总数"}' | jq .
模式三：服务验证
适用场景：部署重启、容器启动、进程存活
# 进程存活
ps aux | grep feiyuadmin | grep -v grep
# 端口
ss -tlnp | grep 8088
# 日志无报错
tail -20 /www/wwwlogs/feiyuadmin-error.log | grep -i error
# 健康端点
curl -f 2>/dev/null && echo "OK" || echo "FAIL"
模式四：数据库验证
适用场景：迁移、初始化、数据完整性
# 迁移状态
docker exec feiyuadmin-php php artisan migrate:status
# 数据查询
docker exec feiyuadmin-mysql mysql -u root -p -e "SELECT COUNT(*) FROM fy_users"
# 连接测试
docker exec feiyuadmin-mysql mysql -u root -p -e "SELECT 1"
很多团队对静态检查的态度是"等有空了再上"。这是一个危险的误解。
代码质量问题的成本，随时间指数级增长：
开发阶段发现问题 → 修复成本 = 1x
测试阶段发现问题 → 修复成本 = 5x
上线后发现问题 → 修复成本 = 20x
用户投诉后发现问题 → 修复成本 = 100x
静态检查的价值，在于把"发现问题的时机"提前到开发阶段，而不是等到上线后。
PHPStan 有 0-9 级，级别越高检查越严格。
| 级别 | 检查内容 | 误报率 |
|---|---|---|
| Level 0-4 | 基础类型安全 | 低 |
| Level 5 | 空指针、类型不安全、魔法数字 | 中 |
| Level 6-9 | 极度严格 | 高 |
我们选择 Level 5 有深意：
Level 6-9 的问题：会产生大量误报——比如检查第三方库的严格类型，但第三方库本身没有做严格类型声明。这会导致开发团队对静态检查产生"狼来了"效应，真正的错误也被忽略。
Level 5 的价值：覆盖了空指针调用、类型不安全、魔法数字等高置信度问题，同时误报率可控，团队可以接受。
当前状态：
检查级别：Level 5
已知错误数：1135 个
处理方式：记录在 phpstan-baseline.neon（基线文件）
新错误：实时拦截
旧错误：逐步清理
钩子：pre-commit hook 已配置
基线机制的设计哲学是：不追求一步到位，而是让团队在不影响日常工作的情况下逐步提升质量。
1135 个已知错误不会阻塞新的检查，只有新引入的问题才会被拦截。这比"一次性修完全部问题再上检查"要现实得多——后者基本上永远做不到。
当系统里有 13 个独立的 AI Agent 时，每个 Agent 都需要两样东西：
knowing what to do → 什么时候该做什么
knowing how to do it → 怎么做
没有技能体系之前，Agent 只能靠"上下文记忆"——把一堆指令塞进 prompt，让它自己判断。但上下文是有限的，指令多了就会互相干扰。
技能体系的核心思想是：把"怎么做"的流程固化下来，变成可复用的工具。
| 技能 | 功能 | 解决的问题 |
|---|---|---|
| code-tools | Grep/Glob/Edit/Task/Bash | 高频工具统一接口 |
| code-explore | 只读代码探索 | 防止误改关键文件 |
| code-plan | 软件架构规划 | 大任务分解路径 |
| code-verify | 对抗性验证 | 找薄弱点，不是证明它工作 |
| code-review | 安全+并发+边界审查 | 上线前的最后一道关 |
| code-simplify | 三视角并行审查 | 复用/质量/效率全覆盖 |
| code-semantic | 语义级符号理解 | 跳转到定义、查找引用 |
| team-coord | 多 Bot 协作调度 | 复杂任务的并行协调 |
| memory-organizer | 三层记忆整理 | 短期→长期的正确流动 |
team-coord 是花最多时间设计的技能，核心理念来自 iCode 的 Coordinator Mode。
传统任务分配的逻辑是这样的：
用户说：做个聊天功能
Bot A：好的，我来负责
Bot B：好的，我来配合
（结果：职责不清，互相等待）
Coordinator Mode 的工作流：
Phase 1：并行研究
→ sessions_send 同时发给所有相关 Bot
→ 各 Bot 分别调查自己负责的模块
Phase 2：综合理解
→ 协调者必须先读懂所有调查结果
→ 自己产出具体执行方案
Phase 3：执行分配
→ 给具体的文件路径、行号、成功标准
Phase 4：验证
→ 必须贴实测结果，不是口头说"可以了"
最关键的一条原则——"Never delegate understanding"：
错误做法：
"基于刘强东的调查，自己理解要做什么"
正确做法：
"在 /path/file.php 第 42 行，找到 handleQuery() 方法，
user_id 字段可能为空，在访问之前加 null check，
如果为空返回 401"
这条原则在实际协作中极其重要。当协调者把任务说清楚时，执行者只需要执行，不需要猜测。
多 Agent 系统的致命弱点：每天凌晨 00:00，所有会话重置，昨天讨论的内容全部丢失。
这不是 bug，是设计选择——Agent 的上下文窗口有限，不可能无限累积。但对于需要"记住之前讨论"的工作场景，这是严重缺陷。
我们部署了统一归档机制：
# /etc/cron.d/openclaw-archive
0 2 * * * /root/.openclaw/scripts/archive-all-bots.sh
# 覆盖范围（8个 Bot）：
# mayun, liujq, liyanh, zhouhy,
# wangj, mahuit, mengyt, daji
每天凌晨 02:00，自动将每个 Bot 的当天会话整理成 memory/YYYY-MM-DD.md 文件。
这实现了：
历史可查：昨天的讨论在 memory/2026-04-02.md
快速恢复：新会话通过 memory_search 检索历史
跨 Bot 共享：各 Bot 的归档独立但格式统一
# 伪代码
for bot in $COVERED_BOTS; do
session_file="/root/.openclaw/agents/$bot/sessions/sessions.json"
# 读取当日会话
today_session=$(filter_by_date $session_file $(date +%Y-%m-%d))
# 整理成标准格式
formatted=$(format_as_markdown $today_session)
# 写入归档
echo "$formatted" >> /root/.openclaw/workspace-$bot/memory/$(date +%Y-%m-%d).md
done
iCode 给了我们一个示范：把能力封装成 skill，把 skill 的设计思想写进文档。
当团队里的每个 Agent 都知道"为什么"时，它们才能真正高效协作，而不是机械执行指令。
PHPStan + pre-commit hook 的组合，让代码质量检查变成了"每次提交自动发生"的事情。这比"等上线后才发现问题"要高效 20 倍。
协调者必须先理解问题再分配任务——这其实对人类协作同样适用。很多团队效率低下的根源就是：任务分配者自己都没想清楚要做什么，就急着往下推。
第一天的核心工作，是建立基础设施和协作规范。
这不是最耀眼的工作，但它是所有后续工作的基础。
当代码质量有保障、Agent 职责清晰、跨日记忆不丢失之后，第二天的深度改造才成为可能——飞书 relay 路由的全面修复、记忆系统的 iCode Taxonomy 改造、以及一个真正精准的多 Bot 协作框架。
