@amaster.ai/pi-lark 0.1.2-beta.52 → 0.1.2-beta.54

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

@@ -0,0 +1,176 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+"""Range and coordinate helpers for Lark Sheet scripts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+CELL_RE = re.compile(r"^\$?([A-Za-z]+)\$?([1-9][0-9]*)$")
+ROW_RE = re.compile(r"^\$?([1-9][0-9]*)$")
+COLUMN_RE = re.compile(r"^\$?([A-Za-z]+)$")
+
+
+@dataclass(frozen=True)
+class RangeBounds:
+    start_row: int
+    start_col: int
+    end_row: int
+    end_col: int
+
+    @property
+    def row_count(self) -> int:
+        return self.end_row - self.start_row + 1
+
+    @property
+    def col_count(self) -> int:
+        return self.end_col - self.start_col + 1
+
+
+def col_to_index(col: str) -> int:
+    value = 0
+    for char in col.strip().upper():
+        if not ("A" <= char <= "Z"):
+            raise ValueError(f"Invalid column: {col}")
+        value = value * 26 + (ord(char) - ord("A") + 1)
+    if value <= 0:
+        raise ValueError(f"Invalid column: {col}")
+    return value
+
+
+def index_to_col(index: int) -> str:
+    if index < 1:
+        raise ValueError(f"Column index must be >= 1: {index}")
+    chars = []
+    n = index
+    while n:
+        n, rem = divmod(n - 1, 26)
+        chars.append(chr(ord("A") + rem))
+    return "".join(reversed(chars))
+
+
+def parse_cell(cell_ref: str) -> tuple[int, int]:
+    match = CELL_RE.match(cell_ref.strip())
+    if not match:
+        raise ValueError(f"Invalid cell reference: {cell_ref}")
+    col, row = match.groups()
+    return int(row), col_to_index(col)
+
+
+def _parse_endpoint(endpoint: str) -> tuple[str, int, int] | tuple[str, int]:
+    cell = CELL_RE.match(endpoint)
+    if cell:
+        col, row = cell.groups()
+        return "cell", int(row), col_to_index(col)
+    row = ROW_RE.match(endpoint)
+    if row:
+        return "row", int(row.group(1))
+    column = COLUMN_RE.match(endpoint)
+    if column:
+        return "column", col_to_index(column.group(1))
+    raise ValueError(f"Invalid A1 range endpoint: {endpoint}")
+
+
+def parse_range(
+    range_ref: str,
+    *,
+    max_row: int | None = None,
+    max_col: int | None = None,
+) -> RangeBounds:
+    """Parse the A1 range forms accepted by ``+csv-get``.
+
+    Open-ended forms need the caller's actual returned grid dimensions. This
+    keeps generated ranges finite without guessing a spreadsheet-wide limit.
+    """
+    ref = range_ref.strip()
+    if "!" in ref:
+        _, ref = ref.rsplit("!", 1)
+    if not ref:
+        raise ValueError(f"Invalid A1 range: {range_ref}")
+    parts = ref.split(":")
+    if len(parts) > 2:
+        raise ValueError(f"Invalid A1 range: {range_ref}")
+    start = _parse_endpoint(parts[0])
+    end = _parse_endpoint(parts[-1])
+
+    if len(parts) == 1:
+        if start[0] != "cell":
+            raise ValueError(f"A1 range must include a cell or ':' separator: {range_ref}")
+        _, row, col = start
+        return RangeBounds(row, col, row, col)
+
+    if start[0] == end[0] == "cell":
+        _, start_row, start_col = start
+        _, end_row, end_col = end
+    elif start[0] == end[0] == "row":
+        _, start_row = start
+        _, end_row = end
+        start_col = 1
+        if max_col is None:
+            raise ValueError(f"Range needs a maximum column: {range_ref}")
+        end_col = max_col
+    elif start[0] == end[0] == "column":
+        _, start_col = start
+        _, end_col = end
+        start_row = 1
+        if max_row is None:
+            raise ValueError(f"Range needs a maximum row: {range_ref}")
+        end_row = max_row
+    elif start[0] == "cell" and end[0] == "column":
+        _, start_row, start_col = start
+        _, end_col = end
+        if max_row is None:
+            raise ValueError(f"Range needs a maximum row: {range_ref}")
+        end_row = max(start_row, max_row)
+    elif start[0] == "cell" and end[0] == "row":
+        _, start_row, start_col = start
+        _, end_row = end
+        if max_col is None:
+            raise ValueError(f"Range needs a maximum column: {range_ref}")
+        end_col = max(start_col, max_col)
+    else:
+        raise ValueError(f"Invalid A1 range: {range_ref}")
+    return RangeBounds(min(start_row, end_row), min(start_col, end_col), max(start_row, end_row), max(start_col, end_col))
+
+
+def format_cell(row: int, col: int) -> str:
+    if row < 1:
+        raise ValueError(f"Row must be >= 1: {row}")
+    return f"{index_to_col(col)}{row}"
+
+
+def format_range(start_row: int, start_col: int, end_row: int, end_col: int) -> str:
+    bounds = RangeBounds(
+        min(start_row, end_row),
+        min(start_col, end_col),
+        max(start_row, end_row),
+        max(start_col, end_col),
+    )
+    start = format_cell(bounds.start_row, bounds.start_col)
+    end = format_cell(bounds.end_row, bounds.end_col)
+    return start if start == end else f"{start}:{end}"
+
+
+def iter_cells(bounds: RangeBounds):
+    for row in range(bounds.start_row, bounds.end_row + 1):
+        for col in range(bounds.start_col, bounds.end_col + 1):
+            yield row, col
+
+
+def ranges_intersect(a: RangeBounds, b: RangeBounds) -> bool:
+    return not (
+        a.end_row < b.start_row
+        or b.end_row < a.start_row
+        or a.end_col < b.start_col
+        or b.end_col < a.start_col
+    )
+
+
+def range_union(a: RangeBounds, b: RangeBounds) -> RangeBounds:
+    return RangeBounds(
+        min(a.start_row, b.start_row),
+        min(a.start_col, b.start_col),
+        max(a.end_row, b.end_row),
+        max(a.end_col, b.end_col),
+    )

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

@@ -0,0 +1,184 @@
+# Copyright (c) 2026 Lark Technologies Pte. Ltd.
+# SPDX-License-Identifier: MIT
+"""Read-only Lark Sheet subset wrapper for the helper scripts."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import Any
+
+
+class LarkCliError(RuntimeError):
+    def __init__(self, message: str, *, cmd: list[str] | None = None):
+        super().__init__(message)
+        self.cmd = cmd or []
+
+
+def add_spreadsheet_args(
+    parser,
+    *,
+    require_sheet: bool = False,
+    allow_sheet: bool = True,
+) -> None:
+    spreadsheet = parser.add_mutually_exclusive_group(required=True)
+    spreadsheet.add_argument("--url")
+    spreadsheet.add_argument("--spreadsheet-token")
+    if allow_sheet:
+        sheet = parser.add_mutually_exclusive_group(required=require_sheet)
+        sheet.add_argument("--sheet-id")
+        sheet.add_argument("--sheet-name")
+
+
+def _append_flag(cmd: list[str], name: str, value: Any) -> None:
+    flag = f"--{name.replace('_', '-')}"
+    if value is None:
+        return
+    if isinstance(value, bool):
+        cmd.append(flag if value else f"{flag}=false")
+        return
+    cmd.extend([flag, str(value)])
+
+
+def run_sheets(
+    shortcut: str,
+    *,
+    url: str | None = None,
+    spreadsheet_token: str | None = None,
+    sheet_id: str | None = None,
+    sheet_name: str | None = None,
+    flags: dict[str, Any] | None = None,
+    timeout: int = 60,
+) -> dict[str, Any]:
+    if bool(url) == bool(spreadsheet_token):
+        raise LarkCliError("Pass exactly one of --url or --spreadsheet-token")
+    if sheet_id and sheet_name:
+        raise LarkCliError("Pass only one of --sheet-id or --sheet-name")
+
+    cmd = ["lark-cli", "sheets", shortcut]
+    _append_flag(cmd, "url", url)
+    _append_flag(cmd, "spreadsheet_token", spreadsheet_token)
+    _append_flag(cmd, "sheet_id", sheet_id)
+    _append_flag(cmd, "sheet_name", sheet_name)
+    for key, value in (flags or {}).items():
+        _append_flag(cmd, key, value)
+
+    try:
+        completed = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise LarkCliError("lark-cli not found", cmd=cmd) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise LarkCliError(f"lark-cli timed out after {timeout}s", cmd=cmd) from exc
+
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout or "").strip()
+        raise LarkCliError(detail or f"lark-cli exited with {completed.returncode}", cmd=cmd)
+
+    try:
+        envelope = json.loads(completed.stdout)
+    except json.JSONDecodeError as exc:
+        snippet = completed.stdout[:500].replace("\n", "\\n")
+        raise LarkCliError(f"lark-cli stdout was not JSON: {snippet}", cmd=cmd) from exc
+
+    if isinstance(envelope, dict) and envelope.get("ok") is False:
+        raise LarkCliError(json.dumps(envelope, ensure_ascii=False), cmd=cmd)
+    if not isinstance(envelope, dict):
+        raise LarkCliError("lark-cli returned a non-object JSON payload", cmd=cmd)
+    return envelope
+
+
+def envelope_data(envelope: dict[str, Any]) -> dict[str, Any]:
+    data = envelope.get("data")
+    return data if isinstance(data, dict) else envelope
+
+
+def emit_success(action: str, data: dict[str, Any], warnings: list[str] | None = None) -> None:
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "engine": "lark",
+                "action": action,
+                "data": data,
+                "warnings": warnings or [],
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+
+
+def emit_error(action: str, message: str, warnings: list[str] | None = None) -> None:
+    print(
+        json.dumps(
+            {
+                "ok": False,
+                "engine": "lark",
+                "action": action,
+                "error": message,
+                "warnings": warnings or [],
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    sys.exit(1)
+
+
+def sheet_title(sheet: dict[str, Any]) -> str:
+    return str(sheet.get("title") or sheet.get("sheet_name") or sheet.get("name") or "")
+
+
+def sheet_identifier(sheet: dict[str, Any]) -> str:
+    return str(sheet.get("sheet_id") or sheet.get("id") or "")
+
+
+def sheet_locator(sheet: dict[str, Any]) -> dict[str, str]:
+    sid = sheet_identifier(sheet)
+    if sid:
+        return {"sheet_id": sid}
+    title = sheet_title(sheet)
+    if title:
+        return {"sheet_name": title}
+    return {}
+
+
+def extract_sheets(workbook_data: dict[str, Any]) -> list[dict[str, Any]]:
+    sheets = workbook_data.get("sheets")
+    if isinstance(sheets, list):
+        return [sheet for sheet in sheets if isinstance(sheet, dict)]
+    workbook = workbook_data.get("workbook")
+    if isinstance(workbook, dict) and isinstance(workbook.get("sheets"), list):
+        return [sheet for sheet in workbook["sheets"] if isinstance(sheet, dict)]
+    return []
+
+
+def resolve_target_sheets(
+    workbook_data: dict[str, Any],
+    *,
+    sheet_id: str | None = None,
+    sheet_name: str | None = None,
+    require_one: bool = False,
+) -> list[dict[str, Any]]:
+    sheets = extract_sheets(workbook_data)
+    if sheet_id:
+        matches = [sheet for sheet in sheets if sheet_identifier(sheet) == sheet_id]
+    elif sheet_name:
+        matches = [sheet for sheet in sheets if sheet_title(sheet) == sheet_name]
+    else:
+        matches = sheets
+
+    if require_one:
+        if len(matches) == 1:
+            return matches
+        if not matches:
+            raise LarkCliError("No matching sheet found")
+        raise LarkCliError("Multiple sheets matched; pass --sheet-id or --sheet-name")
+    return matches

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

@@ -19,11 +19,29 @@ import pandas as pd
 
 def df_to_sheet(df, name, formats=None):
     """Pack one DataFrame into one entry of a `+table-put --sheets` payload."""
+    packed = json.loads(df.to_json(orient="split", date_format="iso"))
+    # The protocol requires string column names. pandas keeps integer labels
+    # (e.g. the default RangeIndex columns 0/1/2) as JSON numbers, while the
+    # dtypes dict keys get stringified during JSON serialization — the CLI
+    # then rejects `columns` ("cannot unmarshal number into … type string")
+    # and the dtype lookup would miss anyway. Stringify every key once, and
+    # refuse to continue when that conversion silently merges two columns.
+    normalized_labels = [str(c) for c in df.columns]
+    columns = [str(c) for c in packed["columns"]]
+    if normalized_labels != columns:
+        columns = normalized_labels
+    if len(set(columns)) != len(columns):
+        raise ValueError(
+            "column labels collide after str() conversion; "
+            "rename the DataFrame columns before packing"
+        )
+    packed["columns"] = columns
+    dtype_values = list(df.dtypes)
     return {
         "name": name,
-        **json.loads(df.to_json(orient="split", date_format="iso")),
-        "dtypes": df.dtypes.astype(str).to_dict(),
-        **({"formats": formats} if formats else {}),
+        **packed,
+        "dtypes": {key: str(dtype) for key, dtype in zip(columns, dtype_values)},
+        **({"formats": {str(k): v for k, v in formats.items()}} if formats else {}),
     }
 
 

package/skills/lark-slides/SKILL.md

@@ -79,10 +79,10 @@ metadata:
 
 | 用户需求 | 优先动作 | 关键文档 / 命令 |
 |----------|----------|-----------------|
-| 新建 PPT | 先规划 `slide_plan.json`，再按复杂度选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`lark-slides-create.md`、`slides +create`、`slides +add-slide`、`lark-slides-add-slide.md`（两步创建逐页添加） |
+| 新建 PPT | 先规划 `slide_plan.json`，再按页数选择一步或两步创建 | `planning-layer.md`、`visual-planning.md`、`asset-planning.md`、`lark-slides-create.md`、`slides +create`、`slides +add-slide`、`lark-slides-add-slide.md`（两步创建逐页添加） |
 | 用户要求使用模板，或提供 PPTX 文件要求修改、美化 | 将模板导入为 Slides 再编辑 | `lark-slides-pptx-template-workflows.md` |
-| 编辑单个标题、文本块、图片或局部元素 | 优先块级替换/插入，不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
-| 一页改动很多、要改背景或删除若干元素，或要整页重建一页/多页 | 在原 presentation 内按页重建，不创建新 Slides 链接 | `slides +replace-pages`、`lark-slides-replace-pages.md` |
+| 编辑单个标题、文本块、图片或局部元素 | 块级替换/插入，**只动点名的 block，同页其他元素不受影响**；不改页序 | `slides +replace-slide`、`lark-slides-replace-slide.md` |
+| 一页改动很多（批量字体/配色）、要改页面背景、要删掉若干元素 | 整页覆盖，`slide_id` 和页序不变；带原 `id` 写回的元素保留 id，不带 `id` 的会作为新元素插入并拿到新 id；**代价是没写进 `--content` 的元素会被删除，所以改个别元素不要用它** | `slides +update-slide`、`lark-slides-update-slide.md` |
 | 给已有 PPT 追加或插入页面 | 一次一页，`--slide` 支持 `@file` 绕开 shell 转义 | `slides +add-slide`、`lark-slides-add-slide.md` |
 | 删除页面 | 按 `slide_id` 单页删除，删前先回读确认 | `slides +delete-slide`、`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`、`lark-slides-xml-presentations-get.md` |
@@ -106,15 +106,13 @@ metadata:
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
 
-**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`slides +add-slide`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
+**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create`、`slides +add-slide` 或 `slides +update-slide` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
 
-**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素，并使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py) 统一检查 XML、越界、重叠、空白页和内容稀疏风险。**
+**CRITICAL — 创建、大幅改写或每次通过 `slides +update-slide` 整页写回后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素，并使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py) 统一检查 XML、越界、重叠、空白页和内容稀疏风险。**
 
 **CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
 
-**CRITICAL — 当前 Slide Engine 后端仍在灰度期间，`slides +replace-pages --help` 及其输出中的 `deprecated` 字段会提示改用 `+update-slide`，该提示在本 skill 生效期间暂不适用；MUST 忽略该提示并继续使用 `+replace-pages`，不得切换到 `+update-slide`。后端全量并由新版 skill 恢复路由后，再使用 `+update-slide`。**
-
-**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；一页改动很多、要改背景或删除若干元素，以及一页或多页的整页重建，优先用 [`+replace-pages`](references/lark-slides-replace-pages.md) 在原 presentation 内按页重建，避免 `slides +create` 生成新链接。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
+**编辑已有幻灯片页面**：单个标题、文本块、图片或局部元素优先用 [`+replace-slide`](references/lark-slides-replace-slide.md)（块级替换/插入，不动页序）；一页里改动很多（例如批量换字体）、要改背景、或要删掉若干元素时用 [`+update-slide`](references/lark-slides-update-slide.md) 整页覆盖（`slide_id` 和页序不变，但没写进 `--content` 的元素会被删除）；**多页大改就对每一页各跑一次 `+update-slide`**。选择 action 和完整读-改-写流程见 [`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)。
 
 **用户要求使用模板**：按 [lark-slides-pptx-template-workflows.md](references/lark-slides-pptx-template-workflows.md) 处理。
 
@@ -153,7 +151,7 @@ lark-cli auth login --domain slides
 - 创建：[`lark-slides-create.md`](references/lark-slides-create.md)、[`lark-slides-add-slide.md`](references/lark-slides-add-slide.md)（逐页添加 / 给已有 PPT 追加页面）
 - 删除页面：[`lark-slides-delete-slide.md`](references/lark-slides-delete-slide.md)
 - 阅读：[`lark-slides-xml-presentations-get.md`](references/lark-slides-xml-presentations-get.md)
-- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-replace-pages.md`](references/lark-slides-replace-pages.md)
+- 编辑：[`lark-slides-edit-workflows.md`](references/lark-slides-edit-workflows.md)、[`lark-slides-replace-slide.md`](references/lark-slides-replace-slide.md)、[`lark-slides-update-slide.md`](references/lark-slides-update-slide.md)
 - 历史版本：[`lark-slides-history.md`](references/lark-slides-history.md)
 - 截图：[`lark-slides-screenshot.md`](references/lark-slides-screenshot.md)
 - 图片：[`lark-slides-media-upload.md`](references/lark-slides-media-upload.md)
@@ -249,7 +247,7 @@ N. 结尾页：[结尾文案]
 | URL 格式 | 示例 | Token 类型 | 处理方式 |
 |----------|------|-----------|----------|
 | `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
-| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
+| `/wiki/` | `https://xxx.feishu.cn/wiki/wikcn_EXAMPLE_NODE_TOKEN_123456` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
 
 > 带 `--presentation` 的 slides shortcut 都会自动解析以上两种 URL；直接调用原生 API 时仍需手动解析 wiki 链接。
 
@@ -258,7 +256,7 @@ N. 结尾页：[结尾文案]
 知识库链接（`/wiki/TOKEN`）不能直接当 `xml_presentation_id`。直接调用原生 API 前，先用 Wiki shortcut 查询节点，确认 `data.obj_type == "slides"`，再用 `data.obj_token` 作为真实 presentation ID。
 
 ```bash
-lark-cli wiki +node-get --node-token '<wiki_url>' --as user --format json
+lark-cli wiki +node-get --node-token 'https://xxx.feishu.cn/wiki/wikcn_EXAMPLE_NODE_TOKEN_123456' --as user --format json
 ```
 
 节点解析必须与后续 Slides 操作使用相同身份；下游明确使用 `--as bot` 时，这里也改为 `--as bot`。
@@ -292,7 +290,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli slides +<verb> [flags]`
 | [`+screenshot`](references/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/lark-slides-media-upload.md) | 上传本地图片到指定演示文稿，返回 `file_token`（用作 `<img src="...">`），最大 20 MB |
 | [`+replace-slide`](references/lark-slides-replace-slide.md) | 对已有幻灯片页面进行块级替换/插入（`block_replace` / `block_insert`），自动注入 id 和 `<content/>`，不改变页序 |
-| [`+replace-pages`](references/lark-slides-replace-pages.md) | 在原演示文稿内重建一页或多页：先创建新页到旧页前，再删除旧页；适合已有 Slides 的整页大改，不新建链接 |
+| [`+update-slide`](references/lark-slides-update-slide.md) | 把一整页 XML 交给已有页面，页面变成 `--content` 描述的样子；能一次改样式/插入/删除/备注/背景，`slide_id` 和页序不变。**没写进 `--content` 的元素会被删除** |
 
 没有 Shortcut 覆盖时使用原生 API。高频资源：`slides +xml-get` 读取全文；`xml_presentation.slide.create/delete/get/replace` 管理单页。
 
@@ -311,7 +309,7 @@ lark-cli slides <resource> <method> [flags] # 调用 API
 4. **文本通过 `<content>` 表达**：必须用 `<content><p>...</p></content>`，不能把文字直接写在 shape 内；注意 `<content>` 只是 XML 元素，不是 `--parts` 的字段名——part 里装 XML 的字段，`block_replace` 是 `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`），不要整页重建；一页改动很多、要改背景或删除若干元素，以及一页或多页的整页重建，用 `+replace-pages`，不要用 `slides +create` 新建整份 PPT；追加/插入单页用 `+add-slide`、删除单页用 `+delete-slide`，只有这些 shortcut 未覆盖的参数才手动调 `slide.create` / `slide.delete`
+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 不支持分片上传）。
 
 > **注意**：如果 md 内容与 `slides_xml_schema_definition.xml` 或 `lark-cli schema slides.<resource>.<method>` 输出不一致，以后两者为准。

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

@@ -11,14 +11,14 @@
 
 | 场景 | 推荐方式 |
 |------|----------|
-| 简单 XML（1-3 页、结构简单、几乎无复杂中文和特殊字符） | `slides +create --slides '[...]'` 一步创建 |
-| 复杂 XML（多页、含中文、大段文本、复杂布局、嵌套引号、特殊字符较多） | **两步创建**：先 `slides +create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加（`--slide @file` 可绕开 shell 转义） |
+| 不超过 10 页 | 每页存一个 XML 文件，`slides +create --slide @page-01.xml --slide @page-02.xml ...` 一步创建 |
+| 超过 10 页 | **两步创建**：先 `slides +create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 |
 | 已有 PPT 继续追加或插入页面 | 使用 [`+add-slide`](lark-slides-add-slide.md)，必要时配合 `--before-slide-id` |
 
-> [!WARNING]
-> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议使用两步创建法。
 > [!IMPORTANT]
-> `slides +create --slides` 底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
+> `slides +create` 带页面时底层会逐页创建，不是原子操作。中途失败时先记录 `xml_presentation_id`，回读确认当前状态，再继续修复或追加。
+
+**CRITICAL — 提交前必须先跑版式 lint**：把待提交的 `<slide>` XML 存成本地文件，运行 [`scripts/xml_text_overlap_lint.py`](../scripts/xml_text_overlap_lint.py)，`summary.error_count` 必须为 0。
 
 ## 命令
 
@@ -26,31 +26,22 @@
 # 创建空白 PPT
 lark-cli slides +create --title "项目汇报"
 
-# 创建 PPT + 添加 slide 页面
-lark-cli slides +create --title "项目汇报" --slides '[
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>封面</p></content></shape></data></slide>",
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data><shape type=\"text\" topLeftX=\"80\" topLeftY=\"80\" width=\"800\" height=\"120\"><content textType=\"title\"><p>第二页</p></content></shape></data></slide>"
-]'
+# 创建 PPT + 添加页面：每页一个 XML 文件，重复 --slide，顺序即页序
+lark-cli slides +create --as user --title "项目汇报" \
+  --slide @.lark-slides/plan/project/slide-01.xml \
+  --slide @.lark-slides/plan/project/slide-02.xml
+
+# 已有组装好的 JSON 数组：从文件或 stdin 读
+lark-cli slides +create --as user --title "项目汇报" --slides @./deck.json
+cat deck.json | lark-cli slides +create --as user --title "项目汇报" --slides -
 
 # 以应用身份创建（自动授权当前用户）
 lark-cli slides +create --title "项目汇报" --as bot
 
 # 预览（不执行）
-lark-cli slides +create --title "项目汇报" --slides '[...]' --dry-run
-```
-
-用 `--slides` 一步创建时，按页保存 XML，再用 `jq --rawfile` 组装参数，不要手写转义：
-
-```bash
-lark-cli slides +create --as user --title "项目汇报" \
-  --slides "$(jq -n \
-    --rawfile s1 .lark-slides/plan/project/slide-01.xml \
-    --rawfile s2 .lark-slides/plan/project/slide-02.xml \
-    '[$s1, $s2]')"
+lark-cli slides +create --title "项目汇报" --slide @./slide-01.xml --dry-run
 ```
 
-`--rawfile` 会把文件内容作为字符串读入 JSON，自动处理 XML 中的引号和换行；不要手动拼接带大量转义符的 JSON 字符串。
-
 ## 返回值
 
 工具成功执行后，返回一个 JSON 对象，包含以下字段：
@@ -59,15 +50,15 @@ lark-cli slides +create --as user --title "项目汇报" \
 - **`title`**（string）：演示文稿标题
 - **`url`**（string，可选）：演示文稿的在线链接，如有返回则务必展示给用户（需要 drive 相关权限；若获取失败则不返回此字段）
 - **`revision_id`**（integer）：演示文稿版本号
-- **`slide_ids`**（string[]，可选）：仅传 `--slides` 时返回，成功添加的页面 ID 列表
-- **`slides_added`**（integer，可选）：仅传 `--slides` 时返回，成功添加的页面数量
-- **`images_uploaded`**（integer，可选）：仅 `--slides` 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
+- **`slide_ids`**（string[]，可选）：带页面创建时返回，成功添加的页面 ID 列表
+- **`slides_added`**（integer，可选）：带页面创建时返回，成功添加的页面数量
+- **`images_uploaded`**（integer，可选）：页面 XML 中含 `@<本地路径>` 占位符时返回，已上传的去重后图片数量
 - **`permission_grant`**（object，可选）：仅 `--as bot` 时返回，说明是否已自动为当前 CLI 用户授予可管理权限
 
 > [!IMPORTANT]
-> 不传 `--slides` 时，`slides +create` 只创建空白演示文稿。创建后用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 slide 内容。
+> 不带页面参数时，`slides +create` 只创建空白演示文稿。创建后用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加 slide 内容。
 >
-> 传了 `--slides` 时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
+> 带了页面时，CLI 先创建空白演示文稿，再逐页调用 slide 创建接口添加页面。如果某一页添加失败，CLI 会停止并报错，已创建的演示文稿和已添加的页面会保留。
 >
 > 如果演示文稿是**以应用身份（bot）创建**的，如 `lark-cli slides +create --as bot`，CLI 会**尝试为当前 CLI 用户自动授予该演示文稿的 `full_access`（可管理权限）**。
 >
@@ -83,27 +74,67 @@ lark-cli slides +create --as user --title "项目汇报" \
 | 参数 | 必填 | 说明 |
 |------|------|------|
 | `--title` | 否 | 演示文稿标题（不传则默认 "Untitled"） |
-| `--slides` | 否 | slide 内容 JSON 数组，每个元素是一个 `<slide>` XML 字符串（最多 10 个；超过 10 页请先用 `+create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加） |
+| `--slide` | 否 | 一页 `<slide>` XML，或 `@路径`；可重复，最多 10 次。格式见[页面输入形式](#页面输入形式) |
+| `--slides` | 否 | 页面 XML 的 JSON 字符串数组，最多 10 个；支持 `@文件` 和 `-`（stdin）。格式见[页面输入形式](#页面输入形式) |
+
+10 页是 CLI 的上限，服务端每次只接收一页。超过 10 页时先用 `+create` 创建空白 PPT，再用 [`+add-slide`](lark-slides-add-slide.md) 逐页添加。
+
+两种形式的每一页都会在发请求前校验成「单个完整的 `<slide>` 文档」。不合格的页在创建演示文稿之前报错并指出页序号，不会留下空壳演示文稿。
+
+## 页面输入形式
+
+页面内容有 `--slide` 和 `--slides` 两种传法，二选一，同时传会报错。
 
-## `--slides` 参数格式
+两种形式的 `@路径` 都必须是 CWD 内的相对路径（如 `./slide-01.xml`）；绝对路径和 `../` 会被拒（报 `invalid file path`）。XML 写在别的目录时，先 `cd` 过去或把文件拷进 CWD 再执行。
+
+### `--slide`：一页一个文件
+
+可重复，重复次数即页数，出现顺序即页序。值是一页完整的 `<slide>` XML，或读取该 XML 的 `@路径`。
+
+文件内容就是这一页 XML 本身，外面没有引号或方括号：
+
+```xml
+<slide xmlns="https://www.larkoffice.com/sml/2.0">
+  <data>…第1页…</data>
+</slide>
+```
+
+文件内容不需要转义：引号、换行、中文原样写。
+
+### `--slides`：一个 JSON 数组
+
+值是 JSON 字符串数组，每个元素是一整页 XML，支持 `@文件` 和 `-`（stdin）。
+
+文件内容是一个 JSON 文档，XML 以 JSON 字符串出现，其中的 `"` 写作 `\"`，换行写作 `\n`：
 
 ```json
 [
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\">...第1页XML...</slide>",
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\">...第2页XML...</slide>"
+  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data>…第1页…</data></slide>",
+  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data>…第2页…</data></slide>"
 ]
 ```
 
-JSON string 数组，每个元素是一页 slide 的完整 XML。CLI 内部负责包装成 API 所需的 `{"slide": {"content": "..."}}` 格式并逐页调用。
+数组元素是页面 XML 原文。包装成 API 所需的 `{"slide": {"content": …}}` 并逐页调用由 CLI 完成。
+
+> [!WARNING]
+> `--slides '[...]'` 的风险点主要在 shell 参数传递，而不是单纯页数。即使只有 1 页，只要 XML 足够复杂，也建议改用 `--slide @page-01.xml` 逐页传文件。
 
-### 本地图片：`@<path>` 占位符
+## 本地图片：`@<path>` 占位符
 
 `<img>` 元素的 `src` 属性如果以 `@` 开头，CLI 会把它当作本地文件路径，自动上传到当前演示文稿，并把占位符替换为返回的 `file_token`。
 
+`slide-01.xml`：
+
+```xml
+<slide xmlns="https://www.larkoffice.com/sml/2.0">
+  <data>
+    <img src="@./assets/chart.png" topLeftX="100" topLeftY="100" width="320" height="180"/>
+  </data>
+</slide>
+```
+
 ```bash
-lark-cli slides +create --as user --title "图测试" --slides '[
-  "<slide xmlns=\"https://www.larkoffice.com/sml/2.0\"><data><img src=\"@./assets/chart.png\" topLeftX=\"100\" topLeftY=\"100\" width=\"320\" height=\"180\"/></data></slide>"
-]'
+lark-cli slides +create --as user --title "图测试" --slide @./slide-01.xml
 ```
 
 行为：
@@ -120,11 +151,11 @@ lark-cli slides +create --as user --title "图测试" --slides '[
 
 ## 创建后续步骤
 
-如果没有使用 `--slides`，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：
+创建空白 PPT 时，`slides +create` 返回的 `xml_presentation_id` 用于后续操作：
 
 ```bash
 # 第 1 步：创建空白 PPT
-PRES_ID=$(lark-cli slides +create --title "项目汇报" | jq -r '.data.xml_presentation_id')
+PRES_ID=$(lark-cli slides +create --title "项目汇报" --jq '.data.xml_presentation_id')
 
 # 第 2 步：逐页添加（--slide 支持 @file，复杂 XML 优先走文件）
 lark-cli slides +add-slide --as user \