@amaster.ai/pi-lark 0.1.9 → 0.1.11

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

@@ -0,0 +1,472 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+"""Check whether Lark Sheet charts have obvious placement problems.
+
+The single required argument is a spreadsheet URL or spreadsheet token. By
+default every worksheet is checked; pass --worksheet-id to restrict the check
+to one worksheet reference_id.
+
+Exit codes:
+  0: check completed and no layout issue was found
+  1: the check could not be completed (CLI/read/response error)
+  2: check completed and at least one layout issue was found
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from lark_sheet_read_cli import (
+    LarkCliError,
+    emit_error,
+    envelope_data,
+    resolve_target_sheets,
+    run_sheets,
+    sheet_identifier,
+    sheet_title,
+)
+
+ACTION = "chart_layout_check"
+DEFAULT_COLUMN_WIDTH = 105.0
+DEFAULT_ROW_HEIGHT = 27.0
+
+
+def column_to_index(column: str) -> int:
+    value = 0
+    text = str(column).strip().upper()
+    if not text or not text.isalpha():
+        raise ValueError(f"Invalid column: {column!r}")
+    for char in text:
+        value = value * 26 + ord(char) - ord("A") + 1
+    return value - 1
+
+
+def index_to_column(index: int) -> str:
+    if index < 0:
+        raise ValueError(f"Invalid column index: {index}")
+    chars: list[str] = []
+    value = index + 1
+    while value:
+        value, remainder = divmod(value - 1, 26)
+        chars.append(chr(ord("A") + remainder))
+    return "".join(reversed(chars))
+
+
+def _span_bounds(span: str, *, columns: bool) -> tuple[int, int]:
+    start, separator, end = str(span).partition(":")
+    end = end if separator else start
+    if columns:
+        return column_to_index(start), column_to_index(end)
+    return int(start) - 1, int(end) - 1
+
+
+def _size_edges(
+    groups: Any,
+    *,
+    count: int,
+    span_key: str,
+    size_key: str,
+    columns: bool,
+    default_size: float,
+) -> tuple[list[float], bool]:
+    sizes: list[float | None] = [None] * count
+    if isinstance(groups, list):
+        for group in groups:
+            if not isinstance(group, dict) or group.get(span_key) is None:
+                continue
+            start, end = _span_bounds(str(group[span_key]), columns=columns)
+            size = float(group.get(size_key, default_size))
+            for index in range(max(0, start), min(count - 1, end) + 1):
+                sizes[index] = max(0.0, size)
+
+    used_default = any(size is None for size in sizes)
+    resolved = [default_size if size is None else size for size in sizes]
+    edges = [0.0]
+    for size in resolved:
+        edges.append(edges[-1] + size)
+    return edges, used_default
+
+
+def build_layout(
+    structure: dict[str, Any], row_count: int, column_count: int
+) -> tuple[list[float], list[float], list[str]]:
+    row_groups = structure.get("row_heights")
+    column_groups = structure.get("col_widths", structure.get("column_widths"))
+    row_edges, row_defaulted = _size_edges(
+        row_groups,
+        count=row_count,
+        span_key="rows",
+        size_key="height",
+        columns=False,
+        default_size=DEFAULT_ROW_HEIGHT,
+    )
+    column_edges, column_defaulted = _size_edges(
+        column_groups,
+        count=column_count,
+        span_key="cols",
+        size_key="width",
+        columns=True,
+        default_size=DEFAULT_COLUMN_WIDTH,
+    )
+    warnings: list[str] = []
+    if row_defaulted:
+        warnings.append("部分行缺少高度信息，按 27 px 估算")
+    if column_defaulted:
+        warnings.append("部分列缺少宽度信息，按 105 px 估算")
+    return row_edges, column_edges, warnings
+
+
+def _first_dict(value: Any) -> dict[str, Any] | None:
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, list):
+        return next((item for item in value if isinstance(item, dict)), None)
+    return None
+
+
+def extract_sheet_structure(data: dict[str, Any]) -> dict[str, Any]:
+    sheet = _first_dict(data.get("sheets")) or _first_dict(data.get("sheet"))
+    return sheet or data
+
+
+def extract_charts(data: dict[str, Any], sheet_id: str, title: str) -> list[dict[str, Any]]:
+    sheets = data.get("sheets")
+    if isinstance(sheets, list):
+        for sheet in sheets:
+            if not isinstance(sheet, dict):
+                continue
+            if sheet_identifier(sheet) == sheet_id or sheet_title(sheet) == title:
+                charts = sheet.get("charts")
+                return [chart for chart in charts if isinstance(chart, dict)] if isinstance(charts, list) else []
+    charts = data.get("charts")
+    return [chart for chart in charts if isinstance(chart, dict)] if isinstance(charts, list) else []
+
+
+def chart_rectangle(
+    chart: dict[str, Any], row_edges: list[float], column_edges: list[float]
+) -> dict[str, Any]:
+    details = chart.get("details") if isinstance(chart.get("details"), dict) else chart
+    position = details.get("position") if isinstance(details.get("position"), dict) else {}
+    offset = details.get("offset") if isinstance(details.get("offset"), dict) else {}
+    size = details.get("size") if isinstance(details.get("size"), dict) else {}
+
+    row = int(position["row"])
+    column = column_to_index(str(position["col"]))
+    if row < 0 or column < 0 or row >= len(row_edges) - 1 or column >= len(column_edges) - 1:
+        raise ValueError(f"anchor outside sheet: {position!r}")
+
+    width = float(size["width"])
+    height = float(size["height"])
+    if width <= 0 or height <= 0:
+        raise ValueError(f"invalid chart size: {size!r}")
+
+    left = column_edges[column] + float(offset.get("col_offset", 0) or 0)
+    top = row_edges[row] + float(offset.get("row_offset", 0) or 0)
+    return {
+        "chart_id": str(chart.get("chart_id") or chart.get("id") or ""),
+        "anchor_cell": f"{index_to_column(column)}{row + 1}",
+        "left": left,
+        "top": top,
+        "right": left + width,
+        "bottom": top + height,
+        "width": width,
+        "height": height,
+    }
+
+
+def intersection(first: dict[str, Any], second: dict[str, Any]) -> dict[str, float] | None:
+    left = max(float(first["left"]), float(second["left"]))
+    top = max(float(first["top"]), float(second["top"]))
+    right = min(float(first["right"]), float(second["right"]))
+    bottom = min(float(first["bottom"]), float(second["bottom"]))
+    if right <= left or bottom <= top:
+        return None
+    return {
+        "width": round(right - left, 2),
+        "height": round(bottom - top, 2),
+        "area": round((right - left) * (bottom - top), 2),
+    }
+
+
+def chart_context(rectangle: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "chart_id": rectangle["chart_id"],
+        "anchor_cell": rectangle["anchor_cell"],
+        "rectangle_px": {
+            "left": round(rectangle["left"], 2),
+            "top": round(rectangle["top"], 2),
+            "right": round(rectangle["right"], 2),
+            "bottom": round(rectangle["bottom"], 2),
+            "width": round(rectangle["width"], 2),
+            "height": round(rectangle["height"], 2),
+        },
+    }
+
+
+def _covered_indexes(edges: list[float], start: float, end: float) -> list[int]:
+    return [
+        index
+        for index in range(len(edges) - 1)
+        if edges[index + 1] > start and edges[index] < end
+    ]
+
+
+def rectangle_cell_range(
+    rectangle: dict[str, Any], row_edges: list[float], column_edges: list[float]
+) -> str | None:
+    rows = _covered_indexes(row_edges, max(0.0, rectangle["top"]), rectangle["bottom"])
+    columns = _covered_indexes(column_edges, max(0.0, rectangle["left"]), rectangle["right"])
+    if not rows or not columns:
+        return None
+    return f"{index_to_column(columns[0])}{rows[0] + 1}:{index_to_column(columns[-1])}{rows[-1] + 1}"
+
+
+def _has_content(cell: Any) -> bool:
+    if not isinstance(cell, dict):
+        return False
+    for key in ("value", "formula", "note"):
+        value = cell.get(key)
+        if value not in (None, ""):
+            return True
+    return bool(cell.get("rich_text") or cell.get("multiple_values"))
+
+
+def non_empty_cells(data: dict[str, Any], sample_limit: int) -> tuple[int, list[str], bool]:
+    count = 0
+    samples: list[str] = []
+    truncated = bool(data.get("has_more"))
+    ranges = data.get("ranges")
+    if not isinstance(ranges, list):
+        return 0, [], truncated
+    for result_range in ranges:
+        if not isinstance(result_range, dict):
+            continue
+        truncated = truncated or bool(result_range.get("truncated"))
+        cells = result_range.get("cells")
+        rows = result_range.get("row_indices")
+        columns = result_range.get("col_indices")
+        if not isinstance(cells, list):
+            continue
+        for row_offset, row in enumerate(cells):
+            if not isinstance(row, list):
+                continue
+            row_number = rows[row_offset] if isinstance(rows, list) and row_offset < len(rows) else row_offset + 1
+            for column_offset, cell in enumerate(row):
+                if not _has_content(cell):
+                    continue
+                count += 1
+                if len(samples) < sample_limit:
+                    column = columns[column_offset] if isinstance(columns, list) and column_offset < len(columns) else index_to_column(column_offset)
+                    samples.append(f"{column}{row_number}")
+    return count, samples, truncated
+
+
+def _locator(target: str) -> dict[str, str]:
+    return {"url": target} if target.startswith(("http://", "https://")) else {"spreadsheet_token": target}
+
+
+def _sheet_counts(sheet: dict[str, Any]) -> tuple[int, int]:
+    row_count = int(sheet.get("row_count") or sheet.get("rowCount") or 0)
+    column_count = int(sheet.get("column_count") or sheet.get("columnCount") or 0)
+    if row_count <= 0 or column_count <= 0:
+        raise LarkCliError(f"Missing row_count/column_count for sheet {sheet_title(sheet)!r}")
+    return row_count, column_count
+
+
+def check_sheet(
+    locator: dict[str, str], sheet: dict[str, Any], *, timeout: int, sample_limit: int
+) -> dict[str, Any]:
+    sheet_id = sheet_identifier(sheet)
+    title = sheet_title(sheet)
+    row_count, column_count = _sheet_counts(sheet)
+    if not sheet_id:
+        raise LarkCliError(f"Missing sheet_id for sheet {title!r}")
+
+    structure_data = envelope_data(
+        run_sheets(
+            "+sheet-info",
+            **locator,
+            sheet_id=sheet_id,
+            flags={"include": "row_heights,col_widths"},
+            timeout=timeout,
+        )
+    )
+    row_edges, column_edges, warnings = build_layout(
+        extract_sheet_structure(structure_data), row_count, column_count
+    )
+    chart_data = envelope_data(
+        run_sheets("+chart-list", **locator, sheet_id=sheet_id, timeout=timeout)
+    )
+    charts = extract_charts(chart_data, sheet_id, title)
+
+    rectangles: list[dict[str, Any]] = []
+    unverifiable: list[dict[str, str]] = []
+    expected_chart_count = sheet.get("chart_count")
+    if expected_chart_count is not None and int(expected_chart_count) != len(charts):
+        unverifiable.append(
+            {
+                "chart_id": "",
+                "reason": (
+                    f"chart-list returned {len(charts)} charts, "
+                    f"but workbook-info reported {int(expected_chart_count)}"
+                ),
+            }
+        )
+    for chart in charts:
+        chart_id = str(chart.get("chart_id") or chart.get("id") or "")
+        if not chart_id:
+            unverifiable.append({"chart_id": "", "reason": "chart is missing chart_id"})
+            continue
+        try:
+            rectangles.append(chart_rectangle(chart, row_edges, column_edges))
+        except (KeyError, TypeError, ValueError) as exc:
+            unverifiable.append({"chart_id": chart_id, "reason": str(exc)})
+
+    overlaps: list[dict[str, Any]] = []
+    for index, first in enumerate(rectangles):
+        for second in rectangles[index + 1 :]:
+            overlap = intersection(first, second)
+            if overlap:
+                overlaps.append(
+                    {
+                        "chart_ids": [first["chart_id"], second["chart_id"]],
+                        "charts": [chart_context(first), chart_context(second)],
+                        "intersection": overlap,
+                    }
+                )
+
+    sheet_width = column_edges[-1]
+    sheet_height = row_edges[-1]
+    out_of_bounds: list[dict[str, Any]] = []
+    content_overlaps: list[dict[str, Any]] = []
+    for rectangle in rectangles:
+        overflow = {
+            "left": round(max(0.0, -rectangle["left"]), 2),
+            "top": round(max(0.0, -rectangle["top"]), 2),
+            "right": round(max(0.0, rectangle["right"] - sheet_width), 2),
+            "bottom": round(max(0.0, rectangle["bottom"] - sheet_height), 2),
+        }
+        if any(overflow.values()):
+            out_of_bounds.append({**chart_context(rectangle), "overflow_px": overflow})
+
+        covered_range = rectangle_cell_range(rectangle, row_edges, column_edges)
+        if not covered_range:
+            continue
+        cells_data = envelope_data(
+            run_sheets(
+                "+cells-get",
+                **locator,
+                sheet_id=sheet_id,
+                flags={"range": covered_range, "include": "value,formula,comment"},
+                timeout=timeout,
+            )
+        )
+        count, samples, truncated = non_empty_cells(cells_data, sample_limit)
+        if truncated:
+            unverifiable.append(
+                {"chart_id": rectangle["chart_id"], "reason": f"cells-get truncated for {covered_range}"}
+            )
+        if count:
+            content_overlaps.append(
+                {
+                    **chart_context(rectangle),
+                    "covered_range": covered_range,
+                    "non_empty_cell_count": count,
+                    "sample_cells": samples,
+                }
+            )
+
+    issue_count = len(overlaps) + len(out_of_bounds) + len(content_overlaps)
+    return {
+        "sheet_id": sheet_id,
+        "sheet_name": title,
+        "chart_count": len(charts),
+        "sheet_size_px": {"width": round(sheet_width, 2), "height": round(sheet_height, 2)},
+        "chart_overlaps": overlaps,
+        "cell_content_overlaps": content_overlaps,
+        "out_of_visible_range": out_of_bounds,
+        "unverifiable_charts": unverifiable,
+        "issue_count": issue_count,
+        "unverifiable_count": len(unverifiable),
+        "warnings": warnings,
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Check chart overlap, covered cell content, and worksheet boundary overflow."
+    )
+    parser.add_argument("sheet_id", help="Spreadsheet URL or spreadsheet token")
+    parser.add_argument("--worksheet-id", help="Only check this worksheet reference_id")
+    parser.add_argument("--timeout", type=int, default=60)
+    parser.add_argument("--sample-limit", type=int, default=10)
+    return parser.parse_args()
+
+
+def success_envelope(results: list[dict[str, Any]]) -> dict[str, Any]:
+    issue_count = sum(result["issue_count"] for result in results)
+    unverifiable_count = sum(result["unverifiable_count"] for result in results)
+    warnings = [
+        f"{result['sheet_name'] or result['sheet_id']}: {warning}"
+        for result in results
+        for warning in result["warnings"]
+    ]
+    return {
+        "ok": True,
+        "engine": "lark",
+        "action": ACTION,
+        "data": {
+            "passed": issue_count == 0 and unverifiable_count == 0,
+            "scope_note": "out_of_visible_range checks worksheet drawable bounds, not a device-specific browser viewport",
+            "summary": {
+                "worksheet_count": len(results),
+                "chart_count": sum(result["chart_count"] for result in results),
+                "issue_count": issue_count,
+                "unverifiable_count": unverifiable_count,
+            },
+            "sheets": results,
+        },
+        "warnings": warnings,
+    }
+
+
+def report_exit_code(report: dict[str, Any]) -> int:
+    if report["data"]["passed"]:
+        return 0
+    if report["data"]["summary"]["issue_count"] > 0:
+        return 2
+    return 1
+
+
+def main() -> None:
+    args = parse_args()
+    locator = _locator(args.sheet_id)
+    try:
+        workbook_data = envelope_data(
+            run_sheets("+workbook-info", **locator, timeout=args.timeout)
+        )
+        sheets = resolve_target_sheets(workbook_data, sheet_id=args.worksheet_id)
+        if not args.worksheet_id:
+            sheets = [sheet for sheet in sheets if not bool(sheet.get("is_hidden"))]
+        if not sheets:
+            raise LarkCliError("No visible worksheet matched")
+        results = [
+            check_sheet(locator, sheet, timeout=args.timeout, sample_limit=args.sample_limit)
+            for sheet in sheets
+        ]
+    except (LarkCliError, KeyError, TypeError, ValueError) as exc:
+        emit_error(ACTION, str(exc))
+        raise SystemExit(1) from exc
+
+    report = success_envelope(results)
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    exit_code = report_exit_code(report)
+    if exit_code:
+        raise SystemExit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

package/skills/lark-slides/SKILL.md

@@ -88,6 +88,7 @@ metadata:
 | 读取或分析已有 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` |
 | 查看或回滚历史版本 | 先用 `+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>` |
 | 上传或使用图片 | 先上传为 `file_token`，禁止直接写 http(s) 外链 | `slides +media-upload`、`cli/lark-slides-media-upload.md`，或 `+create --slides` 的 XML 里写 `<img src="@./path">` 占位符 |
 | 绘制图表 | 原生图表（柱状、条形、折线、面积、饼（环）、雷达、组合图）用 `<chart>`，其他（漏斗图、金字塔图、象限图、矩阵图等）用 `<shape>` + `<line>` 模拟 | `xml/xml-schema-quick-ref.md`、`xml/slides_chart_demo.xml` |
 | 绘制表格 | 优先用 `rect` 和 `text` 模拟，其他用 `<table>` | `xml/xml-schema-quick-ref.md` |
@@ -289,6 +290,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | [`+xml-get`](references/cli/lark-slides-xml-presentations-get.md) | 读取全文 XML，用 `--presentation` 指定演示文稿的 `xml_presentation_id`，用 `--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` 的元素会被删除** |
 

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

@@ -11,20 +11,20 @@
 ```bash
 # 追加到末尾（XML 直接作为参数）
 lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
+  --presentation "$PRES_ID" \
   --slide '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data></data></slide>'
 
 # XML 从文件读（推荐：避免 shell 转义和长参数截断）
 lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
+  --presentation "$PRES_ID" \
   --slide @page3.xml
 
 # XML 从 stdin 读
-cat page3.xml | lark-cli slides +add-slide --as user --presentation "$PID" --slide -
+cat page3.xml | lark-cli slides +add-slide --as user --presentation "$PRES_ID" --slide -
 
 # 插到某页之前
 lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
+  --presentation "$PRES_ID" \
   --slide @cover.xml \
   --before-slide-id "$SID"
 
@@ -34,7 +34,7 @@ lark-cli slides +add-slide --as user \
   --slide @page3.xml
 
 # 预览请求，不实际写入
-lark-cli slides +add-slide --presentation "$PID" --slide @page3.xml --dry-run
+lark-cli slides +add-slide --presentation "$PRES_ID" --slide @page3.xml --dry-run
 ```
 
 ## 参数
@@ -57,7 +57,7 @@ XML 里写 `<img src="@./chart.png" .../>`，CLI 会：先把每个不重复的
 
 ```bash
 lark-cli slides +add-slide --as user \
-  --presentation "$PID" \
+  --presentation "$PRES_ID" \
   --slide '<slide xmlns="https://www.larkoffice.com/sml/2.0"><data><img src="@./chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/></data></slide>'
 ```
 

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

@@ -11,7 +11,7 @@
 ```bash
 # 直接传 xml_presentation_id
 lark-cli slides +delete-slide --as user \
-  --presentation "$PID" \
+  --presentation "$PRES_ID" \
   --slide-id "$SID"
 
 # slides URL / wiki URL 都可以（wiki 会自动解析并校验 obj_type=slides）
@@ -20,7 +20,7 @@ lark-cli slides +delete-slide --as user \
   --slide-id "$SID"
 
 # 删之前先确认打到哪份 PPT、哪一页
-lark-cli slides +delete-slide --presentation "$PID" --slide-id "$SID" --dry-run
+lark-cli slides +delete-slide --presentation "$PRES_ID" --slide-id "$SID" --dry-run
 ```
 
 ## 参数
@@ -48,7 +48,7 @@ lark-cli slides +delete-slide --presentation "$PID" --slide-id "$SID" --dry-run
 `slide_id` 是服务端短 ID，**不能从 XML 里推导**。两个来源：
 
 1. `+create` / `+add-slide` 的返回值里存下来；
-2. 事后回读：`slides +xml-get --presentation "$PID" --output .lark-slides/plan/<deck>/readback.xml`。
+2. 事后回读：`slides +xml-get --presentation "$PRES_ID" --output .lark-slides/plan/<deck>/readback.xml`。
 
 删错页的代价高于多跑一次回读 —— 不确定就先回读 + `+screenshot` 看一眼再删。
 

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

@@ -28,9 +28,9 @@ lark-cli slides +replace-slide --as user \
 
 # 大 --parts 走文件或 stdin（auto-gen 命令不支持 @file，但 shortcut 支持）
 lark-cli slides +replace-slide --as user \
-  --presentation $PID --slide-id $SID --parts @parts.json
+  --presentation $PRES_ID --slide-id $SID --parts @parts.json
 cat parts.json | lark-cli slides +replace-slide --as user \
-  --presentation $PID --slide-id $SID --parts -
+  --presentation $PRES_ID --slide-id $SID --parts -
 
 # wiki URL 直接传（CLI 自动 get_node → 拿真实 xml_presentation_id）
 lark-cli slides +replace-slide --as user \
@@ -39,7 +39,7 @@ lark-cli slides +replace-slide --as user \
 
 # 预览（不实际调用）
 lark-cli slides +replace-slide --as user \
-  --presentation $PID --slide-id $SID --parts "$PARTS" --dry-run
+  --presentation $PRES_ID --slide-id $SID --parts "$PARTS" --dry-run
 ```
 
 ## 参数
@@ -180,16 +180,16 @@ lark-cli slides +replace-slide --as user \
 ### 给已有页加图（典型场景）
 
 ```bash
-PID=xxx
+PRES_ID=xxx
 SID=yyy
 
 # 1) 上传图片
 TOKEN=$(lark-cli slides +media-upload --as user \
-  --file ./pic.png --presentation "$PID" --jq '.data.file_token')
+  --file ./pic.png --presentation "$PRES_ID" --jq '.data.file_token')
 
 # 2) block_insert 到页末
 lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" \
+  --presentation "$PRES_ID" --slide-id "$SID" \
   --parts "$(jq -n --arg token "$TOKEN" \
     '[{action:"block_insert",insertion:("<img src=\""+$token+"\" topLeftX=\"500\" topLeftY=\"100\" width=\"200\" height=\"150\"/>")}]')"
 ```
@@ -199,11 +199,11 @@ 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\":\"$PID\",\"slide_id\":\"$SID\"}"
+  --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}"
 
 # block_replace 换掉整个标题块（id 自动注入）
 lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" \
+  --presentation "$PRES_ID" --slide-id "$SID" \
   --parts '[{"action":"block_replace","block_id":"bUn","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"}]'
 ```
 
@@ -213,7 +213,7 @@ lark-cli slides +replace-slide --as user \
 
 ```bash
 lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" \
+  --presentation "$PRES_ID" --slide-id "$SID" \
   --parts '[
     {"action":"block_replace","block_id":"bab","replacement":"<shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>新标题</p></content></shape>"},
     {"action":"block_insert","insertion":"<img src=\"<file_token>\" topLeftX=\"700\" topLeftY=\"400\" width=\"180\" height=\"100\"/>"}
@@ -225,12 +225,12 @@ lark-cli slides +replace-slide --as user \
 ```bash
 # 读时记录 revision_id
 REV=$(lark-cli slides xml_presentation.slide get --as user \
-  --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
+  --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}" \
   --jq '.data.revision_id')
 
 # 写时传 --revision-id；传不存在的版本号（超过当前 revision）返回 3350002
 lark-cli slides +replace-slide --as user \
-  --presentation "$PID" --slide-id "$SID" --revision-id "$REV" \
+  --presentation "$PRES_ID" --slide-id "$SID" --revision-id "$REV" \
   --parts "$PARTS"
 ```
 

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

@@ -98,7 +98,7 @@ lark-cli slides xml_presentation.slide get --as user --params '{
 
    ```bash
    lark-cli slides xml_presentation.slide get --as user \
-     --params "{\"xml_presentation_id\":\"$PID\",\"slide_id\":\"$SID\"}" \
+     --params "{\"xml_presentation_id\":\"$PRES_ID\",\"slide_id\":\"$SID\"}" \
      --jq '.data.slide.content' | grep -oE 'id="[^"]+"' | sed 's/id="//;s/"//'
    ```
 

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

@@ -95,10 +95,10 @@ lark-cli slides xml_presentation.slide replace --as user --params '{
 
 ```bash
 # 先拿 file_token
-TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PID" --as user --jq '.data.file_token')
+TOKEN=$(lark-cli slides +media-upload --file ./pic.png --presentation "$PRES_ID" --as user --jq '.data.file_token')
 
 lark-cli slides xml_presentation.slide replace --as user --params "{
-  \"xml_presentation_id\": \"$PID\",
+  \"xml_presentation_id\": \"$PRES_ID\",
   \"slide_id\": \"$SID\"
 }" --data "$(jq -n --arg token "$TOKEN" '{
   parts: [