做 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}from'node:path'resolve(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.call：

import{readFile,writeFile,stat,mkdir}from'node:fs/promises'

`stat`：先问「是不是文件、有多大」

constfileStat=awaitstat(filePath)if(!fileStat.isFile())thrownewError('不是普通文件')if(fileStat.size>MAX_READ_BYTES)thrownewError('文件过大')

Read 在readFile之前做这件事，避免把巨型二进制整份读进内存再报错。

ENOENT（不存在）要转成对模型友好的文案，而不是把堆栈塞进tool_result：

try{fileStat=awaitstat(filePath)}catch(err){if(err&&typeoferr==='object'&&'code'inerr&&err.code==='ENOENT'){thrownewError(`文件不存在:${args.file_path}`)}throwerr}

`readFile`：拿正文

constcontent=awaitreadFile(filePath,'utf-8')

指定'utf-8'，得到string。Agent 文本工具几乎总是这么读；二进制另议（你们 MCP Resource 对 blob 是占位，不塞 base64）。

`writeFile`+`mkdir`：写入与建父目录

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	仓库里
相对路径 → 绝对 + 防穿越	`resolve`+`relative`+`isAbsolute`	`resolvePathUnderCwd`
约定死路径	`join`	Memory / hooks / skills 发现
父目录	`dirname`	Write 前 mkdir
元信息 / 大小	`stat`	Read 上限、mtime 刷新
读文本	`readFile(..., 'utf-8')`	Read、加载 AGENTS/MEMORY
写文本	`writeFile`	Write、Edit 落盘
建目录	`mkdir({ recursive: true })`	Write、ensure memory dir

常见坑

坑	建议
只`resolve`不校验	模型可逃出 cwd；必须`relative`检查
用`existsSync`再读	有竞态；`stat`/`readFile`捕获`ENOENT`更干净
同步`fs.readFileSync`塞进热路径	拖住整条 Agent 事件循环；工具里优先 promises
用`length`当字节预算	多字节字符不准；用`Buffer.byteLength`
Windows 路径分隔符	尽量交给`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。

你可以带走什么？

路径先沙箱，再读写——resolve+relative是文件类工具的安全带。
promises 版 fs——和async call()同一套心智。
先stat再读——类型、大小、是否存在，一次问清。
写入常配mkdir(recursive)——少让模型多走一轮建目录。
预算按字节——Buffer.byteLength，不是string.length。

仓库与延伸

GitHub：react-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。

日记详情

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

场景：工具的手脚落在磁盘上

1.path：先把字符串变成「可信绝对路径」