@acedatacloud/skills 2026.720.3 → 2026.721.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acedatacloud/skills",
-  "version": "2026.720.3",
+  "version": "2026.721.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/cnblogs/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: cnblogs
+description: Publish, update and read CNBlogs (博客园) posts with a personal access token through the API used by the official vscode-cnb client. Use when the user wants to publish Markdown to 博客园, save a CNBlogs draft, edit or delete a post, or list posts or categories.
+when_to_use: |
+  Trigger for 博客园 / CNBlogs blog management: verify the connected account,
+  list categories or recent posts, create a Markdown draft, publish or update
+  a post, or delete a post. Public writes and destructive actions require
+  explicit confirmation.
+connections: [cnblogs]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Use the bundled standard-library CLI. The connector injects the user's 博客园
+personal access token as `$CNBLOGS_TOKEN`. Never print it. The CLI follows the
+current official `cnblogs/vscode-cnb` client contract at
+`https://write.cnblogs.com/api` (`Authorization: Bearer` plus
+`Authorization-Type: pat`).
+
+```bash
+python3 "$SKILL_DIR/scripts/cnblogs.py" whoami
+```
+
+If authentication fails, ask the user to create a PAT at
+`https://account.cnblogs.com/settings/tokens` and reconnect. Do not ask for
+their account password or Cookie.
+
+## Read the blog
+
+```bash
+# Verify the token and inspect the account's post template.
+python3 "$SKILL_DIR/scripts/cnblogs.py" whoami
+
+# Categories and recent posts.
+python3 "$SKILL_DIR/scripts/cnblogs.py" categories
+python3 "$SKILL_DIR/scripts/cnblogs.py" posts --limit 20
+python3 "$SKILL_DIR/scripts/cnblogs.py" post POST_ID
+```
+
+## Create a draft or publish
+
+Prepare the complete Markdown in a file. Category values are numeric IDs from
+the `categories` command; tags are names.
+
+```bash
+# First call is always a dry run and does not load credentials or call the API.
+python3 "$SKILL_DIR/scripts/cnblogs.py" create \
+  --title "标题" --content-file /tmp/article.md \
+  --category-ids "123,456" --tags "agent,api"
+
+# Save as a private draft after the user confirms.
+python3 "$SKILL_DIR/scripts/cnblogs.py" create \
+  --title "标题" --content-file /tmp/article.md \
+  --category-ids "123,456" --tags "agent,api" --confirm
+
+# Public publishing additionally requires --publish.
+python3 "$SKILL_DIR/scripts/cnblogs.py" create \
+  --title "标题" --content-file /tmp/article.md \
+  --category-ids "123,456" --tags "agent,api" --publish --confirm
+```
+
+`--confirm` is valid only as the final argument. Always show the title,
+categories, tags, visibility and full content to the user before a public
+publish. Default to a draft unless the user explicitly requests publication.
+
+## Update and delete
+
+Updating requires an explicit visibility choice so an existing post is not
+silently unpublished. All commands below dry-run without trailing `--confirm`.
+
+```bash
+python3 "$SKILL_DIR/scripts/cnblogs.py" update POST_ID \
+  --title "新标题" --content-file /tmp/article.md --publish --confirm
+
+python3 "$SKILL_DIR/scripts/cnblogs.py" update POST_ID \
+  --title "新标题" --content-file /tmp/article.md --draft --confirm
+
+python3 "$SKILL_DIR/scripts/cnblogs.py" delete POST_ID --confirm
+```
+
+Use the real returned `post_id`, URL, or media URL. Do not retry a timed-out
+write automatically because its outcome may be unknown; list recent posts or
+inspect the post first.
+
+## Record the output
+
+After a confirmed public publish returns a real URL, call `publish_artifact`
+once with `kind="article"`, `channel="cnblogs"`, the title, returned URL, and
+`status="delivered"`. Do not record drafts or failed/unknown writes.

package/skills/cnblogs/scripts/cnblogs.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Read and write CNBlogs posts through its official-client JSON API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import socket
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+API_BASE = "https://write.cnblogs.com/api"
+GATED_COMMANDS = {"create", "update", "delete"}
+MAX_CONTENT_BYTES = 10 * 1024 * 1024
+MAX_POSTS = 100
+
+
+def output(value) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, default=str))
+
+
+def die(message: str, code: int = 1) -> None:
+    output({"error": message})
+    raise SystemExit(code)
+
+
+def split_confirmation(argv: list[str]) -> tuple[list[str], bool]:
+    confirmed = bool(argv) and argv[-1] == "--confirm"
+    return (argv[:-1] if confirmed else list(argv), confirmed)
+
+
+class NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class CNBlogsClient:
+    def __init__(self, token: str, opener=None) -> None:
+        self._token = token
+        self._opener = opener or urllib.request.build_opener(NoRedirectHandler())
+
+    @classmethod
+    def from_environment(cls):
+        token = os.environ.get("CNBLOGS_TOKEN", "").strip()
+        if not token:
+            die(
+                "CNBLOGS_TOKEN is not set. Reconnect 博客园 at "
+                "https://auth.acedata.cloud/user/connections."
+            )
+        return cls(token)
+
+    def request(self, method: str, path: str, *, body=None, write: bool = False, expect_json: bool = True):
+        encoded = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
+        request = urllib.request.Request(
+            f"{API_BASE}{path}",
+            data=encoded,
+            method=method,
+            headers={
+                "Accept": "application/json",
+                "Authorization": f"Bearer {self._token}",
+                "Authorization-Type": "pat",
+                "Content-Type": "application/json",
+                "User-Agent": "AceDataCloud-CNBlogs-Skill/1.0",
+            },
+        )
+        try:
+            with self._opener.open(request, timeout=30) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as error:
+            if error.code in {301, 302, 303, 307, 308}:
+                die(f"CNBlogs API redirected {method} {path}; credentials were not forwarded.")
+            suffix = " Reconnect with a valid PAT." if error.code in {401, 403} else ""
+            die(f"CNBlogs API HTTP {error.code} for {method} {path}.{suffix}")
+        except (urllib.error.URLError, OSError, socket.timeout):
+            if write:
+                die(
+                    f"CNBlogs write {method} {path} did not return a result; outcome is unknown. "
+                    "Inspect the post list before retrying."
+                )
+            die(f"Network error while calling CNBlogs {method} {path}.")
+        if not expect_json or not raw:
+            return None
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            die(f"CNBlogs returned invalid JSON for {method} {path}.")
+
+    def template(self) -> dict:
+        value = self.request("GET", "/posts/-1")
+        post = value.get("blogPost") if isinstance(value, dict) else None
+        if not isinstance(post, dict):
+            die("CNBlogs returned malformed post template data.")
+        return post
+
+    def categories(self) -> list[dict]:
+        value = self.request("GET", "/v2/blog-category-types/1/categories")
+        if not isinstance(value, list):
+            die("CNBlogs returned malformed category data.")
+        return value
+
+    def posts(self, limit: int) -> list[dict]:
+        query = urllib.parse.urlencode({"t": 1, "p": 1, "s": limit})
+        value = self.request("GET", f"/posts/list?{query}")
+        posts = value.get("postList") if isinstance(value, dict) else None
+        if not isinstance(posts, list):
+            die("CNBlogs returned malformed post-list data.")
+        return posts
+
+    def post(self, post_id: int) -> dict:
+        value = self.request("GET", f"/posts/{post_id}")
+        post = value.get("blogPost") if isinstance(value, dict) else None
+        if not isinstance(post, dict):
+            die("CNBlogs returned malformed post data.")
+        return post
+
+    def save(self, post: dict) -> dict:
+        value = self.request("POST", "/posts", body=post, write=True)
+        if not isinstance(value, dict) or not isinstance(value.get("id"), int) or value["id"] <= 0:
+            die("CNBlogs did not return a valid saved post.")
+        return value
+
+    def delete(self, post_id: int) -> None:
+        self.request("DELETE", f"/posts/{post_id}", write=True, expect_json=False)
+
+
+def read_content(args) -> str:
+    if args.content_file:
+        path = pathlib.Path(args.content_file)
+        try:
+            if path.stat().st_size > MAX_CONTENT_BYTES:
+                die("Content file exceeds the 10 MiB safety limit.")
+            return path.read_text(encoding="utf-8")
+        except OSError as error:
+            die(f"Cannot read --content-file: {error}")
+    if args.content is not None:
+        if len(args.content.encode("utf-8")) > MAX_CONTENT_BYTES:
+            die("Content exceeds the 10 MiB safety limit.")
+        return args.content
+    die("Provide --content-file <path.md> or --content <markdown>.")
+
+
+def csv_strings(raw: str | None) -> list[str]:
+    return [item.strip() for item in (raw or "").split(",") if item.strip()]
+
+
+def csv_ids(raw: str | None) -> list[int]:
+    try:
+        return [int(item) for item in csv_strings(raw)]
+    except ValueError:
+        die("--category-ids must be a comma-separated list of integers.")
+
+
+def apply_post_fields(post: dict, args, content: str) -> dict:
+    post.update(
+        {
+            "title": args.title,
+            "postBody": content,
+            "isMarkdown": True,
+            "isPublished": args.publish,
+            "isDraft": not args.publish,
+        }
+    )
+    if args.category_ids is not None:
+        post["categoryIds"] = csv_ids(args.category_ids)
+    if args.tags is not None:
+        post["tags"] = csv_strings(args.tags)
+    return post
+
+
+def format_post(post: dict) -> dict:
+    return {
+        "post_id": post.get("id"),
+        "title": post.get("title"),
+        "url": post.get("url"),
+        "published": post.get("isPublished"),
+        "draft": post.get("isDraft"),
+        "category_ids": post.get("categoryIds") or [],
+        "tags": post.get("tags") or [],
+        "created_at": post.get("datePublished"),
+        "updated_at": post.get("dateUpdated"),
+    }
+
+
+def positive_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("must be a positive integer") from error
+    if parsed <= 0:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return parsed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="CNBlogs PAT API CLI")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("whoami")
+    sub.add_parser("categories")
+    posts = sub.add_parser("posts")
+    posts.add_argument("--limit", type=int, default=20)
+    one = sub.add_parser("post")
+    one.add_argument("post_id", type=positive_int)
+
+    for command in ("create", "update"):
+        write = sub.add_parser(command)
+        if command == "update":
+            write.add_argument("post_id", type=positive_int)
+        write.add_argument("--title", required=True)
+        write.add_argument("--content")
+        write.add_argument("--content-file")
+        write.add_argument("--category-ids")
+        write.add_argument("--tags")
+        visibility = write.add_mutually_exclusive_group(required=command == "update")
+        visibility.add_argument("--publish", action="store_true")
+        if command == "update":
+            visibility.add_argument("--draft", action="store_true")
+
+    delete = sub.add_parser("delete")
+    delete.add_argument("post_id", type=positive_int)
+    return parser
+
+
+def dry_run(args, content: str | None = None) -> None:
+    value = {"dry_run": True, "command": args.command, "platform": "cnblogs"}
+    if args.command in {"create", "update"}:
+        value.update(
+            {
+                "post_id": getattr(args, "post_id", None),
+                "title": args.title,
+                "visibility": "published" if args.publish else "draft",
+                "category_ids": csv_ids(args.category_ids) if args.category_ids is not None else None,
+                "tags": csv_strings(args.tags) if args.tags is not None else None,
+                "content_characters": len(content or ""),
+            }
+        )
+    else:
+        value["post_id"] = args.post_id
+    value["note"] = "Re-run with --confirm as the final argument to write to CNBlogs."
+    output(value)
+
+
+def main(argv: list[str] | None = None) -> None:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    clean_argv, confirmed = split_confirmation(raw)
+    args = build_parser().parse_args(clean_argv)
+    content = read_content(args) if args.command in {"create", "update"} else None
+    if args.command in GATED_COMMANDS and not confirmed:
+        dry_run(args, content)
+        return
+
+    client = CNBlogsClient.from_environment()
+    if args.command == "whoami":
+        template = client.template()
+        output({"author": template.get("author"), "blog_id": template.get("blogId"), "template": format_post(template)})
+    elif args.command == "categories":
+        output({"categories": client.categories()})
+    elif args.command == "posts":
+        if not 1 <= args.limit <= MAX_POSTS:
+            die(f"--limit must be between 1 and {MAX_POSTS}.")
+        output({"posts": [format_post(item) for item in client.posts(args.limit)]})
+    elif args.command == "post":
+        output(format_post(client.post(args.post_id)))
+    elif args.command == "create":
+        result = client.save(apply_post_fields(client.template(), args, content or ""))
+        output(
+            {
+                "ok": True,
+                **format_post(result),
+                "published": args.publish,
+                "draft": not args.publish,
+                "edit_url": f"https://i.cnblogs.com/posts/edit;postId={result['id']}",
+            }
+        )
+    elif args.command == "update":
+        result = client.save(apply_post_fields(client.post(args.post_id), args, content or ""))
+        output({"ok": True, **format_post(result), "published": args.publish, "draft": not args.publish})
+    elif args.command == "delete":
+        client.delete(args.post_id)
+        output({"ok": True, "post_id": args.post_id, "deleted": True})
+
+
+if __name__ == "__main__":
+    main()

package/skills/cnblogs/tests/test_cnblogs.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import os
+import pathlib
+import sys
+import urllib.error
+from contextlib import redirect_stdout
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+SCRIPT = pathlib.Path(__file__).resolve().parents[1] / "scripts" / "cnblogs.py"
+SPEC = importlib.util.spec_from_file_location("cnblogs_skill_script", SCRIPT)
+cnblogs = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+sys.modules[SPEC.name] = cnblogs
+SPEC.loader.exec_module(cnblogs)
+
+
+class FakeResponse:
+    def __init__(self, payload=None, *, raw=None):
+        self.payload = raw if raw is not None else (b"" if payload is None else json.dumps(payload).encode())
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        return False
+
+    def read(self):
+        return self.payload
+
+
+def make_client(*responses):
+    opener = MagicMock()
+    opener.open.side_effect = [FakeResponse(item) for item in responses]
+    return cnblogs.CNBlogsClient("secret-token", opener=opener), opener
+
+
+def test_request_uses_official_pat_contract():
+    client, opener = make_client({"postList": []})
+    assert client.posts(20) == []
+    request = opener.open.call_args.args[0]
+    assert request.full_url == "https://write.cnblogs.com/api/posts/list?t=1&p=1&s=20"
+    assert request.get_header("Authorization") == "Bearer secret-token"
+    assert request.get_header("Authorization-type") == "pat"
+
+
+def test_create_uses_server_template_and_returns_real_api_url():
+    template = {"blogPost": {"id": -1, "blogId": 7, "isAllowComments": True}}
+    saved = {"id": 123, "title": "Hello", "url": "https://www.cnblogs.com/alice/p/123"}
+    client, opener = make_client(template, saved)
+    args = cnblogs.build_parser().parse_args(
+        ["create", "--title", "Hello", "--content", "# Body", "--category-ids", "12,34", "--tags", "api, agent"]
+    )
+
+    result = client.save(cnblogs.apply_post_fields(client.template(), args, "# Body"))
+
+    assert result["url"] == "https://www.cnblogs.com/alice/p/123"
+    request = opener.open.call_args_list[1].args[0]
+    payload = json.loads(request.data)
+    assert payload["blogId"] == 7
+    assert payload["postBody"] == "# Body"
+    assert payload["isMarkdown"] is True
+    assert payload["categoryIds"] == [12, 34]
+    assert payload["tags"] == ["api", "agent"]
+    assert payload["isPublished"] is False
+    assert payload["isDraft"] is True
+
+
+def test_dry_run_never_loads_credentials_or_calls_network():
+    stream = io.StringIO()
+    with patch.dict(os.environ, {}, clear=True), patch.object(
+        cnblogs.CNBlogsClient, "from_environment"
+    ) as from_environment, redirect_stdout(stream):
+        cnblogs.main(["create", "--title", "Hello", "--content", "Body"])
+
+    value = json.loads(stream.getvalue())
+    assert value["dry_run"] is True
+    assert value["visibility"] == "draft"
+    from_environment.assert_not_called()
+
+
+def test_confirm_is_recognized_only_as_final_argument():
+    args, confirmed = cnblogs.split_confirmation(["create", "--content", "--confirm", "--title", "Hello"])
+    assert confirmed is False
+    assert "--confirm" in args
+    args, confirmed = cnblogs.split_confirmation(["delete", "123", "--confirm"])
+    assert confirmed is True
+    assert "--confirm" not in args
+
+
+def test_successful_create_update_and_delete_commands():
+    template = {"blogPost": {"id": -1}}
+    created = {"id": 123, "title": "New", "url": "https://www.cnblogs.com/a/p/123"}
+    client, _ = make_client(template, created)
+    stream = io.StringIO()
+    with patch.object(cnblogs.CNBlogsClient, "from_environment", return_value=client), redirect_stdout(stream):
+        cnblogs.main(["create", "--title", "New", "--content", "Body", "--confirm"])
+    create_output = json.loads(stream.getvalue())
+    assert create_output["url"] == created["url"]
+    assert create_output["published"] is False
+    assert create_output["draft"] is True
+
+    current = {"blogPost": {"id": 123, "title": "Old", "categoryIds": [9], "tags": ["keep"]}}
+    updated = {"id": 123, "title": "Updated", "url": "https://www.cnblogs.com/a/p/123"}
+    client, opener = make_client(current, updated)
+    stream = io.StringIO()
+    with patch.object(cnblogs.CNBlogsClient, "from_environment", return_value=client), redirect_stdout(stream):
+        cnblogs.main(["update", "123", "--title", "Updated", "--content", "Body", "--publish", "--confirm"])
+    update_output = json.loads(stream.getvalue())
+    assert update_output["published"] is True
+    assert update_output["draft"] is False
+    update_payload = json.loads(opener.open.call_args_list[1].args[0].data)
+    assert update_payload["categoryIds"] == [9]
+    assert update_payload["tags"] == ["keep"]
+
+    opener = MagicMock()
+    opener.open.return_value = FakeResponse(raw=b"successful response with no JSON contract")
+    client = cnblogs.CNBlogsClient("secret-token", opener=opener)
+    stream = io.StringIO()
+    with patch.object(cnblogs.CNBlogsClient, "from_environment", return_value=client), redirect_stdout(stream):
+        cnblogs.main(["delete", "123", "--confirm"])
+    assert json.loads(stream.getvalue()) == {"ok": True, "post_id": 123, "deleted": True}
+
+
+@pytest.mark.parametrize(("method", "path"), [("POST", "/posts"), ("DELETE", "/posts/123")])
+def test_write_network_failure_reports_unknown_outcome(method, path):
+    opener = MagicMock()
+    opener.open.side_effect = urllib.error.URLError("secret-token")
+    client = cnblogs.CNBlogsClient("secret-token", opener=opener)
+    stream = io.StringIO()
+    with pytest.raises(SystemExit), redirect_stdout(stream):
+        client.request(method, path, body={} if method == "POST" else None, write=True)
+    assert "outcome is unknown" in stream.getvalue()
+    assert "secret-token" not in stream.getvalue()
+
+
+def test_rejects_malformed_responses_and_oversized_content(tmp_path):
+    client, _ = make_client({"blogPost": None})
+    with pytest.raises(SystemExit), redirect_stdout(io.StringIO()):
+        client.template()
+
+    large = tmp_path / "large.md"
+    large.write_bytes(b"x" * (cnblogs.MAX_CONTENT_BYTES + 1))
+    args = cnblogs.build_parser().parse_args(["create", "--title", "T", "--content-file", str(large)])
+    with pytest.raises(SystemExit), redirect_stdout(io.StringIO()):
+        cnblogs.read_content(args)

package/skills/facebook/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: facebook
+description: Publish text, link or photo posts to your Facebook Page via the Facebook Pages API, and read your Page's recent posts. Use when the user wants to post to their Facebook Page, share a link, publish a photo, or review their own Page posts. Auth uses a Page access token (BYOC). 支持 Facebook 主页文本 / 链接 / 图片发帖。
+when_to_use: |
+  Trigger when the user wants to publish a post (text, link or photo) to their
+  Facebook Page, cross-post an article, or review their own recent Page posts.
+  Publishing posts as their real Page — confirm the message + any link/photo
+  first. This posts to a Facebook Page, not a personal profile (the Graph API
+  cannot post to personal timelines).
+connections: [facebook]
+allowed_tools: [Bash]
+license: Apache-2.0
+metadata:
+  author: acedatacloud
+  version: "1.0"
+---
+
+Call the **Facebook Graph API** (`graph.facebook.com`) with `curl + jq`. The
+connector injects `$FACEBOOK_ACCESS_TOKEN` (a **Page** access token with
+`pages_manage_posts` + `pages_read_engagement`) and optionally
+`$FACEBOOK_PAGE_ID`. Never echo them.
+
+The Graph API publishes only to a **Facebook Page** you manage — it cannot post
+to a personal profile timeline.
+
+### Resolve the Page id
+
+If `$FACEBOOK_PAGE_ID` is set, use it. Otherwise derive it from the token — try
+the **Page-token** path first (`/me` is the Page), then fall back to the
+**user-token** path (`/me/accounts` → first managed Page), so either token type
+the connector accepts resolves cleanly:
+
+```bash
+if [ -n "$FACEBOOK_PAGE_ID" ]; then
+  PAGE="$FACEBOOK_PAGE_ID"
+else
+  # Page access token: /me IS the Page
+  PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me?fields=id,name&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r 'select(.name).id // empty')
+  if [ -z "$PAGE" ]; then
+    # User access token: list the managed Pages, take the first
+    PAGE=$(curl -sS "https://graph.facebook.com/v21.0/me/accounts?access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r '.data[0].id // empty')
+  fi
+fi
+echo "page_id=$PAGE"
+```
+
+Errors are JSON with `error.message` / `error.code` — show them verbatim.
+`401` / `OAuthException` → token expired or missing scope; a null `PAGE` → the
+token isn't a Page token / manages no Page (see Gotchas). Reconnect if needed.
+
+> If the user token path is used, `/me/accounts` also returns a per-Page
+> `access_token` in `.data[0].access_token`. Prefer that Page token for the
+> publish call when the injected token is a user token; a Page's own token is
+> what `pages_manage_posts` actually authorizes.
+
+## Publish a text or link post
+
+**Confirm the message (and link, if any) with the user first.** Post to
+`/{page-id}/feed`:
+
+```bash
+# Text-only post
+curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
+  --data-urlencode "message=One endpoint → posters, cards, mockups. #AI #API" \
+  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
+# → {"id":"<PAGE_ID>_<POST_ID>"}
+
+# Link post — Facebook renders a link preview card from the URL
+curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/feed" \
+  --data-urlencode "message=Read our new guide 👇" \
+  -d "link=https://acedata.cloud/blog/xxxx" \
+  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
+```
+
+## Publish a photo post
+
+Post to `/{page-id}/photos` with a **public image URL** (Facebook server-side
+fetches it); `caption` is the post text:
+
+```bash
+curl -sS -X POST "https://graph.facebook.com/v21.0/$PAGE/photos" \
+  -d "url=https://cdn.acedata.cloud/xxxx.jpg" \
+  --data-urlencode "caption=One endpoint → posters, cards, mockups. #AI #API" \
+  -d "access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
+# → {"id":"<PHOTO_ID>","post_id":"<PAGE_ID>_<POST_ID>"}
+```
+
+To attach **multiple photos** to one post: upload each with `published=false` to
+get its media id, then create the feed post with
+`attached_media[0]={"media_fbid":"<ID1>"}` … for each.
+
+## Get the post permalink
+
+Use the returned `post_id` (or `id`) to fetch the live URL to hand back:
+
+```bash
+curl -sS "https://graph.facebook.com/v21.0/<PAGE_ID>_<POST_ID>?fields=permalink_url&access_token=$FACEBOOK_ACCESS_TOKEN" | jq -r .permalink_url
+```
+
+## Read recent Page posts
+
+```bash
+curl -sS "https://graph.facebook.com/v21.0/$PAGE/posts?fields=id,message,created_time,permalink_url&limit=10&access_token=$FACEBOOK_ACCESS_TOKEN" | jq .
+```
+
+## Gotchas
+
+- **Pages only, not profiles** — the Graph API cannot publish to a personal
+  timeline. If the user asks to post to their profile, explain this limitation.
+- **Page token, not user token** — publishing needs a Page access token with
+  `pages_manage_posts`. If you only have a user token, resolve the Page token via
+  `/me/accounts` (see above). A `(#200)` permissions error means the token lacks
+  `pages_manage_posts` or the user isn't an admin of the Page.
+- **Photo URL must be public** on a server Facebook can reach; local files won't
+  work. Host on cdn.acedata.cloud first.
+- **Page Publishing Authorization (PPA):** some Pages must complete PPA before API
+  publishing works — surface the API error verbatim if it mentions PPA.
+- **Token expiry:** a Page token derived from a short-lived user token expires
+  fast. If posting 401s soon after connecting, the user needs a long-lived Page
+  token — surface the `OAuthException` verbatim and suggest reconnecting.
+- API version: keep the `vXX.0` path current if you hit a version/deprecation error.
+
+## Record the output
+
+After you successfully publish and obtain the live permalink, call the built-in
+`publish_artifact` tool ONCE so the user can track it in **My Outputs**:
+
+```
+publish_artifact(kind="post", channel="facebook", title="<title>", url="<the REAL permalink>", status="delivered")
+```
+
+Use the real returned URL — never fabricate one. Call it once per published item,
+only after delivery is confirmed; skip it (or use `status="failed"`) if publishing failed.
+See `_shared/artifacts.md`.