Zhihu Python CLI

Zhihu Python CLI

Use the bundled Python CLI rather than a PATH command of unknown origin. Keep Access Secrets and personal data out of replies, logs, and the Skill directory.

The bundled installer requires uv. Check for it before setup; if it is absent, direct the user to https://docs.astral.sh/uv/getting-started/installation/ instead of improvising another installer.

First check

Run once per session:

bash <skill-dir>/scripts/run.sh status --min-cli-version 0.2.1

If installed=false, obtain installation consent unless the user already asked to install or initialize this Skill, then run:

bash <skill-dir>/scripts/setup.sh

Use <skill-dir>/scripts/run.sh for every later command. It fixes the executable path and defaults credential storage to ~/.config/zhihu-python-cli/.env; ZHIHU_ACCESS_SECRET still has priority.

Authentication

If no credential is configured, direct the user to https://developer.zhihu.com/profile. Accept the Access Secret only when needed and pass it through stdin without echoing it:

bash <skill-dir>/scripts/run.sh auth set --secret-stdin

This verifies the Secret with one minimal personal-content request before writing the private .env with mode 0600. Never put the Secret in a command argument, reply, report, or project file.

Choose the minimum capability

• Community evidence: search zhihu --query "..." --count 10
• External evidence: search global --query "..." --count 10
• Current topics: hot --limit 20
• Fast synthesis: answer --query "..."; do not use it instead of original-source research.
• Personal creations: me contents --type all --limit 20
• Recent saved input: me favorites recent --limit 20
• Collection archaeology: list folders first, then read only folders relevant to the user's question.

Do not automatically exhaust pagination or enumerate followees and private collections. Preserve the service JSON and treat summaries as summaries, not full content.

Generate a knowledge atlas

Generate only after the user asks for a personal report or visualization:

bash <skill-dir>/scripts/run.sh report collect \
  --from-year 2024 --to-year 2026 --full-input \
  --output /absolute/path/knowledge-growth.data.json

Read every point's title and available metadata. Open original URLs for ambiguous items and the key nodes used in the growth narrative when the environment permits it. If originals were not inspected, describe the result as title-level classification rather than claiming body-level reading. As the Agent, define 4–7 themes that fit this user's actual material, assign every point ID, compare every year on the same evidence, and write:

{
  "topics": [{"name": "主题", "description": "边界"}],
  "assignments": {"point-id": "主题"},
  "year_notes": {"2024": "该年的变化"},
  "growth_statement": "跨年成长判断"
}

Do not ask Python to infer, tokenize, cluster, or label topics. Save the Agent result, then render:

bash <skill-dir>/scripts/run.sh report atlas \
  --data /absolute/path/knowledge-growth.data.json \
  --taxonomy /absolute/path/knowledge-growth.taxonomy.json \
  --output /absolute/path/knowledge-growth.html

collect defaults to the most recent three years. --full-input attempts to traverse collection folders up to --max-input-requests; it cannot recover items the API does not return. Inspect input_complete, input_truncated, and unavailable_inputs before making coverage claims. Without --full-input, input is limited to one recent-favorites page and is never complete history. Keep datasets, taxonomy, and HTML in a user-approved location; they contain personal titles and must never be copied into the Skill.

After rendering, verify the default view, one year focus, one legend toggle, one point detail, and a narrow viewport. If the browser automation rejects file://, serve only the report directory from a temporary loopback HTTP server, then stop it after verification.

Read references/atlas.md when interpreting or presenting the visualization.

Error handling

• AUTH_REQUIRED or AUTH_INVALID: stop and request a valid Access Secret.
• RATE_LIMITED or QUOTA_EXHAUSTED: stop repeated calls.
• NETWORK_ERROR or TIMEOUT: retry only idempotent GET operations sparingly; never automatically retry Answer POST.
• input_truncated=true: disclose that favorite collection hit its endpoint or request ceiling.
• unavailable_inputs>0: disclose that the API reported items it did not return; input_truncated=false does not cancel this gap.
• input_complete=false: never describe the input side as complete history.