Web Agent Local File Bridge 是一个零依赖、单脚本、开箱即用的本地HTTP轻量服务器，为网页端AI Agent（DeepSeek/通义千问/豆包/ChatGPT等）提供本地文件系统的安全可控访问能力。
- 零依赖: 仅使用Python标准库，无需安装任何第三方包
- 安全可控: 白名单目录机制 + 全场景路径穿越防护
- 编码兼容: 自动识别UTF-8/GBK/GB2312等主流编码
- 跨域支持: 内置CORS配置，适配所有浏览器环境
- 自动备份: 文件写入前自动备份，防止误操作
- 请求限流: 防止高频请求攻击
- Python 3.8 或更高版本
- Windows 10/11 (优先适配)
-
下载程序
git clone <repository-url> cd webToLocal
-
配置白名单目录
编辑
config.ini文件，设置允许访问的目录：[security] white_list_dirs = D:\code;C:\Users\YourName\Desktop\dev
-
启动服务
python web_agent_file_bridge.py
或指定配置文件：
python web_agent_file_bridge.py --config config.ini
-
访问服务
服务启动后会显示可用的访问地址，例如：
============================================================ Web Agent Local File Bridge 服务启动成功! ============================================================ 监听地址: 0.0.0.0:8080 可用访问地址: - http://localhost:8080 - http://127.0.0.1:8080 - http://192.168.10.162:8080
默认端口为 8080。如果端口被占用，服务会自动切换到 8081-8090 范围内的可用端口。
在 config.ini 中修改端口：
[server]
port = 8080
host = 0.0.0.0请求
GET /read?path=<文件路径>&encoding=<编码>参数
path(必需): 文件路径，支持相对/绝对路径encoding(可选): 强制指定编码，不填则自动识别
成功响应
{
"code": 0,
"msg": "success",
"data": {
"path": "test.py",
"abs_path": "D:\\code\\test.py",
"content": "print('hello world')",
"encoding": "utf-8",
"file_size": 21
},
"request_id": "uuid-xxxx-xxxx"
}请求
POST /write
Content-Type: application/json
{
"path": "test.py",
"content": "print('hello world')",
"encoding": "utf-8",
"backup": true
}参数
path(必需): 文件路径content(必需): 文件内容encoding(可选): 编码格式，默认utf-8backup(可选): 是否备份，默认true
成功响应
{
"code": 0,
"msg": "文件写入成功",
"data": {
"path": "test.py",
"abs_path": "D:\\code\\test.py",
"write_size": 21,
"encoding": "utf-8",
"backup_path": "D:\WORK\webToLocal\webToLocal\web-agent-backup\\test.py.bak.1"
},
"request_id": "uuid-xxxx-xxxx"
}请求
POST /mkdir
Content-Type: application/json
{
"path": "new-project/src"
}参数
path(必需): 目录路径
成功响应
{
"code": 0,
"msg": "目录创建成功",
"data": {
"path": "new-project/src",
"abs_path": "D:\\code\\new-project\\src",
"created": true
},
"request_id": "uuid-xxxx-xxxx"
}请求
GET /health成功响应
{
"code": 0,
"msg": "服务正常",
"data": {"status": "ok"},
"request_id": "uuid-xxxx-xxxx"
}在 DeepSeek 聊天中，告诉 Agent：
我有一个本地文件服务运行在 http://localhost:8080
请帮我读取 D:\code\test.py 文件的内容。
Agent 会自动生成 HTTP 请求来读取文件。
本地文件服务地址：http://192.168.10.162:8080
请读取 D:\project\config.yaml 文件并解释其配置项。
我可以访问本地文件服务 http://localhost:8080
请读取 /read?path=D:\code\main.py
只允许访问配置文件中指定的目录，拒绝所有其他路径访问。
自动拦截所有路径穿越攻击：
../相对路径引用~用户目录- UNC 网络路径
\\server\share - Windows 设备路径
\\.\、\\?\
强制要求 X-Requested-With: XMLHttpRequest 请求头。
单IP每分钟最多 600 次请求，超出返回 429 状态码。
完整配置文件 config.ini：
[server]
# 服务监听端口
port = 8080
# 监听地址，0.0.0.0 表示全网卡监听
host = 0.0.0.0
[security]
# 白名单目录，多个用分号分隔
white_list_dirs = D:\code;C:\Users\YourName\Desktop\dev
# 单IP每分钟最大请求数
rate_limit = 600
# 是否启用文件自动备份
enable_backup = true
# 备份保留数量
backup_keep_count = 3
[security.cors]
# 允许的HTTP方法
allowed_methods = GET, POST, OPTIONS
# 允许的请求头
allowed_headers = Content-Type, X-Requested-With
# 预检请求缓存时间（秒）
max_age = 86400
[log]
# 是否启用控制台日志
enable_console_log = true
# 是否写入日志文件
enable_file_log = false
# 日志文件目录
log_dir = ./logs
# 日志保留天数
log_keep_days = 7问题: 运行 python web_agent_file_bridge.py 后服务没有启动
解决方案:
- 检查 Python 版本是否为 3.8+
- 检查端口 8080 是否被其他程序占用
- 检查防火墙是否阻止了程序运行
问题: 显示"端口8080已被占用"
解决方案: 服务会自动切换到 8081-8090 范围内的可用端口。或者手动修改 config.ini 中的端口号。
问题: 所有请求都返回 403 错误
解决方案:
- 检查请求是否包含
X-Requested-With: XMLHttpRequest请求头 - 检查访问的路径是否在白名单目录内
- 检查路径格式是否正确（避免使用
../等）
问题: 读取的文件内容显示为乱码
解决方案:
- 服务会自动检测文件编码，通常不需要手动指定
- 如需强制指定编码，在请求中添加
encoding参数 - 确保文件确实使用的是文本编码（非二进制文件）
问题: 在浏览器中 Agent 报错无法连接
解决方案:
- 确认服务已启动并显示正确的访问地址
- 检查浏览器控制台的错误信息
- 确认使用的是正确的内网 IP 地址（如 192.168.x.x）
- 检查防火墙设置，确保端口已放行
文件写入前会自动备份到系统临时目录：
- Windows:
C:\Users\YourName\AppData\Local\Temp\web-agent-backup\ - Linux/Mac:
/tmp/web-agent-backup/
每个文件保留最近 3 次备份，文件命名格式：filename.ext.bak.1
# 安装测试依赖
pip install -r requirements.txt
# 运行所有测试
python tests/test_file_bridge.py- 安全测试: 路径穿越、UNC路径、白名单、CSRF、限流
- 功能测试: 文件读写、目录创建、编码兼容、备份机制
MIT License
欢迎提交 Issue 和 Pull Request！
- 初始版本发布
- 支持文件读取、写入、目录创建
- 完整的安全防护机制
- 多编码自动识别
- 自动备份功能