How to Format XHS API Output Using the Agent-Reach CLI

The agent_reach format --platform xhs command sanitizes raw XiaoHongShu JSON payloads into a compact, token-friendly structure by reading from STDIN and extracting only essential fields for LLM processing.

The Agent-Reach repository provides a specialized CLI tool for preprocessing social media API responses. When you need to format XHS API output for downstream language model processing, the format sub-command offers a streamlined solution that strips redundant metadata while preserving critical content fields.

How the Format Command Processes XHS Data

The CLI entry point in agent_reach/cli.py orchestrates the formatting pipeline. When you execute the command with the --platform xhs flag, the tool expects raw JSON input from STDIN and delegates the transformation to a platform-specific handler.

The workflow follows these steps:

1. Reads raw JSON from STDIN – The command accepts complete XHS API responses via pipes or redirects.
2. Parses the payload – Uses json.loads to convert the stream into Python objects.
3. Dispatches to the formatter – Calls format_xhs_result defined in agent_reach/channels/xiaohongshu.py (lines 9-30).
4. Serializes clean output – Returns pretty-printed JSON to STDOUT with unnecessary fields removed.

Deep Cleaning with format_xhs_result

The heavy lifting occurs in agent_reach/channels/xiaohongshu.py within the format_xhs_result function. This implementation performs a deep clean that normalizes both single objects and list-based responses, including the {"items": ...} wrapper common in XHS search endpoints.

The formatter extracts only high-value fields while stripping token-heavy noise:

• Preserved fields: id, title, desc, type, xsec_token, author nickname and user_id, interaction metrics (liked_count, collected_count, comment_count, share_count), image URLs, and tag names.
• Removed fields: Avatar URLs, internal user IDs, extra metadata, and redundant nested structures.

This architecture isolates platform-specific logic from the CLI interface, enabling the same format entry point to support additional platforms through matching formatter functions.

Practical Usage Examples

The command accepts input exclusively through STDIN, making it compatible with Unix pipes and here-documents for testing.

Piping a File

Send an existing raw response through the formatter:

cat raw_xhs.json | python -m agent_reach.cli format --platform xhs

Using a Here-Document

For quick testing without creating intermediate files:

python -m agent_reach.cli format --platform xhs <<'EOF'
{
  "id": "abc123",
  "title": "测试笔记",
  "desc": "这是正文内容",
  "type": "normal",
  "xsec_token": "tok_xxx",
  "user": {
    "nickname": "小红",
    "user_id": "u123",
    "avatar": "https://example.com/avatar.jpg",
    "extra_field": "should be dropped"
  },
  "interact_info": {
    "liked_count": "100",
    "collected_count": "50",
    "comment_count": "20",
    "share_count": "10"
  },
  "image_list": [
    {"url": "https://img.example.com/1.jpg"},
    {"url": "https://img.example.com/2.jpg"}
  ],
  "tag_list": [
    {"name": "旅行"},
    {"name": "美食"}
  ]
}
EOF

Transformed Output Structure

The sanitized output preserves only LLM-relevant fields while dramatically reducing token consumption. Instead of nested objects, the formatter produces a flat, predictable structure.

Key transformations:

• Interaction metrics are flattened from interact_info to top-level keys
• Image URLs are extracted from image_list into a simple images array
• Tags are converted from objects to string arrays
• User objects are stripped to only nickname and user_id

{
  "id": "abc123",
  "title": "测试笔记",
  "desc": "这是正文内容",
  "type": "normal",
  "xsec_token": "tok_xxx",
  "user": {
    "nickname": "小红",
    "user_id": "u123"
  },
  "liked_count": "100",
  "collected_count": "50",
  "comment_count": "20",
  "share_count": "10",
  "images": [
    "https://img.example.com/1.jpg",
    "https://img.example.com/2.jpg"
  ],
  "tags": [
    "旅行",
    "美食"
  ]
}

The expected behavior is validated in tests/test_xhs_format.py (lines 58-71), ensuring consistent field extraction across different XHS endpoint variations.

Summary

• The agent_reach format --platform xhs command reads raw JSON from STDIN and outputs sanitized, token-efficient JSON suitable for LLM ingestion
• Core logic resides in agent_reach/channels/xiaohongshu.py, specifically the format_xhs_result function (lines 9-30)
• The formatter handles both single items and list responses, including {"items": ...} wrappers from search endpoints
• Output flattens interaction metrics, extracts image URLs into arrays, and strips redundant user metadata like avatars
• This architecture isolates platform-specific formatting logic from the CLI interface, enabling easy extension to other platforms

Frequently Asked Questions

What fields does the XHS formatter preserve?

The format_xhs_result function preserves id, title, desc, type, xsec_token, author nickname and user_id, interaction counts (liked, collected, comment, share), image URLs, and tag names. It removes avatar URLs, internal IDs, and other noisy attributes that consume tokens without adding value to LLM processing.

Can I format multiple XHS posts at once?

Yes. The formatter handles both individual dictionary objects and list-based responses, including the {"items": [...]} wrapper returned by XHS search endpoints. When processing a list, it applies the cleaning logic to each item in the collection automatically.

How do I handle authentication tokens in the output?

The formatter preserves the xsec_token field in the root object as it may be required for subsequent API calls, but strips other internal authentication artifacts. According to the test suite in tests/test_xhs_format.py, the output maintains only the necessary identifiers for content reference while removing sensitive session data.

Why does the command use STDIN instead of file arguments?

The STDIN-based design follows Unix philosophy for composability, allowing you to pipe output directly from curl requests or other tools without intermediate files. This approach keeps the CLI interface minimal while supporting flexible workflows like curl -s "https://api.example.com/xhs" | agent_reach format --platform xhs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}