核心用法
headless-vault-cli 是一个远程笔记访问工具，允许VPS上的AI助手通过反向SSH隧道连接用户的个人电脑，读取和管理本地Markdown笔记。核心工作流程：
1. 前置配置：用户需在本地机器安装vaultctl、配置SSH强制命令授权、建立反向隧道（本地→VPS:2222）
2. 命令执行：所有操作通过ssh -p 2222 user@localhost vaultctl <command>完成
3. 强制base64编码：所有路径和内容参数必须base64编码（--base64标志），防止shell注入
支持的7个核心命令：
tree：浏览目录结构resolve：通过路径或标题查找笔记info/read：获取元数据/读取内容create/append：创建新文件或追加到现有文件（不支持删除、覆盖、编辑部分内容）set-root：设置vault根目录
显著优点
| 维度 | 优势 |
|------|------|
| **安全架构** | 强制命令限制（forced-command）确保VPS仅能执行`vaultctl`；SSH隧道隔离，无交互shell权限 |
| **操作约束** | 非破坏性设计——仅创建/追加，无删除、覆盖、重命名；路径遍历防护（`..`、外部symlink拦截） |
| **输入安全** | 强制base64编码杜绝shell注入；路径必须在`VAULT_ROOT`沙箱内 |
| **凭证管理** | 复用VPS现有SSH密钥，不存储额外凭据 |
潜在缺点与局限
- 功能受限：无法编辑文件中间内容、删除笔记、移动/重命名文件、创建空文件夹
- 可用性依赖：本地机器必须在线且隧道持续运行
- 配置门槛：需用户完成多步骤本地配置（SSH授权、隧道维护），技术门槛较高
- IPv4强制：需
-4标志避免IPv6超时，配置细节敏感 - 错误反馈：base64编码增加调试复杂度，路径错误排查较困难
适合人群
- Obsidian/Logseq等本地优先笔记用户，希望远程AI助手能安全访问笔记
- 安全意识强的技术用户，能接受功能受限换取高安全性
- 需要自动化笔记工作流（如每日摘要、来源整理）的开发者
常规风险
| 风险类型 | 说明 | 缓解措施 |
|----------|------|----------|
| 隧道中断 | 本地机器离线或隧道崩溃导致服务不可用 | 用户需维护隧道稳定性 |
| 误操作append | 向错误文件追加内容无法撤销 | 操作前强制`tree`检查，create失败保护 |
| 配置错误 | `authorized_keys`设置不当可能扩大权限 | 严格遵循forced-command模板，定期审计 |
| base64编码失误 | 手动编码错误导致路径解析失败 | 使用脚本自动化编码，避免手动输入 |
安全等级评估
- 架构设计：强制命令+沙箱路径+非破坏性操作，防御深度充分
- 实现依赖：用户侧配置质量直接影响安全边界
- 威胁模型：假设VPS被入侵，攻击者仍受限于
vaultctl白名单，但需防范本地配置降级
综合评估：适合对安全性有明确要求、能接受功能受限的技术用户，不建议非技术用户自行配置。