做 Agent 会用到的 Node API（1）：路径与文件

本系列讲实现 Agent harness 时脚下的 Node API按场景拆篇不当成 Node 全手册。示例仓库react-agent-mini若还不熟「Agent 主循环长什么样」可先看同仓库前作150 行搞懂 Agent 主循环本篇相关代码库工具 Read/Write · Agent Memory场景工具的手脚落在磁盘上Agent 要「读仓库、改文件、记偏好」最后都会碰到两件事路径怎么拼、怎么防逃出工作区文件怎么读、怎么写、写前要不要建目录在 Node 里这对应两个模块模块管什么node:path字符串层面的路径拼接、解析绝对路径、算相对关系node:fs/promises真正碰磁盘stat/readFile/writeFile/mkdir本篇只讲 Agent 里高频的那一小撮对照react-agent-mini的 Read / Write / Memory。1.path先把字符串变成「可信绝对路径」常用三个import{isAbsolute,relative,resolve,join,dirname}fromnode:pathresolve(cwd,inputPath)// 相对 → 绝对处理 . / ..relative(cwd,absolute)// 绝对相对 cwd 的相对串join(cwd,.agents,memory,MEMORY.md)// 纯拼接片段dirname(filePath)// 父目录给 mkdir 用Agent 里最关键的一招cwd 沙箱模型可能传../../etc/passwd。只靠「拼一下」不够要校验结果仍在工作区子树内export function resolvePathUnderCwd( inputPath: string, cwd process.cwd(), ): string { const absolute resolve(cwd, inputPath) const rel relative(cwd, absolute) if (rel.startsWith(..) || isAbsolute(rel)) { throw new Error(拒绝访问路径必须在当前工作目录内) } return absolute }要点resolve会消掉..所以必须再看relative结果rel.startsWith(..)还在往上爬isAbsolute(rel)Windows 上相对结果有时是另一盘符绝对路径也要拦Read / Write / Edit / Glob / Grep 都复用这一函数——路径规则写一次所有文件工具共用。Memory 则用join钉死约定路径不接受模型乱指join(cwd,.agents/memory/MEMORY.md)2.fs/promises异步读盘别阻塞事件循环Agent 一轮里可能连读多个文件用 Promise 版方便await进Tool.callimport{readFile,writeFile,stat,mkdir}fromnode:fs/promisesstat先问「是不是文件、有多大」constfileStatawaitstat(filePath)if(!fileStat.isFile())thrownewError(不是普通文件)if(fileStat.sizeMAX_READ_BYTES)thrownewError(文件过大)Read 在readFile之前做这件事避免把巨型二进制整份读进内存再报错。ENOENT不存在要转成对模型友好的文案而不是把堆栈塞进tool_resulttry{fileStatawaitstat(filePath)}catch(err){if(errtypeoferrobjectcodeinerrerr.codeENOENT){thrownewError(文件不存在:${args.file_path})}throwerr}readFile拿正文constcontentawaitreadFile(filePath,utf-8)指定utf-8得到string。Agent 文本工具几乎总是这么读二进制另议你们 MCP Resource 对 blob 是占位不塞 base64。writeFilemkdir写入与建父目录Write 的典型顺序awaitmkdir(dirname(filePath),{recursive:true})awaitwriteFile(filePath,args.content,utf-8)recursive: true父目录多层一次性建好Memory 启动时的ensureMemoryDirExists也是同一个mkdir(..., { recursive: true })方便模型直接 Write少一轮「先建目录」也可用stat判断「创建还是覆盖」给模型不同成功文案——但仍是覆盖写语义。3. 字节预算Buffer.byteLength截断「最多 32KB / 100KB」时不要用string.length那是 UTF-16 码元数。Memory 用的是Buffer.byteLength(content,utf-8)和readFile/writeFile的字节语义一致避免中文多字节把预算算爆。一张对照表Agent 需求Node API仓库里相对路径 → 绝对 防穿越resolverelativeisAbsoluteresolvePathUnderCwd约定死路径joinMemory / hooks / skills 发现父目录dirnameWrite 前 mkdir元信息 / 大小statRead 上限、mtime 刷新读文本readFile(..., utf-8)Read、加载 AGENTS/MEMORY写文本writeFileWrite、Edit 落盘建目录mkdir({ recursive: true })Write、ensure memory dir常见坑坑建议只resolve不校验模型可逃出 cwd必须relative检查用existsSync再读有竞态stat/readFile捕获ENOENT更干净同步fs.readFileSync塞进热路径拖住整条 Agent 事件循环工具里优先 promises用length当字节预算多字节字符不准用Buffer.byteLengthWindows 路径分隔符尽量交给path少手写/\拼接和主循环的关系主循环query()不关心磁盘工具层才碰path/fs。query → tool_use: Read → resolvePathUnderCwd → stat / readFile → tool_result 文本回模型所以学 Node 文件 API是在学Agent 的效应器不是在学 ReAct 本身。主循环仍是前作那 150 行本篇补的是「手脚怎么落地」。本系列下一篇预告2子进程Bash 与 Hooks 的壳——spawn、stdout/stderr、超时杀掉、跨平台 shell。你可以带走什么路径先沙箱再读写——resolverelative是文件类工具的安全带。promises 版 fs——和async call()同一套心智。先stat再读——类型、大小、是否存在一次问清。写入常配mkdir(recursive)——少让模型多走一轮建目录。预算按字节——Buffer.byteLength不是string.length。仓库与延伸GitHubreact-agent-mini本系列定位Agent 实现向的 Node API 笔记与 harness 设计系列分开前作主循环150 行搞懂 Agent 主循环相关实现ReadTool.ts · WriteTool.ts · memory/load.ts欢迎 Star、Issue 和 PR。本文为「做 Agent 会用到的 Node API」系列第 1 篇示例基于 react-agent-mini。