workbuddy-cli-model-bridge

WorkBuddy CLI 模型桥接

通过 CLIProxyAPI，将受支持的 CLI 订阅转化为经过验证的 WorkBuddy 自定义模型条目。使用随附脚本进行发现、安装、OAuth 授权交接、能力探测和幂等 WorkBuddy 更新。模型能力声明必须以实际探测结果为依据；模型名称或营销页面不能证明特定代理路由保留了相应能力。

确定 Skill 目录

确定已加载 Skill 的目录，并将其绝对路径用作 <skill-dir>。不要假设特定的安装根目录。

确定性的入口点是：

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

默认工作流

1. 更改任何内容前先进行审计

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

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

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

将现有 CLI 登录视为发现信号。CLIProxyAPI 仍可能需要单独的 OAuth 授权；不要复制其他 CLI 的令牌文件。

2. 在需要时引导安装 CLIProxyAPI

预览：

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

如果用户要求安装、配置、修复或收敛此桥接，则应用该计划：

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

设置桥接的请求即表示授权执行可逆的 Homebrew 安装、启动回环服务、生成专用随机代理客户端密钥、设置安全的本地状态，以及创建带时间戳的备份。仅在以下情况下暂停：

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

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

3. 仅授权相关 Provider

随附的 OAuth Provider ID 为 codex、xai-grok 和 antigravity。如果用户提出了相应请求，或审计发现对应的 CLI／登录信号且 CLIProxyAPI 没有匹配的认证／模型路由，则授权该 Provider。

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 文件权限设为仅所有者可访问。

随附的 glm-coding 是 Coding Plan API 密钥 Provider，而非 OAuth。不要运行 authorize glm-coding。请遵循 glm-coding-plan.md：将官方 coding /paas/v4 路由添加到 CLIProxyAPI，然后运行 sync --providers glm-coding。不要使用智谱清言网站登录。

不要仅仅因为其他 Provider 随包提供，就授权无关的 Provider。

4. 探测并同步 WorkBuddy

仅传入相关的 Provider ID：

python3 <skill-dir>/scripts/bridge.py sync --providers codex,xai-grok,glm-coding --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. 验证应用已应用更改

再次运行审计。如果 WorkBuddy 已打开，请检查其当前主线程日志中是否有 models.json changed 或 Loaded custom models config 事件。如果没有重新加载事件，请让用户重新打开模型设置或开始新对话；不要反复重写相同的配置。

报告以下内容：

• CLIProxyAPI 版本／路径和本地端点
• 已授权的 Providers，不含账户标识符
• 已添加或更新的模型
• 能力探测结果
• 冲突、跳过的模型和保留的过时条目
• 备份路径和任何待用户执行的操作
• 生效的输入／输出令牌限制及其非机密元数据来源

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

修复工作流

对于已过期或损坏的模型：

1. 运行 audit，区分代理服务未运行、缺少密钥、缺少 OAuth、模型不可用、Provider 配额问题和 WorkBuddy 缓存故障。
2. 先启动或修复现有服务，再重新安装任何内容。
3. 如果配额恢复后仍持续出现 503 auth_unavailable，请按照 配额已恢复但 503 仍然存在 中的说明操作，然后再重新授权。
4. 仅当缺少身份验证，或身份验证专用探测失败时，才重新运行 authorize <provider>。
5. 重新运行 sync --providers <affected-provider> --apply。
6. 验证实际文本请求和所有已声明的可选能力。

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

请阅读 troubleshooting.md，了解故障分类和回滚指南。

添加新的 CLI Provider

阅读以下两份文档：

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

按以下优先顺序选择：

1. CLIProxyAPI 原生 OAuth Provider
2. 官方 OpenAI 兼容端点
3. 声明式模型别名／协议映射
4. 有明确边界的本地适配器，作为单独披露的最后手段

将机器本地清单保存到：

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

使用前先验证：

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

然后按新的 Provider ID 授权并同步。新的清单可供同一台机器上的所有 Agent 重复使用，无需修改此 Skill。只有在隔离测试证明安装、认证交接、模型选择、能力准确性和回滚行为均符合要求后，才将其纳入公开 Skill。

安全边界

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

• 将代理绑定到回环地址，并保持远程管理禁用。
• 使用权限模式 0600 保存桥接密钥、OAuth 文件、WorkBuddy 配置和包含凭据的备份。
• 仅使用用户拥有的账户，并遵守 Provider 订阅条款和速率限制。
• 绝不实施规避封禁、共享账户、自动重置封禁、提取令牌或隐藏流量伪装。
• 保留用户创建的 WorkBuddy 模型及无关的 CLIProxyAPI 配置。
• 将 Provider 清单视为代码：执行登录标志前，验证其来源并检查本地覆盖项。

完成门槛

完成工作必须满足以下条件：

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

如果任何门槛尚未得到验证，应将该模型报告为未经验证，而不是宣告成功。