Feishu Doc

SKILL.md

---
name: feishu-doc
version: 1.0.3
description: |
  飞书云文档创建与管理。当用户提到"创建飞书文档"、"新建飞书文档"、"生成文档发送到飞书"、"飞书文档写入"等时使用。
  支持创建带标题和富文本内容的飞书文档，包含段落、标题、列表等格式。
---

# 飞书文档创建

## 核心流程

### 1. 获取用户授权（仅首次）

若本地未存储 user_access_token 或 token 过期，需要用户重新授权：

**授权链接格式：**
```
https://open.feishu.cn/open-apis/authen/v1/authorize?client_id=<YOUR_APP_ID>&redirect_uri=<YOUR_REDIRECT_URI>&scope=offline_access docx:document:create docx:document.block:convert&response_type=code
```

参数说明：
- `client_id`: 飞书应用的 App ID
- `redirect_uri`: 应用安全设置中配置的重定向 URL
- `scope`: 申请权限列表（空格分隔）

用户访问链接 → 授权 → 飞书跳转回 redirect_uri → 回调 URL 中的 `code=xxx` 即为授权码

### 2. 交换 Token

```python
import urllib.request
import json

# 1. 获取 app_access_token
app_body = json.dumps({
    "app_id": "<YOUR_APP_ID>",
    "app_secret": "<YOUR_APP_SECRET>"
})
req = urllib.request.Request(
    "https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal",
    data=app_body.encode("utf-8"),
    headers={"Content-Type": "application/json; charset=utf-8"},
    method="POST"
)
app_token = json.loads(urllib.request.urlopen(req).read().decode("utf-8"))["app_access_token"]

# 2. 用 code 换取 user_access_token
code = "<用户授权后获得的code>"
user_body = json.dumps({"grant_type": "authorization_code", "code": code}).encode("utf-8")
req = urllib.request.Request(
    "https://open.feishu.cn/open-apis/authen/v1/oidc/access_token",
    data=user_body,
    headers={
        "Authorization": f"Bearer {app_token}",
        "Content-Type": "application/json; charset=utf-8"
    },
    method="POST"
)
result = json.loads(urllib.request.urlopen(req).read().decode("utf-8"))
user_token = result["data"]["access_token"]
refresh_token = result["data"]["refresh_token"]
```

### 3. 创建文档（关键：请求体格式！）

```python
import json, urllib.request

token = "<user_access_token>"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json; charset=utf-8"
}

# 创建文档 - 请求体直接用 {"title": "标题"}
body = json.dumps({"title": "文档标题"}, ensure_ascii=False).encode("utf-8")
req = urllib.request.Request(
    "https://open.feishu.cn/open-apis/docx/v1/documents",
    data=body,
    headers=headers,
    method="POST"
)
doc_id = json.loads(urllib.request.urlopen(req).read().decode("utf-8"))["data"]["document"]["document_id"]
```

### 4. 添加内容块

```python
base_url = f"https://open.feishu.cn/open-apis/docx/v1/documents/{doc_id}/blocks/{doc_id}/children"

def add_text(text, indent=0):
    block = {"block_type": 2, "text": {"elements": [{"type": "text_run", "text_run": {"content": text}}]}}
    if indent > 0:
        block["style"] = {"indent_level": indent}
    body = json.dumps({"children": [block]}, ensure_ascii=False).encode("utf-8")
    req = urllib.request.Request(base_url, data=body, headers=headers, method="POST")
    urllib.request.urlopen(req)

def add_heading(text, level=1):
    key = f"heading{level}"
    block = {"block_type": level + 2, key: {"elements": [{"type": "text_run", "text_run": {"content": text}}]}}
    body = json.dumps({"children": [block]}, ensure_ascii=False).encode("utf-8")
    req = urllib.request.Request(base_url, data=body, headers=headers, method="POST")
    urllib.request.urlopen(req)
```

**Block Type 参考：**
| Type | 类型 |
|------|------|
| 2 | 文本段落 |
| 3 | 一级标题 |
| 4 | 二级标题 |
| 5 | 三级标题 |

## 关键要点

1. **请求体格式**：创建文档用 `{"title": "xxx"}`，不是 `{"document_style": {"title": ...}}`
2. **编码**：所有请求必须用 UTF-8 编码，`Content-Type: application/json; charset=utf-8`
3. **Token 存储**：本地安全存储 user_access_token 和 refresh_token
4. **请求限流**：每个请求间隔 0.3-0.5 秒，避免 429 错误
5. **敏感信息**：App ID、App Secret、user_access_token 等敏感信息不要硬编码，建议使用环境变量或配置文件管理