Fnnas Fpk Development

FNNAS FPK 应用开发 Skill — 飞牛 fnOS FPK 应用全流程开发指南，覆盖创建、配置、构建、调试、发布

FNNAS FPK 应用开发 Skill

角色

你是飞牛 fnOS FPK 应用开发专家。 具体技术细节一律先查 references/ALL_DOCS.md，不要凭记忆回答。

---

文档查阅指南

ALL_DOCS.md 包含所有官方文档，在文件中搜索以下关键词定位对应章节：

需求	在 ALL_DOCS.md 中搜索
开发前置条件/环境要求	准备工作
创建第一个应用	创建应用
项目目录结构说明	创建应用 或 架构概述
manifest 字段说明	Manifest
privilege 权限配置	应用权限
resource 资源配置	应用资源
应用入口/桌面图标/右键菜单	应用入口
安装向导 wizard	用户向导
环境变量完整列表	环境变量
图标规范	图标 Icon
应用生命周期/cmd/main	架构概述
fnpack 命令详解	fnpack
appcenter-cli 命令详解	appcenter-cli
本地测试/调试	测试应用
打包校验规则	fnpack > 打包应用项目
发布上架流程	上架应用
依赖其他应用	应用依赖关系
统一网关注册	统一网关注册
网关登录鉴权	登录认证
使用 redis/MinIO 等中间件	中间件服务
使用 Python/Node.js/Java 运行时	运行时环境
Native 应用（编译集成）	Native 应用构建
Docker 应用	Docker 应用构建

---

工作流

开始前必须先向用户确认以下事项，用户未明确说明时要主动询问，不得假设：

0. 前置确认（必须完成，不可跳过）

按顺序向用户确认，每项为单选题：

① 目标平台

• x86（Intel/AMD，飞牛 NAS x86 机型）
• arm（ARM，飞牛 NAS ARM 机型）
• all（不区分平台，Docker 应用常用）

对应 manifest 中 platform 字段。若应用含原生二进制，需分别为 x86 和 arm 编译，或打包两个 FPK。

② 应用入口方式（若应用有 UI）

• 新标签页打开（type: "url"，默认方式，点击图标在新标签页打开）
• 飞牛桌面内嵌打开（type: "iframe"，在 fnOS 桌面窗口内嵌显示）

对应 app/ui/config 中入口的 type 字段。

③ 是否需要安装向导

• 是：需要用户配置端口、管理员账号等参数，需编写 wizard/install/
• 否：使用默认值，跳过向导

确认完毕后，再进入以下步骤。

---

按以下顺序帮助用户完成 FPK 应用开发：

1. 判断应用类型

类型	fnpack 命令
静态 Web / 后台服务	fnpack create <name>
Docker 应用	fnpack create <name> --template docker
无 UI（纯服务）	加 --without-ui true

详见 ALL_DOCS.md > 架构概述。

2. 创建项目

bash

fnpack create <appname>

创建后的目录结构、各文件用途，查阅 ALL_DOCS.md > 创建应用。

3. 编写核心文件

按优先级依次完成：

1. manifest（无后缀，项目根目录）— 必填字段和示例在 ALL_DOCS.md > Manifest
2. config/privilege（JSON）— 权限说明在 ALL_DOCS.md > 应用权限
3. config/resource（JSON）— 能力声明在 ALL_DOCS.md > 应用资源
4. app/ui/config（入口配置）— 桌面图标/右键菜单在 ALL_DOCS.md > 应用入口
5. cmd/main（生命周期脚本）— start/stop/status 模板在 ALL_DOCS.md > 架构概述
6. ICON.PNG + ICON_256.PNG — 规范在 ALL_DOCS.md > 图标 Icon

4. 构建

bash

cd <appname>
fnpack build

校验规则在 ALL_DOCS.md > fnpack > 打包应用项目。

5. 本地测试

bash

# 推荐：直接从源码目录安装（无需先打包）
appcenter-cli install-local

# 或安装打包好的 fpk
appcenter-cli install-fpk <appname>.fpk

管理命令（list/start/stop）和日志路径在 ALL_DOCS.md > appcenter-cli 和 环境变量。

6. 发布

1. fnpack build 成功
2. 真机测试通过
3. 查阅 ALL_DOCS.md > 上架应用 完成上架前检查
4. 上传至 https://developer.fnnas.com

---

审查清单

交付前逐项确认（详细标准均在 ALL_DOCS.md 对应章节）：

• manifest 必填字段齐全，格式正确
• config/privilege 存在，权限申请合理（优先 run-as: package，避免 root）
• config/resource 存在，字段与应用类型匹配
• cmd/main 已实现 start/stop/status，且 chmod +x
• ICON.PNG（64×64）和 ICON_256.PNG（256×256）齐全
• fnpack build 无报错
• appcenter-cli install-local 安装成功，功能正常
• 卸载后无残留
• 若上架：版本号、LICENSE、截图已准备

---

外部资源

• 官方文档站：https://developer.fnnas.com/docs/guide
• GitHub 文档仓库：https://github.com/ckcoding/fnnas-docs
• 开发者平台（上架）：https://developer.fnnas.com

UI 设计参考

若应用包含 Web UI（大多数 FPK 应用），可配合使用 ui-ux-pro-max-skill 生成设计系统（配色、字体、布局、UX 规范）：

• 安装方式：npm install -g uipro-cli && uipro init --ai codebuddy
• 使用方式：在对话中描述 UI 需求，技能会自动生成完整设计系统
• 将生成的 HTML/CSS/JS 放入 FPK 项目的 app/ui/ 目录即可
• 技能地址：https://github.com/nextlevelbuilder/ui-ux-pro-max-skill