FileSystem

FileSystem 中间件为 Agent 注入一组文件系统操作工具（ls、read_file、write_file、edit_file、glob、grep）以及可选的命令执行工具（execute），使 Agent 具备与本地或远程文件系统交互的能力。

import "github.com/cloudwego/eino/adk/middlewares/filesystem"

快速开始

import (
    "context"
    "github.com/cloudwego/eino/adk"
    "github.com/cloudwego/eino/adk/middlewares/filesystem"
)

// 1. 创建 middleware
middleware, err := filesystem.New(ctx, &filesystem.MiddlewareConfig{
    Backend: myBackend, // 实现 filesystem.Backend 接口
})

// 2. 注入 Agent
agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    // ...
    Middlewares: []adk.ChatModelAgentMiddleware{middleware},
})

构造函数

函数签名

说明

New(ctx, *MiddlewareConfig) (ChatModelAgentMiddleware, error)

MiddlewareConfig

MiddlewareConfig 是 New / NewTyped 使用的配置结构体。

核心字段

字段	类型	说明
Backend	filesystem.Backend	必填。提供文件系统操作能力，驱动 ls、read\_file、write\_file、edit\_file、glob、grep 共 6 个工具。接口定义在 github.com/cloudwego/eino/adk/filesystem 包。
Shell	filesystem.Shell	可选。提供命令执行能力，设置后注册 execute 工具。与 StreamingShell 互斥。
StreamingShell	filesystem.StreamingShell	可选。提供流式命令执行能力，设置后注册流式 execute 工具。与 Shell 互斥。
UseMultiModalRead	bool	可选，默认 false 。开启后 read_file 工具变为 EnhancedInvokableTool ，支持返回图片/PDF 等多模态内容。要求 Backend 同时实现 filesystem.MultiModalReader 接口。
CustomSystemPrompt	*string	可选。覆盖追加到 Agent Instruction 的系统提示词。若为 nil ，不追加任何系统提示词。

工具配置字段

每个工具均有对应的 *ToolConfig 字段，用于自定义工具名称、描述、替换实现或禁用：

字段	对应工具
LsToolConfig	ls
ReadFileToolConfig	read\_file
WriteFileToolConfig	write\_file
EditFileToolConfig	edit\_file
GlobToolConfig	glob
GrepToolConfig	grep

execute 工具当前不支持通过 ToolConfig 自定义，其注册仅由 Shell / StreamingShell 是否设置来控制。

ToolConfig

type ToolConfig struct {
    Name       string         // 覆盖工具名称，空串使用默认值
    Desc       *string        // 覆盖工具描述，nil 使用默认值
    CustomTool tool.BaseTool  // 自定义工具实现，设置后替代 Backend 默认实现
    Disable    bool           // 设为 true 则不注册该工具
}

优先级：Disable=true > CustomTool > Backend 默认实现。

工具名称常量

const (
    ToolNameLs        = "ls"
    ToolNameReadFile  = "read_file"
    ToolNameWriteFile = "write_file"
    ToolNameEditFile  = "edit_file"
    ToolNameGlob      = "glob"
    ToolNameGrep      = "grep"
    ToolNameExecute   = "execute"
)

注入的工具

工具	默认名称	注册条件	功能说明
ls	ls	Backend ≠ nil	列出目录下的文件和子目录
read\_file	read_file	Backend ≠ nil	读取文件内容，支持 offset/limit 分页。开启 UseMultiModalRead 后可读取图片和 PDF
write\_file	write_file	Backend ≠ nil	创建或覆盖写入文件
edit\_file	edit_file	Backend ≠ nil	精确字符串替换编辑，支持 replace_all
glob	glob	Backend ≠ nil	按 glob 模式匹配文件路径
grep	grep	Backend ≠ nil	正则搜索文件内容，支持多种输出模式和分页
execute	execute	Shell ≠ nil 或 StreamingShell ≠ nil	执行 Shell 命令

Backend 接口

Backend 定义在 github.com/cloudwego/eino/adk/filesystem 包中。middleware 包通过类型别名重导出了请求/响应类型（如 ReadRequest、FileContent 等），但 Backend 接口本身需要从 adk/filesystem 包引用。

type Backend interface {
    LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
    Read(ctx context.Context, req *ReadRequest) (*FileContent, error)
    GrepRaw(ctx context.Context, req *GrepRequest) ([]GrepMatch, error)
    GlobInfo(ctx context.Context, req *GlobInfoRequest) ([]FileInfo, error)
    Write(ctx context.Context, req *WriteRequest) error
    Edit(ctx context.Context, req *EditRequest) error
}

Shell 与 StreamingShell

type Shell interface {
    Execute(ctx context.Context, input *ExecuteRequest) (*ExecuteResponse, error)
}

type StreamingShell interface {
    ExecuteStreaming(ctx context.Context, input *ExecuteRequest) (*schema.StreamReader[*ExecuteResponse], error)
}

二者互斥，只能设置其中一个。StreamingShell 支持流式输出，适合长时间运行的命令。

MultiModalReader 扩展接口

当 UseMultiModalRead = true 时，Backend 需要额外实现 MultiModalReader 接口：

type MultiModalReader interface {
    MultiModalRead(ctx context.Context, req *MultiModalReadRequest) (*MultiFileContent, error)
}

行为说明：

read_file 工具将从 InvokableTool 升级为 EnhancedInvokableTool，通过 schema.ToolResult.Parts 返回多模态结果
默认实现支持读取图片文件（PNG、JPG 等）和 PDF 文件（支持 pages 参数指定页面范围，每次最多 20 页）
工具描述会自动追加多模态能力后缀；若通过 ReadFileToolConfig.Desc 自定义了描述，则不会追加

💡 使用 ChatModelAgentMiddleware 时，需要实现 WrapEnhancedInvokableToolCall 方法，多模态 read_file 工具才能生效。

// MultiModalReadRequest 扩展了 ReadRequest
type MultiModalReadRequest struct {
    ReadRequest
    Pages string  // PDF 页面范围，如 "1-5"、"3"、"10-20"
}

// MultiFileContent 返回结果
type MultiFileContent struct {
    *FileContent            // 纯文本结果
    Parts []FileContentPart // 多模态结果（与 FileContent 互斥，Parts 非空时忽略 FileContent）
}

type FileContentPart struct {
    Type     FileContentPartType // "image" 或 "pdf"
    MIMEType string              // 如 "image/png"、"application/pdf"
    Data     []byte              // 原始二进制数据
}

Deprecated: 旧版 Config 与大结果卸载

💡 以下内容仅适用于 NewMiddleware + Config 旧版路径。New / NewTyped 路径不包含大结果卸载功能。

旧版 Config 在 MiddlewareConfig 的基础上额外提供了「大工具结果卸载」(Large Tool Result Offloading) 机制：

字段	说明
WithoutLargeToolResultOffloading bool	设为 true 禁用卸载，默认 false （启用）
LargeToolResultOffloadingTokenLimit int	Token 阈值，默认 20000
LargeToolResultOffloadingPathGen func(ctx, *compose.ToolInput) (string, error)	卸载路径生成函数，默认 /large_tool_result/{ToolCallID}

触发条件：当工具返回结果的字符数 > tokenLimit × 4 时触发卸载。

卸载行为：将完整结果通过 Backend.Write 写入文件，并用摘要（前 10 行 + 文件路径提示）替换原始返回。Agent 可通过 read_file 分页读取完整结果。

反馈

当前页面对你有帮助吗？

请告诉我们如何改进.

最后修改 May 21, 2026: docs(eino): sync docs from feishu (2026-05-21) (#1545) (14c457e4)