OEM 设备管理器定制与打包
硬件厂商、方案集成商与 OEM 团队可基于 MIT 开源的 CDM_OEM 界面模板,定制自有品牌的 Windows 设备管理软件(修改软件名称、公司标识、Logo 与图标、主题配色、售后链接及可见功能页),无需从零编写设备通信代码。使用国内直连的桌面 AI 编程软件,只需复制一段提示词即可自动完成环境配置、界面修改与 Windows .exe 打包。
开始前准备(国内网络零门槛)
整个定制过程不需要写代码,不需要提前手动安装 Python 或 Git,也不需要海外账号或特殊网络环境:
1. 安装一款国内直连的桌面 AI 编程软件
任选以下一款支持国内网络直连、手机号或微信登录的桌面端 AI 工具安装(若电脑上尚未安装,推荐直接安装 Trae 国内版,全中文界面上手最快):
| 工具名称(官方下载) | 账号与网络要求 | 开启自动执行(智能体)的位置 |
|---|---|---|
| Trae 国内版 | 国内直连,手机号登录即用 | 右侧对话框顶部切换为 Builder 或 SOLO 模式 |
| 通义灵码 IDE | 国内直连,手机号 / 支付宝 / 阿里云登录 | 右侧对话面板切换为 智能体(Agent) 模式 |
| 文心快码 Comate | 国内直连,百度账号 / 手机号登录 | 安装独立 AI IDE 后在对话区切换为 Agent / Zulu 模式 |
| 腾讯云代码助手 | 国内直连,微信扫码登录 | 安装客户端后在对话面板选择 Craft / Agent 模式 |
若团队已配置国际网络环境,同样可使用 Cursor、VS Code(GitHub Copilot)、Claude Code 或 Codex CLI。注意:请勿使用纯网页版聊天窗口(如豆包网页版、DeepSeek 网页版、Kimi 网页版),网页无法直接读取你电脑里的文件夹并编译生成 .exe。
2. 新建一个工作文件夹(可选放入公司 Logo)
- 在 64 位 Windows 10 / 11 电脑上新建一个空文件夹(推荐简短英文路径,例如
D:\MyCDM)。- 你可以什么都不下载,在下一步由 AI 自动从 Gitee 拉取源码;也可以先点击本页顶部的 下载 CDM-0.9.0 源码包,把压缩包内层目录里的文件解压到
D:\MyCDM中。
- 你可以什么都不下载,在下一步由 AI 自动从 Gitee 拉取源码;也可以先点击本页顶部的 下载 CDM-0.9.0 源码包,把压缩包内层目录里的文件解压到
- 若已有公司或产品 Logo 图片(
.png、.jpg或.svg均可,建议正方形构图),直接把图片放进D:\MyCDM文件夹即可,无需自己手动转换.ico图标格式。
三步生成专属安装包
第一步:用 AI 软件打开工作文件夹
以 Trae 国内版为例:打开软件并登录后,点击左上角菜单 文件 -> 打开文件夹,选择刚才准备好的 D:\MyCDM,并确认右侧对话框顶部处于 Builder 或 SOLO 模式(其他工具同样通过「打开文件夹」进入 D:\MyCDM 并切换到智能体模式)。
第二步:复制「一句话全自动提示词」发送给 AI
点击下方代码块右上角的复制按钮,粘贴到 AI 对话框中,只需把方括号 【...】 里的品牌信息改成你自己的内容,按回车发送(提示词已内置 Gitee 国内源、清华/阿里云 PyPI 镜像加速与中文系统用户名兼容处理):
请帮我在这个文件夹里全自动定制并打包一款 OEM 设备管理软件,针对国内网络环境按以下步骤直接执行:
1. 如果当前目录还没有 cdm-runtime.lock.json,请从 Gitee 下载 CANmeleon CDM_OEM 的 CDM-0.9.0 源码包(https://gitee.com/canmeleon/canmeleon-device-manager/archive/refs/tags/CDM-0.9.0.zip ,备选 https://github.com/CANmeleon/canmeleon-device-manager/archive/refs/tags/CDM-0.9.0.zip ),解压并将内层目录里的全部文件移到当前根目录;先阅读 AGENTS.md、docs/oem-development.md 和 docs/cli-api.md。
2. 设置国内 Python 包镜像环境变量 $env:PIP_INDEX_URL = 'https://pypi.tuna.tsinghua.edu.cn/simple'(若连接异常改用 https://mirrors.aliyun.com/pypi/simple/),然后运行 powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1 自动准备项目内 Python 3.12.10 环境并从 Gitee 下载校验 CDM 0.9.0 后端(不要修改全局 Python、requirements.lock 或 cdm-runtime.lock.json)。
3. 按我的品牌信息修改 oem/branding.json:
- 软件显示名称(name):【例如:星河 CAN 设备管理器】
- 发布商英文或拼音标识(publisher):【例如:Xinghe Tech】
- 品牌主题色(theme_color,6 位十六进制):【例如:#0052CC】
- 是否显示在线固件检查入口(online_firmware):【填 true 保留在线检查,或填 false 仅保留离线导入】
- 帮助按钮跳转网址(help_url):【填你的官网或售后链接,或留空隐藏按钮】
- 自动生成专属的英文 product_id(须符合正则 [A-Za-z][A-Za-z0-9_.-]+,替换掉默认示例值)和全新的 GUID 作为 app_id。
4. 图标与界面定制:如果我在当前文件夹里放了图片,请使用 .venv\Scripts\python.exe 中的 PySide6 将其转换为清晰的方形 Logo 与 oem/icon.ico 放入 oem/ 目录并更新 branding.json;如果没放图片,请根据我的软件名称和主题色生成简洁的 oem/logo.svg 及对应的 oem/icon.ico(注意 build.ps1 仅复制 branding.json、logo 和 icon 三个资源文件)。其他界面需求:【例如:保持默认布局;或写明具体改动,如“在帮助弹窗加上技术支持电话 400-xxx-xxxx”,所有界面文字保持中英文双语,设备读写严格调用现有公开 CLI】。
5. 运行 .venv\Scripts\python.exe -m pytest -q 完成测试(若定制修改了默认页面或文案,请同步更新对应 UI 测试用例)。
6. 编译与打包(若系统临时目录含中文字符,先设置 $env:CDM_OEM_BUILD_ROOT = 'C:\cdm-oem-build'):
- 先运行 powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build.ps1 生成免安装编译目录(若本机未装 C++ 编译器且从 GitHub 下载 winlibs 超时,请先执行 winget install Microsoft.VisualStudio.2022.BuildTools --accept-package-agreements --accept-source-agreements --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" 通过微软国内 CDN 安装编译组件后再执行 build.ps1),并将生成的 oem_main.dist 打包一份绿色免安装 ZIP 存放在 dist\ 目录。
- 再检查本机是否安装 Inno Setup 6.7.3;若未安装,尝试执行 winget install --id JRSoftware.InnoSetup --version 6.7.3 --exact --accept-package-agreements --accept-source-agreements 安装,然后传入刚才编译好的目录运行 .\scripts\package.ps1 -PackageDir <oem_main.dist路径> 生成单文件安装向导 EXE(若当前网络无法从 GitHub 下载 Inno Setup 6.7.3,请直接交付已验证可用的绿色免安装 ZIP,并告知我手动安装 Inno Setup 6.7.3 后一键封装的命令)。最后把成品文件路径发给我。执行确认与首次编译耗时
执行期间如果 AI 软件弹出「运行终端命令」确认提示,点击 允许 / 运行 即可。首次将界面编译为原生 Windows 程序通常需要 3–8 分钟;后续微调界面再次打包会直接复用本地编译缓存,速度大幅加快。
第三步:验收效果与交付给客户
AI 运行完成后,你可以在工作文件夹的 dist\ 目录拿到现成可分发的软件包(两种形态均已内置编译后的定制界面与完整 CDM 0.9.0 运行组件,你的终端客户电脑无需安装 Python,也无需另装原版设备管理器):
| 产物位置 | 交付形态与用途 |
|---|---|
dist\CANmeleon-OEM-demo-0.9.0-setup-x64.exe | 单文件安装向导版。可直接重命名为你自己的产品名(如 星河CAN设备管理器_安装程序.exe)发给客户,双击按向导安装并自动生成桌面快捷方式。同目录的 oem-installer-build.json 记录了文件大小与 SHA-256 校验值。 |
dist\*.zip | 绿色免安装便携版(由 build\<时间戳>\oem_main.dist 压缩生成)。客户完整解压后直接双击里面的 CDM_OEM.exe 即可运行,适合内网拷贝或随硬件资料包直接发放。 |
打开软件预览后如果想继续微调,不需要重头开始,直接在同一个 AI 对话框用日常中文继续吩咐即可:
- 秒开窗口看效果(免等待编译):
先运行 .\scripts\run.ps1 打开软件窗口让我看一眼实际界面。 - 改配色与增加联系方式:
把主题色换成深绿色 #0F6B50,在“帮助”弹窗里加上“技术支持热线:400-xxx-xxxx(工作日 9:00–18:00)”(同步补全英文),改完重新打包。 - 改为纯离线内网版:
我的客户都在内网使用,把在线检查和下载固件的控件隐藏(online_firmware 设为 false),只保留“导入离线固件包”,重新打包。 - 精简界面页签:
只需要保留固件管理页和帮助按钮,把“设备信息”页签隐藏(pages 保留 firmware 和 help),更新测试后重新打包。
品牌配置项说明
基础品牌属性集中在 oem/branding.json 中,后续升级软件版本时建议备份并沿用同一份配置:
| 字段名 | 默认示例值 | 作用与填写规则 |
|---|---|---|
name | "CDM_OEM" | 软件窗口标题、桌面快捷方式及安装向导显示的产品名称(支持中文)。不可包含双引号或换行。 |
publisher | "canmeleon-oem" | 可执行文件属性与安装器中显示的发布商/公司名称。 |
product_id | "Kunhong.CANmeleon.OEMDemo" | 产品唯一英文标识(字母开头,仅限字母、数字、.、_、-),决定本地安装目录、缓存路径与运行互斥锁。新品牌首次发布必须修改;同一品牌后续升级须保持不变,以便覆盖升级。 |
app_id | "5C70252A-..." | Inno Setup 安装器升级识别码(GUID)。新品牌首次发布生成新值,后续升级保持不变,避免覆盖其他厂商软件。 |
theme_color | "#007F78" | 选中高亮与品牌强调色,使用 #RRGGBB 六位十六进制色值。 |
online_firmware | true | 设为 true 时显示 stable / beta 在线固件检查与下载按钮;设为 false 时隐藏在线入口,仅使用本地缓存与离线固件 ZIP 导入。 |
logo | "logo.svg" | 窗口左上角显示的品牌图标文件名(位于 oem/ 目录内,默认缩放为 24×24)。 |
icon | "icon.ico" | 窗口标题栏、任务栏、编译 EXE 与安装向导共用的 .ico 图标文件名(位于 oem/ 目录内,修改后需重新运行编译生效)。 |
help_url | "https://canmeleon.com/..." | 帮助弹窗中「帮助网页」按钮跳转的地址;设为空字符串 "" 时自动隐藏该按钮。 |
pages | ["devices", "firmware", "help"] | 控制界面启用的模块:firmware(固件槽位管理与固件市场)、devices(设备信息、通道终端电阻与 USB 模式切换)、help(顶部帮助与诊断弹窗)。至少保留一项。 |
手动命令行流程(可选)
在不使用 AI 自动执行命令的环境中,解压 CDM-0.9.0 源码包后打开 PowerShell 进入源码根目录,依次执行以下命令即可(已配置清华 PyPI 国内镜像加速):
# 1. 配置国内 PyPI 镜像,自动准备项目内 Python 3.12.10 并从 Gitee 下载校验 CDM 0.9.0 后端
$env:PIP_INDEX_URL = 'https://pypi.tuna.tsinghua.edu.cn/simple'
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1
# 2. 启动定制界面进行本地预览(修改 oem/branding.json 后可随时运行查看)
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run.ps1
# 3. 编译生成免安装运行目录(输出至 build\<时间戳>\oem_main.dist,压缩即可作为绿色版分发)
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build.ps1
# 4.(可选)封装单文件安装向导 EXE:需先安装 Inno Setup 6.7.3(每台电脑仅需装一次)
winget install --id JRSoftware.InnoSetup --version 6.7.3 --exact
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\package.ps1若内网打包电脑无法直接联网下载 CDM 后端包,可在有网电脑从 Gitee CDM-0.9.0 发布页 下载 CANmeleon-device-manager-win64.zip(须与 cdm-runtime.lock.json 锁定的版本及 SHA-256 一致),通过 -RuntimeZip 本地传入:
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1 -RuntimeZip 'D:\downloads\CANmeleon-device-manager-win64.zip'功能范围、安全边界与许可说明
0.9.0 OEM 模板适用范围
| 能力类别 | OEM 模板(0.9.0)支持情况 |
|---|---|
| 设备识别与连接 | 支持自动扫描列表、查看 USB 节点与驱动状态、读取设备 UID 与通道数 |
| 固件查看与切换 | 支持查看已装固件槽位与空槽容量、切换当前运行固件、卸载非运行固件 |
| 固件导入与安装 | 支持导入完整离线固件发布 ZIP、按兼容性筛选、安装预览(Dry-run)及指定空槽/替换安装;可选开启在线固件检查与下载 |
| 通道与模式配置 | 在硬件与当前固件支持时,支持读取/设置各通道软件终端电阻(自动回读核对)及切换 USB 工作模式 |
| 售后诊断与多语言 | 支持界面中英文实时切换、操作编号(Operation ID)结果查询与诊断 JSON 一键复制 |
| 恢复与高级维护 | 不包含 KH-Updater 恢复模式刷写、连续空间不足时的整组存储整理、设备自检、V2 流程及客户端在线自更新;遇到此类维护场景请引导用户使用原版 CANmeleon device manager,OEM 软件本身通过发布新版完整安装包升级 |
定制开发安全约束
无论由 AI 修改界面还是团队自行二次开发,均须保留以下保护机制,确保现场刷写安全:
- 仅调用公开 CLI 接口:所有设备枚举、固件安装与参数配置均通过
oem/client.py调用完整锁定的CANmeleon-device-manager.exe公开命令(schema_version=1),保留设备UID与安装计划plan_id校验;不得删减runtime/cdm目录文件或读取内部状态文件。 - 写入中断与未知状态保护:写入固件或切换模式期间必须保持 USB 连接与供电,关闭界面或强行结束进程不会安全取消设备端写入。当返回超时(
TIMEOUT)或结果未知(OUTCOME_UNKNOWN)时,界面会禁用写入操作,必须先重新连接并读取设备实际状态,严禁让 AI 添加“失败后自动重试刷写”逻辑。 - 软件数字签名建议:
package.ps1生成的安装包默认提供 SHA-256 校验记录,不包含商业代码签名证书。企业面向终端客户正式分发前,建议使用贵司自有的 Windows 代码签名证书(通过signtool)对编译目录中的CDM_OEM.exe及最终生成的安装程序.exe进行 Authenticode 签名,避免 Windows SmartScreen 弹出「未知发布者」提示。
开源许可与商标边界
- OEM 模板代码(MIT):仓库中的
oem/界面代码、公开 CLI 适配层、文档、打包脚本及默认示例图标采用 MIT 许可证开放,允许商业定制、编译与再分发。 - 运行组件与第三方库许可:MIT 许可证不授予 CANmeleon 商标使用权,也不改变随包分发的原版 CDM 二进制运行库及第三方组件(包括动态加载的 PySide6 / Qt 6.11.1 LGPL/GPL 库、Python 官方运行库与 Inno Setup)的原有许可条款。
scripts/build.ps1会自动把LICENSE、THIRD_PARTY_NOTICES.md与licenses/打包到软件目录中,定制分发时请完整保留这些许可声明文件,详见 Gitee 仓库 THIRD_PARTY_NOTICES.md(或 GitHub 镜像)。
常见问题排查
国内网络下载缓慢或连接 GitHub 超时
源码包与 CDM 0.9.0 运行库均托管在 Gitee,国内可直接高速下载;如在依赖安装或编译封装阶段遇到海外源较慢,按以下三项对应处理(上文的一句话提示词已自动包含这些处理):
setup.ps1安装 PySide6 较慢:先设置清华镜像$env:PIP_INDEX_URL = 'https://pypi.tuna.tsinghua.edu.cn/simple'或阿里云镜像$env:PIP_INDEX_URL = 'https://mirrors.aliyun.com/pypi/simple/',再运行setup.ps1。- 首次编译时 Nuitka 下载
winlibs编译器超时:未安装 Visual Studio 时,Nuitka 默认从 GitHub 下载 MinGW 编译器。国内网络可直接通过微软官方国内 CDN 安装 Visual Studio C++ 生成工具(winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"),安装后 Nuitka 会直接调用本地 MSVC 编译,无需访问 GitHub。 winget下载 Inno Setup 6.7.3 超时或提示Expected Inno Setup 6.7.3:Inno Setup 官方安装包托管在 GitHub Releases(见 Inno Setup 官方历史版本页 下的6.7.3版本)。若暂时无法拉取,直接运行.\scripts\build.ps1即可生成完整可用的免安装版目录(压缩为.zip即可发给客户);或手动安装innosetup-6.7.3.exe后运行.\scripts\package.ps1(如安装在自定义路径,可附带-Iscc 'C:\Path\To\ISCC.exe')。
源码目录或 Windows 用户名含中文导致编译失败
项目放在中文目录但系统用户名为英文时,build.ps1 会自动借用系统临时目录完成编译。若你的 Windows 登录用户名本身包含中文字符(导致 %TEMP% 路径带中文),在打包前执行 $env:CDM_OEM_BUILD_ROOT = 'C:\cdm-oem-build' 即可解决(一句话提示词已自动包含该指令)。
导入固件包时提示无效(INVALID_PACKAGE)
固件市场导入的是官方完整固件发布 ZIP(见固件目录与下载),不要选成设备管理器软件本身的 CANmeleon-device-manager-win64.zip 或解压后的单个文件。
连接设备提示 BUSY 或 DEVICE_BUSY
目标设备正被原版 CANmeleon device manager 或第三方 CAN 软件(如 CANoe、PCAN-View、ZCANPRO 等)占用。请先断开原版管理器的设备连接并关闭正在通信的 CAN 软件,再回到定制软件点击 刷新。
问题反馈与商业合作
- OEM 模板与脚本问题:国内用户可直接在 Gitee Issues(或 GitHub Issues)提交反馈,附上
CDM-0.9.0版本信息与命令行报错或帮助弹窗复制的诊断信息(对外发送前请按需隐去设备UID)。 - 硬件适配、专属固件与深度合作:需要定制硬件、移植芯片平台、适配自有 USB VID/PID 固件或咨询商业集成方案,请前往 CANmeleon 方案与合作联系入口 或联系鲲弘技术支持。