Jingyun DSH 客户端开发者手册

二次开发与品牌打包指南

本手册适用于开发与技术运维人员，指导如何对 Jingyun DSH Client 桌面客户端进行本地开发调试、定制品牌参数，并最终编译打包为独立的 Windows 安装程序 (.exe)。

---

🛠️ 一、 本地开发环境准备

在开始开发或打包之前，请确保你的本地计算机已安装以下环境依赖：

1.1 内置运行环境（Vendor Runtime）配置

由于客户端运行时包含完整独立的 AI 对话底座及插件引擎，打包时需要内嵌便携版运行时（包含 Node.js、Git、Python 等）。

• 资源路径：必须放置在项目根目录下的 src-tauri/resources/vendor/ 目录中。
• 注意：这些内置环境包由于体积过大，默认不包含在 Git 源码库中。请联系井云官方获取该资源压缩包，并解压至上述路径后再进行编译打包。

---

💻 二、 本地调试与运行

拉取代码后，在项目根目录下依次执行以下步骤：

2.1 安装项目依赖

pnpm install

2.2 构建井云核心定制插件

在本地运行或打包前，必须先编译 packages/jingyun-dsh 的核心代码：

pnpm build

2.3 启动本地 Web 开发预览

如果你想在浏览器中直接预览和调试 DSH 对话及插件：

pnpm start

• 服务启动后，可在浏览器访问：http://localhost:3080

2.4 启动 Tauri 桌面客户端调试

如果你需要调试 Tauri 原生窗口、托盘、系统通知等功能：

pnpm tauri:dev

• 该命令将拉起一个 Tauri 调试窗口，并支持前端代码的热重载 (HMR)。

---

⚙️ 三、 品牌与 SaaS 对接配置

客户端的品牌定制与租户后台对接通过修改配置文件实现。

• 配置文件路径：packages/jingyun-dsh/jingyun-config.json

3.1 核心参数项详解

{
  "api_url": "http://localhost:8889/",
  "tenant_host": "61978ad0",
  "domain": "http://61978ad0.localhost:3003/",
  "custom_name": "Jingyun.Studio",
  "custom_logo": "https://jingyun-studio.oss-cn-chengdu.aliyuncs.com/uploads/1772455818454.png"
}

• api_url: 井云后台 Tenant 服务的 API 地址（本地开发默认为 8889，SaaS 环境为井云官方或私有部署 API 地址）。
• tenant_host: 你的租户唯一 ID Key。用户通过此 Key 与你的租户套餐、支付通道进行绑定。
• domain: 客户端窗口启动后渲染的 Web 地址（即租户的专属二级域名站点）。
• custom_name: 专属客户端的软件名称。
• custom_logo: 软件图标素材地址（可为在线 CDN 图片 URL）。

---

📦 四、 GUI 一键打包 Windows 客户端

项目提供了一个基于 Python 网页服务的一键打包控制台，无需手动修改繁琐的 Tauri 配置文件。

4.1 启动打包控制台

在项目根目录下，双击运行：

run_pack.bat

或者在控制台中执行：

python scripts/pack_gui.py

控制台启动后，将自动在浏览器中打开：
👉 http://127.0.0.1:8089

4.2 网页控制台参数配置

在打开的打包网页中，你可以直接输入以下信息：

1. 应用名称 (App Name): 软件对外显示的名称，例如：阿尔法AI助手。
2. 应用包名 (Bundle ID): 必须是系统唯一的标识符，例如：com.alpha.aihelper。
3. 应用版本号 (Version): 例如 1.0.0。
4. 应用 Logo 图标: 点击 "📁 选择本地文件" 选择一张本地的 .png 图片（必须是高清的 PNG 图）。打包器将自动使用 npx tauri icon 逆向生成多分辨率的平台图标并保存至 src-tauri/icons_generated。
5. SaaS 服务地址 (API URL): 你的 API 接口地址，例如 https://api.yourdomain.com。
6. 租户 Key (Tenant Host): 你的井云租户唯一标识，例如 tenant_alpha。
7. 客户端加载域名 (Domain URL): 客户端启动后要渲染的 Web 页面网址，例如 https://tenant_alpha.yourdomain.com。

4.3 打包原理解析（打包器自动执行的步骤）

当你点击 "开始一键打包生成客户端" 时，Python 后台打包程序会自动执行以下流程：

1. 回写基础配置：将表单数据自动同步到 jingyun-config.json。
2. 编译 Workspace 依赖：执行 pnpm build 并执行 prepare_vendor.js 装配运行依赖。
3. 生成动态启动页：根据配置的 App Name 动态生成 Splash 启动动画屏的 HTML 源码并输出到编译缓存。
4. 修改 Tauri 基础配置：自动读取 src-tauri/tauri.conf.json 并动态写入新的 productName、identifier、version 以及图标集合，并强行将窗口设置为无边框及最大化启动。
5. 更新 Cargo 版本：修改 Rust 模块 Cargo.toml 里的版本号，与客户端版本号对齐。
6. 安全白名单注入：【关键步骤】 自动解析你的 Domain URL 和 API URL，将它们的域名自动追加到 src-tauri/capabilities/default.json 的安全白名单列表 remote.urls 中，确保 Tauri 沙箱不会因安全策略阻断客户端与网页和 API 的网络通信。
7. 图标逆向生成：如果上传了本地 Logo，自动运行 npx tauri icon 构建适用于 Windows (ico) 和 Mac (icns) 的专用图标包。
8. 拉起编译引擎：通过 NSIS 编译器开始打包，自动把安装包的步骤汉化为 100% 简体中文。

4.4 打包产物与提取

• 打包成功后，控制台日志终端将显示 🎉🎉 中文一键客户端打包成功！。
• 你可以点击网页下方的 "📂 打开生成包文件夹" 按钮，或者手动前往项目根目录下的以下路径提取 .exe 安装文件：
  👉 src-tauri/target/release/bundle/nsis/