SDD 规格驱动维护规范

本仓库采用轻量 Specification-Driven Development（SDD）维护模式。需求规格是“做什么以及什么结果算完成”，实施计划是“怎么做以及如何验证”，代码和测试不能替代规格，目标环境验收不能被本地构建结果替代。

规范入口

内容	唯一维护入口
需求规格	`docs/requirements/`
实施计划	`docs/plans/`
真实环境验收证据	`docs/validation/`
应用和插件面向用户说明	`docs/` 下的应用/插件文档
跨需求架构决策	`docs/decisions/`，仅在计划中的决策章节不足以表达时使用

不新建与 requirements/、plans/ 重复的 specs/ 或 stories/ 目录。apps/*/README.md 和 plugins/*/README.md 保留作历史或兼容参考，不作为现行需求和面向用户文档的权威入口。

变更分类

变更类型	必需产物	最低验证
新功能、用户行为、权限、数据、网关或插件契约变化	需求规格 + 实施计划 + 验收条件	代码/测试 + 文档构建；涉及 fnOS 时必须真实 NAS 验收
现有功能行为修复	原需求变更记录 + 计划调整；影响较大时新增需求	回归测试和对应环境验证
安全、依赖、构建或发布变化	变更说明 + 风险/回滚 + 校验结果	受影响的构建、安装、升级或安全检查
仅文档、格式或内部重命名	变更说明	`git diff --check` 和 `pnpm run build -- --docs`

标准流程

text

提出变更
  ├─ 记录或新增需求规格
  ├─ 评审范围、优先级和验收条件
  ├─ 建立对应实施计划和任务追踪
  ├─ 编码并补齐测试/构建验证
  ├─ 在目标 fnOS NAS 完成功能验收
  ├─ 写入验收证据并回写需求/计划状态
  └─ 关联版本、变更记录和回滚方式

未进入计划的 P2、后续计划和未确认能力不得出现在当前计划的阶段任务、详细交互、完成状态或测试清单中。

追踪 ID

新增 P0/P1 功能建议形成以下链路：

对象	格式	示例
需求功能	`FNOS-###-##`	`FNOS-001-10`
验收条件	`<功能 ID>-AC-##`	`FNOS-001-10-AC-01`
计划任务	`PLAN-FNOS-###-T##-##`	`PLAN-FNOS-001-T10-01`
测试场景	`<功能 ID>-TEST-##`	`FNOS-001-10-TEST-01`
环境证据	`<功能 ID>-ENV-##`	`FNOS-001-10-ENV-01`

每个 P0/P1 功能至少要能从需求追踪到验收条件、计划任务、测试和目标环境结论。计划文档可以维护追踪矩阵，不复制需求正文。

状态规则

已完成：代码、必要构建和目标环境验收全部完成。
待完成：代码或本地验证完成，但目标环境尚未验收。
规划中：已进入计划，尚未完成实现。
待验证：依赖 SDK、宿主、权限的事实确认。
待确认：需求边界尚未确认，未进入计划。
后续计划：已登记但未进入当前计划。

状态变化必须追加到需求或计划的变更记录，不能只修改徽章。

路径约束

仓库内所有被跟踪文件禁止写入指向开发者本机的绝对路径。这类路径换一台机器或换一个 CI runner 就失效，且会把个人目录结构带进版本库。需要引用仓库内的文件时，改用相对路径或仓库别名。

禁止的形式包括：

用户主目录：/Users/<name>/...、/home/<name>/...，以及 ~ 展开后的绝对路径。
机器专属的工具安装位置：/opt/homebrew/...（Apple Silicon Homebrew）这类只在某台个人机器上成立的路径。
个人临时目录：/private/tmp/...、/var/folders/...。
Windows 盘符路径：C:\...、/mnt/c/...。

通用系统位置不受此限制。/usr/local/bin、/usr/bin、/etc/... 在 CI runner 和目标设备上语义稳定，CI 安装步骤、安装文档指引和 fnOS 设备端脚本可以继续使用。

替代写法：

场景	写法
引用仓库内文件	仓库根相对路径，例如 `tooling/fn-os-apps-cli/src/index.ts`
脚本内定位同目录文件	基于脚本位置推导，例如 `"$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"`
文档内页面互链	VitePress 路由别名，例如 `/development/sdd-workflow`
本机工具	依赖 `PATH` 解析（配置项留空或写工具名），不要写死安装目录

例外：fnOS 部署契约要求的设备端路径不是本机路径，允许保留。典型是生命周期脚本中的 TRIM_* 变量，以及官方运行时文档规定的跨应用运行时引用（例如 install_dep_apps = python312 之后在 cmd/install_callback 中设置 /var/apps/python312/target/bin）。这类路径指向目标 NAS，在开发机上本来就不存在，写绝对路径是契约要求。使用时应在注释中说明它指向 fnOS 设备环境，避免被误认为本机路径。

PR 检查清单

[ ] 已填写变更类型、需求编号和计划编号；纯文档/格式变更已说明豁免原因。
[ ] 新增或修改的用户行为有可观察的验收条件。
[ ] 计划只包含已进入实施阶段的功能。
[ ] 已运行与改动相关的插件测试、构建、pnpm run check -- --sdd 和 pnpm run build -- --docs。
[ ] 涉及 fnOS 权限、宿主、FPK 安装或升级的功能已记录真实 NAS 验收状态。
[ ] 已说明数据影响、敏感信息、升级兼容和回滚方式。
[ ] 需求、计划和验证记录中的链接与追踪 ID有效。
[ ] 改动中没有开发者本机绝对路径；设备端路径已注明指向 fnOS 环境。

例外规则

依赖升级、构建修复和紧急安全修复可以不新增完整用户需求，但必须在 PR 和变更记录中说明原因、影响、验证和回滚方式。紧急修复完成后，应在下一个维护周期补齐受到影响的需求或决策记录。

SDD 规格驱动维护规范 ​

规范入口 ​

变更分类 ​

标准流程 ​

追踪 ID ​

状态规则 ​

路径约束 ​

PR 检查清单 ​

例外规则 ​