用前必看！iFlow Python SDK - 文件系统使用指南
概述
iFlow Python SDK 提供了安全的文件系统访问功能，允许 AI 助手在受控环境下读写本地文件。该功能基于白名单机制，确保只能访问明确授权的目录。
核心特性
- 目录白名单 - 只允许访问指定目录
- 路径安全 - 自动防止路径遍历攻击
- 大小限制 - 可配置文件大小上限
- 只读模式 - 可选的只读访问模式
- 权限控制 - 细粒度的文件操作权限
快速开始
最小配置（访问当前目录）
from iflow_sdk import IFlowClient, IFlowOptions options = IFlowOptions( file_access=True, # 必须：启用文件系统 ) async with IFlowClient(options) as client: await client.send_message("读取当前目录下的 README.md") # ... 处理响应 说明：
file_access=True是必需的，默认为False- 不指定
file_allowed_dirs时，默认只能访问 Python 进程的当前工作目录
配置参数
必需参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| file_access | bool | False | 必须设置为 True 才能启用文件系统功能 |
重要参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| file_allowed_dirs | List[str] | None | 允许访问的目录列表。None 表示只允许当前工作目录 |
| cwd | str | os.getcwd() | iFlow CLI 的工作目录。如果与当前目录不同，必须在 file_allowed_dirs 中包含 |
可选参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| file_read_only | bool | False | 是否只读模式。True 时禁止写入操作 |
| file_max_size | int | 10485760 | 文件大小限制（字节），默认 10MB |
使用场景
场景 1：访问指定目录
from pathlib import Path from iflow_sdk import IFlowClient, IFlowOptions # 指定允许访问的目录 workspace = Path("/path/to/workspace") options = IFlowOptions( file_access=True, file_allowed_dirs=[str(workspace)], # 明确指定目录 ) async with IFlowClient(options) as client: await client.send_message("列出 workspace 目录下的所有 Python 文件") 场景 2：访问多个目录
options = IFlowOptions( file_access=True, file_allowed_dirs=[ "/home/user/project", "/home/user/data", "/tmp/cache" ], ) 场景 3：只读模式（安全审查）
options = IFlowOptions( file_access=True, file_allowed_dirs=["/home/user/codebase"], file_read_only=True, # 禁止写入 ) async with IFlowClient(options) as client: await client.send_message("分析这个项目的代码结构") # AI 只能读取，无法修改文件 场景 4：自定义工作目录
import os project_dir = "/home/user/my_project" options = IFlowOptions( cwd=project_dir, # iFlow 的工作目录 file_access=True, file_allowed_dirs=[project_dir], # ⚠️ 必须包含 cwd ) ⚠️重要提示：如果cwd与当前 Python 工作目录不同，必须在file_allowed_dirs中明确包含cwd，否则会导致权限错误。
完整示例
作者：iFlow CLI 链接：https://zhuanlan.zhihu.com/p/1999494127029598127 来源：知乎 著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。 import asyncio from pathlib import Path from iflow_sdk import IFlowClient, IFlowOptions, ApprovalMode, AssistantMessage, TaskFinishMessage async def main(): # 1. 准备工作目录 workspace = Path.cwd() / "workspace" workspace.mkdir(exist_ok=True) # 2. 配置文件系统访问 options = IFlowOptions( # 必需配置 file_access=True, file_allowed_dirs=[str(workspace)], # 可选配置 file_read_only=False, file_max_size=5 * 1024 * 1024, # 5MB cwd=str(workspace), # 其他配置 approval_mode=ApprovalMode.YOLO, # 自动执行工具 ) # 3. 创建客户端并使用 async with IFlowClient(options) as client: # 发送文件操作请求 await client.send_message( f"在 {workspace} 目录下创建一个 hello.py 文件，" "内容为一个简单的 Hello World 程序" ) # 接收响应 async for message in client.receive_messages(): if isinstance(message, AssistantMessage): print(message.chunk.text,, flush=True) elif isinstance(message, TaskFinishMessage): print(f"\n完成: {message.stop_reason}") break # 验证文件 hello_file = workspace / "hello.py" if hello_file.exists(): print(f"\n✓ 文件已创建: {hello_file}") print(f"内容:\n{hello_file.read_text()}") if __name__ == "__main__": asyncio.run(main())安全最佳实践
🙆推荐做法
1、最小权限原则
2、使用绝对路径
3、生产环境使用只读模式
4、设置合理的文件大小限制
🙅避免做法
1、不要授权根目录或系统目录
2、不要忽略 cwd 和 file_allowed_dirs 的一致性
3、不要在未启用 file_access 时期望文件操作
错误处理
常见错误
1. PermissionError: Access denied
原因：尝试访问不在 file_allowed_dirs 中的文件
解决：
options = IFlowOptions( file_access=True, file_max_size=50 * 1024 * 1024 # 增加到 50MB )2. ValueError: File too large
原因：文件超过 file_max_size 限制
解决：
3. PermissionError: File system is in read-only mode
原因：在只读模式下尝试写入
解决：
配置检查清单
在使用文件系统功能前，请确认：
file_access=True已设置file_allowed_dirs包含所有需要访问的目录- 如果设置了
cwd，确保它在file_allowed_dirs中 file_max_size足够大以处理目标文件- 根据需求设置
file_read_only模式 - 使用绝对路径而非相对路径
欢迎在使用iFlow CLI python sdk 前查询本文档，如有问题欢迎在iFlow 讨论区留言～
点击直达👉心流AI交流社区
