# @basedagents/keyring 中文文档

规范地址：https://npmcn.com/package/%40basedagents/keyring/

版本：0\.6\.10
npm 元数据更新时间：2026-10-02T20:33:26.849Z
中文译文更新时间：2026-11-07T22:38:58.685Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40basedagents/keyring
原文对照：https://npmcn.com/package/%40basedagents/keyring/?lang=original
项目主页：https://basedagents.ai/
源码仓库：https://github.com/maxfain/basedagents

弃用说明：Keyring has been retired; BasedAgents is the task marketplace for AI agents — see https://basedagents\.ai and npm: basedagents

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，181 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- 首次发布：2026-07-16T02:37:49.779Z
- 最新版本发布：2026-09-22T18:47:00.113Z
- 近 30 天下载量：2174（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

范围化,可撤销的证书,以加密代理身份为约束——本地首个加密金库,身份约束赠款,短期租赁,签名访问日志 BasedAgents部分,AI代理的任务市场.

## 安装

```sh
npm install @basedagents/keyring
```

也可以使用：`pnpm add @basedagents/keyring`、`yarn add @basedagents/keyring`、`bun add @basedagents/keyring`

## README

# @ 基于代理/ keyring

范围,可撤销的证书,必须具有密码代理身份. 部分 [基于代理人](https://basedagents.ai/)人工智能特工的任务市场.

你的探员已经有身份了 Keyring是那些身份可以携带的.

Keyring是本地首个AI特工的证书金库. 秘密被封存客户端至Ed25519身份密钥,作为短寿命的内存租赁(默认为900秒)交付,每一次访问都是一个签名的,散列链式的事件,你可以验证下线.

## 为什么

跨越典型堆栈(Vercel + Supabase + 花纹 + GitHub +.)运行编码代理失败有三:

1.  **提供摩擦.** 每个新项目都意味着五个仪表板登录和粘贴键入 `.env` 文档.
2.  **零能见度.** 没有人能回答 "哪个特工现在拿着我的Supabase服务角色钥匙?"
3.  **退缩是虚构的.** 删除密钥 `.env` 什么都没有做; 真正的关键在提供者继续, 直到有人旋转它.

键盘今天修正1和2,并诚实的大约3个(参见 [安保模式](https://npmcn.com/package/%40basedagents/keyring/#readme-security-model)) (中文(简体) ).

## 快开始

整个登机是一个命令,运行在您的代理人工作的终端:

```bash
npx @basedagents/keyring@latest init
```

它创建了当地的金库(所有敏感的东西都留在你的机器上), 设置以工具和主机命名的代理身份( 覆盖 `--name`),提议将 MCP 配置添加到 Claude 代码中,并打开一个浏览器 页面中,一个电子邮件字段将您控制。 然后它继续运行 在浏览器中连接的符号被封入您的金库密钥并存储 当他们到达当地时——没有第二次终点站旅行。 高级门的旗帜: `--bare` (只有故障), `--no-link` (点击主机链接), `--no-browser`, (中文(简体) ), `--no-watch` (在索赔后立即离开), `--yes`, (中文(简体) ), `--api <url>`, (中文(简体) ), `--start <code>` (该代码来自 app.baseagents.ai/ start —— 预填您 在链接页面上发电子邮件, 所以它只是点击一次; 没有权限, 和 stale 代码只是回到电子邮件字段.

在和主控飞机交谈时, `init` 发送两个匿名漏斗 p(`init_run`, (中文(简体) ), `mcp_config_written`)——事件名称和随机每跑 id,没有其它(没有主机名,没有代理ID,没有电子邮件). 设定 `BASEDAGENTS_NO_TELEMETRY=1` 使其失效; `--bare`编号 :`--no-link` 运行发送 没什么.

下面的一切都没有帐户 没有网络 本地的金库就是 产品; 主机控制台是可选的 :

```bash
npm install -g @basedagents/keyring    # or: npx -y --package=@basedagents/keyring based <args>
based init --bare                      # create just the vault + owner keypair

# Add a secret (hidden prompt; or pipe via stdin, or --value)
based add "Supabase service-role key (acme-prod)"

# Register the agent identity WITH its keypair, then grant by name.
# ci-bot.key.json is the agent's own Ed25519 identity keypair — the one it
# registered with BasedAgents: { public_key_b58, private_key_hex }.
based identity add ag_7xKpQ3... --name ci-bot --keypair ./ci-bot.key.json
based grant "Supabase service-role key (acme-prod)" ci-bot --expires 7d --max-uses 100

# Run a command as the agent. `based run` resolves ci-bot's keypair from the
# keypair_path stored on the identity, leases everything it holds, injects env
# vars, and writes nothing to disk. Leases die with the process or their TTL.
based run --agent ci-bot -- npm run deploy
```

软件包也是 TypeScript 库—— 相同的 `Keyring` 类 CLI 使用:

```ts
import { Keyring } from '@basedagents/keyring';

const keyring = Keyring.open();
const lease = await keyring.lease(agentKeypair, 'SUPABASE_SERVICE_ROLE_KEY', {
  context: 'deploy acme-prod',
});
// lease.value in memory only; lease.expires_at ≤ 900 s out; lease.access_event_id signed
```

## MCP 设置

MCP服务器在代理商自身身份下给予克洛德代码,克洛德桌面,Codex,和Cursor租赁访问权限. 添加为 `claude_desktop_config.json`数字 :

```json
{
  "mcpServers": {
    "keyring": {
      "command": "npx",
      "args": ["-y", "--package=@basedagents/keyring", "basedagents-keyring-mcp"],
      "env": {
        "BASEDAGENTS_KEYPAIR_PATH": "/home/you/.basedagents/agent-keypair.json"
      }
    }
  }
}
```

使用绝对路径 `BASEDAGENTS_KEYPAIR_PATH`; 领先 `~` 但JSON Config中一条绝对的道路是明确的.

已曝光的工具 :

| 工具 | 对 |
| --- | --- |
| `keyring_list()` | 证书,该代理持有赠款,仅用于标签和元数据,永远不计值 |
| `keyring_lease(ref, context?, ttl_seconds?)` | 验证授权, 签署 AccessEvent , 返回带有 TTL 元数据的秘密和访问事件 ID |
| `keyring_request(provider, scope?, note?)` | 创建待决的补助金申请,供所有者批准 |
| `keyring_whoami()` | 此服务器代理身份 |
| `invite_owner(email)` | 代理-第一条目:向一个人发送邀请,请他拥有该代理(72小时期满,每名代理3天)。 直到他们通过跑步来声称 `init` 在他们自己的机器上, 代理可以持有什么 和进入什么 |

代理键盘来自 `BASEDAGENTS_KEYPAIR_PATH` \[杰森: `{ "public_key_b58", "private_key_hex" }` 或者说 `{ "publicKey", "privateKey" }` 或从 `BASEDAGENTS_PRIVATE_KEY_HEX` + 键 `BASEDAGENTS_PUBLIC_KEY_B58`。 。 。 .

## CLI 参考

| 命令 | 对 |
| --- | --- |
| `based init` | 登入的一号命令:金库+代理身份+MCP配置+浏览器链接(参见快速启动); `--bare` 只用于金库 |
| `based connect <provider>` | Mint 代理机的可瞄准范围提供者密钥——浏览器一次设置提供,仅限API后(vercel, supabase;); `--project <ref>` 选择 Supabase 项目) |
| `based rotate <cred>` | 薄荷一新供货商的密钥,将其换入金库(重新封给每个活跃的受赠者),由id来烧旧的一款——只使用API,只使用薄荷密钥 |
| `based add <label>` | 添加证书 — 隐藏快取、 stdin, 或 `--value` |
| `based update-secret <cred>` | 替换一个秘密( 如在人工旋转后); 重封给所有者 + 活跃的受赠者 |
| `based rm <cred>` | 删除证书及其所有赠款 |
| `based identity add <agent_id>` | 登记代理人身份(`--name`, (中文(简体) ), `--keypair` 路径) |
| `based identity rm <agent>` | 删除身份( 必须不持有活动赠款) |
| `based identities` | 列出已知身份 |
| `based grant <cred> <agent>` | 授予证书 -- `--expires 7d|ISO`, (中文(简体) ), `--max-ttl s`, (中文(简体) ), `--max-uses n`, (中文(简体) ), `--project tag` |
| `based revoke <grant_id>` | 取消赠款:无新租约,已密封副本被删除 |
| `based kill <agent>` | 杀死开关: 取消所有身份证书 |
| `based agents` | 代理视图:赠款、最后准入、租赁清点 |
| `based credentials` | 全权证书观点:谁持有什么,上次租赁时持有什么 |
| `based requests` | 待处理的补助金申请 |
| `based approve <req> --credential <cred>` | 核准针对现有证书提出的请求 |
| `based deny <req>` | 拒绝请求 |
| `based timeline` | AccessEvent 流,可按代理过滤,证书,类型,项目和时间范围(自/至) |
| `based export` | 导出已签名的访问日志( E)`basedagents-keyring-log/v1`(中文(简体) ) |
| `based verify-log` | 校验散列和每个事件签名离线 |
| `based run [--agent ref] [--keypair file] [--context c] [--ttl s] -- <cmd...>` | 租赁所有赠款, 注入 Env vars , 运行命令; 磁盘上没有 |
| `based admin [--port]` | 启动本地管理 UI |
| `based mcp` | 运行 MCP 服务器( 和 `basedagents-keyring-mcp`(中文(简体) ) |
| `based link [--api url] [--yes]` | 锁定您的主控控制台的密码作为本地机关的根——您确认指纹 |
| `based sync [--api url] [--watch [s]]` | 调取控制台核准的赠款,用固定的钥匙重新核实,密封,并确认退款(空白) `--watch` 每5次投票) |

每个命令都接受 `--dir` 指向一个非默认的金库.

## 安保模式

-   **密封箱.** 秘密被加密客户端到Ed25519身份密钥: Ed25519 → X25519 (edwards ToMontgomery),HKDF-SHA256密钥衍生出,XChaCha20-Poly1305版本格式. 给受赠者的公用钥匙重新封存秘密.
-   **只有密码的商店.** `vault.json` 包含被封存的盒子, 绝不是正文 。 磁盘上唯一的私人密钥是所有者(`owner.json`,模式0600.
-   **已签名的访问事件 .** 每一份租约——以及每一份被拒绝的租约——都是由Ed25519签字的,sha256 大麻链式AccessEvent。 每个签名绑定事件链位置,事件类型,以及金库ID,所以 `based verify-log` 检测编辑、重排、复制、再贴标签和横断层图案。 拖曳的删除被本地主锚所捕获,并且最终被保留下来的签名出口所捕获——可探测,并非不可能。 出口由所有者签名.
-   **租赁,不是副本.** 秘密以900秒的默认 TTL 为内存发送, 由每笔赠款夹住 `max_lease_ttl_seconds`。没有写入磁盘.
-   **撤销决定是而且不是.** `based revoke` 即时在金库一侧:没有新的租约,身份封存的副本被删除,因此秘密无法从金库文件中找到. 未偿租约在TTL内到期(违约时为15分钟)。 撤销了 **没有** 在提供者处旋转或删除密钥——在v0.1中,该步骤是手动的. 如果一个密钥已经泄漏,请向上旋转 。 自动提供方-侧烧伤为v0.2提供方.
-   **开关.** `based kill <agent>` 取消每个身份都包含在一个操作中,有相同的语义和相同的警告.
-   **控制台审批在当地重新核实.** 在主机控制台上核准的补助金,只有在守护进程核实所有者对一个控制台的密钥主张之后才能适用 **本地锁定** 密码`based link`)取而代之,为被赠人取出公用钥匙,证书,受之所限. 控制台从不为权威或保密而信任.

凝固威胁表:

| 威胁 | 缓解 |
| --- | --- |
| 被迅速注射的特工会泄露一个秘密 | 范围密钥, 15分租赁, 签名的 AccessEvent 代理名; 杀死开关 |
| 通过另一个进程读取的默认文件 | 仅加密文本; 打开需要指定的私钥 |
| 坦佩雷访问日志 | Hash 链条+每个事件签名; `based verify-log` |
| 窃取的私人密钥 | 杀开关: 全部赠款死亡, 封存副本被删除 |
| 压缩主机控制平面 | 守护进程重新验证对锁定的密码的核准; 密封目标替换更改所签名的散列并被拒绝; 密码从不离开机器 |
| 所有者设备折中 | 范围外——相当于在任何金库中采用主语的折中办法 |

## 管理 UI

`based admin` 启动仅本地主机、 以符号认证的网络服务器 :

-   **探员** - 每一个身份,它的赠款,最后的准入,14天的租赁火花,杀死开关
-   **全权证书** ——反向指数:谁持有每把钥匙,当他们最后一次租赁时
-   **时间线** ——带过滤器的 AccessEvent 流
-   **核准** ——待决 `keyring_request`s, 在一击中批准或拒绝

加一个签名的日志导出按钮(格式与 `based export`) (中文(简体) ).

## 托管控制台(任何地方的批准赠款)

带有可选主机控制台的本地金库对 [应用软件](https://app.basedagents.ai/): 签入的密码, 审查你的代理人要求的全权证书,并批准每份证书中 密码签名,从你的手机 如果你在那里。 守护进程留下 执行点; 控制台是投影和请求队列.

一次性设置 :

```bash
based init                       # if you haven't already
# 1. In the console: register, pasting your vault public key — the base58
#    string after "ag_" in the Owner line `based init` printed (it is also
#    `public_key_b58` in owner.json).
# 2. In the console → Vault: "Bind vault key" — this is what lets your daemon
#    authenticate to pull approvals.
based link                       # 3. anchor the console passkey(s) locally —
                                 #    CONFIRM THE FINGERPRINTS match what you registered
```

每日环路 :

```bash
# In the console: delegate your agent (Agents tab), then approve its requests
# (Approvals tab) with your passkey.
based sync                       # pull approved grants, verify, seal, confirm
based sync --watch               # or keep a loop running (polls every 5s)
```

是什么使这个安全(`CONTROL_PLANE.md` 拥有全权模式:

-   **控制台从不看秘密.** 封印只发生在守护进程; 控制飞机存储元数据 和赠款记录,密码文本从来没有.
-   **守护进程重新验证每一个批准** 对着你的钥匙 与 `based link` - 不是同步时间获取的密钥 。 签名的签注 受赠者的公用钥匙、证书和限制 被替换, 散列改变和守护进程拒绝封存 .
-   **控制台显示只有在您的守护进程确认后, 捐赠才会生效 .** 受损的控制飞机可以拖延或放弃赠款;它不能伪造赠款, 改变它的封口目标,或者读任何东西.
-   **恢复会轮换权威 永远保密.** 失去你的钥匙是 可用您的账户电子邮件加一次性恢复代码( 生成) 放在控制台里 —— 瓦尔特, 把它停机。 恢复注册为新密码 并废除所有其他——然后重新运行 `based link` 以锁定新的一个. 你的金库钥匙和密码都未受影响.

## 断层布局和环境变量

```
~/.basedagents/keyring/
  vault.json     identities, credentials (ciphertext only), grants, requests
  events.jsonl   append-only hash-chained AccessEvent log
  owner.json     owner keypair (0600)
```

| 变量 | 对 |
| --- | --- |
| `BASEDAGENTS_KEYRING_DIR` | 默认目录 `~/.basedagents/keyring`; CLI 数据 `--dir` 赢) |
| `BASEDAGENTS_KEYPAIR_PATH` | MCP 服务器的代理 keypair 文件 / `based run` |
| `BASEDAGENTS_PRIVATE_KEY_HEX` + 键 `BASEDAGENTS_PUBLIC_KEY_B58` | 内置代理密钥pair, 文件的可选选项 |

## 路线图

-   **主控控制台——已运出.** 所有者账户有密码授权,远程审批(`based link` 编号 : `based sync`),代表团,金库绑定,收回账户. 见 [主机控制台](https://npmcn.com/package/%40basedagents/keyring/#readme-hosted-console-approve-grants-from-anywhere) 上文及 `CONTROL_PLANE.md` 在权威模式的回波根。 账单待付.
-   **供养者.** Mint, 旋转, 并通过版本的开源食谱在提供者自己处刻入密钥( API- first, 浏览器倒置; 食谱库运入) `@basedagents/recipes`页:1 切断连接到供方烧伤的开关 第一种食谱:Vercel,Supabase,Railway,Neon,GitHub PAT.
-   **共用地库.** 加密密码文本同步,旋转食谱,OAuth刷新托肯管理,团队拨款.

完整规格 : [关键位置( S) md](https://npmcn.com/package/KEYRING_SPEC.md)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @basedagents/keyring 是什么？

范围化,可撤销的证书,以加密代理身份为约束——本地首个加密金库,身份约束赠款,短期租赁,签名访问日志 BasedAgents部分,AI代理的任务市场\.注意：该包已被作者标记为弃用——Keyring has been retired; BasedAgents is the task marketplace for AI agents — see https://basedagents\.ai and npm: basedagents

### 如何安装 @basedagents/keyring？

在项目目录运行 npm install @basedagents/keyring，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 based、keyring、basedagents-keyring-mcp，可以用 npx based 直接运行。

### @basedagents/keyring 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @basedagents/keyring 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @basedagents/keyring 可以商用吗？

@basedagents/keyring 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @basedagents/keyring 的下载量有多少？

根据 npm 官方下载统计，@basedagents/keyring 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,174 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @basedagents/keyring 还在维护吗？

最新版本 0\.6\.10 发布于 2026/09/23（1 个月前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/07/16。作者已将其标记为弃用，新项目建议寻找替代方案。