让 AI IDE（如 OpenCode、Claude Code、Windsurf、Cursor 等）直接在终端读写飞书文档，无需打开浏览器。
下载地址：https://github.com/hanhx/feishu-doc
支持三种安装方式：AI 安装（推荐）、手动安装、软链接。
直接在 AI IDE 中告诉 AI 助手：
"帮我安装 feishu-doc skill，仓库地址是 https://github.com/hanhx/feishu-doc"
AI 会自动识别当前 IDE 并安装到正确的目录。
根据你使用的 AI IDE，选择对应的命令：
OpenCode
git clone https://github.com/hanhx/feishu-doc.git ~/.opencode/skills/feishu-docClaude Code
git clone https://github.com/hanhx/feishu-doc.git ~/.claude/skills/feishu-docWindsurf
git clone https://github.com/hanhx/feishu-doc.git ~/.codeium/windsurf/skills/feishu-docCursor
git clone https://github.com/hanhx/feishu-doc.git ~/.cursor/skills/feishu-doc安装完成后，AI IDE 会自动识别 SKILL.md 并加载该 skill。
如果你已经克隆到其他位置，可以创建软链接：
# OpenCode
ln -s /path/to/feishu-doc ~/.opencode/skills/feishu-doc
# Claude Code
ln -s /path/to/feishu-doc ~/.claude/skills/feishu-doc
# Windsurf
ln -s /path/to/feishu-doc ~/.codeium/windsurf/skills/feishu-doc
# Cursor
ln -s /path/to/feishu-doc ~/.cursor/skills/feishu-doc💡 提示：
- 不同 IDE 版本的 skills 目录可能不同，请以对应 IDE 官方文档为准
- 如果下载 zip 包，解压后文件夹名为
feishu-doc-main，需重命名为feishu-doc或创建软链接
💡 推荐：直接联系作者获取已注册好的 App ID 和 App Secret，无需自己创建应用。
如需自己申请，参考 附录：自建飞书应用。
支持两种配置方式，环境变量优先：
方式1：环境变量（推荐）
在 ~/.zshrc（Mac 默认）或 ~/.bash_profile 中添加：
export FEISHU_APP_ID=cli_xxxx
export FEISHU_APP_SECRET=xxxx保存后执行 source ~/.zshrc 生效。
方式2：配置文件
编辑 assets/.feishu 填入凭证：
app_id=cli_xxxx
app_secret=xxxx
配置完成后，直接在 AI IDE 聊天中告诉 AI 助手：
读取文档
"帮我读一下这个飞书文档 https://xxx.feishu.cn/wiki/TOKEN"
写入文档（覆盖更新）
"帮我把这个方案写到 https://xxx.feishu.cn/wiki/TOKEN"
清空文档
在某章节后追加（支持模糊匹配 / 正则）
"在『技术方案』章节末尾追加这段内容"
删除某个章节后重写
"先删除『技术方案』章节，再把这段新内容写进去"
⚠️ 安全保护：
insert-targeted和delete-section默认都会先展示预览，并要求输入yes确认后才执行。- 非交互执行时需要显式传
--yes。
首次使用时，系统会自动检测到未登录并打开浏览器授权页，你只需点击「授权」即可。Token 过期时也会自动重新登录。
- 标题（H1~H9，第一个 H1 自动设为文档标题）
- 代码块（自动识别 Java、SQL、JSON、Python、Go、Shell、mermaid 等语言）
- 无序列表、有序列表
- 待办事项（
- [ ]/- [x]） - 引用（渲染为飞书 Callout 容器）
- 表格（自动拆分为飞书原生表格，每个子表最多 8 行数据 + 1 行表头，大表格无缝支持）
- 分割线
- 行内样式：加粗、
行内代码、删除线、超链接
下面这些能力，直接在 AI IDE 里用自然语言描述即可：
- 在某个章节后追加内容
- 在某段文本后插入内容
- 删除某个章节后重写
示例：
"在『技术方案』章节末尾追加这段内容"
"在『数据库设计如下』这段话后面插入这段说明"
"先删除『技术方案』章节，再把这段新内容写进去"
⚠️ 安全保护：涉及定点插入和章节删除时，系统会先给你预览，再确认执行。
检查：
- 应用是否已开通
docx:document和docx:document:readonly权限 - 修改权限后是否重新发布了应用版本
- 是否重新运行了
login.py授权
会自动重新登录，无需手动操作。如需手动重新登录或切换账号：
python3 scripts/login.py logout && python3 scripts/login.py飞书 API 限制单次创建表格最多 9 行。超过 9 行的表格会自动拆分为多个子表格，每个子表最多 8 行数据 + 1 行表头，均为飞书原生表格渲染。如果子表创建失败，会自动 fallback 为 markdown 代码块展示。
- 跟应用绑定，不跟个人绑定。同一个飞书组织内的成员可以共用同一对 app_id / app_secret。
- app_id + app_secret 用于启动 OAuth 授权流程，本身不能直接访问任何文档。
- 建议：不要提交到公开仓库，通过
.gitignore忽略assets/.feishu.local文件；assets/.feishu仅作为空模板。
- 必须由用户本人在浏览器中点击授权才能获得，仅凭 app_id + app_secret 无法伪造。
- 权限范围与你的飞书账号一致：你能编辑的文档才能写，你能查看的文档才能读。
- 有效期 2 小时，脚本自动刷新。
- 用于刷新 access_token，有效期 30 天。
⚠️ 泄露 refresh_token = 身份被冒用。请妥善保管assets/.user_token_cache文件，不要分享给他人。
| 凭证 | 能做什么 | 泄露风险 |
|---|---|---|
| app_id + app_secret | 启动 OAuth 授权流程，本身不能访问文档 | 低 |
| user_access_token | 以个人身份读写文档（2h 过期） | 中，但需本人授权才能获取 |
| refresh_token | 刷新出新的 access_token（30 天有效） | 高，泄露等于身份冒用 |
- 共享 app_id + app_secret：团队成员使用同一份
.feishu配置即可 - 各自登录：每人运行
login.py完成个人授权，token 缓存互不影响 - 不共享 token 缓存：
.user_token_cache文件仅限本人使用
如果不使用作者提供的 App ID，可以自己创建飞书应用：
- 打开 飞书开放平台，登录后点击「创建企业自建应用」
- 填写应用名称（如
feishu-doc或AI IDE Doc），创建完成后进入应用详情页 - 记录 App ID 和 App Secret
进入应用详情 → 权限管理 → 搜索并开通以下权限：
| 权限标识 | 说明 | 必须 |
|---|---|---|
docx:document |
查看、编辑和管理云文档 | ✅ |
docx:document:readonly |
查看云文档 | ✅ |
读写权限与你的个人账号一致：授权登录后，AI 助手使用你的身份访问飞书。你能看到的文档就能读，你能编辑的文档就能写，不需要额外给应用分享文档权限。
进入应用详情 → 安全设置 → 重定向 URL → 添加：
http://127.0.0.1:9999/callback
⚠️ 必须使用127.0.0.1，不要用localhost，否则会报 20029 错误。
进入应用详情 → 版本管理与发布 → 创建版本 → 提交发布。
⚠️ 每次修改权限后都需要重新发布版本，否则新权限不生效。
如需手动触发登录流程，在 skill 根目录执行：
python3 scripts/login.py💡 OpenCode 常见路径：
~/.opencode/skills/feishu-doc
💡 Claude Code 常见路径：~/.claude/skills/feishu-doc
💡 Windsurf 常见路径：~/.codeium/windsurf/skills/feishu-doc
💡 Cursor 常见路径：~/.cursor/skills/feishu-doc
Token 有效期：
- access_token：2 小时，脚本自动刷新
- refresh_token：30 天，过期后自动重新登录