@acedatacloud/skills 2026.703.1 → 2026.703.3

package/README.md

@@ -70,7 +70,9 @@ These skills drive third-party connectors users wire up at [auth.acedata.cloud/u
 | [slack](skills/slack/) | Read Slack channels, messages, and user info via Web API | `slack` |
 | [wechat-official-account](skills/wechat-official-account/) | Manage WeChat MP — drafts, publishing, materials, user tags | `wechat` (BYOC) |
 | [personal-wechat](skills/personal-wechat/) | Operate a personal WeChat account through a self-hosted Wisdom service | `personalwechat` (BYOC) |
+| [didi-ride](skills/didi-ride/) | Book DiDi rides, estimate fares, query/cancel orders, plan routes via the DiDi MCP | `didi` (BYOC) |
 | [wecom](skills/wecom/) | WeCom (企业微信) self-built app — contacts, app messages, WeDoc, schedules, meetings | `wecom` (BYOC) |
+| [tencent-docs](skills/tencent-docs/) | Create / read / list / search / manage Tencent Docs — docs, sheets, slides, mind maps, flowcharts | `tencentdocs` (BYOC) |
 
 ## Prerequisites
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.703.1",
+  "version": "2026.703.3",
   "description": "Agent Skills for AceDataCloud AI services — music, image, video generation, LLM chat, web search. Compatible with Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex, and 30+ AI coding agents.",
   "keywords": [
     "agent-skills",

package/skills/didi-ride/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: didi-ride
+description: 通过滴滴出行 MCP 打车、查价、查询订单、取消订单、规划路线（驾车/公交/步行/骑行）和搜索地点。Use when the user mentions 滴滴, 打车, 叫车, 回家/上班要打车, 查一下从 A 到 B 多少钱/怎么走, 查询订单, 司机在哪/多久到, 预约叫车, 路线规划, DiDi, ride-hailing, or booking a taxi.
+when_to_use: |
+  Trigger for anything involving the user's DiDi (滴滴出行) account:
+  book a ride ("打车去…", "回家", "上班"), get a fare/route estimate,
+  query an existing order (driver location, ETA, trip progress), cancel
+  an order, plan a driving/transit/walking/cycling route, or search
+  places / reverse-geocode. Creating and cancelling orders act on real
+  money and a real driver, so those writes are gated behind explicit
+  confirmation.
+connections: [didi]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+# DiDi Ride (滴滴出行)
+
+Drive the user's **DiDi (滴滴出行)** account through the DiDi MCP server:
+book rides, estimate fares, track orders, cancel, and plan routes.
+
+The `didi` BYOC connector injects one env var into the sandbox:
+
+- `DIDI_MCP_KEY` — the user's DiDi MCP key. **Secret — never echo, print, or log it.**
+
+If `DIDI_MCP_KEY` is missing, tell the user to connect the DiDi connector at
+[auth.acedata.cloud/user/connections](https://auth.acedata.cloud/user/connections)
+(they get the key by scanning the QR in the 滴滴出行 App or via
+<https://mcp.didichuxing.com/claw>).
+
+## CLI
+
+The skill ships a stdlib-only helper that speaks the MCP Streamable-HTTP
+protocol to DiDi. Point at it once:
+
+```bash
+DIDI=$SKILL_DIR/scripts/didi.py
+```
+
+Two commands:
+
+```bash
+python3 $DIDI list                        # list tools + their JSON input schemas
+python3 $DIDI call <tool> '<json-args>'   # call any tool
+```
+
+**Always check `references/api_references.md` for the exact tool + parameter
+names before calling.** When unsure, run `python3 $DIDI list` — it returns the
+authoritative input schema for every tool straight from DiDi. Do **not** guess
+parameter names (common mistakes: `keyword` → `keywords`, `region` → `city`,
+four coord fields → six `from_name/from_lat/from_lng/to_name/to_lat/to_lng`).
+
+All argument **values must be strings** (including coordinates and
+`product_category`), e.g. `{"product_category":"1"}` not `{"product_category":1}`.
+
+## Write gating (real money / real driver)
+
+`taxi_create_order` and `taxi_cancel_order` are **gated**: without a trailing
+`--confirm` the helper only DRY-RUNS and changes nothing. Run once without
+`--confirm` to preview, then re-run with `--confirm` as the **last** argument
+after the user approves:
+
+```bash
+python3 $DIDI call taxi_create_order '{"estimate_trace_id":"...","product_category":"1"}' --confirm
+```
+
+- Even when the user says "打车" / "取消订单", confirm the concrete details
+  (起终点、车型 for booking; the order for cancelling) before adding `--confirm`.
+- Cancel intent ≠ cancel confirmation — always ask "确认取消吗？" first.
+
+## Booking flow (最小可执行)
+
+1. **Resolve addresses** — `maps_textsearch` (never invent coordinates; don't
+   reuse coordinates from earlier turns — the user may have moved).
+   - If the user references an address alias (家 / 公司 / etc.) that you don't
+     have, ask them; this skill has no stored preferences.
+2. **Confirm start/end** — if `maps_textsearch` returns ≥2 candidates, list at
+   least the top 3 and let the user pick; a single exact match needs no
+   confirmation.
+3. **Estimate** — `taxi_estimate`; record the returned `traceId` /
+   `estimate_trace_id`. It expires (`-32021`) — re-estimate if stale.
+4. **Pick car type** — user's current message wins ("叫快车"→`product_category`
+   `1`, "专车"→`8`); otherwise ask. Only use categories present in the
+   `taxi_estimate` response; never silently substitute a different service level
+   (快车 `1` ≠ 特惠快车 `201`).
+5. **Create order** — `taxi_create_order` with the latest `estimate_trace_id`
+   (dry-run → confirm → `--confirm`).
+6. **Report** — order id, start/end, car type, estimated fare. Tell the user
+   they can send 「查询订单」 to check status.
+
+## Query an order
+
+Order id comes from (in priority): the user's message → the most recent order
+created this conversation → else ask.
+
+```bash
+python3 $DIDI call taxi_query_order '{"order_id":"ORDER_ID"}'
+```
+
+Status codes (`code`):
+
+| code | 含义 | 输出 |
+|------|------|------|
+| 0 | 匹配中 | ⏳ 正在为您匹配司机 |
+| 1 | 司机已接单 | 展示司机姓名、车型、车牌、电话、距离与预计到达时间 |
+| 2 | 司机已到达 | 🔔 司机已到达上车点 |
+| 4 | 行程进行中 | 🚗 行程已开始 |
+| 5 | 订单完成 | ✅ 行程结束（展示费用，如有） |
+| 6 | 系统取消 | ❌ 订单已被系统取消 |
+| 7 | 已取消 | ❌ 订单已取消 |
+| 3 / 8-12 | 其他终态 | 显示对应状态描述 |
+
+## Routes & places (no order needed)
+
+```bash
+python3 $DIDI call maps_direction_driving  '{"from_name":"...","from_lat":"...","from_lng":"...","to_name":"...","to_lat":"...","to_lng":"..."}'
+python3 $DIDI call maps_direction_transit  '{...}'   # 公交
+python3 $DIDI call maps_direction_walking  '{...}'   # 步行
+python3 $DIDI call maps_direction_bicycling '{...}'  # 骑行
+python3 $DIDI call maps_place_around '{"keywords":"咖啡","lat":"...","lng":"..."}'
+python3 $DIDI call maps_regeocode '{"lat":"...","lng":"..."}'
+```
+
+## Gotchas
+
+- **Never print the key or the raw endpoint URL** — the helper handles the
+  transport and keeps the key internal.
+- `taxi_create_order` takes only `estimate_trace_id`, `product_category`, and
+  optional `caller_car_phone`. Don't pass the estimate's coordinate/name fields.
+- No stored preferences: this skill doesn't remember home/work/car type — ask
+  the user, or wire richer memory in a higher layer.
+- Auth failure surfaces as `-32002` (or HTTP 401/403): the key is missing/expired
+  → have the user reconnect the connector.
+
+> **Setup:** See [authentication](../_shared/authentication.md). This skill uses
+> the `didi` connector's injected `DIDI_MCP_KEY`, not `ACEDATACLOUD_API_TOKEN`.

package/skills/didi-ride/references/api_references.md

@@ -0,0 +1,97 @@
+# DiDi MCP — Tool Reference
+
+Authoritative schemas come from `python3 $DIDI list` (the DiDi server returns
+each tool's `inputSchema`). This file summarizes the tools and the parameter
+names that are easy to get wrong. **All values are strings.**
+
+## Places & geocoding
+
+### `maps_textsearch` — search a place by text
+| param | required | notes |
+|-------|----------|-------|
+| `keywords` | yes | search text, e.g. `北京西站` (NOT `keyword`) |
+| `city` | no | city name to scope the search, e.g. `北京` (NOT `region`) |
+
+Returns candidate places with names + coordinates. Use these coordinates for
+`taxi_estimate` and the `maps_direction_*` tools.
+
+### `maps_regeocode` — coordinates → address
+| param | required |
+|-------|----------|
+| `lat` | yes |
+| `lng` | yes |
+
+## Routes
+
+`maps_direction_driving` / `maps_direction_transit` / `maps_direction_walking`
+/ `maps_direction_bicycling` — all take the same six fields:
+
+| param | required |
+|-------|----------|
+| `from_name` | yes |
+| `from_lat` | yes |
+| `from_lng` | yes |
+| `to_name` | yes |
+| `to_lat` | yes |
+| `to_lng` | yes |
+
+### `maps_place_around` — nearby POI search
+| param | required | notes |
+|-------|----------|-------|
+| `keywords` | yes | POI keyword, e.g. `咖啡` |
+| `lat` | yes | center latitude |
+| `lng` | yes | center longitude |
+
+## Ride hailing
+
+### `taxi_estimate` — price/ETA estimate (do this before ordering)
+Six coordinate/name fields (same as routes):
+`from_name`, `from_lat`, `from_lng`, `to_name`, `to_lat`, `to_lng`.
+
+Returns a list of available car types, each with a `productCategory` and price,
+plus a `traceId` / `estimate_trace_id` required by `taxi_create_order`. The
+trace id expires — a stale one returns `-32021`; re-estimate to refresh.
+
+Common `product_category` values:
+
+| code | 车型 |
+|------|------|
+| `1` | 快车 |
+| `8` | 专车 |
+| `201` | 特惠快车 |
+
+> Treat these as hints — always match against the `productCategory` values the
+> live `taxi_estimate` response actually returns. `1` (快车) and `201`
+> (特惠快车) are different service levels; never swap one for the other.
+
+### `taxi_create_order` — book the ride  ⚠️ WRITE (needs `--confirm`)
+| param | required | notes |
+|-------|----------|-------|
+| `estimate_trace_id` | yes | from the latest `taxi_estimate` |
+| `product_category` | yes | chosen car type code (string) |
+| `caller_car_phone` | no | omit unless the user gives a number |
+
+Only these three fields. Do **not** pass coordinate/name fields.
+
+### `taxi_query_order` — status + driver location
+| param | required |
+|-------|----------|
+| `order_id` | yes |
+
+Status `code`: `0` 匹配中 · `1` 司机已接单 · `2` 司机已到达 · `4` 行程中 ·
+`5` 完成 · `6` 系统取消 · `7` 已取消 · `3`/`8`-`12` 其他终态.
+
+### `taxi_cancel_order` — cancel  ⚠️ WRITE (needs `--confirm`)
+| param | required |
+|-------|----------|
+| `order_id` | yes |
+
+Always ask "确认取消吗？" before adding `--confirm`.
+
+## Errors
+
+| code | meaning | action |
+|------|---------|--------|
+| `-32002` / HTTP 401 / 403 | auth failed | key missing/expired → reconnect connector |
+| `-32021` | estimate trace expired | re-run `taxi_estimate` |
+| HTTP 400 | bad params | re-check parameter names against `didi.py list` |

package/skills/didi-ride/scripts/didi.py

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+"""DiDi ride helper — talks to the DiDi MCP server over the MCP
+Streamable-HTTP transport using only the Python standard library.
+
+The `didi` BYOC connector injects one env var:
+
+    DIDI_MCP_KEY   the user's DiDi MCP key (secret — never printed)
+
+Usage:
+    python3 didi.py list                        # list available tools + schemas
+    python3 didi.py call <tool> '<json-args>'   # call any tool
+
+State-changing tools (`taxi_create_order`, `taxi_cancel_order`) are
+gated: without a trailing `--confirm` they only DRY-RUN and change
+nothing. `--confirm` is honored only as the LAST argument.
+
+Examples:
+    python3 didi.py call maps_textsearch '{"keywords":"北京西站","city":"北京"}'
+    python3 didi.py call taxi_estimate '{"from_name":"...","from_lat":"39.9","from_lng":"116.3","to_name":"...","to_lat":"39.9","to_lng":"116.4"}'
+    python3 didi.py call taxi_create_order '{"estimate_trace_id":"...","product_category":"1"}' --confirm
+    python3 didi.py call taxi_query_order '{"order_id":"..."}'
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+MCP_ENDPOINT = os.environ.get("DIDI_MCP_URL", "https://mcp.didichuxing.com/mcp-servers")
+MCP_KEY = os.environ.get("DIDI_MCP_KEY", "").strip()
+PROTOCOL_VERSION = "2025-06-18"
+
+# Tools that create or cancel a real ride — must be confirmed explicitly.
+WRITE_TOOLS = {"taxi_create_order", "taxi_cancel_order"}
+
+
+def die(payload: dict, code: int = 1) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    sys.exit(code)
+
+
+class MCPClient:
+    """Minimal MCP Streamable-HTTP client (stdlib only).
+
+    Never logs or echoes the key; the endpoint URL (which carries the
+    key as a query param) is kept internal and never printed.
+    """
+
+    def __init__(self, endpoint: str, key: str) -> None:
+        sep = "&" if "?" in endpoint else "?"
+        self._url = f"{endpoint}{sep}key={urllib.parse.quote(key, safe='')}"
+        self._session_id: str | None = None
+        self._rid = 0
+
+    def _post(self, payload: dict, expect_id):
+        body = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(self._url, data=body, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Accept", "application/json, text/event-stream")
+        req.add_header("MCP-Protocol-Version", PROTOCOL_VERSION)
+        if self._session_id:
+            req.add_header("Mcp-Session-Id", self._session_id)
+        try:
+            resp = urllib.request.urlopen(req, timeout=90)
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", "replace")[:600]
+            die(
+                {
+                    "error": f"HTTP {exc.code} from DiDi MCP",
+                    "detail": detail,
+                    "hint": "If 401/403, the DiDi connector key is missing or expired — "
+                    "reconnect at https://auth.acedata.cloud/user/connections",
+                }
+            )
+        except urllib.error.URLError as exc:
+            die({"error": "network error reaching DiDi MCP", "detail": str(exc.reason)})
+        except Exception as exc:  # noqa: BLE001
+            # Never let an unexpected traceback surface — self._url carries the
+            # key as a query param (DiDi mandates ?key=), so emit only the
+            # exception type, never its message or the URL.
+            die({"error": "unexpected error calling DiDi MCP", "detail": type(exc).__name__})
+        sid = resp.headers.get("Mcp-Session-Id")
+        if sid:
+            self._session_id = sid
+        ctype = (resp.headers.get("Content-Type") or "").lower()
+        raw = resp.read().decode("utf-8", "replace")
+        return _parse_response(raw, ctype, expect_id)
+
+    def initialize(self) -> None:
+        self._rid += 1
+        result = self._post(
+            {
+                "jsonrpc": "2.0",
+                "id": self._rid,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "capabilities": {},
+                    "clientInfo": {"name": "acedata-didi-skill", "version": "1.0"},
+                },
+            },
+            expect_id=self._rid,
+        )
+        if isinstance(result, dict) and result.get("error"):
+            die({"error": "DiDi MCP initialize failed", "detail": result["error"]})
+        # Fire-and-forget the initialized notification (no response expected).
+        self._post({"jsonrpc": "2.0", "method": "notifications/initialized"}, expect_id=None)
+
+    def list_tools(self):
+        self._rid += 1
+        return self._post(
+            {"jsonrpc": "2.0", "id": self._rid, "method": "tools/list"},
+            expect_id=self._rid,
+        )
+
+    def call_tool(self, name: str, arguments: dict):
+        self._rid += 1
+        return self._post(
+            {
+                "jsonrpc": "2.0",
+                "id": self._rid,
+                "method": "tools/call",
+                "params": {"name": name, "arguments": arguments},
+            },
+            expect_id=self._rid,
+        )
+
+
+def _parse_response(raw: str, ctype: str, expect_id):
+    """Return the JSON-RPC envelope for our request id.
+
+    Handles both plain application/json and text/event-stream (SSE),
+    where the response arrives as one or more `data: {...}` lines.
+    """
+    messages: list[dict] = []
+    if "text/event-stream" in ctype:
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line.startswith("data:"):
+                continue
+            chunk = line[5:].strip()
+            if not chunk or chunk == "[DONE]":
+                continue
+            try:
+                messages.append(json.loads(chunk))
+            except json.JSONDecodeError:
+                continue
+    else:
+        raw = raw.strip()
+        if not raw:
+            return {}
+        try:
+            messages.append(json.loads(raw))
+        except json.JSONDecodeError:
+            die({"error": "unparseable response from DiDi MCP", "detail": raw[:600]})
+    if expect_id is not None:
+        for msg in messages:
+            if isinstance(msg, dict) and msg.get("id") == expect_id:
+                return msg
+    return messages[-1] if messages else {}
+
+
+def emit(envelope: dict) -> None:
+    if not isinstance(envelope, dict):
+        print(json.dumps(envelope, ensure_ascii=False, indent=2))
+        return
+    if envelope.get("error"):
+        die({"error": envelope["error"]})
+    result = envelope.get("result", envelope)
+    # tools/call results wrap text in a content[] array.
+    if isinstance(result, dict) and isinstance(result.get("content"), list):
+        texts = [
+            c.get("text", "")
+            for c in result["content"]
+            if isinstance(c, dict) and c.get("type") == "text"
+        ]
+        if texts:
+            print("\n".join(texts))
+            if result.get("isError"):
+                sys.exit(1)
+            return
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+def _format_tools(envelope: dict) -> None:
+    tools = (envelope.get("result") or {}).get("tools") if isinstance(envelope, dict) else None
+    if not tools:
+        emit(envelope)
+        return
+    slim = [
+        {
+            "name": t.get("name"),
+            "description": t.get("description"),
+            "inputSchema": t.get("inputSchema"),
+        }
+        for t in tools
+    ]
+    print(json.dumps(slim, ensure_ascii=False, indent=2))
+
+
+def main() -> None:
+    if not MCP_KEY:
+        die(
+            {
+                "error": "DIDI_MCP_KEY not set",
+                "hint": "Connect the DiDi connector at "
+                "https://auth.acedata.cloud/user/connections to inject the key.",
+            }
+        )
+
+    argv = sys.argv[1:]
+    confirm = bool(argv) and argv[-1] == "--confirm"
+    if confirm:
+        argv = argv[:-1]
+    if not argv:
+        die({"error": "usage: didi.py <list|call> ..."})
+
+    cmd, rest = argv[0], argv[1:]
+    client = MCPClient(MCP_ENDPOINT, MCP_KEY)
+
+    if cmd == "list":
+        client.initialize()
+        _format_tools(client.list_tools())
+        return
+
+    if cmd == "call":
+        if not rest:
+            die({"error": "call needs a tool name", "usage": "didi.py call <tool> '<json-args>'"})
+        tool = rest[0]
+        args_raw = rest[1] if len(rest) > 1 else "{}"
+        try:
+            arguments = json.loads(args_raw)
+        except json.JSONDecodeError as exc:
+            die({"error": "arguments must be valid JSON", "detail": str(exc), "got": args_raw})
+        if not isinstance(arguments, dict):
+            die({"error": "arguments JSON must be an object", "got": args_raw})
+
+        if tool in WRITE_TOOLS and not confirm:
+            print(
+                json.dumps(
+                    {
+                        "dry_run": True,
+                        "tool": tool,
+                        "arguments": arguments,
+                        "note": "state-changing call — re-run with --confirm as the LAST "
+                        "argument to actually perform it",
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+            return
+
+        client.initialize()
+        emit(client.call_tool(tool, arguments))
+        return
+
+    die({"error": f"unknown command: {cmd}", "usage": "didi.py <list|call> ..."})
+
+
+if __name__ == "__main__":
+    main()

package/skills/tencent-docs/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: tencent-docs
+description: Create, read, list, search, and manage Tencent Docs (腾讯文档) — online documents, sheets, slides, mind maps, flowcharts, smart tables, and forms — via the Tencent Docs Open API. Use when the user mentions 腾讯文档 / Tencent Docs / docs.qq.com, a docs.qq.com link, or wants to create / read / organize a doc, sheet, slide, mind map, or flowchart in their Tencent Docs space.
+when_to_use: |
+  Trigger when the user wants to work with their Tencent Docs (腾讯文档) space —
+  create a new document / sheet / slide / mind map / flowchart / smart table /
+  form, read a doc or sheet's content, list a folder, search files by keyword,
+  or rename / move / copy / delete a file. Acts in the user's own Tencent Docs
+  account, so destructive or outward-facing writes are gated behind confirmation.
+connections: [tencentdocs]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+# Tencent Docs (腾讯文档)
+
+Drive the [Tencent Docs Open API](https://docs.qq.com/open/document/app/) with
+`curl + jq`. Everything runs **in the user's own Tencent Docs account** — only
+files they can access, only the scopes they granted at connect time.
+
+## Auth — three headers (NOT a single Bearer)
+
+The `tencentdocs` BYOC connector injects three env vars; every call sends **all
+three** headers:
+
+- `TENCENTDOCS_ACCESS_TOKEN` → `Access-Token` header (OAuth2 access token). **Secret.**
+- `TENCENTDOCS_CLIENT_ID` → `Client-Id` header (the developer app's Client ID).
+- `TENCENTDOCS_OPEN_ID` → `Open-Id` header (the user id returned with the token).
+
+All endpoints live under `https://docs.qq.com/openapi`. Define a reusable header
+set once per session:
+
+```sh
+AUTH=(-H "Access-Token: $TENCENTDOCS_ACCESS_TOKEN" \
+      -H "Client-Id: $TENCENTDOCS_CLIENT_ID" \
+      -H "Open-Id: $TENCENTDOCS_OPEN_ID")
+```
+
+Never echo, print, or log `TENCENTDOCS_ACCESS_TOKEN` — it is full account access.
+
+## Response shape & error handling
+
+Every response is `{"ret": 0, "msg": "Succeed", "data": {…}}`. **`ret == 0`
+means success**; any non-zero `ret` is an error — surface `msg` to the user.
+Always check it:
+
+```sh
+resp=$(curl -sS "${AUTH[@]}" … )
+echo "$resp" | jq 'if .ret == 0 then .data else error("Tencent Docs \(.ret): \(.msg)") end'
+```
+
+Common error codes:
+
+| code | meaning | what to do |
+|---|---|---|
+| `400006` | access token invalid / expired | tell the user to reconnect 腾讯文档 at <https://auth.acedata.cloud/user/connections> — do **not** loop-retry |
+| `400007` | VIP (超级会员) privilege required | the requested capability needs a Tencent Docs 超级会员; tell the user, link <https://docs.qq.com/vip> |
+| `400008` | 积分 (credits) insufficient | AI-generation quota is exhausted; tell the user to top up |
+| `11607` / `-32603` | bad request params | recheck `fileID` / `type` / body fields against the recipe below |
+
+## Doc types (`type` when creating)
+
+| type | Product | Notes |
+|---|---|---|
+| `doc` | 在线文档 (Word-style) | classic rich-text document |
+| `sheet` | 在线表格 (Excel) | data tables |
+| `slide` | 幻灯片 (PPT) | presentations |
+| `mind` | 思维导图 | mind map |
+| `flowchart` | 流程图 | flowchart |
+| `smartsheet` | 智能表格 | structured multi-view table |
+| `form` | 收集表 | form / survey |
+
+## Recipes
+
+### Verify auth (always run first)
+
+Cheap sanity check — read the app's OpenAPI usage counter:
+
+```sh
+curl -sS "${AUTH[@]}" "https://docs.qq.com/openapi/drive/v2/util/resource-use" \
+  | jq 'if .ret == 0 then .data else "ERR \(.ret): \(.msg)" end'
+```
+
+If this returns `400006`, the connection is expired — have the user reconnect.
+
+### List a folder (root = `/`)
+
+```sh
+curl -sS "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/folders/%2F?listType=folder&sortType=browse&asc=0" \
+  | jq 'if .ret == 0 then [.data.list[]? | {ID, title, type, url}] else . end'
+```
+
+`%2F` is the URL-encoded root folder id. For a sub-folder use its folder id in
+the path.
+
+### Search files by keyword
+
+```sh
+curl -sS -G "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/search" \
+  --data-urlencode "searchName=Q1 预算" \
+  | jq 'if .ret == 0 then [.data.list[]? | {ID, title, type, url}] else . end'
+```
+
+### Read a file's metadata
+
+The `fileID` is the last path segment of a `https://docs.qq.com/doc/<id>` (or
+`/sheet/`, `/slide/`, …) URL.
+
+```sh
+curl -sS "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/metadata" \
+  | jq 'if .ret == 0 then .data else . end'
+```
+
+### Read an online document's content
+
+```sh
+curl -sS "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/document/v3/files/FILE_ID/export?exportType=text" \
+  | jq 'if .ret == 0 then .data else . end'
+```
+
+### Read a sheet's cell range
+
+Get the sheet's `sheetId` list from the metadata first, then read a range
+(`A1:D10`):
+
+```sh
+curl -sS "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/spreadsheet/v2/files/FILE_ID/sheets/SHEET_ID/values?range=A1:D10" \
+  | jq 'if .ret == 0 then .data.values else . end'
+```
+
+### Create a file
+
+`POST /openapi/drive/v2/files` with form-urlencoded `title` + `type`. Returns the
+new file's `ID` and `url`.
+
+```sh
+curl -sS -X POST "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/files" \
+  --data-urlencode "title=会议纪要 2026-07-03" \
+  --data-urlencode "type=doc" \
+  | jq 'if .ret == 0 then {ID: .data.ID, url: .data.url} else . end'
+```
+
+Swap `type=sheet` / `slide` / `mind` / `flowchart` / `smartsheet` / `form` for
+other doc types. Pass `--data-urlencode "folderID=<id>"` to create inside a
+folder instead of the root.
+
+### Upload an image (for embedding in docs)
+
+```sh
+curl -sS -X POST "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/resources/v2/images" \
+  -F "file=@./cover.png" \
+  | jq 'if .ret == 0 then .data else . end'
+```
+
+### Rename a file — GATED, confirm first
+
+Show the user the current `title` + `url` and the new title, get an explicit
+"yes", then run:
+
+```sh
+curl -sS -X PATCH "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID" \
+  --data-urlencode "title=新的标题" \
+  | jq 'if .ret == 0 then "renamed" else . end'
+```
+
+### Move a file — GATED, confirm first
+
+Show the user the file's current `title` + location and the destination folder,
+get an explicit "yes", then run. `folderID=/` moves it back to the root.
+
+```sh
+curl -sS -X PATCH "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/move" \
+  --data-urlencode "folderID=DEST_FOLDER_ID" \
+  | jq 'if .ret == 0 then "moved" else . end'
+```
+
+### Copy a file
+
+```sh
+curl -sS -X POST "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/copy" \
+  --data-urlencode "title=副本 - 项目计划" \
+  | jq 'if .ret == 0 then {ID: .data.ID, url: .data.url} else . end'
+```
+
+### Delete a file — GATED, confirm first
+
+Deletion moves the file to the recycle bin but is still destructive. **Show the
+user the exact `title` + `url`, get an explicit "yes", then run:**
+
+```sh
+curl -sS -X DELETE "${AUTH[@]}" \
+  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID" \
+  | jq 'if .ret == 0 then "deleted" else . end'
+```
+
+## Notes
+
+- **Gate writes.** Rename / move / delete / copy and any share-permission change
+  act on the user's real files — confirm the exact target before running.
+- **Extract ids from links.** When the user pastes a `docs.qq.com/doc/<id>` (or
+  `/sheet/`, `/slide/`, `/mind/`, `/flowchart/`, `/form/`, `/smartsheet/`) URL,
+  take the id from the path rather than asking for it.
+- **Pagination.** List / search endpoints return a cursor / `next` marker in
+  `data`; pass it back to fetch the next page. Stop when the marker is empty.
+- **Rate / quota.** Free apps get 20,000 API calls/month (超级会员 20,000/day,
+  Plus 40,000/day). AI-generation features additionally consume 积分 and may
+  require 超级会员 — a `400007` / `400008` means the account tier / credits, not a
+  bug in the request.
+- **Full API index.** Beyond the recipes above, the Open API also covers
+  smart-table records, form collection, folder CRUD, permissions, and
+  import/export — see the [接口索引](https://docs.qq.com/open/document/app/openapi/v2/file/).