PLAN-FNOS-007 DSH 0.1.7-rc.2 适配与插件错误修复
| 字段 | 内容 |
|---|---|
| 计划编号 | PLAN-FNOS-007 |
| 计划日期 | 2026-09-24 |
| 对应需求 | FNOS-007 DSH 0.1.7-rc.2 适配与插件错误修复 |
| 本轮功能 | FNOS-007-01 至 FNOS-007-15、FNOS-007-19；全部已验收完成，FNOS-007-15 已废弃（归口 FNOS-007-19） |
| 上游依据 | 本地 Harness checkout 的 dsh-v0.1.7-rc.2，以目标 tag 的源码、类型和构建结果为准 |
| 计划状态 | 已完成 |
计划目标
本计划把应用和四个 DSH 插件从 0.1.5-rc.2 兼容基线迁移到 0.1.7-rc.2，并保证 FNOS-007 中定义的用户功能、用户数据和真实环境验收条件成立。
计划只负责实现和验证需求中的功能，不重新定义 FNOS-007 的功能范围。用户结果和验收条件以需求文档为准。
实施分期
| 阶段 | 对应功能 | 内容 | 状态 |
|---|---|---|---|
| 第一期 | FNOS-007-11 | 文档站 Mermaid 渲染器替换和图表交互验收 | 已完成 |
| 第二期 | FNOS-007-01 至 10、12、13、14 | 依赖基线、插件接缝、FPK、会话、升级、attachment-local、dshmarket 和 workflow 验收 | 已完成 |
| 第三期 | FNOS-007-19 | 应用专用账号下的终端可用性适配。原定由 FNOS-007-15/T11 承担，该条已废弃，归口本条 | 已完成 |
分期原因：插件源码接缝、FPK 运行时和本地开发宿主需要统一到同一目标基线，先完成差异分析，再同步切换运行时与开发工具链。
当前实现与目标设计
| 领域 | 当前实现 | 目标实现 | 影响 |
|---|---|---|---|
| DSH 运行时 | 0.1.5-rc.2 | 0.1.7-rc.2 | catalog、lockfile、安装回调、构建常量和 FPK 运行时 |
| FPK native | node-pty@1.2.0-beta.15、Node.js 24、node-gyp@11.0.0 | node-pty 版本保持不变，按目标 DSH 基线重新生成并验证 native 产物 | native 配置、锁文件、pty.node、spawn-helper、版本清单和安装回调必须一致 |
| 插件门禁 | 旧版本 peer 可被接受 | 新版本 peer 通过安装和启动门禁 | 四个插件的 peer 和兼容性声明 |
| Host 设置 | 旧设置服务读写 | 新设置描述、更新和版本校验 | dsh-fnos Host、配置迁移和失败回滚 |
| Client 设置 | 旧设置作用域 | 新配置表单 | 主题、授权目录卡片和输入引用 |
| LLM 消息 | 工具结果作为旧内容块处理 | 按角色处理工具结果 | CodeBuddy 多轮工具调用和图片输入 |
| 图片请求 | 旧图片策略和字段 | 新图片目标和尺寸字段 | CodeBuddy、Codex Auth 图片能力 |
| 会话 | 旧格式假设 | 兼容新格式读取 | 旧会话打开和导出，不实现自有迁移器 |
| 网关挂载 | 旧版根路径资源和认证转发 | 文档目录相对路径、入口跳转和挂载 Cookie 隔离 | fnOS iframe 下的静态资源、API、WebSocket 与认证边界 |
| 文档图表 | 构建期 Mermaid 插件 | 客户端 vitepress-mermaid-renderer | 依赖链、主题、工具栏和可访问性 |
| 终端 Shell | 默认 Shell 取宿主账号登录 Shell；应用专用账号的登录 Shell 为 /usr/sbin/nologin，终端启动即退出 | 应用为终端进程提供可用的交互式 Shell 默认值 | 应用启动脚本的环境导出；不影响终端运行身份和 fnOS 权限模型 |
既有功能状态变更
mermaid
stateDiagram-v2
[*] --> Legacy: 0.1.5-rc.2 可用
Legacy --> Baseline: 变更点：切换 FPK 运行基线
Baseline --> SeamMigration: 变更点：迁移插件设置、消息、图片和 UI 接缝
SeamMigration --> Compatible: 变更点：插件安装和启动门禁通过
Compatible --> Verified: 变更点：真实 NAS 升级和回滚验收通过
Verified --> [*]状态图中的变更点对应 FNOS-007-01、02、03、04、05、07 和 10；不修改已完成需求的历史状态，所有新结论回写当前 FNOS-007。
升级和交互时序
mermaid
sequenceDiagram
participant User as 用户
participant App as fnOS 应用
participant Gate as 兼容性门禁
participant Plugin as DSH 插件
participant Store as 用户数据
User->>App: 发起安装或升级
App->>Store: 保留 profile、凭据、设置、会话和工作区
Note over App,Gate: 变更点：运行时和插件 peer 升级到 0.1.7-rc.2
App->>Gate: 校验插件兼容性
Gate-->>App: 接受安装并允许启动
App->>Plugin: 启动插件并恢复交互
Plugin->>Store: 读取旧设置和用户数据
Store-->>Plugin: 返回可兼容数据
Plugin-->>User: 保持原有功能结果影响范围分析
| 需求功能 | 源码和配置 | 用户数据/运行时 | 测试和证据 | 目标环境 |
|---|---|---|---|---|
| FNOS-007-01 | pnpm-workspace.yamllockfile DSH 运行时与构建 CLI | 应用运行基线 | 干净 profile 安装 启动与升级 | DSH Web 真实 NAS |
| FNOS-007-02 | 插件 package/compatibility 配置 构建 CLI | 四个插件的安装门禁 | peer 兼容性断言 干净 profile 安装 | dsh-fnos：DSH Web 与真实 NAS其他插件：DSH Web 与 Desktop |
| FNOS-007-03 | dsh-fnos Host/Client设置卡片 | 主题 授权目录 代理路径 设置 profile | 设置读写 升级前后 profile 对照 | DSH Web 真实 NAS |
| FNOS-007-09 | 设置入口 图标和输入契约 | 设置卡片 会话入口和模型图标 | 配置/入口显示与交互回归 | DSH Web/Desktop fnOS 设置卡片另在真实 NAS 验收 |
| FNOS-007-04、05 | CodeBuddy/Codex Auth serializer 图片请求和凭据模块 | 工具结果 图片内容 凭据 模型目录 | 工具调用 图片 登录 用量和配置回归 | DSH Web 与 Desktop 登录另需真实网络/账号 |
| FNOS-007-06 | Semi UI 共享包和总览插件 | 组件 主题和卸载状态 | 构建 渲染 主题和卸载测试 | DSH Web 与 Desktop |
| FNOS-007-07、08、10 | FPK manifest 生命周期 网关 native 会话读取边界 | FPK 运行时 旧会话 网关和插件归档 | FPK 构建/安装 旧会话导出 升级与回滚 | 真实 NAS 客户端功能另在 DSH Web 验收 |
| FNOS-007-12 | dshmarket 安装清单与版本收敛 | 已安装插件版本 | 缺失 版本不一致和同版本场景回归 | DSH Web 与 Desktop，不要求 NAS 插件验收 |
| FNOS-007-13 | attachment-local 安装解析与持久化补丁 | FPK 运行时和附件持久化目录 | 依赖解析 补丁幂等和附件可用性 | 真实 NAS（应用运行时验收） |
| FNOS-007-11 | docs/package.jsonVitePress config/theme | 文档图表渲染方式 | 全部 Mermaid 图表和文档构建 | 浏览器 文档构建 |
原设想为 apps/fn-deepseek-harness/cmd/main 的环境导出段实际改由网关 buildDshRuntimeEnv() 注入 | 终端进程默认 Shell 终端继承环境 | 网关环境回归 终端打开和命令执行回归 | 真实 NAS |
源文件与生成产物边界
apps/fn-deepseek-harness/app/ 下的网关 bundle、native 依赖、插件归档和版本文件属于生成产物，不能直接编辑。它们由以下源码和流程生成：
| 生成产物 | 唯一来源 |
|---|---|
app/gateway-proxy.mjs、app/rolldown-runtime-*.mjs | packages/fnos-gateway/src/ 与 tsdown.app.config.ts |
app/scripts/install-callback-helper.mjs | packages/fnos-gateway/src/install-callback-helper/ |
app/bundled-dsh-plugins/*.tgz | 构建 CLI 对 plugins/* 执行打包 |
app/native/、app/dsh-version、app/node-pty-version* | native 准备脚本和 FPK 构建流程 |
手写源文件包括 manifest、cmd/*、config/*、wizard/*、app/ui/config 和 app/published-dsh-plugins.json。
技术迁移设计
T02：fnOS 设置和交互接缝
| 变更点 | 原实现 | 目标实现 | 保持的用户行为 |
|---|---|---|---|
| Host 设置读写 | 旧设置注册、读取和监听 | 新设置描述、更新和版本校验 | 主题、授权目录、代理路径继续读写 |
| Client 设置 | 旧设置作用域 | 新配置表单 | 设置卡片、主题优先级和保存反馈不变 |
| 设置卡片 | 旧设置插槽 | 新插件设置插槽 | 卡片仍可见，/fn 和引用插入不变 |
| 图标 | 数字后缀图标 | Regular/Medium 图标 | 视觉尺寸和位置不变 |
mermaid
sequenceDiagram
participant User as 用户
participant Client as 设置页面
participant Host as 插件 Host
participant Config as 用户配置
User->>Client: 修改设置
Note over Client,Host: 变更点：旧设置作用域改为新配置表单
Client->>Host: 提交设置变更
Host->>Config: 保留原子写入和版本校验
Config-->>Host: 成功或冲突
Host-->>Client: 返回保存结果
Client-->>User: 显示成功、冲突或错误反馈T03：LLM、附件和凭据接缝
- CodeBuddy 工具结果从旧内容块处理迁移为按消息角色处理，保留调用 ID、错误标记、推理和文本序列化。
- 图片请求使用新目标字段，模型不支持图片时返回明确的原有错误语义。
- Codex Auth 保留凭据、模型目录、用量窗口和图片能力判定，不覆盖已有配置。
T05/T08：FPK、网关和会话
- FPK 运行时、开发宿主顶层 DSH CLI 和本地
.dshprofile 统一对齐到0.1.7-rc.2；不再保留开发宿主与 FPK 的版本分叉。 attachment-patch只修改packages/fnos-gateway/src/的源码，锚点必须匹配一次，补丁必须幂等，路径必须位于应用私有目录。- 旧会话只做读取和导出验证，不实现本仓库自己的格式迁移器，不改写用户会话文件。
T07：文档站 Mermaid 渲染器
- 在客户端主题
Layout中初始化 renderer，保持 SSR 空操作。 - 使用
securityLevel: 'strict'，监听明暗主题并重新渲染已挂载图表。 - 桌面、移动和全屏工具栏统一配置中文文案、缩放、重置、复制、下载和 dialog 全屏。
- 所有流程、关系、状态和时序图使用
mermaidfenced code block，不使用 ASCII 图。
T09：dshmarket
- 发布清单、构建校验常量和用户文档当前值统一到
1.65.1。 plugins与bundled/dshmarket的 registry 安装统一使用wizard_npm_registry写入的.npmrc；未配置时使用 npm 官方源。缺失时安装清单版本，版本不一致时升级或降级，同版本时跳过并保留配置。
T11：应用专用账号下的终端可用性
对应需求 FNOS-007-15。
当前实现与目标实现
| 领域 | 当前实现 | 目标实现 | 迁移影响 |
|---|---|---|---|
| 终端默认 Shell | DSH 侧默认 Shell 解析顺序为进程环境变量 SHELL，其次宿主账号登录 Shell。应用启动脚本未导出 SHELL，于是取到应用专用账号的登录 Shell /usr/sbin/nologin，终端进程启动后立即退出并打印账号不可用提示 | 应用启动脚本为 DSH 服务进程导出可用的交互式 Shell，使终端默认 Shell 解析到 /bin/bash | cmd/main 的环境导出段；不改变终端运行身份，不涉及 config/privilege、config/resource、manifest 或 config 入口字段 |
| 终端环境变量 | 侧边栏终端以 DSH 服务进程环境为底，其中 HOME 被应用启动脚本覆盖为应用共享目录；DSH_* 命名空间在向子进程传递时统一剥离，因此终端内没有 DSH_HOME | 保持 HOME 语义不变；是否向终端补充 DSH_HOME 由本任务一并决定并在用户文档中说明 | 只在明确需要用户终端直接调用 dsh CLI 时补充；模型侧工具不依赖该变量 |
| 终端面板可见性 | 侧边栏终端随 Web 应用无条件挂载，入口存在但打开即失败 | 入口存在且打开即可用 | 不引入开关，不改变入口形态 |
变更原因与用户可观察结果
DSH 0.1.7-rc.2 新增了面向用户的侧边栏终端。该终端按“进程环境变量 SHELL → 宿主账号登录 Shell”的顺序解析默认 Shell。fnOS 应用以专用应用账号运行，该账号在系统中不可登录（登录 Shell 为 /usr/sbin/nologin），且应用启动脚本只导出了 PATH、DSH_HOME、HOME 和 npm 相关变量，从未导出 SHELL。因此终端会以不可登录的 Shell 启动，进程立即退出，用户在终端面板只看到一行账号不可用提示。
mermaid
stateDiagram-v2
[*] --> Mounted: 终端入口已挂载
Mounted --> Spawning: 用户打开终端
Spawning --> Unusable: 变更点：默认 Shell 解析到不可登录账号
Unusable --> [*]: 用户看到账号不可用提示
Spawning --> Usable: 变更点：应用导出可用交互式 Shell
Usable --> Running: Shell 进入交互状态
Running --> Closed: 用户关闭终端
Closed --> [*]图中的 变更点： 表示本任务改变的两处状态转换：原约定下打开终端直接落到不可用状态；新约定下打开终端进入可用状态。终端的挂载方式、入口形态和运行身份均不改变。
mermaid
sequenceDiagram
participant User as 用户
participant Client as 终端面板
participant Host as DSH 服务
participant App as 应用启动脚本
participant Shell as 终端进程
App->>Host: 原约定：只导出 PATH、DSH_HOME、HOME 和 npm 变量
User->>Client: 打开终端
Client->>Host: 请求终端环境
Note over Host,Shell: 变更点：默认 Shell 来自应用账号登录 Shell，无法交互
Host->>Shell: 以不可登录 Shell 启动终端
Shell-->>Client: 进程立即退出
Client-->>User: 显示账号不可用提示
Note over App,Shell: 变更点：应用为终端导出可用交互式 Shell
App->>Host: 新约定：额外导出 SHELL
User->>Client: 再次打开终端
Client->>Host: 请求终端环境
Host->>Shell: 以可用交互式 Shell 启动终端
Shell-->>Client: 返回可交互终端
Client-->>User: 可以执行命令变更原因：宿主的应用账号模型与通用 Linux 交互式账号不同，上游默认值在该环境下不可用。用户可观察结果是：修复前打开终端得到账号不可用提示；修复后打开终端直接得到可交互 Shell，且 id 显示的身份仍是应用账号，不会提升为 root 或切换为 NAS 普通用户。
环境变量一致性事实
供实施和验证依据，避免把差异当成缺陷：
| 变量 | 侧边栏终端 | 模型侧命令工具 | 说明 |
|---|---|---|---|
| 运行身份 | 应用账号 | 应用账号 | 两条通路都不做身份切换 |
HOME | 应用启动脚本覆盖后的值 | 同左 | 由 cmd/main 的 HOME 导出决定，与账号登录目录不同 |
SHELL | 未导出即为不可登录值 | 不读取该变量 | 本任务补齐 |
DSH_HOME | 未设置 | 由模型侧环境注入机制提供 | DSH_* 命名空间在向子进程传递时被统一剥离，故终端内不继承 |
| 沙箱 | 不施加沙箱约束 | 受会话沙箱模式约束 | 由上游产品设计决定，本任务不改变 |
影响范围
| 需求功能 | 源码和配置 | 用户数据/运行时 | 测试和证据 | 目标环境 |
|---|---|---|---|---|
| FNOS-007-15 | apps/fn-deepseek-harness/cmd/main 的环境导出段；如需向用户说明则同步 docs/ 对应说明页 | 终端进程默认 Shell、终端继承环境 | 启动脚本环境断言、终端打开与命令执行回归 | 真实 NAS |
设计决策
| 决策项 | 选择 | 被否决方案 | 原因 |
|---|---|---|---|
| 默认 Shell 的修复位置 | 在应用启动脚本导出 SHELL | 修改 DSH 上游默认 Shell 解析逻辑 | 仓库约束不修改 DSH 官方源码；上游已提供环境变量接缝 |
| 备选实现 | 需要时在 DSH profile 的补丁层为终端控制器配置显式 Shell 配置字段 | 直接把应用账号的登录 Shell 改成可用 Shell | 修改系统账号属于宿主级变更，会影响应用账号的安全语义，且超出应用交付边界 |
| 模型侧六个终端工具是否纳入 | 不纳入 | 一并交付终端工具 | 该能力未随 npm 发行包提供，当前基线无法通过配置开启；如需提供须由上游发布或另行交付包 |
任务
T11 的四个任务已全部作废（2026-09-30）：其对应的需求 FNOS-007-15 已被认定为对终端问题的错误理解，终端实施与验收归口 T15 / FNOS-007-19。下表保留原任务供追溯，不再执行：
| 任务 ID | 原对应验收 | 原修改内容 | 处置 |
|---|---|---|---|
| FNOS-007-15-AC-01、02 | 在 cmd/main 补可用交互式 Shell | 作废：注入点改到网关，由 PLAN-FNOS-007-T15-01 实施（并明确删除 cmd/main 中的重复解析） | |
| FNOS-007-15-AC-03 | 断言终端运行身份不提升、不切换用户 | 转入 PLAN-FNOS-007-T15-03（对应并入的 FNOS-007-19-AC-04） | |
| FNOS-007-15-AC-04、05 | 核对环境变量并决定是否补 DSH_HOME | 作废：环境变量由 T15-01/T15-02 覆盖，HOME/DSH_HOME 边界由 T17 承担 | |
| FNOS-007-15-AC-05 | 真实 NAS 记录终端证据 | 转入 PLAN-FNOS-007-T15-04（FNOS-007-19-AC-05） |
风险与回滚
| 风险/事实 | 影响 | 决策和验证 |
|---|---|---|
| 应用账号登录 Shell 在未来 fnOS 版本变化 | 终端默认 Shell 可能再次不可用 | 以环境变量显式导出，不依赖账号登录 Shell，降低对宿主实现变化的敏感度 |
向终端补充 DSH_HOME 可能改变用户既有脚本行为 | 用户脚本读取到此前不存在的变量 | 仅在确认需要用户终端直接调用 CLI 时补充，并在说明页写明显式差异 |
| 环境导出变更影响其它子进程 | 依赖旧 SHELL 值的脚本行为变化 | 导出值是标准交互式 Shell，属于通用兼容值；通过应用启动和终端回归验证 |
| 回滚 | — | 移除新增导出行即可回到原行为；不涉及数据、凭据、会话或授权目录变更 |
说明
- 侧边栏终端不施加会话沙箱约束、模型侧命令工具受会话沙箱约束，这一差异由上游产品设计决定，本任务不改变，仅在说明页中如实描述。
- 模型侧终端工具相关能力因发行包缺失不在本任务范围；需求 FNOS-007-15 只覆盖用户可见的侧边栏终端可用性。
分阶段任务
T01：建立版本基线和插件门禁
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T01-01 | FNOS-007-01-AC-01、02 | 以目标 tag、lockfile 和依赖树确认 0.1.7-rc.2 基线，区分 FPK 通路和开发宿主通路 | 安装、锁文件和版本来源可审计 |
| PLAN-FNOS-007-T01-02 | FNOS-007-01-AC-03、FNOS-007-07-AC-01 | 清理当前基线的运行时引用，更新构建常量、native 输入、安装回调和文档当前值，保留历史记录 | 当前文件不再引用旧基线作为交付值，历史文档不改 |
| PLAN-FNOS-007-T01-03 | FNOS-007-02-AC-01 | 更新四个插件 peer、兼容性声明和实际依赖包集合 | 兼容性测试覆盖所有 DSH peer |
| PLAN-FNOS-007-T01-04 | FNOS-007-02-AC-02、03 | 在干净 profile 安装并启动四个插件，确认没有禁用日志或版本豁免依赖 | 四个插件安装成功并保持启用 |
T02：迁移 fnOS 设置、插槽和图标
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T02-01 | FNOS-007-03-AC-01 至 04 | 迁移 Host 设置读写、主题偏好、代理路径原子写入和失败回滚 | 类型检查、设置单测、旧 profile 对照 |
| PLAN-FNOS-007-T02-02 | FNOS-007-03-AC-01、02 | 迁移 Client 配置表单和输入契约，保留主题优先级、授权目录和引用插入行为 | Client 构建、交互测试 |
| PLAN-FNOS-007-T02-03 | FNOS-007-09-AC-01、03 | 将设置卡片迁移到新插槽，复核输入触发器、远程服务和 /fn 交互 | 卡片可见、引用插入无回归 |
| PLAN-FNOS-007-T02-04 | FNOS-007-09-AC-02 | 将移除的数字后缀图标替换为目标基线的 Regular/Medium 图标 | 图标导出、渲染和尺寸检查 |
T03：迁移 LLM、图片和 Codex 接缝
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T03-01 | FNOS-007-04-AC-01、02 | 将 CodeBuddy 工具结果序列化迁移到角色消息，保留调用 ID、错误标记和多轮配对 | 工具调用回归和真实请求 |
| PLAN-FNOS-007-T03-02 | FNOS-007-04-AC-03、04 | 将图片请求策略迁移到新目标字段，保留不支持图片时的明确错误 | 图片支持/拒绝测试 |
| PLAN-FNOS-007-T03-03 | FNOS-007-05-AC-01 至 04 | 核对 Codex Auth 的登录、凭据、模型、用量和图片能力接缝 | 类型检查、单元测试和配置保留测试 |
T04：迁移共享 UI 和总览插件
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T04-01 | FNOS-007-06-AC-01、03 | 核对共享 UI、插槽、renderer 和主题导出，修正目标基线下的导入 | typecheck、build、test |
| PLAN-FNOS-007-T04-02 | FNOS-007-06-AC-02、03 | 在新客户端验证总览页面、主题切换、卸载和重复注册 | 客户端交互验证 |
T05/T08：FPK、网关、会话和 native
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T05-01 | FNOS-007-07-AC-01、02 | 更新 FPK 构建常量、native 配置、CI 输入、安装回调和发布清单 | 插件和 FPK 构建 |
| PLAN-FNOS-007-T05-02 | FNOS-007-07-AC-04 | 建立版本、锁文件、native、清单和捆绑包元数据的一致性门禁 | 不一致时构建失败 |
| PLAN-FNOS-007-T05-03 | FNOS-007-07-AC-03 | 在真实 NAS 安装新 FPK，验证运行时版本、网关和 DSH Web | NAS 安装启动证据 |
| PLAN-FNOS-007-T05-04 | FNOS-007-08-AC-01 至 03 | 使用旧会话验证打开和导出，确认插件不实现自有迁移器 | 会话回归和文件不变断言 |
| PLAN-FNOS-007-T05-05 | FNOS-007-07-AC-02、07、08 | 核对目标 dsh-v0.1.7-rc.2 checkout 与本仓库锁文件仍使用 node-pty@1.2.0-beta.15、Node.js 24 和 node-gyp@11.0.0；更新 native 配置中的 DSH 基线和文件名后，在 Linux 构建机重新执行 prepare-dsh-native.sh，验证 pty.node、可选 spawn-helper、app/node-pty-versions 与安装回调版本校验一致 | 内置 native 且 NAS 无 g++ 的安装路径通过；未内置 native 且 NAS 有 g++ 的回退路径通过；版本不一致时构建或安装明确失败 |
| PLAN-FNOS-007-T05-06 | FNOS-007-07-AC-09 | 对齐官方 0.1.7-rc.2 的文档目录相对路径挂载契约：入口 ./ 跳转、静态资源/API/WebSocket 前缀和 Set-Cookie: Path=/ 的应用目录收窄 | 网关请求头、响应头、路径重写和真实挂载回归测试 |
| PLAN-FNOS-007-T08-01 | FNOS-007-07-AC-02 | 修复附件补丁锚点，验证三处锚点单次匹配、幂等和应用私有路径 | 目标包样本、失败锚点和回归测试 |
| PLAN-FNOS-007-T08-02 | FNOS-007-07-AC-02 | 确认新增图片依赖的 FPK 就位方式和 native 处理边界 | 目标架构图片处理可用 |
| PLAN-FNOS-007-T08-03 | FNOS-007-07-AC-05、06；FNOS-007-13-AC-01、02 | 复现日志中的生产安装路径，确认目标 DSH 的 dsh-base 生产依赖把 @deepseek-ai/dsh-attachment-local 放在应用私有依赖树的嵌套目录；把安装回调从固定顶层路径改为受边界约束的依赖树解析，再执行包名/版本校验和 TRIM_PKGVAR 补丁 | 干净安装中嵌套包可解析；不再出现缺少 attachment-local 的误报；版本不一致时明确失败 |
| PLAN-FNOS-007-T08-04 | FNOS-007-13-AC-03、04 | 验证 attachment-local 的 sharp 等生产依赖在目标架构可安装，补丁对附件根目录、共享缓存和耐久边界生效且重复执行幂等 | 自动化补丁测试、生产依赖安装测试和失败回滚证据 |
| PLAN-FNOS-007-T08-05 | FNOS-007-10-AC-01、03、05；FNOS-007-13-AC-03 | 在真实 NAS 验证新装、升级失败恢复和重复执行：应用私有 DSH 运行时包含 attachment-local，附件功能可用，用户数据和旧运行时可恢复 | NAS 新装/升级/失败回滚证据；不修改已完成需求/计划 |
T06：升级、回滚和目标环境验收
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T06-01 | FNOS-007-10-AC-01、02 | 在 NAS 验证应用 profile、fnOS 授权目录、工作区和旧会话保留；在 DSH Web/Desktop 验证 CodeBuddy/Codex Auth 的插件设置与凭据保留，确认各自重复执行幂等 | NAS、Web/Desktop 分别做升级前后数据对照，证据按宿主登记 |
| PLAN-FNOS-007-T06-02 | FNOS-007-10-AC-03 | 注入安装/升级失败，确认旧运行时和配置可恢复 | 回滚后应用可启动 |
| PLAN-FNOS-007-T06-03 | FNOS-007-10-AC-04 | 执行插件、包、FPK、文档和 SDD 门禁 | 全量检查和文档构建 |
| PLAN-FNOS-007-T06-04 | FNOS-007-10-AC-04 | 在真实 NAS 记录应用安装/升级/启动、网关和 fnOS 插件设置证据；CodeBuddy、Codex Auth 与共享 UI 的插件验收分别记录 DSH Web/Desktop 证据 | docs/validation/ 记录可追溯，按插件/宿主分别登记 |
T07：文档站 Mermaid 渲染器（已完成）
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T07-01 | FNOS-007-11-AC-01、04 | 用 vitepress-mermaid-renderer 替换旧构建期插件，清理旧依赖链 | pnpm install 和依赖检查 |
| PLAN-FNOS-007-T07-02 | FNOS-007-11-AC-01 | 在客户端主题挂载 renderer，保持 SSR 空操作和严格安全级别 | VitePress 构建和浏览器渲染 |
| PLAN-FNOS-007-T07-03 | FNOS-007-11-AC-02、03 | 配置桌面、移动、全屏工具栏、中文文案和主题变化重渲染 | 21 个 Mermaid 图表和四种视口验证 |
| PLAN-FNOS-007-T07-04 | FNOS-007-11-AC-01 | 验证图表渲染失败时保留可读错误区域，不影响其它文档内容 | DOM 和可访问性检查 |
T09：dshmarket 精确版本
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T09-01 | FNOS-007-12-AC-01 至 03、05 | 同步发布清单、构建常量和文档当前值到 1.65.1，并确认所有 registry 安装都读取同一份 .npmrc，默认使用 npm 官方源 | 构建校验、源配置和版本一致性检查 |
| PLAN-FNOS-007-T09-02 | FNOS-007-12-AC-04 | 按普通 plugins 规则处理 dshmarket：缺失安装、版本不一致升级/降级、同版本幂等保留 | 自动化 shell 回归及 DSH Web/Desktop 插件验收；FPK 安装回调的 NAS 验收归入 FNOS-007-29/T25 |
T10：FPK 构建 workflow 命名
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T10-01 | FNOS-007-14-AC-01 至 03 | 将可复用 FPK workflow 从 build-dsh-fn.yml 重命名为 build-app.yml，同步 build-release.yml、当前 CI 文档和 Mermaid workflow 图；不改变 workflow_call 输入、native 准备、FPK 构建、产物命名和上传步骤 | 旧文件名无现行引用；YAML 结构和调用路径一致；workflow 文件 diff 只包含命名及引用变更 |
T12：本地 DSH Web 启动状态与 catalog 一致性
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T12-01 | FNOS-007-16-AC-01、02 | 在链接本地插件并启动 Turbo watch 前，递归检查仓库 node_modules、.dsh/profiles 和 .pnpm-store/v11/projects，只移除目标不存在的悬空软链接；插件链接完成后再执行一次，覆盖 dsh CLI 对 hoisted links 的修改 | 本地悬空 .bin、旧 CLI 和临时项目链接夹具；pnpm start -- --web 的 watcher 不再因 walkdir 报错退出 |
| PLAN-FNOS-007-T12-02 | FNOS-007-16-AC-03、04 | 从 pnpm-workspace.yaml 读取 default/named catalog 包名，对所有 workspace manifest 的依赖字段实施 catalog 协议门禁；保留既有 DSH peer 精确版本兼容契约，并单独校验 @earendil-works/pi-ai 使用 catalog: | CLI 构建门禁、FNOS-007 baseline 测试、四插件 manifest 扫描和 git diff --check |
T13：插件未使用 DSH 依赖清理
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T13-01 | FNOS-007-17-AC-01、02 | 审计三个非 fnOS 插件的源码导入、生成声明、dsh.client.inject 和宿主 inject 服务；从 Codex Auth 移除未直接使用的 5 个 DSH 包 | peer/compatibility 对照测试；未使用包清单为空 |
| PLAN-FNOS-007-T13-02 | FNOS-007-17-AC-03、04 | 保留宿主共享 DSH 能力为 peer，不把它们转换为 dependencies；同步 Codex package.json、compatibility.json 和 devDependencies | 三插件 typecheck、unit test、build、profile 安装和 git diff --check |
T14：网关 DSH 浏览器认证 Cookie
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T14-01 | FNOS-007-18-AC-01、02 | 移除 response-headers 对 DSH 根 Cookie 的 Path 改写，保留 DSH BrowserAuth 生成的 Path=/，使挂载前缀下的 API、WebSocket 和设置接口继续携带会话 | response-header 回归测试；gateway API/WS 认证测试；真实 NAS 检查 Set-Cookie 与 API 请求 Cookie |
| PLAN-FNOS-007-T14-02 | FNOS-007-18-AC-03 | 保持 Location、HTML、CSS、JavaScript 和 WebSocket 路径改写逻辑不变，并重新生成 gateway app 产物 | gateway middleware 测试、FPK 构建输入一致性和 NAS 页面回归 |
T15：网关终端 Shell 与字符集环境
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T15-01 | FNOS-007-19-AC-01、02 | 在 buildDshRuntimeEnv() 中按 DSH resolveExecutable() 的 PATH 规则选择第一个可执行 bash，设置 SHELL；删除 cmd/main 中重复的 Shell 解析，避免 preferred shell 与候选 bash 产生两个条目 | dsh-runtime-env 测试、CLI baseline、真实 NAS 终端菜单检查 |
| PLAN-FNOS-007-T15-02 | FNOS-007-19-AC-03 | 在网关环境构造阶段检测本机 locale，注入可用 UTF-8 LANG/LC_CTYPE 并清理非 UTF-8 LC_ALL | gateway typecheck/test、非 ASCII 工作目录和终端输出回归 |
| PLAN-FNOS-007-T15-03 | FNOS-007-19-AC-04 | 断言终端进程运行身份与应用服务一致：网关不调用 setuid/setgid、不切换到其它用户；终端内 id -u 与应用服务进程属主相同 | 网关源码断言（无身份切换调用）+ 真实 NAS 终端内核对身份 |
| PLAN-FNOS-007-T15-04 | FNOS-007-19-AC-05 | 在真实 NAS 记录终端打开、命令执行、关闭和应用重启后的证据，并登记 docs/validation/ | T15-01 至 T15-03 |
T16：网关旧 Cookie 认证恢复
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T16-01 | FNOS-007-20-AC-01、02 | 使用 DSH BrowserAuth 的 authority-hash Cookie 名称判断当前会话；旧 authority Cookie 不阻止首页注入 launch token | gateway server 回归覆盖当前 Cookie、旧 Cookie 和无 Cookie 首页请求 |
| PLAN-FNOS-007-T16-02 | FNOS-007-20-AC-03 | 401 首页恢复继续执行当前 token exchange，重新生成 Cookie 后保持 API、WebSocket 和设置接口的认证链路 | gateway server 8 项集成测试、FPK gateway app 重建和真实 NAS 回归 |
T17：网关与 DSH Web 的 HOME/DSH_HOME 边界
| 任务 ID | 对应验收 | 实施内容 | 验证 |
|---|---|---|---|
| PLAN-FNOS-007-T17-01 | FNOS-007-21-AC-01、02 | buildDshRuntimeEnv() 保留网关继承的 HOME，只设置 DSH_HOME 为 TRIM_PKGHOME；没有网关 HOME 时才回退到 DSH_HOME | runtime-env 回归测试断言两个目录可不同；gateway typecheck/build |
| PLAN-FNOS-007-T17-02 | FNOS-007-21-AC-03 | 重新生成 gateway app 产物并在 NAS 检查 /proc/<dsh-web-pid>/environ 与网关进程环境 | FPK 安装后同时核对 HOME、DSH_HOME、profile、pnpm store 和应用共享目录 |
| PLAN-FNOS-007-T18-01 | FNOS-007-22-AC-01、03 | askFpkApps() 在仅发现一个 FPK 应用时直接返回该应用，不调用 multiselect | tooling/fnos-dsh-cli/tests/prompts.spec.ts 覆盖单应用自动选择和无交互调用 |
| PLAN-FNOS-007-T18-02 | FNOS-007-22-AC-02 | 保留多应用场景的原有多选流程，不改变 --app 显式选择和 FPK 构建参数 | CLI prompts 测试与 typecheck |
| PLAN-FNOS-007-T19-01 | FNOS-007-23-AC-01、03 | 从 wizard/install 移除 wizard_host 选择项，保留 cmd/main 未提供该变量时对 127.0.0.1 的默认回退 | FNOS-007 baseline 测试检查安装向导不含监听地址且运行时默认值不变 |
| PLAN-FNOS-007-T19-02 | FNOS-007-23-AC-02、03 | 将 wizard_npm_registry 配置项移动到 wizard/install 的第一项，保持 npm 官方源空值语义和现有镜像列表 | 向导 JSON 解析测试、JSON/FPK 构建校验 |
| PLAN-FNOS-007-T20-01 | FNOS-007-24-AC-01、02 | DSH 401 首页恢复时，在转发新 token 交换响应中追加历史应用挂载路径 Cookie 的过期指令，同时保留上游新根路径 Cookie | Gateway server 集成测试验证恢复响应同时包含新 Cookie 和旧路径删除 Cookie |
| PLAN-FNOS-007-T20-02 | FNOS-007-24-AC-03 | 覆盖浏览器按路径优先发送旧同名 Cookie 的场景，避免用户必须手动清理浏览器 Cookie | Gateway server stale-cookie 回归测试；真实 NAS 验证设置接口和页面加载 |
| PLAN-FNOS-007-T21-01 | FNOS-007-25-AC-01、02、04 | 在 DSH 全局 npm 前缀中执行 npm install @trimjs/trim-cli@latest -g --ignore-scripts，沿用 .npmrc registry，验证安装后的全局包目录，再执行 Skill 复制 | trim-cli-install.spec.ts 验证 npm 参数、全局包位置、helper 调用和失败边界 |
| PLAN-FNOS-007-T21-02 | FNOS-007-25-AC-03 | 通过安装回调 helper 将包内 skill/ 目录原子更新到 ${HOME}/.agents/skills/trim-cli，自动创建 .agents/skills 并移除旧文件 | trim-cli-skill.spec.ts 验证首次安装、覆盖更新和旧文件清理；NAS 验证应用用户可读取 Skill |
| PLAN-FNOS-007-T22-01 | FNOS-007-26-AC-01、02 | 从 published-dsh-plugins.json 删除 Showcase，并同步构建门禁的内置插件集合和归档循环 | CLI baseline 测试验证发布清单只包含三个 FPK 插件；FPK 构建验证无 Showcase 归档 |
| PLAN-FNOS-007-T22-02 | FNOS-007-26-AC-03 | 保留 plugins/dsh-semi-ui-showcase-plugin、packages/dsh-semi-ui 和 showcase CLI 目标，避免把“移除内置”误实现为删除插件能力 | 插件独立 typecheck/build/test 与 CLI plugin 目标回归 |
| PLAN-FNOS-007-T23-01 | FNOS-007-27-AC-01、02 | 删除发布清单的 registry 字段；保留 .npmrc 作为安装向导、插件、dshmarket 和 trim-cli 的唯一 registry 来源 | baseline 清单断言无 registry；安装回调 registry 测试和 shell syntax 检查 |
| PLAN-FNOS-007-T23-02 | FNOS-007-27-AC-03 | 将 install/upgrade callback 与 DSH runtime 的 NPM_CONFIG_USERCONFIG 统一到应用 HOME/.npmrc，不合并 HOME 与 DSH_HOME | dsh-runtime-env 回归测试断言不同 HOME/DSH_HOME 时 config 路径跟随 HOME；gateway 全量测试 |
| PLAN-FNOS-007-T24-01 | FNOS-007-28-AC-01 | 让 wizard/config、wizard/upgrade 复用 wizard/install 的 wizard_port、wizard_trusted_hosts、wizard_npm_registry 字段契约，移除 config/upgrade 中的 wizard_host | baseline 测试比较三个向导字段集合和 npm 选项定义 |
| PLAN-FNOS-007-T24-02 | FNOS-007-28-AC-02 | 将三个向导的 npm 镜像源 item 放到最后，并统一移除三个向导 label 的“（可选）”文案 | 向导 JSON 回归测试和文档构建 |
| PLAN-FNOS-007-T25-01 | FNOS-007-29-AC-01、02 | 为 FPK archive remove/add 提供独立的 run_dsh_plugin_with_release_age，仅追加 --config.minimum-release-age=0，remove 参数保持插件名称 | bundled-plugin-install 回归测试验证 remove/add 顺序、无版本号和 release-age 参数 |
| PLAN-FNOS-007-T25-02 | FNOS-007-29-AC-03 | 读取 plugins 的第三列 source；thirdparty registry add/update 使用受控 release-age 例外，自有插件继续走既有归档或普通收敛逻辑 | dshmarket 缺失、版本不一致和同版本场景测试；真实 NAS 安装验证 |
| PLAN-FNOS-007-T26-01 | FNOS-007-30-AC-01、03 | 将 Codex Auth 客户端首次开窗地址固定为 https://auth.openai.com/codex/device，不再先开 about:blank 后等待异步请求再导航 | authorization-window 与 authorization-code 回归测试；Codex Auth build |
| PLAN-FNOS-007-T26-02 | FNOS-007-30-AC-02、03 | 保留 Host 对 provider URL 的 HTTPS/凭据校验；device-code 请求失败时只更新原页面错误状态，不提前关闭已打开授权页 | Codex Auth 全量测试；DSH Web/Desktop 在真实网络下验证成功、超时和重试，不要求 NAS |
| PLAN-FNOS-007-T27-01 | FNOS-007-31-AC-01 | 将 Codex Auth 的 llm-pi-ai 静态模型基线更新为当前 profile 使用的 GPT-6/GPT-5.6/GPT-5.5 列表 | patch 配置测试、Codex Auth typecheck |
| PLAN-FNOS-007-T27-02 | FNOS-007-31-AC-02、03 | 删除模型目录手动刷新按钮；在登录状态切换和已登录页面初始化时触发一次刷新，成功后依靠 settings/document-updated 让 DSH 可用模型目录与全局模型选择器同步，失败保留旧目录 | 客户端注册回归、模型目录刷新测试、真实登录后模型弹框验证 |
| PLAN-FNOS-007-T28-01 | FNOS-007-32-AC-01 至 03 | 在 Codex Auth 客户端包裹 llm-pi-ai 的 Codex model discovery，使官方 Models 页的候选弹框读取 session.modelCatalog()；非 Codex provider 和非配置页 discovery 透传原实现 | discovery bridge 单元测试、Codex Auth 全量检查、真实客户端登录后两处列表对照 |
| PLAN-FNOS-007-T29-01 | FNOS-007-33-AC-01、02、04 | 让 dsh-fnos 导出名为 Config 的运行时 settings schema（字段全部 .volatile()），并以 volatileValue() 读取；schema 放在 host-only 模块，避免 schemastery 进入浏览器 bundle | 真实 DSH webserver + 真实 SettingsForms 的 HTTP 端到端测试断言 PUT 返回 200 且设置与允许清单文件一致；built-lib 导出断言；Client bundle 无 schemastery |
| PLAN-FNOS-007-T29-02 | FNOS-007-33-AC-03、04、06 | 网关代理路径路由整体包裹错误处理并返回 JSON 错误；允许清单写入按文件串行化，消除并发原子替换的 ENOENT 丢写；session-log 路由的两个 await 纳入 try；七个 fnOS 路由统一补上兜底错误响应 | 路由级回归测试验证失败时返回可诊断 JSON、补偿写恢复原文件、并发写不丢快照；lib/ 构建产物断言 |
| PLAN-FNOS-007-T29-03 | FNOS-007-33-AC-05 | 对齐插件校验器与网关解析器的 version 判定：两者都要求 version === 1，插件额外接受设置字段的裸数组形态；validateGatewayProxyPaths 内部改用裸数组形状避免重复要求文档版本 | 跨包契约测试逐例断言两侧判定一致；插件与网关全量测试 |
| PLAN-FNOS-007-T29-04 | FNOS-007-33-AC-01、02 | 用证据固定网关包的责任边界：补测网关对带 body 的 PUT 的逐字节转发、前缀与查询串重写、自定义路径 catch-all 转发、自身控制路由本地响应，以及上游 400 原样透传（证明空白 400 来自 DSH 而非网关） | packages/fnos-gateway/tests/proxy-forwarding.spec.ts 6 例；网关全量测试 |
| PLAN-FNOS-007-T29-05 | FNOS-007-33-AC-06 | 加固 PathAllowlistStore 的 listener 隔离：listener 抛错时移除该 listener 并记录，健康 listener 继续收到更新，reload() 始终 resolve，避免 unhandled rejection 触发网关整体重启 | tests/path-allowlist-listener-isolation.spec.ts 5 例（修复前 4 例失败）；网关与插件全量测试 |
| PLAN-FNOS-007-T30-01 | FNOS-007-34-AC-01、02 | 在 @tnnevol/dsh-semi-ui 的气泡浮层（.semi-popover-wrapper）上启用 DSH 官方配套变量 --dsw-menu-backdrop-filter，回退 blur(40px) saturate(150%)；保持 background: var(--dsw-specific-menu) 不变，只补磨砂 | tests/frosted-overlays.spec.ts 断言 lib/style.css 中的 popover 规则含该 token 与回退值；dsh-semi-ui 全量测试 |
| PLAN-FNOS-007-T30-02 | FNOS-007-34-AC-03、04 | -webkit-backdrop-filter 单独放入 @supports 规则（与标准属性同块会被 lightningcss 去重丢弃），并重建四个消费插件产物，使内联样式同步更新 | 测试同时断言 lib/style.css 含前缀声明与 @supports 守卫、且源码同块内无前缀；红绿验证覆盖「完全缺失」与「同块并列」两种写法；四个插件 typecheck 与全量测试 |
| PLAN-FNOS-007-T31-01 | FNOS-007-35-AC-01、02、03、04 | 在 cordis.patch.yml 中为七个 Codex 模型补全 input、contextWindow、maxTokens 与逐模型 reasoningEfforts，取值对齐 pi-ai 0.87.1 的 Codex 目录；off 按模型语义区分「不声明 / off: null / off: none」 | tests/host/model-capabilities.spec.ts 断言每个条目的能力字段、思考等级顺序与 off 写法（修复前 3 例中 2 例失败）；真实 llm-pi-ai 启动后经 PiAiAdapter.resolveModel 读回等级、模态与上下文窗口 |
| PLAN-FNOS-007-T31-02 | FNOS-007-35-AC-05 | 消除能力清单的第二份副本：新增 src/contracts/model-capabilities.ts，客户端候选桥接与宿主自愈都从它取值；补丁条目与该契约逐字段比对，任一侧漂移即测试失败 | tests/host/model-capabilities.spec.ts 新增「补丁 ↔ 契约逐字段一致」与「契约本身取值正确」两例；双向变异验证（改补丁、改契约各自变红，还原后 5 例全绿） |
| PLAN-FNOS-007-T31-03 | FNOS-007-35-AC-05、06 | 客户端候选桥接改为返回完整能力：以契约为准，并用适配器自带目录补齐契约未收录的新 id；列表查询失败时只降级补全、不丢失候选 | tests/client/model-discovery.spec.ts 覆盖「候选带能力」「契约外 id 用适配器补齐」「适配器失败仍返回候选」「契约优先于适配器」；旧实现下 5 例失败 |
| PLAN-FNOS-007-T31-04 | FNOS-007-35-AC-06 | 宿主侧一次性自愈：启动时若用户层 models 条目缺少能力字段则补齐，只填空缺、不覆盖用户已设的值，不增删改模型与顺序，重复执行无写入 | tests/host/model-capability-heal.spec.ts 10 例（含「不覆盖用户值」「保留自有模型/顺序/名称」「契约外 id 不动」「幂等」）；真实 profile 启动后 dump 由 0 条能力字段变为 7 条 |
数据、权限和错误处理
| 类别 | 处理要求 |
|---|---|
| 用户设置 | 由 DSH profile 承载；迁移后旧值可读，写入冲突保留最新有效值 |
| 凭据和授权 | 沿用现有存储位置和权限，不进入表单响应或测试夹具 |
| 会话 | 只读取和导出旧会话，不改写或删除用户文件 |
| FPK 配置 | 配置文件采用临时文件和原子替换，写入失败恢复原值 |
| 插件不兼容 | 安装拒绝或启动禁用；修正 peer，不用用户豁免掩盖问题 |
| 补丁锚点失败 | 以非零退出并指出锚点，不留下半补丁文件 |
| 图表渲染失败 | 显示带 role="alert" 的错误区域，不静默留白 |
依赖、风险和决策
| 风险/事实 | 影响 | 决策和验证 |
|---|---|---|
| 新版本新增插件兼容性门禁 | 插件被拒绝安装或启动禁用 | 先完成 T01，peer 修正是唯一正式放行方式 |
| Settings 接缝替换 | 用户设置读不到或写不进 | T02 采用旧值对照和真实设置读写验证 |
| LLM 消息角色变化 | 工具调用可能返回 400 | T03 保留调用 ID 配对并做真实请求回归 |
| 会话格式升级 | 旧会话可能打不开 | 由上游负责迁移，本仓库只验证读取和导出 |
| 安装补丁锚点变化 | FPK 安装硬失败 | T08 使用目标编译产物样本和单次匹配断言 |
| 开发宿主与 FPK 同步升级 | 根 CLI 和本地 profile 需要跟随目标接缝 | 根项目 DSH CLI、dsh-llm-pi-ai 和本地 .dsh profile 一并验证 0.1.7-rc.2 |
| Mermaid 安全配置 | 不可信图表可能引入风险 | 保持 securityLevel: 'strict'，不放宽渲染边界 |
| 应用账号不可登录 | 终端默认 Shell 落到不可登录值，终端打开即退出 | T11 由应用显式导出可用交互式 Shell，不依赖账号登录 Shell，并在真实 NAS 验证终端可用 |
| 终端环境与模型工具环境存在差异 | 用户可能误判为故障 | T11 在计划中列出差异事实，并在说明页显式描述；DSH_HOME 是否补充由 T11-03 决定 |
既有功能变更记录方式
每当任务改变已完成需求中的状态或交互时，计划必须新增一条变更记录，至少包含原需求/功能/验收编号、当前约定、目标约定、变更原因、影响模块和验证方式。状态图和时序图中的变更节点或 Note 必须使用 变更点： 前缀。
测试、打包、发布和回滚
插件和包级
bash
pnpm run check -- --packages --plugins
pnpm run build -- --plugin fnos覆盖四个插件、共享 UI、网关、peer 兼容性、设置、消息、图片和图表相关测试。
文档级
bash
pnpm run check -- --sdd --docs
pnpm run build -- --docs
git diff --check覆盖需求/计划结构、Mermaid 语法、renderer hydration、主题切换和内部链接。
FPK 和真实 NAS
- 构建 FPK，确认版本、native、清单和捆绑插件一致。
- 在真实 NAS 验证 FPK 应用安装/升级/启动、网关、
dsh-fnos插件与授权目录、旧会话和回滚等 fnOS 相关行为。 - 在 DSH Web 与 Desktop 验证 CodeBuddy、Codex Auth、Semi UI Showcase 等非 fnOS 插件能力；这些插件验收不附加 NAS 门槛。
- 把证据按插件与目标宿主分别写入
docs/validation/，再回写 FNOS-007 和本计划状态。
回滚
- 安装失败不得删除旧运行时、配置、凭据、会话或工作区。
- 设置写入失败恢复写入前版本。
- 补丁锚点不匹配时停止安装，不继续写入半成品。
- dshmarket 版本不一致时按清单收敛，收敛过程不先卸载用户数据；同版本不重复安装。
参考资料
| 外部能力 | 参考 | 用途 |
|---|---|---|
| DSH 上游项目 | deepseek-ai/deepseek-harness 的 dsh-v0.1.7-rc.2 tag | 插件接缝和兼容性契约 |
| 插件兼容性 | 上游 evaluatePluginCompatibility() 契约 | peer 兼容性门禁 |
| fnOS 平台 | fnnas-docs Skill | FPK、权限、安装和升级约束 |
| Mermaid 渲染器 | vitepress-mermaid-renderer Skill | 客户端渲染、工具栏、主题和可访问性 |
| 本仓库规范 | 需求文档规范、计划文档规范 | 文档边界和追踪规则 |
完成状态
| 阶段 | 状态 | 对应功能 |
|---|---|---|
| T01 版本基线和插件门禁 | 已完成 | FNOS-007-01、02 |
| T02 设置、插槽和图标 | 已完成 | FNOS-007-03、09 |
| T03 LLM、图片和 Codex | 已完成 | FNOS-007-04、05 |
| T04 共享 UI | 已完成 | FNOS-007-06 |
| T05/T08 FPK、网关、会话、native 和 attachment-local | 已完成 | FNOS-007-07、08、13；node-pty 版本不变但 native 产物和 attachment-local 生产依赖需按目标基线验收 |
| T06 升级、回滚和 NAS | 已完成 | FNOS-007-10 |
| T07 Mermaid 渲染器 | 已完成 | FNOS-007-11 |
| T09 dshmarket | 已完成 | FNOS-007-12 |
| T10 FPK workflow 命名 | 已完成 | FNOS-007-14 |
| 作废，归口 T15 | FNOS-007-15 → FNOS-007-19 | |
| T12 本地 DSH Web 启动与 catalog 一致性 | 已完成 | FNOS-007-16 |
| T13 插件未使用 DSH 依赖清理 | 已完成 | FNOS-007-17 |
| T14 网关 DSH 浏览器认证 Cookie | 已完成 | FNOS-007-18 |
| T15 网关终端 Shell 与字符集环境 | 已完成 | FNOS-007-19（含并入的身份断言与 NAS 终端证据） |
| T16 网关旧 Cookie 认证恢复 | 已完成 | FNOS-007-20 |
| T17 网关与 DSH Web 的 HOME/DSH_HOME 边界 | 已完成 | FNOS-007-21 |
| T18 FPK 单应用构建选择 | 已完成 | FNOS-007-22 |
| T19 安装向导监听地址与 npm 源顺序 | 已完成 | FNOS-007-23 |
| T20 网关旧挂载路径 Cookie 清理 | 已完成 | FNOS-007-24 |
| T21 全局 trim-cli 与 Agent Skill | 已完成 | FNOS-007-25 |
| T22 FPK 移除 Semi UI Showcase 内置插件 | 已完成 | FNOS-007-26 |
| T23 npm registry 统一由 HOME/.npmrc 管理 | 已完成 | FNOS-007-27 |
| T24 安装/配置向导字段统一 | 已完成 | FNOS-007-28 |
| T25 NAS 安装 release-age 兼容 | 已完成 | FNOS-007-29 |
| T26 Codex Auth 授权页打开 | 已完成 | FNOS-007-30 |
| T27 Codex Auth 模型目录自动同步 | 已完成 | FNOS-007-31 |
| T28 Codex 模型设置弹框与全局模型目录统一 | 已完成 | FNOS-007-32 |
| T29 三方插件 API 反代配置保存 | 已完成 | FNOS-007-33 |
| T30 气泡浮层磨砂背景 | 已完成 | FNOS-007-34 |
| T31 Codex 模型能力元数据补全 | 已完成 | FNOS-007-35 |
变更记录
| 日期 | 变更 | 说明 |
|---|---|---|
| 2026-09-24 | 建立 PLAN-FNOS-007 | 纳入 DSH 0.1.7-rc.2 适配、插件接缝、FPK、会话和验收任务。 |
| 2026-09-27 | 纳入 dshmarket 任务 | 在当前开发计划中同步 dshmarket 精确版本升级，不修改已完成计划正文。 |
| 2026-09-27 | 重整计划边界 | 删除需求正文复制，补充当前/目标设计、影响矩阵、迁移方案、状态图、时序图、任务、验证和变更点规则。 |
| 2026-09-27 | 明确 node-pty 适配边界 | 确认 DSH 0.1.5-rc.2 → 0.1.7-rc.2 的目标依赖树仍为 node-pty@1.2.0-beta.15、Node.js 24、node-gyp@11.0.0；本需求不升级 node-pty 版本，但要求按新 DSH 基线重建 native 产物并验证有/无 g++ 两条安装路径。 |
| 2026-09-27 | 新增 attachment-local 安装阻断项 | 根据 fnos-dsh-log-issues-02.txt 确认三次安装均在 node-pty 成功后因回调找不到顶层 @deepseek-ai/dsh-attachment-local 终止；目标 0.1.7-rc.2 的 dsh-base 仍以生产依赖提供该包，但它可能嵌套安装，纳入 FNOS-007-13，要求安装回调解析应用私有依赖树后再执行持久化补丁。 |
| 2026-09-27 | 新增 FPK workflow 命名功能 | 将可复用 FPK workflow 从 build-dsh-fn.yml 统一重命名为 build-app.yml，只调整文件名和现行引用，不修改构建、native 或 Release 上传行为。 |
| 2026-09-27 | 完成 FNOS-007 本地实现 | 完成 FPK 0.1.7 版本链路、四插件接缝、四插件归档、SettingsForms/ConfigForms、CodeBuddy role-tool/image、attachment-local 嵌套解析与幂等补丁；本地全量 check 和文档/FPK（跳过 native）构建通过，Linux native 与真实 NAS 保持待验收。 |
| 2026-09-27 | 统一 dshmarket 安装行为 | dshmarket registry 安装复用 .npmrc，并与普通 plugins 一样在版本不一致时升级/降级、同版本时跳过。 |
| 2026-09-27 | 同步开发宿主 DSH CLI | 根据用户确认，将根项目 DSH CLI、dsh-llm-pi-ai 和本地 .dsh profile 一并升级到 0.1.7-rc.2，取消原开发宿主 0.1.5-rc.2 独立边界。 |
| 2026-09-27 | 新增 T11 终端可用性任务 | 纳入 FNOS-007-15：DSH 0.1.7-rc.2 的侧边栏终端按“环境变量 SHELL → 宿主账号登录 Shell”解析默认 Shell，而应用专用账号登录 Shell 不可用且应用启动脚本未导出 SHELL，导致终端打开即退出。T11 在应用启动脚本补充可用交互式 Shell 默认值，并核对终端运行身份与环境差异。 |
| 2026-09-27 | 新增 T12 本地启动与 catalog 门禁 | 针对 pnpm start -- --web 遇到历史悬空软链接导致 Turbo watcher 失败的问题，增加生成树修复；同时把 catalog 维护从单一 DSH 包名检查扩展为所有 workspace catalog 依赖，保留既有 DSH peer 精确版本例外并修复 pi-ai。 |
| 2026-09-27 | 新增 T13 插件依赖清理 | 审计三个非 fnOS 插件的直接使用边界，移除 Codex Auth 中 5 个仅由传递 DSH 依赖使用的包；继续使用 peer 表达宿主共享能力，不改为 dependencies。 |
| 2026-09-28 | 新增 T14 网关 Cookie 认证修复 | 发现网关把 DSH BrowserAuth 的根 Cookie 改写到应用路径后，页面下的 /api/settings/describe、credentials、dynamicCordisRunner 和 Remote WebSocket 统一 401；恢复上游 Cookie 路径并补充回归验证。 |
| 2026-09-28 | 新增 T15 网关终端环境适配 | 根据 NAS 终端出现重复 bash 和中文路径乱码，将 Shell/locale 环境设置从应用 cmd/main 移到网关 DSH 子进程环境，并按 DSH 的 PATH 解析规则选择默认 bash。 |
| 2026-09-28 | 新增 T16 网关旧 Cookie 认证恢复 | 根据 NAS 401 与连接重试日志，按 DSH 0.1.7 的 authority-bound Cookie 契约修复旧 Cookie 误判，确保首页在旧会话下重新完成 launch token exchange。 |
| 2026-09-28 | 新增 T17 网关环境边界修复 | 发现 DSH Web 环境把 HOME 和 DSH_HOME 都设置为 TRIM_PKGHOME；改为继承网关 HOME、独立设置 DSH_HOME，并补充 runtime-env 测试。 |
| 2026-09-28 | 新增 T18 FPK 单应用构建选择 | 当工作区只有一个 fnOS FPK 应用时，跳过无必要的交互选择并直接编译该应用；多应用仍使用原多选流程。 |
| 2026-09-28 | 新增 T19 安装向导配置收敛 | 首次安装不再让用户选择 DSH 监听地址，固定通过运行时默认值使用 127.0.0.1；npm 镜像源移到向导第一项，减少安装时的无效交互。 |
| 2026-09-28 | 新增 T20 旧挂载路径 Cookie 清理 | 发现旧版本已经写入应用挂载路径的同名 Cookie 会排在新根 Cookie 前面；网关在 token 恢复响应中显式过期旧路径 Cookie，避免 401 恢复仍依赖手动清理。 |
| 2026-09-28 | 新增 T21 全局 trim-cli 与 Skill 安装 | 明确 trim-cli 不属于 dshmarket 或 DSH profile 插件；安装回调使用 npm latest 全局安装，并从包内 skill/ 更新应用 HOME 下的 Agent Skill。 |
| 2026-09-28 | 新增 T22 移除 Semi UI Showcase FPK 内置插件 | 根据发布范围调整，FPK 不再归档或安装 Showcase；共享 UI、插件源码和独立构建入口继续保留。 |
| 2026-09-28 | 新增 T23 npm registry 配置统一 | 删除清单级 registry 字段，安装和 DSH Web 统一从应用 HOME/.npmrc 读取 registry，保留 DSH_HOME 独立数据边界。 |
| 2026-09-28 | 新增 T24 安装/配置/升级向导字段统一 | 让 config、upgrade 与 install 使用相同运行字段，三个向导的 npm 源都放在末尾并移除“（可选）”文案。 |
| 2026-09-28 | 新增 T25 NAS 安装 release-age 兼容 | 针对 dshmarket 新版本导致 pnpm 在 remove 阶段校验 lockfile 失败的问题，归档替换和 thirdparty registry 操作使用受控 release-age 例外。 |
| 2026-09-28 | 新增 T26 Codex Auth 授权页打开修复 | 设备授权页不再依赖 NAS 端 device-code 请求完成后才导航；客户端先打开固定 HTTPS 授权页，后台继续生成和轮询授权码。 |
| 2026-09-28 | 新增 T27 Codex Auth 模型目录自动同步 | 更新默认模型列表，移除手动刷新入口，登录后自动写入账号目录，并依靠 DSH 的设置变更事件刷新会话可用模型弹框。 |
| 2026-09-28 | 新增 T28 Codex 模型目录桥接 | 官方 Models 页的 Codex 候选弹框不再使用 pi-ai 静态目录，改为读取与全局模型选择器相同的 DSH Remote 动态目录。 |
| 2026-09-29 | 新增 T31 Codex 模型能力元数据补全 | 配置里的 models 会整体替换内置目录，此前只声明 id/name 的条目在遇到目录未收录的 gpt-6-sol、gpt-6-luna 时丢失思考等级与图文输入；改为逐模型显式声明能力，使模型选择器与「恢复默认模型」都回到真实能力。 |
| 2026-09-29 | 收窄插件目标环境验收 | 将 dsh-fnos、网关及 FPK/生命周期行为的 NAS 验收与其他插件的 Web/Desktop 验收分开；更新影响矩阵、阶段状态和验收清单，避免非 fnOS 插件被 NAS 阻塞。 |
| 2026-09-29 | 新增 T31-02 至 T31-04 Codex 能力单一事实来源与自愈 | 复现并固定完整因果链：官方候选弹框的数据来自客户端桥接，桥接只回传 {id, name}，弹框「添加所选」按候选项生成型号行 → 生成的能力不全的行被写入用户层 cordis.patch.yml → 用户层的 models 整体替换插件基线，于是选择器显示灰色 256K/32K 占位且无思考等级。改为：能力收敛到共享契约并加补丁↔契约漂移门；桥接返回完整能力；宿主启动时一次性补齐用户层缺失的能力字段（只填空缺，不覆盖用户值，不增删改模型）。 |
| 2026-09-30 | 废弃 T11，终端归口 T15 | 范围变化。需求 FNOS-007-15 被认定为对终端问题的错误理解（原设想在应用启动脚本 cmd/main 补 SHELL），已废弃；T11 四个任务全部作废，其中身份断言与真实 NAS 证据分别转入新增的 T15-03、T15-04，其余由既有 T15-01/T15-02 与 T17 覆盖。分期表第三期、完成状态表、影响范围表同步更新。详见 FNOS-007 变更记录。 |
| 2026-09-30 | FNOS-007 计划完成 | 状态变化。FNOS-007-01 至 FNOS-007-19 全部功能在目标环境验收通过，计划状态改为 completed；完成状态表与分期表同步。验收证据见 FNOS-007 真实 NAS 验收记录（01、03、07、08、10、13、19）与 FNOS-007 Web/Desktop 验收记录（02、04、05、06、09、12）。详见 FNOS-007 变更记录。 |