构建 Secret Source 插件
Secret source 会从外部密钥管理器(vault、密码管理器、操作系统 keystore、自定义脚本)解析 provider(服务提供商)凭据,并在进程启动时将其转化为环境变量 —— 位于 ~/.kopi/.env 加载之后、Kopi Agent 读取凭据之前。Bitwarden 和 1Password 内置于代码库中;其他所有后端都是 plugin。本指南介绍如何构建这样一个 plugin。
内置的集合有意保持封闭,与 memory provider 的策略一致:在 agent/secret_sources/ 下新增 vault 后端的 PR 会被关闭,并引导至本指南。请将你的后端发布为独立的 plugin 仓库,并在 Kopi Ai Agent Pte Ltd Discord (#plugins-skills-and-skins) 中分享。
框架负责的部分 vs. 你负责的部分
编排器(agent.secret_sources.registry.apply_all)负责所有与安全和优先级相关的事务,因此后端无法在这些地方出错:
| 框架负责 | 你负责 |
|---|---|
| Source 顺序、mapped 与 bulk 的优先级 | 从你的后端获取值 |
| 先声明者获胜的冲突处理 + 警告 | 验证你的引用格式 |
override_existing 语义(永不跨 source) | 与你的 CLI/SDK/API 交互 |
| 受保护的 bootstrap token | 声明哪个 env var 是你的 bootstrap token |
| 每个 source 的墙上时钟超时 | 保持 fetch() 足够快 |
每个变量的来源 + (from X) 标签 | 人类可读的 label |
os.environ 写入 | 无 —— 你永远不接触环境 |
目录结构
~/.kopi/plugins/my-vault/
├── plugin.yaml # name, description
└── __init__.py # SecretSource subclass + register(ctx)
SecretSource 抽象基类
实现 agent.secret_sources.base.SecretSource。仅需一个必需方法:
from pathlib import Path
from agent.secret_sources.base import (
ErrorKind,
FetchResult,
SecretSource,
run_secret_cli,
)
class MyVaultSource(SecretSource):
name = "myvault" # config section key: secrets.myvault
label = "My Vault" # used in startup lines + provenance labels
shape = "mapped" # "mapped" (explicit VAR→ref map) or "bulk" (project dump)
scheme = "mv" # optional: unique URI scheme you own (mv://...)
def fetch(self, cfg: dict, home_path: Path) -> FetchResult:
"""Resolve secrets. MUST NOT raise. MUST NOT prompt."""
result = FetchResult()
token = os.environ.get("MYVAULT_TOKEN", "").strip()
if not token:
result.error = "secrets.myvault.enabled is true but MYVAULT_TOKEN is not set."
result.error_kind = ErrorKind.NOT_CONFIGURED
return result
try:
proc = run_secret_cli(
["myvault-cli", "export", "--json"],
allow_env=["MYVAULT_TOKEN"], # ONLY your auth vars — never full os.environ
timeout=30,
)
except RuntimeError as exc: # spawn failure / timeout
result.error = str(exc)
result.error_kind = ErrorKind.BINARY_MISSING
return result
if proc.returncode != 0:
result.error = f"myvault-cli exited {proc.returncode}: {proc.stderr[:200]}"
result.error_kind = ErrorKind.AUTH_FAILED
return result
result.secrets = parse_your_output(proc.stdout) # {ENV_VAR: value}
return result
def protected_env_vars(self, cfg: dict):
# Your bootstrap token — no source (including yours) may ever overwrite it.
return frozenset({"MYVAULT_TOKEN"})
契约规则(强制执行,非建议)
fetch()永不抛出异常。 错误放入result.error+result.error_kind中。抛出异常的 fetch 会被编排器捕获并上报为INTERNAL—— 这是契约违规,而非特性。fetch()永不发起交互提示。 启动在非 TTY 环境(gateway、cron、Docker)中运行。run_secret_cli()关闭 stdin,让需要交互的 helper 立即失败。交互式认证应位于你的 CLI 设置流程中,绝不应位于启动路径上。- 同步执行,且在预算内。 编排器强制执行墙上时钟超时(默认 120 秒,用户可通过
secrets.<name>.timeout_seconds调整)。超时会报告TIMEOUT,你的结果将被丢弃。 - 你负责获取;编排器负责应用。 返回你本要贡献的映射。绝不要自己写入
os.environ—— 这会绕过优先级、冲突检测和来源追踪。 - API 版本管理。
SecretSource.api_version默认为当前SECRET_SOURCE_API_VERSION。registry 会跳过(并给出警告)基于其他版本构建的 source,而不会使启动崩溃。
选择你的 shape
mapped—— 用户在 config 中显式将 env-var 名称绑定到引用(如 1Password 的env:映射)。意图最强:对于有争议的变量,mapped 声明优先于 bulk 声明。bulk—— 你隐式注入整个项目/文件夹的 secrets(如 Bitwarden BSM)。让位于 mapped source。
可选钩子
| 方法 | 默认值 | 何时覆盖 |
|---|---|---|
is_enabled(cfg) | cfg.get("enabled") | 需要自定义激活逻辑时 |
override_existing(cfg) | cfg.get("override_existing", False) | 你想要不同的默认值(两个内置 source 默认为 True,以便进行轮换) |
protected_env_vars(cfg) | 空 | 你有 bootstrap token(几乎可以肯定你有) |
fetch_timeout_seconds(cfg) | 120s | 你的后端需要不同的预算 |
config_schema() | {} | 为设置界面声明 config 键 |
子进程安全:使用 run_secret_cli()
如果你的后端会调用外部 CLI,请使用共享 helper,而非直接使用 subprocess.run。它会免费提供经过审计的安全姿态:仅使用 argv(不使用 shell=True)、最小化的、白名单化的子进程环境(当 source 运行时,os.environ 已包含 Kopi Agent 知道的所有凭据 —— 绝不能将其交给子进程)、NO_COLOR + 清除 ANSI 的 stderr、关闭 stdin、超时 → 干净的 RuntimeError。请在 argv 中 -- 终止符之后传入用户提供的引用字符串,这样它们永远不会被解析为 flag。
注册
# __init__.py
def register(ctx):
ctx.register_secret_source(MyVaultSource())
以下情况会被拒绝注册(记录日志警告,绝不崩溃):非 SecretSource 实例、无效/重复的名称、已被其他 source 占用的 scheme、错误的 api_version,或 mapped/bulk 之外的 shape。
plugin 的发现时机晚于首次 load_kopi_dotenv() 调用,因此发现它的进程的首次 env 加载不会使用 plugin source。但之后生成的每个 Kopi Agent 进程(gateway 子进程、cron 会话、subagent)都会使用它。内置 source 覆盖首个进程的引导。
用户可以像配置其他 source 一样配置它
secrets:
sources: [myvault, bitwarden] # optional ordering
myvault:
enabled: true
# ... your config_schema keys
多 source 优先级、冲突警告以及 (from My Vault) 来源标签都会自动工作 —— 参见面向用户的 secrets 文档了解优先级阶梯。
使用一致性测试套件验证
在你的 plugin 测试中,子类化 Kopi Agent 仓库 (tests/secret_sources/conformance.py) 中的套件:
import pytest
from tests.secret_sources.conformance import SecretSourceConformance
class TestMyVaultConformance(SecretSourceConformance):
@pytest.fixture
def source(self):
return MyVaultSource()
它会检查那些一旦违反就会影响他人的规则:对畸形 config 永不抛出异常、机器可读的错误类型、默认禁用、正的超时值、有效的受保护变量名称,以及完整的 apply_all() 往返。一致性测试全绿是判定后端符合契约的审核基准。
ErrorKind 参考
| 类型 | 含义 |
|---|---|
NOT_CONFIGURED | 已启用但缺少 token / project / map |
BINARY_MISSING | 找不到 helper CLI 或其不可执行 |
AUTH_FAILED / AUTH_EXPIRED | 凭据错误 / 过期 |
REF_INVALID | 某个 secret 引用验证失败 |
NETWORK | 传输层故障 |
EMPTY_VALUE | 后端对某引用未返回任何内容 —— 绝不能在一个有效的凭据上应用 "" |
TIMEOUT | Fetch 超出其预算 |
INTERNAL | 其他情况(bug、意外结构) |