@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/mcp/SKILL.md

@@ -0,0 +1,72 @@
+---
+id: mcp
+name: mcp
+description: "根据用户提供的 MCP 文档（README/配置片段/链接），自动解析、下载安装并注册 MCP Server"
+when_to_use: "用户要求安装/接入/注册 MCP，或给出 MCP 文档、mcpServers JSON、MCP 启动命令时使用"
+version: "1.0.0"
+tags:
+  - mcp
+  - integration
+  - install
+  - automation
+user_invocable: true
+disable_model_invocation: false
+argument_hint: "<mcp_doc_path_or_url_or_text> [server_name]"
+metadata:
+  display-name: "MCP Skill"
+---
+
+# MCP Skill
+
+把用户提供的 MCP 文档自动落地为可用 MCP Server：**解析文档 -> 安装依赖 -> 注册到本地 MCPRegistry -> 验证可见**。
+
+## 输入
+
+- `$ARGS`: MCP 文档来源，可以是：
+  - 本地文件路径（README/Markdown/JSON）
+  - URL
+  - 一段文本（含 `mcpServers` JSON 或启动命令）
+
+## 执行规则
+
+1. 如果用户已经给了文档路径/URL/文本，直接执行，不要反复追问。
+2. 优先使用本 Skill 自带脚本：
+
+```bash
+python3 "${SKILL_DIR}/scripts/mcp_setup.py" --input "$ARGS"
+```
+
+3. 若文档中有多个 server，优先匹配用户提到的名称；否则使用脚本自动选中的第一个。
+4. 如果安装失败：
+   - 先输出失败命令与 stderr 摘要
+   - 尝试脚本给出的回退路径（例如 npx/uvx 直启）
+   - 仍失败再向用户报告缺失前置依赖（Node/Python/uv 等）
+5. 注册成功后，必须给出：
+   - server id
+   - transport（stdio/streamable_http；旧 http_sse 配置仍兼容）
+   - protocol（legacy 或 auto_2026_07_28；仅在服务端明确支持/需要最新版无状态协议时启用后者）
+   - 安装执行结果
+   - 注册验证结果（list-mcp-servers 中可见）
+
+## 多 server 文档处理
+
+当文档里有多个 `mcpServers` 条目时，使用：
+
+```bash
+python3 "${SKILL_DIR}/scripts/mcp_setup.py" --input "$ARGS" --server "<server_key>"
+```
+
+## 仅预览（不执行安装/注册）
+
+```bash
+python3 "${SKILL_DIR}/scripts/mcp_setup.py" --input "$ARGS" --dry-run
+```
+
+## 结果验收标准
+
+完成时满足以下全部条件：
+
+1. 已解析出结构化 `config`（含 id/name/transport）。
+2. 已执行安装步骤，或明确说明为何可跳过安装。
+3. `add-mcp-server` RPC 返回成功（或幂等更新成功）。
+4. `list-mcp-servers` 中能看到目标 server。

package/skills/mcp/scripts/mcp_setup.py

@@ -0,0 +1,439 @@
+#!/usr/bin/env python3
+"""Parse MCP docs, auto-install dependencies, and register MCP servers via local RPC."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shlex
+import socket
+import subprocess
+import sys
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import Any
+
+
+def sanitize_id(raw: str) -> str:
+    cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "-", raw.strip().lower()).strip("-_")
+    if not cleaned:
+        cleaned = "mcp-server"
+    if cleaned[0].isdigit():
+        cleaned = f"mcp-{cleaned}"
+    return cleaned
+
+
+def socket_path() -> Path:
+    override = os.environ.get("CTENO_RPC_SOCKET")
+    if override:
+        return Path(override)
+
+    home = Path.home()
+    env_tag = os.environ.get("CTENO_ENV", "").strip()
+    if env_tag and env_tag != "release":
+        return home / ".agents" / f"daemon.{env_tag}.sock"
+
+    dev_sock = home / ".agents" / "daemon.dev.sock"
+    if dev_sock.exists():
+        return dev_sock
+    return home / ".agents" / "daemon.sock"
+
+
+def rpc_call(method: str, params: dict[str, Any]) -> Any:
+    sock = socket_path()
+    if not sock.exists():
+        raise RuntimeError(f"RPC socket not found: {sock}")
+
+    req_id = str(uuid.uuid4())
+    payload = {
+        "id": req_id,
+        "method": method,
+        "params": params,
+    }
+
+    with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+        client.settimeout(20)
+        client.connect(str(sock))
+        client.sendall((json.dumps(payload, ensure_ascii=False) + "\n").encode("utf-8"))
+
+        chunks: list[bytes] = []
+        while True:
+            b = client.recv(4096)
+            if not b:
+                break
+            chunks.append(b)
+            if b"\n" in b:
+                break
+
+    if not chunks:
+        raise RuntimeError(f"No RPC response for method {method}")
+
+    line = b"".join(chunks).split(b"\n", 1)[0].decode("utf-8", errors="replace")
+    response = json.loads(line)
+
+    if response.get("id") != req_id:
+        raise RuntimeError(f"RPC id mismatch for method {method}")
+    if "error" in response and response["error"]:
+        raise RuntimeError(f"RPC error ({method}): {response['error']}")
+
+    return response.get("result")
+
+
+def strip_json_comments(text: str) -> str:
+    text = re.sub(r"/\*.*?\*/", "", text, flags=re.DOTALL)
+    text = re.sub(r"(^|\s)//.*$", "", text, flags=re.MULTILINE)
+    text = re.sub(r",\s*([}\]])", r"\1", text)
+    return text
+
+
+def iter_fenced_blocks(text: str) -> list[tuple[str, str]]:
+    out: list[tuple[str, str]] = []
+    for m in re.finditer(r"```([a-zA-Z0-9_-]*)\n(.*?)```", text, flags=re.DOTALL):
+        lang = (m.group(1) or "").strip().lower()
+        body = m.group(2)
+        out.append((lang, body))
+    return out
+
+
+def try_parse_json(text: str) -> Any | None:
+    text = text.strip()
+    if not text:
+        return None
+
+    for candidate in (text, strip_json_comments(text)):
+        try:
+            return json.loads(candidate)
+        except Exception:
+            pass
+
+    return None
+
+
+def is_url(value: str) -> bool:
+    return value.startswith("http://") or value.startswith("https://")
+
+
+def read_input_source(source: str) -> tuple[str, str]:
+    p = Path(source)
+    if p.exists() and p.is_file():
+        return p.read_text(encoding="utf-8", errors="replace"), "file"
+
+    if is_url(source):
+        with urllib.request.urlopen(source, timeout=20) as resp:
+            data = resp.read().decode("utf-8", errors="replace")
+            return data, "url"
+
+    return source, "text"
+
+
+def first_non_flag(args: list[str]) -> str | None:
+    skip_next = False
+    for token in args:
+        if skip_next:
+            skip_next = False
+            continue
+        if token in {"-p", "--port", "-c", "--config", "--env-file"}:
+            skip_next = True
+            continue
+        if token.startswith("-"):
+            continue
+        return token
+    return None
+
+
+def derive_install_commands(command: str, args: list[str]) -> list[list[str]]:
+    cmd = Path(command).name.lower()
+    pkg = first_non_flag(args)
+    if not pkg:
+        return []
+
+    if cmd == "npx":
+        return [["npm", "install", "-g", pkg]]
+    if cmd == "bunx":
+        return [["bun", "add", "-g", pkg]]
+    if cmd == "uvx":
+        return [["uv", "tool", "install", pkg]]
+    if cmd in {"python", "python3"} and len(args) >= 2 and args[0] == "-m":
+        return [["python3", "-m", "pip", "install", "-U", args[1]]]
+    return []
+
+
+def build_config_from_entry(server_key: str, entry: dict[str, Any]) -> dict[str, Any]:
+    server_id = sanitize_id(server_key)
+    name = str(entry.get("name") or server_key)
+    enabled = bool(entry.get("enabled", True))
+    protocol = str(entry.get("protocol") or "legacy")
+    transport = entry.get("transport") if isinstance(entry.get("transport"), dict) else entry
+    transport_type = transport.get("type")
+
+    if isinstance(transport.get("url"), str) and transport["url"].strip():
+        if transport_type not in {None, "streamable_http", "http_sse"}:
+            raise RuntimeError(f"Unsupported HTTP transport type: {transport_type}")
+        return {
+            "id": server_id,
+            "name": name,
+            "enabled": enabled,
+            "protocol": protocol,
+            "transport": {
+                "type": "streamable_http",
+                "url": transport["url"].strip(),
+                "headers": transport.get("headers", {}) if isinstance(transport.get("headers"), dict) else {},
+            },
+        }
+
+    if isinstance(transport.get("command"), str) and transport["command"].strip():
+        if transport_type not in {None, "stdio"}:
+            raise RuntimeError(f"Unsupported stdio transport type: {transport_type}")
+        args = transport.get("args", []) if isinstance(transport.get("args"), list) else []
+        env = transport.get("env", {}) if isinstance(transport.get("env"), dict) else {}
+        return {
+            "id": server_id,
+            "name": name,
+            "enabled": enabled,
+            "protocol": protocol,
+            "transport": {
+                "type": "stdio",
+                "command": transport["command"].strip(),
+                "args": [str(x) for x in args],
+                "env": {str(k): str(v) for k, v in env.items()},
+            },
+        }
+
+    raise RuntimeError(f"Server entry '{server_key}' has neither 'command' nor 'url'")
+
+
+def parse_from_json_obj(obj: Any, server_hint: str | None) -> tuple[dict[str, Any], str] | None:
+    if not isinstance(obj, dict):
+        return None
+
+    mcp_servers = obj.get("mcpServers")
+    if isinstance(mcp_servers, dict) and mcp_servers:
+        if server_hint and server_hint in mcp_servers:
+            key = server_hint
+        else:
+            key = next(iter(mcp_servers.keys()))
+
+        entry = mcp_servers.get(key)
+        if isinstance(entry, dict):
+            return build_config_from_entry(str(key), entry), f"json:mcpServers:{key}"
+
+    if isinstance(obj.get("command"), str) or isinstance(obj.get("url"), str):
+        key = server_hint or str(obj.get("name") or "mcp-server")
+        return build_config_from_entry(key, obj), "json:single"
+
+    transport = obj.get("transport")
+    if isinstance(transport, dict) and isinstance(obj.get("id"), str) and isinstance(obj.get("name"), str):
+        return build_config_from_entry(str(obj["id"]), obj), "json:transport"
+
+    return None
+
+
+def parse_from_command_lines(text: str) -> tuple[dict[str, Any], str] | None:
+    candidates: list[str] = []
+    for lang, body in iter_fenced_blocks(text):
+        if lang in {"bash", "sh", "zsh", "shell", ""}:
+            candidates.extend(body.splitlines())
+
+    if not candidates:
+        candidates = text.splitlines()
+
+    preferred = []
+    fallback = []
+    for raw in candidates:
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if re.match(r"^(npx|bunx|uvx|python3?|node)\b", line):
+            if "mcp" in line.lower():
+                preferred.append(line)
+            else:
+                fallback.append(line)
+
+    line = preferred[0] if preferred else (fallback[0] if fallback else None)
+    if not line:
+        inline = re.search(
+            r"(npx|bunx|uvx|python3?|node)\s+[^\n`]+",
+            text,
+            flags=re.IGNORECASE,
+        )
+        if inline:
+            line = inline.group(0).strip()
+    if not line:
+        return None
+
+    parts = shlex.split(line)
+    if not parts:
+        return None
+
+    command = parts[0]
+    args = parts[1:]
+    key = first_non_flag(args) or Path(command).name
+    key = sanitize_id(key.replace("@", "").replace("/", "-"))
+
+    config = {
+        "id": key,
+        "name": key,
+        "enabled": True,
+        "transport": {
+            "type": "stdio",
+            "command": command,
+            "args": args,
+            "env": {},
+        },
+    }
+    return config, f"command:{line}"
+
+
+def parse_mcp_doc(text: str, server_hint: str | None) -> tuple[dict[str, Any], str]:
+    parsed_full = try_parse_json(text)
+    if parsed_full is not None:
+        out = parse_from_json_obj(parsed_full, server_hint)
+        if out:
+            return out
+
+    for lang, body in iter_fenced_blocks(text):
+        if lang in {"json", "jsonc", "javascript", "js", "ts", ""}:
+            obj = try_parse_json(body)
+            if obj is None:
+                continue
+            out = parse_from_json_obj(obj, server_hint)
+            if out:
+                return out
+
+    cmd_out = parse_from_command_lines(text)
+    if cmd_out:
+        return cmd_out
+
+    raise RuntimeError(
+        "Could not extract MCP config from input. Provide mcpServers JSON or a runnable command."
+    )
+
+
+def maybe_install(config: dict[str, Any], dry_run: bool, continue_on_error: bool) -> list[dict[str, Any]]:
+    transport = config.get("transport", {})
+    if not isinstance(transport, dict):
+        return []
+    if transport.get("type") != "stdio":
+        return []
+
+    command = str(transport.get("command") or "")
+    args = transport.get("args", []) if isinstance(transport.get("args"), list) else []
+    install_cmds = derive_install_commands(command, [str(x) for x in args])
+
+    results: list[dict[str, Any]] = []
+    for cmd in install_cmds:
+        item: dict[str, Any] = {"command": " ".join(shlex.quote(x) for x in cmd)}
+        if dry_run:
+            item["status"] = "skipped(dry-run)"
+            results.append(item)
+            continue
+
+        proc = subprocess.run(cmd, text=True, capture_output=True)
+        item["status"] = "ok" if proc.returncode == 0 else "failed"
+        item["exit_code"] = proc.returncode
+        item["stdout_tail"] = "\n".join(proc.stdout.splitlines()[-10:])
+        item["stderr_tail"] = "\n".join(proc.stderr.splitlines()[-10:])
+        results.append(item)
+
+        if proc.returncode != 0 and not continue_on_error:
+            raise RuntimeError(
+                f"Install command failed: {item['command']}\n{item.get('stderr_tail', '')}".strip()
+            )
+
+    return results
+
+
+def register_server(config: dict[str, Any], dry_run: bool) -> dict[str, Any]:
+    server_id = config["id"]
+
+    if dry_run:
+        return {
+            "status": "skipped(dry-run)",
+            "server_id": server_id,
+        }
+
+    listed = rpc_call("list-mcp-servers", {})
+    servers = listed.get("servers", []) if isinstance(listed, dict) else []
+    exists = any(isinstance(s, dict) and s.get("id") == server_id for s in servers)
+
+    if exists:
+        remove_res = rpc_call("remove-mcp-server", {"serverId": server_id})
+        if isinstance(remove_res, dict) and remove_res.get("success") is False:
+            raise RuntimeError(remove_res.get("error") or f"Failed to remove existing server '{server_id}'")
+
+    add_res = rpc_call("add-mcp-server", config)
+    if isinstance(add_res, dict) and add_res.get("success") is False:
+        raise RuntimeError(add_res.get("error") or f"Failed to add server '{server_id}'")
+
+    listed_after = rpc_call("list-mcp-servers", {})
+    servers_after = listed_after.get("servers", []) if isinstance(listed_after, dict) else []
+    visible = any(isinstance(s, dict) and s.get("id") == server_id for s in servers_after)
+
+    return {
+        "status": "ok" if visible else "warning:not-visible",
+        "server_id": server_id,
+        "already_existed": exists,
+        "add_result": add_res,
+        "visible_in_list": visible,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Auto setup MCP server from docs.")
+    parser.add_argument("--input", required=True, help="Path/URL/raw text containing MCP docs")
+    parser.add_argument("--server", help="Server key when mcpServers has multiple entries")
+    parser.add_argument("--id", dest="override_id", help="Override server id")
+    parser.add_argument("--name", dest="override_name", help="Override server display name")
+    parser.add_argument("--skip-install", action="store_true", help="Skip dependency installation")
+    parser.add_argument("--skip-register", action="store_true", help="Skip RPC registration")
+    parser.add_argument("--continue-on-install-error", action="store_true", help="Continue even when install fails")
+    parser.add_argument("--dry-run", action="store_true", help="Parse only; do not install/register")
+    args = parser.parse_args()
+
+    result: dict[str, Any] = {
+        "ok": False,
+        "input": args.input,
+    }
+
+    try:
+        text, input_kind = read_input_source(args.input)
+        config, parsed_from = parse_mcp_doc(text, args.server)
+
+        if args.override_id:
+            config["id"] = sanitize_id(args.override_id)
+        if args.override_name:
+            config["name"] = args.override_name
+
+        result["input_kind"] = input_kind
+        result["parsed_from"] = parsed_from
+        result["config"] = config
+
+        if args.skip_install:
+            result["install"] = {"status": "skipped"}
+        else:
+            installs = maybe_install(config, dry_run=args.dry_run, continue_on_error=args.continue_on_install_error)
+            result["install"] = {
+                "status": "ok",
+                "steps": installs,
+            }
+
+        if args.skip_register:
+            result["register"] = {"status": "skipped"}
+        else:
+            result["register"] = register_server(config, dry_run=args.dry_run)
+
+        result["ok"] = True
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+
+    except Exception as exc:
+        result["error"] = str(exc)
+        print(json.dumps(result, ensure_ascii=False, indent=2), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/pdf/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Cteno
+Portions Copyright (c) 2026 Nous Research (scripts/ and tests/ adapted from the Hermes Agent productivity skills)
+Portions Copyright (c) 2026 MiniMaxAI (references adapted from MiniMax-AI/skills)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/pdf/NOTICE.md

@@ -0,0 +1,8 @@
+# Sources for the office skills (docx, pptx, xlsx, pdf)
+
+- **Scripts and tests**: adapted from Nous Research Hermes Agent `skills/productivity/{docx,powerpoint,xlsx,pdf}` (MIT), upstream commit `bf0203a` (2026-10-22).
+- **Chinese typesetting, design and formatting references**: adapted from MiniMax-AI/skills `minimax-docx`, `pptx-generator`, `minimax-xlsx`, `minimax-pdf` (MIT); `xlsx/scripts/formula_check.py` from minimax-xlsx.
+- **Cteno additions**: `scripts/render.py` (isolated LibreOffice profile, macOS CJK font exposure and substitution), `scripts/cjk_fonts.py` (East Asian font slots), CJK handling in `docx_create.py` / `pptx_create.py` / `pdf_create.py`, 16:9 layout stretch in `pptx_create.py`, all `SKILL.md` texts.
+- Anthropic's document skills (proprietary licence) informed which pitfalls to cover; no text or code was copied from them.
+
+Not tracked live: to update, diff the upstream folders above against these copies and re-run each skill's `tests/` plus a render check.

package/skills/pdf/SKILL.md

@@ -0,0 +1,63 @@
+---
+id: pdf
+name: pdf
+version: "2.0.0"
+description: "Create, read and manipulate PDFs: designed reports from HTML or a JSON spec (Chinese supported), text/table extraction, OCR of scans, merge/split/rotate, watermark/stamp, fillable forms (build, fill, flatten), metadata/attachments, encryption, and office-to-PDF conversion."
+when_to_use: "Use whenever a .pdf is input or output: make a PDF report/resume/proposal/invoice, export Word/PPT/Excel to PDF, extract text or tables, OCR a scanned PDF, merge/split/rotate pages, add a watermark or signature image, fill or create a PDF form, encrypt/decrypt. For an editable Word deliverable use docx first, then convert."
+license: MIT (see LICENSE; scripts adapted from Nous Research and MiniMax, MIT)
+tags: [pdf, report, forms, ocr, merge, watermark]
+---
+
+# PDF
+
+## Choose the creation route by what the PDF must look like
+
+| Need | Route |
+|---|---|
+| Already have a .docx/.pptx/.xlsx | `python3 ${SKILL_DIR}/scripts/render.py FILE --pdf-only` (LibreOffice; same as the office skills' preview) |
+| Designed report, resume, brochure, invoice with real layout | Write **HTML + CSS** (print styles, `@page` size and margins, page breaks) and print it with the `browser` tool / headless Chrome (`page.pdf()`), or `weasyprint` if installed. Best typography, CJK just works with system fonts. See `${SKILL_DIR}/references/design-tokens.md` for palette/type choices |
+| Simple structured document (headings, paragraphs, tables, images) | JSON spec → `${SKILL_DIR}/scripts/pdf_create.py spec.json -o out.pdf` (reportlab; Chinese is detected and a CJK font is embedded automatically, lines break between characters) |
+| Fillable form | `${SKILL_DIR}/scripts/pdf_form_layout.py spec.json` (lint) → `${SKILL_DIR}/scripts/pdf_make_form.py spec.json -o form.pdf` — read `${SKILL_DIR}/references/forms.md` |
+
+## Read and manipulate
+
+| Task | Command |
+|---|---|
+| Inspect first (pages, encrypted, scanned?) | `${SKILL_DIR}/scripts/pdf_read.py f.pdf --meta` |
+| Text per page / tables → JSON+CSV | `${SKILL_DIR}/scripts/pdf_read.py f.pdf --text` / `--tables --csv-dir t/` |
+| Scanned pages / OCR | read `${SKILL_DIR}/references/ocr-extraction.md` (`${SKILL_DIR}/scripts/extract_pymupdf.py`, `${SKILL_DIR}/scripts/extract_marker.py`) — never report a scan as "no content" |
+| Merge (with bookmarks) | `${SKILL_DIR}/scripts/pdf_merge.py a.pdf b.pdf -o m.pdf [--bookmarks]` |
+| Split / extract / rotate / compress | `${SKILL_DIR}/scripts/pdf_split.py f.pdf --pages 1-3,7 -o part.pdf [--rotate 90] [--compress]` |
+| Watermark with a PDF page | `${SKILL_DIR}/scripts/pdf_watermark.py f.pdf --stamp mark.pdf -o out.pdf [--under]` |
+| Stamp text or image (DRAFT, signature, seal) | `${SKILL_DIR}/scripts/pdf_stamp.py f.pdf -o out.pdf --text "草稿" --x 150 --y 400 --rotation 45 --opacity 0.3` / `--image sig.png --x 400 --y 60 --width 120` |
+| List / fill / flatten form fields | `${SKILL_DIR}/scripts/pdf_read.py f.pdf --fields`, `${SKILL_DIR}/scripts/pdf_fill_form.py f.pdf --fields-json v.json -o out.pdf [--flatten]` |
+| Metadata, attachments | `${SKILL_DIR}/scripts/pdf_meta.py` |
+| Encrypt / decrypt (AES-256) | `${SKILL_DIR}/scripts/pdf_secure.py` |
+| Page images | `${SKILL_DIR}/scripts/pdf_page_image.py f.pdf --pages 1-3 --dpi 150 --out-dir imgs/` or `${SKILL_DIR}/scripts/render.py f.pdf` |
+| Edit text inside an existing PDF | read `${SKILL_DIR}/references/nano-pdf-editing.md`; often better: regenerate from source |
+
+Scripts take `--help`, print JSON, exit non-zero on failure; pages are 1-based. Always call scripts by the absolute paths shown here (not a copy found elsewhere on disk).
+Dependencies: `python3 -m pip install pypdf reportlab pdfplumber pypdfium2` (OCR extras per reference file).
+
+## Design (documents you create)
+
+- Choose palette and type from the content, not "safe" defaults (`${SKILL_DIR}/references/design-tokens.md`): one accent color, one heading face, one body face; A4 for China/Europe, Letter for the US; margins ≥ 20 mm.
+- Chinese text: body 10.5–12 pt with 1.6–1.8 line height; headings 黑体/思源黑体, body 宋体/思源宋体 or 苹方/雅黑 for screen reading; full-width punctuation.
+- Cover pages and TOCs only for long documents (> 6 pages). Tables: header row shaded, numbers right-aligned, repeat header on page breaks.
+- Page numbers on every page except the cover; "第 X 页 / 共 Y 页" for Chinese.
+
+## Pitfalls
+
+- **Fonts**: reportlab's built-in Helvetica has no Chinese glyphs — text becomes black boxes. `pdf_create.py` handles this; in your own reportlab code register a TrueType CJK font (`TTFont`) and set `wordWrap="CJK"`. Hiragino/PingFang on macOS are CFF and can't be embedded by reportlab — use STHeiti/Songti, Windows 微软雅黑/宋体, or Noto Sans/Serif CJK.
+- **Scanned PDFs** have no text layer: empty `--text` plus page images means OCR, not "empty document".
+- **Encrypted inputs** must be decrypted first (`pdf_secure.py --decrypt`).
+- **Owner-password permissions** (no-print/no-copy) are advisory; only a user password protects content. Don't present them as security.
+- **Form values in CJK** are stored correctly but a field's default font may not show them; verify with `--fields` and flatten with an embedded CJK font if appearance matters.
+- **Table extraction is heuristic** — borderless or merged-cell tables need checking against the page image.
+- **PDF/A** is not produced by these libraries; use Ghostscript + veraPDF if archival conformance is required.
+
+## Verify before delivery (required)
+
+1. `python3 ${SKILL_DIR}/scripts/pdf_read.py out.pdf --meta` — page count, sizes, encryption as intended.
+2. `python3 ${SKILL_DIR}/scripts/render.py out.pdf` and **open every page image** (or the pages you changed): black boxes or missing CJK glyphs, text past margins, tables split badly, blank trailing page, wrong page numbers, watermark covering content.
+3. After extraction/OCR: spot-check a known string or table cell against the page image. After form fill: re-read `--fields` and compare values exactly.