fx-proto

把官方 Vercel Labs fx 收成专用原型生成运行时：外部规划 agent 出计划，这个包在指定目录里写出高保真、可交互的多界面 HTML 原型。

不改 fx 内核，不自己编译 Zig。skills、DESIGN.md、屏幕合同和预览都在包外。生成时调用官方 fx 二进制。

模式借鉴 Open Design：先锁定设计系统，再按 skill 写出 HTML，多界面时一屏一个文件。本仓库是原作 skills / 设计系统的再实现，不是 fork，也不搬运他们的品牌包。

为什么可行

| 你的设想 | 本包怎么落地 | | --- | --- | | 外部 agent 负责规划 | apply-plan 吃 plan.json，generate 只负责写原型 | | 在指定目录生成 | 所有输出都在传入的 dir 里 | | 独立第三方模型 | 自己的配置文件（和 fx 一样读 settings.json），隔离 HOME，不碰调用方的 ~/.fx | | 官方包，不编译 | 使用 PATH 上的 fx，或下载 官方 release | | DESIGN.md → HTML | skills/design-system + skills/html-prototype | | 多界面有结构 | screens/01-*.html + prototype.json + gallery index.html |

不要用官方 libfx 做生成。 createFxAgent() 目前不向模型暴露读文件 / 跑命令等工具，写不出原型。本包调用的是官方 CLI：fx ask。

fx 的原生通道是 Vercel AI Gateway（provider/model，例如 anthropic/claude-sonnet-4.6、openai/gpt-5.4）。独立模型 = 本包自己的 Gateway key + 模型 ID，不是规划 agent 的模型。直连任意 OpenAI 兼容网关需要额外的 language-model 协议桥，这一刀还没做。

安装到本地（不要 npx）

先把包装进当前仓库或本机，再直接跑 fx-proto。教程 skill 也按这个写，调用方禁止 npx / npm exec。

npm install --save-dev @qinshm1128/fx-proto   # 装进当前仓库
# 或，从本仓库源码链到用户目录（不要 sudo，不要裸 npm link）
./scripts/link.sh

这台环境里直接 npm link 会写 /usr/lib/node_modules，没有权限。./scripts/link.sh 把 prefix 设到 ~/.npm-global。新开的 shell 若找不到命令：

export PATH="$HOME/.npm-global/bin:$PATH"
fx-proto --help

装完之后：

| 安装方式 | 怎么调用 | | --- | --- | | 仓库本地 | ./node_modules/.bin/fx-proto，或在 npm script 里写 fx-proto | | 本机全局 | fx-proto |

postinstall 会把教程 skill 写到 .agents/skills/。没有的话再跑 fx-proto skills-install。

规划 agent 怎么调用

import { scaffoldWorkspace, generatePrototype, startPreview } from "@qinshm1128/fx-proto";

const dir = "/tmp/north-desk";
const plan = {
  product: "North Desk",
  brief: "A quiet desk for magazine editors reviewing page proofs.",
  screens: [
    { id: "home", name: "Home", goal: "See assigned proofs." },
    { id: "composer", name: "Composer", goal: "Leave a margin note." },
    { id: "settings", name: "Settings", goal: "Change density and night desk." },
  ],
  flows: [{ from: "home", to: "composer", via: "Open proof" }],
};

await scaffoldWorkspace(dir, plan);
await generatePrototype({ dir, plan }); // 模型从 ~/.fx-proto/settings.json 读取

CLI 等价：

npm install --save-dev @qinshm1128/fx-proto
fx-proto setup --global --model anthropic/claude-sonnet-4.6 --api-key "$KEY"   # 只做一次
fx-proto apply-plan ./out --plan plan.json
fx-proto generate ./out
fx-proto preview ./out

plan.json 形状见 templates/plan.example.json。

生成物合同

DESIGN.md              设计系统（9 段）
PLAN.md                规划 agent 留下的 brief / 屏幕 / 流向
prototype.json         机器可读清单
PROTOTYPE.md           给实现同学的对照表
index.html             画廊 / 启动器，不是产品本体
styles/tokens.css
screens/01-home.html   一屏一个可交互 HTML
screens/02-composer.html
skills/                给 fx 读的外部 skill
.fx-proto/settings.json  本工作区模型（fx 同款格式，可省略，会回退到仓库/用户文件）

命令

fx-proto init ./out --name "App" --brief "..." --screens home,search
fx-proto generate ./out --dry-run
fx-proto iterate ./out --note "Make the primary action larger"
fx-proto preview examples/harbor-notes --port 43173
fx-proto doctor --install-fx
fx-proto setup --global --model moonshotai/kimi-k3 --api-key "$KEY"
fx-proto config
fx-proto update
fx-proto skills-install

外部 agent 怎么用（教程 skill）

npm install @qinshm1128/fx-proto 会把教程 skill 写到调用方项目的 .agents/skills/，以及 ~/.agents/skills/。这是给 规划 / 调用方 agent 看的，不是给 fx 写 HTML 用的那套。

| Skill | 作用 | | --- | --- | | fx-proto | 如何 apply-plan / generate / iterate / preview（本地 CLI，不用 npx） | | fx-proto-install | npm install --save-dev 或 -g，然后跑 fx-proto | | fx-proto-setup | 只在配置文件缺失时写一次 settings.json / key；已有文件就复用 | | fx-proto-update | 看到新版本提示后必须执行 fx-proto update | | fx-proto-designs | 多项目隔离；先找已有 DESIGN.md 再决定是否新建 |

fx 自己用的生成 skill（design-system、html-prototype、multi-screen、iterate-prototype）仍在包内 skills/，生成时复制进目标工作区。

手动补装：

fx-proto skills-install

多项目与设计复用

每个产品一个目录，互不改对方的 DESIGN.md / 屏幕 / .fx-proto/：

prototypes/harbor-notes/
prototypes/north-desk/

同一项目再做一版原型时，先找旧设计，默认复用，不要问用户“要不要新建一套”。

fx-proto projects find . --name "Harbor Notes"
fx-proto designs list .
fx-proto generate ./prototypes/harbor-notes          # 目录里已有 DESIGN.md 就沿用
fx-proto designs save ./prototypes/harbor-notes --id harbor-notes
fx-proto designs apply ./prototypes/harbor-v2 --id harbor-notes

apply-plan 会更新 PLAN，但不会覆盖已经写好的 DESIGN.md。只有用户明确要新视觉时才加 --new-design。复用是拷贝进目标目录，之后两边可以各自改，不会串台。

自动更新

每个命令的 JSON 都带 update 字段。有新版本时文本里会出现：

[fx-proto] 有新版本 0.2.0（当前 0.1.0）。调用方请立即执行: fx-proto update

fx-proto-update skill 要求调用方 agent 立刻跑 fx-proto update，再重试原来的命令。不要只口头提醒。

模型与凭证

和官方 fx 一样：写进文件，以后直接读。不要每次 generate 再传 --model，调用方也不要每次再问用户。

配置文件（fx 同款 settings.json，隔离在 ~/.fx-proto，不是 ~/.fx）：

{
  "provider": "gateway",
  "model": "anthropic/claude-sonnet-4.6",
  "models": { "gateway": "anthropic/claude-sonnet-4.6" },
  "permission_mode": "yolo",
  "max_agent_steps": 80
}

| 优先级（高 → 低） | 文件 | | --- | --- | | 环境变量 | FX_PROTO_MODEL、FX_PROTO_API_KEY / AI_GATEWAY_API_KEY | | 本原型覆盖 | <dir>/.fx-proto/settings.json | | 仓库默认 | <repo>/.fx-proto/settings.json | | 用户默认（写一次即可） | ~/.fx-proto/settings.json | | API key | ~/.fx-proto/credentials.json（或工作区同名文件，不进 git） |

也可以交给 CLI 写这些文件：

fx-proto setup --global --model anthropic/claude-sonnet-4.6 --api-key "$KEY"
fx-proto config          # 看当前读的是哪一个文件
fx-proto generate ./out  # 不再传模型

第一次在某个原型目录里 setup ./out 时，如果用户级文件还是空的，会把模型和 key 一并写到 ~/.fx-proto/，后面别的项目直接复用。

生成时 HOME 指到 <dir>/.fx-proto/home，并把上面的 settings.json 同步进去给 fx 读。不复用本机交互式 ~/.fx 登录。

自定义网关

把你自己的 OpenAI 兼容网关填进 upstream 即可，不用管端点后缀：

fx-proto setup --global --upstream https://your-gateway --api-key "$KEY"

裸域名、/v1、完整端点都能识别 —— fx-proto 会先读服务器根路径自报的端点列表，读不到就依次探测 /v1/chat/completions、/chat/completions、/v1/responses、/responses。Chat Completions 和 Responses 两种协议都支持。

为什么需要本地网关

fx 只接受字面意义上的 loopback http 作为聊天端点：scheme 必须是 http、必须带端口、host 必须是 127.0.0.1 / localhost / [::1]（见 fx 源码 src/gateway/client.zig 的 isLoopbackHttpUrl）。任何其他地址——包括 https 公网域名——会被直接丢弃并回落到官方 AI Gateway，表现为 401。

而且 fx 说的不是 OpenAI 协议，是 Vercel AI Gateway 的 language-model 协议（{prompt, tools, toolChoice} 加 ai-language-model-id 头）。

所以 fx-proto 自带一个本地网关做双向协议翻译。你不需要手动启动它：

fx-proto gateway         # 查看状态
fx-proto gateway start   # 手动预热（可选）
fx-proto gateway stop

generate 时若发现 upstream 不是 loopback，会自动确保网关在 127.0.0.1:43450 运行。全机器单例：已在跑就复用，并发调用只会起一个进程。想换端口用 --port。

配置字段旧名 baseUrl（以及 --base-url、FX_PROTO_BASE_URL）仍然可读，写入时会自动迁移成 upstream。

fx-proto doctor --install-fx   # 下载官方 Linux / macOS 二进制到 ~/.fx-proto/bin/fx

Windows 没有官方 fx 构建。

本地预览示例

仓库里的 examples/harbor-notes 是合同的完整样品：四个可点击界面、共享 token、工作中的筛选 / 保存 / 开关。

npm test
npm run preview

许可

Apache-2.0。fx 仍是 Vercel Labs 的官方项目；本包只包装它的发布二进制和我们自己的 skills。