Toksea MVP

组织内的订阅账号授权管理与凭证分配工具。模型请求由本机原生 CLI 直连供应商，服务端没有模型代理接口。

已落地 Go 服务端、PostgreSQL、CLIProxyAPI 认证 worker 和 toksea 客户端。当前是开发版本：账号管理可运行，真实凭证交付默认关闭；Claude 凭证存储适配和额度查询尚未完成。实现范围见 docs/IMPLEMENTATION.md，真实验证门槛见 docs/compatibility-matrix.md。

安装 CLI（npm）

需要 Node.js 18+。支持 macOS 和 Linux 的 x64 / arm64；Windows 请在 WSL 内安装。

npm install -g toksea@latest
toksea --version
toksea login --server https://你的服务域名
toksea whoami

按提示输入管理员提供的成员访问令牌。连接本机开发服务时使用 toksea login --server http://127.0.0.1:8787 --allow-local-http。

toksea add codex     # 贡献账号，浏览器授权后自动接收本机回调
toksea accounts      # 查看账号
toksea codex         # 领取账号并更新本机 Codex 默认登录
codex                # 启动另行安装的 Codex CLI
toksea switch codex  # 换号

也可免全局安装执行 npx --yes toksea@latest --help。npm 包内置四个平台的压缩二进制，安装时自动选择、校验 SHA-256 并解压，无需 Go 或额外下载站点；禁用安装脚本时首次运行自动解压。npm 包只安装客户端，服务端需单独部署。

维护者发布

更新 package.json 版本后运行 npm test、go test -race ./... 和 go vet ./...。npm pack 自动调用 Go 1.26+ 交叉编译四个平台，并将 npm 版本写入 CLI。检查 tarball 文件清单，在临时目录安装该 tarball 验证 toksea --version / --help，然后执行 npm publish ./toksea-<版本>.tgz --access public，发布已验证的同一份产物。构建产物位于忽略跟踪的 dist/。

目录结构

单个 Go module（github.com/zhangzhejian/toksea），按服务拆分：

backend/   服务端：cmd/toksea-server、internal/{httpapi,service,store,vault,providers}、api/openapi.yaml、config/providers.json
cli/       本机客户端：cmd/toksea、internal/client
pkgs/      backend 与 cli 共享的包：protocol（错误码/协议）、domain（模型与请求结构）、native（原生 CLI 凭证文件）
web/       Web 管理界面，尚未开始
deploy/    Docker Compose、Dockerfile、bootstrap
docs/      需求、技术方案、实施记录、兼容性矩阵、验证记录
tools/     codex-probe：独立的 Python 验证工具
scripts/   构建脚本（认证 worker）
third_party/cliproxyapi/  固定上游 commit 的认证 worker 入口与许可

backend/internal 与 cli/internal 互不可见；两边都要用的类型放 pkgs/。

构建

需要 Go 1.26+、Python 3（用于拉取上游构建）、PostgreSQL 16。支持本机 macOS/Linux；Codex 适配目标为 0.154.0。

make build
make worker

输出 bin/toksea、bin/toksea-server、bin/toksea-auth-worker。worker 从固定 CLIProxyAPI commit 构建，只调用认证代码；来源与许可见 third_party/cliproxyapi。

一键启动（Docker Compose）

需要 Docker。数据库、服务端和初始化都在容器里完成：

make up

首次运行会自动生成 deploy/.env、构建镜像、建表、创建初始组织与管理员成员，并打印访问令牌（也可随时 make token 再看）。停止用 make down，连数据一起删用 make nuke。更多命令与配置见 deploy/README.md。

客户端仍在本机运行：make build 后 bin/toksea login --server http://127.0.0.1:8787 --allow-local-http。

本机启动

先创建一个开发数据库，设置连接串。以下端口仅为示例，使用你的 PostgreSQL 实际端口：

export TOKSEA_DATABASE_URL='postgres://127.0.0.1:5432/toksea?sslmode=disable'
mkdir -p .local/mvp
bin/toksea-server keygen --out .local/mvp/credential-keys.json
bin/toksea-server migrate
bin/toksea-server org-create --name '我的组织'
bin/toksea-server member-create --org <返回的组织UUID> --name alice --role admin

member-create 仅这次输出成员令牌，请保存供 toksea login 使用；令牌默认 30 天有效。服务端数据库只保存摘要。

export TOKSEA_CREDENTIAL_KEY_FILE="$PWD/.local/mvp/credential-keys.json"
export TOKSEA_AUTH_WORKER_PATH="$PWD/bin/toksea-auth-worker"
export TOKSEA_PROVIDER_CAPABILITIES_FILE="$PWD/config/providers.json"
export TOKSEA_CODEX_BINARY="$(command -v codex)"
export TOKSEA_LISTEN_ADDR='127.0.0.1:8787'
bin/toksea-server serve

服务默认仅监听回环 HTTP，适合本机开发。远程使用需要 HTTPS 入口；部署与运维见 deploy/README.md。本机诊断入口为 /healthz 与 /readyz。

用户操作

在另一个终端运行：

bin/toksea login --server http://127.0.0.1:8787 --allow-local-http
bin/toksea add codex
bin/toksea add claude
bin/toksea accounts
bin/toksea accounts --json
bin/toksea reauth <账号UUID>
bin/toksea disable <账号UUID>
bin/toksea enable <账号UUID>
bin/toksea doctor

toksea login 隐藏输入组织令牌，优先写系统凭证库，不可用时用 0600 文件。可以用 TOKSEA_HOME 选择独立客户端目录，默认 ~/.toksea。

每个人使用独立的 Toksea 成员令牌；不要共用 local-admin 的令牌，否则领取记录会归到同一成员。该身份与供应商账号的邮箱、订阅、工作区分别管理。toksea whoami 向服务端查询当前成员、组织和权限。

管理员登录后可直接在客户端管理成员，无需登录服务器操作数据库：

bin/toksea whoami
bin/toksea members
bin/toksea members create --name '张三'
bin/toksea members create --name '李四' --role admin
bin/toksea members update <成员UUID> --name '新的姓名' --can-allocate=false
bin/toksea members disable <成员UUID>
bin/toksea members enable <成员UUID>
bin/toksea members reset-token <成员UUID>

创建和重置令牌仅本次返回原文及到期时间（30 天），管理员自行交给对应成员；成员执行 toksea login --server <服务地址> 并按隐藏输入提示粘贴。成员列表不返回任何令牌。停用会撤销全部成员令牌，重新启用后需重置令牌再登录；重置使旧令牌失效，也用于令牌到期后重新签发。不能停用组织最后一位启用的管理员。上述命令支持 --json，创建/重置的 JSON 包含新令牌，应作为秘密保存。toksea logout 只清理当前本机连接。

贡献账号先输入 yes 确认共享给当前组织，再在供应商官方网页授权。Codex 默认在本机 localhost:1455/auth/callback、Claude 在 localhost:54545/callback 监听回调，浏览器授权后自动提交（重新授权同样支持）。端口被占用时自动退回手动回填；在远程机器运行或使用其他电脑的浏览器时，请用 toksea add codex --manual、toksea add claude --manual 或 toksea reauth <account-id> --manual。手动模式下复制浏览器最终的完整回调地址到 CLI 隐藏输入，必须包含 code 和 state；页面无法打开不影响回填。服务端保存认证结果，后台查询身份与额度。

toksea accounts 默认紧凑展示邮箱、可用状态、最近领用标记、近 24 小时领取人数，以及各额度窗口的剩余百分比和重置时间；过期快照与查询错误仍会提示。toksea accounts --verbose 查看完整账号 ID、订阅、工作区、共享范围、成员领取明细和查询时间。默认向所有成员展示组织内全部账号，按本人每种工具最近成功领用的账号、可用账号、其余账号排序。可用性依据当前成员权限、授权及额度状态与服务端支持的交付配置判断，实际领取仍需匹配操作系统和请求模型，Codex 不再限制版本号。--all 保留为默认行为的兼容参数，--json 输出相同权限范围内的结构化元数据，不含凭证。

账号列表还显示 近 24 小时成功领取人数、成员姓名/ID、每人的最近确认时间和自己的最近确认领取时间。按 Toksea 成员 ID 去重，不按邮箱或领取次数统计；只统计客户端确认成功的记录，未确认、失败、被拒绝的记录不计入。时间取服务端首次收到成功确认的时间，离线补报可能延后统计；重复事件不会延长窗口。历史成功事件直接参与统计，不需要重新领取或重新授权。JSON 的 usage 包含窗口起止时间和相同权限范围内的明细。

bin/toksea allocations           # 自己的领取 + 自己贡献账号的领取；管理员看组织全部
bin/toksea allocations --mine    # 只看自己的领取
bin/toksea allocations --json

普通成员即使没有贡献账号，也能用 toksea allocations --mine 查看自己的记录；不会获得其他账号的领取名单。toksea accounts 和 toksea allocations 会先尝试发送本机待补报结果。这些是领取历史，不是当前在线/推理人数。 没有心跳、租约或模型代理，也不能从一次切换推断其他设备停止使用旧凭证；toksea status codex 查看本机上次成功切换记录。

Codex 邮箱和订阅来自 App Server，订阅优先采用在线额度接口的结果；已知订阅类型可推断个人/组织工作区，界面会标明判断依据。这不代表邮箱本身归个人或公司所有，也不同于是否共享到 Toksea。未知套餐不猜测；Claude 当前只能获取邮箱、工作区 ID/名称，订阅等级、工作区类型和额度仍显示未知。额度按供应商实际窗口展示，不默认 primary 是 5 小时；过期快照有提示，不根据重置时间自动补满。未提供的 token/次数总量、订阅续费时间不推算，凭证到期时间也不是订阅到期时间。既有账号下一次后台检查后自动补齐资料，无需重新授权。

bin/toksea codex
bin/toksea codex --select   # 列出 Codex 账号，输入编号并确认后切换
bin/toksea codex --model <已验证模型> --json
bin/toksea claude
bin/toksea switch codex
bin/toksea status codex --json
bin/toksea logout

当前 providers.json 将 Codex 标为 experimental，默认拒绝领取。管理员可为本地 MVP 试用设置服务端 TOKSEA_ALLOW_EXPERIMENTAL_DELIVERY=true，允许该版本的实验性交付，返回结果与分配记录仍标为 experimental；它不会把兼容性改成 verified，也不会放开 unsupported、版本/模型限制或已耗尽/无法确认额度的账号。当前 .local/runtime 已启用本地试用。生产验证门槛仍见兼容性矩阵。Claude 的 add/reauth/accounts/enable/disable 可用，toksea claude 当前明确返回不支持。

Codex 默认额度配置要求 codex/primary，把 codex/secondary 列为 optional_windows：未返回次窗口的 Business 账号可以分配；返回次窗口时同样检查剩余比例及重置时间，不能跳过已耗尽窗口。所有需要检查的窗口都必须还有额度，按其中最小剩余百分比排序；未知/过期快照继续拒绝领取。

分配分三档，各档内都选剩余额度最高的账号：

1. 剩余额度 大于阈值，且近 24 小时无人成功领取、没有正在等待确认的新交付。
2. 剩余额度 大于阈值，但已有上述领取记录。
3. 剩余额度 大于 0 且小于等于阈值，作为后备；不会因低于阈值被直接排除。

阈值默认 10%，服务端通过 TOKSEA_QUOTA_PREFERRED_PERCENT 配置（0–100，可用小数），修改后重启 API 生效，Compose 模板已透传该变量。上次账号只在同档、同额度时优先；其后按最早分配时间和账号 ID 排序。toksea switch 仍排除上次账号。全部耗尽或没有满足认证/权限/额度要求的账号时返回 NO_AVAILABLE_ACCOUNT，不覆盖本机默认登录。

“无人领取”是调度依据，不代表实时无人使用：成功记录使用近 24 小时窗口；刚交付、未确认的记录在原有 5 分钟重放窗口内也暂时影响排序，防止并发请求集中挑中同一个空闲账号。失败或重放窗口过期会结束待确认记录的影响，不需要心跳或归还，仍允许共享账号被再次分配；账号列表的人数仍只统计成功确认的成员。相同请求重试保持原分配，不重新排序。该策略由两种供应商共用，Claude 真实交付仍需完成现有适配与额度接入。

toksea codex 领取、校验凭证并切换本机 Codex 默认登录，完成后退出；toksea switch codex 排除上次领取的账号，执行相同的默认登录切换。命令不打开交互 CLI。Codex 版本号仅作诊断记录，不限制为特定版本；仍须通过实际凭证、身份和额度校验。支持 --model 筛选账号和 --json 输出账号、默认路径及旧登录备份目录，不透传原生 CLI 参数，不输出令牌正文。Claude 仍受上述适配限制。

已验证组合的 Codex 流程为：记录版本并检查默认配置 → 向组织服务申请 → 在独立分配目录安装认证 → 后台在线检查 → 备份旧登录 → 写入默认登录 → 回报。在线检查仍短暂运行隔离的 Codex App Server；它可能刷新凭证，因此安装的是检查后的最新材料。申请或在线检查失败时不修改默认登录。

成功后在同一终端直接运行 codex，无需额外设置 CODEX_HOME。目标是当前 CODEX_HOME，未设置时为 ~/.codex。auth.json 使用 0600 权限；config.toml 仅更新 cli_auth_credentials_store="file"、forced_login_method="chatgpt"、model_provider="openai"，保留原注释、模型、MCP 和其他配置。这与 Codex 官方凭据存储机制一致；原钥匙串记录不删除。已运行的 CLI/扩展可能缓存旧账号或再次写入凭证，请先退出再切换、重开；不保证旧会话热切换。

旧 auth.json 和 config.toml 原文备份在 profiles/<server>/<org>/codex/backups/<allocation>/，目录 0700、文件 0600；manifest.json 记录原文件是否存在、权限和目标路径，toksea status codex --json 可找到上次备份。普通写入或状态保存失败会尝试回滚；并发外部修改不会被回滚覆盖，进程崩溃或回滚冲突需根据备份恢复原文件（原本不存在的文件按 manifest 移除）。备份不自动清理，也不代表旧供应商令牌始终有效。

多个 Toksea 组织共用同一默认 Codex 目录时，最后一次成功领取生效。目标目录加本机锁，并在写入前检查旧文件是否被修改。环境中的 API key/路由覆盖、活动 profile 冲突、强制工作区不匹配或未适配的机器认证策略会明确报错。toksea logout 仅退出组织，不撤销已写入的供应商登录。模型请求继续由原生 Codex 直连供应商。

停用和撤销成员令牌只阻止后续领取，无法让已发出的供应商凭证立即失效。

测试

make test
make check
TEST_DATABASE_URL='postgres://127.0.0.1:5432/toksea_test?sslmode=disable' make integration
make test-probe

集成测试在指定数据库内创建并删除专属随机 schema，需要相应权限，不接触真实账号。测试覆盖越权、OAuth 任务、加密、并发幂等、停用/重授权后的重放拒绝、刷新不确定状态、真实 worker 的 PKCE/state 协议，以及本机默认登录切换、检查后最新凭证、备份/回滚、配置保留、并发修改拒绝和不启动交互进程。设置 TEST_CODEX_BINARY 为已安装 Codex 的绝对路径，可运行隔离的原生文件选择验证；只用合成凭证执行 account/read，不查询额度或发送模型请求。

未设置 TEST_DATABASE_URL 或 TEST_AUTH_WORKER 时对应 Go 测试会跳过；make integration 要求数据库并先构建 worker。测试通过不表示真实订阅账号可复制续期。

文档

• 产品需求 · 技术方案 · 实现状态
• HTTP API 合同 · 兼容性矩阵
• Python Codex 验证工具 · 历史真实验证记录

toksea codex --select 在交互终端列出 Codex 账号、额度与可用状态，输入编号后用 y 确认，回车或 q 取消。不可用账号不可选择；可与 --model 同用，模型、权限、额度由服务端在领取时再次校验。toksea switch codex --select 排除本机上次成功切换的账号。手动选择不自动回退到其他账号，不能与 --json 同用；需要服务端支持 account_id。客户端发现返回账号不匹配时会拒绝切换。Claude 原生凭证交付仍未支持。

npm 自动发布

修改 package.json 的稳定版本号并合并到 main 后，Release npm CLI 工作流会运行 Go race 测试、PostgreSQL API 集成测试、go vet 和 npm 安装器测试，构建 macOS/Linux 的 x64/arm64 安装包，验证安装后发布到 npm latest。使用 npm Trusted Publisher（OIDC），无需 NPM_TOKEN。npm 包设置绑定 GitHub Actions 的 botlearn-ai/toksea、工作流文件 release-npm.yml，Environment name 留空，并允许 npm publish。工作流使用 GitHub-hosted runner、npm 11 和 id-token: write 获取短期发布授权。已存在的版本跳过发布；网络或认证错误不会当作“版本不存在”。也可从 Actions 手动运行，修复认证后重试同一未发布版本。