零JavaScript写插件：desktop-cc-gui Tier-0声明式插件实战教程-开发者社区

零JavaScript写插件：desktop-cc-gui Tier-0声明式插件实战教程

【免费下载链接】desktop-cc-guiMulti-engine AI coding desktop client (Tauri). Claude Code, Codex, Gemini, OpenCode, DeepSeek Harness and more in one GUI.项目地址: https://gitcode.com/zhukunpenglinyutong/desktop-cc-gui

desktop-cc-gui 是一款多引擎 AI 编程桌面客户端（Tauri 架构），一个界面即可驱动 Claude Code、Codex、Gemini、OpenCode 等多个引擎。它内置了一套三层信任的插件系统，其中最友好的就是Tier-0 声明式插件——只用 JSON + CSS，零 JavaScript就能换肤、加设置项、放状态栏文本。本文带你理解它的原理，并一步步写出、安装第一个声明式插件。

什么是 Tier-0 声明式插件？

desktop-cc-gui 把插件分成三个信任层级（完整定义见官方规范 docs/plugin-development-guide.zh-CN.md）：

层级	形态	能力	审核成本
Tier-0 声明式	纯 JSON + CSS，零 JS	主题换肤、状态栏文本、设置表单、命令入口	无代码可审，从简
Tier-1 JS（市场）	单文件 ESM bundle + manifest	完整 SDK 扩展点 API	人工审核，可签名获「已验证」徽章
Tier-2 JS（个人）	同 Tier-1，未签名	同 Tier-1	不上架，本地安装需确认 diff

💡选型建议：只做样式、主题、状态栏文字、简单设置项？优先做 Tier-0——审核最快、用户信任成本最低，AI 也能可靠地帮你生成。

Tier-0 的核心思想是：你只声明「贡献什么」，宿主负责「执行」。manifest 里的每一项contributes都会被宿主的一对一解释器翻译成一个上下文调用，源码见 interpreter.tsx 中的applyDeclarativePlugin：

themes→ctx.theme.setTokens()（主题 token 覆盖）
i18n→ctx.i18n.addBundle()（注册语言包）
configSchema→ 自动渲染设置页表单
statusBarItems→ 状态栏文本芯片
commands→ 命令面板条目（触发后发事件总线消息）

因为每一项注册都走统一的 Disposer 栈，卸载插件时自动逆序清理，没有任何残留——这也是它敢「零 JS」的底气。

Tier-0 能做什么、不能做什么

✅能做（扩展点见 manifest.ts 的PluginManifest类型）：

🎨 覆盖主题语义 token（light/dark双套），实现一键换肤
📊 状态栏放静态文本芯片
⚙️ 通过configSchema（JSON Schema）让宿主自动生成设置表单
🧩 命令面板注册命令，执行时向事件总线emit一个 topic
🌏 注册 i18n 语言包

🚫不能做（需要这些就升级 Tier-1）：

写交互逻辑、监听事件并做出响应
调用 SDK 的storage、events、bridge等运行时能力
发起网络请求（network:<host>授权只对 JS 插件生效）

3 分钟写出第一个插件：完整 manifest 示例

一个最小可用的 Tier-0 插件只需要一个manifest.json。下面这个「Midnight 主题 + 状态栏徽章 + 设置表单」三合一插件，展示了全部核心扩展点：

{ "id": "midnight-kit", "name": "Midnight 主题套件", "version": "1.0.0", "minAppVersion": "1.1.0", "author": "you", "description": "深蓝午夜主题 + 状态栏徽章 + 可配置设置页", "tier": "declarative", "permissions": ["theme", "i18n"], "contributes": { "themes": [ { "name": "Midnight", "tokens": { "dark": { "--background-primary-default": "#0d1117", "--text-primary": "#e6edf3" } } } ], "statusBarItems": [{ "text": "Midnight v1" }], "commands": [{ "key": "about", "title": "关于 Midnight 主题" }], "i18n": [ { "lang": "zh-CN", "ns": "midnight", "resources": { "about": "一个纯声明式主题插件" } } ] }, "configSchema": { "type": "object", "properties": { "enableGlow": { "type": "boolean", "title": "启用辉光", "default": true }, "accent": { "type": "string", "title": "强调色", "enum": ["blue", "purple"], "default": "blue" } } } }

逐行拆解几个关键字段：

字段	说明	注意事项
`id`	插件全局唯一标识	小写字母/数字/连字符，上架后永不更改
`tier`	信任层级	Tier-0 固定填`"declarative"`
`version`	语义化版本	必须与 Release tag 完全一致
`permissions`	权限声明	只声明用到的，多余声明会被审核要求删减
`configSchema`	JSON Schema 子集	宿主据此自动生成设置页表单

权限全集可以在 permissions.json 中查到——这份文件是 TS、Rust、模板三方共用的单一事实源，Tier-0 通常只需要theme和i18n（theme甚至对声明式插件是隐含的）。

逐项解析五个 contributes 扩展点

主题 tokens：只改语义变量，不碰选择器

换肤不是写一堆selector { color: xxx }，而是覆盖 BoardUI 的语义 CSS 变量。解释器会把它翻译成ctx.theme.setTokens()（见 interpreter.tsx）：

"themes": [{ "name": "Midnight", "tokens": { "dark": { "--background-primary-default": "#0d1117" }, "light": { "--background-primary-default": "#f6f8fa" } } }]

好处有两点：深浅色模式自动翻转，插件 UI 与宿主视觉永远协调；宿主可静态校验，禁止远程资源引用。

状态栏文本：一行 JSON 一个芯片

statusBarItems里每个{ "text": "..." }会变成状态栏右侧的一枚静态文本芯片。适合放版本标记、模式标识这类「只读信息」。注意它是纯文本——想要动态更新的状态栏组件，那是 JS 插件registerStatusBarItem的能力。

命令面板入口：命令即事件

"commands": [{ "key": "about", "title": "关于 Midnight 主题" }]

用户在命令面板（⌘K）执行后，解释器会在事件总线发出plugin:midnight-kit:command:about（可通过emits自定义 topic）。Tier-0 自己无法响应这个事件，但可以配合一个 JS 插件做跨插件协作——声明式出「界面」，JS 出「逻辑」，这是很实用的分工。

configSchema：设置表单零代码生成

只要声明了configSchema，宿主就会自动在设置页渲染一个表单，代码见 PluginConfigForm.tsx：

Schema 类型	自动渲染为
`boolean`	开关（Switch）
`string`+`enum`	下拉选择（Select）
`number`/`integer`	数字输入框
其他 string	文本输入框

用户每次改动会向plugin-config://changed事件广播值，同样可供其他插件响应。你一行 React 都不用写，就拥有了原生观感的设置页。

i18n：插件也要双语

contributes.i18n注册的lang+ns+resources会在卸载时自动回收。审核要求至少提供en与zh-CN两套资源——Tier-0 把文案直接写在 JSON 里，对新手非常友好。

本地安装与调试步骤

把manifest.json（及 i18n/CSS 资源）放进一个目录，例如~/plugins/midnight-kit/
打开 desktop-cc-gui →设置 → 插件 → 从本地目录安装，指向该目录
宿主加载器 loader.ts 会校验 manifest 与权限（未知权限 = 安装期直接拒绝），然后把状态机推进到active
立即生效：主题 token 覆盖、状态栏芯片、命令面板条目、设置页表单
改完 manifest 重新安装即可，Tier-0 没有构建步骤

发版上架时记得：Release tag 必须等于version字段（不带v前缀），Release 附件名固定为manifest.json、styles.css等，详见 docs/plugin-development-guide.zh-CN.md 的硬性要求。

进阶：什么时候该升级到 Tier-1 JS 插件？

出现下面任一需求，就该写 JS 插件了：

需要响应事件（如监听usage://updated更新动态 UI）
需要持久化数据（ctx.storageKV）
需要向 composer 插槽、面板 tab、Markdown 渲染管线注入组件
需要受控的network:/exec:授权调用外部能力

升级路径很平滑：Tier-0 里写好的configSchema、themes、i18n在 JS 插件的 manifest 中原样保留（静态声明 + 动态代码共存），你只是多写了一个main.js。

常见问题（FAQ）

Q：Tier-0 能访问文件或网络吗？不能。声明式插件没有运行时，权限面只覆盖theme/i18n这类 UI 声明，这也是它审核从简的前提。

Q：为什么我的插件没出现？先查三件事：tier是否为declarative、id是否符合命名规则、permissions是否都在 permissions.json 的已知列表中（未知权限会在安装期被拒绝）。

Q：状态栏文本能动态变化吗？Tier-0 不行。静态文本走statusBarItems；动态内容请注册 JS 命令 + 事件，或升级为 Tier-1 插件。

Q：卸载会留残留吗？不会。解释器对每一项贡献都记录 Disposer，卸载时逆序清理主题、语言包、表单、芯片与命令。

模块路径速查

插件开发权威规范（唯一提交标准）：docs/plugin-development-guide.zh-CN.md
Tier-0 解释器（manifest → 宿主调用的一对一翻译）：src/features/plugins/declarative/interpreter.tsx
自动设置表单渲染：src/features/plugins/declarative/PluginConfigForm.tsx
插件 SDK 契约（manifest/权限/版本/上下文）：packages/plugin-sdk/src/
权限单一事实源（TS/Rust/模板三方共用）：packages/plugin-sdk/spec/permissions.json
插件运行时加载器与状态机：src/features/plugins/runtime/loader.ts

从零代码的 JSON 出发，你现在就能为自己的 desktop-cc-gui 定制主题与设置页了。写完 Tier-0，再按需升级为 JS 插件——这就是这套三层信任模型想给你的路径。🚀

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考