前言¶
团队的知识库在飞书里，常见的痛点是：Wiki 链接点进去还要跳一层才是真实文档；文档正文、表格、多维表格（Bitable）各自结构不同，人工复制粘贴既慢又容易丢格式；写脚本直接对接开放平台又要自己处理 token 鉴权和分页。
这个 Skill 的作用是让 agent 直接按文档或 token 取飞书内容，自动把 Wiki URL 解析成真实实体，并把结果转成 Markdown，省掉自己写对接代码的功夫。
这是什么¶
Feishu Doc 是一个基于通用 SKILL.md 格式的 Agent Skill，用来读写飞书（Lark）的 Wiki、文档、表格和 Bitable。
它由 autogame-17 发布，来源为 clawhub，上游仓库在 clawhub.ai/autogame-17/feishu-doc，当前版本 v1.2.7，许可证 MIT-0。SkillHub 上同步收录了该 Skill，坐标 @clawhub_autogame-17/feishu-doc，分类 office-efficiency。
它解决的问题是：给 agent 一个统一的入口读飞书内容并转成 Markdown，同时支持创建、覆盖写入和追加写入文档。
核心功能¶
下面是已从官方资料核实的能力，按官方 SKILL.md 的分类列出。
读取：从文档、表格、Bitable 和 Wiki 获取内容，自动把 Wiki URL 解析为真实实体，并转换为 Markdown。
创建：创建新的空白文档。
写入：用 Markdown 覆盖文档已有内容。
追加：把 Markdown 内容追加到文档末尾。
Block 级操作：列出、获取、更新和删除具体的 block，用于在文档内部做局部修改。
注意，官方资料里的写入动作描述是「overwrite document content with Markdown」，也就是覆盖写，不是在光标处插入。需要保留原文时要先 read 出来再整体写回。
前置依赖¶
这个 Skill 不能单独使用，必须先装 feishu-common。
官方说明：该 Skill 依赖 ../feishu-common/index.js 来完成 token 和 API 鉴权。也就是说鉴权逻辑不在 feishu-doc 自身，而是由配套的 common 包提供。漏装这一步，后续 read/write 都会因为没有鉴权而失败。
安装顺序上，先装 feishu-common，再装 feishu-doc。
安装与启用¶
官方给出的安装命令走 OpenClaw/clawhub 生态的 CLI，命令如下。
openclaw skills install @autogame-17/feishu-doc
这条命令拉取 Skill 包到本地 skills 目录，之后由 agent 运行时加载 SKILL.md。
官方资料中没有分别给出 Cursor、Codex CLI、Claude Code 的安装方式，也没有说明这些工具是否需要额外配置。这一点按现状说明，不做推断。
配置¶
鉴权需要飞书开放平台应用的 app_id 和 app_secret，有两种提供方式，二选一。
在 Skill 根目录创建 config.json：
{
"app_id": "YOUR_APP_ID",
"app_secret": "YOUR_APP_SECRET"
}
或用环境变量：
export FEISHU_APP_ID="YOUR_APP_ID"
export FEISHU_APP_SECRET="YOUR_APP_SECRET"
配好之后，agent 或 CLI 调用时才能拿到有效的访问凭证。app_id 和 app_secret 需替换为实际值，官方资料未提供占位符之外的示例值。
典型用法¶
官方资料给出了一组可复现的 CLI 调用，下面按动作分别列出。这些都是在 Skill 目录下执行 node index.js。
读取文档内容：
node index.js --action read --token <doc_token>
创建空白文档：
node index.js --action create --title "My Doc"
覆盖写入，--content 接收 Markdown 字符串：
node index.js --action write --token <doc_token> --content "# Title\nHello world"
追加写入，适合分段补内容：
node index.js --action append --token <doc_token> --content "## Section 2\nMore text"
实际使用时把 <doc_token> 换成真实文档的 token。创建动作返回的 doc_token 可以接在后续 write / append 里，形成先建文档再填内容的顺序。
长文档处理¶
官方资料专门说明了超过 LLM 输出长度上限时的处理方式。默认单次输出大约在 2000 到 4000 tokens，长文档一次写完会被截断。
官方建议的做法是分块追加：
1、先 create 拿到 doc_token。
2、把内容按逻辑章节切分，例如 Introduction、Chapter 1、Chapter 2。
3、逐块调用 feishu_doc_append 顺序追加。
官方明确提醒：文档很长时不要试图用一次 feishu_doc_write 写完整篇，用 append 循环的方式更稳。
这个约束来自模型输出长度，而不是飞书接口本身，所以内容越长，分块策略越重要。
适用场景与注意¶
适合的场景：需要把飞书 Wiki、文档、表格或 Bitable 的内容拉出来转成 Markdown，再交给 agent 做总结、检索或二次加工；需要在 agent 里创建或更新飞书文档。
需要注意的地方：
必须先装 feishu-common，否则没有鉴权。
必须配置 app_id 和 app_secret，否则请求会被拒绝。
write 是覆盖写，操作前先 read 确认内容，避免误覆盖。
长文档要分块 append，不要指望一次 write 完成。
官方安装命令面向 OpenClaw/clawhub 生态，其他工具的安装方式官方未说明。
小结¶
这个 Skill 的价值在于把飞书内容的读取和 Markdown 转换收敛成一个标准动作，Wiki URL 解析、鉴权依赖和分块写入这些细节由 Skill 内部处理，使用者只需要提供 token 和凭证。官方地址：https://api.skillhub.cn/zcwl/feishu-doc
