能力体系（Capabilities）

**能力（Capability）**是 Sigil 暴露给 AI 客户端的"动作单元"。每个能力背后是一段 Rust 代码或一个 HTTP 模板，它知道如何使用某种凭据完成某类操作。

心智模型

AI 客户端           Sigil                  目标服务
   │                  │                      │
   │ 我要 git push    │                      │
   ├─────────────────►│                      │
   │                  │ 查找 git_mutate 能力 │
   │                  │ 查找 github_token    │
   │                  │ 注入 Authorization   │
   │                  ├─────────────────────►│
   │                  │                      │ 执行 push
   │                  │◄─────────────────────│
   │                  │ 脱敏响应             │
   │◄─────────────────│                      │
   │ push 成功        │                      │

能力是"凭据 + 操作"的桥。AI 知道"有哪些操作可以请求"，但不知道具体哪条凭据被用、不知道凭据明文。

内置能力清单

读类（无副作用）

能力	用途	用到的凭据类型
`git_query`	查询分支 / 提交 / tag	`github_token` / `gitee_token` / `gitcode_token`
`db_query`	执行 SELECT / WITH	`db_conn`
`ssh_query`	远程只读命令（system info / ps / df）	`ssh_key`
`http_request`	GET / HEAD（按目标 host 自动选 `http_api`）	`http_api` / Git Token
`health_check`	快速诊断凭据有效性（不返回数据）	任意
`sys_info`	本机系统信息（不需凭据）	无
`capability_list`	列出当前已注册的能力	无

写类（有副作用）

能力	用途	默认行为
`git_mutate`	push / pull / merge / branch / tag	需调用方在请求里声明意图
`db_execute`	INSERT / UPDATE / DELETE / DDL	需调用方在请求里声明意图
`ssh_exec`	远程任意命令	黑名单（`rm -rf /` 等永久拦截）
`http_request` (POST/PUT/DELETE/PATCH)	改动型 HTTP	客户端需明确指定方法
`password_generate`	强密码 / 助记词 / TOTP 生成	不需凭据

管理类（不直接执行业务）

能力	用途
`__temp_grant__`	临时授权一条凭据（参见临时授权）
`__temp_revoke__`	撤销已签发的临时授权
`audit_query`	查询审计日志

带 __ 前缀的是内部管理能力，默认对所有客户端隐藏；需要在客户端 Token 范围里显式勾选才暴露。

自定义 HTTP 模板

Sigil 内置能力覆盖了 80% 通用场景，剩下 20% 通常是"调用我们公司内部 API"——为此提供 HTTP 模板机制，无需写一行 Rust。

一个例子

公司内部对账系统有个接口 POST https://billing.acme.internal/api/refund，需要 X-Service-Token 头鉴权。

在 Sigil → 能力 → 新增 HTTP 模板：

名称：    refund-acme
方法：    POST
URL：     https://billing.acme.internal/api/refund
Headers：
  X-Service-Token: ${cred:acme-internal-svc.value}
  Content-Type: application/json
Body：
  {
    "order_id": "${input:order_id}",
    "reason":   "${input:reason}",
    "operator": "${meta:caller}"
  }
默认凭据：acme-internal-svc
范围：    白名单客户端

占位符语法：

占位符	含义
`${cred:<name>.<field>}`	引用金库里某条凭据的某字段
`${input:<name>}`	调用方传入的参数
`${meta:caller}`	当前调用方的 Token 名（用于审计追溯）
`${meta:now}`	当前 ISO 时间戳

保存后，这条 HTTP 模板就出现在 Claude / Cursor 的工具列表里，叫做 refund-acme。AI 可以像调内置能力一样调它，全程不知道 acme-internal-svc 的明文 Token。

占位符替换时机

客户端发起请求
Sigil 校验白名单 + Scope Policy
解密 acme-internal-svc → 拿到明文 Token
替换所有 ${cred:...} 占位符
真的发起 HTTP 请求
响应回来后，把所有可能的凭据明文用 [REDACTED:xxx] 占位
返回给客户端

明文只在第 4-5 步之间出现在内存里（< 1 ms），用完立刻清零。

能力的两层确认

写类能力（git_mutate / db_execute / ssh_exec 等）默认走两层确认：

协议层声明：调用方必须在请求里明确写出 mode: "mutate"——AI 想"顺手"执行修改是不行的，必须明确
客户端确认：Claude Code 等 MCP 客户端会在 UI 里弹"是否同意执行 X"——这是客户端层面的安全网

如果你信任某个客户端做了完整确认，可以在 Sigil → 设置 → 信任策略中把这个客户端标为"免二次确认"。

能力注解（readOnlyHint / destructiveHint）

每个能力在 tools/list 里都带 MCP 行为注解，供客户端做分级审批：

注解	含义	客户端典型行为
`readOnlyHint: true`	只读、无副作用（各 `_list` / `_query` / 自省类）	可免二次确认、失败可安全重试
`destructiveHint: true`	破坏性（删除 / 覆盖 / 不可逆，如删分支、force-push、取消 run、改 GITHUB_TOKEN 权限）	强确认

注解是给客户端的 UX 提示，不是安全保证——真正的拦截靠 require_confirm + Scope Policy + 危险命令黑名单。

危险命令拦截

ssh_exec 内置一个永久黑名单：

rm -rf /
rm -rf /*
:(){:|:&};:
mkfs.*
dd if=/dev/zero of=/dev/sd*
chmod -R 000 /

这些命令在任何上下文都不可能是合理的——直接在 Sigil 内拒绝，客户端层面再怎么确认也过不去。

类似地，db_execute 拒绝：

不带 WHERE 的 DELETE / UPDATE
DROP DATABASE / TRUNCATE（除非显式 mode: "destructive"）

AI Kill Switch

Sigil 状态栏右下角有一个红色拨杆——禁用所有 AI 能力执行。

启用后：

MCP Server 仍在监听，但所有能力调用立即返回 kill_switch_active
金库 UI 仍可正常使用（人能看、能管理）
审计日志记录"Kill Switch 期间被拦截 N 次"

适用场景：

上线敏感时段（不希望任何代理执行）
应急响应（怀疑某个 Token 泄漏，先全停再排查）
合规审查窗口

下一步

了解 MCP Server 的协议细节：MCP Server →
了解临时授权机制：临时授权 →
了解能力调用的安全模型：AI 使用边界 →

能力体系（Capabilities） ​

心智模型 ​

内置能力清单 ​

读类（无副作用） ​

写类（有副作用） ​

管理类（不直接执行业务） ​

自定义 HTTP 模板 ​

一个例子 ​

占位符替换时机 ​

能力的两层确认 ​

能力注解（readOnlyHint / destructiveHint） ​

危险命令拦截 ​

AI Kill Switch ​

下一步 ​