Appearance
AI 辅助开发
Qomicex 为 AI agent（Claude / opencode / Cursor 等）提供插件开发技能包，把生成合规插件所需的全部事实（manifest 校验、权限目录、桥 API、主题 token、签名、调试）收敛到一个目录，避免 AI 臆造字段。配合 CLI 的 create / dev / verify / pack / publish 全流程，AI 可以端到端产出可发布的插件。
技能包仓库
技能包独立维护在 qomicex-plugin-skills 仓库（skills/qomicex-plugin-dev/）：
skills/qomicex-plugin-dev/
├── SKILL.md # 主入口：何时使用、文件导航、完整流程、起步提示词
├── refs/ # 12 个专题参考（按需加载）
│ ├── cli.md # CLI 命令速查（create/dev/verify/pack/publish）
│ ├── manifest.md # manifest.json 全字段 + layers + dependencies + contributes
│ ├── plugin-api.md # 桥 API（__PLUGIN_API__）签名速查
│ ├── theme.md # 主题语义 token 三级体系 + var() 消费约定
│ ├── publishing.md # Ed25519 签名流程（生成密钥 → pack --key → publish）
│ ├── debugging.md # harness 热重载调试
│ └── ... # 其余专题
└── templates/ # 13 个可复用模板（React/manifest/overlay 等）这些文件与代码事实对齐（src/plugins/types.ts、CLI src/lib/*、公开文档）。字段含义有疑问时以代码为准，不确定就标注，不要虚构 API。
安装技能包
方式一：复制安装 prompt 给 AI（推荐）
把下面内容复制给任意 AI 助手，AI 会自动完成安装：
text
请帮我安装 Qomicex 插件开发 skill。步骤：
1. 执行 `git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git /tmp/qomicex-plugin-skills`（或任意临时目录）
2. 创建目录 `~/.agents/skills/`（如不存在）
3. 把仓库里的 `skills/qomicex-plugin-dev/` 整个目录复制到 `~/.agents/skills/`
4. 确认 `~/.agents/skills/qomicex-plugin-dev/SKILL.md` 存在，并删除临时 clone 目录
5. 告诉我已安装完成，重启 AI 工具（opencode / Claude Code）后生效Windows 用户（PowerShell）：
text
请帮我安装 Qomicex 插件开发 skill。步骤：
1. 执行 `git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git $env:TEMP\qomicex-plugin-skills`
2. 创建目录 `$HOME\.agents\skills\`（如不存在）
3. 把 `skills\qomicex-plugin-dev\` 整个目录复制到 `$HOME\.agents\skills\`
4. 确认 `$HOME\.agents\skills\qomicex-plugin-dev\SKILL.md` 存在，删除临时 clone 目录
5. 告诉我已安装完成，重启 AI 工具后生效方式二：手动运行安装脚本
bash
# macOS / Linux
git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git /tmp/qomicex-plugin-skills
bash /tmp/qomicex-plugin-skills/install.sh
# Windows (PowerShell)
git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git $env:TEMP\qomicex-plugin-skills
& "$env:TEMP\qomicex-plugin-skills\install.ps1"安装脚本默认复制到 ~/.agents/skills/（Agent Skills 开放标准的用户级目录，opencode 和 Claude Code 都能识别）。可用环境变量 QOMICEX_SKILLS_DIR 覆盖目标目录（如 ~/.config/opencode/skills/ 或 ~/.claude/skills/）。
手动放置
| 平台 | 放置位置 |
|---|---|
| Claude Code | 把 skills/qomicex-plugin-dev/ 复制到项目 .claude/skills/ |
| Cursor | 把 skill 文件放到 .cursor/rules/ |
| opencode | 把 skill 目录登记到 skills 配置，或直接粘贴 SKILL.md |
| 通用（最简） | 把 SKILL.md 与相关分册内容直接粘进对话 |
安装完成后重启 AI 工具生效。遇到"开发 Qomicex 插件"相关任务时 AI 会自动加载该 skill。
卸载
bash
rm -rf ~/.agents/skills/qomicex-plugin-dev起步提示词
你是 Qomicex 插件开发工程师。先读
~/.agents/skills/qomicex-plugin-dev/下的 SKILL.md 与各分册（尤其 refs 里的 cli.md、manifest.md、plugin-api.md），再按流程工作：qomicex create <id>生成项目 → 实现功能 →qomicex verify过 0 error →qomicex pack出包。manifest 字段、权限、API 签名一律以技能包内文档为准，不臆造。
CLI 全流程（AI 端到端开发）
技能包配合 CLI 使用，AI 可端到端产出可发布插件：
bash
qomicex create com.example.myplugin # 1. 脚手架生成项目
cd com.example.myplugin
pnpm install # 2. 装依赖
qomicex dev # 3. 热重载调试（仓库内走 harness）
# ... AI 实现功能 ...
qomicex verify # 4. 静态校验（manifest/权限/长循环），0 error
qomicex pack --key ./dev-key.pem # 5. 构建 + 打包（可签名）
qomicex publish --changelog "..." # 6. 发布商店（设备流登录 → 签名 → 上传）完整命令参考见 CLI 工具参考。
硬性规则摘要（技能包 refs/pitfalls）
AI 生成/修改插件时必须逐条遵守，违反任何一条都可能导致 qomicex verify 不通过或运行时错误。核心摘录：
| 类别 | 硬性规则 |
|---|---|
| manifest | id 反向域名格式（^[a-z0-9]+([.-][a-z0-9]+)*$，3-128 字符，必须含点）；version 严格 semver；minLauncherVersion 必填；声明 entry.frontend 则 layers 需含 l2/l3（否则 UI 无法渲染） |
| 权限 | 最小权限原则：verify 会扫描源码，声明未用 / 用了未声明都会报错；shell:execute、filesystem:write、plugin:install 为 danger 权限非必要不声明 |
| 代码 | TS import 必须带扩展名（./api.ts）；vite.config.ts 必须设 base: './'；内部导航用 <Link> 不用 <a>；沙箱内不用 window.open；外部网络用 proxyFetch / proxyFetchStream（自带 SSRF 防护） |
| 主题 | CSS 全用 var(--*)，禁止 #hex / rgb() / hsl() 字面量；Tailwind 用语义类名（bg-primary 等） |
| 安全 | 禁止硬编码密钥（用户配置经 setSettings/getSettings）；不滥用 shell:execute；文件读写走授权制 |
| 流程 | 项目从 qomicex create 生成，不手写骨架；打包前必须 qomicex verify（0 error）；不触碰启动器核心代码；插件开发阶段不 commit |
完整规则见技能包 refs/pitfalls.md，以上仅为摘要。
AI 生成后的校验
AI 生成的插件必须过 qomicex verify（0 error 才算通过）：
bash
qomicex verify # 目录模式：manifest + 权限最小化 + 长循环
qomicex verify --package ./release/xxx.qplugin # 包模式：manifest + 签名验签校验覆盖：manifest 合法性、权限最小化（对比源码实际调用的桥方法）、长循环告警（while(true) / 无界 setInterval）。warning 可接受但建议消除。
通过后再 qomicex pack --version x.y.z 出包，qomicex pack --key 签名，qomicex publish 发布。完整流程见 CLI 工具参考 与 发布规范。