@jc20231028/local-code-agent 0.1.1 → 0.1.4

package/README.md

@@ -27,6 +27,7 @@
 - 進行局部字串替換
 - 寫入 `.py` / `.js` / `.mjs` 後自動做語法檢查，結果會回饋給模型自我修正
 - 執行本地命令（`dotnet build`、`npm test`、`python xxx.py` 等）來編譯/測試/執行程式碼——預設每次執行前會在終端機跳出來問你要不要允許，`--allow-commands` 則整個 session 都自動允許不再詢問
+- 上網查資料：`web_search`（DuckDuckGo 搜尋，回傳標題/連結/摘要）、`web_fetch`（抓單一網頁並轉成純文字給模型讀）——讓模型能回答訓練資料截止日之後的新資訊。預設每次連網前也會在終端機問你要不要允許，`--allow-network` 則整個 session 都自動允許不再詢問
 - 用 `/名稱` 打關鍵字叫出自訂 Skill（見下方「Skill 系統」）
 - 任務進度 Checkpoint：存目標/待辦事項，並自動附上最近對話內容，跨 session 恢復（見下方「任務進度 Checkpoint」）
 
@@ -49,6 +50,13 @@ local-code chat
 npm 只會把執行檔裝進當下專案的 `node_modules/.bin`，不會加進系統 PATH，
 在 cmd 直接打 `local-code` 會抓不到指令。這種情況下要嘛加 `-g` 重裝，要嘛用 `npx local-code chat` 執行。
 
+如果你已經用沒加 `-g` 的方式裝過，先移除本地安裝再改用全域安裝：
+
+```powershell
+npm uninstall @jc20231028/local-code-agent
+npm install -g @jc20231028/local-code-agent
+```
+
 `provider` / `model` 留空時，`local-code chat` 第一次啟動就會直接跳出互動選單讓你選（見下方「初始化設定」），
 不需要先手動跑 `local-code init`——`init` 只是用來印出設定檔範例，不是必要步驟。
 
@@ -89,6 +97,8 @@ node ./bin/local-code.js init
   "lmStudioBaseUrl": "http://127.0.0.1:1234",
   "maxSteps": 12,
   "allowCommands": false,
+  "allowWrites": false,
+  "allowNetwork": false,
   "temperature": 0.2
 }
 ```
@@ -133,6 +143,20 @@ node ./bin/local-code.js run "編譯並執行這個 C# 專案"
 node ./bin/local-code.js run "執行測試並修正失敗案例" --allow-commands
 ```
 
+同樣地，模型呼叫 `write_file`、`append_file`、`replace_in_file`、`make_directory` 這些會建立/覆寫/修改檔案或資料夾的工具時，預設也會先印出要變更的路徑（和內容預覽）並問 `Allow this change? [y/N]:`，按 `y` 才會真的寫入；沒有 TTY 時一樣直接安全拒絕。想跳過詢問可以加 `--allow-writes`：
+
+```powershell
+node ./bin/local-code.js run "幫我建立這個功能的檔案" --allow-writes
+```
+
+模型呼叫 `web_search`（查 DuckDuckGo）或 `web_fetch`（抓網頁內容）時，一樣預設會先問 `Allow this network request? [y/N]:`，按 `y` 才會真的發出連線；沒有 TTY 時直接安全拒絕。這讓模型能查到訓練資料截止日之後的新資訊（例如新版本號、近期新聞），不用只靠舊的訓練知識回答。想跳過詢問可以加 `--allow-network`：
+
+```powershell
+node ./bin/local-code.js run "幫我查一下最新的 Node.js LTS 版本" --allow-network
+```
+
+`run_command` 之外的其他工具（`list_files`、`read_file`、`search_text`）只是讀取，不會跳出詢問。每一步驟模型在做什麼、呼叫了哪個工具、帶了什麼參數，都會即時印在終端機（stderr），不會等到最後才一次顯示結果。
+
 列出目前可用的 Skill：
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc20231028/local-code-agent",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "A local coding CLI that uses Ollama or LM Studio models to inspect and modify project files.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,6 +1,4 @@
 import path from "node:path";
-import readline from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
 import {
   loadAppState,
   loadConfig,
@@ -18,7 +16,9 @@ import {
   summarizeProvider
 } from "./runtime.js";
 import {
+  closeSharedReadline,
   color,
+  getSharedReadline,
   isInteractive,
   printNote,
   printSplash,
@@ -116,8 +116,11 @@ function buildProgressHooks() {
     onStep(step) {
       console.error(`step ${step}: waiting for model...`);
     },
+    onReasoning({ step, text }) {
+      console.error(`step ${step} thinking: ${truncateForLog(text, 200)}`);
+    },
     onToolCall(toolCall) {
-      console.error(`step result: called tool "${toolCall.tool}"`);
+      console.error(`step result: called tool "${toolCall.tool}" -> ${summarizeToolCall(toolCall)}`);
     },
     onToolCallError({ step, reason, message, attempt }) {
       const label = reason === "truncated" ? "reply cut off (length limit)" : "invalid tool call JSON";
@@ -129,6 +132,37 @@ function buildProgressHooks() {
   };
 }
 
+function summarizeToolCall(toolCall) {
+  const args = toolCall.args ?? {};
+  switch (toolCall.tool) {
+    case "read_file":
+    case "make_directory":
+      return args.path ?? "";
+    case "write_file":
+    case "append_file":
+      return `${args.path ?? ""} (${String(args.content ?? "").length} chars)`;
+    case "replace_in_file":
+      return `${args.path ?? ""} (find: "${truncateForLog(args.findText ?? "", 40)}")`;
+    case "search_text":
+      return `"${args.query ?? ""}" in ${args.path ?? "."}`;
+    case "list_files":
+      return args.path ?? ".";
+    case "run_command":
+      return [args.command, ...(args.args ?? [])].join(" ");
+    case "web_search":
+      return `"${args.query ?? ""}"`;
+    case "web_fetch":
+      return args.url ?? "";
+    default:
+      return JSON.stringify(args);
+  }
+}
+
+function truncateForLog(text, max) {
+  const flattened = text.replace(/\s+/g, " ").trim();
+  return flattened.length > max ? `${flattened.slice(0, max)}...` : flattened;
+}
+
 function printResult(result) {
   if (result.failed) {
     console.log(`⚠️ ${result.content}`);
@@ -164,7 +198,7 @@ function buildUnknownSkillMessage(token, skills) {
 }
 
 async function runChat(config, skills) {
-  const rl = readline.createInterface({ input, output });
+  const rl = getSharedReadline();
   let activeConfig = { ...config };
   let chatState = await loadChatState(activeConfig);
   let session = createChatSession(activeConfig, chatState.history);
@@ -294,7 +328,7 @@ async function runChat(config, skills) {
       printResult(result);
     }
   } finally {
-    rl.close();
+    closeSharedReadline();
   }
 }
 
@@ -347,7 +381,7 @@ async function runCheckpointCommand(config, subcommand, rest) {
 }
 
 async function cmdCheckpointSave(config) {
-  const rl = readline.createInterface({ input, output });
+  const rl = getSharedReadline();
   try {
     const fields = await collectCheckpointFields(rl);
     const state = await loadAppState(config.statePath);
@@ -359,7 +393,7 @@ async function cmdCheckpointSave(config) {
 
     console.log(`\ncheckpoint saved: ${checkpoint.id}`);
   } finally {
-    rl.close();
+    closeSharedReadline();
   }
 }
 
@@ -453,6 +487,8 @@ async function printInitExample(cwd) {
     lmStudioBaseUrl: "http://127.0.0.1:1234",
     maxSteps: 12,
     allowCommands: false,
+    allowWrites: false,
+    allowNetwork: false,
     temperature: 0.2
   };
 
@@ -518,6 +554,8 @@ Options:
   --model MODEL_NAME
   --workspace PATH
   --allow-commands
+  --allow-writes
+  --allow-network
   --max-steps 12
   --temperature 0.2
   --ollama-base-url http://127.0.0.1:11434

package/src/config.js

@@ -9,6 +9,8 @@ const DEFAULTS = {
   lmStudioBaseUrl: "http://127.0.0.1:1234",
   maxSteps: 12,
   allowCommands: false,
+  allowWrites: false,
+  allowNetwork: false,
   temperature: 0.2
 };
 
@@ -65,7 +67,9 @@ function readEnvConfig() {
     model: process.env.LOCAL_CODE_MODEL,
     ollamaBaseUrl: process.env.OLLAMA_BASE_URL,
     lmStudioBaseUrl: process.env.LM_STUDIO_BASE_URL,
-    allowCommands: parseBoolean(process.env.LOCAL_CODE_ALLOW_COMMANDS)
+    allowCommands: parseBoolean(process.env.LOCAL_CODE_ALLOW_COMMANDS),
+    allowWrites: parseBoolean(process.env.LOCAL_CODE_ALLOW_WRITES),
+    allowNetwork: parseBoolean(process.env.LOCAL_CODE_ALLOW_NETWORK)
   };
 }
 

package/src/tools.js

@@ -1,5 +1,5 @@
 import { checkSyntax } from "./syntaxCheck.js";
-import { confirmCommand } from "./ui.js";
+import { confirmCommand, confirmNetwork, confirmWrite } from "./ui.js";
 
 export function createToolset(workspace) {
   const tools = {
@@ -17,15 +17,22 @@ export function createToolset(workspace) {
       description: [
         "Create or overwrite a UTF-8 file inside the workspace.",
         "For files longer than ~40 lines, write a small skeleton first (imports and function signatures), then use append_file to add the rest in smaller pieces.",
-        "Do not use this to add to a file that already has content you want to keep - use append_file instead, so you never have to retype existing content."
+        "Do not use this to add to a file that already has content you want to keep - use append_file instead, so you never have to retype existing content.",
+        "Unless the session was started with --allow-writes, the user is asked to approve each file change in the terminal before it is written."
       ].join(" "),
       args: { path: "string", content: "string" },
-      run: async ({ path, content }) => withSyntaxCheck(workspace, path, () => workspace.writeFile(path, content))
+      run: async ({ path, content }) => {
+        const approved = await approveWrite(workspace, { action: "write", path, preview: content });
+        return withSyntaxCheck(workspace, path, () => workspace.writeFile(path, content, { approved }));
+      }
     },
     append_file: {
       description: "Append content to the end of a file, creating it if it does not exist. Prefer this over write_file when a file already has content you want to keep.",
       args: { path: "string", content: "string" },
-      run: async ({ path, content }) => withSyntaxCheck(workspace, path, () => workspace.appendFile(path, content))
+      run: async ({ path, content }) => {
+        const approved = await approveWrite(workspace, { action: "append", path, preview: content });
+        return withSyntaxCheck(workspace, path, () => workspace.appendFile(path, content, { approved }));
+      }
     },
     replace_in_file: {
       description: "Replace text inside an existing file.",
@@ -35,11 +42,18 @@ export function createToolset(workspace) {
         replaceText: "string",
         replaceAll: "boolean?"
       },
-      run: async (args) => withSyntaxCheck(
-        workspace,
-        args.path,
-        () => workspace.replaceInFile(args.path, args.findText, args.replaceText, args.replaceAll)
-      )
+      run: async (args) => {
+        const approved = await approveWrite(workspace, {
+          action: "replace",
+          path: args.path,
+          preview: `Find:\n${args.findText}\nReplace with:\n${args.replaceText}`
+        });
+        return withSyntaxCheck(
+          workspace,
+          args.path,
+          () => workspace.replaceInFile(args.path, args.findText, args.replaceText, args.replaceAll, { approved })
+        );
+      }
     },
     search_text: {
       description: "Search for a plain text query across workspace files.",
@@ -49,7 +63,10 @@ export function createToolset(workspace) {
     make_directory: {
       description: "Create a directory recursively in the workspace.",
       args: { path: "string" },
-      run: async ({ path }) => workspace.makeDirectory(path)
+      run: async ({ path }) => {
+        const approved = await approveWrite(workspace, { action: "mkdir", path });
+        return workspace.makeDirectory(path, { approved });
+      }
     },
     run_command: {
       description: "Run a local shell command inside the workspace (e.g. dotnet run, npm test, python script.py) to build, test, or execute code. Unless the session was started with --allow-commands, the user is asked to approve each command in the terminal before it runs.",
@@ -62,6 +79,31 @@ export function createToolset(workspace) {
         const approved = await confirmCommand({ command, args, cwd: workspace.rootPath });
         return workspace.runCommand(command, args, { approved });
       }
+    },
+    web_search: {
+      description: [
+        "Search the public web (DuckDuckGo) and return up to `limit` results as {title, url, snippet}.",
+        "Use this when the user asks about recent events, current versions/releases, prices, or anything that may have changed since your training data - do not answer from memory alone in those cases.",
+        "Follow up with web_fetch on a promising result to read the full page.",
+        "Unless the session was started with --allow-network, the user is asked to approve each network request in the terminal before it runs."
+      ].join(" "),
+      args: { query: "string", limit: "number?" },
+      run: async ({ query, limit = 5 }) => {
+        const approved = await approveNetwork(workspace, { action: "web_search", detail: query });
+        return workspace.searchWeb(query, { approved, limit });
+      }
+    },
+    web_fetch: {
+      description: [
+        "Fetch a web page by URL and return its title and readable text content (HTML tags stripped, truncated to maxChars).",
+        "Use this to read a specific page, e.g. a result from web_search or a URL the user gave you.",
+        "Unless the session was started with --allow-network, the user is asked to approve each network request in the terminal before it runs."
+      ].join(" "),
+      args: { url: "string", maxChars: "number?" },
+      run: async ({ url, maxChars = 8000 }) => {
+        const approved = await approveNetwork(workspace, { action: "web_fetch", detail: url });
+        return workspace.fetchUrl(url, { approved, maxChars });
+      }
     }
   };
 
@@ -89,6 +131,22 @@ export function createToolset(workspace) {
   };
 }
 
+async function approveWrite(workspace, { action, path, preview }) {
+  if (workspace.allowWrites) {
+    return true;
+  }
+
+  return confirmWrite({ action, path, preview, cwd: workspace.rootPath });
+}
+
+async function approveNetwork(workspace, { action, detail }) {
+  if (workspace.allowNetwork) {
+    return true;
+  }
+
+  return confirmNetwork({ action, detail, cwd: workspace.rootPath });
+}
+
 async function withSyntaxCheck(workspace, targetPath, writeAction) {
   const message = await writeAction();
   const result = await checkSyntax(workspace.resolvePath(targetPath));

package/src/ui.js

@@ -2,6 +2,25 @@ import readline from "node:readline";
 import readlinePromises from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 
+let sharedRl = null;
+
+// A second readline interface on the same stdin (e.g. a confirm prompt opened
+// while chat's main loop still owns one) causes duplicated/garbled input, since
+// both instances read every keystroke. Reuse a single process-wide interface instead.
+export function getSharedReadline() {
+  if (!sharedRl) {
+    sharedRl = readlinePromises.createInterface({ input, output });
+  }
+  return sharedRl;
+}
+
+export function closeSharedReadline() {
+  if (sharedRl) {
+    sharedRl.close();
+    sharedRl = null;
+  }
+}
+
 const ANSI = {
   reset: "\u001b[0m",
   bold: "\u001b[1m",
@@ -165,13 +184,56 @@ export async function confirmCommand({ command, args = [], cwd }) {
   output.write(`\n${style("Model wants to run:", "yellow")} ${commandLine}\n`);
   output.write(`${style("Working directory:", "dim")} ${cwd}\n`);
 
-  const rl = readlinePromises.createInterface({ input, output });
-  try {
-    const answer = (await rl.question("Allow this command? [y/N]: ")).trim().toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    rl.close();
+  const rl = getSharedReadline();
+  const answer = (await rl.question("Allow this command? [y/N]: ")).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+const WRITE_ACTION_LABELS = {
+  write: "create/overwrite file",
+  append: "append to file",
+  replace: "replace text in file",
+  mkdir: "create directory"
+};
+
+export async function confirmWrite({ action, path: targetPath, preview = "", cwd }) {
+  if (!isInteractive()) {
+    return false;
   }
+
+  const label = WRITE_ACTION_LABELS[action] ?? action;
+  output.write(`\n${style("Model wants to " + label + ":", "yellow")} ${targetPath}\n`);
+  if (cwd) {
+    output.write(`${style("Working directory:", "dim")} ${cwd}\n`);
+  }
+
+  if (preview) {
+    const snippet = preview.length > 400 ? `${preview.slice(0, 400)}...` : preview;
+    output.write(`${style("Preview:", "dim")}\n${snippet}\n`);
+  }
+
+  const rl = getSharedReadline();
+  const answer = (await rl.question("Allow this change? [y/N]: ")).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+
+export async function confirmNetwork({ action, detail = "", cwd }) {
+  if (!isInteractive()) {
+    return false;
+  }
+
+  output.write(`\n${style("Model wants to access the network:", "yellow")} ${action}\n`);
+  if (detail) {
+    const snippet = detail.length > 200 ? `${detail.slice(0, 200)}...` : detail;
+    output.write(`${style("Detail:", "dim")} ${snippet}\n`);
+  }
+  if (cwd) {
+    output.write(`${style("Working directory:", "dim")} ${cwd}\n`);
+  }
+
+  const rl = getSharedReadline();
+  const answer = (await rl.question("Allow this network request? [y/N]: ")).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
 }
 
 export function printNote(message) {

package/src/workspace.js

@@ -8,10 +8,27 @@ const DEFAULT_IGNORES = new Set([
   ".DS_Store"
 ]);
 
+const NETWORK_TIMEOUT_MS = 15000;
+const USER_AGENT = "Mozilla/5.0 (compatible; local-code-agent/1.0)";
+
 export class Workspace {
   constructor(rootPath, options = {}) {
     this.rootPath = path.resolve(rootPath);
     this.allowCommands = Boolean(options.allowCommands);
+    this.allowWrites = Boolean(options.allowWrites);
+    this.allowNetwork = Boolean(options.allowNetwork);
+  }
+
+  assertWriteApproved(approved) {
+    if (!this.allowWrites && !approved) {
+      throw new Error("File change was not approved. Re-run with --allow-writes to skip the prompt, or approve it when asked.");
+    }
+  }
+
+  assertNetworkApproved(approved) {
+    if (!this.allowNetwork && !approved) {
+      throw new Error("Network access was not approved. Re-run with --allow-network to skip the prompt, or approve it when asked.");
+    }
   }
 
   resolvePath(targetPath = ".") {
@@ -47,21 +64,24 @@ export class Workspace {
     return fs.readFile(fullPath, "utf8");
   }
 
-  async writeFile(targetPath, content) {
+  async writeFile(targetPath, content, { approved = false } = {}) {
+    this.assertWriteApproved(approved);
     const fullPath = this.resolvePath(targetPath);
     await fs.mkdir(path.dirname(fullPath), { recursive: true });
     await fs.writeFile(fullPath, content, "utf8");
     return `Wrote ${path.relative(this.rootPath, fullPath)}`;
   }
 
-  async appendFile(targetPath, content) {
+  async appendFile(targetPath, content, { approved = false } = {}) {
+    this.assertWriteApproved(approved);
     const fullPath = this.resolvePath(targetPath);
     await fs.mkdir(path.dirname(fullPath), { recursive: true });
     await fs.appendFile(fullPath, content, "utf8");
     return `Appended to ${path.relative(this.rootPath, fullPath)}`;
   }
 
-  async replaceInFile(targetPath, findText, replaceText, replaceAll = false) {
+  async replaceInFile(targetPath, findText, replaceText, replaceAll = false, { approved = false } = {}) {
+    this.assertWriteApproved(approved);
     const fullPath = this.resolvePath(targetPath);
     const current = await fs.readFile(fullPath, "utf8");
     if (!current.includes(findText)) {
@@ -102,7 +122,8 @@ export class Workspace {
     return matches;
   }
 
-  async makeDirectory(targetPath) {
+  async makeDirectory(targetPath, { approved = false } = {}) {
+    this.assertWriteApproved(approved);
     const fullPath = this.resolvePath(targetPath);
     await fs.mkdir(fullPath, { recursive: true });
     return `Created ${path.relative(this.rootPath, fullPath)}`;
@@ -144,6 +165,112 @@ export class Workspace {
       });
     });
   }
+
+  async fetchUrl(targetUrl, { approved = false, maxChars = 8000 } = {}) {
+    this.assertNetworkApproved(approved);
+
+    const parsed = new URL(targetUrl);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
+    }
+
+    const response = await fetchWithTimeout(parsed.toString());
+    if (!response.ok) {
+      throw new Error(`Fetch failed: ${response.status} ${response.statusText}`);
+    }
+
+    const html = await response.text();
+    const titleMatch = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const title = titleMatch ? decodeEntities(titleMatch[1]).trim() : "";
+    const text = stripTags(html);
+
+    return {
+      url: parsed.toString(),
+      title,
+      text: text.length > maxChars ? `${text.slice(0, maxChars)}...` : text
+    };
+  }
+
+  async searchWeb(query, { approved = false, limit = 5 } = {}) {
+    this.assertNetworkApproved(approved);
+
+    const response = await fetchWithTimeout("https://html.duckduckgo.com/html/", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: `q=${encodeURIComponent(query)}`
+    });
+    if (!response.ok) {
+      throw new Error(`Search failed: ${response.status} ${response.statusText}`);
+    }
+
+    const html = await response.text();
+    const snippets = [];
+    const snippetPattern = /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+    let snippetMatch;
+    while ((snippetMatch = snippetPattern.exec(html)) !== null) {
+      snippets.push(stripTags(snippetMatch[1]));
+    }
+
+    const results = [];
+    const linkPattern = /<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+    let linkMatch;
+    while ((linkMatch = linkPattern.exec(html)) !== null && results.length < limit) {
+      results.push({
+        title: stripTags(linkMatch[2]),
+        url: resolveDuckDuckGoUrl(linkMatch[1]),
+        snippet: snippets[results.length] ?? ""
+      });
+    }
+
+    return results;
+  }
+}
+
+async function fetchWithTimeout(url, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    return await fetch(url, {
+      ...options,
+      signal: controller.signal,
+      headers: { "User-Agent": USER_AGENT, ...options.headers }
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function resolveDuckDuckGoUrl(href) {
+  try {
+    const url = new URL(href.startsWith("//") ? `https:${href}` : href);
+    const target = url.searchParams.get("uddg");
+    return target ? decodeURIComponent(target) : url.toString();
+  } catch {
+    return href;
+  }
+}
+
+function decodeEntities(text) {
+  return text
+    .replace(/&nbsp;/g, " ")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#0*39;|&#x0*27;/gi, "'")
+    .replace(/&#(\d+);/g, (_, code) => String.fromCodePoint(Number(code)))
+    .replace(/&#x([0-9a-f]+);/gi, (_, code) => String.fromCodePoint(parseInt(code, 16)))
+    .replace(/&amp;/g, "&");
+}
+
+function stripTags(html) {
+  return decodeEntities(
+    html
+      .replace(/<script[\s\S]*?<\/script>/gi, " ")
+      .replace(/<style[\s\S]*?<\/style>/gi, " ")
+      .replace(/<[^>]+>/g, " ")
+  )
+    .replace(/\s+/g, " ")
+    .trim();
 }
 
 const MAX_SCANNED_ENTRIES = 5000;