muse-fileapi local file connector

# muse-fileapi

[English](README.en.md) | 中文

让 Meta Muse 能读写你本机文件的连接器服务。

Muse 住在 Meta 云端的机器里，够不到你的电脑。这个服务在你本机跑一个小 HTTP 接口，再经 Cloudflare Tunnel 暴露出去，Muse 就能通过自定义连接器访问它：列目录、读写改删文件、执行 shell 命令。

> ⚠️ **用你自己的域名！**
> 本项目不提供任何公共服务端点。`https://files.your-domain.com` 这类地址只是占位写法——
> 你必须用**自己的域名 + 自己的 Cloudflare Tunnel** 把本机服务暴露出去。
> 绝不要把 token 告诉任何人，也绝不要提交到 Git（见下方安全设计）。

## 快速开始

1. 安装 [Node.js](https://nodejs.org/)（只需要运行时，无第三方依赖）
2. 复制配置：`config.example.json` → `config.json`，把 `allowedRoots` 改成你想开放的目录
3. 启动：`node server.mjs`（监听 `127.0.0.1:8787`）
4. 用你自己的 Cloudflare Tunnel 把 `127.0.0.1:8787` 暴露到**你自己的域名**
5. 把 `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`。

```powershell
schtasks /Run   /TN muse-fileapi     # 立即启动
schtasks /End   /TN muse-fileapi     # 停止
schtasks /Query /TN muse-fileapi /V  # 查看状态
```

**保活**：`watchdog.ps1` 注册为计划任务（每 5 分钟跑一次），`/health` 不通就重启服务并弹通知。`check-status.cmd` 一键自检（本地/公网/隧道）。

手工前台运行（先停掉计划任务，否则端口占用）：

```bash
cd D:\YourWorkspace\muse-fileapi