workbuddy-cli-model-bridge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WorkBuddy CLI Model Bridge

WorkBuddy CLI模型桥

Turn supported CLI subscriptions into verified WorkBuddy custom-model entries through CLIProxyAPI. Use the bundled script for discovery, installation, OAuth handoff, capability probes, and idempotent WorkBuddy updates. Keep model claims tied to real probes; a model name or marketing page is not evidence that a particular proxy route preserves the capability.

通过CLIProxyAPI将受支持的CLI订阅转换为已验证的WorkBuddy自定义模型条目。使用捆绑脚本进行发现、安装、OAuth移交、功能探测以及幂等的WorkBuddy更新。确保模型声明与实际探测结果绑定；仅模型名称或营销页面不能作为特定代理路由保留该功能的依据。

Resolve the Skill directory

解析Skill目录

Resolve this loaded Skill's directory and use its absolute path as

<skill-dir>

. Do not assume a specific installation root.

The deterministic entry point is:

bash

python3 <skill-dir>/scripts/bridge.py

解析已加载的Skill目录，并将其绝对路径用作

<skill-dir>

。请勿假设特定的安装根目录。

确定的入口点为：

bash

python3 <skill-dir>/scripts/bridge.py

Default workflow

默认工作流

1. Audit before changing anything

1. 更改前先执行审计

bash

python3 <skill-dir>/scripts/bridge.py audit

Read the JSON findings. The audit redacts secrets and detects:

Homebrew, CLIProxyAPI, active config, bind address, and proxy reachability
WorkBuddy initialization and existing model count
bundled and local Provider manifests
CLI executables and login signals without reading token contents
CLIProxyAPI auth-file counts without exposing account names

Treat an existing CLI login as a discovery signal. CLIProxyAPI may still require its own OAuth grant; do not copy another CLI's token file.

bash

python3 <skill-dir>/scripts/bridge.py audit

读取JSON检查结果。审计会脱敏机密信息并检测以下内容：

Homebrew、CLIProxyAPI、活动配置、绑定地址和代理可达性
WorkBuddy初始化状态和现有模型数量
捆绑的和本地的Provider清单
CLI可执行文件和登录信号（不读取令牌内容）
CLIProxyAPI认证文件数量（不暴露账户名称）

将现有CLI登录视为发现信号。CLIProxyAPI可能仍需自身的OAuth授权；请勿复制其他CLI的令牌文件。

2. Bootstrap CLIProxyAPI when required

2. 必要时引导CLIProxyAPI

Preview:

bash

python3 <skill-dir>/scripts/bridge.py bootstrap

Apply the plan when the user asked to install, configure, repair, or converge the bridge:

bash

python3 <skill-dir>/scripts/bridge.py bootstrap --apply

The request to set up the bridge authorizes reversible Homebrew installation, loopback service startup, a dedicated random proxy client key, secure local state, and timestamped backups. Pause only when:

Homebrew itself is missing and its installer requires administrator interaction
an existing proxy listens beyond loopback; explain the remote-client impact before using
```
--allow-rebind-local
```
an overlapping deployment or config conflict makes ownership ambiguous

Keep a healthy existing installation in place. Prefer official Homebrew installation for a new macOS setup.

预览：

bash

python3 <skill-dir>/scripts/bridge.py bootstrap

当用户要求安装、配置、修复或整合桥接工具时，执行计划：

bash

python3 <skill-dir>/scripts/bridge.py bootstrap --apply

设置桥接工具的请求允许可逆的Homebrew安装、回环服务启动、专用随机代理客户端密钥、安全本地状态以及带时间戳的备份。仅在以下情况暂停：

Homebrew本身缺失，且其安装程序需要管理员交互
现有代理监听范围超出回环；在使用
```
--allow-rebind-local
```
前需解释远程客户端的影响
存在重叠部署或配置冲突导致所有权不明确

保留运行正常的现有安装。对于新的macOS设置，优先使用官方Homebrew安装方式。

3. Authorize only relevant Providers

3. 仅授权相关的Providers

Bundled Provider IDs are

codex

xai-grok

, and

antigravity

. Authorize a Provider when the user requested it or the audit found its CLI/login signal and CLIProxyAPI has no matching auth/model route.

bash

python3 <skill-dir>/scripts/bridge.py authorize codex
python3 <skill-dir>/scripts/bridge.py authorize xai-grok
python3 <skill-dir>/scripts/bridge.py authorize antigravity

The command delegates to CLIProxyAPI's native OAuth flag. Tell the user to approve the browser page, then continue automatically. Never paste, print, transform, or reuse OAuth tokens. Secure resulting auth JSON files to owner-only permissions.

Do not authorize unrelated Providers merely because they are bundled.

捆绑的Provider ID为

codex

、

xai-grok

和

antigravity

。当用户请求某Provider，或审计发现其CLI/登录信号且CLIProxyAPI无匹配的认证/模型路由时，授权该Provider。

bash

python3 <skill-dir>/scripts/bridge.py authorize codex
python3 <skill-dir>/scripts/bridge.py authorize xai-grok
python3 <skill-dir>/scripts/bridge.py authorize antigravity

该命令委托给CLIProxyAPI的原生OAuth标志。告知用户在浏览器页面中批准授权，然后自动继续。切勿粘贴、打印、转换或重用OAuth令牌。将生成的认证JSON文件设置为仅所有者可访问的权限。

请勿仅因Providers已捆绑就授权无关的Providers。

4. Probe and synchronize WorkBuddy

4. 探测并同步WorkBuddy

Pass only the relevant Provider IDs:

bash

python3 <skill-dir>/scripts/bridge.py sync --providers codex,xai-grok --apply

The sync command:

fetches the live
```
/v1/models
```
list
selects recommended chat/agent models from Provider manifests
probes text, SSE streaming, tools, images, and reasoning controls where declared
resolves token limits by exact model ID, using Provider-declared catalogs before sourced manifest metadata
refuses to register a model with an unknown input/output limit or a rejected output-limit probe
skips models whose text or streaming probes fail
downgrades optional capability flags when their probes fail
backs up and atomically updates
```
~/.workbuddy/models.json
```
preserves manual entries and stale managed entries
refuses to overwrite a manual entry with the same model ID
records ownership separately under
```
~/.config/workbuddy-cli-model-bridge/
```

Do not use

--skip-probes

for a live setup. That option exists for deterministic offline tests only.

When the user explicitly requests Fast mode and no Fast model appears, read the Fast-model section in troubleshooting.md. A Fast alias needs both a distinct CLIProxyAPI route and verified priority semantics; never relabel an ordinary model as Fast.

A reasoning probe verifies control compatibility. It cannot expose private chain of thought. For teaching or screen recording, ask the model to emit a deliberate problem decomposition as normal answer content.

WorkBuddy represents each custom model as a separate entry. This Skill registers verified entries; it does not change the user's currently selected conversation model.

仅传入相关的Provider ID：

bash

python3 <skill-dir>/scripts/bridge.py sync --providers codex,xai-grok --apply

同步命令执行以下操作：

获取实时的
```
/v1/models
```
列表
从Provider清单中选择推荐的聊天/Agent模型
探测已声明的文本、SSE流式传输、工具、图像和推理控制功能
通过精确模型ID解析令牌限制，优先使用Provider声明的目录而非源清单元数据
拒绝注册输入/输出限制未知或输出限制探测未通过的模型
跳过文本或流式传输探测失败的模型
当可选功能探测失败时，降级其功能标志
备份并原子更新
```
~/.workbuddy/models.json
```
保留手动条目和过时的托管条目
拒绝用相同模型ID覆盖手动条目
在
```
~/.config/workbuddy-cli-model-bridge/
```
下单独记录所有权信息

对于线上环境，请勿使用

--skip-probes

选项。该选项仅用于确定性离线测试。

当用户明确请求Fast模式且无Fast模型显示时，请查阅troubleshooting.md中的Fast模型章节。Fast别名需要独立的CLIProxyAPI路由和已验证的优先级语义；切勿将普通模型重新标记为Fast。

推理探测用于验证控制兼容性，不会暴露私有的思维链。用于教学或屏幕录制时，可要求模型将刻意的问题分解作为常规回答内容输出。

WorkBuddy将每个自定义模型表示为单独条目。本Skill仅注册已验证的条目；不会更改用户当前选择的对话模型。

5. Verify the application consumed the change

5. 验证应用已读取更改

Run the audit again. If WorkBuddy is already open, inspect its current main-thread log for a

models.json changed

Loaded custom models config

event. If no reload event appears, ask the user to reopen model settings or start a new conversation; do not rewrite the same config repeatedly.

Report:

CLIProxyAPI version/path and local endpoint
authorized Providers, without account identifiers
models added or updated
capability probe results
conflicts, skipped models, and preserved stale entries
backup paths and any remaining user action
effective input/output token limits and their non-secret metadata source

Never include API keys, OAuth URLs containing one-time codes, token file contents, or raw request bodies.

再次运行审计。如果WorkBuddy已打开，检查其当前主线程日志中是否有

models.json changed

或

Loaded custom models config

事件。如果未出现重新加载事件，请告知用户重新打开模型设置或启动新对话；请勿重复重写相同配置。

报告内容包括：

CLIProxyAPI版本/路径和本地端点
已授权的Providers（不包含账户标识符）
添加或更新的模型
功能探测结果
冲突、跳过的模型和保留的过时条目
备份路径及任何剩余的用户操作
有效的输入/输出令牌限制及其非机密元数据源

切勿包含API密钥、含有一次性代码的OAuth URL、令牌文件内容或原始请求体。

Repair workflow

修复工作流

For an expired or broken model:

Run
```
audit
```
and distinguish proxy-down, missing key, missing OAuth, unavailable model, and WorkBuddy-cache failures.
Start or repair the existing service before reinstalling anything.
Rerun
```
authorize <provider>
```
only when auth is absent or an authenticated probe fails.

Rerun

sync --providers <affected-provider> --apply

Verify a real text request and every declared optional capability.

Do not rotate the WorkBuddy API key merely because a Provider OAuth session changed. The proxy client key and upstream OAuth credentials have different lifecycles.

Read troubleshooting.md for failure classification and rollback guidance.

针对过期或损坏的模型：

运行
```
audit
```
，区分代理宕机、密钥缺失、OAuth缺失、模型不可用和WorkBuddy缓存失败等情况。
在重新安装任何内容之前，启动或修复现有服务。
仅当认证缺失或已认证探测失败时，重新运行
```
authorize <provider>
```
。

重新运行

sync --providers <affected-provider> --apply

。

验证真实文本请求和每个已声明的可选功能。

切勿仅因Provider OAuth会话变更就轮换WorkBuddy API密钥。代理客户端密钥和上游OAuth凭据具有不同的生命周期。

查阅troubleshooting.md获取故障分类和回滚指导。

Add a new CLI Provider

添加新的CLI Provider

Read both:

provider-schema.md
onboarding-new-cli.md

Prefer, in order:

CLIProxyAPI native OAuth Provider
official OpenAI-compatible endpoint
declarative model alias/protocol mapping
a bounded local adapter as a separately disclosed last resort

Save machine-local manifests under:

text

~/.config/workbuddy-cli-model-bridge/providers.d/<provider-id>.json

Validate before use:

bash

python3 <skill-dir>/scripts/bridge.py validate-provider ~/.config/workbuddy-cli-model-bridge/providers.d/<provider-id>.json

Then authorize and sync by the new Provider ID. A new manifest becomes reusable by every Agent on the same machine without modifying this Skill. Promote it into the public Skill only after isolated tests prove installation, authentication handoff, model selection, capability accuracy, and rollback behavior.

请阅读以下两份文档：

provider-schema.md
onboarding-new-cli.md

优先按以下顺序选择：

CLIProxyAPI原生OAuth Provider
官方OpenAI兼容端点
声明式模型别名/协议映射
作为最后手段的受限本地适配器（需单独披露）

将本地机器的清单保存在：

text

~/.config/workbuddy-cli-model-bridge/providers.d/<provider-id>.json

使用前验证：

bash

python3 <skill-dir>/scripts/bridge.py validate-provider ~/.config/workbuddy-cli-model-bridge/providers.d/<provider-id>.json

然后按新的Provider ID进行授权和同步。新清单可被同一台机器上的所有Agent复用，无需修改本Skill。只有在独立测试证明安装、认证移交、模型选择、功能准确性和回滚行为均正常后，才可将其推广至公共Skill。

Safety boundaries

安全边界

Read security-boundaries.md before changing service exposure, credentials, or adding a local adapter.

Bind the proxy to loopback and keep remote management disabled.
Store bridge secrets, OAuth files, WorkBuddy config, and credential-bearing backups with mode
```
0600
```
.
Use only accounts the user owns and respect Provider subscription terms and rate limits.
Never implement ban evasion, account sharing, automated block reset, token extraction, or hidden traffic cloaking.
Preserve user-created WorkBuddy models and unrelated CLIProxyAPI configuration.
Treat Provider manifests as code: validate their source and inspect local overrides before executing login flags.

在更改服务暴露范围、凭据或添加本地适配器之前，请阅读security-boundaries.md。

将代理绑定到回环地址，保持远程管理禁用状态。
将桥接工具机密、OAuth文件、WorkBuddy配置和含凭据的备份设置为
```
0600
```
权限。
仅使用用户拥有的账户，遵守Provider订阅条款和速率限制。
切勿实现规避封禁、账户共享、自动重置限制、令牌提取或隐藏流量伪装等功能。
保留用户创建的WorkBuddy模型和无关的CLIProxyAPI配置。
将Provider清单视为代码：在执行登录标志之前，验证其来源并检查本地覆盖内容。

Completion gate

完成标准

Completion requires:

audit has no unresolved security error
CLIProxyAPI is reachable on loopback with the dedicated client key
each registered model passed text and streaming probes
every enabled optional capability passed its probe
every registered model has sourced input/output limits and passed the bounded output-limit probe
WorkBuddy loaded the resulting model list
repeated sync is idempotent
backups and rollback paths are reported

If any gate remains unproven, report the model as unverified rather than declaring success.

完成需满足以下条件：

审计无未解决的安全错误
CLIProxyAPI可通过专用客户端密钥在回环地址访问
每个注册模型均通过文本和流式传输探测
每个启用的可选功能均通过其探测
每个注册模型均有来源明确的输入/输出限制，并通过有限输出限制探测
WorkBuddy已加载生成的模型列表
重复同步具有幂等性
已报告备份路径和回滚路径

如果任何标准未满足，请将模型报告为未验证状态，而非宣告成功。