需求清单

这里记录三方飞牛应用项目的正式需求。需求文档描述“要解决什么问题、涉及哪些范围以及如何验收”；具体实现方案放在对应的详细计划中。

需求与计划的边界

需求和计划不是同一份文档的重复版本：

1. 需求文档记录完整的需求范围，包括已经完成、正在规划、待验证以及暂未排期的功能。
2. 计划文档只记录已经进入当前实施阶段的功能，负责说明具体实现、交互、验证和发布方式。
3. 需求中的 P2 或“后续计划”可以保留在需求清单中，但未正式进入计划前，不得出现在计划的阶段任务、详细交互、完成状态或测试清单中。
4. 需求范围发生变化时，先更新需求文档；确认进入实施后，再在对应计划中增加任务并记录变更。
5. 需求验收完成后，需求文档和计划文档都要更新状态；只有在目标环境完成验收后，才能标记为“已完成”。

文档关系如下：

需求提出
  └─ 需求文档：范围、优先级、状态、验收条件
       └─ 进入计划
            └─ 计划文档：架构、交互、实现、测试、发布
                 └─ 目标环境验收
                      └─ 回写需求和计划的完成状态

需求文档规范

文件位置和命名

需求文档统一放在 docs/requirements/，文件名使用：

FNOS-###-需求主题.md

规则：

• 编号前缀使用需求主编号 FNOS-###，并在项目范围内保持唯一、连续。
• 需求主题使用简短、明确的中文或英文短语，概括需求的核心对象和目标；英文或多词名称使用短横线连接。
• 名称概括需求目标，不使用“修改”“临时”“test”等无法表达范围的名称。
• 日期不写入文件名前缀，需求正式确认或开始记录的日期保留在 Frontmatter 和元信息表中。

示例：

docs/requirements/FNOS-001-dsh-fnos-adaptation.md
docs/requirements/FNOS-002-dsh-workspace-access.md

Frontmatter、标题和元信息

文档必须包含 title 和 description，一级标题与 title 保持一致：

---
title: FNOS-001 DSH 飞牛 NAS 适配
description: DeepSeek Harness 在飞牛 fnOS 中的应用、插件和 NAS 能力适配需求。
---

# FNOS-001 DSH 飞牛 NAS 适配

一级标题后使用元信息表，字段固定为：

字段	要求
需求编号	使用 FNOS-###，同一需求的功能使用 FNOS-###-##
提出日期	使用需求正式确认或开始记录的日期，格式为 YYYY-MM-DD
需求状态	使用状态徽章，表示整个需求的当前阶段
关联计划	已进入计划时链接到对应计划；未排期时写明“暂未进入计划”

固定章节和内容要求

每篇需求文档按以下顺序编写，章节名称保持一致：

1. 需求背景与目标：说明现状、问题、用户或宿主环境，以及本需求要达到的结果。
2. 需求目标：用短句列出可判断的目标，不写具体代码实现。
3. 涉及范围：用表格列出应用、插件、公共模块、目录或外部项目及其职责。
4. 功能列表：列出用户可感知或可验收的功能。
5. 交互和行为约束：记录文案、入口、权限、宿主差异和必须保持的行为。
6. 不在本次范围内：明确不修改的源码、数据、平台能力和未承诺的兼容场景。
7. 验收条件与完成状态：按优先级写验收条件，并用状态看板汇总阶段进度。
8. 变更记录：追加需求范围、状态或验收规则的变化。

功能编号、优先级和状态

功能列表至少使用以下列：

编号	优先级	功能	用户行为	状态
FNOS-###-01	P0/P1/P2	可验收的功能名称	用户如何使用以及预期结果	状态徽章或状态文字

编号规则：

• 需求主编号在项目范围内递增，例如 FNOS-001。
• 功能编号继承主编号，例如 FNOS-001-01、FNOS-001-02。
• 历史需求整合后，以整合文档中的新编号为准；旧编号从现行文档和清单中移除，不再继续引用。

优先级含义：

优先级	含义
P0	应用或插件的运行基线，未完成会影响核心可用性
P1	当前需求确定要实现的主要功能，可在 P0 稳定后实施
P2	已记录但尚未进入当前实施阶段的扩展需求

统一状态含义：

状态	使用条件
已完成	代码、必要构建和目标环境验收均已完成
待完成	已有代码或本地验证，但目标环境尚未验收完成
规划中	已确认要实现，但实现尚未完成；通常已进入计划
待验证	依赖 SDK、宿主或 DSH seam 等技术事实，需验证后才能确定实现方式
待确认	需求边界或交互方式尚未确认，未进入当前计划
后续计划	需求已登记，但尚未进入当前计划；不得在计划文档中展开实现任务

状态看板应优先使用 VitePress Badge，例如：

<Badge type="warning" text="待完成" />

验收和状态规则

• 每个 P0/P1 功能必须有对应的验收条件，验收条件应描述可观察结果，而不是“代码已提交”。
• 涉及 fnOS NAS、权限、主题事件或 FPK 安装的功能，必须把真实 NAS 验收列为完成条件。
• 本地调试通过但尚未在目标 NAS 环境验证时，状态使用“待完成”，不能写“已完成”。
• 验收条件与完成状态中先按阶段说明验收条件，再用状态看板汇总当前状态和下一步。
• 状态变化必须追加到变更记录，不能只修改徽章而隐藏历史状态。

需求变更和历史整合

• 需求变更在原文档追加变更记录，不通过删除旧内容隐藏范围变化。
• 新增功能先加入需求文档并标记优先级和状态；只有确认进入实施后，才同步到计划文档。
• 历史需求整合后，整合文档作为当前唯一版本，重新使用当前有效编号；已迁移的历史 Markdown 内容应删除或停止作为现行入口维护。
• 需求清单只维护规范和当前整合结果，不复制应用或插件的实现说明。

当前需求整合结果

截至 2026-08-24，历史上明确标记为规划、后续或待评估的 fnOS/DSH 适配内容已统一纳入 FNOS-001：DSH 飞牛 NAS 适配，该需求的 P0/P1 已完成目标环境验证：

历史内容	当前归属	状态
fnOS 主题桥接	FNOS-001-02	已完成验证
fnOS 应用入口、统一网关和访问权限	FNOS-001-01	已完成验证
FPK 安装阶段集成 DSH 插件	FNOS-001-09	已完成验证
授权目录展示、添加、删除和刷新	FNOS-001-04	已完成验证
工作区快捷跳转已授权 fnOS 目录	FNOS-001-10	已完成验证
内容输入框选择 NAS 目录和文件	FNOS-001-11	已完成验证
上下文文件访问适配	FNOS-001-12	已完成验证
后续 fnOS JS SDK 能力	FNOS-001-08	后续计划

当前需求文档

编号	需求文档	状态
FNOS-001	DSH 飞牛 NAS 适配	P0/P1 已完成验证
FNOS-002	DSH 应用与插件优化（含版本统一、Codex 状态、NAS 引用、共享 UI、FPK 网关和 DSH Web 恢复）	P1 部分 NAS 验证
FNOS-003	FPK 应用运行设置统一	规划中

当前未发现其他明确的历史待开发需求未登记到需求文档中。新增需求先登记在对应需求文档，确认进入实施后再同步到详细计划；整合完成后，旧的拆分编号不再作为现行需求编号使用。