dsh-deepseek-web-login 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 本项目遵循大致语义化版本；日期为本地时间。
 
+## 0.6.2 — 2026-09-27
+
+> 长尾工具压成**一行**：`` `签名` — 首句 ``。目录再瘦一圈，能力依然一个不少。
+
+### 改进
+
+- **长尾工具改成一行格式**，并拆出独立的 `## Other tools` 小节：
+
+  ```
+  ## Available tools
+  ### pwsh
+  <完整描述>
+  pwsh(command: string, description: string)
+    command: …
+    description: …
+
+  ## Other tools
+
+  Call these the same way. Parameter names and types are in the parentheses.
+
+  - `job_list(limit?: number)` — 列出后台任务
+  - `web_search(queries: string[])` — 联网搜索
+  ```
+
+  这是抄 cuckoo 的（它的 `getFormattedJsApiForPrompt` 对每个工具就是 `` 1. `read(path)` — 读取文件 ``）：
+  **名字 / 签名 / 一句话三样都在，但只占一行** —— 长尾工具的价值就是"让模型知道它存在、怎么传参"。
+- 那句话取**首句**（到第一个句末点）而不是开头若干字，上限 160 字符：描述的第一句才是"这工具干什么"。
+
+### 实测收益（13 个真实 DSH 工具定义）
+
+| 版本 | 目录长度 | 累计省 |
+|---|---|---|
+| 0.5.3（JSON + 完整描述） | 18,217 | — |
+| 0.6.0（签名 + 完整描述） | 14,815 | 19% |
+| 0.6.1（分级：长尾 240 字） | 11,000+ | 42% |
+| **0.6.2（长尾一行）** | **9,024** | **50%** |
+
+按 61 个工具（50,942 字符）外推，约 **省 2.5 万字符 ≈ 6,000 token / 每轮上下文**，
+**零额外请求**、**工具一个不少**。
+
+### 说明
+
+- ⚠️ **这是 head 的变化**：重启 DSH 后**第一个任务会全量重发一次**，之后照常。
+- 🔴 **渲染顺序变了**：以前是"按 DSH 下发的原序"，现在是**分组**（核心在前、长尾在后），
+  各组**内部**仍保持原序。所以目录里工具的排列与之前不同。
+- 长尾工具丢的是「遇错怎么办」那类长指引；核心工具（真正常用的）一个字没动。
+- 调整名单：改 `src/protocol.ts` 的 `CORE_TOOLS` 集合 —— 那是唯一的开关。
+
+## 0.6.1 — 2026-09-27
+
+> 工具目录按「用不用得上」分级：常用的给完整说明，长尾的只留一句话。**能力一个不少。**
+
+### 改进
+
+- **工具描述分两级下发**。0.6.0 把参数从 JSON 换成签名之后，目录里最大的一块变成了
+  **工具级描述**（13 个真实工具实测：描述 10,369 字符 vs 参数段 7,588）。现在：
+  - **核心工具** —— `pwsh` / `bash` / `run_code` / `read` / `write` / `edit` / `grep` / `glob` /
+    `ls` / `todo_write` / `skill` / `present` / `ask_user_question`：描述按 3200 字符完整保留，参数说明也在；
+  - **长尾工具** —— 描述压到 240 字符，且**不输出参数说明**。
+- ⚠️ **两级都保留工具名与参数签名** ⇒ 模型照样能调用长尾工具，只是看不到长篇说明。
+  **这不是「禁用工具」**，不会出现「要用的工具看不见」。
+
+### 为什么这么分（实测依据）
+
+扫最近 8 个会话的 **826 次真实工具调用**：
+
+| 工具 | 次数 | 占比 |
+|---|---|---|
+| pwsh | 230 | 27.8% |
+| run_code | 206 | 24.9% |
+| edit | 140 | 16.9% |
+| read | 80 | 9.7% |
+| write | 66 | 8.0% |
+| bash | 46 | 5.6% |
+| 其余（grep/glob/present/skill/todo_write…） | 58 | 7.1% |
+
+**覆盖 90% 的调用只需要 6 个工具**，而 DSH 每轮下发 **61 个**。剩下的那些
+（jobs / goal / ralph / workflow / web / subagent 系列…）在这 8 个会话里**一次都没被调用过**，
+却每个都在每一轮的上下文里占几百字符。
+
+### 实测收益（13 个真实 DSH 工具定义）
+
+| 版本 | 目录长度 | 累计省 |
+|---|---|---|
+| 0.5.3（JSON + 完整描述） | 18,217 | — |
+| 0.6.0（签名 + 完整描述） | 14,815 | 19% |
+| **0.6.1（分级）** | **10,544** | **42%** |
+
+按 61 个工具（50,942 字符）外推，约 **省 2.1 万字符 ≈ 5,000 token / 每轮上下文**，
+而且**零额外请求**。
+
+### 说明
+
+- ⚠️ **这是 head 的变化**：重启 DSH 后**第一个任务会全量重发一次**，之后照常。
+- 长尾工具丢的是「遇错怎么办」那类长指引；**真正常用的工具一个字没动**。
+- 想调整名单：改 `src/protocol.ts` 里的 `CORE_TOOLS` 集合 —— 那是唯一的开关。
+  哪天真觉得某个工具"看不懂了"，把它加进去重新构建即可。
+
 ## 0.6.0 — 2026-09-27
 
 > 工具目录改用**紧凑类型签名**下发，不再给模型贴原始 JSON。

package/lib/index.js

@@ -3325,6 +3325,65 @@ function staleAuthMessage(auth) {
 */
 const MAX_DESCRIPTION_CHARS = 3200;
 /**
+* 「核心工具」白名单 —— 只有它们值得在**每轮上下文**里都带上完整描述。
+*
+* 依据（2026-09-27 实测）：扫最近 8 个会话的 **826 次真实工具调用**，
+*   pwsh 27.8% / run_code 24.9% / edit 16.9% / read 9.7% / write 8.0% / bash 5.6%
+*   ⇒ **覆盖 90% 的调用只需要这几个**。
+* 其余 50 多个工具（jobs / goal / ralph / workflow / web / subagent / cordis_*…）
+* 在那 8 个会话里**一次都没被调用过**，却每个都在每轮上下文里占几百字符。
+*
+* ⚠️ 分级只压**说明文字**：工具名与参数签名字字不少 ⇒ 模型照样能调用它们，
+* 只是看不到长篇说明（"遇错怎么办"那类指引只对常用工具才值得每轮都带着）。
+* 要调整就把名字增删进这个集合 —— 这是唯一的开关。
+*/
+const CORE_TOOLS = /* @__PURE__ */ new Set([
+	"pwsh",
+	"bash",
+	"run_code",
+	"read",
+	"write",
+	"edit",
+	"grep",
+	"glob",
+	"ls",
+	"todo_write",
+	"skill",
+	"present",
+	"ask_user_question"
+]);
+/**
+* 长尾工具「一行说明」里那句话的上限。
+*
+* 长尾工具只占**一行**：`` `name(签名)` — 首句 ``（抄 cuckoo 的 `getFormattedJsApiForPrompt`，
+* 它对每个工具就是 `` 1. `read(path)` — 读取文件 ``）。
+* 取**首句**而不是开头 160 字 —— 描述的第一句才是"这工具干什么"，后面的多是用法细节。
+*/
+const MAX_TAIL_DESCRIPTION_CHARS = 160;
+/** 工具是否属于核心组（决定描述给多长、要不要带参数说明）。 */
+function isCoreTool(name) {
+	return CORE_TOOLS.has(String(name ?? ""));
+}
+/** 取描述的首句（到第一个句末点），再按上限截断。 */
+function tailSentence(text) {
+	const flat = text.replace(/\s+/g, " ").trim();
+	const stop = flat.search(/\.(\s|$)/);
+	return truncate(stop >= 0 ? flat.slice(0, stop + 1) : flat, MAX_TAIL_DESCRIPTION_CHARS);
+}
+/**
+* 长尾工具的**一行**形式：`` `name(签名)` — 首句 ``。
+*
+* 名字、签名、一句话三样都在，但只占一行 —— 长尾工具的价值就是"让模型知道它存在、怎么传参"。
+* ⚠️ 签名认不出来时（`buildToolSignature` 返回 null）不冒险拼一行，只给名字 + 首句，
+* 让模型知道有这个工具、但不会照着残缺签名瞎传参（它会被兜底文案要求去问用户）。
+*/
+function formatTailTool(tool) {
+	const sentence = tailSentence(String(tool.description ?? ""));
+	const signature = buildToolSignature(tool, false);
+	if (signature === null) return `\`${tool.name}\` — ${sentence}`;
+	return `\`${signature.replace(/\s+/g, " ").trim()}\` — ${sentence}`;
+}
+/**
 * 工具目录（一节）的总预算。
 *
 * 2026-09-12 从 24_000 提到 56_000。理由：实测 DSH 下发 61 个工具、不截描述时共需
@@ -3557,8 +3616,11 @@ function renderParamType(schema, depth) {
 *
 * ⚠️ 返回 `null` = "这份 parameters 不敢降级"，调用方必须回退到原始 JSON：
 * 宁可多花字符，也不能让模型看不见参数。
+*
+* @param withParamDocs 是否附上每个参数的说明。核心工具传 `true`，长尾工具传 `false`
+*   —— 签名里已经有参数名、类型、必填性，那是模型写出正确 arguments 的**最小信息集**。
 */
-function buildToolSignature(tool) {
+function buildToolSignature(tool, withParamDocs = true) {
 	try {
 		const node = asRecord(tool.parameters);
 		if (!node) return `${tool.name}()`;
@@ -3567,7 +3629,7 @@ function buildToolSignature(tool) {
 		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)) {
+		if (withParamDocs) for (const [name, def] of Object.entries(map)) {
 			const description = paramDescription(def);
 			if (description) lines.push(`  ${name}: ${truncate(description, MAX_PARAM_DESC_CHARS)}`);
 		}
@@ -3579,16 +3641,35 @@ function buildToolSignature(tool) {
 /**
 * 渲染工具目录。
 *
-* 每个工具占一段：`### 名字` / 工具描述（≤3200 字符，不轻易砍）/ **参数紧凑签名**。
-* 签名由 `buildToolSignature` 产出；它只在 schema 不敢降级时返回 null，那时才贴原始 JSON Schema。
+* 结构（0.6.2）：
+*
+*     ## Available tools   ← 核心工具：一段一个（`### 名字` / 完整描述 / 紧凑签名 / 参数说明）
+*     ## Other tools       ← 长尾工具：**一行一个** —— `` - `name(签名)` — 首句 ``
+*
+* 长尾用一行格式是抄 cuckoo 的（它的 `getFormattedJsApiForPrompt` 对每个工具就是
+* `` 1. `read(path)` — 读取文件 ``）：同样三样信息（名字 / 签名 / 一句话），
+* 三行能装下的，一行就够 —— 而 61 个工具里有 48 个是长尾。
+*
+* ⚠️ **两级都保留工具名与参数签名** ⇒ 模型照样能调用长尾工具，只是看不到长篇说明。
 */
 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];
-		const signature = buildToolSignature(tool);
+	const coreTools = tools.filter((tool) => isCoreTool(tool?.name));
+	const tailTools = tools.filter((tool) => !isCoreTool(tool?.name));
+	/**
+	* 预算用尽时的兜底：**必须把剩下的工具名说出来**，并明确要求别猜参数。
+	* 旧写法只有一句 "(remaining tools omitted for length)"，模型连"还有哪些工具存在"
+	* 都不知道，只能盲猜名字和参数 —— 实测 61 个工具里 26 个就是这样静默消失的。
+	*/
+	const omittedNotice = (rest) => {
+		const names = rest.map((item) => String(item?.name ?? "")).filter(Boolean);
+		return `\n(⚠️ The following ${names.length} tools are NOT described above (omitted for length): ${names.join(", ")}. If you need one of them, ask the user for its exact parameters — do NOT guess them.)`;
+	};
+	for (let index = 0; index < coreTools.length; index += 1) {
+		const tool = coreTools[index];
+		const signature = buildToolSignature(tool, true);
 		let parametersText = signature ?? "";
 		if (signature === null) {
 			let schemaText = "";
@@ -3606,13 +3687,35 @@ function buildToolSection(tools, maxChars = MAX_TOOLS_SECTION_CHARS) {
 			parametersText
 		].join("\n");
 		if (budget - block.length < 0) {
-			const rest = tools.slice(index).map((item) => String(item?.name ?? "")).filter(Boolean);
-			parts.push(`\n(⚠️ The following ${rest.length} tools are NOT described above (omitted for length): ${rest.join(", ")}. If you need one of them, ask the user for its exact parameters — do NOT guess them.)`);
-			break;
+			parts.push(omittedNotice([...coreTools.slice(index), ...tailTools]));
+			return parts.join("\n");
 		}
 		budget -= block.length;
 		parts.push(block);
 	}
+	if (tailTools.length > 0) {
+		const header = [
+			"",
+			"## Other tools",
+			"",
+			"Call these the same way. Parameter names and types are in the parentheses."
+		].join("\n");
+		if (budget - header.length < 0) {
+			parts.push(omittedNotice(tailTools));
+			return parts.join("\n");
+		}
+		budget -= header.length;
+		parts.push(header);
+		for (let index = 0; index < tailTools.length; index += 1) {
+			const line = `- ${formatTailTool(tailTools[index])}`;
+			if (budget - line.length < 0) {
+				parts.push(omittedNotice(tailTools.slice(index)));
+				break;
+			}
+			budget -= line.length;
+			parts.push(line);
+		}
+	}
 	return parts.join("\n");
 }
 function flattenText(blocks, out = []) {
@@ -8791,7 +8894,7 @@ async function checkForUpdate(current, fetchImpl) {
 * 兜底常量与 package.json 的一致性由 `tests/check-smoke.mjs` 守着，不会漂。
 */
 /** 与 package.json 保持一致的兜底版本（由测试保证不会漂）。 */
-const FALLBACK_VERSION = "0.6.0";
+const FALLBACK_VERSION = "0.6.2";
 let cached;
 /** 本插件版本（如 `0.1.26`）。 */
 function pluginVersion() {