Feishu Subagent Creator

SKILL.md

# feishu-subagent-creator - 飞书子 Agent 创建向导

**功能：** 引导用户创建新的子 Agent，并**自动完成所有配置**，无需用户手动编辑文件。

**触发词：** 创建子 agent、添加新角色、创建飞书机器人、绑定新 agent、多 agent 配置

---

## 使用方式

### 方式 1：对话引导（推荐）

直接说："创建一个新的子 agent" 或 "添加一个新的飞书机器人角色"

我会逐步引导你完成以下流程，**所有配置自动完成**：

1. **收集角色信息** - 名称、性格、定位等（我会解释什么是 Agent ID）
2. **创建飞书应用** - 指导你在飞书开放平台创建应用（逐步截图级指引）
3. **自动创建 Agent** - 自动创建工作空间、人设文件、目录结构
4. **自动配置路由** - 自动修改 openclaw.json，添加 agent、account、binding
5. **自动重启 Gateway** - 使配置生效
6. **测试验证** - 确认新 Agent 正常工作

### 方式 2：命令行调用

```bash
openclaw skills run feishu-subagent-creator -- \
  --agent-id "new-role" \
  --agent-name "新角色名称" \
  --feishu-app-id "cli_xxx" \
  --feishu-app-secret "xxx"
```

---

## 参数说明

| 参数 | 必填 | 说明 |
|------|------|------|
| `--agent-id` | ✅ | Agent 的唯一标识（小写字母 + 数字 + 短横线） |
| `--agent-name` | ✅ | Agent 的显示名称 |
| `--feishu-app-id` | ✅ | 飞书应用的 App ID（cli_xxx 格式） |
| `--feishu-app-secret` | ✅ | 飞书应用的 App Secret |
| `--model` | ❌ | 使用的模型（默认 miaoda/glm-5） |

---

## 详细流程

### 步骤 1：收集角色信息

我会询问以下信息，**并告诉你每个信息的含义和如何确定**：

#### 1.1 角色名称
- **是什么：** 这个 Agent 在飞书中显示的名字
- **如何确定：** 想一个符合角色定位的名字
- **示例：** `客服助手 `、`技术专家`、` 销售专员`

#### 1.2 Agent ID
- **是什么：** 系统内部用来标识这个 Agent 的唯一代号
- **如何确定：** 用角色名称的英文或拼音，全部小写，单词间用短横线连接
- **格式要求：** 只能包含小写字母（a-z）、数字（0-9）、短横线（-）
- **示例：** 
  - 客服助手 → `customer-service`
  - 技术专家 → `tech-expert`
  - 销售专员 → `sales-bot`

#### 1.3 角色定位
- **是什么：** 这个 Agent 主要负责什么任务
- **如何确定：** 用一句话描述它的核心职责
- **示例：** `回答客户咨询问题`、`处理技术支持请求`、`协助销售流程`

#### 1.4 性格特点
- **是什么：** 这个 Agent 的说话风格和语气
- **如何确定：** 想 2-4 个形容词描述它的个性
- **示例：** `专业严谨但耐心 `、`活泼开朗爱开玩笑`、`简洁直接高效率`

#### 1.5 Emoji（可选）
- **是什么：** 代表这个角色的表情符号
- **如何确定：** 选一个符合角色气质的 emoji
- **示例：** 客服→💁、技术→🔧、销售→💼、通用→🤖

---

### 步骤 2：创建飞书应用

我会提供**截图级的详细操作指引**，即使从未接触过飞书开放平台也能完成：

#### 2.1 访问飞书开放平台
- **网址：** https://open.feishu.cn/app
- **操作：** 在浏览器中打开，用你的飞书账号登录
- **提示：** 需要使用企业管理员账号或有应用创建权限的账号

#### 2.2 创建企业自建应用
- **操作步骤：**
  1. 点击页面右上角的「创建应用」按钮
  2. 在弹出的窗口中选择「企业自建应用」
  3. 填写应用名称：建议填写「{角色名称}助手」，如「客服助手」
  4. 填写应用描述（可选）：简单描述这个应用的用途
  5. 选择一个应用图标：可以上传角色头像或选择一个默认图标
  6. 点击「确定」完成创建

#### 2.3 复制凭证（App ID 和 App Secret）
- **在哪里找：**
  1. 创建应用后，自动进入应用管理页面
  2. 在左侧菜单点击「凭证与基础信息」
  3. 页面会显示 App ID 和 App Secret
- **操作步骤：**
  1. 复制 App ID（格式如：`cli_a9420019bb78dbcd`）
  2. 点击 App Secret 右侧的「查看」按钮
  3. 复制 App Secret（一串字母数字组合）
- **⚠️ 重要：** App Secret 只显示一次，请务必妥善保存！如丢失需重新生成

#### 2.4 配置权限
- **在哪里找：** 左侧菜单 →「权限管理」
- **操作步骤：**
  1. 在权限管理页面，找到「权限配置」区域
  2. 点击「批量导入」按钮
  3. 在弹出的文本框中粘贴以下 JSON：

```json
{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot",
      "im:message:readonly",
      "im:chat.members:bot_access",
      "contact:user.employee_id:readonly"
    ],
    "user": ["im:chat.access_event.bot_p2p_chat:read"]
  }
}
```

  4. 点击「确定」完成导入
  5. 确认权限列表中出现了刚才导入的权限

#### 2.5 启用机器人能力
- **在哪里找：** 左侧菜单 →「应用功能」→「机器人」
- **操作步骤：**
  1. 点击「机器人」进入配置页面
  2. 打开「启用机器人」开关
  3. 设置机器人名称：填写你的角色名称，如「客服助手」
  4. （可选）上传机器人头像
  5. 点击「保存」

#### 2.6 配置事件订阅（关键步骤）
- **在哪里找：** 左侧菜单 →「事件订阅」
- **⚠️ 前置条件：** 必须先启动 OpenClaw Gateway，否则长连接无法配置
- **检查 Gateway 是否运行：**
  ```bash
  openclaw gateway status
  ```
  如果未运行，先执行：
  ```bash
  sh scripts/restart.sh
  ```
- **操作步骤：**
  1. 在事件订阅页面，找到「事件接收配置」
  2. 选择「使用长连接接收事件」（不要选 webhook）
  3. 点击「添加事件」按钮
  4. 在搜索框中输入 `im.message`
  5. 选择 `im.message.receive_v1` 事件
  6. 点击「确定」保存
  7. 如果提示「验证失败」，请检查 Gateway 是否正常运行

#### 2.7 发布应用
- **在哪里找：** 左侧菜单 →「版本管理与发布」
- **操作步骤：**
  1. 点击「创建版本」按钮
  2. 填写版本号：如 `1.0.0`
  3. 填写版本说明：如「初始版本」
  4. 点击「提交审核」
  5. 企业自建应用通常自动审核通过，等待几秒即可
  6. 审核通过后，点击「发布」按钮

---

### 步骤 3：自动创建 Agent（无需用户操作）

我会**自动完成**以下操作：

#### 3.1 创建目录结构
```
/home/gem/workspace/agent/agents/{agent-id}/
├── agent/              # 运行时配置
├── workspace/          # 工作空间
│   ├── SOUL.md        # 核心人格
│   ├── IDENTITY.md    # 身份设定
│   ├── AGENTS.md      # 工作指南
│   ├── USER.md        # 用户信息
│   └── memory/        # 日志目录
└── sessions/          # 会话存储
```

#### 3.2 生成人设文件
- **SOUL.md** - 核心人格模板
- **IDENTITY.md** - 根据用户输入自动生成
- **AGENTS.md** - 工作指南
- **USER.md** - 用户信息

---

### 步骤 4：自动配置 openclaw.json（无需用户操作）

我会**自动读取并修改**配置文件，添加：

#### 4.1 agents.list
自动添加新的 Agent 定义

#### 4.2 channels.feishu.accounts
自动添加新的飞书账户

#### 4.3 bindings
自动添加路由绑定

#### 4.4 tools.agentToAgent.allow
自动更新允许列表

---

### 步骤 5：自动重启 Gateway（无需用户操作）

配置完成后，我会：
1. 自动备份现有配置
2. 应用新配置
3. 重启 Gateway
4. 验证重启成功

---

### 步骤 6：测试验证

#### 6.1 在飞书中测试
1. 打开飞书
2. 在搜索框中搜索你的新机器人名称
3. 点击进入对话
4. 发送一条测试消息，如「你好」
5. 检查是否收到回复

#### 6.2 验证会话隔离
1. 用新机器人发送消息
2. 切换到其他机器人
3. 询问刚才和新机器人聊的内容
4. 如果其他机器人不知道，说明会话隔离正常

---

## 自动化能力说明

### ✅ 我能自动完成的

| 任务 | 说明 |
|------|------|
| 创建目录结构 | 自动创建 agent、workspace、sessions 目录 |
| 生成人设文件 | 自动写入 SOUL.md、IDENTITY.md 等 |
| 读取配置 | 自动读取 openclaw.json 当前内容 |
| 修改配置 | 自动添加 agent、account、binding 配置 |
| 备份配置 | 修改前自动备份 |
| 重启 Gateway | 自动执行重启命令 |
| 验证状态 | 自动检查 Gateway 运行状态 |

### ⚠️ 需要用户配合的

| 任务 | 原因 |
|------|------|
| 创建飞书应用 | 需要用户在飞书开放平台操作 |
| 复制 App ID/Secret | 涉及安全凭证，需用户确认 |
| 配置飞书权限 | 需要在飞书开放平台操作 |
| 配置事件订阅 | 需要在飞书开放平台操作 |

---

## 注意事项

### ⚠️ 安全提醒
- **App Secret 存储：** 建议使用 secrets provider，不要明文存储
- **权限最小化：** 只配置必要的权限
- **备份配置：** 修改前自动备份 `openclaw.json`

### ✅ 最佳实践
- **Agent ID 命名：** 使用小写字母 + 短横线，如 `customer-service`
- **工作空间隔离：** 每个 Agent 独立的工作空间
- **人设差异化：** 确保每个 Agent 有独特的性格和定位
- **会话隔离：** 设置 `dmScope: "per-channel-peer"`

### 🔧 故障排查
| 问题 | 解决方案 |
|------|----------|
| 飞书长连接配置失败 | 先启动 Gateway，再配置事件订阅 |
| 消息路由错误 | 检查 `bindings` 中 `accountId` 是否匹配 |
| 会话混淆 | 设置 `dmScope: "per-channel-peer"` |
| 权限不足 | 确保应用已发布且权限完整 |
| 机器人不回复 | 检查事件订阅是否配置了 `im.message.receive_v1` |
| App Secret 找不到 | 在「凭证与基础信息」页面重新生成 |

---

## 示例对话

**助手：** 好的！我来帮你创建一个新的子 Agent。首先，请告诉我：

1. 这个新角色的**名称**是什么？（如"客服助手"、"销售专员"）
   > 💡 提示：这是用户在飞书中看到的机器人名字

2. 你希望它的 **Agent ID** 是什么？（小写字母 + 短横线，如 `customer-service`）
   > 💡 提示：可以用角色名称的英文或拼音，如客服助手→customer-service

3. 这个 Agent 主要负责什么**任务**？
   > 💡 提示：用一句话描述它的核心职责

4. 它的**性格特点**是怎样的？（如"专业严谨"、"活泼开朗"）
   > 💡 提示：想 2-4 个形容词描述它的个性

**用户：** 名称是"技术专家"，Agent ID 叫 tech-expert，负责回答技术问题，性格专业严谨但耐心

**助手：** 收到！接下来我们需要在飞书开放平台创建一个新应用。请按照以下步骤操作：

**步骤 1：访问飞书开放平台**
1. 在浏览器中打开：https://open.feishu.cn/app
2. 用你的飞书账号登录

**步骤 2：创建企业自建应用**
1. 点击右上角「创建应用」
2. 选择「企业自建应用」
3. 填写应用名称：「技术专家助手」
4. 选择一个图标
5. 点击「确定」

**步骤 3：复制 App ID 和 App Secret**
1. 在左侧菜单点击「凭证与基础信息」
2. 复制 App ID（格式如：cli_xxx）
3. 点击 App Secret 右侧的「查看」，复制 Secret

请完成上述步骤后，告诉我你的 App ID 和 App Secret。

**用户：** App ID 是 cli_a9420019bb78dbcd，Secret 是 xxx

**助手：** 好的！现在开始自动创建 Agent...

✅ 已创建目录：/home/gem/workspace/agent/agents/tech-expert
✅ 已生成 SOUL.md
✅ 已生成 IDENTITY.md
✅ 已生成 AGENTS.md
✅ 已生成 USER.md
✅ 已备份 openclaw.json
✅ 已添加 agent 配置
✅ 已添加飞书账户配置
✅ 已添加路由绑定
✅ 已更新 agentToAgent 允许列表
✅ 已重启 Gateway

新 Agent 创建完成！现在可以在飞书中搜索「技术专家」并开始对话了。

---

## 相关文件

- 主配置：`/home/gem/workspace/agent/openclaw.json`
- Agent 工作空间：`/home/gem/workspace/agent/agents/{agent-id}/workspace/`
- 会话存储：`/home/gem/workspace/agent/agents/{agent-id}/sessions/`

---

**标签：** 飞书、多 Agent、子 agent 创建、机器人绑定、配置向导、自动化