造岛 ZaoDao 适配 WorkBuddy 指南：从 Claude Code/Codex 到腾讯 AI 工作台的平滑迁移

本文以企业级全栈开发平台造岛 ZaoDao为实际案例，分享如何将一个深度集成 Claude Code 和 Codex 的开源项目，适配到腾讯 WorkBuddy AI 办公工作台，实现 AI 辅助开发工具链的平滑迁移。

一、背景介绍

1.1 造岛 ZaoDao 是什么？

造岛 ZaoDao 是一个企业级全栈开发平台，采用可插拔模块体系，核心理念是"如同在汪洋中造岛，一块一块，稳扎稳垒"。

技术栈：

层级	技术选型
后端	Java 17 / Spring Boot 3.3.6 / MyBatis-Plus / MySQL 8
前端	Vue 3 + TypeScript + Element Plus + Vite 6
移动端	uni-app (Vue 3) → 微信小程序 / H5 / App
低代码	Schema 驱动应用构建器，设计态 + 运行态

核心特性：

多模块架构：核心模块与业务模块分离，按需引入
低代码平台：可视化页面配置，快速构建业务模块
流程引擎：内置工作流引擎，支持自定义流程设计
权限管理：用户、角色、菜单权限体系 + 数据行级权限
多租户支持：原生多租户架构，租户数据隔离
微信生态：深度集成小程序、公众号、企业微信、微信支付
AI 辅助开发：集成 Claude Code、Codex 等 AI 开发工具

1.2 为什么要适配 WorkBuddy？

造岛项目此前深度集成了 Claude Code 和 Codex 两个 AI 开发工具，项目根目录下维护了 .claude/ 和 .codex/ 两套配置，包含 43 个项目专属 Skills、自定义 Hooks、权限配置等。

但这两个工具存在一些局限：

Claude Code：需要 API Token 配置，国内访问不稳定
Codex：与 Claude Code 配置体系不互通，需要维护两套 Skills 副本
两者均侧重代码生成，在文档撰写、数据分析、部署运维等全场景能力上有所欠缺

WorkBuddy是腾讯推出的全场景 AI 办公工作台，核心优势在于：

一句话下达任务，自主规划执行：不只是对话，而是真正"干活"
本地文件操作：可读取授权的电脑文件夹，进行批量处理
多任务并行：支持同时发起和管理多个任务
全场景覆盖：代码开发、文档生成、数据分析、PPT 制作、深度研究
MCP 连接器生态：支持飞书、钉钉、企业微信、腾讯文档等腾讯办公生态
Skills 技能系统：可自定义项目级 Skills，让 AI 理解项目规范
国内网络友好：腾讯云服务，无需翻墙

二、适配核心工作

2.1 适配全景图

复制代码

造岛项目 AI 工具链适配全景

Claude Code (.claude/)          WorkBuddy
├── settings.local.json    →    MCP 配置 (~/.workbuddy/mcp.json)
├── skills/ (43个)         →    skills/ (根目录, 43个)
├── hooks/ (3个脚本)       →    AGENTS.md 项目上下文
├── CLAUDE.md              →    AGENTS.md (统一入口)
└── CONTEXT_SOLUTION.md    →    内置 LCM 无损上下文管理

Codex (.codex/)                  WorkBuddy
├── skills/ (39个)         →    skills/ (与 .claude 同步)
└── 配置文件                →    AGENTS.md 统一管理

2.2 第一步：编写 AGENTS.md --- 项目上下文的统一入口

WorkBuddy 通过读取项目根目录的 AGENTS.md 文件来理解项目上下文。这个文件相当于 Claude Code 的 CLAUDE.md，但更加结构化。

造岛项目的 AGENTS.md 包含以下关键章节：

markdown 复制代码

# AGENTS.md - Scaffold v2 Workspace

## Project Overview
Scaffold v2 --- 企业级全栈开发平台，可插拔模块体系。
- Backend: Java 17 / Spring Boot 3.3.6
- Frontend: Vue 3 + TypeScript + Element Plus + Vite 6
- Mobile: uni-app (Vue 3)
- Low-code: Schema 驱动应用构建器

## Common Commands
### Backend
mvn clean compile                    # 全量编译
mvn spring-boot:run -pl scaffold-admin  # 启动

### Frontend
npm run dev            # Dev server port 3000
npm run build          # vue-tsc type-check + vite build

## Architecture
### Backend 4-Layer Architecture (强制)
Controller → Service → Repository → Mapper

### Pluggable Module System
scaffold-common ← all modules depend on this
  ├── scaffold-redis     ← optional
  ├── scaffold-security  ← JWT auth
  ├── scaffold-tenant    ← multi-tenant
  ├── scaffold-system    ← users, roles, menus
  └── scaffold-admin     ← main app

编写要点：

Common Commands 必须准确：WorkBuddy 会直接执行这些命令，路径、端口、profile 都要写清楚
Architecture 要有层次：用表格和代码块清晰展示架构约束，AI 会据此生成符合规范的代码
Code Style 要明确：缩进、行宽、命名规范，AI 会严格遵守
包含 Skill 触发规则：明确什么操作该触发哪个 Skill，避免 AI 盲目操作

2.3 第二步：Skills 系统迁移

这是适配工作中最重要的一环。造岛项目在 .claude/skills/ 下维护了 43 个项目专属 Skills，涵盖从数据库规范到支付模块开发的各个方面。

Skills 目录结构

复制代码

skills/
├── scaffold-coding/          # 编码规范（4层架构、命名、异常处理）
├── scaffold-database/        # 数据库规范（建表、命名、索引）
├── scaffold-security/        # 安全模块（JWT、权限）
├── scaffold-tenant/          # 多租户模块
├── scaffold-pay/             # 支付模块（微信/支付宝）
├── scaffold-bpm/             # 流程引擎模块
├── scaffold-lowcode/         # 低代码平台
├── scaffold-wechat/          # 微信生态集成
├── scaffold-deploy/          # 部署运维
├── scaffold-codegen/         # 代码生成器
├── ...                       # 共 43 个 Skills

迁移过程

WorkBuddy 自动发现项目根目录 skills/ 下的 SKILL.md 文件，按 frontmatter 中的触发条件自动激活。迁移过程分为三步：

第一步：全量复制

bash 复制代码

# 将 .claude/skills 的全部内容复制到根 skills/ 目录
cp -r .claude/skills/* skills/

第二步：同步 .codex/skills

bash 复制代码

# Codex 智能体也使用同一套 Skills
cp -r .claude/skills/* .codex/skills/

第三步：验证一致性

bash 复制代码

# 确认三个目录的文件数量和内容完全一致
find skills -type f | wc -l           # 48
find .claude/skills -type f | wc -l   # 48
find .codex/skills -type f | wc -l    # 48

# 抽查内容一致性
diff .claude/skills/scaffold-database/SKILL.md skills/scaffold-database/SKILL.md
# 无输出 = 完全一致

Skill 文件示例

以 scaffold-database 为例，展示 Skill 的结构：

markdown 复制代码

---
name: scaffold-database
description: 造岛项目数据库规范与操作指南
trigger:
  - 建表 / 修改表结构 / 编写 DDL
  - 实体类修改 / Mapper 编写
  - 数据库迁移脚本
---

# Scaffold Database Skill

## 1. 数据库基本规范
- MySQL 8.0，UTF8MB4 字符集
- 雪花ID (ASSIGN_ID)，不使用自增ID

## 2. 表前缀规则（强制）
| 前缀 | 适用范围 | 示例 |
|------|----------|------|
| sys_ | 系统核心表 | sys_user, sys_role |
| t_{模块}_ | 业务模块 | t_pay_order, t_product_spu |
| bpm_ | 流程引擎 | bpm_process_instance |
| lc_ | 低代码 | lc_model, lc_field |

## 3. 字段规范
- 主键：id BIGINT，雪花算法
- 逻辑删除：deleted TINYINT(1) DEFAULT 0
- 状态字段：status TINYINT DEFAULT 1（0=停用 1=正常）

2.4 第三步：MCP 连接器配置

WorkBuddy 的 MCP (Model Context Protocol) 连接器是其区别于 Claude Code 的重要特性。通过 MCP，WorkBuddy 可以连接腾讯文档、飞书、企业微信等外部服务。

造岛项目适配中，我们在 ~/.workbuddy/mcp.json 中配置了需要的连接器：

json 复制代码

{
  "mcpServers": {
    "tencent-docs": {
      "command": "npx",
      "args": ["@anthropic/mcp-tencent-docs"]
    }
  }
}

与 Claude Code 的差异：

特性	Claude Code	WorkBuddy
配置位置	`.claude/settings.local.json`	`~/.workbuddy/mcp.json`
生态	依赖社区 MCP Server	内置腾讯办公生态连接器
激活方式	自动	需在连接器管理页面点击"信任"
安全	API Token 明文存储	连接器授权机制

2.5 第四步：记忆系统适配

WorkBuddy 提供三层记忆系统，替代了 Claude Code 时代的手动上下文管理方案。

三层记忆架构

复制代码

Layer 1 --- 云端记忆 (只读)
├── 用户画像 (服务端自动生成)
└── 历史会话检索 (conversation_search)

Layer 2 --- 用户级本地记忆
└── ~/.workbuddy/MEMORY.md (跨项目, 4000字符限制)

Layer 3 --- 工作区记忆 (项目级)
├── .workbuddy/memory/MEMORY.md     (长期项目笔记)
└── .workbuddy/memory/YYYY-MM-DD.md (每日工作日志, 只追加)

对比 Claude Code 的 CONTEXT_SOLUTION.md：

造岛项目此前维护了一个 CONTEXT_SOLUTION.md 文件用于手动备份和恢复上下文。适配 WorkBuddy 后，这一手动机制被内置的 LCM (Lossless Context Management) 取代，无需手动 /compact，上下文自动无损压缩和恢复。

工作区记忆实践

markdown 复制代码

# .workbuddy/memory/2026-07-03.md

## Skills 目录同步
- 将 .claude/skills/ 的 43 个 skills 同步到根 skills/ 目录
- 同步 .codex/skills/ 至与 .claude/skills/ 完全一致
- 三个目录现在完全统一：43 skills / 48 files

每次完成实质性工作后，WorkBuddy 会自动追加日志，确保跨会话的上下文连续性。

2.6 第五步：清理遗留文件

适配完成后，清理 Claude Code 时代的遗留文件：

文件/目录	处理方式	原因
`CONTEXT_SOLUTION.md`	可删除	WorkBuddy 内置 LCM 替代
`claude.sh`	可删除	Claude Code 专用脚本
`.claude/hooks/`	可删除	WorkBuddy 不支持 Claude Code Hooks
`.claude/settings.local.json`	清理 Token	含明文 API Token，安全风险
`.gitignore`	保留	已正确忽略 `.claude/`、`.codex/`

三、适配效果

3.1 开发效率提升

场景	Claude Code	WorkBuddy	提升
新增业务模块	手动描述规范 + 生成代码	AGENTS.md 自动注入 + Skills 自动触发	规范一致性提升
数据库建表	需手动提醒规范	scaffold-database Skill 自动激活	减少沟通成本
部署运维	仅代码层面	可执行 deploy.sh + 分析日志	全流程覆盖
文档撰写	不支持	原生支持	新增能力
跨会话上下文	手动 CONTEXT_SOLUTION	自动 LCM + 三层记忆	无需手动维护

3.2 Skills 触发示例

当我对 WorkBuddy 说"帮我新增一个支付订单表"时：

WorkBuddy 读取 AGENTS.md，理解项目是 Spring Boot + MyBatis-Plus 架构
自动匹配 scaffold-database Skill（触发条件：建表 / DDL）
自动匹配 scaffold-pay Skill（触发条件：支付模块开发）
按 Skill 规范生成 SQL：表名 t_pay_order，雪花ID，逻辑删除字段，状态字段
按 4 层架构生成 Java 代码：Controller → Service → Repository → Mapper

整个过程无需手动提醒任何规范，AI 自动遵循项目约定。

3.3 实际使用体验

复制代码

用户：帮我给 scaffold-pay 模块新增一个退款记录表

WorkBuddy（自动执行）：
1. 读取 AGENTS.md → 理解项目架构
2. 激活 scaffold-database Skill → 获取建表规范
3. 激活 scaffold-pay Skill → 获取支付模块规范
4. 生成 DDL：CREATE TABLE t_pay_refund ...
5. 生成 Entity：PayRefund extends BaseEntity
6. 生成 Mapper：PayRefundMapper extends BaseMapper
7. 生成 Repository：PayRefundRepository extends ServiceImpl
8. 生成 Service：PayRefundService / PayRefundServiceImpl
9. 生成 Controller：PayRefundController（@PostMapping, Result<T>）
10. 追加工作日志到 .workbuddy/memory/

四、踩坑经验

4.1 Skills 目录不统一

问题： 项目同时存在三个 skills 目录（.claude/skills/、.codex/skills/、根 skills/），但只有 .claude/skills/ 是完整的 43 个，根 skills/ 只有 14 个，导致 WorkBuddy 加载不到 29 个关键 Skills。

解决： 以 .claude/skills/ 为权威来源，全量同步到另外两个目录。

bash 复制代码

cp -r .claude/skills/* skills/
cp -r .claude/skills/* .codex/skills/

4.2 Skill 内容版本不一致

问题： 即使是都存在的 Skills，不同目录下的内容也有差异。例如 scaffold-database 在 .claude 版本中有完整的表前缀规则、索引规范，但根 skills/ 版本内容简略，导致 AI 生成的 SQL 不符合规范。

解决： 统一以 .claude/skills/ 版本为准，覆盖所有目录。后续更新也只修改一处，再同步。

4.3 API Token 安全

问题： .claude/settings.local.json 中包含明文 API Token，虽然 .gitignore 已忽略 .claude/，但如果项目文件夹被分享或打包，仍有泄露风险。

解决： 迁移到 WorkBuddy 后，Token 由 WorkBuddy 统一管理，不再需要项目级配置文件存储密钥。

4.4 AGENTS.md 的 Skill 触发规则

问题： WorkBuddy 不会自动推断什么时候该用哪个 Skill，需要在 AGENTS.md 中明确触发规则。

解决： 在 AGENTS.md 中添加触发映射表：

markdown 复制代码

## Skill 触发规则（强制）

| 操作类型 | 必须触发的 Skill |
|---------|------------------|
| scaffold-server 模块代码修改 | 对应模块的 SKILL.md |
| 执行 DDL / 修改实体类 | scaffold-database |
| 支付相关开发 | scaffold-pay |
| 部署相关操作 | scaffold-deploy |

五、总结与展望

适配成果

造岛 ZaoDao 项目成功从 Claude Code/Codex 迁移到 WorkBuddy，实现了：

43 个项目 Skills 全量迁移，三个目录完全统一
AGENTS.md 统一项目上下文，替代 CLAUDE.md + CONTEXT_SOLUTION.md
三层记忆系统替代手动上下文管理，跨会话上下文连续性更好
全场景 AI 能力：从纯代码开发扩展到文档、数据分析、部署运维
国内网络友好：无需 API Token 配置和代理

适用场景建议

场景	推荐工具
企业级全栈项目开发	WorkBuddy + AGENTS.md + Skills
需要腾讯办公生态集成	WorkBuddy (MCP 连接器)
需要文档/数据分析/PPT	WorkBuddy (原生支持)
纯代码生成（需海外网络）	Claude Code