Feishu Doc

Feishu Doc — 飞书文档创建与管理（v2）

功能概述

使用 lark-cli docs v2 API + Lark XML 格式创建/编辑飞书文档，支持 50+ 种 block 类型，彻底解决旧 REST API 仅支持 4 种 block 的限制。

核心能力

1. 知识库检索：docs +search 全文搜索，判断主题是否已存在
2. 创建文档：docs +create --api-version v2 --doc-format xml 一步创建并写入内容
3. 编辑文档：docs +update 精准局部编辑（str_replace / block_insert_after / append 等）
4. 知识库归档：--parent-token 直接创建到知识库指定分类下
5. 图片插入：docs +media-insert 插入本地图片/文件
6. 图表支持：<whiteboard type="mermaid"> 内嵌 Mermaid/PlantUML/SVG 图表
7. 全 block 类型：表格、列表、代码块、引用、分割线、高亮卡片、待办清单、分栏等
8. 评论驱动修订：读取文档评论→AI 解析修改意图→精准编辑文档→回复评论告知结果 🔥
9. 文档推送：用户文档先发审阅再归档（两步流程）；自动化采集产出可直接推送变更摘要
10. PRD 需求对齐分析：原始 PRD + 会议转写/纪要 → 结构化差异对照文档（已对齐/差异/新增）— 详见 references/prd-diff-methodology.md
11. 非 docx 文件访问：Wiki 节点包裹的 PDF/MD/TXT 文件通过 Drive API 下载读取 — 详见 references/wiki-file-access.md

认证

CLI v2 已配置完成（lark-cli config init --app-id cli_aa9ead14c2641cc3 --app-secret-stdin），每次命令自动处理 token，无需手动刷新。

# 验证配置
lark-cli config show

身份选择：

• --as bot（默认）：应用身份，可创建文档/发消息
• --as user：用户身份，需 lark-cli auth login（可访问个人数据）

知识库信息

分类父节点（用于 --parent-token）

知识库已于 2026-06-01 重组为 4 一级分类 + 21 子类。一级分类用于 --parent-token，子分类 node_token 用于精确定位。

子分类 node_token（用于精确创建）：

特殊文档 token

Lark XML 格式速查

写入内容使用 XML（HTML 子集），以下是核心标签。

块级标签

行内标签

颜色参考：red, orange, yellow, green, blue, purple, gray + light-{色} / medium-{色} 变体。

转义规则

• 标签本身不转义 — <p>内容</p> ✅，<p>内容</p> ❌
• 文本内容中：& → &，< → <，> → >
• 文件传参时可绕过转义：--content @path/to/file.xml

Markdown 模式（v2 轻量替代）

当文档以文本为主、不需要 callout/grid/checkbox/whiteboard 等高级 block 时，可以直接用 Markdown 写入，跳过 XML 转换。支持创建和更新两种场景：

创建文档（含知识库归档）：

# ⚠️ --title is DEPRECATED (lark-cli v1.0.53+). Title goes in first line of markdown content.
# Markdown content must start with: <title>文档标题</title>
# @file must be relative path from CWD — cd to file dir first
cd /tmp && lark-cli docs +create --api-version v2 --doc-format markdown \
  --content @file.md \
  --parent-token KVPTwrbOKiQMUkkUPlscaEKfnUd \
  --as bot

更新已有文档：

cd /tmp && lark-cli docs +update --api-version v2 --doc DOC_ID \
  --command overwrite --doc-format markdown \
  --content @file.md --as bot

lark-cli 自动完成 Markdown → Lark XML 转换。适用场景：工作流阶段文档（Clarify/Brief/Architect）、纯文本方案、会议纪要。

⚠️ Markdown 模式的 block 类型有限（h1-h6、p、ul/ol、table、hr、code、img），需要高级 block 时仍需 XML。

⚠️ v1 docs +create --markdown 不支持 --parent-token，文档只能创建在云空间。要归档到知识库必须用 v2 + --parent-token。

⚠️ --title 被 markdown # Title 覆盖 (2026-06-02): 当 markdown 内容以 # 标题 开头时，lark-cli 自动将文档标题设为该 heading 文本，忽略 --title 参数。后果：自动化采集场景中 YYYY-MM-DD_source_topic 格式标题被原始文章标题取代，丢失日期/来源前缀。对策：若需精确控制标题（如 travel-intel 自动化命名），使用 XML 格式或在 markdown 中省略 # 开头行，改用 --title 传标题。

⛔ 两步法陷阱（2026-06-01 定位根因 + 验证方法）

不要先用 Wiki API 创建节点，再用 docs +update 写入内容。 这是静默失败模式：

# ❌ 两步法 — 返回 ok:true 但文档内容可能为空
Step 1: lark-cli api POST /open-apis/wiki/v2/spaces/{id}/nodes → 创建节点
Step 2: lark-cli docs +update --api-version v2 --doc OBJ_TOKEN \
          --command overwrite --doc-format markdown --content @file.md --as bot
# → 返回 {"ok": true, "revision_id": N} 但实际内容写入不稳定

根因：Wiki API 创建的 docx 节点与 docs +update 的内容写入路径存在不兼容。此问题在 lark-cli v1.0.40–v1.0.44 上均存在。

正确做法：必须用一步法 — docs +create --api-version v2 --doc-format markdown 同时创建文档和写入内容：

# ✅ 一步法
cd /tmp && lark-cli docs +create --api-version v2 --doc-format markdown \
  --title "文档标题" --content @file.md \
  --parent-token PARENT_TOKEN --as bot

已验证：一步法创建的文档内容可正常回读（blocks > 0, text 完整）。

⚠️ docs +fetch 无法可靠验证文档内容（2026-06-01, updated 2026-06-06）

lark-cli docs +fetch --api-version v2 在 Wiki 节点和云空间文档上均不可靠——即使内容已成功写入（REST API 确认 blocks 存在），fetch 仍显示 Outline items: 0, Blocks: 0。2026-06-06 确认云空间文档 (docs +create 不带 --parent-token) 同样受影响，回退到 Outline items: 0。

验证命令：

# ✅ 可靠验证（Wiki + 云空间均适用）
lark-cli api GET "/open-apis/docx/v1/documents/{obj_token}/blocks/{obj_token}/children?page_size=500" --as bot 2>&1 | head -50
# 确认返回 items 数组非空即可，不依赖 fetch 的 blocks 计数

⚠️ 读取文档：工具优先级

当需要读取飞书文档内容时，按优先级尝试：

关键 pitfall 1：feishu_doc_read 在非飞书评论上下文中（如群聊、私聊）报 "Feishu client not available (not in a Feishu comment context)"。永远不要依赖它。 关键 pitfall 2：docs +fetch 对 Wiki 和云空间文档均可能返回 blocks=0 误报（见实测陷阱）。读取后如 blocks=0，不要断言文档为空——立即用 REST API blocks/children 二次验证。

# 读取（可能不可靠）
lark-cli docs +fetch --api-version v2 --doc <doc_token> --as bot

# 验证（可靠 — fetch 返回 blocks=0 时必做）
lark-cli api GET "/open-apis/docx/v1/documents/{doc_token}/blocks/{doc_token}/children?page_size=500" --as bot

⚠️ 用户不希望你让他们"补全内容"或"重新说一遍"已经在文档里的东西。先读文档，再行动。

核心工作流程

流程零：知识库检索（必须优先执行）

lark-cli docs +search --query "搜索关键词" --as user

• 命中 → 向用户确认："知识库中已存在相关文档《{标题}》，是否直接编辑？"
  • 确认编辑 → 流程二（更新已有文档）
  • 新建 → 流程一
• 未命中 → 流程一
• --as user 身份可能未配置（需 lark-cli auth login），此时回退为手动列出知识库节点匹配

⚠️ docs +search 仅支持 --as user（--as bot 报错 not supported）。在 cron/自动化环境中不可用。替代方案：lark-cli wiki +node-list --parent-node-token TOKEN --page-all --as bot 列出节点后本地过滤匹配。

流程一：创建新文档

1. 生成内容 XML 文件（写入 /tmp/doc_content.xml）
2. 创建文档：

cd /tmp && lark-cli docs +create \
  --api-version v2 \
  --doc-format xml \
  --content @doc_content.xml \
  --parent-token {{分类的 parent_node_token}} \
  --as bot

3. 从响应 JSON 提取 document_id 和 url
4. 如需插入图片，后续调用 docs +media-insert

⚠️ @file 必须是相对路径：先 cd 到文件所在目录，或用 --content - 从 stdin 传入。

⚠️ 标题创建后无法通过旧 API 修改，但 CLI v2 支持 +update --new-title。

流程二：更新已有文档

推荐模式：精准局部编辑

# 追加内容到末尾
lark-cli docs +update --api-version v2 --doc {{doc_id}} --command append \
  --content @追加内容.xml --as bot

# 替换特定文本
lark-cli docs +update --api-version v2 --doc {{doc_id}} --command str_replace \
  --pattern "旧文本" --content "新文本" --as bot

# 替换整个 block
lark-cli docs +update --api-version v2 --doc {{doc_id}} --command block_replace \
  --block-id "目标block_id" --content '<p>新内容</p>' --as bot

# 全文覆盖（谨慎使用，会丢失图片/评论）
lark-cli docs +update --api-version v2 --doc {{doc_id}} --command overwrite \
  --content @新内容.xml --as bot

获取 block ID 用于精准操作：

lark-cli docs +fetch --api-version v2 --doc {{doc_id}} --detail with-ids --as bot

流程三：图片插入

# 本地文件（必须 cd 到文件所在目录，传相对路径）
cd /path/to/dir && lark-cli docs +media-insert \
  --doc {{doc_id}} \
  --file image.png \
  --caption "图片说明" \
  --align center \
  --as bot

# 插入到指定位置（在匹配文本之前插入）
cd /path/to/dir && lark-cli docs +media-insert \
  --doc {{doc_id}} \
  --file image.png \
  --type image \
  --width 1920 \
  --align center \
  --selection-with-ellipsis "目标段落中的唯一文本" \
  --before \
  --as bot

# 网络图片（直接在 XML 中）
<img href="https://example.com/image.png" width="800" caption="说明"/>

SVG 转 PNG 嵌入飞书文档

飞书 markdown 和 Lark XML 均不支持内嵌 <svg> 标签。如需在飞书文档中嵌入 SVG 图，必须先转为 PNG：

# 步骤 1：在 venv 中安装 cairosvg（PEP 668 环境必须用 venv）
python3 -m venv /tmp/svg2png
/tmp/svg2png/bin/pip install cairosvg

# 步骤 2：转换 SVG → PNG（1920×1080 适配飞书全宽）
/tmp/svg2png/bin/python3 -c "
import cairosvg
cairosvg.svg2png(url='file.svg', write_to='output.png', output_width=1920, output_height=1080)
"

# 步骤 3：用 +media-insert 插入 PNG 到文档
cd /tmp && lark-cli docs +media-insert \
  --doc DOC_ID \
  --file output.png \
  --type image \
  --width 1920 \
  --align center \
  --as bot

注意：+media-insert 的 --file 必须是相对路径（在当前目录下），不能用绝对路径如 /tmp/file.png。务必先 cd 到文件所在目录。

SVG 转 PNG 中文字体坑

cairosvg 渲染 SVG 时，如果 SVG 中引用的字体（如 PingFang SC）在服务器上不存在，中文会变成方框（□□□）。

修复步骤：

# 1. 检查系统可用的中文字体
fc-list :lang=zh | head -5

# 2. 修改 SVG 中的 font-family 为可用字体
sed -i 's/PingFang SC, HarmonyOS Sans SC, sans-serif/Noto Sans SC, SimSun, sans-serif/g' file.svg

# 3. 移除 emoji 字符（也可能渲染为方框）
sed -i 's/🏗️ //g' file.svg

# 4. 重新转换
/tmp/svg2png/bin/python3 -c "
import cairosvg
cairosvg.svg2png(url='file.svg', write_to='output.png', output_width=1920, output_height=1080)
"

验证：转换后 PNG 文件大小显著增加（从 ~47KB 跳到 ~230KB）意味着字体正确渲染。方框渲染时文件很小因为只有空框路径。也可用 understand_image 工具目视检查。

替换已存在的图片块

lark-cli docs +media-upload 只上传文件获取 token，不会更新已有的图片块。要替换文档中已有图片：

# 步骤 1：上传新图片获取 file_token
cd /tmp && lark-cli docs +media-upload \
  --doc-id DOC_ID \
  --parent-node BLOCK_ID \
  --parent-type docx_image \
  --file new_image.png \
  --as bot
# 返回 {"file_token": "NEW_TOKEN_xxx"}

# 步骤 2：用 PATCH API 替换图片块中的 token
lark-cli api PATCH "/open-apis/docx/v1/documents/DOC_ID/blocks/BLOCK_ID" \
  --data '{"replace_image":{"token":"NEW_TOKEN_xxx"}}' \
  --as bot

BLOCK_ID 可通过 lark-cli docs +fetch --api-version v2 --doc DOC_ID --detail with-ids --as bot 获取，或从 +media-insert 的返回值中提取。替换后 document_revision_id 会递增。

流程四：图表插入（Mermaid / PlantUML）

方式一：直接嵌入 XML（推荐）

<whiteboard type="mermaid">
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
</whiteboard>

方式二：创建空白画板后通过 +whiteboard-update 写入

先创建空白画板：

<whiteboard type="blank"></whiteboard>

再更新画板内容：

lark-cli docs +whiteboard-update \
  --whiteboard-token {{board_token}} \
  --input_format mermaid \
  --source 'graph TD; A-->B;' \
  --as bot

从 docs +create 或 +update 的返回值 document.new_blocks 中获取 block_token 作为 --whiteboard-token。

流程五：推送给用户（★ 先发再审，不要急着归档）

用户文档（非自动化产物）的两步流程：

1. 创建文档 — 正常 docs +create --parent-token 创建到知识库
2. 发链接给用户审阅 — 用 send_message 把文档链接发给用户，不要在此时宣称"已归档"或"已完成"。文案示例：「模版已生成，你看看结构有没有要调整的：[链接]」
3. 等用户确认 — 用户审阅后可能要求修改（改结构、增减字段、换分类等）。修改完再等待确认
4. 用户认可后才视为定稿 — 此时可以正常推送变更摘要

⚠️ 禁止行为：不要在用户审阅前就推送「文档已创建到知识库 XX 分类」——用户反馈"不要着急入库，你先发给我"。先发链接，等审阅通过再说归档的事。

自动化情报采集（cron 产出）的推送流程：

流程六：评论驱动修订（@hermes 自动触发）🔥

核心理念：用户/客户在飞书文档中添加评论，只要有一条评论包含 @hermes，Hermes 自动读取全部评论并处理——无需用户额外通知。

6.1 触发机制

关键变更：当检测到任何评论中有 @hermes，Hermes 处理的是该文档的全部未解决评论，不是仅限 @hermes 那条。这样客户只需在一条评论 @hermes，所有意见都被处理。

6.2 读取评论（注意嵌套结构）

评论文本不在 rich_text 字段，而在 reply_list.replies[*].content.elements[*].text_run.text：

for item in api_response['data']['items']:
    cid = item['comment_id']
    # 🔑 文本在嵌套结构中，不在 flat rich_text
    replies = item.get('reply_list', {}).get('replies', [])
    if replies:
        elements = replies[0].get('content', {}).get('elements', [])
        text = ''.join(e.get('text_run', {}).get('text', '') for e in elements)
    else:
        text = ''
    
    has_hermes = '@hermes' in text
    unresolved = not item['is_solved']

6.3 细颗粒度意图识别

不再笼统分类，精确到操作级别：

6.4 执行修订 + 回复评论

1. feishu_drive_list_comments → 获取评论，提取文本（注意嵌套结构）
2. 检测 @hermes 触发器 → 若存在，处理全部未解决评论
3. 逐条解析评论 → 精确匹配意图（用上表）
4. lark-cli docs +update → 精准 str_replace/append
5. 回复评论：feishu_drive_reply_comment → 告知修改结果

回复评论格式（注意 reply API 需要嵌套结构）：

# 回复评论的正确结构
reply_body = {"reply_list": {"replies": [{
    "content": {"elements": [{"type": "text_run", "text_run": {"text": "回复内容"}}]}
}]}}
# POST /open-apis/drive/v1/files/{doc_token}/comments/{comment_id}/replies

回复模板：

• ✅ "已修改：KOL预算从20万调整为15万，物料制作增加至15万"
• ⚠️ "已按理解为'删除整段XX内容'执行，如有误请告知"
• 🤔 "您的意思是[理解]，请确认后修改"
• ❌ "此修改需人工处理：[原因]"

6.5 批量处理策略

comments = list_comments(file_token=DOC)
if not any("@hermes" in c.text for c in comments):
    return  # 无 @hermes 触发器，跳过

for c in comments:
    if c.is_solved:
        continue
    
    intent = parse_intent(c.text)  # 用 6.3 细颗粒度匹配
    if intent.confidence == "high":
        execute_revision(DOC, intent)
        reply_comment(c.id, f"✅ 已修改：{intent.summary}")
    elif intent.confidence == "medium":
        execute_revision(DOC, intent)
        reply_comment(c.id, f"⚠️ 已按理解修改：{intent.summary}，请确认")
        notify_user(f"可能需要确认：{c.summary}")
    else:
        reply_comment(c.id, f"🤔 需要更多信息才能修改：{intent.reason}")
        notify_user(f"评论需人工处理：{c.summary}")

6.6 关键约束

• 文本提取：评论在 reply_list.replies[0].content.elements[*].text_run.text，不在 rich_text
• @hermes 触发范围：检测到任意 @hermes → 处理文档全部未解决评论
• 不用 overwrite：会丢失图片/图表/未处理评论
• str_replace 精确匹配：pattern 必须与 raw_content 中的文本完全一致
• 评论回复 API：需要嵌套 reply_list.replies[*].content.elements 结构
• 去重：同一位置的多次 str_replace 可能冲突，按评论顺序执行
• 清理测试：测试后删除测试文档

Markdown → Lark XML 转换规则

当用户提供 Markdown 格式的内容时，按以下规则转换为 Lark XML：

⚠️ 不再需要降级处理。旧版中表格→文本行、代码块→普通文本、列表→文本等降级策略全部废弃。

文档创作规范（CRITICAL — 每次生成内容前必读）

文档命名规范 ★

两类场景，两套规则：

原则：用户对话中产出的文档是给人看的——干净、直接、一眼知道内容。自动化采集的文档是给系统追溯的——需要时间戳和来源标记方便排序和审计。不可混淆：不要把机器格式强加给用户文档，也不要把无日期标题用于审计流。

自动化标题生成规则

当文档属于自动化情报采集（如 travel-intel L1a/L1b/L2/L3），使用以下规则生成标题：

1. 前缀 日期_来源_（约 18-22 字符），主题片段 ≤ 40 字符，总长 ≤ 60 字符
2. 去除控制字符/换行/emoji，保留中英文/数字/基本标点
3. 在自然断点截断（句号/逗号/空格），不断在词中
4. 兜底：标题为空/过短时使用搜索关键词替代
5. 过长/含特殊字符的标题会被飞书 API 静默拒绝→回退默认名"无标题"

核心原则

1. 格式一致：所有生成的内容必须使用 Lark XML 原生标签，与飞书渲染格式完全一致。不得使用 Markdown 语法写在 <p> 内（如 <p>**加粗**</p> ❌，应写 <p><b>加粗</b></p> ✅）。
2. 类型多样：每篇文档必须使用 ≥4 种不同的 block 类型（标题不计入），禁止纯文本堆砌。
3. 读者优先：结构清晰、层次分明，关键信息在 3 秒内可定位。

强制多样性规则

文档骨架模板

每篇文档必须包含以下结构元素：

<title>精准概括文档主题</title>

<!-- 1. 开篇摘要 — callout 高亮 -->
<callout emoji="📌" background-color="light-blue" border-color="blue">
  <p><b>一句话概述本文档的核心内容和目标读者。</b></p>
</callout>

<!-- 2. 正文章节 — 每章必须混合多种 block -->
<h1>章节标题</h1>
<h2>子标题</h2>
<!-- 段落 + 列表 + 表格/图表/高亮 交替出现 -->
<p>段落内容</p>
<ul><li>要点</li></ul>
<table>...</table>

<!-- 3. 关键结论 — callout 强调 -->
<callout emoji="🎯" background-color="light-green" border-color="green">
  <p><b>核心结论</b></p>
  <ul><li>结论一</li><li>结论二</li></ul>
</callout>

<!-- 4. 待办清单 — checkbox -->
<h2>后续行动</h2>
<checkbox done="false">待办事项一</checkbox>
<checkbox done="false">待办事项二</checkbox>
</ol>

常见内容类型 → 最佳 block 映射

易读性检查清单

生成 XML 后自查：

• 能在 5 秒内扫到所有 h2 标题？
• 每段 <p> 不超过 4 行（超长则拆分或用列表）？
• 关键数字/结论是否在 <callout> 或 <b> 中突出？
• 同类信息是否已聚合为 <table> / <ul> / <ol>？
• 外部链接是否用 <bookmark> 而非 <a>？
• 是否使用了 ≥4 种 block 类型？

集成文档模式（可视化仪表盘 + 详细内容）

当文档需要同时服务"决策者快速扫读"和"执行者深度参考"时，使用双区结构：上半部分 6 模块可视化仪表盘（callout + table），下半部分完整细节。模板和约束见 references/integrated-doc-pattern.md。

钉钉文档 CP 提取

当 browser_navigate 无法渲染钉钉在线文档（SPA页面）时，可通过底层 CP 协议 JSON 直接提取文本内容。 详见 references/dingtalk-cp-extraction.md。

API 能力总结

✅ 可通过 CLI v2 完成

⛔ 用户说"有现成文档"时，先搜本地再搜Wiki

当用户提到已有文档/方案/报价时，不要直接创建新文档。按以下顺序搜寻：

1. 本地文件 — 用户指定路径（如 /tmp/xxx/、~/workspace/）或搜索 /mnt/c/Users/*/Desktop|Documents|Downloads/
2. Feishu Wiki 节点 — lark-cli wiki +node-list 搜索知识库
3. Feishu 云空间 — 用户可能分享过文档链接（feishu.cn/docx/ token）

用户反馈：「本地电脑里有的文档，不要从零开始写」——先从本地 docx/xlsx 读取原始数据，再在此基础上修订。 | 读取/回复评论 | lark-cli api GET/POST .../comments（详见 references/comments-api.md）| | 创建 Bitable 节点 | --parent-token PARENT + 后续 Bitable API | | 列出文档评论 | feishu_drive_list_comments(file_token=DOC, file_type="docx") | | 查看评论回复 | feishu_drive_list_comment_replies(file_token=DOC, comment_id=ID) | | 回复评论 | feishu_drive_reply_comment(file_token=DOC, comment_id=ID, content="回复内容") | | 添加评论 | feishu_drive_add_comment(file_token=DOC, content="评论内容") |

❌ 仍不可通过 API 完成

✅ 通过 wiki +node-create 独立创建（知识库节点）

以上 5 种类型均可作为知识库独立节点创建。其中 sheet 还可通过 XML <sheet type="blank"> 嵌入 docx。

✅ 外部内容嵌入

⚠️ <a type="url-preview"> 在 XML 中会被降级为普通链接。使用 <bookmark> 实现富媒体卡片嵌入。

错误处理

实测陷阱（2026-05-27 全量验证）

XML 多表格渲染为 callout（2026-06-10 实测）

• 触发条件：用 --doc-format xml 创建含 ≥3 个 <table> 块的文档
• 后果：部分表格被错误渲染为 callout（type 31），而非 table（type 22）。5 个表格中 3 个变成 callout，仅 2 个正确。文档视觉结构被破坏
• 根因：lark-cli v1.0.40 XML tokenizer 在处理连续表格块时存在 bug，callout 和 table 混淆
• 正确做法：表格密集的文档必须用 --doc-format markdown 创建，Markdown 模式可正确渲染所有表格
• 规则：文档含 ≥3 个表格 → 用 Markdown；≤2 个表格且需要 callout/whiteboard/grid 等高级 block → 用 XML

<source> 文件附件

• 不能用 name 属性凭空创建。<source name="报告.pdf"/> 作为独立块会报 too big file size 错误，因为缺少实际文件 token
• 正确做法：用 docs +media-insert --type file 上传本地文件；或仅在 XML 中 +update 已有 source 块时保留其 token

<img> 网络图片

• <img href="https://..." width="800" caption="说明"/> ✅ 可用
• <img> 不传 href 无法创建（需要图片 token）。本地图片用 +media-insert

<cite type="citation"> 引文

• 作为独立块时可能不渲染。建议放在 <p> 内行内使用

颜色标签回读

• docs +fetch 回读时 <span text-color="..."> 和 <callout background-color="..."> 的颜色属性可能被剥离。这是正常的 — 颜色已写入文档，仅在回读 XML 中丢失

嵌入资源自动创建

• <whiteboard type="mermaid"> → 自动创建 whiteboard block（new_blocks 中返回 block_token）
• <sheet type="blank"> → 自动创建嵌入式电子表格（new_blocks 中返回 token + sheet-id）
• 响应中的 block_token / token 可用于后续 +whiteboard-update 或 Sheets API

@file 相对路径

• --content @/tmp/file.xml ❌ 报错 invalid file path
• 必须先 cd /tmp && lark-cli ... --content @file.xml ✅
• 或用 stdin：cat /tmp/file.xml | lark-cli ... --content -

--as user 依赖 auth login

• docs +search --as user 需要先 lark-cli auth login（OAuth 设备流）
• 未登录时回退到 Bot 身份或手动 lark-cli wiki +node-list

Shell heredoc 写入 XML 会截断内容 (2026-05-28)

• cat > /tmp/file.xml << 'XMLEOF' 写入 XML 内容时，XML 中的 <hr/> 等自闭合标签会触发 heredoc 截断，导致文件内容不完整
• 正确做法：使用 Python write_file 或 open().write() 写入 XML 文件
• 示例：with open("/tmp/file.xml", "w") as f: f.write(xml_content)
• 此问题在 shell 中静默失败，lark-cli 不会报错但文档内容为空或截断

docs +fetch 输出解析

• 输出包含状态行（如 "Running docs fetch..."）后才跟 JSON
• Python 解析时找第一个以 { 开头的行获取 JSON 体：

lines = result["output"].split("\n")
json_start = next(i for i, l in enumerate(lines) if l.strip().startswith("{"))
data = json.loads("\n".join(lines[json_start:]))

str_replace 插入 XML block（callout 等）会被扁平化为纯文本 (2026-06-03)

• 触发条件：通过 stdin 管道用 str_replace 插入 <callout>、<ol>、<whiteboard> 等 XML block，lark-cli 的 str_replace 命令将 --content 作为纯文本而非 XML 解析
• 后果：XML 标签被剥离/扁平化——<callout emoji="✅"><p>内容</p></callout> 变成 <h3><b>内容</b></h3>（被包裹到当前所在 block 的标签中），callout 的视觉结构完全丢失
• 根因：str_replace 是文本级替换，不对 content 做 XML tokenization。即使通过 stdin 传入完整 XML，它也只做字符串替换，不创建新的 XML block 结构
• 正确做法：如需在文档中插入新 XML block（callout、列表、图表等），使用以下优先级：
  1. 首选 overwrite：fetch 全文 → Python 修复所有问题 → overwrite 回写（参见下方「多变更级联修复」）
  2. 次选 append：如果只是追加到文档末尾，append 正确处理 XML
  3. 不推荐 str_replace：仅适用于纯文本替换（单行/单段），不适用于插入 XML block
• 检测：fetch 后检查目标 block 的标签结构是否完整（是否出现 <callout> 而非 <h3>）；关键标记计数是否为 1（确保无重复残留）
• 完整案例和修复脚本见 references/overwrite-rescue-pattern.md

多变更级联修复工作流 (2026-06-03)

当需要对文档做 ≥3 处分散修改，或前序 str_replace 已造成内容损坏时：

1. fetch 全文 → Python 提取 JSON 中的 document.content
2. Python 中一次性完成所有修复：
   - str.replace() 做文本级替换
   - 字符串拼接插入新 XML block
   - 正则清理重复/残留内容
3. 检查 <title> 标签——如有则移除（避免 overwrite 产生幽灵节点）
4. 写入 /tmp/fixed.xml → overwrite 回写
5. fetch 验证：检查关键标记存在且唯一

为什么不用多次 str_replace 逐个修：

• 每次 str_replace 修改 revision，前后文位置漂移
• 单次失败会留下半修复状态，后续修复更难定位
• XML block 插入会被扁平化（见上一陷阱）
• 一个 str_replace 的残留内容可能干扰下一个 str_replace 的 pattern 匹配

overwrite 安全检查：

• overwrite 前移除 <title> 标签（防止幽灵节点）
• 确认文档无内部图片（<img src="...">），否则会被截断
• 检查 result: "success" + 无 warnings
• 立即 fetch 验证关键内容完整性

str_replace 对大段文本静默失败 (2026-05-29, updated 2026-06-01)

• 触发条件：--pattern 或 --content 字符串过长（实测 ≥3700 chars 的 pattern 会失败），lark-cli 可能因命令行参数长度限制而静默失败或行为异常
• 后果：str_replace 返回 success 但文档内容未变化，或仅部分替换
• 检测方法：fetch 对比替换前后内容；若未生效，改用 overwrite（需处理 img 标签风险）
• 适用范围：str_replace 适合小范围文本替换（单行/单段/单个 block），不适合整章节替换。章节级别替换参见下方 overwrite 安全策略

stdin 管道绕过 @file XML 校验失败 (2026-06-01)

• 触发条件：str_replace --content @file.xml 且文件包含大量 XML 标签（如整个章节的逐帧脚本表格）。lark-cli 将 --content @file 的内容当作 Lark XML 解析校验，报 degrade_code=3001（XML tokenization error），result: "failed"，revision 不变。
• 根因：str_replace --content 在 @file 模式下仍然走 XML tokenizer，大量嵌套标签可能触发校验失败
• 正确做法：通过 stdin 管道传入，绕过文件级别的 XML 校验：

cat /tmp/content.txt | lark-cli docs +update --api-version v2 --doc DOC \
  --command str_replace --pattern "目标文本" --content - --as bot

• 文件扩展名用 .txt 而非 .xml 可进一步避免触发 XML 解析路径
• 此方法实测成功：~15KB 的脚本 XML 内容通过 stdin 管道一次性 str_replace 成功

str_replace 插入式替换会吃掉 pattern 前缀 (2026-06-01)

• 场景：想在「脚本10」之前插入「脚本1-9」，用 --pattern '<hr/><h2>脚本10' 匹配脚本10的起始标记，--content 放脚本1-9的全部内容
• 陷阱：str_replace 是完全替换——pattern 匹配的文本 <hr/><h2>脚本10 会被整个替换为 content，不会保留。结果脚本10的开头标签消失了，只剩残缺的 ｜「桨板上的朋友」｜15秒</h2>
• 检测：替换后 grep 检查所有关键标题是否完整出现
• 修复：再用一次 str_replace 把残缺标题补全。或从一开始就在 replacement 末尾包含原 pattern：

# ❌ 错误：content 不含 pattern，会丢失脚本10标题
--pattern '<hr/><h2>脚本10' --content @scripts_1_9.txt

# ✅ 正确：在 content 末尾把 pattern 原文加回去
# scripts_1_9.txt 末尾应包含 '<hr/><h2>脚本10' 作为衔接
cat scripts_with_s10_header.txt | lark-cli ... --content -

• 通用规则：任何「在 X 之前插入 Y」的场景，replacement 必须是 Y + X，不能只有 Y

overwrite 遇到内部 <img src> 标签导致内容截断 (2026-05-29)

• 触发条件：文档中包含 Feishu 内部图片引用 <img name="..." href="https://internal-api-drive-stream.feishu.cn/..." mime="image/png" scale="1.000000" src="DfdjbqxhJoTYypxCjMBcnk3fn2f"/>（带 src 属性的内部文件 token），执行 overwrite 时 lark-cli XML tokenizer 报 degrade_code=3001（"XML tokenization error"）
• 后果：①所有带 src 的内部 <img> 标签被剥离 ②第一个问题 <img> 之后的全部内容被截断丢失（静默失败，revision 仍递增）
• 检测方法：overwrite 响应中 "result": "partial_success" + "warnings": ["degrade_code=3001..."]；随后 fetch 比对内容长度和关键章节
• 修复方法：fetch 定位截断位置 → 构造丢失内容 XML（跳过问题 img 标签，用 <p><em>（照片需手动重新上传）</em></p> 占位）→ append 补回
• 预防策略：替换文档中某一章节时，优先用多个小范围 str_replace 而非一次大段 overwrite。若必须 overwrite，提前从 preserve 内容中移除所有带 src 属性的 <img> 标签。完整操作流程见 references/safe-section-replacement.md。

overwrite 含 <title> 导致 Wiki 节点幽灵残留 (2026-05-30)

• 触发条件：docs +update --command overwrite --content @file.xml 且 XML 包含 <title>新标题</title>
• 后果：lark-cli 自动重命名文档，但 Wiki 节点树中保留旧名称的幽灵条目——该条目仍显示旧标题，点开为空内容。用户看到旧标题节点以为是空文档，误判"文档未生成"
• 检测方法：wiki +node-list --parent-node-token <project> 后发现有标题相似但不同 node_token 的重复条目
• 幽灵节点特征：wiki +node-delete 对该节点报 131005 not found（底层文档已不存在，只剩树形引用）
• 正确做法：
  • 推荐：不写 <title> 标签，用 --new-title 单独设置标题
  • 备选：如需在 XML 中写 <title>，write 后立即 wiki +node-list 检查是否出现幽灵条目
• 防混淆向用户交付：提供文档直链 https://acn3kz7weyc0.feishu.cn/docx/{obj_token} 而非 Wiki 节点链接 https://acn3kz7weyc0.feishu.cn/wiki/{node_token}

feishu-wiki 联动（v4）

• 全量巡检：每日 5:00 自动扫描知识库 → 检测变动 → 自动移动分类错误文档 → 级联验证
• AI 文档总结：LLM Agent 读取文档内容 → 生成 200 字中文总结 → 缓存到 wiki_summaries.json
• 首页同步：骨架 XML（含 ##SUMMARY## 占位符）→ Agent 填充总结 → overwrite 写入首页
• 变更日志：每次变动（新增/删除/移动/更新）自动写入变更日志 docx，最新条目在最上方
• 首页 token：Y4LYd1X8Yo1Du9x9WtNcYD51nte
• 变更日志 token：LJ7RdGzVVoUX6rxmzwpcH3L0npg
• 详细操作 → 加载 feishu-wiki 技能

lark-cli api DELETE 查询参数必须用 --params 而非 URL query string (2026-06-06)

• 触发条件：lark-cli api DELETE "/path?type=docx" — 在 URL 中附加 ?type=docx 查询参数
• 后果：返回 99992402: field validation failed, "type is required"。lark-cli 在 DELETE 请求中不自动将 URL query string 传参
• 正确做法：使用 --params '{"type":"docx"}' 显式传递查询参数：

  # ✅ 正确
  lark-cli api DELETE "/open-apis/drive/v1/files/{doc_token}" --params '{"type":"docx"}' --as bot
  

• 验证：删除后 docs +fetch 返回 3380003: Document page has been deleted 确认成功

多实例文本替换（≥3 处）：用源 XML + overwrite

str_replace 仅替换首次匹配，无法处理批量同名替换（如"于袁天"出现 9 次需 9 次 API 调用）。高效方案：

# 1. 保留文档的原始 XML 源文件（创建时用的 .xml）
# 2. sed 一次性替换所有实例
sed -i 's/旧文本/新文本/g' /tmp/doc_source.xml
# 3. overwrite 回写
cd /tmp && lark-cli docs +update --api-version v2 --doc DOC_ID \
  --command overwrite --content @doc_source.xml --as bot

前提：必须有原始 XML 源文件。如果丢失，docs +fetch 不可靠（Wiki 文档 blocks=0），需用 REST API 逐 block 重建 XML，代价大。

docs +fetch 云空间文档同样 blocks=0 (2026-06-06)

此前已记录 Wiki 文档的 docs +fetch blocks=0 误报。2026-06-06 确认：不带 --parent-token 创建的云空间文档同样受影响，fetch 返回 Outline items: 0, Blocks: 0 但 REST API 确认内容存在（callout、heading1、divider 等 block 正常）。

对策不变：始终用 GET /docx/v1/documents/{id}/blocks/{id}/children 做内容验证，不依赖 fetch。

保留源 XML 时的批量文本替换：sed + overwrite (2026-06-06)

当需要对文档做全量文本替换（如人名/术语统一修正），且仍持有创建时的源 XML 文件时，最快路径：

# 1. 直接在源 XML 上替换
sed -i 's/旧文本/新文本/g' /tmp/source.xml

# 2. overwrite 回写
cd /tmp && lark-cli docs +update --api-version v2 --doc DOC_ID \
  --command overwrite --content @source.xml --as bot

优势：绕过了 docs +fetch blocks=0 的不可靠问题，也绕过了 str_replace 每次只替换一个匹配的限制。本次会话中用此法一次性替换了 3 篇文档共 20 处"于袁天→夏与"，每篇仅 1 次 API 调用。

前提：源 XML 没有 <img src="..."> 内部图片标签（否则 overwrite 会截断，见 overwrite 陷阱）。会议纪要、审议文档等纯文本+callout+table 的文档完全安全。

对比 str_replace：str_replace 每次只替换一个匹配，20 处需 20 次调用，且中间可能因 revision 变化导致定位偏移。sed+overwrite 是一步完成的原子操作。

• 触发条件：先用 v1 docs +create 创建文档到云空间，再试图通过 POST /open-apis/wiki/v2/spaces/{space_id}/nodes 的 origin_node_token 将已有文档挂载到知识库
• 后果：API 返回成功 code:0，但在知识库中创建的是一个全新的空文档（obj_token 与原始文档不同），不是对已有文档的引用。原始文档仍在云空间中，内容未迁移
• 检测方法：用新 obj_token 执行 docs +fetch → outline 为空
• 正确做法：创建时直接用 v2 --api-version v2 --doc-format markdown --parent-token TOKEN，一步到位写入知识库。如果已经在云空间创建了文档，用 docs +fetch 取回内容后 overwrite 到知识库文档中
• 清理：空节点需用 lark-cli wiki +node-delete --node-token <NODE> --obj-type wiki --yes 删除

知识库 nodes API 对所有 parent 返回相同根节点列表 (2026-06-01)

• 触发条件：GET /nodes?parent_node_token=<ANY_CLASSIFICATION_SUBNODE> — 无论传哪个子分类的 node_token，API 始终返回相同的 6 个根级节点（首页、最近更新、运营管理、内容素材、咨询洞察、AI Native 工作流）
• 影响：无法通过 REST API 验证文档是否出现在正确的子分类下
• 根因：此知识库在 2026-06-01 重组过分类结构，API 的父子关系映射可能未同步更新。飞书 UI 中的树形结构正常，仅 API 查询异常
• 对策：创建时直接指定正确的 --parent-token（CLI v2 已验证可正确归档到子分类），信任创建行为，不依赖 API node-list 做归档验证

批量文本替换 → overwrite 优于多次 str_replace

当需要对文档做多处相同文本替换时（如全文替换人名、地名），逐次 str_replace 需要 N 次 API 调用且容易遗漏。更高效的方式：

# 前提：你有创建该文档时使用的原始 XML 文件
sed -i 's/旧文本/新文本/g' original.xml
lark-cli docs +update --api-version v2 --doc DOC_ID --command overwrite --content @original.xml --as bot

一次 overwrite 替代 N 次 str_replace。适用于：全文人名替换、地名修正、统一术语等场景。注意 overwrite 会丢失图片/评论，仅当文档无图片时使用。

子分类 node_token 可能失效，须做回退 (2026-06-03)

• 触发条件：创建文档时使用子分类 node_token（如 FB6DwZlXhijL38kz0J6cy8gznhd 业务规范）作为 --parent-token，返回 3380002: Parent node not found
• 根因：知识库 2026-06-01 重组后，子分类 token 可能已变化。表中列出的子分类 token 是重组前记录的值，部分已失效。飞书 API 的 nodes 端点无法返回子节点列表（见上一陷阱），无法通过 API 发现新 token
• 已确认有效的 token（2026-06-03 验证）：
  • ✅ W57jwRHJYimFRskVK2VcCQjfnXf — 运营管理（一级分类）
  • ✅ XMVrw88PsijL6Ek4S2sc1B5enuh — 内容素材（一级分类）
  • ✅ UF7Cw5w2WiHGfjkKVvBcxj8Hnib — 咨询洞察（一级分类）
  • ✅ J4EewYIT2ieFuwkRWbxcgWbFnhe — AI Native 工作流（一级分类）
• ✅ GI1cwlAUviHXIqk291vcjNxvnGb — 会议纪要（子分类）— 已确认有效 (2026-06-06)，连续两次创建成功
• ✅ J9h6wJgO4ij7NjkXNTCc6mNDnwf — 文案素材（子分类）— 已确认有效 (2026-06-09)\n- ✅ HrJXwlne7ioywnkDpAlc6p08ngV — 产品研发（子分类）— 已确认有效 (2026-06-08)
• ✅ J9h6wJgO4ij7NjkXNTCc6mNDnwf — 文案素材（子分类）— 已确认有效 (2026-06-09)
• ✅ PAVdwkNpNiedvfkPLIec1gK7nAU — 团队管理（子分类）— 已确认有效 (2026-06-08)
• ✅ JIKCw1IXAi5ZYxkBKW0cYEuanGF — 运营策略（子分类）— 已确认有效 (2026-06-08)
• ✅ NHaQwmHNliUnSekHDOmcPPGfn8f — 任务复盘（子分类）— 已确认有效 (2026-06-08)
• ✅ J9h6wJgO4ij7NjkXNTCc6mNDnwf — 文案素材（子分类）— 已确认有效 (2026-06-09)
• ❌ FB6DwZlXhijL38kz0J6cy8gznhd — 业务规范（子分类）— 3380002 失效
• ❌ V0Lhwl7KYiWYDDk1vCncv2GhnYf — 行业资讯（子分类）— 3380002 已确认失效 (2026-06-04)
• ❌ EAMYw1CPoipVWtkObbtcR2oDnNc — 竞品动态（子分类）— 3380002 已确认失效 (2026-06-04)
• ✅ KVPTwrbOKiQMUkkUPlscaEKfnUd — 方案计划（子分类）— 已确认有效 (2026-06-10)，本次会话成功创建文档
• ⚠️ 其余子分类 token — 未逐一验证，可能部分失效
• 回退策略：
  1. 优先尝试子分类 token → 如返回 3380002，立即回退到对应的一级分类 token
  2. 一级分类 token（上述 4 个）已确认稳定有效，文档会创建在对应大类下
  3. 事后通知用户文档在一级分类下，需手动移至子分类（或等待 feishu-wiki 自动巡检移动）
• 不必浪费时间逐个验证子分类 token：直接尝试目标子分类，失败即回退一级分类。此策略不会阻塞文档产出

常用命令速查