№ 0225Skill
muse-fileapi local file connector
muse-fileapi is a dependency-free local HTTP service exposed via Cloudflare Tunnel that lets Muse, through a custom connector, list, read and write files in whitelisted directories with two-phase writes and an audit log.
muse-fileapi
English | 中文
让 Meta Muse 能读写你本机文件的连接器服务。
Muse 住在 Meta 云端的机器里，够不到你的电脑。这个服务在你本机跑一个小 HTTP 接口，再经 Cloudflare Tunnel 暴露出去，Muse 就能通过自定义连接器访问它：列目录、读写改删文件、执行 shell 命令。
⚠️ 用你自己的域名！
本项目不提供任何公共服务端点。https://files.your-domain.com这类地址只是占位写法——
你必须用自己的域名 + 自己的 Cloudflare Tunnel 把本机服务暴露出去。
绝不要把 token 告诉任何人，也绝不要提交到 Git（见下方安全设计）。
快速开始
- 安装 Node.js（只需要运行时，无第三方依赖）
- 复制配置：
config.example.json→config.json，把allowedRoots改成你想开放的目录 - 启动：
node server.mjs（监听127.0.0.1:8787） - 用你自己的 Cloudflare Tunnel 把
127.0.0.1:8787暴露到你自己的域名 - 把
CONNECTOR-BRIEF.md的内容喂给 Muse，走它的安全凭据流程输入 token（首次启动时自动生成，见下文"取 token"）
结构
muse-fileapi/
├─ server.mjs 服务本体（单文件，无依赖）
├─ config.json ← 你要改的就是这个：白名单在这里（不进 git，见 config.example.json）
├─ CONNECTOR-BRIEF.md 喂给 Muse 的连接器说明
└─ .muse-fileapi/ 自动生成，不要手动改（不进 git）
├─ token 访问令牌（绝不通过 API 暴露）
├─ backups/ 每次覆盖写入前的自动备份
├─ trash/ 删除的文件移到这里（可手动恢复）
└─ audit.jsonl 所有操作的审计日志
安全设计
| 机制 | 作用 |
|---|---|
只监听 127.0.0.1 |
默认本机可达，公网暴露是单独的显式步骤 |
| Bearer token | 256 位随机；存在 .muse-fileapi/token，不在 config.json 里 |
| 目录白名单 | allowedRoots 之外一律 403，含路径穿越 |
| 敏感文件黑名单 | 白名单内也拦 .env、密钥、.ssh、.git、node_modules |
| 自我防护 | 拒绝提供 config.json、token、备份、回收站、审计日志本身 |
| 两阶段变更 | prepare 只算 diff/预览不落盘，confirm 才执行；适用于写、改、删、执行命令 |
| 自动备份 | 覆盖已有文件前先存一份 |
| 删除进回收站 | delete 只是把文件移到 trash/，不是真删，可手动恢复 |
| 审计日志 | 每次读、写、删、执行、拒绝都记录 |
注意：隧道一旦启用，这个服务就是公网可达的。Token 是唯一的锁，不要分享、不要提交到 Git。/run 端点可以执行任意 shell 命令——拿到 token 就等于能在你电脑上跑命令，保管级别和密码一样。
能力（Muse 能用它做什么）
- 读：列目录、读文件（含分页）、看文件信息、按文件名找（glob）、搜内容（字面量或正则）
- 改：整文件覆盖、精确字符串替换、一次多处替换、末尾追加——覆盖/替换两阶段确认，追加直接执行
- 文件操作：复制、移动/重命名（默认防覆盖）、建目录——直接执行
- 删：两阶段确认，删进回收站
- 跑：执行 shell 命令（Windows 下是 pwsh），比如改完代码跑个
node --check校验——每次都要你点头；
长任务可用后台模式（background: true），随时查输出、随时停（连进程树一起杀）
完整端点说明见 CONNECTOR-BRIEF.md。
启动（Windows 常驻方案）
开机自启：建一个 Windows 计划任务，登录时运行 start-muse-fileapi.cmd，无需手动启动，日志追加到 .muse-fileapi\server.log。
schtasks /Run /TN muse-fileapi # 立即启动
schtasks /End /TN muse-fileapi # 停止
schtasks /Query /TN muse-fileapi /V # 查看状态
保活：watchdog.ps1 注册为计划任务（每 5 分钟跑一次），/health 不通就重启服务并弹通知。check-status.cmd 一键自检（本地/公网/隧道）。
手工前台运行（先停掉计划任务，否则端口占用）：
cd D:\YourWorkspace\muse-fileapi
