用途:Splitch 用于管理功能开关与 A/B 实验,适合项目已采用 Splitch 或请求涉及 Splitch Apps、Environments、Flags 的场景。核心模型为:App 拥有 Flags 并跨越 Environments;Flag 决定某 Entity 获得哪个 Variant;Experiment Run 借助 Exposures 与 Metric Events 衡量效果。
主要能力与用法:官方建议优先使用 CLI,它提供与 Web 面板相同的控制面操作、稳定 JSON 输出和命令级帮助;能使用 CLI 时不应打开控制面板。先检查已安装版本与当前作用域:splitch --version、splitch context --json。若 CLI 不可用,用 Node.js 24 或更高版本安装官方包:npm install --global @splitch/cli,然后执行 splitch login(登录可能需用户在浏览器批准 OAuth 设备流程,不要用浏览器自动化或 API Key 绕过认证)。
作用域:多数命令作用于 App,很多还作用于 Environment。通过 --app 与 --env 显式解析,或在仓库中一次性选择:splitch use --app <app-id-or-slug> --env <environment-id-or-slug> --json。use 会写入 splitch.json;命令标志优先于 SPLITCH_APP、SPLITCH_ENV,后者优先于该文件。不要猜测未解析或含糊的作用域。
JSON 契约:代理消费的每条命令都加 --json。带该标志时 stdout 只含一个 JSON 文档,叙述性内容输出到 stderr;失败也返回含 code、message、remediation、docsUrl、details 的 JSON。应依据退出状态和 code 分支,切勿解析人类可读输出或用空值推断成功。列表响应含 readTruncated、readLimit、cursor;readTruncated 为 true 时不可视为完整。
常见操作:检查上下文、列出/获取 Flag、获取 flag-config、列出实验、列出 Run、获取实验结果。创建、启用并验证布尔 Flag 的示例:splitch flags create --key <flag-key> --variants on,off --json;splitch flag-config update <flag-key> --enabled true --rollout 100 --json;splitch flags test-eval <flag-key> --targeting-key <test-key> --json;splitch flags verify <flag-key> --targeting-key <test-key> --json。test-eval 通过已认证控制面测试解析,verify 用所选 Environment 的 Client Key 做真实数据面往返,二者都不触发 Exposure。
凭证:Client Key(pk_...)是公开的,可嵌入不可信客户端;用 splitch client-key get --json 读取。API Key(sk_...)是机密,仅限服务端,创建时仅显示一次,切勿打印、粘贴到聊天、提交或在客户端代码中使用。可用 --output-file 将其直接写入 mode-0600 文件。
限制与注意:遇到错误应阅读文档 URL 或其 .md 版并按其修复,CLI 失败时不要回退到点击控制面板。重试逻辑变更时应复用调用方自有的 --idempotency-key。Environment Policy 可能要求确认或审批;有门槛的变更失败时不会部分应用,仅当响应要求确认且调用方授权时才用 --confirm 重试,--confirm 无法绕过必需的 Approval Request。不要臆造命令、标志、请求字段或重试行为,以已安装二进制的 --help 为准。