SKILL.md 34.5 KB

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 插件实现。lark CLI 仅用于群聊管理、文档、日历等高级功能。

  1. 安装 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
  1. 配置环境变量(~/.hermes/.env):

    FEISHU_APP_ID=cli_a91b01debab81cd1
    FEISHU_APP_SECRET=your_app_secret_here
    
  2. 绑定应用:

    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)。

正确做法:

  1. API 不支持创建图片 block → 告诉用户这个限制
  2. 把生成的图片发到飞书聊天(IM image upload + send message)
  3. 让用户从聊天中手动拖到文档对应位置

如果已经误替换了原图:

  • 有原始 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}/children body={"index":N,"children":[block_data]}
  • 删除:DELETE .../children/batch_delete body={"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。

在控制台中检查:

  1. 飞书开放平台 → 应用 → 权限管理
  2. 搜索 base:app:read
  3. 找到「获取多维表格信息」行,检查「权限类型」列(用户身份/应用身份)
  4. 确保应用身份那行也显示「已开通」

404 的三层原因(由浅入深):

  1. 完全没开通 base:app:read — 去搜索并添加
  2. 仅开通了用户身份 — 找到该权限的应用身份行,点击开通
  3. 开通后未发布 — 保存后点「发布」创建新版本

关键诊断信号:未开通 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 配置(接收消息)

问题: 用户 @ 机器人但无回复

原因:

  1. Gateway 未运行
  2. 用户未授权
  3. 日志目录权限问题

解决方案:

  1. 配置 Gateway 允许所有用户 (~/.hermes/.env):

    GATEWAY_ALLOW_ALL_USERS=true
    
  2. 配置飞书平台 (config.yaml):

    platforms:
    feishu:
    streaming: true
    app_id: cli_a91b01debab81cd1
    domain: feishu
    allow_all_users: true
    
  3. 授权特定用户:

    # 用户首次使用会收到配对码
    hermes pairing approve feishu <PAIRING_CODE>
    
  4. 修复日志目录权限 (Termux 环境):

    # Gateway 日志默认写入 ~/.hermes/logs,但 Termux 可能有权限问题
    mkdir -p /sdcard/.hermes/logs
    rm -rf ~/.hermes/logs
    ln -s /sdcard/.hermes/logs ~/.hermes/logs
    
  5. 启动 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.yaml platforms.feishu.admins(通过 extra.get("admins"))
  • allowed_group_users 来源: env FEISHU_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 通 → /apps 404 → /apps/:dummy 400 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 端点验证矩阵
    1. 去飞书开放平台 → 应用 → 权限管理 → 搜索 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/:token body {"name": "新名"} → 404
  • 根因: tenant_access_token 不支持更新多维表格元数据
  • 解决: 在创建时设好名称,命名错误则新建表格

错误: write_file 和 execute_code 工具损坏 Python 代码

  • 症状: 写入的 .py 文件中出现 TOKEN=...、...json.l... 等截断,或 \n 后的变量赋值被合并到上一行
  • 根因: 工具的 content filtering 对包含 token-like 字符串的代码进行掩码处理
  • 解决: 用 terminal 的 cat << 'PYEOF' > file.py heredoc 写 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)丢失关键信息。

应该包含的内容:

  1. 背景:问题的完整上下文,涉及的系统、配置、历史操作
  2. 问题描述:具体症状列表,每条都要展开说明
  3. 排查方向:如果问题未定位,列出可能的排查路径和步骤
  4. 期望结果:明确「修好后应该是什么样」
  5. 相关链接:涉及的 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 — 把已完成/已修复/已取消记录迁移到新建「归档表」的工作流和字段映射