Skip to content

Commit 4f4c0b5

Browse files
docs(lark-doc): replace append with block_insert_after in skeleton workflow guidance (#1340)
`append` always inserts at document end (equiv. `block_insert_after --block-id -1`), but skill docs previously recommended it for the "skeleton + chapter-by-chapter fill" pattern, causing all content to pile up after the last heading. Changes: - Remove `append` from skeleton workflow guidance in `lark-doc-create-workflow.md` and `lark-doc-create.md`; recommend `block_insert_after` with explicit `--block-id` - Fix `block_move_after` required params: remove `--content` (not supported), only `--block-id` and `--src-block-ids` are valid - Add bash language tag to code block for proper highlighting
1 parent 2b4c634 commit 4f4c0b5

3 files changed

Lines changed: 5 additions & 5 deletions

File tree

skills/lark-doc/references/lark-doc-create.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
7373
## 最佳实践
7474

7575
- 文档标题从内容中自动提取(XML `<title>` 或 Markdown `#`),不要在内容开头重复写标题
76-
- **创建较长的文档时只建骨架**`--content` 仅传标题 + 各级 heading + 简短占位摘要;正文留给后续 `docs +update --command append``block_insert_after` 分段追加。一次性塞超长 `--content` 既容易触发参数限制,调试也更难。
76+
- **创建较长的文档时只建骨架**`--content` 仅传标题 + 各级 heading + 简短占位摘要;正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制,调试也更难。
7777
- **视觉丰富度**:必须遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南,主动使用结构化 block 丰富文档
7878

7979
## 参考

skills/lark-doc/references/lark-doc-update.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@
4040
| `block_replace` | 替换指定 block(同一 block 仅限一次) | `--block-id` `--content` |
4141
| `block_delete` | 删除指定 block(逗号分隔可批量) | `--block-id` |
4242
| `overwrite` | ⚠️ 清空文档后全文重写(可能丢失图片、评论) | `--content` |
43-
| `append` | 在文档末尾追加内容(等价于 `block_insert_after --block-id -1`| `--content` |
44-
| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` + (`--content``--src-block-ids`) |
43+
| `append` | ⚠️ 在文档**末尾**追加内容(等价于 `block_insert_after --block-id -1`**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` |
44+
| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` |
4545

4646
## 指令示例
4747

skills/lark-doc/references/style/lark-doc-create-workflow.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,14 @@
2222
2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block;承载重要信息的章节优先规划画板
2323
3. `docs +create --api-version v2` **只建骨架**:标题 + 开头 `<callout>` + 各级标题 + 每节一句占位摘要
2424
- ⚠️ **不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
25-
- 完整内容留到第二波,由各 Agent 用 `docs +update --command append``block_insert_after` 分段写入。
25+
- 完整内容留到第二波,由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
2626

2727
### 第二波 — 内容撰写(并行 Agent)
2828

2929
4. Spawn Agent 并行撰写各章节。每个 Agent 需收到:
3030
- 文档 token、负责的章节范围、期望的 block 类型
3131
- `lark-doc-xml.md``lark-doc-style.md` 的完整路径(Agent 须先读取)
32-
- 使用 `docs +update --command append``block_insert_after` 写入
32+
- 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
3333

3434
### 第三波 — 整合审查 + 画板意图识别(串行)
3535

0 commit comments

Comments
 (0)