详细计划

这里记录需求对应的具体实施方案。计划文档回答“准备怎么实现、如何交互、如何验证以及如何发布”；它不是需求清单，也不替代代码和真实环境验收。

计划与需求的边界

1. 一篇计划对应一篇需求，计划页顶部必须链接对应需求；计划编号使用 PLAN-FNOS-###。
2. 需求文档可以记录完整范围和未排期功能，计划文档只展开已经进入当前实施阶段的功能。
3. 未进入计划的 P2、后续计划或尚未确认的扩展能力，不得出现在当前计划的阶段任务、详细交互、完成状态、测试和发布清单中。
4. 待验证的功能可以进入计划，但只能记录验证目标、判断条件和备用方案，不能把未经确认的 SDK/API 写成已确定实现。
5. 计划状态只代表实施计划的进度；功能是否完成，必须以需求文档中的目标环境验收为准。

计划与需求的关系如下：

需求功能
  ├─ 尚未排期：只保留在需求文档
  └─ 已进入当前计划：写入计划的任务、交互、实现和验证章节
                                      └─ 目标环境验收后回写完成状态

计划文档规范

文件位置和命名

计划文档统一放在 docs/plans/，文件名使用：

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

编号前缀使用计划编号 PLAN-FNOS-###，其中 FNOS-### 必须与对应需求编号一致；需求主题应与对应需求文档一致：

docs/requirements/FNOS-001-dsh-fnos-adaptation.md
docs/plans/PLAN-FNOS-001-dsh-fnos-adaptation.md

Frontmatter、标题和元信息

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

---
title: PLAN-FNOS-001 DSH 飞牛 NAS 适配
description: DeepSeek Harness 在飞牛 fnOS 中的应用和专用插件适配实施计划。
---

# PLAN-FNOS-001 DSH 飞牛 NAS 适配

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

字段	要求
计划编号	使用 PLAN-FNOS-###，与对应需求编号一一对应
计划日期	使用计划正式建立的日期，格式为 YYYY-MM-DD
对应需求	链接到完整需求文档
计划状态	使用 分阶段实施 或能反映当前实施阶段的状态

固定章节和内容要求

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

1. 计划目标：说明本次实施的结果、技术边界和明确不修改的上游范围。
2. 实现范围和边界：用模块表说明目录、入口和责任；标出应用、Host、Client、网关、文档和测试的边界。
3. 目标架构和数据流：使用流程图、文本图或时序描述请求从宿主到应用、插件和 API 的路径。
4. 分阶段任务：按需求中的 P0/P1 等优先级拆分具体任务，只列出已进入当前计划的阶段。
5. 详细交互：描述页面入口、状态、按钮、权限、成功/失败反馈和返回路径；用户流程必须可据此实现和验收。
6. 数据、权限和错误处理：说明持久化、敏感信息、权限边界、错误分类和重试策略。
7. 依赖、风险和决策：列出外部依赖、未确认事实、影响和处理方案。
8. 测试、打包和发布：列出插件、应用、文档、NAS 验证、升级和回滚要求。
9. 参考资料：列出实际使用的 SDK 包、官方 API、上游仓库和版本/契约依据。
10. 完成状态：只汇总当前计划中已列出的阶段，不添加未排期需求。
11. 变更记录：追加计划范围、实现方案、状态和验收条件的变化。

实现范围和责任边界

实现范围表至少包含以下信息：

模块	计划入口	实现责任
应用/FPK	目录或脚本	生命周期、网关、资源和权限
Host 插件	Host 入口	服务端权限、API、敏感信息和错误转换
Client 插件	Client 入口	页面注册、用户交互和状态展示
应用配置	manifest/config	最小 Scope、共享目录和宿主配置
网关	网关入口	页面、API、插件和 SSE 的访问路径
文档/测试	docs 或测试目录	验证、排查和发布检查

官方项目只作为契约、行为和兼容性参考时，必须明确“只参考、不修改、不提交上游补丁”。

分阶段任务和状态

每个阶段应包含：

• 阶段目标和当前状态。
• 按实现顺序排列的任务编号或条目。
• 涉及的代码入口、配置字段、SDK/API 和前置条件。
• 验收结果或待验证条件。
• 失败时的降级、备用方案和不实施边界。

计划中使用以下状态：

状态	使用条件
已完成	当前计划任务和目标环境验证均已完成
待完成	实现或本地验证已完成，但目标环境仍未验收
规划中	已进入计划，尚未完成实现
待验证	依赖 SDK、宿主、权限或 DSH seam 的事实确认

计划不使用“后续计划”作为阶段。尚未排期的内容应留在需求文档，待新计划建立后再加入。

详细交互规范

交互章节至少说明：

• 用户从哪个页面、菜单或卡片进入功能。
• 首次加载、空数据、加载中、成功、失败和无权限状态如何展示。
• 按钮和字段的准确文案、可用条件、提交时机和返回路径。
• 宿主内与独立浏览器环境的差异，以及 iframe、授权回调或同源网关要求。
• 操作是否立即生效，是否需要保存、取消、恢复或刷新。
• 删除、取消授权、覆盖数据等有风险操作的确认文案和数据保护边界。
• 成功后如何重新查询真实服务端状态，避免只更新本地假状态。

复杂交互使用流程图或代码块表达；简单交互使用编号步骤表达。交互标题应包含对应优先级和功能名称，例如 P1：授权目录管理用户交互流程。

参考资料规范

计划中实际调用的每个外部能力都必须有可访问的参考链接，并说明用途：

外部能力	必须记录
fnOS JS SDK	npm 包链接、使用的方法、宿主限制和官方调用文档
fnOS API/Scope	API 名称、Scope、调用端（Host/Client）和官方 API 文档
DSH 官方项目	对应 profile、插件或 seam 的源码/文档链接，以及是否修改上游
构建或发布工具	版本要求、命令或官方文档链接

参考资料应放在 参考资料 章节；关键 API 也可以在对应任务或交互步骤旁边就近链接。不能只写“参考官方文档”而不提供链接。

测试、发布和回滚规范

计划必须区分：

• 插件级 typecheck、单元测试和构建。
• 应用级 FPK 构建、安装、启动、网关、权限和资源验证。
• 目标 NAS 环境的真实功能验收，尤其是主题、授权、SSE 和宿主事件。
• 文档构建和内部链接检查。
• 升级对用户配置、数据、授权和旧版本兼容性的影响。
• 回滚时允许移除什么，明确禁止删除哪些用户数据。

只在本地浏览器或开发环境通过时，不能把涉及 NAS 的阶段标记为“已完成”。

变更记录

变更记录使用追加表格：

日期	变更
YYYY-MM-DD	简要说明范围、实现、状态或验收规则的变化。

不得通过删除既有任务、交互、风险或验收说明来隐藏计划变化；如果方案被否决，应保留决策结果和原因。