@amaster.ai/pi-lark 0.1.14 → 0.1.16

package/skills/lark-sheets/scripts/lark_inspect_workbook.py

@@ -15,11 +15,14 @@ from lark_sheet_read_cli import (
     emit_error,
     emit_success,
     envelope_data,
+    is_grid_sheet,
     resolve_target_sheets,
     run_sheets,
     sheet_identifier,
     sheet_locator,
+    sheet_resource_type,
     sheet_title,
+    visible_grid_selection,
 )
 
 ACTION = "inspect_workbook"
@@ -31,6 +34,7 @@ def _sheet_summary(sheet: dict[str, Any]) -> dict[str, Any]:
         "sheet_id": sheet_identifier(sheet),
         "title": sheet_title(sheet),
         "index": sheet.get("index"),
+        "resource_type": sheet_resource_type(sheet),
         "row_count": sheet.get("row_count"),
         "column_count": sheet.get("column_count"),
         "is_hidden": sheet.get("is_hidden"),
@@ -78,29 +82,53 @@ def inspect_workbook(args) -> tuple[dict[str, Any], list[str]]:
     # An explicit selector must resolve: without require_one a typo'd
     # --sheet-id/--sheet-name silently yields sheet_count 0, which reads as
     # "empty workbook" instead of a locator error.
+    selection = visible_grid_selection(workbook, sheet_id=args.sheet_id, sheet_name=args.sheet_name)
+    all_sheets = resolve_target_sheets(workbook)
     target_sheets = resolve_target_sheets(
         workbook,
         sheet_id=args.sheet_id,
         sheet_name=args.sheet_name,
         require_one=bool(args.sheet_id or args.sheet_name),
     )
+    preview_targets = target_sheets
+    if not args.sheet_id and not args.sheet_name:
+        # is_hidden 缺失不等于隐藏：预览只是只读预检，除显式 is_hidden=true 外一律纳入，
+        # 否则旧 payload 会静默退化成「只有 summary、零预览」。写入侧的保守可见性判定
+        # 仍由 selection 负责（visibility_unknown 在那里照样排除）。
+        preview_targets = [sheet for sheet in all_sheets if is_grid_sheet(sheet) and sheet.get("is_hidden") is not True]
     if args.max_sheets < 1:
         raise LarkCliError("--max-sheets must be at least 1")
-    inspect_count = len(target_sheets)
-    if not args.sheet_id and not args.sheet_name:
-        inspect_count = min(len(target_sheets), args.max_sheets)
-        if inspect_count < len(target_sheets):
+    inspect_count = min(len(preview_targets), args.max_sheets)
+    if inspect_count < len(preview_targets):
+        warnings.append(
+            f"layout and preview skipped for {len(preview_targets) - inspect_count} visible grid sheets; "
+            "pass --sheet-id or --sheet-name to inspect one"
+        )
+    if not preview_targets and all_sheets:
+        if any(is_grid_sheet(sheet) for sheet in all_sheets):
+            warnings.append(
+                "no previewable grid sheet: every grid sheet is explicitly hidden; "
+                "pass --sheet-id or --sheet-name to inspect one anyway"
+            )
+        else:
+            # 非网格子表在 visible_grid_selection 里会被显式拒绝，别提示「带 selector 重跑」
+            # ——照做必然拿到 "is not a grid sheet"，恢复动作等于死路。
             warnings.append(
-                f"layout and preview skipped for {len(target_sheets) - inspect_count} sheets; "
-                f"pass --sheet-id or --sheet-name to inspect one"
+                "no grid sheet in this workbook: every sheet is non-grid; "
+                "read it through the matching product API instead of the grid read/write path"
             )
+    # 按对象身份而非 sheet_id 圈定预览集合：payload 缺 sheet_id 时 sheet_identifier 全为
+    # 空串，用 id 集合会把所有子表折叠成同一个 key，--max-sheets 直接失效（照样逐表发
+    # +sheet-info / +csv-get）。all_sheets 与 preview_targets 取自同一份 workbook，元素是
+    # 同一批 dict 实例，id() 比较安全。
+    preview_marks = {id(sheet) for sheet in preview_targets[:inspect_count]}
 
     profiles = []
-    for position, sheet in enumerate(target_sheets):
+    for sheet in all_sheets:
         sid = sheet_identifier(sheet)
         title = sheet_title(sheet)
         profile = _sheet_summary(sheet)
-        if position >= inspect_count:
+        if id(sheet) not in preview_marks:
             profiles.append(profile)
             continue
         locator = sheet_locator(sheet)
@@ -165,7 +193,7 @@ def inspect_workbook(args) -> tuple[dict[str, Any], list[str]]:
             }
         )
 
-    return {"sheet_count": len(target_sheets), "sheets": profiles}, warnings
+    return {"sheet_count": len(all_sheets), "sheets": profiles, "selection": selection}, warnings
 
 
 def main() -> None:

package/skills/lark-sheets/scripts/lark_sheet_read_cli.py

@@ -160,6 +160,59 @@ def extract_sheets(workbook_data: dict[str, Any]) -> list[dict[str, Any]]:
     return []
 
 
+def sheet_resource_type(sheet: dict[str, Any]) -> str:
+    return str(sheet.get("resource_type") or "")
+
+
+def is_grid_sheet(sheet: dict[str, Any]) -> bool:
+    resource_type = sheet_resource_type(sheet)
+    if resource_type == "sheet":
+        return True
+    # Legacy responses may omit resource_type but still include grid dimensions.
+    return not resource_type and sheet.get("row_count") is not None and sheet.get("column_count") is not None
+
+
+def visible_grid_selection(
+    workbook_data: dict[str, Any],
+    *,
+    sheet_id: str | None = None,
+    sheet_name: str | None = None,
+) -> dict[str, Any]:
+    """Resolve explicit targets or publish a safe default-selection decision.
+
+    Unspecified targets are never selected by index: only visible ordinary grids
+    participate, and multiple candidates remain ambiguous for the caller to match
+    by task wording or ask the user.
+    """
+    sheets = extract_sheets(workbook_data)
+    specified = {"sheet_id": sheet_id, "sheet_name": sheet_name}
+    if sheet_id or sheet_name:
+        matches = resolve_target_sheets(workbook_data, sheet_id=sheet_id, sheet_name=sheet_name, require_one=True)
+        sheet = matches[0]
+        if not is_grid_sheet(sheet):
+            raise LarkCliError(f"Sheet {sheet_title(sheet) or sheet_identifier(sheet)} is not a grid sheet; use the matching product API")
+        warnings = ["explicit_hidden_sheet"] if sheet.get("is_hidden") is True else []
+        return {"policy": "visible_grid_v1", "specified": specified, "selected": _selection_sheet(sheet), "candidates": [_selection_sheet(sheet)], "excluded": [], "ambiguous": False, "warnings": warnings, "next_action": "use selected sheet_id for grid read/write"}
+
+    candidates, excluded = [], []
+    for sheet in sheets:
+        if not is_grid_sheet(sheet):
+            excluded.append({**_selection_sheet(sheet), "reason": "non_grid"})
+        elif sheet.get("is_hidden") is True:
+            excluded.append({**_selection_sheet(sheet), "reason": "hidden"})
+        elif sheet.get("is_hidden") is not False:
+            excluded.append({**_selection_sheet(sheet), "reason": "visibility_unknown"})
+        else:
+            candidates.append(_selection_sheet(sheet))
+    candidates.sort(key=lambda item: item.get("index") if isinstance(item.get("index"), int) else 10**9)
+    selected = candidates[0] if len(candidates) == 1 else None
+    return {"policy": "visible_grid_v1", "specified": specified, "selected": selected, "candidates": candidates, "excluded": excluded, "ambiguous": len(candidates) > 1, "warnings": [], "next_action": "use selected sheet_id for grid read/write" if selected else "match task wording/title/header; do not choose by index"}
+
+
+def _selection_sheet(sheet: dict[str, Any]) -> dict[str, Any]:
+    return {"sheet_id": sheet_identifier(sheet), "title": sheet_title(sheet), "index": sheet.get("index"), "resource_type": sheet_resource_type(sheet) or "legacy_grid", "is_hidden": sheet.get("is_hidden"), "row_count": sheet.get("row_count"), "column_count": sheet.get("column_count")}
+
+
 def resolve_target_sheets(
     workbook_data: dict[str, Any],
     *,

package/skills/lark-sheets/scripts/{sheets_df.py → lark_sheets_df.py}

@@ -8,7 +8,7 @@ This is the same 7-line snippet the skill docs already inline (see
 `lark-sheets-read-data` "输出 → DataFrame（2 行 helper）"), pulled out
 so callers can `import` it instead of copy-pasting:
 
-    from sheets_df import df_to_sheet, sheet_to_df
+    from lark_sheets_df import df_to_sheet, sheet_to_df
 
 Callers run lark-cli themselves; this file is a library, not a CLI.
 """

package/skills/lark-slides/SKILL.md

@@ -85,7 +85,7 @@ metadata:
 | 一页改动很多（批量字体/配色）、要改页面背景、要删掉若干元素 | 整页覆盖，`slide_id` 和页序不变；带原 `id` 写回的元素保留 id，不带 `id` 的会作为新元素插入并拿到新 id；**代价是没写进 `--content` 的元素会被删除，所以改个别元素不要用它** | `slides +update-slide`、`lark-slides-update-slide.md` |
 | 给已有 PPT 追加或插入页面 | 一次一页，`--slide` 支持 `@file` 绕开 shell 转义 | `slides +add-slide`、`cli/lark-slides-add-slide.md` |
 | 删除页面 | 按 `slide_id` 单页删除，删前先回读确认 | `slides +delete-slide`、`cli/lark-slides-delete-slide.md` |
-| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文 XML 或读取单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`、`xml_presentation.slide.get`、`cli/lark-slides-xml-presentations-get.md` |
+| 读取或分析已有 PPT | 解析 slides/wiki token，用 shortcut 回读全文或单页 XML，保存 `xml_presentation_id`、`slide_id`、`revision_id` | `slides +xml-get`（单页传 `--slide-id` 或 `--slide-number`）、`cli/lark-slides-xml-presentations-get.md` |
 | 查看或回滚历史版本 | 先用 `+history-list` 找 `history_version_id`，再 `+history-revert`，必要时 `+history-revert-status` 轮询 | [`cli/lark-slides-history.md`](references/cli/lark-slides-history.md) |
 | 获取幻灯片页面截图 | 按页码用 `--slide-number`，按 ID 用 `--slide-id`；单张用 `--output`，批量或全量用 `--output-dir`，每批最多 10 页串行执行；截图目录复用同一任务的 deck/task 标识，后续读取返回的实际路径 | `slides +screenshot`、`cli/lark-slides-screenshot.md` |
 | 下载图片 | `--output` 选填；传入时指定单个文件路径，未传时自动保存到默认目录 `.lark-slides/media`，并按响应文件名/类型生成路径；调用后读取返回的 `path`，不要猜测文件名；直连被拒时自动回退到源文件预览 | `slides +media-download --file-token <file_token>` |
@@ -250,11 +250,11 @@ N. 结尾页：[结尾文案]
 | `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
 | `/wiki/` | `https://xxx.feishu.cn/wiki/wikcn_EXAMPLE_NODE_TOKEN_123456` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
 
-> 带 `--presentation` 的 slides shortcut 都会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。
+> 带 `--presentation` 的 slides shortcut 会自动解析以上两种 URL。
 
 ### Wiki 链接特殊处理（关键！）
 
-知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先用 Wiki shortcut 查询节点，确认 `data.obj_type == "slides"`，再用 `data.obj_token` 作为真实 presentation ID。
+知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。使用 Slides shortcut 时直接传入链接，CLI 会查询节点、校验 `data.obj_type == "slides"` 并使用 `data.obj_token`。
 
 ```bash
 lark-cli wiki +node-get --node-token 'https://xxx.feishu.cn/wiki/wikcn_EXAMPLE_NODE_TOKEN_123456' --as user --format json
@@ -262,7 +262,7 @@ lark-cli wiki +node-get --node-token 'https://xxx.feishu.cn/wiki/wikcn_EXAMPLE_N
 
 节点解析必须与后续 Slides 操作使用相同身份；下游明确使用 `--as bot` 时，这里也改为 `--as bot`。
 
-带 `--presentation` 的 slides shortcut 都会自动解析 `/wiki/` URL 并校验 `obj_type`；手动调用 `xml_presentations.*` / `xml_presentation.slide.*` 时才需要自己做这一步。
+带 `--presentation` 的 slides shortcut 都会自动解析 `/wiki/` URL 并校验 `obj_type`。
 
 ### 资源关系
 
@@ -278,30 +278,23 @@ Slides (演示文稿)
     └── slide_id (页面唯一标识)
 ```
 
-## Shortcuts 与 API
+## Shortcuts
 
-Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+Slides 相关操作使用 shortcut（`lark-cli slides +<verb> [flags]`）。
 
 | Shortcut | 说明 |
 |----------|------|
 | [`+create`](references/cli/lark-slides-create.md) | 创建 PPT，可选一步添加页面 |
 | [`+add-slide`](references/cli/lark-slides-add-slide.md) | 向已有演示文稿追加或插入**一页**（`--before-slide-id` 控制位置），XML 支持 `@file` / stdin，`<img src="@./path">` 占位符自动上传 |
 | [`+delete-slide`](references/cli/lark-slides-delete-slide.md) | 按 `slide_id` 删除**一页** |
-| [`+xml-get`](references/cli/lark-slides-xml-presentations-get.md) | 读取全文 XML，用 `--presentation` 指定演示文稿的 `xml_presentation_id`，用 `--output` 把 XML 存到本地文件（必须是 CWD 内的相对路径，如 `.lark-slides/plan/<deck>/readback.xml`） |
+| [`+xml-get`](references/cli/lark-slides-xml-presentations-get.md) | 读取全文或单页 XML；用 `--presentation` 指定演示文稿，单页传 `--slide-id` 或 `--slide-number`；用 `--output` 把 XML 存到本地文件（必须是 CWD 内的相对路径，如 `.lark-slides/plan/<deck>/readback.xml`） |
 | [`+screenshot`](references/cli/lark-slides-screenshot.md) | 把幻灯片页面截图保存为本地图片；用 `--slide-number` 指定页码（从 1 开始，多页重复传入）或用 `--slide-id` 指定页面；单张用 `--output .lark-slides/screenshots/<deck-or-task-id>/page-01`，批量用 `--output-dir .lark-slides/screenshots/<deck-or-task-id>`（一次最多 10 页）；后续必须读取返回的 `output` / `screenshots[].path` |
 | [`+media-upload`](references/cli/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | `+media-download` | 根据 Slides 图片 `file_token` 下载本地图片；`--output` 选填，未传时使用 `--output-dir` 默认值 `.lark-slides/media` 并自动生成文件名；调用后使用返回的 `path`，不要猜测实际路径；直连下载无权限时自动回退到源文件预览 |
 | [`+replace-slide`](references/cli/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
 | [`+update-slide`](references/cli/lark-slides-update-slide.md) | 把一整页 XML 交给已有页面，页面变成 `--content` 描述的样子；能一次改样式/插入/删除/备注/背景，`slide_id` 和页序不变。**没写进 `--content` 的元素会被删除** |
 
-没有 Shortcut 覆盖时使用原生 API。高频资源：`slides +xml-get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
-
-```bash
-lark-cli schema slides.<resource>.<method>   # 调用 API 前必须先查看参数结构
-lark-cli slides <resource> <method> [flags] # 调用 API
-```
-
-> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
+本 skill 已覆盖的 Slides 操作必须使用上表 shortcut；执行前读取对应 reference，按其中参数和约束执行。
 
 ## 核心规则
 
@@ -311,7 +304,7 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内；不要混淆 XML 元素 `<content>` 和 `--parts` 的 JSON 字段：编写 `--parts` 时，`block_replace` 装载 XML 使用标准字段 `replacement`，`block_insert` 使用 `insertion`
 5. **保存关键 ID**：后续操作需要 `xml_presentation_id`、`slide_id`、`revision_id`
 6. **删除谨慎**：删除不可逆，删前先回读确认 `slide_id`
-7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；一页改动很多或要改背景用 `+update-slide` 整页覆盖（保 `slide_id` 和页序），多页整页重建就对每页各跑一次 `+update-slide`，不要用 `slides +create` 新建整份 PPT；追加/插入单页用 `+add-slide`、删除单页用 `+delete-slide`，只有这些 shortcut 未覆盖的参数才手动调 `slide.create` / `slide.delete`
-8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传，或在 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（slides upload API 不支持分片上传）。
+7. **编辑已有页面优先原链接更新**：修改单个 shape/img 用 `+replace-slide`（`block_replace` / `block_insert`），不要整页重建；一页改动很多或要改背景用 `+update-slide` 整页覆盖（保 `slide_id` 和页序），多页整页重建就对每一页各跑一次 `+update-slide`，不要用 `slides +create` 新建整份 PPT；追加/插入单页用 `+add-slide`、删除单页用 `+delete-slide`
+8. **`<img src>` 只能用上传到飞书 drive 的 `file_token`，禁止使用 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 在 PPT 里通常不显示或显示破图。流程必须是「先把图存到本地 → 用 `slides +media-upload` 上传，或在 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符自动上传 → 拿 `file_token` 写进 `<img src>`」。如果用户给了网图链接，先 `curl`/下载到 CWD 内再走上传流程，不要直接把外链 URL 塞进 `src`。**图片最大 20 MB**（媒体上传不支持分片）。
 
-> **注意**：如果 md 内容与 `xml/slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。
+> **注意**：如果 md 内容与 `xml/slides_xml_schema_definition.xml` 不一致，以后者为准。

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

@@ -28,7 +28,7 @@ lark-cli slides +add-slide --as user \
   --slide @cover.xml \
   --before-slide-id "$SID"
 
-# wiki 链接（CLI 自动 wiki.spaces.get_node 解析，并校验 obj_type=slides）
+# wiki 链接（CLI 自动通过 node_by_token 接口解析，并校验 obj_type=slides）
 lark-cli slides +add-slide --as user \
   --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" \
   --slide @page3.xml

package/skills/lark-slides/references/cli/lark-slides-create.md

@@ -58,7 +58,7 @@ lark-cli slides +create --title "项目汇报" --slide @./slide-01.xml --dry-run
 > [!IMPORTANT]
 > 不带页面参数时，`slides +create` 只创建空白演示文稿。创建后用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 slide 内容。
 >
-> 带了页面时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
+> 带了页面时，CLI 先创建空白演示文稿，再逐页添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
 >
 > 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
 >
@@ -114,7 +114,7 @@ lark-cli slides +create --title "项目汇报" --slide @./slide-01.xml --dry-run
 ]
 ```
 
-数组元素是页面 XML 原文。包装成 API 所需的 `{"slide": {"content": …}}` 并逐页调用由 CLI 完成。
+数组元素是页面 XML 原文；请求封装和逐页提交由 `+create` 完成。
 
 > [!WARNING]
 > `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议改用 `--slide @page-01.xml` 逐页传文件。
@@ -142,7 +142,7 @@ lark-cli slides +create --as user --title "图测试" --slide @./slide-01.xml
 - 路径相对于**当前工作目录**（CWD）解析；**必须是 CWD 内的相对路径**（如 `./pic.png`、`./assets/x.png`）
 - 同一份图被多次引用时**只上传一次**（按路径去重）
 - `src` 不以 `@` 开头的会原样保留，但**只允许写 `slides +media-upload` 拿到的 `file_token`**；**禁止写 http(s) 外链 URL**：飞书 slides 渲染端不会代理外链图片，外链 src 通常显示破图。要用网图必须先下载到 CWD 内、再走上传流程
-- 单张图片最大 20 MB（slides upload API 不支持分片上传）
+- 单张图片最大 20 MB（媒体上传不支持分片）
 - 校验阶段就会检查所有占位符文件存在及大小；缺文件或超限直接报错，不会创建空白 PPT 占位
 - 创空白 PPT → 上传所有图 → 替换 token → 逐页创建 slide，按这个顺序执行
 

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

@@ -2,7 +2,7 @@
 
 从演示文稿删除**一页**，按 `slide_id` 指定。只改一页里的局部内容用 [`+replace-slide`](lark-slides-replace-slide.md)，不要删了重建。
 
-`--presentation` 接受 token / `/slides/` URL / `/wiki/` URL，ID 是普通 flag 而不是 `--params` JSON 串。
+`--presentation` 接受 token / `/slides/` URL / `/wiki/` URL，页面 ID 通过 `--slide-id` 传入。
 
 > `--slide-id` 只接受单个 ID —— 不支持逗号分隔的列表（`+screenshot` 的 `--slide-id` 支持，这个不支持），也不支持按页号删。
 

package/skills/lark-slides/references/cli/lark-slides-history.md

@@ -12,7 +12,7 @@
 4. 使用 `+history-revert` 发起回滚。接口会立即返回 `task_id`，回滚任务在服务端异步执行。
 5. 如果返回 `status: running`，保存 `task_id`，按照返回的 `poll_after_ms` 等待后调用 `+history-revert-status`。任务创建成功后，不得因为状态查询失败而重新发起回滚。
 6. 状态变为 `done`、`partial_failed` 或 `failed` 后停止轮询；达到整体轮询上限时也停止轮询，并向用户返回 `task_id` 和当前状态。
-7. 回滚完成后，用 `slides +xml-get` 或 `slides xml_presentations get` 读取演示文稿确认内容。
+7. 回滚完成后，用 `slides +xml-get` 读取演示文稿确认内容。
 
 ## 按 revision_id 或时间点回滚
 
@@ -123,10 +123,3 @@ lark-cli slides +history-revert-status --presentation "<slides_url_or_token>" --
 ```bash
 lark-cli slides +xml-get --presentation "<slides_url_or_token>" --output ./presentation.xml
 ```
-
-如果只需要快速检查返回结构，也可以走 raw OpenAPI：
-
-```bash
-lark-cli api get "/open-apis/slides_ai/v1/xml_presentations/<xml_presentation_id>" \
-  --params '{"revision_id":-1}'
-```

package/skills/lark-slides/references/cli/lark-slides-media-upload.md

@@ -15,7 +15,7 @@ lark-cli slides +media-upload --as user \
   --file ./chart.png \
   --presentation "https://xxx.feishu.cn/slides/slidesXXXXXXXXXXXXXXXXXXXXXX"
 
-# 传 wiki URL（CLI 自动 wiki.spaces.get_node 解析为真实 token，校验 obj_type=slides）
+# 传 wiki URL（CLI 自动通过 node_by_token 接口解析真实 token，校验 obj_type=slides）
 lark-cli slides +media-upload --as user \
   --file ./pic.png \
   --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX"
@@ -43,7 +43,7 @@ lark-cli slides +media-upload --file ./pic.png --presentation $PRES_ID --dry-run
 
 | 参数 | 必填 | 说明 |
 |------|------|------|
-| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（slides upload API 不支持分片上传）。**仅支持 png / jpeg / gif / bmp / tiff / webp** |
+| `--file` | 是 | 本地图片路径，**必须是 CWD 内的相对路径**（如 `./pic.png`）。**最大 20 MB**（媒体上传不支持分片）。**仅支持 png / jpeg / gif / bmp / tiff / webp** |
 | `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
 
 > [!IMPORTANT]
@@ -78,21 +78,16 @@ lark-cli slides +replace-slide --as user \
 1. **`<img>` 坐标避开现有元素** —— 先读现有元素 bbox 挑空白区；空间不够就先用 `block_replace` 挪动/缩小现有元素后再放图
 2. **`<img>` 的 `width:height` 对齐原图比例** —— 比例不一致会被裁剪，参见 [xml-schema-quick-ref.md](../xml/xml-schema-quick-ref.md) `<img>` 说明
 
-## 工作原理
+## 上传约束
 
-`+media-upload` 内部调用 `POST /open-apis/drive/v1/medias/upload_all`（单次上传，最大 20 MB），固定使用：
-
-- `parent_type=slide_file`（slides 后端唯一接受的取值）
-- `parent_node=<xml_presentation_id>`
-
-**不要尝试用 `slides_image`、`slide_image` 等 parent_type**——后端会返回 1061001 / 1061002 错误。这是 slides 的特殊约定。
+`+media-upload` 会处理 Slides 所需的媒体归属参数；调用者只需传入 `--file` 和 `--presentation`。单张图片最大 20 MB。
 
 ## 常见错误
 
 | 错误码 | 含义 | 解决方案 |
 |--------|------|----------|
-| 1061002 | params error / 不支持的 parent_type | 不要用原生 API 自己拼 parent_type；用 `+media-upload` 即可 |
-| 1061004 | forbidden：当前身份对该演示文稿无编辑权限 | 确认当前身份（user 或 bot）对目标 PPT 有编辑权限。bot 模式常见原因：PPT 不是该 bot 创建的——可用 `+create --as bot` 新建，或以 user 身份给 bot 授权 `lark-cli drive permission.members create --as user ...` |
+| 1061002 | params error / 不支持的 parent_type | 使用 `+media-upload`；它会采用 Slides 所需的 `parent_type` |
+| 1061004 | forbidden：当前身份对该演示文稿无编辑权限 | 确认当前身份（user 或 bot）对目标 PPT 有编辑权限。bot 模式常见原因：PPT 不是该 bot 创建的——可用 `+create --as bot` 新建，或以 user 身份执行 `lark-cli drive +member-add --as user --token "$PRES_ID" --type slides --member-id "$BOT_OPEN_ID" --member-type openid --perm full_access --yes` 给 bot 授权 |
 | 1061044 | parent node not exist | `--presentation` 给的 token 不对，或不是 slides 类型 |
 | 403 | 权限不足 | 检查 `docs:document.media:upload` scope；wiki URL 还需要 `wiki:node:read` |
 

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

@@ -4,10 +4,10 @@
 
 > **编写 `--parts` 时只使用标准 action 和字段**：`block_replace` 使用 `block_id` + `replacement`，`block_insert` 使用 `insertion`（可选 `insert_before_block_id`）。不要根据其他 API 或自然语言猜 action、字段名；具体结构以本文表格为准。
 
-相比直接调 `xml_presentation.slide.replace`，这个 shortcut 的四个额外价值：
+此 shortcut 的四个关键能力：
 
 1. `--presentation` 接受 `xml_presentation_id` / `/slides/` URL / `/wiki/` URL（wiki 自动解析）；
-2. `block_replace` 的 `replacement` 根元素 `id="<block_id>"` 由 CLI 自动注入——底层 API 的硬约束（不注入返回 3350001）；直接调原生 API 需自己加，用 Shortcut 则自动注入；
+2. `block_replace` 的 `replacement` 根元素 `id` 会被 CLI 自动注入为 `block_id`；3350001 时优先确认 `block_id` 来自最新 `+xml-get --slide-id` 且存在于当前页；
 3. `<shape>` 元素缺少 `<content/>` 子元素时由 CLI 自动注入——SML 2.0 schema 要求每个 `<shape>` 必须有 `<content/>` 子元素，缺失同样触发 3350001；自闭合的 `<shape .../>` 也会被自动展开为 `<shape ...><content/></shape>`；
 4. 3350001 错误时提供上下文感知的 hint，帮助 AI agent 和用户快速定位原因。
 
@@ -32,7 +32,7 @@ lark-cli slides +replace-slide --as user \
 cat parts.json | lark-cli slides +replace-slide --as user \
   --presentation $PRES_ID --slide-id $SID --parts -
 
-# wiki URL 直接传（CLI 自动 get_node → 拿真实 xml_presentation_id）
+# wiki URL 直接传（CLI 自动通过 node_by_token 拿真实 xml_presentation_id）
 lark-cli slides +replace-slide --as user \
   --presentation "https://xxx.feishu.cn/wiki/wikcnXXXXXX" --slide-id pfG \
   --parts '[{"action":"block_insert","insertion":"<shape type=\"rect\" width=\"100\" height=\"100\"/>"}]'
@@ -47,7 +47,7 @@ lark-cli slides +replace-slide --as user \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--presentation` | 是 | `xml_presentation_id`、`/slides/<token>` URL，或 `/wiki/<token>` URL |
-| `--slide-id` | 是 | 页面 ID（`xml_presentation.slide.get` / `slides +xml-get` 都能拿到） |
+| `--slide-id` | 是 | 页面 ID（通过 `slides +xml-get` 获取） |
 | `--parts` | 是 | JSON 数组（`[{...}, ...]`），单次最多 200 条。支持 `@<file>` 和 `-`（stdin）读取 |
 | `--revision-id` | 否 | 基础版本号；默认 `-1` 表示基于最新版执行；传具体版本号时，服务端以该版本为 base 执行；**传不存在的版本号（超过当前 revision）返回 3350002** |
 | `--tid` | 否 | 并发事务 ID；多人协作长事务才用，单次单人调用留空 |
@@ -63,7 +63,7 @@ lark-cli slides +replace-slide --as user \
 | 字段 | 必填 | 说明 |
 |------|------|------|
 | `action` | 是 | `"block_replace"` |
-| `block_id` | 是 | 目标块的 3 位 short element ID（从 `slide.get` 返回 XML 里读） |
+| `block_id` | 是 | 目标块的 3 位 short element ID（从 `+xml-get --slide-id` 返回 XML 里读） |
 | `replacement` | 是 | 新 XML 片段；**根元素 `id` 会被 CLI 自动注入为 `block_id`**，用户不用自己加（如果已经加了且不一致会被覆盖为正确值） |
 
 ### action = `block_insert`
@@ -102,7 +102,7 @@ lark-cli slides +replace-slide --as user \
 | `<img>` | 图片 | `src` 必须是 [`+media-upload`](lark-slides-media-upload.md) 返回的 `file_token`，不能是 URL |
 | `<icon>` | 图标 | `iconType` 取自 iconpark 资源；语义图标先用 `scripts/iconpark_tool.py search` 检索 |
 | `<table>` | 表格 | 整表替换会**重建内部 td id**，旧 td block_id 立即失效 |
-| `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `slide.get` 拿到的 td id |
+| `<td>` | 单元格局部替换 | 只能 `block_replace`，不能 `block_insert`；`block_id` 必须是最新 `+xml-get --slide-id` 拿到的 td id |
 | `<chart>` | 图表（line/bar/column/pie/area/radar/combo） | 必须嵌 `<chartPlotArea>` + `<chartData>` + `<dim1>/<dim2>/<chartField>` |
 
 **不可作为根元素**：
@@ -137,7 +137,7 @@ lark-cli slides +replace-slide --as user \
 </table>
 ```
 
-`<td>`（`block_replace` 单元格；`block_id` 必须是最新 `slide.get` 拿到的 td id）：
+`<td>`（`block_replace` 单元格；`block_id` 必须是最新 `+xml-get --slide-id` 拿到的 td id）：
 ```xml
 <td><content><p>新内容</p></content></td>
 ```
@@ -198,8 +198,8 @@ lark-cli slides +replace-slide --as user \
 
 ```bash
 # 先拿原页 XML，从里面找到标题块的 3 位 short id（如 bUn）
-lark-cli slides xml_presentation.slide get --as user \
-  --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}"
+lark-cli slides +xml-get --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" --raw
 
 # block_replace 换掉整个标题块（id 自动注入）
 lark-cli slides +replace-slide --as user \
@@ -224,8 +224,8 @@ lark-cli slides +replace-slide --as user \
 
 ```bash
 # 读时记录 revision_id
-REV=$(lark-cli slides xml_presentation.slide get --as user \
-  --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}" \
+REV=$(lark-cli slides +xml-get --as user \
+  --presentation "$PRES_ID" --slide-id "$SID" \
   --jq '.data.revision_id')
 
 # 写时传 --revision-id；传不存在的版本号（超过当前 revision）返回 3350002
@@ -238,8 +238,8 @@ lark-cli slides +replace-slide --as user \
 
 | 现象 | 原因 | 对策 |
 |------|------|------|
-| 3350001 + hint "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新 `slide.get` 拿最新 XML，按里面的 short ID 再填 |
-| 3350002 not found | `--revision-id` 传了不存在的版本号（超过当前 revision） | 用 `-1` 或用 `slide.get` 拿到的有效 `revision_id` |
+| 3350001 + hint "block_id not found" | `parts[i].block_id` 在当前页不存在 | 重新用 `+xml-get --slide-id` 拿最新 XML，按里面的 short ID 再填 |
+| 3350002 not found | `--revision-id` 传了不存在的版本号（超过当前 revision） | 用 `-1` 或用 `+xml-get --slide-id` 拿到的有效 `revision_id` |
 | `--parts invalid JSON` | JSON 本身不完整，或被 shell 引号/转义破坏 | 将数组写入 `parts.json` 后传 `--parts @parts.json`，或通过 stdin 传给 `--parts -` |
 | `--parts[i] action "str_replace" is not supported` | CLI 不暴露 `str_replace` | 把替换需求改写成 `block_replace` / `block_insert` |
 | `--parts[i] action "page_replace" / "slide_replace" means whole-page replacement` | 把整页更新意图传给了块级 shortcut | 改用 [`slides +update-slide`](lark-slides-update-slide.md) 整页原地写回 |
@@ -248,12 +248,11 @@ lark-cli slides +replace-slide --as user \
 | `--parts[i] unknown field "insertion"; it belongs to block_insert` | 字段和 `action` 不配对 | 按 action 取字段：`block_replace` = `block_id` + `replacement`；`block_insert` = `insertion` (+ `insert_before_block_id`) |
 | `--parts[i] (block_replace) requires non-empty block_id` / `replacement` | 字段名对，但值缺失或是空串 | 按 parts 元素结构补齐值 |
 | `<img>` 不显示 / 显示破图 | `src` 写了外链 URL | 换成通过 [`+media-upload`](lark-slides-media-upload.md) 拿到的 `file_token` |
-| 3350001 | `replacement` 不是合法单根 XML 片段，或 `block_id` 不存在 | CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，重新 `slide.get` 拿最新 XML 确认 `block_id` 存在；检查 XML 结构是否合法；坐标是否超出 960×540 |
+| 3350001 | `replacement` 不是合法单根 XML 片段，或 `block_id` 不存在 | CLI 已自动注入 `id` 和 `<content/>`；如果仍报错，重新 `+xml-get --slide-id` 拿最新 XML 确认 `block_id` 存在；检查 XML 结构是否合法；坐标是否超出 960×540 |
 | 403 | 权限不足 | 需要 `slides:presentation:update` 或 `slides:presentation:write_only`；wiki URL 还需要 `wiki:node:read` |
 
 ## 相关命令
 
-- [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 读原页拿 `block_id` / `revision_id`
-- [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
+- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读原页拿 `block_id` / `revision_id`
 - [+media-upload](lark-slides-media-upload.md) — 上传图片拿 `file_token`
 - [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环 + 决策树

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

@@ -36,7 +36,7 @@ lark-cli slides +update-slide --as user \
 | `--tid` | 否 | 调用方提供的任务/事务标识，CLI 原样透传；用于关联同一编辑任务或重试，不等同于版本前置条件，不能单独保证并发冲突时拒绝写入。一般留空 |
 
 `@file` 和 `+xml-get --output` 一样**只接受当前目录下的相对路径**，绝对路径会被拒。
-命令别名：`slides +update`（隐藏）；服务别名：`lark-cli slide …` 等价于 `lark-cli slides …`。
+命令别名：`slides +update`（隐藏）。
 
 如果要求“从读取之后页面一旦变化就不再写入”，不能只传 `--revision-id` 或 `--tid`。写入前必须再次用 `+xml-get` 回读最新版，比较读取期间是否发生变化；有变化时先基于最新版重新合并本次修改，再执行整页写回。当前 shortcut 不提供严格的 compare-and-swap 保证。
 
@@ -106,7 +106,7 @@ lark-cli slides +update-slide --as user \
 
 - **只改一个元素** → 用 [`+replace-slide`](lark-slides-replace-slide.md)，一条 `block_replace` part 更省，也不用带上整页
 - **要改多个页面** → 对每一页各跑一次本命令
-- **要新建页面** → `slides +create` 或 `xml_presentation.slide create`
+- **要新建页面** → `slides +create` 或 `slides +add-slide`
 
 ## 提交前与写入后验证
 

package/skills/lark-slides/references/cli/lark-slides-xml-presentation-slide-get.md

@@ -1,110 +1,5 @@
-# lark-slides xml_presentation.slide get
+# slides +xml-get（单页读取兼容入口）
 
-## 用途
+本文档已合并至 [lark-slides-xml-presentations-get.md](lark-slides-xml-presentations-get.md)。
 
-按 `slide_id` 拉取指定演示文稿单页的 XML 内容（可指定历史版本）。常用于"读-改-写"编辑闭环的第一步。
-
-## 命令
-
-```bash
-lark-cli slides xml_presentation.slide get --as user --params '<json_params>'
-```
-
-## 参数说明
-
-| 参数 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `--params` | JSON string | 是 | 路径参数与查询参数 |
-
-### params JSON 结构
-
-```json
-{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "revision_id": -1
-}
-```
-
-| 字段 | 类型 | 必需 | 说明 |
-|------|------|------|------|
-| `xml_presentation_id` | string | 是 | 目标演示文稿唯一标识 |
-| `slide_id` | string | 是 | 目标页面唯一标识 |
-| `revision_id` | integer | 否 | 版本号，`-1` 表示最新版（默认）|
-
-## 使用示例
-
-### 读最新版本
-
-```bash
-lark-cli slides xml_presentation.slide get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id"
-}'
-```
-
-### 只提取 XML 内容
-
-```bash
-lark-cli slides xml_presentation.slide get --as user \
-  --params '{"xml_presentation_id":"slides_example_presentation_id","slide_id":"slide_example_id"}' \
-  --jq '.data.slide.content'
-```
-
-### 读指定历史版本
-
-```bash
-lark-cli slides xml_presentation.slide get --as user --params '{
-  "xml_presentation_id": "slides_example_presentation_id",
-  "slide_id": "slide_example_id",
-  "revision_id": 42
-}'
-```
-
-## 返回值
-
-```json
-{
-  "ok": true,
-  "identity": "user",
-  "data": {
-    "slide": {
-      "slide_id": "slide_example_id",
-      "content": "<slide id=\"slide_example_id\"><style/><data>...</data></slide>"
-    },
-    "revision_id": 100
-  }
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `data.slide.slide_id` | string | 页面唯一标识 |
-| `data.slide.content` | string | 页面完整 XML（`<slide>` 根节点，不含 xmlns）|
-| `data.revision_id` | integer | 此次读到的版本号，可用于后续 replace 的乐观锁 |
-
-## 常见错误
-
-| 错误码 | 含义 | 解决方案 |
-|--------|------|----------|
-| 404 | 演示文稿或页面不存在 | 检查 `xml_presentation_id` / `slide_id` |
-| 403 | 权限不足 | 需要 `slides:presentation:read` scope，并对该 PPT 有访问权限 |
-| 400 | `revision_id` 不存在 | 传了无效版本号，用 `-1` 或真实存在的版本号 |
-
-## 注意事项
-
-1. **执行前必做**：`lark-cli schema slides.xml_presentation.slide.get` 查看最新参数结构
-2. **block_id 提取**：返回 XML 里每个顶层块（shape、img、table、chart 等）的 `id` 属性即为 `block_id`，通常是 3 字符短码，例如 `<shape id="bUn" ...>`。用以下命令列出当前页所有 block_id：
-
-   ```bash
-   lark-cli slides xml_presentation.slide get --as user \
-     --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}" \
-     --jq '.data.slide.content' | grep -oE 'id="[^"]+"' | sed 's/id="//;s/"//'
-   ```
-
-## 相关命令
-
-- [slides +replace-slide](lark-slides-replace-slide.md) — 块级替换 shortcut（推荐）
-- [xml_presentation.slide replace](lark-slides-xml-presentation-slide-replace.md) — 底层 replace API 参考
-- [slides +xml-get](lark-slides-xml-presentations-get.md) — 读整个 PPT 并保存到本地文件
-- [slides-editing.md](../workflow/slides-editing.md) — 读-改-写闭环
+此文件保留已发布路径兼容性；后续引用请使用该正式 reference。