144 lines
4.4 KiB
Markdown
144 lines
4.4 KiB
Markdown
# Feishu Smart Doc Writer
|
||
|
||
> **English**: Feishu/Lark Smart Document Writer. Solves API content limits by auto-chunking long documents and auto-transferring ownership. Guides OpenID config on first use.
|
||
>
|
||
> **中文**: 飞书智能文档写入器，解决长文档API限制导致的空白问题，自动转移所有权。首次使用自动引导配置。
|
||
|
||
飞书智能文档写入器 - 解决长文档写入时的 API 限制问题，支持自动转移所有权。
|
||
|
||
## 认证说明
|
||
|
||
本 Skill 使用 OpenClaw 内置的飞书工具集，**无需手动获取 token**。
|
||
|
||
- `tenant_access_token` 由 OpenClaw 自动管理（通过配置好的 `appId` 和 `appSecret` 自动换取）
|
||
- 你**不需要**去飞书后台点击"获取 token"
|
||
- 本 Skill 唯一需要配置的是 **用户 OpenID**（用于文档所有权转移，见下方配置步骤）
|
||
|
||
## 核心功能
|
||
|
||
### 1. 智能分块写入
|
||
飞书 API 对单次写入有限制（创建~4000字符，追加~2000字符），超过会导致文档空白。本 Skill 自动将长内容分块写入，确保完整无丢失。
|
||
|
||
### 2. 自动转移所有权
|
||
应用创建的文档默认所有权属于应用，用户无法编辑。本 Skill 在创建文档后自动转移所有权给用户，用户拥有完全控制权。
|
||
|
||
### 3. 首次使用自动引导
|
||
首次使用时自动引导用户配置 OpenID，无需查阅文档。
|
||
|
||
## 使用流程
|
||
|
||
### 第1步：首次使用（自动引导）
|
||
|
||
当你第一次使用 `write_smart` 时，Skill 会自动提示配置指南。
|
||
|
||
### 第2步：获取你的 OpenID
|
||
|
||
**详细步骤（精确路径）：**
|
||
|
||
1. **登录飞书开放平台**
|
||
- 网址：https://open.feishu.cn
|
||
|
||
2. **进入权限管理并前往调试台**
|
||
- 进入你的**相关应用**
|
||
- 点击 **"权限管理"**
|
||
- 搜索权限：`im:message`
|
||
- 鼠标移动到 **"相关API事件"**
|
||
- 选择：**【API】发送消息**
|
||
- 点击右下角：**"前往API调试台"**
|
||
|
||
3. **找到 "快速复制 open_id"**
|
||
- 在页面中找到 **蓝色文字** "快速复制 open_id"
|
||
- 点击这个链接
|
||
|
||
4. **选择用户并复制**
|
||
- 在弹出的选择框中，**选择你的账号**
|
||
- 点击 **"复制"** 按钮
|
||
- 得到格式如：`ou_xxxxxxxx`
|
||
|
||
### 第3步：开通并发布权限
|
||
|
||
⚠️ **重要：需要开通权限并发布应用新版本**
|
||
|
||
1. **进入权限管理**
|
||
- 登录 https://open.feishu.cn
|
||
- 进入你的应用 → **权限管理**
|
||
|
||
2. **搜索并开通权限**
|
||
- 搜索：`docs:permission.member:transfer`
|
||
- 点击 **"开通"**
|
||
|
||
3. **发布新版本（关键！）**
|
||
- 点击页面右上角的 **"发布"** 按钮
|
||
- 等待发布完成
|
||
- ⚠️ **不发布的话，权限不会生效！**
|
||
|
||
### 第4步：配置 Skill
|
||
|
||
根据引导，使用 `configure` 工具配置：
|
||
|
||
```python
|
||
await ctx.invoke_tool("feishu_smart_doc_writer.configure", {
|
||
"openid": "ou_5b921cba0fd6e7c885276a02d730ec19",
|
||
"permission_checked": true
|
||
})
|
||
```
|
||
|
||
### 第5步：创建文档（自动转移所有权）
|
||
|
||
配置完成后，直接创建文档：
|
||
|
||
```python
|
||
result = await ctx.invoke_tool("feishu_smart_doc_writer.write_smart", {
|
||
"title": "项目报告",
|
||
"content": "# 项目报告\n\n很长很长的内容...（支持10000+字）"
|
||
})
|
||
|
||
# 返回：
|
||
# {
|
||
# "doc_url": "https://feishu.cn/docx/xxx",
|
||
# "chunks_count": 5,
|
||
# "owner_transferred": true,
|
||
# "message": "✅ 文档创建成功，共分 5 块写入，所有权已转移"
|
||
# }
|
||
```
|
||
|
||
**配置一次，永久生效！** 之后创建文档会自动转移所有权。
|
||
|
||
## 工具列表
|
||
|
||
| 工具名 | 功能 |
|
||
|--------|------|
|
||
| `write_smart` | 创建文档，自动分块写入，自动转移所有权（首次使用引导配置） |
|
||
| `configure` | 配置 OpenID 和确认权限 |
|
||
| `append_smart` | 追加内容到已有文档（自动分块） |
|
||
| `transfer_ownership` | 转移已有文档的所有权 |
|
||
| `get_config_status` | 查看当前配置状态 |
|
||
|
||
## 为什么需要这个 Skill？
|
||
|
||
### 原生 feishu_doc 的问题
|
||
|
||
```python
|
||
# ❌ 原生方式 - 长内容会失败
|
||
feishu_doc.create(
|
||
title="项目报告",
|
||
content="# 很长很长的内容..." * 1000 # 超过4000字符
|
||
)
|
||
# 结果：文档创建，但内容空白或报错
|
||
```
|
||
|
||
### 使用本 Skill
|
||
|
||
```python
|
||
# ✅ 自动处理 - 内容分块写入，自动转移所有权
|
||
write_smart(
|
||
title="项目报告",
|
||
content="# 很长很长的内容..." * 1000, # 10000字符
|
||
)
|
||
# 结果：自动分为5块写入，所有权转移给用户，文档完整
|
||
```
|
||
|
||
## License
|
||
|
||
MIT
|