@klarkxy/dsh-zhihu 0.1.8 → 0.1.10

package/lib/open-platform.js

@@ -0,0 +1,687 @@
+import { ZHIHU_QUOTA_IDS } from "./contracts.js";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+//#region src/zhihu-client.ts
+/**
+* 知乎开放平台共享请求层:Access Secret 解析、超时封装、信封解析与执行计量。
+*
+* 端点规范（来源：github.com/klarkxy/zhihu-search，src/zhihu_search/upstream/http_client.py）：
+*   - Base URL: https://developer.zhihu.com
+*   - 公共 Headers: Authorization: Bearer <access_secret>、X-Request-Timestamp、Accept
+*   - 除直答外的 REST 接口返回 {Code, Message, Data} 信封,Code 非 0 表示业务错误。
+*
+* Token 解析顺序（按契约,**不**把 token 放进 schema 参数）：
+*   1. 可选的 credential 解析器（应用设置界面写入 `ZHIHU_ACCESS_TOKEN` 后,
+*      通过 `ctx.credentials.resolve` 取回）;命中即返回,source 标记为 `credential`。
+*   2. 环境变量 ZHIHU_ACCESS_TOKEN
+*   3. 环境变量 ZHIHU_ACCESS_SECRET（zhihu-search CLI 同名变量）
+*   4. ~/.config/zhihu-search/credentials.json 的 access_secret 字段
+* 都没有则抛出带中文配置指引的 TOKEN_MISSING。
+*/
+const ZHIHU_BASE_URL = "https://developer.zhihu.com";
+const ZHIHU_DEFAULT_TIMEOUT_MS = 15e3;
+const ZHIHU_CREDENTIALS_PRIMARY = "ZHIHU_ACCESS_TOKEN";
+const ZHIHU_CREDENTIALS_FALLBACK = "ZHIHU_ACCESS_SECRET";
+const ZHIHU_CREDENTIALS_FILE = join(homedir(), ".config", "zhihu-search", "credentials.json");
+const globalFetch = typeof globalThis !== "undefined" && typeof globalThis.fetch === "function" ? (input, init) => {
+	const f = globalThis.fetch;
+	return f(input, init);
+} : void 0;
+function looksLikeToken(value) {
+	const trimmed = value.trim();
+	return trimmed.length >= 8 && trimmed.length <= 256;
+}
+async function readCredentialsFile(path) {
+	try {
+		const raw = await readFile(path, "utf8");
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && typeof parsed.access_secret === "string" && looksLikeToken(parsed.access_secret)) return parsed.access_secret.trim();
+	} catch {}
+}
+async function resolveZhihuToken(env = process.env, options = {}) {
+	if (options.resolveCredential) {
+		const fromCredential = (await options.resolveCredential())?.trim();
+		if (fromCredential && looksLikeToken(fromCredential)) return {
+			token: fromCredential,
+			source: "credential"
+		};
+	}
+	const primary = env[ZHIHU_CREDENTIALS_PRIMARY]?.trim();
+	if (primary && looksLikeToken(primary)) return {
+		token: primary,
+		source: "env-primary"
+	};
+	const fallback = env[ZHIHU_CREDENTIALS_FALLBACK]?.trim();
+	if (fallback && looksLikeToken(fallback)) return {
+		token: fallback,
+		source: "env-fallback"
+	};
+	const fromFile = await readCredentialsFile(ZHIHU_CREDENTIALS_FILE);
+	if (fromFile) return {
+		token: fromFile,
+		source: "file"
+	};
+	throw new ZhihuSearchError("TOKEN_MISSING", ["未找到知乎 Access Secret。请在「设置 → 知乎」中填写；", `也可设置环境变量 ${ZHIHU_CREDENTIALS_PRIMARY} 或写入 ~/.config/zhihu-search/credentials.json。`].join(""));
+}
+var ZhihuSearchError = class extends Error {
+	code;
+	status;
+	upstreamCode;
+	retryAfter;
+	retryable;
+	constructor(code, message, status, details = {}) {
+		super(message);
+		this.name = "ZhihuSearchError";
+		this.code = code;
+		if (status !== void 0) this.status = status;
+		if (details.upstreamCode !== void 0) this.upstreamCode = details.upstreamCode;
+		if (details.retryAfter !== void 0) this.retryAfter = details.retryAfter;
+		if (details.retryable !== void 0) this.retryable = details.retryable;
+	}
+};
+/** Metering must never break the tool itself. */
+function reportExecuted(hook, event) {
+	if (!hook) return;
+	try {
+		hook(event);
+	} catch {}
+}
+function isAbortError(error) {
+	if (error instanceof Error && error.name === "AbortError") return true;
+	return typeof error === "object" && error !== null && error.name === "AbortError";
+}
+/** Parse Retry-After seconds or an HTTP date; never invent a quota reset time. */
+function parseZhihuRetryAfter(value, now = Date.now()) {
+	if (!value?.trim()) return void 0;
+	const text = value.trim();
+	if (/^\d+(?:\.\d+)?$/.test(text)) {
+		const seconds = Number(text);
+		return Number.isFinite(seconds) ? Math.ceil(seconds) : void 0;
+	}
+	if (!/[a-z]/i.test(text)) return void 0;
+	const date = Date.parse(text);
+	return Number.isFinite(date) ? Math.max(0, Math.ceil((date - now) / 1e3)) : void 0;
+}
+/**
+* Shared authenticated request. envelope=true opts into official error semantics
+* and returns Data. Legacy callers still receive the full JSON / chat response.
+* The timeout and cancellation cover BOTH headers and response-body consumption.
+* No requests are retried, including 429, exhausted quota, or risk-control denial.
+*/
+async function zhihuFetchJson(path, init, label, options = {}) {
+	const linked = options.signal;
+	if (linked?.aborted) throw new ZhihuSearchError("CANCELLED", "请求已取消");
+	const url = new URL(path, ZHIHU_BASE_URL);
+	if (url.origin !== "https://developer.zhihu.com" || url.username || url.password) throw new ZhihuSearchError("INVALID_ARGUMENTS", "只允许请求知乎开放平台。");
+	for (const [key, value] of Object.entries(init.params ?? {})) url.searchParams.set(key, value);
+	const token = await resolveZhihuToken(options.env, { resolveCredential: options.resolveCredential });
+	if (linked?.aborted) throw new ZhihuSearchError("CANCELLED", "请求已取消");
+	const fetcher = options.fetcher ?? globalFetch;
+	if (!fetcher) throw new ZhihuSearchError("BAD_RESPONSE", "当前环境没有可用的 fetch。");
+	const method = init.method ?? (init.formData || init.body !== void 0 ? "POST" : "GET");
+	const timeout = options.timeoutMs !== void 0 && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : ZHIHU_DEFAULT_TIMEOUT_MS;
+	const controller = new AbortController();
+	const onAbort = () => controller.abort(linked?.reason);
+	if (linked?.aborted) onAbort();
+	else linked?.addEventListener("abort", onAbort, { once: true });
+	const timer = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("zhihu request timeout")), timeout);
+	let stopWaiting = () => {};
+	const aborted = new Promise((_resolve, reject) => {
+		const rejectAbort = () => reject(controller.signal.reason);
+		if (controller.signal.aborted) rejectAbort();
+		else {
+			controller.signal.addEventListener("abort", rejectAbort, { once: true });
+			stopWaiting = () => controller.signal.removeEventListener("abort", rejectAbort);
+		}
+	});
+	try {
+		const request = async () => {
+			controller.signal.throwIfAborted();
+			const response = await fetcher(url.toString(), {
+				method,
+				headers: {
+					Authorization: `Bearer ${token.token}`,
+					"X-Request-Timestamp": String(Math.floor(Date.now() / 1e3)),
+					Accept: "application/json",
+					...method === "POST" && !init.formData ? { "Content-Type": "application/json" } : {}
+				},
+				signal: controller.signal,
+				...init.formData ? { body: init.formData } : init.body !== void 0 ? { body: JSON.stringify(init.body) } : {}
+			});
+			const retryAfter = parseZhihuRetryAfter(response.headers?.get("Retry-After"));
+			const httpError = () => {
+				const code = response.status === 429 ? "RATE_LIMITED" : init.envelope && (response.status === 401 || response.status === 403) ? "TOKEN_INVALID" : "HTTP_ERROR";
+				return new ZhihuSearchError(code, `${label}返回 HTTP ${response.status}。`, response.status, code === "RATE_LIMITED" ? {
+					retryAfter,
+					retryable: true
+				} : {});
+			};
+			let body;
+			try {
+				body = await response.json();
+			} catch (error) {
+				if (controller.signal.aborted) throw error;
+				if (!response.ok) throw httpError();
+				throw new ZhihuSearchError("BAD_RESPONSE", `${label}响应不是合法 JSON。`);
+			}
+			controller.signal.throwIfAborted();
+			const isEnvelope = body !== null && typeof body === "object" && !Array.isArray(body) && "Code" in body;
+			if (!response.ok && !isEnvelope) throw httpError();
+			if (init.envelope || isEnvelope && body.Code !== 0 && body.Code !== "0") {
+				const data = parseZhihuEnvelope(body, {
+					status: response.status,
+					retryAfter,
+					officialErrors: init.envelope
+				});
+				if (!response.ok) throw httpError();
+				if (init.envelope) return data;
+			}
+			if (!response.ok) throw httpError();
+			return body;
+		};
+		return await Promise.race([request(), aborted]);
+	} catch (error) {
+		if (linked?.aborted) throw new ZhihuSearchError("CANCELLED", "请求已取消");
+		if (controller.signal.aborted || isAbortError(error)) throw new ZhihuSearchError("TIMEOUT", `${label}超时（${Math.round(timeout / 1e3)} 秒），请稍后再试。`);
+		if (error instanceof ZhihuSearchError) {
+			error.message = error.message.replaceAll(token.token, "[REDACTED]");
+			throw error;
+		}
+		throw new ZhihuSearchError("BAD_RESPONSE", `${label}失败：${(error instanceof Error ? error.message : String(error)).replaceAll(token.token, "[REDACTED]")}`);
+	} finally {
+		clearTimeout(timer);
+		stopWaiting();
+		linked?.removeEventListener("abort", onAbort);
+	}
+}
+const ZHIHU_BUSINESS_ERRORS = {
+	10001: "INVALID_ARGUMENTS",
+	20001: "TOKEN_INVALID",
+	30001: "RATE_LIMITED",
+	30002: "RATE_LIMITED",
+	40001: "INVALID_ARGUMENTS",
+	40002: "INVALID_ARGUMENTS",
+	40003: "RATE_LIMITED",
+	40004: "INVALID_ARGUMENTS",
+	40005: "INVALID_ARGUMENTS",
+	40006: "INVALID_ARGUMENTS",
+	50002: "UPSTREAM_UNAVAILABLE",
+	90001: "UPSTREAM_UNAVAILABLE"
+};
+/** Parse the official envelope without coercing null/false/empty Code into success. */
+function parseZhihuEnvelope(body, meta = {}) {
+	if (!body || typeof body !== "object" || Array.isArray(body)) throw new ZhihuSearchError("BAD_RESPONSE", "知乎响应缺少 {Code,Message,Data} 信封。", meta.status);
+	const envelope = body;
+	const rawCode = envelope.Code;
+	if (!(typeof rawCode === "number" && Number.isSafeInteger(rawCode) || typeof rawCode === "string" && /^\d+$/.test(rawCode) && Number.isSafeInteger(Number(rawCode)))) throw new ZhihuSearchError("BAD_RESPONSE", "知乎响应缺少有效的 Code 字段。", meta.status);
+	const code = Number(rawCode);
+	if (code !== 0) {
+		const message = typeof envelope.Message === "string" && envelope.Message ? envelope.Message : "未知错误";
+		if (code === 30003) throw new ZhihuSearchError("UPSTREAM_UNAVAILABLE", `知乎开放平台被风控拒绝：${message}。请不要立即重试。`, meta.status, {
+			upstreamCode: code,
+			retryable: false
+		});
+		const kind = ZHIHU_BUSINESS_ERRORS[code] ?? (meta.officialErrors ? "UPSTREAM_UNAVAILABLE" : "HTTP_ERROR");
+		throw new ZhihuSearchError(kind, `知乎开放平台返回错误（code=${code}）：${message}`, meta.status, {
+			upstreamCode: code,
+			...kind === "RATE_LIMITED" ? {
+				retryAfter: meta.retryAfter,
+				retryable: true
+			} : {}
+		});
+	}
+	return envelope.Data ?? {};
+}
+function truncateSummary(text, limit) {
+	if (text.length <= limit) return text;
+	return `${text.slice(0, limit)}…`;
+}
+function normalizeSearchItem(raw) {
+	const summary = typeof raw.ContentText === "string" ? raw.ContentText : "";
+	return {
+		title: typeof raw.Title === "string" && raw.Title.length > 0 ? raw.Title : "(无标题)",
+		type: typeof raw.ContentType === "string" && raw.ContentType.length > 0 ? raw.ContentType : "内容",
+		url: typeof raw.Url === "string" ? raw.Url : "",
+		summary: truncateSummary(summary.trim(), 200),
+		votes: typeof raw.VoteUpCount === "number" ? raw.VoteUpCount : 0,
+		comments: typeof raw.CommentCount === "number" ? raw.CommentCount : 0,
+		author: typeof raw.AuthorName === "string" && raw.AuthorName.length > 0 ? raw.AuthorName : "匿名",
+		authority: typeof raw.AuthorityLevel === "string" && raw.AuthorityLevel.length > 0 ? raw.AuthorityLevel : "?",
+		editTime: typeof raw.EditTime === "number" ? String(raw.EditTime) : ""
+	};
+}
+const ZHIHU_SEARCH_PATH = "/api/v1/content/zhihu_search";
+function clampCount(value) {
+	const n = typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : 5;
+	if (n < 1) return 1;
+	if (n > 10) return 10;
+	return n;
+}
+function filterItems(data) {
+	const row = data ?? {};
+	return {
+		items: Array.isArray(row.Items) ? row.Items.filter((item) => !!item && typeof item === "object" && !Array.isArray(item)) : [],
+		emptyReason: typeof row.EmptyReason === "string" ? row.EmptyReason : void 0
+	};
+}
+async function executeZhihuSearch(query, count, options = {}) {
+	const trimmed = query.trim();
+	if (!trimmed) throw new ZhihuSearchError("BAD_RESPONSE", "搜索词不能为空。");
+	const resolvedCount = clampCount(count);
+	const { items, emptyReason } = filterItems(parseZhihuEnvelope(await zhihuFetchJson(ZHIHU_SEARCH_PATH, { params: {
+		Query: trimmed,
+		Count: String(resolvedCount)
+	} }, "知乎搜索", options)));
+	return {
+		version: 1,
+		query: trimmed,
+		count: resolvedCount,
+		items: items.map(normalizeSearchItem),
+		emptyReason
+	};
+}
+function renderZhihuSearch(result) {
+	if (result.items.length === 0) return `知乎站内搜索「${result.query}」无结果${result.emptyReason ? `（${result.emptyReason}）` : ""}。`;
+	const lines = [`知乎站内搜索「${result.query}」共 ${result.items.length} 条：`, ""];
+	result.items.forEach((item, index) => {
+		lines.push(`${index + 1}. [${item.title}](${item.url || "（无链接）"})`);
+		lines.push(`   - 类型：${item.type}　作者：${item.author}　权威：${item.authority}`);
+		if (item.editTime) lines.push(`   - 时间：${item.editTime}`);
+		lines.push(`   - 赞同 ${item.votes}　评论 ${item.comments}`);
+		if (item.summary) lines.push(`   - 摘要：${item.summary}`);
+		lines.push("");
+	});
+	return lines.join("\n").trimEnd();
+}
+const GLOBAL_SEARCH_PATH = "/api/v1/content/global_search";
+const HOT_LIST_PATH = "/api/v1/content/hot_list";
+const ASK_PATH = "/v1/chat/completions";
+const KNOWLEDGE_SEARCH_PATH = "/api/v1/knowledge/search";
+const ZHIHU_ASK_MODELS = [
+	"zhida-fast-1p5",
+	"zhida-thinking-1p5",
+	"zhida-agent"
+];
+/** 直答的价值在于比本机模型更强的综合考据,默认用思考档;fast 只配简单事实查询。 */
+const ZHIHU_ASK_DEFAULT_MODEL = "zhida-thinking-1p5";
+function clampInt(value, fallback, max) {
+	const n = typeof value === "number" && Number.isFinite(value) ? Math.trunc(value) : fallback;
+	if (n < 1) return 1;
+	if (n > max) return max;
+	return n;
+}
+function requireQuery(query, hint) {
+	const trimmed = query.trim();
+	if (!trimmed) throw new ZhihuSearchError("BAD_RESPONSE", hint);
+	return trimmed;
+}
+function objectItems(data, key = "Items") {
+	const items = (data ?? {})[key];
+	return Array.isArray(items) ? items.filter((item) => !!item && typeof item === "object" && !Array.isArray(item)) : [];
+}
+async function executeZhihuGlobalSearch(query, count, searchDb, options = {}) {
+	const trimmed = requireQuery(query, "搜索词不能为空。");
+	const resolvedCount = clampInt(count, 10, 20);
+	const data = parseZhihuEnvelope(await zhihuFetchJson(GLOBAL_SEARCH_PATH, { params: {
+		Query: trimmed,
+		Count: String(resolvedCount),
+		SearchDB: searchDb
+	} }, "知乎全网搜索", options));
+	return {
+		version: 1,
+		query: trimmed,
+		count: resolvedCount,
+		searchDb,
+		items: objectItems(data).map(normalizeSearchItem),
+		emptyReason: typeof data.EmptyReason === "string" ? data.EmptyReason : void 0
+	};
+}
+function renderZhihuGlobalSearch(result) {
+	if (result.items.length === 0) return `全网搜索「${result.query}」无结果${result.emptyReason ? `（${result.emptyReason}）` : ""}。`;
+	const lines = [`全网搜索「${result.query}」共 ${result.items.length} 条：`, ""];
+	result.items.forEach((item, index) => {
+		lines.push(`${index + 1}. [${item.title}](${item.url || "（无链接）"})`);
+		lines.push(`   - 类型：${item.type}　作者：${item.author}`);
+		if (item.summary) lines.push(`   - 摘要：${item.summary}`);
+		lines.push("");
+	});
+	return lines.join("\n").trimEnd();
+}
+const ZHIHU_HOT_LIST_SUMMARY_MAX_CHARS = 200;
+function normalizeHotItem(raw) {
+	const summary = typeof raw.Summary === "string" ? raw.Summary.trim() : "";
+	return {
+		title: typeof raw.Title === "string" && raw.Title.length > 0 ? raw.Title : "(无标题)",
+		url: typeof raw.Url === "string" ? raw.Url : "",
+		summary: summary.length > ZHIHU_HOT_LIST_SUMMARY_MAX_CHARS ? `${summary.slice(0, ZHIHU_HOT_LIST_SUMMARY_MAX_CHARS)}…` : summary
+	};
+}
+async function executeZhihuHotList(limit, options = {}) {
+	const resolvedLimit = clampInt(limit, 10, 30);
+	return {
+		version: 1,
+		limit: resolvedLimit,
+		items: objectItems(parseZhihuEnvelope(await zhihuFetchJson(HOT_LIST_PATH, { params: { Limit: String(resolvedLimit) } }, "知乎热榜", options))).map(normalizeHotItem)
+	};
+}
+function renderZhihuHotList(result) {
+	if (result.items.length === 0) return "知乎热榜为空。";
+	const lines = ["知乎热榜：", ""];
+	result.items.forEach((item, index) => {
+		lines.push(`${index + 1}. [${item.title}](${item.url || "（无链接）"})`);
+		if (item.summary) lines.push(`   - ${item.summary}`);
+		lines.push("");
+	});
+	return lines.join("\n").trimEnd();
+}
+async function executeZhihuAsk(query, model, options = {}) {
+	const trimmed = requireQuery(query, "直答问题不能为空。");
+	const body = await zhihuFetchJson(ASK_PATH, {
+		method: "POST",
+		body: {
+			model,
+			messages: [{
+				role: "user",
+				content: trimmed
+			}],
+			stream: false
+		}
+	}, "知乎直答", {
+		...options,
+		timeoutMs: options.timeoutMs ?? 12e4
+	});
+	if (!body || typeof body !== "object" || Array.isArray(body)) throw new ZhihuSearchError("BAD_RESPONSE", "知乎直答响应不是 OpenAI 兼容格式。");
+	const payload = body;
+	if (payload.error) throw new ZhihuSearchError("HTTP_ERROR", `知乎直答返回错误：${typeof payload.error.message === "string" ? payload.error.message : "未知错误"}`);
+	const message = (Array.isArray(payload.choices) ? payload.choices[0] : void 0)?.message ?? {};
+	const content = typeof message.content === "string" ? message.content.trim() : "";
+	const reasoning = typeof message.reasoning_content === "string" ? message.reasoning_content.trim() : "";
+	if (!content) throw new ZhihuSearchError("BAD_RESPONSE", "知乎直答返回为空。");
+	return {
+		version: 1,
+		query: trimmed,
+		model,
+		content,
+		reasoning
+	};
+}
+function renderZhihuAsk(result) {
+	const parts = [];
+	if (result.reasoning) parts.push(`【思考过程】\n${result.reasoning}`);
+	parts.push(result.content);
+	return `知乎直答「${result.query}」：\n\n${parts.join("\n\n")}`;
+}
+const ZHIHU_RECALL_SCOPES = [
+	"personal",
+	"subscription",
+	"public"
+];
+function normalizeKnowledgeItem(raw) {
+	const content = raw.Content;
+	const snippets = Array.isArray(content) ? content.map((snippet) => String(snippet).trim()).filter((snippet) => snippet.length > 0) : [];
+	return {
+		docName: typeof raw.DocName === "string" && raw.DocName.length > 0 ? raw.DocName : "(未命名文档)",
+		originUrl: typeof raw.OriginUrl === "string" ? raw.OriginUrl : "",
+		snippets
+	};
+}
+/** 收敛召回范围:只保留合法档位、去重;为空或未提供时回退公开库。 */
+function normalizeRecallScopes(value) {
+	if (!Array.isArray(value)) return ["public"];
+	const scopes = [...new Set(value.filter((scope) => typeof scope === "string" && ZHIHU_RECALL_SCOPES.includes(scope)))];
+	return scopes.length > 0 ? scopes : ["public"];
+}
+async function executeZhihuKnowledgeSearch(query, limit, recallScopes, options = {}) {
+	const trimmed = requireQuery(query, "知识库检索词不能为空。");
+	const resolvedLimit = clampInt(limit, 5, 10);
+	return {
+		version: 1,
+		query: trimmed,
+		limit: resolvedLimit,
+		recallScopes,
+		items: objectItems(parseZhihuEnvelope(await zhihuFetchJson(KNOWLEDGE_SEARCH_PATH, {
+			method: "POST",
+			body: {
+				Query: trimmed,
+				Limit: resolvedLimit,
+				RecallScopes: recallScopes
+			}
+		}, "知乎知识库检索", {
+			...options,
+			timeoutMs: options.timeoutMs ?? 3e4
+		}))).map(normalizeKnowledgeItem)
+	};
+}
+function renderZhihuKnowledgeSearch(result) {
+	if (result.items.length === 0) return `知乎知识库检索「${result.query}」无匹配结果。`;
+	const lines = [`知乎知识库检索「${result.query}」共 ${result.items.length} 条：`, ""];
+	result.items.forEach((item, index) => {
+		lines.push(`${index + 1}. ${item.docName}`);
+		if (item.originUrl) lines.push(`   - 来源：${item.originUrl}`);
+		for (const snippet of item.snippets) lines.push(`   - ${snippet}`);
+		lines.push("");
+	});
+	return lines.join("\n").trimEnd();
+}
+//#endregion
+//#region src/open-platform.ts
+/**
+* Contract source: klarkxy/zhihu-search@62fd3ce5, upstream/http_client.py.
+* Six question/creator APIs use the current Access Secret only, never OAuth.
+* This module has no DSH/UI dependencies; RPC and tools share these validators.
+*/
+const ZHIHU_OPEN_PLATFORM_APIS = {
+	"question.recommendations": {
+		path: "/api/v1/user/question_recommendations",
+		label: "适合回答的问题",
+		quotaId: "creator"
+	},
+	"question.answers": {
+		path: "/api/v1/content/question_answers",
+		label: "问题回答摘要",
+		quotaId: "question_answers"
+	},
+	"content.detail": {
+		path: "/api/v1/user/content_detail",
+		label: "本人创作全文",
+		quotaId: "creator"
+	},
+	"content.comments": {
+		path: "/api/v1/user/content_comments",
+		label: "本人创作评论",
+		quotaId: "creator"
+	},
+	"creator.account.stats": {
+		path: "/api/v1/user/creator_account_stats",
+		label: "账号创作数据",
+		quotaId: "creator"
+	},
+	"creator.content.stats": {
+		path: "/api/v1/user/creator_content_stats",
+		label: "单篇创作数据",
+		quotaId: "creator"
+	},
+	quota: {
+		path: "/api/v1/quota",
+		label: "官方每日额度",
+		quotaId: void 0
+	}
+};
+const ENDPOINT_ALIASES = {
+	question_recommendations: "question.recommendations",
+	question_answers: "question.answers",
+	content_detail: "content.detail",
+	user_content_detail: "content.detail",
+	"user.content.detail": "content.detail",
+	content_comments: "content.comments",
+	user_content_comments: "content.comments",
+	"user.content.comments": "content.comments",
+	creator_account_stats: "creator.account.stats",
+	creator_content_stats: "creator.content.stats"
+};
+function resolveZhihuOpenPlatformOperation(endpoint) {
+	if (Object.hasOwn(ZHIHU_OPEN_PLATFORM_APIS, endpoint)) return endpoint;
+	return Object.hasOwn(ENDPOINT_ALIASES, endpoint) ? ENDPOINT_ALIASES[endpoint] : void 0;
+}
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+function jsonValue(value) {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(jsonValue);
+	return record(value) && Object.values(value).every(jsonValue);
+}
+function jsonRecord(value) {
+	return record(value) && Object.values(value).every(jsonValue);
+}
+function invalid(message) {
+	throw new ZhihuSearchError("INVALID_ARGUMENTS", message);
+}
+function inputObject(input) {
+	if (!record(input)) return invalid("参数必须是对象。");
+	for (const key of [
+		"token",
+		"accessSecret",
+		"access_secret",
+		"accessToken",
+		"access_token",
+		"oauthToken",
+		"oauth_token",
+		"useConfiguredOauthUser",
+		"use_configured_oauth_user"
+	]) if (Object.hasOwn(input, key)) invalid("这些接口仅使用当前 Access Secret，不接受 token 参数或 OAuth 身份切换。");
+	return input;
+}
+function limit(value, fallback, maximum, name = "limit") {
+	const count = value === void 0 ? fallback : value;
+	if (typeof count !== "number" || !Number.isInteger(count) || count < 1 || count > maximum) return invalid(`${name} 必须是 1-${maximum} 的整数。`);
+	return String(count);
+}
+/** Accept all nonnegative Int64 values as strings, but never accept an unsafe JS number. */
+function normalizeZhihuOffset(value) {
+	let decimal;
+	if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) decimal = String(value);
+	else if (typeof value === "string" && /^\d+$/.test(value)) decimal = value.replace(/^0+(?=\d)/, "");
+	else return invalid("offset 必须是非负 Int64 整数；超过 JavaScript 安全整数范围时请用十进制字符串，不能使用不透明游标。");
+	if (decimal.length > 19 || BigInt(decimal) > 9223372036854775807n) return invalid("offset 超出 Int64 范围。");
+	return decimal;
+}
+function zhihuUrl(value, question) {
+	if (typeof value !== "string" || !value.trim()) return invalid(question ? "questionUrl 不能为空。" : "contentUrl 不能为空。");
+	const cleaned = value.trim();
+	if (/[\u0000-\u0020\u007f\\]/.test(cleaned)) return invalid("知乎链接不能包含空白、控制字符或反斜线。");
+	let url;
+	try {
+		url = new URL(cleaned);
+	} catch {
+		return invalid("不是有效的知乎 URL。");
+	}
+	if (url.protocol !== "https:" || url.username || url.password || url.port) return invalid("必须使用无账号密码、无非标准端口的 HTTPS 知乎链接。");
+	if (!(question ? url.hostname === "www.zhihu.com" && /^\/question\/\d+\/?$/.test(url.pathname) : url.hostname === "www.zhihu.com" && /^\/(?:answer\/\d+|question\/\d+\/answer\/\d+|pin\/\d+|zvideo\/\d+)\/?$/.test(url.pathname) || url.hostname === "zhuanlan.zhihu.com" && /^\/p\/\d+\/?$/.test(url.pathname))) return invalid(question ? "questionUrl 仅支持 https://www.zhihu.com/question/{id}。" : "contentUrl 仅支持知乎回答、专栏文章、想法或视频链接。");
+	return cleaned;
+}
+function dates(input, params) {
+	const { startDate, endDate } = input;
+	if (startDate === void 0 && endDate === void 0) return;
+	if (startDate === void 0 || endDate === void 0) invalid("startDate 与 endDate 必须同时提供或同时省略。");
+	for (const [key, value] of [["StartDate", startDate], ["EndDate", endDate]]) {
+		if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value) || value.slice(0, 4) === "0000") invalid(`${key} 必须是有效的 YYYY-MM-DD 公历日期。`);
+		const time = /* @__PURE__ */ new Date(`${value}T00:00:00Z`);
+		if (!Number.isFinite(time.getTime()) || time.toISOString().slice(0, 10) !== value) invalid(`${key} 不是有效公历日期。`);
+		params[key] = value;
+	}
+	if (params.EndDate < params.StartDate) invalid("endDate 不得早于 startDate。");
+}
+function paramsFor(operation, input) {
+	const params = {};
+	if (operation === "question.recommendations") {
+		if (input.query !== void 0) {
+			if (typeof input.query !== "string" || !input.query.trim()) invalid("主题关键词不能为空；省略 query 才会按画像推荐。");
+			params.Query = input.query.trim();
+		}
+		params.Count = limit(input.count, 5, 20, "count");
+	} else if (operation === "question.answers") params.QuestionUrl = zhihuUrl(input.questionUrl, true);
+	else if (operation === "content.detail" || operation === "content.comments" || operation === "creator.content.stats") params.ContentUrl = zhihuUrl(input.contentUrl, false);
+	else if (operation === "creator.account.stats") {
+		const type = input.contentType === void 0 ? "all" : input.contentType;
+		if (typeof type !== "string" || ![
+			"all",
+			"answer",
+			"article",
+			"pin",
+			"zvideo"
+		].includes(type)) invalid("contentType 必须是 all、answer、article、pin 或 zvideo。");
+		params.ContentType = type;
+	} else if (operation === "quota" && input.apiIds !== void 0) {
+		if (!Array.isArray(input.apiIds) || input.apiIds.some((id) => typeof id !== "string" || !ZHIHU_QUOTA_IDS.includes(id))) invalid("apiIds 包含未知官方额度项。");
+		if (input.apiIds.length) params.APIIDs = [...new Set(input.apiIds)].join(",");
+	}
+	if (operation === "question.answers" || operation === "content.comments") {
+		params.Offset = normalizeZhihuOffset(input.offset === void 0 ? 0 : input.offset);
+		params.Limit = limit(input.limit, 20, 50);
+	}
+	if (operation === "content.comments") {
+		const order = input.order === void 0 ? "score" : input.order;
+		if (typeof order !== "string" || ![
+			"score",
+			"reverse",
+			"ascending"
+		].includes(order)) invalid("order 必须是 score、reverse 或 ascending。");
+		params.Order = order;
+	}
+	if (operation === "creator.account.stats" || operation === "creator.content.stats") dates(input, params);
+	return params;
+}
+function normalizeZhihuPaging(data, offset) {
+	const paging = data.Paging;
+	if (!record(paging) || typeof paging.IsEnd !== "boolean") return {
+		canContinue: false,
+		warning: "分页信息不完整：缺少有效的 Paging.IsEnd，请停止翻页。"
+	};
+	if (paging.IsEnd) return {
+		isEnd: true,
+		canContinue: false
+	};
+	try {
+		const nextOffset = normalizeZhihuOffset(paging.NextOffset);
+		if (BigInt(nextOffset) <= BigInt(offset)) throw new Error("non-advancing offset");
+		return {
+			isEnd: false,
+			canContinue: true,
+			nextOffset
+		};
+	} catch {
+		return {
+			isEnd: false,
+			canContinue: false,
+			warning: "分页信息不完整：NextOffset 缺失、无效或未前进，请停止翻页；不要按条数计算偏移。"
+		};
+	}
+}
+async function executeZhihuOpenPlatform(operation, input = {}, options = {}) {
+	const params = paramsFor(operation, inputObject(input));
+	const api = ZHIHU_OPEN_PLATFORM_APIS[operation];
+	const raw = await zhihuFetchJson(api.path, {
+		params,
+		envelope: true
+	}, api.label, options);
+	const data = operation === "quota" && Array.isArray(raw) ? { Items: raw } : raw;
+	if (!jsonRecord(data)) throw new ZhihuSearchError("BAD_RESPONSE", `${api.label}的 Data 必须是 JSON 对象。`);
+	return {
+		version: 1,
+		operation,
+		data,
+		...api.quotaId ? { quotaId: api.quotaId } : {},
+		...operation === "question.answers" || operation === "content.comments" ? { paging: normalizeZhihuPaging(data, params.Offset) } : {}
+	};
+}
+function zhihuOpenPlatformResultCount(result) {
+	if (result.operation === "quota") return 0;
+	if (result.operation === "content.detail") return typeof result.data.Body === "string" && result.data.Body.trim() ? 1 : 0;
+	if (result.operation === "creator.account.stats") return Object.keys(result.data).length ? 1 : 0;
+	return Array.isArray(result.data.Items) ? result.data.Items.filter(record).length : 0;
+}
+//#endregion
+export { zhihuFetchJson as S, executeZhihuSearch as _, ZHIHU_ASK_DEFAULT_MODEL as a, parseZhihuEnvelope as b, executeZhihuAsk as c, executeZhihuKnowledgeSearch as d, normalizeRecallScopes as f, renderZhihuKnowledgeSearch as g, renderZhihuHotList as h, zhihuOpenPlatformResultCount as i, executeZhihuGlobalSearch as l, renderZhihuGlobalSearch as m, executeZhihuOpenPlatform as n, ZHIHU_ASK_MODELS as o, renderZhihuAsk as p, resolveZhihuOpenPlatformOperation as r, ZHIHU_RECALL_SCOPES as s, ZHIHU_OPEN_PLATFORM_APIS as t, executeZhihuHotList as u, renderZhihuSearch as v, reportExecuted as x, ZhihuSearchError as y };
+
+//# sourceMappingURL=open-platform.js.map