feishu-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feishu / Lark IM Skill

飞书（Feishu）/ Lark 即时通讯（IM）Skill

Use this skill to run Feishu or Lark IM operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用本Skill通过

uxc

+ OpenAPI执行飞书或Lark的即时通讯操作。

复用

uxc

Skill以实现共享执行、认证和错误处理指引。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.

Network access to

https://open.feishu.cn/open-apis

https://open.larksuite.com/open-apis

Access to the curated OpenAPI schema URL:

https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json

A Feishu or Lark app with bot capability enabled.
A Feishu or Lark app
```
app_id
```
+
```
app_secret
```
, or a current
```
tenant_access_token
```
if you are using the manual fallback path.

```
uxc
```
已安装且可在
```
PATH
```
中访问。

可访问

https://open.feishu.cn/open-apis

或

https://open.larksuite.com/open-apis

网络。

可访问精选的OpenAPI schema地址：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json

已启用机器人功能的飞书或Lark应用。
飞书或Lark应用的
```
app_id
```
+
```
app_secret
```
；若使用手动备用方案，则需当前有效的
```
tenant_access_token
```
。

Scope

适用范围

This skill covers an IM-focused request/response surface:

chat lookup
chat member lookup
image and file upload for IM sends
message send and reply
selected message history reads
basic user lookup through contact APIs

This skill does not cover:

docs, bitable, approval, or non-IM product families
the full Feishu or Lark Open Platform surface

本Skill聚焦于即时通讯领域的请求/响应操作，包括：

聊天查询
聊天成员查询
用于即时通讯消息发送的图片和文件上传
消息发送与回复
指定消息历史记录查询
通过联系人API进行基础用户查询

本Skill不涵盖以下内容：

文档、多维表格、审批或非即时通讯类产品
飞书或Lark开放平台的全部功能

Subscribe Status

订阅状态

Feishu and Lark expose event-delivery models beyond plain request/response APIs, including long-connection event delivery in the platform ecosystem.

Current

uxc subscribe

status:

request/response IM operations are validated
inbound message intake is validated through the built-in
```
feishu-long-connection
```
transport
live validation confirmed real
```
im.message.receive_v1
```
events delivered into the subscribe sink for a
```
p2p
```
bot chat

Important runtime notes:

```
feishu-long-connection
```
is a provider-aware transport inside
```
uxc subscribe
```
; it is not a plain raw WebSocket stream
the runtime opens a temporary WebSocket URL from
```
/callback/ws/endpoint
```
frames are protobuf binary messages, not text JSON
the runtime sends required event acknowledgements and ping control frames automatically

飞书和Lark除了基础的请求/响应API外，还提供事件推送模型，包括平台生态中的长连接事件推送。

当前

uxc subscribe

的支持状态：

即时通讯的请求/响应操作已验证通过
通过内置的
```
feishu-long-connection
```
传输方式验证了入站消息接收功能
实时验证确认，
```
p2p
```
机器人聊天中的真实
```
im.message.receive_v1
```
事件可推送至订阅接收器

重要运行时说明：

```
feishu-long-connection
```
是
```
uxc subscribe
```
内部的、适配服务商的传输方式，并非普通的原始WebSocket流
运行时会从
```
/callback/ws/endpoint
```
获取临时WebSocket地址
传输帧为protobuf二进制消息，而非文本JSON格式
运行时会自动发送所需的事件确认和ping控制帧

Endpoint Choice

端点选择

This schema works against either Feishu or Lark Open Platform base URLs:

China / Feishu default:
```
https://open.feishu.cn/open-apis
```
International / Lark alternative:
```
https://open.larksuite.com/open-apis
```

The fixed link example below uses Feishu. For Lark, use the same schema URL against the Lark base host.

该schema可适配飞书或Lark开放平台的基础地址：

中国区/飞书默认：
```
https://open.feishu.cn/open-apis
```
国际版/Lark备选：
```
https://open.larksuite.com/open-apis
```

以下固定链接示例使用飞书地址。若使用Lark，请将同一schema地址搭配Lark基础主机使用。

Authentication

认证方式

Feishu and Lark service-side APIs use

Authorization: Bearer <tenant_access_token>

for these operations.

Preferred setup is to store

app_id

app_secret

as credential fields and let

uxc auth bootstrap

fetch and refresh the short-lived tenant token automatically.

Feishu bootstrap-managed setup:

bash

uxc auth credential set feishu-tenant \
  --auth-type bearer \
  --field app_id=env:FEISHU_APP_ID \
  --field app_secret=env:FEISHU_APP_SECRET

uxc auth bootstrap set feishu-tenant \
  --token-endpoint https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  --header 'Content-Type=application/json; charset=utf-8' \
  --request-json '{"app_id":"{{field:app_id}}","app_secret":"{{field:app_secret}}"}' \
  --access-token-pointer /tenant_access_token \
  --expires-in-pointer /expire \
  --success-code-pointer /code \
  --success-code-value 0

uxc auth binding add \
  --id feishu-tenant \
  --host open.feishu.cn \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

For Lark, use the same bootstrap shape against the Lark host and bind the credential to

open.larksuite.com

To use long-connection subscribe, the credential still needs

app_id

and

app_secret

fields because the transport opens its own temporary event URL outside the normal bearer-token request path.

Manual fallback if you already have a tenant token:

bash

curl -sS https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"app_id":"cli_xxx","app_secret":"xxxx"}'

Lark uses the same path shape on the Lark host:

bash

curl -sS https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"app_id":"cli_xxx","app_secret":"xxxx"}'

Configure one bearer credential and bind it to the Feishu API host:

bash

uxc auth credential set feishu-tenant \
  --auth-type bearer \
  --secret-env FEISHU_TENANT_ACCESS_TOKEN

uxc auth binding add \
  --id feishu-tenant \
  --host open.feishu.cn \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

For Lark, create the same binding against

open.larksuite.com

bash

uxc auth binding add \
  --id lark-tenant \
  --host open.larksuite.com \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

Inspect or pre-warm bootstrap state when auth looks wrong:

bash

uxc auth bootstrap info feishu-tenant
uxc auth bootstrap refresh feishu-tenant

Validate the active binding when auth looks wrong:

bash

uxc auth binding match https://open.feishu.cn/open-apis

飞书和Lark的服务端API在执行这些操作时使用

Authorization: Bearer <tenant_access_token>

认证方式。

推荐配置方式：将

app_id

app_secret

存储为凭证字段，由

uxc auth bootstrap

自动获取并刷新短期租户令牌。

飞书自动管理式配置：

bash

uxc auth credential set feishu-tenant \
  --auth-type bearer \
  --field app_id=env:FEISHU_APP_ID \
  --field app_secret=env:FEISHU_APP_SECRET

uxc auth bootstrap set feishu-tenant \
  --token-endpoint https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  --header 'Content-Type=application/json; charset=utf-8' \
  --request-json '{"app_id":"{{field:app_id}}","app_secret":"{{field:app_secret}}"}' \
  --access-token-pointer /tenant_access_token \
  --expires-in-pointer /expire \
  --success-code-pointer /code \
  --success-code-value 0

uxc auth binding add \
  --id feishu-tenant \
  --host open.feishu.cn \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

对于Lark，使用相同的自动配置结构，将凭证绑定到

open.larksuite.com

主机。

若要使用长连接订阅，凭证仍需包含

app_id

和

app_secret

字段，因为该传输方式会在常规Bearer令牌请求路径之外打开自己的临时事件地址。

若已持有租户令牌，可使用手动备用方案：

bash

curl -sS https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"app_id":"cli_xxx","app_secret":"xxxx"}'

Lark在其主机上使用相同的路径结构：

bash

curl -sS https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"app_id":"cli_xxx","app_secret":"xxxx"}'

配置一个Bearer凭证并绑定到飞书API主机：

bash

uxc auth credential set feishu-tenant \
  --auth-type bearer \
  --secret-env FEISHU_TENANT_ACCESS_TOKEN

uxc auth binding add \
  --id feishu-tenant \
  --host open.feishu.cn \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

对于Lark，创建绑定到

open.larksuite.com

的相同配置：

bash

uxc auth binding add \
  --id lark-tenant \
  --host open.larksuite.com \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

当认证出现问题时，可查看或预加载自动配置状态：

bash

uxc auth bootstrap info feishu-tenant
uxc auth bootstrap refresh feishu-tenant

当认证出现问题时，验证当前生效的绑定：

bash

uxc auth binding match https://open.feishu.cn/open-apis

Core Workflow

核心工作流

Use the fixed link command by default:

```
command -v feishu-openapi-cli
```

If missing, create it:

uxc link feishu-openapi-cli https://open.feishu.cn/open-apis --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json

```
feishu-openapi-cli -h
```

Inspect operation schema first:

```
feishu-openapi-cli get:/im/v1/chats -h
```

feishu-openapi-cli post:/im/v1/images -h

```
feishu-openapi-cli post:/im/v1/files -h
```

feishu-openapi-cli post:/im/v1/messages -h

feishu-openapi-cli get:/im/v1/messages -h

Prefer read/setup validation before writes:

feishu-openapi-cli get:/im/v1/chats page_size=20

feishu-openapi-cli get:/im/v1/chats/{chat_id} chat_id=oc_xxx

feishu-openapi-cli get:/contact/v3/users/{user_id} user_id=ou_xxx user_id_type=open_id

Execute with key/value or positional JSON:

key/value:

feishu-openapi-cli get:/im/v1/messages container_id_type=chat container_id=oc_xxx page_size=20

multipart upload:

feishu-openapi-cli post:/im/v1/images image_type=message image=/tmp/example.png

positional JSON:

feishu-openapi-cli post:/im/v1/messages receive_id_type=chat_id '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello from UXC\"}"}'

For inbound message intake, use

uxc subscribe

directly:

uxc subscribe start https://open.feishu.cn/open-apis --transport feishu-long-connection --auth feishu-tenant --sink file:$HOME/.uxc/subscriptions/feishu.ndjson

send a bot-visible message, then inspect the sink for
```
header.event_type = "im.message.receive_v1"
```

默认使用固定链接命令：

检查

feishu-openapi-cli

是否存在：

command -v feishu-openapi-cli

若不存在，创建该链接：

uxc link feishu-openapi-cli https://open.feishu.cn/open-apis --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json

查看帮助：
```
feishu-openapi-cli -h
```

先查看操作schema：

```
feishu-openapi-cli get:/im/v1/chats -h
```

feishu-openapi-cli post:/im/v1/images -h

```
feishu-openapi-cli post:/im/v1/files -h
```

feishu-openapi-cli post:/im/v1/messages -h

feishu-openapi-cli get:/im/v1/messages -h

优先执行读取/配置验证，再进行写入操作：

feishu-openapi-cli get:/im/v1/chats page_size=20

feishu-openapi-cli get:/im/v1/chats/{chat_id} chat_id=oc_xxx

feishu-openapi-cli get:/contact/v3/users/{user_id} user_id=ou_xxx user_id_type=open_id

使用键值对或位置JSON参数执行操作：

键值对方式：

feishu-openapi-cli get:/im/v1/messages container_id_type=chat container_id=oc_xxx page_size=20

多部分上传：

feishu-openapi-cli post:/im/v1/images image_type=message image=/tmp/example.png

位置JSON方式：

feishu-openapi-cli post:/im/v1/messages receive_id_type=chat_id '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello from UXC\"}"}'

对于入站消息接收，直接使用

uxc subscribe

：

uxc subscribe start https://open.feishu.cn/open-apis --transport feishu-long-connection --auth feishu-tenant --sink file:$HOME/.uxc/subscriptions/feishu.ndjson

发送一条机器人可见的消息，然后检查接收器中是否存在
```
header.event_type = "im.message.receive_v1"
```
事件

Operation Groups

操作分组

Chat Reads

聊天查询

```
get:/im/v1/chats
```
```
get:/im/v1/chats/{chat_id}
```
```
get:/im/v1/chats/{chat_id}/members
```

```
get:/im/v1/chats
```
```
get:/im/v1/chats/{chat_id}
```
```
get:/im/v1/chats/{chat_id}/members
```

Message Reads / Writes

消息查询/写入

```
get:/im/v1/messages
```
```
get:/im/v1/messages/{message_id}
```
```
post:/im/v1/messages
```
```
post:/im/v1/messages/{message_id}/reply
```

```
get:/im/v1/messages
```
```
get:/im/v1/messages/{message_id}
```
```
post:/im/v1/messages
```
```
post:/im/v1/messages/{message_id}/reply
```

Uploads

上传操作

```
post:/im/v1/images
```
```
post:/im/v1/files
```

```
post:/im/v1/images
```
```
post:/im/v1/files
```

User Lookup

用户查询

```
get:/contact/v3/users/{user_id}
```
```
post:/contact/v3/users/batch_get_id
```

```
get:/contact/v3/users/{user_id}
```
```
post:/contact/v3/users/batch_get_id
```

Guardrails

防护规则

Keep automation on the JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
Prefer
```
uxc auth bootstrap
```
over manual token management. Manual
```
tenant_access_token
```
setup is still supported as a fallback.
```
feishu-long-connection
```
requires the app credential fields
```
app_id
```
and
```
app_secret
```
; a plain bearer-only credential is not enough for event intake.
```
post:/im/v1/images
```
and
```
post:/im/v1/files
```
use
```
multipart/form-data
```
. File fields must be local path strings; help output marks them as multipart file fields.
```
post:/im/v1/messages
```
requires the
```
receive_id_type
```
query parameter and the body
```
content
```
field is a JSON-encoded string, not a nested JSON object.

Upload first, then send by returned key:

image sends use

msg_type=image

with

content='{\"image_key\":\"img_xxx\"}'

file sends use

msg_type=file

with

content='{\"file_key\":\"file_xxx\"}'

```
post:/im/v1/messages/{message_id}/reply
```
is for explicit replies to an existing message. Treat it as a high-risk write.
History reads only return chats and messages visible to the bot/app configuration. Auth success does not imply access to every chat.
Long-connection message intake is validated for Feishu bot chats; webhook-style callbacks and non-IM products are still out of scope.

feishu-openapi-cli <operation> ...

is equivalent to

uxc https://open.feishu.cn/open-apis --schema-url <feishu_openapi_schema> <operation> ...

自动化操作请基于JSON输出格式，不要使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
优先使用
```
uxc auth bootstrap
```
而非手动令牌管理。手动配置
```
tenant_access_token
```
仍作为备用方案支持。
```
feishu-long-connection
```
需要应用凭证字段
```
app_id
```
和
```
app_secret
```
；仅含Bearer令牌的凭证不足以支持事件接收。
```
post:/im/v1/images
```
和
```
post:/im/v1/files
```
使用
```
multipart/form-data
```
格式。文件字段必须为本地路径字符串；帮助输出会将其标记为多部分文件字段。
```
post:/im/v1/messages
```
需要
```
receive_id_type
```
查询参数，且请求体中的
```
content
```
字段为JSON编码字符串，而非嵌套JSON对象。
先上传，再通过返回的key发送：
- 图片发送使用
```
msg_type=image
```
  ，并搭配
```
content='{"image_key":"img_xxx"}'
```
- 文件发送使用
```
msg_type=file
```
  ，并搭配
```
content='{"file_key":"file_xxx"}'
```
```
post:/im/v1/messages/{message_id}/reply
```
用于对已有消息进行显式回复，请将其视为高风险写入操作。
历史记录查询仅返回机器人/应用配置可见的聊天和消息。认证成功不代表可访问所有聊天。
长连接消息接收已针对飞书机器人聊天验证；Webhook式回调和非即时通讯类产品仍不在本Skill范围内。

feishu-openapi-cli <operation> ...

等价于

uxc https://open.feishu.cn/open-apis --schema-url <feishu_openapi_schema> <operation> ...

。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
Curated OpenAPI schema:
```
references/feishu-im.openapi.json
```
Feishu Open Platform docs: https://open.feishu.cn/document/
Lark Open Platform docs: https://open.larksuite.com/document/

使用模式：
```
references/usage-patterns.md
```
精选OpenAPI schema：
```
references/feishu-im.openapi.json
```
飞书开放平台文档：https://open.feishu.cn/document/
Lark开放平台文档：https://open.larksuite.com/document/