@klarkxy/dsh-zhihu 0.1.10 → 0.2.1

package/lib/open-platform.js

@@ -1,7 +1,178 @@
-import { ZHIHU_QUOTA_IDS } from "./contracts.js";
-import { readFile } from "node:fs/promises";
+import { ZHIHU_QUOTA_IDS, normalizeZhihuQuotaId } from "./contracts.js";
+import { mkdir, open, readFile, rename, rmdir, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
+//#region src/call-policy.ts
+var ZhihuCallPolicyError = class extends Error {};
+const blocked = (message) => {
+	throw new ZhihuCallPolicyError(message);
+};
+const GROUPS = {
+	"/api/v1/content/zhihu_search": "zhihu_search",
+	"/api/v1/content/global_search": "global_search",
+	"/api/v1/content/hot_list": "hot_list",
+	"/api/v1/content/question_answers": "question_discovery",
+	"/api/v1/user/contents": "user_data",
+	"/api/v1/user/followees": "user_data",
+	"/api/v1/user/collections": "user_data",
+	"/api/v1/user/favlists": "user_data",
+	"/api/v1/user/favlist_contents": "user_data",
+	"/api/v1/user/content_detail": "creator",
+	"/api/v1/user/content_comments": "creator",
+	"/api/v1/user/creator_account_stats": "creator",
+	"/api/v1/user/creator_content_stats": "creator",
+	"/api/v1/knowledge/bases": "knowledge",
+	"/api/v1/knowledge/files": "knowledge",
+	"/api/v1/knowledge/search": "knowledge"
+};
+const PRICED_PATHS = new Set(Object.keys(GROUPS));
+GROUPS["/api/v1/user/question_recommendations"] = "question_discovery";
+function zhihuQuotaGroup(path, body) {
+	if (path === "/v1/chat/completions" && body && typeof body === "object" && [
+		"zhida-agent",
+		"zhida-fast-1p5",
+		"zhida-thinking-1p5"
+	].includes(String(body.model))) return "zhida_openai";
+	if (/^\/api\/v1\/knowledge\/bases\/[^/]+\/items$/.test(path)) return "knowledge";
+	if (/^\/api\/v1\/(?:pdf-parse|ppt-generation)\/tasks(?:\/[^/]+)?$/.test(path)) return "tools";
+	return GROUPS[path] ?? blocked("调用已阻止：该能力的官方额度映射未确认；不能擅自套价。");
+}
+function resolveZhihuCallPolicy(env = process.env, options = {}) {
+	const raw = (env.ZHIHU_ALLOW_PAID ?? "false").toLowerCase();
+	if (options.allowPaid === void 0 && ![
+		"true",
+		"false",
+		"1",
+		"0"
+	].includes(raw)) blocked("ZHIHU_ALLOW_PAID 必须是 true/false 或 1/0。");
+	const allowPaid = options.allowPaid ?? ["true", "1"].includes(raw);
+	const capText = env.ZHIHU_DAILY_CALL_LIMIT ?? "100";
+	if (options.dailyCallLimit === void 0 && !/^\d+$/.test(capText)) blocked("每日调用上限必须是 1-100000 的整数。");
+	const dailyCallLimit = options.dailyCallLimit ?? Number(capText);
+	if (typeof allowPaid !== "boolean" || !Number.isInteger(dailyCallLimit) || dailyCallLimit < 1 || dailyCallLimit > 1e5) blocked("付费开关必须是布尔值，每日调用上限必须是 1-100000 的整数。");
+	return {
+		allowPaid,
+		dailyCallLimit
+	};
+}
+const integer = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const day = () => new Date(Date.now() + 288e5).toISOString().slice(0, 10);
+const code = (error) => error?.code;
+async function readLedger(directory) {
+	let value;
+	try {
+		value = JSON.parse(await readFile(join(directory, "daily.json"), "utf8"));
+	} catch (error) {
+		if (code(error) === "ENOENT") return {
+			version: 1,
+			day: day(),
+			calls: 0,
+			uncertain: {},
+			free: {}
+		};
+		return blocked("本地调用记录不可读；已阻止请求，请检查 call-policy/daily.json。");
+	}
+	const row = value;
+	if (!row || row.version !== 1 || typeof row.day !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(row.day) || !integer(row.calls) || !row.uncertain || Array.isArray(row.uncertain) || typeof row.uncertain !== "object" || !Object.values(row.uncertain).every(integer)) blocked("本地调用记录无效；已阻止请求，不能自动清零。");
+	if (row.free === void 0) row.free = {};
+	if (!row.free || Array.isArray(row.free) || typeof row.free !== "object" || !Object.values(row.free).every(integer)) blocked("本地免费预留记录无效；已阻止请求。");
+	if (row.day !== day()) {
+		row.day = day();
+		row.calls = 0;
+		row.free = {};
+	}
+	return row;
+}
+async function writeLedger(directory, row) {
+	const temporary = join(directory, `daily-${randomUUID()}.tmp`);
+	try {
+		const file = await open(temporary, "wx");
+		try {
+			await file.writeFile(JSON.stringify(row), "utf8");
+			await file.sync();
+		} finally {
+			await file.close();
+		}
+		await rename(temporary, join(directory, "daily.json"));
+	} catch {
+		blocked("本地调用记录保存失败；已阻止请求。");
+	} finally {
+		await unlink(temporary).catch((error) => {
+			if (code(error) !== "ENOENT") throw error;
+		});
+	}
+}
+async function withZhihuCallPolicy(path, body, quota, execute, options = {}) {
+	const group = zhihuQuotaGroup(path, body);
+	const env = options.env ?? process.env;
+	const policy = resolveZhihuCallPolicy(env, options);
+	const priced = PRICED_PATHS.has(path) || /^\/api\/v1\/knowledge\/bases\/[^/]+\/items$/.test(path) || path === "/v1/chat/completions" && body && typeof body === "object" && body.model === "zhida-agent";
+	if (policy.allowPaid && !priced) blocked("付费调用已阻止：该能力的官方计费未确认；请使用免费保护模式。");
+	const directory = options.directory ?? env.ZHIHU_CALL_POLICY_DIR ?? join(env.ZHIHU_SEARCH_HOME ?? join(homedir(), ".config", "zhihu-search"), "call-policy");
+	const lock = join(directory, "request.lock");
+	let acquired = false;
+	const deadline = Date.now() + (options.lockTimeoutMs ?? 3e4);
+	try {
+		options.signal?.throwIfAborted();
+		await mkdir(directory, { recursive: true });
+		while (!acquired) {
+			options.signal?.throwIfAborted();
+			try {
+				await mkdir(lock);
+				acquired = true;
+			} catch (error) {
+				if (code(error) !== "EEXIST") throw error;
+				if (Date.now() >= deadline) blocked("本地保护锁忙或遗留；已阻止请求。确认两个客户端均无在途请求后再移除 call-policy/request.lock。");
+				await setTimeout$1(50, void 0, { signal: options.signal });
+			}
+		}
+		options.signal?.throwIfAborted();
+		const row = await readLedger(directory);
+		if (row.calls >= policy.dailyCallLimit) blocked("已达到本地北京时间每日业务调用上限；额度查询仍可使用。");
+		if (!policy.allowPaid) {
+			let rows;
+			try {
+				rows = await quota(group);
+			} catch {
+				options.signal?.throwIfAborted();
+				blocked("免费额度预查失败；未发送业务请求，请稍后手动查询官方额度。");
+			}
+			options.signal?.throwIfAborted();
+			const matches = Array.isArray(rows) ? rows.filter((value) => value && typeof value === "object" && value.APIID === group) : [];
+			if (matches.length !== 1 || !integer(matches[0].RemainingQuota)) blocked("官方未返回有效的免费剩余额度；未发送业务请求。");
+			const available = Math.min(matches[0].RemainingQuota - (row.uncertain[group] ?? 0), row.free[group] ?? matches[0].RemainingQuota);
+			if (available <= 0) blocked("免费额度不足，或有结果未知的已发送请求；未发送业务请求。");
+			row.free[group] = available - 1;
+		} else if (row.free[group] !== void 0) row.free[group] = Math.max(0, row.free[group] - 1);
+		options.signal?.throwIfAborted();
+		row.calls++;
+		row.uncertain[group] = (row.uncertain[group] ?? 0) + 1;
+		await writeLedger(directory, row);
+		options.signal?.throwIfAborted();
+		const result = await execute();
+		row.uncertain[group]--;
+		await writeLedger(directory, row);
+		return result;
+	} catch (error) {
+		options.signal?.throwIfAborted();
+		if (error instanceof ZhihuCallPolicyError) throw error;
+		if ([
+			"EACCES",
+			"EPERM",
+			"ENOSPC",
+			"EIO",
+			"EROFS",
+			"ENOENT",
+			"ENOTDIR"
+		].includes(String(code(error)))) blocked("本地保护存储不可用；已阻止业务请求。");
+		throw error;
+	} finally {
+		if (acquired) await rmdir(lock);
+	}
+}
+//#endregion
 //#region src/zhihu-client.ts
 /**
 * 知乎开放平台共享请求层:Access Secret 解析、超时封装、信封解析与执行计量。
@@ -11,13 +182,11 @@ import { join } from "node:path";
 *   - 公共 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。
+* Token 解析（按契约,**不**把 token 放进 schema 参数）：
+*   - 提供 credential 解析器时只使用它，缺失或无效时抛出 TOKEN_MISSING。
+*     宿主通过 `ctx.credentials.resolve` 统一管理凭据来源和清除操作。
+*   - 未提供解析器的独立客户端依次兼容 ZHIHU_ACCESS_TOKEN、
+*     ZHIHU_ACCESS_SECRET 和 ~/.config/zhihu-search/credentials.json。
 */
 const ZHIHU_BASE_URL = "https://developer.zhihu.com";
 const ZHIHU_DEFAULT_TIMEOUT_MS = 15e3;
@@ -41,11 +210,13 @@ async function readCredentialsFile(path) {
 }
 async function resolveZhihuToken(env = process.env, options = {}) {
 	if (options.resolveCredential) {
-		const fromCredential = (await options.resolveCredential())?.trim();
+		const value = await options.resolveCredential();
+		const fromCredential = typeof value === "string" ? value.trim() : void 0;
 		if (fromCredential && looksLikeToken(fromCredential)) return {
 			token: fromCredential,
 			source: "credential"
 		};
+		throw new ZhihuSearchError("TOKEN_MISSING", "未配置有效的知乎 Access Secret。请在「插件 → 知乎 → 设置」中填写。");
 	}
 	const primary = env[ZHIHU_CREDENTIALS_PRIMARY]?.trim();
 	if (primary && looksLikeToken(primary)) return {
@@ -180,10 +351,34 @@ async function zhihuFetchJson(path, init, label, options = {}) {
 			if (!response.ok) throw httpError();
 			return body;
 		};
-		return await Promise.race([request(), aborted]);
+		const quota = async (apiId) => {
+			const quotaUrl = new URL("/api/v1/quota", ZHIHU_BASE_URL);
+			quotaUrl.searchParams.set("APIIDs", apiId);
+			const response = await fetcher(quotaUrl.toString(), {
+				method: "GET",
+				signal: controller.signal,
+				headers: {
+					Authorization: `Bearer ${token.token}`,
+					"X-Request-Timestamp": String(Math.floor(Date.now() / 1e3)),
+					Accept: "application/json"
+				}
+			});
+			const data = parseZhihuEnvelope(await response.json(), {
+				status: response.status,
+				officialErrors: true
+			});
+			if (!response.ok) throw new Error("官方额度查询失败");
+			return data;
+		};
+		return await (path === "/api/v1/quota" && method === "GET" ? Promise.race([request(), aborted]) : withZhihuCallPolicy(path, init.body, (apiId) => Promise.race([quota(apiId), aborted]), () => Promise.race([request(), aborted]), {
+			...options.callPolicy,
+			env: options.env,
+			signal: controller.signal
+		}));
 	} 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 ZhihuCallPolicyError) throw new ZhihuSearchError("CALL_BLOCKED", error.message, void 0, { retryable: false });
 		if (error instanceof ZhihuSearchError) {
 			error.message = error.message.replaceAll(token.token, "[REDACTED]");
 			throw error;
@@ -475,12 +670,12 @@ const ZHIHU_OPEN_PLATFORM_APIS = {
 	"question.recommendations": {
 		path: "/api/v1/user/question_recommendations",
 		label: "适合回答的问题",
-		quotaId: "creator"
+		quotaId: "question_discovery"
 	},
 	"question.answers": {
 		path: "/api/v1/content/question_answers",
 		label: "问题回答摘要",
-		quotaId: "question_answers"
+		quotaId: "question_discovery"
 	},
 	"content.detail": {
 		path: "/api/v1/user/content_detail",
@@ -550,7 +745,7 @@ function inputObject(input) {
 		"useConfiguredOauthUser",
 		"use_configured_oauth_user"
 	]) if (Object.hasOwn(input, key)) invalid("这些接口仅使用当前 Access Secret，不接受 token 参数或 OAuth 身份切换。");
-	return input;
+	return { ...input };
 }
 function limit(value, fallback, maximum, name = "limit") {
 	const count = value === void 0 ? fallback : value;
@@ -613,6 +808,7 @@ function paramsFor(operation, input) {
 		].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 = input.apiIds.map(normalizeZhihuQuotaId);
 		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(",");
 	}
@@ -682,6 +878,6 @@ function zhihuOpenPlatformResultCount(result) {
 	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 };
+export { resolveZhihuCallPolicy as C, 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