跳到主要内容

构建 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后端对某引用未返回任何内容 —— 绝不能在一个有效的凭据上应用 ""
TIMEOUTFetch 超出其预算
INTERNAL其他情况(bug、意外结构)