oxframe

oxframe-cli

状态： oxframe 正处于非常活跃的开发阶段。API 尚不稳定，可能随版本变化。请在 Cargo.toml 中固定确切版本，并在升级前查看更新日志。

面向 oxframe 项目的 oxframe 命令：创建、热重载预览、渲染和检查。

cargo install oxframe-cli          # or a prebuilt binary:
#   Linux, macOS:  curl -fsSL https://github.com/oxygenframe/oxframe-cli/releases/latest/download/install.sh | sh
#   Windows:       powershell -ExecutionPolicy Bypass -c "irm https://github.com/oxygenframe/oxframe-cli/releases/latest/download/install.ps1 | iex"
oxframe init hello && cd hello
oxframe dev --open                 # editor on http://127.0.0.1:3000/?token=…
oxframe render                     # out/hello.mp4
oxframe publish --title "Hello"    # upload to oxframe.dev, print a link with a player
oxframe check                      # compile, then storyboard + report.json
oxframe inspect --at 2.5           # scene tree at that time, as JSON (--graph adds passes)
oxframe snapshot --at 1.5          # one frame as PNG in out/snapshots/
oxframe agents                     # refresh AGENTS.md and the Claude Code skill
oxframe upgrade                    # move the project to this CLI's SDK version
oxframe doctor                     # Rust, a C linker, ffmpeg: what is missing and how to fix it

更新

cargo install oxframe-cli --force  # the CLI
oxframe upgrade                    # then, in each project: SDK pin, Cargo.lock, agent files

项目会固定 SDK 版本（oxframe = "=0.22.0"），因此新版本发布不会自行更改现有项目。CLI 每天会在后台检查 crates.io（cargo search），并提示有更新的版本；设置 OXFRAME_NO_UPDATE_CHECK=1 可关闭此功能（CI 中默认关闭）。

完整参考文档：https://oxframe.dev/docs/cli。

AI 编码 Agent

oxframe init 会生成 AGENTS.md、CLAUDE.md（@AGENTS.md）以及 .claude/skills/oxframe/ 中的技能文件（工作流 + API 速查表）。这些文件会告知 Agent 使用 oxframe check（故事板和 report.json）验证视觉更改，并且绝不运行 oxframe dev。 升级后，oxframe agents 会刷新这些文件；除非使用 --force，否则会保留未带有 oxframe-agents 标记（由你编辑）的文件。

oxframe mcp 是通过标准输入/输出运行的 MCP 服务，提供 check、inspect、 render_graph、render_frame、render、list_components 和 docs_search：

{ "mcpServers": { "oxframe": { "command": "oxframe", "args": ["mcp"] } } }

• MCP Registry 名称：mcp-name: io.github.oxygenframe/oxframe

oxframe dev 的工作方式

browser ──WS──▶ oxframe dev (127.0.0.1:3000) ──WS──▶ <project> preview --port 0
                 serves the embedded editor           restarted on every change
                 watches src/, assets/, Cargo.toml → cargo build

• 更改（防抖 200 ms）会触发 cargo build；编辑器会显示 Building…，之后显示 Reloaded（会重新定位到同一帧），或者显示带有文件和行号的编译器错误——与此同时，之前的构建仍会继续运行。
• 旧进程会收到 Shutdown，等待 2 s 后会被终止（Windows 上会终止整个进程树）。项目崩溃后最多会重启三次。
• 安全性：仅限环回地址、检查 Origin、URL 中使用一次性令牌；CLI 只运行 cargo 和你的项目，不会发起网络请求。

退出代码：0 正常，1 构建错误，2 环境问题（ffmpeg、端口），3 版本不匹配。

内嵌编辑器

ui/dist 是由 ui.lock 固定版本的 editor-ui 发布版，通过 rust-embed 打包进二进制（build.rs 或 cargo install 不会访问网络）。

./scripts/fetch-ui.sh             # download the pinned release
just build-ui ../oxframe-web       # or build it from a sibling checkout
oxframe dev --ui-dir ../oxframe-web/packages/editor-ui/dist   # develop the editor

ui/debug-client/ 是一个精简的单文件协议客户端，供调试使用。

开发

cargo test                                          # unit tests, ui.lock check
cargo test --test e2e -- --ignored --nocapture      # init → dev → reload → render (needs ../oxframe-sdk)

采用 MIT 或 Apache-2.0 许可证授权。

许可证

你可以选择采用 Apache License, Version 2.0 或 MIT license 许可证。