@klarkxy/dsh-zhihu 0.1.7 → 0.1.9

package/README.md

@@ -1,18 +1,24 @@
 # @klarkxy/dsh-zhihu
 
-Zhihu search, answers, knowledge bases, and usage tracking for DSH.
+Zhihu search, answers, question discovery, creator data, knowledge bases, and usage tracking for DSH.
 
-[简体中文](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-zhihu/docs/README.zh-CN.md)
+[简体中文](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/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:
+
+```sh
+npm install @klarkxy/dsh-zhihu
+```
+
+Then load it:
 
 ```sh
 dsh plugin --profile web add @klarkxy/dsh-zhihu
 ```
 
-Restart DSH Web, open **Zhihu resources**, and enter your Access Secret (DSH credential `ZHIHU_ACCESS_TOKEN`). Use the full scoped name; the unscoped `dsh-zhihu` package belongs to another maintainer.
+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`:
 
@@ -22,14 +28,60 @@ To enable agent tools, add this entry to the plugin list in the agent's `agent.c
 
 ## Use
 
-DSH Web provides search, settings, usage, and knowledge-base views. In DSH Editor, open **Settings → Zhihu resources** for configuration, usage, knowledge bases, and a connection test; the agent tools are included.
+DSH Web provides search, settings, usage, and knowledge-base views. Open **Plugins → @klarkxy/dsh-zhihu** for configuration, usage, knowledge bases, and search. Question discovery, creator data, and official quota queries are available through the agent tools and shared RPC service; this update does not add dedicated Web views for them.
+
+Twelve agent tools are available once the tools 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.
+- `zhihu_hot_list`: pull the Zhihu hot list to see current community trends; reference for topics and hotspots only.
+- `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.
+
+### 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.
+
+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.
 
-Search covers Zhihu, the wider web, trending topics, answers, and public knowledge bases. Uploaded reference files are stored in Zhihu's cloud; do not upload unpublished manuscripts.
+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; 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.
+
+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.
 
 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.
 
 ## Development
 
-Read [contracts](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-zhihu/src/contracts.ts) and [tools](https://github.com/klarkxy/dsh-editor/blob/main/packages/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. This sync covers the six question/creator endpoints and official quota, not all upstream CLI/MCP features (such as OAuth management or PDF/PPT tasks).
+
+```sh
+pnpm --filter @klarkxy/dsh-zhihu typecheck
+pnpm --filter @klarkxy/dsh-zhihu test
+pnpm --filter @klarkxy/dsh-zhihu build
+```
+
+[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)
 
-[Publishing](https://github.com/klarkxy/dsh-editor/blob/main/packages/PUBLISHING.md) · [License](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-zhihu/LICENSE)
+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.

package/docs/README.zh-CN.md

@@ -1,18 +1,24 @@
 # @klarkxy/dsh-zhihu
 
-DSH 知乎搜索、直答、知识库与用量插件。
+DSH 知乎搜索、直答、问题发现、创作数据、知识库与用量插件。
 
-[English](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-zhihu/README.md)
+[English](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/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
+```
+
+然后加载：
 
 ```sh
 dsh plugin --profile web add @klarkxy/dsh-zhihu
 ```
 
-重启 DSH Web，打开「知乎资料」填写 Access Secret（DSH 凭据 `ZHIHU_ACCESS_TOKEN`）。请使用完整 scoped 包名；无 scope 的 `dsh-zhihu` 属于其他维护者。
+重启 DSH Web，从「插件」打开「知乎（@klarkxy/dsh-zhihu）」填写 Access Secret（DSH 凭据 `ZHIHU_ACCESS_TOKEN`）。请使用完整 scoped 包名；无 scope 的 `dsh-zhihu` 属于其他维护者。
 
 模型需要使用知乎工具时，在所用 `agent.cordis.yml` 的插件列表加入：
 
@@ -22,7 +28,45 @@ dsh plugin --profile web add @klarkxy/dsh-zhihu
 
 ## 使用
 
-DSH Web 提供搜索、设置、用量与知识库视图。DSH Editor 在「设置 → 知乎资料」配置、查看用量、管理知识库和测试连接，已内置模型工具。
+DSH Web 提供搜索、设置、用量与知识库视图。在「插件 → 知乎（@klarkxy/dsh-zhihu）」配置、查看用量、管理知识库和搜索。问题发现、创作数据与官方额度查询通过模型工具和共享 RPC 服务使用；此次更新不增加这几项能力的独立 Web 页面。
+
+启用 tools 入口后，模型可使用十二个工具。原有五个工具保持兼容：
+
+- `zhihu_search`：知乎站内搜索，拉取社区证据；结果仅作社区/读者反馈参考，不构成 canon，也不直接写入项目文件。
+- `zhihu_global_search`：知乎开放平台全网搜索，检索站外公开网页资料；仅作参考。
+- `zhihu_hot_list`：拉取知乎热榜，了解当前社区热点；仅作题材与热点参考。
+- `zhihu_ask`：调用知乎直答（OpenAI 兼容的 AI 问答），基于知乎社区内容生成综合回答；适合考据与背景调研。
+- `zhihu_knowledge_search`：检索知乎知识库（RAG 片段），默认只查公开库；在知乎网页端上传过个人资料后可加个人/订阅召回范围。
+
+### 问题发现与创作能力
+
+对齐 [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` 为风控拒绝，不是普通限流**，会提示不要立即重试。所有请求均不自动重试；超时和取消覆盖响应正文读取，而不仅是等待响应头。
 
 可查询站内、全网、热榜、直答和公开知识库。上传的参考文件保存在知乎云端，请勿上传未发表手稿。
 
@@ -30,6 +74,14 @@ DSH Web 提供搜索、设置、用量与知识库视图。DSH Editor 在「设
 
 ## 开发
 
-接口见 [contracts](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-zhihu/src/contracts.ts) 与 [tools](https://github.com/klarkxy/dsh-editor/blob/main/packages/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)。此次同步覆盖六个问题发现/创作端点及官方额度，不代表主库的全部 CLI/MCP 能力都已移植；OAuth 管理、PDF/PPT 任务等不在本次范围。
+
+```sh
+pnpm --filter @klarkxy/dsh-zhihu typecheck
+pnpm --filter @klarkxy/dsh-zhihu test
+pnpm --filter @klarkxy/dsh-zhihu build
+```
+
+[发布维护](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)
 
-[发布维护](https://github.com/klarkxy/dsh-editor/blob/main/packages/PUBLISHING.md) · [许可证](https://github.com/klarkxy/dsh-editor/blob/main/packages/dsh-zhihu/LICENSE)
+客户端接收宿主提供的结构化控件，缺失时使用原生 HTML 控件。构建和使用本包不依赖应用私有 UI 包；原有 Agent 工具、凭据、RPC 合同和存储标识保持兼容，上述能力为增量扩展。

package/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none">
+  <defs>
+    <linearGradient id="zbubble" x1="6" y1="6" x2="30" y2="28" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#4D75F5"/>
+      <stop offset="1" stop-color="#8EB6FF"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(3.6 3.6) scale(.8)">
+  <path d="M6 9C6 7.3 7.3 6 9 6H27C28.7 6 30 7.3 30 9V21C30 22.7 28.7 24 27 24H20L13 30V24H9C7.3 24 6 22.7 6 21V9Z" fill="url(#zbubble)"/>
+  <path d="M11 12H25M11 12V19M25 12V19M11 19H25M18 12V19" stroke="#E0EBFF" stroke-width="2" stroke-linecap="round"/>
+  <circle cx="14.5" cy="15.5" r="1.4" fill="#65DED0"/>
+  <circle cx="21.5" cy="15.5" r="1.4" fill="#65DED0"/>
+  </g>
+</svg>