核心用法
headless-vault-cli 是一个通过SSH反向隧道连接本地计算机（macOS/Linux）与VPS的Markdown笔记管理工具。用户需在本地运行隧道脚本建立连接后，即可通过云端AI助手远程操作个人笔记库。
关键工作流程：
1. 本地运行 tunnel-setup.sh 建立SSH反向隧道（默认端口2222）
2. 使用 tree 浏览笔记结构，resolve 按标题查找笔记
3. read 读取笔记内容，create 新建笔记，append 追加内容
4. 路径/内容含特殊字符时必须使用 --base64 编码
显著优点
- 隐私优先：笔记始终保存在本地设备，不上传云端
- 无缝集成：AI助手可直接操作本地知识库，无需手动复制粘贴
- 原子化操作：仅支持创建和追加，避免误删或覆盖风险
- 结构化输出：所有命令返回JSON，便于程序化处理
- 自动目录创建：
create时自动创建父目录
潜在局限
- 单向写入限制：仅支持追加到文件末尾，无法编辑中间内容
- 无文件管理功能：不支持重命名、删除、移动文件或文件夹
- 本地依赖：电脑必须在线且隧道保持运行，断电即无法访问
- 平台限制：仅支持macOS/Linux本地端
- 路径复杂性：含空格的名称必须手动base64编码
适合人群
- 注重数据隐私、希望笔记完全本地化的知识管理用户
- 需要AI辅助处理本地笔记但不愿上传敏感数据的用户
- 已使用Obsidian等Markdown工具、希望扩展云端AI能力的用户
常规风险
- 隧道安全：SSH密钥泄露可能导致本地设备被访问
- 并发写入：多客户端同时追加可能导致内容交错
- 编码陷阱：忘记
--base64标志会导致含特殊字符的命令失败 - 误创建重复：
create在文件存在时失败，但需手动检查避免创建相似名称文件 - 网络暴露：本地SSH端口暴露给VPS，需确保VPS安全