@acedatacloud/skills 2026.702.0 → 2026.703.0

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.0",
   "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/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.