Skip to content

feat(doc-skill): document upload-then-move workflow for inserting images into container blocks #970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
fangshuyu-768 wants to merge 1 commit into from
Closed

feat(doc-skill): document upload-then-move workflow for inserting images into container blocks #970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skills/lark-doc/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,6 @@ Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）
| [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown) |
| [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
| [`+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-insert`](references/lark-doc-media-insert.md) | Insert a local image or file into a Lark document (4-step orchestration + auto-rollback). Appends to end by default; to insert into a container block (table cell, callout, grid column), use the upload-then-move workflow (`+media-insert` → `block_move_after`). 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. |
90 changes: 87 additions & 3 deletions skills/lark-doc/references/lark-doc-media-insert.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@

# docs +media-insert（文档末尾插入图片/文件）
# docs +media-insert（插入图片/文件到文档）

> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在**文档末尾**插入本地图片或文件。
把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在文档中插入本地图片或文件。默认追加到文档末尾；如需插入到表格单元格、callout 等容器 block 内部，使用[上传后移动](#插入图片到容器-block)工作流。

@coderabbitai coderabbitai Bot May 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

统一默认插入位置描述，避免前后冲突。

Line 6/Line 118 写的是“默认到文档末尾”，但 Line 113 已说明默认是文档顶层（可能在 --selection-with-ellipsis 附近）。建议三处统一成同一口径，否则用户会误判 Step 1 的实际落点。

Also applies to: 113-113, 118-118

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-doc/references/lark-doc-media-insert.md` at line 6, The
documentation contains conflicting default-insertion descriptions: one sentence
says "默认追加到文档末尾" while another says "默认是文档顶层（可能在 `--selection-with-ellipsis`
附近）"; locate the three occurrences (the opening summary sentence that starts
with 把"创建空 block → 上传文件 → 设置 token"..., the Step 1 description mentioning
insertion location, and the later note that references
`--selection-with-ellipsis`) and make them consistent by choosing one canonical
wording (e.g., "默认插入到文档顶层；默认位置可能在 `--selection-with-ellipsis` 附近，如需追加到末尾请说明")
and update all three places to that exact phrasing so users get the same
default-insertion behavior across the doc.


## 来源选择（Agent 必读）

Expand Down Expand Up @@ -108,7 +108,91 @@ lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height
> [!CAUTION]
> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。

## 插入图片到容器 block

`+media-insert` 默认将图片插入到文档顶层（末尾或 `--selection-with-ellipsis` 匹配的顶层 block 附近），无法直接放入表格单元格、callout、grid column 等容器内部。通过"上传后移动"两步工作流可实现：

### 工作流

```
Step 1: +media-insert 上传图片到文档末尾 → 得到 img block_id
Step 2: +update block_move_after 将图片移入目标容器
```

### Step 1：上传图片

```bash
lark-cli docs +media-insert --doc doxcnXXX --file ./image.png --caption "架构图" --width 800
# 返回: { "block_id": "blkImgXXX", "file_token": "filXXX", ... }
```

### Step 2：移动到容器内

用 `docs +update --command block_move_after` 将图片移入目标容器。`--block-id` 指定容器内的锚点 block（图片将出现在锚点之后），`--src-block-ids` 指定 Step 1 返回的 img block_id。

```bash
# 移动图片到表格单元格内（锚点为单元格内的某个 block，如 <p>）
lark-cli docs +update --api-version v2 --doc doxcnXXX \
--command block_move_after \
--block-id blkParagraphInTd \
--src-block-ids blkImgXXX

# 移动图片到 callout 内
lark-cli docs +update --api-version v2 --doc doxcnXXX \
--command block_move_after \
--block-id blkParagraphInCallout \
--src-block-ids blkImgXXX

# 移动图片到 grid column 内
lark-cli docs +update --api-version v2 --doc doxcnXXX \
--command block_move_after \
--block-id blkParagraphInColumn \
--src-block-ids blkImgXXX
```

> `block_move_after` 支持跨父节点移动，即从文档顶层移入容器 block 内部。详见 [`lark-doc-update.md`](lark-doc-update.md)。

### 获取容器内的锚点 block_id

使用 `docs +fetch --detail with-ids` 获取文档内容，从返回的 XML 中提取容器内目标位置的 block `id` 属性：

```bash
lark-cli docs +fetch --api-version v2 --doc doxcnXXX --detail with-ids
```

返回示例中，`<td>` 内的 `<p id="blkXXX">` 即可作为锚点：

```xml
<td vertical-align="top">
<p id="blkParagraphInTd">单元格文字</p>
</td>
```

### 完整示例：插入图片到表格单元格

```bash
# 1. 先 fetch 获取目标单元格内的 block_id
lark-cli docs +fetch --api-version v2 --doc doxcnXXX --detail with-ids

# 2. 上传图片到文档末尾（可指定 --width/--height 控制尺寸）
lark-cli docs +media-insert --doc doxcnXXX --file ./chart.png --caption "数据图表" --width 800
# → block_id: blkNewImg

# 3. 将图片移入表格单元格
lark-cli docs +update --api-version v2 --doc doxcnXXX \
--command block_move_after \
--block-id blkCellParagraph \
--src-block-ids blkNewImg
```

### 注意事项

- **两步非原子操作**：Step 1 成功但 Step 2 失败时，文档末尾会残留图片 block，需手动删除（`docs +update --command block_delete --block-id blkNewImg`）
- **图片尺寸**：在 Step 1 通过 `--width`/`--height` 设置即可，移动后保留
- **`--align` 和 `--caption`**：在 Step 1 设置即可，移动后保留

## 参考

- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token 和 block_id）
- [lark-doc-update](lark-doc-update.md) — 更新文档（`block_move_after` / `block_delete` 等指令）
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
Loading