科研笔记库一旦从几篇 Markdown 笔记扩展到主库、项目子库、模板和索引，维护成本也会跟着上来。新建项目要遵守目录结构，记录要带上身份属性，删除后还得能恢复；如果这些步骤全靠手动，很容易出现项目编号不一致、文件放错位置，或者误覆盖已有内容。

我做了 scientific-vault-cli（命令名：svault），希望把科研 Vault 中重复、容易出错的维护操作收进一个命令行工具。它面向主 Vault 和叶级项目 Vault，帮助整理库结构与笔记生命周期；它本身不调用 AI、不运行实验，也不连接外部实验仓库。

项目仓库：SuShuheng/scientific-vault-cli。

把科研 Vault 的边界落实到日常操作

这个工具的出发点是两级结构：主库负责总览、规则、模板和共享知识；每个独立研究目标对应一个项目子库。svault 会根据当前工作目录识别操作范围，让主库和子库执行各自允许的维护操作。例如，主库可以创建项目和维护共享模板，子库则围绕当前项目整理笔记、查询记录或更新项目状态。

CLI 的权限检查用于约束它自己的命令范围，不等同于操作系统级的隔离。实际使用时仍要结合 Vault 的目录权限与 Agent 规则。

常用维护工作集中在一套命令里

svault 覆盖从初始化到日常维护的几个环节：

  • 创建主库或项目库：按内置结构蓝图生成目录、模板和基础索引；支持先预览计划。
  • 维护项目和笔记：创建项目、查询笔记、按模板新增记录、更新状态，并列出当前库中的项目或指定类型笔记。
  • 保护已有内容：修改时可校验文件哈希；删除会移入库内回收区，支持恢复；文件修改会保留旧版本，满足条件时可回滚。
  • 诊断和补齐结构：doctor 只读检查问题，repair 先展示补缺计划，经哈希确认后才应用，不替换已有笔记和设置。
  • 管理 Agent 规则：生成或同步主库、项目库规则，预览差异并保留项目自己的补充规则。
  • 维护 Windows 工具版本：查询公开 Release，校验下载文件后再更新，并保留旧版以便失败时恢复。

这些操作保留了明确的预览、校验和恢复步骤，让“准备执行什么”以及“出了问题如何回退”能被看见。

Windows 用户可以直接使用随附的 exe

当前仓库提供 Windows 原生 svault.exe，安装到 Vault 的 工具 目录后即可使用，不需要在笔记库里放 Python 脚本。可以先从主库目录运行：

1
2
3
4
.\工具\svault.exe whoami
.\工具\svault.exe operations
.\工具\svault.exe project list
.\工具\svault.exe check

如果需要从源码运行，则可在安装 Python 和项目依赖的开发环境中使用仓库提供的入口。项目代码、测试和构建文件留在独立仓库，Vault 只保存部署使用的可执行文件。

当前版本与适用范围

本文依据仓库中的 README 和 1.1.0 版本说明整理。该版本新增了离线初始化、目录蓝图生成、库身份登记、只读诊断与预览式补缺等能力，也保留了已有的笔记维护、回收恢复和规则管理流程。

项目当前声明验证范围为 Windows；README 没有声称已构建 macOS 或 Linux 原生二进制。CLI 提供的是本地 Vault 管理能力，不会替代实验运行、数据管理或科研结论核验。真实项目中的证据、数据版本、配置与结果，仍需要研究者按自己的流程记录和检查。

项目资料