@dsh-plus/web-search-services 0.1.2 → 0.1.4

package/lib/index.d.ts

@@ -1,49 +1,53 @@
-import z from "@deepseek-ai/schemastery";
+import { UnwrapVolatile } from "@dsh-plus/shared";
 import { WebSearchProvider, WebSearchRequest, WebSearchResult } from "@deepseek-ai/dsh-web";
 import { spawn } from "node:child_process";
+import z from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/config.d.ts
 declare const SETTINGS_NS = "dsh-plus-web-search-services";
-declare const Config: z<Schemastery.ObjectS<{
-  scriptPath: z<string, string>;
-  envFile: z<string, string>;
-  python: z<string, string>;
-  priority: z<("exa" | "openai-chat" | "tavily")[], ("exa" | "openai-chat" | "tavily")[]>;
-  timeoutMs: z<number, number>;
-  keys: z<Schemastery.ObjectS<{
-    tavily: z<string, string>;
-    exa: z<string, string>;
-    openaiApiKey: z<string, string>;
-    openaiBaseUrl: z<string, string>;
-    openaiModel: z<string, string>;
-  }>, Schemastery.ObjectT<{
-    tavily: z<string, string>;
-    exa: z<string, string>;
-    openaiApiKey: z<string, string>;
-    openaiBaseUrl: z<string, string>;
-    openaiModel: z<string, string>;
-  }>>;
-}>, Schemastery.ObjectT<{
-  scriptPath: z<string, string>;
-  envFile: z<string, string>;
-  python: z<string, string>;
-  priority: z<("exa" | "openai-chat" | "tavily")[], ("exa" | "openai-chat" | "tavily")[]>;
-  timeoutMs: z<number, number>;
-  keys: z<Schemastery.ObjectS<{
-    tavily: z<string, string>;
-    exa: z<string, string>;
-    openaiApiKey: z<string, string>;
-    openaiBaseUrl: z<string, string>;
-    openaiModel: z<string, string>;
-  }>, Schemastery.ObjectT<{
-    tavily: z<string, string>;
-    exa: z<string, string>;
-    openaiApiKey: z<string, string>;
-    openaiBaseUrl: z<string, string>;
-    openaiModel: z<string, string>;
-  }>>;
-}>>;
-type WebSearchServicesConfig = Schemastery.TypeT<typeof Config>;
+declare const Config: z<Schemastery.ObjectS<NoInfer<{
+  scriptPath: z<string, string, "volatile-defined">;
+  envFile: z<string, string, "volatile-defined">;
+  python: z<string, string, "volatile-defined">;
+  priority: z<NoInfer<("exa" | "openai-chat" | "tavily")[]>, NoInfer<("exa" | "openai-chat" | "tavily")[]>, "volatile-defined">;
+  timeoutMs: z<number, number, "volatile-defined">;
+  keys: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+    tavily: z<string, string, "defined">;
+    exa: z<string, string, "defined">;
+    openaiApiKey: z<string, string, "defined">;
+    openaiBaseUrl: z<string, string, "defined">;
+    openaiModel: z<string, string, "defined">;
+  }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+    tavily: z<string, string, "defined">;
+    exa: z<string, string, "defined">;
+    openaiApiKey: z<string, string, "defined">;
+    openaiBaseUrl: z<string, string, "defined">;
+    openaiModel: z<string, string, "defined">;
+  }>>>, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+  scriptPath: z<string, string, "volatile-defined">;
+  envFile: z<string, string, "volatile-defined">;
+  python: z<string, string, "volatile-defined">;
+  priority: z<NoInfer<("exa" | "openai-chat" | "tavily")[]>, NoInfer<("exa" | "openai-chat" | "tavily")[]>, "volatile-defined">;
+  timeoutMs: z<number, number, "volatile-defined">;
+  keys: z<NoInfer<Schemastery.ObjectS<NoInfer<{
+    tavily: z<string, string, "defined">;
+    exa: z<string, string, "defined">;
+    openaiApiKey: z<string, string, "defined">;
+    openaiBaseUrl: z<string, string, "defined">;
+    openaiModel: z<string, string, "defined">;
+  }>>>, NoInfer<Schemastery.ObjectT<NoInfer<{
+    tavily: z<string, string, "defined">;
+    exa: z<string, string, "defined">;
+    openaiApiKey: z<string, string, "defined">;
+    openaiBaseUrl: z<string, string, "defined">;
+    openaiModel: z<string, string, "defined">;
+  }>>>, "volatile-defined">;
+}>>, "plain">;
+/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+type WebSearchServicesConfigFields = Schemastery.TypeT<typeof Config>;
+/** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
+type WebSearchServicesConfig = UnwrapVolatile<WebSearchServicesConfigFields>;
 //#endregion
 //#region src/runner.d.ts
 type SpawnFn = typeof spawn;
@@ -67,6 +71,6 @@ declare class SearchServicesProvider implements WebSearchProvider {
 declare const name = "dsh-plus-web-search-services";
 /** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
 declare const inject: readonly ['web'];
-declare function apply(ctx: Context, config: WebSearchServicesConfig): void;
+declare function apply(ctx: Context, config: WebSearchServicesConfig | WebSearchServicesConfigFields): void;
 //#endregion
 export { Config, PROVIDER_ID, SETTINGS_NS, SearchServicesProvider, apply, inject, name };

package/lib/index.js

@@ -1,55 +1,11 @@
-import z from "@deepseek-ai/schemastery";
+import { unwrapVolatile } from "@dsh-plus/shared";
 import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { WebError } from "@deepseek-ai/dsh-web";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
-//#endregion
-//#region src/config.ts
-/**
-* 配置单一事实源：cordis 行级 Config（组合默认值，patch 层可覆盖）与 settings
-* namespace（用户层 $DSH_HOME/settings.yaml，热生效）共用同一 schemastery schema。
-*
-* 密钥主来源是 search-services skill 的 env 文件（envFile，默认
-* ~/.config/search-services/env），保持 skill 单事实源、零搬迁。行级 keys 仅为
-* 覆盖逃生舱；按存储规范 role('secret') 字段只允许行级注入，settings 用户层勿填。
-* @module web-search-services/config
-*/
-const SETTINGS_NS = "dsh-plus-web-search-services";
-const DEFAULT_ENV_FILE = "~/.config/search-services/env";
-const DEFAULT_TIMEOUT_MS = 55e3;
-const DEFAULT_PRIORITY = [
-	"tavily",
-	"exa",
-	"openai-chat"
-];
-const PRIORITY_ENTRY = z.union([
-	"tavily",
-	"exa",
-	"openai-chat"
-]);
-const KeysSchema = z.object({
-	tavily: z.string().role("secret").description("Tavily API key（覆盖 envFile 的 TAVILY_API_KEY；行级注入专用）").default(""),
-	exa: z.string().role("secret").description("Exa API key（覆盖 envFile 的 EXA_API_KEY；行级注入专用）").default(""),
-	openaiApiKey: z.string().role("secret").description("OpenAI-compatible API key（覆盖 SEARCH_OPENAI_API_KEY；行级注入专用）").default(""),
-	openaiBaseUrl: z.string().description("OpenAI-compatible base URL（覆盖 SEARCH_OPENAI_BASE_URL）").default(""),
-	openaiModel: z.string().description("OpenAI-compatible 搜索模型名（覆盖 SEARCH_OPENAI_MODEL）").default("")
-});
-const Config = z.object({
-	scriptPath: z.string().description("search.py 路径（支持 ~ 展开）；空串 = 使用随包内置脚本副本").default(""),
-	envFile: z.string().description("skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile").default(DEFAULT_ENV_FILE),
-	python: z.string().description("python 可执行文件").default("python3"),
-	priority: z.array(PRIORITY_ENTRY).description("后端优先级：靠前的先尝试，失败自动回退到下一个").default([...DEFAULT_PRIORITY]),
-	timeoutMs: z.natural().min(1e3).description("单次搜索子进程超时（毫秒），应低于 dsh-tool-web 的 searchTimeoutMs").default(DEFAULT_TIMEOUT_MS),
-	keys: KeysSchema.default({
-		tavily: "",
-		exa: "",
-		openaiApiKey: "",
-		openaiBaseUrl: "",
-		openaiModel: ""
-	})
-});
+import z from "@deepseek-ai/schemastery";
 /** 由 web 请求 + 插件配置生成 search.py 的 argv（不含解释器与脚本路径）。 */
 function buildSearchArgv(cfg, request) {
 	const query = request.query.trim();
@@ -118,6 +74,12 @@ function asNonEmptyString(value) {
 function asArray(value) {
 	return Array.isArray(value) ? value : [];
 }
+/** snippet 截断上限：官方 deepseek provider 的摘录是短引文；Tavily content /
+*  Exa highlights 原始值可达整页文本，直接透传会撑爆工具结果上下文。 */
+const SNIPPET_MAX_CHARS = 500;
+function truncateSnippet(text) {
+	return text.length <= SNIPPET_MAX_CHARS ? text : `${text.slice(0, SNIPPET_MAX_CHARS)}…`;
+}
 function makeSource(url, title, snippet, publishedAt) {
 	return {
 		url,
@@ -157,8 +119,9 @@ function normalizeTavily(raw) {
 	const payload = payloadOf(raw);
 	const sources = sourcesFromResults(payload.results, (item) => {
 		const url = asNonEmptyString(item.url);
+		const content = asNonEmptyString(item.content);
 		if (url === void 0) return void 0;
-		return makeSource(url, asNonEmptyString(item.title), asNonEmptyString(item.content), asNonEmptyString(item.published_date));
+		return makeSource(url, asNonEmptyString(item.title), content !== void 0 ? truncateSnippet(content) : void 0, asNonEmptyString(item.published_date));
 	});
 	return finish(asNonEmptyString(payload.answer), sources);
 }
@@ -167,7 +130,7 @@ function normalizeExa(raw) {
 		const url = asNonEmptyString(item.url) ?? asNonEmptyString(item.id);
 		if (url === void 0) return void 0;
 		const highlights = asArray(item.highlights).map((h) => asNonEmptyString(h)).filter((h) => h !== void 0);
-		return makeSource(url, asNonEmptyString(item.title), highlights.length > 0 ? highlights.join(" ") : void 0, asNonEmptyString(item.publishedDate));
+		return makeSource(url, asNonEmptyString(item.title), highlights.length > 0 ? truncateSnippet(highlights.join(" ")) : void 0, asNonEmptyString(item.publishedDate));
 	}));
 }
 const MARKDOWN_LINK = /\[([^\]]*)\]\((https?:\/\/[^)\s]+)\)/g;
@@ -406,29 +369,58 @@ var SearchServicesProvider = class {
 	}
 };
 //#endregion
+//#region src/config.ts
+/**
+* 配置单一事实源：cordis 行级 Config（组合默认值，patch 层可覆盖）与 settings
+* namespace（用户层 $DSH_HOME/settings.yaml，热生效）共用同一 schemastery schema。
+*
+* 密钥主来源是 search-services skill 的 env 文件（envFile，默认
+* ~/.config/search-services/env），保持 skill 单事实源、零搬迁。行级 keys 仅为
+* 覆盖逃生舱；按存储规范 role('secret') 字段只允许行级注入，settings 用户层勿填。
+* @module web-search-services/config
+*/
+const SETTINGS_NS = "dsh-plus-web-search-services";
+const DEFAULT_ENV_FILE = "~/.config/search-services/env";
+const DEFAULT_TIMEOUT_MS = 55e3;
+const DEFAULT_PRIORITY = [
+	"tavily",
+	"exa",
+	"openai-chat"
+];
+const PRIORITY_ENTRY = z.union([
+	"tavily",
+	"exa",
+	"openai-chat"
+]);
+const KeysSchema = z.object({
+	tavily: z.string().role("secret").description("Tavily API key（覆盖 envFile 的 TAVILY_API_KEY；行级注入专用）").default(""),
+	exa: z.string().role("secret").description("Exa API key（覆盖 envFile 的 EXA_API_KEY；行级注入专用）").default(""),
+	openaiApiKey: z.string().role("secret").description("OpenAI-compatible API key（覆盖 SEARCH_OPENAI_API_KEY；行级注入专用）").default(""),
+	openaiBaseUrl: z.string().description("OpenAI-compatible base URL（覆盖 SEARCH_OPENAI_BASE_URL）").default(""),
+	openaiModel: z.string().description("OpenAI-compatible 搜索模型名（覆盖 SEARCH_OPENAI_MODEL）").default("")
+});
+const Config = z.object({
+	scriptPath: z.string().description("search.py 路径（支持 ~ 展开）；空串 = 使用随包内置脚本副本").default("").volatile(),
+	envFile: z.string().description("skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile").default(DEFAULT_ENV_FILE).volatile(),
+	python: z.string().description("python 可执行文件").default("python3").volatile(),
+	priority: z.array(PRIORITY_ENTRY).description("后端优先级：靠前的先尝试，失败自动回退到下一个").default([...DEFAULT_PRIORITY]).volatile(),
+	timeoutMs: z.natural().min(1e3).description("单次搜索子进程超时（毫秒），应低于 dsh-tool-web 的 searchTimeoutMs").default(DEFAULT_TIMEOUT_MS).volatile(),
+	keys: KeysSchema.default({
+		tavily: "",
+		exa: "",
+		openaiApiKey: "",
+		openaiBaseUrl: "",
+		openaiModel: ""
+	}).volatile()
+});
+//#endregion
 //#region src/index.ts
 const name = "dsh-plus-web-search-services";
 /** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
 const inject = ["web"];
 function apply(ctx, config) {
-	const provider = new SearchServicesProvider(configSource(ctx, config));
+	const provider = new SearchServicesProvider(() => unwrapVolatile(config));
 	ctx.effect(() => ctx.web.registerSearchProvider(provider), "dsh-plus-web-search-services: register search provider");
 }
-/**
-* 配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）在时优先生效，
-* 缺席/detach 回落 cordis 行级 config（官方 installSection 可选消费范式）。
-*/
-function configSource(ctx, rowConfig) {
-	let current = () => rowConfig;
-	ctx.inject(["settings"], (settingsCtx) => {
-		settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, rowConfig, {
-			setSource: (source) => {
-				current = source;
-			},
-			onChange: () => {}
-		});
-	});
-	return () => current();
-}
 //#endregion
 export { Config, PROVIDER_ID, SETTINGS_NS, SearchServicesProvider, apply, inject, name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/web-search-services",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "dsh-plus service plugin: web_search 免费后端聚合——经官方 ctx.web provider 扩展点桥接 search-services skill（Tavily/Exa/OpenAI Chat 免费额度，优先级+自动回退+key 配置），官方 web_search 工具与输出格式零修改",
   "type": "module",
   "main": "lib/index.js",
@@ -18,17 +18,20 @@
     "src",
     "scripts"
   ],
+  "dependencies": {
+    "@dsh-plus/shared": "0.1.22"
+  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-web": "^0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-settings": "^0.1.7-alpha.2",
+    "@deepseek-ai/dsh-web": "^0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-settings": "0.1.6-alpha.2",
-    "@deepseek-ai/dsh-web": "0.1.6-alpha.2",
-    "@deepseek-ai/schemastery": "3.18.2"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-settings": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-web": "0.1.7-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.4"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -8,6 +8,7 @@
  * @module web-search-services/config
  */
 import z from '@deepseek-ai/schemastery'
+import type { UnwrapVolatile } from '@dsh-plus/shared'
 
 import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
 
@@ -49,33 +50,43 @@ const KeysSchema = z.object({
     .default(''),
 })
 
+// 0.1.7：全字段 `.volatile()`——条目进入 settings describe 视图（卡片可读写；
+// keys 内 role('secret') 字段由 describe/write 层做密文遮蔽，用户层勿填），
+// loader 原位提交活动引用，current() 现取即热。
 export const Config = z.object({
   scriptPath: z
     .string()
     .description('search.py 路径（支持 ~ 展开）；空串 = 使用随包内置脚本副本')
-    .default(DEFAULT_SCRIPT_PATH),
+    .default(DEFAULT_SCRIPT_PATH)
+    .volatile(),
   envFile: z
     .string()
     .description('skill 密钥 env 文件路径（支持 ~ 展开）；空串表示不读 envFile')
-    .default(DEFAULT_ENV_FILE),
-  python: z.string().description('python 可执行文件').default('python3'),
+    .default(DEFAULT_ENV_FILE)
+    .volatile(),
+  python: z.string().description('python 可执行文件').default('python3').volatile(),
   priority: z
     .array(PRIORITY_ENTRY)
     .description('后端优先级：靠前的先尝试，失败自动回退到下一个')
-    .default([...DEFAULT_PRIORITY]),
+    .default([...DEFAULT_PRIORITY])
+    .volatile(),
   timeoutMs: z
     .natural()
     .min(1000)
     .description('单次搜索子进程超时（毫秒），应低于 dsh-tool-web 的 searchTimeoutMs')
-    .default(DEFAULT_TIMEOUT_MS),
+    .default(DEFAULT_TIMEOUT_MS)
+    .volatile(),
   keys: KeysSchema.default({
     tavily: '',
     exa: '',
     openaiApiKey: '',
     openaiBaseUrl: '',
     openaiModel: '',
-  }),
+  }).volatile(),
 })
 
-export type WebSearchServicesConfig = Schemastery.TypeT<typeof Config>
+/** 活动字段形态（0.1.7 loader 解析产物：volatile 字段为活动引用）。 */
+export type WebSearchServicesConfigFields = Schemastery.TypeT<typeof Config>
+/** 平面配置形态（消费面的读取形态，由活动引用解包得到）。 */
+export type WebSearchServicesConfig = UnwrapVolatile<WebSearchServicesConfigFields>
 export type KeysConfig = WebSearchServicesConfig['keys']

package/src/index.ts

@@ -10,8 +10,9 @@
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-settings'
 import type {} from '@deepseek-ai/dsh-web'
+import { unwrapVolatile } from '@dsh-plus/shared'
 
-import { Config, SETTINGS_NS, type WebSearchServicesConfig } from './config.ts'
+import type { WebSearchServicesConfig, WebSearchServicesConfigFields } from './config.ts'
 import { SearchServicesProvider } from './provider.ts'
 
 export const name = 'dsh-plus-web-search-services'
@@ -19,33 +20,18 @@ export const name = 'dsh-plus-web-search-services'
 /** 行级 inject：dsh-web 服务激活后才应用本行（provider 注册即需 ctx.web）。 */
 export const inject = ['web'] as const
 
+export { Config, SETTINGS_NS } from './config.ts'
 export { PROVIDER_ID, SearchServicesProvider } from './provider.ts'
-export { Config, SETTINGS_NS }
 
-export function apply(ctx: Context, config: WebSearchServicesConfig): void {
-  const provider = new SearchServicesProvider(configSource(ctx, config))
+// config 运行期为 loader 解析的 volatile 活动字段（用户层 override 并入行级
+// config，写入原位提交）——每次读现取平面快照，替代 0.1.6 installSection/setSource。
+export function apply(
+  ctx: Context,
+  config: WebSearchServicesConfig | WebSearchServicesConfigFields,
+): void {
+  const provider = new SearchServicesProvider(() => unwrapVolatile(config))
   ctx.effect(
     () => ctx.web.registerSearchProvider(provider),
     'dsh-plus-web-search-services: register search provider',
   )
 }
-
-/**
- * 配置源：settings 用户层（$DSH_HOME/settings.yaml，热生效）在时优先生效，
- * 缺席/detach 回落 cordis 行级 config（官方 installSection 可选消费范式）。
- */
-function configSource(
-  ctx: Context,
-  rowConfig: WebSearchServicesConfig,
-): () => WebSearchServicesConfig {
-  let current: () => WebSearchServicesConfig = () => rowConfig
-  ctx.inject(['settings'], (settingsCtx) => {
-    settingsCtx.settings.installSection(ctx, SETTINGS_NS, Config, rowConfig, {
-      setSource: (source) => {
-        current = source
-      },
-      onChange: () => {},
-    })
-  })
-  return () => current()
-}

package/src/normalize.ts

@@ -25,6 +25,14 @@ function asArray(value: unknown): unknown[] {
   return Array.isArray(value) ? value : []
 }
 
+/** snippet 截断上限：官方 deepseek provider 的摘录是短引文；Tavily content /
+ *  Exa highlights 原始值可达整页文本，直接透传会撑爆工具结果上下文。 */
+const SNIPPET_MAX_CHARS = 500
+
+export function truncateSnippet(text: string): string {
+  return text.length <= SNIPPET_MAX_CHARS ? text : `${text.slice(0, SNIPPET_MAX_CHARS)}…`
+}
+
 function makeSource(
   url: string,
   title?: string,
@@ -76,11 +84,12 @@ function normalizeTavily(raw: JsonObject): WebSearchResult {
   const payload = payloadOf(raw)
   const sources = sourcesFromResults(payload.results, (item) => {
     const url = asNonEmptyString(item.url)
+    const content = asNonEmptyString(item.content)
     if (url === undefined) return undefined
     return makeSource(
       url,
       asNonEmptyString(item.title),
-      asNonEmptyString(item.content),
+      content !== undefined ? truncateSnippet(content) : undefined,
       asNonEmptyString(item.published_date),
     )
   })
@@ -98,7 +107,7 @@ function normalizeExa(raw: JsonObject): WebSearchResult {
     return makeSource(
       url,
       asNonEmptyString(item.title),
-      highlights.length > 0 ? highlights.join(' ') : undefined,
+      highlights.length > 0 ? truncateSnippet(highlights.join(' ')) : undefined,
       asNonEmptyString(item.publishedDate),
     )
   })