FNOS-002 DSH 应用与插件优化
| 项目 | 内容 |
|---|---|
| 需求编号 | FNOS-002 |
| 提出日期 | 2026-08-24 |
| 需求状态 | 部分 NAS 验证（7 条业务用例、157 条自动化测试通过） |
| 关联计划 | PLAN-FNOS-002 DSH 应用与插件优化 |
需求背景与目标
DSH 在 fnOS 中运行后，还有几处使用体验需要调整。Codex 登录状态和用量状态现在分散处理，未登录时仍可能显示状态，用量接口是否提供五小时窗口也没有反映到页面；NAS 引用可能改动输入框中的空格，输入框删除本次选择后 Tree 也不会同步取消勾选。FPK 网关仍由直接调用 node:http 的代码承担代理，三方插件使用自定义 API URL 时，还需要手工修改浏览器 bridge 的反代路径并重新打包 FPK。项目也缺少共享 Semi UI 组件的集中预览入口。
这些内容统一在 FNOS-002 中记录，当前重点是已进入开发的插件、网关和 DSH Web 恢复能力。DSH 运行时、插件、插件依赖和 FPK 发布还必须遵循同一版本约束；原 FNOS-003 的版本统一内容已迁移到本需求，避免版本要求与具体运行设置需求分散维护。
需求目标
- 统一 Codex 登录与用量状态：只在确认登录后显示状态，用量接口提供五小时窗口时自动显示对应状态，接口未提供时自动隐藏。
- NAS 文件和目录引用不改动用户已有文本；Tree 面板打开期间，当前操作插入的引用被删除时同步取消对应勾选。
- 新增 DSH Semi UI 总览插件。
- 使用
connect与http-proxy-middleware重写 FPK 网关，通过 tsdown 生成可直接随 FPK 分发的单文件入口；浏览器 Bridge 使用独立 JS 源文件维护，网关常驻时在 Web 左侧菜单提供“重启 Web”按钮。 - 由 fnOS 插件管理三方插件 API URL 反代配置，网关监听配置并将匹配的绝对 URL 请求改写到统一网关下的 DSH 服务。
- 统一 DSH 运行时、插件、插件依赖、native 产物、FPK 安装流程和发布文档的目标版本为
0.1.1-rc.2，并保留用户数据与配置。
涉及范围
| 模块 | 目录或入口 | 职责 |
|---|---|---|
| Codex 插件 | plugins/dsh-codex-auth-plugin | 控制登录状态和用量窗口显示 |
| fnOS 插件 | plugins/dsh-fnos-plugin | 处理 NAS 引用和三方插件 API URL 反代配置 |
| 共享 UI | packages/dsh-semi-ui、待新增总览插件 | 展示共享组件和主题效果 |
| 网关源码包 | packages/fnos-gateway | 使用 connect、http-proxy-middleware 和 tsdown 维护网关源码、独立浏览器 Bridge 与构建入口 |
| FPK 网关产物 | apps/fn-deepseek-harness/app/gateway-proxy.mjs | 监听 fnOS Unix Socket，代理 DSH HTTP、WebSocket 和流式请求 |
| 项目文档 | docs/ | 记录需求、调研结论和后续计划 |
功能列表
| 编号 | 优先级 | 功能 | 用户行为 | 状态 |
|---|---|---|---|---|
| FNOS-002-01 | P1 | Codex 登录与用量状态 | 未登录时不显示状态；登录和退出后及时更新；接口提供五小时窗口时自动显示对应状态 | 已实现 |
| FNOS-002-02 | P1 | NAS 引用与 Tree 状态 | 插入引用时保留原文空格；面板打开期间删除本次引用后同步 Tree，历史引用不参与本次勾选 | 已实现 |
| FNOS-002-03 | P1 | Semi UI 总览插件 | 点击插件入口后跳转到独立路由，查看共享组件及主题效果 | 已实现 |
| FNOS-002-04 | P1 | FPK 网关、进程恢复与 API URL 反代 | 使用专业代理中间件；DSH Web 退出后，Web 端显示“重启 Web”按钮并从网关恢复；用户可配置三方插件 API URL 反代规则并即时生效 | 部分验证 |
版本统一（跨功能约束）
版本统一不是新增功能编号，而是 FNOS-002 各功能的发布约束：
- DSH 运行时、DSH 插件及
@deepseek-ai/dsh-*依赖统一使用0.1.1-rc.2。 - FPK 安装/升级回调、node-pty native 配置、已发布插件清单和相关文档必须与该版本一致。
- 版本检查和升级不得清理
DSH_HOME、profile、凭据、工作区或现有插件配置。 - 共享 UI 包继续由 workspace 管理，不作为 DSH 运行时插件重复安装。
交互和行为约束
- Codex 未登录、加载中或鉴权失败时隐藏成功状态，登录入口保留。
- 五小时用量以接口返回的
limit_window_seconds为准；只有明确等于 18,000 秒的窗口才展示，不根据primary_window或secondary_window的位置猜测。 - 五小时窗口没有用户配置项，不写入插件设置；接口刷新后，设置卡片和对话输入区状态同步更新。
- Codex 配置面板可同时展示五小时和每周窗口；对话输入区状态栏只展示一个紧凑窗口，优先五小时、否则每周，没有可识别窗口时隐藏。
- NAS 引用只处理插入位置。前面已有空白时不补空格，没有空白时补一个空格。
- fnOS Tree 面板每次打开时记录已有引用作为操作基线；面板打开后新插入的引用属于本次操作，之前已存在的引用不自动映射为当前 Tree 选中状态。
- 面板保持打开时，用户从输入框删除本次操作插入的 structured reference，Tree 必须同步取消对应节点；删除历史引用不得改变当前 Tree 状态。
- 当前操作关联使用 DSH occurrence 身份区分，不只按路径判断。同一路径存在历史引用和本次引用时，只同步本次 occurrence。
- Semi UI 总览插件使用
@tnnevol/dsh-semi-ui的公开组件，并覆盖浅色和深色主题。 - 设置中的插件卡片只保留总览入口；点击后进入
#/plugins/semi-ui。总览页面使用 DSHshell.overlay插槽呈现，不覆盖conversation、sidebar等 single slot。 - 总览路由支持浏览器前进、后退和刷新；关闭总览时返回进入前的 DSH 页面。未安装插件时该 Hash 不得影响 DSH 正常启动。
- 网关源码放在
packages/fnos-gateway，使用 tsdown 将依赖打包到apps/fn-deepseek-harness/app/gateway-proxy.mjs；NAS 安装阶段不再安装网关的 npm 依赖。 - 浏览器注入代码必须放在独立
.js文件中维护，不在 TypeScript 中保留BRIDGE_SCRIPT_BODY一类大段模板字符串。默认由构建插件使用fs读取源文件并作为虚拟模块内联到单文件 ESM，NAS 运行时不读取仓库源码路径。 - HTML 默认直接注入构建后的 Bridge 内容；若以后改用
<script src>，必须由网关提供稳定的内部静态路由，并将对应资源纳入 FPK，不允许引用packages/源码目录。 - 网关监听
app/ui/config声明的app.sock，统一网关公开路径保持/app/fn-deepseek-harness，上游固定为 DSH 回环地址127.0.0.1:3080。 - FPK 运行状态以常驻网关进程为准，DSH Web PID 只表示可单独恢复的上游子进程；Web 退出不能清除网关状态或重复启动网关。
- Web 正常时，浏览器 Bridge 在 DSH Web 左侧菜单提供“重启 Web”按钮；DSH Web 不可用时，网关提供带同名按钮的独立恢复页面。恢复接口只接受管理员的同源 POST 请求。
- 启动中的 PID 先写临时状态，只有 DSH Web 健康检查通过后才原子替换正式 PID；失败时网关继续运行并展示错误。
- 反代规则只决定三方插件绝对 API URL 是否补统一网关前缀，不作为接口访问权限控制；fnOS 网关登录校验与插件自身权限仍按原规则执行。
- 自定义路径由 fnOS 插件设置卡片统一编辑，点击“保存”后写入
${TRIM_PKGVAR}/gateway/path-allowlist.json；“放弃”恢复服务端已保存内容。 - 网关通过
fs.watch读取最新配置，并把完整快照推送给已打开的页面；配置变更不要求刷新 DSH Web。
不在本次范围内
- 不修改 DSH 官方源码和 Codex OAuth 流程。
- 不调整 Codex 模型调用、OAuth 和图片能力；用量接口只用于状态展示，不修改额度或刷新规则。
- 不改动 NAS 授权、路径转换和权限校验规则。
- 不把动态路径列表扩展成接口访问控制、防火墙或插件权限系统。
- 不自动扫描三方插件源码推断 API URL；反代规则由用户在 fnOS 插件设置中明确维护。
- 不对 DSH Web 进行无限自动重启；本阶段提供明确的人工恢复入口和并发启动保护。
验收条件与完成状态
P1 验收条件
- Codex 登录状态在登录、退出和异常场景下显示正确。
- 用量接口返回 18,000 秒窗口时显示五小时剩余额度和重置时间；未返回、字段不完整或请求失败时不显示该窗口。
- 五小时窗口显隐不依赖用户设置，刷新用量后能根据最新接口响应自动变化。
- NAS 文件和目录引用保留原文空格，不产生重复空格；面板打开期间删除本次引用会立即取消对应 Tree 勾选，历史引用不会进入当前选择状态。
- Semi UI 总览插件可正常安装和卸载；点击入口可进入独立总览路由，浏览器前进、后退和刷新有效，组件在浅色、深色主题下显示正常。
- 新网关兼容 HTTP、WebSocket、SSE、插件 API 和静态资源，产物位于 FPK 的
app目录，并在真实 fnOS 统一网关入口完成验证。 - Bridge 可作为独立 JS 文件完成语法检查和单元测试；生成的单文件网关不包含未替换占位符，也不依赖 NAS 上不存在的 Bridge 源文件。
- Web 左侧菜单可重启 DSH Web；DSH Web 被单独终止后，fnOS 应用仍保持运行状态，访问入口显示恢复页面，管理员可点击“重启 Web”，成功后自动恢复 DSH 页面且不会产生第二个网关进程。
- 恢复过程使用启动锁、临时 PID 和健康检查；重复点击、启动失败及陈旧 PID 不会产生多个 DSH Web 或误杀无关进程。
- fnOS 插件可查看、添加、删除三方插件 API URL 反代规则；未保存的修改不影响当前配置，“放弃”后恢复已保存值。
- 保存后 JSON 使用约定结构写入
${TRIM_PKGVAR}/gateway/path-allowlist.json，网关无需重启即可加载。 - 已打开页面能收到最新路径快照；新增路径随后发起的
fetch、XHR、EventSource、WebSocket 和动态脚本请求会补/app/fn-deepseek-harness前缀并代理到127.0.0.1:3080。 - 无效或损坏配置不会替换最后一次有效快照，也不会导致网关或 DSH 退出。
- DSH 版本、插件依赖、FPK 安装回调、native 产物、发布清单和文档均指向
0.1.1-rc.2；目标 NAS 验证前状态保持“待完成”。
当前 NAS 验证结果
- 本地自动化测试已通过：39 个测试文件、157 条测试全部通过；该结果不替代真实 NAS 业务验收。
- 已通过 7 条真实 NAS 浏览器用例，记录见FNOS-002 NAS 浏览器验收记录。
- 已验证 Codex 登录状态、五小时/每周用量、用量 Popover、设置刷新接口和会话输入区状态同步。
- 已验证 NAS TreeSelect 授权目录、复选框选中/取消、设置快捷键、跟随系统切换浅色和未启用菜单隐藏。
- 已验证 DSH Web 左侧刷新和重启；刷新只作用于 DSH Web iframe，不会刷新 iframe 外部的 fnOS 宿主页面，重启后页面约 15 秒恢复。
- 已验证静态资源通过完整路径
/app/fn-deepseek-harness/dsh-pet-7340/pic/cursor-grab.png返回200 image/png。 - API URL 反代即时生效、SSE/WebSocket、升级回滚、异常注入、权限差异和并发控制等场景仍按原验收条件继续验证。
状态看板
| 阶段 | 状态 | 当前范围 | 下一步 |
|---|---|---|---|
| P1 应用与插件优化 | 部分 NAS 验证（7 条业务用例、157 条自动化测试通过） | 自动化测试 157/157 通过；Codex 状态、NAS Tree、快捷键、主题、刷新/重启和静态资源已完成部分 NAS 验证 | 完成 API 反代即时生效、实时连接、权限、版本升级和回滚验收 |
变更记录
| 日期 | 变更 | 说明 |
|---|---|---|
| 2026-08-24 | 新增 FNOS-002 | 记录 Codex 登录状态需求 |
| 2026-08-25 | 合并 NAS 引用需求 | 将原 FNOS-003 合并到本需求 |
| 2026-08-27 | 扩展需求范围 | 增加 UI 总览、网关代理和应用跳转调研 |
| 2026-08-27 | 精简需求文档 | 合并重复功能和验收说明，技术细节留到详细计划 |
| 2026-08-28 | 增加 Codex 用量显隐需求 | 五小时窗口由接口能力自动决定，不提供用户开关 |
| 2026-08-28 | 合并 API URL 反代需求 | 将原 FNOS-003 合并到 FNOS-002-04，确认代理技术、持久配置和即时生效规则 |
| 2026-08-28 | 合并 Codex 状态功能 | 将原 FNOS-002-06 合并到 FNOS-002-01，登录状态和用量状态统一规划 |
| 2026-08-28 | 更新应用跳转调研 | SDK 存在未公开的跨应用方法，但无法确认可稳定直达应用中心 DSH 详情页 |
| 2026-08-29 | 增加 DSH Web 恢复需求 | FPK 状态改由常驻网关承载，Web 退出后通过网关恢复页面单独启动 |
| 2026-08-30 | 明确 DSH Web 恢复交互 | Web 左侧菜单和故障恢复页面均提供“重启 Web”按钮，点击后重新启动 DSH Web 并自动恢复页面 |
| 2026-08-29 | 明确 Semi UI 总览路由 | 插件入口跳转独立 Hash 路由，通过 shell.overlay 展示总览页面 |
| 2026-08-29 | 增加 Tree 反向同步需求 | 输入框删除本次面板插入的引用时同步取消勾选，并隔离历史引用状态 |
| 2026-08-29 | 调整 Bridge 源码组织 | 注入脚本改为独立 JS 文件维护，构建期读取并内联到单文件网关产物 |
| 2026-08-29 | 完成 P1 开发 | 完成 Codex 状态、NAS 引用同步、Semi UI 总览和新网关代码，进入真实 NAS 验证 |
| 2026-08-30 | 完成 NAS 引用同步修正 | 按 DSH structured reference 的占位符和 draftRev 计算多选偏移，补齐懒加载节点插入、部分插入和分隔空格回归测试 |
| 2026-08-30 | 合并需求编号并完成 Web 恢复验证 | 移除已替换的 FNOS-002-05，统一使用 FNOS-002-04；真实 NAS 已验证 Web 正常重启且 FPK 应用保持启用 |
| 2026-08-31 | 迁移版本统一需求 | 将原 FNOS-003 的 DSH、插件、依赖、FPK 和 native 版本约束并入本需求；FNOS-003 改用于 FPK 应用运行设置 |
| 2026-08-31 | 同步刷新与重启验证状态 | 真实 fnOS 环境已验证侧边菜单刷新、重启均正常，刷新不会影响 iframe 外部页面 |
| 2026-09-01 | 增加真实 NAS 浏览器验收结果 | 7 条 FNOS-002 用例通过；补充用量、TreeSelect、快捷键、主题、刷新/重启和静态图片 Network 证据，其余场景保持待验证 |
| 2026-09-01 | 更新自动化测试状态 | 根目录 pnpm run test:unit 通过，39 个测试文件、157 条自动化测试全部通过；未改变尚未完成真实 NAS 验收的业务用例状态 |