主题开发指南

面向主题作者：如何在 Host 契约下做官方或第三方主题。边界总览见主题与 Host；契约细节见主题契约。

你在做什么

主题提供站点「形状」：信息架构（pages）、Chrome（Header/Footer）、tokens、可选 section。 Host 提供内容实体、权限、发布、媒体、SEO、Public/Admin API、可复用渲染原语。

禁止：主题包内定稿营销长文当唯一数据源；深依赖 host @/…；自带 React 副本；调用带密钥的 admin API。

快速联调

# Host 仓库
git clone https://github.com/yixian-huang/inkless.git
cd inkless && pnpm install

# 本地主题旁路（示例 product-first）
THEME_PRODUCT_FIRST_PATH=../inkless-theme-product-first pnpm -C frontend dev
# 前端 :3000 · API :8088

其他主题类似：用对应 env / package pin。生产 pin 主题 git sha 于 frontend/package.json。

包结构

inkless-theme-<name>/
  inkless.theme.json   # id, version, contractVersion, umd, esm
  dist/theme.umd.js    # 远程安装 / 外链加载
  dist/theme.es.js
  src/                 # ThemePlugin 实现
  types/theme-host-shim.d.ts  # 独立仓库类型垫片（可选）

安装路径：

内置 pin — host 依赖官方主题包并 registerBuiltIn
远程 UMD — 管理端 externalUrl → host loadExternal → 主题调用 window.__INKLESS_THEME_REGISTER__(plugin)

ThemePlugin 最小面

字段	必填	说明
manifest	是	id、名称、version、type: theme
contractVersion	是（外置）	当前 Host 主版本 `"1"`
defaultTokens	是	colors / fonts / layout
pages	是	至少 home 若接管 `/`
layoutChrome	推荐	Header / Footer 组件
settingSchema	可选	管理端可改 options（docsUrl、CTA…）
tokenPresets	可选	命名色板
sections / sectionMetas	可选	构建器积木

一级页面（class C）

与首页同级、换主题必须跟着变的叙事页 → 主题 pages[]（如 product-first 的 /features、/get-started）。

用户扩展常青页 → Host /p/*（class D）。时间流 → /blog（Host）。完整选型：内容类型。

主题 section

规则	说明
命名空间	`type` 前缀：`pf-` / `ef-` / `bf-*`；勿覆盖 Host 内置 `hero`/`rich-text`…
生命周期	draft/publish/权限在 Host
切换主题	未知 type → Host fallback，不删页面配置
数据	props 存 unified_pages，无主题私有写 API

共享运行时（勿打进主题包）

window.__INKLESS_SHARED__ = { React, ReactDOM, ReactRouterDOM, ReactI18next, host }
window.InklessThemeHost = host
window.__INKLESS_THEME_REGISTER__(themePlugin)

构建与验收

pnpm build                 # 主题仓
pnpm theme:umd:smoke       # Host 仓：UMD 烟测

CI Quality Gate 含 UMD smoke。成功标准：可 URL 安装、无 core PR；样式 PR 主要落在主题仓；Host facade 变更有 inventory + 版本锁。

官方主题参考

主题	仓库（示例）
blog-first	https://github.com/yixian-huang/inkless-theme-blog-first
product-first	https://github.com/yixian-huang/inkless-theme-product-first
editorial-firm	https://github.com/yixian-huang/inkless-theme-editorial-firm

演示：https://themes.inkless.run

下一步：主题契约 · 系统架构