人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载在构建生产级 AI Agent 时让模型以编程方式查看、创建和修改文件是最常见也最危险的需求之一。本指南以 harness-sdk 的 TypeScript SDKstrands-ts内置的fileEditor工具为对象系统讲解它的四种核心命令view、create、str_replace、insert、参数语义、安全校验机制与沙箱集成方式。读完本文你将能够把 fileEditor 挂载到 Agent 上让模型通过自然语言可靠地操作文件系统同时理解其路径校验、唯一性约束和大小限制等关键防护手段。一、工具定位一个可编程的文件系统编辑器fileEditor是 harness-sdk 提供的vended tool官方预置工具之一用于让 Agent 程序化地查看、创建和编辑文件。它提供字符串替换、行插入和目录查看能力并内置安全校验。该工具的实现位于 file-editor.ts对外导出封装在 index.ts入口描述为Filesystem editor tool for viewing, creating, and editing files. Supports view (with line ranges), create, str_replace, and insert operations. Files must use absolute paths.在 SDK 的发布配置中它通过独立子路径导出消费者可以按需引入而不必加载整个vended-tools包见 package.json 中的./vended-tools/file-editor导出项。此外SDK 还提供了功能对应的 Python 版本实现file_editor.py方便跨语言项目对齐行为。二、安全警告先读清楚再使用原文档将安全警告置于最前这是使用该工具前必须理解的前提该工具会在没有沙箱或工作区限制的情况下读取和写入任意绝对路径的文件。具体而言仅可用于受信任的输入模型输出的内容、提示词注入带来的指令都不可信除非你有额外的防护文件操作以 Node.js 进程的完整权限执行这意味着它能读写进程权限允许范围内的所有路径生产部署建议放入沙箱环境容器、虚拟机等运行切勿在没有任何额外安全措施的情况下向不受信任的用户或不受信任的提示词输入暴露此工具。从源码看工具的所有 I/O 实际都经由 Agent 配置的Sandbox完成sandbox.readText、sandbox.writeText、sandbox.listFiles接口定义见 base.ts因此无沙箱与否取决于 Agent 的运行时配置——在本地直接运行时即为宿主机权限。这一点务必在部署架构层面想清楚。三、功能特性一览fileEditor 的核心能力与 README 保持一致并补充实现细节特性说明实现位置查看文件带行号输出支持可选行范围[start, end]handleViewfile-editor.ts创建文件写入初始内容自动创建缺失的父目录handleCreatefile-editor.ts字符串查找替换精确匹配、强制唯一出现多次则拒绝buildStrReplaceResultfile-editor.ts行插入在任意位置按行插入文本0 起始下标buildInsertResultfile-editor.ts目录查看递归列出最多 2 层深度可配置排除隐藏项listDirectoryfile-editor.ts文件大小限制默认上限 1MBDEFAULT_MAX_FILE_SIZE 1048576assertWithinSizeLimitfile-editor.ts其中两个关键常量定义在源码顶部file-editor.tsSNIPPET_LINES 4编辑操作返回结果时变更点前后各展示 4 行上下文片段MAX_DIRECTORY_DEPTH 2目录递归列出的最大深度。四、安装与接入 Agent将 fileEditor 挂载到 Agent 只需几行代码import { fileEditor } from strands-agents/sdk/vended-tools/file-editor import { Agent, BedrockModel } from strands-agents/sdk const agent new Agent({ model: new BedrockModel({ region: us-east-1 }), tools: [fileEditor], }) await agent.invoke(Create a file /tmp/notes.txt with # My Notes)接入后Agent 便可以直接用自然语言驱动文件操作例如await agent.invoke(Create /tmp/config.json with {debug: false}) await agent.invoke(Replace debug: false with debug: true in /tmp/config.json) await agent.invoke(View lines 1-20 of /tmp/config.json)4.1 导入路径说明strands-agents/sdk/vended-tools/file-editor是 package.json 中显式声明的子路径导出package.json 中./vended-tools/file-editor条目指向dist/src/vended-tools/file-editor/index.js。如果希望一次性引入所有内置工具也可以使用聚合入口strands-agents/sdk/vended-tools见 index.ts但注意该聚合入口依赖 Node 内置模块如child_process浏览器环境下应使用各工具的子路径导出。4.2 自定义工具实例makeFileEditor除了直接使用默认的fileEditor实例SDK 还提供工厂函数makeFileEditor支持两种用法file-editor.ts// 用法一仅自定义名称与描述 const custom makeFileEditor({ name: myFileEditor, description: Custom file editor description, }) // 用法二在创建时绑定沙箱沙箱实现内部常这样做 const bound makeFileEditor(mySandbox, { name: fileEditor })其行为规则是若传入Sandbox实例则在创建时绑定否则在每次调用时从context.agent.sandbox读取。这正是沙箱实现通过getTools()暴露内置工具时采用的模式。相应的MakeFileEditorOptions类型定义在 file-editor.ts。4.3 输入校验Zod Schema工具输入由 Zod Schema 定义并做运行时校验file-editor.ts并通过 SDK 的tool()工厂tool-factory.ts构建为可调用的InvokableToolcommand枚举[view, create, str_replace, insert]必填path绝对路径字符串必填file_textcreate命令的初始内容可选view_range[start, end]二元组1 起始end可为-1表示到文件末尾可选old_strstr_replace的待查找精确字符串可选new_str替换/插入文本可选insert_line插入行号0 起始可选。对应的 TypeScript 类型定义集中在 types.ts包括ViewInput、CreateInput、StrReplaceInput、InsertInput及联合类型FileEditorInput同时声明了FileEditorOptionsmaxFileSize默认 1MB与可插拔的IFileReader接口read(path): Promisestring用于扩展支持不同文件类型。五、命令详解参数、行为与错误语义5.1view查看文件或目录参数pathstring必填文件或目录的绝对路径view_range可选[start_line, end_line]1 起始end可为-1表示读到文件末尾EOF。行为与输出文件存在且是文件时读取内容并按cat -n风格输出带行号的结果输出格式为Heres the result of running \cat -n on:行号右对齐填充 6 位后接两空格 makeOutput输出前会展开制表符tab 扩展为 8 个空格路径是目录时递归列出内容最多 2 层排除隐藏文件与隐藏目录此时不允许传view_range读取后执行大小校验默认 1MB超出即报错。边界校验applyViewRangefile-editor.tsstart必须满足1 start nLines否则报错并提示合法区间end ! -1时end nLines否则报错end ! -1时end start否则报错。典型错误信息示例路径不存在The path path does not exist. Please provide a valid path.非绝对路径提示应以/开头并给出path.resolve推算的建议路径。5.2create创建新文件参数pathstring必填新文件的绝对路径file_textstring必填初始内容。行为与约束若目标已存在文件或目录直接拒绝File already exists at: path. Cannot overwrite files using command \create.——create 命令不允许覆盖这是防止误写的关键设计缺失的父目录会被自动创建底层Sandbox.writeFile要求实现支持创建父目录成功后返回File created successfully at: path允许创建空文件file_text: 允许在多层不存在的目录中创建文件。5.3str_replace唯一字符串替换参数pathstring必填文件绝对路径old_strstring必填要查找的精确字符串new_strstring可选替换字符串。核心约束old_str必须且只能出现一次buildStrReplaceResultold_str为空字符串时拒绝old_str must not be empty未找到时报错old_str \... did not appear verbatim in出现多次时报错并列出所有出现行号Multiple occurrences of old_str \... in lines [...]提示请确保其唯一。替换细节精确字面量匹配非正则new_str中的$、$1、$$等模式会原样保留不解释为替换引用支持多行old_str与多行new_strnew_str缺省或为空串时即删除匹配内容替换区域之外的内容包括 tab、CRLF 换行、二进制字节保持原样替换点前后各 4 行生成上下文片段供模型复核Review the changes and make sure they are as expected. Edit the file again if necessary.5.4insert按行插入参数pathstring必填文件绝对路径insert_linenumber必填插入位置的行号0 起始0表示文件开头new_strstring必填要插入的文本。行为与校验buildInsertResult合法范围为[0, nLines]nLines为文件行数insert_line等于行数即插入到文件末尾负数或超过行数报错Invalid \insert_line parameter: ... should be within the range of lines of the file: [0, nLines]支持多行插入new_str含换行空文件也允许插入insert_line: 0结果同样返回变更点附近前后各 4 行的片段并提示复核缩进与重复行。注意view的行号是1 起始而insert的insert_line是0 起始两者坐标系不同编写提示词时需特别留意避免 Agent 因混淆行号而插错位置。六、安全机制四道防线原文档的 Security 章节总结了四条防护下面结合源码逐一展开6.1 强制绝对路径所有命令都先经过validatePathfile-editor.ts使用path.isAbsolute判断若为相对路径则报错并附带path.resolve计算出的建议绝对路径。6.2 拦截目录穿越对原始输入按/或\拆分后检查是否包含..段。源码注释明确指出path.normalize会解析掉..因此必须在 normalize 之前对原始字符串做检查否则view /tmp/../etc/passwd这类输入就会被放行。匹配到..即抛错Invalid path: path traversal is not allowed。6.3 文件大小限制读取内容后用Buffer.byteLength(content, utf-8)计算字节数assertWithinSizeLimit超过默认10485761MB即拒绝报错信息同时给出实际大小与上限。测试用例使用x.repeat(1048577)1MB1 字节验证了该拦截见 file-editor.test.node.ts。6.4 清晰的错误信息工具在所有异常路径都返回带上下文的可读错误缺失路径、非绝对路径、路径穿越、目录误用、重复出现、范围越界等均有专门文案方便模型在对话中自我纠错并重试。6.5 沙箱路径探测的细节工具通过probeSandboxPathfile-editor.ts判断路径存在性与是否为目录它列出父目录后匹配条目名父目录不存在或条目缺失时视为不存在但权限错误、传输错误等非未找到异常会被原样抛出而不是伪装成路径不存在——测试用例专门验证了这一点当listFiles抛出EACCES时错误会继续向上传播见 file-editor.test.node.ts。七、沙箱集成所有 I/O 都走 Sandbox 抽象实现上fileEditor 并不直接调用fs而是通过 SDK 的Sandbox抽象类完成全部读写与列举操作sandbox.readText(path)读取文件文本base.tssandbox.writeText(path, content)写入文件文本base.tssandbox.listFiles(path)列举目录条目返回FileInfo[]base.ts。Sandbox是抽象基类具体实现可以是本地文件系统沙箱也可以是远程/容器化环境。这带来两个使用要点默认实例在调用时读取context.agent.sandbox因此工具实际能访问的路径范围取决于 Agent 配置的沙箱沙箱实现可通过getTools()用makeFileEditor(sandbox)绑定自身让 Agent 拿到的工具天然限定在自己的沙箱文件系统内。测试文件 file-editor.test.node.ts 中专门有一组通过沙箱操作的用例如通过TestSandbox完成 view/create/str_replace/insert 全流程并验证了带尾部斜杠的路径也能正确处理。八、已知限制原文档列出的限制与实现一一对应使用时需心中有数仅限 Node.js依赖文件系统 API 与 Node 内置模块不能在浏览器端运行仅支持文本文件按 UTF-8 处理二进制内容只能原样保留于编辑区之外无法被有意义地编辑精确字符串匹配不支持正则str_replace是字面量匹配需要模糊修改时应借助view定位后多次精确操作历史记录是会话级的session-scoped工具不维护跨会话的文件修改历史每次编辑都是对当前文件的即时写操作无覆盖语义create对已存在路径一律拒绝防止 Agent 误覆盖关键文件目录操作受限str_replace与insert只能作用于文件对目录执行会报错提示只有view命令可用于目录。九、测试与验证行为均有用例背书fileEditor 的行为由 file-editor.test.node.ts 全面覆盖可视为使用契约的权威参考view整文件/空文件/单行文件/行范围/负 end/单行范围/目录列出/隐藏文件排除以及文件不存在、相对路径、路径穿越、范围越界等错误分支create新建、嵌套目录自动创建、空文件、已存在拒绝、相对路径拒绝、目录路径拒绝str_replace唯一替换、删除空new_str、多行替换、$模式字面保留、特殊正则字符$100.00 (USD)安全处理、CRLF 与 tab 保留、重复出现报错含多行重复时的准确行号lines [1,5]、二进制内容保留、文件首/尾替换、文件增大替换、混合缩进不破坏insert开头/中间/末尾插入、多行插入、空文件插入、越界报错其他默认 1MB 大小限制、Unicode/emoji/特殊字符内容、tab 展开以及沙箱路径下的完整流程与错误传播。这些用例既验证了正确路径的可用性也锁定了安全边界的行为——在为自己的 Agent 选用 fileEditor 时建议先运行该测试套件确认环境行为与预期一致。十、最佳实践小结结合 README 的安全警告、源码防护与测试覆盖使用 fileEditor 的推荐姿势如下默认不开放不要直接向不可信用户或不可信提示词输入暴露该工具生产环境配合沙箱在容器/虚拟机等隔离环境中运行并配置受限的Sandbox实现让工具 I/O 落在受控文件系统内让模型遵循先 view 后改提示词中引导模型先查看目标文件确认路径、行号、内容唯一性再执行str_replace或insert可显著降低误改概率利用唯一性约束自我纠错str_replace对非唯一匹配的拒绝是特性而非缺陷——它迫使模型把替换目标写得足够具体善用 1MB 限制如需调整上限可通过FileEditorOptions.maxFileSize见 types.ts自定义但应保持上限克制避免模型读取超大文件拖慢上下文。十一、延伸阅读工具实现与导出file-editor.ts、index.ts、types.ts测试契约file-editor.test.node.ts工具工厂与 Zod 校验tool-factory.tsSandbox 抽象层base.tsPython 语言对应实现file_editor.py赞分享人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务【免费下载链接】harness-sdkBuild an agent harness and control it end-to-end. Open-source SDK for production AI agents in Python TypeScript - any model, any cloud.项目地址https://gitcode.com/GitHub_Trending/sdkpython13/harness-sdk点击查看免费下载相关推荐voltagent Workspace 文件系统完全指南为 Agent 提供持久化文件层与安全读写能力voltagent Workspace 文件系统完全指南为 Agent 提供持久化文件层与安全读写能力 Workspace Filesystem 是 volt人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆Agent 工作流AI 评测MCP 服务MCP Clients语音SWE-agent文件操作智能读写与代码编辑工具链SWE agent文件操作智能读写与代码编辑工具链 概述 SWE agentSoftware Engineering Agent是一个革命性的AI辅助软件AI AgentAgent 框架代码智能体后端开发工具Serena MCP 工具箱为你的编程 Agent 提供符号级语义检索与编辑能力Serena MCP 工具箱为你的编程 Agent 提供符号级语义检索与编辑能力 导读 Serena 是一套面向编程场景的 MCPModel Context开发工具MCP 服务代码智能体上一篇Android Uiautomator2 Python Wrapper高级技巧XPath定位与元素操作全攻略下一篇RustGPT词汇表管理自定义分词与tokenization系统完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考