From 54c3fd3fb86ea82dad8aa4591a4dd5acfc07e088 Mon Sep 17 00:00:00 2001 From: baiqing Date: Thu, 23 Apr 2026 11:02:13 +0800 Subject: [PATCH 1/6] docs(lark-doc): document read-only block types that create/update silently skip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents hit a repeatable gotcha where docs +create / docs +update returns success but the block is silently dropped on the server side — e.g. sync blocks used for weekly-report team headers, or AddOns that fetch-doc only represents as '' comments. Because the API answers code=0 success=true, nothing in the tooling chain currently surfaces the drop. Add references/lark-doc-block-type-limits.md with the known read-only block inventory, the fetch-time marker, signals for detecting a silent drop, and suggested workarounds (manual UI step vs avoiding the block in generated markdown). Link it from the docs SKILL.md so Agents see it before writing markdown. --- skills/lark-doc/SKILL.md | 6 +++ .../references/lark-doc-block-type-limits.md | 42 +++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 skills/lark-doc/references/lark-doc-block-type-limits.md diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 3bdad9d8f..7e6250037 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -66,3 +66,9 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs + [flags]`） | [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. | | [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) | | [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. | + +## Block type 写入限制 + +`docs +create` / `docs +update` 并非支持全部 block 类型。引用同步块（``）、部分 AddOns 等是 **read-only**，API 返回成功但 block 不会真的写入。撰写 markdown 前请先读： + +- [`references/lark-doc-block-type-limits.md`](references/lark-doc-block-type-limits.md) — 已知只读 block 清单、`` 占位符来源与推荐处理方式。 diff --git a/skills/lark-doc/references/lark-doc-block-type-limits.md b/skills/lark-doc/references/lark-doc-block-type-limits.md new file mode 100644 index 000000000..ff375e996 --- /dev/null +++ b/skills/lark-doc/references/lark-doc-block-type-limits.md @@ -0,0 +1,42 @@ +# Block type limits (read-only blocks) + +> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 `docs +create` / `docs +update` 的调用方式。 + +`docs +create` / `docs +update` 底层的 `create-doc` MCP 工具**不支持部分 block 类型**。当 markdown 中出现这些块时，服务端会静默跳过或以 HTML 注释兜底，**API 返回成功但 block 不会真的写入**，是 AI Agent 经常踩坑的盲区。 + +本文档列出已知的只读 / 受限 block 类型，供 Agent 在撰写 markdown 前自检。 + +## 已知只读 block（API 只支持 fetch，不支持 create / update） + +| 块类型 | Markdown / HTML 形式 | 现象 | 推荐做法 | +|--------|---------------------|------|---------| +| 引用同步块 | `...` | 静默跳过；API 返回成功但文档中不会出现此块 | 通过 UI 手动绑定；或在 skill 中把"同步块占位"作为单独的手工步骤记录 | +| 源同步块 | `...` | 同上 | 同上 | + +## 会产生 `` 占位符的块 + +`docs +fetch` 导出时遇到无法序列化成 markdown 的原生 block，会以 `` 形式占位（例如 block type 53）。这是 **`fetch-doc` 的已知限制**，典型触发者包括： + +- 部分 **文档小组件（AddOns）** — `` 子集 +- **Wiki SubPageList** — `` 在 wiki 节点以外的上下文 +- **议程（Agenda）** 的部分子块 + +如果 round-trip 回灌时看到这些注释，**不要直接把注释当成 markdown 源再 create** — `create-doc` 不会把注释解析成 block。需要人工在 UI 中重建，或寻找对应的 OpenAPI 专用接口。 + +## 定位"该块没进去"的信号 + +1. `docs +create` / `docs +update` 响应 `code=0`、`success=true`，UI 上却找不到预期 block +2. 随后 `docs +fetch` 拿回来的 markdown 里该块消失，或变成 `` +3. round-trip diff 多出一段 `+` / `-` + +出现上述任一信号时，优先怀疑 block 类型在表格中。 + +## 对 AI Agent 的影响 + +- **周报 / 文档模板场景**：首行 `reference-synced` 团队介绍块必须通过 UI 手动补上；skill 里应显式记录"绑定同步块"是手工步骤，不要用 markdown 伪造。 +- **文档迁移 / round-trip**：跨文档迁移同步块会在源文档失权后出现占位 / 丢失，属于预期行为，不是 bug。 +- **生成式内容**：Agent 生成 markdown 时应避免主动插入 `` 等标签（生成出来也写不进去）。 + +## 相关 MCP 层记录 + +`fetch-doc` / `create-doc` 的其它接口层限制汇总见 [lark-cli-dev skill](../../lark-cli-dev/SKILL.md) 的「已知 MCP 层限制」章节，涵盖有序列表编号重置、callout emoji 误配、代码块嵌套围栏等问题。 From 0cd0f5243ededbe1114ba8d5a2e79b41ae2984d6 Mon Sep 17 00:00:00 2001 From: baiqing Date: Thu, 23 Apr 2026 11:31:40 +0800 Subject: [PATCH 2/6] docs(lark-doc): separate write-path vs fetch-path behavior in block-type limits CodeRabbit noted the opening paragraph could be read as if create-doc itself emits the '' comment, when in fact that placeholder is a fetch-doc rendering artifact for blocks it cannot serialize back to markdown. Split the sentence so the two paths are clearly separate: write-path silently drops the block; fetch-path surfaces the placeholder comment. --- skills/lark-doc/references/lark-doc-block-type-limits.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/skills/lark-doc/references/lark-doc-block-type-limits.md b/skills/lark-doc/references/lark-doc-block-type-limits.md index ff375e996..f68a83a66 100644 --- a/skills/lark-doc/references/lark-doc-block-type-limits.md +++ b/skills/lark-doc/references/lark-doc-block-type-limits.md @@ -2,7 +2,12 @@ > **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 `docs +create` / `docs +update` 的调用方式。 -`docs +create` / `docs +update` 底层的 `create-doc` MCP 工具**不支持部分 block 类型**。当 markdown 中出现这些块时，服务端会静默跳过或以 HTML 注释兜底，**API 返回成功但 block 不会真的写入**，是 AI Agent 经常踩坑的盲区。 +`docs +create` / `docs +update` 底层的 `create-doc` MCP 工具**不支持部分 block 类型**。具体行为分为两条路径： + +- **写入路径（create / update）**：markdown 中出现这些 block 时，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进文档。 +- **读取路径（`docs +fetch` 导出）**：同类无法稳定序列化成 markdown 的原生 block，会以占位注释 `` 呈现。 + +两条路径都不会抛错，是 AI Agent 经常踩坑的盲区。 本文档列出已知的只读 / 受限 block 类型，供 Agent 在撰写 markdown 前自检。 From 245a0a5ea0128c80d9b73f3a7e29d46c01121693 Mon Sep 17 00:00:00 2001 From: baiqing Date: Tue, 28 Apr 2026 16:08:47 +0800 Subject: [PATCH 3/6] docs(lark-doc): align block-type-limits with lark-doc-xml.md (snake_case + complete inventory) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address fangshuyu-768's three review notes on PR #620: 1. Tag naming: switch from kebab-case / to snake_case / , matching the canonical form already used in skills/lark-doc/SKILL.md and lark-doc-xml.md. Agents copying tags from this doc were producing forms the create/update path doesn't recognize. 2. Inventory: add , , and alongside the two sync blocks. lark-doc-xml.md:48 already lists all five as 'not creatable, only movable'; this doc is now the single source of truth for the same set with deeper guidance on each. 3. Phrasing: rewrite the opening so the reader doesn't conclude these blocks 'never appear in documents'. They do — fetch-doc serializes them, block_move_after relocates them — they just can't be created or updated. The new structure splits create/update vs fetch vs move semantics explicitly. Also update SKILL.md's 'Block type 写入限制' callout to use the same snake_case names so the skill index agrees with the reference doc. --- skills/lark-doc/SKILL.md | 4 +- .../references/lark-doc-block-type-limits.md | 40 +++++++++++-------- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 7e6250037..a359b8403 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -69,6 +69,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs + [flags]`） ## Block type 写入限制 -`docs +create` / `docs +update` 并非支持全部 block 类型。引用同步块（``）、部分 AddOns 等是 **read-only**，API 返回成功但 block 不会真的写入。撰写 markdown 前请先读： +`docs +create` / `docs +update` 并非支持全部 block 类型。`` / `` / `` / `` / `` 这五类**不可创建**，写入路径会静默跳过；但它们可以通过 fetch 读出、通过 `block_move_after` 在文档间搬动。生成内容前请先读： -- [`references/lark-doc-block-type-limits.md`](references/lark-doc-block-type-limits.md) — 已知只读 block 清单、`` 占位符来源与推荐处理方式。 +- [`references/lark-doc-block-type-limits.md`](references/lark-doc-block-type-limits.md) — 不可创建 block 清单、各自的 XML 形态、`` 占位符来源与推荐处理方式。 diff --git a/skills/lark-doc/references/lark-doc-block-type-limits.md b/skills/lark-doc/references/lark-doc-block-type-limits.md index f68a83a66..951ee9f25 100644 --- a/skills/lark-doc/references/lark-doc-block-type-limits.md +++ b/skills/lark-doc/references/lark-doc-block-type-limits.md @@ -1,22 +1,30 @@ # Block type limits (read-only blocks) -> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 `docs +create` / `docs +update` 的调用方式。 +> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 `docs +create` / `docs +update` 的调用方式，必要时再读 [`lark-doc-xml.md`](lark-doc-xml.md)（资源块语法的权威定义）。 -`docs +create` / `docs +update` 底层的 `create-doc` MCP 工具**不支持部分 block 类型**。具体行为分为两条路径： +## 概念区分（避免误读） -- **写入路径（create / update）**：markdown 中出现这些 block 时，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进文档。 -- **读取路径（`docs +fetch` 导出）**：同类无法稳定序列化成 markdown 的原生 block，会以占位注释 `` 呈现。 +`docs +create` / `docs +update` 并非支持全部 block 类型。**这些 block 在文档里 _可以存在_（通过 fetch 读出、通过 `block_move_after` 在文档之间搬动），但 _不能创建/更新_** —— 也就是说写入路径会静默跳过它们，不会抛错也不会出现在新文档中。两条路径行为如下： -两条路径都不会抛错，是 AI Agent 经常踩坑的盲区。 +- **写入路径（`docs +create` / `docs +update --command append/overwrite/...`）**：如果输入里出现这些 block 标签，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进入新文档。 +- **读取路径（`docs +fetch`）**：原文档里**已经存在**的同类 block 仍会被序列化输出（保留为对应 XML 标签或 markdown 占位）；少数飞书内部块如果无法稳定序列化成 markdown，会以 `` 形式占位呈现。 +- **跨文档移动（`docs +update --command block_move_after`）**：所有 block 都支持移动，因此这些 read-only block 可以从一篇文档搬到另一篇。`block_copy_insert_after` 也可对部分类型生效，详见 [`lark-doc-xml.md`](lark-doc-xml.md) 的「四、块级复制与移动」。 -本文档列出已知的只读 / 受限 block 类型，供 Agent 在撰写 markdown 前自检。 +简单说：**这些 block 不是"完全只读"，只是"create / update 时无法新建"**。 -## 已知只读 block（API 只支持 fetch，不支持 create / update） +## 已知不支持 create / update 的 block -| 块类型 | Markdown / HTML 形式 | 现象 | 推荐做法 | -|--------|---------------------|------|---------| -| 引用同步块 | `...` | 静默跳过；API 返回成功但文档中不会出现此块 | 通过 UI 手动绑定；或在 skill 中把"同步块占位"作为单独的手工步骤记录 | -| 源同步块 | `...` | 同上 | 同上 | +权威定义见 [`lark-doc-xml.md` §三](lark-doc-xml.md)（『不可创建，仅支持移动』）。下表汇总命名、典型 XML 形式与处理建议： + +| 块类型 | XML 标签（snake_case）| 典型形态 | 推荐处理 | +|---|---|---|---| +| 引用同步块 | `` | `` | 写入路径无效，需通过 UI 手动绑定；fetch 读出后可用 `block_move_after` 搬到目标文档 | +| 源同步块 | `` | `...内容...` | 同上 | +| 多维表格 | `` | `` | 在另一篇文档里嵌入已有 base 时，先 fetch 拿到 `` 标签，再 `block_move_after` 搬过去 | +| Base 引用 | `` | `` | 同上 | +| OKR | `` | `` | 同上 | + +> **复制限制（`block_copy_insert_after`）**：上述五类（外加 `task`）都**不支持复制**；img / source / whiteboard / sheet / chat_card 才支持复制。 ## 会产生 `` 占位符的块 @@ -32,15 +40,15 @@ 1. `docs +create` / `docs +update` 响应 `code=0`、`success=true`，UI 上却找不到预期 block 2. 随后 `docs +fetch` 拿回来的 markdown 里该块消失，或变成 `` -3. round-trip diff 多出一段 `+` / `-` +3. round-trip diff 多出一段 `+` / `-` 或类似标签 -出现上述任一信号时，优先怀疑 block 类型在表格中。 +出现上述任一信号时，优先怀疑 block 类型在上面表格中。 ## 对 AI Agent 的影响 -- **周报 / 文档模板场景**：首行 `reference-synced` 团队介绍块必须通过 UI 手动补上；skill 里应显式记录"绑定同步块"是手工步骤，不要用 markdown 伪造。 -- **文档迁移 / round-trip**：跨文档迁移同步块会在源文档失权后出现占位 / 丢失，属于预期行为，不是 bug。 -- **生成式内容**：Agent 生成 markdown 时应避免主动插入 `` 等标签（生成出来也写不进去）。 +- **周报 / 文档模板场景**：首行 `synced_reference` 团队介绍块必须通过 UI 手动补上；skill 里应显式记录"绑定同步块"是手工步骤，不要在 markdown 里伪造。 +- **文档迁移 / round-trip**：跨文档迁移同步块、bitable、okr 等优先用 `block_move_after`（搬不复制）；权限或环境变化导致引用断链时，需要人工修复。 +- **生成式内容**：Agent 从零生成时应避免主动插入 ``、``、``、`` 等标签（写不进去）；如果是从一篇旧文档迁内容到新文档，先 fetch 这些 block 再用 `block_move_after`。 ## 相关 MCP 层记录 From 12f53998f5db04fba4aa648ba05fd03d387ff943 Mon Sep 17 00:00:00 2001 From: fangshuyu Date: Thu, 30 Apr 2026 18:10:54 +0800 Subject: [PATCH 4/6] docs(lark-doc): drop dead lark-cli-dev link, deep-anchor xml.md section refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two review findings on PR #620: 1. The "相关 MCP 层记录" trailing section pointed at ../../lark-cli-dev/SKILL.md, which doesn't exist anywhere in the repo (no skill, no git history, no content matching the described "已知 MCP 层限制" topics like ordered-list renumbering / callout emoji mismatch / code fence nesting). Drop the section; if a real target ever shows up, link it from there rather than carry a phantom reference in the meantime. 2. Two cross-references to lark-doc-xml.md §三 / §四 were file-only links that landed at the top of the file. Convert them to GitHub anchor links (#三资源块 and #四块级复制与移动), matching the CJK anchor convention already in use in skills/lark-mail/references and skills/lark-base/references. Readers now jump straight to the referenced section. --- skills/lark-doc/references/lark-doc-block-type-limits.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/skills/lark-doc/references/lark-doc-block-type-limits.md b/skills/lark-doc/references/lark-doc-block-type-limits.md index 951ee9f25..c2281fdde 100644 --- a/skills/lark-doc/references/lark-doc-block-type-limits.md +++ b/skills/lark-doc/references/lark-doc-block-type-limits.md @@ -8,13 +8,13 @@ - **写入路径（`docs +create` / `docs +update --command append/overwrite/...`）**：如果输入里出现这些 block 标签，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进入新文档。 - **读取路径（`docs +fetch`）**：原文档里**已经存在**的同类 block 仍会被序列化输出（保留为对应 XML 标签或 markdown 占位）；少数飞书内部块如果无法稳定序列化成 markdown，会以 `` 形式占位呈现。 -- **跨文档移动（`docs +update --command block_move_after`）**：所有 block 都支持移动，因此这些 read-only block 可以从一篇文档搬到另一篇。`block_copy_insert_after` 也可对部分类型生效，详见 [`lark-doc-xml.md`](lark-doc-xml.md) 的「四、块级复制与移动」。 +- **跨文档移动（`docs +update --command block_move_after`）**：所有 block 都支持移动，因此这些 read-only block 可以从一篇文档搬到另一篇。`block_copy_insert_after` 也可对部分类型生效，详见 [`lark-doc-xml.md` §四 块级复制与移动](lark-doc-xml.md#四块级复制与移动)。 简单说：**这些 block 不是"完全只读"，只是"create / update 时无法新建"**。 ## 已知不支持 create / update 的 block -权威定义见 [`lark-doc-xml.md` §三](lark-doc-xml.md)（『不可创建，仅支持移动』）。下表汇总命名、典型 XML 形式与处理建议： +权威定义见 [`lark-doc-xml.md` §三 资源块](lark-doc-xml.md#三资源块)（『不可创建，仅支持移动』）。下表汇总命名、典型 XML 形式与处理建议： | 块类型 | XML 标签（snake_case）| 典型形态 | 推荐处理 | |---|---|---|---| @@ -49,7 +49,3 @@ - **周报 / 文档模板场景**：首行 `synced_reference` 团队介绍块必须通过 UI 手动补上；skill 里应显式记录"绑定同步块"是手工步骤，不要在 markdown 里伪造。 - **文档迁移 / round-trip**：跨文档迁移同步块、bitable、okr 等优先用 `block_move_after`（搬不复制）；权限或环境变化导致引用断链时，需要人工修复。 - **生成式内容**：Agent 从零生成时应避免主动插入 ``、``、``、`` 等标签（写不进去）；如果是从一篇旧文档迁内容到新文档，先 fetch 这些 block 再用 `block_move_after`。 - -## 相关 MCP 层记录 - -`fetch-doc` / `create-doc` 的其它接口层限制汇总见 [lark-cli-dev skill](../../lark-cli-dev/SKILL.md) 的「已知 MCP 层限制」章节，涵盖有序列表编号重置、callout emoji 误配、代码块嵌套围栏等问题。 From d1845a528ca37e3003d2044f7203ddc77dbb41a9 Mon Sep 17 00:00:00 2001 From: fangshuyu Date: Thu, 30 Apr 2026 18:17:24 +0800 Subject: [PATCH 5/6] docs(lark-doc): qualify placeholder as v1 fetch / markdown specific MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 5-block read-only inventory (synced_reference, synced_source, bitable, base_ref, okr) is rooted in Lark's data model and applies to both v1 MCP and v2 OpenAPI write paths — that part of the doc was already version-agnostic. The "" placeholder, however, is a serialization fallback specific to v1 MCP `fetch-doc` rendering to markdown. v2 fetch (`POST /open-apis/docs_ai/v1/documents//fetch`) defaults to XML and represents blocks structurally, so this comment form doesn't appear there. Without that qualifier, an agent reading this doc on v2 might chase a placeholder that never materializes, or worse, treat its absence as evidence the block was successfully written. Changes: - "概念区分" bullet now scopes the placeholder note to "v1 fetch + markdown" and adds a one-line v2 fetch contrast. - "会产生 ... 占位符的块" section gets a `(v1 fetch / markdown 输出)` qualifier in the heading and an explicit blockquote note about v2 behavior at the top. - Closing sentence broadens "create-doc 不会把注释解析" to "v1 / v2 写入路径都不会" so the don't-feed-comments-back-in advice survives the v2 migration. - Signal #2 in the detection list now flags the placeholder as "v1 fetch + markdown" specific and clarifies signal #1 / #3 are v1/v2 generic. --- .../references/lark-doc-block-type-limits.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/skills/lark-doc/references/lark-doc-block-type-limits.md b/skills/lark-doc/references/lark-doc-block-type-limits.md index c2281fdde..205e7b2f5 100644 --- a/skills/lark-doc/references/lark-doc-block-type-limits.md +++ b/skills/lark-doc/references/lark-doc-block-type-limits.md @@ -7,7 +7,7 @@ `docs +create` / `docs +update` 并非支持全部 block 类型。**这些 block 在文档里 _可以存在_（通过 fetch 读出、通过 `block_move_after` 在文档之间搬动），但 _不能创建/更新_** —— 也就是说写入路径会静默跳过它们，不会抛错也不会出现在新文档中。两条路径行为如下： - **写入路径（`docs +create` / `docs +update --command append/overwrite/...`）**：如果输入里出现这些 block 标签，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进入新文档。 -- **读取路径（`docs +fetch`）**：原文档里**已经存在**的同类 block 仍会被序列化输出（保留为对应 XML 标签或 markdown 占位）；少数飞书内部块如果无法稳定序列化成 markdown，会以 `` 形式占位呈现。 +- **读取路径（`docs +fetch`）**：原文档里**已经存在**的同类 block 仍会被序列化输出（保留为对应 XML 标签）；少数飞书内部块如果无法稳定序列化，**v1 fetch（MCP `fetch-doc`）+ markdown 输出**会以 `` 形式占位呈现。v2 fetch（`POST /open-apis/docs_ai/v1/documents//fetch`）默认 XML 输出，走结构化 block 表示，无此 markdown 注释占位符。 - **跨文档移动（`docs +update --command block_move_after`）**：所有 block 都支持移动，因此这些 read-only block 可以从一篇文档搬到另一篇。`block_copy_insert_after` 也可对部分类型生效，详见 [`lark-doc-xml.md` §四 块级复制与移动](lark-doc-xml.md#四块级复制与移动)。 简单说：**这些 block 不是"完全只读"，只是"create / update 时无法新建"**。 @@ -26,20 +26,22 @@ > **复制限制（`block_copy_insert_after`）**：上述五类（外加 `task`）都**不支持复制**；img / source / whiteboard / sheet / chat_card 才支持复制。 -## 会产生 `` 占位符的块 +## 会产生 `` 占位符的块（v1 fetch / markdown 输出） -`docs +fetch` 导出时遇到无法序列化成 markdown 的原生 block，会以 `` 形式占位（例如 block type 53）。这是 **`fetch-doc` 的已知限制**，典型触发者包括： +> 本节专指 **v1 MCP `fetch-doc` + markdown 输出** 的兜底行为。v2 fetch 默认 XML 输出走结构化 block 表示，不会出现此 markdown 注释形式；v2 markdown 输出的兜底未单独验证，可能与 v1 不同。 + +v1 `fetch-doc` 导出 markdown 时遇到无法稳定序列化的原生 block，会以 `` 形式占位（例如 block type 53）。典型触发者包括： - 部分 **文档小组件（AddOns）** — `` 子集 - **Wiki SubPageList** — `` 在 wiki 节点以外的上下文 - **议程（Agenda）** 的部分子块 -如果 round-trip 回灌时看到这些注释，**不要直接把注释当成 markdown 源再 create** — `create-doc` 不会把注释解析成 block。需要人工在 UI 中重建，或寻找对应的 OpenAPI 专用接口。 +如果 round-trip 回灌时看到这些注释，**不要直接把注释当成 markdown 源再 create / update** —— v1 / v2 写入路径都不会把 HTML 注释解析成 block。需要人工在 UI 中重建，或寻找对应的 OpenAPI 专用接口。 ## 定位"该块没进去"的信号 -1. `docs +create` / `docs +update` 响应 `code=0`、`success=true`，UI 上却找不到预期 block -2. 随后 `docs +fetch` 拿回来的 markdown 里该块消失，或变成 `` +1. `docs +create` / `docs +update` 响应 `code=0`、`success=true`，UI 上却找不到预期 block（v1 / v2 通用） +2. 随后 `docs +fetch` 拿回来的内容里该块消失；若用 **v1 fetch + markdown** 还可能出现 `` 注释 3. round-trip diff 多出一段 `+` / `-` 或类似标签 出现上述任一信号时，优先怀疑 block 类型在上面表格中。 From f0096903a6d34d7c05792f599fa5bb85318c788f Mon Sep 17 00:00:00 2001 From: fangshuyu Date: Thu, 30 Apr 2026 18:25:04 +0800 Subject: [PATCH 6/6] docs(lark-doc): drop v1-specific content to match the v2-only stance of lark-doc skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Main branch's `lark-doc` skill is v2-exclusive: - SKILL.md description: "使用本 skill 时，docs +create、docs +fetch、docs +update **必须携带 --api-version v2**" - lark-doc-fetch.md parameter table: `--api-version` is "固定传 v2" - A repo-wide grep across `skills/lark-doc/` for v1 / MCP / fetch-doc / create-doc / update-doc returns zero hits on main This new reference doc was reintroducing v1 vocabulary into a skill that had consciously scrubbed it. The previous attempt to "qualify the placeholder section as v1-specific" pointed in the wrong direction: adding a `(v1 fetch / markdown 输出)` watermark to a section that should not exist for this audience at all. Agents told to use --api-version v2 will never trigger the v1 MCP fetch-doc + markdown placeholder fallback, so the section was teaching defenses against a failure mode that doesn't apply. Removed: - The entire `## 会产生 占位符的块` section (heading + v1 blockquote + AddOns/SubPageList/Agenda triggers + the round-trip-don't-feed-comments-back paragraph). Pure v1 fetch + markdown fallback content. - The "v1 fetch (MCP fetch-doc) + markdown 输出 ... v2 fetch ... 无此 markdown 注释占位符" sentence from the 概念区分 read-path bullet. Replaced with a tight v2 description: existing same-type blocks serialize to their XML tags, readable and usable as a block_move_after source. - Signal #2's reference to the placeholder fallback. Replaced with the direct v2 signal: fetch comes back without the tag the write attempted to add (pre-existing same-type blocks remain, unrelated to the write). Kept (unchanged, all version-agnostic / data-model rooted): - 5-block read-only inventory (synced_reference / synced_source / bitable / base_ref / okr) — non-creatable from text in any API version - block_move_after migration advice — v2 command, applies natively - block_copy_insert_after exclusion note for the same 5 types + task - "对 AI Agent 的影响" guidance (with a small consistency tweak: "在 markdown 里伪造" → "在生成的 XML / markdown 里伪造", since v2 defaults to XML) Net: -12 / +2 lines. Doc now only describes behavior that applies to the v2-only audience the skill is targeting. --- .../references/lark-doc-block-type-limits.md | 20 ++++--------------- 1 file changed, 4 insertions(+), 16 deletions(-) diff --git a/skills/lark-doc/references/lark-doc-block-type-limits.md b/skills/lark-doc/references/lark-doc-block-type-limits.md index 205e7b2f5..3867d4a22 100644 --- a/skills/lark-doc/references/lark-doc-block-type-limits.md +++ b/skills/lark-doc/references/lark-doc-block-type-limits.md @@ -7,7 +7,7 @@ `docs +create` / `docs +update` 并非支持全部 block 类型。**这些 block 在文档里 _可以存在_（通过 fetch 读出、通过 `block_move_after` 在文档之间搬动），但 _不能创建/更新_** —— 也就是说写入路径会静默跳过它们，不会抛错也不会出现在新文档中。两条路径行为如下： - **写入路径（`docs +create` / `docs +update --command append/overwrite/...`）**：如果输入里出现这些 block 标签，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进入新文档。 -- **读取路径（`docs +fetch`）**：原文档里**已经存在**的同类 block 仍会被序列化输出（保留为对应 XML 标签）；少数飞书内部块如果无法稳定序列化，**v1 fetch（MCP `fetch-doc`）+ markdown 输出**会以 `` 形式占位呈现。v2 fetch（`POST /open-apis/docs_ai/v1/documents//fetch`）默认 XML 输出，走结构化 block 表示，无此 markdown 注释占位符。 +- **读取路径（`docs +fetch --api-version v2`）**：原文档里**已经存在**的同类 block 仍会被序列化为对应 XML 标签输出，可读、可作为 `block_move_after` 的搬动来源。 - **跨文档移动（`docs +update --command block_move_after`）**：所有 block 都支持移动，因此这些 read-only block 可以从一篇文档搬到另一篇。`block_copy_insert_after` 也可对部分类型生效，详见 [`lark-doc-xml.md` §四 块级复制与移动](lark-doc-xml.md#四块级复制与移动)。 简单说：**这些 block 不是"完全只读"，只是"create / update 时无法新建"**。 @@ -26,28 +26,16 @@ > **复制限制（`block_copy_insert_after`）**：上述五类（外加 `task`）都**不支持复制**；img / source / whiteboard / sheet / chat_card 才支持复制。 -## 会产生 `` 占位符的块（v1 fetch / markdown 输出） - -> 本节专指 **v1 MCP `fetch-doc` + markdown 输出** 的兜底行为。v2 fetch 默认 XML 输出走结构化 block 表示，不会出现此 markdown 注释形式；v2 markdown 输出的兜底未单独验证，可能与 v1 不同。 - -v1 `fetch-doc` 导出 markdown 时遇到无法稳定序列化的原生 block，会以 `` 形式占位（例如 block type 53）。典型触发者包括： - -- 部分 **文档小组件（AddOns）** — `` 子集 -- **Wiki SubPageList** — `` 在 wiki 节点以外的上下文 -- **议程（Agenda）** 的部分子块 - -如果 round-trip 回灌时看到这些注释，**不要直接把注释当成 markdown 源再 create / update** —— v1 / v2 写入路径都不会把 HTML 注释解析成 block。需要人工在 UI 中重建，或寻找对应的 OpenAPI 专用接口。 - ## 定位"该块没进去"的信号 -1. `docs +create` / `docs +update` 响应 `code=0`、`success=true`，UI 上却找不到预期 block（v1 / v2 通用） -2. 随后 `docs +fetch` 拿回来的内容里该块消失；若用 **v1 fetch + markdown** 还可能出现 `` 注释 +1. `docs +create` / `docs +update` 响应 `code=0`、`success=true`，UI 上却找不到预期 block +2. 随后 `docs +fetch --api-version v2` 拿回来的 XML 里**找不到本次写入的对应 tag**（写入前就存在的同类 block 仍可见，与本次写入无关） 3. round-trip diff 多出一段 `+` / `-` 或类似标签 出现上述任一信号时，优先怀疑 block 类型在上面表格中。 ## 对 AI Agent 的影响 -- **周报 / 文档模板场景**：首行 `synced_reference` 团队介绍块必须通过 UI 手动补上；skill 里应显式记录"绑定同步块"是手工步骤，不要在 markdown 里伪造。 +- **周报 / 文档模板场景**：首行 `synced_reference` 团队介绍块必须通过 UI 手动补上；skill 里应显式记录"绑定同步块"是手工步骤，不要在生成的 XML / markdown 里伪造。 - **文档迁移 / round-trip**：跨文档迁移同步块、bitable、okr 等优先用 `block_move_after`（搬不复制）；权限或环境变化导致引用断链时，需要人工修复。 - **生成式内容**：Agent 从零生成时应避免主动插入 ``、``、``、`` 等标签（写不进去）；如果是从一篇旧文档迁内容到新文档，先 fetch 这些 block 再用 `block_move_after`。