> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qomicex.top/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 辅助开发

## AI 辅助开发

Qomicex 为 AI agent（Claude / opencode / Cursor 等）提供**插件开发技能包**，把生成合规插件所需的全部事实（manifest 校验、权限目录、桥 API、主题 token、签名、调试）收敛到一个目录，避免 AI 臆造字段。配合 CLI 的 `create` / `dev` / `verify` / `pack` / `publish` 全流程，AI 可以端到端产出可发布的插件。

## 技能包仓库

技能包独立维护在 **[qomicex-plugin-skills](https://github.com/Qomicex-Public/qomicex-plugin-skills)** 仓库（`skills/qomicex-plugin-dev/`）：

```text theme={null}
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 theme={null}
请帮我安装 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 theme={null}
请帮我安装 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 theme={null}
# 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 theme={null}
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 theme={null}
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 工具参考](https://docs.qomicex.top/plugins/cli.md)。

## 硬性规则摘要（技能包 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 theme={null}
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 工具参考](https://docs.qomicex.top/plugins/cli.md) 与 [发布规范](https://docs.qomicex.top/plugins/publishing.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.