启航插件标准 v1（QPS v1）

1文档定位

这份文档定义开发者面向启航 Code 写插件时唯一需要遵守的接口，不描述 DSH 内部机制。

插件不得直接 import @deepseek-ai/*，不得访问 DSH Cordis 内部对象，不得依赖 DSH 的 React slot 或内部类名。所有能力通过启航 SDK 的稳定契约提供。

2与旧标准的区别

3架构：构建期适配 + 薄 Shim

开发者代码
  │  @qihang/plugin-sdk
  ▼
启航标准包 (.qhp)
  │  manifest + dist + assets
  ▼
平台构建服务
  │  按 DSH 版本编译
  ├─ DSH 0.2.x 产物
  ├─ DSH 0.3.x 产物
  └─ 兼容性 / 权限 / 签名
  ▼
启航Code 客户端
  │  下载匹配当前内核的产物
  ▼
Qihang Runtime Shim
  │  auth / license / config / panel / log
  ▼
DSH 内核（Cordis / bundle / patch）

• 不是在运行时把启航 API 逐条翻译成 Cordis；
• 而是在构建期生成目标内核的产物，运行时只保留薄桥接；
• DSH 升级时，平台更新编译器/Shim，并批量重建已上架插件；
• 开发者只在 QPS 大版本升级时评估迁移。

4插件类型

v1 开放 tool、command、panel、server。service 和 bundle 先内部使用，稳定后再开放。

5包结构与 Manifest

my-plugin/
├─ qihang.plugin.json      # 启航清单（唯一入口）
├─ package.json            # npm 构建信息
├─ src/
│  ├─ host.ts
│  └─ client.ts            # 可选
├─ assets/icon.png
├─ README.md
└─ dist/
   ├─ host.js
   └─ client.js

发布包扩展名 .qhp（本质是 zip）。包内必须有 qihang.plugin.json，平台只认这个清单。

{
  "schemaVersion": 1,
  "id": "com.blokeai.douyin-order",
  "name": "抖音订单同步",
  "version": "1.0.0",
  "description": "同步抖音订单、对账、异常订单提醒。",
  "author": { "name": "齐合智汇", "uid": 1, "url": "https://blokeai.com" },
  "license": "MIT",
  "icon": "assets/icon.png",
  "type": ["tool", "panel"],
  "entry": { "host": "dist/host.js", "client": "dist/client.js" },
  "qihang": { "apiVersion": "1", "minAppVersion": "1.2.0" },
  "permissions": ["network:https://api.blokeai.com", "fs:workspace:read"],
  "config": { "schema": { "type": "object", "properties": {} } },
  "pricing": { "type": "monthly", "price": 9, "trialCalls": 20, "licenseRequired": true }
}

6SDK API

import { definePlugin } from '@qihang/plugin-sdk'

export default definePlugin({
  manifest: './qihang.plugin.json',
  async setup(ctx) {
    ctx.tools.register({
      name: 'douyin_order_sync',
      description: '同步抖音订单',
      input: {
        type: 'object',
        properties: { shopId: { type: 'string' } },
        required: ['shopId']
      },
      async run(input) {
        const res = await ctx.http.post('https://api.blokeai.com/plugin/douyin/orders', {
          shopId: input.shopId
        })
        return { content: [{ type: 'text', text: `同步 ${res.count} 条订单` }] }
      }
    })
  }
})

7Panel 契约

UI 插件不直接依赖 DSH React slot，使用稳定 Panel 契约：

ctx.panels.register({
  id: 'order-dashboard',
  title: '订单看板',
  mount(element, api) {
    element.innerHTML = '<div id="app"></div>'
    api.callHost('sync', { shopId: '123' })
  }
})

Host 与 Panel 通过结构化 postMessage 通信；平台负责 iframe 沙箱、CSP、主题变量、生命周期和 DSH slot 桥接。

8构建与分发

npm create qihang-plugin@latest
cd my-plugin
npm run dev        # 本地加载到启航Code
npm run build      # 生成 .qhp
npm run validate   # 校验 manifest/权限/兼容

开发者上传 .qhp
  → 平台校验 manifest/权限/签名
  → 平台按 DSH 版本生成产物
  → 写入兼容矩阵
  → 上架/审核
  → 客户端下载匹配产物 → 安装 → 重载 Host

9兼容策略

10权限与安全

"permissions": [
  "network:https://api.blokeai.com",
  "fs:workspace:read",
  "fs:workspace:write",
  "clipboard:write",
  "shell:openExternal"
]

• 安装前展示权限，未声明直接拒绝；
• 高风险权限（文件写入 / shell / child_process）需二次确认；
• .qhp 包签名 + 平台审核 + 静态扫描；
• 插件只能拿 license token，不拿用户密码/上游主 Key；
• 网络域名白名单，日志脱敏。

11License 与付费

身份使用 Bearer，不再使用隐藏 Cookie：

POST /api/plugin-license.php
Authorization: Bearer <forum_token>
Content-Type: application/json

{ "action": "issue", "agent_id": 305, "device_id": "..." }

{
  "ok": true,
  "license": "lic_...",
  "type": "trial",
  "trial_remaining": 12,
  "expires_at": "2026-11-30T00:00:00+08:00",
  "signature": "..."
}

• 免费插件跳过 license；
• 试用原子扣减；订阅校验有效期；
• 客户端缓存 24h，过期必须联网；
• 插件调用服务端 API 时带 license；
• 服务端校验签名/用户/设备/到期/次数。

12旧版插件说明

旧版 tgz + npm_name 只作为测试数据，不进入 QPS v1 兼容范围。旧包不迁移，新插件按 QPS v1 重写/重新构建。

如果你有旧插件，迁移步骤：

1. 新建 qihang.plugin.json；
2. 把工具逻辑改为 definePlugin + ctx.tools.register；
3. 把 UI 改为 Panel 契约；
4. 声明权限与 pricing；
5. 用 npm run validate / npm run build 生成 .qhp。

13里程碑

14变更记录