@code4bug/jarvis-agent 1.2.1 → 1.3.1

package/dist/hooks/useMultilineInputStream.js

@@ -0,0 +1,141 @@
+import { useEffect, useRef } from 'react';
+export function useMultilineInputStream({ stdin, isActive, pasteDetectWindowMs, imeComposeWindowMs, isAsciiLowerAlpha, hasNonAscii, insertPaste, handleNormalInput, commitImeBuffer, flushImeBuffer, appendImeBuffer, getImeBuffer, clearImeBufferWithInsertedLenRollback, }) {
+    const pasteBufferRef = useRef(null);
+    const batchBufferRef = useRef('');
+    const batchTimerRef = useRef(null);
+    const imeTimerRef = useRef(null);
+    const escTimerRef = useRef(null);
+    const ESC_WAIT_MS = 50;
+    useEffect(() => {
+        if (!stdin || !isActive)
+            return;
+        const flushBatchBuffer = () => {
+            const buf = batchBufferRef.current;
+            batchBufferRef.current = '';
+            batchTimerRef.current = null;
+            if (!buf)
+                return;
+            const cleaned = buf.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+            if (cleaned.includes('\n') && cleaned.length > 1) {
+                insertPaste(cleaned);
+                return;
+            }
+            if (isAsciiLowerAlpha(buf)) {
+                appendImeBuffer(buf);
+                if (imeTimerRef.current !== null) {
+                    clearTimeout(imeTimerRef.current);
+                }
+                imeTimerRef.current = setTimeout(flushImeBuffer, imeComposeWindowMs);
+                return;
+            }
+            if (hasNonAscii(buf) && getImeBuffer().length > 0) {
+                if (imeTimerRef.current !== null) {
+                    clearTimeout(imeTimerRef.current);
+                    imeTimerRef.current = null;
+                }
+                clearImeBufferWithInsertedLenRollback();
+                handleNormalInput(buf);
+                return;
+            }
+            if (getImeBuffer().length > 0) {
+                commitImeBuffer();
+            }
+            handleNormalInput(buf);
+        };
+        const onData = (data) => {
+            const raw = data.toString('utf-8');
+            if (raw.includes('\x1B[200~')) {
+                const startIdx = raw.indexOf('\x1B[200~') + 6;
+                const endIdx = raw.indexOf('\x1B[201~');
+                if (endIdx !== -1) {
+                    insertPaste(raw.slice(startIdx, endIdx));
+                }
+                else {
+                    pasteBufferRef.current = raw.slice(startIdx);
+                }
+                return;
+            }
+            if (pasteBufferRef.current !== null) {
+                const endIdx = raw.indexOf('\x1B[201~');
+                if (endIdx !== -1) {
+                    pasteBufferRef.current += raw.slice(0, endIdx);
+                    insertPaste(pasteBufferRef.current);
+                    pasteBufferRef.current = null;
+                }
+                else {
+                    pasteBufferRef.current += raw;
+                }
+                return;
+            }
+            if (escTimerRef.current !== null) {
+                clearTimeout(escTimerRef.current);
+                escTimerRef.current = null;
+                if (raw === '\r' || raw === '\n') {
+                    handleNormalInput('\x1B\r');
+                    return;
+                }
+                handleNormalInput('\x1B');
+            }
+            const isSingleControl = raw === '\r' || raw === '\n' ||
+                raw === '\x7F' || raw === '\x08' ||
+                raw === '\t' || raw === '\x1B' ||
+                raw === '\x1B\r' || raw === '\x1B\n' ||
+                raw.startsWith('\x1B[') || raw.startsWith('\x1B]') || raw.startsWith('\x1BO');
+            if (raw === '\x03' || raw === '\x0F' || raw === '\x0C')
+                return;
+            if (raw === '\x1B') {
+                escTimerRef.current = setTimeout(() => {
+                    escTimerRef.current = null;
+                    handleNormalInput('\x1B');
+                }, ESC_WAIT_MS);
+                return;
+            }
+            if (isSingleControl && batchBufferRef.current === '') {
+                if (getImeBuffer().length > 0) {
+                    commitImeBuffer();
+                }
+                handleNormalInput(raw);
+                return;
+            }
+            if (isSingleControl && batchBufferRef.current !== '') {
+                batchBufferRef.current += raw;
+                return;
+            }
+            batchBufferRef.current += raw;
+            if (batchTimerRef.current !== null) {
+                clearTimeout(batchTimerRef.current);
+            }
+            batchTimerRef.current = setTimeout(flushBatchBuffer, pasteDetectWindowMs);
+        };
+        stdin.prependListener('data', onData);
+        return () => {
+            stdin.off('data', onData);
+            if (batchTimerRef.current !== null) {
+                clearTimeout(batchTimerRef.current);
+                batchTimerRef.current = null;
+            }
+            if (escTimerRef.current !== null) {
+                clearTimeout(escTimerRef.current);
+                escTimerRef.current = null;
+            }
+            if (imeTimerRef.current !== null) {
+                clearTimeout(imeTimerRef.current);
+                imeTimerRef.current = null;
+            }
+        };
+    }, [
+        stdin,
+        isActive,
+        pasteDetectWindowMs,
+        imeComposeWindowMs,
+        isAsciiLowerAlpha,
+        hasNonAscii,
+        insertPaste,
+        handleNormalInput,
+        commitImeBuffer,
+        flushImeBuffer,
+        appendImeBuffer,
+        getImeBuffer,
+        clearImeBufferWithInsertedLenRollback,
+    ]);
+}

package/dist/hooks/useTerminalCursorSync.d.ts

@@ -0,0 +1,8 @@
+interface UseTerminalCursorSyncOptions {
+    showCursor: boolean;
+    isActive: boolean;
+    rowsBelow: number;
+    delayMs?: number;
+}
+export declare function useTerminalCursorSync({ showCursor, isActive, rowsBelow, delayMs, }: UseTerminalCursorSyncOptions): void;
+export {};

package/dist/hooks/useTerminalCursorSync.js

@@ -0,0 +1,44 @@
+import { useEffect, useRef } from 'react';
+import { moveCursorToColumn, relocateCursorToInputLine } from '../terminal/cursor.js';
+export function useTerminalCursorSync({ showCursor, isActive, rowsBelow, delayMs = 80, }) {
+    const cursorRelocTimerRef = useRef(null);
+    const lastCursorCommandRef = useRef('');
+    useEffect(() => {
+        return () => {
+            if (cursorRelocTimerRef.current !== null) {
+                clearTimeout(cursorRelocTimerRef.current);
+            }
+        };
+    }, []);
+    useEffect(() => {
+        if (cursorRelocTimerRef.current !== null) {
+            clearTimeout(cursorRelocTimerRef.current);
+        }
+        if (!showCursor || !isActive) {
+            cursorRelocTimerRef.current = setTimeout(() => {
+                cursorRelocTimerRef.current = null;
+                const commandKey = 'col:1';
+                if (lastCursorCommandRef.current === commandKey)
+                    return;
+                lastCursorCommandRef.current = commandKey;
+                moveCursorToColumn(1);
+            }, delayMs);
+        }
+        else {
+            cursorRelocTimerRef.current = setTimeout(() => {
+                cursorRelocTimerRef.current = null;
+                const commandKey = `input:${rowsBelow}:3`;
+                if (lastCursorCommandRef.current === commandKey)
+                    return;
+                lastCursorCommandRef.current = commandKey;
+                relocateCursorToInputLine(rowsBelow, 3);
+            }, delayMs);
+        }
+        return () => {
+            if (cursorRelocTimerRef.current !== null) {
+                clearTimeout(cursorRelocTimerRef.current);
+                cursorRelocTimerRef.current = null;
+            }
+        };
+    }, [showCursor, isActive, rowsBelow, delayMs]);
+}

package/dist/hooks/useTerminalSize.d.ts

@@ -0,0 +1,7 @@
+interface TerminalSize {
+    width: number;
+    height: number;
+}
+/** 响应式终端尺寸 */
+export declare function useTerminalSize(): TerminalSize;
+export {};

package/dist/hooks/useTerminalSize.js

@@ -0,0 +1,21 @@
+import { useState, useEffect } from 'react';
+/** 响应式终端尺寸 */
+export function useTerminalSize() {
+    const [size, setSize] = useState(() => ({
+        width: process.stdout.columns || 80,
+        height: process.stdout.rows || 24,
+    }));
+    useEffect(() => {
+        const onResize = () => {
+            setSize({
+                width: process.stdout.columns || 80,
+                height: process.stdout.rows || 24,
+            });
+        };
+        process.stdout.on('resize', onResize);
+        return () => {
+            process.stdout.off('resize', onResize);
+        };
+    }, []);
+    return size;
+}

package/dist/screens/repl.js

@@ -1,20 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useCallback, useRef, useEffect } from 'react';
-import { Box, Text, useInput, useApp } from 'ink';
-import Spinner from 'ink-spinner';
-import MultilineInput from '../components/MultilineInput.js';
+import { Box, useInput, useApp } from 'ink';
 import WelcomeHeader from '../components/WelcomeHeader.js';
-import MessageItem from '../components/MessageItem.js';
-import StreamingText from '../components/StreamingText.js';
-import StatusBar from '../components/StatusBar.js';
-import SlashCommandMenu from '../components/SlashCommandMenu.js';
-import DangerConfirm from '../components/DangerConfirm.js';
+import MessageViewport from '../components/MessageViewport.js';
+import ComposerPane from '../components/ComposerPane.js';
+import FooterPane from '../components/FooterPane.js';
 import { useWindowFocus } from '../hooks/useFocus.js';
 import { useInputHistory } from '../hooks/useInputHistory.js';
 import { useDoubleCtrlCExit } from '../hooks/useDoubleCtrlCExit.js';
 import { useTerminalWidth } from '../hooks/useTerminalWidth.js';
 import { useStreamThrottle } from '../hooks/useStreamThrottle.js';
-import { useTokenDisplay } from '../hooks/useTokenDisplay.js';
 import { useSlashMenu } from '../hooks/useSlashMenu.js';
 import { executeSlashCommand } from './slashCommands.js';
 import { QueryEngine } from '../core/QueryEngine.js';
@@ -24,6 +19,7 @@ import { subscribeAgentCount, getActiveAgentCount } from '../core/spawnRegistry.
 import { logError, logInfo, logWarn } from '../core/logger.js';
 import { getAgentSubCommands } from '../commands/index.js';
 import { setActiveAgent } from '../config/agentState.js';
+import { hideTerminalCursor, showTerminalCursor } from '../terminal/cursor.js';
 export default function REPL() {
     const { exit } = useApp();
     const width = useTerminalWidth();
@@ -43,13 +39,34 @@ export default function REPL() {
     const [placeholder, setPlaceholder] = useState('');
     const [activeAgents, setActiveAgents] = useState(getActiveAgentCount());
     const lastEscRef = useRef(0);
+    const lastAbortNoticeRef = useRef(0);
     const sessionRef = useRef({
         id: '', messages: [], createdAt: 0, updatedAt: 0, totalTokens: 0, totalCost: 0,
     });
     const engineRef = useRef(null);
+    const tokenCountRef = useRef(0);
     // 节流 hooks
     const { streamText, streamBufferRef, startStreamTimer, stopStreamTimer, appendStreamChunk, clearStream, handleThinkingUpdate, finishThinking, thinkingIdRef, stopAll, } = useStreamThrottle(setMessages);
-    const { displayTokens, tokenCountRef, startTokenTimer, stopTokenTimer, updateTokenCount, syncTokenDisplay, resetTokens, } = useTokenDisplay();
+    const syncTokenDisplay = useCallback((count) => {
+        tokenCountRef.current = count;
+    }, []);
+    const resetTokens = useCallback(() => {
+        tokenCountRef.current = 0;
+    }, []);
+    const appendAbortNotice = useCallback(() => {
+        const now = Date.now();
+        if (now - lastAbortNoticeRef.current < 800)
+            return;
+        lastAbortNoticeRef.current = now;
+        setMessages((prev) => [...prev, {
+                id: `abort-notice-${now}`,
+                type: 'system',
+                status: 'aborted',
+                content: '已中断当前推理',
+                timestamp: now,
+                abortHint: '推理已中断（ESC）',
+            }]);
+    }, []);
     // ===== 新会话逻辑 =====
     const handleNewSession = useCallback(() => {
         logInfo('ui.new_session');
@@ -125,17 +142,15 @@ export default function REPL() {
             setLoopState(state);
             setIsProcessing(state.isRunning);
             if (state.isRunning) {
-                startTokenTimer();
                 startStreamTimer();
             }
             else {
-                stopTokenTimer();
                 stopAll();
             }
         },
         onSessionUpdate: (s) => {
             sessionRef.current = s;
-            updateTokenCount(s.totalTokens);
+            tokenCountRef.current = s.totalTokens;
         },
         onConfirmDangerousCommand: (command, reason, ruleName) => {
             return new Promise((resolve) => {
@@ -321,19 +336,11 @@ export default function REPL() {
     }, [placeholder]);
     // ===== 隐藏系统默认终端光标，使用 ink 渲染的反色光标代替 =====
     useEffect(() => {
-        process.stdout.write('\x1B[?25l');
+        hideTerminalCursor();
         return () => {
-            process.stdout.write('\x1B[?25h');
+            showTerminalCursor();
         };
     }, []);
-    // ===== processing/streaming 期间，每次 re-render 后将物理光标移到行首 =====
-    // ink 每次渲染后光标停在 StatusBar 行末，macOS IME 会在该位置显示 composing 候选框，
-    // 导致候选框与进度条重叠。将光标移到列 1（行首）让候选框出现在屏幕左侧空白区域。
-    useEffect(() => {
-        if (!isProcessing)
-            return;
-        process.stdout.write('\x1B[1G');
-    });
     // ===== processing 期间隐藏终端光标，阻止 IME composing 显示 =====
     const isProcessingRef = useRef(isProcessing);
     isProcessingRef.current = isProcessing;
@@ -341,7 +348,7 @@ export default function REPL() {
         if (!isProcessing)
             return;
         // 隐藏终端光标 — 终端 IME 的 inline composing 仅在光标可见时渲染
-        process.stdout.write('\x1B[?25l');
+        hideTerminalCursor();
         // 高优先级 stdin 拦截：吞掉 processing 期间的所有输入（Ctrl+C / ESC 除外）
         // 防止字符积累在缓冲区，processing 结束后污染输入框
         const drain = (data) => {
@@ -374,6 +381,7 @@ export default function REPL() {
                 return;
             }
             if (key.escape && engineRef.current) {
+                appendAbortNotice();
                 engineRef.current.abort();
                 return;
             }
@@ -412,6 +420,7 @@ export default function REPL() {
         if (key.escape) {
             if (isProcessing && engineRef.current) {
                 logWarn('ui.abort_by_escape');
+                appendAbortNotice();
                 engineRef.current.abort();
             }
             else if (input.length > 0) {
@@ -428,8 +437,10 @@ export default function REPL() {
         }
     });
     // ===== 渲染 =====
-    return (_jsxs(Box, { flexDirection: "column", width: width, children: [showWelcome && _jsx(WelcomeHeader, { width: width }), _jsxs(Box, { flexDirection: "column", paddingX: 1, marginTop: showWelcome ? 0 : 1, children: [messages.map((msg) => (_jsx(MessageItem, { msg: msg, showDetails: showDetails }, msg.id))), streamText && _jsx(StreamingText, { text: streamText }), dangerConfirm && (_jsx(DangerConfirm, { command: dangerConfirm.command, reason: dangerConfirm.reason, ruleName: dangerConfirm.ruleName, onSelect: (choice) => {
-                            dangerConfirm.resolve(choice);
-                            setDangerConfirm(null);
-                        } })), loopState?.isRunning && (_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { color: "gray", children: [" iteration ", loopState.iteration, "/", loopState.maxIterations] })] }))] }), _jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { color: "gray", children: '─'.repeat(Math.max(width - 2, 1)) }), slashMenu.slashMenuVisible && !isProcessing && (_jsx(SlashCommandMenu, { commands: slashMenu.slashMenuItems, selectedIndex: slashMenu.slashMenuIndex })), _jsx(Box, { children: countdown !== null ? (_jsxs(Box, { children: [_jsx(Text, { color: "gray", dimColor: true, children: "\u276F " }), _jsx(Text, { color: "yellow", children: "Press " }), _jsx(Text, { color: "yellow", bold: true, children: "Ctrl+C" }), _jsx(Text, { color: "yellow", children: " again to exit " }), _jsxs(Text, { color: "gray", dimColor: true, children: ["(", countdown, "s)"] })] })) : isProcessing ? (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u276F " }), _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { color: "gray", italic: true, children: " processing..." })] })) : (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", bold: true, children: "\u276F " }), _jsx(MultilineInput, { value: input, onChange: handleInputChange, onSubmit: handleEditorSubmit, onUpArrow: handleUpArrow, onDownArrow: handleDownArrow, placeholder: placeholder, isActive: !isProcessing, showCursor: windowFocused && !isProcessing, slashMenuActive: slashMenu.slashMenuVisible, onSlashMenuUp: slashMenu.handleSlashMenuUp, onSlashMenuDown: slashMenu.handleSlashMenuDown, onSlashMenuSelect: handleSlashMenuAutocomplete, onSlashMenuClose: slashMenu.handleSlashMenuClose, onTabFillPlaceholder: handleTabFillPlaceholder })] })) }), _jsx(Text, { color: "gray", children: '─'.repeat(Math.max(width - 2, 1)) }), _jsx(StatusBar, { width: width - 2, totalTokens: displayTokens, activeAgents: activeAgents })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", width: width, children: [showWelcome && _jsx(WelcomeHeader, { width: width }), _jsx(Box, { marginTop: showWelcome ? 0 : 1, children: _jsx(MessageViewport, { messages: messages, streamText: streamText, showDetails: showDetails, dangerConfirm: dangerConfirm, loopState: loopState, onResolveDangerConfirm: (choice) => {
+                        if (!dangerConfirm)
+                            return;
+                        dangerConfirm.resolve(choice);
+                        setDangerConfirm(null);
+                    } }) }), _jsx(ComposerPane, { width: width, countdown: countdown, isProcessing: isProcessing, input: input, placeholder: placeholder, windowFocused: windowFocused, slashMenuVisible: slashMenu.slashMenuVisible, slashMenuItems: slashMenu.slashMenuItems, slashMenuIndex: slashMenu.slashMenuIndex, onInputChange: handleInputChange, onSubmit: handleEditorSubmit, onUpArrow: handleUpArrow, onDownArrow: handleDownArrow, onSlashMenuUp: slashMenu.handleSlashMenuUp, onSlashMenuDown: slashMenu.handleSlashMenuDown, onSlashMenuSelect: handleSlashMenuAutocomplete, onSlashMenuClose: slashMenu.handleSlashMenuClose, onTabFillPlaceholder: handleTabFillPlaceholder }), _jsx(FooterPane, { width: width, tokenCountRef: tokenCountRef, activeAgents: activeAgents })] }));
 }

package/dist/services/api/llm.js

@@ -185,7 +185,9 @@ export class LLMServiceImpl {
             '不要为了讨好用户而突破角色边界。' +
             '\n\n[安全围栏] 系统已内置安全围栏（Safeguard），会自动拦截危险命令并弹出交互式确认菜单。' +
             '当你需要执行任何命令时，直接调用 Bash 工具即可，不要自行判断命令是否危险，不要用文字询问用户"是否确认执行"。' +
-            '安全围栏会自动处理拦截和用户确认流程。';
+            '安全围栏会自动处理拦截和用户确认流程。' +
+            '\n\n[文件修改约束] 修改已有文件时，先读取目标文件，再优先使用局部修改方式。' +
+            '如果只改少量内容，优先使用 write_file 的 replace 模式；需要结构化补丁时使用 diff 模式；只有新建文件或确实需要大范围重写时才使用 overwrite。';
         // 追加系统环境信息，帮助 LLM 感知用户运行环境
         const systemInfo = getSystemInfoPrompt();
         // 追加当前激活模型信息

package/dist/skills/index.js

@@ -85,7 +85,6 @@ function buildParamsFromScript(scriptPath, skill) {
  * 通过写入临时 .py 文件再执行，避免 shell 转义问题。
  */
 async function executeSkillScript(scriptPath, skill, args) {
-    const funcName = skill.meta.name.replace(/-/g, '_');
     const kwargs = [];
     for (const [key, value] of Object.entries(args)) {
         if (key === 'arguments') {
@@ -112,8 +111,16 @@ async function executeSkillScript(scriptPath, skill, args) {
     const pyCode = [
         'import sys,os,json',
         `sys.path.insert(0, ${JSON.stringify(path.dirname(scriptPath))})`,
-        `from skill import ${funcName}`,
-        `result = ${funcName}(${kwargs.join(', ')})`,
+        'import skill as skill_module',
+        `tool_name = getattr(skill_module, "TOOL_METADATA", {}).get("name") or ${JSON.stringify(skill.meta.name.replace(/-/g, '_'))}`,
+        'func = getattr(skill_module, tool_name, None)',
+        'if func is None:',
+        '    candidates = [name for name, value in vars(skill_module).items() if callable(value) and not name.startswith("_")]',
+        '    if len(candidates) == 1:',
+        '        func = getattr(skill_module, candidates[0])',
+        '    else:',
+        '        raise ImportError(f"未找到可调用函数: {tool_name}，候选: {candidates}")',
+        `result = func(${kwargs.join(', ')})`,
         'print(json.dumps(result, ensure_ascii=False, indent=2))',
     ].join('\n');
     try {

package/dist/terminal/cursor.d.ts

@@ -0,0 +1,6 @@
+export declare function hideTerminalCursor(): void;
+export declare function showTerminalCursor(): void;
+export declare function enableBracketedPaste(): void;
+export declare function disableBracketedPaste(): void;
+export declare function moveCursorToColumn(column: number): void;
+export declare function relocateCursorToInputLine(rowsBelow: number, column: number): void;

package/dist/terminal/cursor.js

@@ -0,0 +1,21 @@
+const ESC = '\x1B[';
+export function hideTerminalCursor() {
+    process.stdout.write(`${ESC}?25l`);
+}
+export function showTerminalCursor() {
+    process.stdout.write(`${ESC}?25h`);
+}
+export function enableBracketedPaste() {
+    process.stdout.write(`${ESC}?2004h`);
+}
+export function disableBracketedPaste() {
+    process.stdout.write(`${ESC}?2004l`);
+}
+export function moveCursorToColumn(column) {
+    process.stdout.write(`${ESC}${column}G`);
+}
+export function relocateCursorToInputLine(rowsBelow, column) {
+    const up = rowsBelow > 0 ? `${ESC}${rowsBelow}A` : '';
+    const down = rowsBelow > 0 ? `${ESC}${rowsBelow}B` : '';
+    process.stdout.write(`${up}${ESC}${column}G${down}`);
+}

package/dist/tools/writeFile.js

@@ -73,6 +73,35 @@ function applyUnifiedDiff(original, diff) {
     }
     return result.join('\n');
 }
+/**
+ * 基于文本片段做精确替换，适合只改少量代码的场景。
+ */
+function applyStringReplace(original, oldString, newString, replaceAll, expectedReplacements) {
+    if (!oldString) {
+        throw new Error('replace 模式下 old_string 不能为空');
+    }
+    let matchCount = 0;
+    let searchStart = 0;
+    while (true) {
+        const idx = original.indexOf(oldString, searchStart);
+        if (idx === -1)
+            break;
+        matchCount++;
+        searchStart = idx + oldString.length;
+    }
+    if (matchCount === 0) {
+        throw new Error('replace 模式未找到要替换的内容');
+    }
+    if (expectedReplacements !== undefined && matchCount !== expectedReplacements) {
+        throw new Error(`replace 模式匹配数量不符合预期，期望 ${expectedReplacements}，实际 ${matchCount}`);
+    }
+    if (!replaceAll && matchCount !== 1) {
+        throw new Error(`replace 模式要求目标内容唯一，当前匹配到 ${matchCount} 处。请提供更精确的 old_string，或开启 replace_all`);
+    }
+    return replaceAll
+        ? original.split(oldString).join(newString)
+        : original.replace(oldString, newString);
+}
 /**
  * 写入文件内容（支持安全检测）。
  * 返回写入结果消息。
@@ -95,13 +124,33 @@ function doWrite(filePath, content) {
 }
 export const writeFile = {
     name: 'write_file',
-    description: '写入内容到指定文件。支持两种模式：overwrite（默认）完整替换文件内容；diff 模式接收 unified diff 格式补丁，对文件进行增量更新。',
+    description: '写入内容到指定文件。修改已有文件时优先使用 replace 或 diff 做局部更新，只有新建文件或大范围重写时才使用 overwrite。支持三种模式：overwrite（完整替换）、replace（按文本片段精确替换）、diff（基于 unified diff 增量更新）。',
     parameters: {
         path: { type: 'string', description: '文件路径', required: true },
         content: { type: 'string', description: '文件内容（overwrite 模式必填）', required: false },
         mode: {
             type: 'string',
-            description: '写入模式：overwrite（完整替换，默认）| diff（增量更新）',
+            description: '写入模式：overwrite（完整替换，默认）| replace（局部替换）| diff（增量更新）',
+            required: false,
+        },
+        old_string: {
+            type: 'string',
+            description: 'replace 模式必填：要查找并替换的原始文本片段',
+            required: false,
+        },
+        new_string: {
+            type: 'string',
+            description: 'replace 模式必填：替换后的文本片段',
+            required: false,
+        },
+        replace_all: {
+            type: 'boolean',
+            description: 'replace 模式可选：是否替换所有匹配项，默认 false',
+            required: false,
+        },
+        expected_replacements: {
+            type: 'number',
+            description: 'replace 模式可选：期望匹配数量，不符合时直接报错，防止误替换',
             required: false,
         },
         diff: {
@@ -113,6 +162,18 @@ export const writeFile = {
     execute: async (args) => {
         const filePath = args.path;
         const mode = args.mode || 'overwrite';
+        if (mode === 'replace') {
+            const oldString = args.old_string;
+            const newString = args.new_string ?? '';
+            const replaceAll = Boolean(args.replace_all);
+            const expectedReplacements = args.expected_replacements === undefined ? undefined : Number(args.expected_replacements);
+            if (!fs.existsSync(filePath)) {
+                throw new Error(`replace 模式要求目标文件已存在: ${filePath}`);
+            }
+            const original = fs.readFileSync(filePath, 'utf-8');
+            const replaced = applyStringReplace(original, oldString, newString, replaceAll, expectedReplacements);
+            return doWrite(filePath, replaced);
+        }
         if (mode === 'diff') {
             const diffContent = args.diff;
             if (!diffContent) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code4bug/jarvis-agent",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "基于 React + TypeScript + Ink 构建的命令行智能体交互界面",
   "type": "module",
   "main": "dist/index.js",