@klarkxy/dsh-zhihu 0.1.8 → 0.1.10

package/README.md

@@ -1,12 +1,12 @@
 # @klarkxy/dsh-zhihu
 
-Zhihu search, answers, knowledge bases, and usage tracking for DSH.
+Hand Zhihu to the agent as a research source: in-site search, global web search, the hot list, 直答 AI answers and public knowledge bases, plus question discovery, creator statistics and usage tracking. Every call uses your own Zhihu Access Secret, and what comes back is reference material for the agent, not a settled verdict.
 
-[简体中文](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/docs/README.zh-CN.md)
+[简体中文](docs/README.zh-CN.md)
 
-## Install
+Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed.
 
-Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed. Install:
+## Install
 
 ```sh
 npm install @klarkxy/dsh-zhihu
@@ -20,17 +20,19 @@ dsh plugin --profile web add @klarkxy/dsh-zhihu
 
 Restart DSH Web, open **Plugins → @klarkxy/dsh-zhihu**, and enter your Access Secret (DSH credential `ZHIHU_ACCESS_TOKEN`). Use the full scoped name; the unscoped `dsh-zhihu` package belongs to another maintainer.
 
-To enable agent tools, add this entry to the plugin list in the agent's `agent.cordis.yml`:
+## Use
+
+**Plugins → @klarkxy/dsh-zhihu** holds the settings, **Statistics**, **Official usage**, the knowledge bases and **Test**. **Test** uses one function selector and shows the parameters and the result of whichever function you pick, covering search and question/creator queries: question recommendations, answer excerpts, your published content and comments, and account or per-content statistics. **Statistics** shows the daily calls, failures and returned results recorded on this machine. The separate **Official usage** tab fetches every official quota category when it opens and when you refresh it, drawing metric charts and values rather than showing raw JSON. Totals or used amounts that Zhihu does not return are never inferred, and separate API categories are not summed. **Test** holds business queries only, each of which needs an explicit click. No request is automatically retried or paginated. Existing agent tools and RPC endpoints remain available.
+
+## Agent tools
+
+To enable the agent tools, add this entry to the plugin list in the `agent.cordis.yml` you use:
 
 ```yaml
 - name: '@klarkxy/dsh-zhihu/tools'
 ```
 
-## Use
-
-DSH Web provides search, settings, usage, and knowledge-base views. Open **Plugins → @klarkxy/dsh-zhihu** for configuration, usage, knowledge bases, and search; the agent tools are included.
-
-Five agent tools are available once the tools entry is enabled:
+Twelve tools are available once that entry is enabled. The five existing tools are unchanged:
 
 - `zhihu_search`: search within Zhihu for community evidence; results are community/reader feedback only, never canon, and never written into project files.
 - `zhihu_global_search`: search the wider web beyond Zhihu through the open platform's global search; reference only.
@@ -38,16 +40,56 @@ Five agent tools are available once the tools entry is enabled:
 - `zhihu_ask`: ask Zhihu 直答, an OpenAI-compatible AI answer service grounded in Zhihu community content; suited for research and background investigation.
 - `zhihu_knowledge_search`: retrieve RAG fragments from Zhihu knowledge bases — public bases by default, with personal and subscription recall scopes available after you upload material on Zhihu's web side.
 
-Usage is tracked as daily counters of calls, failures, and returned results; usage views default to the last 30 days and accept at most 90. Knowledge-base uploads are limited to 20 MB per file.
+### Question discovery and creator data
+
+Aligned with [zhihu-search PR #4](https://github.com/klarkxy/zhihu-search/pull/4) and upstream `main` at `62fd3ce5c5761dd217094280390b394e4eb77ed2` (2026-09-28). All seven additions use **only the current Access Secret**. They neither accept an OAuth identity switch nor expose credentials as tool parameters.
+
+| Agent tool | RPC endpoint on `/zhihu` | Parameters | Official quota |
+| --- | --- | --- | --- |
+| `zhihu_question_recommendations` | `question.recommendations` | Optional `query`; `count` 1–20, default 5 | `creator` |
+| `zhihu_question_answers` | `question.answers` | `questionUrl`; `offset`, `limit` | `question_answers` |
+| `zhihu_user_content_detail` | `content.detail` | `contentUrl` | `creator` |
+| `zhihu_user_content_comments` | `content.comments` | `contentUrl`; `offset`, `limit`; `order`: `score` (default), `reverse`, `ascending` | `creator` |
+| `zhihu_creator_account_stats` | `creator.account.stats` | `contentType`: `all` (default), `answer`, `article`, `pin`, `zvideo`; paired dates | `creator` |
+| `zhihu_creator_content_stats` | `creator.content.stats` | `contentUrl`; paired dates | `creator` |
+| `zhihu_quota` | `quota` | Optional `apiIds` array; omit or `[]` for all | None |
+
+The service also accepts upstream-style underscore aliases such as `question_recommendations`, `question_answers`, `content_detail`, `content_comments`, `creator_account_stats`, and `creator_content_stats` (plus `user_content_detail` / `user_content_comments`). Parameter names remain camelCase as shown above.
 
-Search covers Zhihu in-site search, the wider web, the hot list, Zhihu 直答 AI answers, and public knowledge bases. Uploaded reference files are stored in Zhihu's cloud; do not upload unpublished manuscripts.
+Omit `query` to get profile-based recommendations. An explicitly empty or whitespace-only theme is rejected. Recommendations do not paginate. `questionUrl` must be an HTTPS `www.zhihu.com/question/{id}` link. `contentUrl` must be a Zhihu answer, column article, pin, or video link; creator endpoints apply only to content published by the current account. Video details contain associated text, not video files.
+
+Paged tools accept `offset` as a non-negative Int64 **decimal string**, default `"0"`; RPC also accepts safe JavaScript integers. `limit` is an integer from 1 to 50, default 20. Every call fetches one page. Only continue when `paging.canContinue` is true, using its `nextOffset` verbatim. A short or empty page is not the end; a missing, invalid, non-advancing, or unsafe numeric `NextOffset` stops pagination with a warning. Never derive the next offset from item counts. `Totals` may include filtered answers; `Summary` is an upstream excerpt, not full text or a newly generated AI summary. Attached comment `Children` may be incomplete.
+
+Both statistics tools require `startDate` and `endDate` together, as valid `YYYY-MM-DD` calendar dates with end ≥ start. Omit both for the upstream default range; no range is invented locally. Missing metrics stay missing and ratios are not converted to percentages. New results contain `version`, `operation`, `data`, optional `quotaId`, and optional safe `paging`. Structured `data` retains the original upstream fields and HTML; tool rendering strips HTML and displays inert fenced text. Empty/missing `Body` is not presented as full text.
+
+### Official quota versus local usage
+
+`zhihu_quota` calls `GET /api/v1/quota`; it is the only source of official remaining quota. Its `apiIds` allowlist is `global_search`, `zhihu_search`, `hot_list`, `question_answers`, `zhida_openai`, `tools`, `knowledge`, `user_data`, and `creator`. Duplicate IDs are removed in first-seen order. Quota reads do not emit business-usage events, even on failure. No remaining-quota prediction, reset countdown, or automatic retry is added.
+
+Local usage is still tracked as daily counters of calls, failures, and returned results; usage views default to the last 30 days and accept at most 90. New business operations emit one event per tool/RPC call, with their quota category; local counters are not a billing ledger or official balance. Existing storage identifiers are unchanged. Knowledge-base uploads remain limited to 20 MB per file.
+
+Business errors retain their upstream message and code, including on HTTP error responses. RPC `error.details` may contain `status`, `upstreamCode`, `retryAfter` (seconds), and `retryable`. `30001` / `30002` are rate/quota limits; **`30003` is risk-control rejection, not an ordinary rate limit** and tells callers not to retry immediately. No request is automatically retried. Timeouts and cancellation cover response-body reads as well as the initial request.
+
+## Works with the web search manager
 
 When [@klarkxy/dsh-web-search-manager](https://www.npmjs.com/package/@klarkxy/dsh-web-search-manager) is also installed in the same profile, this plugin registers **Zhihu global search** as a provider in its web search settings. Enable that provider to use Zhihu's global search through the standard web search tool with the Access Secret from Zhihu settings. The dedicated Zhihu tools work independently.
 
+## Boundaries and limits
+
+- Search covers Zhihu in-site search, the wider web, the hot list, Zhihu 直答 AI answers, and public knowledge bases.
+- Uploaded reference files are stored in Zhihu's cloud; do not upload unpublished manuscripts.
+- This sync does not cover all upstream CLI/MCP features, such as OAuth identity management or PDF/PPT tasks.
+- The client accepts structural host controls and has native HTML fallbacks. Building or using this package does not require application-private UI packages.
+- Existing agent tools, credentials, RPC contracts and storage identifiers are preserved; the additions above are additive.
+
 ## Development
 
-Read [contracts](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/contracts.ts) and [tools](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/tools.ts) for the API.
+Read [contracts](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/contracts.ts), [tools](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/tools.ts), and [open-platform client](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/open-platform.ts) for the API. The seven additions cover the six question/creator endpoints plus official quota.
 
-[Publishing](https://github.com/klarkxy/dsh-plugins/blob/main/docs/editor-plugin-migration.md) · [License](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/LICENSE)
+```sh
+pnpm --filter @klarkxy/dsh-zhihu typecheck
+pnpm --filter @klarkxy/dsh-zhihu test
+pnpm --filter @klarkxy/dsh-zhihu build
+```
 
-The client accepts structural host controls and has native HTML fallbacks. Building or using this package does not require application-private UI packages. Agent tools, credentials, RPC contracts and storage identifiers are unchanged.
+[Publishing](../PUBLISHING.md) · [License](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/LICENSE)

package/docs/README.zh-CN.md

@@ -1,12 +1,12 @@
 # @klarkxy/dsh-zhihu
 
-DSH 知乎搜索、直答、知识库与用量插件。
+把知乎交给模型当调研信源：站内搜索、全网搜索、热榜、直答和公开知识库，外加问题发现、创作数据与用量统计。每次请求都只用你自己的知乎 Access Secret，取回的内容是给模型参考的资料，不是定论。
 
-[English](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/README.md)
+[English](../README.md)
 
-## 安装
+需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。
 
-需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。安装：
+## 安装
 
 ```sh
 npm install @klarkxy/dsh-zhihu
@@ -20,17 +20,19 @@ dsh plugin --profile web add @klarkxy/dsh-zhihu
 
 重启 DSH Web，从「插件」打开「知乎（@klarkxy/dsh-zhihu）」填写 Access Secret（DSH 凭据 `ZHIHU_ACCESS_TOKEN`）。请使用完整 scoped 包名；无 scope 的 `dsh-zhihu` 属于其他维护者。
 
+## 使用
+
+「插件 → 知乎（@klarkxy/dsh-zhihu）」下有设置、统计、官方用量、知识库和「测试」分区。「测试」通过一个功能选择框统一选择搜索、问题与创作查询，按所选功能显示对应参数和结果，覆盖问题推荐、回答摘要、本人已发布内容及评论、账号和单篇创作统计。「统计」展示本机记录的每日调用、失败和结果条数；独立的「官方用量」页签在打开时和手动刷新时查询全部官方额度项，以图表和数值展示，不显示原始 JSON。知乎未返回的总量或已用量不自行推算，不同接口类别的数据也不相加。「测试」只保留业务查询，均需手动点击。所有请求都不会自动重试或翻页。原有模型工具和共享 RPC 仍可使用。
+
+## 模型工具
+
 模型需要使用知乎工具时，在所用 `agent.cordis.yml` 的插件列表加入：
 
 ```yaml
 - name: '@klarkxy/dsh-zhihu/tools'
 ```
 
-## 使用
-
-DSH Web 提供搜索、设置、用量与知识库视图。在「插件 → 知乎（@klarkxy/dsh-zhihu）」配置、查看用量、管理知识库和搜索；模型工具随插件一同提供。
-
-启用 tools 入口后，模型可使用五个工具：
+加入后，模型可使用十二个工具。原有五个工具保持兼容：
 
 - `zhihu_search`：知乎站内搜索，拉取社区证据；结果仅作社区/读者反馈参考，不构成 canon，也不直接写入项目文件。
 - `zhihu_global_search`：知乎开放平台全网搜索，检索站外公开网页资料；仅作参考。
@@ -38,16 +40,56 @@ DSH Web 提供搜索、设置、用量与知识库视图。在「插件 → 知
 - `zhihu_ask`：调用知乎直答（OpenAI 兼容的 AI 问答），基于知乎社区内容生成综合回答；适合考据与背景调研。
 - `zhihu_knowledge_search`：检索知乎知识库（RAG 片段），默认只查公开库；在知乎网页端上传过个人资料后可加个人/订阅召回范围。
 
-用量按日计数（调用次数、失败次数与成功调用返回的条目数），视图默认展示最近 30 天，最多可查 90 天。知识库上传单文件上限 20 MB。
+### 问题发现与创作能力
+
+对齐 [zhihu-search PR #4](https://github.com/klarkxy/zhihu-search/pull/4) 和主库 `main` 的 `62fd3ce5c5761dd217094280390b394e4eb77ed2`（2026-09-28）。以下新增接口**只使用当前 Access Secret**，不接受 OAuth 身份切换，模型参数中不暴露密钥。
+
+| 模型工具 | `/zhihu` 上的 RPC 端点 | 参数 | 官方额度分类 |
+| --- | --- | --- | --- |
+| `zhihu_question_recommendations` | `question.recommendations` | 可选 `query`；`count` 1–20，默认 5 | `creator` |
+| `zhihu_question_answers` | `question.answers` | `questionUrl`；`offset`、`limit` | `question_answers` |
+| `zhihu_user_content_detail` | `content.detail` | `contentUrl` | `creator` |
+| `zhihu_user_content_comments` | `content.comments` | `contentUrl`；`offset`、`limit`；`order` 为 `score`（默认）、`reverse`、`ascending` | `creator` |
+| `zhihu_creator_account_stats` | `creator.account.stats` | `contentType` 为 `all`（默认）、`answer`、`article`、`pin`、`zvideo`；成对日期 | `creator` |
+| `zhihu_creator_content_stats` | `creator.content.stats` | `contentUrl`；成对日期 | `creator` |
+| `zhihu_quota` | `quota` | 可选 `apiIds` 数组，省略或 `[]` 查全部 | 不消耗业务额度 |
+
+RPC 还接受主库风格的下划线别名：`question_recommendations`、`question_answers`、`content_detail`、`content_comments`、`creator_account_stats`、`creator_content_stats`，以及 `user_content_detail` / `user_content_comments`。参数名仍使用表中的 camelCase。
 
-可查询站内、全网、热榜、直答和公开知识库。上传的参考文件保存在知乎云端，请勿上传未发表手稿。
+省略 `query` 才按当前账号画像推荐；显式空字符串或纯空白主题会被拒绝。推荐不分页。`questionUrl` 必须是 HTTPS `www.zhihu.com/question/{id}` 问题链接。`contentUrl` 仅支持知乎回答、专栏文章、想法或视频链接；创作接口仅查询当前账号已发布的内容，视频仅返回关联正文，不返回视频文件。
+
+分页工具的 `offset` 使用非负 Int64 **十进制字符串**，默认 `"0"`；RPC 也接受 JavaScript 安全整数。`limit` 为 1–50 的整数，默认 20。每次只取一页，只有 `paging.canContinue=true` 才原样使用其 `nextOffset` 继续。空页或条目不足不能视为结束；`NextOffset` 缺失、无效、未前进或为不安全的数值时，返回警告并停止翻页，不按条目数补偏移。`Totals` 可能包含被过滤的回答；`Summary` 是上游摘要/截取文本，不是全文，也不是额外生成的 AI 摘要。评论附带的 `Children` 不保证完整。
+
+统计日期 `startDate` / `endDate` 必须同时提供或同时省略，格式为有效公历 `YYYY-MM-DD`，结束日期不得早于开始日期。省略时采用上游默认范围，不自行指定天数。缺失指标不补零，比例不换算百分比。新增结果包含 `version`、`operation`、`data`、可选 `quotaId` 与安全分页信息 `paging`。结构化 `data` 保留上游字段及原始 HTML；工具展示清洗 HTML 后放入不会执行的文本代码块。缺少或为空的 `Body` 不能视为全文。
+
+### 官方额度与本地用量
+
+`zhihu_quota` 调用 `GET /api/v1/quota`，是官方剩余额度的唯一来源。`apiIds` 白名单为 `global_search`、`zhihu_search`、`hot_list`、`question_answers`、`zhida_openai`、`tools`、`knowledge`、`user_data`、`creator`；重复项按首次出现顺序去重。额度查询本身不记录业务调用事件，失败时也不计入。不会用本地计数预测余额或推算额度重置时间，也不自动重试。
+
+本地用量仍按日计数（调用次数、失败次数与成功调用返回的条目数），视图默认展示最近 30 天，最多可查 90 天。新增业务工具与 RPC 每次调用只记录一次事件，并带有额度分类；本地计数不是账单，也不是官方余额。存储标识保持不变。知识库上传单文件上限仍为 20 MB。
+
+业务错误保留上游消息与错误码，即使 HTTP 状态为失败。RPC 的 `error.details` 可包含 `status`、`upstreamCode`、`retryAfter`（秒）和 `retryable`。`30001` / `30002` 为频率或额度限制；**`30003` 为风控拒绝，不是普通限流**，会提示不要立即重试。所有请求均不自动重试；超时和取消覆盖响应正文读取，而不只是等待响应头。
+
+## 与网络搜索联动
 
 同一 profile 还安装 [@klarkxy/dsh-web-search-manager](https://www.npmjs.com/package/@klarkxy/dsh-web-search-manager) 时，本插件会向网络搜索注册「知乎全网搜索」后端。在网络搜索设置中启用它，即可让通用网络搜索工具使用知乎的全网搜索能力，并共用「知乎资料」中配置的 Access Secret。专用知乎工具仍可独立使用。
 
+## 边界与限制
+
+- 可查询站内、全网、热榜、直答和公开知识库。
+- 上传的参考文件保存在知乎云端，请勿上传未发表手稿。
+- 此次同步不代表主库的全部 CLI/MCP 能力都已移植；OAuth 身份管理、PDF/PPT 任务等不在本次范围。
+- 客户端接收宿主提供的结构化控件，缺失时使用原生 HTML 控件。构建和使用本包不依赖应用私有 UI 包。
+- 原有 Agent 工具、凭据、RPC 合同和存储标识保持兼容，上述能力为增量扩展。
+
 ## 开发
 
-接口见 [contracts](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/contracts.ts) 与 [tools](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/tools.ts)。
+接口见 [contracts](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/contracts.ts)、[tools](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/tools.ts) 与 [开放平台客户端](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/src/open-platform.ts)。七个新增接口覆盖六个问题发现/创作端点及官方额度。
 
-[发布维护](https://github.com/klarkxy/dsh-plugins/blob/main/docs/editor-plugin-migration.md) · [许可证](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/LICENSE)
+```sh
+pnpm --filter @klarkxy/dsh-zhihu typecheck
+pnpm --filter @klarkxy/dsh-zhihu test
+pnpm --filter @klarkxy/dsh-zhihu build
+```
 
-客户端接收宿主提供的结构化控件，缺失时使用原生 HTML 控件。构建和使用本包不依赖应用私有 UI 包；Agent 工具、凭据、RPC 合同和存储标识保持不变。
+[发布维护](../../PUBLISHING.md) · [许可证](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/LICENSE)