dsh-zhihu-search 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zlZayn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# dsh-zhihu-search
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](.node-version)
+[![DSH](https://img.shields.io/badge/DSH-0.1.5--rc.2-blue.svg)](package.json)
+
+给 DSH 装上知乎：站内检索、全网检索与直答三个工具，返回可引用的来源列表，而不是一段无法核对的摘要。
+
+![插件配置页中的「知乎搜索」卡片](https://raw.githubusercontent.com/zlZayn/dsh-zhihu-search/main/docs/images/settings-card.png)
+
+*在 **设置 → 插件 → 插件配置** 中与其他插件并排，Access Secret 就地填写、立即生效。*
+
+## 能力
+
+- 检索知乎站内问答与文章：按点赞数、评论数或更新时间排序，可按发布时间范围过滤。
+- 检索知乎索引中的公开网页：按站点域名与发布时间过滤。
+- 调用知乎直答：快问快答、深度思考、智能体三个档位。
+- 相同查询在缓存 TTL 内复用结果，减少每日额度消耗。
+- 本地令牌桶在额度之外再兜一层，约束单轮对话内的突发请求。
+- 搜索结果显示为带作者与点赞数的来源卡片，同时保留纯 Markdown 回退。
+
+## 安装
+
+### 前置
+
+- DSH `0.1.5-rc.2`
+- Node `>= 20`
+
+### 从源码安装
+
+```bash
+git clone https://github.com/zlZayn/dsh-zhihu-search.git
+cd dsh-zhihu-search
+npm install && npm run build
+
+dsh plugin --profile web add "$PWD"
+```
+
+`dsh plugin` 会把本包装进 profile 并挂进 `dsh.profile.bundles`。重启 `dsh web` 后生效。
+
+### 从 npm 安装
+
+```bash
+dsh plugin --profile web add dsh-zhihu-search
+```
+
+## 配置
+
+### 在设置界面填写
+
+打开 **设置 → 插件 → 插件配置 → 知乎搜索**，填入 Access Secret 并保存。保存后立即生效，无需重启 DSH。
+
+Access Secret 在知乎开放平台的[个人中心](https://developer.zhihu.com/profile)获取。
+
+### 用环境变量代替
+
+不想把密钥存在设置里时，改用环境变量 `ZHIHU_ACCESS_SECRET`；或在卡片的「凭据引用名」里填别的名字，指向另一个环境变量或凭据记录。
+
+## 安全与边界
+
+- Access Secret 只在设置界面、凭据域与环境变量之间流转：不写日志、不以明文进入缓存键、不进仓库。
+- 返回内容按外部不可信数据处理：摘要剥离 HTML 标签，链接剥离跟踪参数。
+- 只访问 `developer.zhihu.com`，不代理、不转发其他流量。
+
+## 许可
+
+[MIT](LICENSE)。
+
+## 贡献
+
+维护者文档地图见 [AGENTS.md](AGENTS.md)；不变的设计约束见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)；发布流程见 [docs/PUBLISHING.md](docs/PUBLISHING.md)。

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh-zhihu-search bundle patch —— 把本插件作为一行插入 dsh profile。
+#
+# 格式对齐 DSH 官方 bundle patch（见 @deepseek-ai/dsh-base/cordis.patch.yml）：
+# 顶层是 loader patch 条目数组；`insert` 在 profile 根上追加插件行。
+#
+# 关于 name：必须是 loader 能从 profile 的 node_modules 解析到的模块 id，即本包自身的包名。
+#
+# 关于 config：**刻意不写 accessSecret**。写了空串会让设置卡片的「已配置」判据
+# （DSH 的 RedactedSecret.set = value !== undefined）把空串当成已设值，卡片一打开就显示
+# 「已配置」，而实际没有任何密钥。密钥应当只从设置界面写入。
+- insert:
+    - id: dsh-zhihu-search
+      name: dsh-zhihu-search

package/lib/client.js

@@ -0,0 +1,308 @@
+window.__ModuleLoader__.load({
+	id: "dsh-zhihu-search",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client/index.tsx
+var client_exports = {};
+__export(client_exports, {
+  apply: () => apply,
+  inject: () => inject,
+  readConfigured: () => readConfigured
+});
+module.exports = __toCommonJS(client_exports);
+var import_react = require("react");
+var import_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+var import_jsx_runtime = require("react/jsx-runtime");
+var inject = ["slots", "settingsScope"];
+var NAMESPACE = "zhihu-search";
+var SECRET_FIELD = "accessSecret";
+var REF_FIELD = "accessSecretRef";
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : void 0;
+}
+function readConfigured(mirror) {
+  const view = mirror.getSnapshot().view?.namespaces.find((row) => row.ns === NAMESPACE);
+  const slot = view?.secrets?.find(
+    (entry) => entry.path.length === 1 && entry.path[0] === SECRET_FIELD
+  );
+  return slot?.set === true;
+}
+var S = {
+  card: {
+    listStyle: "none",
+    border: "0.5px solid var(--dsw-alias-border-l4)",
+    borderRadius: 16,
+    background: "var(--dsw-alias-bg-layer-3)",
+    transition: "border-color .16s, background .16s"
+  },
+  cardOpen: {
+    listStyle: "none",
+    border: "0.5px solid var(--dsw-alias-label-dimmed)",
+    borderRadius: 16,
+    background: "var(--dsw-alias-bg-layer-2)",
+    transition: "border-color .16s, background .16s"
+  },
+  header: {
+    width: "100%",
+    appearance: "none",
+    border: 0,
+    background: "none",
+    font: "inherit",
+    color: "inherit",
+    textAlign: "left",
+    cursor: "pointer",
+    display: "flex",
+    alignItems: "center",
+    gap: 12,
+    padding: "14px 16px",
+    borderRadius: 12
+  },
+  headText: { flex: 1, minWidth: 0, display: "flex", flexDirection: "column", gap: 4 },
+  name: { fontSize: 15, fontWeight: 600, lineHeight: 1.4, color: "var(--dsw-alias-label-primary)" },
+  description: { fontSize: 13, lineHeight: 1.5, color: "var(--dsw-alias-label-tertiary)" },
+  chevron: { flex: "none", color: "var(--dsw-alias-label-tertiary)", transition: "transform .16s" },
+  chevronOpen: { flex: "none", color: "var(--dsw-alias-label-tertiary)", transform: "rotate(180deg)", transition: "transform .16s" },
+  body: { borderTop: "0.5px solid var(--dsw-alias-border-l2)", margin: "0 16px", paddingBottom: 8 },
+  readOnly: { margin: "12px 0 0", fontSize: 12, lineHeight: 1.5, color: "var(--dsw-alias-label-tertiary)" },
+  field: { display: "flex", flexDirection: "column", gap: 6, padding: "12px 0" },
+  fieldDivider: { display: "flex", flexDirection: "column", gap: 6, padding: "12px 0", borderTop: "0.5px solid var(--dsw-alias-border-l2)" },
+  head: { display: "flex", alignItems: "center", gap: 8 },
+  label: { flex: 1, minWidth: 0, fontSize: 13, fontWeight: 500, lineHeight: 1.5, color: "var(--dsw-alias-label-primary)" },
+  badges: { display: "inline-flex", alignItems: "center", gap: 8 },
+  reset: {
+    border: "none",
+    background: "none",
+    padding: 0,
+    font: "inherit",
+    fontSize: 12,
+    lineHeight: 1.5,
+    color: "var(--dsw-alias-label-secondary)",
+    cursor: "pointer"
+  },
+  input: {
+    height: 34,
+    padding: "0 12px",
+    border: "0.5px solid var(--dsw-alias-border-l4)",
+    borderRadius: 8,
+    background: "var(--dsw-alias-bg-layer-3)",
+    font: "inherit",
+    fontSize: 13,
+    lineHeight: 1.5,
+    color: "var(--dsw-alias-label-primary)",
+    boxSizing: "border-box",
+    width: "100%"
+  },
+  hint: { margin: 0, fontSize: 12, lineHeight: 1.5, color: "var(--dsw-alias-label-tertiary)" },
+  footer: {
+    display: "flex",
+    alignItems: "center",
+    justifyContent: "flex-end",
+    gap: 8,
+    padding: "12px 0 4px",
+    borderTop: "0.5px solid var(--dsw-alias-border-l2)"
+  },
+  failed: { flex: 1, minWidth: 0, margin: 0, fontSize: 12, lineHeight: 1.5, color: "var(--dsw-alias-label-error)" },
+  discard: {
+    appearance: "none",
+    border: "1px solid var(--dsw-alias-border-l2)",
+    borderRadius: 8,
+    padding: "5px 14px",
+    font: "inherit",
+    fontSize: 13,
+    lineHeight: 1.5,
+    cursor: "pointer",
+    background: "none",
+    color: "var(--dsw-alias-label-secondary)"
+  },
+  save: {
+    appearance: "none",
+    border: "1px solid transparent",
+    borderRadius: 8,
+    padding: "5px 14px",
+    font: "inherit",
+    fontSize: 13,
+    lineHeight: 1.5,
+    cursor: "pointer",
+    background: "var(--dsw-alias-label-primary)",
+    color: "var(--dsw-alias-bg-layer-3)"
+  }
+};
+function dimStyle(base, disabled) {
+  return disabled ? { ...base, opacity: 0.4, cursor: "default" } : base;
+}
+function ZhihuCard({ scope, mirror }) {
+  const snapshot = (0, import_react.useSyncExternalStore)(
+    (onChange) => scope.subscribe(onChange),
+    () => scope.getSnapshot()
+  );
+  const configured = (0, import_react.useSyncExternalStore)(
+    (onChange) => mirror.subscribe(onChange),
+    () => readConfigured(mirror)
+  );
+  const [open, setOpen] = (0, import_react.useState)(false);
+  const [secret, setSecret] = (0, import_react.useState)("");
+  const [refDraft, setRefDraft] = (0, import_react.useState)(void 0);
+  const [saving, setSaving] = (0, import_react.useState)(false);
+  const [failed, setFailed] = (0, import_react.useState)("");
+  const writable = snapshot.writable && snapshot.status === "ready";
+  const disabled = !writable || saving;
+  const effectiveRef = typeof snapshot.value?.[REF_FIELD] === "string" ? snapshot.value[REF_FIELD] : "";
+  const refText = refDraft ?? effectiveRef;
+  const refOverridden = asRecord(snapshot.user)?.[REF_FIELD] !== void 0;
+  const refDirty = refText !== effectiveRef;
+  const dirty = secret !== "" || refDirty;
+  const blocked = !dirty || disabled;
+  const discard = () => {
+    setSecret("");
+    setRefDraft(void 0);
+    setFailed("");
+  };
+  const save = async () => {
+    setSaving(true);
+    setFailed("");
+    try {
+      if (secret !== "") await scope.set(SECRET_FIELD, secret);
+      if (refDirty) {
+        if (refText === "") await scope.unset(REF_FIELD);
+        else await scope.set(REF_FIELD, refText);
+      }
+      setSecret("");
+      setRefDraft(void 0);
+      setOpen(false);
+    } catch (error) {
+      setFailed(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSaving(false);
+    }
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("li", { style: open ? S.cardOpen : S.card, children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+      "button",
+      {
+        type: "button",
+        style: S.header,
+        "aria-expanded": open,
+        onClick: () => {
+          setOpen(!open);
+        },
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { style: S.headText, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: S.name, children: "\u77E5\u4E4E\u641C\u7D22" }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: S.description, children: "\u77E5\u4E4E\u5F00\u653E\u5E73\u53F0\u7684\u7AD9\u5185\u68C0\u7D22\u3001\u5168\u7F51\u68C0\u7D22\u4E0E\u76F4\u7B54\u5DE5\u5177\u3002" })
+          ] }),
+          dirty ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.Tag, { tone: "neutral", children: "\u672A\u4FDD\u5B58" }) : null,
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: open ? S.chevronOpen : S.chevron, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.IconChevronDownOutline14, {}) })
+        ]
+      }
+    ),
+    open ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: S.body, children: [
+      !writable && snapshot.status !== "loading" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: S.readOnly, role: "status", children: "\u5F53\u524D\u8FDE\u63A5\u4E0D\u5141\u8BB8\u5199\u5165\u8BBE\u7F6E\u3002" }) : null,
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: S.field, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: S.head, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { style: S.label, htmlFor: "zhihu-access-secret", children: "Access Secret" }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: S.badges, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.Tag, { tone: configured ? "neutral" : "quiet", children: configured ? "\u5DF2\u914D\u7F6E" : "\u672A\u914D\u7F6E" }) })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            id: "zhihu-access-secret",
+            style: S.input,
+            type: "password",
+            autoComplete: "off",
+            value: secret,
+            disabled,
+            onChange: (event) => {
+              setSecret(event.target.value);
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: S.hint, children: "\u5728 developer.zhihu.com \u4E2A\u4EBA\u4E2D\u5FC3\u83B7\u53D6\u3002\u7559\u7A7A\u5219\u4E0D\u4FEE\u6539\u5DF2\u4FDD\u5B58\u7684\u5BC6\u94A5\u3002" })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: S.fieldDivider, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: S.head, children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("label", { style: S.label, htmlFor: "zhihu-access-secret-ref", children: "\u51ED\u636E\u5F15\u7528\u540D" }),
+          refOverridden ? /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { style: S.badges, children: [
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_dsh_client_ui_primitives.Tag, { tone: "neutral", children: "\u5DF2\u8986\u76D6" }),
+            /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              "button",
+              {
+                type: "button",
+                style: dimStyle(S.reset, disabled),
+                disabled,
+                onClick: () => {
+                  setRefDraft("");
+                },
+                children: "\u91CD\u7F6E"
+              }
+            )
+          ] }) : null
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            id: "zhihu-access-secret-ref",
+            style: S.input,
+            type: "text",
+            spellCheck: false,
+            value: refText,
+            disabled,
+            onChange: (event) => {
+              setRefDraft(event.target.value);
+            }
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: S.hint, children: "\u73AF\u5883\u53D8\u91CF\u6216\u51ED\u636E\u8BB0\u5F55\u7684\u540D\u5B57\uFF1B\u7559\u7A7A\u5E76\u4FDD\u5B58\u4F1A\u6E05\u6389\u8986\u76D6\uFF0C\u56DE\u843D\u5230\u9ED8\u8BA4\u7684 ZHIHU_ACCESS_SECRET\u3002" })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: S.footer, children: [
+        failed !== "" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { style: S.failed, role: "status", children: failed }) : null,
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", style: dimStyle(S.discard, !dirty || saving), disabled: !dirty || saving, onClick: discard, children: "\u653E\u5F03" }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "button",
+          {
+            type: "button",
+            style: dimStyle(S.save, blocked),
+            disabled: blocked,
+            onClick: () => {
+              void save();
+            },
+            children: saving ? "\u4FDD\u5B58\u4E2D\u2026" : "\u4FDD\u5B58"
+          }
+        )
+      ] })
+    ] }) : null
+  ] });
+}
+function apply(ctx) {
+  const scope = ctx.settingsScope.bind({ namespace: NAMESPACE });
+  const mirror = ctx.settingsScope.describe();
+  ctx.slots.inject(
+    "settings.plugin.item",
+    () => ctx.slots.register(
+      { name: "settings.plugin.item", key: NAMESPACE },
+      () => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ZhihuCard, { scope, mirror })
+    )
+  );
+}
+		return module.exports;
+	}
+});

package/lib/credentials.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Access Secret 的解析：三条来源、固定优先级、可单测。
+ *
+ * 为什么独立成模块：优先级是**契约**而不是实现细节 ——
+ * 设置界面填的值、凭据记录、环境变量三者谁赢，直接决定用户改了设置为什么不生效。
+ * 写在 `apply()` 的闭包里就没法单测，而这类问题只在真机上暴露。
+ */
+/** 解析所需的三条来源。全部是函数，因为密钥可以在运行期被改动。 */
+export interface SecretSources {
+    /** 凭据域查询。返回空白串按「未配置」处理。 */
+    readonly fromCredentials: (reference: string) => Promise<string | undefined>;
+    /** 设置 section 里由用户直接填写的值。 */
+    readonly fromSettings: () => string | undefined;
+    /** 环境变量查询。 */
+    readonly fromEnvironment: (name: string) => string | undefined;
+    /** 凭据引用名（默认 `ZHIHU_ACCESS_SECRET`）。 */
+    readonly referenceName: () => string;
+}
+/**
+ * 按固定优先级解析 Access Secret。
+ *
+ * 优先级：**凭据域 → 设置 section → 环境变量**。
+ * 凭据域排在第一位，是因为它是设置界面与凭据记录的落点；
+ * 排在它前面的任何来源都会让「我在设置里填了却不生效」变成一个真实故障。
+ *
+ * @param sources - 三条来源。
+ * @returns 可用的密钥；三条都空时返回 `undefined`，由调用方转成鉴权错误。
+ */
+export declare function resolveAccessSecret(sources: SecretSources): Promise<string | undefined>;
+//# sourceMappingURL=credentials.d.ts.map

package/lib/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,QAAQ,CAAC,eAAe,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7E,6BAA6B;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IAChD,cAAc;IACd,QAAQ,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/D,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,MAAM,CAAC;CACtC;AAOD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAa7F"}

package/lib/credentials.js

@@ -0,0 +1,35 @@
+/**
+ * Access Secret 的解析：三条来源、固定优先级、可单测。
+ *
+ * 为什么独立成模块：优先级是**契约**而不是实现细节 ——
+ * 设置界面填的值、凭据记录、环境变量三者谁赢，直接决定用户改了设置为什么不生效。
+ * 写在 `apply()` 的闭包里就没法单测，而这类问题只在真机上暴露。
+ */
+/** 判定一个候选值是否可用：必须是含非空白字符的字符串。 */
+function usable(value) {
+    return value !== undefined && value.trim() !== '';
+}
+/**
+ * 按固定优先级解析 Access Secret。
+ *
+ * 优先级：**凭据域 → 设置 section → 环境变量**。
+ * 凭据域排在第一位，是因为它是设置界面与凭据记录的落点；
+ * 排在它前面的任何来源都会让「我在设置里填了却不生效」变成一个真实故障。
+ *
+ * @param sources - 三条来源。
+ * @returns 可用的密钥；三条都空时返回 `undefined`，由调用方转成鉴权错误。
+ */
+export async function resolveAccessSecret(sources) {
+    const reference = sources.referenceName();
+    const fromCredentials = await sources.fromCredentials(reference);
+    if (usable(fromCredentials))
+        return fromCredentials;
+    const fromSettings = sources.fromSettings();
+    if (usable(fromSettings))
+        return fromSettings;
+    const fromEnvironment = sources.fromEnvironment(reference);
+    if (usable(fromEnvironment))
+        return fromEnvironment;
+    return undefined;
+}
+//# sourceMappingURL=credentials.js.map

package/lib/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,iCAAiC;AACjC,SAAS,MAAM,CAAC,KAAyB;IACvC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AACpD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAsB;IAC9D,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAE1C,MAAM,eAAe,GAAG,MAAM,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;IACjE,IAAI,MAAM,CAAC,eAAe,CAAC;QAAE,OAAO,eAAe,CAAC;IAEpD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAC5C,IAAI,MAAM,CAAC,YAAY,CAAC;QAAE,OAAO,YAAY,CAAC;IAE9C,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,eAAe,CAAC;QAAE,OAAO,eAAe,CAAC;IAEpD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * dsh-zhihu-search 插件入口。
+ *
+ * 本文件是**唯一**接触 Cordis 的地方：生命周期、配置校验、设置命名空间、工具注册。
+ * 工具实现本身不依赖 Cordis，因此可以用普通对象直接单测。
+ *
+ * 生命周期纪律（红线 4）：
+ * 客户端与全部状态（缓存、令牌桶）都在 `ctx.effect()` 内创建，
+ * 由返回的 disposer 释放。模块顶层**不持有任何可变状态** ——
+ * 否则 HMR 重载后会留下两代插件共用缓存与限流桶的幽灵故障。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Cordis 插件名，用于 loader 诊断。 */
+export declare const name = "zhihu-search";
+/** 本插件依赖的工具注册表服务。 */
+export declare const inject: string[];
+/**
+ * 设置命名空间。
+ *
+ * 同时是 client 半体注册设置卡片时的 `key`：官方「插件」设置页按命名空间
+ * 分派卡片，两端必须用同一个字符串，否则卡片不会被渲染。
+ */
+export declare const ZHIHU_SETTINGS_NAMESPACE = "zhihu-search";
+/** 凭据引用的默认名，按 DSH 约定取环境变量名。 */
+export declare const DEFAULT_ACCESS_SECRET_REF = "ZHIHU_ACCESS_SECRET";
+/** 插件配置。 */
+export interface Config {
+    /**
+     * 字面量 Access Secret。
+     *
+     * `role('secret')` 让设置界面把它渲染成掩码输入框，并在下行描述里隐藏其值。
+     * 留空时回落到 {@link Config.accessSecretRef} 指向的凭据记录。
+     */
+    accessSecret?: string;
+    /** 凭据引用名（环境变量名或凭据记录名）。 */
+    accessSecretRef?: string;
+    /** 覆盖接入域名，便于指向沙箱或代理。 */
+    baseUrl?: string;
+    /** 单次 HTTP 请求的超时预算（毫秒）。 */
+    timeoutMs?: number;
+    /** 搜索结果缓存存活时长（毫秒）。 */
+    cacheTtlMs?: number;
+    /** 搜索结果缓存条目上限。 */
+    cacheMaxEntries?: number;
+    /** 搜索类工具的本地每分钟上限（知乎额度之外的额外保护）。 */
+    searchPerMinute?: number;
+    /** 直答的本地每分钟上限。 */
+    zhidaPerMinute?: number;
+    /** 是否注册站内搜索工具。 */
+    enableSearch?: boolean;
+    /** 是否注册全网搜索工具。 */
+    enableGlobalSearch?: boolean;
+    /** 是否注册直答工具。 */
+    enableZhida?: boolean;
+}
+/** 配置的运行时校验 schema；默认值同时是文档。 */
+export declare const Config: z<Schemastery.ObjectS<{
+    accessSecret: z<string, string>;
+    accessSecretRef: z<string, string>;
+    baseUrl: z<string, string>;
+    timeoutMs: z<number, number>;
+    cacheTtlMs: z<number, number>;
+    cacheMaxEntries: z<number, number>;
+    searchPerMinute: z<number, number>;
+    zhidaPerMinute: z<number, number>;
+    enableSearch: z<boolean, boolean>;
+    enableGlobalSearch: z<boolean, boolean>;
+    enableZhida: z<boolean, boolean>;
+}>, Schemastery.ObjectT<{
+    accessSecret: z<string, string>;
+    accessSecretRef: z<string, string>;
+    baseUrl: z<string, string>;
+    timeoutMs: z<number, number>;
+    cacheTtlMs: z<number, number>;
+    cacheMaxEntries: z<number, number>;
+    searchPerMinute: z<number, number>;
+    zhidaPerMinute: z<number, number>;
+    enableSearch: z<boolean, boolean>;
+    enableGlobalSearch: z<boolean, boolean>;
+    enableZhida: z<boolean, boolean>;
+}>>;
+/**
+ * 注册插件：创建状态与客户端，注册设置命名空间，并按配置注册各工具。
+ *
+ * @param ctx - Cordis 上下文，其 `tools` 注册表接收工具定义。
+ * @param config - 已由 {@link Config} 校验并填充默认值的配置。
+ */
+export declare function apply(ctx: Context, config: Config): void;
+export { ZHIHU_BASE_URL, ZhihuClient } from './transport.js';
+export { resolveAccessSecret } from './credentials.js';
+export type { SecretSources } from './credentials.js';
+export { createState, LocalRateLimitError, MemoryCache, TokenBucket } from './state.js';
+export { compileFilter, compileSortBy, CompileError } from './utils/compiler.js';
+export type { ZhidaOutput, SearchOutput } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,CAAC,MAAM,0BAA0B,CAAC;AASzC,+BAA+B;AAC/B,eAAO,MAAM,IAAI,iBAAiB,CAAC;AAEnC,qBAAqB;AACrB,eAAO,MAAM,MAAM,UAAY,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,iBAAiB,CAAC;AAEvD,+BAA+B;AAC/B,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,YAAY;AACZ,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sBAAsB;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kBAAkB;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kCAAkC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,kBAAkB;IAClB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gBAAgB;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,gCAAgC;AAChC,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;GAcjB,CAAC;AAwBH;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA8FxD;AAED,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACjF,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}