中文 | English

create-bitfun-skin

create-bitfun-skin 是面向当前 BitFun Appearance 皮肤系统的 Codex Skill。它告诉模型哪些界面表面可以修改、如何编写声明式 .bitfun-appearance 包、怎样验证包与当前 BitFun 宿主，并通过风格示例指导具体的视觉实现。

这个仓库只描述当前契约，不维护其他格式或内部重构历史。

能力

• 查询当前注册的 Scenes、Components、Parts、States、Facets 和 Renderer。
• 查询 Style IR 属性、CSS Token 和 Widget Token。
• 初始化、检查、打包和分析稀疏 Appearance 覆盖包。
• 检查资源引用、完整性哈希、ZIP 安全和包体限制。
• 使用真实 BitFun checkout 的 Validator 和 Compiler 进行严格验证。
• 创建带 VP9 动态背景、静态 poster 和派生 WebP 资产的电影感皮肤。
• 记录构建输入、媒体编码选择、输出哈希和运行时检查状态。
• 从 skin-build.json 重建，并检查资源或 manifest 漂移。

设计原则

仓库按三层组织：

1. 根 Skill 是当前 BitFun Appearance 契约的入口和任务路由器。
2. scripts/ 提供与视觉风格无关的确定性工具。
3. examples/ 只描述特定风格如何使用当前契约。

Registry 决定“能不能改”，风格示例决定“这类设计怎么改”。示例中的组件覆盖、颜色、透明度、裁剪和材质不是其他皮肤的默认规则。

目录结构

create-bitfun-skin/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   ├── appearance-registry.json
│   ├── package-contract.md
│   ├── renderer-contracts.md
│   ├── authoring-workflow.md
│   ├── media-quality-policy.md
│   └── style-example-contract.md
├── scripts/
│   ├── bitfun_appearance.py
│   ├── build_support.py
│   ├── media_support.py
│   ├── sync_registry.py
│   ├── verify_host.py
│   └── test_*.py
└── examples/
    └── cinematic-animated-wallpaper/
        ├── SKILL.md
        ├── references/
        └── scripts/

环境要求

• Python 3.10+
• Git
• Pillow：python -m pip install Pillow
• FFmpeg 和 FFprobe：生成或检查动态壁纸时需要
• BitFun 源码 checkout：只在同步 Registry 或执行生产宿主验证时需要

执行宿主验证前，应确保目标 BitFun checkout 已安装其 Node/pnpm 依赖。

安装

克隆到 Codex Skills 目录：

git clone https://github.com/kev1n77/create-bitfun-skin.git `
  "$env:USERPROFILE\.codex\skills\create-bitfun-skin"

macOS 或 Linux：

git clone https://github.com/kev1n77/create-bitfun-skin.git \
  ~/.codex/skills/create-bitfun-skin

安装后可以在请求中显式使用：

使用 $create-bitfun-skin 检查这个 BitFun 皮肤包。

使用 $create-bitfun-skin 和我提供的视频创建一个电影感 BitFun 皮肤。

查询当前契约

在仓库根目录运行：

python scripts/bitfun_appearance.py contract list components
python scripts/bitfun_appearance.py contract list scenes
python scripts/bitfun_appearance.py contract list renderers
python scripts/bitfun_appearance.py contract show components <component-id>
python scripts/bitfun_appearance.py contract show scenes <scene-id>
python scripts/bitfun_appearance.py contract properties
python scripts/bitfun_appearance.py contract tokens css
python scripts/bitfun_appearance.py contract tokens widget

不要根据 DOM、另一个皮肤或示例 surface plan 推测 Part。只有当前 Registry 返回的表面、Part、状态和属性可以写入包中。

创建普通皮肤包

初始化稀疏覆盖：

python scripts/bitfun_appearance.py init <project-dir> `
  --id <skin-id> `
  --name "<Skin name>" `
  --mode dark

编辑 <project-dir>/appearance.json 后验证并打包：

python scripts/bitfun_appearance.py validate <project-dir>
python scripts/bitfun_appearance.py build <project-dir> `
  --output <skin-id>.bitfun-appearance
python scripts/bitfun_appearance.py validate <skin-id>.bitfun-appearance

分析已有项目或归档：

python scripts/bitfun_appearance.py inspect <project-or-archive>

电影感动态壁纸示例

当前内置的风格示例是 cinematic-animated-wallpaper。它适合动画角色壁纸、透明电影感材质、图片卡片和插画弹窗。

先生成时间戳接触表：

python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py contact `
  --source <wallpaper.mp4> `
  --output <skin-root>

检查 contact-sheet.png 并选择合适的时间和裁剪，再执行完整构建：

python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py build `
  --source <wallpaper.mp4> `
  --output <skin-root> `
  --id <skin-id> `
  --name "<Skin name>" `
  --frame-time <seconds> `
  --palette <palette.json> `
  --bitfun-repo <bitfun-repo>

重建或检查：

python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py rebuild `
  --output <skin-root>

python examples/cinematic-animated-wallpaper/scripts/build_cinematic_skin.py check `
  --output <skin-root>

媒体质量策略

默认视频策略为 --video-quality auto：

• 小型素材先尝试 VP9 编码级无损。
• 大型素材从 CRF 20 开始。
• 只有输出超过 64 MiB 时才逐步提高 CRF。
• 最终选择和每次尝试都会记录在 skin-build.json。

默认静态策略为 --static-quality-mode auto：先尝试无损 WebP，超限后按质量从高到低回退。

可显式指定：

--video-quality lossless
--video-quality high
--video-quality balanced
--video-crf 24
--static-quality-mode lossless
--static-quality 95

编码级无损不代表派生文件与原视频完全一致。宿主处理仍会限制时长和分辨率、转换为 30 FPS / yuv420p，并移除音频和元数据。

包限制

• 归档扩展名：.bitfun-appearance
• 归档格式：ZIP
• 根 manifest：appearance.json
• 单个背景视频：最大 64 MiB
• 压缩归档：最大 96 MiB
• 展开内容：最大 128 MiB
• 单张普通图片：最大 16 MiB
• Preview 图片：最大 4 MiB
• 背景视频：最长 60 秒，单边最大 4096 像素，总像素最大 900 万

包是声明式的，不支持 CSS 文件、选择器、HTML、脚本、字体、远程 URL、SVG 或可执行内容。视频只能通过顶层 backgroundMedia 使用，并且必须提供图片 poster。

使用真实 BitFun 宿主验证

确认 Registry 与目标 checkout 一致：

python scripts/sync_registry.py <bitfun-repo> --check

该检查比较实际导出的 Appearance 契约；如果 Registry 内容未变，BitFun 中无关提交造成的 revision 差异不会使检查失败。

使用生产 Validator 和 Compiler：

python scripts/verify_host.py <bitfun-repo> `
  <skin>.bitfun-appearance `
  --report host-verification.json `
  --strict-warnings

Validator 和 Compiler 通过只代表包可以被当前宿主接受。最终仍需导入 BitFun，检查实际界面、长内容、弹窗、独立窗口、明暗动态帧和 reduced-motion poster。

开发验证

python -B scripts/test_bitfun_appearance.py
python -B scripts/test_cinematic_tools.py

同步 Registry 时必须使用干净的 BitFun checkout。不要手工编辑 references/appearance-registry.json。

贡献

提交新风格示例前，请先阅读 references/style-example-contract.md。新示例必须只使用当前 Registry 注册的表面，并将通用构建和媒体能力留在根 scripts/ 中。