Manifest 清单配置

apps/<appname>/manifest 是 fnOS 应用的基础清单，使用对齐的 INI 风格键值格式。它描述应用身份、版本、平台、桌面入口和运行约束。应用目录、app/ui/config、config/、wizard/ 和生命周期脚本必须与 Manifest 保持一致。

新建或重建应用前，先查阅 fnnas-docs Skill 和飞牛应用开放平台文档。本文是本仓库的维护约定，不替代平台对字段的最新定义。

文件格式

apps/<appname>/
├── manifest
├── app/
├── cmd/
├── config/
└── wizard/

示例（字段之间使用空格对齐，不要改成 JSON）：

appname               = fn-deepseek-harness
version               = 7.0.2
display_name          = DeepSeek Harness
desc                  = DeepSeek AI 开源的插件化智能代理工具，通过 Web UI 提供 dsh 操作界面。
platform              = x86
source                = thirdparty
maintainer            = DeepSeek AI
maintainer_url        = https://github.com/deepseek-ai/deepseek-harness
distributor           = tnnevol
distributor_url       = https://github.com/FNOSP/fnos-dsh
os_min_version        = 1.1.3100
desktop_uidir         = ui
desktop_applaunchname = fn-deepseek-harness.Application
install_dep_apps      = nodejs_v24

常用字段

字段	作用	维护要求
appname	应用唯一标识	与应用目录名及相关入口 ID 保持一致
version	应用版本号	使用根 fnos-dsh-cli version 项目/FPK 流程维护
display_name	应用中心显示名称	面向用户，避免包含内部构建信息
desc	应用描述	支持富文本（HTML），随每次功能完成及时更新：说明用途、核心能力、快捷键和安装提示；用 <br />、<strong>、<code> 等标签组织版式，不写无法验证的承诺
changelog	应用变更摘要	随每次功能完成及时更新：概括本轮功能、修复与行为变化，与文档站对应需求的变更记录保持口径一致
platform	目标架构	按实际 FPK 产物填写，例如 x86、arm 或 all
source	应用来源	第三方应用通常使用 thirdparty
maintainer / maintainer_url	原始项目维护者和地址	指向真实上游项目
distributor / distributor_url	当前分发者和仓库地址	与发布主体保持一致
os_min_version	最低 fnOS 版本	使用已验证的系统版本，不凭构建机版本推断
desktop_uidir	桌面入口资源目录	必须对应 app/ui/ 下实际目录
desktop_applaunchname	桌面启动项 ID	必须能在 app/ui/config 中找到对应键
service_port	服务监听端口	与应用启动脚本、向导字段和入口配置一致
install_dep_apps	安装前置依赖	只填写应用中心可提供且确实需要的依赖
micro_app	是否作为微应用运行	与入口类型和网关方案一起验证

其他字段（例如 checkport、disable_authorization_path）应只在应用确实需要时增加，并以平台文档和同类已验证应用为准。

desc 与 changelog 的更新时机

每次功能完成（需求功能实现并通过本地验证）时，必须同步更新 manifest 中的 desc 与 changelog，不能等版本发布时才补：

• desc 支持富文本（HTML），使用 <br /> 换行、<strong> 分节标题、<code> 标记按键和路径；功能新增、删除或行为变化时同步增删对应描述，不留过期内容。
• changelog 追加或改写为本轮变更的简要摘要；保持中文，与需求文档变更记录、文档站安装说明口径一致。
• 两个字段都是单行 INI 值：换行用 <br /> 表达，不写真实换行；值内不要出现未转义的 # 开头注释或引号包裹。
• 更新后运行 pnpm run check -- --all 确认清单检查通过。

版本发布时不会自动改 desc 与 changelog

pnpm run version 只改版本字段（manifest 的 version、根 package.json、packages/*、插件版本与文档里的安装命令）以及 desc 中「运行基线为 DSH <基线>」这一处基线字样（对齐 catalog 当前值），不碰 desc 与 changelog 的其余内容——这两项是给用户看的内容，机器推不出该写什么。

因此发版时的检查项是「确认它们已经是本轮要发布的内容」，而不是「现在补写」：

1. 功能完成时先写好 changelog（与需求文档变更记录同源），再推版本；
2. 执行 pnpm run version 后，用 git diff 或 git show --stat 确认本次版本提交没有覆盖 changelog；
3. 若 changelog 仍是上一轮的内容，说明功能阶段的第 1 步漏了——在版本提交前补一次功能提交，不要混进版本提交。

changelog 的写法要求（面向用户、只写可感知变化、覆盖本轮项目与插件的全部对外变化）见版本发布后要维护什么。

与其他配置的对应关系

Manifest 里的关键字段必须在别处真实成立，否则安装后才会暴露问题：

Manifest	对应文件	需要保持一致的内容
desktop_uidir	app/ui/	UI 目录存在且包含入口资源
desktop_applaunchname	app/ui/config	.url 下存在同名入口
service_port	cmd/main、wizard/*	服务监听端口和用户配置来源一致
install_dep_apps	config/、安装回调	依赖确实由 fnOS 管理或已声明
os_min_version	测试记录	在最低版本设备上完成基础验证
version	发布 Tag、FPK	FPK、升级说明和仓库版本保持一致

提交前检查

# 检查 Manifest 与目录、入口和资源
pnpm run check -- --all

# 构建单个应用
cd apps/<appname>
fnpack build

逐项确认：

• appname、应用目录名、桌面入口 ID 没有拼写漂移。
• version 是合法版本号，并符合项目或 FPK 的版本策略。
• platform 与实际构建架构一致。
• desktop_uidir、desktop_applaunchname 和入口文件真实存在。
• 端口、网关前缀、授权路径和健康检查配置能串联工作。
• 不把密钥、个人路径、临时构建信息或未经验证的版本写入 Manifest。

最终应在测试 NAS 上通过应用中心完成安装、启动、停止、升级和卸载验证；本地 fnpack build 只证明清单和包结构可以构建。

相关页面

• 应用结构
• 生命周期脚本
• 权限与入口
• 用户向导