【免费下载链接】fastctxFast, context-efficient repository tools for AI agents (MCP)项目地址https://gitcode.com/gh_mirrors/fa/fastctx点击查看免费下载FastCtx replace 是面向 AI Agent 的本地批量替换工具通过 MCP 协议提供先预览、再写入的确定性批量修改能力。它专为符号重命名、导入路径重写、配置键迁移这类机械式变更设计用 dry-run 预览、原子写入和跨进程文件锁三道防线让全库级替换不出乱子。为什么批量替换对 AI Agent 是个危险动作当编码 Agent 需要把old_name(全部改成new_name(时最朴素的做法是拼一条sed或grep 脚本命令直接执行。问题在于误伤范围不可控正则写错一点改动就可能波及上千处而 Agent 往往执行完才发现并发冲突用户此刻正在编辑器里改同一个文件Agent 的写入会直接覆盖未保存的外部修改文件损坏风险写到一半断电、进程崩溃文件就停在写了一半的中间状态静默失真编码、BOM、CRLF/LF 换行、文件末尾换行符任何一项被悄悄改掉diff 都会变得面目全非。FastCtx 的replace工具正是为了解决这些问题而设计它把批量替换拆成两趟确定性流程——先完整分析、再逐文件提交——每一步都有明确的拒绝条件。核心实现位于 src/edit/replace.rs参数定义见 src/edit/mod.rs。两趟式流程先数清爆炸半径再动笔replace的执行分两个阶段第二阶段的写入范围被第一阶段的统计结果严格约束第一趟冻结候选集 全量计数工具先扫描目标目录可用glob参数缩小范围冻结候选文件集合然后对每个文件以正确的编码解码为逻辑文本逐处匹配正则统计总匹配数并生成前几处匹配的预览行号: 原文 - 新文做一次完整的试替换校验结果大小、编码可表示性等。此时如果总匹配数超过max_replacements上限工具会直接拒绝写入返回类似这样的错误Refusing to write: 3421 matches exceed max_replacements500. Raise the cap or narrow the pattern; nothing was written.这个设计的关键在于max_replacements是全库级别的熔断器。正则能匹配空串零宽模式时FastCtx 甚至要求必须先设置该上限才允许执行防止在每个位置插入内容这类灾难性模式。第二趟逐文件提交候选集冻结后工具按确定的顺序逐文件处理。每写一个文件前都会重新验证下一节详述单个文件失败只会进入失败报告其余文件继续处理最后汇总为一份完整报告。dry-run 预览一行参数看清全部改动把dry_run设为truereplace只报告、不写入{ pattern: old_name\\(, replacement: new_name(, path: V:/repo/src, glob: **/*.rs, dry_run: true }典型输出src/lib.rs 12: old_name( - new_name( 40: old_name( - new_name( (Complete: dry run — 12 matches in 3 files; nothing written.)预览同时列出四类信息命中的文件与行、被跳过的文件如二进制文件、规划失败的文件、以及扫描器没能进入的路径权限被拒、符号链接循环等标记为unreachable。对要写盘的工具来说没走进某个目录不是脚注而是必须上报的覆盖缺口——只要存在 unreachable 路径收尾状态就会从Complete降级为Partial见 src/edit/replace.rs 中的downgrade_if_unreachable。原子写入断电也写不出半截文件replace从不直接修改目标文件。真正的落盘走的是 src/control/transaction.rs 中的atomic_replace同目录写临时文件命名为.{文件名}.{进程号}.{序号}.tmp同目录是为了保证后续重命名在同一文件系统内完成完整落盘并sync_all刷到磁盘且临时文件直接按原文件的 Unix 权限位创建原子重命名覆盖目标Linux/macOS 用renamePOSIX 保证原子性Windows 用ReplaceFileW任何一步失败临时文件立即删除目标文件保持原样。也就是说观察者任何时候读到的都要么是旧版本、要么是完整的新版本不存在中间态。此外还有一个容易被忽视的细节如果目标文件存在硬链接硬链接数大于 1replace会拒绝写入并提示先解除额外链接——因为原子替换会切断其他链接路径指向的内容src/edit/document.rs。跨进程锁多个 Agent 会话同时改同一文件会怎样这是replace最有工程含量的一层实现在 src/edit/locks.rs。问题不只是同一个路径。同一个文件可能有多个名字相对/绝对路径不同、大小写不同、符号链接、甚至硬链接别名。如果锁只按字符串路径上锁两个进程完全可能拿着不同拼写的路径同时改同一个文件。FastCtx 的做法是为每个文件计算一个文件系统级身份PathIdentityUnix设备号 inode 号Windows卷序列号 文件索引文件尚不存在时规范化父目录身份 规范化文件名保证创建前和创建后拿到同一把锁。不同拼写、符号链接、硬链接别名都会归约到同一身份因此它们共享同一把锁。锁本身是内核级独占文件锁存放在用户私有目录edit-locks下按身份哈希命名目录构建与防符号链接劫持逻辑见 src/edit/private_storage.rs。这带来两个保证跨进程互斥另一个 FastCtx 会话甚至另一个用户目录下的服务正在编辑同一文件时后来的请求会收到明确报错Cannot lock ... for editing. Retry after the other FastCtx process finishes.崩溃自愈锁由操作系统持有持锁进程崩溃时内核自动释放不需要任何锁文件清理机制——项目测试里专门验证了别名路径无法绕过锁以及持锁进程被 kill 后锁自动释放src/edit/locks.rs。同一进程内的并发调用则由共享的内存锁表src/edit/mod.rs串行化两层锁按名称身份 → 目标身份的固定顺序获取避免死锁。CAS 乐观校验拒绝覆盖别人的修改拿到锁还不够。第一趟和第二趟之间可能已经过了一段时间期间用户或别的工具可能改过文件。replace采用比较并交换CAS策略在提交前做三重核对src/edit/replace.rs核对项内容不匹配的后果文件身份设备/inode 或卷/文件索引是否还是原来那个该文件进入失败报告其余文件继续内容版本原始字节的 SHA-256 是否未变同上提示changed on disk during the edit; nothing was written匹配数量重新试算的匹配数是否与预览一致同上三个条件全过才执行原子写入。任何一步不过该文件的改动被整体放弃绝不会写出一半对一半错的结果。单文件目标则更严格任何可跳过的异常都会直接返回错误。字节级保真编码、换行与权限原样保留很多批量工具能跑但伤文件把 UTF-8 文件写成带 BOM 的、把 CRLF 统一成 LF、丢掉文件末尾的换行符。replace在 src/edit/document.rs 中为每个文件维护一张逻辑视图匹配和替换都在统一为\n的逻辑文本上进行写回时按该文件原有的行结束风格多数是 CRLF 就整体 CRLF逐行还原替换片段必须能用文件原编码WHATWG 标签编码编码不了就拒绝而不是硬写原文件末尾有无换行符结果就保持一致未命中的字节原样拷贝BOM、Unix 权限位一并保留。再叠加两道资源护栏候选文件数超过 10000 个会要求你缩小path或glob单个文件与替换结果默认不得超过 256 MiB可在控制终端 Config → Editing 中于 64 MiB–4 GiB 间调整超限报File too large for line edits或Refusing to write。读懂收尾报告Complete、Partial 与四类清单每次执行replace都会输出一份结构化报告按文件分组列出成功文件/path/to/file.rs: 8 replacementsskipped跳过的文件及原因如 binary filefailed失败文件及具体原因unreachable未进入的路径及原因。结尾的状态行是判断依据(Complete: 42 replacements in 6 files.)(Partial: 42 replacements written in 6 files; 1 file failed — see the report above.)只要出现过失败、或存在 unreachable 路径状态必然是Partial而非Complete——对一个会写盘的工具来说夸大覆盖率才是真正危险的方向src/edit/replace.rs。总结把批量替换变成一件可审计的事把replace的安全机制串起来看就是四条清晰的防线dry-run max_replacements动手之前先知道会改多少处超上限直接拒绝文件身份锁硬链接、符号链接、不同拼写的别名都被归约为同一把内核级跨进程锁CAS 乐观校验身份、SHA-256 版本、匹配数三关全过才允许写入外部修改一律让位原子替换 字节保真临时文件 原子重命名杜绝半截文件编码、换行、BOM、权限原样保留。对新手最实用的操作路径是先dry_run: true预览 → 核对报告 → 加max_replacements保险 → 正式执行 → 看结尾是Complete还是Partial。这四步走完一次全库级批量替换就变成了一件完全可审计、可回滚通过版本控制的事情。赞分享【免费下载链接】fastctxFast, context-efficient repository tools for AI agents (MCP)项目地址https://gitcode.com/gh_mirrors/fa/fastctx点击查看免费下载相关推荐如何用Sketch-Find-And-Replace插件轻松完成批量文本替换如何用Sketch Find And Replace插件轻松完成批量文本替换 还在为Sketch中重复修改文本而烦恼吗每次设计稿需要更新设计师姓名、修改版权信DiceDB JSON.MSET 命令详解批量原子写入多个 JSON 键值DiceDB JSON.MSET 命令详解批量原子写入多个 JSON 键值 JSON.MSET 是 DiceDB 提供的批量 JSON 写入命令允许在一次调数据库缓存后端FastCtx搜索详解grep与glob如何完成代码内容搜索和文件发现的完整工作流FastCtx搜索详解grep与glob如何完成代码内容搜索和文件发现的完整工作流 FastCtx 是一款面向 AI 编程代理MCP的本地 Rust 工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考