diff --git a/Document/飞牛fpk打包与部署.md b/Document/飞牛fpk打包与部署.md
new file mode 100644
index 0000000..c8be6ed
--- /dev/null
+++ b/Document/飞牛fpk打包与部署.md
@@ -0,0 +1,118 @@
+# 飞牛 fnOS fpk 打包与部署
+
+把网页粒子编辑器打包成飞牛 fnOS 应用包（`.fpk`），装到 NAS 后从桌面图标直接打开。本文是完整流程，照着做即可重复出包。
+
+## 1. 一次性准备
+
+**打包机**：开发用的 Mac/Windows/Linux 即可，需要 Node 环境（项目本来就有）。
+
+**fnpack**：飞牛官方的打包工具，从 https://developer.fnnas.com/docs/cli/fnpack/ 下载对应平台版本（本项目实测 `fnpack-1.2.3-darwin-arm64`）：
+
+```text
+chmod +x fnpack-1.2.3-darwin-arm64
+mv fnpack-1.2.3-darwin-arm64 /usr/local/bin/fnpack   # 或任意位置，后面用 FNPACK 指定
+fnpack --help
+```
+
+**目标设备**：已初始化的飞牛 fnOS，管理员账号，有可用存储空间，开发机可访问。
+
+## 2. 目录与职责
+
+| 路径 | 作用 |
+| --- | --- |
+| `src/` | 前端源码，编辑器本体 |
+| `dist/` | vite 构建产物，**网页端和飞牛包共用这一份** |
+| `packaging/fnos/SpineParticle/` | fnOS 包工程：`manifest`、`cmd/`、`config/`、`app/ui/`、`app/server/`、图标 |
+| `scripts/build-fnos-package.mjs` | 把 `dist/` 复制进包的 `app/www/` 并调用 fnpack |
+| `release/fnos/` | 打好的 `.fpk`（已加入 `.gitignore`，不入库） |
+
+包工程里 `app/www/` 由脚本生成，不要手改，改了也会被下次打包覆盖。
+
+## 3. 打包
+
+**第一步，改版本号**：编辑 `packaging/fnos/SpineParticle/manifest`，改这两行（飞牛按版本号识别升级，重打包务必递增）：
+
+```ini
+version=1.0.3
+changelog=这次改了什么，面向用户写一句话
+```
+
+**第二步，执行打包**：
+
+```text
+npm run pack:fnos
+```
+
+它等价于 `npm run build && node scripts/build-fnos-package.mjs`：先做 vue-tsc 类型检查和 vite 构建，然后清空 `app/www/`、复制 `dist/`（自动排除 `.DS_Store`）、调用 `fnpack build`，最后把产物移到 `release/fnos/`。
+
+**产物**：`release/fnos/SpineParticle-<version>.fpk`，当前约 2.6MB。
+
+如果 `fnpack` 不在 PATH 里：
+
+```text
+FNPACK=/path/to/fnpack npm run pack:fnos
+```
+
+## 4. 安装到飞牛
+
+方式一（图形界面）：飞牛桌面 → 应用中心 → 左下角「手动安装」→ 选 `.fpk`。
+
+方式二（命令行，需 SSH 到 NAS）：
+
+```text
+appcenter-cli install-fpk SpineParticle-1.0.3.fpk
+```
+
+安装完成后 `cmd/install_callback` 会自动启动内置静态服务；如果应用中心显示未运行，手动点一次「启动」。装好刷新一次飞牛桌面（F5 或重新登录），桌面图标才会出现。
+
+## 5. 装完必须验证的几项
+
+| 检查项 | 预期 |
+| --- | --- |
+| 桌面图标 | 出现「Spine粒子编辑器」，点开是编辑器界面（`http://<飞牛地址>:27850/`） |
+| 应用中心状态 | 显示运行中，可启动/停止 |
+| 预设下拉 | 能加载出预设列表（读取 `/Preset/index.json`） |
+| 连接器下载 | 帮助弹窗第 9 节两个下载按钮可用，能下到 exe 和 zip |
+| 远程备用入口 | `<飞牛地址>/cgi/ThirdParty/SpineParticle/index.cgi/` 也能打开 |
+| 连接器联动 | 本机启动连接器后，导出区显示「连接器可用 · Spine 已就绪」 |
+
+## 6. 包形态说明（重要，避免走回头路）
+
+当前用的是**端口服务**形态：
+
+```ini
+service_port=27850
+install_dep_apps=nodejs_v22
+ctl_stop=true
+```
+
+`app/server/server.mjs` 是 Node 写的静态服务，把 `app/www` 挂到 27850 端口，`cmd/main` 负责启停，桌面入口配置在 `app/ui/config`，指向该端口。
+
+**为什么不用 CGI 入口**：`/cgi/ThirdParty/{appname}/index.cgi/` 这套（纯静态、不占端口）在开发机上打包校验能通过，页面直连也能打开，但在目标设备上桌面入口始终没注册——表现就是桌面没有图标、应用中心「打开」点了没反应。试过补 `protocol`/`port` 字段也无效，换成端口服务后立即正常。所以后续请沿用端口形态。
+
+`app/ui/index.cgi` 保留着，仅作为远程访问备用入口，和端口走同一份 `www`。
+
+## 7. 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| 桌面没有图标 / 「打开」没反应 | 确认应用状态是运行中；刷新（F5）或重新登录飞牛桌面 |
+| 安装报依赖错误 | 确认 `manifest` 里 `install_dep_apps=nodejs_v22`，且设备能安装该运行时 |
+| 端口被占用 | 同时改两处并保持一致：`manifest` 的 `service_port`、`app/ui/config` 的 `port`，然后重打包 |
+| 外网点图标打不开 | 端口形态需要该端口可达；外网请用 `/cgi/ThirdParty/SpineParticle/index.cgi/` |
+| 页面白屏或资源 404 | 前端构建已改为相对路径（vite `base: './'`），若做过路径相关改动，先跑 `npm run build` 再用新 `dist` 打包 |
+| 服务起不来 | 看设备上 `/var/apps/SpineParticle/var/app.log` |
+| 安装异常 | 看设备上 `/var/log/trim_app_center/error.log` |
+
+## 8. 上架应用中心前待办
+
+- 替换图标：`packaging/fnos/SpineParticle/` 下 `ICON.PNG`(64×64)、`ICON_256.PNG`(256×256)，以及 `app/ui/images/icon_64.png`、`icon_256.png`，规格 sRGB、圆角方形、单文件 ≤1MB。目前是脚本生成的占位图。
+- 核对 `manifest` 里的 `maintainer`、`maintainer_url`、`distributor`、`os_min_version`（现填 Yeomai / gitlab 地址 / 1.0.0）。
+- 准备真实界面截图和测试材料。
+- 通过飞牛开发者先锋群 / 开发者后台提交。
+
+## 9. 提交代码时注意
+
+- `dist/` 在版本库里是**跟踪状态**，重新构建会带出 assets 的增删（文件名带哈希），要和源码改动一起提交，否则别人拉下来跑出的页面和打包不一致。
+- `packaging/fnos/SpineParticle/app/www/`、`release/fnos/`、以及包工程根目录的 `*.fpk` 都是构建产物，已在 `.gitignore` 中排除。
+- 包的形态、端口、入口配置一旦上架，跨版本要保持稳定，改端口等于改变用户访问方式。
diff --git a/release/fnos/SpineParticle-1.0.2.fpk b/release/fnos/SpineParticle-1.0.2.fpk
new file mode 100644
index 0000000..054cc61
Binary files /dev/null and b/release/fnos/SpineParticle-1.0.2.fpk differ