飞书 CLI 操作速查（lark-cli）

本 SKILL 沉淀 lark-cli 在 wiki/drive 迁移、复制、清理任务中的实战用法。 与 feishu-doc / feishu-wiki / feishu-drive 等 plugin skill 不同： 这里全部走 lark-cli 命令行 + user identity，适合需要跨租户/跨空间/批量操作的场景。

速查表

1. 核心认知

1.1 身份

• lark-cli 默认以 user identity 执行（--as user），调用的是已登录用户的权限。
• 这与 bot/app identity 不同：user 能看到自己可见的文档，bot 不一定能。

1.2 文档类型与 URL 映射

1.3 常见错误码

2. Wiki 节点管理

2.1 列出子节点

lark-cli wiki +node-list --space-id <space_id> --parent-node-token <parent_node_token>

• 默认返回 50 条，data.has_more 为 true 时需用 --page-token 翻页。
• 若不给 --parent-node-token，则列出空间根节点。

2.2 获取节点详情

lark-cli wiki +node-get --node-token https://<tenant>.feishu.cn/wiki/<token>

返回关键字段：

• node_token：wiki 节点标识
• obj_token：底层文档/文件 token
• obj_type：底层类型（docx/file/sheet 等）
• parent_node_token：父节点
• space_id：所属空间
• title：标题

2.3 创建子节点

lark-cli wiki +node-create --parent-node-token <parent_token> --title "标题" --obj-type docx

--obj-type 可选：docx（默认）、sheet、bitable、mindnote、file、doc、slides。

2.4 删除节点

lark-cli wiki +node-delete --node-token https://<tenant>.feishu.cn/wiki/<token> --yes

关键点：

• 传完整 URL，CLI 自动推断 obj_type=wiki。
• 必须加 --yes。
• 不要传 --obj-type，否则会报类型冲突。
• 删除是异步任务，CLI 会自动轮询到完成。

2.5 复制 wiki 节点（同空间）

lark-cli wiki +node-copy \
  --node-token https://<tenant>.feishu.cn/wiki/<token> \
  --target-parent-node-token <parent_token> \
  --space-id <source_space_id> \
  --yes

限制： 仅适用于同 wiki 空间内且 user 有权限的节点。跨租户/外部文档通常失败。

2.6 移动 wiki 节点

lark-cli wiki +move --node-token <node_token> \
  --target-parent-token <new_parent_token> \
  --target-space-id <space_id>

3. Drive 文件操作

3.1 获取 My Space 根目录 folder_token

lark-cli api GET /open-apis/drive/explorer/v2/root_folder/meta --as user

响应：data.token 就是根目录 folder_token。

3.2 复制文件

lark-cli api POST /open-apis/drive/v1/files/<file_token>/copy \
  --as user \
  --data '{"name":"副本标题","type":"docx","folder_token":"<root_folder_token>"}'

请求体字段：

• name：新文件名（必填，最长 256 字节）
• type：源文件类型（必填）。注意表格是 sheet，不是 sheets。
• folder_token：目标文件夹 token（必填，用根目录 token 即可）

成功返回： data.file.token（新文件 token）、type、url。

3.3 将 drive 文件移入 wiki

lark-cli wiki +move --obj-token <new_file_token> --obj-type <type> \
  --target-space-id <space_id> --target-parent-token <parent_wiki_token>

--obj-type 与复制时返回的 type 一致：docx、doc、sheet、file、slides 等。

这是把 drive 副本挂到 wiki 主节点下的标准路径。

3.4 导入本地文件为云文档

lark-cli drive +import \
  --file <local.md或.docx> \
  --type docx \
  --name "标题" \
  --folder-token <root_folder_token>

要点：

• 支持 .md 直接导入为 docx，文字和基本结构保留。
• 复杂格式（高级表格、嵌入块）可能损失。
• 导入成功返回 token；之后用 wiki +move 移入 wiki。

3.5 导出云文档到本地

lark-cli drive +export \
  --token <file_token> \
  --doc-type docx \
  --file-extension docx \
  --output-dir .

限制： 需要导出权限。无权限时报 1069902 no permission。

3.6 列出文件夹内容

lark-cli drive files list --folder-token <folder_token>

根目录可省略 --folder-token。

4. 典型迁移场景

场景 1：把外部/跨租户 docx 复制到自己的 wiki

判断： 先尝试 API copy。

# 1. copy 到 My Space 根目录
lark-cli api POST /open-apis/drive/v1/files/<src_token>/copy \
  --as user --data '{"name":"副本","type":"docx","folder_token":"<root>"}'

# 2. 拿到新 token 后移入 wiki
lark-cli wiki +move --obj-token <new_token> --obj-type docx \
  --target-space-id <space_id> --target-parent-token <parent_wiki_token>

• 成功 → 完成。
• 失败 1061004 forbidden → 转场景 3。
• 失败 1770032 forBidden / 无读取权限 → 跳过，记录。

场景 2：把 file（PPT/PDF 等）复制到自己的 wiki

与场景 1 相同，只是 type 用 file。

lark-cli api POST /open-apis/drive/v1/files/<src_token>/copy \
  --as user --data '{"name":"副本.pptx","type":"file","folder_token":"<root>"}'

lark-cli wiki +move --obj-token <new_token> --obj-type file \
  --target-space-id <space_id> --target-parent-token <parent_wiki_token>

场景 3：无 copy 权限但网页可读 → Markdown 导入

适用： API copy 返回 1061004 forbidden，但浏览器能打开文档。

# 1. 抓取为 Markdown
node scripts/fetch-feishu-doc.js "https://<tenant>.feishu.cn/docx/<token>" "tmp/out.md"

# 2. 导入为 docx
lark-cli drive +import --file tmp/out.md --type docx --name "标题" --folder-token <root>

# 3. 移入 wiki
lark-cli wiki +move --obj-token <new_token> --obj-type docx \
  --target-space-id <space_id> --target-parent-token <parent_wiki_token>

场景 4：旧版 doc 的处理

旧版 doc 在飞书中逐步淘汰，API 支持有限：

• lark-cli docs +fetch --api-version v2 不支持旧版 doc。
• drive file copy 对旧版 doc 可能返回 1061004 forbidden 或 3380002 unsupported。
• drive +export 可能可用，也可能报 1069902 no permission。

建议流程：

1. 先尝试 drive file copy（type=doc）。
2. 若失败，尝试 drive +export --doc-type doc --file-extension docx。
3. 若仍失败且网页可读，用 fetch-feishu-doc.js 抓取 Markdown，再走场景 3。
4. 若网页也无权限，跳过。

场景 5：表格 sheet 的处理

复制时 type 必须是 sheet：

lark-cli api POST /open-apis/drive/v1/files/<sheet_token>/copy \
  --as user --data '{"name":"副本","type":"sheet","folder_token":"<root>"}'

lark-cli wiki +move --obj-token <new_token> --obj-type sheet \
  --target-space-id <space_id> --target-parent-token <parent_wiki_token>

注意： 不要写成 sheets，否则会报 99992402 field validation failed。

场景 6：批量清空 wiki 主节点下所有子节点

import subprocess, json

with open('children.json', 'r', encoding='utf-8') as f:
    nodes = json.load(f)['data']['nodes']

for n in nodes:
    url = f"https://<tenant>.feishu.cn/wiki/{n['node_token']}"
    subprocess.run([
        'lark-cli.cmd', 'wiki', '+node-delete',
        '--node-token', url, '--yes'
    ])

要点：

• 传 URL，不传 --obj-type。
• 删除是异步的，CLI 会自动轮询，但批量时建议 sleep 0.3s 避免 QPS 限制。

场景 7：批量复制 + 移入 wiki

import subprocess, json, time

ROOT = '<root_folder_token>'
SPACE = '<space_id>'
PARENT = '<parent_wiki_token>'

for src in sources:
    req = {'name': src['title'], 'type': src['type'], 'folder_token': ROOT}

    # copy
    r = subprocess.run([
        'lark-cli.cmd', 'api', 'POST',
        f'/open-apis/drive/v1/files/{src["token"]}/copy',
        '--as', 'user',
        '--data', json.dumps(req, ensure_ascii=False)
    ], capture_output=True, text=True, encoding='utf-8')

    copy_data = json.loads(r.stdout)
    if copy_data.get('code') == 0:
        new_token = copy_data['data']['file']['token']
        new_type = copy_data['data']['file']['type']

        # move to wiki
        subprocess.run([
            'lark-cli.cmd', 'wiki', '+move',
            '--obj-token', new_token,
            '--obj-type', new_type,
            '--target-space-id', SPACE,
            '--target-parent-token', PARENT
        ])
    time.sleep(0.3)

5. 诊断清单

遇到失败时按顺序检查：

1. token 类型对不对？ doc 用 /doc/ URL，新版 docx 用 /docx/，wiki 用 /wiki/。
2. CLI 命令参数是否冲突？ wiki +node-delete 传 URL 时不要同时传 --obj-type。
3. 是否加了 --yes？ 高风险写操作需要确认。
4. 是 user 身份还是 bot 身份？ 默认 user，明确需要 bot 时才 --as bot。
5. 目标 folder_token 对不对？ wiki 主节点不是 folder，copy 时先放到 My Space 根目录再 move。
6. 表格 type 是不是写成了 sheets？ 应该是 sheet。
7. 外部文档/跨租户？ API copy 通常 forbidden，转场景 3。
8. 旧版 doc 是否走了新版 API？ 检查 --api-version 或 --doc-type。
9. 请求体 JSON 是否合法？ 中文标题需确保编码正确。
10. 是否服务端临时错误？ 131001 时重试。

6. 浏览器自动化兜底

当 API 和导出都不可用，但文档在网页上可读时，可启动带远程调试端口的 Chrome/Edge，用 Playwright 连接：

& "C:\Program Files\Google\Chrome\Application\chrome.exe" "--remote-debugging-port=9222"

const { chromium } = require('playwright');
const browser = await chromium.connectOverCDP('http://127.0.0.1:9222');

用途：

• 检测文档网页可读性
• 提取可见文本/HTML（作为 Markdown 素材）
• 触发网页上的"创建副本"按钮（如果有）

限制： 需要用户已登录飞书；无权限页面仍无法读取。

7. 相关脚本与工具

• scripts/fetch-feishu-doc.js：抓取 docx/wiki 为 Markdown
• lark-cli drive +import：把 Markdown/本地 docx 导入为云文档
• lark-cli wiki +move：把 drive 云文档挂到 wiki 下
• lark-cli wiki +node-delete：删除 wiki 节点
• lark-cli api：直接调用飞书 Open API

8. 版本与更新

• 当前 lark-cli 版本：1.0.46（有更新提示 1.0.59）。
• 新版本中部分命令参数可能变化，执行前可先 lark-cli <command> --help 确认。