@acedatacloud/skills 2026.702.0 → 2026.703.1

package/README.md

@@ -70,6 +70,7 @@ 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) |
+| [wecom](skills/wecom/) | WeCom (企业微信) self-built app — contacts, app messages, WeDoc, schedules, meetings | `wecom` (BYOC) |
 
 ## Prerequisites
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.702.0",
+  "version": "2026.703.1",
   "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/_shared/wecom.md

@@ -0,0 +1,97 @@
+# 企业微信 (WeCom) Authentication
+
+The `wecom` skill talks to the [WeCom server-side API](https://developer.work.weixin.qq.com/document/path/90664)
+(`https://qyapi.weixin.qq.com`) as a **self-built app (企业内部开发 / 自建应用)**.
+Unlike OAuth-bearer connectors, WeCom uses a two-step token flow that is
+identical in shape to the WeChat Official Account API:
+
+1. Exchange `CorpID + Secret` for an `access_token` (TTL 7200s).
+2. Pass that `access_token` as a **query string parameter** on every other call.
+
+## Create a self-built app & collect three values
+
+1. Sign in to the [WeCom admin console](https://work.weixin.qq.com/wework_admin/) as an
+   administrator → **应用管理 (App Management) → 自建 (Self-built) → 创建应用 (Create App)**.
+2. After the app is created, open it and read off:
+   - **CorpID** — 我的企业 (My Company) → 企业信息 (Company Info), at the bottom (`ww...` / `wc...`).
+   - **Secret** — the app's own Secret, shown on the app detail page (click "查看"/"获取"; it is
+     sent to the admin's WeCom, not displayed inline).
+   - **AgentId** — the app's AgentId, shown on the same app detail page.
+
+## Grant the app the permissions the skill needs
+
+An app only sees what you grant it. On the app detail page configure:
+
+| Capability the skill uses | What to enable on the app |
+|---|---|
+| Read members / departments (通讯录) | **通讯录 (Contacts)** → set the app's "可见范围" (visible scope) to the members/departments it may act on; to read real names/mobiles, grant **通讯录同步/读取** privilege |
+| Send app messages (应用消息) | enabled by default for a self-built app (uses its AgentId) |
+| Docs / smart sheets (文档/智能表格) | **文档 (WeDoc)** interface permission |
+| Schedules (日程) | **日历/日程 (Calendar)** interface permission |
+| Meetings (会议) | **会议 (Meeting)** interface permission |
+
+> ⚠️ **Server IP allowlist.** WeCom rejects calls whose source IP is not in the app's
+> **企业可信IP (trusted IP)** list. If you see `errcode 60020` ("not allow to access from your ip"),
+> add the caller's egress IP shown in `errmsg` to the app's trusted-IP list and retry.
+
+## Environment variables
+
+The skill reads three variables. On AceDataCloud they are injected automatically for you
+(see below); for local runs, export them yourself.
+
+| Variable | Description | Example |
+|---|---|---|
+| `WECOM_CORP_ID` | Enterprise CorpID | `ww1234567890abcdef` |
+| `WECOM_CORP_SECRET` | The self-built app's Secret (sensitive) | `xxxxxxxxxxxxxxxxxxxx` |
+| `WECOM_AGENT_ID` | The self-built app's AgentId | `1000002` |
+
+**Local dev — `.env` file**:
+
+```bash
+WECOM_CORP_ID=ww1234567890abcdef
+WECOM_CORP_SECRET=your-app-secret
+WECOM_AGENT_ID=1000002
+```
+
+Load it before running the skill:
+
+```bash
+set -a; source .env; set +a
+```
+
+> ⚠️ **Never commit `.env`** — the Secret is equivalent to full app access. Add it to `.gitignore`.
+
+**Agent usage** (Claude / Studio / etc.): install the
+[企业微信 connector](https://auth.acedata.cloud/user/connections) on AceDataCloud once. Your
+CorpID / Secret / AgentId are AES-256-GCM encrypted at rest and injected as the env vars above
+only inside the sandbox while the skill runs — no manual `.env` setup needed. Revoke anytime from
+the connections page.
+
+## Response shape & error handling
+
+Every WeCom response is JSON returned with **HTTP 200**; success is `errcode == 0`:
+
+```json
+{"errcode": 0, "errmsg": "ok", "...": "..."}
+```
+
+Any non-zero `errcode` is an error — surface `errmsg` to the user verbatim. Common codes:
+
+| errcode | meaning | what to do |
+|---|---|---|
+| `40014` / `42001` | invalid / expired `access_token` | refresh the token (the recipe caches it — delete the cache and retry) |
+| `40056` | invalid AgentId | check `WECOM_AGENT_ID` matches the app whose Secret you used |
+| `48002` | API forbidden — app lacks this interface permission | grant the matching capability (docs/calendar/meeting) to the app |
+| `60011` | no privilege to access this user/department/resource | the target is outside the app's visible scope — widen 可见范围 |
+| `60020` | caller IP not in trusted-IP list | add the egress IP from `errmsg` to 企业可信IP |
+| `301002` | no privilege to read contacts detail | grant 通讯录读取 privilege to the app |
+| `81013` | user not in app scope | add the user to the app's 可见范围 |
+
+## What is intentionally out of scope
+
+- **Reading inbound chat history (会话内容存档 / msgaudit).** That is a separate paid
+  enterprise capability requiring a dedicated Secret, an RSA private key, and the native
+  WeCom Finance SDK — it cannot run inside this stdlib sandbox. The skill can *send* app
+  messages but cannot *read* members' private conversations.
+- **A general todo (待办) CRUD.** WeCom's open API exposes no self-built-app todo endpoints;
+  use **schedules (日程)** for time-bound reminders instead.

package/skills/medium/SKILL.md

@@ -25,7 +25,9 @@ The connector injects the cookie jar as an env var:
 
 - `MEDIUM_COOKIES` — a JSON array of cookies (`sid`, `uid`, `xsrf`). **Secret —
   never echo or print it.** The CLI echoes the `xsrf` cookie as the
-  `x-xsrf-token` header on writes for you.
+  `x-xsrf-token` header on writes for you. If the captured jar has no `xsrf`
+  cookie (common), the CLI mints one automatically before writing, so publishes
+  no longer fail with "Missing xsrf token".
 
 ## CLI
 
@@ -51,7 +53,11 @@ On an auth error the cookie is expired — have the user reconnect at
 ## Publishing — GATED (dry-run unless trailing `--confirm`)
 
 `publish` writes to the user's real account. Content is **Markdown** (converted
-to Medium paragraph blocks: `#`→H1, `##`→H2, `>`→quote, ```` ``` ````→code).
+to Medium paragraph blocks: `#`/`##`→heading, `###`→sub-heading, `>`→quote,
+```` ``` ````→code, `-`/`*`→bullet list, `1.`→numbered list, tables→aligned
+code block). Inline **bold**, *italic*, `code`, and `[links](url)` render as
+real Medium formatting (clickable links included). Bare `https://…` URLs in text
+are auto-linked too (URLs inside code spans are left untouched).
 Without a trailing `--confirm` it dry-runs. `--confirm` is honored **only as the
 last argument**. Always show the dry-run, get an explicit "yes", then re-run.
 
@@ -76,9 +82,12 @@ to a link paragraph (never blocks the post).
 ## Gotchas
 
 - **This is the user's real Medium account.** Confirm before any publish.
-- Markdown→Medium conversion is paragraph-level (headings, quotes, code, body);
-  complex inline formatting / images aren't converted — the user can polish in
-  the Medium editor before going public.
+- Markdown→Medium conversion covers headings, quotes, fenced code, bullet/
+  numbered lists, images, and inline markups (bold/italic/code/links). Medium's
+  editor has no table element: a narrow markdown table renders as an aligned
+  monospace code block, while a wide one (long cells / URLs, which would wrap into
+  an unreadable grid) is rendered as per-row records — the first column bolded as
+  a lead-in, the remaining columns as `header: value` bullets.
 - Medium sits behind Cloudflare; an occasional 403/429 is transient — the CLI
   auto-retries once after a short pause. A *persistent* 403 means the cookie is
   genuinely expired (reconnect).

package/skills/medium/scripts/medium.py

@@ -174,6 +174,32 @@ def api(method, url, jar, *, body=None, _retried=False):
     return d
 
 
+def prime_xsrf(jar) -> None:
+    """Ensure the jar carries an ``xsrf`` cookie. Captured jars frequently lack
+    it, but Medium hands one out on any GET of the site; without it the
+    ``x-xsrf-token`` header is absent and every write fails ('Missing xsrf token')."""
+    if cookie_value(jar, "xsrf"):
+        return
+    url = BASE + "/"
+    hdrs = {"User-Agent": UA, "Accept": "text/html",
+            "X-Requested-With": "XMLHttpRequest"}
+    req = urllib.request.Request(url, headers=hdrs, method="GET")
+    req.add_unredirected_header("Cookie", cookie_header(jar, url))
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            set_cookies = resp.headers.get_all("Set-Cookie") or []
+    except urllib.error.HTTPError as e:
+        set_cookies = e.headers.get_all("Set-Cookie") or []
+    except urllib.error.URLError:
+        return
+    for sc in set_cookies:
+        m = re.match(r"\s*xsrf=([^;]+)", sc)
+        if m:
+            jar.append({"name": "xsrf", "value": m.group(1).strip('"'),
+                        "domain": ".medium.com", "path": "/"})
+            return
+
+
 # ── commands ────────────────────────────────────────────────────────
 
 def md_me(jar):
@@ -336,15 +362,163 @@ def medium_upload_image(jar, post_id, img_bytes, content_type):
     return val["fileId"], val.get("imgWidth"), val.get("imgHeight")
 
 
+# Inline markdown → Medium markups. Groups: 1/2 link, 3 bold, 4 code, 5 italic,
+# 6 bare URL (autolinked).
+_INLINE = re.compile(
+    r"\[([^\]]+)\]\((https?://[^)\s]+)\)"
+    r"|\*\*([^*]+)\*\*"
+    r"|`([^`]+)`"
+    r"|(?<![\w*])\*([^*\n]+)\*(?![\w*])"
+    r"|(https?://[^\s<>()\[\]]+)"
+)
+_TABLE_SEP = re.compile(r"^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$")
+_LIST_ITEM = re.compile(r"^\s*([-*+]|\d+\.)\s+(.*)$")
+# Medium's code column wraps past ~66 monospace chars; wider tables are rendered
+# as per-row records instead of an unreadable wrapped grid.
+_TABLE_MAX_W = 66
+
+
+def _u16(s: str) -> int:
+    """Length in UTF-16 code units — Medium indexes markup offsets like JS."""
+    return len(s.encode("utf-16-le")) // 2
+
+
+def _inline(text: str):
+    """Parse inline markdown → (plain_text, markups). Emits Medium markups for
+    links (type 3), bold (1), italic (2) and inline code (10) so they render as
+    real formatting instead of literal ``**`` / ``[..](..)`` characters. Bold,
+    italic and link labels are parsed recursively so nested markup (e.g. a link
+    inside bold) is preserved as overlapping markups rather than dropped."""
+    plain: list[str] = []
+    markups: list[dict] = []
+    pos = 0
+    off = 0  # running UTF-16 offset into the assembled plain text
+
+    def _nest(inner: str, start: int):
+        sub_plain, sub_mk = _inline(inner)
+        plain.append(sub_plain)
+        for x in sub_mk:
+            markups.append({**x, "start": x["start"] + start, "end": x["end"] + start})
+        return _u16(sub_plain)
+
+    for m in _INLINE.finditer(text):
+        if m.start() > pos:
+            seg = text[pos:m.start()]
+            plain.append(seg)
+            off += _u16(seg)
+        start = off
+        if m.group(1) is not None:            # link
+            off += _nest(m.group(1), start)
+            markups.append({"type": 3, "start": start, "end": off,
+                            "href": m.group(2), "title": "", "rel": "", "anchorType": 0})
+        elif m.group(3) is not None:          # bold
+            off += _nest(m.group(3), start)
+            markups.append({"type": 1, "start": start, "end": off})
+        elif m.group(4) is not None:          # inline code — literal, no recursion
+            inner = m.group(4)
+            plain.append(inner); off += _u16(inner)
+            markups.append({"type": 10, "start": start, "end": off})
+        elif m.group(5) is not None:          # italic
+            off += _nest(m.group(5), start)
+            markups.append({"type": 2, "start": start, "end": off})
+        elif m.group(6) is not None:          # bare URL → autolink
+            url = m.group(6)
+            tail = ""
+            while url and url[-1] in ".,;:!?。，；：！？":
+                tail = url[-1] + tail
+                url = url[:-1]
+            plain.append(url); off += _u16(url)
+            markups.append({"type": 3, "start": start, "end": off,
+                            "href": url, "title": "", "rel": "", "anchorType": 0})
+            if tail:
+                plain.append(tail); off += _u16(tail)
+        pos = m.end()
+    if pos < len(text):
+        plain.append(text[pos:])
+    return "".join(plain), markups
+
+
+def _is_table(lines):
+    return (len(lines) >= 2 and "|" in lines[0]
+            and "-" in lines[1] and _TABLE_SEP.match(lines[1]) is not None)
+
+
+def _split_row(line):
+    line = line.strip()
+    if line.startswith("|"):
+        line = line[1:]
+    if line.endswith("|"):
+        line = line[:-1]
+    return [c.strip().replace("\\|", "|") for c in re.split(r"(?<!\\)\|", line)]
+
+
+def _render_table(lines):
+    """Markdown table → aligned monospace text (rendered as a PRE code block, the
+    closest faithful representation since Medium's editor has no table element)."""
+    rows = [_split_row(ln) for i, ln in enumerate(lines) if i != 1]
+    ncol = max(len(r) for r in rows)
+    rows = [r + [""] * (ncol - len(r)) for r in rows]
+    widths = [max(len(r[c]) for r in rows) for c in range(ncol)]
+    def fmt(r):
+        return " | ".join(r[c].ljust(widths[c]) for c in range(ncol)).rstrip()
+    sep = "-+-".join("-" * widths[c] for c in range(ncol))
+    body = [fmt(rows[0]), sep] + [fmt(r) for r in rows[1:]]
+    return "\n".join(body)
+
+
+def _table_paras(lines):
+    """Markdown table → Medium paragraphs. A table that fits Medium's ~66-char
+    code column keeps the aligned monospace grid; a wider one (long notes / full
+    URLs would wrap into an unreadable mess) becomes a per-row record — the first
+    cell as a bold lead-in, the remaining columns as ``header: value`` bullets.
+    Both paths stay inside the stdlib-only, no-image contract."""
+    grid = _render_table(lines)
+    if max((len(ln) for ln in grid.split("\n")), default=0) <= _TABLE_MAX_W:
+        return [{"type": 8, "text": grid}]
+    rows = [_split_row(ln) for i, ln in enumerate(lines) if i != 1]
+    header = rows[0] if rows else []
+    out = []
+    for r in rows[1:]:
+        cells = [c.strip() for c in r]
+        if not any(cells):
+            continue
+        if cells[0]:                               # lead cell → whole-cell bold
+            txt, mk = _inline(cells[0])
+            mk.append({"type": 1, "start": 0, "end": _u16(txt)})
+            out.append({"type": 1, "text": txt, "markups": mk})
+        for i in range(1, len(cells)):
+            if not cells[i]:
+                continue
+            vtxt, vmk = _inline(cells[i])
+            label = header[i].strip() if i < len(header) else ""
+            if label:                              # "label: value", label bolded
+                prefix = f"{label}: "
+                shift = _u16(prefix)
+                markups = [{"type": 1, "start": 0, "end": _u16(f"{label}:")}]
+                markups += [{**x, "start": x["start"] + shift, "end": x["end"] + shift}
+                            for x in vmk]
+                out.append({"type": 9, "text": prefix + vtxt, "markups": markups})
+            else:
+                out.append({"type": 9, "text": vtxt, "markups": vmk})
+    return out or [{"type": 8, "text": grid}]
+
+
+def _is_list(lines):
+    ls = [ln for ln in lines if ln.strip()]
+    return bool(ls) and all(_LIST_ITEM.match(ln) for ln in ls)
+
+
 def _build_deltas(jar, post_id, title, content, rehost=True):
-    """Markdown → Medium paragraph deltas (image-aware). A standalone
-    ``![alt](url)`` block is uploaded to Medium and emitted as an image
-    paragraph (type 4); on upload failure it degrades to a link paragraph."""
+    """Markdown → Medium paragraph deltas. Handles standalone ``![alt](url)``
+    images (uploaded → type-4 image paragraph), headings, quotes, fenced code,
+    tables (narrow → aligned code block; wide → per-row records), bullet/ordered
+    lists, and inline markups (links/bold/italic/code) on ordinary text."""
     paras = [{"type": 3, "text": title}]
     for block in re.split(r"\n\s*\n", content.strip()):
         b = block.strip("\n")
         if not b.strip():
             continue
+        lines = b.split("\n")
         first = b.lstrip()
         m = _MD_IMG.fullmatch(first)
         if m:
@@ -367,19 +541,34 @@ def _build_deltas(jar, post_id, title, content, rehost=True):
             continue
         if first.startswith("```"):
             paras.append({"type": 8, "text": re.sub(r"^```[^\n]*\n?|\n?```$", "", b)})
+        elif _is_table(lines):
+            paras.extend(_table_paras(lines))
+        elif _is_list(lines):
+            for ln in lines:
+                lm = _LIST_ITEM.match(ln)
+                if not lm:
+                    continue
+                ptype = 10 if lm.group(1).endswith(".") else 9
+                txt, mk = _inline(lm.group(2).strip())
+                paras.append({"type": ptype, "text": txt, "markups": mk})
         elif first.startswith("# "):
-            paras.append({"type": 12, "text": first[2:].strip()})
+            txt, mk = _inline(first[2:].strip())
+            paras.append({"type": 2, "text": txt, "markups": mk})
         elif first.startswith("## "):
-            paras.append({"type": 2, "text": first[3:].strip()})
+            txt, mk = _inline(first[3:].strip())
+            paras.append({"type": 2, "text": txt, "markups": mk})
         elif first.startswith("### "):
-            paras.append({"type": 3, "text": first[4:].strip()})
+            txt, mk = _inline(first[4:].strip())
+            paras.append({"type": 3, "text": txt, "markups": mk})
         elif first.startswith("> "):
-            paras.append({"type": 6, "text": first[2:].strip()})
+            txt, mk = _inline(first[2:].strip())
+            paras.append({"type": 6, "text": txt, "markups": mk})
         else:
-            paras.append({"type": 1, "text": b.replace("\n", " ").strip()})
+            txt, mk = _inline(b.replace("\n", " ").strip())
+            paras.append({"type": 1, "text": txt, "markups": mk})
     out_deltas = []
     for i, p in enumerate(paras):
-        para = {"type": p["type"], "text": p["text"], "markups": []}
+        para = {"type": p["type"], "text": p["text"], "markups": p.get("markups") or []}
         if "layout" in p:
             para["layout"] = p["layout"]
         if "metadata" in p:
@@ -413,6 +602,12 @@ def cmd_publish(jar, args):
         })
         return
 
+    # Captured jars often lack an xsrf cookie; mint one so writes don't 400.
+    prime_xsrf(jar)
+    if not cookie_value(jar, "xsrf"):
+        die("could not obtain an xsrf token from Medium (cookie may be expired) — "
+            "reconnect at https://auth.acedata.cloud/user/connections.")
+
     # 1. create empty draft
     d = api("POST", f"{BASE}/new-story", jar, body={})
     payload = d.get("payload") or {}

package/skills/wecom/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: wecom
+description: Read your WeCom (企业微信 / WeCom / Work Weixin) contacts, send app & group messages, create and read WeDoc docs/smart sheets, and manage schedules (日程) and meetings (会议) via the WeCom server-side API as a self-built app. Use when the user mentions 企业微信, WeCom, 通讯录成员/部门, 应用消息, 群机器人/应用群聊, 企业微信文档/智能表格, 企业微信日程 or 会议, or a qyapi.weixin.qq.com call.
+when_to_use: |
+  Trigger when the user wants to operate their WeCom (企业微信) via a
+  self-built app: list departments / members, look up a member's userid,
+  send an app message or push to an app group chat, create or read a
+  WeDoc document / smart sheet, or create / list / cancel a schedule
+  (日程) or meeting (会议).
+connections: [wecom]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+We drive the [WeCom server-side API](https://developer.work.weixin.qq.com/document/path/90664)
+(`https://qyapi.weixin.qq.com`) with `curl + jq` as a **self-built app (自建应用)**.
+
+> **Setup:** see [WeCom authentication](../_shared/wecom.md) for how to create the self-built app,
+> collect **CorpID / Secret / AgentId**, and grant it the contacts / docs / calendar / meeting
+> permissions. The skill reads `WECOM_CORP_ID`, `WECOM_CORP_SECRET` and `WECOM_AGENT_ID` from the
+> environment; on AceDataCloud they are injected automatically by the 企业微信 connector.
+
+WeCom uses a two-step token flow (identical in shape to the WeChat MP API):
+
+1. Exchange `CorpID + Secret` for an `access_token` (TTL 7200s).
+2. Pass that `access_token` as a **query string parameter** on every other call.
+
+**Never log or echo `$WECOM_CORP_SECRET`** — treat it like a password.
+
+Responses are JSON returned with **HTTP 200**; `errcode == 0` means success. On any non-zero
+`errcode`, show the original `errmsg` to the user verbatim (see the error table in
+[the setup doc](../_shared/wecom.md#response-shape--error-handling)).
+
+## Recipes
+
+### Step 0 — get an access_token (do this first, cache the result)
+
+Every recipe below assumes `$AT` holds a valid token from this step.
+
+```sh
+# Fail loudly if credentials are missing/blank. WECOM_AGENT_ID must be a plain
+# integer because message/meeting recipes pass it to jq via --argjson (numeric JSON).
+: "${WECOM_CORP_ID:?WECOM_CORP_ID not set}" "${WECOM_CORP_SECRET:?WECOM_CORP_SECRET not set}"
+case "${WECOM_AGENT_ID:?WECOM_AGENT_ID not set}" in *[!0-9]*|"") echo "WECOM_AGENT_ID must be an integer" >&2; exit 1;; esac
+
+# Cache to $TMPDIR so subsequent calls in the same session reuse it (WeCom
+# rate-limits gettoken). Refresh 5 minutes early to avoid edge-of-window failures.
+TOKEN_CACHE="${TMPDIR:-/tmp}/wecom-token-${WECOM_CORP_ID}-${WECOM_AGENT_ID}.json"
+NOW=$(date +%s)
+if [ -f "$TOKEN_CACHE" ] && [ "$(jq -r '.exp_at // 0' "$TOKEN_CACHE")" -gt "$((NOW + 300))" ]; then
+  AT=$(jq -r '.access_token' "$TOKEN_CACHE")
+else
+  RESP=$(curl -sS "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=${WECOM_CORP_ID}&corpsecret=${WECOM_CORP_SECRET}")
+  AT=$(echo "$RESP" | jq -r 'if .errcode == 0 then .access_token else empty end')
+  if [ -z "$AT" ]; then
+    echo "Failed to fetch access_token: $RESP" >&2
+    exit 1
+  fi
+  EXPIRES=$(echo "$RESP" | jq -r '.expires_in // 7200')
+  echo "$RESP" | jq --argjson now "$NOW" --argjson ttl "$EXPIRES" \
+    '{access_token, exp_at: ($now + $ttl)}' > "$TOKEN_CACHE"
+  chmod 600 "$TOKEN_CACHE"
+fi
+```
+
+A tiny helper keeps the recipes short — GET with the token appended, erroring on non-zero `errcode`:
+
+```sh
+wc_get()  { curl -sS "https://qyapi.weixin.qq.com/cgi-bin/$1&access_token=${AT}" \
+              | jq 'if .errcode == 0 then . else error("WeCom \(.errcode): \(.errmsg)") end'; }
+wc_post() { curl -sS -X POST "https://qyapi.weixin.qq.com/cgi-bin/$1?access_token=${AT}" \
+              -H 'Content-Type: application/json' -d "$2" \
+              | jq 'if .errcode == 0 then . else error("WeCom \(.errcode): \(.errmsg)") end'; }
+```
+
+### 通讯录 Contacts (read)
+
+> Reading real names / mobiles requires the app to have **通讯录读取** privilege; otherwise names
+> come back masked. Members outside the app's 可见范围 return `errcode 60011` / `81013`.
+
+List the department tree (root department id is `1`):
+
+```sh
+wc_get "department/list?id=1" | jq '[.department[] | {id, name, parentid}]'
+```
+
+**Preferred enumeration — `user/list_id` (cursor).** This is the robust way to list members:
+it works for a self-built app with only its own Secret. `user/simplelist` / `user/list` still
+work *within the app's 可见范围*, but WeCom has been tightening those (the 2022‑08‑15 change blocks
+newly‑added 通讯录同步 IPs from calling them), so lead with `user/list_id` and fall back to
+`simplelist` only if you need names in one shot.
+
+```sh
+wc_post "user/list_id" '{"cursor":"","limit":10000}' \
+  | jq '{next_cursor, userids: [.dept_user[] | .userid] | unique}'
+```
+
+Get one member's full profile — this is how you resolve a **name → userid** for messaging:
+
+```sh
+wc_get "user/get?userid=USERID" \
+  | jq '{userid, name, department, position, mobile, email, status}'
+```
+
+List members of a department in one call (convenience; needs 通讯录 view on that department —
+if it returns `60011`, use `user/list_id` + `user/get` above instead):
+
+```sh
+wc_get "user/simplelist?department_id=1&fetch_child=1" \
+  | jq '[.userlist[] | {userid, name, department}]'
+```
+
+Search by name — robust path (enumerate ids, then read each profile and filter):
+
+```sh
+for uid in $(wc_post "user/list_id" '{"cursor":"","limit":10000}' | jq -r '.dept_user[].userid' | sort -u); do
+  wc_get "user/get?userid=${uid}" | jq -c '{userid, name}'
+done | jq -s --arg q "张三" '[.[] | select(.name | contains($q))]'
+```
+
+> Shortcut when `simplelist` is available to the app: `wc_get "user/simplelist?department_id=1&fetch_child=1" | jq --arg q "张三" '[.userlist[] | select(.name | contains($q)) | {userid, name}]'`.
+
+### 应用消息 App messages (send) — GATED
+
+`message/send` pushes a notification from your app to members. `agentid` is required and comes from
+`$WECOM_AGENT_ID`. `touser` is a `|`-joined list of **userid**s (use `@all` for everyone in scope);
+`toparty` / `totag` target departments / tags.
+
+> Sending fans out to real people. **Always show the exact recipients + content and get explicit
+> user confirmation before running `message/send` / `appchat/send`**, even if the instruction says
+> "just send it".
+
+Send a text message to one or more members:
+
+```sh
+wc_post "message/send" "$(jq -nc --arg to "USERID1|USERID2" --argjson agent "${WECOM_AGENT_ID}" \
+  --arg content "构建已通过，请查看。" \
+  '{touser:$to, msgtype:"text", agentid:$agent, text:{content:$content}, safe:0}')" \
+  | jq '{msgid, invaliduser}'
+```
+
+Send a Markdown card (richer formatting, members only):
+
+```sh
+wc_post "message/send" "$(jq -nc --arg to "@all" --argjson agent "${WECOM_AGENT_ID}" \
+  --arg md "**发布通知**\n>版本：v1.2.0\n>状态：<font color=\"info\">成功</font>" \
+  '{touser:$to, msgtype:"markdown", agentid:$agent, markdown:{content:$md}}')" \
+  | jq '{msgid}'
+```
+
+Send a clickable text-card:
+
+```sh
+wc_post "message/send" "$(jq -nc --arg to "USERID1" --argjson agent "${WECOM_AGENT_ID}" \
+  '{touser:$to, msgtype:"textcard", agentid:$agent,
+    textcard:{title:"周报已生成", description:"点击查看本周汇总", url:"https://example.com/report", btntxt:"详情"}}')" \
+  | jq '{msgid}'
+```
+
+### 应用群聊 App group chat
+
+Create a group the app owns, then push messages into it. `chatid` is a custom id you choose (reuse it later).
+
+```sh
+# Create (owner + members are userids). Omit chatid to let WeCom assign one.
+wc_post "appchat/create" '{"name":"项目组","owner":"USERID1","userlist":["USERID1","USERID2","USERID3"],"chatid":"proj_alpha"}' \
+  | jq '{chatid}'
+
+# Send into it (same GATED confirmation rule as app messages).
+wc_post "appchat/send" '{"chatid":"proj_alpha","msgtype":"text","text":{"content":"今晚 8 点线上同步。"}}' \
+  | jq '{errcode, errmsg}'
+
+# Inspect a group the app created.
+wc_get "appchat/get?chatid=proj_alpha" | jq '.chat_info | {name, owner, userlist}'
+```
+
+### 企业微信文档 WeDoc (docs & smart sheets)
+
+Requires the app's **文档 (WeDoc)** permission. `doc_type`: `3` = 文档 (document), `4` = 表格 (spreadsheet),
+`10` = 智能表格 (smart sheet).
+
+Create a document and get its edit URL:
+
+```sh
+wc_post "wedoc/create_doc" "$(jq -nc --arg name "项目周报 2026-07" \
+  '{doc_type:3, doc_name:$name}')" \
+  | jq '{docid, url}'
+```
+
+Get a shareable link for an existing doc:
+
+```sh
+wc_post "wedoc/doc_share" '{"docid":"DOCID"}' | jq '{share_url: .share_url}'
+```
+
+Read a document's structured content. WeCom returns a `document` object (keyed by `document_id`,
+not `doc_id`) whose body is a tree of typed blocks, **not** Markdown — inspect the real shape before
+relying on inner field names:
+
+```sh
+wc_post "wedoc/document/get" '{"docid":"DOCID"}' \
+  | jq '{document_id: .document.document_id, top_level_keys: (.document | keys)}'
+```
+
+> Smart-sheet (智能表格) sub-tables, fields and records use the `wedoc/smartsheet/*` endpoints
+> (`get_sheet`, `get_fields`, `get_records`, `add_records`, …) — same `wc_post` pattern, keyed by
+> `docid` + `sheet_id`. Reach for them when the user asks to read/write rows of a 智能表格.
+
+### 日程 Schedule (日程)
+
+Requires the app's **日历/日程** permission. Times are **epoch seconds**; convert with GNU `date`:
+
+```sh
+START=$(date -d "2026-07-10 15:00" +%s); END=$(date -d "2026-07-10 16:00" +%s)
+```
+
+Create a schedule (organizer + attendees are userids):
+
+```sh
+wc_post "oa/schedule/add" "$(jq -nc --arg org "USERID1" --argjson s "$START" --argjson e "$END" \
+  '{schedule:{organizer:$org, start_time:$s, end_time:$e, summary:"项目评审",
+    description:"评审 v1.2 需求", location:"会议室 A",
+    attendees:[{userid:"USERID2"},{userid:"USERID3"}],
+    reminders:{is_remind:1, remind_before_event_secs:900}}}')" \
+  | jq '{schedule_id}'
+```
+
+Read schedules by id, and cancel one:
+
+```sh
+wc_post "oa/schedule/get" '{"schedule_id_list":["SCHEDULE_ID"]}' \
+  | jq '[.schedule_list[] | {schedule_id, summary, start_time, end_time, organizer}]'
+
+wc_post "oa/schedule/del" '{"schedule_id":"SCHEDULE_ID"}' | jq '{errcode, errmsg}'
+```
+
+> To *list* a member's upcoming schedules you need their calendar id (`cal_id`) and
+> `oa/schedule/get_by_calendar` — create/query calendars via the `oa/calendar/*` endpoints first.
+
+### 会议 Meeting (会议)
+
+Requires the app's **会议** permission. `meeting_start` is epoch seconds, `meeting_duration` is seconds.
+
+Create a scheduled meeting:
+
+```sh
+wc_post "meeting/create" "$(jq -nc --arg admin "USERID1" --argjson start "$(date -d '2026-07-11 10:00' +%s)" \
+  '{admin_userid:$admin, title:"周例会", meeting_start:$start, meeting_duration:3600,
+    description:"同步本周进展", invitees:{userid:["USERID2","USERID3"]}}')" \
+  | jq '{meetingid}'
+```
+
+List a member's meetings, read details, and cancel (`get_user_meetingid` is a **POST** with a
+cursor body, mirroring WeCom's other `get_user_*_id` list endpoints):
+
+```sh
+wc_post "meeting/get_user_meetingid" '{"userid":"USERID1","cursor":"","limit":100}' \
+  | jq '{meetingid_list, next_cursor}'
+
+wc_post "meeting/get_info" '{"meetingid":"MEETINGID"}' \
+  | jq '.meeting_info | {title, meeting_start, meeting_duration, state}'
+
+wc_post "meeting/cancel" '{"meetingid":"MEETINGID"}' | jq '{errcode, errmsg}'
+```
+
+## Safety rules
+
+- **Never print `$WECOM_CORP_SECRET`.** It is equivalent to full app access.
+- **Confirm before anything outward-facing** — `message/send`, `appchat/send`, `oa/schedule/add`
+  and `meeting/create` all notify real colleagues. Show the exact recipients / attendees and the
+  content, get explicit approval, *then* run the call. Never infer consent from vague wording.
+- Messaging / schedules / meetings act on **userids**, not display names — resolve a name to a
+  userid with the contact recipes first, and confirm the person if the name is ambiguous.
+- On `errcode 48002` (API forbidden) or `60011` / `301002` (no privilege), the app is missing a
+  permission or the target is outside its 可见范围 — tell the user which capability to grant rather
+  than retrying blindly.
+
+## Not supported here
+
+- **Reading inbound chat history** (会话内容存档 / msgaudit) — a separate paid capability needing a
+  dedicated Secret, an RSA key and the native WeCom Finance SDK; it can't run in this sandbox. The
+  skill *sends* messages but can't *read* members' private conversations.
+- **A generic todo (待办) CRUD** — WeCom's open API exposes none for self-built apps; use
+  **schedules (日程)** for time-bound reminders instead.