热插拔画布 pihme/fregoli

Fregoli

Fregoli 是个 Web 应用，智能体能在它运行期间直接改写它。不用改文件再重启进程：各项能力都是 Cordis 插件，在活着的 Node 进程里挂载和卸载。名字取自 Leopoldo Fregoli（1867–1936），那位快速换装艺人：一个演员，千般扮相，演出从不中断。

启动后，你会拿到一个跑在 8080 端口的画布，右下角还有个助手聊天框。grok 在 PATH 上时，聊天经 ACP 转给 Grok CLI；否则转给进程内的桩实现。Grok 会收到一个 MCP 服务器，借此观察页面、加载和卸载插件、高亮元素，并等待用户点击。

命令行名字完整写作 fregoli，不要缩写成 freg。

- 网站 — 手册与当前状态
- 规格说明 — 产品规格
- 使用指南 — 命令行、HTTP、Grok、Docker
- 参与贡献 — 欢迎提 issue，暂不接受外部 pull request

三个问题

Fregoli 围绕三个问题构建：

1. 如果你不必再买现成软件，而是能自己造，会怎样？
2. 如果软件不是一次做完交付，而是能不断变化，会怎样？
3. 如果 AI 不只造软件，还能在这软件里接手那些确定性软件做不了的任务，会怎样？

快速上手

需要 Node 22+。想接真智能体，还要 PATH 上有 Grok CLI（通过 Grok CLI 登录或 XAI_API_KEY 认证）。

git clone https://github.com/pihme/fregoli.git
cd fregoli
npm ci
npx tsx src/cli.ts # http://127.0.0.1:8080/
npx tsx src/cli.ts --assistant # force the stock assistant UI
npx tsx src/cli.ts --version
npm link # puts fregoli on PATH; uses the tsx in this checkout
启动时会显示欢迎画布（plugins/shipped/welcome.ts）。右下角的助手是 Helferlein 形象（v0.1.2）：静止时点它会打开聊天；聊天打开后，它浮在面板上方。智能体应用改动后，它会换一个新造型，浏览器会记住这个造型。grok 可用时，聊天通过 ACP 交给 Grok；否则走进程内 stub。启动时加 --assistant，本次启动强制使用内置助手 UI。fregoli 命令能存在，靠的是 npm link，不需要全局 tsx。

跑测试（合并门槛）：

npm test

容器镜像（Hermetarium 是推荐栖息地，不是必需）：

docker build -t fregoli:local --build-arg FREGOLI_VERSION="$(git describe --tags --match 'fregoli/v' 2>/dev/null || echo dev)" .
docker run --rm -p 8080:8080 fregoli:local

镜像监听 0.0.0.0:8080，包含 plugins/shipped/、fregoli.json 和 .grok/skills/fregoli-app/，并安装 iproute2 和 iptables，供 Hermetarium 防火墙使用。本地进程仍监听 127.0.0.1，除非你传 --host 或设置 FREGOLI_HOST。

保存的配置放在进程工作目录下的 fregoli.json。加载和卸载都会写入它，所以运行时插件和已移除的助手都能在重启后保留：

{ "assistant": true, "plugins": [] }

fregoli/vX.Y.Z 的 GitHub Releases 附带源码 tarball，版本号已写入其中。--version 会打印 FREGOLI_VERSION（如果设置了），否则打印 git describe --tags --match 'fregoli/v'，再否则打印 dev。完整命令行与 HTTP 参考：使用指南。

架构

Fregoli 架构：浏览器通过 HTTP 与 web 插件通信；agent 插件通过 ACP 运行 Grok 命令行；Grok 启动 Fregoli MCP 服务器，后者调用 web 插件的 HTTP API。

agent 插件启动 grok agent --always-approve stdio，并在 ACP session/new 中传入 MCP 服务器规格；Grok 启动 src/mcp.ts，其中 FREGOLI_URL 指回本进程。随附插件（plugins/shipped/）在启动时挂载；运行时插件通过 fregoli.json 或 POST /load 挂载。

内核是 Cordis。各项能力都是插件（「fiber」），可在运行时挂载和销毁。

Web 在 8080 上提供 HTTP、画布、助手槽位、JSON API 和页面桥（DOM 快照、高亮、用户点击）。

Agent 启动 grok agent --always-approve stdio 并说 ACP。它交给 Grok 一个 MCP 服务器：list_plugins（已挂载的 Cordis fiber）、load_plugin（挂载插件文件）、unload_plugin（按名称销毁 fiber）、observe_page（当前标签页的序列化 DOM）、highlight（高亮 CSS 选择器）、wait_click（高亮选择器并等待用户点击或输入）、reload_page（重载浏览器标签页；助手聊天保持打开）。没有 grok 时回退到 stub。卸载会杀掉对应子进程。
Assistant 本身就是插件：右下角聊天，可替换、可移除。默认 UI 就是上文介绍的 Helferlein 头像。

Loader 从 fregoli.json 或 POST /load 挂载额外的 Cordis 插件，并在加载或卸载插件时写入 fregoli.json。apply 失败不会进入 ACTIVE 状态，也不会替换画布。

目录结构

| 路径 | 内容 |
| src/cli.ts、src/boot.ts、src/kernel.ts | 命令行入口、启动流程、Cordis 上下文 |
| src/loader.ts、src/config.ts | 插件加载器/卸载器、fregoli.json 处理 |
| src/mcp.ts | 交给 Grok 的 MCP 服务器 |
| src/plugins/{web,agent,assistant}/ | 启动插件（纳入版本跟踪） |
| plugins/shipped/ | 随仓库发布的画布插件；每个 .ts 都在启动时挂载 |
| plugins/runtime/ | 智能体在运行时写入的插件（已 gitignore） |
| .grok/skills/fregoli-app/ | Grok 技能：如何改动正在运行的应用 |
| tests/ | 通过 tsx 运行的 node:test 测试套件 |
| docs/images/ | 本 README 和网站使用的示意图 |

这个项目是怎么构建的

Fregoli 采用智能体优先的开发方式。AI 编程智能体编写全部代码、测试和文档，并互相审查改动，由人把握方向：规格、设计决策，以及基于实际行为和测试结果的验收。没有人逐行阅读代码。这是有意为之。质量靠自动化测试、CI 和独立的智能体审查来保证。

依赖之前，请按你自己的需求评估代码。发现问题？欢迎开 issue。

许可证：PolyForm Noncommercial 1.0.0。源码可见，但不是 OSI 开源。第三方软件及其许可证：THIRD_PARTY_NOTICES.md。