在浏览器中运行编码智能体：fx WebAssembly SDK 完整教程-CSDN博客

在浏览器中运行编码智能体：fx WebAssembly SDK 完整教程

【免费下载链接】fx Unix like coding agent 项目地址: https://gitcode.com/gh_mirrors/fx10/fx

想不想不安装任何命令行工具，直接在浏览器标签页里跑一个编码智能体？fx 是 GitHub 加速计划收录的一个用 Zig 编写的 Unix 风格编码智能体（coding agent），它通过 WebAssembly SDK（libfx） 把完整的智能体核心编译成 fx-core.wasm，让你能在纯前端环境中运行 AI 编程助手。这篇 fx WebAssembly SDK 完整教程会带你从零开始，掌握在浏览器中创建编码智能体和交互式终端的所有核心技巧。

fx 是什么？为什么适合浏览器嵌入？

fx 是一个极简、高性能的开源编码智能体，整个二进制仅约 7.8 MiB。它提供三种嵌入形态：

嵌入方式	说明
`fx acp`	通过 Agent Client Protocol 连接原生编辑器
`createFxAgent()`	用 `fx-core.wasm` 在 JS 宿主中运行无头智能体
`createFxTerminal()`	用 `fx-term.wasm` 运行交互式终端

其中 WebAssembly 形态专为浏览器设计：无原生依赖、跨平台、可嵌入任意网页应用。核心入口源码见 src/wasm_core_main.zig，终端入口见 src/wasm_term_main.zig。

快速开始：浏览器环境要求

在浏览器中使用 fx 编码智能体，你需要满足：

✅ Chrome 或 Edge 137+（支持 WebAssembly JSPI）
✅ 一个 AI Gateway 凭据（短期令牌），或宿主提供的已认证 fetch
✅ 通过 npm 安装 SDK：npm install libfx

安装后包内自带 fx-core.wasm（无头智能体）与 fx-term.wasm（交互式终端），还有零依赖的 JS 宿主层，详见 sdk/README.md。

关键：先检测 JSPI 支持

JSPI（JavaScript Promise Integration）是浏览器内运行异步 Wasm 的关键技术。用 supportsJspi() 做环境检测，一步到位：

import { supportsJspi } from "libfx/browser";

if (!supportsJspi()) {
  throw new Error("当前浏览器不支持 WebAssembly JSPI，请升级到 Chrome/Edge 137+");
}

在浏览器中创建编码智能体：createFxAgent 三步走

掌握 createFxAgent() 就能在网页里跑起编码智能体，全程只要三步：

第一步：创建智能体实例

import { createFxAgent } from "libfx/browser";

const agent = await createFxAgent({
  env: {
    AI_GATEWAY_API_KEY: "<短期凭据>", // 切勿在公开代码中写死长期密钥
  },
});

第二步：发起会话与提问

const session = await agent.createSession();
const turn = session.prompt("解释一下这个项目的目录结构");

for await (const update of turn) {
  console.log(update); // 流式接收智能体的每一步输出
}
console.log("停止原因:", await turn.stopReason);

第三步：优雅关闭

await session.close();
await agent.close();

💡 提示：prompt() 既支持字符串，也支持包含 text 与 resource 块的数组，方便把文件内容作为上下文喂给智能体。

用 AbortSignal 中断编码智能体任务

每个会话同时只允许一个活动任务。用 AbortController 即可随时取消：

const controller = new AbortController();
const turn = session.prompt("继续分析这个文件", {
  signal: controller.signal,
});
controller.abort();
console.log(await turn.stopReason); // 输出 "cancelled"

在浏览器中运行交互式终端：createFxTerminal 配置方法

如果想让用户体验完整的终端交互（就像在浏览器里开了一个 fx 命令行），用 createFxTerminal() 配合 xterm.js 是最快配置方法：

第一步：安装 xterm 依赖

npm install @xterm/xterm @xterm/addon-fit

第二步：创建终端并接入 fx

import { Terminal } from "@xterm/xterm";
import { FitAddon } from "@xterm/addon-fit";
import { createFxTerminal, xtermAdapter } from "libfx/browser";

const terminal = new Terminal({ cursorBlink: true, scrollback: 10_000 });
const fit = new FitAddon();
terminal.loadAddon(fit);
terminal.open(document.querySelector("#terminal"));
fit.fit();

const runtime = await createFxTerminal({
  terminal: xtermAdapter(terminal), // 桥接 xterm.js 与 fx
  env: { AI_GATEWAY_API_KEY: "<短期凭据>" },
});

await runtime.interactive; // 等待终端就绪

第三步：窗口缩放时自动适配

window.addEventListener("resize", () => {
  fit.fit();
  runtime.resize(); // 通知 fx 终端尺寸变化
});

xterm 键盘事件映射由 sdk/fx-sdk.js 中的 encodeXtermKeyEvent() 负责，适配器实现见 xtermAdapter()。

智能体生命周期 API 速查表

createFxAgent() 返回的实例提供完整生命周期控制：

成员	作用
`createSession()`	创建新的活动会话
`openSession(id)`	加载已存储的会话
`listSessions()`	列出已存储会话
`close()`	关闭会话并干净退出
`abort()`	立即中止运行时
`exited`	Promise，解析为进程退出码

终端运行时（createFxTerminal() 返回值）则提供 interactive、exited、write()、resize()、abort() 五个成员，满足终端场景的全部需求。

安全边界：浏览器智能体必须知道的限制

在浏览器中运行的编码智能体与桌面版不同，出于安全考虑，Wasm 运行时不会提供：

❌ 原生进程与 OS 沙箱
❌ 原生 MCP 服务器、子智能体与技能
❌ 剪贴板集成、自动升级
❌ 任意 WASI 文件系统访问与 Web 搜索

同时，不要在公开的浏览器代码里嵌入长期 API Key，请使用短期凭据或经过认证的服务端代理。文件系统访问通过受限的 workspace 适配器（{ action: "exec", command } 契约）交给宿主自行裁决，详见 src/wasm_core_main.zig 与 sdk/README.md 的安全章节。

本地开发调试技巧

仓库自带浏览器调试页面，开发时在仓库根目录执行：

python3 -m http.server 8080

然后打开两个本地页面：

🧪 Core 调试器：http://localhost:8080/sdk/index.html（无头智能体，可切换模型、模式与传输方式）
🖥️ 交互式终端演示：http://localhost:8080/sdk/term-demo.html

构建 Wasm 产物则使用：

zig build -Dwasm-surface=core -Doptimize=ReleaseSmall
zig build -Dwasm-surface=term -Doptimize=ReleaseSmall

需要复现源码环境时，可克隆仓库：git clone https://gitcode.com/gh_mirrors/fx10/fx。

总结

fx 的 WebAssembly SDK 把"Unix 风格编码智能体"完整搬进了浏览器：无头模式用 createFxAgent()，交互式终端用 createFxTerminal()，环境检测用 supportsJspi()。只需三步即可在网页中嵌入一个可对话、可流式输出、可中断的 AI 编程助手。本文覆盖了环境准备、智能体创建、终端接入、生命周期管理与安全边界，跟着教程动手试一试，你也能快速拥有一个属于自己的浏览器编码智能体。🎉

【免费下载链接】fx Unix like coding agent 项目地址: https://gitcode.com/gh_mirrors/fx10/fx

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考