headless-vault-cli

Headless Vault CLI 是一款通过 SSH 隧道实现 VPS 与本地计算机笔记库安全连接的工具技能。它允许用户在远程服务器上通过命令行界面管理位于个人电脑（macOS 或 Linux）上的 Markdown 笔记文件，解决了远程办公场景下无法直接访问本地知识库的难题。

核心用法围绕 vaultctl 命令行工具展开，通过预建立的反向 SSH 隧道（默认端口 2222）执行受限的文件操作。支持的功能包括浏览目录结构（tree）、查询文件元数据（info）、读取笔记内容（read）、创建新文件（create）以及向现有文件追加内容（append）。所有命令均通过 SSH 加密传输，支持 Base64 编码处理特殊字符路径，确保命令注入防护。

显著优点体现在其"最小权限"安全设计理念。与完整的文件管理系统不同，该技能明确禁用了删除（delete）、重命名（rename）、移动（move）和原地编辑（edit）等高危操作，仅允许追加式写入，极大降低了误操作或恶意操作导致数据丢失的风险。数据隐私方面表现优异，所有通信均通过用户自行控制的 SSH 隧道直连本地机器，无第三方服务器中转，无静默数据收集行为。

潜在缺点主要来自功能局限性和部署复杂度。功能上仅支持 Markdown 文件的简单读写，无法执行复杂的文件管理任务；不支持富文本或二进制文件处理；追加式编辑无法满足需要修改文件中间内容的需求。部署方面要求用户具备一定的系统管理能力，需要在本地计算机配置并持续运行 vaultctl 服务和 SSH 守护进程，且需手动维护隧道连接。此外，作为个人开发者项目（T3 来源），缺乏企业级的长期维护保障。

适合的目标群体主要包括：需要在 VPS 上处理本地笔记的远程开发者、追求数据隐私自托管的极客用户、以及希望通过自动化脚本管理知识库的高级用户。特别适用于"在云端 AI 助手协助下调取本地资料进行创作"的混合工作流场景。

使用风险主要集中在 SSH 密钥管理和服务端完整性上。用户需妥善保管 SSH 私钥，避免未授权访问；由于文件操作实际在远程端执行，需确保 vaultctl 服务端代码未被篡改；网络中断会导致服务不可用；此外，虽然技能本身无漏洞，但错误的 SSH 配置（如过于宽松的 IP 白名单）可能引入安全隐患。建议配合防火墙规则和定期备份使用。

Headless Vault CLI 评估报告

核心用法

Headless Vault CLI 是一款通过反向 SSH 隧道实现远程访问本地 Markdown 笔记库的命令行工具。它部署在 VPS 上，通过连接到用户个人电脑（macOS/Linux）上运行的 vaultctl 服务，实现跨设备的笔记读写操作。

支持的六类核心命令：

• tree: 浏览笔记库目录结构，支持深度限制和全文件列表
• resolve: 通过标题或路径查找笔记，支持 base64 编码处理特殊字符
• info: 获取文件元数据（行数、字节数、SHA256、修改时间）
• read: 读取笔记完整内容，返回 JSON 格式
• create: 创建新笔记（失败保护机制，文件已存在时拒绝）
• append: 向现有笔记追加内容

所有命令通过标准化 SSH 连接执行，强制 IPv4 以避免超时，并内置合理的连接超时（10秒）和主机密钥检查策略。

显著优点

1. 架构安全：纯 SSH 隧道通信，无第三方 API 依赖，数据全程加密不离开用户控制的基础设施
2. 功能边界清晰：仅支持读、创建、追加操作，明确禁止重命名、删除、编辑、移动等高风险操作，大幅降低误操作和数据丢失风险
3. 零依赖攻击面：无 npm/pip 等第三方包依赖，彻底规避供应链攻击
4. 开发者友好：支持 base64 编码参数，优雅处理带空格的文件路径和特殊字符；JSON 输出便于脚本集成
5. 隐私合规：遵循 GDPR 数据最小化原则，不收集敏感数据，环境变量读取范围严格限定于功能必需的 SSH 配置

潜在局限

1. 功能受限：不支持文件重命名、删除、移动，也不支持行级编辑（仅追加），复杂笔记管理需配合 Obsidian 等 GUI 工具
2. 实时性依赖：本地机器必须保持在线且隧道运行，无法像云同步方案那样随时访问历史版本
3. T3 来源可信度：由个人开发者维护，虽经代码审计无恶意模式，但长期维护承诺和社区治理弱于组织级项目
4. 错误处理初级：SSH 连接失败时的排查指引不足，JSON 错误信息对终端用户不够友好
5. 无许可证声明：仓库缺少明确的 LICENSE 文件，知识产权状态模糊

适合人群

• 已有 VPS 和 SSH 基础，希望搭建私有笔记同步管道的技术用户
• Obsidian/Logseq 用户，需要远程批量写入或自动化处理笔记内容
• 对数据主权敏感，拒绝第三方云服务的隐私优先用户
• 开发自动化工作流（如每日摘要生成、RSS 归档）的脚本编写者

常规风险

• SSH 密钥泄露风险：若 VPS 被入侵，攻击者可利用配置的环境变量尝试连接本地隧道，需确保 ~/.ssh/authorized_keys 最小化授权
• 路径遍历风险：虽 Skill 层面无恶意代码，但若 vaultctl 服务端验证不足，理论上存在越权访问 vault 根目录外文件的可能
• 隧道稳定性：网络波动或本地机器休眠会导致操作失败，不适合高可用性场景
• 版本冲突：无内置冲突解决机制，多设备同时写入可能导致内容覆盖（append 模式可缓解但非根治）