MetonaTeam/metona-ai-desktop
2
0
Fork 0
Code Issues 51 Pull Requests Actions Packages Projects Releases 8 Wiki Activity

feat: 升级至 v0.3.12 — 文件与代码类工具全面优化（16 项）

Browse Source 
【阶段一 · 紧急修复 F1】
- F1-1 file_editor regex 计数 bug：强制 g 标志 + 同一 RegExp 实例做 match+replace
- F1-2 code_search 统一 safeResolvePath（含路径遍历 + MEMORY.md 拦截）
- F1-3 git_commit amend 模式：message 可选 + --no-edit 防止编辑器 hang
- F1-4 write_file append 模式原子化：显式 open(O_APPEND)+write+fsync+close

【阶段二 · 增强现有工具 F2】
- F2-1 read_file 智能编码检测：BOM(UTF-8/UTF-16 LE/BE) + GBK 降级
- F2-2 read_file 支持 tail 模式（读取末尾 N 行，适用日志）
- F2-3 search_files 二进制过滤 + 智能编码检测
- F2-4 search_files 多 glob 匹配（逗号分隔，如 *.ts,*.js）
- F2-5 file_editor 新增 find_replace 操作（字面量替换，规避正则歧义）
- F2-6 file_editor regex 支持跨行匹配（multiline 参数）
- F2-7 file_editor 新增 backup 参数（编辑前 .bak 备份）

【阶段三 · 新增工具 F3】
- F3-1 file_move：双路径校验 + overwrite + 自动建父目录 + rename 原子
- F3-2 file_info：大小/时间/类型/编码/二进制/权限位

【阶段四 · 优化 F4】
- F4-1 diff_viewer Uint32Array→Uint16Array（省一半内存）+ safeResolvePath + 智能编码
- F4-2 错误处理统一：diff-viewer/file-editor/code-search catch 块改用 extractErrorMessage

【阶段五 · 验证 F5】
- tsc --noEmit 类型检查通过
- 人工审查通过：路径校验/错误处理/原子性/资源释放/权限策略/导出注册

工具数量：13 → 15（新增 file_move / file_info）
This commit is contained in:
thzxx
2026-07-21 16:08:39 +08:00
parent 8973ea6d47
commit 058ee2de36
12 changed files with 586 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files
electron/harness/tools/built-in/filesystem.ts
+285 -15
View File
@@ -22,7 +22,7 @@
* @see standard/开发规范.md — 使用 fs/path 内置模块
*/
import { readFile, writeFile, readdir, stat, appendFile, mkdir, open, unlink, rmdir, rm, rename, type FileHandle } from 'fs/promises';
import { readFile, writeFile, readdir, stat, mkdir, open, unlink, rmdir, rm, rename, type FileHandle } from 'fs/promises';
import { join, relative, resolve, dirname } from 'path';
import { existsSync } from 'fs';
import type { IMetonaTool, ToolExecutionContext } from '../../types/metona-tool';
@@ -33,7 +33,9 @@ import {
isPathWithinWorkspace,
safeResolvePath,
matchGlob,
matchAnyGlob,
extractErrorMessage,
decodeBufferWithDetection,
MAX_FILE_SIZE_BYTES,
FILE_TOOL_TIMEOUT_MS,
MAX_LINE_LENGTH,
@@ -83,13 +85,14 @@ export class ReadFileTool implements IMetonaTool {
readonly definition: MetonaToolDef = {
name: 'read_file',
description:
'Read the contents of a text file. Returns lines with offset/limit for large files. Auto-detects and rejects binary files (suggest view_image for images). File size limit: 10MB. Lines longer than 10000 chars are truncated.',
'Read the contents of a text file. Returns lines with offset/limit for large files. Auto-detects and rejects binary files (suggest view_image for images). File size limit: 10MB. Lines longer than 10000 chars are truncated. Smart encoding detection: supports UTF-8/UTF-8-BOM/UTF-16LE/UTF-16BE (BOM) and GBK/CP936 (fallback for Windows Chinese files). Returns the detected encoding in the response. Supports tail mode to read the last N lines (useful for logs).',
parameters: {
type: 'object',
properties: {
file_path: { type: 'string', description: 'Absolute or relative path to the file to read' },
offset: { type: 'number', description: 'Start line number (1-indexed, default 1)' },
limit: { type: 'number', description: 'Maximum lines to read (default 500, max 2000)' },
offset: { type: 'number', description: 'Start line number (1-indexed, default 1). Ignored if tail is specified.' },
limit: { type: 'number', description: 'Maximum lines to read (default 500, max 2000). Ignored if tail is specified.' },
tail: { type: 'number', description: 'Read the last N lines from the file. Takes precedence over offset/limit. Useful for reading log tails. Max 2000.' },
},
required: ['file_path'],
},
@@ -104,6 +107,10 @@ export class ReadFileTool implements IMetonaTool {
const filePath = safeResolvePath(args.file_path as string, context.workspacePath);
const offset = Math.max(1, (args.offset as number) ?? 1);
const limit = Math.min(2000, Math.max(1, (args.limit as number) ?? 500));
// F2-2: tail 模式 — 从文件末尾读取 N 行（优先于 offset/limit）
const tail = args.tail !== undefined
? Math.min(2000, Math.max(1, Math.floor(args.tail as number)))
: undefined;
// v0.3.2: 文件存在性 + 大小预检（先 stat 再决定是否读取，避免大文件 OOM）
let stats;
@@ -135,9 +142,27 @@ export class ReadFileTool implements IMetonaTool {
};
}
const content = await readFile(filePath, 'utf-8');
// F2-1: 智能编码检测 — 读取原始 Buffer 后用 BOM 检测 + UTF-8/GBK 降级
// 解决 Windows 中文环境 GBK 文件读取乱码，以及 UTF-16 文件读取问题
const buffer = await readFile(filePath);
const { content, encoding } = decodeBufferWithDetection(buffer);
const lines = content.split('\n');
const slicedLines = lines.slice(offset - 1, offset - 1 + limit);
// F2-2: 根据 tail 参数选择切片模式
let slicedLines: string[];
let truncated: boolean;
let startLine: number;
if (tail !== undefined) {
// tail 模式：从末尾取 tail 行
slicedLines = lines.slice(-tail);
truncated = lines.length > tail;
startLine = Math.max(1, lines.length - tail + 1);
} else {
// offset/limit 模式
slicedLines = lines.slice(offset - 1, offset - 1 + limit);
truncated = lines.length > offset - 1 + limit;
startLine = offset;
}
// v0.3.2: 超长行截断
const processedLines = slicedLines.map((line) => truncateLine(line));
@@ -147,9 +172,12 @@ export class ReadFileTool implements IMetonaTool {
content: processedLines.map((l) => l.text).join('\n'),
total_lines: lines.length,
returned_lines: slicedLines.length,
truncated: lines.length > offset - 1 + limit,
truncated,
start_line: startLine, // F2-2: 返回实际起始行号
lines_truncated: truncatedLines,
file_size: stats.size,
encoding, // F2-1: 检测到的编码（utf-8 / utf-8-bom / utf-16le / utf-16be / gbk / utf-8-loose）
mode: tail !== undefined ? 'tail' : 'offset', // F2-2: 读取模式
success: true,
};
} catch (error) {
@@ -207,13 +235,41 @@ export class WriteFileTool implements IMetonaTool {
}
if (mode === 'append') {
// append 模式：直接 appendFile（append 本身是原子的）
await appendFile(filePath, content, 'utf-8');
// F1-4: append 模式增强 — 显式 open(O_APPEND) + write + fsync + close
// 修复 v0.3.2 注释错误："append 本身是原子的"不准确
// 实际：fs.appendFile 内部是 open(O_APPEND) + write + close，存在：
// - 无 fsync：write 后数据在 page cache，崩溃可能丢失
// - 大内容（> 4KB）非完全原子：可能被分成多个 write
// 改进：显式 open + 循环 write + fsync + close，保证数据持久化到磁盘
// 保持 append 语义（O_APPEND 内核级追加），不改变并发行为
const fileExisted = existsSync(filePath);
const oldSize = fileExisted ? (await stat(filePath)).size : 0;
let fd: FileHandle | null = null;
try {
fd = await open(filePath, 'a');
// 'a' 模式下 write 追加到末尾（O_APPEND 内核级保证）
// 循环写入确保大内容完整写入（单次 write 可能不完整）
const buffer = Buffer.from(content, 'utf-8');
let totalWritten = 0;
while (totalWritten < buffer.length) {
const { bytesWritten } = await fd.write(buffer, totalWritten, buffer.length - totalWritten);
totalWritten += bytesWritten;
}
await fd.sync(); // fsync 保证数据持久化到磁盘
} finally {
if (fd) {
try { await fd.close(); } catch { /* 忽略关闭错误 */ }
}
}
const newStats = await stat(filePath);
return {
bytes_written: contentBytes,
path: filePath,
mode: 'append',
created: !fileExisted,
old_size: oldSize,
new_file_size: newStats.size,
success: true,
};
@@ -256,7 +312,7 @@ export class ListDirectoryTool implements IMetonaTool {
properties: {
dir_path: { type: 'string', description: 'Directory path (default: workspace root)' },
depth: { type: 'number', description: 'Recursive depth (default 1, max 5)' },
glob: { type: 'string', description: 'Filename filter pattern (e.g., "*.ts")' },
glob: { type: 'string', description: 'Filename filter pattern. Supports comma-separated multi-glob (e.g., "*.ts" or "*.ts,*.js,*.tsx")' },
include_hidden: { type: 'boolean', description: 'Include hidden files/dirs starting with "." (default false)' },
},
},
@@ -324,8 +380,8 @@ export class ListDirectoryTool implements IMetonaTool {
await this.listDir(rootPath, fullPath, maxDepth, glob, includeHidden, currentDepth + 1, results, maxEntries);
}
} else {
// glob 过滤仅适用于文件
if (glob && !matchGlob(entry.name, glob)) continue;
// F2-4: glob 过滤仅适用于文件，支持多 glob（逗号分隔，如 "*.ts,*.js"）
if (glob && !matchAnyGlob(entry.name, glob)) continue;
const stats = await stat(fullPath);
// v0.3.2: 添加 modified time（ISO 字符串）
results.push({
@@ -356,7 +412,7 @@ export class SearchFilesTool implements IMetonaTool {
pattern: { type: 'string', description: 'Search pattern (regex for content, glob for filenames)' },
target: { type: 'string', description: '"content" (default) to search file contents, "files" to search filenames', enum: ['content', 'files'] },
path: { type: 'string', description: 'Search directory (default: workspace root)' },
file_glob: { type: 'string', description: 'Limit to specific file types (e.g., "*.py")' },
file_glob: { type: 'string', description: 'Limit to specific file types. Supports comma-separated multi-glob (e.g., "*.py" or "*.ts,*.js,*.tsx")' },
limit: { type: 'number', description: 'Maximum results (default 50, max 200)' },
context_lines: { type: 'number', description: 'Lines of context to show around content matches (default 0, max 5). Only for target="content".' },
include_hidden: { type: 'boolean', description: 'Include hidden files/dirs starting with "." (default false)' },
@@ -443,7 +499,13 @@ export class SearchFilesTool implements IMetonaTool {
const fileStats = await stat(filePath);
if (fileStats.size > MAX_FILE_SIZE_BYTES) return;
const content = await readFile(filePath, 'utf-8');
// F2-3: 跳过二进制文件（避免读取乱码 + 提升性能）
// 空文件不算二进制，直接放行（size=0 时 isBinaryFile 内部 bytesRead=0 返回 false）
if (fileStats.size > 0 && await isBinaryFile(filePath)) return;
// F2-3: 用智能编码检测读取文件（支持 GBK 等非 UTF-8 编码）
const buffer = await readFile(filePath);
const { content } = decodeBufferWithDetection(buffer);
const lines = content.split('\n');
for (let i = 0; i < lines.length; i++) {
if (results.length >= limit) break;
@@ -492,7 +554,8 @@ export class SearchFilesTool implements IMetonaTool {
if (entry.isDirectory()) {
await this.walkDir(fullPath, callback, fileGlob, includeHidden, workspacePath);
} else {
if (fileGlob && !matchGlob(entry.name, fileGlob)) continue;
// F2-4: 支持多 glob（逗号分隔，如 "*.ts,*.js,*.tsx"）
if (fileGlob && !matchAnyGlob(entry.name, fileGlob)) continue;
await callback(fullPath, entry.name);
}
}
@@ -613,3 +676,210 @@ export class DeleteFileTool implements IMetonaTool {
}
}
}
// ===== 6. file_move =====
/**
* F3-1: 文件移动/重命名工具
*
* 安全策略：
* 1. 源路径和目标路径都必须在工作空间内（双重 safeResolvePath 校验）
* 2. 受保护文件（MEMORY.md）禁止移动（safeResolvePath 内置拦截）
* 3. 自动创建目标父目录
* 4. 支持覆盖已存在文件（overwrite 参数）
* 5. 禁止移动工作空间根目录
* 6. rename 在同文件系统上是原子操作
*/
export class FileMoveTool implements IMetonaTool {
readonly definition: MetonaToolDef = {
name: 'file_move',
description:
'Move or rename a file or directory. Source and destination must be within workspace. Auto-creates destination parent directory. Use overwrite: true to replace existing destination. Atomic on same filesystem (uses rename).',
parameters: {
type: 'object',
properties: {
source_path: { type: 'string', description: 'Path to the file/directory to move' },
destination_path: { type: 'string', description: 'Destination path' },
overwrite: { type: 'boolean', description: 'Overwrite if destination exists (default false)' },
},
required: ['source_path', 'destination_path'],
},
category: MetonaToolCategory.FILESYSTEM,
riskLevel: MetonaRiskLevel.MEDIUM,
requiresPermission: true,
timeoutMs: FILE_TOOL_TIMEOUT_MS,
};
async execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<unknown> {
try {
const sourcePath = args.source_path as string;
const destinationPath = args.destination_path as string;
const overwrite = (args.overwrite as boolean) ?? false;
if (!sourcePath || !destinationPath) {
return { error: 'source_path and destination_path are required', success: false };
}
// F3-1: 双路径校验（源和目标都必须在工作空间内 + 非 MEMORY.md）
let resolvedSource: string;
let resolvedDest: string;
try {
resolvedSource = safeResolvePath(sourcePath, context.workspacePath);
resolvedDest = safeResolvePath(destinationPath, context.workspacePath);
} catch (error) {
return { error: extractErrorMessage(error), success: false };
}
// 禁止移动工作空间根目录
const workspaceRoot = resolve(context.workspacePath);
if (resolvedSource === workspaceRoot) {
return {
error: 'Cannot move workspace root directory',
source_path: sourcePath,
success: false,
};
}
// 源必须存在
if (!existsSync(resolvedSource)) {
return { error: 'Source not found', path: sourcePath, success: false };
}
// 目标已存在处理
let overwritten = false;
if (existsSync(resolvedDest)) {
if (!overwrite) {
return {
error: 'Destination already exists. Use overwrite: true to replace.',
destination_path: destinationPath,
success: false,
};
}
// overwrite: true — 删除目标
const destStats = await stat(resolvedDest);
if (destStats.isDirectory()) {
await rm(resolvedDest, { recursive: true, force: false });
} else {
await unlink(resolvedDest);
}
overwritten = true;
}
// 自动创建目标父目录
const destParentDir = dirname(resolvedDest);
if (!existsSync(destParentDir)) {
await mkdir(destParentDir, { recursive: true });
}
// 执行移动（rename 在同文件系统上是原子操作）
await rename(resolvedSource, resolvedDest);
const stats = await stat(resolvedDest);
return {
source: sourcePath,
destination: destinationPath,
isDirectory: stats.isDirectory(),
overwritten,
success: true,
};
} catch (error) {
return { error: extractErrorMessage(error), success: false };
}
}
}
// ===== 7. file_info =====
/**
* F3-2: 文件信息查询工具
*
* 返回文件的元信息：大小、时间戳、类型、编码检测、权限位。
* 只读操作，风险等级 SAFE。
*
* 编码检测只读取前 8KB，避免大文件 OOM。
*/
export class FileInfoTool implements IMetonaTool {
readonly definition: MetonaToolDef = {
name: 'file_info',
description:
'Get detailed file information: size, timestamps (created/modified/accessed), type (file/directory/symlink), encoding detection (UTF-8/UTF-16/GBK), binary check, and permission bits.',
parameters: {
type: 'object',
properties: {
file_path: { type: 'string', description: 'Path to the file or directory' },
},
required: ['file_path'],
},
category: MetonaToolCategory.FILESYSTEM,
riskLevel: MetonaRiskLevel.SAFE,
requiresPermission: false,
timeoutMs: FILE_TOOL_TIMEOUT_MS,
};
async execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<unknown> {
try {
const filePath = safeResolvePath(args.file_path as string, context.workspacePath);
if (!existsSync(filePath)) {
return { error: 'File not found', path: args.file_path, success: false };
}
const stats = await stat(filePath);
const isDir = stats.isDirectory();
const isFile = stats.isFile();
const isSymlink = stats.isSymbolicLink();
const info: Record<string, unknown> = {
path: args.file_path,
absolute_path: filePath,
type: isDir ? 'directory' : isFile ? 'file' : isSymlink ? 'symlink' : 'unknown',
size: stats.size,
created: stats.birthtime.toISOString(),
modified: stats.mtime.toISOString(),
accessed: stats.atime.toISOString(),
mode: stats.mode.toString(8), // 八进制权限位
success: true,
};
// F3-2: 文件类型额外信息（编码 + 二进制检测）
// 只读前 8KB，避免大文件 OOM
if (isFile) {
let fd: FileHandle | null = null;
try {
fd = await open(filePath, 'r');
const buffer = Buffer.alloc(8192);
const { bytesRead } = await fd.read(buffer, 0, 8192, 0);
const actualBuffer = buffer.slice(0, bytesRead);
// 二进制检测（NULL 字节检查）
let isBinary = false;
for (let i = 0; i < bytesRead; i++) {
if (actualBuffer[i] === 0) {
isBinary = true;
break;
}
}
info.is_binary = isBinary;
// 编码检测（仅非二进制文件）
if (!isBinary && bytesRead > 0) {
const { encoding } = decodeBufferWithDetection(actualBuffer);
info.encoding = encoding;
} else if (bytesRead === 0) {
info.encoding = 'utf-8'; // 空文件默认 UTF-8
}
} catch {
// 读取失败，不报告编码信息
} finally {
if (fd) {
try { await fd.close(); } catch { /* 忽略关闭错误 */ }
}
}
}
return info;
} catch (error) {
return { error: extractErrorMessage(error), success: false };
}
}
}