feishu-docs-cli 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +47 -21
  2. package/README.zh.md +47 -21
  3. package/package.json +1 -1
  4. package/skills/feishu-docs/SKILL.md +3 -2
package/README.md CHANGED
@@ -1,31 +1,40 @@
1
1
  # feishu-docs-cli
2
2
 
3
- [中文文档](./README.zh.md)
3
+ [![License](https://img.shields.io/badge/License-MIT-yellow)](./LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D18.3.0-blue)](https://nodejs.org) [![npm](https://img.shields.io/npm/v/feishu-docs-cli)](https://www.npmjs.com/package/feishu-docs-cli) [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)
4
+
5
+ [中文文档](./README.zh.md) | English
4
6
 
5
7
  CLI tool for AI Agents to read/write Feishu (Lark) docs via shell commands.
6
8
 
7
- ## Why feishu-docs-cli?
9
+ ## Project Status
10
+
11
+ > **Note**: The official [lark-cli](https://github.com/larksuite/cli) has been released by the Lark/Feishu team (2026). It covers a much broader range of Feishu APIs (IM, calendar, tasks, contacts, bitable, etc.). We believe the official tool will continue to improve, so **this project will slow down on new feature development**. Existing functionality will be maintained but no major additions are planned.
12
+ >
13
+ > If you need full Feishu API coverage, use [lark-cli](https://github.com/larksuite/cli). If you primarily work with **documents and knowledge bases** and need clean Markdown I/O, feishu-docs-cli still offers a better experience in that specific area.
8
14
 
9
- Feishu/Lark already offers the official [lark-mcp](https://github.com/larksuite/lark-openapi-mcp) MCP server. Here's what this project does differently:
15
+ ## Comparison with lark-cli
10
16
 
11
- | Capability | feishu-docs-cli | lark-mcp |
12
- |------------|:-:|:-:|
13
- | Read docs as Markdown | **Yes** — 30+ block types rendered | No — returns raw Block JSON |
14
- | Write docs from Markdown | **Yes** — auto-convert, auto-batch (>1000 blocks) | No |
15
- | Knowledge base tree browsing | **Yes** — `spaces` → `tree` → `cat` workflow | Search/get single node only |
16
- | Batch read entire wiki subtree | **Yes** — `cat` recursively exports Markdown | No |
17
- | Write safety (backup/restore) | **Yes** — auto-backup before overwrite, auto-recover on failure | No |
18
- | OAuth user login | **Yes** — full OAuth v2 with auto-refresh, tiered scope management, interactive recovery | Yes — basic OAuth login |
19
- | Works with any AI agent | **Yes** — standard CLI, pipes, scripts | MCP protocol only |
20
- | IM / messaging | No | Yes |
21
- | Bitable CRUD | Read-only (rendered as table) | Yes |
22
- | Contact lookup | Via `share add` only | Yes |
17
+ Based on real-world testing against the same knowledge base (2026-03-29):
23
18
 
24
- **In short**: lark-mcp is a thin wrapper over Feishu APIs with broad coverage. feishu-docs-cli is purpose-built for **document workflows** — it lets AI agents truly read, understand, and write Feishu documents as Markdown, with safety guardrails that the raw API doesn't provide.
19
+ | Capability | feishu-docs-cli | lark-cli (official) |
20
+ |------------|-----------------|---------------------|
21
+ | **Read as Markdown** | Standard Markdown — tables, lists, code blocks render correctly | Returns JSON with `<lark-table>` custom HTML tags, not standard Markdown |
22
+ | **Knowledge base tree** | `tree` command — one call, full recursive tree | No equivalent — must call `get_node` per node |
23
+ | **Batch read wiki** | `cat` — recursively reads all child docs | No equivalent |
24
+ | **Create in wiki** | `--wiki <space> --parent <node>` — supports parent node placement | `--wiki-space` and `--wiki-node` are mutually exclusive |
25
+ | **Update docs** | Accepts file path (`--body file.md`), auto-backup before overwrite | Inline `--markdown` only, `--mode` required |
26
+ | **Search** | `search "keyword"` — one step | Requires separate scope authorization |
27
+ | **Share / permissions** | `share list/add/remove/update/set` — fully wrapped | No wrapper — requires raw API calls |
28
+ | **JSON output** | Clean, pipe-friendly `--json` | Mixes progress text (`[page 1] fetching...`) into stdout |
29
+ | **Error messages** | Chinese messages with recovery hints, missing scope auto-detection | English errors, manual scope lookup |
30
+ | **API coverage** | Documents, wiki, drive, search, permissions | **Full platform** — IM, calendar, tasks, contacts, bitable, mail, video conference, etc. |
31
+ | **Dependencies** | Zero runtime deps (Node.js built-ins only) | Go binary |
32
+ | **Cold start** | ~0.5s (Node.js) | ~0.1s (Go) |
25
33
 
34
+ **In short**: feishu-docs-cli is purpose-built for **document workflows** — clean Markdown I/O, recursive wiki browsing, and write safety. lark-cli is a comprehensive platform CLI with broader API coverage.
26
35
  ## Features
27
36
 
28
- - **Read** documents as Markdown, raw text, or original Block JSON
37
+ - **Read** documents as Markdown (images downloaded to local files), raw text, or original Block JSON
29
38
  - **Create** documents in knowledge bases or cloud folders
30
39
  - **Update** documents with overwrite or append mode (auto-batch for large content)
31
40
  - **Delete** documents (move to recycle bin)
@@ -145,7 +154,7 @@ With these three variables set, all commands work without `feishu-docs login`. T
145
154
  ### Read
146
155
 
147
156
  ```bash
148
- # Read document as Markdown
157
+ # Read document as Markdown (images auto-downloaded to ~/.feishu-docs/images/)
149
158
  feishu-docs read https://xxx.feishu.cn/wiki/wikcnXXX
150
159
 
151
160
  # Read by token
@@ -161,6 +170,8 @@ feishu-docs read <url> --raw
161
170
  feishu-docs read <url> --with-meta
162
171
  ```
163
172
 
173
+ Images in documents are automatically downloaded to `~/.feishu-docs/images/` and referenced as local file paths in the Markdown output. Cached images are reused for 30 days.
174
+
164
175
  ### Knowledge Base
165
176
 
166
177
  ```bash
@@ -405,8 +416,23 @@ dist/ # Compiled output (git-ignored)
405
416
 
406
417
  - [x] Feishu cloud document operations (read, create, update, delete, info)
407
418
  - [x] Knowledge base operations (spaces, tree, cat, wiki management, share, search)
408
- - [ ] Feishu Bitable (multi-dimensional table) operations
409
- - [ ] Feishu Sheets (spreadsheet) operations
419
+ - [x] Quality hardening — 456 tests, retry logic, error recovery, dead code cleanup
420
+
421
+ > Bitable and Sheets operations are not planned. For those, use the official [lark-cli](https://github.com/larksuite/cli).
422
+
423
+ ## Mermaid Diagrams
424
+
425
+ feishu-docs-cli and lark-cli handle Mermaid differently when writing:
426
+
427
+ | | feishu-docs-cli | lark-cli (official) |
428
+ |---|---|---|
429
+ | **Write** | Stored as `` ```mermaid `` code block (block_type 14) | Converted to whiteboard/board (block_type 43) via Lark MCP |
430
+ | **Read back own output** | Returns original Mermaid code — lossless round-trip | Returns whiteboard node graph (shapes, coordinates, connectors) — cannot recover Mermaid source |
431
+ | **Read native Mermaid** | Both tools can read Mermaid code blocks written natively in Feishu — no issue here |
432
+ | **Human readability** | Code block in document — not visually rendered (Feishu supports "text diagram" blocks but the Open API cannot create them) | Renders as interactive diagram immediately |
433
+ | **Best for** | AI agent workflows — Mermaid survives read/write round-trips | Human consumption — visual diagrams, but one-way (write-only) |
434
+
435
+ **Why this trade-off?** Feishu has a native "text diagram" block that renders Mermaid visually, but the Open API's Convert endpoint does not support creating it — Mermaid is treated as a plain code block. lark-cli works around this by converting Mermaid to a whiteboard (board) via the Lark MCP protocol, which produces a visual result but loses the Mermaid source code. We chose to preserve the code block so AI agents can reliably read and modify diagrams.
410
436
 
411
437
  ## Limitations
412
438
 
@@ -415,7 +441,7 @@ dist/ # Compiled output (git-ignored)
415
441
  - **Link only**: mindnote
416
442
  - **Not supported**: doc (legacy format)
417
443
  - Markdown conversion is lossy (colors, merged cells, layouts are dropped). Use `--blocks` for lossless JSON.
418
- - Image write is not supported (read returns temporary URLs valid ~24h)
444
+ - Image read downloads to local files (`~/.feishu-docs/images/`) with 30-day cache. Image write is not supported.
419
445
 
420
446
  ## License
421
447
 
package/README.zh.md CHANGED
@@ -1,31 +1,40 @@
1
1
  # feishu-docs-cli
2
2
 
3
- [English](./README.md)
3
+ [![License](https://img.shields.io/badge/License-MIT-yellow)](./LICENSE) [![Node](https://img.shields.io/badge/node-%3E%3D18.3.0-blue)](https://nodejs.org) [![npm](https://img.shields.io/npm/v/feishu-docs-cli)](https://www.npmjs.com/package/feishu-docs-cli) [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)
4
+
5
+ 中文文档 | [English](./README.md)
4
6
 
5
7
  让 AI Agent（Claude Code、Codex、Trae 等）通过 shell 命令读写飞书云文档和知识库。
6
8
 
7
- ## 为什么选 feishu-docs-cli？
9
+ ## 项目状态
10
+
11
+ > **说明**：飞书官方已发布 [lark-cli](https://github.com/larksuite/cli)（2026），覆盖 IM、日历、任务、通讯录、多维表格等全平台 API。相信官方工具会不断完善，**本项目将放缓新功能开发**，现有功能会继续维护，但不再计划大的功能新增。
12
+ >
13
+ > 如需完整的飞书 API 能力，请使用 [lark-cli](https://github.com/larksuite/cli)。如果主要场景是**文档和知识库**且需要标准 Markdown 输入输出，feishu-docs-cli 在这个细分领域仍有更好的体验。
8
14
 
9
- 飞书官方已有 [lark-mcp](https://github.com/larksuite/lark-openapi-mcp) MCP 服务。以下是本项目的差异化能力：
15
+ ## 与 lark-cli 的对比
10
16
 
11
- | 能力 | feishu-docs-cli | lark-mcp |
12
- |------|:-:|:-:|
13
- | 读取文档输出 Markdown | **支持** — 30+ 种 block 类型渲染 | 不支持 — 返回原始 Block JSON |
14
- | 从 Markdown 写入文档 | **支持** — 自动转换、大文档自动分批（>1000 blocks） | 不支持 |
15
- | 知识库目录树浏览 | **支持** — `spaces` → `tree` → `cat` 完整工作流 | 仅搜索/获取单个节点 |
16
- | 批量读取知识库子树 | **支持** — `cat` 递归导出为 Markdown | 不支持 |
17
- | 写入安全（备份/恢复） | **支持** — 覆盖前自动备份，失败自动恢复 | 不支持 |
18
- | OAuth 用户登录 | **支持** — 完整 OAuth v2 + token 自动刷新 + 分级权限管理 + 交互式权限恢复 | 支持 — 基础 OAuth 登录 |
19
- | 兼容任意 AI Agent | **支持** — 标准 CLI，支持管道和脚本 | 仅 MCP 协议 |
20
- | 即时消息 | 不支持 | 支持 |
21
- | 多维表格 CRUD | 只读（渲染为表格） | 支持 |
22
- | 通讯录查询 | 仅 `share add` 时使用 | 支持 |
17
+ 基于同一知识库的真实操作对比（2026-03-29 实测）：
23
18
 
24
- **一句话总结**：lark-mcp 是飞书 API 的薄封装，覆盖面广但每个功能都是原始 API 级别。feishu-docs-cli 专注于**文档工作流**，让 AI Agent 能以 Markdown 为媒介真正读懂和编写飞书文档，并提供原始 API 没有的安全保障。
19
+ | 能力 | feishu-docs-cli | lark-cli（官方） |
20
+ |------|-----------------|------------------|
21
+ | **读取为 Markdown** | 标准 Markdown — 表格、列表、代码块正确渲染 | 返回 JSON + `<lark-table>` 自定义标签，非标准 Markdown |
22
+ | **知识库目录树** | `tree` 命令 — 一次调用，递归展示完整树 | 无此功能 — 需逐节点调用 `get_node` |
23
+ | **批量读取知识库** | `cat` — 递归读取所有子文档 | 无此功能 |
24
+ | **在知识库创建文档** | `--wiki <space> --parent <node>` — 支持指定父节点 | `--wiki-space` 和 `--wiki-node` 互斥，不能指定父节点 |
25
+ | **更新文档** | 接受文件路径（`--body file.md`），覆盖前自动备份 | 仅支持内联 `--markdown`，必须显式指定 `--mode` |
26
+ | **搜索** | `search "关键词"` — 一步到位 | 需要单独授权不同的 scope |
27
+ | **权限管理** | `share list/add/remove/update/set` — 完整封装 | 无封装 — 需手写原始 API 路径 |
28
+ | **JSON 输出** | 纯净可管道的 `--json` | stdout 混入进度文本（`[page 1] fetching...`），破坏 JSON 管道 |
29
+ | **错误提示** | 中文提示 + 恢复建议 + 缺失 scope 自动检测 | 英文错误提示，需手动查找 scope |
30
+ | **API 覆盖面** | 文档、知识库、云空间、搜索、权限 | **全平台** — IM、日历、任务、通讯录、多维表格、邮件、视频会议等 |
31
+ | **依赖** | 零运行时依赖（仅 Node.js 内置模块） | Go 二进制 |
32
+ | **冷启动** | ~0.5 秒（Node.js） | ~0.1 秒（Go） |
25
33
 
34
+ **一句话总结**：feishu-docs-cli 专注于**文档工作流** — 标准 Markdown 输入输出、知识库递归浏览、写入安全保障。lark-cli 是覆盖全平台的综合性 CLI。
26
35
  ## 功能
27
36
 
28
- - **读取** 文档，输出 Markdown、纯文本或原始 Block JSON
37
+ - **读取** 文档，输出 Markdown（图片自动下载到本地）、纯文本或原始 Block JSON
29
38
  - **创建** 文档到知识库或云空间文件夹
30
39
  - **更新** 文档，支持覆盖写入或追加模式（大文档自动分批）
31
40
  - **删除** 文档（移至回收站）
@@ -127,7 +136,7 @@ feishu-docs login --port 4567
127
136
  ### 读取
128
137
 
129
138
  ```bash
130
- # 读取文档，输出 Markdown
139
+ # 读取文档，输出 Markdown（图片自动下载到 ~/.feishu-docs/images/）
131
140
  feishu-docs read https://xxx.feishu.cn/wiki/wikcnXXX
132
141
 
133
142
  # 通过 token 读取
@@ -143,6 +152,8 @@ feishu-docs read <url> --raw
143
152
  feishu-docs read <url> --with-meta
144
153
  ```
145
154
 
155
+ 文档中的图片会自动下载到 `~/.feishu-docs/images/`，在 Markdown 输出中引用本地文件路径。缓存有效期 30 天。
156
+
146
157
  ### 知识库
147
158
 
148
159
  ```bash
@@ -387,8 +398,23 @@ dist/ # 编译输出（不提交到 git）
387
398
 
388
399
  - [x] 飞书云文档操作（读取、创建、更新、删除、详情）
389
400
  - [x] 知识库操作（空间列表、目录树、批量读取、Wiki 管理、分享、搜索）
390
- - [ ] 飞书多维表格操作
391
- - [ ] 飞书电子表格操作
401
+ - [x] 质量加固 — 456 个测试、重试逻辑、错误恢复、死代码清理
402
+
403
+ > 多维表格和电子表格操作不再计划。如有需要，请使用官方 [lark-cli](https://github.com/larksuite/cli)。
404
+
405
+ ## Mermaid 图表
406
+
407
+ feishu-docs-cli 和 lark-cli 在写入 Mermaid 时的处理方式不同：
408
+
409
+ | | feishu-docs-cli | lark-cli（官方） |
410
+ |---|---|---|
411
+ | **写入** | 保存为 `` ```mermaid `` 代码块（block_type 14） | 通过 Lark MCP 转换为画板（block_type 43） |
412
+ | **读取自己写入的内容** | 返回原始 Mermaid 代码 — 无损读写往返 | 返回画板节点图（形状、坐标、连接线）— 无法还原 Mermaid 源码 |
413
+ | **读取云文档原生 Mermaid** | 两个工具都能正常读取飞书文档中原生的 Mermaid 代码块，没有问题 |
414
+ | **人类可读性** | 文档中显示为代码块，不会可视化渲染（飞书支持"文本绘图"块，但 Open API 无法创建） | 立即渲染为可交互的图表 |
415
+ | **适合场景** | AI Agent 工作流 — Mermaid 读写往返无损 | 人工阅读 — 可视化图表，但单向（写入后无法读回源码） |
416
+
417
+ **为什么这样取舍？** 飞书有原生的"文本绘图"块可以渲染 Mermaid，但 Open API 的 Convert 接口不支持创建它 — Mermaid 被当作普通代码块处理。lark-cli 通过 Lark MCP 协议将 Mermaid 转为画板来绕过此限制，视觉效果好但丢失了 Mermaid 源码。我们选择保留代码块，确保 AI Agent 能可靠地读取和修改图表。
392
418
 
393
419
  ## 限制
394
420
 
@@ -397,7 +423,7 @@ dist/ # 编译输出（不提交到 git）
397
423
  - **仅链接**：思维笔记（mindnote）
398
424
  - **不支持**：doc（旧版格式）
399
425
  - Markdown 转换有损（颜色、合并单元格、布局会丢失）。使用 `--blocks` 获取无损 JSON。
400
- - 不支持图片写入（读取返回约 24 小时有效的临时 URL）
426
+ - 图片读取时自动下载到本地（`~/.feishu-docs/images/`，30 天缓存）。不支持图片写入。
401
427
 
402
428
  ## 许可证
403
429
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "feishu-docs-cli",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "CLI tool for AI Agents to read/write Feishu docs via shell commands",
5
5
  "type": "module",
6
6
  "bin": {
package/skills/feishu-docs/SKILL.md CHANGED
@@ -207,8 +207,9 @@ Default auth mode is `auto` — tries user token first, falls back to tenant.
207
207
  - Only `docx` (new document format) is fully supported for read/write
208
208
  - Legacy `doc` format is not supported
209
209
  - Embedded `sheet` and `bitable` are rendered as tables (lossy)
210
- - Embedded `board`/`whiteboard` are exported as local PNG images (temporary file paths)
210
+ - Embedded `board`/`whiteboard` are exported as local PNG images
211
211
  - `mindnote` renders as a link only
212
- - Images cannot be written; read returns temporary URLs valid ~24 hours
212
+ - Images are downloaded to `~/.feishu-docs/images/` with 30-day cache. Image write is not supported.
213
+ - Mermaid code blocks are preserved as-is (code block, not visual diagram) — the Open API does not support creating visual "text diagram" blocks
213
214
  - Markdown conversion is lossy — use `--blocks` for lossless JSON when precision matters
214
215
  - Search requires user-level auth (run `feishu-docs login` first)