Switchyard

Switchyard Dev Bootstrap

文档目的

这份 runbook 面向的是：

它不回答“产品为什么存在”，而回答：

今天在这台机器上，怎样把开发环境、参考运行时、验证前提和第一步实现准备到位。

适用边界

本 runbook 只服务当前 V1 主线：

它不服务：

成功定义

完成本 runbook 后，应该达到以下状态：

  1. Switchyard 仓本地开发环境已准备好
  2. 关键参考运行时可被本地研究
  3. V1 固定 5 家网页登录 provider 的账户/测试前提明确
  4. LiteLLM 与 openclaw-zero-token 能以 lab sidecar 身份被使用
  5. 实现者知道下一步应该进入 Kernel Alpha，而不是继续想 abstract strategy

当前验证分层（5 layers）

这份 runbook 现在只负责第五层，也就是 manual / credentialed workstation。

更直白一点说：

如果你要看完整 5-layer 总图，先看：

当前 live reality（truth-first checkpoint）

这份 runbook 现在不能再按“仓库还是 docs-only、还没开工”来理解。

当前工作区现实已经是：

当前更保守、也更适合接手验收的写法是：

当前 closeout 输出里的 external-blocker 还会再带一个 classification 字段，用来说明“为什么它仍然是外部尾巴”：

所以这份 runbook 现在服务的现实阶段，不再是：

“所有 gate 都重新回到全绿的固定工作站”

而更接近：

“在 repo-side gate 已过、但 current workspace live truth 仍停在一组 workstation-bound external blockers 的 credentialed workstation 上，继续维护 repo-local runtime hygiene，并在未来环境变化时重新做 truth reset”

同时保留一个很重要的护栏：

这类 live checkpoint 天生会过期。

runbook 里的 checkpoint 不是永久真理；每次接手都应 fresh 运行：

它也不覆盖更高优先级的 ADR / blueprint / task board。

这份 runbook 记录的是“当前这台机器最近一次怎么跑通”，不是正式改写阶段裁决的地方。

当前还多了一个很实用的 M2 证据脚本：

这条脚本会直接启动本地 Switchyard service，并通过统一的 service-first invoke 入口验证高稳定 trio：

它的作用不是替代 reality:gate，而是补一张更面向 M2 / service-first readiness 的成绩单：

当前还多了一条很实用的 browser diagnosis 工具：

pnpm run diagnose:web-login-browser -- --provider chatgpt --reload --json

它不是另一个 aggregate gate。
它更像一把手电筒，专门照这件事：

为什么 auth store 已经显示 ready， 但 live verifier 还是说 browser session 不完整。

这条命令会输出：

如果你本地已经把 service 跑起来了，现在还有一组更细的只读 CLI 读法：

pnpm run switchyard:cli -- provider-store-readiness --provider chatgpt
pnpm run switchyard:cli -- provider-live-readiness --provider chatgpt
pnpm run switchyard:cli -- provider-attach-target --provider chatgpt
pnpm run switchyard:cli -- provider-diagnose-ladder --provider chatgpt
pnpm run switchyard:cli -- provider-diagnose --provider chatgpt
pnpm run switchyard:cli -- surface-catalog
pnpm run switchyard:cli -- compat-targets
pnpm run switchyard:cli -- compat-target --target codex
pnpm run switchyard:cli -- mcp-status
pnpm run switchyard:cli -- mcp-tools

可以先这样理解：

这些命令现在只属于本地排障手册。
它们不等于 public CLI 已经升格成 today supported surface。

更直白一点说：

本地运行时磁盘治理

这条 runbook 现在还多了一个 repo-local 的磁盘治理入口：

pnpm run audit:runtime-footprint
pnpm run cleanup:runtime -- --dry-run

先把它理解成：

当前 .runtime-cache/ 里的东西要分 4 类看：

repo 外如果还需要当前仓专属的临时缓存，也只能进：

默认治理规则现在是：

护栏也要说清楚：

在执行 live / browser / cleanup 类命令前，先跑：

pnpm run scan:host-process-risks

本地 credentialed 浏览器默认模式

现在这仓更推荐的本地 credentialed 工作方式不是 repo-local managed browser 常开，而是：

推荐环境变量：

export SWITCHYARD_BROWSER_MODE=isolated-chrome-root
export SWITCHYARD_CHROME_USER_DATA_DIR="$HOME/.cache/switchyard/browser/chrome-user-data"
export SWITCHYARD_CHROME_PROFILE_NAME="switchyard"
export SWITCHYARD_EXTERNAL_CACHE_ROOT="$HOME/.cache/switchyard"
export SWITCHYARD_CACHE_TTL_DAYS=7
export SWITCHYARD_CACHE_MAX_BYTES=8589934592
export SWITCHYARD_WEB_AUTH_EXISTING_PROFILE_CDP_URL="http://127.0.0.1:9338"

这里要记住一个边界：

~/.cache/switchyard/browser/chrome-user-data 是当前 repo 的永久浏览器工位。 它属于 repo 专属 steady-state browser root，不参与 TTL / cap 自动裁剪。

第一次把默认 Chrome 根目录里的 switchyard profile 搬进来，要显式跑：

pnpm run seed:isolated-chrome-root -- --json

只有你明确要重建独立根目录时，才允许：

pnpm run reseed:isolated-chrome-root -- --json

现在也明确一条 fail-closed 规则：

这轮还补了一条宿主机安全边界：

bootstrap-web-auth-browser 现在不能再通过 detached: true + .unref() 偷留一个 Chrome child handle。 新实例启动必须走宿主机 launcher handoff；已在线的 repo-owned 浏览器若需要补开登录页，走 CDP /json/new。 如果宿主机不能证明这条 handoff 是安全成立的，脚本必须 fail-closed，让你改走 existing-browser-session / 手工启动，而不是偷偷回退到 detached launch。

这轮还新增了一条很关键的 coherence 纪律：

ready 不再只由 .runtime-cache/local-web-auth-store.json 单独决定。
后续 live verify 会同时核对：

如果 store 还说 ready，但当前浏览器页已经掉到登录页，或者当前 root 上关键 cookie 不在，系统会把它降级成：

CI 边界

当前仓继续只使用 GitHub Hosted Runner，不引入 self-hosted。

云端 CI 只跑：

下面这些仍然是 local credentialed only：

如果这些 live 路径在 CI 环境中被误触发，现在应该直接 fail-closed，报出 credentialed-workstation only，而不是偷偷依赖云端没有的本地登录态或真实 Chrome Profile。

共享机器资源预算

这台机器是共享实验室，不是当前 repo 一个人的桌子。

当前 repo 的默认预算是：

如果两次检查都已经说明当前 repo 自己的 canonical browser/profile 里没有有效登录态，就把它记成 blocker。不要继续靠多开浏览器、重复 clone profile、反复 attach session 碰运气。

Docker 边界

当前 Switchyard 没有 repo-owned Docker runtime。

一、先读完这些文档

在跑任何命令前，先读：

  1. README.md
  2. docs/product/v1-brief.md
  3. docs/product/scope-and-nongoals.md
  4. docs/adr/0001-v1-boundary-and-lane-model.md
  5. docs/adr/0002-external-repo-adoption-matrix.md
  6. docs/adr/0003-upstream-relationship-openclaw-zero-token.md
  7. docs/adr/0004-architecture-skeleton-monorepo.md
  8. docs/contracts/provider-runtime-contract.md
  9. docs/contracts/auth-accounts-and-credentials.md
  10. docs/contracts/service-and-sdk-surfaces.md
  11. docs/blueprints/v1-delivery-plan.md
  12. .agents/Tasks/TASK_BOARD-2026-03-29-switchyard-bootstrap.md

如果这些没读够，就不要开工写代码。

二、宿主环境准备

必需工具

最小检查

node -v
pnpm -v
python3 --version
git --version

当前阶段，只要这些工具存在并能工作，就已经够开始实现 Switchyard 的 Day 1 范围。

三、参考仓就位检查

当前主线只看这 3 个主参考：

边缘/后续参考只在需要时看：

检查参考仓是否存在

ls '<local-reference-root>'

当前明确排除

不要再把已经被正式移出主线的历史小样本仓拉回当前研究主线。

即使本地未来又重新出现，也只允许作为备查，不允许进入当前主线合同。

四、Vercel AI SDK 准备方式

当前定位

对实现者的含义

Vercel AI SDK 不需要先独立跑成一个 sidecar。
它更像是 Switchyard 自己将来会直接依赖的核心包。

当前要做的不是

当前要做的是

五、LiteLLM 准备方式

当前定位

启动方式

根据本地 README，当前最小实验方式可以是：

pip install 'litellm[proxy]'
litellm --model gpt-4o

你为什么要跑它

不是因为 Switchyard 要依赖它做核心内核，而是为了：

它当前在 Switchyard 里扮演什么

不是：

六、openclaw-zero-token 准备方式

当前定位

当前工作区本地路径

本地技术母本路径按占位写法记为：

<local-reference-root>/openclaw-zero-token

其中 <local-reference-root> 表示你在本机存放第三方参考仓的根目录；公开 runbook 不写个人绝对路径。

为什么必须跑起来

因为它不是一个小库，而是一个完整运行时平台。
如果只看 README，不把它真正当 sidecar 研究，你很难理解：

最小研究式启动路径

根据本地 README，最小研究路径是：

pnpm install
pnpm build
pnpm ui:build
./start-chrome-debug.sh
./onboard.sh webauth
./server.sh

当前要观察什么

不要把精力花在它的全产品世界上。
当前只观察这些层：

  1. Web/Login provider runtime
  2. auth/session/refresh 路径
  3. gateway 运行形态
  4. OpenResponses-compatible HTTP surface
  5. diagnostics / operator-facing 状态模型

当前必须优先看的源码入口

如果你要继续推进 Web/Login、live-proof、acquisition、browser transport，优先看这些本地源码：

换句话说：

当前 Web/Login lane 最值钱的学习路径，不是继续在小样本仓里横跳，而是直接深读 openclaw-zero-token 本地母本。

当前不要被带偏到什么

不要把注意力消耗在：

这些是它的产品世界，不是 Switchyard V1 的施工面。

七、V1 账号与测试前提准备

网页登录固定目标 provider

必须准备好：

  1. ChatGPT
  2. Gemini
  3. Claude
  4. Grok
  5. Qwen

当前约束

BYOK 准备

当前必须确保：

其余 provider 可以暂时停在：

而不必全部先做真实 credential 验证。

Reality Gate proof 输入

如果要跑当前仓里的 reality-gate proof，当前约定是：

当前推荐的本地浏览器准备方式

如果你要走 Web/Login acquisition 主路径，默认优先让 Switchyard 自己准备浏览器，而不是手工研究某个 9222 Chrome：

pnpm run bootstrap:web-login-browser -- --provider chatgpt
pnpm run bootstrap:web-login-browser -- --provider gemini
pnpm run bootstrap:web-login-browser -- --provider grok

这条脚本会尝试启动或复用 Switchyard 自己的本地 onboarding 浏览器，再打开对应 provider 登录页。
这是默认模式，也就是：

当前还存在两条高级 acquisition 路径：

它们仍然属于同一条 local-first acquisition/store 主线，但只在你明确需要复用已有 Chrome 登录态时才启用。
换句话说：

只有当你在做 fallback/debug/proof harness 时，才需要回到 env 层面关注 SWITCHYARD_WEB_AUTH_CDP_URL 一类底层变量；产品主路径不应该要求用户先理解这些实现细节。

这里的 <PROVIDER> 当前对应：

这些变量只用于 终端用户自己的本地 proof 输入，不是平台共享凭证，也不是公共账号池配置。

当前 .env 自动加载行为

当前仓里的以下入口会自动加载 repo 根目录的 .env.local 与 .env：

加载顺序是：

  1. .env.local
  2. .env

同时保留一条更高优先级规则：

已经存在于 shell 的环境变量优先，.env* 只补缺，不覆盖。

这里必须再强调一次：

这套 env 输入只是当前 reality gate / closeout harness 的 proof 契约。

它不是最终产品主 UX。

最终产品主路径应该是：

八、定义“环境已准备好”

当且仅当下面这些条件成立，才算“可以进入 Kernel Alpha 实现”：

文档面

宿主环境面

都可用

参考运行时面

测试前提面

认知面

实现者已经明确知道：

九、进入实现前的最后提醒

不要做的事

现在该做的事

进入 Kernel Alpha，从这些开始：

  1. contracts
  2. kernel
  3. credentials
  4. diagnostics
  5. lanes/byok
  6. lanes/web
  7. providers/byok/*
  8. providers/web/*
  9. surfaces/http

十、Decision Summary

这份 runbook 的核心不是“把所有东西都跑起来”。
而是：

把实现者带到一个足够确定的起跑线。

到达这条线之后，下一步就不该继续聊抽象，而应该进入 Kernel Alpha 的代码实现。

This site is open source. Improve this page.