chatccc 0.2.227 → 0.2.229

package/src/builtin/file-tools.ts

@@ -3,13 +3,22 @@ import { createHash, randomBytes } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { copyFile, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 
 import { jsonSchema, tool, type ToolSet } from "ai";
 
 import { isDangerousCommand, type PermissionGate, type PermissionRequest } from "./permissions.js";
 import { killProcessTree } from "./proc-tree-kill.js";
+import {
+  webFetchForTool,
+  webSearchForTool,
+  type WebFetchInput,
+  type WebFetchOutput,
+  type WebSearchInput,
+  type WebSearchOutput,
+} from "./web-tools.js";
 
 const MAX_READ_BYTES = 1024 * 1024;
 const MAX_LIST_ENTRIES = 200;
@@ -180,10 +189,24 @@ export interface ApplyPatchOutput {
   changedFiles: ApplyPatchFileChange[];
 }
 
+/**
+ * 把 `~` / `~/x`（含反斜杠 `~\\x`）展开为用户主目录绝对路径。
+ * `~user/x` 形式不展开（Node 无内置支持），保持原样交给后续解析。
+ * 供路径工具共用：技能索引里 `~/...` 路径可直接传给 read_file 等工具。
+ */
+export function expandHomePath(value: string): string {
+  if (value === "~") return homedir();
+  if (value.startsWith("~/") || value.startsWith("~\\")) {
+    return join(homedir(), value.slice(2));
+  }
+  return value;
+}
+
 function resolveToolPath(cwd: string, value: string | undefined): string {
   const raw = value?.trim();
   if (!raw) return resolve(cwd);
-  return isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+  const expanded = expandHomePath(raw);
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
 }
 
 function toPositiveInt(value: number | undefined): number | undefined {
@@ -1403,5 +1426,34 @@ export function createBuiltinFileTools(
         return applyPatchForTool(cwd, input);
       },
     }),
+    // 联网工具：只读外部网络操作，不触碰本地文件系统，无需权限询问
+    websearch: tool<WebSearchInput, WebSearchOutput>({
+      description:
+        "Search the web (DuckDuckGo, no API key) and return matching titles, URLs, and snippets. Use when you need current or external information not available locally, e.g. latest docs, news, or package versions.",
+      inputSchema: jsonSchema<WebSearchInput>({
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          query: { type: "string", description: "Search query." },
+          maxResults: { type: "number", description: "Optional result count, default 5, capped at 10." },
+        },
+        required: ["query"],
+      }),
+      execute: (input, options) => webSearchForTool(input, { abortSignal: options.abortSignal }),
+    }),
+    webfetch: tool<WebFetchInput, WebFetchOutput>({
+      description:
+        "Fetch a URL and return its readable text content (HTML stripped, truncated). Use for documentation pages, articles, or API docs. Only http/https URLs are allowed.",
+      inputSchema: jsonSchema<WebFetchInput>({
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          url: { type: "string", description: "http/https URL to fetch." },
+          maxChars: { type: "number", description: "Optional text length cap, default 10000, capped at 100000." },
+        },
+        required: ["url"],
+      }),
+      execute: (input, options) => webFetchForTool(input, { abortSignal: options.abortSignal }),
+    }),
   };
 }

package/src/builtin/index.ts

@@ -230,21 +230,26 @@ export class ChatSession {
     );
   }
 
-  /** 组装系统提示词：固定规则 + 项目指令 + 技能索引 + 用户补充 + 运行时上下文 */
+  /**
+   * 组装系统提示词。顺序遵循“稳定性优先”原则（缓存命中友好）：
+   * 固定规则 → 项目指令 → runtime 上下文 → 用户补充 → 技能索引（最后）。
+   * 技能索引是最易变的部分（热加载，任何 SKILL.md 变化都会改前缀），
+   * 放最后可以让前面的稳定内容尽量命中缓存，只丢尾段。
+   */
   private buildSystemPrompt(skills: BuiltinSkill[]): string {
     const systemContent = [SYSTEM_PROMPT];
     const projectInstructions = readProjectInstructionFiles(this.cwd);
     if (projectInstructions) {
       systemContent.push("", projectInstructions);
     }
+    systemContent.push("", buildRuntimeWorkspacePrompt(this.cwd));
+    if (this.customSystemPrompt) {
+      systemContent.push("", this.customSystemPrompt);
+    }
     const skillsPrompt = buildSkillsIndexPrompt(skills);
     if (skillsPrompt) {
       systemContent.push("", skillsPrompt);
     }
-    if (this.customSystemPrompt) {
-      systemContent.push("", this.customSystemPrompt);
-    }
-    systemContent.push("", buildRuntimeWorkspacePrompt(this.cwd));
     return systemContent.join("\n");
   }
 
@@ -405,6 +410,8 @@ export class ChatSession {
       system: SUMMARY_SYSTEM_PROMPT,
       messages: [{ role: "user", content: buildSummaryPrompt(plan) }],
       abortSignal: signal,
+      // 温度 0：相同输入尽量产出相同摘要，避免压缩后上下文前缀随机漂移破坏缓存
+      temperature: 0,
     });
 
     if (!result.text.trim()) return 0;

package/src/builtin/skills.ts

@@ -17,7 +17,6 @@ import { readdirSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-
 export type SkillSource = "deepccc" | "codex" | "cursor" | "claude";
 export type SkillScope = "global" | "project";
 
@@ -140,11 +139,27 @@ export function buildDefaultSkillDirs(cwd: string): SkillDirSpec[] {
   ];
 }
 
+/**
+ * 把技能绝对路径转成 prompt 展示形式：主目录下的路径缩写为 `~/...`（跨机器、
+ * 跨用户稳定，避免用户名/盘符差异导致 system 前缀变化破坏缓存命中）；
+ * 分隔符统一为 `/`。主目录外的路径保持绝对路径（仅统一分隔符）。
+ */
+export function normalizeSkillPathForPrompt(skillPath: string): string {
+  const home = homedir().replace(/[\\/]+$/, "").replace(/\\/g, "/");
+  const normalized = skillPath.replace(/\\/g, "/");
+  if (normalized === home) return "~";
+  if (normalized.startsWith(home + "/")) {
+    return "~" + normalized.slice(home.length);
+  }
+  return normalized;
+}
+
 /**
  * 生成 skill 索引提示词（注入 system prompt）。
  * 索引只含 name + description + 来源 + 路径，并指示模型在任务匹配时
  * 先用 read_file 读取 SKILL.md 全文再执行；同时声明"创建技能"约定
  * （模型在对话中应把新技能创建到 ~/.deepccc/skills 或项目 .deepccc/skills）。
+ * 路径经 normalizeSkillPathForPrompt 缩写，保持跨机器前缀稳定。
  */
 export function buildSkillsIndexPrompt(skills: BuiltinSkill[]): string {
   if (skills.length === 0) return "";
@@ -155,7 +170,7 @@ export function buildSkillsIndexPrompt(skills: BuiltinSkill[]): string {
     "On name conflicts: DeepCCC > Codex > Cursor > Claude wins; within one source, project scope wins over global.",
     "When a user request matches a skill's description, first read its full SKILL.md with read_file, then follow the instructions in it exactly.",
     "",
-    ...skills.map((s) => `- **${s.name}** [${s.source}:${s.scope}] (\`${s.skillPath}\`): ${s.description || "(no description)"}`),
+    ...skills.map((s) => `- **${s.name}** [${s.source}:${s.scope}] (\`${normalizeSkillPathForPrompt(s.skillPath)}\`): ${s.description || "(no description)"}`),
     "",
     "## Creating Skills",
     "When the user asks to create a skill, create it as a Codex-style directory skill at",

package/src/builtin/web-tools.ts

@@ -0,0 +1,313 @@
+/**
+ * web-tools.ts — websearch / webfetch 内置工具（agent 端联网，业界主流做法）
+ *
+ * 与 Claude Code 的 WebSearch/WebFetch、Codex 的 web search 相同形态：
+ * 模型通过 function calling 调用，agent 进程执行 HTTP 请求，结果回填上下文。
+ * 两者都是只读外部网络操作，不触碰本地文件系统，无需权限询问。
+ *
+ * - websearch：DuckDuckGo HTML 端点（免 API key），返回标题 + URL + 摘要
+ * - webfetch：HTTP GET + HTML 转纯文本，控制大小与超时
+ *
+ * 零新依赖：使用 Node 20 内置 fetch / AbortSignal / Buffer。
+ * 解析逻辑拆成纯函数导出，便于单测；fetch 可通过 options 注入 mock。
+ */
+
+export interface WebSearchInput {
+  query: string;
+  /** 返回结果条数上限，默认 5，上限 10 */
+  maxResults?: number;
+}
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+export interface WebSearchOutput {
+  query: string;
+  results: WebSearchResult[];
+  truncated: boolean;
+  durationMs: number;
+}
+
+export interface WebFetchInput {
+  url: string;
+  /** 返回纯文本字符数上限，默认 10000，上限 100000 */
+  maxChars?: number;
+}
+
+export interface WebFetchOutput {
+  url: string;
+  contentType: string;
+  title: string;
+  text: string;
+  chars: number;
+  truncated: boolean;
+  durationMs: number;
+}
+
+export const WEB_SEARCH_TIMEOUT_MS = 15_000;
+export const WEB_FETCH_TIMEOUT_MS = 20_000;
+export const WEB_SEARCH_DEFAULT_RESULTS = 5;
+export const WEB_SEARCH_MAX_RESULTS = 10;
+export const WEB_FETCH_DEFAULT_CHARS = 10_000;
+export const WEB_FETCH_MAX_CHARS = 100_000;
+/** webfetch 读取响应体的大小上限（超出即截断），防止把整个大文件拉进上下文 */
+export const WEB_FETCH_MAX_BYTES = 512 * 1024;
+
+const SEARCH_UA =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+
+export type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface WebToolOptions {
+  abortSignal?: AbortSignal;
+  /** 测试注入用，默认全局 fetch */
+  fetchImpl?: FetchLike;
+  timeoutMs?: number;
+}
+
+function normalizeMaxResults(value: number | undefined): number {
+  if (value === undefined) return WEB_SEARCH_DEFAULT_RESULTS;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("maxResults must be a positive integer when provided");
+  }
+  return Math.min(value, WEB_SEARCH_MAX_RESULTS);
+}
+
+function normalizeMaxChars(value: number | undefined): number {
+  if (value === undefined) return WEB_FETCH_DEFAULT_CHARS;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("maxChars must be a positive integer when provided");
+  }
+  return Math.min(value, WEB_FETCH_MAX_CHARS);
+}
+
+function buildSignal(timeoutMs: number, abortSignal?: AbortSignal): AbortSignal {
+  const signals: AbortSignal[] = [AbortSignal.timeout(timeoutMs)];
+  if (abortSignal) signals.push(abortSignal);
+  return signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+}
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#0?39;/gi, "'")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&#(\d+);/g, (_, n: string) => {
+      try {
+        return String.fromCodePoint(Number(n));
+      } catch {
+        return "";
+      }
+    })
+    .replace(/&#x([0-9a-f]+);/gi, (_, h: string) => {
+      try {
+        return String.fromCodePoint(parseInt(h, 16));
+      } catch {
+        return "";
+      }
+    })
+    .replace(/&amp;/gi, "&");
+}
+
+function stripTags(s: string): string {
+  return decodeEntities(s.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim());
+}
+
+/** 提取 <title> 文本（用于 webfetch 结果），无则返回空字符串 */
+export function extractHtmlTitle(html: string): string {
+  const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+  return m ? stripTags(m[1]) : "";
+}
+
+/**
+ * HTML 转纯文本：
+ * 去掉 script/style/noscript/svg/注释 → 块级元素补换行 → 去标签 → 解实体 → 压缩空白。
+ */
+export function htmlToPlainText(html: string): string {
+  let text = html
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, " ")
+    .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, " ")
+    .replace(/<svg\b[^>]*>[\s\S]*?<\/svg>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<\/(p|div|li|tr|h[1-6]|pre|blockquote|section|article|table|ul|ol|header|footer|nav|dl|dd|dt)>/gi, "\n")
+    .replace(/<(br|hr)\s*\/?>/gi, "\n")
+    .replace(/<[^>]+>/g, "");
+
+  text = decodeEntities(text);
+
+  return text
+    .split("\n")
+    .map((line) => line.replace(/\s+/g, " ").trim())
+    .filter((line, i, arr) => line !== "" || (i > 0 && arr[i - 1] !== ""))
+    .join("\n")
+    .trim();
+}
+
+/** 解码 DuckDuckGo 结果链接：/l/?uddg=<encoded> 还原为目标 URL */
+export function decodeDdgHref(href: string): string {
+  let h = href.trim();
+  if (h.startsWith("//")) h = "https:" + h;
+  try {
+    const u = new URL(h);
+    if (u.hostname === "duckduckgo.com" && u.pathname.startsWith("/l/")) {
+      const uddg = u.searchParams.get("uddg");
+      if (uddg) return decodeURIComponent(uddg);
+    }
+    return u.toString();
+  } catch {
+    return h;
+  }
+}
+
+/**
+ * 解析 DuckDuckGo HTML 搜索结果页（html.duckduckgo.com/html）。
+ * 提取 result__a（标题 + href）与 result__snippet（摘要）。
+ */
+export function parseDuckDuckGoHtml(html: string): WebSearchResult[] {
+  const results: WebSearchResult[] = [];
+  const titleRe = /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+  const snippetRe = /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+
+  const titleMatches = [...html.matchAll(titleRe)];
+  const snippetMatches = [...html.matchAll(snippetRe)];
+
+  titleMatches.forEach((m, i) => {
+    const title = stripTags(m[2]);
+    const url = decodeDdgHref(m[1]);
+    const snippet = snippetMatches[i] ? stripTags(snippetMatches[i][1]) : "";
+    if (!title && !url) return;
+    results.push({ title, url, snippet });
+  });
+
+  return results;
+}
+
+/** 读取响应体并限制字节数（超出截断），避免整页大文件进入上下文 */
+async function readBodyWithLimit(res: Response, maxBytes: number): Promise<{ text: string; truncated: boolean }> {
+  if (!res.body) {
+    const text = await res.text();
+    return { text, truncated: Buffer.byteLength(text, "utf8") > maxBytes };
+  }
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  let truncated = false;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    if (total + value.byteLength > maxBytes) {
+      const remaining = maxBytes - total;
+      if (remaining > 0) chunks.push(value.subarray(0, remaining));
+      truncated = true;
+      await reader.cancel().catch(() => {});
+      break;
+    }
+    chunks.push(value);
+    total += value.byteLength;
+  }
+  return { text: Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8"), truncated };
+}
+
+/**
+ * websearch：DuckDuckGo HTML 搜索（免 API key），返回标题 + URL + 摘要。
+ * 网络失败抛错（成为 tool-error），搜索无结果返回空数组（不是错误）。
+ */
+export async function webSearchForTool(
+  input: WebSearchInput,
+  options: WebToolOptions = {},
+): Promise<WebSearchOutput> {
+  const query = input.query?.trim();
+  if (!query) throw new Error("query is required");
+
+  const maxResults = normalizeMaxResults(input.maxResults);
+  const startedAt = Date.now();
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+
+  const res = await fetchImpl(url, {
+    headers: {
+      "User-Agent": SEARCH_UA,
+      Accept: "text/html,application/xhtml+xml",
+    },
+    redirect: "follow",
+    signal: buildSignal(options.timeoutMs ?? WEB_SEARCH_TIMEOUT_MS, options.abortSignal),
+  });
+  if (!res.ok) {
+    throw new Error(`web search failed: HTTP ${res.status} ${res.statusText}`);
+  }
+
+  const { text } = await readBodyWithLimit(res, WEB_FETCH_MAX_BYTES);
+  const all = parseDuckDuckGoHtml(text);
+  const results = all.slice(0, maxResults);
+
+  return {
+    query,
+    results,
+    truncated: all.length > results.length,
+    durationMs: Date.now() - startedAt,
+  };
+}
+
+/**
+ * webfetch：HTTP GET + HTML 转纯文本。
+ * 只允许 http/https（防 file:// 等本地协议），非 2xx 抛错。
+ */
+export async function webFetchForTool(
+  input: WebFetchInput,
+  options: WebToolOptions = {},
+): Promise<WebFetchOutput> {
+  const raw = input.url?.trim();
+  if (!raw) throw new Error("url is required");
+
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`invalid URL: ${raw}`);
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`unsupported protocol: ${parsed.protocol} (only http/https allowed)`);
+  }
+
+  const maxChars = normalizeMaxChars(input.maxChars);
+  const startedAt = Date.now();
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  const res = await fetchImpl(parsed.toString(), {
+    headers: {
+      "User-Agent": SEARCH_UA,
+      Accept: "text/html,application/xhtml+xml,text/plain;q=0.9,*/*;q=0.8",
+    },
+    redirect: "follow",
+    signal: buildSignal(options.timeoutMs ?? WEB_FETCH_TIMEOUT_MS, options.abortSignal),
+  });
+  if (!res.ok) {
+    throw new Error(`HTTP ${res.status} ${res.statusText} for ${parsed.toString()}`);
+  }
+
+  const contentType = res.headers.get("content-type") ?? "";
+  const { text: body, truncated: bodyTruncated } = await readBodyWithLimit(res, WEB_FETCH_MAX_BYTES);
+  const title = extractHtmlTitle(body);
+  const plain = htmlToPlainText(body);
+  const text = plain.length > maxChars ? plain.slice(0, maxChars) : plain;
+
+  return {
+    url: parsed.toString(),
+    contentType,
+    title,
+    text,
+    chars: text.length,
+    truncated: bodyTruncated || plain.length > maxChars,
+    durationMs: Date.now() - startedAt,
+  };
+}