这套东西是什么

要准备什么

1. 一台 Windows 电脑（Windows 10 / 11 64 位）。插件开发不挑机器，办公本就行。
2. 云捷电商工具箱客户端 + 一个开发者账号：客户端用来「本地调试」和「打包提交审核」； 开发者账号用来登录客户端的开发者中心。
3. 代码编辑器/开发工具：YunJev（云捷科技自己做的 AI 开发工具）。 为什么用它：打开一个目录后，AI 会自动按云捷的规范帮你写插件、查接口、避坑； 顶栏还带「更新 SDK」—— 点一下就把它自己的 SDK 版本提到最新（不用再单独下载开发包）。 用 VS Code / Cursor 也能开发（只是没有这套 skill 加持）。

下载并安装YunJev

1. 下载

1. 直接点这里下载安装包：下载YunJev （等价于右上角那个蓝色按钮）。
2. 也可以到官网首页（服务端根地址）→ 点「下载」→ 选右侧「YunJev」→「下载安装包」， 得到 YunJev_x.x.x_x64.exe（版本号以页面显示的为准）。

2. 安装

1. 右键安装包 →「以管理员身份运行」
2. 同意协议 → 选安装路径：装到非系统盘、纯英文路径（如 D:\YunJieIDE），不要中文/空格
3. 勾「创建桌面快捷方式」→ 安装 → 完成后启动

3. 首次启动配置

1. 用云捷账号登录（账号密码，或手机验证码）—— 只给开发者开放，普通用户账号登不进去
2. 登录后到「设置 → 模型」里配好要用的 AI 模型（能直接管模型：新增 / 编辑 / 选默认）
3. 其它设置（技能目录、终端、调试、更新）都在「设置」面板里，默认值就能用

第 1 步：打开目录 + 更新 SDK

1. 开发软件里「文件 → 打开文件夹」，选一个好找、路径纯英文的目录，例如 D:\我的插件 （还没有就新建一个空目录打开，或者用「新建项目」）。
2. 点顶栏右侧的 SDK 版本徽章（它一直显示你当前用的 SDK 版本，如 2.5.92）→ 面板里点「更新 SDK / 更新开发包」—— SDK、文档（技能）、组件、资源整包铺进当前目录。
3. 开发软件会自动识别 .yunjie/skills/yunjie-plugin-dev（云捷插件开发技能）； 然后直接用中文提需求，例如：
   • 「用云捷插件开发 skill，做一个批量改标题的插件」
   • 「用云捷插件开发 skill，做一个批量改库存的插件」
   • 「查一下云捷 SDK 里怎么发优惠券」（它会去读 参考/02-SDK-营销.md）

更新完目录里就是这一套（别手写、别改名）：

D:\我的插件\                 ← 用开发软件打开的就是这个目录
├── 云捷SDK.js              ← 唯一能力入口，别手写、别改名
├── SDK更新日志.md           ← 每个版本改了什么
├── 资源\                   ← vue.min.js + element-ui（本地文件，不要改用 CDN）
├── 组件\                   ← 可复用组件（如 SKU搜索.js）
├── .yunjie\skills\         ← 云捷插件开发 skill 文档（打开本目录即生效）
├── 参考\                   ← 分模块文档（SDK 速查 / 营销 / 商品 / 售后 / 避坑…）
├── index.html              ← 你的入口（自己写）
└── app.js                  ← 你的逻辑（自己写）

第 2 步：在客户端里关联目录并本地调试

1. 打开云捷电商工具箱客户端 → 登录开发者账号
2. 进「开发者中心 → 我的应用」，找到（或新建）你的应用，点「版本」
3. 点「选择 / 更换目录」，选中你的插件目录（选一次就记住了）
4. 点「本地调试」→ 客户端会开一个应用标签，直接看到你的界面

看报错（AI 自己连 CDP，或按 F12）

怎么打开

三个面板各看什么

什么现象先看哪个面板

报错让 AI 自己连上去拿（推荐做法）

目录结构与入口

我的插件\                ← 客户端里选这个当「源码目录」（选**上层这一层**）
├── 发布\                ← 【会上传】要上线运行的文件都放这里
│   ├── 云捷SDK.js       ← 包自带，不要动
│   ├── 资源\            ← 包自带（Vue3 + Element Plus 本地文件）
│   ├── index.html       ← 入口（你写）
│   └── app.js           ← 业务代码（你写，ES Module）
├── 笔记.md              ← 【不上传】随便放
└── 设计稿.psd           ← 【不上传】

index.html（入口写法）

<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>我的插件</title>
<!-- UI 资源用本地的，不要改成 CDN -->
<link rel="stylesheet" href="./资源/element-plus/index.css">
</head>
<body>
<div id="app" v-cloak>
  <div class="page-header">
    <span>我的插件</span>
    <el-button size="small" @click="搜索()">搜索</el-button>
  </div>
</div>

<!-- 依赖：先 Vue（Vue3），再 Element Plus，再中文语言包 -->
<script src="./资源/vue.global.js"></script>
<script src="./资源/element-plus/index.js"></script>
<script src="./资源/element-plus/locale/zh-cn.js"></script>   <!-- 中文语言包（不引组件文案是英文） -->
<script src="./资源/element-plus/icons.js"></script>   <!-- 要用图标才引 -->

<!-- ⚠️ 业务代码必须是 ES Module（这样才 import 得动 云捷SDK.js） -->
<script type="module" src="./app.js"></script>
</body>
</html>

app.js（骨架）

// 只从 SDK 拿能力（不要写 const 云捷 = window.云捷，会白屏）
import 云捷 from './云捷SDK.js'

const app = Vue.createApp({
  data() {
    return { 店铺列表: [], 当前标签ID: '', 状态: '' }
  },
  async mounted() {
    this.店铺列表 = await 云捷.店铺列表()   // 只拿到"本应用可用"的店铺
    this.当前标签ID = this.店铺列表[0] ? this.店铺列表[0].标签ID : ''
  },
  methods: {
    /** 搜索商品（每个接口都要 try/catch，失败原因给用户看） */
    async 搜索() {
      try {
        const 结果 = await 云捷.商品.列表(this.当前标签ID, { 标签: 'onSale', 每页: 20 })
        if (结果.code !== 0) return this.$message.error('读取失败：' + (结果.msg || '未知原因'))
        this.状态 = '共 ' + (结果.data?.products?.length || 0) + ' 条'
      } catch (错误) {
        this.$message.error('读取失败：' + (错误 && 错误.message ? 错误.message : 错误))
      }
    }
  }
})
app.use(ElementPlus, { locale: window.ElementPlusLocaleZhCn })   // ⚠️ 不带 locale，组件自带文案是英文（确定/取消、分页 Go to、表格 No Data…）
app.config.globalProperties.$message = ElementPlus.ElMessage   // 想在方法里写 this.$message 就自己挂
app.mount('#app')

业务代码骨架（照着填就行）

import 云捷 from './云捷SDK.js'

/** 每批最多 20 个（抖店接口限制） */
const 每批上限 = 20

new Vue({
  el: '#app',
  data() {
    return {
      店铺列表: [],       // 有权限的店铺
      当前标签ID: '',     // 当前店铺的标签ID（调接口都用它）
      商品列表: [],       // 表格数据
      页码: 0, 每页: 20, 总数: 0,
      选中商品: [],
      执行中: false,      // 长任务时给按钮加 loading
      结果清单: []        // 成功/失败清单（必须给用户看）
    }
  },
  async mounted() { await this.初始化() },
  methods: {
    /** 初始化：取店铺列表并选中第一家 */
    async 初始化() {
      try {
        this.店铺列表 = await 云捷.店铺列表()
        if (!this.店铺列表.length) return this.$message.warning('这个应用还没有可用店铺，请先在客户端里授权')
        this.当前标签ID = this.店铺列表[0].标签ID
        await this.搜索()
      } catch (错误) {
        this.$message.error('初始化失败：' + (错误 && 错误.message ? 错误.message : 错误))
      }
    },

    /** 搜商品（分页从 0 开始） */
    async 搜索() {
      try {
        const 结果 = await 云捷.商品.列表(this.当前标签ID, { 页码: this.页码, 每页: this.每页, 标签: 'onSale' })
        if (结果.code !== 0) return this.$message.error('搜索失败：' + (结果.msg || '未知原因'))
        this.商品列表 = 结果.data?.products || []
      } catch (错误) {
        this.$message.error('搜索失败：' + (错误 && 错误.message ? 错误.message : 错误))
      }
    },

    /** 批量下架：先确认 → 分批（≤20）→ 汇总成败 */
    async 批量下架() {
      if (!this.选中商品.length) return this.$message.warning('先勾选商品')
      if (!window.confirm('下架 ' + this.选中商品.length + ' 个商品，确定吗？')) return
      this.执行中 = true
      this.结果清单 = []
      for (let i = 0; i < this.选中商品.length; i += 每批上限) {
        const 本批 = this.选中商品.slice(i, i + 每批上限)
        try {
          const 结果 = await 云捷.商品.批量上下架(this.当前标签ID, {
            商品ID列表: 本批.map((项) => 项.product_id), 上架: false
          })
          // 按接口返回的成败逐条记进"结果清单"
          本批.forEach((项) => this.结果清单.push({ 商品ID: 项.product_id, 结果: 结果.code === 0 ? '成功' : '失败', 原因: 结果.msg || '' }))
        } catch (错误) {
          本批.forEach((项) => this.结果清单.push({ 商品ID: 项.product_id, 结果: '失败', 原因: String(错误 && 错误.message ? 错误.message : 错误) }))
        }
      }
      this.执行中 = false
      const 失败数 = this.结果清单.filter((项) => 项.结果 !== '成功').length
      this.$message[失败数 ? 'warning' : 'success']('完成：成功 ' + (this.结果清单.length - 失败数) + '，失败 ' + 失败数)
    }
  }
})

常用能力速查

铁律与交付前自查

铁律（违反必定跑不通）

1. 模板里调用中文方法必须带括号：@click="搜索()"、@change="换店铺()"； 写成 @click="搜索" 会「只读函数引用不调用」→ 点了毫无反应、Console 还不报错。
2. 自定义组件标签不要自闭合：页内模板里 <el-input ... /> 会把**后面的兄弟节点整片吞掉** （表现：该有的按钮凭空消失）→ 必须写 <el-input ...></el-input>。 只有 <img />、<br /> 这类 HTML 空元素可以自闭合。
3. 模板里用到的字段，data/computed/methods 里必须真存在：改字段名要同步「data 定义 + 模板引用 + 方法里读写」三处， 否则整页 ReferenceError，点哪都没反应。
4. 不要用 localStorage 存业务数据：用 云捷.缓存 / 云捷.数据库。
5. 【强制】需要用户给"商品ID"时，不要让用户手输商品ID：只允许两种方式 —— ① 页面里嵌 <sku-search>（包内 组件\SKU搜索.js，组件库唯一的组件， 用户贴 SKU编码 → 自动搜出商品ID）；② 用 云捷.商品.列表() 拉列表让用户勾选。 拿到的是商品ID数组，直接传给批量接口 / 创建活动。详见 11-平台能力与组件库 4.1。
6. 每个接口都要 try/catch 并把失败原因展示给用户（不要只说"失败了"）。

交付前自查

• 所有事件绑定都带括号（搜「纯中文方法名、无括号」的绑定）
• 没有自闭合的自定义组件标签（搜 <el-[a-z0-9-]+[^<>]*/>）
• 用了「发布」目录的话：要上线的文件都放进了 发布\（源码 / 笔记 / 文档放外面不会被上传）
• 入口是 type="module" + import 云捷 from './云捷SDK.js'（没有 const 云捷 = window.云捷）
• 有全局错误条（window.onerror + unhandledrejection），报错看得见
• 金额按「分」处理；列表分页；批量每批 ≤ 20
• 多店铺循环一家失败不影响其他家，最后汇总成功/失败清单
• 危险操作（删除/作废/批量）有二次确认
• 没有引用 CDN（UI 资源用包里的本地文件）

改了代码怎么看效果

1. 改完 app.js / index.html，保存（Ctrl+S）
2. 客户端「开发者中心 → 我的应用 → 版本」再点一次「本地调试」， 或者关掉那个应用标签重新打开
3. 看界面右上角的「构建标记」之类的版本号，确认跑的是新代码（建议你在自己的插件里也放一个）

常见报错与坑

SDK 里没有你要的函数？让 AI 输出「缺函数清单」

应用：<应用名>　插件目录：<绝对路径>　开发包版本：<云捷.开发包版本>

下面几个函数 SDK 里没有，麻烦平台作者加一下：

| # | 期望的 SDK 函数 | 业务场景（想干什么） | 期望入参 | 期望返回 | 线索（哪个页面 / 什么现象） |
|---|---|---|---|---|---|
| 1 | 云捷.商品.取详情 | 批量改价前按商品ID校验标题/主图/价格 | { 店铺ID, 商品ID } | { 标题, 主图, 价格, 库存 } | 「商品管理」列表页能看到这些字段 |

打包提交审核

1. 客户端「开发者中心 → 我的应用 → 版本」→ 点「打包提交审核」 （把打包来源压成 zip 上传：有「发布」目录就只打它，没有就打整个源码目录； 上传时会显示进度 / 已传大小 / 预估剩余时间）
2. 版本号用平台建议值（YYYYMMDD-序号），填一句更新说明
3. 等平台审核；审核通过后上架应用市场
4. 用户在客户端应用市场里安装 / 订阅后即可使用（插件是整包下发到客户端内存里运行，不是从服务器拉页面； 用户那边下载时同样有进度条）

版本与更新开发包

完整流程清单（照着做一遍就能上架）

1. 装YunJev：本页右上「下载YunJev」（或官网首页 →「下载」→「YunJev」）→ 安装（非系统盘、英文路径）→ 云捷账号登录
2. 打开目录 + 更新 SDK：开发软件里打开（或新建）D:\我的插件， 点顶栏 SDK 版本徽章 →「更新 SDK」把 SDK / 文档 / 组件 / 资源铺进来（skill 自动生效）
3. 照抄骨架：按 .yunjie\skills\yunjie-plugin-dev\SKILL.md 第 1 节，在目录根写出 index.html + app.js
4. 关联目录：客户端「开发者中心 → 我的应用 → 版本 → 选择/更换目录」
5. 本地调试：点「本地调试」，先确认骨架能跑起来
6. 提需求给 AI：「用云捷插件开发 skill，做一个 XXX 的插件」，然后自己按需改
7. 边改边看：保存 → 在应用页面里刷新一下（F5；本地调试禁缓存，刷新即最新代码）
8. 跑接口：先取 云捷.店铺列表()，用 标签ID 调业务接口；失败原因要显示给用户
9. 自查：「铁律与交付前自查」逐条过一遍（括号、自闭合、字段、错误条、分页 ≤20、二次确认）
10. 打包提交审核 → 填版本号与更新说明 → 等审核
11. 上架后：用户在应用市场安装；后续要改就重复 6~10； 平台更新了 SDK，就在开发软件里点一次「更新 SDK」同步

常见问题（FAQ）

一定要用YunJev吗？

不一定。VS Code / Cursor 也能写（插件就是 HTML + JS，不需要打包工具）。用它的好处是 .yunjie/skills 会让 AI 按云捷规范写代码、自动查接口文档、避开已知坑， 顶栏还能一键「更新 SDK」，而且它跟客户端是同一套云捷账号、插件调试链路也是对着客户端做的。

插件要 npm install / 打包构建吗？

不需要。Vue3 和 Element Plus 都是开发包里的本地文件，浏览器直接跑；提交流程也是客户端点按钮自动压缩上传。

插件能直连数据库吗？能自己发 HTTP 吗？

不能直连数据库（平台不给）。发请求走 云捷.请求（抖店接口，自带店铺登录态与签名）或 云捷.网络.请求（站外接口，主进程发，绕开跨域）。

为什么我改了代码，界面没变？

本地调试是读磁盘的，但页面会被缓存 → 关掉应用标签重新打开（或再点一次「本地调试」）。仍不行就重启客户端。

为什么点了按钮一点反应都没有，也不报错？

九成是模板里中文方法名没带括号（见「铁律」第 1 条）；其次是整页渲染崩了（字段不存在，先看页面顶部错误条）。

多开 / 多店铺怎么处理？

客户端支持同时开多个应用标签；插件自己按 云捷.店铺列表() 逐个处理即可。 多店铺循环要「一家失败不影响其他家」，最后给出成功/失败清单。

开发包更新了，我要重写吗？

不用。点「更新开发包（整包）」覆盖 SDK 与文档即可（不动你的代码）；如果新版本的接口签名变了， 看 SDK 更新日志里对应版本的说明改一下调用点。

想加新能力 / 发现 SDK 不够用怎么办？

把需求提给平台（说明你想调什么接口、要什么参数），平台会把能力封装进 SDK 再随开发包下发 —— 插件永远只调 SDK，不自己造轮子。

接口与文件链接