Current version
0.6.4
Describe the feature
Proposed direction
Xiaohongshu's private web APIs and response schemas can change without notice. I propose a small compatibility and diagnostics layer that makes failures reproducible without exposing user credentials.
Phase 1: xhs doctor
Add a machine-readable diagnostic command:
It would report:
- CLI and Python versions
- authentication availability
- individual capability status
- active endpoint
- HTTP/API error category
- whether verification is required
It must never output cookies, session values, signing headers, or private account data.
Phase 2: sanitized support bundle
Add:
xhs support-bundle -o xhs-support.json
The bundle would contain only sanitized diagnostics suitable for attaching to a GitHub issue. Sensitive fields would be removed by an allowlist, rather than relying only on key-name masking.
Phase 3: response-contract fixtures
Introduce sanitized API response fixtures and offline replay tests so that response schema changes can be detected and fixed without requiring real cookies in CI.
Possible initial coverage:
- search
- note detail
- comments
- login status
- current user
Implementation approach
I propose implementing this as several small PRs:
- capability model and
xhs doctor
- sanitization utility and
support-bundle
- sanitized fixtures and replay tests
Each PR would remain independently useful and reviewable.
Use case
Motivation
When a command fails today, users often can only report “it stopped working”. Maintainers then need to determine whether the problem comes from:
- expired cookies
- request signing changes
- endpoint changes
- response schema changes
- captcha or account risk control
- IP/network restrictions
The proposed diagnostics would help users provide actionable, privacy-safe reports and let maintainers reproduce response-contract regressions offline.
Non-goals
This proposal would not initially add:
- a daemon
- telemetry
- automatic upload of diagnostics
- a new networking abstraction
- automatic API reverse engineering
- write-operation automation
- real user credentials in tests
Questions
- Would this direction be useful to the project?
- Is
xhs doctor an acceptable command name?
- Which 3–5 commands should be included in the first capability probe?
- Would you prefer fixtures committed under
tests/fixtures/?
- Should this proposal stay CLI-only initially, with MCP considered separately?
If the direction is accepted, I can start with Phase 1 as a small PR.
Current version
0.6.4
Describe the feature
Proposed direction
Xiaohongshu's private web APIs and response schemas can change without notice. I propose a small compatibility and diagnostics layer that makes failures reproducible without exposing user credentials.
Phase 1:
xhs doctorAdd a machine-readable diagnostic command:
It would report:
It must never output cookies, session values, signing headers, or private account data.
Phase 2: sanitized support bundle
Add:
The bundle would contain only sanitized diagnostics suitable for attaching to a GitHub issue. Sensitive fields would be removed by an allowlist, rather than relying only on key-name masking.
Phase 3: response-contract fixtures
Introduce sanitized API response fixtures and offline replay tests so that response schema changes can be detected and fixed without requiring real cookies in CI.
Possible initial coverage:
Implementation approach
I propose implementing this as several small PRs:
xhs doctorsupport-bundleEach PR would remain independently useful and reviewable.
Use case
Motivation
When a command fails today, users often can only report “it stopped working”. Maintainers then need to determine whether the problem comes from:
The proposed diagnostics would help users provide actionable, privacy-safe reports and let maintainers reproduce response-contract regressions offline.
Non-goals
This proposal would not initially add:
Questions
xhs doctoran acceptable command name?tests/fixtures/?If the direction is accepted, I can start with Phase 1 as a small PR.