KAPI CLI 想法

日期：2026-05-15

SDD 工作流

本项目采用 SDD + TDD 工作流：

1. 先写 SDD，明确命令行为、输入输出、错误场景和验收标准。
2. 再按 SDD 写失败测试。
3. 最后实现代码让测试通过。

当前规格：

• SDD 0001: MVP Ping
• SDD 0002: First Run Onboarding
• SDD 0003: Local State And Credentials
• SDD 0004: Configure Claude Code
• SDD 0005: Configure Codex
• SDD 0006: MVP Implementation Baseline

README 记录产品方向和后续想法；MVP 的可测试行为以 SDD 为准。

当前实现状态

已实现 MVP 主路径：

• kapi 默认进入首次运行 onboarding。
• CLI 面向用户的 help、交互提示、preview、成功和错误输出使用中文。
• 本地没有有效凭据时，通过 K+ 协议登录，并把账号密码保存到系统 keyring 便于后续自动登录。
• 登录后进入选择页面，支持测速后从最快 3 个端点中选择、配置 Claude Code、配置 Codex、退出登录。
• 只有选择配置 Claude Code 或 Codex 后，才进入分组选择；Claude Code 只显示 anthropic 分组，Codex 只显示 openai 分组，按倍率从高到低排序，并用渐变色展示倍率后再创建或复用 KAPI API key。
• kapi ping 和 kapi ping --json 可独立执行 endpoint 探测。
• 如果用户通过 npm 全局安装 @ent9/kapi，CLI 启动时会自动检查 npm 最新版本；发现新版本时自动执行全局更新。npx 临时运行和本地源码运行不会自改。
• API key 优先写入系统 keyring；不可用时在交互确认后降级到权限受限的文件凭据。
• Claude Code 写入 ~/.claude/settings.json，写前 preview、备份、原子替换。
• Codex 写入 ~/.codex/auth.json 和 ~/.codex/config.toml，写前 preview、备份、失败回滚。

验证命令：

npm test
npm run typecheck
npm run build

命名

• 产品名：KAPI
• npm 包名：@ent9/kapi
• CLI 命令：kapi
• npx 用法：npx @ent9/kapi

安装和更新

临时运行：

npx @ent9/kapi@latest

全局安装：

npm install -g @ent9/kapi
kapi

全局安装后的 kapi 会自动检查更新。检测只在直接运行 npm 全局安装的 CLI 时启用；npx 已经由 npm 解析版本，本地开发的 node dist/cli.js 也不会触发自更新。

如需临时禁用自动更新：

KAPI_AUTO_UPDATE=0 kapi

已确认默认策略

• 生产 K+ 管理入口：https://api.ticketpro.cc。
• 可通过 KAPI_API_BASE_URL 覆盖管理入口，便于测试、本地 mock 和后续迁移。
• endpoint 候选来自 GET /api/v1/settings/public 的 api_base_url 和 custom_endpoints[]。
• custom_endpoints[].endpoint 是完整 K+ 根 URL，不是 /v1 网关 URL。
• 写入 Claude Code 和 Codex CLI 时，把 endpoint 根 URL 规范化为 OpenAI-compatible gateway base URL，也就是追加 /v1。
• Codex provider ID 固定为 k。
• Codex 配置时显式切换 model_provider = "k"，保留其他 provider 但不更新它们。
• K+ API key 优先保存到系统 keyring；keyring 不可用时允许提示后降级到权限受限的文件凭据。
• K+ 登录账号密码只保存到系统 keyring；keyring 不可用时不保存密码。
• 明文 HTTP endpoint 可以参与测速展示，但默认不写入 Claude Code 或 Codex CLI 配置。
• MVP endpoint 选择是全局默认，不按客户端或模型分别保存。
• MVP 不做地理区域硬编码策略，以用户本机实时 ping 结果为准。

目标

KAPI 是一个面向用户的命令行工具，用来帮助用户在当前网络环境下自动选择可用且速度较快的端点，并尽量自动完成 Claude Code 或 Codex CLI 的配置。

要解决的核心问题是：端点很多，用户手动测试和配置不方便。KAPI 应该把“探测端点、选择最快、选择分组、创建或复用 key、写入客户端配置”变成尽量少的命令。

用户体验

默认用法应该是一次性执行，而不是要求用户长期在后台运行一个 npx 进程。

默认入口：

npx @ent9/kapi

首次运行时，如果本地没有可用登录凭据，CLI 会提示输入 K+ 账号密码，通过协议登录，然后进入动作选择页面。选择配置 Claude Code 或 Codex 时，再选择分组并创建或复用该分组的 key。

选择页面包含：

• 选择当前网络环境下最快端点。
• 配置 Claude Code。
• 配置 Codex。
• 退出登录。

探测命令：

npx @ent9/kapi ping

后续命令：

npx @ent9/kapi login
npx @ent9/kapi config codex
npx @ent9/kapi config claude

默认入口预期行为：

• kapi 检查本地登录状态。
• 本地没有可用登录凭据时，提示输入 K+ 账号密码。
• CLI 通过协议登录 K+，保存 keyring 登录凭据。
• 登录成功后进入选择页面。
• 用户可以测速后从最快 3 个端点中选择、配置 Claude Code、配置 Codex 或退出登录。
• 用户选择配置 Claude Code 或 Codex 后，进入分组选择页面。
• CLI 按所选分组查找 KAPI 创建的同名 key；没有时才创建新 key。
• 用户选择退出登录后，CLI 清理本地登录凭据和默认 API key，保留已选 endpoint，不删除远端 K+ key。

探测命令预期行为：

• kapi ping 测试所有已知端点，输出延迟、可用性和推荐结果。

后续预期行为：

• kapi login 单独执行登录流程。
• kapi config codex 把选中的端点和 key 写入 Codex CLI 配置。
• kapi config claude 把选中的端点和 key 写入 Claude Code 配置。
• kapi doctor 检查 DNS、TCP、TLS、HTTP 健康检查、鉴权和本地配置问题。

后续可以增加可选的本地代理模式，但普通用户不应该必须运行后台代理。

端点探测

CLI 应该先从服务端拉取端点列表，然后从用户本机网络环境发起探测。

端点列表从 https://api.ticketpro.cc/api/v1/settings/public 拉取，除非用户通过 KAPI_API_BASE_URL 覆盖管理入口。api_base_url 和 custom_endpoints[].endpoint 都按完整 endpoint 根 URL 处理，写入客户端配置时再追加 /v1。

MVP 阶段先做 HTTP 健康检查、延迟统计和推荐输出。DNS、TCP、TLS 分阶段诊断放到后续 doctor 或增强探测规格中。

长期探测维度：

• DNS 解析是否成功，以及解析耗时。
• TCP 连接是否成功，以及连接耗时。
• HTTPS 端点的 TLS 握手是否成功，以及握手耗时。
• HTTP 健康检查是否成功。
• 用户登录后，可以执行一次轻量鉴权 API 检查。
• 多次请求的失败率。
• 延迟中位数和抖动情况。

推荐逻辑：

• 优先选择所有健康检查都通过的端点。
• 稳定优先：失败率更低者优先。
• 失败率相同时按 medianMs + jitterMs 综合分排序，让抖动大的端点明显降权。
• 综合分相同时再按延迟中位数、抖动和稳定 ID 排序。
• 可以缓存最近一次探测结果，但写入配置前必须重新检查。

登录和创建 Key

默认入口使用 K+ 协议登录。首次运行时，如果本地没有可用登录凭据，KAPI 会在终端提示用户输入账号密码。

登录流程：

• CLI 提示输入账号和密码。
• 密码输入必须隐藏。
• CLI 使用账号密码调用 K+ 登录协议。
• CLI 把账号密码保存到系统 keyring，用于 token 过期或缺失时自动登录。
• CLI 不在普通文件 fallback 中保存账号密码。
• 服务端只在用户选择配置 Claude Code 或 Codex 并选定分组后，返回或创建一个命名 API key。
• CLI 保存 key，不保存到 shell 环境变量。

Key 管理：

• key 名称使用稳定安装 ID 和分组 ID，例如 kapi-macbook-a1b2c3d4-g42，避免每天创建新 key。
• 后续支持列出和撤销由 KAPI 创建的 key。
• 优先保存到系统 keyring。
• 如果没有 keyring，则降级保存到权限受限的本地凭据文件。
• 普通配置和敏感凭据的本地保存规则见 SDD 0003。

配置目标

第一批支持的配置目标：

• Codex CLI
• Claude Code

写入配置前必须展示 preview，用户确认后才写入。独立 config ... --dry-run 命令放到后续实现。

也应该支持用户显式选择端点：

npx @ent9/kapi use hk
npx @ent9/kapi use auto

服务端 API

当前 K+ 已有接口：

• GET /api/v1/settings/public
• POST /api/v1/auth/login
• POST /api/v1/auth/login/2fa
• GET /api/v1/auth/me
• GET /api/v1/keys
• POST /api/v1/keys
• GET /v1/models

当前缺口：

• 没有专用的 CLI endpoint 列表接口。
• 没有专用的 ensure API key 接口。
• 没有专用的 config targets 接口。

后续可新增：

• GET /api/v1/cli/endpoints
• POST /api/v1/cli/api-key/ensure
• GET /api/v1/cli/config-targets

MVP 范围

第一版最小可用范围：

• 发布 npm 包 @ent9/kapi。
• kapi 默认进入首次运行引导。
• 首次运行支持账号密码协议登录 K+。
• 登录后提供选择页面。
• 配置 Claude Code 或 Codex 时支持按目标 CLI 过滤分组、按倍率从高到低排序、用渐变色展示倍率，并按分组创建或复用 key。
• 支持从选择页面配置 Claude Code。
• 支持从选择页面配置 Codex。
• 实现 kapi ping。
• 实现端点列表拉取。
• 实现本地 HTTP 健康探测。
• 输出推荐端点；默认 onboarding 的“选择最快端点”会在测速前询问是否只需要 HTTPS 端点（默认是）和是否使用真实测速环境（默认是），先通过 ipinfo.io 检测当前出口 IP、地区、运营商和本地代理环境。网络检测、健康测速、线路检测和真实测速都以折叠框展示：执行中展开，完成后折叠成单行摘要。真实测速会并发测试前 3 个候选，会创建或复用 Minimax 分组 key，使用 Claude Messages 格式和 claude-opus-4-6 模型，执行中按约 1200 输出 token 显示每个端点的进度条，并在选择项中展示首字时间和输出 token/s。保存最快端点后会询问应用到 Claude Code、Codex 或两者；应用前会检查目标 CLI 当前 Base URL 是否为空或属于 K+ 已知端点，非 K+ 时停止应用。
• 支持 --json 输出，方便脚本使用。

MVP 之后再做：

• 浏览器登录。
• kapi login 独立命令。
• kapi config codex 独立命令。
• kapi config claude 独立命令。
• kapi doctor 诊断命令。
• 更完整的 DNS、TCP、TLS 分阶段诊断。

后续待评估

• 是否公开 kapi logout，用于清理 keyring、本地配置和 KAPI 创建的 key。