附录：Bridge Runtime 兼容说明

Bridge 是兼容外部 Agent CLI 的可选路径。Hadamard SDK 本身不依赖 Bridge；新应用的独立 Runtime 主线见 01–04 章。

这一章解释什么是 bridge，以及什么时候才需要使用它。

1. 前置条件 — 链接运行时 bundle

hadamard-bridge-sdk 依赖第三方 agent runtime 的运行时 bundle（例如 Claude Code）。该文件不包含在 actoviq-agent-sdk 包中。

如果你已安装 Claude Code，可以链接它的 bundle：

bash

# Claude Code 的 npm 包名为 @anthropic-ai/claude-code

# macOS / Linux（npm 全局安装）
npx hadamard-link-runtime /usr/local/lib/node_modules/@anthropic-ai/claude-code

# macOS / Linux（nvm 安装）
npx hadamard-link-runtime ~/.nvm/versions/node/v22/lib/node_modules/@anthropic-ai/claude-code

# Windows
npx hadamard-link-runtime %AppData%\npm\node_modules\@anthropic-ai\claude-code

# 或者让 npm 自己找：
npx hadamard-link-runtime "$(npm root -g)/@anthropic-ai/claude-code"

或者设置环境变量：

bash

export HADAMARD_RUNTIME_BUNDLE="/path/to/runtime-bundle"

没有这个 bundle，hadamard-bridge-sdk 功能将不可用。

注意（原生 exe 形态的 Claude Code）： 新版 @anthropic-ai/claude-code 以原生可执行文件发布（bin/claude.exe），包内没有 runtime.bundle.br， hadamard-link-runtime 对它无法生效。此时请改用下面的 directCli 模式，它直接 spawn 本机 claude 二进制，不需要 bundle。

1.1 直接复用本机 Claude Code（directCli 模式）

如果你已在 PATH 上装好 Claude Code，可以跳过 bundle，直接让 bridge spawn 本机的 claude：

import { createHadamardBridgeSdk } from 'actoviq-agent-sdk';

const sdk = await createHadamardBridgeSdk({
  directCli: true,           // spawn 本机 claude，绕过 runtime.bundle.br + Bun
  // executable: 'claude',   // 可选，默认在 PATH 上找 `claude`
  workDir: process.cwd(),
});

const result = await sdk.run('用一句话总结当前目录。');

directCli 模式的工作方式（与 multica daemon 的 "shell out by name" 一致）： bridge 在 PATH 上找到 claude，以 -p --output-format stream-json --verbose … 参数 spawn 它，并解析标准 system/assistant/result 事件流——与 bundle 模式的协议完全相同，只是子进程换成了你本机安装的官方 claude。

Provider 隔离（关键能力）： directCli 模式完整保留 hadamard 的 env 注入链（~/.hadamard/settings.json 的 env 块 → ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_MODEL 等，见 anthropicEnvMapping.ts）。因此你可以让 交互式 claude 走 Claude 官方，而 bridge 下的 claude 子进程重定向到 DeepSeek 等其他 provider——子进程的 ANTHROPIC_* 环境变量覆盖 ~/.claude/settings.json，两者互不干扰。例：

json

// ~/.hadamard/settings.json（仅影响 bridge 子进程，不影响交互式 claude）
{
  "env": {
    "HADAMARD_AUTH_TOKEN": "sk-...",
    "HADAMARD_BASE_URL": "https://api.deepseek.com/anthropic",
    "HADAMARD_DEFAULT_MAX_MODEL": "deepseek-v4-pro"
  }
}

提示：若你的 PowerShell 当前 shell 已 ANTHROPIC_API_KEY 指向 Claude 官方，且 settings.json 未配凭证，子进程会回退到该值——请把 provider 配置写全。

1.2 六大 provider（claude / pi / codex / codewhale / reasonix / crush）

Provider	`directCliProvider`	本机二进制	入口	协议
Claude Code（默认）	`'claude'`	`claude`	`claude -p --output-format stream-json …`	stream-json
pi	`'pi'`	`pi`	`pi -p --mode json …`	JSONL
codex	`'codex'`	`codex`	`codex exec --json …`	JSONL
CodeWhale	`'codewhale'`	`codewhale`	`codewhale exec --auto --output-format stream-json …`	stream-json（与 claude 相同）
Reasonix	`'reasonix'`	`reasonix`	`reasonix run [--model] [--effort] <task>`	纯文本
Crush	`'crush'`	`crush`	`crush run [--model] [--session] <prompt>`	纯文本

const sdk = await createHadamardBridgeSdk({
  directCli: true,
  directCliProvider: 'codewhale',   // 或 'reasonix', 'crush', …
  workDir: process.cwd(),
});

凭证： claude → ANTHROPIC_*；codewhale → ANTHROPIC_/DEEPSEEK_； reasonix → DEEPSEEK_；crush → OPENAI_/ANTHROPIC_*。在 ~/.hadamard/settings.json 的 env 块里直接写对应 provider 的 key。

Introspection 降级 适用于 pi/codex/reasonix/crush（启动事件不含 tools/skills 清单）。 run/stream/session 等生命周期方法六家完整对齐。

1.3 环境覆盖与自动检测

`HADAMARD_<PROVIDER>_PATH`

当 CLI 不在 PATH 上时，用它覆盖自动检测的二进制路径：

bash

export HADAMARD_CLAUDE_PATH=/opt/claude-code/bin/claude
export HADAMARD_CODEX_PATH=/custom/codex
export HADAMARD_REASONIX_PATH=~/bin/reasonix
# … 每个 provider 都遵循 HADAMARD_<ID>_PATH 模式

写在 ~/.hadamard/settings.json 的 env 块（或顶层）——与 HADAMARD_BASH_PATH 惯例一致。

`bridge` 设置块

jsonc

// ~/.hadamard/settings.json
{
  "bridge": {
    "defaultProvider": "codewhale",
    "providers": {
      "crush": { "path": "/opt/crush" }
    }
  }
}

解析优先级（全部在内存中，run 时无文件 I/O）： executable 选项 → HADAMARD_<ID>_PATH 环境变量 → bridge.providers[id].path → PATH。

`detectBridgeProviders()` API

import { detectBridgeProviders } from 'actoviq-agent-sdk';

const providers = await detectBridgeProviders();
// [{ id:'claude', available:true, path:'/…/claude.cmd', version:'2.1.186', displayName:'…' }, …]

返回每个已注册 provider 的条目，包含 best-effort --version 探测。被 CLI 的 /bridge 向导、TUI 的 /bridge 控制面板、GUI 的 Settings→Bridge 面板使用。

TUI 运行时切换

在 TUI 中，/bridge 打开已保存连接配置的控制面板。选中一个配置即将其激活为当前运行时：此后直接输入的每条普通 prompt 都会经该配置的 provider/apiKey/baseURL/model 在进程内 执行——不启动子进程。预构建的模型客户端按轮次通过 session.stream({model, modelApi}) 注入（/model 路由器使用的相同机制），复用整个 TUI——实时状态 spinner、流式 transcript、工具卡片、Esc 中断、输入历史。/bridge off 切回 SDK 默认 provider。由于 bridge 和普通轮次使用同一个 Hadamard session，切换 bridge↔hadamard 时上下文不丢失，/resume 可看到完整对话——"相当于一直用 claude code，直到你退出"。

命名 bridge 配置

/bridge config 打开配置管理界面：新增配置（或对已有配置编辑/删除）会进入一个单页配置编辑器，一次性显示所有字段——名称、provider（运行时）、apiKey、 baseURL、可选的 model——并显示每个字段的当前值。你可以按任意顺序编辑任意字段（例如先配置好 key，再回去修改名称），然后保存提交或取消放弃。配置保存在 ~/.hadamard/bridge-configs.json。每个 config 是一个完整预设——例如 deepseek-claude（provider=claude、ANTHROPIC_BASE_URL=https://api.deepseek.com、 ANTHROPIC_API_KEY=…、model=deepseek-chat）——可以保留多个后端配置，按名称切换。

保存后，/bridge 会列出已保存的配置；选中一个（或 /bridge switch <名称>）即激活该运行时。config 的凭证会逐轮注入（作为 per-run env 覆盖，优先级高于 ~/.hadamard/settings.json），随后作为普通多轮对话运行，支持全部 agent 功能。/bridge off 切回进程内 SDK。可在 /bridge config 中编辑/删除配置；编辑当前激活的配置将在下一轮生效。

按 provider 的凭证映射：claude/codewhale → ANTHROPIC_*；pi/codex → OPENAI_* （baseURL 含 anthropic 时 pi 用 ANTHROPIC_*）；reasonix → DEEPSEEK_API_KEY； crush → OPENAI_API_KEY。实现：src/parity/bridgeConfigs.ts（buildConfigEnv）。

1.4 问题排查——没有检测到 runtime？

安装 CLI（npm i -g @anthropic-ai/claude-code、npm i -g codewhale、…）并重启 shell 确保它在 PATH 上。
运行 npx hadamard-tui 并输入 /bridge——控制面板会展示检测到的 provider，让你选择一个作为默认。
设置 HADAMARD_<ID>_PATH（见 1.3），适用于二进制已安装但不在 PATH 的情况（CI、不继承 shell profile 的 IDE 启动器等常见场景）。
让 Claude Code 帮忙： 把 /providers 的输出（或 GUI 的「Detect runtimes」按钮结果）贴给 Claude Code，让它指导安装和配置。

实现：src/parity/bridgeProviders.ts（各 provider 的 argv/env/normalizer + BRIDGE_PROVIDER_CREDENTIALS 凭证就绪提示），src/tui/hadamardTui.ts（TUI /bridge 控制面板——一键激活 provider、逐 provider 设置模型、凭证提示、实跑状态；run/switch/model/setup/off/help 子命令支持自动补全），src/gui/hadamardGui.ts（bridge 面板 + 实跑）。

2. bridge 是什么

bridge 可以理解成一层兼容适配层。它暴露的是更偏 runtime 风格的执行路径。

入口：

import { createHadamardBridgeSdk } from 'actoviq-agent-sdk';

2. 什么情况下才需要 bridge

更适合使用 bridge 的场景：

你要研究现有 runtime 的行为
你要查看 runtime 当前有哪些 tools / skills / agents
你要分析 runtime 事件流
你要做兼容层、迁移层或对照测试

如果你是在开发一个新的业务项目，通常优先使用 Hadamard SDK：

createAgentSdk()

bridge 更适合“兼容”和“研究”，不是默认主路径。

3. 最小 bridge 示例

import {
  createHadamardBridgeSdk,
  loadDefaultHadamardSettings,
} from 'actoviq-agent-sdk';

await loadDefaultHadamardSettings();

const sdk = await createHadamardBridgeSdk({
  workDir: process.cwd(),
  maxTurns: 4,
});

const result = await sdk.run('检查 examples 目录，并总结 quickstart.ts。');

console.log(result.text);
console.log(result.events.length);

4. Runtime Introspection

bridge 可以查看当前 runtime 暴露出来的能力：

const runtime = await sdk.getRuntimeInfo();

console.log(runtime.tools);
console.log(runtime.skills);
console.log(runtime.agents);

仓库示例：

5. Bridge Helper

bridge 侧还支持：

sdk.runSkill(...)
sdk.runWithAgent(...)
sdk.sessions.continueMostRecent(...)
sdk.sessions.fork(...)
session.runSkill(...)
session.compact(...)

6. Bridge 事件 Helper

如果你要分析 runtime 输出的事件流，可以使用：

getHadamardBridgeTextDelta(...)
extractHadamardBridgeToolRequests(...)
extractHadamardBridgeToolResults(...)
extractHadamardBridgeTaskInvocations(...)
analyzeHadamardBridgeEvents(...)

05-testing-troubleshooting-cheatsheet.md

附录：Bridge Runtime 兼容说明 ​

1. 前置条件 — 链接运行时 bundle ​

1.1 直接复用本机 Claude Code（directCli 模式） ​

1.2 六大 provider（claude / pi / codex / codewhale / reasonix / crush） ​

1.3 环境覆盖与自动检测 ​

HADAMARD_<PROVIDER>_PATH ​

bridge 设置块 ​

detectBridgeProviders() API ​

TUI 运行时切换 ​

命名 bridge 配置 ​

1.4 问题排查——没有检测到 runtime？ ​

2. bridge 是什么 ​

2. 什么情况下才需要 bridge ​

3. 最小 bridge 示例 ​

4. Runtime Introspection ​

5. Bridge Helper ​

6. Bridge 事件 Helper ​

附录：Bridge Runtime 兼容说明

1. 前置条件 — 链接运行时 bundle

1.1 直接复用本机 Claude Code（directCli 模式）

1.2 六大 provider（claude / pi / codex / codewhale / reasonix / crush）

1.3 环境覆盖与自动检测

`HADAMARD_<PROVIDER>_PATH`

`bridge` 设置块

`detectBridgeProviders()` API

TUI 运行时切换

命名 bridge 配置

1.4 问题排查——没有检测到 runtime？

2. bridge 是什么

2. 什么情况下才需要 bridge

3. 最小 bridge 示例

4. Runtime Introspection

5. Bridge Helper

6. Bridge 事件 Helper