2026-08-21 SDD 模式维护转换报告

项目	结论
SDD 定义	本报告按 Specification-Driven Development（规格驱动开发）理解：先定义可验收规格，再制定计划、实现、验证并回写状态。
当前状态	第一阶段已落地。项目已具备 SDD 维护规范、规格检查、PR 模板和 PR 工作流；真实 NAS 证据和完整追踪闭环仍需持续补齐。
建议模式	采用轻量 SDD，不新建一套重复的 specs/ 目录；继续以 docs/requirements/ 作为需求规格，以 docs/plans/ 作为实施计划。
本次转换范围	维护流程、文档结构、追踪关系、验证证据、PR/CI 门禁；不改变 fnOS 应用运行时、FPK 格式或 DSH 插件业务逻辑。
评估基线	2026-08-22；已将最新 main（d6f55ad）合并到当前 SDD 分支后继续优化。

1. 当前盘点

已具备的 SDD 基础

• docs/requirements/index.md 已定义需求与计划边界、功能编号、优先级、状态和验收规则。
• docs/plans/index.md 已定义计划结构、实现范围、交互、风险、测试、发布和回滚要求。
• FNOS-001 需求 与 PLAN-FNOS-001 计划 已形成一对需求/计划文档。
• DSH 插件包已经提供 typecheck、test、build 和 check 脚本，插件侧具备较好的实现验证基础。
• 文档站已有 pnpm run build -- --docs，贡献指南已有 git diff --check 和文档构建要求。
• 面向用户的应用和插件文档已经确定统一维护在 docs/，减少 README 多处漂移。

转换前缺口

领域	当前情况	SDD 风险
维护制度	AGENTS.md 和贡献指南主要描述构建、文档和发布，没有明确“什么改动必须先有需求/计划”	新功能可能直接改代码，需求与实现再次分离
追踪关系	功能使用 FNOS-001-##，但验收条件、计划任务和测试没有统一的稳定 ID	无法快速回答某个功能由哪些代码、测试和环境证据覆盖
需求元数据	文档只有标题和描述，缺少负责人、更新时间、目标版本、验证环境等机器可读字段	难以自动生成状态看板和检查逾期验收
CI 门禁	CI 主要负责文档部署、FPK 构建和 Release，没有 PR 级 SDD 检查	规范只能靠人工遵守
根级校验	根 package.json 只有文档命令；插件有独立 check，没有统一的仓库级检查入口	不同类型改动的验证标准不一致
目标环境证据	FNOS-001 多项能力仍标记为待真实 NAS 验收，但没有统一的验收记录模板	“代码完成”容易被误认为“需求完成”
历史应用	现有多个应用没有对应需求规格	一次性回填成本高，也不应为了 SDD 阻塞日常维护
文档一致性	已规定 docs/ 为面向用户文档唯一入口，但 README 等历史文件仍存在	后续维护者可能误改非规范入口

合并 main 后的处理

• 保留 main 分支最新的 DSH 版本、fnOS 插件、工作区流程、输入引用和上下文文件访问实现。
• 解决文档导航和 SDD 转换报告的同名文件冲突，没有用旧分支内容覆盖 main 的实现说明。
• 在合并后的代码基线上继续补充 SDD 维护规范、追踪矩阵、验收记录入口和自动检查。

2. 转换后的目标工作流

提出变更
  ├─ 文档/依赖/发布类低风险变更：登记变更说明并直接校验
  └─ 行为/权限/交互/数据/架构变更：
       ├─ 更新或新增需求规格
       ├─ 评审范围、优先级和验收条件
       ├─ 建立实施计划和任务追踪
       ├─ 编码并补齐单元/契约/构建验证
       ├─ 在真实 fnOS NAS 完成目标环境验收
       ├─ 回写需求、计划和验收证据
       └─ 关联发布版本、回滚方式和变更记录

核心规则是：规格描述“做什么以及什么结果算完成”，计划描述“怎么做以及如何验证”，代码和测试不能替代规格，目标环境验收不能被本地构建结果替代。

3. 转换实施与剩余工作

已完成的第一阶段转换

• 新增 SDD 维护规范，明确需求、计划、实现、验证、发布和例外规则。
• 新增 tooling/fn-os-apps-cli/src/sdd/checker.ts，由 fn-apps-cli check --sdd 检查 SDD 文档结构、元信息、编号唯一性和内部链接。
• 新增统一 fn-apps-cli check 命令，支持交互选择或使用 --sdd、--docs、--packages、--plugins、--all 参数。
• 新增 PR 模板、sdd-check.yml 和 docs/validation/README.md。
• 为当前 FNOS-001 需求和计划补充 SDD 元数据，并在计划中加入 P0/P1 追踪矩阵。
• 修正插件检查顺序为 typecheck → build → test，使根级质量门禁可重复执行。

P0：统一维护规则

1. 已在 AGENTS.md 和 docs/guide/sdd-workflow.md 中明确全仓库 SDD 流程，并要求所有新功能、用户可见行为、权限、数据格式、网关和插件契约变更关联需求编号。

2. 采用以下变更分类，避免把所有小改动都强制写成完整需求：

   变更类型	必需产物
   新功能、用户行为、权限、数据或架构变化	需求规格 + 实施计划 + 验收条件
   现有功能行为修复	原需求变更记录 + 计划调整；影响较大时新增需求
   安全、依赖、构建或发布变更	变更说明 + 风险/回滚 + 对应校验
   仅文档、格式或内部重命名	变更说明 + 文档/静态校验

3. 明确规范入口：需求以 docs/requirements/ 为准，计划以 docs/plans/ 为准，应用和插件面向用户说明以 docs/ 为准；历史 README 不再作为规格来源。

4. 保留现有需求和计划的变更记录，不通过删除旧条目隐藏方案变化。

P0：补齐可追踪 ID

已在不改变现有 FNOS-001-## 编号的前提下定义以下 ID：

对象	示例	用途
需求功能	FNOS-001-10	用户可感知功能的稳定标识
验收条件	FNOS-001-10-AC-01	可观察的完成条件
计划任务	PLAN-FNOS-001-T10-01	实施步骤、代码入口和依赖
测试场景	FNOS-001-10-TEST-01	单元、契约、应用或 NAS 测试
环境证据	FNOS-001-10-ENV-01	目标 NAS、版本、用户和结果记录

每个 P0/P1 功能至少形成一条“需求功能 → 验收条件 → 计划任务 → 测试 → 环境证据”的链路。建议将追踪矩阵放在对应计划末尾，不额外复制一份完整需求正文。

P1：增加需求元数据和模板

当前 FNOS-001 需求和计划已在现有 title/description 基础上增加统一 frontmatter；后续新文档沿用该字段：

---
id: FNOS-001
title: FNOS-001 DSH 飞牛 NAS 适配
status: in-progress
owner: tnnevol
priority: mixed
targetVersion: 5.0.x
lastVerified: 2026-08-22
---

需求和计划继续使用现有规范；真实环境验收已有 docs/validation/ 入口。决策记录模板暂不单独建立，优先使用计划中的“依赖、风险和决策”章节。

P1：建立真实环境验收记录

已新增 docs/validation/ 及记录模板，每次真实 NAS 验收记录至少包含：

• fnOS 版本、设备架构、应用 FPK 版本、插件版本和 DSH 版本；
• 安装/升级方式、用户角色、授权目录和 npm 源等前置条件；
• 对应的 *-AC-* 验收条件、操作步骤、预期结果和实际结果；
• 日志、截图或失败复现信息；
• 结论、遗留问题、回滚方式和验收日期。

FNOS-001 当前“待真实 NAS 验收”的 P0/P1 项目应优先生成这类记录，完成后再回写需求和计划状态。

P1：增加 PR/CI 门禁

已新增 PR 级工作流和统一根级检查命令：

{
  "scripts": {
    "check": "pnpm exec fn-apps-cli check"
  }
}

交互式运行 pnpm run check 选择检查范围；自动化或 Agent 运行参数化命令，例如 pnpm run check -- --all、pnpm run check -- --sdd --docs 或 pnpm run check -- --plugins。

check --sdd 当前做低风险静态检查：

• 需求/计划 frontmatter、标题和编号格式；
• 需求与计划的一对一链接；
• 功能编号重复、验收编号重复和悬空引用；
• 计划不得展开未进入计划的 P2/后续功能；
• 变更记录存在且文档内部链接可构建。

PR 模板至少要求填写：变更类型、需求编号、计划编号、验收条件、测试命令、目标 NAS 验收状态、数据影响和回滚方式。

P2：处理历史应用，不做一次性大回填

• 不建议为所有历史应用重写完整需求历史；这会增加噪声并阻塞维护。
• 建立一个轻量的应用基线清单，记录应用负责人、当前版本、构建入口、目标平台、权限风险和最低验收项。
• 历史应用从下一次行为变更开始采用 SDD；仅版本升级、依赖升级或构建修复按对应变更分类登记。
• 新增应用必须从需求规格开始，不允许只提交应用目录和 FPK 配置而没有验收说明。

4. 当前项目的转换映射

目标 SDD 产物	当前文件/目录	结论
需求规范	docs/requirements/index.md、docs/requirements/FNOS-001-dsh-fnos-adaptation.md	已具备元数据、验收规则和功能编号
实施计划	docs/plans/index.md、docs/plans/PLAN-FNOS-001-dsh-fnos-adaptation.md	已具备元数据和 P0/P1 追踪矩阵
代码实现	plugins/*、apps/*	插件级验证和根级统一入口均已具备
用户文档	docs/apps/、docs/plugins/、docs/guide/	已规定 docs/ 为规范入口，需持续避免重复维护
验收证据	docs/validation/README.md	已有统一记录模板，真实 NAS 记录待补齐
变更门禁	.github/workflows/sdd-check.yml、docs/contributing.md	已有 PR 级 SDD、文档和插件检查
维护约束	AGENTS.md、docs/guide/sdd-workflow.md	已有 SDD 变更分类、必需产物和例外规则

5. 建议的目标目录

docs/
├── requirements/       # 正式需求规格
├── plans/              # 已进入实施的计划
├── validation/         # 真实 NAS/发布环境验收证据
├── decisions/          # 仅记录跨需求的架构决策，可选
└── guide/
    └── sdd-workflow.md # 批准后的长期维护规范

tooling/
└── fn-os-apps-cli/
    └── src/sdd/checker.ts # 规格、计划、编号和链接校验

.github/
├── pull_request_template.md
└── workflows/
    └── sdd-check.yml

当前不建议立即创建 specs/、design/、stories/ 等平行目录。它们会和现有 requirements/、plans/ 产生重复权威来源；只有当需求、计划和决策确实需要独立生命周期时，再引入 decisions/。

6. 分阶段落地计划

阶段	内容	完成标志
阶段 0：现状确认	已保留现有需求/计划体系，并在合并最新 main 后确认 SDD 适用范围	当前分支基于 d6f55ad，转换报告已更新
阶段 1：规则固化	已增加 SDD 工作流、模板、PR 模板和 FNOS-001 追踪 ID	新的 P0/P1 变更可按模板完整记录
阶段 2：自动门禁	已增加统一 check、参数化检查范围和 PR 工作流首版	本地完整检查可发现规格、链接和构建问题
阶段 3：验收闭环	已增加 docs/validation/ 模板，FNOS-001 的真实 NAS 证据待补齐并回写状态	P0/P1 具备可复核的环境验收记录
阶段 4：增量覆盖	历史应用按修改时机补齐基线和规格，新应用强制从规格开始	不阻塞旧应用，同时新改动不再脱离规格

7. 转换完成判定

项目已具备进入 SDD 维护模式的第一阶段条件；正式宣布完整闭环仍需满足：

1. 新增或修改用户可见行为时，PR 关联需求和实施计划。
2. 每个 P0/P1 功能都有验收 ID、测试 ID 和目标环境结论。
3. 需求、计划、代码、测试和验收记录之间不存在悬空引用。
4. PR 级检查能够自动发现文档格式、编号、链接和计划范围违规。
5. 真实 fnOS NAS 验收没有被本地构建或单元测试结果替代。
6. Release 前可以从版本号反查本次变更对应的需求、计划、验证证据和回滚方案。

8. 最终建议

本项目不需要推倒重建文档，也不需要先给所有历史应用补齐完整规格。当前分支已落地“现有 requirements/plans 体系 + 追踪矩阵 + 验收证据模板 + PR/CI 门禁”的轻量 SDD 方案。

后续优先工作是：

1. 为 FNOS-001 当前 P0/P1 功能补齐真实 NAS 验收记录，并回写需求与计划状态；
2. 在后续行为变更中持续维护需求、计划、测试和环境证据的追踪矩阵；
3. 按历史应用的实际改动时机增量补齐基线，不阻塞当前开发。

本报告记录本次转换和落地结果，不改变现有应用运行逻辑；当前 SDD 结构的剩余工作主要是目标 NAS 证据和历史应用的增量覆盖。