FAQ¶

常见问题速查。按"症状 → 诊断 → 修法"组织。

vault check 报悬空引用¶

症状：

✗ 发现 X 个问题：
  - resource aliyun/ecs/i-xxx: account_ref 'aliyun/main' not found

诊断：被引用的账号文件不存在。要么你删了账号没一起处理资源，要么账号 slug 写错了。

修：

# 看是哪个字段指错了
vault resource show aliyun/ecs/i-xxx

# 方案 A：补上账号
vault account add aliyun/main

# 方案 B：改资源指向已有的账号
vault resource edit aliyun/ecs/i-xxx

schema 校验挂¶

症状（pre-commit 输出）：

credentials schema.......................Failed
  data/credentials/foo.json::$: 'values' is a required property

诊断：文件字段跟 schemas/<layer>.schema.json 不匹配。

修：

# 对照 schema 看缺什么
cat schemas/credential.schema.json | jq '.required'

# 看你写的文件
cat data/credentials/foo.json

# 补字段、再 commit

vault install 报 "credential not found"¶

症状：

install failed: credential 'aliyun-main' (alias 'aliyun'): not found: .../aliyun-main.json

诊断：vault.json 里引用的 credential slug 在 data/credentials/ 下不存在。

修：

# 列真实存在的
vault credential list

# 改 vault.json 里的 slug 或建凭证
vault credential add aliyun-main

vault install 报 "has no field X"¶

症状：

credential 'aliyun-main' has no field 'something' (listed in alias 'aliyun'.fields)

诊断：vault.json 声明要读某字段，但 credential 里没那字段。

修：

vault credential show aliyun-main --unmask --json | jq '.values | keys'
# 看有哪些真实字段；改 vault.json 的 fields 数组

代码 `import vault` 找不到¶

症状：ModuleNotFoundError: No module named 'vault'

诊断：消费方项目不该 import vault 模块（vault 不是 Python SDK，是 CLI）。

修：改成读 JSON 或 env：

import json
secrets = json.loads(open(".vault/secrets.json").read())

详见项目接入。

git commit 特别慢¶

症状：git commit 卡 30 秒以上。

诊断：pre-commit 第一次安装某个 hook 要下载 binary（比如 gitleaks），走网络。

修：耐心等第一次；之后缓存在 ~/.cache/pre-commit/，秒级。

如果网差，可以用 git commit --no-verify 跳过（只临时用；下次正常 commit）。

git-crypt 乱码¶

症状：别人 clone 仓库后看 data/ 里全是 GITCRYPT 头 + 乱码。

诊断：对方没 unlock。git-crypt 密钥不在仓库里，要手动导入。

修（对方机器上）：

cd vault
git-crypt unlock /path/to/backup-key   # 备份 key 的路径
# 之后 data/ 明文可读

详见安全密钥管理章节。

ruff 报错但本地能过¶

症状：本地 uv run ruff check 全绿，CI 挂。

诊断：pre-commit 和 uv 的 ruff 版本不一致。

修：改 .pre-commit-config.yaml：

- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.15.11     # ← 跟你 uv 装的版本对齐

查本地版本：uv run ruff --version

CI 说 data/ 不存在但我本地有¶

症状：CI 的 pytest integration 挂 / 某 script 说读不到 data/。

诊断：CI 看到的是加密的 data/。我们有意设计 VAULT_SKIP_INTEGRATION=1 跳过真实数据测试。

修：不用修，这是故意的。整合测试留本地跑：

uv run pytest                          # 本地跑所有测试

CF Pages 部署挂 "Project not found"¶

症状：

Error: Project not found. [code: 8000007]

诊断：CF 那边根本没建过这个项目。

修：先手动 API 创建：

TOKEN="..." && ACCOUNT="..." && curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/pages/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"agentaily-vault","production_branch":"main"}'

文档站没更新¶

症状：push 到 main 了，但 https://agentaily-vault.pages.dev/ 还是旧的。

诊断：CI 可能还在跑，或 Pages 缓存。

修：

gh run list --limit 1             # CI 状态
# 等到 completed success 后
curl -I https://agentaily-vault.pages.dev/ | grep -i cf-cache
# 没缓存的话强刷新：
curl -I "https://agentaily-vault.pages.dev/?_=$(date +%s)"
# 或浏览器 cmd+shift+R

EDITOR 怎么设¶

vault <layer> add/edit 打开的是 $EDITOR 环境变量里的编辑器。

# zsh/bash config 里
export EDITOR=code-wait    # VS Code 等关窗口才继续
# 或
export EDITOR=vim
# 或
export EDITOR='cursor -w'

不设的话 click 默认开 vi / nano。

我可以手动编辑 data/ 里的 json 吗？¶

可以，但： 1. 编完跑一次 vault check 确认自洽 2. pre-commit 会跑 schema 校验，挡不合法的 3. 推荐还是走 vault <layer> edit <slug>（打开模板、退出自动校验）

vault 能不能存音频 / 视频¶

能，但不建议。git-crypt 是 blob-level 加密，大文件会让仓库变慢。建议只放 < 10MB 的文件。大于这个的： - 放加密 OSS / 自建存储，只在 resource metadata 里记 URL + sha256 - 或者别存（不是所有事都要进 vault）

vault 被其他 agent skill 触发的时机¶

见 SKILL.md 顶部 TRIGGER 清单。核心： - 用户说"查凭证 / 密码 / api key" - 用户说"查 ECS / 机器 / OSS / 域名" - 项目接入（vault.json / vault install） - 关系校验（vault check） - 人/组织（身份证、护照、合同）

不该触发：讨论概念、操作云资源、记关系事实、记笔记决策（后两个进 knowledge-graph）。

没列到的问题¶

提 GitHub Issue 或直接问 Claude。