做 Agent 会用到的 Node API(1):路径与文件

发布时间:2026/11/16 22:50:35

做 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。
延伸阅读

更多相关文章

2026/11/13 18:03:50

AI算力盒子与DMA:从数据传输到边缘AI部署的技术解析

最近在技术社区和硬件圈子里,一个词被反复提及——“AI算力盒子”。乍一看,这似乎又是一个被热炒的概念,让人联想到那些层出不穷的“智能硬件”和“边缘计算盒子”。但当你深入去看,会发现很多讨论都把它和另一个经典的技术名词“…

2026/11/16 22:50:35

电商高并发场景下的JVM调优与多线程实践

1. 电商高并发场景的技术挑战电商大促期间的系统压力与普通场景存在本质区别。去年双11某头部电商平台的峰值数据显示,核心交易接口QPS突破50万,订单创建服务集群的瞬时线程数达到8000,内存中同时存活的订单对象超过2000万个。这种量级的并发…

2026/11/13 22:20:25

Inter字体:重新定义数字时代的文字可读性标准

Inter字体:重新定义数字时代的文字可读性标准 【免费下载链接】inter The Inter font family 项目地址: https://gitcode.com/gh_mirrors/in/inter 在像素密度日益增长的屏幕世界里,文字不再是简单的信息载体,而是用户体验的核心组成部…

2026/11/16 22:47:04

大四考电工证是什么真实经历告诉你实操考试心里没底怕挂科

大四考电工证是什么真实经历告诉你实操考试心里没底怕挂科 实操考试心里没底怕挂科,这事儿我懂,我自己就经历过。去年我还在洛阳一个建筑项目上做现场管理员,看到好几个大学生抱着电工证的考试资料,眉头紧锁,问他们怎么了,才知道他们也是大四准备考电工…

2026/11/16 22:47:04

怎么考中级高级电工证外省证能转吗电子证书怎么用

怎么考中级高级电工证外省证能转吗电子证书怎么用 之前考的证在外省能不能转过来?这几乎是每个想考电工证的小伙伴都会问的问题。其实,很多人的证书是在老家或外省考的,但因为工作调动、换城市等原因,不得不面对证书是否能转移的问题。今天就以济源市的一…

2026/11/16 22:47:04

电工证复审多少钱陕西到期换证流程通过率揭秘

电工证复审多少钱陕西到期换证流程通过率揭秘 不知道去哪报名怕被中介坑?陕西的电工证复审流程其实没有想象中那么复杂,但关键是要找对门路,避免被坑。尤其是像你这样刚拿到证、还不太懂流程的人,最容易被那些“包过”“包办”的虚假宣传忽悠。今天我们就…

2026/11/16 22:47:04

河南电工证去哪里办理网上查询不难 普通工人也能轻松考下来

河南电工证去哪里办理网上查询不难 普通工人也能轻松考下来 学历不高怕报不上名?河南电工证去哪里办理?你不是一个人。很多一线建筑工人因为学历限制,担心自己考不了电工证,甚至不知道从哪儿开始准备。其实,现在的政策已经非常人性化,网上查询流程也越…

2026/11/16 22:42:03

低压电工作业试题讲解千万别踩坑,找工作必备的备考攻略来了

低压电工作业试题讲解千万别踩坑,找工作必备的备考攻略来了 你是不是正在为找工作发愁?是不是听说必须要有低压电工作业证才能上岗?别急,今天就给你讲讲低压电工作业试题讲解的那些事,帮你避开坑,顺利拿到证书,早日实现就业!…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/16 0:00:11

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱 你是不是也和我一样,想考电工证,但不知道去哪报名,怕被中介坑?最近网上有不少人问“黎城电工证查询报名费多少钱”,结果一查,信息五花八门,真假难辨。别担心,今天我就从一线从业者的角度…

2026/11/16 0:00:11

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来?

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来? 之前考的证在外省能不能转过来?这个问题困扰着很多在外地打工的电工,尤其是像南阳卧龙区的建筑工人,他们常年在工地作业,手上持有电工证是基本要求,但很多人因为工作流动性大,担心证书不能转到本…

2026/11/15 4:46:37

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑