# 北航云盘本机 MCP / CLI

非官方Windows接入实验版。复用已登录的官方客户端，在**明确配置的同步目录**内查找、读取、新建和更新Markdown/TXT，并核对客户端状态。与学校及爱数无隶属或背书关系。

本项目独立实现；不包含厂商客户端、账号凭据或个人文件。不是完整远端云盘API。首个Alpha版本为0.1.0a1；MIT许可证见[LICENSE](LICENSE)。

## 当前能力

七工具：`list_directory`、`search_files`、`read_text`、`create_directory`、`write_text`、`sync_status`、`refresh_file`。没有删除或分享工具。配置逐根默认只读，覆盖要求完整原始SHA-256并保留旧版备份。默认小文本上限128KiB。

已配置目录的这些操作使用命令或MCP，无需AI操控鼠标。首次登录、验证码、加密解锁仍由用户本地处理。客户端Latest和本地/缓存一致不等于独立云端验证。

## 安装

使用Windows、Python3.12及已登录/运行的官方客户端。将代码放在你选择的工作目录；个人资料、配置、缓存和备份遵守该机保护规则。

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .
```

安装不修改客户端同步映射，不获取登录凭据。若没有`py`，使用已有Python3.12可执行文件。不要为脚本关闭系统安全策略。

## 首次配置及验收

详见[两台电脑部署与验收](docs/DEPLOYMENT.md)。配置向导要求选择已存在的同步根，以及独立工具状态目录；仅创建新的虚构测试子目录，不读取原有文档。

```powershell
.\.venv\Scripts\buaa-drive-setup.exe --storage-root 'E:\ExampleData\ToolState'
```

默认只允许虚构资料测试标记，不证明加密。真实资料必须另行配置本机保护命令并核验缓存位置；没有保护配置时程序拒绝访问。工位既有Vault规则应保持，不用测试标记替代。

每次调用需配置`BUAA_DRIVE_CONFIG_DIR`和`BUAA_DRIVE_GUARD`，向导会生成只含本机路径/保护参数的`Start-CLI.ps1`和`Start-MCP.ps1`。不要公开生成的状态目录。

```powershell
# 在向导生成的状态目录里
pwsh -NoProfile -File .\Start-CLI.ps1 doctor
pwsh -NoProfile -File .\Start-CLI.ps1 list
```

若本机没有pwsh，可用本机允许的Windows PowerShell执行脚本，或根据生成说明直接设置环境后调用Python；不要绕过执行策略。MCP客户端的服务命令指向生成启动器，设置启动超时30秒、工具超时60秒。

## 验证与发布范围

原工位版已通过74项核心测试及7工具实际调用；公开候选的测试与安装结果见[兼容范围](docs/COMPATIBILITY.md)。两机已分别完成虚构范围设备及独立Codex CLI验收，同一虚构文件往返摘要一致；不能扩展到所有目录或客户端版本。

```powershell
.\.venv\Scripts\python.exe -m pip install '.[dev]'
.\.venv\Scripts\python.exe -m pytest -q
```

测试仅虚构文件；在工位运行时将临时目录显式指定到受保护且不参与同步的位置。没有声称Linux或所有客户端版本通过。

详见[安全与边界](docs/SECURITY.md)、[实现来源](docs/PROVENANCE.md)。文件返回给云端模型时可能进入模型请求；目录约束不是对恶意本地进程的操作系统沙箱。

## 下载与验证记录

- [GitHub仓库](https://github.com/TH0RGOODMAN/buaa-drive-local-mcp)
- [Alpha下载](https://github.com/TH0RGOODMAN/buaa-drive-local-mcp/releases)
- [Windows自动测试](https://github.com/TH0RGOODMAN/buaa-drive-local-mcp/actions)

下载wheel后，在独立Python3.12环境执行 `python -m pip install <下载的.whl路径>`，再按部署说明配置本机路径与保护。也可下载源码按前文安装。初次线上测试112通过、1条件跳过，安装与构建成功；客户端现场验证仍限已记录的两台Windows机器和虚构目录。