@acedatacloud/skills 2026.719.0 → 2026.719.2

package/package.json

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

@@ -70,6 +70,8 @@ The helper is deterministic and has no network or browser access. Pass JSON thro
 - `validate-publish`: validate and normalize a publish preview.
 - `normalize-filters`: validate and normalize search filters.
 - `parse-feed-snapshot`: convert a `www.xiaohongshu.com` semantic snapshot into bounded note cards.
+- `parse-note-snapshot --note-url <url>`: normalize one visible note detail snapshot.
+- `parse-profile-snapshot --profile-url <url>`: normalize one visible profile snapshot.
 
 ## Completion rules
 

package/skills/xiaohongshu/references/browse.md

@@ -28,10 +28,14 @@ Read the attached home/recommendation page. Scroll in bounded steps and read aft
 
 Open a note from its fresh result ref or same-origin canonical URL. Read visible text, media labels, author, engagement, and the first visible comment batch. For more comments/replies, expand and scroll in bounded batches, reading after every transition and stopping at the requested limit. This is not a guaranteed full-comment export.
 
+Pass the final semantic snapshot to `parse-note-snapshot --note-url <canonical-url>`. Preserve missing, ambiguous, and truncated states instead of filling absent fields. Only nodes with an explicit `comment` role are returned as structured comments; generic list items are never assumed to be comments.
+
 ## Profile
 
 Open the fresh author link from a result/detail page. Return visible profile text, followers/following/engagement totals, and bounded recent notes. Do not expose unrelated private account data.
 
+Pass the final semantic snapshot to `parse-profile-snapshot --profile-url <canonical-url>` before reporting structured profile data. `visible_metrics` contains explicitly labeled profile metrics. Preserve `visible_counts` separately as unlabeled page counters; never reinterpret them as followers, following, likes, or favorites.
+
 ## Content planning
 
 Search multiple user-approved keywords, compare recent and visibly high-engagement notes, inspect representative details/comments, and synthesize themes, title patterns, formats, audience questions, and tag opportunities. This workflow stays read-only unless the user separately requests publishing.

package/skills/xiaohongshu/scripts/xhs_contract.py

@@ -8,7 +8,7 @@ import json
 import re
 import sys
 from datetime import datetime, timedelta, timezone
-from typing import Match, Optional, Pattern
+from typing import Dict, List, Match, Optional, Pattern, Set
 from urllib.parse import urlparse
 
 
@@ -25,6 +25,9 @@ MAX_MEDIA = 20
 NOTE_PATH = re.compile(r"^/explore/([A-Za-z0-9]+)$")
 PROFILE_PATH = re.compile(r"^/user/profile/([A-Za-z0-9]+)$")
 TITLE_UNIT = re.compile(r"[\u3400-\u9fff]|[A-Za-z0-9]+")
+COUNT_VALUE = re.compile(r"^(\d+(?:\.\d+)?)([万千]?)$")
+PROFILE_METRIC = re.compile(r"^(关注|粉丝|获赞与收藏|获赞|收藏)\s*([\d,.]+(?:万|千|w|W|k|K)?)$")
+ENGAGEMENT_METRIC = re.compile(r"^(赞|点赞|收藏|评论|分享)\s*[:：]?\s*([\d,.]+(?:万|千|w|W|k|K)?)$")
 
 
 class ContractError(ValueError):
@@ -211,9 +214,123 @@ def parse_feed_snapshot(snapshot: dict) -> dict:
     return {"notes": notes, "truncated": bool(snapshot.get("truncated", False))}
 
 
+def _valid_nodes(snapshot: dict, origin: str) -> List[Dict]:
+    if snapshot.get("origin") != origin:
+        raise ContractError(f"snapshot requires the {origin} origin")
+    nodes = snapshot.get("nodes")
+    if not isinstance(nodes, list):
+        raise ContractError("snapshot nodes must be an array")
+    return [node for node in nodes if isinstance(node, dict)]
+
+
+def _named_text(node: Dict) -> str:
+    name = node.get("name")
+    return name.strip() if isinstance(name, str) else ""
+
+
+def _first_named(nodes: List[Dict], roles: Set[str]) -> Optional[str]:
+    for node in nodes:
+        name = _named_text(node)
+        if name and node.get("role") in roles:
+            return name
+    return None
+
+
+def _visible_counts(nodes: List[Dict]) -> List[str]:
+    values = []
+    for node in nodes:
+        name = _named_text(node)
+        if node.get("role") in {"button", "section"} and (
+            COUNT_VALUE.fullmatch(name) or ENGAGEMENT_METRIC.fullmatch(name)
+        ):
+            values.append(name)
+    return values
+
+
+def parse_note_snapshot(snapshot: dict, note_url: str) -> dict:
+    nodes = _valid_nodes(snapshot, "https://www.xiaohongshu.com")
+    match = _path_match(note_url, NOTE_PATH)
+    if not match:
+        raise ContractError("note_url must be a canonical Xiaohongshu explore URL")
+    canonical_url = f"https://www.xiaohongshu.com/explore/{match.group(1)}"
+    profiles = []
+    comments = []
+    content_parts = []
+    comments_started = False
+    for node in nodes:
+        name = _named_text(node)
+        if not name:
+            continue
+        if node.get("role") == "comment":
+            comments_started = True
+            comments.append(name)
+            continue
+        profile = _path_match(node.get("href"), PROFILE_PATH)
+        if profile and not comments_started:
+            profiles.append({"user_id": profile.group(1), "name": name, "url": f"https://www.xiaohongshu.com/user/profile/{profile.group(1)}"})
+        if node.get("role") in {"article", "paragraph", "p"}:
+            content_parts.append(name)
+    unique_profiles = {item["url"]: item for item in profiles}
+    author = next(iter(unique_profiles.values())) if len(unique_profiles) == 1 else None
+    return {
+        "note_id": match.group(1),
+        "canonical_url": canonical_url,
+        "title": _first_named(nodes, {"heading"}),
+        "author": author,
+        "author_state": "available" if author else ("unavailable" if not unique_profiles else "ambiguous"),
+        "profile_url": author["url"] if author else None,
+        "content": content_parts,
+        "visible_engagement": _visible_counts(nodes),
+        "comments": comments,
+        "truncated": bool(snapshot.get("truncated", False)),
+    }
+
+
+def parse_profile_snapshot(snapshot: dict, profile_url: str) -> dict:
+    nodes = _valid_nodes(snapshot, "https://www.xiaohongshu.com")
+    match = _path_match(profile_url, PROFILE_PATH)
+    if not match:
+        raise ContractError("profile_url must be a canonical Xiaohongshu profile URL")
+    canonical_url = f"https://www.xiaohongshu.com/user/profile/{match.group(1)}"
+    notes = []
+    seen = set()
+    metrics = []
+    counts = []
+    for node in nodes:
+        name = _named_text(node)
+        if node.get("role") == "section" and PROFILE_METRIC.fullmatch(name):
+            metrics.append(name)
+        elif node.get("role") in {"button", "section"} and COUNT_VALUE.fullmatch(name):
+            counts.append(name)
+        note = _path_match(node.get("href"), NOTE_PATH)
+        if note and name and note.group(1) not in seen:
+            seen.add(note.group(1))
+            notes.append({"note_id": note.group(1), "title": name, "url": f"https://www.xiaohongshu.com/explore/{note.group(1)}"})
+    return {
+        "user_id": match.group(1),
+        "canonical_url": canonical_url,
+        "display_name": _first_named(nodes, {"heading"}),
+        "visible_metrics": metrics,
+        "visible_counts": counts,
+        "notes": notes,
+        "truncated": bool(snapshot.get("truncated", False)),
+    }
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("command", choices=("validate-publish", "normalize-filters", "parse-feed-snapshot"))
+    parser.add_argument(
+        "command",
+        choices=(
+            "validate-publish",
+            "normalize-filters",
+            "parse-feed-snapshot",
+            "parse-note-snapshot",
+            "parse-profile-snapshot",
+        ),
+    )
+    parser.add_argument("--note-url")
+    parser.add_argument("--profile-url")
     args = parser.parse_args()
     try:
         payload = _read_json()
@@ -221,8 +338,16 @@ def main() -> None:
             result = validate_publish(payload)
         elif args.command == "normalize-filters":
             result = normalize_filters(payload)
-        else:
+        elif args.command == "parse-feed-snapshot":
             result = parse_feed_snapshot(payload)
+        elif args.command == "parse-note-snapshot":
+            if not args.note_url:
+                raise ContractError("--note-url is required")
+            result = parse_note_snapshot(payload, args.note_url)
+        else:
+            if not args.profile_url:
+                raise ContractError("--profile-url is required")
+            result = parse_profile_snapshot(payload, args.profile_url)
     except ContractError as exc:
         print(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False))
         raise SystemExit(2) from exc

package/skills/xiaohongshu/tests/fixtures/note.json

@@ -0,0 +1,13 @@
+{
+  "origin": "https://www.xiaohongshu.com",
+  "nodes": [
+    {"role": "heading", "name": "示例笔记"},
+    {"role": "link", "name": "示例作者", "href": "https://www.xiaohongshu.com/user/profile/user123"},
+    {"role": "article", "name": "这是脱敏后的示例正文"},
+    {"role": "button", "name": "赞：128"},
+    {"role": "comment", "name": "示例评论"},
+    {"role": "link", "name": "赞过的人", "href": "https://www.xiaohongshu.com/user/profile/liker999"},
+    {"role": "link", "name": "评论者", "href": "https://www.xiaohongshu.com/user/profile/commenter456"}
+  ],
+  "truncated": false
+}

package/skills/xiaohongshu/tests/fixtures/profile.json

@@ -0,0 +1,11 @@
+{
+  "origin": "https://www.xiaohongshu.com",
+  "nodes": [
+    {"role": "heading", "name": "示例作者"},
+    {"role": "section", "name": "粉丝 128"},
+    {"role": "section", "name": "999"},
+    {"role": "link", "name": "最近笔记", "href": "https://www.xiaohongshu.com/explore/abc123?source=profile"},
+    {"role": "button", "name": "5678"}
+  ],
+  "truncated": false
+}

package/skills/xiaohongshu/tests/test_contract_script.py

@@ -188,4 +188,83 @@ def test_sanitized_home_fixture_matches_parser_contract() -> None:
             }
         ],
         "truncated": False,
-    }
+    }
+
+
+def test_parse_note_fixture() -> None:
+    fixture = Path(__file__).parent / "fixtures" / "note.json"
+    result = xhs_contract.parse_note_snapshot(
+        json.loads(fixture.read_text(encoding="utf-8")),
+        "https://www.xiaohongshu.com/explore/abc123?tracking=removed",
+    )
+
+    assert result["canonical_url"] == "https://www.xiaohongshu.com/explore/abc123"
+    assert result["title"] == "示例笔记"
+    assert result["author_state"] == "available"
+    assert result["profile_url"] == "https://www.xiaohongshu.com/user/profile/user123"
+    assert result["visible_engagement"] == ["赞：128"]
+    assert result["comments"] == ["示例评论"]
+
+
+def test_parse_note_ignores_generic_list_items_before_author() -> None:
+    snapshot = {
+        "origin": "https://www.xiaohongshu.com",
+        "nodes": [
+            {"role": "heading", "name": "示例笔记"},
+            {"role": "listitem", "name": "导航项"},
+            {
+                "role": "link",
+                "name": "示例作者",
+                "href": "https://www.xiaohongshu.com/user/profile/user123",
+            },
+        ],
+    }
+
+    result = xhs_contract.parse_note_snapshot(
+        snapshot, "https://www.xiaohongshu.com/explore/abc123"
+    )
+
+    assert result["author_state"] == "available"
+    assert result["comments"] == []
+
+
+def test_parse_note_refuses_to_guess_between_pre_comment_profiles() -> None:
+    snapshot = {
+        "origin": "https://www.xiaohongshu.com",
+        "nodes": [
+            {"role": "heading", "name": "示例笔记"},
+            {
+                "role": "link",
+                "name": "赞过的人",
+                "href": "https://www.xiaohongshu.com/user/profile/liker999",
+            },
+            {
+                "role": "link",
+                "name": "示例作者",
+                "href": "https://www.xiaohongshu.com/user/profile/user123",
+            },
+        ],
+    }
+
+    result = xhs_contract.parse_note_snapshot(
+        snapshot, "https://www.xiaohongshu.com/explore/abc123"
+    )
+
+    assert result["author"] is None
+    assert result["author_state"] == "ambiguous"
+
+
+def test_parse_profile_fixture() -> None:
+    fixture = Path(__file__).parent / "fixtures" / "profile.json"
+    result = xhs_contract.parse_profile_snapshot(
+        json.loads(fixture.read_text(encoding="utf-8")),
+        "https://www.xiaohongshu.com/user/profile/user123?tracking=removed",
+    )
+
+    assert result["canonical_url"] == "https://www.xiaohongshu.com/user/profile/user123"
+    assert result["display_name"] == "示例作者"
+    assert result["visible_metrics"] == ["粉丝 128"]
+    assert result["visible_counts"] == ["999", "5678"]
+    assert result["notes"] == [
+        {"note_id": "abc123", "title": "最近笔记", "url": "https://www.xiaohongshu.com/explore/abc123"}
+    ]