# Zhihu Python CLI

> Use the Python Zhihu Open Platform CLI to search Zhihu or the web, inspect hot topics, call Zhihu Answer, read the current account's creations and favorites, and generate a yearly input/output knowledge-atlas HTML report. Trigger for Zhihu Python CLI setup, environment or .env authentication, collection archaeology, annual knowledge reports, knowledge constellations, and Agent-oriented JSON workflows.

- Skill: `zly2006/zhihu-python-cli` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add zly2006/zhihu-python-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zly2006/zhihu-python-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: zly2006 (https://skillmd.com/u/zly2006)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zly2006/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
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
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:

```text
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
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:

```json
{
  "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
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](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.