142 lines
4.5 KiB
Markdown
142 lines
4.5 KiB
Markdown
---
|
||
name: lark-action-as-bot
|
||
version: 1.0.0
|
||
description: "飞书 Bot 身份操作指南：指导每个 agent 如何以自己的应用（bot）身份执行 lark-cli 命令。包含环境变量配置、凭证隔离、bot 身份调用规范。当 agent 需要以 bot 身份操作飞书资源（知识库、文档、消息等）时使用。"
|
||
metadata:
|
||
requires:
|
||
bins: ["lark-cli"]
|
||
---
|
||
|
||
# 以 Bot 身份操作飞书
|
||
|
||
本技能指导你（AI agent）如何以**自己的应用身份（bot）**独立执行飞书操作。
|
||
|
||
## 核心机制
|
||
|
||
每个 agent 拥有独立的飞书应用凭证，存放在各自的配置目录中。通过设置 `LARKSUITE_CLI_CONFIG_DIR` 环境变量，让 `lark-cli` 读取对应 agent 的凭证，实现身份隔离。
|
||
|
||
## Agent 凭证目录
|
||
|
||
| Agent | 配置目录 |
|
||
|-------|---------|
|
||
| xiaoxi（小溪） | `/root/.openclaw/credentials/xiaoxi/` |
|
||
| xiaoban（小斑） | `/root/.openclaw/credentials/xiaoban/` |
|
||
| xiaobian（小编） | `/root/.openclaw/credentials/xiaobian/` |
|
||
| xiaoyan（小研） | `/root/.openclaw/credentials/xiaoyan/` |
|
||
| xiaokui（小葵） | `/root/.openclaw/credentials/xiaokui/` |
|
||
| may（May） | `/root/.openclaw/credentials/may/` |
|
||
|
||
每个目录下包含 `config.json`，格式为：
|
||
|
||
```json
|
||
{
|
||
"apps": [
|
||
{
|
||
"appId": "<该agent的appId>",
|
||
"appSecret": "<该agent的appSecret>",
|
||
"brand": "feishu",
|
||
"lang": "zh",
|
||
"users": []
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 调用规范
|
||
|
||
### 基本格式
|
||
|
||
**所有 lark-cli 命令前必须加上环境变量前缀：**
|
||
|
||
```bash
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> lark-cli <command> --as bot
|
||
```
|
||
|
||
### 确定你的 agent_name
|
||
|
||
你需要根据自己的身份确定 `agent_name`。查看你的 IDENTITY.md 或 workspace 目录名称来确认。例如：
|
||
- 如果你是小斑，`agent_name` 为 `xiaoban`
|
||
- 如果你是小溪，`agent_name` 为 `xiaoxi`
|
||
|
||
### 常用操作示例
|
||
|
||
#### 读取知识库文档
|
||
|
||
```bash
|
||
# 1. 解析 wiki 链接获取真实文档 token
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
|
||
lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}' --as bot
|
||
|
||
# 2. 获取文档内容
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
|
||
lark-cli docs +fetch --doc <obj_token> --as bot
|
||
```
|
||
|
||
#### 编辑知识库文档
|
||
|
||
```bash
|
||
# 追加内容
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
|
||
lark-cli docs +update --doc <obj_token> --as bot --markdown '要追加的内容' --mode append
|
||
|
||
# 覆盖内容
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
|
||
lark-cli docs +update --doc <obj_token> --as bot --markdown '新的完整内容' --mode overwrite
|
||
```
|
||
|
||
#### 搜索文档
|
||
|
||
```bash
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
|
||
lark-cli docs +search --query '搜索关键词' --as bot
|
||
```
|
||
|
||
#### 发送消息
|
||
|
||
```bash
|
||
LARKSUITE_CLI_CONFIG_DIR=/root/.openclaw/credentials/<agent_name> \
|
||
lark-cli im messages create --as bot --data '{"receive_id":"<id>","msg_type":"text","content":"{\"text\":\"消息内容\"}"}'
|
||
```
|
||
|
||
## Wiki 链接处理（重要）
|
||
|
||
知识库链接格式为 `https://<domain>.feishu.cn/wiki/<wiki_token>`，其中 `wiki_token` **不能直接用于文档操作**。必须先通过 `wiki spaces get_node` 获取 `obj_token`，再用 `obj_token` 调用 `docs` 相关命令。详见 `lark-doc` 和 `lark-wiki` 技能。
|
||
|
||
## Bot 身份注意事项
|
||
|
||
- **始终使用 `--as bot`**：agent 自主操作时统一使用 bot 身份，无需 `auth login`
|
||
- **Bot 只能访问被授权的资源**：知识库需管理员将 bot 应用添加为知识空间成员
|
||
- **Bot 创建的内容归属应用**：创建的文档、发送的消息均以应用名义
|
||
- **权限不足时**：检查错误中的 `console_url`，引导管理员在飞书开发者后台开通对应 scope
|
||
- **禁止对 bot 执行 `auth login`**
|
||
|
||
## 凭证初始化（新 agent）
|
||
|
||
如果某个 agent 的凭证目录尚未创建，按以下步骤初始化：
|
||
|
||
1. 从 `openclaw.json` 的 `channels.feishu.accounts` 中获取该 agent 的 `appId` 和 `appSecret`
|
||
2. 创建目录和配置文件：
|
||
|
||
```bash
|
||
mkdir -p /root/.openclaw/credentials/<agent_name>
|
||
cat > /root/.openclaw/credentials/<agent_name>/config.json << 'EOF'
|
||
{
|
||
"apps": [
|
||
{
|
||
"appId": "<appId>",
|
||
"appSecret": "<appSecret>",
|
||
"brand": "feishu",
|
||
"lang": "zh",
|
||
"users": []
|
||
}
|
||
]
|
||
}
|
||
EOF
|
||
```
|
||
|
||
## 安全规则
|
||
|
||
- **禁止在终端明文输出 appSecret 或 accessToken**
|
||
- **写入/删除操作前必须确认用户意图**
|
||
- 使用 `--dry-run` 预览危险请求
|