API Key Case

API Key Case

把工作交给 AI 编码 Agent，而不是密钥。 API Key Case 会在本地扫描项目，报告可能的密钥处理风险，并为 Claude Code、Codex、Cursor 等工具生成经过脱敏的上下文。密钥值存储在操作系统的密钥存储中；Pro deploy 会通过 Cloudflare、Vercel 或 GitHub 的官方 CLI 将密钥值部署到相应平台——密钥值绝不会被返回、打印或记录到日志中。

README 的日语版见 README.ja.md。

本 README 介绍的是 v0.9.2 稳定版发布候选版本。 @latest 遵循 npm 已发布的 dist-tag，在分阶段发布期间可能会滞后。使用其 Agent 工作流前，请确认确切的 0.9.2 版本包已可用；发布检查清单记录了各项门槛和验收证据。

这款预稳定版工具可降低意外暴露风险，但不保证密钥得到全面保护。分享生成的文件前，请务必检查。

不保证绝对安全。本工具旨在降低意外发生的概率。将生成内容交给 AI 或外部服务之前，请务必亲自检查。

网站 · 操作系统支持状态 · npm · 更新日志 · 安全 · 支持 · 条款 · 隐私 · 品牌与第三方声明

快速开始

常规的 Agent 优先支持基线为 Windows 11 并启用 Windows Hello。 macOS 属于协作验证版本：其实现、当前 CI 和真实 Keychain 证据均已具备，但原生 GUI 审批、辅助功能防护、Intel 硬件以及在真实 Mac 上部署到服务提供商的功能仍未经验证。 macOS 验证仍在进行中；请勿因 macOS deploy 功能而购买 Pro。请参阅操作系统支持状态 和 macOS 验证计划。

Windows、macOS 或 Linux 需要 Node.js 20 或更高版本。在 Windows 上，v0.9.1 中的高风险审批、remove 和 trust forget 要求 Windows 11 build 22000 或更高版本，并且该账户已设置 Windows Hello（PIN、指纹或面部识别）； 对于 Windows 10 和未设置 Hello 的账户，这些操作会安全失败并交由人工处理，但扫描、保管库和密钥输入功能仍可使用。 由于 deploy 是付费功能，请在购买前确认这一点。Linux 支持本地诊断、状态/历史记录，以及在操作系统密钥存储可用时由用户在终端中自行存储；不提供 Agent 优先输入、审批、执行 deploy，以及需要审批的密钥值/信任关系移除功能。Linux 密钥环后端的选择以及登录/重启后的持久性取决于具体环境。

已发布版本的基本命令可以单独试用：

# Scan the current project locally. Real .env contents are not read.
npx -y api-key-case@latest scan .

# Generate redacted context for an AI coding agent.
npx -y api-key-case@latest scan . --agent-report

# Save a value through a hidden interactive prompt.
npx -y api-key-case@latest save OPENAI_API_KEY

# Check status only. The value is never returned.
npx -y api-key-case@latest check OPENAI_API_KEY

切勿将真实密钥放在命令参数、Issue、聊天消息或生成的报告中。由用户自行操作的终端会保留隐藏提示；Agent 优先使用时，必须请求 save --ask，并且只在 Human Plane 对话框中输入密钥值。

从当前的 .env 开始

你可以注册已在使用的密钥，而不让 Agent 读取 .env。只需确认 Secret 名称，自行打开文件，并将其中的值复制到 Human Plane。这不是自动导入：API Key Case 不会删除、同步、替换或以其他方式更改原始 .env，因此你可以在需要时继续使用它。注册可以作为任务的终点；部署是单独的步骤。

扫描器目前可识别 .env.example 以及常见的 JavaScript/TypeScript 引用。其他语言中的名称未被识别，或语法不受支持，并不意味着 Secret 没有必要：只要知道名称，你仍然可以直接保存或检查它。存储没有部署环境这一维度，因此同一个项目/名称无法同时保存不同的开发环境和生产环境值；请选择一个值进行注册，并避免意外覆盖现有条目。

部署还有其他服务提供商/项目方面的限制。具体来说，如果 Wrangler 项目同时存在真实的 .env、.env.*（不包括 .env.example）、.dev.vars 或 .dev.vars.* 文件，Cloudflare Agent 优先部署会因 API Key Case 的安全条件而停止，因为 Wrangler 可以加载这些文件。这不是登录或 Free 计划导致的失败：本地 Secret 注册仍可进行，且 API Key Case 不会修改该文件。购买 Pro 前，请先运行 Free 就绪情况诊断。

Agent 优先的控制平面与人工平面（阶段 A/B/C/D/E）

以下命令需要 v0.9.2。使用前请确认 npx -y [email protected] --version 的结果为 0.9.2。在 npm 列出该确切版本之前，请按 候选版本测试 中所述使用已安装的候选 tarball。

api-key-case agent-init .          # print the session protocol and manage existing host instructions
api-key-case agent-init . --check  # no-write drift/symlink safety check
api-key-case agent-init . --host agents # explicitly create AGENTS.md in a fresh project
api-key-case next --json .         # closed semantic status and nextActions
api-key-case save OPENAI_API_KEY --ask # separate Windows/macOS Human Plane
api-key-case history --json .      # Free: past deploy results, never current values

agent-init 会保留其管理区块以外的内容，只在项目内写入，拒绝符号链接/目录联接，并且不会编辑全局配置或 MCP 配置。持久化指令会固定运行 agent-init 的确切版本（例如 [email protected]），绝不使用 @latest 或浮动的主版本系列；这样可避免后续的稳定版发布前小版本在没有明确重新运行 agent-init 的情况下，改变现有仓库的 Agent 协议。

next --json 只返回封闭枚举以及名称/状态。它不包含 command、argv 或自由格式的执行字段，也绝不会包含 Secret 值、部分值、根据值生成的哈希或值的长度。对于 actor: "human"、kind: "register-secret"，确切版本的 Agent 协议会请求执行 save <NAME> --ask；值只会在单独的 Human Plane 中输入，返回给 Agent 侧的也只有状态。

Schema 2 新增 Free 就绪情况和项目设置摘要，供你现有的编码 Agent用你的语言进行说明。setup.stage 和 setup.counts 会显示已注册、缺失和需要处理的内容。host 描述输入/批准要求；每个目标的 readiness 会使用与执行部署相同的可信 CLI/配置规则检查其环境，不会放置 Secret 或打开对话框。环境阻碍项与 license.plan 分开；购买 Pro 无法解决不受支持的主机问题。prerequisites-checked 仍不代表已验证人工交互和服务提供商写入权限；部署始终会重新检查自身边界。本地注册不等于远程部署：setup.deploymentState 仍为 not-inspected。 Agent 会对缺少名称的项目进行归组，依次打开现有输入对话框，准备请求的目标位置，并汇总实际操作结果。取消或失败会停止该组操作；不会创建可重复使用的审批或批量审批。服务提供商登录、密钥签发、购买／许可证激活和 OS 验证仍需由人工完成。对于全新的仓库，当前 Agent 可以明确使用 agent-init --host agents、--host claude 或 --host cursor；这只会创建对应主机的项目说明，并执行相同的路径／偏差检查。不指定 --host 时，只使用现有的主机标记。请参阅设置约定。

next --json 中的每个目标还包含一个 deployment 区块：automatic 列出 Agent 当前可在其中部署、无需人工交互的环境，humanApproval 列出其余环境，destinationTrust 则报告本项目的目标位置是 trusted、unconfirmed、changed、unresolved 还是 not-applicable。目标位置未确认或已更改时，会添加一个 actor: "human"、kind: "approve-deploy-destination" 操作。Agent 会转达该操作，但绝不能代替人工完成审批。

在 Windows 和 macOS 上，Phase B 密钥输入与 Phase C 高风险审批使用不同的 OS 对话框。在已设置 Windows Hello 的 Windows 11 build 22000+ 上，计划对话框中的 Yes/Delete 按钮只会启动 IUserConsentVerifierInterop::RequestVerificationForWindowAsync；只有 OS 返回 Verified 才会批准，其他所有结果都会安全失败。Linux、Windows 10、未设置 Hello 的账户、无头会话，以及无法验证固定系统助手程序的主机，都会改为移交处理。没有由 Agent 管理的 PTY 回退方案。生产环境、GitHub、Vercel 开发环境（可由服务提供商读取）、破坏性／可覆盖操作及其他高风险计划都需要经过此边界。Phase C 会将已验证的决定绑定到单个进程内执行快照。

Phase D 增加了该边界的目标位置部分。每次实际执行的部署都会绑定到一个目标身份（Destination Identity），包括固定的项目 realpath、目标、环境、用于选择目标的仓库配置，以及通过同一可信 CLI 和经过净化的环境解析出的服务提供商账户身份。人工确认一次操作后，该身份会记录在 OS 密钥存储中；首次使用或身份发生任何变化时，都会重新经过人工管控层（Human Plane）。此后，只有在已确认的目标位置上、处于 project 范围内且未使用 --force 的 Vercel preview，才能在不再次询问的情况下重复部署。

过往部署结果

开始新的聊天或恢复部署任务时，Agent 也会读取 history --json。 它会报告过往的 completed、incomplete 或 unknown 操作。失败的 --force 可能已经更改了提供方；中断或未保存的结果仍然未知。 较晚的注册时间戳表示发生过更新，但时间戳相同且目标位置一致，并不能证明当前值相同。 历史记录不代表已获批准或可信，也不会触发自动重试或自动重新部署。

本地元数据文件 ~/.api-key-case/deployment-history/ 会保留每个项目最近 200 次尝试。 其中包含名称、范围、目标/环境、仅用于标识目标位置的标识符，以及操作时间戳/结果；不包含值、 部分值、值的哈希或长度，也不包含提供方输出。没有部署正在运行时，你可以明确删除该目录（或某个项目的子目录） 以丢弃历史记录；已存储的值和目标位置的信任状态相互独立。历史记录缺失或无法读取时，状态为未知。 保存开始记录失败时，会在写入提供方之前阻止操作；保存结果失败时，即使部署成功，也会发出警告。 请停止操作并商定剩余工作，而不是自动重复该操作。 历史报告架构 2 会区分日志缺失与锁定、数据无效、访问受限及其他关闭失败代码，并为 Agent 提供恢复指引。 锁可能属于正在运行的操作，并不能证明发生了崩溃。检查成功并不代表写入权限正常。 开始记录失败会明确指出本次调用未向提供方写入任何内容；结果保存失败则会保留实际操作结果。 解决原因后，请重新检查，并明确决定是否丢弃元数据或重新部署。不会自动删除现有锁或历史记录来进行恢复。 现有日志文件仍采用架构 1。 请参阅历史记录约定。

演示

观看 28 秒的工作流示意图（日语字幕和音频）——Agent 引导完成 GitHub Secret 设置，同时由人工通过专用界面输入并批准该值。

这是合成的示意图，并非真实凭据部署的现场录制，其中不含真实密钥。旧版 CLI 演示生成器仍保留在 demo/ 中供参考，但其旧录制内容不属于当前网站或 npm 包。

功能

• 检查 .env 和 .env.* 是否已被忽略。
• 检测对环境变量文件的当前和历史 Git 跟踪情况，包括嵌套文件。
• 从 .env.example 和常见代码引用中查找必需的环境变量名称。
• 报告可能的密钥值，但不会复现源代码行或值本身。
• 生成值为空的 .env.example。
• 为 AI 编码 Agent 生成 AGENT_CONTEXT.safe.md 和 AI_SAFE_PROMPT.md。
• 支持 JSON 输出和严格的 CI 退出代码。
• 将密钥值存储在操作系统的密钥存储中（Keychain / Credential Manager / Linux OS keyring），并且只报告已注册/缺失状态，绝不显示值本身。

扫描器核心不会读取真实 .env 文件的内容，也不会发起网络请求。目标命令完成后，如果启用了遥测功能，可能会另行发送匿名使用事件（尽力而为）；扫描数据绝不会传递给该模块。

匿名使用情况遥测

CLI 使用一个受隐私限制的 PostHog 事件 cli_command_result 来辅助制定产品整体决策。此事件仅在 scan、save、license_activate 和 deploy 时发送，包含固定上下文 product: api_key_case、surface: cli，以及命令、结果、CLI 版本、操作系统系列等封闭值；对于 deploy，还包含允许列表中的目标。事件绝不包含机密值或名称、环境变量名称、路径、扫描发现、argv、项目或许可证信息，也不包含原始终端输入。

遥测默认启用，但首次符合条件的交互式命令会在发送任何内容之前显示一次性通知。v0.9.1 发行版构建包含 API Key Case 的公开 PostHog Project Token，因此此构建无需用户提供遥测令牌。API_KEY_CASE_POSTHOG_PROJECT_TOKEN 仍可用于开发、测试或覆盖；只要其值非空，就会优先使用。此软件包绝不包含 Personal API Key 或 Project Secret API Key。没有发行版令牌的自定义构建会安全地不执行任何操作。非交互式运行会在显示通知前抑制遥测；在 CI 中或设置了 DO_NOT_TRACK=1 时，也始终会抑制遥测。PostHog 故障和超时会被忽略，因此不会影响命令结果。匿名安装 ID 是一个随机值，仅存储在 ~/.api-key-case/telemetry.json 中；它并非根据机器、用户、仓库、许可证或硬件生成。

api-key-case telemetry status
api-key-case telemetry enable
api-key-case telemetry disable

disable 会停止遥测并删除匿名安装 ID。之后重新启用时会创建新的 ID。完整的事件约定和解读规则见 docs/analytics/MEASUREMENT.md。

它不会做什么

• 它不会替你获取 API 密钥。它不会集成登录 Cloudflare、Vercel、OpenAI 或其他服务来获取或生成凭据——你需要从提供方获取该值，并手动输入一次。
• 它不会取代 wrangler、vercel 或 gh。deploy 会运行你已安装并登录的实际 CLI；如果缺少某个 CLI，它会显示手动操作步骤，而不会安装该工具或尝试绕过任何问题。
• MCP 不会完成 production 或 GitHub 部署，也没有审批参数或征询路径。高风险 CLI 部署需要使用独立的 Human Plane；由 Agent 控制的 stdin/PTY 输入无法批准这些部署。
• 它不保证机密始终保密。请参阅安全模型和局限性，了解它实际能保护的内容以及无法保护的内容。

机密存储（save / check / list / remove）

机密有两种本地存储路径。在由人控制的终端中：隐藏式提示词 → 本地 CLI 进程内存 → 操作系统机密存储。在 Windows/macOS 的 Agent 优先使用场景中：Human Plane 密码对话框 → 经净化的固定路径辅助进程内存 → Credential Manager/Keychain。辅助进程会直接写入，仅向父进程返回状态。macOS 辅助进程会在同一个 /usr/bin/osascript 进程中调用 Security.framework；它不会调用 security CLI，也不会启动包含值的子进程。这两种路径都不会打印、导出、记录或将该值写入文件，也都不会通过 argv 或管道 stdin 接收该值。

api-key-case save OPENAI_API_KEY          # prompts for the value (hidden input, TTY required)
api-key-case save OPENAI_API_KEY --ask    # Windows/macOS Human Plane; Agent-side stdin is ignored
api-key-case check                        # status of every secret referenced by scan
api-key-case check OPENAI_API_KEY --json  # status of one secret
api-key-case list                         # names and metadata only, never values
api-key-case remove OPENAI_API_KEY        # deletes from the OS secret store (Human Plane decision)

选项：

--scope user|project   Store per-machine (user) or per-project (project, default).
--force                (save) overwrite an existing secret without the confirmation error.
--ask                  (save) request Agent-independent Human Plane Secret input.
--json                 (check, list) machine-readable output.
--strict               (check) exit with code 2 when one or more secrets are missing.

只有在人工通过与高风险部署相同且独立于 Agent 的 Human Plane 对话框进行确认后，remove 才会删除值。此操作没有 --yes 参数，也不接受通过 stdin 确认，因此无法由控制此进程终端的 Agent 完成删除。如果无法使用该对话框，remove 会安全地拒绝操作，并提示使用操作系统机密存储自身的用户界面。

退出代码 3 表示该操作没有可用的操作系统机密存储。在 Linux 上，当前的密钥环依赖项可能会从 Secret Service 回退到内核 keyutils。仅缺少 D-Bus 并不意味着会返回此退出代码，而且 available 状态并不能证明登录或重启后数据仍会保留。请参阅已观察到的存储限制。

部署密钥（deploy / targets）—— Pro 功能

deploy 会通过 Cloudflare、Vercel 或 GitHub 各自的官方 CLI（wrangler、vercel、gh），将已通过 save 保存的值发送到相应平台——绝不直接调用 API。对于 check/hasSecret，OS 密钥存储的读取结果会立即简化为布尔值；不会返回、存储或记录该值。执行 deploy 时，该值唯一保留的路径是：OS 密钥存储 → 此 CLI 读取一次 → 写入目标 CLI 的 stdin → 丢弃。该值绝不会出现在命令行参数、环境变量、临时文件或日志行中，并且捕获的 CLI 输出会先清除该值，再进行打印。

deploy（包括 --dry-run）是一次性购买的 Pro 功能。免费版涵盖 scan、save、check、list、remove、targets、agent-init、next、history、 trust status、trust forget，以及除 deploy_secret 以外的所有 MCP 工具。 免费访问不绕过主机／审批条件。请参阅下文的许可。

api-key-case targets                                    # what's detected here, and is each CLI installed/logged in?
api-key-case deploy OPENAI_API_KEY --target cloudflare   # development env by default
api-key-case deploy OPENAI_API_KEY --target vercel --env preview
api-key-case deploy OPENAI_API_KEY --target cloudflare --env production --dry-run

选项：

--target <cloudflare|vercel|github>   Required. This is a closed list; no other target is supported.
--env production|preview|development  Default: development. production is never the default.
                                      On github this also decides repository vs environment
                                      secret — see "What each platform does" below.
--scope user|project                  Default: project. Does not fall back to user if not found there.
--dry-run                             Show the plan and stop before reading the value or running anything.
--force                               Vercel only: remove an existing value first, then add the new one.

部署到 production、每次部署到 github、Vercel development（提供方可读取）、每次 --force 操作、每次 --scope user 部署，以及可能覆盖现有值的提供方操作，都需要独立于 Agent 的 Human Plane。在已设置 Windows Hello 的 Windows 11 build 22000+ 上，固定路径的 PowerShell 计划对话框之后会进行与 HWND 绑定的 OS 用户验证，只有 Verified 才会批准。现有的 macOS AppKit 对话框保持不变。审批和执行仍在一次调用中完成。Linux、Windows 10、未设置 Hello 的账户，以及不可用／无头的 Human Plane 会话都会以移交给人工的方式安全失败，而不会接受 stdin 或可重复使用的令牌。

其他所有操作都需要使用人工已确认的目标位置。Vercel preview 是唯一可能在不询问的情况下重复执行的操作类别，但必须处于 project 范围且不带 --force，并且仅当其 Destination Identity 未改变时才可重复。Cloudflare 不在此范围内，因为 wrangler secret put 总是会覆盖；GitHub 也不在此范围内，因为 GitHub 密钥在任何 --env 下都可由 CI 访问。

每次实际执行的部署都需要一个明确的本地目标位置：一个包含 name 和 account_id 的 Wrangler 配置文件、包含组织和项目 ID 的 Vercel .vercel/project.json，或具有唯一明确的 origin 远程地址（位于 github.com）的 GitHub 仓库根目录。对话框会显示该目标位置、这是首次使用还是自上次批准后已发生变化、固定的提供方身份、cwd、CLI 路径、环境、命令以及破坏性预处理步骤。状态有歧义或发生变化时会拒绝操作。Windows 会根据注册表状态独立解析受信任的 CLI／配置文件；macOS 使用 OS 用户数据库和一个封闭且识别架构的常见安装位置集合。两者都会传入全新的净化环境，并固定／重新检查确切的 CLI；对于使用 Node shebang 的提供方 CLI，macOS 还会固定确切的 Node 运行时。Linux 目前会移交部署执行，并打印手动完成提供方操作的步骤。

如果目标的 CLI 未安装或尚未登录，deploy 会打印供你自行执行的手动步骤，而不会猜测或替你安装任何内容。

查看已确认的目标位置（trust）

api-key-case trust status                                 # which destinations you confirmed here
api-key-case trust forget --target vercel --env preview   # make it ask for approval again

trust status 为只读操作。trust forget 会通过同一个 Human Plane 对话框删除确认记录；这只会导致下次部署再次请求审批，绝不会授予审批。只有可在不询问的情况下重复执行的操作类别才会记录任何内容，因此列表本来就很短。

各平台如何处理之后的值

交接后，值将遵循平台自身的规则，而非此工具的规则：

• Vercel 的 --env development 值可以读取。 deploy 不会在此处传递 --sensitive，因此 vercel 会将其存储为 Config 变量：任何有权访问该项目的人都可以通过 vercel env pull 读回该值，并将其写入本地 .env 文件。如果你希望某个值始终不可读，请勿将其放入 development。较旧版本的 Vercel 会直接拒绝在 development 中使用敏感变量；在 vercel 59.11.7 中，该标志在此处会被接受（测量日期：2026-09-08），因此这现在是此工具自身采取的保守默认设置，而非服务提供商的限制。对于 production 和 preview，deploy 会自行传递 --sensitive，而不是依赖 Vercel 的默认设置，因此该值会以只写方式存储，无法读回——每次部署前显示的计划都会包含此标志。preview 还会传递 --yes，该参数会采用 CLI 文档中说明的默认选项来回答其 Git 分支问题，即每次都使用 Preview 分支；如果不传递此参数，非交互式运行会停在该提示处，并在未创建任何内容的情况下成功退出。（如果 vercel CLI 版本太旧、不识别这些标志，部署会失败，而不会悄悄存储可读取的值。）
• Cloudflare 会将其存储为 Worker 密钥（secret_text）——之后无法读取，只能覆盖。
• GitHub 会根据 --env 的值，将其存储为两种不同类型之一。development（默认值）会写入仓库密钥，可供该仓库中的所有工作流使用。production 和 preview 会写入同名 GitHub Environment 下的环境密钥，只有声明了 environment: <name> 的作业才能读取——而且该环境必须已在 GitHub 上创建，否则 gh 会失败。因此，在 GitHub 上，默认值的作用范围是三者中最广的，这与名称所暗示的恰好相反；每次部署前显示的计划都会说明即将创建哪种类型。两种类型之后都无法读回，只能覆盖。

许可（deploy）

诊断与就绪检查、Agent 设置、本地存储与信任管理，以及除 deploy_secret 之外的 MCP 工具，在各自支持的条件下均可免费使用。deploy（包括 dry-run）需通过 Lemon Squeezy 一次性购买 Pro 版后解锁，价格为 ¥2,980，并非订阅。购买包含 v0.9.1，以及 Pro v1（1.x 系列）内的更新；未来的主版本可能需要单独授权。

功能	免费版	Pro 版
本地扫描和已脱敏的 Agent 报告	✓	✓
OS 密钥存储（save / check / list / remove）	✓	✓
目标与就绪状态诊断、Agent 设置和信任管理	✓	✓
除 deploy_secret 之外的可选 MCP 工具	✓	✓
Cloudflare / Vercel / GitHub deploy，包括 dry-run	—	✓

一次购买仅供一人使用，可用于该用户自己的设备和项目。组织需为每位用户购买一份。退款申请可在 14 天内提交，详见退款政策。《使用条款》规定了官方 Pro 权益和服务。源代码的使用属于单独的授权层，由各版本随附的 LICENSE 规定。

api-key-case license activate     # interactive hidden input; argv and non-TTY input are rejected
api-key-case license status [--json]
api-key-case license deactivate

Lemon Squeezy 会通过电子邮件发送买家专属的购买密钥。license activate 会通过 HTTPS 将该密钥一次性发送到固定的 API Key Case 交换 Worker。Worker 会验证 Lemon 许可证、确切的商店／产品／变体，以及订单是否已付款且未退款，然后返回经 Ed25519 签名的 AKC1 许可证。CLI 会验证并存储该响应。此后每次 Pro 检查都在本地离线进行——不会重新验证许可证、绑定设备或检查有效期。这与上文所述、限制隐私影响且可选择退出的使用情况遥测相互独立。已退款的订单不能进行新的交换，但已离线存储的 AKC1 无法被远程撤销。

成功激活和状态输出会将通用权益标识为许可证，绝不会标识为订单：

OK: pro license activated (license ls_license_xxx).
plan: pro (license ls_license_xxx, issued YYYY-MM-DD)

签名后的 AKC1 载荷仍为 { "v": 1, "plan": "pro", "id": "...", "issuedAt": "..." }；经验证的进程内／JSON 状态会将该 id 值命名为 entitlementId。

API Key Case 0.9.1 产品代码以 Elastic License 2.0（Elastic-2.0）提供源代码。源代码、安全敏感实现、测试和设计记录仍然公开，便于检查其行为和边界；这并不代表项目已通过独立审计。Pro 权益和许可证密钥实现保持不变，且与源代码许可证相互独立。有关生成式指令、品牌和第三方材料的边界，请参阅 NOTICE；完整设计和威胁模型请参阅 docs/design/phase-5-license.md。

MCP 服务（可选，供 Agent 使用）

上面的 CLI 是主要接口。api-key-case mcp 还可启动一个 MCP（stdio）服务，直接向 Agent 主机提供相同的纯状态操作——秘密值绝不会通过 MCP 协议传输。

api-key-case mcp [path]   # path defaults to the current directory

使用客户端注册：

# Claude Code
claude mcp add api-key-case -- npx -y api-key-case mcp

// Cursor (mcp.json)
{ "mcpServers": { "api-key-case": { "command": "npx", "args": ["-y", "api-key-case", "mcp"] } } }

它提供 7 个工具：list_required_secrets、check_secret、save_secret、deploy_secret、generate_env_example、scan_secret_leaks、check_gitignore。save_secret 不接受值参数，也不会接触密钥库——它会返回固定的 save --ask Human Plane 操作。绝不会使用 MCP elicitation 来获取值。deploy_secret 不会完成 production 或 github 部署；它同样会将操作交给在终端中运行 api-key-case deploy 的人工人员。若没有有效的 Pro 许可证，deploy_secret 会返回正常（非错误）状态并指向购买链接，而不会执行部署。完整的安全边界请参阅 packages/mcp/README.md。

要求

• Node.js 20 或更高版本
• 建议使用 Git 进行跟踪和历史记录检查

开发环境检出

npm install
npm test
node dist/cli/index.js scan .

命令

api-key-case agent-init [path] [--check] [--host agents|claude|cursor]
api-key-case next --json [path]
api-key-case history --json [path]
api-key-case scan [path] [options]

agent-init 会初始化仅包含状态的 Agent 协议，并更新已识别的项目指令标记，或更新通过 --host 明确选定的当前宿主。--check 不会执行任何写入；如果缺少持久化内容或内容存在偏差，则以状态码 2 退出。next 必须使用 --json，并输出上文所述的封闭模式。

选项：

--json                Emit a machine-readable report.
--strict              Exit with code 2 when warnings are found.
--write-env-example   Generate .env.example with empty values.
--agent-report        Generate agent-safe context and prompt files.
--force               Replace generated files that already exist.

示例：

api-key-case scan .
api-key-case scan . --strict
api-key-case scan . --json
api-key-case scan . --write-env-example
api-key-case scan . --agent-report
api-key-case scan . --agent-report --force

默认情况下会保留生成的文件。只有提供 --force 时才会替换现有文件。

Agent 报告

--agent-report 会生成：

• .env.example：检测到的变量名及空值
• AGENT_CONTEXT.safe.md：变量名、使用位置和实现约束
• AI_SAFE_PROMPT.md：可复用的 AI 编码 Agent 提示词

生成的 Markdown 仅包含名称和文件位置，不包含机密值。请将每个生成的文件视为草稿，并在分享前进行审核。

退出代码

• 0：命令已完成；除非使用了 --strict，否则 check 可能会有警告或缺少机密项（已完成的 deploy --dry-run 也会返回 0）
• 1：命令、选项或路径无效；扫描失败；保存或移除被拒绝；操作在获批后发生变更；机密未注册以供 deploy 使用；或目标 CLI 出错
• 2：scan --strict / check --strict 发现警告或缺少机密项，或者 agent-init --check 发现缺少持久化内容或内容存在偏差
• 3：此系统上没有可用的 OS 机密存储（save、check、list、remove、deploy）
• 4：Human Plane Secret 输入已取消，或明确拒绝了高风险部署
• 5：未安装或未登录 deploy 目标的 CLI；可信 CLI/Human Plane 边界不可用；或者在写入提供方之前无法保存部署历史记录
• 6：deploy 需要 Pro 许可证（api-key-case license activate）

安全模型与局限性

• 发现项会使用 ***REDACTED***；不会显示源代码行和部分值。
• 实际环境文件会根据文件名和 Git 状态检查，而非检查其内容。
• 令牌检测采用启发式方法，仅匹配一组固定的已知密钥格式，并且只扫描特定文本文件扩展名（跳过 node_modules、dist、构建输出和超过 1 MB 的文件）——可能产生误报，也可能漏掉不熟悉的格式或未扫描的文件。扫描结果干净只表示“未发现明显问题”，不表示“其中没有任何内容”。
• Git 历史检查会检测环境文件名，而非所有历史上的秘密值。
• 恶意仓库可能包含误导性的源文本或文件名。将生成的上下文提供给 Agent 前，请先检查。
• 这不能替代 GitHub secret scanning、Gitleaks、TruffleHog、秘密管理器或凭据轮换。
• 一旦 deploy 通过标准输入将值交给 wrangler、vercel 或 gh，该值就进入了官方 CLI 自身的进程——其安全性取决于该 CLI 的日志记录和行为，而非本项目。输出清理仅覆盖返回给此 CLI 的内容，不涵盖目标 CLI 内部的行为。
• 本工具无法阻止他人通过操作系统秘密存储自身的界面（Keychain Access、Credential Manager 或 Linux 上的 Secret Service 前端）读取值，再手动粘贴或输入到聊天、工单或 AI 对话中——本工具只能封堵其直接控制的路径。
• 操作系统秘密存储的安全性取决于你的操作系统账户，以及操作系统密钥链所实施的应用级访问控制。本 CLI 依赖平台提供的保护，不会额外添加第二层保护。
• AKC1 Pro 许可证一旦兑换为离线使用，就无法远程撤销；退款只会阻止下一次兑换（参见许可证）。此离线许可证检查与匿名使用情况遥测的退出机制彼此独立。
• 如果真实凭据已提交或以其他方式泄露，只有在服务提供商处轮换该凭据才能消除泄露风险——扫描结果干净、删除文件都无法做到这一点。仅删除文件并不足够。
• 每次执行 deploy 时，都会冻结可信的绝对 CLI 路径和经过清理的环境；如果在启动子进程前，项目 cwd、目标配置、身份验证元数据、服务提供商环境变量是否存在、计划或 CLI 身份发生变化，就会中止。--dry-run 仍会使用普通的 PATH 解析，因为它不会运行任何程序。
• 高风险部署没有标志、标准输入审批、审批参数或可重复使用的审批凭据。如果 Human Plane 不可用，请改用平台自身的 CI 原生秘密注入机制。
• 目标信任记录不是审批。它只会在操作系统秘密存储中保存目标指纹，本身不授予任何权限，且永远不适用于 production、github、Vercel development、--force 或已发生变化的目标。也无法通过写入文件来创建此记录：任何能够直接调用操作系统凭据 API 的对象，都已处于本工具所依赖的操作系统账户信任边界之内。

如需了解凭据泄露时的报告指南、已知局限性以及应采取的措施，请参阅 SECURITY.md。

开发

npm test
npm run build
npm pack --dry-run

npm pack 会通过 prepack 生命周期运行完整的验证套件。

npm run test:package 会构建真实的 tarball，检查其文件边界，将其安装到一个不包含开发依赖的一次性使用者项目中，并测试可执行文件发现、新建 Agent 主机的设置、漂移拒绝和诊断。它还会审计该使用者项目的运行时依赖。添加 -- --offline 可使用缓存的软件包并跳过网络审计。

在已安装 dbus-run-session、gnome-keyring-daemon、dbus-send 和 gdbus 的 Linux 上，npm run test:keyring:linux 会创建一个一次性 D-Bus 会话和 XDG 数据目录。它会在严格检查真实操作系统存储的条件下运行完整套件，然后针对该存储验证已安装的 tarball。所有值都是合成的；不会替换用户现有的登录密钥环。这不会增加 Linux Human Plane／部署支持，也不会验证 Windows/macOS 对话框。请参阅验证记录。

本仓库有意在测试和演示样例中包含合成的金丝雀值，以便验证扫描器的脱敏行为。因此，根目录中的 npm run scan 可能会报告这些样例产生的预期警告；请勿削弱扫描器，也不要添加宽泛的跳过规则来消除这些警告。在将问题视为发布阻断项之前，请检查相关路径并确认它们仅用于测试。

许可证兑换 Worker 环境

测试和正式兑换服务使用单独的 Wrangler 文件、Worker 名称、密钥和速率限制命名空间。LEMON_TEST_MODE 由各自的文件固定设置，不作为密钥输入。只能输入与对应 Lemon 模式匹配的值；请勿在正式环境中重复使用测试环境的商店／产品／变体 ID，反之亦然。

# Test secrets (repeat for LEMON_PRODUCT_ID, LEMON_VARIANT_ID,
# LEMON_API_KEY, and AKC_ED25519_PRIVATE_KEY)
npx wrangler secret put LEMON_STORE_ID --config workers/license-exchange/wrangler.test.jsonc
npx wrangler deploy --dry-run --config workers/license-exchange/wrangler.test.jsonc
npx wrangler deploy --config workers/license-exchange/wrangler.test.jsonc

# Live secrets (repeat for the same five names, using live Lemon values)
npx wrangler secret put LEMON_STORE_ID --config workers/license-exchange/wrangler.live.jsonc
npx wrangler deploy --dry-run --config workers/license-exchange/wrangler.live.jsonc
npx wrangler deploy --config workers/license-exchange/wrangler.live.jsonc

测试 Worker 为 api-key-case-license-exchange-test；正式 Worker 为 api-key-case-license-exchange。只有已部署的正式 HTTPS 端点可以替换已发布 CLI 中的 LICENSE_EXCHANGE_URL。完整的设置矩阵和所有密钥命令，请参阅 workers/license-exchange/README.md。

状态与路线图

当前源代码候选版本：v0.9.2（预稳定版）。此前的 v0.9.1 版本已于 2026-09-14（JST）在 npm 上发布。安全修复仅针对最新发布的预稳定版本提供。代码补全和可移植测试并不能证明其已获真实 Agent 主机、Windows/macOS 对话框或服务提供商账户的认可。请参阅发布检查清单、验证记录和变更日志。在外部用户验证真实项目之前，1.0 版本仍暂不发布。

• 阶段 1：本地扫描和安全文件生成
• 阶段 2：操作系统密钥存储的保存／检查／列出／删除（user／project 范围）
• 阶段 3：通过 Cloudflare／Vercel／GitHub 的官方 CLI 部署，并提供 targets 诊断
• 阶段 4：可选的 MCP 服务（api-key-case mcp），向 Agent 主机提供相同的仅状态操作
• 阶段 5：通过 Lemon Squeezy 兑换购买密钥，然后为 deploy 启用离线 Pro 门控（参见许可（部署））
• 阶段 6A/B/C/D/E：精确版本的 Agent Control Plane、Windows/macOS Human Plane 密钥输入、绑定到执行快照的单次高风险审批、默认拒绝自动策略下的持久化目标信任，以及删除／清理生命周期：Agent 可以提议删除，但绝不能完成删除。不包括 Linux Human Plane 和执行部署

许可证

API Key Case 0.9.1 的产品代码在 Elastic License 2.0（Elastic-2.0）下以源代码形式提供；包括 deploy 在内的完整源代码仍公开提供。agent-init 生成的托管指令文本——且仅限该文本——采用标准 0BSD 许可证，用户可在自己的代码库中保留、编辑和分享，而无需更改该代码库的许可证。API Key Case 0.9.0 仍采用该版本随附的 MIT 许可证。有关确切范围，请参阅 LICENSE、0BSD 文本 和 NOTICE。

产品支持和贡献指南：SUPPORT.md · CONTRIBUTING.md。商业信息披露：条款 · 隐私 · 退款 · 特定商取引法に基づく表記.