dsh-deepseek-web-login 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 本项目遵循大致语义化版本；日期为本地时间。
 
+## 0.6.0 — 2026-09-27
+
+> 工具目录改用**紧凑类型签名**下发，不再给模型贴原始 JSON。
+
+### 改进
+
+- **每个工具的参数不再原样贴 JSON**。原先那行是
+  `Parameters (JSON Schema): {"type":"object","properties":{…}}`，现在渲染成类型签名：
+
+  ```
+  ### read_file
+  Read a file.
+  read_file(file_path: string, offset?: number, limit?: number)
+    file_path: Path to read, resolved by the filesystem backend.
+    offset: 1-based first line to return. Defaults to 1.
+  ```
+
+  模型要写出 `arguments`，真正需要的只是**参数名、类型、必填性**；那串 JSON 里
+  `"type":"…"`、键名的引号、每个参数各套一层对象，全是结构性样板。
+- **两种参数形态都认**。DSH 自家工具是**扁平**写法（顶层键直接是参数名、`required: true`
+  挂在参数自己身上），而 `@deepseek-ai/dsh-tools` 的 `schemaOf()` 把它**原样透传**、不做规范化；
+  标准 JSON Schema 包裹形态（`{type:'object',properties:{…}}`）一并支持。
+- 嵌套对象/数组/枚举/`anyOf` 都能渲染：`{content: string, status: string}[]`、
+  `"view" | "create" | "str_replace" | "insert"`。
+
+### 实测（2026-09-27，取自 13 个真实 DSH 工具定义）
+
+- 参数段 **7,588 → 4,186 字符（省 45%）**，`required` 与参数描述全部保留、零回退。
+- 折算到**整个工具目录约省 18%** —— 目录里更大的一块是工具级描述（同批样本 10,369 字符），
+  那块**没动**：它藏的是"遇错怎么办"的指引，不许砍。
+- 按 61 个工具 / 50,942 字符的目录估，约 **省 9,500 字符 ≈ 2,400 token**，占单轮输入 **3%** 左右。
+  ⇒ 别指望它解决"提示词太长"：真正的大头是消息历史与环境注入，不在工具目录。
+
+### 说明 / 风险
+
+- ⚠️ **这是 head 的变化**：升级后**第一个任务会全量重发一次**（投喂链断），之后照常。
+- ⚠️ 模型看到的参数形态变了（JSON → 类型签名）。签名是模型最熟的形态，预期更好读；
+  但**首次实测若发现参数写错，请立刻反馈** —— 回退只改一处：`buildToolSection` 里不用
+  `buildToolSignature` 即退回原始 JSON（回退分支与"认不出就不许发空参数"由
+  `tests/check-tool-signature.mjs` 守着）。
+- 参数描述超过 160 字符会被截断；**工具级描述仍是 3200 上限，不受影响**。
+
 ## 0.5.3 — 2026-09-27
 
 > 修掉一个"重启后前 3 分钟里限流不换号"的窗口 —— 0.5.2 的漏洞。

package/lib/index.js

@@ -3443,24 +3443,167 @@ function truncate(text, max) {
 	if (text.length <= max) return text;
 	return `${text.slice(0, max - 3)}...`;
 }
-/** 渲染工具目录（含 JSON Schema）。 */
+/**
+* 参数级描述的截断长度。
+*
+* 紧凑签名保留的是「参数名 + 类型 + 必填性」—— 那是模型写出正确 arguments 的**最小信息集**。
+* 参数描述是锦上添花：第 160 字符之后通常是举例或边角说明（`path` 这类参数压根没有），
+* 砍掉它比砍掉工具级描述划算得多 —— 工具级描述里藏的是「遇错怎么办」。
+*/
+const MAX_PARAM_DESC_CHARS = 160;
+/** 嵌套展开的深度上限：异常 schema（自引用、深层嵌套）不该把工具目录撑爆。 */
+const MAX_SIGNATURE_DEPTH = 4;
+/** `parameters` 是对象时才当映射用（`parameters: []` 这类异常值直接忽略）。 */
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/**
+* 「标准 JSON Schema 包裹」形态的顶层关键字。顶层**只**出现这些键 ⇒ 是
+* `{type:'object',properties:{…},required:[…]}` 包裹；出现别的键 ⇒ 那些键就是参数名。
+*/
+const SCHEMA_TOP_KEYS = /* @__PURE__ */ new Set([
+	"type",
+	"properties",
+	"required",
+	"additionalProperties",
+	"description",
+	"title",
+	"default",
+	"examples",
+	"$schema",
+	"definitions",
+	"$defs"
+]);
+/**
+* `parameters` 是「标准包裹」还是「DSH 扁平写法」。
+*
+* ⚠️ 两种都得认（2026-09-27 读 `@deepseek-ai/dsh-tools/lib/index.js` 的 `schemaOf()` 确认）：
+* 它把工具定义里的 `parameters` **原样透传**给 provider，不做任何规范化。而 DSH 自家工具
+* 清一色写**扁平**形态 —— 顶层键直接是参数名、`required: true` 写在参数自己身上：
+*
+*     parameters: { command: { type: 'string', required: true, description: '…' },
+*                   description: { type: 'string', required: true, description: '…' } }
+*
+* 常见的标准包裹形态仍要支持（第三方工具可能按 OpenAI 惯例写）。
+*/
+function isWrappedSchema(node) {
+	const properties = asRecord(node.properties);
+	if (!properties || Object.keys(properties).length === 0) return false;
+	if (!Object.values(properties).every((value) => asRecord(value) !== null)) return false;
+	return Object.keys(node).every((key) => SCHEMA_TOP_KEYS.has(key));
+}
+/** 参数自己身上的必填标记（DSH 扁平写法）。 */
+function isRequiredParam(def) {
+	return asRecord(def)?.required === true;
+}
+/** 读参数描述并压平空白。 */
+function paramDescription(schema) {
+	const description = asRecord(schema)?.description;
+	return typeof description === "string" ? description.replace(/\s+/g, " ").trim() : "";
+}
+/**
+* 渲染**一层参数映射**（`{参数名: 定义}`）→ `['a: string', 'b?: number']`。
+*
+* ⚠️ `depth` 必须**由调用方透传**。第一版在这里硬编码了 `1`，于是每下沉一层深度就重置，
+* `MAX_SIGNATURE_DEPTH` 完全失效 —— 深层嵌套（甚至自引用 schema）会一路展开到栈溢出，
+* 再被 catch 吞掉，表现为"莫名其妙回退到原始 JSON"。
+*/
+function renderParamMap(map, requiredList, depth) {
+	const fromList = new Set(requiredList);
+	return Object.entries(map).map(([name, def]) => {
+		return `${name}${fromList.has(name) || isRequiredParam(def) ? "" : "?"}: ${renderParamType(def, depth)}`;
+	});
+}
+/**
+* 渲染一个参数的类型表达式：`string` / `T[]` / `{a: T, b?: U}` / `"x" | "y"`。
+*
+* 认不出来的形态一律退化成 `any` —— 签名本身永远合法。只有整份 parameters
+* 都不敢降级时，才由 `buildToolSignature` 返回 null 让调用方回退到原始 JSON。
+*/
+function renderParamType(schema, depth) {
+	const node = asRecord(schema);
+	if (!node) return "any";
+	if (depth > MAX_SIGNATURE_DEPTH) return "any";
+	if (Array.isArray(node.enum) && node.enum.length > 0) return node.enum.map((value) => JSON.stringify(value)).join(" | ");
+	const variants = Array.isArray(node.anyOf) ? node.anyOf : Array.isArray(node.oneOf) ? node.oneOf : null;
+	if (variants && variants.length > 0) {
+		const rendered = variants.map((item) => renderParamType(item, depth + 1));
+		return [...new Set(rendered)].join(" | ");
+	}
+	const declared = typeof node.type === "string" ? node.type : "";
+	if (declared === "array" || !declared && node.items !== void 0) {
+		const item = renderParamType(node.items, depth + 1);
+		return item.includes("|") ? `(${item})[]` : `${item}[]`;
+	}
+	const properties = asRecord(node.properties);
+	if (declared === "object" || properties) {
+		const inner = properties ? renderParamMap(properties, [], depth + 1) : [];
+		const extra = asRecord(node.additionalProperties);
+		if (extra) inner.push(`[key: string]: ${renderParamType(extra, depth + 1)}`);
+		if (inner.length === 0) return "object";
+		return `{${inner.join(", ")}}`;
+	}
+	return declared || "any";
+}
+/**
+* 把工具参数渲染成紧凑签名（0.6.0）：
+*
+*     read_file(file_path: string, offset?: number, limit?: number)
+*       file_path: Path to read, resolved by the filesystem backend.
+*
+* 为什么值得做：原先直接贴 `JSON.stringify(parameters)`。那串文本里**结构性样板**占了大头
+* —— 每个参数都要套一层 `{"type":"…","description":"…"}`、键名与类型值全带引号，
+* 而模型写出 arguments 真正需要的只是**参数名、类型、必填性**。
+*
+* ⚠️ 返回 `null` = "这份 parameters 不敢降级"，调用方必须回退到原始 JSON：
+* 宁可多花字符，也不能让模型看不见参数。
+*/
+function buildToolSignature(tool) {
+	try {
+		const node = asRecord(tool.parameters);
+		if (!node) return `${tool.name}()`;
+		const wrapped = isWrappedSchema(node);
+		const map = wrapped ? asRecord(node.properties) : node;
+		const args = renderParamMap(map, wrapped && Array.isArray(node.required) ? node.required.filter((key) => typeof key === "string") : [], 1);
+		if (args.length === 0) return Object.keys(node).length === 0 ? `${tool.name}()` : null;
+		const lines = [`${tool.name}(${args.join(", ")})`];
+		for (const [name, def] of Object.entries(map)) {
+			const description = paramDescription(def);
+			if (description) lines.push(`  ${name}: ${truncate(description, MAX_PARAM_DESC_CHARS)}`);
+		}
+		return lines.join("\n");
+	} catch {
+		return null;
+	}
+}
+/**
+* 渲染工具目录。
+*
+* 每个工具占一段：`### 名字` / 工具描述（≤3200 字符，不轻易砍）/ **参数紧凑签名**。
+* 签名由 `buildToolSignature` 产出；它只在 schema 不敢降级时返回 null，那时才贴原始 JSON Schema。
+*/
 function buildToolSection(tools, maxChars = MAX_TOOLS_SECTION_CHARS) {
 	if (!tools || tools.length === 0) return "";
 	const parts = ["", "## Available tools"];
 	let budget = Math.max(0, Math.min(MAX_TOOLS_SECTION_CHARS, maxChars));
 	for (let index = 0; index < tools.length; index += 1) {
 		const tool = tools[index];
-		let schemaText = "";
-		try {
-			schemaText = JSON.stringify(tool.parameters ?? {});
-		} catch {
-			schemaText = "{}";
+		const signature = buildToolSignature(tool);
+		let parametersText = signature ?? "";
+		if (signature === null) {
+			let schemaText = "";
+			try {
+				schemaText = JSON.stringify(tool.parameters ?? {});
+			} catch {
+				schemaText = "{}";
+			}
+			parametersText = `Parameters (JSON Schema): ${schemaText}`;
 		}
 		const block = [
 			"",
 			`### ${tool.name}`,
 			truncate(String(tool.description ?? "").replace(/\s+/g, " ").trim(), MAX_DESCRIPTION_CHARS),
-			`Parameters (JSON Schema): ${schemaText}`
+			parametersText
 		].join("\n");
 		if (budget - block.length < 0) {
 			const rest = tools.slice(index).map((item) => String(item?.name ?? "")).filter(Boolean);
@@ -8648,7 +8791,7 @@ async function checkForUpdate(current, fetchImpl) {
 * 兜底常量与 package.json 的一致性由 `tests/check-smoke.mjs` 守着，不会漂。
 */
 /** 与 package.json 保持一致的兜底版本（由测试保证不会漂）。 */
-const FALLBACK_VERSION = "0.5.3";
+const FALLBACK_VERSION = "0.6.0";
 let cached;
 /** 本插件版本（如 `0.1.26`）。 */
 function pluginVersion() {