name: feishu-lark description: > 飞书 Lark 官方 CLI 封装。支持消息发送、文档操作、 日历管理、云盘文件、联系人查询等核心功能。 基于 larksuite/cli 工具,适配 Android/Termux 环境。 category: productivity tags: [feishu, lark, messaging, productivity, cli] author: Hermes Agent version: 1.0.0
requires: [lark-cli]
Feishu/Lark Skill
飞书官方 CLI 工具的封装,适配 Android/Termux 环境。
前置要求
核心功能无需 lark CLI:发送文本/卡片/表格消息、上传文件已通过 Python 脚本 + hermes-feishu 插件实现。
larkCLI 仅用于群聊管理、文档、日历等高级功能。
- 安装 lark-cli:
⚠️ Android/Termux: /tmp 无写入权限,用 ~/tmp。
⚠️ 二进制名为 lark-cli 不是 lark,需要创建 symlink 才能用 lark 命令。
# 1. 查最新版本号(避免硬编码过期 URL)
LATEST_TAG=$(curl -s "https://api.github.com/repos/larksuite/cli/releases/latest" | \
python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'])")
echo "Latest: $LATEST_TAG"
# 获取版本号去掉 v 前缀
VER="${LATEST_TAG#v}"
mkdir -p ~/tmp
# 2. 下载 linux-arm64 包(wget 断点续传更稳)
wget -t 10 -T 30 -O ~/tmp/lark-cli.tar.gz \
"https://github.com/larksuite/cli/releases/download/${LATEST_TAG}/lark-cli-${VER}-linux-arm64.tar.gz"
# 3. 解压安装(二进制名为 lark-cli)
tar -xzf ~/tmp/lark-cli.tar.gz -C /data/data/com.termux/files/usr/bin/ lark-cli
chmod +x /data/data/com.termux/files/usr/bin/lark-cli
# 4. 创建 lark 快捷方式
ln -sf /data/data/com.termux/files/usr/bin/lark-cli /data/data/com.termux/files/usr/bin/lark
# 5. 验证
lark --version
配置环境变量(~/.hermes/.env):
FEISHU_APP_ID=cli_a91b01debab81cd1 FEISHU_APP_SECRET=your_app_secret_here绑定应用:
lark config bind --source hermes --app-id cli_a91b01debab81cd1 --identity user-default --force
认证方式
由于 Android/Termux DNS 限制,使用 tenant_access_token 方式:
# 获取 token
curl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
-H "Content-Type: application/json" \
-d '{"app_id":"cli_a91b01debab81cd1","app_secret":"your_secret"}'
核心功能
⚠️ 发送目标铁律
默认发送给用户 bo 个人,绝不发群聊。 仅当用户明确要求「发到群里」时才发群。
| 目标 | ID | receive_id_type |
|---|---|---|
| bo(用户个人) | ou_e8e457355c6cc3c85057377c99091be0 |
open_id |
| Lemonbot 全员+机器人群 | oc_3156253ca92a5f8649945c59769d9c52 |
chat_id |
查找用户 open_id:
req = urllib.request.Request(
"https://open.feishu.cn/open-apis/contact/v3/users?page_size=20",
headers={"Authorization": f"Bearer {token}"})
# 遍历 items,匹配 name 或 nickname
1. 消息管理 (IM)
发送文本消息到群聊
lark im message create \
--receive_id_type chat_id \
--receive_id "oc_xxxxxx" \
--msg_type text \
--content '{"text":"消息内容"}'
发送富文本消息
lark im message create \
--receive_id_type chat_id \
--receive_id "oc_xxxxxx" \
--msg_type post \
--content '{"zh_cn":{"title":"标题","content":[[{"tag":"text","text":"内容"}]]}}'
获取群聊列表
lark im chat list
获取群成员
lark im chat member list --chat_id "oc_xxxxxx"
2. 文件发送 (IM File Upload + Send)
无需 lark-cli,纯 Python urllib 即可上传并发送文件到飞书用户/群聊:
# 发送文件给用户
python3 ~/.hermes/skills/productivity/feishu-lark/scripts/upload_and_send.py \
/path/to/file.tar.gz ou_e8e457355c6cc3c85057377c99091be0
完整 API 参考:references/file-upload-send.md(含 token 获取、multipart 上传、发送流程)
3. 文档管理 (Docs)
创建文档
lark docs create --title "文档标题" --content "文档内容"
获取文档内容
lark docs content get --document_id "doccnxxxxxx"
列出文档
lark docs list
3a. 文档 Block 级操作(读取/插入/删除)
通过 docx block API 可以精确操作文档结构——读取每个段落、在指定位置插入翻译或内容、删除多余 block。
Wiki 链接转换:用户分享的 wudaima.feishu.cn/wiki/<node_token> 需要先转换为 obj_token 才能调 docx API:
req = urllib.request.Request(
f"https://open.feishu.cn/open-apis/wiki/v2/spaces/get_node?token={wiki_token}",
headers={"Authorization": f"Bearer {TOKEN}"})
doc_id = json.loads(urllib.request.urlopen(req).read())["data"]["node"]["obj_token"]
权限:即使应用有 docx:document 权限,也需在每个具体文档上把应用加为协作者(分享→搜索应用名→可编辑)。未授权返回 403 code=1770032。
⚠️ 图片操作铁律 — 永远不要替换用户原有的图片:
用户要求「在文档中插入图片」或「把图放在对应章节下面」时,绝对不能替换文档中已有的图片 block。replace_image 会永久覆盖原图内容,且无法通过 API 恢复(飞书没有版本历史 API)。
正确做法:
- API 不支持创建图片 block → 告诉用户这个限制
- 把生成的图片发到飞书聊天(IM image upload + send message)
- 让用户从聊天中手动拖到文档对应位置
如果已经误替换了原图:
- 有原始 token 记录 →
replace_image恢复 - 没有原始 token → 只能让用户通过飞书网页端「版本历史」手动恢复
- 教训:在执行 replace_image 之前,必须先记录所有原始 token,宁可不做也不能破坏用户数据
关键操作:
- 读取:
GET /docx/v1/documents/{doc_id}/blocks?page_size=500 - 插入:
POST /docx/v1/documents/{doc_id}/blocks/{doc_id}/childrenbody={"index":N,"children":[block_data]} - 删除:
DELETE .../children/batch_deletebody={"start_index":N,"end_index":M} - 批量插入需逆序(从后往前)避免索引偏移
⚠️ Image block 不支持 API 创建,但可以替换已有图片:
POST .../children创建 block_type=27 返回1770029 "block not support to create"— 无法通过 API 新建图片 block- 但
PATCH .../blocks/{image_block_id}+{"replace_image": {"token": file_token}}可以替换已有图片 block 的内容 - 替换流程:Drive
upload_all(parent_node=block_id,parent_type=小写 docx_image)→ 拿 file_token →PATCH replace_image - 关键:parent_node 必须是 image block 的 block_id(不是文档 ID),否则返回
1770013 relation mismatch - 详见
references/docx-api-notes.md
⚠️ 图片上传字段名差异(IM vs Drive 相反):
- Drive
upload_all:字段名 =file,parent_type 必须小写docx_image(不是DOCX_IMAGE) - IM
images:字段名 =image(不是file!),image_type =message - 搞混返回
code:234001 Invalid request param
详见 references/docx-api-notes.md(含完整错误码表、Wiki→Docx token 转换、block 类型速查、翻译插入模板)和 references/docx-block-api.md(含中文弯引号陷阱)
3. 日历管理 (Calendar)
获取日历列表
lark api GET /open-apis/calendar/v4/calendars
创建事件
lark calendar event create \
--calendar_id "primary" \
--summary "会议标题" \
--start_time "2026-06-25T10:00:00+08:00" \
--end_time "2026-06-25T11:00:00+08:00"
4. 云盘管理 (Drive)
上传文件
lark drive file upload --file_path "/path/to/file" --parent_node "folder_token"
列出文件
lark drive file list --parent_node "folder_token"
7. 文件上传与发送
上传文件到飞书
import json, urllib.request
TOKEN = '***' # from tenant_access_token API
FILE_PATH = '/path/to/file.tar.gz'
FILE_NAME = 'file.tar.gz'
with open(FILE_PATH, 'rb') as f:
file_data = f.read()
boundary = '----FormBoundary7MA4YWxkTrZu0gW'
body = (
f'--{boundary}\r\n'
f'Content-Disposition: form-data; name="file_name"\r\n\r\n{FILE_NAME}\r\n'
f'--{boundary}\r\n'
f'Content-Disposition: form-data; name="file_type"\r\n\r\nstream\r\n'
f'--{boundary}\r\n'
f'Content-Disposition: form-data; name="file"; filename="{FILE_NAME}"\r\n'
f'Content-Type: application/octet-stream\r\n\r\n'
).encode() + file_data + f'\r\n--{boundary}--\r\n'.encode()
req = urllib.request.Request(
'https://open.feishu.cn/open-apis/im/v1/files',
data=body,
headers={
'Authorization': f'Bearer {TOKEN}',
'Content-Type': f'multipart/form-data; boundary={boundary}'
},
method='POST'
)
with urllib.request.urlopen(req, timeout=30) as r:
result = json.loads(r.read())
file_key = result['data']['file_key'] # Use this to send
发送文件消息
content = json.dumps({"file_key": file_key})
msg_data = json.dumps({
"receive_id": "ou_xxxxxx", # open_id for user, oc_xxxxxx for chat
"msg_type": "file",
"content": content
}).encode()
req = urllib.request.Request(
'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id',
data=msg_data,
headers={'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json'},
method='POST'
)
搜索联系人
req = urllib.request.Request(
f'https://open.feishu.cn/open-apis/contact/v3/users?page_size=20&name=用户名',
headers={'Authorization': f'Bearer {TOKEN}'}
)
# Returns open_id for each matching user
lark contact user search --query "用户名"
获取用户信息
lark contact user get --user_id "ou_xxxxxx"
权限模型
多维表格 API 需要应用在飞书开放平台单独开通权限 scope。IM 权限和 bitable 权限是独立的——IM 能正常通信不代表 bitable 能通。
必要权限(控制台中的名称):
base:app:read(获取多维表格信息)— 列出表格、获取表格元数据需此权限base:app:readonly— 只读访问记录(旧名bitable:app:readonly)
🔑 身份双重权限模型(本次发现的根因)
飞书每个权限 scope 都有两个独立的开关:用户身份和应用身份。
| Token 类型 | 对应用的身份列 | 说明 |
|---|---|---|
tenant_access_token |
应用身份 | 服务端直接调用,无用户参与 |
user_access_token |
用户身份 | 用户授权后调用 |
关键陷阱: 权限可能对「用户身份」已开通但对「应用身份」未开通。控制台权限表格中每行有「权限类型」列标注。如果 base:app:read 行显示「用户身份: 已开通」但「应用身份: -」→ tenant_access_token 调 API 会返回 404。
在控制台中检查:
- 飞书开放平台 → 应用 → 权限管理
- 搜索
base:app:read - 找到「获取多维表格信息」行,检查「权限类型」列(用户身份/应用身份)
- 确保应用身份那行也显示「已开通」
404 的三层原因(由浅入深):
- 完全没开通
base:app:read— 去搜索并添加 - 仅开通了用户身份 — 找到该权限的应用身份行,点击开通
- 开通后未发布 — 保存后点「发布」创建新版本
关键诊断信号:未开通 bitable 权限时,API 返回 404 page not found(不是 403 Forbidden),容易误判为端点不存在。
注意: 飞书控制台已从 bitable:* 改名为 base:*(如 base:app:read = 获取多维表格信息),但 API 路径仍是 /open-apis/bitable/v1/...。
先验证 token + IM 可用(已知能通的端点),再测 bitable:
# 1. 拿 token
TOKEN=$(curl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
-H "Content-Type: application/json" \
-d '{"app_id":"cli_a91b01debab81cd1","app_secret":"<secret>"}' \
| python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")
# 2. 验证 IM 通路(应返回 code:0)
curl -s -H "Authorization: Bearer *** \
"https://open.feishu.cn/open-apis/im/v1/chats?page_size=1" | python3 -m json.tool | head -5
# 3. 测 bitable(404 = 无权限,需去开放平台开通)
curl -s -w "\nHTTP:%{http_code}" -H "Authorization: Bearer *** \
"https://open.feishu.cn/open-apis/bitable/v1/apps?page_size=5"
列出表格(需 lark CLI 或 API 权限已开通)
lark base app list
获取记录
lark base record list --app_token "bas_xxxxxx" --table_id "tbl_xxxxxx"
直接 API(Python,无 lark CLI)
import json, urllib.request, urllib.error
# ... 先获取 token(同上)...
# 列表格
req = urllib.request.Request(
"https://open.feishu.cn/open-apis/bitable/v1/apps?page_size=20",
headers={"Authorization": f"Bearer {token}"}
)
try:
with urllib.request.urlopen(req, timeout=15) as r:
apps = json.loads(r.read())
for app in apps.get("data", {}).get("items", []):
print(f" {app['name']} → app_token: {app['app_token']}")
except urllib.error.HTTPError as e:
if e.code == 404:
print("404: 应用未开通 bitable:app 权限,去开放平台添加")
else:
print(f"HTTP {e.code}: {e.read().decode()[:200]}")
常用 API 调用
通用 API 调用方式
lark api GET <path> [--params '<json>']
lark api POST <path> [--data '<json>']
lark api PUT <path> [--data '<json>']
lark api DELETE <path>
示例:获取用户信息
lark api GET /open-apis/contact/v3/users/ou_xxxxxx
示例:发送消息(注意 content 格式)
# ❌ 错误:content 不是 JSON 字符串
lark api POST /open-apis/im/v1/messages \
--data '{
"receive_id": "oc_xxxxxx",
"msg_type": "text",
"content": {"text": "Hello"} # 错误!
}'
# ✅ 正确:content 必须是 JSON 字符串
lark api POST /open-apis/im/v1/messages \
--data '{
"receive_id": "oc_xxxxxx",
"msg_type": "text",
"content": "{\"text\":\"Hello\"}" # 正确!
}'
Python 辅助脚本(处理 JSON 转义):
import json
import urllib.request
APP_ID = "cli_a91b01debab81cd1"
APP_SECRET = "your_secret"
# 获取 token
token_data = json.dumps({"app_id": APP_ID, "app_secret": APP_SECRET}).encode('utf-8')
token_req = urllib.request.Request(
'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal',
data=token_data,
headers={'Content-Type': 'application/json'},
method='POST'
)
with urllib.request.urlopen(token_req, timeout=30) as response:
token_result = json.loads(response.read().decode('utf-8'))
TOKEN = token_result['tenant_access_token']
# 发送消息(content 自动转义)
message_data = {
"receive_id": "oc_xxxxxx",
"msg_type": "text",
"content": json.dumps({"text": "Hello"}) # 自动转义
}
msg_req = urllib.request.Request(
'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id',
data=json.dumps(message_data).encode('utf-8'),
headers={
'Authorization': f'Bearer {TOKEN}',
'Content-Type': 'application/json'
},
method='POST'
)
with urllib.request.urlopen(msg_req, timeout=30) as response:
result = json.loads(response.read().decode('utf-8'))
print(result)
实用脚本
快速发送消息(Bash)
#!/bin/bash
# send_feishu_msg.sh
CHAT_ID="$1"
MESSAGE="$2"
if [ -z "$CHAT_ID" ] || [ -z "$MESSAGE" ]; then
echo "Usage: $0 <chat_id> <message>"
exit 1
fi
lark im message create \
--receive_id_type chat_id \
--receive_id "$CHAT_ID" \
--msg_type text \
--content "{\"text\":\"$MESSAGE\"}"
发送消息(Python - 推荐,自动处理 JSON 转义)
# 使用内置脚本(自动处理 content 格式)
python3 ~/.hermes/skills/productivity/feishu-lark/scripts/send_message.py \
oc_xxxxxx "Hello World"
# 发送卡片消息
python3 ~/.hermes/skills/productivity/feishu-lark/scripts/send_message.py \
oc_xxxxxx '{"config":{"wide_screen_mode":true},"header":{"title":{"tag":"plain_text","content":"标题"},"template":"blue"},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"**内容**"}}]}' \
interactive
Python 脚本优势:
- 自动处理 JSON 转义(避免 9499 错误)
- 自动获取 token
- 支持 text/post/interactive 消息类型
- 更好的错误提示
获取 Token 脚本
#!/bin/bash
# get_feishu_token.sh
APP_ID="${FEISHU_APP_ID}"
APP_SECRET="${FEISHU_APP_SECRET}"
if [ -z "$APP_ID" ] || [ -z "$APP_SECRET" ]; then
echo "Error: FEISHU_APP_ID and FEISHU_APP_SECRET must be set"
exit 1
fi
RESPONSE=$(curl -s -X POST \
https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
-H "Content-Type: application/json" \
-d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}")
TOKEN=$(echo "$RESPONSE" | grep -o '"tenant_access_token":"[^"]*"' | cut -d'"' -f4)
EXPIRE=$(echo "$RESPONSE" | grep -o '"expire":[0-9]*' | cut -d':' -f2)
echo "Token: $TOKEN"
echo "Expire: $EXPIRE seconds"
故障排除
lark CLI DNS 解析失败 (Android/Termux 特有)
症状: lark auth login --recommend 报错 dial tcp: lookup accounts.feishu.cn on [::1]:53: read udp [::1]:xxx->[::1]:53: read: connection refused
根因: Go 编译的二进制在 Android 上找不到 /etc/resolv.conf(Android /etc 是只读的),DNS 解析器回退到 [::1]:53(IPv6 localhost),但 Android 上没有本地 DNS 服务。
验证: curl 能正常解析飞书域名,只有 lark CLI/Go 程序不行
尝试过但无效的方法:
GODEBUG=netdns=go— Go 的纯 Go DNS 解析器同样需要/etc/resolv.conf,在 Android 上仍回退到 localhost:53- 写 hosts 文件 — 只覆盖固定域名,OAuth 流程涉及多个子域名(
accounts.feishu.cn等),不全覆盖就没用 ln -sf到/etc/resolv.conf—/etc只读,无法创建
当前解决方案: 放弃 lark CLI 的 OAuth 登录,改用 Python urllib 直接调 API(curl 和 Python 的 DNS 解析在 Termux 上正常工作)。lark config bind 无需网络可完成配置绑定,后续需要用户授权的命令(lark auth login、lark base app list 等)无法使用。
备选路线(未验证):
- 使用
proxychains或tsocks劫持 Go 程序 DNS - Termux 内装
dnsmasq在 localhost:53 监听
问题: GitHub 下载超时/断连(国内网络)
根因: GitHub releases 走 objects.githubusercontent.com CDN,国内经常超时。
解决方案:
# 方案 1: wget 重试(断点续传 + 10 次重试)
mkdir -p ~/tmp
wget -t 10 -T 30 -O ~/tmp/lark-cli.tar.gz \
"https://github.com/larksuite/cli/releases/download/v1.0.57/lark-cli-1.0.57-linux-arm64.tar.gz"
# 方案 2: 后台下载(不阻塞 session)
wget -t 10 -T 30 -O ~/tmp/lark-cli.tar.gz \
"https://github.com/larksuite/cli/releases/download/v1.0.57/lark-cli-1.0.57-linux-arm64.tar.gz" &
# 验证完整性
file ~/tmp/lark-cli.tar.gz # 约 3MB
tar -tzf ~/tmp/lark-cli.tar.gz | head # 列出内容
# 解压安装
tar -xzf ~/tmp/lark-cli.tar.gz -C /data/data/com.termux/files/usr/bin/
chmod +x /data/data/com.termux/files/usr/bin/lark
注意:
/tmp在 Android Termux 下无写入权限,用~/tmp替代- 部分下载的文件(
- 核心功能不依赖 lark CLI:发消息/卡片/表格通过 Python 脚本 + hermes-feishu 插件即可,不影响日常使用 如果在 Android/Termux 遇到 DNS 解析错误: ```bash # 配置 DNS echo "nameserver 8.8.8.8 nameserver 114.114.114.114" > /data/data/com.termux/files/usr/etc/resolv.conf
手动添加 hosts
echo "198.18.0.87 accounts.feishu.cn" >> /data/data/com.termux/files/usr/etc/hosts
或使用 IP 直接访问 API
curl -H "Host: open.feishu.cn" https://198.18.0.87/open-apis/...
### 认证失败
```bash
# 检查配置
lark config show
# 检查认证状态
lark auth status
# 重新绑定
lark config bind --source hermes --app-id cli_a91b01debab81cd1 --identity user-default --force
Gateway 配置(接收消息)
问题: 用户 @ 机器人但无回复
原因:
- Gateway 未运行
- 用户未授权
- 日志目录权限问题
解决方案:
配置 Gateway 允许所有用户 (~/.hermes/.env):
GATEWAY_ALLOW_ALL_USERS=true配置飞书平台 (config.yaml):
platforms: feishu: streaming: true app_id: cli_a91b01debab81cd1 domain: feishu allow_all_users: true授权特定用户:
# 用户首次使用会收到配对码 hermes pairing approve feishu <PAIRING_CODE>修复日志目录权限 (Termux 环境):
# Gateway 日志默认写入 ~/.hermes/logs,但 Termux 可能有权限问题 mkdir -p /sdcard/.hermes/logs rm -rf ~/.hermes/logs ln -s /sdcard/.hermes/logs ~/.hermes/logs启动 Gateway:
# 检查状态 hermes gateway status
启动(前台)
hermes gateway run
或后台启动
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &
6. **验证 Gateway 连接**:
```bash
# 查看日志
tail -f ~/.hermes/logs/gateway.log
# 应看到:
# - "Connecting to feishu..."
# - "[Feishu] Connected in websocket mode"
# - "Gateway running with X platform(s)"
🔑 Approval 卡片按钮点击无反应(重要陷阱)
症状: 飞书聊天中弹出 "⚠️ Command Approval Required" 卡片,用户点 "Allow Once / Session / Always" 按钮后没有任何反应——卡片不更新,agent 线程一直阻塞。每次都弹,点了 Always 也没用。
根因: DM 消息收发和 approval 按钮点击走的是两条不同的权限检查路径:
- DM 消息收发:检查
GATEWAY_ALLOW_ALL_USERS/FEISHU_ALLOW_ALL_USERS→true即放行 - Approval 按钮点击:走
_allow_group_message()→ 只认admins(config.yaml)和FEISHU_ALLOWED_USERS(.env)。默认 group policy 是allowlist,两个列表都为空 → 用户不在空 allowlist 里 → 判定 "Unauthorized approval click" → 按钮点击被静默丢弃
诊断:
grep "Unauthorized approval click" ~/.hermes/logs/gateway.log
# 如果看到你的 open_id → 就是这个问题
修复: 在 config.yaml 的 platforms.feishu 下加 admins 列表:
platforms:
feishu:
streaming: true
app_id: cli_a91b01debab81cd1
domain: feishu
allow_all_users: true
admins:
- ou_e8e457355c6cc3c85057377c99091be0 # 用户的 open_id
⚠️ hermes config set platforms.feishu.admins 会把列表写成字符串而非 YAML 列表。用 Python yaml 模块直接修改文件更可靠:
import yaml
with open("~/.hermes/config.yaml") as f: cfg = yaml.safe_load(f)
cfg["platforms"]["feishu"]["admins"] = ["ou_xxxxx"]
with open("~/.hermes/config.yaml","w") as f: yaml.dump(cfg, f, allow_unicode=True)
改完后重启 gateway:hermes gateway restart(或 kill + hermes gateway run 后台重启)。
代码路径(供调试参考):
- 按钮点击入口:
adapter.py→_on_card_action_trigger()→_handle_approval_card_action() - 权限检查:
_allow_group_message()→ 检查_admins∪_allowed_group_users - 二次权限检查:
_resolve_approval()→_is_interactive_operator_authorized()→ 同样检查_admins∪_allowed_group_users admins来源: config.yamlplatforms.feishu.admins(通过extra.get("admins"))allowed_group_users来源: envFEISHU_ALLOWED_USERS(逗号分隔)
常见错误
错误: Unauthorized user: xxx on feishu
- 解决: 设置
GATEWAY_ALLOW_ALL_USERS=true或执行hermes pairing approve feishu <code>
错误: Permission denied: '/.hermes'
- 解决: 创建日志目录链接到 /sdcard
错误: cannot import name 'env_float' from 'utils'
- 解决: 检查 Python 环境,可能需要更新 hermes-agent
错误: 多维表格 API 返回 404 page not found(但 IM API 正常)— 四种可能原因
原因 A(最常见): 应用未开通 base:app:read 权限 scope
- 诊断: IM 通 →
/apps404 →/apps/:dummy400 NOTEXIST → 权限缺失 - 解决: 飞书开放平台 → 权限管理 → 搜索 base → 添加
base:app:read→ 发布
原因 B(常见): 权限已开通但仅限「用户身份」而非「应用身份」
- 诊断: 在权限管理页面看
base:app:read的「应用身份」行是否显示「-」(未开通)。tenant_access_token 走应用身份 - 解决: 为「应用身份」也开通该权限
原因 C(实战发现): 权限两个身份都已开通,但 /bitable/v1/apps 列表端点对 tenant_access_token 永久不可用
- 诊断:
POST /apps创建成功 +GET /apps/:token获取成功 → 列表仍 404 → 不是权限问题 - 根因: 列表端点需要 user_access_token(用户上下文),tenant token 只能做 single-app CRUD
- 解决: 获取 user_access_token(需 OAuth 授权),或用
POST /apps创建 +GET /apps/:token操作单个表格 - 详见
references/bitable-api-notes.md端点验证矩阵- 去飞书开放平台 → 应用 → 权限管理 → 搜索
base:app:read→ 检查该权限的「应用身份」行是否显示「已开通」(不是只看「用户身份」行)
- 去飞书开放平台 → 应用 → 权限管理 → 搜索
- 注意: 飞书控制台里权限 scope 已从
bitable:*改名为base:*(如base:app:read= 获取多维表格信息) - 解决: 在权限管理页面找到
base:app:read(获取多维表格信息),为「应用身份」开通该权限,然后保存并发布新版本。仅开通「用户身份」不够
原因 D(易误判): tenant_access_token 不支持列表端点
- 诊断:
POST /bitable/v1/apps(创建)成功 +GET /bitable/v1/apps/:token(获取单个)成功 +GET /bitable/v1/apps(列表)仍 404 → 不是权限问题,是 token 类型限制 - 根因: 飞书多维表格列表端点需要 user_access_token,tenant_access_token 只支持对已知 app_token 的单表格 CRUD
- 解决: 使用 user_access_token 调列表端点
- Chrome 调试: Android 上
uiautomator dump检查权限页面时,input swipe易触发 Chrome 地址栏下拉遮盖内容。先tap 500 800关闭下拉,再从中部swipe滚动
错误: 多维表格写操作返回 {"code":91403,"msg":"Forbidden"}(HTTP 403)
- 症状: 能读(GET 正常返回),但 PATCH/POST/DELETE 全部 403
- 根因: 应用开通的是
bitable:app:readonly(只读)而非bitable:app(读写) - 解决: 把权限 scope 从
bitable:app:readonly升级为bitable:app
错误: GET /fields/{field_id} 返回 404(但 GET /fields 列表正常)
- 症状: 能列出所有字段,但获取单个字段详情 404
- 根因: tenant_access_token 不支持单字段详情端点
- 解决: 用 GET /fields 获取全部字段列表后在 Python 中筛选需要的字段
错误: PATCH 更新字段名返回 404,PUT 返回 type is required
- 症状:
PATCH /bitable/v1/apps/:token/tables/:tid/fields/:fid→ 404;PUT同一路径 → 400 "type is required" - 根因: 飞书 bitable API 不支持 PATCH,字段更新必须用 PUT 且请求体必须包含
type(字段类型:1=文本, 3=单选, 5=日期, 17=附件) - 解决: 始终用 PUT 更新字段,body 包含
{"field_name": "新名称", "type": <数字>}。单选字段还需带property.options
错误: DELETE 表/字段 返回 None(静默失败)
- 症状:
DELETE /bitable/v1/apps/:token/tables/:tid返回{"code": null, "msg": null} - 根因: tenant_access_token 不支持删除多维表格的表(可能需要 user token 或更高权限)
- 解决: 手动在飞书网页端删除,或重命名标记为废弃
错误: PATCH 重命名多维表格名称返回 404
- 症状:
PATCH /bitable/v1/apps/:tokenbody{"name": "新名"}→ 404 - 根因: tenant_access_token 不支持更新多维表格元数据
- 解决: 在创建时设好名称,命名错误则新建表格
错误: write_file 和 execute_code 工具损坏 Python 代码
- 症状: 写入的 .py 文件中出现
TOKEN=...、...json.l...等截断,或\n后的变量赋值被合并到上一行 - 根因: 工具的 content filtering 对包含 token-like 字符串的代码进行掩码处理
- 解决: 用
terminal的cat << 'PYEOF' > file.pyheredoc 写 Python 脚本,避免使用write_file写包含 API token 变量赋值的代码。变量名避免TOKEN、APP_TOKEN、SECRET,改用t、app、s等短名
提示: Termux 上复杂的 shell 嵌套引号(curl + Python f-string + JSON)容易报语法错误。遇到时直接 write_file 写一个 .py 脚本再 terminal 执行,比在 execute_code 里拼 shell 命令可靠
Bitable 任务处理 Cron 工作流
⚠️ 写任务前必须读 fcfg.json 确认正确的表
Plan Agent / Dev Agent / Test Agent 读的飞书表配置在 ~/tmp/fcfg.json(由 plan_build_cfg.py 生成),不是 memory 或 SKILL.md 里的硬编码值。cron 每次 rebuild 这个文件。
import json, os
cfg = json.load(open(os.path.expanduser("~/tmp/fcfg.json")))
APP_TOKEN = cfg["a"] # app token (agents 实际读的)
TABLE_ID = cfg["r"] # 需求表
BUG_TABLE = cfg["b"] # Bug表
TOKEN = cfg["t"] # tenant token
铁律:手动写任务到飞书之前,先读 fcfg.json 确认 app_token 和 table_id。直接用 memory 或旧值会写错表,agents 完全看不到。曾经踩过:memory 记的是 BbtPbNtuGaffoRsNLNJcpYEBnEb(5条记录),agents 实际读的是 RzLHbMp2paNYIssxy9tcBjxonVe(93条记录),4条任务全白写。
飞书 API 有缓存延迟,写入后可能需等一个 cron 周期 agents 才能看到。可用 cronjob action=run 手动触发 Plan Agent 立即执行验证。
🔑 记录撰写原则 —「不要惜墨如金」
用户明确指出:向多维表格写入需求/Bug 记录时,必须保留完整上下文,不能总结得太简略。精简会导致未来执行者(人或 Agent)丢失关键信息。
应该包含的内容:
- 背景:问题的完整上下文,涉及的系统、配置、历史操作
- 问题描述:具体症状列表,每条都要展开说明
- 排查方向:如果问题未定位,列出可能的排查路径和步骤
- 期望结果:明确「修好后应该是什么样」
- 相关链接:涉及的 API token、文件路径、cron job ID、群聊 ID
反例(❌):「cron job 学习任务未执行 — 3 个步骤没跑」 正例(✅):含「背景」+「问题表现 1/2/3」+「排查方向 1/2/3/4」+「期望结果」的结构化 Markdown
写入时想象自己是几个月后接手这个任务的人——只读标题和描述能否完全理解需求?
将飞书多维表格作为任务队列,用 Hermes cron job 自动轮询处理:
用户 → 飞书表格添加需求/Bug → cron job 每30min轮询
→ 选最高优先级未完成任务 → Agent 执行 + 测试
→ PATCH 标记「已完成✅」→ 汇报到聊天
setup 参考: references/bitable-task-cron.md(含完整 cron 配置、API 端点、字段映射)
Hermes 飞书插件集成
hermes-feishu 插件 (推荐)
arkseek/hermes-feishu - 增强 Hermes 飞书消息通道,支持卡片消息和表格渲染。
安装:
hermes plugins install arkseek/hermes-feishu
hermes plugins enable hermes-feishu
配置环境变量 (~/.hermes/.env):
FEISHU_APP_ID=cli_a91b01debab81cd1
FEISHU_APP_SECRET=your_secret
HERMES_FEISHU_CHAT_ID=oc_xxxxxx # 默认群聊ID
提供的工具:
send_feishu_card- 发送卡片消息(支持 Markdown + 表格)send_feishu_table- 发送结构化表格数据pre_llm_call- 自动注入格式化指令
使用示例:
# 发送卡片消息(注意:table 使用 columns 而不是 headers)
lark api POST /open-apis/im/v1/messages \
--data '{
"receive_id": "oc_xxxxxx",
"msg_type": "interactive",
"content": "{\"config\":{\"wide_screen_mode\":true},\"header\":{\"title\":{\"tag\":\"plain_text\",\"content\":\"标题\"},\"template\":\"blue\"},\"elements\":[{\"tag\":\"div\",\"text\":{\"tag\":\"lark_md\",\"content\":\"**内容**\"}},{\"tag\":\"table\",\"columns\":[{\"tag\":\"text\",\"text\":\"列1\",\"width\":\"auto\",\"weight\":1},{\"tag\":\"text\",\"text\":\"列2\",\"width\":\"auto\",\"weight\":1}],\"rows\":[[{\"tag\":\"text\",\"text\":\"数据1\"},{\"tag\":\"text\",\"text\":\"数据2\"}]]}]}"
}'
卡片消息格式要点:
config.wide_screen_mode: true(宽屏模式)header.title: 标题(plain_text 或 lark_md)header.template: 颜色模板(blue, red, green, orange, grey, default, wathet, turquoise, yellow, carmine, violet, purple, indigo)elements: 内容元素数组tag: div- 文本块(text 支持 lark_md 格式)tag: table- 表格(使用 columns 而不是 headers)tag: img- 图片tag: action- 按钮
常见错误:
- ❌
headers- 错误!table 不支持 headers - ✅
columns- 正确!table 使用 columns 定义表头 - ❌ 直接传递 Python dict - 错误!content 必须是 JSON 字符串
- ✅
json.dumps(content)- 正确!使用 json.dumps 转义
机器人身份
当前机器人: pixel phone agent (cli_a91b01debab81cd1)
- Open ID: ou_187699924a3759c17932ac8f3c685978
- 群聊: Lemonbot 全员+机器人群 (oc_3156253ca92a5f8649945c59769d9c52)
注意: 群里可能有多个机器人,用户需要 @ 正确的机器人才能收到回复。
参考文档
- 飞书开放平台:https://open.feishu.cn/
- API 文档:https://open.feishu.cn/document/
- lark-cli GitHub:https://github.com/larksuite/cli
- hermes-feishu 插件:https://github.com/arkseek/hermes-feishu
- Gateway 配置详细指南:
references/gateway-setup.md - 故障排除速查:
references/troubleshooting.md - 多维表格 API 实战笔记:
references/bitable-api-notes.md— 权限模型、端点验证矩阵、Python 访问模板 - 文档 Block 级 API:
references/docx-block-api.md— Wiki token 转换、block 读取/插入/删除、批量翻译工作流、中文弯引号陷阱 - 文档 API 实战笔记:
references/docx-api-notes.md— image block 限制、Drive/IM 图片上传字段名差异、完整错误码表、翻译插入模板 - API 诊断脚本:
scripts/diagnose_api.py— 一键检测 token/IM/bitable 连通性 - Agent 执行状态检查:
references/agent-inspection.md— 查 state.db 判断 agent 是 SILENT 还是在干活,手动触发 cron - 批量归档/迁移:
references/bitable-batch-archive.md— 把已完成/已修复/已取消记录迁移到新建「归档表」的工作流和字段映射