201 lines
5.4 KiB
Markdown
201 lines
5.4 KiB
Markdown
# Skills Vault
|
||
|
||
**_[English](./README.md)_**
|
||
|
||
[](https://www.npmjs.com/package/skvlt)
|
||
[](https://www.npmjs.com/package/skvlt)
|
||
[](https://github.com/xixu-me/skills-vault/actions/workflows/ci.yml)
|
||
[](https://bun.sh/)
|
||
[](./LICENSE)
|
||
|
||
Skills Vault 是一个用于备份和恢复 [Agent Skills](https://agentskills.io) 的 CLI。
|
||
|
||
它主要服务于这样一个常见流程：
|
||
|
||
1. 把当前机器上已安装的 skills 快照出来
|
||
2. 提交或移动这个 manifest
|
||
3. 在另一台机器上恢复同一组 skill source
|
||
|
||
> [!IMPORTANT]
|
||
> 仅支持 Bun 运行时。Skills Vault 设计上就是通过 [Bun](https://bun.com) 安装和运行的。
|
||
|
||
## 为什么需要 Skills Vault
|
||
|
||
Skills Vault 的存在，是为了补上 [vercel-labs/skills#729](https://github.com/vercel-labs/skills/issues/729) 里提到的缺口：缺少一种声明式 manifest，来支持可移植、可复现的 skills 配置。
|
||
|
||
- 把已安装的 skills 备份为确定性的 `skvlt.yaml`
|
||
- 按 source、按 agent，或者一次性从 manifest 恢复
|
||
- 通过 `--dry-run` 在真正改动前先预览
|
||
- 用 `doctor` 快速检查本地环境
|
||
- 为 `bash`、`zsh` 和 `powershell` 生成补全脚本
|
||
|
||
## 快速开始
|
||
|
||
备份当前已安装的 skills：
|
||
|
||
```bash
|
||
bunx skvlt backup
|
||
```
|
||
|
||
预览一次 restore 将会执行什么：
|
||
|
||
```bash
|
||
bunx skvlt restore --dry-run
|
||
```
|
||
|
||
恢复 manifest 中记录的全部内容：
|
||
|
||
```bash
|
||
bunx skvlt restore --all
|
||
```
|
||
|
||
如果你想直接使用一个精选好的 manifest，可以查看 [xixu-me/skvlt](https://github.com/xixu-me/skvlt)，这是一个持续维护的 `skvlt.yaml` 集合。
|
||
|
||
默认 manifest 路径是 `./skvlt.yaml`。一个典型文件如下：
|
||
|
||
```yaml
|
||
total_sources: 2
|
||
total_skills: 3
|
||
scope: "global"
|
||
|
||
sources:
|
||
"alpha/source":
|
||
count: 1
|
||
skills:
|
||
- "beta"
|
||
|
||
"beta/source":
|
||
count: 2
|
||
skills:
|
||
- "alpha"
|
||
- "zulu"
|
||
```
|
||
|
||
## 命令
|
||
|
||
### `backup`
|
||
|
||
把已安装的 skills 快照到 `skvlt.yaml`。
|
||
|
||
```bash
|
||
bunx skvlt backup
|
||
bunx skvlt backup --dry-run
|
||
bunx skvlt backup --output ./skvlt.yaml
|
||
bunx skvlt backup --project-scope --lock-file ./skills-lock.json
|
||
```
|
||
|
||
`backup` 会先读取已安装的 skill 名称，再结合 lock file 元数据，最终按 source 分组写出 manifest。
|
||
|
||
> [!NOTE]
|
||
> 全局备份默认读取 `~/.agents/.skill-lock.json`。项目级备份目前仍然需要显式传入 `--lock-file`。
|
||
|
||
### `restore`
|
||
|
||
从 manifest 安装 skills。
|
||
|
||
```bash
|
||
bunx skvlt restore --all
|
||
bunx skvlt restore --only-source xixu-me/skills
|
||
bunx skvlt restore --project-scope
|
||
bunx skvlt restore --dry-run
|
||
```
|
||
|
||
默认情况下，`restore` 会遵循 manifest 中记录的 scope。如果希望即使 manifest 来自全局状态，也强制恢复到项目作用域，可以使用 `--project-scope`。
|
||
|
||
`--dry-run` 会打印推导出的 `bunx skills add ...` 命令，但不会真正执行。实际安装时会采用 lock-safe 模式串行执行，以避免全局 lock file 竞争。
|
||
|
||
如果你想从一个精选 manifest 起步，也可以直接使用 [xixu-me/skvlt](https://github.com/xixu-me/skvlt) 中维护的 `skvlt.yaml`。
|
||
|
||
### `doctor`
|
||
|
||
检查本地 Skills Vault 环境和全局 skill 状态。
|
||
|
||
```bash
|
||
bunx skvlt doctor
|
||
bunx skvlt doctor --manifest ./skvlt.yaml
|
||
```
|
||
|
||
`doctor` 会检查：
|
||
|
||
- Bun 运行时
|
||
- `bunx skills --help`
|
||
- manifest 是否存在
|
||
- 全局 lock file 和 skills 目录是否存在
|
||
- lock file 中追踪的技能与实际安装状态是否一致
|
||
|
||
### `completion`
|
||
|
||
输出 shell 补全脚本。
|
||
|
||
```bash
|
||
bunx skvlt completion bash
|
||
bunx skvlt completion zsh
|
||
bunx skvlt completion powershell
|
||
```
|
||
|
||
## JSON 输出
|
||
|
||
所有顶层命令都支持 `--json` 结构化输出：
|
||
|
||
```bash
|
||
bunx skvlt --json doctor
|
||
bunx skvlt --json backup --dry-run
|
||
```
|
||
|
||
成功时会返回 `ok`、`command` 和 `data`。失败时会返回 `ok`、`command`，以及稳定的 `error.code` 和错误消息。
|
||
|
||
## 本地开发
|
||
|
||
安装依赖：
|
||
|
||
```bash
|
||
bun install --frozen-lockfile
|
||
```
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
bun run ./src/cli.ts --help
|
||
bun run ./src/cli.ts doctor
|
||
bun run backup
|
||
bun run restore
|
||
bun run test
|
||
bun run check
|
||
```
|
||
|
||
`bun run check` 是主要的发布前校验入口。它会运行格式检查、完整的 Bun 测试，以及 `npm pack --dry-run --json`。
|
||
|
||
如果你修改了 workflow 文件，也请额外运行：
|
||
|
||
```bash
|
||
bunx prettier --check ".github/**/*.yml"
|
||
```
|
||
|
||
## 打包与发布说明
|
||
|
||
npm 包会把 `src/cli.ts` 作为 `skvlt` 可执行入口，并且有意只将 `src` 目录作为运行时载荷发布。
|
||
|
||
发布前，可以先在本地检查 tarball 内容：
|
||
|
||
```bash
|
||
npm pack --dry-run --json
|
||
```
|
||
|
||
Release workflow 使用 trusted publishing。实际发布步骤为：
|
||
|
||
```bash
|
||
npm publish --access public
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
- 如果 restore 报告全局状态不一致，请检查 `~/.agents/.skill-lock.json` 和 `~/.agents/skills`
|
||
- 如果环境检查失败，先运行 `bunx skvlt doctor`
|
||
- 如果打包检查失败，运行 `bun run check`，并检查 `npm pack --dry-run --json` 的输出
|
||
|
||
关于贡献、支持和安全策略，请参阅 [`CONTRIBUTING.md`](./CONTRIBUTING.md)、[`SUPPORT.md`](./SUPPORT.md) 和 [`SECURITY.md`](./SECURITY.md)。
|
||
|
||
## 许可证
|
||
|
||
基于 MIT 许可证发布。详见 [`LICENSE`](./LICENSE)。
|