npm - zen-gitsync - Versions diffs - 2.17.23 → 2.17.25 - Mend

zen-gitsync 2.17.23 → 2.17.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/src/ui/public/index.html CHANGED Viewed

@@ -10,29 +10,29 @@
     <meta name="theme-color" content="#141820" media="(prefers-color-scheme: dark)" />
     <title>Zen GitSync</title>
     <!-- 字体改为自托管(@font-face 见 src/main.css),不再依赖 Google Fonts 外链 -->
-    <script type="module" crossorigin src="/assets/index-CFX8sK4w.js"></script>
+    <script type="module" crossorigin src="/assets/index-eq1OUcdk.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
     <link rel="modulepreload" crossorigin href="/assets/element-plus-Bx3j6vzG.js">
     <link rel="modulepreload" crossorigin href="/assets/monaco-DkJuNcCr.js">
-    <link rel="modulepreload" crossorigin href="/assets/vendor-CyWsJd6S.js">
-    <link rel="modulepreload" crossorigin href="/assets/_plugin-vue_export-helper-C_bQVzeb.js">
-    <link rel="modulepreload" crossorigin href="/assets/SvgIcon-xtz4vvc9.js">
-    <link rel="modulepreload" crossorigin href="/assets/IconButton-BShiC2AP.js">
-    <link rel="modulepreload" crossorigin href="/assets/configStore-DJH7OlB_.js">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-BjomZKSS.js">
+    <link rel="modulepreload" crossorigin href="/assets/_plugin-vue_export-helper-C7IvbEC3.js">
+    <link rel="modulepreload" crossorigin href="/assets/SvgIcon-diKLLWK9.js">
+    <link rel="modulepreload" crossorigin href="/assets/IconButton-D4df4t9A.js">
+    <link rel="modulepreload" crossorigin href="/assets/configStore-C-htWfWm.js">
     <link rel="modulepreload" crossorigin href="/assets/socket-io-TBtw0msS.js">
-    <link rel="modulepreload" crossorigin href="/assets/gitStore-ByP9lpuT.js">
+    <link rel="modulepreload" crossorigin href="/assets/gitStore-DYpd8vZK.js">
     <link rel="modulepreload" crossorigin href="/assets/fileIcon-B5p5pGN9.js">
     <link rel="modulepreload" crossorigin href="/assets/flow-mindmap-OPE_D4da.js">
-    <link rel="modulepreload" crossorigin href="/assets/previewSandbox-DSzZ_Rky.js">
+    <link rel="modulepreload" crossorigin href="/assets/previewSandbox-Z707CZD9.js">
     <link rel="modulepreload" crossorigin href="/assets/useThemeObserver-DYxFoHh1.js">
-    <link rel="modulepreload" crossorigin href="/assets/CommonDialog-BEm2cK1X.js">
-    <link rel="modulepreload" crossorigin href="/assets/FileDiffViewer-CYxcLw10.js">
-    <link rel="modulepreload" crossorigin href="/assets/toolsStore-B49mCaQ_.js">
-    <link rel="modulepreload" crossorigin href="/assets/TemplateManager-DhKTZ4EM.js">
+    <link rel="modulepreload" crossorigin href="/assets/CommonDialog-CRXyMlp5.js">
+    <link rel="modulepreload" crossorigin href="/assets/FileDiffViewer-BEYcCYs5.js">
+    <link rel="modulepreload" crossorigin href="/assets/toolsStore-DFu4Alwg.js">
+    <link rel="modulepreload" crossorigin href="/assets/TemplateManager-D9gyZbHP.js">
     <link rel="modulepreload" crossorigin href="/assets/vue-flow-fVVGZspa.js">
     <link rel="stylesheet" crossorigin href="/assets/element-plus-Qexo5hiM.css">
     <link rel="stylesheet" crossorigin href="/assets/monaco-B2lPvkrc.css">
-    <link rel="stylesheet" crossorigin href="/assets/vendor-BzMymUBi.css">
+    <link rel="stylesheet" crossorigin href="/assets/vendor-BY5ZDlW1.css">
     <link rel="stylesheet" crossorigin href="/assets/SvgIcon-BQ6bR7l0.css">
     <link rel="stylesheet" crossorigin href="/assets/IconButton-W2X09OKH.css">
     <link rel="stylesheet" crossorigin href="/assets/flow-mindmap-BMpmHdqh.css">
@@ -41,7 +41,7 @@
     <link rel="stylesheet" crossorigin href="/assets/FileDiffViewer-B6zy6NiA.css">
     <link rel="stylesheet" crossorigin href="/assets/TemplateManager-DiM3vrbf.css">
     <link rel="stylesheet" crossorigin href="/assets/vue-flow-CavUTEzp.css">
-    <link rel="stylesheet" crossorigin href="/assets/index-DVJITdth.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-BZFKDSGv.css">
   </head>
   <body>
     <div id="app"></div>

package/src/ui/server/index.js CHANGED Viewed

@@ -52,6 +52,7 @@ import { registerCodeAnalysisRoutes } from './routes/codeAnalysis.js';
 import { registerInstancesRoutes } from './routes/instances.js';
 import { registerMonitorRoutes } from './routes/monitor.js';
 import { registerMindmapRoutes } from './routes/mindmap.js';
+import { registerMemoryRoutes } from './routes/memory.js';
 import { registerAgentRoutes } from './routes/workbench/agentRoutes.js';
 import { createWorkspaceSnapshotter } from './routes/aiContext/wiring.js';
 import { createInstanceRegistry, getRegistryPath } from './utils/instanceRegistry.js';
@@ -478,6 +479,9 @@ async function startUIServer(noOpen = false, savePort = false) {
   // 思维导图：.mindmap.json 文件的列/读/写/建/删/重命名
   registerMindmapRoutes({ app });
+  // 记忆库：跨轮经验的浏览 / 读正文 / 删条目（设置 → 记忆库面板）
+  registerMemoryRoutes({ app });
   // 智能体：Web 端 AI 编码助手（含工具调用 + 会话持久化）
   // 快照生成器在上面已经建好（要走同一个实例），这里注入进去复用。
   registerAgentRoutes({

package/src/ui/server/routes/config.js CHANGED Viewed

@@ -989,7 +989,7 @@ export function registerConfigRoutes({
   // 保存通用设置（主题、语言、工作台任务执行器、任务完成提示）
   app.post('/api/config/save-general-settings', express.json(), async (req, res) => {
     try {
-      const { theme, locale, taskExecutor, notifyOnTaskDone } = req.body
+      const { theme, locale, taskExecutor, notifyOnTaskDone, notifySoundOnTaskDone } = req.body
       // 读取原始配置以保留项目设置
       const rawConfig = await configManager.readRawConfigFile()
@@ -1015,13 +1015,22 @@ export function registerConfigRoutes({
       if (normalizedNotify !== null) {
         rawConfig.notifyOnTaskDone = normalizedNotify
       }
+      // 任务完成提示音开关（全局，默认开）。同上：非布尔值静默忽略。
+      // 它从属于 notifyOnTaskDone —— 这里不替前端做联动（关总开关时不顺带清掉这个），
+      // 两个键各自保留用户的选择，联动只在消费端（useTaskNotifier）。这样用户
+      // 临时关掉总开关再打开，提示音设置还在，不用重设一遍。
+      const normalizedNotifySound = configManager.normalizeNotifySoundOnTaskDone(notifySoundOnTaskDone)
+      if (normalizedNotifySound !== null) {
+        rawConfig.notifySoundOnTaskDone = normalizedNotifySound
+      }
       // 直接写入原始配置，避免覆盖项目设置
       await configManager.writeRawConfigFile(rawConfig)
       res.json({
         success: true,
         taskExecutor: normalizedExecutor || undefined,
-        notifyOnTaskDone: normalizedNotify ?? undefined
+        notifyOnTaskDone: normalizedNotify ?? undefined,
+        notifySoundOnTaskDone: normalizedNotifySound ?? undefined
       })
     } catch (error) {
       res.status(500).json({ success: false, error: error.message })

package/src/ui/server/routes/fileOpen.js CHANGED Viewed

@@ -437,24 +437,82 @@ async function launchClaudeCode(dirPath, { permissionMode } = {}) {
   return launchInTerminal(dirPath, 'claude', cliArgs);
 }
-async function launchCodex(dirPath) {
-  // OpenAI Codex CLI - 无 permissionMode 参数(与 claude 不同)
+/**
+ * codex 的启动参数（按权限档位）。与 claude / opencode 的档位对应关系：
+ *
+ *   默认（不带 token）  → 一个 flag 都不加，跟随 `~/.codex/config.toml` 的
+ *                        approval / sandbox 设置
+ *   'sandboxed'        → `-a never -s workspace-write`：**从不问人，但命令仍在沙箱里跑**
+ *                        （写限工作区、默认无网络）。这是"不想被批准提示打断、又不想
+ *                        完全交出去"的那一档，语义上对应 claude 的「批准文件编辑」。
+ *   'bypass'           → `--dangerously-bypass-approvals-and-sandbox`：免批准 + 免沙箱。
+ *                        官方帮助原文 "Skip all confirmation prompts and execute commands
+ *                        without sandboxing. EXTREMELY DANGEROUS."。**完全批准**就是它。
+ *   'bypassPermissions'→ 同上。只为让调用方（顶栏菜单与编排台项目菜单）跟 claude 那档
+ *                        共用同一个字符串，不是第三种行为。
+ *
+ * ⚠️ codex 没有 claude 的 `--permission-mode`，两档都得自己拼 flag。
+ * ⚠️ 别只看 sandbox：本机 config.toml 写的是 `sandbox_mode = "danger-full-access"`，
+ *    也就是说这台机器的**默认档本来就没有沙箱**，完全批准档真正多出来的只是"不再弹批准"。
+ *
+ * 回归 `test/open-with-permission.test.mjs`（与 opencode 那份参数映射放一起验）。
+ */
+const CODEX_MODE_FLAGS = new Map([
+  ['sandboxed', ['-a', 'never', '-s', 'workspace-write']],
+  ['bypass', ['--dangerously-bypass-approvals-and-sandbox']],
+  ['bypassPermissions', ['--dangerously-bypass-approvals-and-sandbox']],
+]);
+export function buildCodexArgs(permissionMode) {
+  // Map.get 对非字符串返回 undefined → 未知 token 一律空数组，白名单式，不存在拼参数注入
+  return [...(CODEX_MODE_FLAGS.get(permissionMode) || [])];
+}
+async function launchCodex(dirPath, { permissionMode } = {}) {
+  // OpenAI Codex CLI - https://github.com/openai/codex
+  const cliArgs = buildCodexArgs(permissionMode);
   if (process.platform === 'win32') {
-    return spawnDetached('cmd.exe', ['/c', 'start', '""', 'codex'], {
+    return spawnDetached('cmd.exe', ['/c', 'start', '""', 'codex', ...cliArgs], {
       cwd: dirPath
     });
   }
-  return launchInTerminal(dirPath, 'codex');
+  return launchInTerminal(dirPath, 'codex', cliArgs);
 }
-async function launchOpenCode(dirPath) {
+/**
+ * opencode 的「完全批准」= `--auto`（官方文档里的 auto mode）：把**未被显式拒绝**的
+ * 权限请求自动批准。
+ *
+ * 它不等于"什么都放行"：配置里显式 `deny` 的仍然会被拦（opencode 默认就 deny 了
+ * `read` 的 `*.env` / `*.env.*`，TUI 里 `--auto` 也一样读不到），这与 claude 的
+ * bypassPermissions 受 `~/.claude/settings.json` deny 约束是同一个口径 —— 两边都是
+ * "除非你明确禁止，否则全放"。
+ *
+ * 档位 token：`auto` 是本工具的正式叫法；`bypassPermissions` 只是为了让调用方
+ * （顶栏菜单与编排台项目菜单）与 claude 那档共用同一个字符串。
+ */
+const OPENCODE_AUTO_MODES = new Set(['auto', 'bypassPermissions']);
+/**
+ * opencode 的启动参数（按权限档位）。
+ *
+ * 单独抽成纯函数是为了能**真的跑断言**而不用 spawn 一个终端窗口 —— 带 `--auto` 的
+ * TUI 会弹出来并停在那里等人输入，验证不能有这种副作用。回归 `test/opencode-permission.test.mjs`。
+ * 白名单式：非字符串 / 未知 token 一律返回空数组，不存在拼参数注入的面。
+ */
+export function buildOpencodeArgs(permissionMode) {
+  return OPENCODE_AUTO_MODES.has(permissionMode) ? ['--auto'] : [];
+}
+async function launchOpenCode(dirPath, { permissionMode } = {}) {
   // opencode (sst/opencode) CLI - https://opencode.ai
+  const cliArgs = buildOpencodeArgs(permissionMode);
   if (process.platform === 'win32') {
-    return spawnDetached('cmd.exe', ['/c', 'start', '""', 'opencode'], {
+    return spawnDetached('cmd.exe', ['/c', 'start', '""', 'opencode', ...cliArgs], {
       cwd: dirPath
     });
   }
-  return launchInTerminal(dirPath, 'opencode');
+  return launchInTerminal(dirPath, 'opencode', cliArgs);
 }
 // Run the CLI shipped with this server, even when `g` is not in PATH or points
@@ -960,7 +1018,7 @@ export function registerFileOpenRoutes({
   // 用 Codex 打开目录
   app.post('/api/open-directory-with-codex', asyncRoute(async (req, res) => {
       try {
-        const { path: dirPath } = req.body || {};
+        const { path: dirPath, permissionMode } = req.body || {};
         if (!dirPath) {
           throw new HttpError(400, '目录路径不能为空');
         }
@@ -972,8 +1030,12 @@ export function registerFileOpenRoutes({
         }
         try {
-          await launchCodex(dirPath);
-          res.json({ success: true, message: '已用 Codex 打开目录' });
+          await launchCodex(dirPath, { permissionMode });
+          const codexArgs = buildCodexArgs(permissionMode);
+          const message = codexArgs.length
+            ? `已用 Codex 打开目录（${codexArgs.join(' ')}）`
+            : '已用 Codex 打开目录';
+          res.json({ success: true, message });
         } catch (error) {
           res.status(400).json({
             success: false,
@@ -988,7 +1050,7 @@ export function registerFileOpenRoutes({
   // 用 OpenCode 打开目录
   app.post('/api/open-directory-with-opencode', asyncRoute(async (req, res) => {
       try {
-        const { path: dirPath } = req.body || {};
+        const { path: dirPath, permissionMode } = req.body || {};
         if (!dirPath) {
           throw new HttpError(400, '目录路径不能为空');
         }
@@ -1000,8 +1062,11 @@ export function registerFileOpenRoutes({
         }
         try {
-          await launchOpenCode(dirPath);
-          res.json({ success: true, message: '已用 OpenCode 打开目录' });
+          await launchOpenCode(dirPath, { permissionMode });
+          const message = OPENCODE_AUTO_MODES.has(permissionMode)
+            ? '已用 OpenCode 打开目录（--auto：自动批准未被显式拒绝的权限）'
+            : '已用 OpenCode 打开目录';
+          res.json({ success: true, message });
         } catch (error) {
           res.status(400).json({
             success: false,

package/src/ui/server/routes/memory.js ADDED Viewed

@@ -0,0 +1,125 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 记忆库的浏览 / 删除接口（设置 → 记忆库面板用）。
+//
+// 口径（与其它 workbench 路由一致，详见 routes/workbench/index.js 头部三条）：
+//   - 非 SSE 路由统一 asyncRoute 包装，**handler 内不写 try/catch**
+//   - 定制状态码用 `throw new HttpError(4xx, msg)`
+//   - 危险操作（删）要求调用方显式传 `confirm: true`
+//
+// ⚠️ **本文件不导出"任意路径"接口。** 前端只传 `{scope, file}`，
+// 绝对路径由 src/memory/library.js 从 scope 重新拼（见那个文件头注释）。
+// 这是结构性防越界：不合法参数压根不参与路径拼接，
+// 也就没有"前端传个 path 就删到别处"的可能。**别为了"省一次校验"改成传路径。**
+import { asyncRoute, HttpError } from '../utils/asyncRoute.js';
+import {
+  listScopes,
+  listEntries,
+  readEntry,
+  deleteEntry,
+  isValidScope,
+  isValidFile,
+  memoryDirExists,
+  SCOPE_GLOBAL,
+  SCOPE_GLOBAL_INDEX,
+} from '../../../memory/library.js';
+/** 批量删除的单次上限：再多就该分批，别让一个请求把整个库清空 */
+const BATCH_MAX = 200;
+function requireScope(scope) {
+  if (!isValidScope(scope)) throw new HttpError(400, 'scope 不合法');
+  return scope;
+}
+function requireFile(file) {
+  if (!isValidFile(file)) throw new HttpError(400, 'file 不合法');
+  return file;
+}
+export function registerMemoryRoutes({ app }) {
+  // ── 有哪些可看的范围（全局两篇 + 每个项目）──────────────────────────
+  app.get('/api/memory/scopes', asyncRoute(async (_req, res) => {
+    const available = await memoryDirExists();
+    if (!available) {
+      // 没就绪是**合法状态**（用户还没开过工作台），给空列表而不是 500：
+      // 面板据此显示"尚未初始化"，而不是一个看不懂的报错
+      res.json({ success: true, available: false, scopes: [] });
+      return;
+    }
+    res.json({ success: true, available: true, scopes: await listScopes() });
+  }));
+  // ── 某个范围下有哪些条目 ────────────────────────────────────────────
+  app.get('/api/memory/entries', asyncRoute(async (req, res) => {
+    const scope = requireScope(String(req.query.scope || ''));
+    res.json({ success: true, scope, entries: await listEntries(scope) });
+  }));
+  // ── 读单条正文（展开看内容时按需拉）─────────────────────────────────
+  app.get('/api/memory/entry', asyncRoute(async (req, res) => {
+    const scope = requireScope(String(req.query.scope || ''));
+    const file = requireFile(String(req.query.file || ''));
+    const r = await readEntry(scope, file);
+    if (r.error === 'invalid') throw new HttpError(400, 'scope 或 file 不合法');
+    if (r.tooLarge) throw new HttpError(413, `内容过大（${Math.round(r.size / 1024)} KB），不予展示`);
+    if (r.missing) throw new HttpError(404, '条目不存在');
+    res.json({ success: true, scope, file, content: r.content, size: r.size, mtime: r.mtime });
+  }));
+  // ── 删一条（连带清掉 INDEX.md 里那行索引）───────────────────────────
+  app.delete('/api/memory/entry', asyncRoute(async (req, res) => {
+    if (req.body?.confirm !== true) throw new HttpError(400, '需要 confirm: true');
+    const scope = requireScope(String(req.body?.scope || ''));
+    const file = requireFile(String(req.body?.file || ''));
+    // 全局两篇是索引/规范本身，删了整套记忆就失去记账口径 —— 不给删
+    if (scope === SCOPE_GLOBAL || scope === SCOPE_GLOBAL_INDEX) {
+      throw new HttpError(400, '全局索引与规范文件不可删除');
+    }
+    const r = await deleteEntry(scope, file);
+    res.json({ success: true, ...r });
+  }));
+  // ── 批量删 ──────────────────────────────────────────────────────────
+  app.post('/api/memory/batch-delete', asyncRoute(async (req, res) => {
+    if (req.body?.confirm !== true) throw new HttpError(400, '需要 confirm: true');
+    const items = Array.isArray(req.body?.items) ? req.body.items : [];
+    if (items.length === 0) throw new HttpError(400, '没有选中任何条目');
+    if (items.length > BATCH_MAX) throw new HttpError(400, `一次最多删 ${BATCH_MAX} 条`);
+    let removed = 0;
+    let indexLinesRemoved = 0;
+    const failed = [];
+    for (const it of items) {
+      const scope = String(it?.scope || '');
+      const file = String(it?.file || '');
+      if (!isValidScope(scope) || !isValidFile(file)) { failed.push({ scope, file, reason: 'invalid' }); continue; }
+      if (scope === SCOPE_GLOBAL || scope === SCOPE_GLOBAL_INDEX) {
+        failed.push({ scope, file, reason: 'protected' });
+        continue;
+      }
+      try {
+        const r = await deleteEntry(scope, file);
+        if (r.removed) removed += 1;
+        if (r.indexLineRemoved) indexLinesRemoved += 1;
+      } catch (err) {
+        // 单条失败**不中断整批** —— 否则前几条已删、后几条报错，用户重试会重复删
+        failed.push({ scope, file, reason: err?.message || 'delete failed' });
+      }
+    }
+    res.json({ success: true, removed, indexLinesRemoved, failed });
+  }));
+}

package/src/ui/server/routes/workbench/agentChat.js CHANGED Viewed

@@ -21,7 +21,10 @@
 //   - { type: 'meta', sessionId, isNew, title }
 //   - { type: 'thinking', delta }          — 推理过程增量
 //   - { type: 'content', delta }           — 正文增量
-//   - { type: 'tool_call_start', toolCallId, name, argsPreview }
+//   - { type: 'tool_call_start', toolCallId, name, argsPreview, arguments }
+//       arguments 只在计划类工具(update_plan 等)上出现:前端要拿原始 steps 渲染
+//       计划清单,argsPreview 是截断过的摘要拆不出步骤。其他工具不带全文,免得
+//       write_file 那种几十 KB 的 content 灌进 SSE。
 //   - { type: 'tool_output', toolCallId, chunk }       — 命令执行中的增量输出(仅展示)
 //   - { type: 'tool_result', toolCallId, name, result }
 //   - { type: 'ask_user', interactionId, question, options, allowFreeText, multiple }
@@ -33,7 +36,7 @@ import os from 'os';
 import { logger } from './shared.js';
 // 从 CLI 侧导入工具定义、执行器与 LLM 传输层（同一 monorepo，路径可达）
-import { TOOL_DEFINITIONS, executeTool } from '../../../../cli/ai/tools.js';
+import { TOOL_DEFINITIONS, executeTool, normalizePlanSteps, summarizePlan, isPlanToolName } from '../../../../cli/ai/tools.js';
 import { prepareRequestMessages } from '../../../../cli/ai/context.js';
 import { streamChatOnce } from '../../../../cli/ai/transport.js';
 import { checkDangerousCommand } from '../../../../cli/ai/safety.js';
@@ -131,6 +134,15 @@ ${isWin ? `- 当前是 Windows,以下 Unix 命令**不存在**,用了必定报"
 - run_command 默认就在工作目录执行,不要再加 cd 前缀;默认超时 120 秒,长任务加大 timeout_seconds(最大 600)
 - 命令在 ${shellDesc} 下执行,注意语法兼容
+# 任务计划(多步任务必用)
+- 任务需要多步时(改代码、排查、调研、多文件改动),**动手之前**先调一次 update_plan,把要做的事
+  拆成 3-8 个可核对的步骤,让用户在你改任何东西之前就知道范围和验收标准
+- 单步小事(读个文件、答一个问题)不要列计划,那是噪音
+- 每次都传**完整**的当前计划(不是增量),顺序即执行顺序;同一时刻最多一个 in_progress
+- 完成一步就更新一次状态,别攒到最后一次性刷;计划与实际不符时直接改计划,不要硬着头皮往下走
+- 全部做完后把 steps 传空表示收尾
+- update_plan 只是给人看的进度板,不要为了"更新计划"去改文件或跑命令
 # 与用户交互
 - 需要向用户确认、提问或汇报重要决策时,直接用普通文本输出
 - 需要暂停当前任务并等待用户决定或补充信息时,调用 ask_user,不要猜测或只在普通文本里提问
@@ -213,6 +225,17 @@ ${isWin ? `- This is Windows. The following Unix commands do NOT exist here:
 - run_command defaults to the working directory; default timeout 120s, max 600s
 - When the task must pause for a decision or missing detail, call ask_user and wait for the user's answer. The user may attach images to a message; they arrive as image_url parts in the user message. If the current model rejects images (no vision support), tell the user to switch to a vision-capable model
+# Task plan (required for multi-step work)
+- When a task takes several steps (code changes, debugging, research, multi-file edits), call update_plan
+  **before touching anything**: break it into 3-8 verifiable steps so the user knows the scope and the
+  acceptance criteria before you modify a single file
+- Do not plan single trivial actions (read one file, answer one question) — that is noise
+- Always send the **complete** current plan (not a delta), in execution order; at most one in_progress
+- Update the status right after finishing a step instead of batching everything at the end; when the
+  plan no longer matches reality, rewrite the plan instead of pushing ahead
+- Send an empty steps list once everything is done
+- update_plan is a progress board for humans: never edit files or run commands just to "update the plan"
 # Output
 - Your text output is displayed in the user's Web UI
 - After completing a task, briefly summarize the result`;
@@ -384,7 +407,11 @@ export async function runAgentTurn({ session, model, userMessage, images = [], c
       // 工具参数预览(给前端展示)
       const argsPreview = summarizeArgs(name, args);
-      send({ type: 'tool_call_start', toolCallId, name, argsPreview });
+      // 计划类工具额外发**完整参数**:前端要拿原始 steps 渲染清单,而 argsPreview
+      // 是截断过的摘要,拆不出步骤。只给计划类工具发完整参数 ——
+      // write_file 的 content 可能几十 KB,为它开一路全文等于给 SSE 带宽找麻烦。
+      const rawArgsForClient = isPlanToolName(name) ? rawArgs : undefined;
+      send({ type: 'tool_call_start', toolCallId, name, argsPreview, arguments: rawArgsForClient });
       const toolCtx = {
         ...ctx,
@@ -430,6 +457,11 @@ function summarizeArgs(name, args) {
         return String(args.path || '.');
       case 'search_text':
         return String(args.pattern || '');
+      case 'update_plan': {
+        const steps = normalizePlanSteps(args.steps ?? args.todos ?? args.plan);
+        const why = String(args.explanation || '').replace(/\s+/g, ' ').trim();
+        return [summarizePlan(steps), why].filter(Boolean).join(' — ').slice(0, 200);
+      }
       default:
         return JSON.stringify(args).slice(0, 200);
     }

package/src/ui/server/routes/workbench/agentChatShared.test.js CHANGED Viewed

@@ -179,3 +179,52 @@ test('400 且正文提到 tool/function 时提示换模型,而不是甩网关 JS
   assert.match(error.error, /不支持 function calling/)
   assert.match(error.error, /换用支持工具调用的模型/)
 })
+// ── 计划工具的透传契约 ──────────────────────────────────────
+// 前端要拿原始 steps 渲染计划清单，而它拿到的是 argsPreview（截断过的摘要）——
+// 摘要里拆不出步骤，所以服务端必须为计划类工具额外带一份完整 arguments。
+// 这条钉死了「只给计划类发全文」的口径：多发会让 write_file 的 content
+// 几十 KB 灌进 SSE，少发则前端永远退化成普通工具块。
+test('计划类工具的 tool_call_start 带完整 arguments,其他工具不带', async () => {
+  const planArgs = JSON.stringify({
+    steps: [
+      { content: '读代码', status: 'completed' },
+      { content: '改代码', status: 'in_progress' }
+    ],
+    explanation: '先改库再改宿主'
+  })
+  const round = [
+    sse([event({
+      choices: [{ delta: { tool_calls: [
+        { index: 0, id: 'p1', function: { name: 'update_plan', arguments: planArgs } },
+        { index: 1, id: 'p2', function: { name: 'write_file', arguments: JSON.stringify({ path: 'a.js', content: 'x'.repeat(50) }) } }
+      ] } }, { finish_reason: 'tool_calls' }],
+    }), 'data: [DONE]\n\n']),
+    okStream(),
+  ]
+  let turn = 0
+  const session = newSession('ag-sandbox-plan', withSystem())
+  const { events } = await runWeb({
+    session,
+    userMessage: '把这个功能做出来',
+    respond: () => round[turn++] || okStream(),
+  })
+  const starts = events.filter(e => e.type === 'tool_call_start')
+  assert.equal(starts.length, 2)
+  const planStart = starts.find(e => e.name === 'update_plan')
+  const writeStart = starts.find(e => e.name === 'write_file')
+  // 计划：全文必须一字不差地带到前端（前端靠它渲染清单）
+  assert.equal(planStart.arguments, planArgs)
+  assert.match(planStart.argsPreview, /1\/2|1 完成/)
+  // 其他工具：只给摘要，不灌全文
+  assert.equal(writeStart.arguments, undefined)
+  const planResult = events.find(e => e.type === 'tool_result' && e.name === 'update_plan')
+  assert.match(planResult.result, /计划已更新/)
+  // 计划也要进会话记录 —— 重新打开会话时前端靠历史里的 arguments 复原清单
+  const assistantWithPlan = session.messages.find(m => m.role === 'assistant' && m.tool_calls?.some(t => t.function.name === 'update_plan'))
+  assert.equal(assistantWithPlan.tool_calls[0].function.arguments, planArgs)
+})