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

package/lib/index.js

@@ -1,5 +1,6 @@
 import z from "@deepseek-ai/schemastery";
 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";
@@ -16,7 +17,6 @@ import { spawn } from "node:child_process";
 * @module web-search-services/config
 */
 const SETTINGS_NS = "dsh-plus-web-search-services";
-const DEFAULT_SCRIPT_PATH = "~/.dsh/skills/search-services/scripts/search.py";
 const DEFAULT_ENV_FILE = "~/.config/search-services/env";
 const DEFAULT_TIMEOUT_MS = 55e3;
 const DEFAULT_PRIORITY = [
@@ -37,7 +37,7 @@ const KeysSchema = z.object({
 	openaiModel: z.string().description("OpenAI-compatible 搜索模型名（覆盖 SEARCH_OPENAI_MODEL）").default("")
 });
 const Config = z.object({
-	scriptPath: z.string().description("search-services skill 的 search.py 路径（支持 ~ 展开）").default(DEFAULT_SCRIPT_PATH),
+	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]),
@@ -126,6 +126,12 @@ function makeSource(url, title, snippet, publishedAt) {
 		...publishedAt !== void 0 ? { publishedAt } : {}
 	};
 }
+/** skill 各服务 request() 统一信封 {ok, service, status, data: <API 响应>}；
+* 取 data 为业务 payload，data 缺失/空对象时回退顶层（旧形状容差）。 */
+function payloadOf(raw) {
+	const data = asObject(raw.data);
+	return Object.keys(data).length > 0 ? data : raw;
+}
 function finish(content, sources) {
 	const seen = /* @__PURE__ */ new Set();
 	const deduped = sources.filter((source) => {
@@ -148,15 +154,16 @@ function sourcesFromResults(results, pick) {
 	return out;
 }
 function normalizeTavily(raw) {
-	const sources = sourcesFromResults(raw.results, (item) => {
+	const payload = payloadOf(raw);
+	const sources = sourcesFromResults(payload.results, (item) => {
 		const url = asNonEmptyString(item.url);
 		if (url === void 0) return void 0;
 		return makeSource(url, asNonEmptyString(item.title), asNonEmptyString(item.content), asNonEmptyString(item.published_date));
 	});
-	return finish(asNonEmptyString(raw.answer), sources);
+	return finish(asNonEmptyString(payload.answer), sources);
 }
 function normalizeExa(raw) {
-	return finish(void 0, sourcesFromResults(raw.results, (item) => {
+	return finish(void 0, sourcesFromResults(payloadOf(raw).results, (item) => {
 		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);
@@ -308,6 +315,14 @@ function runProcess(opts) {
 * @module web-search-services/provider
 */
 const PROVIDER_ID = "search-services";
+/**
+* scriptPath 解析：空串 = 随包内置脚本副本（tgz 内 scripts/search.py，与 lib/
+* 同级；src 直跑时为包根 scripts/）。非空按 ~ 展开。
+*/
+function resolveScriptPath(scriptPath) {
+	if (scriptPath.trim() !== "") return expandHome(scriptPath);
+	return fileURLToPath(new URL("../scripts/search.py", import.meta.url));
+}
 /** 各后端在合并环境（进程 env ⊕ envFile ⊕ 行级 keys）中的可用性判定变量。 */
 const BACKEND_KEY_VARS = {
 	tavily: ["TAVILY_API_KEY", "TAVILY_API_KEYS"],
@@ -343,7 +358,7 @@ var SearchServicesProvider = class {
 	/** 廉价本地检查：脚本存在 + 优先级内至少一个后端有 key；不做网络调用。 */
 	available() {
 		const cfg = this.current();
-		if (!existsSync(expandHome(cfg.scriptPath))) return false;
+		if (!existsSync(resolveScriptPath(cfg.scriptPath))) return false;
 		const env = this.childEnv(cfg);
 		return cfg.priority.some((backend) => BACKEND_KEY_VARS[backend].some((name) => (env[name]?.trim() ?? "") !== ""));
 	}
@@ -365,7 +380,7 @@ var SearchServicesProvider = class {
 		try {
 			return await runProcess({
 				command: cfg.python,
-				args: [expandHome(cfg.scriptPath), ...argv],
+				args: [resolveScriptPath(cfg.scriptPath), ...argv],
 				env: this.childEnv(cfg),
 				timeoutMs: cfg.timeoutMs,
 				...signal !== void 0 ? { signal } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/web-search-services",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -15,7 +15,8 @@
   },
   "files": [
     "lib",
-    "src"
+    "src",
+    "scripts"
   ],
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",

package/scripts/README.md

@@ -0,0 +1,34 @@
+# scripts/：search-services skill Python 脚本的项目维护副本
+
+本目录是从 `~/.dsh/skills/search-services/scripts/` **原样复制**的单向副本
+（标准库实现，无第三方依赖），供 `@dsh-plus/web-search-services` 插件经
+`python3 search.py search ...` 子进程桥接调用。**skill 本体不受本仓维护影响。**
+
+## 为什么是 Python 桥接（特例声明）
+
+> **本插件是特例，不是先例。** dsh-plus 集成外部 HTTP 服务（provider、工具、
+> webhook 等）**默认直接用 TS 原生实现**（进程内 fetch、编译期契约、无进程边界）。
+> 仅当需求明确要求复用一套已存在、持续维护、且逻辑非平凡的外部编排
+> （本例：search-services skill 的链内 fallback、`TAVILY_API_KEYS` 多 key
+> 轮转、intent 服务链、per-service 参数细节）时，才允许整体桥接其脚本，
+> 把外部实现当作单一事实源，本仓只维护「dsh-web 契约 ↔ CLI」薄适配层。
+
+判定标准（新增集成时自检）：
+
+1. 外部逻辑是否已在维护中且有独立演进（skill/CLI 工具）？——否则 TS 原生重写更便宜。
+2. 桥接节省的是否是**编排逻辑**而非一个 POST 请求？——单接口直调一律 TS 原生。
+3. 失败域、超时、密钥注入是否都能在薄适配层兜住？——兜不住则不桥接。
+
+## 同步策略
+
+- **单向**：skill → 本目录。skill 升级后人工比对同步（diff 后整体覆盖），
+  不做自动同步、不做双向回写；本目录的定向修改（如有）须注释 `dsh-plus:`
+  标记并记录在下表。
+- 同步时复核文件清单：`search.py fetch.py fetch_playwright.py env_loader.py
+  openai_chat.py context7.py exa.py tavily.py`（`__pycache__` 不入仓）。
+
+## 本仓定向修改记录
+
+| 日期 | 文件 | 修改 | 原因 |
+|---|---|---|---|
+| — | — | 暂无（verbatim 副本） | — |

package/scripts/context7.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Context7 REST API helper.
+
+不使用 MCP，仅通过 Context7 HTTP API 获取库文档、代码片段和相关上下文。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+from env_loader import load_env_file
+
+load_env_file()
+
+
+class ServiceError(RuntimeError):
+    """服务调用失败。"""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, details: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.details = details
+
+
+class MissingAPIKey(ServiceError):
+    """缺少 API Key。"""
+
+
+DEFAULT_BASE_URL = "https://context7.com/api"
+
+
+def _timeout() -> float:
+    return float(os.getenv("SEARCH_TIMEOUT") or os.getenv("CONTEXT7_TIMEOUT") or "30")
+
+
+def _base_url() -> str:
+    return (os.getenv("CONTEXT7_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _api_key() -> str:
+    key = os.getenv("CONTEXT7_API_KEY", "").strip()
+    if not key:
+        raise MissingAPIKey("缺少 CONTEXT7_API_KEY")
+    return key
+
+
+def _decode_response(raw: bytes) -> Any:
+    text = raw.decode("utf-8", "replace")
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+def request(
+    method: str,
+    path: str,
+    *,
+    params: Optional[Dict[str, Any]] = None,
+    body: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """调用 Context7 API，返回带元信息的 JSON。"""
+
+    query = urllib.parse.urlencode({k: v for k, v in (params or {}).items() if v is not None})
+    url = f"{_base_url()}{path}"
+    if query:
+        url = f"{url}?{query}"
+
+    headers = {
+        "Authorization": f"Bearer {_api_key()}",
+        "Accept": "application/json",
+        "User-Agent": "pi-search-services-skill/1.0",
+    }
+    data = None
+    if body is not None:
+        data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+
+    req = urllib.request.Request(url, data=data, headers=headers, method=method.upper())
+    try:
+        with urllib.request.urlopen(req, timeout=_timeout()) as resp:
+            parsed = _decode_response(resp.read())
+            return {"ok": True, "service": "context7", "status": resp.status, "data": parsed}
+    except urllib.error.HTTPError as exc:
+        details = _decode_response(exc.read())
+        raise ServiceError(f"Context7 HTTP {exc.code}", status=exc.code, details=details) from exc
+    except urllib.error.URLError as exc:
+        raise ServiceError(f"Context7 网络错误: {exc.reason}", details=str(exc)) from exc
+
+
+def search_libraries(library_name: str, query: Optional[str] = None, fast: bool = False) -> Dict[str, Any]:
+    """搜索 Context7 库 ID。"""
+
+    return request(
+        "GET",
+        "/v2/libs/search",
+        params={"libraryName": library_name, "query": query, "fast": str(fast).lower() if fast else None},
+    )
+
+
+def get_context(
+    library_id: str,
+    query: str,
+    *,
+    response_type: str = "json",
+    fast: bool = False,
+) -> Dict[str, Any]:
+    """获取某个库的文档上下文。"""
+
+    return request(
+        "GET",
+        "/v2/context",
+        params={
+            "libraryId": library_id,
+            "query": query,
+            "type": response_type,
+            "fast": str(fast).lower() if fast else None,
+        },
+    )
+
+
+def lookup(
+    library: str,
+    query: str,
+    *,
+    response_type: str = "json",
+    fast: bool = False,
+) -> Dict[str, Any]:
+    """先解析库 ID，再获取文档上下文。library 可为 /owner/repo 或库名。"""
+
+    if library.startswith("/"):
+        library_id = library
+        search_result = None
+    else:
+        search_result = search_libraries(library, query=query, fast=fast)
+        results = (search_result.get("data") or {}).get("results") or []
+        if not results:
+            raise ServiceError("Context7 未找到匹配库", status=404, details=search_result.get("data"))
+        library_id = results[0].get("id")
+        if not library_id:
+            raise ServiceError("Context7 搜索结果缺少 library id", details=results[0])
+
+    context = get_context(library_id, query, response_type=response_type, fast=fast)
+    context["resolvedLibraryId"] = library_id
+    if search_result is not None:
+        context["librarySearch"] = search_result.get("data")
+    return context
+
+
+def refresh(library_name: str, *, branch: Optional[str] = None, git_token: Optional[str] = None) -> Dict[str, Any]:
+    body: Dict[str, Any] = {"libraryName": library_name}
+    if branch:
+        body["branch"] = branch
+    if git_token:
+        body["gitToken"] = git_token
+    return request("POST", "/v1/refresh", body=body)
+
+
+def add_website(website_url: str) -> Dict[str, Any]:
+    return request("POST", "/v2/add/website", body={"websiteUrl": website_url})
+
+
+def add_llmstxt(llmstxt_url: str) -> Dict[str, Any]:
+    return request("POST", "/v2/add/llmstxt", body={"llmstxtUrl": llmstxt_url})
+
+
+def add_openapi(openapi_url: str) -> Dict[str, Any]:
+    return request("POST", "/v2/add/openapi", body={"openApiUrl": openapi_url})
+
+
+def raw(method: str, path: str, *, params_json: Optional[str] = None, body_json: Optional[str] = None) -> Dict[str, Any]:
+    params = json.loads(params_json) if params_json else None
+    body = json.loads(body_json) if body_json else None
+    return request(method, path, params=params, body=body)
+
+
+def _print_json(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2))
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Context7 REST API helper")
+    sub = parser.add_subparsers(dest="operation", required=True)
+
+    p = sub.add_parser("search-libraries", help="搜索库 ID")
+    p.add_argument("--library", "--library-name", dest="library", required=True)
+    p.add_argument("--query")
+    p.add_argument("--fast", action="store_true")
+
+    p = sub.add_parser("context", help="获取文档上下文")
+    p.add_argument("--library-id", required=True)
+    p.add_argument("--query", required=True)
+    p.add_argument("--type", default="json")
+    p.add_argument("--fast", action="store_true")
+
+    p = sub.add_parser("lookup", help="按库名/库 ID 查询文档上下文")
+    p.add_argument("--library", required=True)
+    p.add_argument("--query", required=True)
+    p.add_argument("--type", default="json")
+    p.add_argument("--fast", action="store_true")
+
+    p = sub.add_parser("refresh", help="刷新库文档")
+    p.add_argument("--library-name", required=True)
+    p.add_argument("--branch")
+    p.add_argument("--git-token-env", help="从指定环境变量读取 gitToken")
+
+    p = sub.add_parser("add-website", help="提交网站文档源")
+    p.add_argument("--url", required=True)
+
+    p = sub.add_parser("add-llmstxt", help="提交 llms.txt 文档源")
+    p.add_argument("--url", required=True)
+
+    p = sub.add_parser("add-openapi", help="提交 OpenAPI 文档源")
+    p.add_argument("--url", required=True)
+
+    p = sub.add_parser("raw", help="原始 Context7 API 调用")
+    p.add_argument("--method", required=True)
+    p.add_argument("--path", required=True)
+    p.add_argument("--params-json")
+    p.add_argument("--body-json")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.operation == "search-libraries":
+            out = search_libraries(args.library, query=args.query, fast=args.fast)
+        elif args.operation == "context":
+            out = get_context(args.library_id, args.query, response_type=args.type, fast=args.fast)
+        elif args.operation == "lookup":
+            out = lookup(args.library, args.query, response_type=args.type, fast=args.fast)
+        elif args.operation == "refresh":
+            git_token = os.getenv(args.git_token_env, "") if args.git_token_env else None
+            out = refresh(args.library_name, branch=args.branch, git_token=git_token)
+        elif args.operation == "add-website":
+            out = add_website(args.url)
+        elif args.operation == "add-llmstxt":
+            out = add_llmstxt(args.url)
+        elif args.operation == "add-openapi":
+            out = add_openapi(args.url)
+        elif args.operation == "raw":
+            out = raw(args.method, args.path, params_json=args.params_json, body_json=args.body_json)
+        else:
+            parser.error("未知操作")
+            return 2
+        _print_json(out)
+        return 0
+    except ServiceError as exc:
+        _print_json({"ok": False, "service": "context7", "error": str(exc), "status": exc.status, "details": exc.details})
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/env_loader.py

@@ -0,0 +1,46 @@
+"""Search Services skill 环境变量加载器。
+
+从用户私有 env 文件加载变量到当前 Python 进程环境，避免在脚本中硬编码密钥。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+
+DEFAULT_ENV_FILE = Path.home() / ".config" / "search-services" / "env"
+
+
+def _strip_shell_quotes(value: str) -> str:
+    value = value.strip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+        value = value[1:-1]
+    return value
+
+
+def load_env_file(path: str | None = None, *, override: bool = False) -> None:
+    """加载 export KEY=value 格式的私有 env 文件。
+
+    默认不覆盖已存在的环境变量；可用 SEARCH_SERVICES_ENV_FILE 指定路径。
+    """
+
+    env_path = Path(path or os.getenv("SEARCH_SERVICES_ENV_FILE", "") or DEFAULT_ENV_FILE).expanduser()
+    if not env_path.is_file():
+        return
+
+    pattern = re.compile(r"^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=(.*)$")
+    try:
+        for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            match = pattern.match(line)
+            if not match:
+                continue
+            key, value = match.group(1), _strip_shell_quotes(match.group(2))
+            if override or key not in os.environ:
+                os.environ[key] = value
+    except OSError:
+        return