J.A.R.V.I.S.的大脑:用Claude Agent SDK把Claude Code跑成无头库,构建零API Key助手

原创2026-11-04 09:48:582,000 阅读

J.A.R.V.I.S.的大脑:用Claude Agent SDK把Claude Code跑成无头库,构建零API Key助手

J.A.R.V.I.S. 是一个跑在浏览器里的钢铁侠全息语音助手,它的大脑正是 Claude Code——通过 Claude Agent SDK 以无头(headless)库的形式运行,完全复用你已有的 Claude Code 登录态,无需任何 API Key。项目地址:https://gitcode.com/gh_mirrors/jarvis90/jarvis。

一、为什么浏览器里跑不了 Claude Code?

大多数 AI 应用的常规做法是:网页直接调 Claude API。但这条路有两个致命问题:

  • 要 API Key:密钥要么写进前端代码(谁打开 DevTools 谁就能看到),要么再搭一个中转服务;
  • 够不到本地工具:浏览器标签页无法启动本地 stdio 的 MCP 服务器(图像生成、手机控制、语音合成等),而这些恰恰是语音助手最需要的"手脚"。

J.A.R.V.I.S. 的答案是:不在浏览器里调 API,而是在本机起一个 Node 进程(bridge),把 Claude Code 当成一个库来用。这正是 Claude Agent SDK(@anthropic-ai/claude-agent-sdk)的设计初衷——它会真正拉起 claude CLI 子进程,所以"大脑"字面意义上就是无头运行的 Claude Code。

依赖声明在 package.json 中:

"@anthropic-ai/claude-agent-sdk": "^0.3.220"

二、双进程架构:脸在大屏上,脑在本机上

整个系统只有两个进程,职责划分非常清晰:

┌─ 浏览器(脸)────────────────┐        ┌─ bridge(脑)────────────────┐
│  "Hey Jarvis" 唤醒词          │        │  Node · bridge/server.mjs    │
│  本地 VAD → 语音转文字        │   ws   │  Claude Agent SDK            │
│  Reactor 界面(Three.js+GLSL)│◄─────►│  = 无头 Claude Code          │
│  文字转语音                    │ 8787  │  拉起你的 MCP 服务器         │
└───────────────────────────────┘        └──────────────────────────────┘

你看到、听到的一切都在浏览器里发生;bridge 是单个 Node 进程 bridge/server.mjs,两者通过 ws://localhost:8787 的 WebSocket 通信。架构说明来自 README.md 的 "How it works" 一节。

前端这边,src/lib/brain.ts 统一封装了两种"大脑"的切换:默认的 bridge 模式走本地进程(零 API Key、可用全部 MCP 服务器);备用 direct 模式由浏览器直连 Claude API(需 VITE_ANTHROPIC_API_KEY,仅能访问远程 HTTP MCP),切换逻辑见 src/config.ts。

三、三步跑起来:最快上手步骤

准备工作只有一句话:一个 Claude Code 订阅(或已登录的 Claude Code)+ Node.js 20+ + Chrome,ElevenLabs Key 是可选增强。

git clone https://gitcode.com/gh_mirrors/jarvis90/jarvis
cd jarvis
npm install
npm run setup   # 体检脚本:检查 Node、claude CLI、MCP 配置
npm start       # 一键同时启动"脑"和"脸"

然后在 Chrome 中打开 http://localhost:5173,点击 INITIALISE,对麦克风说 "Hey Jarvis" 即可唤醒。

⚠️ 必须是真实浏览器窗口,编辑器内嵌预览会屏蔽麦克风,JARVIS 会"看起来活着但永远不理你"。

几个关键脚本:

命令 作用
npm start 一键启动 brain + face(scripts/start.mjs)
npm run bridge 只启动大脑 bridge/server.mjs
npm run dev 只启动前端 Vite 开发服务器
npm run bridge:writes 开启写权限(手机/浏览器操作类工具)
npm run setup 只读体检,不改任何东西(scripts/setup.mjs)

四、零 API Key 的秘密:复用登录态 + 显式传参

bridge 的核心就是一个 query() 调用(bridge/server.mjs),几个关键参数值得逐条拆解:

  • 鉴权:不传任何 Key,SDK 沿用你 claude CLI 的登录态,费用直接计在你已有的 Claude 账户上;
  • mcpServers:手动读取 ~/.claude.json 里配置的全部 MCP 服务器并显式传入(bridge/server.mjs)——因为下面这行把自动发现关掉了;
  • settingSources: []:不加载文件系统设置。这有两个目的:让 bridge 自己的权限闸门成为唯一权威(全局 bypassPermissions 无法绕过),同时阻止写给编程场景的 CLAUDE.md 塞进每轮语音对话;
  • systemPrompt:不用 claude_code 预设,换成一段"英国管家人设"提示词(bridge/server.mjs),要求回答中位数不超过 12 个词——因为每个字都要读出来;
  • includePartialMessages: true:没有增量事件,JARVIS 就要等整段回答写完才开口;有了它,第一句话说完就能立即朗读;
  • maxTurns: 24:给每轮对话一个兜底上限。

启动时 bridge 会在终端打印当前模型与推理力度(默认 claude-opus-5),可用 JARVIS_MODEL / JARVIS_EFFORT 环境变量覆盖。

五、权限闸门:默认只读,写操作要"申请"

语音是很糟糕的确认对话框——你没法对着空气点"确认"。所以 J.A.R.V.I.S. 的做法是在启动前就决定好策略:bridge/server.mjs 中的 decideTool() 函数是最后一道闸门:

  • 只读/生成类工具(搜索、图像生成、列表查询)→ 直接放行;
  • 工具名带 send / delete / install / pay 等"实效动词"→ 默认拒绝;
  • 需要动真格时,改用 npm run bridge:writes 启动(等价于 JARVIS_ALLOW_WRITES=1),放行写操作。

该闸门通过 SDK 的 canUseTool 回调生效(bridge/server.mjs),被拒的工具会收到一段"会被读出来"的拒绝理由。官方 README 也提醒:开写权限前请先读完 decideTool()——"Hey Jarvis,清理一下我的下载文件夹"在有写权限时是另一回事了。

六、JARVIS 的"手脚":内置 MCP 工具服务器

除了你在 Claude Code 里配置的服务器,bridge 还用 SDK 的 createSdkMcpServer 在进程内注册了四组自己的工具:

模块 工具 能力
bridge/panels.mjs display / blade 模型自己撰写 HTML,按 .hud-* 设计系统生成全息面板(浏览器侧经 DOMPurify 消毒后渲染)
bridge/ui.mjs ui_theme、ui_reactor、ui_orbit、ui_effect… JARVIS 控制自己的脸:换色、变形、粒子特效,"变红、隐藏列表、把图挂到轨道上"是一句语音指令
bridge/chrome.mjs chrome_* 通过 Claude for Chrome 扩展的本地 socket 直接驱动你真实登录着的 Chrome,而不是无 cookies 的 Playwright
bridge/vision.mjs look / watch 相机帧经"请求-应答"通道回传给模型,帧用完即弃、不落盘

远程图片/视频则由 bridge 服务端代理抓取(/img、/media,带 SSRF 防护),既能绕过防盗链,又保证页面从不直接暴露你的 IP 给模型选中的主机。

七、安全设计清单

bridge 的注释写得非常"较真",核心防线(详见 README.md 的 Security 一节):

  1. Origin 白名单:WebSocket 握手阶段即拒绝非本地开发源的连接,缺失 Origin 的客户端(curl、脚本、本地恶意程序)默认拒之门外;
  2. 文件端点最小化:/file 只服务白名单图片扩展名、只读白名单根目录、先解析符号链接再校验路径,且刻意不服务 .svg(SVG 是脚本);
  3. 严格 CSP + 消毒:模型撰写的面板 HTML 经 DOMPurify、class 白名单和严格 Content-Security-Policy 后才上屏;
  4. 工具闸门默认拒绝:上文第五节的 decideTool 策略。

八、常用配置速查

bridge 侧全部为环境变量(README.md Configuration 一节):

变量 默认值 说明
JARVIS_BRIDGE_PORT 8787 WebSocket + HTTP 端口
JARVIS_MODEL claude-opus-5 运行模型
JARVIS_EFFORT medium 推理力度
JARVIS_ALLOW_WRITES 关 1 放行写操作工具
ELEVENLABS_API_KEY — 可选:更好音质 + Scribe 转写

前端配置写在 .env.local(如 VITE_BACKEND、VITE_BRIDGE_URL),ElevenLabs Key 也可以放在 ~/.claude.json 的 elevenlabs MCP 条目里,bridge 会自动借用——没有任何需要手动打开的开关,/health 探针(src/lib/capabilities.ts)会在启动时自动选择最优语音引擎,没 Key 就回落到浏览器自带语音。

九、总结:这个架构好在哪?

🧠 零 API Key:鉴权、计费、模型推理全部落在你已有的 Claude Code 订阅上,低配笔记本只负责渲染界面;

🔌 工具即插即用:~/.claude.json 里配了多少 MCP 服务器,JARVIS 就能用多少,包括浏览器永远够不到的本地 stdio 服务;

🔒 权限策略前置:读操作自由、写操作默认拒绝、总开关一个环境变量,安全边界清晰可审计;

🗣 流式优先:增量事件驱动语音,开口快、可被打断(barge-in),像一个真正的对话者而不是播报机。

如果你想在本地拥有一个"说句话就能搜网页、生成图像、驱动浏览器"的私人 JARVIS,这条 Claude Agent SDK + 无头 Claude Code + WebSocket bridge 的路线值得直接参考,核心代码全部集中在 bridge/ 目录下,单个文件读完就能复刻。

登录后查看全文
jarvis