@zhengjunyao/dsh-zhihu

A Zhihu (知乎) plugin for DeepSeek Harness: it wraps the local zhihu CLI — pyzhihu-cli, command name zhihu — as zhihu_* agent tools. Search questions, read the hot list, inspect questions / answers / comments, look up users, browse the recommended feed, topics and notifications. Publishing, voting, following and deleting are off by default and gated behind an explicit readOnly switch.

• Read tools call zhihu <command> --json and normalize the raw Zhihu API payload into compact items (id, type, title, URL, author, upvotes, answer count).
• Login rides Zhihu's official QR-code API: the CLI writes the QR image to a PNG and the plugin hands the path to the agent, which can show it to the user. Pasting a cookie string is also supported — the plugin writes the CLI's cookie file directly, so the token never lands in the process list.
• Write tools are not registered at all by default, so nothing can be published or deleted by accident.

Prerequisites

# Install the Zhihu CLI (Python 3.10+; uv keeps it in its own venv)
uv tool install pyzhihu-cli      # or: pipx install pyzhihu-cli
zhihu --version                  # zhihu-cli, version 0.2.4

The plugin resolves zhihu from $PATH, ~/.local/bin, /opt/homebrew/bin and /usr/local/bin; point cliPath at an absolute path if it lives elsewhere.

Important: every pyzhihu-cli command requires a login — even the hot list fails with Not authenticated. The first run must therefore be a zhihu_login.

Tools

Management and auth

Tool	Purpose
zhihu_status	CLI availability and version, login state (cookie has z_c0/_xsrf/d_c0), read-only mode, paths, timeout. Never echoes cookie contents
zhihu_config	Configure readOnly / cliPath / timeoutMs / loginWaitMs / proxy / cliHome; reset: true restores defaults. Call with no arguments to read
zhihu_login	Log in. mode: qrcode (default) returns the QR PNG path (~/.zhihu-cli/login_qrcode.png) to show the user and can be called again to keep waiting (it never spawns a second QR code); mode: cookie accepts pasted z_c0/_xsrf/d_c0 and verifies online
zhihu_logout	Remove the CLI's cookie file
zhihu_whoami	Current account profile

Read

Tool	Purpose
zhihu_search	Search content (type: general|people|topic)
zhihu_hot	Zhihu hot list
zhihu_question	Question detail; answers: true adds the answer list (limit / sort)
zhihu_answer	Answer body; comments: true adds comments
zhihu_user	User profile, or their answers / articles / followers / following (include)
zhihu_feed	Recommended feed; withComments: true uses the CLI's text-mode "feed + comments"
zhihu_topic	Topic detail; hotQuestions: true adds the topic's hot questions
zhihu_notifications	Notifications (with offset paging)
zhihu_collections	Your collections

Write (registered only when readOnly: false)

Tool	Purpose
zhihu_publish	Publish a question / pin / article (kind: ask|pin|article, optional topics and local images; dryRun: true only echoes the command)
zhihu_vote	Upvote / cancel an upvote
zhihu_follow_question	Follow / unfollow a question
zhihu_delete	Delete your own question / pin / article (requires explicit confirm: true)

Web panel

Two entries, one component:

1. A bottom-right floating ball (blue 「知」 button) — reachable from any page, opening a 380px popover.
2. A 「知乎」 card in the settings page (settings.section).

The panel covers: login state with an inline QR code (one click, auto-detects the scan), the account summary, the read-only switch, proxy / timeout settings, and quick hot-list / search lookups with clickable links.

It talks to the loopback-only /api/dsh-zhihu/* route family (status, config, login, qrcode, logout, whoami, hot, search); non-loopback peers, foreign Host headers and cross-site Origins get 403. The QR is returned as a PNG data URL — no new files on disk.

Client changes need a browser hard refresh; host changes or dsh.client manifest changes need a dsh web restart.

Read-only switch

The plugin is read-only by default: write tools are never registered, so the model cannot even see them.

Two ways to open them up:

// 1) At install time, seed it in cordis.patch.yml
- insert:
    - id: zhihu
      name: dsh-zhihu
      config:
        readOnly: false

2) At runtime via the tool (stored in ~/.dsh/dsh-zhihu.json, remounts immediately):
   zhihu_config({ readOnly: false })     # enable write tools
   zhihu_config({ readOnly: true })      # revoke them

The store value wins over the install-time seed; with neither set, read-only applies.

Configuration

Key	Default	Meaning
readOnly	true	Only read tools when true; write tools are registered when false
cliPath	zhihu	CLI command name or absolute path
timeoutMs	90000	Per-invocation timeout
loginWaitMs	15000	How long zhihu_login waits for a scan before returning; call it again to keep waiting
proxy	empty	Empty = inherit the environment; none = force no proxy (Zhihu is a domestic site, a system proxy can actually break it); or http://host:port
cliHome	~/.zhihu-cli	CLI config directory. The CLI hardcodes Path.home()/".zhihu-cli", so the plugin overrides the child process's HOME

Stored in ~/.dsh/dsh-zhihu.json (mode 0600). Credentials are not stored here — the CLI keeps cookies in <cliHome>/cookies.json (the CLI chmods it 0600 itself).

Logging in

Option 1 — QR code (recommended)

zhihu_login()                     → returns qrcodePath (~/.zhihu-cli/login_qrcode.png)
   ↓ the agent shows it with read_image / present
the user scans it in the Zhihu app
zhihu_login()                     → keeps waiting; returns authenticated: true

Option 2 — paste a cookie

zhihu_login({ mode: "cookie", cookie: "z_c0=...; _xsrf=...; d_c0=..." })

The plugin writes the cookie straight into the CLI's cookies.json (byte-compatible with the CLI's own save_cookies) and then verifies it online via zhihu whoami; a failed check removes the file and reports why. Unlike zhihu login --cookie, this path never exposes the token in the process list.

Compatibility

Requires DeepSeek Harness ≥ 0.1.5-rc.1 (declared in dsh.engines.dsh, which the plugin market reads) and is tested on 0.1.5-rc.1. This build follows the DSH 0.1.5 strict tool-result contract (lossless-JSON snapshots, additionalProperties: false schema validation, output.render returning ContentBlock[]) and resolves the executable independently of the host PATH (a launchd-managed host only has /usr/bin:/bin).

Known limitations

• The CLI's --json mode does not cover comments, the "feed + comments" command, or a topic's hot questions. Those three fall back to text mode and land in the result's text field (ANSI colour codes stripped).
• zhihu_search / zhihu_hot accept -a/--answers only in the CLI's human-readable mode; it is ignored under --json, so the plugin does not expose it.
• Zhihu applies risk control. This plugin is a thin wrapper — request volume and compliance are the caller's responsibility; do not crawl aggressively.
• Zhihu's public API can change; the real command surface is whatever zhihu <cmd> --help reports locally.

Troubleshooting

Symptom	Cause and fix
Every command fails with Not authenticated	pyzhihu-cli needs a session for all commands, the hot list included. Run zhihu_login first.
403 with code 40352, a redirect to /account/unhuman, or "系统监测到您的网络环境存在异常"	Zhihu risk control rejects the request fingerprint, not just missing cookies — so re-pasting a cookie may not help. Use zhihu_login({ mode: "browser" }) to import the real session from local Chrome, then retry. QR-code polling is anonymous and gets 403 on every poll, which is why scanning appears to do nothing.
403 with code 10003 mentioning x-zse-96	The endpoint requires Zhihu's request signature. Topic detail is unavailable; zhihu_question automatically falls back to the answer list (the embedded question.title carries the title).
zhihu_status reports the CLI unavailable	Install it (uv tool install pyzhihu-cli) or point cliPath at an absolute path.
The panel's QR code never completes the login	Expected under risk control, for the reason above. Use the 「从 Chrome 导入登录态」 button in the panel instead.

Every failure now names which of these it is: failureReason classifies the CLI output instead of returning a bare timeout.

Development

pnpm install
pnpm typecheck         # tsc --noEmit (host + client)
pnpm build             # tsc for .d.ts + tsdown for lib/index.js (host) and lib/client.js (browser)
pnpm test              # smoke tests (real CLI calls; all writes land in a temp dir)
pnpm test:e2e          # drive the plugin's own tools against the real CLI (no host restart)
node tests/routes.mjs  # hit /api/dsh-zhihu/* with synthetic req/res
node tests/client.mjs  # execute lib/client.js under a synthetic __ModuleLoader__
pnpm verify:full       # portability check in an isolated DSH_HOME (tarball install + stability watch)

Portability verification follows PORTABILITY-SOP.md and must print ✅ 通过 before a release.

Artifacts: lib/index.js (host, ESM) + lib/client.js (browser closure-factory) + lib/types/ (.d.ts).

Install into a profile

dsh plugin --profile web add @zhengjunyao/dsh-zhihu
dsh plugin --profile web add link:/path/to/dsh-zhihu
# or, once published
dsh plugin --profile web add github:zhengjy01/dsh-zhihu

A DSH web restart is required afterwards (there is no hot reload).

License

MIT. The Zhihu CLI itself (pyzhihu-cli) is Apache-2.0; this project only invokes it as a subprocess and contains none of its code.