制作插件：先做一个主题，再扩展到其他类型

在卖家站新建插件

“我的插件”→“新建插件”，类型选 theme，插件 ID 用已认领命名空间下的名字，例如 com.example.ocean，填写中文名称和简介。插件 ID 与类型创建后不能修改；ID 标识产品，不要把版本号写进 ID，后续 1.0.0、1.0.1 都用同一个 ID。此时先不加价格、不公开。

取得主题工具

主题工具 cdnca-site-theme 需要 Node.js 22 或更高的 LTS，零依赖。目前它随开发源码提供，还没有公开下载包或 npm 包：请通过官网页脚“联系我们”申请与你的主控版本匹配的主题工具包（含 bin/、lib/、package.json 和说明），说明你的主控版本和系统。拿到工具前可以先完成公钥登记和新建插件。

CDNCA_THEME_TOOL="$(pwd -P)/bin/cdnca-site-theme.mjs"
test -f "$CDNCA_THEME_TOOL"

生成工程

node "$CDNCA_THEME_TOOL" init "$PWD/ocean" \
  --template user+site \
  --plugin-id com.example.ocean \
  --name Ocean

cd ocean

把示例 ID 换成你新建的插件 ID，--name 可以直接写中文名称。user+site 同时生成用户控制台与公开网站主题，只要其一时用 user 或 site。目标目录必须为空。

文件	用途
theme.config.json	主题基本设置与打包配置
console-theme.json	用户控制台主题（user 模板）
site/index.html, site/assets/	公开网站模板与资源（site 模板）
auth/auth.css	登录等认证页样式
content-schema.json, preview/content.json	网站内容字段约束与本地预览内容（site 模板）
plugin.manifest.json	插件声明与发布者资料
schemas/config.schema.json	客户可填写的配置字段
supply-chain/	SBOM 与构建来源材料

修改 plugin.manifest.json 里的发布者名称、支持地址和中文说明。supply-chain/ 应反映真实依赖和构建来源，模板里的示例值不能代替真实声明。

预检与本地预览

node "$CDNCA_THEME_TOOL" check
node "$CDNCA_THEME_TOOL" preview

check 通过时打印“预检通过（N 字节）”，有问题逐条列出代码与字段并退出 1。preview 默认监听 127.0.0.1:4173（--port 可改），终端会打印访问地址并一直运行，按 Ctrl+C 退出。加 --screenshot 会截首屏生成预览图后退出。本地预览只看内容与样式；登录、安装授权、真实数据和客户权限要在主控里另行验证。

打包并签名

node "$CDNCA_THEME_TOOL" pack \
  --version 1.0.0 \
  --sign \
  --key "$CDNCA_PUBLISHER_KEY" \
  --cdnca-plugin "$CDNCA_PLUGIN_CLI"

pack 计算内容、配置模型和供应链材料的摘要写进清单，再调用 cdnca-plugin sign-manifest。上传时用 dist/ 下这三个文件：

dist/manifest.signed.json：已签名清单
dist/schemas/config.schema.json：客户配置模型
dist/theme.json：主题内容

怎样确认：终端依次打印 content、schema、manifest 和 signed 四行，三个文件都在，签名清单里的插件 ID、版本、发布者和兼容范围（模板默认 >=1.0.35 <2.0.0）符合预期。只看退出码不够，一定要核对这几行和文件。缺预览图只提示不报错，但仍建议在工程根目录放 preview.webp（1200×750，不超过 512 KiB）。

不要把整个工程目录压缩上传，也不要只改 dist/ 里的文件；改源文件后重新 check 和 pack，否则摘要与签名会对不上。

其他类型：清单与上传文件

不用主题工具的类型按插件清单 schema 手写清单，再用 sign-manifest 签名。清单至少包含：

部分	要确认的内容
api_version, kind	marketplace.cdnca.io/v1 与 Plugin
metadata	插件 ID、不带 v 的规范 SemVer、中文名称与简介、发布者 ID/名称/支持地址
spec.compatibility.control_api	兼容的主控版本范围
spec.entrypoint	与插件类型相符的唯一入口
spec.permissions	实际需要的最小权限
spec.configuration_schema	配置模型的相对路径与 SHA-256
spec.supply_chain	真实 SBOM 与构建来源材料的 SHA-256
integrity	由 sign-manifest 写入，不要手写

入口类型	上传的文件
theme, rule_pack	已签名清单、配置模型、内容文件（content）
ui_page	只有已签名清单和配置模型；页面放在你已验证的 HTTPS 来源上
external_https	已签名清单、配置模型、1–16 个平台包（字段 package:<平台>，如 package:linux-amd64）

上限：清单 256 KiB，配置模型 64 KiB，主题与规则内容 8 MiB，单个平台包默认 64 MiB，整个上传请求默认 200 MiB。平台包是 zip、tar.gz 或 tar，不能含越界路径、符号链接等不安全条目。每类插件的完整字段、协议与审核规则见对应的按类型开发指南。