Moonshine-Image 说明文档
官网 下载

开发者指南 / 当前实现

先理解边界，再进入代码。

Moonshine-Image 是一个 Electron 桌面应用：Vue 渲染层负责工作台，Electron 主进程负责本地系统与安全边界，Python / FastAPI 后端负责模型和媒体处理。

01

技术栈

Renderer

Vue 3 · Quasar · Vite

图片、视频、设置与活动视图。

Desktop

Electron

窗口、托盘、生命周期、更新、preload IPC 与 MCP。

Backend

Python · FastAPI

OCR、SAM、图像 / 视频处理与模型管理。

Media & AI

WebAV · FFmpeg · ONNX Runtime

视频预览 / 导出、失败回退和 OCR 推理。
Node.js^18 · ^20 · ^22 · ^24 · ^26 · ^28
npm>= 6.13.4
Python 开发基线3.12.x
首发桌面目标Windows x64

02

本地开发

在仓库根目录安装依赖，再启动 Quasar 的 Electron 开发模式。具体 Python 环境应与项目的运行环境管理策略保持一致。

PowerShell
npm install
npm run dev
环境要求项目支持 managed 与 external Python。不要手动把 runtime manifest 复制到 env，也不要假设某个 CUDA / 模型 flavor 在所有开发机器上都存在。

常用质量检查

PowerShell
npm test
npm run lint
npm run test:contracts:mcp-ocr
npm run test:regression:p0:full

测试名表示仓库内的验证范围，不等于已通过独立 Windows 机器、完整模型 / 许可矩阵或所有外部客户端的最终验收。

03

架构与安全边界

RendererVue / Quasar 工作台只通过命名 preload IPC 请求安全能力
Electron main本地可信边界窗口、后端生命周期、secret、任务真相
Python backendFastAPI / 模型服务OCR、SAM、图像、视频与模型管理
  • Electron main 拥有系统能力：窗口、Tray、退出、后端生命周期、MCP secret 和持久任务状态不归 renderer 所有。
  • Renderer 只接收安全投影：本地路径、secret 和受控 artifact 不应绕过 preload IPC 暴露。
  • 后端是本地处理服务：媒体和模型处理位于 server/moonshine_server，不要把它描述成公开云 API。
  • 输出不覆盖输入：所有处理路径都应保持新文件语义，并验证输出目录和可信路径 containment。

04

项目地图

Repository
src/                         Vue renderer
src/pages/IndexPage.vue      图片工作台
src/pages/VideoPage.vue      视频时间轴工作台
src/services/                图片、SAM、视频服务封装
src-electron/                Electron main、preload、runtime、MCP
server/moonshine_server/     FastAPI、OCR、SAM、模型管理
scripts/                     构建、发布、验证
test/                        Node / Electron / contract tests
server/tests/                Python backend tests
/image图片工作台
/video视频工作台
/activity/mcpMCP 活动与任务视图

05

构建与验证

下面是仓库当前提供的 Windows 构建入口。它们用于生成可运行目录、安装器或 Windows 分发矩阵。

PowerShell
npm run build:electron:packager
npm run build:electron:installer
npm run package:win:matrix
  1. 1
    先验证源码

    运行与改动范围相称的测试和 lint。

  2. 2
    准备受保护资源

    生成 backend、FFmpeg、模型适配和 runtime 资源，并审计清单。

  3. 3
    构建所需形态

    日常验证优先 packager，需要安装体验时再构建 NSIS。

  4. 4
    验证产物边界

    确认 app-only、manifest、签名和包内容，再进入发布流程。

不要从构建成功外推发布结论。仓库内测试或本机 packager 成功不能单独证明 clean-machine 安装、更新、回滚、卸载，也不能证明 beta / canary / stable 人工验收已经完成。

06

实现口径

开发文档只陈述当前源码和已验证边界。接入或二次开发时，请保留“已实现”“条件可用”“待外部验收”的区分。

  • 可以依赖：当前源码中的图片 / 视频工作台、模型能力 metadata、preload IPC、MCP 工具白名单和仓库测试入口。
  • 需要前置条件：CUDA、SAM3、MAT、SLBR 和真实模型运行取决于本机环境、权重与许可。
  • 尚不能对外承诺：全平台 / 全 flavor 可用、独立 clean-machine 完整验收、完整外部 OCR / MCP E2E 或所有 CUDA / SAM3 组合。