AI 客户端 ──MCP(stdio/HTTP+Bearer)──> 能力注册表 ──> 策略 ──> 审批 ──> 注入 ──> 脱敏 ──> 哈希链审计
                                        ▲                                      │
                                    capabilities/*.yaml（加一行=多一个工具）     └──> 脱敏后的结构化结果

# 1) 安装（幂等：重复执行不覆盖数据）
./install.sh                        # 数据目录默认 ~/.credvault
export CREDVAULT_HOME=~/.credvault

# 2) 录一条凭据（值不回显；kind 决定必填字段与形态校验）
credvault cred set ZABBIX_TOKEN --kind api_token --value-stdin < /dev/stdin

# 3) 签一个 AI 令牌（明文只显示一次）
credvault token add workbuddy-local --ttl-days 90

# 4) 接进 MCP 客户端
#    {"mcpServers":{"credvault":{"command":"credvault","args":["mcp"],
#      "env":{"CREDVAULT_TOKEN":"cbk_..."}}}}

# 5) 起 Web（审批/审计/令牌三视图）
credvault user add admin
credvault serve --mode web          # http://127.0.0.1:8443

credvault doctor                     # 8 项探针：策略/能力/凭据/密文/KEK/审计链/开关/到期
credvault policy-check               # 逐条列出授权，防「以为放开了其实没有」
credvault invoke zabbix_host_list --agent workbuddy-local --explain   # 干跑，不发起真实调用
credvault audit verify               # 哈希链完整性

{"mcpServers":{"credvault":{"command":"credvault","args":["mcp"],
  "env":{"CREDVAULT_TOKEN":"cbk_..."}}}}

credvault token add ci-probe --ttl-days 30 --scope api      # 特意签发 api 专用令牌

export CV=http://127.0.0.1:8443/api/v1
export T="Authorization: Bearer cbk_..."

curl -H "$T" $CV/whoami                       # 我是谁、能调什么、还剩多少额度
curl -H "$T" $CV/capabilities                 # 能力清单（含约束与配额）
curl -H "$T" $CV/credentials                  # 凭据元数据（永不返回值）
curl -H "$T" "$CV/audit?hours=24&limit=50"    # 审计检索
curl -H "$T" $CV/health                       # 平台自检

# 干跑：不发真实请求，先看判定
curl -X POST -H "$T" -H 'Content-Type: application/json' \
     -d '{"capability":"zabbix_host_list","args":{"limit":5}}' $CV/explain

# 真实调用
curl -X POST -H "$T" -H 'Content-Type: application/json' \
     -d '{"capability":"zabbix_host_list","args":{"limit":5}}' $CV/invoke

# 需审批的写操作：返回 202 + approval_id，人工批准后带上它重试
curl -X POST -H "$T" -H 'Content-Type: application/json' \
     -d '{"capability":"wecom_send_text","args":{"content":"x"}}' $CV/invoke
# → 202 {"code":11,"approval_id":"..."}   ← 人点 Web 审批 → 重试同一请求并附 approval_id

version: 1
capabilities:
  - name: zabbix_host_list                # ^[a-z][a-z0-9_]{2,60}$
    kind: http                            # http | exec | rotate
    description: 列出 Zabbix 主机（只读）。用于晨检与资产盘点。   # 必填，AI 靠它选工具
    read_only: true                       # Kill Switch 期间只读能力仍放行
    require_confirm: false                # 写操作建议 true
    secret_ref: ZABBIX_TOKEN              # 只写名字，值由内核注入
    input_schema:                         # JSON Schema 子集，错参数当场拒
      type: object
      properties:
        filter: {type: string, maxLength: 64}
        limit:  {type: integer, default: 50, minimum: 1, maximum: 500}
    http:
      method: POST                        # 固定方法，不接受调用方改写
      base_url: https://zabbix.example.com
      path: /api_jsonrpc.php              # 固定路径，可含 {{ 变量 }}
      inject: {type: header, name: Authorization, prefix: "Bearer "}
      allow_private_upstream: true        # 内网地址需显式开启（默认禁）
      body_template:
        jsonrpc: "2.0"
        method: host.get
        params: {output: [hostid, host], search: {host: "{{ filter | default('') }}"}}
        id: 1
    response: {json: true, pick: result, array_limit: 50}   # 结构化裁剪，省 token

version: 1
defaults: {deny_by_default: true, quota_per_min: 60, quota_per_day: 2000}
deny:                                  # deny 永远优先于 allow
  - {capability: "*delete*", reason: 不可逆动作走人工}
agents:
  - id: workbuddy-local
    allow_exec: false                  # exec 注入默认关闭（第二把锁在 exec.enabled）
    visible_credentials: [ZABBIX_TOKEN] # 双轴之一：连「能看见哪些凭据名」都受限
    capabilities:
      - {name: zabbix_host_list, allow: true}
      - {name: wecom_send_text, allow: true, require_approval: true}
      - {name: "*", allow: false}

python -m unittest discover -s tests -v     # 109 个用例，全绿

credvault/
├── credvault/            # 包（24 个模块，见下）
│   ├── config.py         # 配置外置 + 路径锚定
│   ├── crypto.py         # KEK→DEK 信封加密
│   ├── store.py          # 元数据库 / 密文库（分离）
│   ├── kinds.py          # 凭据类型注册表（必填字段 + 形态校验）
│   ├── registry.py       # 能力注册表（YAML → 工具 + 参数校验 + 模板）
│   ├── policy.py         # 能力级授权（deny-by-default / deny 优先）
│   ├── approvals.py      # 异步审批 + 会话豁免 + 通知
│   ├── tokens.py         # 双轴令牌 + IP + TTL
│   ├── executor.py       # HTTP 代发 / 子进程注入（SSRF、白名单、池上限）
│   ├── redact.py         # 脱敏 + 返回体预算
│   ├── audit.py          # 哈希链审计
│   ├── rotate.py         # 轮换（探针 + 回滚）
│   ├── service.py        # 装配 + 公开面（闸门/配额/执行委托）
│   ├── gates.py          # 闸门链（static→policy→credential→quota→approval）
│   ├── quota.py          # 配额 + 软限流（config>policy>默认）
│   ├── runner.py         # 执行器（唯一明文边界：解出→注入→脱敏）
│   ├── cli/              # 命令行：_common/lifecycle/health/creds/access/parser
│   ├── mcp.py            # MCP 服务（手写 JSON-RPC，不依赖 SDK）
│   ├── web.py            # 路由 + 登录 + 探针 + MCP-over-HTTP
│   ├── webui.py          # 三视图 HTML 渲染（纯函数）
│   ├── dist.py           # lease 化凭据分发
│   ├── backup.py         # .cvault 备份包
│   ├── ops.py            # 自检 / 指标
│   └── cli.py            # 命令行
├── capabilities/         # 能力定义（加 YAML 即加工具）
├── deploy/               # systemd 单元 + 环境投影示例
├── tests/                # 109 个用例
└── pyproject.toml       # 打包元数据（extras 预留）