本文记录开发文档和开放 API 的主要更新。最新更新在最上方。

2026-07-31

本次更新新增开放 API 文档，用于说明应用如何通过前端 JS SDK 和后端 API 接入 fnOS 的开放能力。相关接口当前要求系统版本 1.2.0401 及以上，App 版本 1.34.0 及以上。

主要变化

• 新增开放 API 文档，覆盖调用方式、授权与文件、页面能力和错误码。
• 更新 llms.txt 和 llms-full.txt，补充开放 API 的文档索引和完整内容。

开放 API

• 新增 调用方式 文档，说明 api-scope 声明、前端 JS SDK 安装与初始化、宿主环境和独立浏览器页面的差异、授权跳转回调处理，以及后端 API 的统一请求结构。
• 新增 授权与文件概览，说明应用访问用户文件前为什么需要授权、应用用户 ACL 的作用，以及应用共享授权和用户个人授权的选择方式。
• 新增 应用共享授权路径，说明管理员如何通过 pickSharedFile 或授权跳转流程为应用配置固定目录授权，并通过后端 API 查询或删除授权目录。
• 新增 用户个人授权路径，说明当前用户如何通过 pickUserFile 授权自己的目录或文件，并说明目录授权可查询、文件授权直接通过返回结果使用。
• 新增 文件权限检查，说明后端如何通过 trim.file.checkUserACL 判断当前用户对指定路径是否具备读、写或删除权限。
• 新增 路径转换，说明后端如何通过 trim.file.convertPath 把 /vol1/... 这类内部路径转换成适合展示给用户看的路径。
• 新增 页面路由，说明前端如何打开文件、文件详情、文件管理器、应用设置页和外部 URL。
• 新增 页面交互，说明前端如何获取平台配置、设置页面标题、设置离开页面提示、关闭当前应用页面，并在 Web 宿主环境中监听主题或语言变化。
• 新增 错误码，整理 JS SDK 错误码和后端 API 错误码，方便开发者定位权限、参数、认证和系统异常问题。

2026-07-05

本次更新优化了文档结构和应用案例，方便开发者更快理解应用开发流程。

主要变化

• fnpack 更新至 V1.2.3。
• 优化部分描述，提升文档整体一致性。

2026-05-09

本次更新补充统一网关相关文档，用于说明应用如何复用飞牛 fnOS 访问域名提供服务。

主要变化

• 新增统一网关文档，介绍通过 gatewayPrefix 和 gatewaySocket 注册应用访问路径。
• 补充统一网关的登录态校验说明，以及网关转发给应用的用户信息 Header。
• 补充 WebSocket 接入方式，说明长连接请求如何通过统一网关转发到应用服务。

适用场景

统一网关适合需要复用系统访问域名、接入 NAS 登录态、提供 API 或支持 WebSocket 的应用。简单静态页面或兼容已有包时，也可以继续使用 index.cgi。

2025-12-31

本次更新调整了文档组织方式，并补充多架构、环境变量和打包工具相关说明。

主要变化

• 增加文档更新日志分类，便于查看不同阶段的文档变化。
• 调整部分文档结构，使阅读顺序更接近应用开发流程。
• 增加 New、Update 等文档标记，用于提示新增或更新内容。

开发概念

• 环境变量文档新增授权目录列表相关说明。
• 应用入口配置支持使用环境变量。
• 应用入口 protocol 字段支持为空，由系统根据当前访问方式自适应处理。
• manifest 中废弃原 arch 字段，改用 platform 表示应用支持的架构范围。

工具更新

• fnpack 更新至 V1.2.0。
• 补充打包前校验规则。
• 新增 Linux ARM 版本下载。

2025-12-16

本次更新主要优化文档结构、搜索能力和入门示例。

主要变化

• 修复暗色主题下首页和 Footer 的显示问题。
• 优化首页一级分类命名，让新开发者可以按顺序阅读，熟悉流程的开发者也能快速定位内容。
• 在页面右上角加入全局搜索，支持文档内容检索。
• 调整 创建应用 文档位置，并更新为更容易理解的入门案例。

内容更新

• manifest 新增应用更新相关说明，并增加 change_log 字段。
• fnpack 更新至 V1.0.4，补充命令说明和注释。
• Docker 应用文档补充注释并优化说明。
• 入门示例调整为 HTML、JavaScript、CSS 静态页面，降低初次阅读门槛。

---