@klarkxy/dsh-zhihu 0.1.9 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +26 -22
  2. package/docs/README.zh-CN.md +26 -22
  3. package/lib/client.js +2012 -887
  4. package/lib/index.d.ts +1 -1
  5. package/lib/index.js +78 -103
  6. package/lib/index.js.map +1 -1
  7. package/lib/open-platform.js +8 -8
  8. package/lib/open-platform.js.map +1 -1
  9. package/lib/tools.js +11 -11
  10. package/lib/tools.js.map +1 -1
  11. package/locale/en.json +6 -0
  12. package/locale/zh.json +6 -0
  13. package/package.json +22 -15
package/README.md CHANGED
@@ -1,36 +1,34 @@
1
1
  # @klarkxy/dsh-zhihu
2
2
 
3
- Zhihu search, answers, question discovery, creator data, knowledge bases, and usage tracking for DSH.
3
+ 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.
4
4
 
5
- [简体中文](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/docs/README.zh-CN.md)
5
+ [简体中文](docs/README.zh-CN.md)
6
+
7
+ Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed.
6
8
 
7
9
  ## Install
8
10
 
9
- Requires Node.js ≥22 and DSH `0.1.7-rc.2`. No repository build is needed. Install:
11
+ Install the published package into the target profile:
10
12
 
11
13
  ```sh
12
- npm install @klarkxy/dsh-zhihu
14
+ dsh plugin --profile web add @klarkxy/dsh-zhihu
13
15
  ```
14
16
 
15
- Then load it:
17
+ Replace `web` with your profile name. 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 uninstall, run `dsh plugin --profile web remove @klarkxy/dsh-zhihu`.
16
18
 
17
- ```sh
18
- dsh plugin --profile web add @klarkxy/dsh-zhihu
19
- ```
19
+ ## Use
20
+
21
+ **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.
20
22
 
21
- 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.
23
+ ## Agent tools
22
24
 
23
- To enable agent tools, add this entry to the plugin list in the agent's `agent.cordis.yml`:
25
+ To enable the agent tools, add this entry to the plugin list in the `agent.cordis.yml` you use:
24
26
 
25
27
  ```yaml
26
28
  - name: '@klarkxy/dsh-zhihu/tools'
27
29
  ```
28
30
 
29
- ## Use
30
-
31
- 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.
32
-
33
- Twelve agent tools are available once the tools entry is enabled. The five existing tools are unchanged:
31
+ Twelve tools are available once that entry is enabled. The five existing tools are unchanged:
34
32
 
35
33
  - `zhihu_search`: search within Zhihu for community evidence; results are community/reader feedback only, never canon, and never written into project files.
36
34
  - `zhihu_global_search`: search the wider web beyond Zhihu through the open platform's global search; reference only.
@@ -56,7 +54,7 @@ The service also accepts upstream-style underscore aliases such as `question_rec
56
54
 
57
55
  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.
58
56
 
59
- 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.
57
+ 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.
60
58
 
61
59
  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.
62
60
 
@@ -68,13 +66,21 @@ Local usage is still tracked as daily counters of calls, failures, and returned
68
66
 
69
67
  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.
70
68
 
71
- 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.
69
+ ## Works with the web search manager
72
70
 
73
- 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.
71
+ When this profile provides `ctx.web`, the plugin registers **Zhihu global search** directly with the host, independently of the search manager. If [@klarkxy/dsh-web-search-manager](https://www.npmjs.com/package/@klarkxy/dsh-web-search-manager) is installed, it discovers the provider for enablement and ordering. Configure the Access Secret in Zhihu settings; the Zhihu plugin resolves it per request and refreshes local availability after credential changes. The dedicated Zhihu tools work independently.
72
+
73
+ ## Boundaries and limits
74
+
75
+ - Search covers Zhihu in-site search, the wider web, the hot list, Zhihu 直答 AI answers, and public knowledge bases.
76
+ - Uploaded reference files are stored in Zhihu's cloud; do not upload unpublished manuscripts.
77
+ - This sync does not cover all upstream CLI/MCP features, such as OAuth identity management or PDF/PPT tasks.
78
+ - The client accepts structural host controls and has native HTML fallbacks. Building or using this package does not require application-private UI packages.
79
+ - Existing agent tools, credentials, RPC contracts and storage identifiers are preserved; the additions above are additive.
74
80
 
75
81
  ## Development
76
82
 
77
- 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).
83
+ 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.
78
84
 
79
85
  ```sh
80
86
  pnpm --filter @klarkxy/dsh-zhihu typecheck
@@ -82,6 +88,4 @@ pnpm --filter @klarkxy/dsh-zhihu test
82
88
  pnpm --filter @klarkxy/dsh-zhihu build
83
89
  ```
84
90
 
85
- [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)
86
-
87
- 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.
91
+ [Publishing](../PUBLISHING.md) · [License](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/LICENSE)
package/docs/README.zh-CN.md CHANGED
@@ -1,24 +1,26 @@
1
1
  # @klarkxy/dsh-zhihu
2
2
 
3
- DSH 知乎搜索、直答、问题发现、创作数据、知识库与用量插件。
3
+ 把知乎交给模型当调研信源：站内搜索、全网搜索、热榜、直答和公开知识库，外加问题发现、创作数据与用量统计。每次请求都只用你自己的知乎 Access Secret，取回的内容是给模型参考的资料，不是定论。
4
4
 
5
- [English](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/README.md)
5
+ [English](../README.md)
6
+
7
+ 需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。
6
8
 
7
9
  ## 安装
8
10
 
9
- 需要 Node.js ≥22、DSH `0.1.7-rc.2`，无需构建本仓库。安装：
11
+ 把已发布包装进目标 profile：
10
12
 
11
13
  ```sh
12
- npm install @klarkxy/dsh-zhihu
14
+ dsh plugin --profile web add @klarkxy/dsh-zhihu
13
15
  ```
14
16
 
15
- 然后加载：
17
+ 把 `web` 换成你的 profile 名。重启 DSH Web，从「插件」打开「知乎（@klarkxy/dsh-zhihu）」填写 Access Secret（DSH 凭据 `ZHIHU_ACCESS_TOKEN`）。请使用完整 scoped 包名；无 scope 的 `dsh-zhihu` 属于其他维护者。卸载用 `dsh plugin --profile web remove @klarkxy/dsh-zhihu`。
16
18
 
17
- ```sh
18
- dsh plugin --profile web add @klarkxy/dsh-zhihu
19
- ```
19
+ ## 使用
20
+
21
+ 「插件 → 知乎（@klarkxy/dsh-zhihu）」下有设置、统计、官方用量、知识库和「测试」分区。「测试」通过一个功能选择框统一选择搜索、问题与创作查询，按所选功能显示对应参数和结果，覆盖问题推荐、回答摘要、本人已发布内容及评论、账号和单篇创作统计。「统计」展示本机记录的每日调用、失败和结果条数；独立的「官方用量」页签在打开时和手动刷新时查询全部官方额度项，以图表和数值展示，不显示原始 JSON。知乎未返回的总量或已用量不自行推算，不同接口类别的数据也不相加。「测试」只保留业务查询，均需手动点击。所有请求都不会自动重试或翻页。原有模型工具和共享 RPC 仍可使用。
20
22
 
21
- 重启 DSH Web，从「插件」打开「知乎（@klarkxy/dsh-zhihu）」填写 Access Secret（DSH 凭据 `ZHIHU_ACCESS_TOKEN`）。请使用完整 scoped 包名；无 scope 的 `dsh-zhihu` 属于其他维护者。
23
+ ## 模型工具
22
24
 
23
25
  模型需要使用知乎工具时，在所用 `agent.cordis.yml` 的插件列表加入：
24
26
 
@@ -26,11 +28,7 @@ dsh plugin --profile web add @klarkxy/dsh-zhihu
26
28
  - name: '@klarkxy/dsh-zhihu/tools'
27
29
  ```
28
30
 
29
- ## 使用
30
-
31
- DSH Web 提供搜索、设置、用量与知识库视图。在「插件 → 知乎（@klarkxy/dsh-zhihu）」配置、查看用量、管理知识库和搜索。问题发现、创作数据与官方额度查询通过模型工具和共享 RPC 服务使用；此次更新不增加这几项能力的独立 Web 页面。
32
-
33
- 启用 tools 入口后，模型可使用十二个工具。原有五个工具保持兼容：
31
+ 加入后，模型可使用十二个工具。原有五个工具保持兼容：
34
32
 
35
33
  - `zhihu_search`：知乎站内搜索，拉取社区证据；结果仅作社区/读者反馈参考，不构成 canon，也不直接写入项目文件。
36
34
  - `zhihu_global_search`：知乎开放平台全网搜索，检索站外公开网页资料；仅作参考。
@@ -56,7 +54,7 @@ RPC 还接受主库风格的下划线别名：`question_recommendations`、`ques
56
54
 
57
55
  省略 `query` 才按当前账号画像推荐；显式空字符串或纯空白主题会被拒绝。推荐不分页。`questionUrl` 必须是 HTTPS `www.zhihu.com/question/{id}` 问题链接。`contentUrl` 仅支持知乎回答、专栏文章、想法或视频链接；创作接口仅查询当前账号已发布的内容，视频仅返回关联正文，不返回视频文件。
58
56
 
59
- 分页工具的 `offset` 使用非负 Int64 **十进制字符串**，默认 `"0"`；RPC 也接受 JavaScript 安全整数。`limit` 为 1–50 的整数，默认 20。每次只取一页，只有 `paging.canContinue=true` 才使用其 `nextOffset` 继续。空页或条目不足不能视为结束；`NextOffset` 缺失、无效、未前进或为不安全的数值时，返回警告并停止翻页，不按条目数补偏移。`Totals` 可能包含被过滤的回答；`Summary` 是上游摘要/截取文本，不是全文，也不是额外生成的 AI 摘要。评论附带的 `Children` 不保证完整。
57
+ 分页工具的 `offset` 使用非负 Int64 **十进制字符串**，默认 `"0"`；RPC 也接受 JavaScript 安全整数。`limit` 为 1–50 的整数，默认 20。每次只取一页，只有 `paging.canContinue=true` 才原样使用其 `nextOffset` 继续。空页或条目不足不能视为结束；`NextOffset` 缺失、无效、未前进或为不安全的数值时，返回警告并停止翻页，不按条目数补偏移。`Totals` 可能包含被过滤的回答；`Summary` 是上游摘要/截取文本，不是全文，也不是额外生成的 AI 摘要。评论附带的 `Children` 不保证完整。
60
58
 
61
59
  统计日期 `startDate` / `endDate` 必须同时提供或同时省略，格式为有效公历 `YYYY-MM-DD`，结束日期不得早于开始日期。省略时采用上游默认范围，不自行指定天数。缺失指标不补零，比例不换算百分比。新增结果包含 `version`、`operation`、`data`、可选 `quotaId` 与安全分页信息 `paging`。结构化 `data` 保留上游字段及原始 HTML；工具展示清洗 HTML 后放入不会执行的文本代码块。缺少或为空的 `Body` 不能视为全文。
62
60
 
@@ -66,15 +64,23 @@ RPC 还接受主库风格的下划线别名：`question_recommendations`、`ques
66
64
 
67
65
  本地用量仍按日计数（调用次数、失败次数与成功调用返回的条目数），视图默认展示最近 30 天，最多可查 90 天。新增业务工具与 RPC 每次调用只记录一次事件，并带有额度分类；本地计数不是账单，也不是官方余额。存储标识保持不变。知识库上传单文件上限仍为 20 MB。
68
66
 
69
- 业务错误保留上游消息与错误码，即使 HTTP 状态为失败。RPC 的 `error.details` 可包含 `status`、`upstreamCode`、`retryAfter`（秒）和 `retryable`。`30001` / `30002` 为频率或额度限制；**`30003` 为风控拒绝，不是普通限流**，会提示不要立即重试。所有请求均不自动重试；超时和取消覆盖响应正文读取，而不仅是等待响应头。
67
+ 业务错误保留上游消息与错误码，即使 HTTP 状态为失败。RPC 的 `error.details` 可包含 `status`、`upstreamCode`、`retryAfter`（秒）和 `retryable`。`30001` / `30002` 为频率或额度限制；**`30003` 为风控拒绝，不是普通限流**，会提示不要立即重试。所有请求均不自动重试；超时和取消覆盖响应正文读取，而不只是等待响应头。
70
68
 
71
- 可查询站内、全网、热榜、直答和公开知识库。上传的参考文件保存在知乎云端，请勿上传未发表手稿。
69
+ ## 与网络搜索联动
72
70
 
73
- 同一 profile 还安装 [@klarkxy/dsh-web-search-manager](https://www.npmjs.com/package/@klarkxy/dsh-web-search-manager) 时，本插件会向网络搜索注册「知乎全网搜索」后端。在网络搜索设置中启用它，即可让通用网络搜索工具使用知乎的全网搜索能力，并共用「知乎资料」中配置的 Access Secret。专用知乎工具仍可独立使用。
71
+ 同一 profile 提供 `ctx.web` 时，本插件直接向宿主注册「知乎全网搜索」，无需安装搜索管理器。安装 [@klarkxy/dsh-web-search-manager](https://www.npmjs.com/package/@klarkxy/dsh-web-search-manager) 后，管理器会自动发现它，可在那里启用并排序。Access Secret 仍在「知乎资料」中配置，每次请求由知乎插件读取，凭据变更会刷新本地可用状态。专用知乎工具仍可独立使用。
72
+
73
+ ## 边界与限制
74
+
75
+ - 可查询站内、全网、热榜、直答和公开知识库。
76
+ - 上传的参考文件保存在知乎云端，请勿上传未发表手稿。
77
+ - 此次同步不代表主库的全部 CLI/MCP 能力都已移植；OAuth 身份管理、PDF/PPT 任务等不在本次范围。
78
+ - 客户端接收宿主提供的结构化控件，缺失时使用原生 HTML 控件。构建和使用本包不依赖应用私有 UI 包。
79
+ - 原有 Agent 工具、凭据、RPC 合同和存储标识保持兼容，上述能力为增量扩展。
74
80
 
75
81
  ## 开发
76
82
 
77
- 接口见 [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 任务等不在本次范围。
83
+ 接口见 [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)。七个新增接口覆盖六个问题发现/创作端点及官方额度。
78
84
 
79
85
  ```sh
80
86
  pnpm --filter @klarkxy/dsh-zhihu typecheck
@@ -82,6 +88,4 @@ pnpm --filter @klarkxy/dsh-zhihu test
82
88
  pnpm --filter @klarkxy/dsh-zhihu build
83
89
  ```
84
90
 
85
- [发布维护](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)
86
-
87
- 客户端接收宿主提供的结构化控件，缺失时使用原生 HTML 控件。构建和使用本包不依赖应用私有 UI 包；原有 Agent 工具、凭据、RPC 合同和存储标识保持兼容，上述能力为增量扩展。
91
+ [发布维护](../../PUBLISHING.md) · [许可证](https://github.com/klarkxy/dsh-plugins/blob/main/plugins/dsh-zhihu/LICENSE)