核心用法
Headless Vault CLI 是一套用于远程管理本地 Markdown 笔记的命令行工具。用户需在个人电脑（本地机器）上安装 vaultctl 并建立反向 SSH 隧道，使 VPS 上的 AI 助手能够安全访问笔记仓库。
典型工作流程：
1. 通过 tree 查看笔记目录结构
2. 使用 resolve 按标题或路径定位笔记
3. 使用 read 读取笔记内容
4. 使用 create 新建笔记（自动创建父目录）
5. 使用 append 向现有笔记追加内容
所有路径和内容参数必须通过 Base64 编码传递，防止 shell 注入攻击。
显著优点
- 深度安全隔离：采用 SSH 强制命令（forced-command）机制，VPS 端仅可执行
vaultctl，无法获取交互式 shell 或运行任意命令 - 路径沙箱保护：
vaultctl严格验证所有路径位于VAULT_ROOT内，拒绝目录遍历攻击 - 非破坏性设计：仅支持创建新文件和追加内容，无删除、重命名、覆盖等危险操作
- 零凭证存储：复用 VPS 现有 SSH 密钥对，不额外存储用户凭证
- 透明可审计：所有命令通过标准 SSH 通道执行，日志可追溯
潜在局限
- 配置门槛较高：需用户自行完成本地机器的安装、SSH 密钥配置、隧道建立等一次性设置
- 功能受限：不支持文件编辑（仅追加）、删除、移动、重命名等常见文件操作
- 网络依赖：本地机器必须在线并保持隧道活跃
- 平台限制：当前支持 macOS 和 Linux，Windows 需额外配置
适合人群
- 重视数据主权、不愿将笔记上传至云端的技术用户
- 已具备 SSH 和命令行基础知识的开发者或高级用户
- 需要在远程 VPS 上运行 AI 助手同时保持笔记本地化的 Obsidian/Logseq 用户
常规风险
| 风险类型 | 说明 |
|---------|------|
| 隧道安全 | 若 SSH 密钥泄露，攻击者可访问 vaultctl，但受限于 forced-command 无法执行系统命令 |
| 路径逃逸 | `vaultctl` 已内置路径验证，但仍需确保 `VAULT_ROOT` 配置正确 |
| 数据完整性 | 仅支持追加模式，意外操作可通过本地 Git 等版本控制回滚 |
| 可用性风险 | 本地机器离线或隧道中断时无法访问笔记 |