用 Muse File Bridge 只读访问 Windows 指定文件夹

这篇指南聚焦“Muse Windows 本地文件”。下面把问题拆成容易跟做和复查的步骤。

01｜先弄清这座文件桥会开放什么

Muse File Bridge 是 TTNAN 发布的社区项目，不是 Meta 官方 Windows 客户端或官方连接器。它在 Windows 本机启动一个 Python HTTP 服务，只监听 127.0.0.1:18790，然后由 cloudflared 把服务接到 Cloudflare Tunnel。访问者仍要带 Bearer token，服务端再按你在配置里选的文件夹名称和相对路径处理请求。

这条路能让 Muse 读取真实本地文件，但文件内容会经网络请求交给远端 Muse 处理，不能当成只在本机运行。10 月 1 日的一条公开帖子提到了这个项目，没有展示连接或读写的实际结果。先挑一个新建的空文件夹，别选整个用户目录、桌面、下载文件夹或含有身份证件、客户资料、密码文件的目录。项目仓库写明默认只读和接口边界；本文依据 2026 年 10 月 2 日可见的 main 提交整理，没有在你的 Windows 或 Muse 账号上实测。

02｜先核对项目版本和安装脚本

本次检查的公开仓库是 TTNAN/muse-file-bridge，MIT 许可证，当前读取的 main 提交为 0646361a8359f5ff2d3c372b4c5dc5005d6d3542，变更记录写到 1.0.1。仓库包含安装脚本、Python 服务端、命令行客户端和卸载脚本。

项目文档要求 Windows 10 或 11 和 Python 3.9 以上；安装脚本会尝试通过 winget 安装 Python 3.12 与 cloudflared，再把服务端放入 %USERPROFILE%\.muse-bridge。先从仓库下载 ZIP，打开 install.ps1、server/muse-file-api.py 和 uninstall.ps1 看它们会改哪些路径，再运行脚本。命令里的 ExecutionPolicy Bypass 只应在你确认来源和脚本内容后使用。

03｜首次安装只给一个空目录和读取权限

在解压后、能看见 install.ps1 的文件夹里打开 PowerShell。首次运行时，目录问题直接回车会用 Documents 下的 MuseBridge；更稳妥的做法是先确认这个位置里只有准备让 Muse 查看的一小批非敏感文件。脚本询问是否允许写入时输入 n，这样 read_only 会保持 true。如果电脑上已经有旧配置，安装脚本会跳过默认值，先检查 %USERPROFILE%\.muse-bridge\config.json 里每个 root 指向哪里。

运行命令如下。powershell -ExecutionPolicy Bypass -File .\install.ps1。它会创建 MuseFileBridge API 和 MuseFileBridge Tunnel 两个登录启动计划任务，所以关掉安装窗口并不会自动停止服务。首次试用可选临时隧道，但不要用来开放敏感文件；长期命名隧道需要你自己的 Cloudflare 域名和登录授权，安装脚本不会替你创建 Access 登录策略。

原创五步流程从检查源码、选择空白白名单目录、启用只读、验证连接到撤销访问 — 原创步骤图，强调先只读验证，再决定是否开放写入。

04｜把隧道地址交给 Muse，令牌留在凭据输入框

安装结束后，脚本会显示临时 trycloudflare.com 地址，或者你绑定的命名隧道域名。Cloudflare 官方把 Quick Tunnel 定位为测试和开发用途，提醒任何拿到 URL 的人都能访问映射到本机的服务入口，停掉 cloudflared 后地址就失效；它没有在线时间保证。File Bridge 仍用自己的 Bearer token 验证 API 请求，但公网地址本身不应当被理解成访问控制。

仓库里的 CONNECTOR-BRIEF.md 是作者为 Muse 准备的对接说明，里面列了 /api/health、/api/list 和 /api/read 等接口。Meta 帮助页说可以直接请 Muse 创建自定义连接器，由 Muse 引导完成；API 信息可能需要你提供，凭据会保存在 Muse 的 Secure Credentials Store。Meta 也提醒，官方不会审核自定义连接器及其数据用法。先确认当前客户端确实提供这套流程，再把 brief 和临时或命名 HTTPS 地址交给 Muse。Bearer token 只输入专用凭据入口，不要粘贴进普通聊天；如果没有安全凭据输入、权限说明不清楚，或 Muse 要求你在对话里发 token，就暂停。

05｜用一份无隐私的样例核对实际结果

在白名单里放一个你手工创建的 bridge-check.txt，写入不含个人资料的一行测试文本。先在本机 PowerShell 用下面的请求检查服务状态，它从 token 文件读入令牌，不会把令牌值写进命令文本。$t = (Get-Content (Join-Path $env:USERPROFILE '.muse-bridge\token') -Raw).Trim()，接着运行 Invoke-RestMethod -Headers @{Authorization = ('Bearer ' + $t)} http://127.0.0.1:18790/api/health。返回里应能看到 ok、允许的 root 名和 read_only 状态。

再按 README 的方法打开公网域名根路径。返回 401 表示隧道能到本机服务，只是浏览器没有 Bearer token。之后在 Muse 里先要求列出唯一的测试 root，再要求读取 bridge-check.txt，对照原文件确认文字完全一致。连接器 brief 说所有 API 请求都要鉴权，/api/list 单次最多返回 5000 项，/api/read 上限是 2 MB。日志会记录接口、root、相对路径和响应码，所以文件名也不要用来存敏感信息。

06｜看懂白名单、错误码和本机痕迹

服务端从 config.json 读取 roots 和 read_only。请求必须带 Authorization: Bearer，root 只能是白名单中的名称，path 必须相对该目录；源码会拒绝绝对路径和解析后跑到白名单外的路径。空目录再加只读模式能把试用范围收紧。不要为了省事把 C:\Users\你的名字 或整个磁盘加入 roots，因为那会把里面大量文件纳入可读范围。

连接时先处理最常见的返回值。401 通常是令牌没有填对，403 在只读模式下是写入被拒绝，404 表示路径或目录不存在，413 代表单次读取或写入超过项目限制，429 是速率限制。服务端的 audit.log 会保存路径和状态码，server.log 也会记录请求行。它们有助于查谁读过什么路径，但也意味着日志本身要留在本机受控目录。

07｜确实需要写文件时，把可写范围再缩小

项目的 read_only=true 会让 /api/write 和 /api/mkdir 返回 403。作者文档建议确认只读行为后再开启写入。你要先备份文件，再给白名单改成一个单独的空工作目录；在 Windows 记事本里把 %USERPROFILE%\.muse-bridge\config.json 的 read_only 改成 false，随后到任务计划程序重启 MuseFileBridge API。项目没有按 root 分开设置读写权限，关闭只读后，所有配置好的 roots 都能写。

启用后先做一个新文件的写入练习，不要对原始文件发覆盖指令。源码会自动建立缺失的父目录，写文件采用临时文件再替换目标的方式；单次写入上限 10 MB。接口提供 write 和 mkdir，没有删除接口，不过 write 仍可能覆盖同名文件。只有当前 Muse 连接器确实显示写入工具时才试；如果看不到，就不要假设权限已经开通。

08｜结束试用并撤销访问

短期试用结束时，在解压目录运行 powershell -ExecutionPolicy Bypass -File .\uninstall.ps1。脚本会停止并移除两个计划任务，让本机 API 和隧道停止；它会再询问要不要删除 .muse-bridge 中的配置、token 和日志。白名单文件夹本身不会被卸载脚本删除。你还应在 Muse 里断开该自定义连接器并移除已保存的凭据。

如果曾把令牌发到聊天或怀疑令牌泄露，在隧道还通时进入仓库文件夹，先用客户端轮换。命令通过环境变量读本地 token，不要把真实 token 加到命令参数里。$env:MUSE_BRIDGE_URL = 'https://你的隧道域名'，$env:MUSE_BRIDGE_TOKEN = (Get-Content (Join-Path $env:USERPROFILE '.muse-bridge\token') -Raw).Trim()，运行 python .\client\pcfile.py rotate-token，接着运行 Remove-Item Env:MUSE_BRIDGE_URL,Env:MUSE_BRIDGE_TOKEN，并在凭据入口删除旧项。轮换会立即让旧 token 失效，新 token 只写回本机文件。命名隧道还会留在 Cloudflare 账号里；确认不再需要后按官方文档删除 tunnel。

参考来源

以下资料用于核对本文中的产品信息。Musevip 为独立中文指南，与 Meta 无隶属关系。

本文最后核验于 2026.10.02。产品页面可能更新。