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 会自动完成安装：

请帮我安装 Qomicex 插件开发 skill。步骤：
执行 `git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git /tmp/qomicex-plugin-skills`（或任意临时目录）
创建目录 `~/.agents/skills/`（如不存在）
把仓库里的 `skills/qomicex-plugin-dev/` 整个目录复制到 `~/.agents/skills/`
确认 `~/.agents/skills/qomicex-plugin-dev/SKILL.md` 存在，并删除临时 clone 目录
告诉我已安装完成，重启 AI 工具（opencode / Claude Code）后生效

Windows 用户（PowerShell）：

请帮我安装 Qomicex 插件开发 skill。步骤：
执行 `git clone https://github.com/Qomicex-Public/qomicex-plugin-skills.git $env:TEMP\qomicex-plugin-skills`
创建目录 `$HOME\.agents\skills\`（如不存在）
把 `skills\qomicex-plugin-dev\` 整个目录复制到 `$HOME\.agents\skills\`
确认 `$HOME\.agents\skills\qomicex-plugin-dev\SKILL.md` 存在，删除临时 clone 目录
告诉我已安装完成，重启 AI 工具后生效

方式二：手动运行安装脚本

# 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。

卸载

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 可端到端产出可发布插件：

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 才算通过）：

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 工具参考与发布规范。

启动器使用指引

插件开发

前置插件文档

插件商店使用

AI 辅助开发

AI 辅助开发

技能包仓库

安装技能包

方式一：复制安装 prompt 给 AI（推荐）

方式二：手动运行安装脚本

手动放置

卸载

起步提示词

CLI 全流程（AI 端到端开发）

硬性规则摘要（技能包 refs/pitfalls）

AI 生成后的校验