内容
# kprun v0.2.3
[](https://github.com/numikel/kprun/actions/workflows/ci.yml)
[](LICENSE)
**适用于开发人员和人工智能代理工作流的本地密钥注入工具。** 支持 KeePass `.kdbx` 保险箱（与 KeePassXC 兼容）、操作系统密钥链解锁、按进程环境注入 - 而不是会话范围。
[发行版](https://github.com/numikel/kprun/releases) · [更新日志](CHANGELOG.md) · [安装](#installation) · [快速入门](#quick-start) · [编码代理和 OpenRouter](#coding-agents-and-openrouter) · [MCP 集成](#mcp-integration) · [安全模型](#security-model)
---
## 关于
kprun 将 API 密钥和令牌存储在您计算机上的 KeePass 数据库中。通过 `KPRUN_KEYFILE`、操作系统凭证存储或交互式提示解锁保险箱，然后将密钥作为环境变量注入到**一个子进程**中。不会导出到您的 shell 配置文件中，也不会出现在 MCP 服务器的标准输出中。
典型用途：
- 在不粘贴令牌到客户端配置文件的情况下运行 MCP 服务器（`npx …`）
- 启动编码代理（Claude Code、Hermes、Junie、AGY、…）并注入 OpenRouter 环境变量，仅限一次会话
- 启动开发工具并注入限定密钥（`kprun run openai -- python app.py`）
- 管理独立的 **开发密钥** 保险箱，与个人密码管理器分开
## 工作原理
```mermaid
flowchart LR
subgraph without ["没有 kprun"]
direction TB
W1["shell exports GITHUB_TOKEN=…"]
W1 -->|"密钥在每个子进程中"| W2["所有进程继承环境变量"]
end
subgraph with ["使用 kprun"]
direction TB
K1["kprun run github -- npx @mcp/server-github"]
K1 --> K2["解锁保险箱<br/>(密钥文件 → 密钥环 → 提示)"]
K2 --> K3["读取条目 'github' 自定义字段"]
K3 --> K4["仅注入环境变量到子进程"]
K4 --> K5["继承标准输入/输出；审计日志（仅密钥名称）"]
end
```
解锁优先级：`KPRUN_KEYFILE` → 操作系统密钥存储（`kprun` / `master`）→ 隐藏的标准错误提示。
## 功能
- ✅ **KeePass / KeePassXC 保险箱** — 条目标题 = 服务名称；自定义字符串字段 = 环境变量名称
- ✅ **按进程注入** — `kprun run` 打开保险箱只读并生成一个具有合并环境的子进程
- ✅ **MCP 安全标准输入/输出** — `run` 在标准输出上不打印任何内容；子进程拥有标准输入/输出/标准错误
- ✅ **完整的密钥生命周期** — `init`、`set`、`get`、`unset`、`delete`、`export`、`import`、`doctor`
- ✅ **审计日志** — JSON 行包含条目名称和注入的密钥名称；**绝不包含值**
- ✅ **跨平台** — Linux、macOS、Windows（PATHEXT 感知 spawn，keyring v1）
- ✅ **RTK 风格安装** — `install.sh` / `install.ps1` 带有 SHA-256 校验和验证
- ✅ **CI 矩阵** — fmt、clippy、ubuntu/windows/macos 上的测试；标签 `v*` 上的发布资产
## 要求
- **Rust**：1.88.0+（从源代码构建）
- **操作系统**：Linux、macOS 或 Windows
- **可选**：[KeePassXC](https://keepassxc.org/) 以创建或编辑 `.kdbx` 文件
- **MCP 客户端**：Cursor、Claude Code 或任何通过标准输入/输出生成子进程的工具
## 安装
### 快速安装（Linux / macOS）
```bash
curl -fsSL https://raw.githubusercontent.com/numikel/kprun/refs/heads/main/scripts/install.sh | sh
```
默认安装到 `~/.local/bin`。使用 `KPRUN_INSTALL_DIR` 覆盖。跳过路径更改，使用 `KPRUN_NO_MODIFY_PATH=1`。
> 如果需要手动添加到 PATH：
>
> ```bash
> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # 或 ~/.zshrc
> ```
### 快速安装（Windows）
```powershell
irm https://raw.githubusercontent.com/numikel/kprun/refs/heads/main/scripts/install.ps1 | iex
```
默认安装目录：`%LOCALAPPDATA%\kprun\bin`。除非 `KPRUN_NO_MODIFY_PATH=1`，否则添加用户 `Path`。
打开一个**新终端**，然后验证：
```bash
kprun --version
```
### 预构建二进制文件
从 [GitHub Releases](https://github.com/numikel/kprun/releases) 下载（在第一个标签后）：
| 平台 | 资产 |
|----------|-------|
| Linux x86_64 | `kprun-x86_64-unknown-linux-gnu.tar.gz` |
| Linux arm64 | `kprun-aarch64-unknown-linux-gnu.tar.gz` |
| macOS Intel | `kprun-x86_64-apple-darwin.tar.gz` |
| macOS Apple Silicon | `kprun-aarch64-apple-darwin.tar.gz` |
| Windows | `kprun-x86_64-pc-windows-msvc.zip` + 独立 `kprun.exe` |
使用 `checksums.txt` 验证，除非 `KPRUN_SKIP_CHECKSUM=1`。
### 从源代码构建
```bash
git clone https://github.com/numikel/kprun.git
cd kprun
cargo build --release -p kprun
# 二进制文件：target/release/kprun（或 target/<triple>/release/kprun）
```
或安装到 Cargo bin 目录：
```bash
cargo install --path crates/kprun
```
## 快速入门
```bash
# 1. 创建保险箱（主密码 → 默认操作系统密钥链）
kprun init
# 2. 存储密钥（条目标题 = 服务；字段 = 环境变量）
kprun set github GITHUB_TOKEN=ghp_xxx
# 3. 注入到子进程
kprun run github -- npx -y @modelcontextprotocol/server-github
```
Windows（`install.ps1` 后）：
```powershell
kprun init
kprun set github GITHUB_TOKEN=ghp_xxx
kprun run github -- npx -y @modelcontextprotocol/server-github
```
### 附加现有的 KeePassXC 数据库
```bash
kprun init --db /path/to/existing.kdbx
```
验证解锁并可选地将主密码存储在操作系统密钥链中。不**重新创建**数据库。
## 编码代理和 OpenRouter
许多终端编码代理从**环境变量**读取 API 密钥和提供商 URL。而不是在 `~/.bashrc` 或 `~/.zshrc` 中导出它们（每个进程都继承它们），将 OpenRouter 配置文件存储在您的保险箱中，并通过 `kprun run` 启动代理。
分隔符 `--` 是必需的 - 它标志着保险箱条目名称的结尾和子命令的开始：
```text
kprun run <entry> -- <agent-command> [args...]
```
### 一次性保险箱设置（Claude Code / OpenRouter）
按照 [OpenRouter 的 Claude Code 指南](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration)，Claude Code 期望这些变量。将它们存储在一个保险箱条目下（标题 = `openrouter` 这里；任何名称都有效）：
```bash
kprun set openrouter \
OPENROUTER_API_KEY=sk-or-... \
ANTHROPIC_BASE_URL=https://openrouter.ai/api \
ANTHROPIC_AUTH_TOKEN=sk-or-... \
ANTHROPIC_API_KEY=
```
KeePass 字段是字面值 - 将 `ANTHROPIC_AUTH_TOKEN` 设置为与 `OPENROUTER_API_KEY` 相同的密钥。将 `ANTHROPIC_API_KEY` 设置为空字符串以避免与缓存的 Anthropic 登录（如果您之前在 Claude Code 中登录，请运行 `/logout`）发生身份冲突。
可选模型覆盖（也来自 OpenRouter 文档）：
```bash
kprun set openrouter \
ANTHROPIC_DEFAULT_SONNET_MODEL='~anthropic/claude-sonnet-latest' \
ANTHROPIC_DEFAULT_OPUS_MODEL='~anthropic/claude-opus-latest'
```
### 启动示例
**Claude Code** — 密钥仅保留在子进程中；您的 shell 配置文件保持干净：
```bash
kprun run openrouter -- claude
```
Windows PowerShell：
```powershell
kprun run openrouter -- claude
```
在 Claude Code 中使用 `/status` 验证（身份令牌：`ANTHROPIC_AUTH_TOKEN`，基准 URL：`https://openrouter.ai/api`）。
**Antigravity CLI（`agy`）** — CLI 默认通过 Google 进行身份验证。如果您使用 OpenRouter 通过插件、扩展或任何读取 `OPENROUTER_API_KEY` 环境变量的工作流程，请像这样注入：
```bash
kprun set openrouter OPENROUTER_API_KEY=sk-or-...
kprun run openrouter -- agy
```
**Hermes Agent** — Nous Research 的终端代理从环境中读取 `OPENROUTER_API_KEY`（替代 `~/.hermes/.env`）。模型和提供商保留在 `~/.hermes/config.yaml` 中；参见 [OpenRouter 的 Hermes 指南](https://openrouter.ai/docs/cookbook/coding-agents/hermes-integration)：
```bash
kprun set openrouter OPENROUTER_API_KEY=sk-or-...
kprun run openrouter -- hermes
# 或：kprun run openrouter -- hermes --tui
```
**Junie CLI** — JetBrains 的终端代理使用 OpenRouter 作为原生 BYOK 提供商，通过 `JUNIE_OPENROUTER_API_KEY`；参见 [OpenRouter 的 Junie 指南](https://openrouter.ai/docs/cookbook/coding-agents/junie)：
```bash
kprun set openrouter \
OPENROUTER_API_KEY=sk-or-... \
JUNIE_OPENROUTER_API_KEY=sk-or-...
kprun run openrouter -- junie
```
无头 CI 示例（相同的环境变量注入，无 shell 配置文件）：
```bash
kprun run openrouter -- junie "Review and fix any code quality issues in the latest commit"
```
**GitHub Copilot CLI** — Copilot 在启动时修复模型并使用 OpenAI 兼容的 API；仅环境变量注入对于实时模型切换很麻烦。对于 Copilot CLI（和 Codex CLI with OpenRouter），作者建议 **[copilot-cli-custom-proxy](https://github.com/numikel/copilot-cli-custom-proxy)** 代替：一个本地托盘代理，动态切换模型，从内存注入 API 密钥，并使用正确的环境变量启动 Copilot/Codex - 而不是将密钥放入您的 shell 配置文件中。
| 代理 | kprun 适用性 | 备注 |
|-------|-----------|-------|
| Claude Code | ✅ 最佳适用 | 基于环境的 OpenRouter 设置；参见 [OpenRouter 文档](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration) |
| Hermes Agent | ✅ 最佳适用 | `OPENROUTER_API_KEY`；配置在 `~/.hermes/config.yaml` 中；参见 [OpenRouter 文档](https://openrouter.ai/docs/cookbook/coding-agents/hermes-integration) |
| Junie CLI | ✅ 最佳适用 | `JUNIE_OPENROUTER_API_KEY`；参见 [OpenRouter 文档](https://openrouter.ai/docs/cookbook/coding-agents/junie) |
| Antigravity CLI（`agy`） | ⚠️ 部分 | 默认身份验证是 Google；当工作流程读取环境变量时使用 kprun |
| Copilot CLI / Codex CLI | ❌ 使用代理 | 优先使用 [copilot-cli-custom-proxy](https://github.com/numikel/copilot-cli-custom-proxy) |
一个 OpenRouter 密钥可以为上述每个工具提供支持；在 [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys) 生成它。
## 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `KPRUN_DB` | `~/.kprun/secrets.kdbx` | KeePass 数据库路径 |
| `KPRUN_KEYFILE` | — | 加密密钥文件路径（第二因素） |
| `KPRUN_LOG` | `~/.kprun/access.log` | 审计日志路径（JSON 行，仅限密钥名称） |
| `KPRUN_INSTALL_DIR` | `~/.local/bin` / `%LOCALAPPDATA%\kprun\bin` | 安装脚本目标 |
| `KPRUN_NO_MODIFY_PATH` | 未设置 | 设置为 `1` 以跳过 shell PATH 更新 |
| `KPRUN_SKIP_CHECKSUM` | 未设置 | 设置为 `1` 以跳过安装校验和验证 |
| `KPRUN_VERSION` | 最新发布 | 固定安装脚本版本 |
| `KPRUN_TEST_MASTER` | — | 测试钩子（仅在 `--features test-hooks` 编译构建中；不在 GitHub Release 二进制文件中）：固定自动化主密码 |
安装脚本环境变量在 `scripts/install.sh` 和 `scripts/install.ps1` 中有文档记录。
## CLI 参考
```
kprun init [--db PATH] [--no-store] [--keyfile PATH]
kprun run <entry> [entry2 ...] -- <command> [args...]
kprun list [--json]
kprun get <entry> [--keys] [--reveal]
kprun set <entry> KEY=val [KEY2=val2 ...]
kprun unset <entry> KEY [KEY2 ...]
kprun delete <entry>
kprun export [--format json|dotenv] [--stdout] [--reveal]
kprun import <file> [--merge]
kprun doctor [--mcp <entry>]
kprun deinit`
```
注意：
- `get` 和 `export` 默认显示 **名称**；使用 `--reveal` 仅需值（stderr 警告 + 审计）。
- `|mcp <entry>`
### 导出和导入
`import` 接受 JSON（`.json`）或 kprun dotenv（`.env`）。JSON 是 `kprun export --stdout` 的结构化格式。dotenv **不是** 通用项目 `.env` 文件 - 它是 `kprun export --format dotenv` 生成的往返格式。
每个保险箱 **条目** 是一条注释行，包含条目标题，后跟 `KEY=value` 行。单独的条目用空白行分隔：
```env
# github
GITHUB_TOKEN="ghp_xxx"
# postgres
DATABASE_URL="postgres://local"
```
要迁移平面项目 `.env`（仅限密钥，无标题注释），请在顶部添加一行标题。在下一个 `# title` 或空白行之前，所有后续密钥都归入该条目，直到下一个 `# title` 或空白行：
```env
# default
OPENAI_API_KEY="sk-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
```
然后导入：
```bash
kprun import secrets.env --merge # 添加/更新密钥；保留其他保险箱条目
kprun import secrets.env # 用文件条目替换保险箱内容
```
使用 `--reveal` 检查规范 dotenv 布局：
```bash
kprun export --format dotenv --stdout --reveal
```
结构仅 dotenv 导出（`#` 注释中的密钥名称，无值）不能被导入 - 重新导出时使用 `--reveal`。
## MCP 集成
MCP 客户端生成一个命令，通过子进程的标准输入/输出与之交互。使用 `kprun run` 作为透明包装器。
**Linux / macOS**（`kprun` 在 `PATH` 上）：
```json
{
"mcpServers": {
"github": {
"command": "kprun",
"args": ["run", "github", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}
```
**Windows**（更倾向于完整路径 - 部分 MCP 客户端无法可靠地解析 `PATH`）：
```json
{
"mcpServers": {
"github": {
"command": "C:\\Users\\you\\AppData\\Local\\kprun\\bin\\kprun.exe",
"args": ["run", "github", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}
```
生成一个可以直接粘贴的片段：
```bash
kprun doctor --mcp github
```
对于其他条目，请在 `--` 之后附加 MCP 服务器命令：
```bash
kprun doctor --mcp qdrant -- npx -y @modelcontextprotocol/server-qdrant
```
如果没有子命令，则通用条目会发出 `["run", "<entry>", "--"]` 和 stderr 提示 - 将服务器命令粘贴到 `args` 中或重新运行并使用 `--`。
编辑 MCP 配置后，请检查 `git diff` - 一些工具可能会将机密写回磁盘。
## 自动化和 cron
当没有交互式会话可用时（cron，任务调度器），操作系统密钥链可能不可用。使用 **密钥文件**：
```bash
kprun init --keyfile ~/.kprun/master.key
export KPRUN_KEYFILE=~/.kprun/master.key
kprun run myservice -- /path/to/script.sh
```
密钥文件由 kprun 生成（64 个随机字节），而不是纯文本密码文件。限制权限（Unix 上的 `chmod 600`；Windows 上的用户权限 ACL）。
对于调度作业，在作业环境中设置 `KPRUN_DB` 和 `KPRUN_KEYFILE`。在 `init` 时使用 `--no-store` 如果您不想将主密码存储在密钥链中。
## 项目结构
```
kprun/
├── crates/
│ ├── kprun-core/ # 保险箱，解锁，注入，审计（无 clap / Command）
│ └── kprun/ # CLI 二进制文件，生成，命令
├── scripts/
│ ├── install.sh # RTK 风格安装程序（Unix）
│ └── install.ps1 # Windows 安装程序
├── tests/ # 集成测试（运行，初始化，管理，导出，医生，...）
├── .github/workflows/
│ ├── ci.yml # fmt, clippy, 测试矩阵
│ └── release.yml # 交叉构建 + 校验和在标签 v*
└── docs/
├── kprun.gif # 演示动画
└── changelogs/ # 每个版本的发布说明
```
## 开发
### 设置
```bash
git clone https://github.com/numikel/kprun.git
cd kprun
cargo build -p kprun
```
### 运行测试
```bash
cargo test --all
```
KeePassXC 兼容性测试（可选，当地夹具）：
```bash
# 在 KeePassXC 中创建 tests/fixtures/keepassxc.kdbx（gitignored）
# 条目标题：fixture；自定义属性：FIXTURE_KEY
KPRUN_KEEPASSXC_FIXTURE=1 KPRUN_TEST_MASTER='your-pass' \
cargo test reads_keepassxc_fixture -- --ignored
```
### 代码质量（匹配 CI）
```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
```
## 安全模型
- 使用专用的 **开发密钥** 保险箱，而不是个人密码管理器。
- 按照 [SECURITY.md](SECURITY.md) (**contact@michalsk.pl**) 报告漏洞；不要为安全漏洞创建公开问题。
- 机密存在于 **子进程环境** 注入后（与其他机密运行器相同模型）。
- 审计日志记录条目名称和注入的密钥名称 - **绝不包含值**。
- 不要为 API 密钥使用 `setx` 或全局 shell 配置文件。
- 仅传递命令需要的条目：`kprun run openai -- python script.py`，而不是一次传递所有机密。
- `export --reveal` 和 `get --reveal` 打印值到终端 - 谨慎使用。
## 版本发布
版本发布时，维护人员标记 `vX.Y.Z` 并推送：
```bash
git tag vX.Y.Z
git push origin main --tags
```
CI 验证变更日志文件和版本匹配，构建发布二进制文件，适用于五个目标，并在标签 `v*` 上发布 GitHub 版本，其正文来自 [docs/changelogs/vX.Y.Z.md](docs/changelogs/).
## 贡献
1. 分叉仓库。
2. 创建一个功能分支 (`git checkout -b feat/my-change`).
3. 使用 **Conventional Commits 1.0.0** 提交（例如 `feat(cli): add example command`，`fix(core): handle locked db`）。
4. 为行为更改添加或更新测试。
5. 运行 `cargo fmt`，`cargo clippy --all-targets --all-features -- -D warnings` 和 `cargo test --all`。
6. 打开一个拉取请求到 `main`。
使用英语编写代码、注释和 CLI 消息。
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE)。
## 作者
**@numikel**
---
**安全说明：** kprun 将机密注入子进程环境。请像对待保险箱文件、密钥文件和审计日志一样，将其视为敏感信息。不要将 `.kdbx` 文件或密钥文件提交到版本控制中。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器