@wagemule/daemon 0.1.2 → 0.1.3

package/dist/skills/larksuite/lark-contact/references/lark-contact-search-user.md

@@ -0,0 +1,124 @@
+# +search-user
+
+仅 user 身份。需要 scope `contact:user:search`。
+
+## 适用范围
+
+- ✅ 已知姓名 / 邮箱 / 「聊过的人」想找出 open_id
+- ✅ 已知一组 open_id 想批量校验或回填字段(`--user-ids`,最多 100,支持 `me`)
+- ✅ 按聊天关系 / 在职状态 / 租户边界 / 企业邮箱等维度筛选员工
+- ❌ 已知 open_id 想拿完整 profile → 用 `+get-user --as bot`
+- ❌ 已知 open_id 想发消息 → 直接走 `lark-im`,不经过本命令
+
+## 关键 flag
+
+`--query` / `--queries` / `--user-ids` / bool filter 至少传一个。bool filter 显式传 `=false` 会报错——不传等于不过滤。
+
+| Flag | 作用 |
+|---|---|
+| `--query <text>` | 关键词(姓名 / 邮箱 / 手机号),≤ 50 rune |
+| `--queries <csv>` | 多个关键词并行搜,**最多 20 条**;与 `--query` / `--user-ids` 互斥;输出新 shape(见下) |
+| `--user-ids <csv>` | open_id 列表,≤ 100;支持 `me` 表示自己;与 `--query` 同传时把搜索范围限定在该集合 |
+| `--has-chatted` | 仅搜聊过天的 |
+| `--has-enterprise-email` | 仅搜有企业邮箱的 |
+| `--exclude-external-users` | 仅搜同租户(排除外部联系人) |
+| `--left-organization` | 仅搜已离职的 |
+| `--lang <locale>` | 覆盖 `localized_name` 的语种(如 `zh_cn` / `en_us` / `ja_jp`) |
+| `--page-size <n>` | 单页大小 1-30,默认 20 |
+
+## 常用例子
+
+```bash
+# 按姓名搜,看候选确认是哪个张三
+lark-cli contact +search-user --query "张三" --has-chatted
+
+# 按完整邮箱搜(命中通常唯一,适合作后续命令的输入)
+lark-cli contact +search-user --query "alice@example.com"
+
+# 查看自己
+lark-cli contact +search-user --user-ids me
+
+# 批量回填:已知一组 open_id,取姓名 / 邮箱 / 部门
+lark-cli contact +search-user --user-ids "ou_a,ou_b,ou_c" --format json
+
+# 多 filter 组合:同租户的、有企业邮箱的「王」姓员工
+lark-cli contact +search-user --query "王" --exclude-external-users --has-enterprise-email
+
+# filter-only 枚举:列出所有"聊过天的离职同事"(无关键词)
+lark-cli contact +search-user --has-chatted --left-organization
+```
+
+## 批量并行查询 (fanout)
+
+一次查多个名字:
+
+```bash
+lark-cli contact +search-user --queries "Alice,Bob,张三"
+```
+
+- 每行 user 带 `matched_query`,标识来自哪个 query
+- `queries[]` 每个输入一条 `{query, error?, has_more}`,失败的有 `error`
+- 部分失败不影响其它 query;全部失败才 exit 非 0
+
+```bash
+# bool filter 对每个 query 都生效
+lark-cli contact +search-user --queries "Alice,Bob" --has-chatted
+
+# 与 --query / --user-ids 互斥
+lark-cli contact +search-user --queries "a" --query "b"   # ❌ exit 2
+```
+
+约束:
+- 最多 20 条; 每条 ≤ 50 字符
+- 重复条目静默去重;全空 csv (`,,,`) 报错
+
+## 同名 disambiguation
+
+搜常见姓名常返回多条同名结果。后续操作若有副作用(发消息、邀请会议等),把候选列给用户挑;**不要擅自选**。
+
+筛选信号(可信度从高到低):`chat_recency_hint`(近期联系过) > `enterprise_email` 前缀 > `department` 关键词。`localized_name` 同名时无区分作用。
+
+```bash
+# 用 jq 按部门精筛
+lark-cli contact +search-user --query "张三" \
+  --jq '.data.users[] | select(.department | contains("<部门关键词>"))'
+```
+
+## 注意事项
+
+- **不会自动翻页**。`has_more=true` 表示需要 refine query。
+- **`--lang` 只影响输出展示名**,不影响匹配字段。
+- **`--query` 与 `--user-ids` 同时设**:`--user-ids` 限定搜索范围,`--query` 在该集合内匹配。
+
+## 输出字段 contract
+
+跨租户用户(`is_cross_tenant=true`)的业务字段可能为空字符串,需做空值兜底。
+
+| 字段 | 类型 | 说明 | 跨租户 |
+|---|---|---|---|
+| `open_id` | string | 稳定标识,后续命令的输入 | 始终非空 |
+| `localized_name` | string | 按 `--lang` / brand 选出的展示名 | 始终非空(兜底为 open_id) |
+| `email` | string | 个人邮箱 | 可能为空 |
+| `enterprise_email` | string | 企业邮箱 | 可能为空 |
+| `is_activated` | bool | 是否已激活飞书账号(未激活也可投递消息,但用户可能看不到) | 可能 false |
+| `is_cross_tenant` | bool | 是否跨租户用户(同公司=false,外部联系人=true) | — |
+| `p2p_chat_id` | string | 与当前用户的 P2P 会话 ID(`oc_...`);空表示从未私聊过。可作为接受 `--chat-id` 的 IM 命令的输入 | 可能为空 |
+| `has_chatted` | bool | `p2p_chat_id != ""` 的派生字段 | — |
+| `department` | string | 部门路径,服务端可能用 `-` 拼层级,层级数不固定。**按可子串匹配的字符串处理** | 可能为空 |
+| `signature` | string (optional) | 用户个性签名;空时字段不出现 | 可能不出现 |
+| `chat_recency_hint` | string | 最近联系的提示文案,仅供展示 | 可能为空 |
+| `match_segments` | string[] | 关键词命中的字符串片段,用于高亮展示;无命中则为空数组 | — |
+
+### `--queries` 模式额外字段
+
+`data.users[]` 每条多 `matched_query` (string),指明本行来自哪个 query。
+
+`data.queries[]` 按输入顺序、dedup 后每个 query 一条:
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `query` | string | 该输入 |
+| `error` | string (optional) | 失败原因;成功时不出现 |
+| `has_more` | bool | 该 query 还有更多结果 |
+
+fanout 模式无顶层 `data.has_more`。

package/dist/skills/larksuite/lark-doc/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: lark-doc
+description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板（含 SVG 画板）、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML，也支持 Markdown。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli docs --api-version v2 --help; lark-cli docs +create --api-version v2 --help; lark-cli docs +fetch --api-version v2 --help; lark-cli docs +update --api-version v2 --help"
+---
+
+# docs (v2)
+
+> **⚠️ API 版本：本 skill 使用 v2 API。所有 `docs +create --api-version v2`、`docs +fetch --api-version v2`、`docs +update --api-version v2` 命令必须携带 `--api-version v2`。**
+
+```bash
+# 常用示例
+lark-cli docs +fetch  --api-version v2 --doc "文档URL或token"
+lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容</p>'
+lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'
+```
+
+## 前置条件 — 执行操作前必读
+
+**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
+1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
+2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`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-create-workflow.md`](references/style/lark-doc-create-workflow.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（可用 callout、grid、checkbox 等富 block）。
+> - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
+
+## 快速决策
+- 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
+- 写文档时，重要信息（核心流程、架构、对比、风险、路线图、关键指标、因果关系）优先规划为画板，不要只用文字或表格承载
+- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
+- 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
+- 用户明确说"下载素材" → 用 `lark-cli docs +media-download`
+- 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
+- 用户说"找一个表格""按名称搜电子表格""找报表""最近打开的表格""最近我编辑过的 xxx" → 直接用 `lark-cli drive +search`（参考 [`lark-drive`](../lark-drive/references/lark-drive-search.md)）。**老的 `docs +search` 已进入维护期、后续会下线，不要再新增依赖。**
+- `drive +search` 结果里会直接返回 `SHEET` / `Base` / `FOLDER` 等云空间对象，是资源发现的统一入口
+- 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
+- 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 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) |
+| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch --api-version v2` 读取 src-token 文档，定位 block |
+
+**补充：** 云空间资源发现统一走 [`drive +search`](../lark-drive/references/lark-drive-search.md)；当用户口头说"表格/报表/最近我编辑过的 xxx"时，也优先从 `drive +search` 开始。老的 `docs +search` 只在沿用 `--filter` JSON 的存量脚本里保留，后续会下线。
+
+## Shortcuts（推荐优先使用）
+
+Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+
+| Shortcut | 说明 |
+|----------|------|
+| [`+search`](references/lark-doc-search.md) | ⚠️ **Deprecated — use [`drive +search`](../lark-drive/references/lark-drive-search.md)**. Search Lark docs, Wiki, and spreadsheet files (Search v2: doc_wiki/search). Kept for back-compat; new flows should use the drive-scoped command with flat 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-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. |

package/dist/skills/larksuite/lark-doc/references/lark-doc-create.md

@@ -0,0 +1,89 @@
+# docs +create（创建飞书云文档）
+
+> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
+> 1. [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证、全局参数和安全规则
+> 2. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
+> 3. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
+> 4. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
+>
+> **未读完以上文件就生成内容会导致格式错误或样式不达标。**
+
+从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
+
+> **⚠️ 格式选择规则：** 创建 / 导入场景下 XML 和 Markdown 都可以——用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；没有明确指示时默认 XML（表达能力更强，支持 callout、grid、checkbox 等富 block 类型）。不要在用户没要求的情况下主动从 XML 切到 Markdown，也不要在用户已给出 Markdown 时强行改成 XML。
+
+## 命令
+
+```bash
+# 创建 XML 文档（默认格式，推荐）
+lark-cli docs +create --api-version v2 --content '<title>项目计划</title><h1>目标</h1><ul><li>目标 1</li><li>目标 2</li></ul>'
+
+# 创建到指定文件夹（XML）
+lark-cli docs +create --api-version v2 --parent-token fldcnXXXX --content '<title>标题</title><p>首段内容</p>'
+
+# 创建到个人知识库（XML）
+lark-cli docs +create --api-version v2 --parent-position my_library --content '<title>标题</title><p>内容</p>'
+
+# 仅当用户明确要求时才使用 Markdown
+lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项目计划\n\n## 目标\n\n- 目标 1\n- 目标 2'
+```
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "document": {
+      "document_id": "doxcnXXXXXXXXXXXXXXXXXXX",
+      "revision_id": 1,
+      "url": "https://xxx.feishu.cn/docx/doxcnXXXXXXXXXXXXXXXXXXX",
+      "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 转给自己，必须单独确认。
+
+## 参数
+
+| 参数                  | 必填 | 说明                                          |
+| ------------------- | -- |---------------------------------------------|
+| `--api-version`     | 是  | 固定传 `v2`                                    |
+| `--content`         | 是  | 文档内容（XML 或 Markdown 格式）                     |
+| `--doc-format`      | 否  | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
+| `--parent-token`    | 否  | 父文件夹或知识库节点 token（与 `--parent-position` 互斥）  |
+| `--parent-position` | 否  | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |
+
+## 最佳实践
+
+- 文档标题从内容中自动提取（XML `<title>` 或 Markdown `#`），不要在内容开头重复写标题
+- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `docs +update --command append` 或 `block_insert_after` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
+- **视觉丰富度**：必须遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block 丰富文档
+
+## 参考
+
+- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
+- [`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) — 插入图片/文件到文档
+- [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证和全局参数
+

package/dist/skills/larksuite/lark-doc/references/lark-doc-fetch.md

@@ -0,0 +1,141 @@
+
+# docs +fetch（获取飞书云文档）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+## 命令
+
+```bash
+# 获取文档（默认 XML，simple）
+lark-cli docs +fetch --api-version v2 --doc "https://xxx.feishu.cn/docx/Z1Fj...tnAc"
+
+# Markdown 格式
+lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --doc-format markdown
+
+# 带 block ID（用于后续 block 级更新）
+lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --detail with-ids
+
+# 只拿目录
+lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --scope outline --max-depth 3
+
+# 按 block id 区间精读
+lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
+  --scope range --start-block-id blkA --end-block-id blkB --detail with-ids
+
+# 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）
+lark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \
+  --scope section --start-block-id <标题id> --detail with-ids
+
+# 按关键词定位（多关键词用 | 分隔，任一命中即返回）
+lark-cli docs +fetch --api-version v2 --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` |
+| **编辑**：任何修改文档内容的需求 | `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>"
+    }
+  }
+}
+```
+
+`content` 的格式由 `--doc-format` 决定。设置 `--scope` 时会被 `<fragment>` 包裹，详见上文"局部读取的输出结构"。
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--api-version` | 是 | 固定传 `v2` |
+| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |
+| `--doc-format` | 否 | `xml`（默认）\| `markdown` \| `text` |
+| `--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`
+
+## 嵌入电子表格 / 多维表格
+
+返回中可能含 `<sheet>`、`<bitable>`、`<cite file-type="sheets|bitable">`。内部数据无法通过 `docs +fetch --api-version v2` 获取，提取 `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-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/dist/skills/larksuite/lark-doc/references/lark-doc-md.md

@@ -0,0 +1,71 @@
+# Markdown 格式参考
+
+`docs +fetch --api-version v2` / `docs +create --api-version v2` / `docs +update --api-version v2` 使用 `--doc-format markdown` 时适用。
+
+## 转义规则
+
+> **⚠️ 当文本中包含以下字符且不想触发 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 --api-version v2 --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\[`、`\|`、`\\` 等）。这些 `\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\`。**
+
+**写入时必须转义：**
+使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。
+
+**导出 → 更新 工作流示例：**
+
+1. `docs +fetch --api-version v2` 导出得到 `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`）
+- **默认用单引号 `'...'`**：完全字面量，`$`、`` ` ``、`\`、`>`、`\<b>` 等全部原样保留
+- **双引号 `"..."`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\` 仍参与转义，易踩坑
+- **`$'...'` ANSI-C 引号**：按 C 转义解析，`\n`=换行、`\\`=单个 `\`；**zsh 下未知转义（如 `\<`）的 `\` 会被吞**，要保留字面 `\` 必须写 `\\`。只在确实需要 `\n`/`\t` 时用
+- **多行内容**：用 `<<'EOF'` heredoc，EOF 必须带引号，否则仍展开 `$`
+- **`\n` 在 `'...'` 和 `"..."` 里都是字面量**，不是换行；要真换行用 `$'...\n...'` 或 heredoc
+
+## 图片语法
+
+Markdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：
+```markdown
+![alt text](https://example.com/photo.png)
+```
+- `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>`。

package/dist/skills/larksuite/lark-doc/references/lark-doc-media-download.md

@@ -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` 返回的 Markdown 里可能包含：
+  - 图片：`<image token="..." .../>`
+  - 文件：`<file 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) — 认证和全局参数