@amaster.ai/pi-lark 0.1.2-beta.58 → 0.1.2-beta.59

package/skills/lark-base/references/{lark-base-data-analysis-sop.md → lark-base-record-query-and-analysis-sop.md}

@@ -1,20 +1,34 @@
-# Base 数据表查询与分析 SOP
+# Base Record 查询、匹配与分析 SOP
 
-数据表记录查询和分析任务先读本 SOP，包括记录预览、筛选、排序、去重、统计、聚合、TopN、多值计算、Link 或多表关联、复杂行级计算、全局结论和查询后写入。先区分需要 LLM 理解原文的语义分析与可程序化计算的确定性分析，再按任务所需数据规模与计算复杂度选择对应路径。用户直接要求解释、编写或排错 `+data-query` 命令或 DSL 时，直接读 [data-query guide](lark-base-data-query-guide.md)。
+任何 Record 读取、预览、搜索、筛选、匹配、统计、聚合、TopN、多表或语义分析，以及写操作中的记录定位和结果验收，都先完整读取本 SOP。先区分需要 LLM 理解原文的语义分析与可程序化计算的确定性分析，再按数据规模与计算复杂度选择路径；即使用户直接要求解释、编写或排错 `+data-query` 命令或 DSL，也先由本 SOP 确认口径和路径，再读取底层 reference。
 
 ## 分流决策
 
-1. 明确所有需要参与分析的表及其 `records_count`。
+1. 明确所有需要参与分析的表；上下文已有整表 `records_count` 时用于提前分流，否则直接按下文导出或探测，不为获取规模单独枚举表。
 2. 如果结论必须依赖 LLM 理解原始内容，例如开放文本打标、情绪或意图识别、主题归纳、语义分类、相似性判断或实体消歧，进入下文“LLM 语义分析”路径。
-3. 对于其余确定性查询，任一分析表超过 2000 行时，先从任务意图中为所有大表提取可在单表内独立执行的谓词，例如日期范围、状态和关键词，再按下文将谓词逐表下推，并用 `--field-id '<一个简单标量字段>' --limit 2000 --output <probe>.ndjson --minimal-stdout` 探测。目标是每张表都达到 `has_more=false`；任一表无法压缩到 2000 行以内时，转 [lark-base-data-analysis-cloud.md](lark-base-data-analysis-cloud.md) 用云端的数据分析能力。
+3. 对于其余确定性查询，任一分析表已知超过 2000 行或 NDJSON 探测返回 `has_more=true` 时，先从任务意图中提取可在单表内独立执行的日期、状态、关键词等谓词，逐表下推后用 `--field-id '<一个简单标量字段>' --limit 2000 --format ndjson --output <probe>.ndjson --minimal-stdout` 复查。目标是每张表都达到 `has_more=false`；任一表无法压缩到 2000 行以内时，转 [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md) 用云端的数据分析能力。
 4. 所有分析表都不超过 2000 行后：若只有一张表且短 jq 可清晰完成筛选、计数、简单分组/聚合/排序、TopN 可以使用 jq。
-5. 其余确定性任务比如多表、日历计算和复杂数据分析，在 Python 可用时使用 Python，否则进入 [Cloud SOP](lark-base-data-analysis-cloud.md)。
+5. 其余确定性任务比如多表、日历计算和复杂数据分析，在 Python 可用时使用 Python，否则进入 [Cloud SOP](lark-base-record-query-and-analysis-cloud-sop.md)。
 
-进入 Cloud 后先由 Cloud SOP 在原始记录查询与聚合查询之间选路；只有选定 `+data-query` 时才读取 data-query guide。
+进入 Cloud 后先由 Cloud SOP 在原始记录查询与聚合查询之间选路；只有选定 `+data-query` 时才读取 [data-query DSL reference](lark-base-data-query.md)。
 
 ## 执行与交付
 
-分析输入默认采用 `--output x.ndjson`；NDJSON 未显式传 `--limit` 时默认读取最多 2000 条，正式分析通常沿用该范围。窄投影探测、快速预览或用户明确要求前 N 条时再设置较小的 `--limit`。`--format json` 和 Markdown 适用于向用户即时展示的小结果。
+所有 records 读取统一使用 `--format ndjson --output <artifact>.ndjson`。NDJSON 将大记录集写入 records 文件，并在 stdout 返回包含摘要、列 schema 和 stats 的 manifest，避免把过长用户数据直接加载进模型上下文。用 Python 或数据分析引擎直接处理 records 文件。未传 `--limit` 时最多读取 2000 条；仅在探测、预览或用户明确要求前 N 条时缩小限制。
+
+### NDJSON 读取示例
+
+按任务替换真实 token、ID、投影、条件和 artifact 名称；`+record-search` 和 `+record-get` 使用相同的 NDJSON 输出参数。
+
+```bash
+lark-cli base +record-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --field-id <field> \
+  --format ndjson \
+  --output ./records.ndjson \
+  --as user
+```
 
 缩小大表记录范围时，展示文本关键词用 `+record-search`，日期、状态、数字、空值、选项、人员和关联等结构化条件用 `+record-list --filter-json`。
 
@@ -45,7 +59,7 @@
 }
 ```
 
-全表分析的常规资源链路是 `+table-list` 确认目标表与规模，对所有参与分析的表并发执行 `+field-list` 读取所需 schema，再用 `+record-list` 导出记录；已有可信的 `table_id` 时可直接并发读取各表 `+field-list`。`+view-get` 可按需读取，作为用户持久化访问习惯的可选参考；其中的 filter、sort 与字段范围可辅助理解用户常用的查询范围和排序偏好，并结合当前任务确定最终口径。
+全表分析的常规资源链路是 `+table-list` 确认目标表，并用已有整表 `records_count` 或 NDJSON `has_more` 确认规模；对所有参与分析的表并发执行 `+field-list` 读取所需 schema，再按上述 NDJSON 契约用 `+record-list` 导出记录。已有可信的 `table_id` 时可直接并发读取各表 `+field-list`。`+view-get` 可按需读取，作为用户持久化访问习惯的可选参考；其中的 filter、sort 与字段范围可辅助理解用户常用的查询范围和排序偏好，并结合当前任务确定最终口径。
 
 1. 每次读取使用任务所需的最小投影，并包含 JOIN、解释、回查或写入需要的业务 key。
 2. 全局结论以 `has_more=false` 的完整导出或 Cloud 聚合结果为依据；`has_more=true` 时继续收敛单表谓词或选择 Cloud 路径。
@@ -53,16 +67,12 @@
 4. Base 标量空值很常见；聚合前按用户口径确定空值是排除、按零计入还是进入分母。用户未指定且不同处理会实质改变结论时，说明空值数量、采用的口径及其影响；任务涉及业务键、展开、JOIN 或金额分摊时，同样明确目标粒度及与口径直接相关的重复或总量守恒。
 5. 最终结果保留真实表、查询范围和计算口径，展示用户可读字段；内部 ID 用于连接或定位。
 
-`+table-list` / `+base-block-list` 返回的 `records_count` 表示整表行数；manifest 的 `records_count` 表示本次查询实际导出的行数。
-
 ## 复用本轮 NDJSON
 
 Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否复用：
 
 1. 短时间内继续分析或表中数据低频变化时，谓词下推口径一致且已有列覆盖计算需求即可优先复用。
-2. 间隔较长或表中数据高频变化时，批量提取 manifests 的 `base_token/table_id/rev`，并发执行 `+table-list` 校验最新 `rev`；版本一致且谓词口径未变时复用，否则重新导出对应表。
-
-> 例：本轮已按“日期在 2026 年”导出 `orders.ndjson`，用户继续要求按负责人聚合；谓词和所需列未变，直接复用。若间隔较长或该表频繁写入，manifest `rev=42` 与 `+table-list` 最新 `rev` 相同则复用，最新 `rev=43` 则重新导出。
+2. 间隔较长或表中数据高频变化时，批量提取 manifests 的 `base_token/table_id/rev`，刷新相关表元数据并校验最新 `rev`；版本一致且谓词口径未变时复用，否则重新导出对应表。
 
 ## LLM 语义分析
 
@@ -76,7 +86,7 @@ Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否
 
 ## Manifest
 
-`--output <path>.ndjson` 生成 `<path>.ndjson` 与 `<path>.manifest.json`；记录写入 NDJSON，stdout 返回 manifest，`--minimal-stdout` 只保留文件位置、文件字节数、`records_count` 和 `has_more`。
+`--output <path>.ndjson` 生成 `<path>.ndjson` 与 `<path>.manifest.json`；记录写入 NDJSON，stdout 返回 manifest。
 
 分析 artifact 使用相对路径输出到当前工作目录，例如 `--output ./records.ndjson`。
 
@@ -115,7 +125,6 @@ Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否
 
 - stdout 的 `records_count` 和 `has_more` 描述本次导出；确认后无需在分析代码中重读 manifest 或重新统计 NDJSON 行数。
 - `record_file_size_bytes` 是 NDJSON artifact 的实际字节数，用于选择一次读取、预览或分批方式；确定性计算由 jq/Python 直接读取文件。
-- manifest 的 `rev` 是导出首个响应页返回的 table revision；与 `+table-list` 返回的最新 `rev` 比较，可判断本轮 NDJSON 是否仍对应当前表版本。
 - `query_context` 保存导出查询范围；复用本轮 NDJSON 时结合原查询上下文确认谓词下推口径保持一致。
 - 仅在需要 `columns`、example、hint 或执行 artifact 复用判断时读取 `manifest_file`；满足复用条件后直接继续分析现有 NDJSON。
 - `ignored_fields` 和 `record_not_found` 仅在 stdout 返回时关注。
@@ -174,7 +183,7 @@ Agent 上下文曾下载过当前表的 NDJSON 时，按以下规则判断是否
 
 NDJSON 每行是一条 record。单表短筛选、计数和简单聚合可直接用 jq；下面筛选“状态”包含“进行中”的记录，并统计记录数和金额合计：
 
-默认导出后使用本地 `jq -s`，同一 artifact 可反复查询而无需重新下载。表达式很短且只执行一次，或本地 jq 不可用时，可改用 `--jq-records '<expr>'` 等价 `jq -s '<expr>' records.ndjson`。使用 CLI 内置 jq 处理 NDJSON 记录时必须使用 `--jq-records`；通用 `--jq` 不支持 ndjson。
+默认导出后使用本地 `jq -s`，同一 artifact 可反复查询而无需重新下载；本地 jq 不可用时，使用 Python 或其他数据分析引擎处理 records 文件。
 
 ```bash
 lark-cli base +record-list \
@@ -182,8 +191,8 @@ lark-cli base +record-list \
   --table-id <table_id> \
   --field-id 状态 \
   --field-id 金额 \
-  --output records.ndjson \
-  --minimal-stdout &&
+  --format ndjson \
+  --output records.ndjson &&
 jq -s '
   map(select((.["状态"] | index("进行中")) != null)) as $records
   | ($records | map(.["金额"] | select(. != null))) as $amounts

package/skills/lark-base/references/{role-config.md → lark-base-role-config.md}

@@ -1,6 +1,6 @@
-# Base role permission JSON SSOT
+# Base Role Permission Schema
 
-> **入口指南**: [lark-base-role-guide.md](lark-base-role-guide.md) | **相关命令**: `+role-create` · `+role-update` · `+role-get`
+> **模块入口**: [Advanced Permission 与 Role](lark-base-advanced-permission-and-role.md) | **相关命令**: `+role-create` · `+role-update` · `+role-get`
 
 本文档是角色权限 JSON（AdvPermBaseRoleConfig）的单一事实来源（SSOT），供 `+role-create` 和 `+role-update` 构造 `--json` 参数时参考。
 

package/skills/lark-base/references/lark-base-view-set-filter.md

@@ -62,4 +62,4 @@ lark-cli base +view-set-filter \
 ## 6. 参考
 
 - [lark-base-filter-condition.md](lark-base-filter-condition.md)：filter/visible_rule 条件结构公共协议 SSOT
-- [lookup-field-guide.md](lookup-field-guide.md)
+- [Lookup Field](lark-base-field-lookup.md)

package/skills/lark-base/references/lark-base-workflow-schema.md

@@ -3,7 +3,7 @@
 本文档是 Workflow `steps` JSON 的单一事实来源（SSOT），定义完整数据结构，适用于：
 - **查询场景**：理解 `+workflow-get` 返回的 `steps` 结构
 - **创建/修改场景**：构造 `+workflow-create` / `+workflow-update` 的 `--json` body
-> 💡 **本文档是纯字段参考**。如需**创建/修改**工作流的完整示例，请阅读 [workflow-guide.md](lark-base-workflow-guide.md)。
+> 💡 **本文档是纯字段参考**。如需**创建/修改**工作流的完整示例，请阅读 [Workflow](lark-base-workflow.md)。
 ---
 ## 📖 快速导航
 
@@ -1067,5 +1067,5 @@ $.{stepId}.{fieldId}.fileToken    → 文件 Token 列表（array<string>，仅
 
 ## 参考
 
-- [lark-base-workflow-guide.md](lark-base-workflow-guide.md) — 完整示例和构造技巧
+- [Workflow](lark-base-workflow.md) — 完整示例和构造技巧
 - 创建/更新时外层只承载 workflow 元信息，核心校验对象是 `steps`；列表只用于拿 workflow ID 和启停状态

package/skills/lark-base/references/{lark-base-workflow-guide.md → lark-base-workflow.md}

@@ -1,4 +1,4 @@
-# Workflow guide
+# Base Workflow
 
 本文档是 Workflow 的入口指南，帮助选择步骤组合、理解创建/更新边界，并引导到 steps JSON SSOT。
 

package/skills/lark-doc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-doc
-description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。文档评论走 lark-drive；表格或 Base 内部数据操作不在本 skill。"
+description: "飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -33,7 +33,7 @@ metadata:
 ### 资源、画板与思维笔记
 
 - **插入本地素材 — [`+media-insert`](references/lark-doc-media-insert.md)**：在文末插入本地图片或文件。
-- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档中的图片、附件或素材。
+- **预览素材 — [`+media-preview`](references/lark-doc-media-preview.md)**：预览文档或评论中的图片、附件或素材。
 - **下载素材 — [`+media-download`](references/lark-doc-media-download.md)**：下载文档中的图片、附件、素材或画板缩略图。
 - **Docx 封面 — [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md)**：下载、更新或删除 Docx 封面。
 - **画板 — [`画板工作流`](references/lark-doc-whiteboard.md)**：创建或更新画板时先读取工作流；更新已有画板必须复用现有 token，禁止新建空白画板；使用 [`whiteboard +update`](../lark-whiteboard/references/lark-whiteboard-update.md) 写入。
@@ -46,4 +46,4 @@ metadata:
 ## 不在本 Skill 范围
 
 - **Drive 文件级操作**：找文档、导入导出、云空间文件上传 / 下载 / 权限管理 → [`lark-drive`](../lark-drive/SKILL.md)。复制文档、创建副本或另存为副本时，按其指引使用 `lark-cli drive files copy`；不要用 `docs +fetch` + `docs +create` 重建正文。
-- **文档评论**：添加、查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)。
+- **独立评论操作**：添加、分页查看、回复评论或增删 reaction → [`lark-drive`](../lark-drive/SKILL.md)；只需紧凑评论上下文时，直接使用默认 JSON 响应的 `docs +fetch`。

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

@@ -5,7 +5,7 @@
 ## 常用示例
 
 ```bash
-# 读取整篇文档
+# 读取整篇文档，并附带当前用户可见的未解决评论；
 lark-cli docs +fetch --doc "文档URL或token"
 
 # 按 URL 中的 #share 锚点局部读取
@@ -34,7 +34,6 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
 |`--context-before`|否|返回命中项之前的顶层兄弟块数量（默认 `0`）|
 |`--context-after`|否|返回命中项之后的顶层兄弟块数量（默认 `0`）|
 |`--max-depth`|否|`outline` 表示标题层级上限；其它模式表示子树深度（默认 `-1`，不限）|
-|`--format`|否|`json`（默认）\| `pretty`|
 
 ## 选择详细度：`--detail`
 
@@ -90,6 +89,11 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
           "<ref>": {
             "<real-attr-key>": "<real-attr-value>"
           }
+        },
+        "comments": {
+          "c1": {
+            "data": "<comment comment-id=\"xx\" block-id=\"xx\"><quote>引用内容</quote><msg>评论内容</msg></comment>"
+          }
         }
       },
       "tips": "<safe replay or degradation guidance>"
@@ -97,7 +101,8 @@ lark-cli docs +fetch --doc Z1Fj...tnAc --scope section --start-block-id blkTitle
   }
 }
 ```
-`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>` 包裹，详见上文"局部读取的输出结构"。
+- `content` 的格式由 `--doc-format` 决定。`reference_map` 是结构化 sidecar，一级键表示引用组：普通资源组通常以 `block_type` 命名，二级键 `ref` 对应正文中的临时引用，其值由真实属性组成；保留组 `comments` 使用 `<ref>.data` 保存评论。XML、Markdown 和 IM Markdown 在存在可见评论时都会返回该组；Markdown 正文没有与评论 key 对应的内联引用，这是有意的协议设计。没有提取数据时，`reference_map` 可能为空。`comments.tips.data` 表示评论因数量上限被截断，文档顶层 `tips` 则给出安全回放或依赖降级提示。`content` 和 `reference_map` 属于同一份响应，应保留完整 JSON 响应；`im-markdown` 仅用于获取内容后在 `lark-im` 场景下使用。设置 `--scope` 时会被 `<fragment>` 包裹，详见下文“局部读取的输出结构”。
+- 评论内容不保证全部返回，需要详细信息时使用  `drive +list-comments` 获取完整评论。
 
 ### 理解局部读取结果
 

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

@@ -13,12 +13,15 @@ lark-cli docs +fetch --doc "文档URL或token" --scope keyword --keyword "key1|k
 # 替换文本；--content "" 可删除文本
 lark-cli docs +update --doc "xx" --command str_replace --pattern "旧内容" --content "新内容"
 
-# 替换或插入 block
+# 替换单个 block，或同父连续范围内的 block
 lark-cli docs +update --doc "xx" --command block_replace --block-id blkTarget --content '<p>新段落</p>'
+lark-cli docs +update --doc "xx" --command block_replace --start-block-id blkFirst --end-block-id blkLast --content '<p></p>'
+
 lark-cli docs +update --doc "xx" --command block_insert_after --block-id blkAnchor --content '<h2>新章节</h2><p>章节内容</p>'
 
-# 删除多个 block
-lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
+# 删除单个 block 或范围内的 block
+lark-cli docs +update --doc "xx" --command block_delete --block-id blkA
+lark-cli docs +update --doc "xx" --command block_delete --start-block-id blkFirst --end-block-id blkLast
 ```
 
 ## 推荐流程
@@ -29,8 +32,8 @@ lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
    - 只有模糊关键词：用 `--scope keyword --keyword "key1|key2" --context-before 1 --context-after 1 --detail with-ids`
    - 明确整篇重构才读 `--detail with-ids` 全文；只读摘要或确认事实时用更轻的 fetch
 2. **Diagnose（诊断问题）**：判断用户目标、当前结构、语气、重复、断流、事实口径和需要保留的资源；识别哪些 block 必须原样保留。
-3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内文本替换用 `str_replace`，但它不支持资源替换，涉及多个 block 时优先使用 `block_replace`；整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
-4. **Patch（精确修改）**：按 block / section 执行局部命令。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
+3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内文本替换用 `str_replace`，但它不支持资源替换；单个 block 用一个 `--block-id`，同一直接父节点下的连续 block 用 `--start-block-id`/`--end-block-id`。连续范围适用于 `block_replace` 和 `block_delete`。整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
+4. **Patch（精确修改）**：按 block / section 执行局部命令。替换内容必须符合目标父容器的结构；例如替换列表项范围时使用 `<li>...</li>`。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
 5. **Verify（fetch 验证）**：每轮写操作后按影响范围重新 fetch，检查用户要求、结构、语气、事实、资源块和 block ID 是否符合预期；不满足就基于最新 fetch 结果继续 Diagnose / Patch，不要沿用上一轮 block ID。
 
 除非用户明确要求完全重建，或原文已无保留价值，否则不要使用 `overwrite`；它可能丢失评论和暂不支持的资源。
@@ -51,7 +54,8 @@ lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
 |`--doc-format`|否|`xml`（默认）或 `markdown`|
 |`--content`|视指令|写入内容；`str_replace` 传空字符串可删除文本|
 |`--pattern`|视指令|`str_replace` 的简单行内匹配文本；不要用于多行、整段或多个 block|
-|`--block-id`|视指令|目标 block ID；批量删除时用逗号分隔；`-1` 表示文档末尾，`0` 表示文档开头（仅适用于支持这些锚点的指令）|
+|`--block-id`|视指令|目标 block ID；`-1` 表示文档末尾，`0` 表示文档开头（仅适用于支持这些锚点的指令）|
+|`--start-block-id` / `--end-block-id`|视指令|`block_replace` / `block_delete` 的同父连续闭区间，必须成对使用，且不能与 `--block-id` 混用；`--start-block-id` 用 `0` 表示从文档开头开始，`--end-block-id` 用 `-1` 表示到文档末尾结束|
 |`--src-block-ids`|视指令|要复制或移动的源 block ID，多个 ID 用逗号分隔|
 |`--reference-map`|否|保留或回放既有 `reference_map`，需与 `--content` 配合；支持 JSON、任务目录内的相对 `@file` 或 stdin `-`|
 |`--revision-id`|否|基准版本号，默认 `-1`（最新版本）|
@@ -63,8 +67,8 @@ lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
 |`str_replace`|全文查找替换；支持富文本内的文本替换，但不支持资源替换；涉及多个 block 时建议用 `block_replace`；空 `--content` 表示删除|`--pattern`、`--content`|
 |`block_insert_after`|在指定 block 后插入内容；逐章填充时指定对应标题的 block ID|`--block-id`、`--content`|
 |`block_copy_insert_after`|按 ID 顺序复制源 block，源 block 不变；基础标签均支持，资源块仅支持 `img`、`source`、`whiteboard`、`sheet`、`chat_card`、`sub-page-list`，不支持 `task`、`bitable`、`base_ref`、`synced_reference`、`synced_source`、`okr`|`--block-id`、`--src-block-ids`|
-|`block_replace`|替换指定 block；同一 block 一次操作中只能替换一次|`--block-id`、`--content`|
-|`block_delete`|删除一个或多个 block|`--block-id`|
+|`block_replace`|替换单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--content`，以及 `--block-id` 或 `--start-block-id`+`--end-block-id`|
+|`block_delete`|删除单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--block-id` 或 `--start-block-id`+`--end-block-id`|
 |`block_move_after`|移动已有 block，支持所有块类型；|`--block-id`、`--src-block-ids`|
 |`append`|仅在文末追加，等价于 `block_insert_after --block-id -1`|`--content`|
 |`overwrite`|清空后重写全文，丢失图片、评论等内容，非必要不使用|`--content`|

package/skills/lark-slides/references/cli/lark-slides-update-slide.md

@@ -54,6 +54,22 @@ lark-cli slides +update-slide --as user \
 
 一次请求就能同时做完改样式、插入、删除、换备注、换背景——这是 `+replace-slide` 逐元素 part 做不到的（它没法寻址背景，也没有 move 操作）。
 
+## 本地图片：`@路径` 占位符
+
+`--content` 的 XML 里写 `<img src="@./chart.png" .../>`，CLI 会：先把每个不重复的本地文件上传到这份演示文稿（`parent_type=slide_file`），再把 `src` 替换成返回的 `file_token`，最后才整页写回。
+
+占位符路径按**执行命令时的 CWD** 解析，跟 `--content @file` 所在目录无关；`@./assets/x.png` 找的是 `$PWD/assets/x.png`。
+
+```bash
+lark-cli slides +update-slide --as user \
+  --presentation "$PRES" --slide-id "$SLIDE" \
+  --content '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data><img src="@./chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/></data></slide>'
+```
+
+- 文件不存在、不是普通文件、超过 20 MB，都在**调用任何接口之前**报错，不会留下半成品。
+- 去重只在**单次调用内**生效：多页共用同一张图时，逐页更新会把它每页重传一次。这种图先用 [`+media-upload`](lark-slides-media-upload.md) 传一次，把 `file_token` 写进各页的 `src`。
+- 整页只发一个 part，所以上传是这条命令里**唯一不可逆的一半**：图先落进演示文稿的 media store，若随后 replace 失败，报错 hint 会告诉你已经传了几张，直接重试会再传一份。先 `--dry-run` 可提前看到 `images_to_upload` 和上传步骤。
+
 ## 标准读-改-写流程
 
 ```bash
@@ -130,6 +146,7 @@ lark-cli slides +xml-get --as user \
 | `xml_presentation_id` | 实际写入的演示文稿 ID |
 | `slide_id` | 与传入相同——整页覆盖不换页 id |
 | `revision_id` | 写入后的新版本号 |
+| `images_uploaded` | 仅当 `--content` 带 `@` 占位符时出现：本次去重后实际上传的图片张数 |
 
 服务端拒绝这次写入时（`failed_reason` 非空）**不会**返回成功输出，而是报错并带上原因——单个 part 承载整页，任何失败都意味着页面没被写入。
 
@@ -143,4 +160,4 @@ lark-cli slides +xml-get --as user \
 | 3350001，原因包含 `not found` | `--presentation` 不匹配，或 `--slide-id` 对应的页面已被删除 | 检查 `--presentation` 和 `--slide-id`，再用 `slides +xml-get` 回读当前页面 ID |
 | 3350001，其他 invalid param | `--content` 的 XML 结构有问题（如 `<shape>` 缺 `<content/>`、包含服务端不支持的元素） | 按 [error-handling.md](../workflow/error-handling.md) 检查 `--content` 的 XML 结构 |
 | 3350002 not found | `--revision-id` 传了不存在的版本号 | 用 `-1` 或真实存在的 `revision_id` |
-| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |
+| 1061004 / 403 | 当前身份对这份 PPT 没有编辑权限 | 检查是否拥有 `slides:presentation:update` 或 `slides:presentation:write_only` scope；wiki 链接另需 `wiki:node:read`，`@` 占位符另需 `docs:document.media:upload`；`--as bot` 还要求该 bot 对目标 PPT 有编辑权限 |

package/skills/lark-base/references/lark-base-data-query-guide.md

@@ -1,67 +0,0 @@
-# Base data-query guide
-
-Read this guide after the [data analysis SOP](lark-base-data-analysis-sop.md) enters the Cloud path and selects `+data-query`, or directly when the user explicitly asks about the `+data-query` command or DSL. It provides common aggregation fewshots; use [lark-base-data-query.md](lark-base-data-query.md) only for complete DSL fields, operators, limits, response details, or error recovery.
-
-## When to use
-
-Use `+data-query` when the user asks for server-side:
-
-- group by / aggregation
-- sum, average, min, max, count, distinct count
-- filtered aggregation
-- sorted Top N or Bottom N
-- global statistical conclusions
-
-`+data-query` can return dimension field rows, but those rows are grouped by dimension values and do not include `record_id`. Use `+record-list`, `+record-search`, or `+record-get` for row-level output, record identity, or full raw record details.
-
-## Common Fewshots
-
-Count records by a category field:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Status","alias":"status"}],"measures":[{"field_name":"Status","aggregation":"count","alias":"count"}],"shaper":{"format":"flat"}}'
-```
-
-Sum a number field by category and return Top 10:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Region","alias":"region"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"sort":[{"field_name":"total_amount","order":"desc"}],"pagination":{"limit":10},"shaper":{"format":"flat"}}'
-```
-
-Aggregate only records matching a filter:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableId":"<table_id>"}},"dimensions":[{"field_name":"Owner","alias":"owner"}],"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"filters":{"type":1,"conjunction":"and","conditions":[{"field_name":"Status","operator":"is","value":["Done"]}]},"shaper":{"format":"flat"}}'
-```
-
-## Common filter values
-
-Common `Condition.value` shapes: select `is` / `isNot` uses exactly one option
-name; datetime `is` / `isGreater` / `isLess` uses `["Today"]` or
-`["ExactDate","<epoch_ms>"]`; `isEmpty` / `isNotEmpty` uses `[]`.
-Use relative date keywords only for relative requests; see
-[lark-base-data-query.md](lark-base-data-query.md) for other field types and operators.
-
-Use `tableName` when the table ID is unavailable but the table name is known:
-
-```bash
-lark-cli base +data-query \
-  --base-token <base_token> \
-  --dsl '{"datasource":{"type":"table","table":{"tableName":"Orders"}},"measures":[{"field_name":"Amount","aggregation":"sum","alias":"total_amount"}],"shaper":{"format":"flat"}}'
-```
-
-## Routing to the DSL SSOT
-
-Read [lark-base-data-query.md](lark-base-data-query.md) when you need:
-
-- the full DSL field reference
-- supported aggregations and field types
-- filter operator details
-- pagination and result limits
-- response shape and error recovery

package/skills/lark-base/references/lark-base-record-upsert.md

@@ -1,63 +0,0 @@
-# base +record-upsert
-
-> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
-创建记录，或在带 `--record-id` 时更新记录。
-
-## 推荐命令
-
-```bash
-# 创建记录
-lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> \
-  --json '{"项目名称":"Apollo","状态":"进行中"}'
-
-# 更新记录
-lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --record-id <record_id> \
-  --json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00"}'
-```
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--base-token <token>` | 是 | Base Token |
-| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
-| `--record-id <id>` | 否 | 传入时走更新，不传时走创建 |
-| `--json <body>` | 是 | 字段写入对象，类型 `Map<FieldNameOrID, CellValue>` |
-
-## API
-
-- 创建：`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records`
-- 更新：带 `--record-id` 时改走 `PATCH /records/:record_id`
-
-## `--json` 结构
-
-- `--json` 必须是 **JSON object map**，形状是 `Map<FieldNameOrID, CellValue>`。
-- key 是字段名或字段 ID；value 是该字段的 `CellValue`。
-- 一次请求里同一字段只用一种标识，避免重复写入冲突。
-- 写入前先 `+field-list` 确认字段类型和字段名/ID。
-- CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
-
-```json
-{
-  "项目名称": "Apollo",
-  "状态": "进行中",
-  "完成时间": "2026-03-24 10:00"
-}
-```
-
-## 返回重点
-
-- 创建时返回 `record` 和 `created: true`。
-- 更新时返回 `record` 和 `updated: true`。
-- 如果写入了 `formula / lookup / created_at / updated_at / created_by / updated_by` 等只读字段，返回里可能出现 `ignored_fields`，这些字段不会被更新。
-
-## 坑点
-
-- 有 `--record-id` 就一定更新；不传就一定创建，不会自动查重或按业务键 upsert。
-- `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
-- 这是写入操作，执行前必须确认目标表和字段。
-
-## 参考
-
-- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范