forked from AxTps/Starlight_Lancher
feat：移除了弹窗，服务器添加sls
This commit is contained in:
84
.claude/skills/lark-doc/SKILL.md
Normal file
84
.claude/skills/lark-doc/SKILL.md
Normal file
@ -0,0 +1,84 @@
|
||||
---
|
||||
name: lark-doc
|
||||
version: 2.0.0
|
||||
description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。当用户明确要操作飞书思维笔记时，也使用本 skill。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
cliHelp: "lark-cli docs --help;lark-cli mindnotes --help"
|
||||
---
|
||||
|
||||
# docs
|
||||
|
||||
**身份：文档操作默认使用 `--as user`。首次使用前执行 `lark-cli auth login`。**
|
||||
|
||||
```bash
|
||||
# 常用示例
|
||||
lark-cli docs +fetch --doc "文档URL或token；若 URL 存在 #share-... 锚点，优先使用锚点方式读取，不要全文拉取"
|
||||
lark-cli docs +create --content '<title>标题</title><p>内容</p>'
|
||||
lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
|
||||
```
|
||||
|
||||
## 前置条件 — 执行操作前必读
|
||||
|
||||
**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
|
||||
1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
|
||||
2. **读取文档（`docs +fetch`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
|
||||
3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）和必读 [`lark-doc-style.md`](references/style/lark-doc-style.md)（写作原则：默认段落、按体裁、组件克制）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update.md`](references/lark-doc-update.md) 和 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
|
||||
|
||||
**未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
|
||||
|
||||
> **格式选择规则（全局）：**
|
||||
> - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML。
|
||||
> - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
|
||||
|
||||
## 快速决策
|
||||
- 用户要**复制文档 / 创建文档副本 / 另存为副本**时，切到 [`lark-drive`](../lark-drive/SKILL.md)，按其中的复制指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文，也不要走 `drive +export` / `drive +import`。
|
||||
- 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full`
|
||||
- block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids`
|
||||
- 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
|
||||
- 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
|
||||
- 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
|
||||
- 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent
|
||||
- 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
|
||||
- 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
|
||||
- 用户想把文档回滚到某个 `revision_id` 或某一时刻 → 先读 [`lark-doc-history.md`](references/lark-doc-history.md)，按其中流程操作
|
||||
- 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
|
||||
- `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
|
||||
- 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
|
||||
- 用户明确要操作思维笔记时；已有**思维笔记**，走 [思维笔记链路](references/lark-doc-mindnote.md)；新建**思维笔记**，走 [lark-doc-whiteboard](references/lark-doc-whiteboard.md)
|
||||
- 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
|
||||
- 用户需要统计文档的**总字数 / 总字符数**（word count / character count）时，先读取 [`lark-doc-word-stat.md`](references/lark-doc-word-stat.md)，并按其中流程调用 [`scripts/doc_word_stat.py`](scripts/doc_word_stat.py)；统计口径以该脚本为准，不要改用其他方式自行计算。
|
||||
- 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到 `lark-drive` 处理
|
||||
- 文档内容中出现嵌入的 `<sheet>`、`<bitable>` 或 `<cite file-type="sheets|bitable">` 标签时 → **必须主动提取 token 并切到对应技能下钻读取内部数据**，不能只呈现标签本身
|
||||
|
||||
| 标签 / 属性 | 提取字段 | 切到技能 |
|
||||
|-|-|-|
|
||||
| `<sheet token="..." sheet-id="...">` | `token` -> spreadsheet_token, `sheet-id` | [`lark-sheets`](../lark-sheets/SKILL.md) |
|
||||
| `<bitable token="..." table-id="...">` | `token` -> app_token, `table-id` | [`lark-base`](../lark-base/SKILL.md) |
|
||||
| `<cite type="doc" file-type="sheets" token="..." sheet-id="...">` | 同 `<sheet>` | [`lark-sheets`](../lark-sheets/SKILL.md) |
|
||||
| `<cite type="doc" file-type="bitable" token="..." table-id="...">` | 同 `<bitable>` | [`lark-base`](../lark-base/SKILL.md) |
|
||||
| `<vc-transcribe-tab vc-node-id="...">` | `vc-node-id` -> note_id | [`lark-note`](../lark-note/SKILL.md)：先 `note +detail --note-id <vc-node-id>` |
|
||||
| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch` 读取 src-token 文档，定位 block |
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
|
||||
Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
|
||||
| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
|
||||
| [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
|
||||
| [`+history-list` / `+history-revert` / `+history-revert-status`](references/lark-doc-history.md) | List document history, revert to a `history_version_id`, and query revert task status |
|
||||
| [`+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) |
|
||||
| [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
|
||||
| [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md) | Download, update, or delete a Docx cover image resource with `--type cover` |
|
||||
| [`+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. |
|
||||
|
||||
## 不在本 Skill 范围
|
||||
|
||||
- 文档评论管理 → [`lark-drive`](../lark-drive/SKILL.md)
|
||||
- 电子表格或 Base 的数据操作 → [`lark-sheets`](../lark-sheets/SKILL.md) / [`lark-base`](../lark-base/SKILL.md)
|
||||
- 云空间文件上传、下载、权限管理 → [`lark-drive`](../lark-drive/SKILL.md)
|
||||
80
.claude/skills/lark-doc/references/lark-doc-create.md
Normal file
80
.claude/skills/lark-doc/references/lark-doc-create.md
Normal file
@ -0,0 +1,80 @@
|
||||
# docs +create（创建飞书云文档）
|
||||
|
||||
> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
|
||||
> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
|
||||
> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
|
||||
> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
|
||||
>
|
||||
> **未读完以上文件就生成内容会导致格式错误。**
|
||||
|
||||
从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
|
||||
|
||||
> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，可承载更丰富的结构化内容）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 创建 XML 文档（默认格式，推荐）
|
||||
lark-cli docs +create --content '<title>项目计划</title><h1>目标</h1><p>记录本周重点。</p>'
|
||||
|
||||
# 仅当用户明确要求导入 Markdown 时才使用；文档标题用 --title，正文标题按内容自然组织
|
||||
lark-cli docs +create --doc-format markdown --title "项目计划" --content $'## 目标\n\n- 明确重点\n- 记录待办'
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {
|
||||
"document": {
|
||||
"document_id": "docx_token",
|
||||
"revision_id": 1,
|
||||
"url": "https://xxx.feishu.cn/docx/docx_token",
|
||||
"new_blocks": [
|
||||
{ "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- **`document.new_blocks`**：本次操作新增的 block 列表（如画板）。`block_id` 可用于 `docs +update` 的 `--block-id` 做精确编辑；`block_token` 是资源块（如画板）的 token，可交给 `lark-whiteboard` 等 skill 继续操作
|
||||
|
||||
> \[!IMPORTANT]
|
||||
> 如果文档是**以应用身份（bot）创建**的，如 `lark-cli docs +create --as bot` 在文档创建成功后，CLI 会**尝试为当前 CLI 用户自动授予该文档的 `full_access`（可管理权限）**。
|
||||
>
|
||||
> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：
|
||||
> - `status = granted`：当前 CLI 用户已获得该文档的可管理权限
|
||||
> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限
|
||||
> - `status = failed`：文档已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档
|
||||
>
|
||||
> `permission_grant.perm = full_access` 表示该资源已授予”可管理权限”。
|
||||
>
|
||||
> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
| ------------------- | -- |---------------------------------------------|
|
||||
| `--title` | 否 | 文档标题，Markdown 导入时使用；XML 创建推荐在 `--content` 开头写 `<title>...</title>`；多个标题仅保留第一个并在 `warnings` / `degrade_details` 提示 |
|
||||
| `--content` | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title` |
|
||||
| `--reference-map` | 否 | 结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。 |
|
||||
| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
|
||||
| `--parent-token` | 否 | 父文件夹或知识库节点 token（与 `--parent-position` 互斥） |
|
||||
| `--parent-position` | 否 | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容
|
||||
- **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
|
||||
|
||||
## 参考
|
||||
|
||||
- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、单 Agent 串行撰写）
|
||||
- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
|
||||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
|
||||
- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
|
||||
- [`lark-doc-update.md`](lark-doc-update.md) — 更新文档
|
||||
- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
|
||||
148
.claude/skills/lark-doc/references/lark-doc-fetch.md
Normal file
148
.claude/skills/lark-doc/references/lark-doc-fetch.md
Normal file
@ -0,0 +1,148 @@
|
||||
|
||||
# docs +fetch（获取飞书云文档）
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 获取文档（默认 XML，simple）
|
||||
lark-cli docs +fetch --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
|
||||
|
||||
# Markdown 格式
|
||||
lark-cli docs +fetch --doc Z1Fj...tnAc --doc-format markdown
|
||||
|
||||
# 带 block ID（用于后续 block 级更新）
|
||||
lark-cli docs +fetch --doc Z1Fj...tnAc --detail with-ids
|
||||
|
||||
# 只拿目录
|
||||
lark-cli docs +fetch --doc Z1Fj...tnAc --scope outline --max-depth 3
|
||||
|
||||
# 按 block id 区间精读
|
||||
lark-cli docs +fetch --doc Z1Fj...tnAc --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
|
||||
|
||||
# URL 带 #share 选区锚点时自动局部读取
|
||||
lark-cli docs +fetch --doc 'docURL#share-anchor'
|
||||
|
||||
# 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
|
||||
lark-cli docs +fetch --doc Z1Fj...tnAc \
|
||||
--scope section --start-block-id <标题id> --detail with-ids
|
||||
|
||||
# 按关键词定位（多关键词用 | 分隔，任一命中即返回）
|
||||
lark-cli docs +fetch --doc Z1Fj...tnAc \
|
||||
--scope keyword --keyword "部署|发布|上线"
|
||||
```
|
||||
|
||||
## 选 `--detail`（每块详细度）
|
||||
|
||||
| 意图 | `--detail` | 说明 |
|
||||
|------|-----------|------|
|
||||
| **只读**：浏览或总结文档内容 | `simple`（默认） | 简洁 XML/Markdown，不含 block ID、样式属性、引用元数据 |
|
||||
| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `<p id="blkcnXXXX">`），可用于 `+update` 的 `--block-id`，也可用于拼接 `文档URL#block_id` 形式的直达链接 |
|
||||
| **编辑**：任何修改文档内容的需求 | `full` | 包含 block ID + 样式属性 + 引用元数据，提供完整文档结构信息 |
|
||||
|
||||
## 选 `--scope`（读取范围）
|
||||
|
||||
`--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。**
|
||||
|
||||
| 模式 | 何时用 | 关键参数 | 行为要点 |
|
||||
|-|-|-|-|
|
||||
| `outline` | 不知道结构，先看目录 | `--max-depth`（标题层级上限） | 扁平列出所有标题，**包括嵌在容器里的内嵌标题**（如 callout 里的 h3）；这些 id 可直接作后续 `section` / `range` 端点 |
|
||||
| `section` | 读某个标题对应的整节 | `--start-block-id`（必填） | 顶层标题 → 展开到下一同级/更高级标题前；容器内节点（含内嵌标题） → 按"最小包容单元"返回容器/表格切片，不做 heading 扩展；顶层非标题块 → 仅该块 |
|
||||
| `range` | 已知精确起止 | `--start-block-id` / `--end-block-id` 至少一个；`-1` = 读到末尾 | 两端同顶层 → 顶层序列切片；两端同一容器 → 容器整体；两端同一表格 → 瘦身切片；**跨顶层 → 端点所在顶层块整块输出，不做瘦身** |
|
||||
| `keyword` | 只有模糊关键词 | `--keyword`（**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\|` 分隔多分支 OR） | 每处命中按"最小包容单元"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |
|
||||
|
||||
> 💡 **多关键词用 `\|` 拼接（OR 语义，任一命中即返回）**：例 `"部署\|发布\|上线"`，三词任一命中都进结果，适合**同义词/别名/多业务术语**一次召回（如 `bug\|缺陷\|故障`）。
|
||||
|
||||
**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`。
|
||||
|
||||
- `--max-depth`：`outline` = 标题层级上限（3 = h1~h3）；其它模式 = 被选块的子树遍历深度（`-1` 不限，`0` 仅块自身）。
|
||||
- `--context-before/--context-after`：**只对整块顶层单元生效**；命中落在容器/表格内（返回容器或切片）时 before/after 被忽略，需要更大范围改用 `section` / `range` 显式指定。
|
||||
|
||||
**决策顺序**（核心原则：**局部获取优于全量获取**，根据需求形态选起点，必要时多步组合收敛范围）：
|
||||
1. 需求**直接给出待查的具体术语/错误码/标识** → 直接走 `keyword` 粗匹配（多级 fallback 自动覆盖形变），需要更大上下文时用返回的 `top-block-id` 走 `section` / `range`
|
||||
2. 需求**指向某个章节/标题**（"修改 XX 章"、"总结第 3 节"、"关于 xx 的内容"）→ 先 `outline --max-depth 3` 拿目录 → `section --start-block-id <标题id>` 精读
|
||||
3. 已知**精确起止 / 跨节连续区间** → `range`
|
||||
4. **结构未知且无明确关键词/章节线索** → `outline` 探测，再回到 2/3
|
||||
5. **兜底**：仅在确需整篇时才省略 `--scope`；不要为省事直接读整篇
|
||||
|
||||
## 局部读取的输出结构：`<fragment>` 与 `<excerpt>`
|
||||
|
||||
设置 `--scope` 时返回的 `content` 被一个 `<fragment>` 节点包裹，属性包含 `mode` / `requested-start` / `requested-end` / `keyword`（按需）。子节点只有两种形态：
|
||||
|
||||
- **顶层块**：完整块直接作为 `<fragment>` 的子节点，无额外包裹。
|
||||
- **`<excerpt top-block-id="..." parent-block-path="...">`**：非顶层节选（容器整体 / 表格瘦身切片）。
|
||||
- `top-block-id`：所在顶层块 id，想看该块全貌时作 `section` / `range` 锚点再拉一次。
|
||||
- `parent-block-path`：从顶层块到 excerpt 内容直接父节点的 id 路径，`/` 分隔（表格切片时即表格自身 id）。
|
||||
|
||||
**看到 `<excerpt>` 即意味着这是节选**，不能假设看到了该顶层块的全貌。
|
||||
|
||||
**表格默认瘦身**：即便 `<table>` 本身是顶层块也只返回 thead + 命中 tr。想拿整张表 → `range --start-block-id <table-id> --end-block-id <table-id>`；切片范围恰好覆盖全部 tr 时 SDK 自动升级为整块、不包 `<excerpt>`。
|
||||
|
||||
## 返回值
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {
|
||||
"document": {
|
||||
"document_id": "doxcnXXXX",
|
||||
"revision_id": 12,
|
||||
"content": "<title>标题</title><p>文档内容...</p>",
|
||||
"reference_map": {
|
||||
"<block_type>": {
|
||||
"<ref>": {
|
||||
"<real-attr-key>": "<real-attr-value>"
|
||||
}
|
||||
}
|
||||
},
|
||||
"tips": "<safe replay or degradation guidance>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`content` 的格式由 `--doc-format` 决定。`reference_map` 是正文引用数据的结构化 sidecar：一级键 `block_type` 表示引用所在的块类型，二级键 `ref` 对应正文中的临时引用；每个引用的值是由 `real-attr-key` 和 `real-attr-value` 组成的真实属性映射，具体属性由块类型决定。没有提取数据时，`reference_map` 可能为空。`content` 和 `reference_map` 属于同一份响应，保留或回放内容时应配套处理。`tips` 给出安全回放或降级提示。`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见上文"局部读取的输出结构"。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
|
||||
| `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `im-markdown`（仅用于获取内容后在 `lark-im` 场景下使用） |
|
||||
| `--detail` | 否 | `simple`（默认）\| `with-ids` \| `full` |
|
||||
| `--revision-id` | 否 | 文档版本号，`-1` = 最新（默认） |
|
||||
| `--scope` | 否 | `outline` \| `range` \| `keyword` \| `section`（省略 = 读整篇） |
|
||||
| `--start-block-id` | 否 | `range`/`section` 起始/锚点 id（`section` 必填） |
|
||||
| `--end-block-id` | 否 | `range` 结束 id；`-1` 表示读到末尾 |
|
||||
| `--keyword` | 否 | `keyword` 模式关键词，**4 层自动 fallback**（子串 → 归一化 → 分词形变 → RE2 正则）；`\|` 分隔多分支 OR |
|
||||
| `--context-before` | 否 | 命中前拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
|
||||
| `--context-after` | 否 | 命中后拉几个兄弟块（仅对顶层单元生效，默认 `0`） |
|
||||
| `--max-depth` | 否 | `outline` = 标题层级上限；其它 = 子树深度（`-1` 不限，默认） |
|
||||
| `--format` | 否 | `json`（默认）\| `pretty` |
|
||||
|
||||
## 图片、文件、画板的处理
|
||||
|
||||
**文档中的素材以 XML 标签形式出现：**
|
||||
|
||||
```xml
|
||||
<img token="..." url="https://..." width="..." height="..."/>
|
||||
<source token="..." url="https://..." name="skills.zip"/>
|
||||
<whiteboard token="..."/>
|
||||
```
|
||||
|
||||
- `<img>` / `<source>` 带 `url` 时，直接用该 URL 下载即可（普通 HTTP GET），无需走 shortcut。
|
||||
- 没有 `url`、或只想预览 → `docs +media-preview --token <token> --output ./preview_media`
|
||||
- 明确下载，或目标是 `<whiteboard>`（画板只能走 shortcut） → `docs +media-download --token <token> --output ./downloaded_media`
|
||||
- 文档封面图不是正文素材；下载/更新/删除封面图 → `docs +resource-download/+resource-update/+resource-delete --type cover`
|
||||
|
||||
## 嵌入电子表格 / 多维表格
|
||||
|
||||
返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-create](lark-doc-create.md) — 创建文档
|
||||
- [lark-doc-update](lark-doc-update.md) — 更新文档
|
||||
- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
|
||||
- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图
|
||||
- [lark-doc-resource-cover](lark-doc-resource-cover.md) — 读取、更新、删除文档封面图
|
||||
107
.claude/skills/lark-doc/references/lark-doc-history.md
Normal file
107
.claude/skills/lark-doc/references/lark-doc-history.md
Normal file
@ -0,0 +1,107 @@
|
||||
# docs history（历史版本与回滚）
|
||||
|
||||
用于查看 Docx 历史版本、按 `history_version_id` 回滚，以及查询回滚任务状态。
|
||||
|
||||
## 安全流程
|
||||
|
||||
1. 先用分页接口 `+history-list` 找到目标版本的 `history_version_id`。
|
||||
2. 如果用户指定的是 `revision_id`，不要假设它唯一，也不要把 `revision_id` 直接传给 `+history-revert`。先拉一页并在 `entries[]` 中筛选 `revision_id` 相同的候选；如果未匹配到且 `has_more=true`，继续用 `page_token` 翻页；如果已匹配到候选，最多额外再拉一页补齐可能跨页的相邻候选。最终优先根据用户目标时间与 `edit_time` 的接近程度选择最合适的一条，取同一条的 `history_version_id`；如果没有目标时间，或多个候选无法可靠区分，再向用户展示候选版本（`history_version_id`、`revision_id`、`edit_time`、`name/description`）并确认后回滚。
|
||||
3. 如果用户指定的是某一时刻但没有指定 `revision_id`，按 `entries[].edit_time` 匹配；优先选择不晚于目标时刻的最近一条历史记录，无法明确匹配时先向用户确认候选版本。
|
||||
4. 再用 `+history-revert --history-version-id <history_version_id>` 发起回滚。默认最多等待 30 秒；如果返回 `status: running`，记录 `task_id`。
|
||||
5. 用 `+history-revert-status` 轮询 `task_id`，直到状态不再是 `running`。
|
||||
6. 回滚完成后，用 `docs +fetch` 读取文档确认内容。
|
||||
|
||||
## 按 revision_id 或时间点回滚
|
||||
|
||||
当用户说“回滚到 revision_id=42”“恢复到昨天下午 3 点的版本”这类需求时，流程是：
|
||||
|
||||
1. 执行 `docs +history-list --doc <doc>` 获取第一页历史记录；`+history-list` 是分页接口，只有 `has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
|
||||
2. 如果用户给出 `revision_id`：先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。如果未命中且 `has_more=true`，继续拉下一页；如果已经命中候选，最多额外再拉一页，补齐同一个 `revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间，在候选里选择 `edit_time` 与目标时间最接近的一条；若未给目标时间但候选只有一条，可直接使用；若多个候选无法可靠区分，不要自行取第一条，向用户展示候选并确认。
|
||||
3. 如果用户只给出时间：用 `entries[].edit_time` 匹配，选择目标时刻之前最近的一条；如果用户表达的是“最接近某时刻”，则选择绝对时间差最小的一条。
|
||||
4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`，这是回滚接口需要的 ID。
|
||||
5. 执行 `docs +history-revert --doc <doc> --history-version-id <history_version_id>`。
|
||||
|
||||
候选确认时使用类似格式：
|
||||
|
||||
```text
|
||||
同一个 revision_id 命中多个历史版本，请确认要回滚哪一条：
|
||||
- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
|
||||
- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
|
||||
```
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 列出历史版本
|
||||
lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20
|
||||
|
||||
# 翻页
|
||||
lark-cli docs +history-list --doc "<docx_url_or_token>" --page-size 20 --page-token "<page_token>"
|
||||
|
||||
# 回滚到指定 history_version_id（默认等待 30000ms）
|
||||
lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42
|
||||
|
||||
# 只发起任务，不等待
|
||||
lark-cli docs +history-revert --doc "<docx_url_or_token>" --history-version-id 42 --wait-timeout-ms 0
|
||||
|
||||
# 查询回滚任务状态
|
||||
lark-cli docs +history-revert-status --doc "<docx_url_or_token>" --task-id "<task_id>"
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 命令 | 参数 | 必填 | 说明 |
|
||||
|-|-|-|-|
|
||||
| `+history-list` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
|
||||
| `+history-list` | `--page-size` | 否 | 返回条数，范围 `1-20`，默认 `20` |
|
||||
| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
|
||||
| `+history-revert` | `--doc` | 是 | Docx URL/token，或可解析为 Docx 的 wiki URL |
|
||||
| `+history-revert` | `--history-version-id` | 是 | `+history-list` 返回的 `history_version_id`，必须大于 0 |
|
||||
| `+history-revert` | `--wait-timeout-ms` | 否 | 等待回滚完成的毫秒数，范围 `0-30000`，默认 `30000` |
|
||||
| `+history-revert-status` | `--doc` | 是 | 同一个文档 |
|
||||
| `+history-revert-status` | `--task-id` | 是 | `+history-revert` 返回的 `task_id` |
|
||||
|
||||
## 返回值要点
|
||||
|
||||
`+history-list` 返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"revision_id": 42,
|
||||
"history_version_id": "11",
|
||||
"edit_time": "1780000000",
|
||||
"type": 1,
|
||||
"name": "版本名",
|
||||
"description": "版本说明",
|
||||
"editor_ids": ["ou_xxx"]
|
||||
}
|
||||
],
|
||||
"has_more": true,
|
||||
"page_token": "page_token"
|
||||
}
|
||||
```
|
||||
|
||||
`+history-revert` 返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id": "task_xxx",
|
||||
"status": "running",
|
||||
"history_version_id": "11",
|
||||
"poll_after_ms": 10000
|
||||
}
|
||||
```
|
||||
|
||||
`+history-revert-status` 返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "partial_failed",
|
||||
"history_version_id": "11",
|
||||
"failed_block_tokens": ["blk_xxx"]
|
||||
}
|
||||
```
|
||||
|
||||
`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或 `failed` 时，优先检查 `failed_block_tokens`。
|
||||
76
.claude/skills/lark-doc/references/lark-doc-md.md
Normal file
76
.claude/skills/lark-doc/references/lark-doc-md.md
Normal file
@ -0,0 +1,76 @@
|
||||
# Markdown 格式参考
|
||||
|
||||
`docs +fetch` / `docs +create` / `docs +update` 使用 `--doc-format markdown` 时适用；fetch 的 `--doc-format im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用，不作为 create/update 写入格式。
|
||||
|
||||
## 转义规则
|
||||
|
||||
> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。
|
||||
|
||||
### 无条件转义（行内生效，任何位置都要转义）
|
||||
|
||||
| 符号 | Markdown 语法用途 | 转义写法 | 示例 |
|
||||
|------|-------------------|----------|------|
|
||||
| `\` | 转义符本身 | `\\` | `C:\\Users` → C:\Users |
|
||||
| `` ` `` | 行内代码 | `` \` `` | `` 用 \` 包裹 `` |
|
||||
| `*` | 斜体 / 加粗 | `\*` | `3 \* 5 = 15` → 3 \* 5 = 15 |
|
||||
| `_` | 斜体 / 加粗 | `\_` | `foo\_bar\_baz` → foo\_bar\_baz |
|
||||
| `[` `]` | 链接文本 | `\[` `\]` | `\[非链接\]` |
|
||||
| `$` | 数学公式定界 | `\$` | `价格 \$100` |
|
||||
| `~` | 删除线（GFM `~~text~~`） | `\~` | `a\~\~b\~\~c` → a~~b~~c |
|
||||
| `<` | XML 标签起始（`<b>`、`<img>` 等会被当作标签解析并生效） | `\<` | 字面量 `<b>` 须写为 `\<b>`；`a < b` 建议写为 `a \< b` |
|
||||
|
||||
### 位置敏感转义（仅在特定位置才需要转义）
|
||||
|
||||
| 符号 | Markdown 语法用途 | 转义条件 | 示例 |
|
||||
|------|-------------------|----------|------|
|
||||
| `#` | 标题 | **仅行首**（去除前导空白后）| 行首 `\# 这不是标题`；行内 `A # B` 无需转义 |
|
||||
| `+` | 无序列表 | **仅行首**（去除前导空白后）| 行首 `\+ item`；行内 `1 + 2` 无需转义 |
|
||||
| `-` | 无序列表 / 分隔线 | **仅行首**（去除前导空白后）| 行首 `\- item`；行内 `A - B` 无需转义 |
|
||||
| `>` | 引用块 | **仅行首**（去除前导空白后）| 行首 `\> 不是引用`；行内 `a > b` 无需转义 |
|
||||
| `\|` | 表格 cell 分隔 | **仅在 GFM 表格 cell 内** | cell 内 `A \| B`；行内普通文本 `a \| b` 无需转义 |
|
||||
|
||||
**不需要转义的场景：**
|
||||
- 在 `` ` `` 行内代码或 ` ``` ` 代码块内，所有符号均为字面量，无需转义
|
||||
- `$...$` 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响
|
||||
|
||||
**导出已转义，不要反转义：**
|
||||
`docs +fetch --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
|
||||
|
||||
**写入时必须转义：**
|
||||
使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。
|
||||
|
||||
**导出 → 更新 工作流示例：**
|
||||
|
||||
1. `docs +fetch` 导出得到 `C:\\Users\\test\[1\]`
|
||||
2. 用 `str_replace --pattern 'C:\\Users\\test\[1\]'` 匹配（直接使用导出的转义形式）
|
||||
3. `--content` 中的替换内容也要保持转义：`C:\\Users\\prod\[2\]`
|
||||
|
||||
自行构造 Markdown 内容写入时同理：如字面文本 `a]b` 应写为 `a\]b`，`C:\Users` 应写为 `C:\\Users`。
|
||||
|
||||
## Shell 传参
|
||||
- **首选文件传参**：`--content` 支持 `@path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）
|
||||
- **⚠️ `@file` 路径限制**：`@file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下（如 `./_content.md`），用完自行清理。
|
||||
- **默认用单引号 `'...'`**：完全字面量，`$`、`` ` ``、`\`、`>`、`\<b>` 等全部原样保留
|
||||
- **双引号 `"..."`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\` 仍参与转义，易踩坑
|
||||
- **`$'...'` ANSI-C 引号**：按 C 转义解析，`\n`=换行、`\\`=单个 `\`；**zsh 下未知转义（如 `\<`）的 `\` 会被吞**，要保留字面 `\` 必须写 `\\`。只在确实需要 `\n`/`\t` 时用
|
||||
- **多行内容**：用 `<<'EOF'` heredoc，EOF 必须带引号，否则仍展开 `$`
|
||||
- **`\n` 在 `'...'` 和 `"..."` 里都是字面量**，不是换行；要真换行用 `$'...\n...'` 或 heredoc
|
||||
|
||||
## 图片语法
|
||||
|
||||
Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：
|
||||
```markdown
|
||||
|
||||
```
|
||||
- `alt text` 为图片描述（可选，可留空）
|
||||
- URL 支持 `http://` 和 `https://` 协议
|
||||
- 对应的 XML 格式为：`<img href="https://example.com/photo.png"/>`
|
||||
|
||||
## Markdown 不支持的 Block 类型
|
||||
|
||||
非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。
|
||||
> **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`<b>`、`<u>`、`<img>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `<tag>`），必须转义左尖括号：`\<b>`、`\<img>`。
|
||||
|
||||
## 参考
|
||||
|
||||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
|
||||
@ -0,0 +1,50 @@
|
||||
|
||||
# docs +media-download（下载文档素材/画板缩略图）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
下载文档中的图片/文件素材（`file_token`），或下载画板缩略图（`whiteboard_id`）。当 `--output` 不带扩展名时，会根据响应的 `Content-Type` 自动补全扩展名。
|
||||
|
||||
## 选择规则
|
||||
|
||||
- 用户明确说“下载素材”时，使用 `docs +media-download`
|
||||
- 用户只是想查看、预览图片或文件素材时，优先使用 [`docs +media-preview`](lark-doc-media-preview.md)
|
||||
- 如果目标明确是画板 / whiteboard / 画板缩略图，继续使用 `docs +media-download --type whiteboard`；`+media-preview` 不支持画板
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 下载图片/文件素材（默认 type=media）
|
||||
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset
|
||||
|
||||
# 指定输出文件名（带扩展名则不会自动补全）
|
||||
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset.png
|
||||
|
||||
# 下载画板缩略图（whiteboard token）
|
||||
lark-cli docs +media-download --type whiteboard --token "wbcnxxxxxxxx" --output ./whiteboard
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--token <token>` | 是 | 资源 token：素材为 `file_token`，画板为 `whiteboard_id` |
|
||||
| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
|
||||
| `--type <type>` | 否 | `media`（默认）或 `whiteboard` |
|
||||
|
||||
## token 从哪里来
|
||||
|
||||
- 若你是从文档内容里提取：`lark-doc-fetch` 返回的内容里可能包含：
|
||||
- 图片：`<img token="..." .../>`
|
||||
- 文件：`<source token="..." name="..."/>`
|
||||
- 画板：`<whiteboard token="..."/>`
|
||||
|
||||
## 排障
|
||||
|
||||
- 如果报错返回的信息包含 `HTTP 403`，且目标是图片/文件素材，可以改成调用 [`docs +media-preview`](lark-doc-media-preview.md) 看是否能先预览内容
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
|
||||
- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
114
.claude/skills/lark-doc/references/lark-doc-media-insert.md
Normal file
114
.claude/skills/lark-doc/references/lark-doc-media-insert.md
Normal file
@ -0,0 +1,114 @@
|
||||
|
||||
# docs +media-insert（文档末尾插入图片/文件）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在**文档末尾**插入本地图片或文件。
|
||||
|
||||
## 来源选择（Agent 必读）
|
||||
|
||||
> **最高优先级：用户明确指定了来源，就严格按用户的来。** 下面的启发式只在用户没表态时生效。
|
||||
>
|
||||
> - 用户说"把这张截图插进去"、"用剪切板里的图"、"我刚复制的" → 无条件走 `--from-clipboard`。
|
||||
> - 用户说"用 `~/Downloads/foo.png`"、"插本地这个文件"、给了具体路径 → 无条件走 `--file`。
|
||||
> - 用户两者都没说清 → 按下表的启发式推断。
|
||||
>
|
||||
> 即使推断看起来更"优"（比如用户说了路径但你觉得走剪切板更省事），也**不要自作主张**换来源。要换，先问。
|
||||
|
||||
按下列顺序判断，**不要反向做**：
|
||||
|
||||
| 用户的图片来源 | 命令 | 禁止做法 |
|
||||
|----------------|------|----------|
|
||||
| 图片已经在剪切板里（截图快捷键、从飞书/浏览器复制、从设计稿复制） | `--from-clipboard` | ❌ 不要先把剪切板存到本地文件再用 `--file`。多一步文件 I/O，还得清理临时文件。 |
|
||||
| 图片是磁盘上的真实文件 | `--file <path>` | — |
|
||||
| 图片是 URL | 先下载到本地 → `--file`；或用 `drive` 相关命令 | — |
|
||||
|
||||
`--from-clipboard` 走进程内存直传，不产生临时文件；macOS / Windows 内置支持，Linux 需要 `xclip` 或 `wl-paste` 或 `xsel` 任一。
|
||||
|
||||
### 剪切板为空时的 fallback
|
||||
|
||||
`--from-clipboard` 失败（剪切板里不是图片 / 没有图片 / Linux 上三个工具都没装）时，命令会返回 `clipboard contains no image data`（或类似的平台错误）。**这不是错误退出理由，而是 fallback 信号。**
|
||||
|
||||
**Agent 的标准处置顺序**（每一步失败再进下一步，不要并行）：
|
||||
|
||||
1. 先用 `--from-clipboard` 试一次。
|
||||
2. 如果返回"no image data"类错误，**向用户明确说明剪切板里没有可识别的图片**，请用户提供本地文件路径或重新复制一张图。
|
||||
3. 拿到本地路径后，用 `--file <path>` 重试**同一条插入命令**（其他参数如 `--doc` / `--align` / `--caption` 保持不变）。
|
||||
|
||||
**禁止做法**：
|
||||
- ❌ 不要悄悄把空剪切板当"成功但没插入"处理。必须提示用户。
|
||||
- ❌ 不要在剪切板失败后自行瞎猜某个本地文件路径（比如最近修改的 png）。必须让用户给路径。
|
||||
- ❌ 不要用"先让用户保存剪切板到磁盘再 `--file`"的建议绕过 `--from-clipboard`，当且仅当剪切板确实没图片时才退回本地路径。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 🟢 推荐：从剪切板直接插入（无需先存盘）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard
|
||||
|
||||
# 从本地文件插入
|
||||
# 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地：
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
|
||||
--block-id "目标 block_id" \
|
||||
--content '<img href="https://example.com/photo.png"/>'
|
||||
|
||||
# 插入图片（默认）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --file ./image.png
|
||||
|
||||
# doc 支持直接传 docx URL（自动提取 document_id）
|
||||
lark-cli docs +media-insert --doc "https://xxx.feishu.cn/docx/doxcnXXX" --from-clipboard
|
||||
|
||||
# 如果上一步是 create-doc，优先传返回值里的 doc_id
|
||||
# 不要把 /wiki/... 形式的 doc_url 直接传给 docs +media-insert
|
||||
lark-cli docs +media-insert --doc doxcnReturnedByCreateDoc --file ./image.png
|
||||
|
||||
# 插入文件（非图片）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file
|
||||
|
||||
# 图片对齐与描述（caption）
|
||||
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --caption "架构图"
|
||||
|
||||
# Insert image with explicit display width (height auto-computed from aspect ratio)
|
||||
lark-cli docs +media-insert --doc doxcnXXX --file ./banner.png --width 800 --align center
|
||||
|
||||
# Insert image with explicit width and height
|
||||
lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height 447 --caption "architecture diagram"
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--doc <id>` | 是 | 文档 ID 或 docx URL（仅支持 `/docx/<document_id>` 形式自动提取；**不支持 `/wiki/...` URL 自动提取**） |
|
||||
| `--from-clipboard` | 二选一 | 从系统剪切板读取图片（与 `--file` 互斥）。macOS/Windows 内置支持，Linux 需要 `xclip` / `wl-paste` / `xsel` 之一。 |
|
||||
| `--file <path>` | 二选一 | 本地文件路径（文件大于 20MB 时自动切换分片上传） |
|
||||
| `--type <type>` | 否 | `image`（默认）或 `file`。`--from-clipboard` 目前只产出 image。 |
|
||||
| `--align <align>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |
|
||||
| `--caption <text>` | 否 | 仅图片：图片描述 |
|
||||
| `--width <px>` | 否 | Image display width in pixels (only for `--type=image`). If `--height` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
|
||||
| `--height <px>` | 否 | Image display height in pixels (only for `--type=image`). If `--width` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。
|
||||
|
||||
## 平台注意（仅 `--from-clipboard`）
|
||||
|
||||
| 平台 | 依赖 | 典型错误 |
|
||||
|------|------|---------|
|
||||
| macOS | osascript（内置） | 剪切板为空 / 不是图片 → "clipboard contains no image data" |
|
||||
| Windows | PowerShell + System.Windows.Forms（内置） | 同上 |
|
||||
| Linux | `xclip` 或 `wl-paste` 或 `xsel` 任一 | 都没安装 → 报错会提示用发行版包管理器安装 |
|
||||
|
||||
命令不支持读取 TIFF 等非 PNG/JPEG/GIF/WebP/BMP 的冷门格式；遇到这类剪切板会返回 "contains no image data"，此时才考虑先用系统工具转成文件再 `--file`。
|
||||
|
||||
## 输出
|
||||
|
||||
命令成功后会输出 JSON，包含：`document_id`、`block_id`、`file_token`、`file_name`（剪切板路径下为 `clipboard.png`）、`type`。
|
||||
|
||||
> [!CAUTION]
|
||||
> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
41
.claude/skills/lark-doc/references/lark-doc-media-preview.md
Normal file
41
.claude/skills/lark-doc/references/lark-doc-media-preview.md
Normal file
@ -0,0 +1,41 @@
|
||||
|
||||
# docs +media-preview（预览文档素材）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。
|
||||
|
||||
## 选择规则
|
||||
|
||||
- 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview`
|
||||
- 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md)
|
||||
- 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard`
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 预览图片/文件素材
|
||||
lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset
|
||||
|
||||
# 指定输出文件名（带扩展名则不会自动补全）
|
||||
lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset.png
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--token <token>` | 是 | 素材 token，即 `file_token` |
|
||||
| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
|
||||
|
||||
## token 从哪里来
|
||||
|
||||
- 若你是从文档内容里提取：`lark-doc-fetch` 返回的内容里可能包含：
|
||||
- 图片：`<img token="..." .../>`
|
||||
- 文件：`<source token="..." name="..."/>`
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
|
||||
- [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
128
.claude/skills/lark-doc/references/lark-doc-mindnote.md
Normal file
128
.claude/skills/lark-doc/references/lark-doc-mindnote.md
Normal file
@ -0,0 +1,128 @@
|
||||
# 飞书思维笔记（Mindnote）
|
||||
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 和 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和路由规则。
|
||||
|
||||
当用户要操作思维笔记时，入口属于 `lark-doc`，但实际执行命令使用 `lark-cli mindnotes nodes list/create`，不是 `docs +...`。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 当前这条链路只支持**读取已有思维笔记**，以及在**已有思维笔记**里读取节点、创建子节点。
|
||||
> `mindnotes nodes create` 是新增/更新节点命令，**不是**新建一个新的思维笔记。
|
||||
> 如果用户要**新建思维笔记**，不要走本链路，改走 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
|
||||
|
||||
## 获取 `mindnote_id`
|
||||
|
||||
`--mindnote-id` 传 **Mindnote 文档 token**，不是节点 ID。`lark-cli mindnotes` 只负责读取和写入思维笔记内部节点。
|
||||
|
||||
```bash
|
||||
# 用户给了 Mindnote URL，或给了可能包着 Mindnote 的 Wiki URL
|
||||
lark-cli drive +inspect --url "<mindnote_or_wiki_url>"
|
||||
```
|
||||
|
||||
处理规则：
|
||||
|
||||
- 普通 Mindnote URL：`drive +inspect` 返回的 Mindnote token 可作为 `--mindnote-id`。
|
||||
- Wiki URL：不要把 `/wiki/` 路径里的 wiki token 当作 `--mindnote-id`；必须先 `drive +inspect` 解包，确认底层类型是 `mindnote` 后再使用返回的真实 token。直接把 wiki token 传给 `mindnotes nodes list` 通常会返回 `3410003 resource not found`。
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 先看命令帮助
|
||||
lark-cli mindnotes nodes list --help
|
||||
lark-cli mindnotes nodes create --help
|
||||
|
||||
# 读取节点列表
|
||||
lark-cli mindnotes nodes list --mindnote-id "<mindnote_token>"
|
||||
|
||||
# 创建子节点
|
||||
lark-cli mindnotes nodes create \
|
||||
--mindnote-id "<mindnote_token>" \
|
||||
--data '{"client_token":"<client_token>","nodes":[{"parent_id":"node_parent123","texts":[{"element_type":"text","text":{"content":"子节点内容"}}],"highlight":"yellow","finish":false}]}'
|
||||
|
||||
# 更新已有节点
|
||||
lark-cli mindnotes nodes create \
|
||||
--mindnote-id "<mindnote_token>" \
|
||||
--data '{"client_token":"<client_token>","nodes":[{"node_id":"node_existing123","texts":[{"element_type":"text","text":{"content":"更新后的节点内容"}}],"highlight":"blue","finish":true}]}'
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
### `mindnotes nodes list`
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--mindnote-id` | 是 | 思维笔记 token / 唯一标识 |
|
||||
|
||||
返回重点：`data.nodes` 中常见字段有 `node_id`、`parent_id`、`texts`、`notes`、`images`、`finish`、`highlight`。
|
||||
|
||||
### `mindnotes nodes create`
|
||||
|
||||
命令参数：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--mindnote-id` | 是 | 思维笔记 token / 唯一标识 |
|
||||
| `--data` | 是 | JSON 请求体 |
|
||||
|
||||
请求体字段：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `client_token` | 否 | 幂等 token，建议写操作传入；推荐使用时间戳或 UUID |
|
||||
| `nodes` | 是 | 待创建或更新的节点数组 |
|
||||
| `nodes[].node_id` | 否 | 节点 ID；传入已有 `node_id` 时表示更新对应节点 |
|
||||
| `nodes[].parent_id` | 否 | 父节点 ID；创建子节点时传入 |
|
||||
| `nodes[].texts` | 否 | 节点正文富文本数组 |
|
||||
| `nodes[].notes` | 否 | 节点备注富文本数组 |
|
||||
| `nodes[].images` | 否 | 节点图片列表 |
|
||||
| `nodes[].highlight` | 否 | `red` / `yellow` / `pink` / `blue` / `cyan` / `olive` / `grey` |
|
||||
| `nodes[].finish` | 否 | 节点完成状态 |
|
||||
|
||||
富文本字段 `texts` / `notes` 是元素数组。最常见的是：
|
||||
|
||||
```json
|
||||
[{"element_type":"text","text":{"content":"节点内容"}}]
|
||||
```
|
||||
|
||||
### 节点图片（`nodes[].images`）
|
||||
|
||||
`nodes[].images` 接收的是**图片 token**，不是本地文件路径，也不是 URL。
|
||||
|
||||
```bash
|
||||
# 先上传图片，拿到 token
|
||||
lark-cli docs +media-upload --file ./image.png --parent-type mindnote_image --parent-node <mindnote_token>
|
||||
|
||||
# 再把 token 写进节点
|
||||
lark-cli mindnotes nodes create \
|
||||
--mindnote-id "<mindnote_token>" \
|
||||
--data '{"client_token":"<client_token>","nodes":[{"node_id":"node_existing123","images":[{"token":"canonical_token"}]}]}'
|
||||
```
|
||||
|
||||
参数说明：
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--file` | 是 | 本地图片路径 |
|
||||
| `--parent-type` | 是 | 上传目标类型；图片使用 `mindnote_image` |
|
||||
| `--parent-node` | 是 | 传 Mindnote 的 token |
|
||||
| `nodes[].images[].token` | 是 | 上传后返回的图片 token |
|
||||
|
||||
## 推荐工作流
|
||||
|
||||
1. 先判断用户目标是不是“新建一个思维笔记”。
|
||||
2. 如果是新建思维笔记，切到 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
|
||||
3. 如果是操作已有思维笔记，先按上方「获取 `mindnote_id`」确认已拿到 Mindnote 文档 token。
|
||||
4. 确认目标类型是 **Mindnote** 后，把真实 Mindnote token 作为 `--mindnote-id`。
|
||||
5. 先执行 `mindnotes nodes list`，确认目标 `parent_id`。
|
||||
6. 新增子节点时，在 `nodes[]` 里传 `parent_id`；更新已有节点时，在 `nodes[]` 里传已有 `node_id`。
|
||||
7. 再执行 `mindnotes nodes create`。
|
||||
8. 写操作优先带 `client_token`，推荐使用时间戳或 UUID，避免重试时重复创建或重复更新。
|
||||
|
||||
> [!CAUTION]
|
||||
> `mindnotes nodes create` 是写操作。创建时确认插入位置，更新时确认 `node_id` 指向的就是目标节点。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容
|
||||
- [lark-doc-whiteboard](lark-doc-whiteboard.md) — 新建思维笔记走画板链路
|
||||
- [lark-drive](../../lark-drive/SKILL.md) — 解析 Mindnote / Wiki 等云空间资源
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
@ -0,0 +1,70 @@
|
||||
# docs +resource-*（Docx 封面图资源）
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
Docx 封面图不是正文里的 `<img token="...">` 素材块。读取、更新、删除文档封面图时，使用 `docs +resource-download/+resource-update/+resource-delete --type cover`，不要使用 `+media-insert` 或 `+media-download --token <cover.token>` 让用户手动拼步骤。
|
||||
|
||||
## 选择规则
|
||||
|
||||
- 用户要下载文档封面图：`docs +resource-download --type cover`
|
||||
- 用户要设置/替换文档封面图：`docs +resource-update --type cover`
|
||||
- 用户要删除文档封面图：`docs +resource-delete --type cover`
|
||||
- 用户要下载正文图片、附件、画板缩略图：继续使用 [`docs +media-download`](lark-doc-media-download.md)
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 下载封面图。CLI 会先读取 document.cover.token，再下载图片内容并保存到本地。
|
||||
lark-cli docs +resource-download --doc doxcnXXX --type cover --output ./cover
|
||||
|
||||
# 使用本地文件更新封面图。
|
||||
lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png
|
||||
|
||||
# 使用剪切板图片更新封面图。
|
||||
lark-cli docs +resource-update --doc doxcnXXX --type cover --from-clipboard
|
||||
|
||||
# 使用 HTTPS URL 更新封面图。CLI 会先下载 URL 内容，再上传并写入 cover.token。
|
||||
lark-cli docs +resource-update --doc doxcnXXX --type cover --url "https://example.com/cover.png"
|
||||
|
||||
# 可选：设置封面图裁切偏移。
|
||||
lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png --offset-ratio-x 0.2 --offset-ratio-y 0.8
|
||||
|
||||
# 删除封面图；当文档本来没有封面图时也成功返回。
|
||||
lark-cli docs +resource-delete --doc doxcnXXX --type cover
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 命令 | 参数 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| all | `--doc <id>` | 是 | 文档 ID、docx URL，或可解析为 docx 的 wiki URL |
|
||||
| all | `--type cover` | 否 | 当前只支持 `cover`；默认值也是 `cover` |
|
||||
| download | `--output <path>` | 是 | 本地保存路径；不带扩展名会根据响应类型自动补全 |
|
||||
| download | `--overwrite` | 否 | 覆盖已存在的输出文件 |
|
||||
| update | `--file <path>` | 三选一 | 磁盘上的真实图片文件；大于 20MiB 自动使用分片上传 |
|
||||
| update | `--from-clipboard` | 三选一 | 从系统剪切板读取图片 |
|
||||
| update | `--url <https-url>` | 三选一 | 从 HTTPS URL 下载图片后上传 |
|
||||
| update | `--offset-ratio-x <number>` | 否 | 视图相对原图中心的横向偏移比例：水平偏移 px / 原图宽度 px；0 为居中，正数向右，负数向左 |
|
||||
| update | `--offset-ratio-y <number>` | 否 | 视图相对原图中心的纵向偏移比例：垂直偏移 px / 原图高度 px；0 为居中，正数向上，负数向下 |
|
||||
|
||||
## 输出契约
|
||||
|
||||
- `+resource-download` 成功时 stdout JSON 的 `data` 包含 `document_id`、`type`、`saved_path`、`size_bytes`、`content_type`、`cover.token`。如果文档没有封面图，命令失败退出，错误包含 `document has no cover` 和脱敏 `document_id`，不会创建输出文件。
|
||||
- `+resource-update` 成功时 stdout JSON 的 `data` 包含完整 `file_token` 和 `cover.token`；stderr 只打印脱敏 token。
|
||||
- `+resource-delete` 成功时 stdout JSON 的 `data.deleted` 表示本次是否真的发起删除，`data.already_empty` 表示删除前是否没有封面图。空封面图是幂等成功，不报错。
|
||||
|
||||
## URL 来源安全边界
|
||||
|
||||
`+resource-update --url` 只用于下载公开 HTTPS 图片：
|
||||
|
||||
- 只允许 `https://`，拒绝 HTTP、空 host 和 URL userinfo。
|
||||
- 拒绝解析到 private、loopback、link-local、multicast、unspecified 地址的 host。
|
||||
- 最多跟随 3 次跳转，每次跳转都重新校验 URL。
|
||||
- 响应 `Content-Type` 只允许 `image/png`、`image/jpeg`、`image/gif`、`image/webp`。
|
||||
- 响应体最大 20MiB。
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-doc-media-download](lark-doc-media-download.md) — 下载正文素材或画板缩略图
|
||||
- [lark-doc-media-insert](lark-doc-media-insert.md) — 在正文插入图片/文件
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
260
.claude/skills/lark-doc/references/lark-doc-update.md
Normal file
260
.claude/skills/lark-doc/references/lark-doc-update.md
Normal file
@ -0,0 +1,260 @@
|
||||
|
||||
# docs +update（更新飞书云文档）
|
||||
|
||||
> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
|
||||
> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
|
||||
> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
|
||||
> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
|
||||
>
|
||||
> **未读完以上文件就生成内容会导致格式错误。**
|
||||
|
||||
通过八种指令精确更新飞书云文档。支持字符串级别和 block 级别的操作。
|
||||
|
||||
> **⚠️ 格式选择规则：**
|
||||
> - **局部精修**（`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after`）：优先使用 XML（默认）。XML 能稳定表达 block 结构和样式，精准编辑更可控；不要因为 Markdown 写起来更简单就自行切换。
|
||||
> - **整段写入**（`append` / `overwrite`）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件或明确要求 Markdown 时直接用 Markdown；否则默认 XML。
|
||||
>
|
||||
> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--doc` | 是 | 文档 URL 或 token |
|
||||
| `--command` | 是 | 操作指令（见下方指令速查表） |
|
||||
| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
|
||||
| `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除） |
|
||||
| `--reference-map` | 否 | 结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。 |
|
||||
| `--pattern` | 视指令 | 匹配文本（str_replace） |
|
||||
| `--block-id` | 视指令 | 目标 block ID（block_* 操作），逗号分隔可批量删除，-1 表示末尾 |
|
||||
| `--src-block-ids` | 视指令 | 源 block ID（逗号分隔），用于 block_copy_insert_after / block_move_after |
|
||||
| `--revision-id` | 否 | 基准版本号，-1 = 最新（默认 `-1`） |
|
||||
|
||||
## 指令速查表
|
||||
|
||||
| 指令 | 说明 | 必需参数 |
|
||||
|------|------|----------|
|
||||
| `str_replace` | 全文文本查找替换（replacement 支持富文本标签；`--content` 传空字符串即为删除） | `--pattern` `--content` |
|
||||
| `block_insert_after` | 在指定 block 之后插入新内容 | `--block-id` `--content` |
|
||||
| `block_copy_insert_after` | 复制源 block 并插入到锚点之后（源块不变） | `--block-id` `--src-block-ids` |
|
||||
| `block_replace` | 替换指定 block（同一 block 仅限一次） | `--block-id` `--content` |
|
||||
| `block_delete` | 删除指定 block（逗号分隔可批量） | `--block-id` |
|
||||
| `overwrite` | ⚠️ 清空文档后全文重写（可能丢失图片、评论） | `--content` |
|
||||
| `append` | ⚠️ 在文档**末尾**追加内容（等价于 `block_insert_after --block-id -1`）。**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` |
|
||||
| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` |
|
||||
|
||||
## Block ID 生命周期
|
||||
|
||||
写操作后不要默认复用之前 fetch 到的 block ID：
|
||||
|
||||
- `overwrite` / `block_replace` / `block_delete`：受影响旧 ID 失效，继续 block 级操作前重新 fetch
|
||||
- `block_insert_after` / `append` / `block_copy_insert_after`：锚点 / 源 ID 通常保留，新内容是新 ID；要操作新内容先重新 fetch
|
||||
- `block_move_after`：被移动 ID 通常保留，但位置、章节、range 语义变化；后续依赖位置时重新 fetch
|
||||
- `str_replace`：简单行内替换通常不改变 ID；跨行 / 大段替换后如继续 block 级操作，先重新 fetch
|
||||
|
||||
## 指令示例
|
||||
|
||||
### str_replace — 全文文本替换
|
||||
|
||||
> **匹配范围：**
|
||||
> - **XML 模式（默认）**：`--pattern` 只支持**行内匹配**，不能跨 block / 跨段落匹配。涉及整段或多 block 的改动，请改用 `block_replace`。
|
||||
> - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行匹配**，可以用多行字符串匹配并替换一整段内容。
|
||||
> - 还支持**`前缀...后缀` 省略号语法**：用 `...`（三个英文句点）串联起始与结束片段，匹配从前缀到后缀之间的全部内容（含中间被省略部分）。适合一段很长、但首尾特征明显的文本，避免把整段都塞进 `--pattern`。
|
||||
> - 前缀、后缀本身仍遵循 Markdown 转义规则；省略号中间的内容**会被替换**为 `--content` 的完整文本，不会被保留。
|
||||
|
||||
```bash
|
||||
# 简单文本替换
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--pattern "张三" --content "李四"
|
||||
|
||||
# 替换为富文本（加粗 + 链接）
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--pattern "旧链接" --content '<b>新链接</b> <a href="https://example.com">点击查看</a>'
|
||||
|
||||
# 仅当用户明确要求时才使用 Markdown
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--doc-format markdown --pattern "旧内容" --content "新内容"
|
||||
|
||||
# Markdown 模式下支持跨行匹配（--pattern 与 --content 都需要真实换行；"..."/'...' 里的 \n 是字面量）
|
||||
# 多行内容推荐 heredoc 或 --content @file.md，避免 shell 转义踩坑
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--doc-format markdown \
|
||||
--pattern "$(printf '## 旧标题\n\n第一段原文\n\n第二段原文')" \
|
||||
--content - <<'EOF'
|
||||
## 新标题
|
||||
|
||||
改写后的第一段
|
||||
|
||||
改写后的第二段
|
||||
EOF
|
||||
|
||||
# Markdown 模式下使用 `前缀...后缀` 省略号匹配首尾特征明显的大段内容
|
||||
# 下例会把「## 旧标题」到「结束语。」之间的所有内容整体替换
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--doc-format markdown \
|
||||
--pattern "## 旧标题...结束语。" \
|
||||
--content - <<'EOF'
|
||||
## 新标题
|
||||
|
||||
重写后的正文...
|
||||
|
||||
新的结束语。
|
||||
EOF
|
||||
|
||||
# 删除文本：--content 传空字符串即可
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--pattern "废弃的内容" --content ""
|
||||
```
|
||||
|
||||
### block_insert_after — 在指定 block 之后插入
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
|
||||
--block-id "目标 block_id" \
|
||||
--content '<h2>新章节</h2><ul><li>要点 1</li><li>要点 2</li></ul>'
|
||||
```
|
||||
|
||||
### block_replace — 替换指定 block
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_replace \
|
||||
--block-id "目标 block_id" \
|
||||
--content '<p>替换后的段落内容</p>'
|
||||
```
|
||||
|
||||
### block_delete — 删除指定 block
|
||||
|
||||
```bash
|
||||
# 删除多个块时用逗号 "," 分隔
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_delete \
|
||||
--block-id "block_id_1,block_id_2,block_id_3"
|
||||
```
|
||||
|
||||
### overwrite — 全文覆盖
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --doc "<doc_id>" --command overwrite \
|
||||
--content '<title>全新文档</title><h1>概述</h1><p>新的内容</p>'
|
||||
```
|
||||
|
||||
> ⚠️ 会清空文档后重写，可能丢失图片、评论等。仅在需要完全重建文档时使用。
|
||||
|
||||
### append — 在文档末尾追加
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --doc "<doc_id>" --command append \
|
||||
--content '<h2>新增章节</h2><p>追加的内容</p>'
|
||||
```
|
||||
|
||||
> 等价于 `block_insert_after --block-id -1`，无需先获取 block ID。
|
||||
|
||||
### block_copy_insert_after — 复制块并插入
|
||||
|
||||
将一个或多个源块复制到锚点块之后，源块保持不变。`--src-block-ids` 为逗号分隔的源块 ID，按顺序依次插入到锚点之后。
|
||||
|
||||
```bash
|
||||
# 复制多个块（按顺序插入：anchor → a → b → c）
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_copy_insert_after \
|
||||
--block-id "锚点 block_id" \
|
||||
--src-block-ids "block_a,block_b,block_c"
|
||||
```
|
||||
|
||||
### block_move_after — 移动已有 block
|
||||
|
||||
将文档中已有的 block 移动到指定锚点之后。使用 `--src-block-ids` 指定要移动的块 ID，无需 `--content`。
|
||||
|
||||
```bash
|
||||
# 移动到页面末尾
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_move_after \
|
||||
--block-id "-1表示末尾，page_id表示开头，blk" \
|
||||
--src-block-ids "block_a,block_b"
|
||||
```
|
||||
|
||||
## 返回值
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"identity": "user",
|
||||
"data": {
|
||||
"document": {
|
||||
"revision_id": 13,
|
||||
"new_blocks": [
|
||||
{ "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
|
||||
]
|
||||
},
|
||||
"result": "success",
|
||||
"updated_blocks_count": 3,
|
||||
"warnings": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `result` | `success` \| `partial_success` \| `failed` |
|
||||
| `updated_blocks_count` | 实际更新的 block 数量 |
|
||||
| `warnings` | 警告信息列表 |
|
||||
| `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |
|
||||
|
||||
## 典型工作流
|
||||
|
||||
### 精确 block 级更新
|
||||
|
||||
1. **获取文档内容和 block ID**：
|
||||
```bash
|
||||
lark-cli docs +fetch --doc "<doc_id>" --detail with-ids
|
||||
```
|
||||
|
||||
2. **定位目标 block**：从返回的 XML 中找到要修改的 block 及其 `id` 属性
|
||||
|
||||
3. **执行更新**：
|
||||
```bash
|
||||
# 替换特定 block
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_replace \
|
||||
--block-id "blkcnXXXX" --content "<p>新内容</p>"
|
||||
|
||||
# 在某 block 后插入
|
||||
lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
|
||||
--block-id "blkcnXXXX" --content "<h2>追加的章节</h2>"
|
||||
```
|
||||
|
||||
### 简单文本替换
|
||||
|
||||
不需要 block ID，直接匹配替换：
|
||||
|
||||
```bash
|
||||
lark-cli docs +update --doc "<doc_id>" --command str_replace \
|
||||
--pattern "v1.0" --content "v2.0"
|
||||
```
|
||||
|
||||
## 画板处理
|
||||
|
||||
> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
|
||||
|
||||
画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- **精确操作优于全文覆盖**：使用 `block_replace`/`block_insert_after` 精确修改，避免 `overwrite` 全文覆盖
|
||||
- **str_replace 的匹配范围取决于格式**：
|
||||
- **XML 模式（默认）**：`--pattern` 只支持**行内**匹配，不支持跨行 / 跨 block。段落、整块或容器级（列表、表格、分栏、引用块等）改动请改用 `block_replace` 指定 block_id 重建。
|
||||
- **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行**匹配，还支持 `前缀...后缀` 省略号语法（用 `...` 串联首尾片段匹配一大段内容），可以一次替换多行文本；但仍建议优先按最小片段匹配，跨 block 容器级重写仍优先用 `block_replace`，避免副作用。
|
||||
- **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block
|
||||
- **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本
|
||||
- **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace
|
||||
- **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除
|
||||
- **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：
|
||||
1. 用 `block_insert_after` 在目标位置插入新的富文本结构
|
||||
2. 用 `block_delete` 批量删除旧的 block
|
||||
3. 这样可以保留文档中其他不相关的内容（图片、评论等）
|
||||
- **表达形式**：插入或替换内容时，优先沿用用户要求和已有文档风格；需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要为了固定丰富度主动添加组件
|
||||
|
||||
## 参考
|
||||
|
||||
- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
|
||||
- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
|
||||
- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
|
||||
- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
|
||||
- [`lark-doc-create.md`](lark-doc-create.md) — 创建文档
|
||||
- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
|
||||
159
.claude/skills/lark-doc/references/lark-doc-whiteboard.md
Normal file
159
.claude/skills/lark-doc/references/lark-doc-whiteboard.md
Normal file
@ -0,0 +1,159 @@
|
||||
# lark-doc 画板处理指南
|
||||
|
||||
> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
## 两个 Skill 的职责边界
|
||||
|
||||
| Skill | 核心职责 | 约束 |
|
||||
|-------------------|-----------------------------------------------------------|---------------------------------|
|
||||
| `lark-doc` | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容； |
|
||||
| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |
|
||||
|
||||
## 画板适用规则
|
||||
|
||||
写文档时，核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，如果图示能明显降低理解成本，可以规划为画板；结构简单或文字更清楚的内容不必强行画板化。
|
||||
|
||||
同一篇文档可以有多个画板。确有多个独立图示点时，可拆成多个聚焦画板，而不是把所有信息塞进一张大图。
|
||||
|
||||
## 文档与画板协同流程
|
||||
|
||||
### 步骤 1：识别画板机会
|
||||
|
||||
| 场景 | 入口 |
|
||||
|-------------------------|-----------------------------------------------------------|
|
||||
| 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表 |
|
||||
| 文档中需要插入其他图表/自定义图形 | 步骤 2B: 使用 SVG 插入图表 |
|
||||
| 已有画板需要更新内容 | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3B |
|
||||
| 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ⚠️ **分别对每个图表进行决策**
|
||||
|
||||
如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B
|
||||
中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动
|
||||
SubAgent 插入 SVG。
|
||||
|
||||
建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表
|
||||
|
||||
### 步骤 2A: 使用 mermaid 插入图表
|
||||
|
||||
```xml
|
||||
|
||||
<whiteboard type="mermaid">
|
||||
mermaid 代码...
|
||||
</whiteboard>
|
||||
```
|
||||
|
||||
如果 Mermaid 已在本地文件中，可写成 `<whiteboard type="mermaid" path="@diagram.mmd"></whiteboard>`；CLI 会在写入前读取文件并展开为内联内容。
|
||||
|
||||
### 步骤 2B: SubAgent 使用 SVG 插入图表
|
||||
|
||||
主 Agent 启动 SubAgent，让它用 `docs +create` / `docs +update` 插入：
|
||||
|
||||
```xml
|
||||
|
||||
<whiteboard type="svg">
|
||||
<svg...>...
|
||||
</svg>
|
||||
</whiteboard>
|
||||
```
|
||||
|
||||
如果 SVG 已在本地文件中，可写成 `<whiteboard type="svg" path="@diagram.svg"></whiteboard>`；PlantUML 文件同理使用 `<whiteboard type="plantuml" path="@sequence.puml"></whiteboard>`。
|
||||
|
||||
Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：
|
||||
|
||||
- doc token、插入位置（标题 / block_id / command）
|
||||
- 图表目标、受众、源段落或数据
|
||||
- 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`
|
||||
- SVG 必须完整自包含：包含 `<svg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源
|
||||
|
||||
#### 画板 SVG 设计指南
|
||||
|
||||
使用 SVG 插入画板时，最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
|
||||
**核心心智纠正 (重要)**：
|
||||
|
||||
- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, *
|
||||
*这将被视为不及格！**
|
||||
- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀,
|
||||
大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！
|
||||
|
||||
##### SVG 设计 Workflow
|
||||
|
||||
###### 1. 想清楚要画什么
|
||||
|
||||
- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
|
||||
- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
|
||||
- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构
|
||||
|
||||
###### 2. 写 SVG
|
||||
|
||||
> [!IMPORTANT]
|
||||
> 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
|
||||
> 操作边界约束：
|
||||
|
||||
- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
|
||||
- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
|
||||
- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
|
||||
- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲
|
||||
|
||||
###### 画板怎么处理 SVG
|
||||
|
||||
画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但非阴影用途的
|
||||
`<filter>` / `<pattern>` / `<clipPath>` / `<mask>` 等装饰特性画板不支持（见下方⚠️）
|
||||
**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
|
||||
|
||||
**可识别的元素**
|
||||
|
||||
- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
|
||||
- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
|
||||
- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
|
||||
- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
|
||||
- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
|
||||
- 阴影：`<filter>` 里放 `<feDropShadow>` 或标准 drop/inner primitive 链 (`<feGaussianBlur in="SourceAlpha">` + `<feOffset>` + `<feFlood>` + `<feComposite>` + `<feMerge>`), 会被识别成节点阴影, drop 至多 1 个, inner 至多 1 个; 其余 filter 效果不识别
|
||||
- 渐变：`<linearGradient>` / `<radialGradient>` 在 `<defs>` 中定义, 通过 `fill="url(#id)"` 引用 (载体限 `<rect>` / `<circle>` / `<ellipse>` / `<polygon>` / `<path>`), 需要至少 2 个 `<stop>`, `gradientUnits` 只支持默认的 `objectBoundingBox` (不写即可)
|
||||
|
||||
> [!IMPORTANT]
|
||||
> ⚠️ **不支持的装饰特性**
|
||||
|
||||
- `<pattern>` / `<clipPath>` / `<mask>` / 非阴影用途的 `<filter>` (blur / hue-rotate / 复合合成 / `flood-color=url(...)` / 多个 `<feDropShadow>` 等) → 画板不支持，**请避免使用，否则会导致画板渲染问题**
|
||||
- 渐变边界：`gradientUnits="userSpaceOnUse"` / `spreadMethod="reflect|repeat"` / stops 少于 2 个 / 复杂 `gradientTransform` 会变成不可编辑图片, 视觉正确但失去可编辑性, 若无必要请沿用默认 `objectBoundingBox`
|
||||
|
||||
###### 3.插入后审查
|
||||
|
||||
插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png
|
||||
图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 [
|
||||
`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。
|
||||
|
||||
```bash
|
||||
lark-cli whiteboard +export \
|
||||
--whiteboard-token "wbcnxxxxxxxx" \
|
||||
--output-type preview \
|
||||
--output ./preview.png
|
||||
```
|
||||
|
||||
### 步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent
|
||||
|
||||
复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。
|
||||
|
||||
复杂图 SubAgent 的最小上下文：
|
||||
|
||||
- board_token
|
||||
- 图表目标、推荐画板类型、受众
|
||||
- 与图表直接相关的源段落或数据
|
||||
- 要求读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，按其完整流程写入该 board_token
|
||||
|
||||
多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。
|
||||
|
||||
### 步骤 4：完成校验
|
||||
|
||||
- Mermaid: 确认插入的是 `<whiteboard type="mermaid">`，且内容 mermaid 语法完整
|
||||
- SVG: 确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
|
||||
- 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成
|
||||
|
||||
---
|
||||
|
||||
---
|
||||
|
||||
## 关联参考
|
||||
|
||||
- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)
|
||||
93
.claude/skills/lark-doc/references/lark-doc-word-stat.md
Normal file
93
.claude/skills/lark-doc/references/lark-doc-word-stat.md
Normal file
@ -0,0 +1,93 @@
|
||||
# 文档统计：总字数 / 总字符数
|
||||
|
||||
当用户需要统计 Docx / Wiki 文档的总字数或总字符数时，使用本 skill 附带脚本 `scripts/doc_word_stat.py`。统计口径以该脚本为准，不要改用其他方式自行计算，也不要只读取 simple 摘要后统计。
|
||||
|
||||
## 调用方式
|
||||
|
||||
在线文档使用 XML full 内容，并让脚本读取 `docs +fetch --format json` 的 envelope：
|
||||
|
||||
```bash
|
||||
lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
|
||||
| python3 skills/lark-doc/scripts/doc_word_stat.py --protocol xml --lark-json --pretty
|
||||
```
|
||||
|
||||
`$URL` 可以是用户给出的 docx/wiki URL，也可以是可被 `docs +fetch` 解析的 token。
|
||||
|
||||
## 统计范围
|
||||
|
||||
先判断用户要求的是**整篇文档**还是**局部内容**：
|
||||
|
||||
- 整篇文档的总字数 / 总字符数：按上方「调用方式」抓取 `full` 内容后统计。
|
||||
- 本次新增 / 替换 / 改写片段的字数：优先统计拟写内容本身；内容已写入文档时，只 fetch 对应 block / range 后统计。不得用整篇文档字数对比局部目标。
|
||||
|
||||
如需在自动化或回归验证中发现未覆盖块类型，追加严格参数：
|
||||
|
||||
```bash
|
||||
lark-cli docs +fetch --doc "$URL" --doc-format xml --detail full --format json \
|
||||
| python3 skills/lark-doc/scripts/doc_word_stat.py --protocol xml --lark-json --pretty --fail-on-unsupported --fail-on-unknown
|
||||
```
|
||||
|
||||
## 如何读取结果
|
||||
|
||||
脚本输出 JSON。对用户汇报时默认只读两个核心字段：
|
||||
|
||||
- `word_count`：总字数。按语义单位统计汉字、英文单词/URL/code path、数字、中文标点；普通贴着英文的英文标点不计入，但独立 ASCII 符号、中文之间的 `/` 等以脚本结果为准。
|
||||
- `char_count`：总字符数。统计汉字、英文字母、数字、中英文标点和脚本识别的可见符号；空格不计入。
|
||||
|
||||
其余字段用于排查或解释：
|
||||
|
||||
- `breakdown`：拆分统计来源，例如 `han_chars`、`english_words`、`digits`、`chinese_punctuations`。
|
||||
- `unknown_blocks`：脚本遇到未知 XML/Markdown 块类型；通常表示需要扩展解析规则。
|
||||
- `unsupported_blocks`：脚本识别到块类型，但当前无法可靠提取可见文本。
|
||||
- `diagnostics.has_unknown` / `diagnostics.has_unsupported`：快速判断统计是否存在覆盖风险。
|
||||
|
||||
如果 `unknown_blocks` 或 `unsupported_blocks` 非空，回复用户时要说明“已统计可提取文本，但存在未覆盖块，结果可能偏低”，并列出对应块类型。为空时可直接给出结果。
|
||||
|
||||
## 字数遵循校验
|
||||
|
||||
当用户给了明确字数要求（写 N 字 / x-y 字 / x 字左右 / 上下浮动）时执行；没有明确字数要求则跳过。字数必须按本文流程用脚本统计，不要自己估。
|
||||
|
||||
1. 先按「统计范围」确认统计对象，再把要求归一成目标区间：`>x`→`[x+1, +∞)`；`<y`→`(-∞, y-1]`；`x-y`→`[x, y]`；`x 字左右`→`[round(0.9x), round(1.1x)]`
|
||||
2. 按统计对象选择对应输入并调用脚本统计实际字数，读取输出里的 `word_count`
|
||||
3. 对比 `word_count` 与目标区间：区间内即通过；低于下限 → 补充**实质内容**（非注水）；高于上限 → 删减冗余内容。改完重新统计
|
||||
4. **最多 2 轮**。2 轮后仍不达标：停止，不得为达标而注水或删关键内容；如实汇报【目标区间 / 当前字数 / 差值与方向 / 已试 2 轮 / 未达原因】，**禁止谎称达标**
|
||||
|
||||
## 输出示例
|
||||
|
||||
输入正文等价于：`标题` + `一个苹果是 an apple。` 时，输出形态如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"word_count": 10,
|
||||
"char_count": 15,
|
||||
"breakdown": {
|
||||
"han_chars": 7,
|
||||
"english_words": 2,
|
||||
"number_words": 0,
|
||||
"chinese_punctuations": 1,
|
||||
"english_letters": 7,
|
||||
"digits": 0,
|
||||
"english_punctuations": 0,
|
||||
"symbol_words": 0,
|
||||
"symbol_chars": 0
|
||||
},
|
||||
"protocol": "xml",
|
||||
"unknown_blocks": [],
|
||||
"unsupported_blocks": [],
|
||||
"diagnostics": {
|
||||
"has_unknown": false,
|
||||
"has_unsupported": false,
|
||||
"types": {},
|
||||
"unknown_types": {},
|
||||
"unsupported_types": {},
|
||||
"actions": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
面向用户的回复可简化为：
|
||||
|
||||
```text
|
||||
总字数：10
|
||||
总字符数：15
|
||||
```
|
||||
@ -0,0 +1,76 @@
|
||||
# XML 扩展块补充说明
|
||||
|
||||
本文件用于补充说明 block XML 扩展能力。常用标签和通用规则见 [`lark-doc-xml.md`](lark-doc-xml.md)；后续新增其他 block 说明时可继续追加到本文件。
|
||||
|
||||
## HTML5 block
|
||||
|
||||
1. 写入 HTML 内容块时，把完整单文件 HTML 存为本地 `.html` 文件，XML 写 `<html5-block path="@widget.html"></html5-block>`；已有 `data-ref` 时配合 `--reference-map @reference-map.json`。读取时 `<html5-block data-ref="html5_1"></html5-block>` 只是占位，必须从 `document.reference_map["html5-block"]["html5_1"].data` 读取 HTML；若 entry 是 `path`，读取对应 `@doc-fetch-resources/...html` 文件。
|
||||
2. 格式如下：
|
||||
|
||||
```html
|
||||
<!doctype html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<meta name="use-iframe" content="true">
|
||||
<meta name="html-box-height-mode" content="auto">
|
||||
<meta name="description" content="内容摘要，会导出为 html5-block 的 alt 属性，帮助模型理解该 HTML 块的用途">
|
||||
<title></title>
|
||||
</head>
|
||||
<body>
|
||||
...
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### 布局与高度
|
||||
|
||||
- `lark-cli` 会读取 `.html` 文件并原样写入 `reference_map`，不会解析或校验 `html-box-height-mode`；创建或更新文档前在 `<head>` 中显式声明 `auto` 或 `viewport`。
|
||||
- 生成时只使用 `auto` 或 `viewport`，不要臆造 `fixed`、`initial` 或像素值等其他 mode。
|
||||
- 文档常见可用宽度约 `820px`；根容器使用 `width: 100%`、`max-width: 100%`、`box-sizing: border-box`。
|
||||
|
||||
四种策略：
|
||||
|
||||
1. 内容自然撑开：`auto` + 普通文档流；根容器不设固定高度或 `overflow: hidden`。
|
||||
2. 仅按初始内容定高：`auto` + 首次渲染后不再追加或展开内容。
|
||||
3. 固定像素操作区：`auto` + 业务容器按场景设置固定的 CSS `height` 和 `overflow: auto`；高度数值不写进 meta。
|
||||
4. 单屏应用：`viewport` + `100vh` + 内部滚动、切页或缩放；适用于游戏、幻灯片、Dashboard、canvas 编辑器。
|
||||
|
||||
正文需要在飞书文档中完整展开时选 `auto`；内容应在 HTML Block 内滚动时选 `viewport`。`lark-cli` 不参与页面加载后的高度刷新，不要臆造相关 CLI flag。
|
||||
|
||||
### 内容限制
|
||||
|
||||
- HTML 总长度上限为 500KB。不要内联大图片、Base64、字体、长 JSON/CSV 或大量 mock 数据。
|
||||
|
||||
## OKR block
|
||||
|
||||
OKR block 可用 XML 格式完整表达。创建前先参考 [`lark-okr`](../../lark-okr/SKILL.md) 确认可用周期；创建时只写 root-only `<okr cycle-id="..."/>` 挂载已有 OKR，不构造 Objective/KR/Progress 子树。
|
||||
|
||||
获取时，XML 结构示例如下：
|
||||
|
||||
```xml
|
||||
<okr cycle-id="" cycle-name="CYCLE_NAME" user-name="USER_NAME">
|
||||
<okr-objective objective-id="OBJECTIVE_ID" status="normal" percent="80" score="75">
|
||||
<p>O 描述</p>
|
||||
<okr-progress>
|
||||
<p>O 进展</p>
|
||||
<checkbox done="true">事项</checkbox>
|
||||
<ul><li>列表项内可包含 <a href="https://example.com">链接</a></li></ul>
|
||||
</okr-progress>
|
||||
<okr-key-result key-result-id="KEY_RESULT_ID" status="risk" percent="60" score="80">
|
||||
<p>KR 描述</p>
|
||||
<okr-progress>
|
||||
<p>KR 进展</p>
|
||||
</okr-progress>
|
||||
</okr-key-result>
|
||||
</okr-objective>
|
||||
</okr>
|
||||
```
|
||||
|
||||
- `cycle-id` 仅用于创建时挂载已有当前周期 OKR；`cycle-name`、`user-name` 只读。
|
||||
- `objective-id`、`key-result-id` 为只读业务 ID，更新已有 OKR 时保持不变。
|
||||
- `okr-objective` / `okr-key-result`
|
||||
- 可更新 `status`、`percent`、`score`；`percent` / `score` 取值 0-100，`status` 取值 `unset`/`normal`/`risk`/`extended`。
|
||||
- 不可更新 objective 和 key-result 内容描述。
|
||||
- `okr-progress` 承载进展内容，支持更新。直接子节点支持 `<p>`、`<checkbox>`、`<grid>`、`<img>`、`<source>`、`<ol>`、`<ul>`、`<h1>` 到 `<h9>`。
|
||||
183
.claude/skills/lark-doc/references/lark-doc-xml.md
Normal file
183
.claude/skills/lark-doc/references/lark-doc-xml.md
Normal file
@ -0,0 +1,183 @@
|
||||
基于 HTML 子集的 XML 格式描述飞书文档内容。
|
||||
|
||||
# 一、标准 HTML 标签
|
||||
p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr, img, b, em, u, del, a, br, span 语义不变
|
||||
|
||||
# 二、扩展标签速查表
|
||||
## 块级标签
|
||||
|标签|说明|关键属性|
|
||||
|-|-|-|
|
||||
| `<title>` | 文档标题（每篇唯一）| `align` |
|
||||
| `<checkbox>` | 待办项| `done="true"\|"false"` |
|
||||
|
||||
## 容器标签
|
||||
|标签|说明|关键属性|
|
||||
|-|-|-|
|
||||
| `<callout>` | 高亮框，子块仅支持文本块（如 `<p>`）、标题、列表、待办、引用；禁止裸文本及 `<table>`、`<img>`、`<pre>`、`<hr>`、`<grid>`、`<whiteboard>`、`<sheet>` 等其他块级标签或资源块 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
|
||||
| `<grid>` + `<column>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |
|
||||
| `<whiteboard>` | 嵌入画板 | `type`: `blank` \| `mermaid` \| `plantuml` \| `svg` |
|
||||
| `<pre>` | （代码块，内含 `code`）| `lang`, `caption` |
|
||||
| `<figure>` | 视图容器 | `view-type` |
|
||||
| `<bookmark>` | 书签链接 | `<bookmark name="标题" href="https://..."></bookmark>`，必传 name 和 href |
|
||||
|
||||
## 行内组件
|
||||
| 标签 | 说明 | 关键属性 |
|
||||
|-|-|-|
|
||||
| `<cite type="user">` | @人 | XML 导入时必须显式传入 `user-id`：`<cite type="user" user-id="userID"></cite>` |
|
||||
| `<cite type="doc">` | @文档 | `<cite type="doc" doc-id="docx_token"></cite>` |
|
||||
| `<latex>` | 行内公式 | `<latex>E = mc^2</latex>` |
|
||||
| `<img>` | 图片（可独立成块或内联） | `<img width="800" height="600" caption="说明" name="图.png" href="http 或 https"/>` |
|
||||
| `<source>` | 文件附件（可独立成块或内联） | `<source name="报告.pdf"/>` |
|
||||
| `<a type="url-preview">` | 预览卡片 | `<a type="url-preview" href="...">标题</a>` |
|
||||
| `<button>` | 操作按钮 | `background-color`、`src`，必须包含 `action=OpenLink\|DuplicatePage\|FollowPage` |
|
||||
| `<time>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\|false` |
|
||||
|
||||
## 文本块通用属性
|
||||
- `align` — `"left"`|`"center"`|`"right"`（适用于 p / h1-h9 / li / checkbox）
|
||||
- 有序列表项用 `seq="auto"` 自动编号
|
||||
|
||||
# 三、资源块
|
||||
|
||||
文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：
|
||||
|
||||
- `<img>` — `<img href="https://..."/>` 上传网络图片
|
||||
- `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；也可用本地文件简写 `<whiteboard type="svg" path="@diagram.svg"></whiteboard>`、`<whiteboard type="mermaid" path="@flow.mmd"></whiteboard>`、`<whiteboard type="plantuml" path="@sequence.puml"></whiteboard>`，CLI 会写入前展开为内联内容；复杂图使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
|
||||
- `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
|
||||
- `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
|
||||
- `<chat_card>` — `<chat_card chat-id="CHAT_ID"></chat_card>`，必传 chat-id
|
||||
- `<sub-page-list>` — `<sub-page-list></sub-page-list>` 子页面列表块；仅 wiki 文档可插入
|
||||
- `<html5-block>`、`<okr>` — 前者在飞书文档「HTML 块」iframe 中加载单文件 HTML，内容可用 HTML 渲染时直接使用；后者创建时仅支持 root-only `<okr cycle-id="..."/>` 挂载已有 OKR。完整语法与字段规则见 [`lark-doc-xml-extended-blocks.md`](lark-doc-xml-extended-blocks.md)。
|
||||
- bitable、base_ref、synced_reference、synced_source — 不可创建，仅支持移动
|
||||
|
||||
# 四、块级复制与移动
|
||||
|
||||
## 移动（block_move_after）
|
||||
支持**所有**块类型（块级标签、容器标签、行内组件、资源块），使用 `docs +update --command block_move_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
|
||||
|
||||
## 复制（block_copy_insert_after）
|
||||
- **基础标签**（块级标签、容器标签、行内组件）：均支持复制
|
||||
- **资源块**：仅 img、source、whiteboard、sheet、chat_card、sub-page-list 支持复制；task、bitable、base_ref、synced_reference、synced_source、okr 不支持复制
|
||||
|
||||
使用 `docs +update --command block_copy_insert_after --block-id "<锚点>" --src-block-ids "id1,id2"`。
|
||||
|
||||
> 详见 [lark-doc-update.md](lark-doc-update.md)。
|
||||
|
||||
# 五、补充规则
|
||||
|
||||
## 富文本样式嵌套顺序
|
||||
- 行内样式标签必须按以下固定顺序嵌套（外 → 内），关闭顺序严格反转：`<a> → <b> → <em> → <del> → <u> → <code> → <span> → 文本内容`
|
||||
|
||||
## 列表分组
|
||||
- 连续同类型列表项自动合并为一个 `<ul>` 或 `<ol>`
|
||||
- 嵌套子列表放在 `<li>` 内部
|
||||
- 新增列表项必须包在 `<ul>` 或 `<ol>` 内：
|
||||
```xml
|
||||
<ul>
|
||||
<li>第一项</li>
|
||||
<li>第二项</li>
|
||||
</ul>
|
||||
```
|
||||
|
||||
## 代码块
|
||||
- 代码块必须写成 `<pre lang="xxx" caption="可选说明"><code>代码内容</code></pre>`。
|
||||
- 不要将代码文本直接放在 `<pre>` 下；应放在内层 `<code>` 中。
|
||||
|
||||
|
||||
## 用户名写入规则
|
||||
|
||||
- 任何包含 `<cite type="user">` 的 XML 在导入、新建或编辑回写时，都必须显式传入 `user-id`；其值为用户的 `open_id`，不得省略。
|
||||
- 当从 IM 消息、日历、审批、任务等来源获取到用户的 `open_id` 时，写入文档**必须**使用 `<cite type="user" user-id="open_id">` 标签，而非纯文本名字。这样文档中会渲染为可点击的 @人。
|
||||
- 典型场景：IM 消息的 `sender`、`mentions`、reactions 的 `operator`、卡片消息中引用的用户、系统消息中的用户名、合并转发中的用户名。
|
||||
- 当只有纯文本名字而没有 `open_id` 时（如系统消息、合并转发内容），先通过 `lark-cli contact +search-user --query "名字" --as user` 反查 `open_id`，再写入 cite 标签。
|
||||
|
||||
## 表格扩展
|
||||
标准 HTML table 结构不变，扩展点：
|
||||
- `<colgroup>` / `<col>` 定义列宽，紧跟 `<table>` 之后：`<col span="2" width="100"/>`
|
||||
- `<th>` / `<td>` 增加 `background-color` 和 `vertical-align`（top | middle | bottom）
|
||||
- 有表头时第一行在 `<thead>` 用 `<th>`，其余在 `<tbody>` 用 `<td>`
|
||||
- 合并单元格仅起始格输出 `colspan` / `rowspan`，被合并的格不出现
|
||||
|
||||
# 六、美化系统
|
||||
- 颜色优先使用命名色，也可写 `rgb(r,g,b)` / `rgba(r,g,b,a)`。**基础色（7 色）**：red, orange, yellow, green, blue, purple, gray
|
||||
| 属性 | 支持的命名色 |
|
||||
|-|-|
|
||||
| 文字颜色 `<span text-color>` | 基础色 |
|
||||
| 高亮框字色 `<callout text-color>` | 基础色 |
|
||||
| 高亮框边框 `<callout border-color>` | 基础色 |
|
||||
| 文字背景 `<span background-color>` | 基础色 + `light-{色}` + `medium-gray` |
|
||||
| 高亮框填充 `<callout background-color>` | `gray` + `light-{色}` + `medium-{色}` |
|
||||
| 单元格背景 `<th/td background-color>` | 同文字背景 |
|
||||
| 按钮背景 `<button background-color>` | 同文字背景 |
|
||||
- 常用 emoji： 💡(默认)✅❌📝❓❗👍❤️📌🏁⭐
|
||||
|
||||
# 七、**重要规则**
|
||||
## 转义规则：标签本身 **禁止转义**，只有标签内部的文本内容才需要转义
|
||||
|
||||
**错误** ❌：`<p>内容</p>`（把标签也转义了）
|
||||
**正确** ✅：`<p>A & B 的对比：1 < 2</p>`（标签保持原样，文本中的 `&` 和 `<` 才转义）
|
||||
|
||||
转义字符表：
|
||||
- `<` → `<`
|
||||
- `>` → `>`
|
||||
- `&` → `&`
|
||||
- `\n`（换行符） → `<br/>`
|
||||
|
||||
|
||||
# 八、完整示例
|
||||
|
||||
```xml
|
||||
<title>文档标题</title>
|
||||
|
||||
<h1>一级标题</h1>
|
||||
|
||||
<p><b>加粗文本</b>，<span text-color="green">绿色文本</span></p>
|
||||
|
||||
<callout emoji="💡" background-color="light-yellow" border-color="yellow">
|
||||
<p>高亮框内容，子块仅支持文本/标题/列表/待办/引用</p>
|
||||
</callout>
|
||||
|
||||
<checkbox done="true">已完成事项</checkbox>
|
||||
<checkbox done="false">未完成事项</checkbox>
|
||||
|
||||
<grid>
|
||||
<column width-ratio="0.5">
|
||||
<p>左栏</p>
|
||||
</column>
|
||||
<column width-ratio="0.5">
|
||||
<p>右栏</p>
|
||||
</column>
|
||||
</grid>
|
||||
|
||||
<table>
|
||||
<colgroup><col span="2" width="120"/></colgroup>
|
||||
<thead><tr><th background-color="light-gray">表头</th><th background-color="light-gray">表头</th></tr></thead>
|
||||
<tbody><tr><td>单元格</td><td>单元格</td></tr></tbody>
|
||||
</table>
|
||||
|
||||
<p><cite type="doc" doc-id="DOC_TOKEN"></cite> <cite type="user" user-id="USER_ID"></cite></p>
|
||||
|
||||
<ol><li seq="auto">第一项</li><li seq="auto">第二项</li></ol>
|
||||
|
||||
<p><a type="url-preview" href="https://example.com">链接标题</a></p>
|
||||
|
||||
<p><latex>E = mc^2</latex></p>
|
||||
|
||||
<pre lang="go" caption="示例"><code>fmt.Println("hello")</code></pre>
|
||||
|
||||
<hr/>
|
||||
|
||||
<source name="文件名.pdf"/>
|
||||
<img src="IMG_TOKEN" width="800" height="400" caption="说明" name="图.png"/>
|
||||
<img href="https://example.com/photo.png"/>
|
||||
|
||||
<button action="OpenLink" src="https://example.com">按钮文字</button>
|
||||
|
||||
<time expire-time="1775916000000" notify-time="1775912400000" should-notify="false">时间戳毫秒</time>
|
||||
|
||||
<cite type="citation"><a href="https://example.com">引文标题</a></cite>
|
||||
<bookmark name="书签标题" href="https://example.com"></bookmark>
|
||||
|
||||
<task task-id="TASK_GUID"></task>
|
||||
<chat_card chat-id="CHAT_ID"></chat_card>
|
||||
<sub-page-list></sub-page-list>
|
||||
```
|
||||
@ -0,0 +1,47 @@
|
||||
# 从零创作工作流
|
||||
|
||||
用户提供主题、需求或简要说明，需要生成一份新的飞书文档时，遵循本工作流。
|
||||
|
||||
## 核心方法论 — Code-Act Loop
|
||||
|
||||
通过自适应的 **Code-Act Loop** 驱动文档创作，而非固定模板式的工作流。每次任务都循环执行：
|
||||
|
||||
1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
|
||||
2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进正文；仅画板渲染按需隔离到 SubAgent（见步骤三）
|
||||
3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
|
||||
4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
|
||||
|
||||
循环在文档达到质量标准且满足用户需求时结束。不要试图一次性产出完美内容——迭代打磨效果更好。根据用户实际需求灵活决定文档结构和版块，而不是套用固定模板。
|
||||
|
||||
|
||||
## 典型 Code-Act Loop 流程
|
||||
|
||||
### 步骤一：规划与撰写（单 Agent 串行）
|
||||
|
||||
正文由主 Agent 串行维护，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效。
|
||||
|
||||
1. 分析用户需求：受众、目的、范围
|
||||
2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
|
||||
3. `docs +create` 创建并撰写：
|
||||
- **短文档**：一次写入完整内容。使用 Markdown 时，避免同时传入 `--title` 和同名 `# 标题`
|
||||
- **长文档**：先建骨架（标题 + 各级标题），再由主 Agent **顺序逐节**用 `block_insert_after --block-id <章节标题 block_id>` 补全正文；写完一节再写下一节，始终带着已写内容的上下文，保证衔接、不重复
|
||||
- ⚠️ 不要一次性把超长完整内容塞进 `--content`，容易触发字符/参数限制；长文按节分次写入
|
||||
- ⚠️ 同一节内多次插入时，要锚到**上一个新插入的 block**（按 [`lark-doc-update.md`](../lark-doc-update.md) 的「Block ID 生命周期」），否则反复锚同一个标题会让段落顺序颠倒
|
||||
- ⚠️ 若先建骨架写了占位摘要，补正文时**删除占位摘要**，不要留残渣
|
||||
- ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理
|
||||
|
||||
### 步骤二：整合审查与画板识别（串行）
|
||||
|
||||
4. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
|
||||
5. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材；检查跨节有无重复、矛盾或断流。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题就地定向修正
|
||||
6. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
|
||||
|
||||
### 步骤三：画板处理与润色
|
||||
|
||||
7. **优先处理步骤二识别出的画板需求**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
|
||||
8. 由**主 Agent 自行润色**（不另起内容子 Agent，正文始终一人维护）：文字密集且不易读时，优先拆段、加小标题或调整顺序——叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）；只有确实存在行列数据时才用 `<table>`。其余富 block 的取舍一律遵循 `lark-doc-style.md` 的写作原则，不主动堆叠。需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用。本地图片使用 `docs +media-insert` 插入
|
||||
|
||||
### 步骤四：专项校验
|
||||
|
||||
9. **字数门禁**：如果用户给出任何明确字数要求（如“700-800 字”“1000 字左右”“不少于 500 字”“控制在 800 字以内”），本步骤必须执行，不属于按需项。读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；未得到脚本统计结果前，不得向用户声明“符合字数要求”。若没有明确字数要求，则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现目标区间、`word_count` 和达标结论
|
||||
10. **重复标题检查**：文档生成后，检查文档标题和正文第一个标题块是否重复；若重复，删除或改写正文第一个标题块，避免读者看到同一标题连续出现
|
||||
68
.claude/skills/lark-doc/references/style/lark-doc-style.md
Normal file
68
.claude/skills/lark-doc/references/style/lark-doc-style.md
Normal file
@ -0,0 +1,68 @@
|
||||
# 飞书文档写作原则
|
||||
|
||||
写飞书文档，像一个该领域资深的人类作者那样写，而不是把内容"装配"成组件。
|
||||
本文只讲"何时用、什么风格"；具体标签 / 命令语法见 [`lark-doc-xml.md`](../lark-doc-xml.md)。
|
||||
|
||||
## 一、用户明确要求优先
|
||||
|
||||
用户点名要某种格式——高亮块、分栏、列表、某编号体例、表格、画板、某模板、某已有文档的风格——**一律照用户的来，下面的"默认克制"全部让位**。用户给了样例或已有文档，就沿用它的结构与语气。
|
||||
|
||||
## 二、默认写连贯段落
|
||||
|
||||
用户没指定时，**默认是连贯段落**；其余按内容类型分流，别一律"少用结构"，也别什么都升标题：
|
||||
|
||||
| 内容 | 用什么 | ❌ 别 |
|
||||
|---|---|---|
|
||||
| 叙述、论证、分析、说明 | **连贯段落** | 拆成列举 |
|
||||
| 真·行列数据（预算、指标、对比、排期、字段说明） | **表格** | 写成段落或把字段堆成一行 |
|
||||
| 字段:值（主题、时长、负责人等，少量） | **加粗标签行**或一句话 | 每字段一个标题 |
|
||||
| 方法 / 措施 + 每项一段描述 | **加粗引导句段落**（「**全程督导。**…」） | 每项升标题 |
|
||||
| 任务清单 / 检查项 / 待办事项 | **`<checkbox>`** | 用普通列表替代可交互待办 |
|
||||
| 纯短并列项（无描述，如材料清单） | 列表 | — |
|
||||
| 章节（内容成块、需在目录导航） | 标题层级 | — |
|
||||
|
||||
- 判断标准：**去掉结构后能顺成段落，就用段落；成行成列的数据，就用表格。**
|
||||
- **红线一：标题层级只给"章节"。** "小标题 + 一两句话"的小项（字段、方法、要点）不该占标题层级——按上表降成标签行 / 加粗引导句段落（否则目录里全是没信息量的条目）。
|
||||
- **红线二：列举（「一是 / 二是」「第一 / 第二」「(1)(2)(3)」）只给真正并列的具体项，且别每节都用。**
|
||||
- 「一是 / 二是」是党务列举的措辞——只用在列具体的**问题 / 措施**那一处；背景、现状、认识、分析、过渡、总结**一律成段**。
|
||||
- **整篇每段 / 每节都"一是 / 二是"，和"每段一个 bullet"是同一个骨架化的错——不因为是党务就变对**（纯清单 / 台账类除外）。
|
||||
|
||||
## 三、按体裁写
|
||||
|
||||
- **公文 / 法律 / 学术 / 申报 / 项目方案等严肃正式提交物**：靠规范的标题层级、段落与编号体系表达；**默认不用高亮块、分栏**，要强调用加粗或规范小标题。
|
||||
- **面向公众号、微信等外部平台粘贴 / 发布的内容**：不用飞书特有富 block（高亮块、分栏等），粘出去会丢样式 / 错乱；改用标准标题、段落、列表、引用。
|
||||
- **一般文档**：以可读为先，不堆砌结构。
|
||||
|
||||
## 四、编号与层级
|
||||
|
||||
- **一套编号体例、全篇一致；最忌中文大层级与阿拉伯小数编号混用。**
|
||||
- 公文 / 正式材料常用：「一、→（一）→ 1.→（1）」（中文大层级 + 阿拉伯细分层级）。
|
||||
- 学术 / 技术 / 商业报告：「1 → 1.1 → 1.1.1」或「一、→（一）→ 1.」，**择一**。
|
||||
- ⚠️ **「一、」只能配「（一）」；要用阿拉伯小数就从顶层全用「1 / 1.1」。绝不「一、」配「1.1 / 2.1」**——这是最常见的混用。
|
||||
- **不混用**多套（别"第X部分"+"一、"+"1."混着来）；**同级不跳号**；**不跳级**。
|
||||
- **编号 / 标题层级只给"章节"**，不要为了凑齐体例把每个小项都编上「（一）」、升成标题（小项处理方式见上文「二、默认写连贯段落」）。
|
||||
- 简单的 1.2.3 并列项用原生 `<ol><li seq="auto">…</li></ol>` 让飞书自动编号、自动对齐；「一、(一)」原生产不出，才手打成文字——此时用标题级别表达层次，**不靠手动缩进**、各级顶格（全角括号「（）」叠手动缩进会视觉错位）。
|
||||
|
||||
## 五、飞书特有组件，克制使用
|
||||
|
||||
- **高亮块 `<callout>`**：很重的强提醒信号，**默认不用**；只给"不提醒就会出错 / 遗漏"的关键项，全文极少（0~1 个），不要每节导语 / 结论都做成高亮块。
|
||||
- **分栏 `<grid>`**：仅左右信息量相当、确需并排对照的短内容；否则用段落或表格。
|
||||
- **画板**：默认用文字，只在**图示明显比文字更易懂**（流程、架构、时间线、对比、占比等）或用户要求时才用。怎么插、用哪种类型见 [`lark-doc-xml.md`](../lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](../lark-doc-whiteboard.md)。
|
||||
- **颜色**：默认朴素、不上色；需要时保持语义一致，按下表选择对应颜色，不为装饰上色。可用色见 [`lark-doc-xml.md`](../lark-doc-xml.md) 的「美化系统」。
|
||||
|
||||
| 语义 | 背景色 | 文字色 |
|
||||
|-|-|-|
|
||||
| 信息、说明 | `light-blue` | `blue` |
|
||||
| 成功、推荐 | `light-green` | `green` |
|
||||
| 警告 / 错误 / 风险 | `light-red` | `red` |
|
||||
| 注意、待确认 | `light-yellow` | `yellow` |
|
||||
| 中性、辅助 | `light-gray` | — |
|
||||
|
||||
## 六、写完自检
|
||||
|
||||
交付前快速回看：
|
||||
- **叙述是否被列举化**：背景 / 现状 / 认识 / 分析 / 成效 / 过渡 / 总结等应成段；列举只用于同层级、可并列处理的信息，如问题、措施、步骤、任务或材料清单。若正文反复使用连续编号、项目符号或固定并列句式，导致内容缺少叙述，应把背景 / 认识 / 分析 / 过渡改写成有承接关系的段落（纯清单 / 台账类除外）。
|
||||
- **数据是否正确呈现**：成行成列的数据应使用表格呈现，不要写成段落，也不要用分隔符把多个字段硬串在一起。
|
||||
- **标题是否滥用**："小标题 + 一句话"的小项不要升成标题；应改成标签行、加粗引导句段落或普通段落。
|
||||
- **编号是否统一**：全篇一套、不跳号、不跳级，尤其不要中文 + 阿拉伯混用（如「一、」配「1.1」）。
|
||||
- **组件是否克制且保真**：高亮块 / 分栏 / 画板 / 颜色应符合体裁和用户要求；引用 / 图片 / 资源块必须保留。
|
||||
@ -0,0 +1,48 @@
|
||||
# 改写增强工作流
|
||||
|
||||
用户提供已有文档链接或 token，需要改写、润色、补充或重排版时，遵循本工作流。
|
||||
|
||||
## 核心方法论 — Code-Act Loop
|
||||
通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：
|
||||
1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
|
||||
2. **Execute（执行）** — 由主 Agent 自己运行 `lark-cli docs` 命令推进改写；仅画板渲染按需隔离到 SubAgent（见步骤二）
|
||||
3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
|
||||
4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
|
||||
|
||||
## 核心原则：精准手术优于全量覆盖
|
||||
1. **精准手术**：只改用户指定的 block，不改其他 block。
|
||||
2. **全量覆盖**：如果用户明确要改整篇，才用 `overwrite` 命令。
|
||||
3. **保真约束**：改写时原文里的 `<cite type="user">`（@人）、`<cite type="doc">`（@文档）、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等行内组件和资源块一律原样保留（含所有 token / user-id / doc-id 属性），不许替换成纯文本姓名、链接或占位符。
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 步骤一：分析与画板识别（串行）
|
||||
|
||||
1. **选择读取范围**（节省上下文的关键）：
|
||||
- 用户只改某一节 / 文档较大 → 先 `docs +fetch --scope outline --max-depth 2` 拿目录，再 `docs +fetch --scope section --start-block-id <目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）
|
||||
- 需要精确跨节区间 → `docs +fetch --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）
|
||||
- 用户只给了模糊关键词 → `docs +fetch --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`
|
||||
- 用户明确要改整篇 → `docs +fetch --detail with-ids`
|
||||
- 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) 中「选 `--scope`（读取范围）」小节
|
||||
2. 系统性评估：用户想改什么、现有文档风格是什么、哪些内容需要保留、哪些问题影响理解
|
||||
3. **画板识别**：逐章节扫描，判断是否有段落用图明显比文字更易懂（流程 / 架构 / 时间线 / 对比 / 占比等，见 `lark-doc-style.md` 的画板原则）。默认用文字，只有确需图示才记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段
|
||||
4. 向用户简要说明改进计划（包含识别出的画板机会）
|
||||
|
||||
### 步骤二：定向改写（单 Agent 串行）
|
||||
|
||||
5. **优先处理步骤一识别出的画板候选段落**：读取并按 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 选型和插入；正文本身不交给 SubAgent
|
||||
6. 由主 Agent **顺序逐节**改写，**不按章节拆给并行 Agent**，避免上下文割裂、重复矛盾和全文级约束失效：
|
||||
- 沿用或轻微调整已有文档风格，除非用户要求彻底重排版
|
||||
- 优先通过重写段落、调整标题、补充小标题提升可读性；叙述内容保持成段，**不要默认改成列表**，只有确属并列要点 / 步骤才用列表（见 `lark-doc-style.md`）
|
||||
- 富 block 是可选表达手段，不因固定比例而添加，取舍遵循 `lark-doc-style.md` 的写作原则；画板类需求只走第 5 步
|
||||
|
||||
### 步骤三：验证（串行）
|
||||
|
||||
7. 获取更新后文档局部内容，检查是否符合用户目标和已有风格
|
||||
8. 检查是否满足用户目标并保留原有关键内容。再按 `lark-doc-style.md` 的「写完自检」快速核对，发现问题则定向修正
|
||||
|
||||
### 步骤四：专项校验（按需执行）
|
||||
|
||||
9. 仅当用户预期需要校验字数时，才读取并执行 [`lark-doc-word-stat.md`](../lark-doc-word-stat.md) 的「字数遵循校验」；否则跳过本项，不读取该 workflow。若执行了专项校验，向用户呈现结果
|
||||
|
||||
**上下文节省提示**：主 Agent 改某节时如需重新读取，优先用 `docs +fetch --scope section --start-block-id <章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉当前章节，不要重复拉全文。
|
||||
1243
.claude/skills/lark-doc/scripts/doc_word_stat.py
Normal file
1243
.claude/skills/lark-doc/scripts/doc_word_stat.py
Normal file
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user