sophhub 0.4.19 → 0.4.21

package/skills/feishu-notes-assistant-universal/src/scripts/openclaw_notes_crud.py

@@ -1,547 +1,547 @@
-#!/usr/bin/env python3
-"""OpenClaw note CRUD orchestrator for Feishu docs."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-import subprocess
-import sys
-from typing import Any
-
-
-class CLIError(Exception):
-    def __init__(self, message: str, code: str = "cli_error", detail: Any = None):
-        super().__init__(message)
-        self.code = code
-        self.detail = detail
-
-
-DOCX_URL_RE = re.compile(r"/docx/([A-Za-z0-9_-]+)")
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Feishu note CRUD via bundled lark-cli")
-    parser.add_argument(
-        "--op",
-        required=True,
-        choices=[
-            "create",
-            "read",
-            "update",
-            "delete",
-            "search",
-            "media-insert",
-            "media-download",
-            "comment",
-            "section-update",
-        ],
-        help="note operation",
-    )
-    parser.add_argument("--doc", help="doc token or doc/docx URL")
-    parser.add_argument("--title", help="note title")
-    parser.add_argument("--markdown", help="note markdown content")
-    parser.add_argument("--query", help="search keyword")
-    parser.add_argument("--mode", default="append", help="update mode")
-    parser.add_argument("--new-title", help="rename title while update")
-    parser.add_argument("--selection-by-title", help="title-based locator for update")
-    parser.add_argument(
-        "--selection-with-ellipsis", help="content locator for range update/delete"
-    )
-    parser.add_argument("--folder-token", help="target folder token when creating")
-    parser.add_argument("--wiki-node", help="target wiki node token when creating")
-    parser.add_argument("--wiki-space", help="target wiki space when creating")
-    parser.add_argument("--page-size", default="15", help="search page size")
-    parser.add_argument("--page-token", help="search page token")
-    parser.add_argument("--file", help="local file path for media insert")
-    parser.add_argument(
-        "--media-type",
-        default="image",
-        choices=["image", "file"],
-        help="media type for insert: image | file",
-    )
-    parser.add_argument(
-        "--token", help="media token or whiteboard token for media download"
-    )
-    parser.add_argument(
-        "--resource-type",
-        default="media",
-        choices=["media", "whiteboard"],
-        help="resource type for media download: media | whiteboard",
-    )
-    parser.add_argument("--output", help="local output path for media download")
-    parser.add_argument(
-        "--overwrite", action="store_true", help="overwrite existing download file"
-    )
-    parser.add_argument("--caption", help="image caption for media insert")
-    parser.add_argument(
-        "--align", choices=["left", "center", "right"], help="image alignment"
-    )
-    parser.add_argument("--comment", help="plain text comment body")
-    parser.add_argument(
-        "--comment-json",
-        help="raw reply_elements JSON array for advanced comment payloads",
-    )
-    parser.add_argument(
-        "--block-id", help="comment anchor block ID for local comment mode"
-    )
-    parser.add_argument(
-        "--full-comment",
-        action="store_true",
-        help="create full-document comment instead of local comment",
-    )
-    parser.add_argument("--section-title", help="title locator like '## Section'")
-    parser.add_argument(
-        "--section-mode",
-        choices=["replace", "delete", "insert_before", "insert_after"],
-        default="replace",
-        help="section update mode",
-    )
-    parser.add_argument("--as", dest="identity", default="user", help="user | bot")
-    parser.add_argument("--config-dir", help="optional LARKSUITE_CLI_CONFIG_DIR")
-    parser.add_argument("--lark-cli-bin", default="lark-cli", help="lark-cli binary")
-    return parser.parse_args()
-
-
-def build_env(config_dir: str | None) -> dict[str, str]:
-    env = os.environ.copy()
-    if config_dir:
-        env["LARKSUITE_CLI_CONFIG_DIR"] = config_dir
-    return env
-
-
-def run_cli(
-    cli_bin: str, env: dict[str, str], args: list[str], cwd: str | None = None
-) -> Any:
-    proc = subprocess.run(
-        [cli_bin] + args,
-        capture_output=True,
-        text=True,
-        env=env,
-        cwd=cwd,
-    )
-    stdout = proc.stdout.strip()
-    stderr = proc.stderr.strip()
-
-    parsed: Any = None
-    if stdout:
-        try:
-            parsed = json.loads(stdout)
-        except json.JSONDecodeError as exc:
-            raise CLIError(
-                f"lark-cli returned non-JSON stdout: {stdout[:400]}",
-                code="invalid_cli_output",
-                detail={"stderr": stderr, "args": args},
-            ) from exc
-
-    if proc.returncode != 0:
-        detail = parsed if isinstance(parsed, dict) else {"stderr": stderr}
-        raise CLIError(
-            f"lark-cli command failed: {' '.join(args)}",
-            code="lark_cli_failed",
-            detail=detail,
-        )
-    return parsed
-
-
-def localize_cli_path(path: str) -> tuple[str, str]:
-    abs_path = os.path.abspath(path)
-    parent = os.path.dirname(abs_path) or os.getcwd()
-    return parent, f"./{os.path.basename(abs_path)}"
-
-
-def unwrap_payload(payload: Any) -> Any:
-    if isinstance(payload, dict) and "ok" in payload:
-        if not payload.get("ok", False):
-            error = payload.get("error") or {}
-            raise CLIError(
-                error.get("message", "lark-cli returned an error envelope"),
-                code=error.get("type", "lark_error"),
-                detail=payload,
-            )
-        return payload.get("data")
-    return payload
-
-
-def parse_doc_token(doc: str) -> str:
-    if not doc:
-        return ""
-    if doc.startswith("http://") or doc.startswith("https://"):
-        match = DOCX_URL_RE.search(doc)
-        if match:
-            return match.group(1)
-        return ""
-    return doc
-
-
-def create_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.title:
-        raise CLIError("missing --title for create", code="validation")
-    if not args.markdown:
-        raise CLIError("missing --markdown for create", code="validation")
-    cmd = [
-        "docs",
-        "+create",
-        "--as",
-        args.identity,
-        "--title",
-        args.title,
-        "--markdown",
-        args.markdown,
-    ]
-    if args.folder_token:
-        cmd.extend(["--folder-token", args.folder_token])
-    if args.wiki_node:
-        cmd.extend(["--wiki-node", args.wiki_node])
-    if args.wiki_space:
-        cmd.extend(["--wiki-space", args.wiki_space])
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
-    if not isinstance(data, dict):
-        raise CLIError("unexpected docs +create payload", code="invalid_create_payload")
-    return data
-
-
-def read_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.doc:
-        raise CLIError("missing --doc for read", code="validation")
-    cmd = [
-        "docs",
-        "+fetch",
-        "--as",
-        args.identity,
-        "--doc",
-        args.doc,
-        "--format",
-        "json",
-    ]
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
-    if not isinstance(data, dict):
-        raise CLIError("unexpected docs +fetch payload", code="invalid_read_payload")
-    return data
-
-
-def update_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.doc:
-        raise CLIError("missing --doc for update", code="validation")
-    cmd = [
-        "docs",
-        "+update",
-        "--as",
-        args.identity,
-        "--doc",
-        args.doc,
-        "--mode",
-        args.mode,
-    ]
-    if args.markdown:
-        cmd.extend(["--markdown", args.markdown])
-    if args.new_title:
-        cmd.extend(["--new-title", args.new_title])
-    if args.selection_by_title:
-        cmd.extend(["--selection-by-title", args.selection_by_title])
-    if args.selection_with_ellipsis:
-        cmd.extend(["--selection-with-ellipsis", args.selection_with_ellipsis])
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
-    if not isinstance(data, dict):
-        raise CLIError("unexpected docs +update payload", code="invalid_update_payload")
-    return data
-
-
-def search_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    cmd = [
-        "docs",
-        "+search",
-        "--as",
-        args.identity,
-        "--format",
-        "json",
-        "--page-size",
-        args.page_size,
-    ]
-    if args.query:
-        cmd.extend(["--query", args.query])
-    if args.page_token:
-        cmd.extend(["--page-token", args.page_token])
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
-    if not isinstance(data, dict):
-        raise CLIError("unexpected docs +search payload", code="invalid_search_payload")
-    return data
-
-
-def delete_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.doc:
-        raise CLIError("missing --doc for delete", code="validation")
-    token = parse_doc_token(args.doc)
-    if not token:
-        raise CLIError(
-            "delete only supports doc token or /docx/<token> URL",
-            code="validation",
-        )
-
-    # Try direct delete first. Some tenants require explicit type param.
-    attempts = [
-        [
-            "api",
-            "DELETE",
-            f"/open-apis/drive/v1/files/{token}",
-            "--as",
-            args.identity,
-            "--format",
-            "json",
-        ],
-        [
-            "api",
-            "DELETE",
-            f"/open-apis/drive/v1/files/{token}",
-            "--as",
-            args.identity,
-            "--params",
-            '{"type":"docx"}',
-            "--format",
-            "json",
-        ],
-    ]
-    last_exc: CLIError | None = None
-    for cmd in attempts:
-        try:
-            payload = run_cli(args.lark_cli_bin, env, cmd)
-            return {
-                "deleted_doc_token": token,
-                "raw": unwrap_payload(payload),
-            }
-        except CLIError as exc:
-            last_exc = exc
-    assert last_exc is not None
-    raise last_exc
-
-
-def media_insert(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.doc:
-        raise CLIError("missing --doc for media-insert", code="validation")
-    if not args.file:
-        raise CLIError("missing --file for media-insert", code="validation")
-
-    file_cwd, cli_file = localize_cli_path(args.file)
-    cmd = [
-        "docs",
-        "+media-insert",
-        "--as",
-        args.identity,
-        "--doc",
-        args.doc,
-        "--file",
-        cli_file,
-        "--type",
-        args.media_type,
-    ]
-    if args.align:
-        cmd.extend(["--align", args.align])
-    if args.caption:
-        cmd.extend(["--caption", args.caption])
-
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd, cwd=file_cwd))
-    if not isinstance(data, dict):
-        raise CLIError(
-            "unexpected docs +media-insert payload", code="invalid_media_insert_payload"
-        )
-    return data
-
-
-def media_download(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.token:
-        raise CLIError("missing --token for media-download", code="validation")
-    if not args.output:
-        raise CLIError("missing --output for media-download", code="validation")
-
-    output_cwd, cli_output = localize_cli_path(args.output)
-    cmd = [
-        "docs",
-        "+media-download",
-        "--as",
-        args.identity,
-        "--token",
-        args.token,
-        "--type",
-        args.resource_type,
-        "--output",
-        cli_output,
-    ]
-    if args.overwrite:
-        cmd.append("--overwrite")
-
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd, cwd=output_cwd))
-    if not isinstance(data, dict):
-        raise CLIError(
-            "unexpected docs +media-download payload",
-            code="invalid_media_download_payload",
-        )
-    saved_path = data.get("saved_path")
-    if isinstance(saved_path, str) and not os.path.isabs(saved_path):
-        data["saved_path"] = os.path.abspath(os.path.join(output_cwd, saved_path))
-    return data
-
-
-def build_comment_content(args: argparse.Namespace) -> str:
-    if args.comment_json:
-        try:
-            parsed = json.loads(args.comment_json)
-        except json.JSONDecodeError as exc:
-            raise CLIError(
-                "--comment-json must be valid JSON", code="validation"
-            ) from exc
-        if not isinstance(parsed, list):
-            raise CLIError(
-                "--comment-json must be a reply_elements JSON array",
-                code="validation",
-            )
-        return args.comment_json
-
-    if args.comment:
-        return json.dumps(
-            [{"type": "text", "text": args.comment}],
-            ensure_ascii=False,
-        )
-
-    raise CLIError(
-        "missing --comment or --comment-json for comment", code="validation"
-    )
-
-
-def add_comment(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.doc:
-        raise CLIError("missing --doc for comment", code="validation")
-
-    cmd = [
-        "drive",
-        "+add-comment",
-        "--as",
-        args.identity,
-        "--doc",
-        args.doc,
-        "--content",
-        build_comment_content(args),
-    ]
-    if args.full_comment:
-        cmd.append("--full-comment")
-    if args.selection_with_ellipsis:
-        cmd.extend(["--selection-with-ellipsis", args.selection_with_ellipsis])
-    if args.block_id:
-        cmd.extend(["--block-id", args.block_id])
-
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
-    if not isinstance(data, dict):
-        raise CLIError(
-            "unexpected drive +add-comment payload", code="invalid_comment_payload"
-        )
-    return data
-
-
-def normalize_section_markdown(section_title: str, markdown: str) -> str:
-    stripped = markdown.lstrip()
-    if stripped.startswith("#"):
-        return markdown
-    return f"{section_title}\n\n{markdown}"
-
-
-def update_section(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if not args.doc:
-        raise CLIError("missing --doc for section-update", code="validation")
-    if not args.section_title:
-        raise CLIError("missing --section-title for section-update", code="validation")
-
-    mode_map = {
-        "replace": "replace_range",
-        "delete": "delete_range",
-        "insert_before": "insert_before",
-        "insert_after": "insert_after",
-    }
-    cli_mode = mode_map[args.section_mode]
-    cmd = [
-        "docs",
-        "+update",
-        "--as",
-        args.identity,
-        "--doc",
-        args.doc,
-        "--mode",
-        cli_mode,
-        "--selection-by-title",
-        args.section_title,
-    ]
-    if args.new_title:
-        cmd.extend(["--new-title", args.new_title])
-    if args.section_mode != "delete":
-        if not args.markdown:
-            raise CLIError(
-                "missing --markdown for non-delete section-update",
-                code="validation",
-            )
-        markdown = args.markdown
-        if args.section_mode == "replace":
-            markdown = normalize_section_markdown(args.section_title, markdown)
-        cmd.extend(["--markdown", markdown])
-
-    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
-    if not isinstance(data, dict):
-        raise CLIError(
-            "unexpected section update payload", code="invalid_section_update_payload"
-        )
-    enriched = dict(data)
-    enriched["section_title"] = args.section_title
-    enriched["section_mode"] = args.section_mode
-    return enriched
-
-
-def run(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
-    if args.op == "create":
-        return create_note(args, env)
-    if args.op == "read":
-        return read_note(args, env)
-    if args.op == "update":
-        return update_note(args, env)
-    if args.op == "search":
-        return search_note(args, env)
-    if args.op == "delete":
-        return delete_note(args, env)
-    if args.op == "media-insert":
-        return media_insert(args, env)
-    if args.op == "media-download":
-        return media_download(args, env)
-    if args.op == "comment":
-        return add_comment(args, env)
-    if args.op == "section-update":
-        return update_section(args, env)
-    raise CLIError(f"unsupported op: {args.op}", code="validation")
-
-
-def main() -> int:
-    args = parse_args()
-    env = build_env(args.config_dir)
-    try:
-        data = run(args, env)
-        out = {
-            "ok": True,
-            "op": args.op,
-            "data": data,
-            "error": None,
-        }
-    except CLIError as exc:
-        out = {
-            "ok": False,
-            "op": args.op,
-            "data": None,
-            "error": {
-                "code": exc.code,
-                "message": str(exc),
-                "detail": exc.detail,
-            },
-        }
-    json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
-    sys.stdout.write("\n")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+#!/usr/bin/env python3
+"""OpenClaw note CRUD orchestrator for Feishu docs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from typing import Any
+
+
+class CLIError(Exception):
+    def __init__(self, message: str, code: str = "cli_error", detail: Any = None):
+        super().__init__(message)
+        self.code = code
+        self.detail = detail
+
+
+DOCX_URL_RE = re.compile(r"/docx/([A-Za-z0-9_-]+)")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Feishu note CRUD via bundled lark-cli")
+    parser.add_argument(
+        "--op",
+        required=True,
+        choices=[
+            "create",
+            "read",
+            "update",
+            "delete",
+            "search",
+            "media-insert",
+            "media-download",
+            "comment",
+            "section-update",
+        ],
+        help="note operation",
+    )
+    parser.add_argument("--doc", help="doc token or doc/docx URL")
+    parser.add_argument("--title", help="note title")
+    parser.add_argument("--markdown", help="note markdown content")
+    parser.add_argument("--query", help="search keyword")
+    parser.add_argument("--mode", default="append", help="update mode")
+    parser.add_argument("--new-title", help="rename title while update")
+    parser.add_argument("--selection-by-title", help="title-based locator for update")
+    parser.add_argument(
+        "--selection-with-ellipsis", help="content locator for range update/delete"
+    )
+    parser.add_argument("--folder-token", help="target folder token when creating")
+    parser.add_argument("--wiki-node", help="target wiki node token when creating")
+    parser.add_argument("--wiki-space", help="target wiki space when creating")
+    parser.add_argument("--page-size", default="15", help="search page size")
+    parser.add_argument("--page-token", help="search page token")
+    parser.add_argument("--file", help="local file path for media insert")
+    parser.add_argument(
+        "--media-type",
+        default="image",
+        choices=["image", "file"],
+        help="media type for insert: image | file",
+    )
+    parser.add_argument(
+        "--token", help="media token or whiteboard token for media download"
+    )
+    parser.add_argument(
+        "--resource-type",
+        default="media",
+        choices=["media", "whiteboard"],
+        help="resource type for media download: media | whiteboard",
+    )
+    parser.add_argument("--output", help="local output path for media download")
+    parser.add_argument(
+        "--overwrite", action="store_true", help="overwrite existing download file"
+    )
+    parser.add_argument("--caption", help="image caption for media insert")
+    parser.add_argument(
+        "--align", choices=["left", "center", "right"], help="image alignment"
+    )
+    parser.add_argument("--comment", help="plain text comment body")
+    parser.add_argument(
+        "--comment-json",
+        help="raw reply_elements JSON array for advanced comment payloads",
+    )
+    parser.add_argument(
+        "--block-id", help="comment anchor block ID for local comment mode"
+    )
+    parser.add_argument(
+        "--full-comment",
+        action="store_true",
+        help="create full-document comment instead of local comment",
+    )
+    parser.add_argument("--section-title", help="title locator like '## Section'")
+    parser.add_argument(
+        "--section-mode",
+        choices=["replace", "delete", "insert_before", "insert_after"],
+        default="replace",
+        help="section update mode",
+    )
+    parser.add_argument("--as", dest="identity", default="user", help="user | bot")
+    parser.add_argument("--config-dir", help="optional LARKSUITE_CLI_CONFIG_DIR")
+    parser.add_argument("--lark-cli-bin", default="lark-cli", help="lark-cli binary")
+    return parser.parse_args()
+
+
+def build_env(config_dir: str | None) -> dict[str, str]:
+    env = os.environ.copy()
+    if config_dir:
+        env["LARKSUITE_CLI_CONFIG_DIR"] = config_dir
+    return env
+
+
+def run_cli(
+    cli_bin: str, env: dict[str, str], args: list[str], cwd: str | None = None
+) -> Any:
+    proc = subprocess.run(
+        [cli_bin] + args,
+        capture_output=True,
+        text=True,
+        env=env,
+        cwd=cwd,
+    )
+    stdout = proc.stdout.strip()
+    stderr = proc.stderr.strip()
+
+    parsed: Any = None
+    if stdout:
+        try:
+            parsed = json.loads(stdout)
+        except json.JSONDecodeError as exc:
+            raise CLIError(
+                f"lark-cli returned non-JSON stdout: {stdout[:400]}",
+                code="invalid_cli_output",
+                detail={"stderr": stderr, "args": args},
+            ) from exc
+
+    if proc.returncode != 0:
+        detail = parsed if isinstance(parsed, dict) else {"stderr": stderr}
+        raise CLIError(
+            f"lark-cli command failed: {' '.join(args)}",
+            code="lark_cli_failed",
+            detail=detail,
+        )
+    return parsed
+
+
+def localize_cli_path(path: str) -> tuple[str, str]:
+    abs_path = os.path.abspath(path)
+    parent = os.path.dirname(abs_path) or os.getcwd()
+    return parent, f"./{os.path.basename(abs_path)}"
+
+
+def unwrap_payload(payload: Any) -> Any:
+    if isinstance(payload, dict) and "ok" in payload:
+        if not payload.get("ok", False):
+            error = payload.get("error") or {}
+            raise CLIError(
+                error.get("message", "lark-cli returned an error envelope"),
+                code=error.get("type", "lark_error"),
+                detail=payload,
+            )
+        return payload.get("data")
+    return payload
+
+
+def parse_doc_token(doc: str) -> str:
+    if not doc:
+        return ""
+    if doc.startswith("http://") or doc.startswith("https://"):
+        match = DOCX_URL_RE.search(doc)
+        if match:
+            return match.group(1)
+        return ""
+    return doc
+
+
+def create_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.title:
+        raise CLIError("missing --title for create", code="validation")
+    if not args.markdown:
+        raise CLIError("missing --markdown for create", code="validation")
+    cmd = [
+        "docs",
+        "+create",
+        "--as",
+        args.identity,
+        "--title",
+        args.title,
+        "--markdown",
+        args.markdown,
+    ]
+    if args.folder_token:
+        cmd.extend(["--folder-token", args.folder_token])
+    if args.wiki_node:
+        cmd.extend(["--wiki-node", args.wiki_node])
+    if args.wiki_space:
+        cmd.extend(["--wiki-space", args.wiki_space])
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
+    if not isinstance(data, dict):
+        raise CLIError("unexpected docs +create payload", code="invalid_create_payload")
+    return data
+
+
+def read_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.doc:
+        raise CLIError("missing --doc for read", code="validation")
+    cmd = [
+        "docs",
+        "+fetch",
+        "--as",
+        args.identity,
+        "--doc",
+        args.doc,
+        "--format",
+        "json",
+    ]
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
+    if not isinstance(data, dict):
+        raise CLIError("unexpected docs +fetch payload", code="invalid_read_payload")
+    return data
+
+
+def update_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.doc:
+        raise CLIError("missing --doc for update", code="validation")
+    cmd = [
+        "docs",
+        "+update",
+        "--as",
+        args.identity,
+        "--doc",
+        args.doc,
+        "--mode",
+        args.mode,
+    ]
+    if args.markdown:
+        cmd.extend(["--markdown", args.markdown])
+    if args.new_title:
+        cmd.extend(["--new-title", args.new_title])
+    if args.selection_by_title:
+        cmd.extend(["--selection-by-title", args.selection_by_title])
+    if args.selection_with_ellipsis:
+        cmd.extend(["--selection-with-ellipsis", args.selection_with_ellipsis])
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
+    if not isinstance(data, dict):
+        raise CLIError("unexpected docs +update payload", code="invalid_update_payload")
+    return data
+
+
+def search_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    cmd = [
+        "docs",
+        "+search",
+        "--as",
+        args.identity,
+        "--format",
+        "json",
+        "--page-size",
+        args.page_size,
+    ]
+    if args.query:
+        cmd.extend(["--query", args.query])
+    if args.page_token:
+        cmd.extend(["--page-token", args.page_token])
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
+    if not isinstance(data, dict):
+        raise CLIError("unexpected docs +search payload", code="invalid_search_payload")
+    return data
+
+
+def delete_note(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.doc:
+        raise CLIError("missing --doc for delete", code="validation")
+    token = parse_doc_token(args.doc)
+    if not token:
+        raise CLIError(
+            "delete only supports doc token or /docx/<token> URL",
+            code="validation",
+        )
+
+    # Try direct delete first. Some tenants require explicit type param.
+    attempts = [
+        [
+            "api",
+            "DELETE",
+            f"/open-apis/drive/v1/files/{token}",
+            "--as",
+            args.identity,
+            "--format",
+            "json",
+        ],
+        [
+            "api",
+            "DELETE",
+            f"/open-apis/drive/v1/files/{token}",
+            "--as",
+            args.identity,
+            "--params",
+            '{"type":"docx"}',
+            "--format",
+            "json",
+        ],
+    ]
+    last_exc: CLIError | None = None
+    for cmd in attempts:
+        try:
+            payload = run_cli(args.lark_cli_bin, env, cmd)
+            return {
+                "deleted_doc_token": token,
+                "raw": unwrap_payload(payload),
+            }
+        except CLIError as exc:
+            last_exc = exc
+    assert last_exc is not None
+    raise last_exc
+
+
+def media_insert(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.doc:
+        raise CLIError("missing --doc for media-insert", code="validation")
+    if not args.file:
+        raise CLIError("missing --file for media-insert", code="validation")
+
+    file_cwd, cli_file = localize_cli_path(args.file)
+    cmd = [
+        "docs",
+        "+media-insert",
+        "--as",
+        args.identity,
+        "--doc",
+        args.doc,
+        "--file",
+        cli_file,
+        "--type",
+        args.media_type,
+    ]
+    if args.align:
+        cmd.extend(["--align", args.align])
+    if args.caption:
+        cmd.extend(["--caption", args.caption])
+
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd, cwd=file_cwd))
+    if not isinstance(data, dict):
+        raise CLIError(
+            "unexpected docs +media-insert payload", code="invalid_media_insert_payload"
+        )
+    return data
+
+
+def media_download(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.token:
+        raise CLIError("missing --token for media-download", code="validation")
+    if not args.output:
+        raise CLIError("missing --output for media-download", code="validation")
+
+    output_cwd, cli_output = localize_cli_path(args.output)
+    cmd = [
+        "docs",
+        "+media-download",
+        "--as",
+        args.identity,
+        "--token",
+        args.token,
+        "--type",
+        args.resource_type,
+        "--output",
+        cli_output,
+    ]
+    if args.overwrite:
+        cmd.append("--overwrite")
+
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd, cwd=output_cwd))
+    if not isinstance(data, dict):
+        raise CLIError(
+            "unexpected docs +media-download payload",
+            code="invalid_media_download_payload",
+        )
+    saved_path = data.get("saved_path")
+    if isinstance(saved_path, str) and not os.path.isabs(saved_path):
+        data["saved_path"] = os.path.abspath(os.path.join(output_cwd, saved_path))
+    return data
+
+
+def build_comment_content(args: argparse.Namespace) -> str:
+    if args.comment_json:
+        try:
+            parsed = json.loads(args.comment_json)
+        except json.JSONDecodeError as exc:
+            raise CLIError(
+                "--comment-json must be valid JSON", code="validation"
+            ) from exc
+        if not isinstance(parsed, list):
+            raise CLIError(
+                "--comment-json must be a reply_elements JSON array",
+                code="validation",
+            )
+        return args.comment_json
+
+    if args.comment:
+        return json.dumps(
+            [{"type": "text", "text": args.comment}],
+            ensure_ascii=False,
+        )
+
+    raise CLIError(
+        "missing --comment or --comment-json for comment", code="validation"
+    )
+
+
+def add_comment(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.doc:
+        raise CLIError("missing --doc for comment", code="validation")
+
+    cmd = [
+        "drive",
+        "+add-comment",
+        "--as",
+        args.identity,
+        "--doc",
+        args.doc,
+        "--content",
+        build_comment_content(args),
+    ]
+    if args.full_comment:
+        cmd.append("--full-comment")
+    if args.selection_with_ellipsis:
+        cmd.extend(["--selection-with-ellipsis", args.selection_with_ellipsis])
+    if args.block_id:
+        cmd.extend(["--block-id", args.block_id])
+
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
+    if not isinstance(data, dict):
+        raise CLIError(
+            "unexpected drive +add-comment payload", code="invalid_comment_payload"
+        )
+    return data
+
+
+def normalize_section_markdown(section_title: str, markdown: str) -> str:
+    stripped = markdown.lstrip()
+    if stripped.startswith("#"):
+        return markdown
+    return f"{section_title}\n\n{markdown}"
+
+
+def update_section(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if not args.doc:
+        raise CLIError("missing --doc for section-update", code="validation")
+    if not args.section_title:
+        raise CLIError("missing --section-title for section-update", code="validation")
+
+    mode_map = {
+        "replace": "replace_range",
+        "delete": "delete_range",
+        "insert_before": "insert_before",
+        "insert_after": "insert_after",
+    }
+    cli_mode = mode_map[args.section_mode]
+    cmd = [
+        "docs",
+        "+update",
+        "--as",
+        args.identity,
+        "--doc",
+        args.doc,
+        "--mode",
+        cli_mode,
+        "--selection-by-title",
+        args.section_title,
+    ]
+    if args.new_title:
+        cmd.extend(["--new-title", args.new_title])
+    if args.section_mode != "delete":
+        if not args.markdown:
+            raise CLIError(
+                "missing --markdown for non-delete section-update",
+                code="validation",
+            )
+        markdown = args.markdown
+        if args.section_mode == "replace":
+            markdown = normalize_section_markdown(args.section_title, markdown)
+        cmd.extend(["--markdown", markdown])
+
+    data = unwrap_payload(run_cli(args.lark_cli_bin, env, cmd))
+    if not isinstance(data, dict):
+        raise CLIError(
+            "unexpected section update payload", code="invalid_section_update_payload"
+        )
+    enriched = dict(data)
+    enriched["section_title"] = args.section_title
+    enriched["section_mode"] = args.section_mode
+    return enriched
+
+
+def run(args: argparse.Namespace, env: dict[str, str]) -> dict[str, Any]:
+    if args.op == "create":
+        return create_note(args, env)
+    if args.op == "read":
+        return read_note(args, env)
+    if args.op == "update":
+        return update_note(args, env)
+    if args.op == "search":
+        return search_note(args, env)
+    if args.op == "delete":
+        return delete_note(args, env)
+    if args.op == "media-insert":
+        return media_insert(args, env)
+    if args.op == "media-download":
+        return media_download(args, env)
+    if args.op == "comment":
+        return add_comment(args, env)
+    if args.op == "section-update":
+        return update_section(args, env)
+    raise CLIError(f"unsupported op: {args.op}", code="validation")
+
+
+def main() -> int:
+    args = parse_args()
+    env = build_env(args.config_dir)
+    try:
+        data = run(args, env)
+        out = {
+            "ok": True,
+            "op": args.op,
+            "data": data,
+            "error": None,
+        }
+    except CLIError as exc:
+        out = {
+            "ok": False,
+            "op": args.op,
+            "data": None,
+            "error": {
+                "code": exc.code,
+                "message": str(exc),
+                "detail": exc.detail,
+            },
+        }
+    json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())