# DSH 鸿蒙 PC 原生客户端开发方案（方案 C：ArkUI 全原生）

> 版本：v1.1（2026-08-23 check 后更新：决策落地、R1 落定、双速路线整合）
> 定位：HarmonyOS PC 上的 DSH 原生桌面应用——全原生 ArkUI 界面 + 本地 DSH Host 运行时托管 + 永远跟随官方升级
> 路线（2026-08-23 定稿）：**双速**——先出 Web 壳首发版（P1）抢鸿蒙卡位，协议原生（方案C 主体）并行分支推进，壳即 4.5 节 WebView 逃生舱
> 姊妹篇：**HANDOVER.md（交接文档——新会话入口，先读它）**｜dsh-desktop/PRODUCT-PLAN.zh.md（macOS 薄壳版，0.2.1）｜SCHEDULE-AND-DECISIONS.zh.md（AI 工期估算）｜COMPETITIVE-RESEARCH.zh.md（竞品调研）

---

## 0. 状态板（2026-08-23）

| 项 | 状态 |
|---|---|
| 工程 | ✅ /Users/eastudio/DevEcoStudioProjects/dsh-harmony（com.dotouch.dshharmony / DSH Harmony / vendor dotouch） |
| API 版本 | ✅ compatibleSdkVersion 6.0.0(20)（HarmonyOS 6.0）/ targetSdkVersion 26.0.0（HarmonyOS 7），编译验证通过 |
| CLI 构建链 | ✅ scripts/build.sh（Java/SDK 环境配方固化，见 knowledge-base/build-recipe.md） |
| 签名 | ✅ 自动签名完成，entry-default-signed.hap 构建通过 |
| 验证设备 | ✅ MateBook Pro 模拟器（HarmonyOS 7 Beta / API 26 / 2in1）已部署；MatePad Edge 真机可接入（compatible=20 兼容回归 + 真机大屏场景） |
| 知识库 | ✅ knowledge-base/（官方文档目录、SDK API 映射、生态跟踪、构建配方、问题清单） |
| git | ✅ 本地仓库初始化（main 基线 2913ad6 + feature/protocol-native 双分支；仓库级身份 dotouch，无远程——开源时再加） |
| 壳版（P0/P1） | 🔄 已在其它对话任务中启动（2026-08-23），本对话通过 git diff / 工程状态跟踪其进展 |
| 协议原生线（P2a 起） | ⏳ 待启动，工作分支 feature/protocol-native |

---

## 1. 项目概述

### 1.1 目标

1. 全原生体验：用 ArkTS/ArkUI 重写 DSH Web GUI 的完整功能（非 WebView 嵌套），获得鸿蒙 PC 原生窗口管理、多窗口、通知、系统集成。
2. 随官方升级（第一优先级）：DSH 官方发版后，客户端可在小时级内完成跟进，且不需要重新发版安装包——原生端零分叉官方代码，只消费官方 wire 协议；Host 运行时作为可热替换资产独立升级。
3. 指定模型：模型与 provider 在配置层锁定，UI 只读展示，不提供模型切换。
4. 支付界面（后续阶段）：预留账户/计费/支付的模块边界与接口，本期只做架构占位。

### 1.2 Non-goals（明确不做）

- 不 fork / 不内嵌 / 不重新分发任何官方 UI 代码（这是「随官方升级」永远成立的前提）
- 不替代 dsh 的 profile / 插件体系，只做托管、转发与展示
- 不做云同步、多用户（本期）
- 不做嵌入式交互终端（node-pty 在 ohos 未适配，见第 10 节风险）

### 1.3 核心设计原则（四条，全部来自已验证的架构事实）

| # | 原则 | 架构依据（已在本机源码确认） |
|---|---|---|
| P1 | 官方代码零分叉 | Web UI 必须由 dsh web 注入 window.__DSH_BOOT__ 才能跑，任何打包 UI 的做法都会分叉；但协议消费不分叉——DSH 官方为非浏览器壳预留了 __DSH_TRANSPORT__ 逃生舱，wire 契约（Typert RPC + 事件流）就是公开边界 |
| P2 | 协议即边界 | 客户端与 Host 之间只有三样东西：HTTP POST /api（Typert RPC）、两条只下行 WebSocket（/api/events.mux 与 /api/events.host）、named-stream 会话增量协议。原生端只依赖这三样，绝不 import 任何 @deepseek-ai/dsh-* 内部模块 |
| P3 | 数据驱动渲染 | 会话状态以 session projection 整体值 JSON 下发（todo、goal、plan、工具卡片数据），schema 校验、last-wins；DSH 官方明确「rendering belongs to the slot system」。原生端实现通用投影渲染器：官方新增工具/领域 → 新 key 进来 → 已知 key 用专属卡片、未知 key 用通用 JSON 卡片降级显示，不崩、不白屏、不阻塞升级 |
| P4 | 运行时可插拔 | npm i -g @deepseek-ai/dsh@latest + 重启 = 整个后端与协议实现立即最新（web bundle 全是 CLI 包的依赖）。运行时升级走独立通道 + 冒烟测试 + 自动回滚（移植 macOS 版已验证的升级管家） |

---

## 2. 依据：DSH 本地产品已实现功能盘点

以下清单来自本机 @deepseek-ai/dsh@0.1.1-rc.2 安装的 dsh-client-ui-* 模块族实测盘点，是原生端的功能对齐基线。

### 2.1 功能全景 → 原生端映射

| 功能域 | Web GUI 已实现（来源包） | 原生端实现 | 优先级 |
|---|---|---|---|
| 会话列表/恢复 | dsh-client-ui-sidebar | 原生侧栏（会话列表、标题、按工作区分组） | P0 |
| 对话主视图 | dsh-client-ui-conversation | 原生消息流（LazyForEach 虚拟滚动 + 流式增量） | P0 |
| 消息渲染 | dsh-client-ui-renderer | 自研 Markdown/代码高亮/图像渲染器（见 5.3） | P0 |
| 工具调用卡片 | dsh-client-ui-tool | 通用工具卡片框架 + 常用工具专属卡片（见 5.4） | P0 |
| 用户提问/审批 | dsh-client-ui-user-questions | 原生审批弹层（选项/多选/自由输入） | P0 |
| 会话中断/继续 | conversation 内 | 停止按钮 + 恢复 | P0 |
| 附件上传 | dsh-client-ui-attachment | 系统文件选择器 + 图像预览 | P1 |
| 文件引用 | dsh-client-ui-reference | @文件 引用与点击回跳 | P1 |
| 权限预设 | dsh-client-ui-permission-presets | 审批策略选择（workspace-write/ask 等） | P1 |
| 计划模式 | dsh-client-ui-plan | 计划审批流（exit_plan_mode 全屏计划卡片） | P1 |
| Todo 列表 | dsh-tool-todo 投影 | 投影驱动的任务清单卡片 | P1 |
| 目标 Goal | dsh-client-ui-goal | 目标状态卡片（轮次/阶段/blocked） | P1 |
| 子代理 | dsh-client-ui-subagent | 子代理面板（列表/追问/中断） | P1 |
| 后台任务 | dsh-client-ui-jobs | 任务中心（读取输出/终止） | P1 |
| 工作流 | dsh-client-ui-workflow-run | 工作流运行视图（阶段进度） | P2 |
| 技能 | dsh-client-ui-skill | 技能加载状态展示 | P2 |
| 目录选择 | dsh-client-ui-directory-picker | 系统目录选择器（FSPicker） | P1 |
| 工作区切换 | dsh-client-ui-workspace | 工作区管理与状态 | P1 |
| Agent 预设 | dsh-client-ui-agent-preset | 预设选择（code/standard/minimal/cordis） | P1 |
| 模型选择 | dsh-client-ui-model-selection | 替换为只读「模型信息」（见 6） | — |
| 消息反馈 | dsh-client-ui-message-feedback | 点赞/点踩 + 反馈提交 | P2 |
| 轨迹视图 | dsh-client-ui-trajectory | 详情侧栏（完整工具轨迹/参数/结果） | P1 |
| 交付物 | dsh-client-ui-deliverables | 产出文件列表与直达 | P2 |
| 斜杠命令 | dsh-client-ui-commands | 输入框命令触发器 | P1 |
| 设置-通用 | dsh-client-ui-settings-general | 原生设置页 | P1 |
| 设置-插件 | dsh-client-ui-settings-plugins | 插件面板（转发 dsh plugin 命令，流式输出） | P2 |
| 设置-模型 | dsh-client-ui-settings-models | 锁定展示（见 6） | — |
| 主题 | dsh-client-ui-theme | 深色/浅色/跟随系统 | P1 |
| 布局 | dsh-client-ui-layout | 三栏自适应 + 自由窗口 | P1 |
| 本地化 | dsh-client-locale | 中/英 | P2 |
| 升级管家 | （macOS 薄壳版已实现） | 运行时升级中心（见 4.2，移植已验证设计） | P0 |

### 2.2 关键架构事实（全部实测确认）

通信协议（原生客户端要实现的全部）：

- 一元/应答调用：HTTP POST /api，Typert RPC 信封（InvocationDescriptor：精确命名参数 + 严格 codec 校验）
- 事件下行：/api/events.mux 与 /api/events.host 各一条只下行 WebSocket，客户端不上行应用数据；任一断开即连接代际失效、重建两条流
- 就绪握手：两条 WS 打开 + host.describe HTTP 调用成功 → onConnected，并发布 host 能力描述
- 会话增量：独立的 named-stream 协议（同连接承载）；投影帧 session/projection（整体值、schema 校验、last-wins）
- 信任围栏：/api 要求 Host 为 loopback 或 trustedHosts 成员（DNS-rebinding 防御）→ 本方案 Host 永远跑在本机 loopback，天然满足

Host 侧：

- 会话持久化于 ~/.dsh/sessions（按工作区分片），服务重启不丢；历史读取走 api-proxy history tail 分页
- SIGINT/SIGTERM 有界优雅停机（5 秒）→ 可被安全托管
- profile（~/.dsh/profiles/web）只引用 bundle 名，解析到 CLI 安装目录的 node_modules；用户插件在 profile 自己的 node_modules，升级不影响
- LLM 配置：dsh-llm-deepseek（baseURL/apiKeyEnv/models/thinking 全部可配）+ dsh-llm-pi-ai；凭据走 ctx.credentials（credentials.set/unset/describe RPC）

OpenHarmony 侧（来自 dsh-ohos-patch 2026-08 实测）：

- Node v24.13.0（hnp，HarmonyOS 官方构建）可跑完整 DSH：pnpm install 全量成功、bin/dsh --help PASS
- esbuild/oxc 均有 openharmony-arm64 WASM shim 变体，transform 可用；原生 ELF 不可在用户分区执行 → 只走 WASM 路线
- node-pty 无 prebuild → PTY 终端功能不可用（本期 Non-goal）

---

## 3. 总体架构

### 3.1 分层架构图

+---------------------------------------------------------------+
|                DSH Harmony（原生 App，ArkTS/ArkUI）              |
|                                                               |
|  +---------------------------------------------------------+  |
|  | UI 层：页面/组件（会话流、工具卡片、审批、设置、升级中心）      |  |
|  |   ArkUI 声明式 + ObservedV2 状态 + LazyForEach 虚拟滚动      |  |
|  +--------------------------+------------------------------+  |
|  +--------------------------+------------------------------+  |
|  | 视图模型层：SessionViewModel / ConnectionState /            |  |
|  |   ApprovalQueue / TodoGoalPlanStore（订阅投影帧）            |  |
|  +--------------------------+------------------------------+  |
|  +--------------------------+------------------------------+  |
|  | 协议适配层（Protocol Adapter，本方案核心资产）                 |  |
|  |  - transport：HTTP POST /api + WS 下行x2 + 重连/代际管理     |  |
|  |  - typert：RPC 信封编解码、命名参数、AbortSignal 取消          |  |
|  |  - projections：投影帧解析 → 状态分发（已知 key/通用降级）      |  |
|  |  - adapters：DshVersionAdapter 注册表（按 host 版本选择）      |  |
|  |  - capabilities：host.describe 能力协商 → UI 特性开关          |  |
|  +--------------------------+------------------------------+  |
|  +--------------------------+------------------------------+  |
|  | 运行时管理层（Runtime Manager，移植 macOS 版已验证设计）        |  |
|  |  - Supervisor：探测/拉起/守护 Host，就绪探测，崩溃退避重启     |  |
|  |  - Updater：盯 npm 发版 → 升级 → 冒烟 → 无感重启 → 回滚        |  |
|  |  - EnvironmentDoctor：Node/hnp/网络/磁盘体检与修复引导         |  |
|  +--------------------------+------------------------------+  |
+-----------------------------+---------------------------------+
                              | loopback: HTTP POST /api + WSx2
+-----------------------------+---------------------------------+
|  DSH Host（官方代码，黑盒资产，绝不修改）                          |
|  node(hnp) + @deepseek-ai/dsh（npm/npmmirror 安装）              |
|  dsh web --port 0 --host 127.0.0.1（端口从 stdout 解析）           |
|  profile: ~/.dsh/profiles/web（含本产品的锁定补丁层，见 6）         |
+-----------------------------------------------------------------+

### 3.2 Host 托管模型（鸿蒙关键决策）

鸿蒙三方 App 的沙箱对 spawn 任意子进程存在策略限制（2026-08-23 已由 SDK 源码证实，见附录 B），因此采用双轨托管：

| 模式 | 做法 | 适用 |
|---|---|---|
| Attach（默认） | App 启动时探测 127.0.0.1 端口段的健康 dsh（GET / + host.describe），健康则直接复用 | 用户已在 hnp 终端跑着 dsh；或已安装我们的常驻服务 |
| Guided Service（首启向导） | 首启向导引导用户在 hnp 终端执行一条我们生成的安装命令，安装「DSH Host 常驻服务」（ohos 下的 daemon 脚本 + dsh 运行时），此后开机自启，App 永远 attach | 大多数用户 |
| ~~In-App Spawn~~（已否定） | SDK 源码证实 childProcessManager 仅支持 ArkTS 同步子进程，无法拉起 node 二进制（附录 B，2026-08-23） | 除非未来官方开放受限进程能力，否则不再评估 |

双轨设计与 macOS 薄壳版 Supervisor 的「attach 优先、否则 spawn」策略同构，代码可平移。**移植清单必含 macOS 0.2.1 实战修复**：spawn 前重解析 dsh 路径（npm 升级重写 bin 链接的窗口期竞态）、ENOENT 每 3 秒重试最多 5 次、childEnv() 最小 PATH 增强（hnp 环境同样存在此问题）。

### 3.3 数据流（一次对话的完整链路）

用户输入 → POST /api session.send → Host 组装请求 → 指定模型（见 6）→ 流式响应 → events.mux 帧下推 → 协议适配层解码 → SessionViewModel 增量上屏；工具调用 → 投影帧 session/projection（工具卡片整体值）→ ToolCardStore → 卡片渲染；需要审批 → user-questions 事件 → ApprovalQueue → 原生弹层 → POST /api 应答；todo/goal/plan 变化 → 各自投影 key → 对应卡片实时刷新。

---

## 4. 随官方升级机制（核心章节）

### 4.1 升级的三个层面

官方发版 @deepseek-ai/dsh@x.y.z 之后：

- L1 运行时升级：npm 通道，小时级跟进，无需 App 发版——覆盖后端全部能力
- L2 协议契约：契约测试矩阵 + 版本适配器 + 能力协商——保证原生端不被 breaking change 打死
- L3 表现层：投影驱动的通用渲染 + 降级策略——新工具/新领域自动可渲染

### 4.2 L1：运行时升级管家（移植已验证的 macOS 设计）

- 发现：定时 npm view @deepseek-ai/dsh dist-tags（走独立 cache 目录；鸿蒙侧经 hnp npm，registry 用 npmmirror），启动时 + 每 6h（可配 1h/6h/24h）+ 手动
- 执行：npm install -g @deepseek-ai/dsh@<tag>（hnp 全局 prefix，无需提权），不动 profile 与用户插件
- 生效：SIGTERM 优雅停机 → 重新拉起/通知常驻服务重启 → 就绪探测（两条 WS + host.describe）通过 → UI 重连
- 冒烟与回滚：升级后 60s 内服务起不来（rc 版本可能有破坏性变更）→ 自动回装旧版本 → 通知用户；版本史保留最近 5 个版本可手动切换
- UI：设置内「运行时升级中心」——当前版本、可升级版本、升级日志、自动升级开关

### 4.3 L2：协议契约测试 + 版本适配器

这是原生方案区别于「WebView 薄壳」的最大工程投入，也是「随时升级」的保险：

1. 契约快照仓库（Node 工程，独立于 App）：对每个 dsh 版本启动真实 Host，录制：
   - host.describe 全量输出
   - 全部 RPC 端点的 InvocationDescriptor（参数名/schema）
   - 会话事件流样本（一次含工具调用/审批/todo/图像的标准对话，录制成 fixture）
2. 版本矩阵 CI：官方每发版自动跑 [新版本] x [当前 App 协议层]，产出兼容性报告（绿/黄/红）
   - 绿 → 升级管家放开该版本
   - 黄（新增端点/新增投影 key）→ 原生端自动降级路径覆盖，排期跟进专属卡片
   - 红（参数改名/语义变更）→ 写一个 DshVersionAdapter（纯映射层），App 发小版本
3. 运行时适配器注册表：adapters/vN.ts 按 host.describe 的版本信息选择；adapter 只做字段改名/信封转换，绝不掺业务
4. 能力协商：连接成功后以 host.describe 输出驱动 UI 特性开关（capability absent → 隐藏入口，不报错）

### 4.4 L3：投影驱动的通用渲染

- 已知投影 key（todo/goal/plan/工具卡片）→ 专属原生卡片
- 未知 key → 通用 JSON 卡片（折叠、语法高亮、复制）——官方任何新增领域立即可见、不阻塞
- 工具卡片按「工具名 → 卡片组件」注册表渲染；未注册工具名 → 通用卡片（参数表 + 结果 diff/文本 + 状态）
- 每张卡片的数据层 schema 校验失败 → 降级为原始 JSON 展示，绝不整页崩溃

### 4.5 WebView 逃生舱（兜底，非日常路径）

保留一个隐藏的「兼容模式」入口：内置 ArkUI Web 组件加载本地 Host 的官方 Web UI。仅当契约测试未覆盖的极端 breaking change 发生时，用户可临时切到官方 UI 保证可用，同时我们发适配版本。这保证最坏情况下产品仍可用，且该路径加载的仍是官方随 npm 升级的 UI（不分叉）。

---

## 5. 原生功能模块设计

### 5.1 页面与导航

主窗口（三栏，自由窗口/可最大化）：
- 左栏：会话列表（当前工作区分组 + 搜索 + 新建）
- 中栏：会话主视图（消息流 + 输入区）
  - 消息流：流式 Markdown、工具卡片、审批卡片、todo/goal/plan 卡片
  - 输入区：多行输入、附件、@引用、斜杠命令触发器、发送/中断、权限预设选择、Agent 预设选择、计划模式开关
- 右栏（可收起）：轨迹详情（选中工具调用的完整参数/结果）、子代理/任务面板

弹层：审批问答（ask_user_question：选项/多选/自由输入）
独立窗口：设置（通用/运行时升级中心/插件/凭据/账户占位）、工作流运行视图
系统级：通知（升级完成/审批等待/任务完成）、托盘/任务栏常驻（可选）

### 5.2 会话与消息流

- 消息模型：MessageItem[] 分片状态（ObservedV2），流式 delta 只更新尾部 item 的富文本缓冲，避免整列表重绘
- 虚拟滚动：List + LazyForEach，长会话（数千事件）内存平稳；滚动到顶触发 history tail 分页拉取
- 会话恢复：attach 已有会话走 history 分页 + 投影快照对齐 asOfSeq
- 中断：RPC 取消（Typert 原生 AbortSignal 语义）+ UI 立即冻结输入区

### 5.3 Markdown/代码渲染器（自研，工作量最大单体）

- Markdown → ArkUI 节点树的两遍解析器（块级：标题/列表/代码块/引用/表格；行内：粗斜/链接/行内码）
- 代码高亮：自研 tokenizer（TS/JS/JSON/YAML/Bash/Python/Md），流式期间高亮节流（150ms 批量重排）
- 图像：Image 组件 + 本地缓存；附件图像直读
- 官方消息内特殊语法（文件引用、折叠结果）走协议层识别后转原生组件

### 5.4 工具卡片框架

ToolCardRegistry：
- bash/execute → 命令行卡片（等宽字体、退出码、截断展开）
- read/write/edit → 文件卡片（路径、行号范围、diff 视图）
- grep/glob → 检索卡片（命中列表、计数）
- web_search → 结果卡片（标题/链接/摘要）
- subagent → 子代理卡片（状态、输出摘要）
- default → 通用卡片（参数 KV 表 + JSON 结果折叠展示）

每张卡片：运行中（进度/耗时）→ 完成（可展开详情至右栏轨迹）→ 失败（错误高亮 + 重试语义提示）。

### 5.5 审批与用户问答

- Host 下发 user-question 事件 → 全局 ApprovalQueue → 模态弹层（单选/多选/自由文本，带推荐项标记）
- 应答走 RPC 应答通道；排队期间输入区禁用并发对话
- 权限预设变化（ask→workspace-write 等）即时生效于下次工具执行

### 5.6 计划模式 / Todo / Goal

- 三者均为投影 key：plan.active、todo 列表、goal 快照 → 各自专属卡片，整体值刷新、无增量合并复杂度
- 计划审批：exit_plan_mode 触发全屏计划卡片（Markdown 渲染 + 批准/继续规划）

### 5.7 子代理 / Jobs / 工作流

- 子代理面板：代理树（父子关系）、状态（running/idle/ready）、send_message 追问输入、interrupt 按钮
- Jobs：任务列表 + 输出流式查看 + kill
- 工作流：阶段进度条（phase 标题）+ 阶段内代理计数 + 失败项定位

### 5.8 附件 / 引用 / 目录选择

- 附件：系统 FilePicker → 上传通道（RPC 附件端点）→ 消息内预览
- 引用：输入 @ 触发文件浏览（走 fs 检索 RPC）；消息内引用点击 → 定位文件
- 目录选择：优先 DirectoryPickerNative（系统 FSPicker）；不可用时降级 browse 模式（树形浏览 RPC）

### 5.9 设置中心

| 页 | 内容 |
|---|---|
| 通用 | 语言、主题、开机自启、端口策略、缓存管理 |
| 运行时升级中心 | dsh 版本、检查更新、自动升级开关、版本史/回滚、冒烟日志 |
| 模型信息 | 只读：指定模型名称、provider、上下文窗口、thinking 开关状态（见 6） |
| 插件 | 插件清单（pluginInventory RPC）+ 安装/卸载（转发 dsh plugin，终端式流式输出面板） |
| 凭据 | Asset Store 加密存储；API Key 录入/清除（credentials.set/unset）；为支付预留：凭证可由计费网关下发（见 7） |
| 账户（占位） | 后续支付阶段启用（见 7） |

---

## 6. 模型指定方案

### 6.1 锁定层级（配置层锁定，UI 层只读）

在产品 profile 的补丁层（~/.dsh/profiles/web/cordis.patch.yml，我们首启向导生成）固定：

- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    baseURL: <指定端点，由运行时管理器注入>   # 官方 API 或自建 OpenAI 兼容网关
    models: ['<指定模型ID>']                   # 白名单 = 唯一可选
    reasoningEffort: high
    thinking: enabled

- 若指定模型是 DeepSeek 官方 → 直接 dsh-llm-deepseek
- 若是第三方 OpenAI 兼容端点（含后续计费网关）→ 同一 provider 配 baseURL 即可，官方 adapter 原生支持
- API Key：不落明文，Asset Store 加密 → 启动 Host 时经受控环境变量注入（apiKeyEnv）
- UI：隐藏 model-selection 与 settings-models 的编辑能力，替换为只读「模型信息」页（P1 中完成）

### 6.2 与支付的关系（前瞻）

指定模型为「计费网关换发凭证」留好了位置：baseURL 指向我们的网关，网关鉴权用户订阅 → 转发官方 API → 凭证由第 7 节的 Billing 服务下发。用户无感、DSH 零改动。

---

## 7. 支付界面（后续阶段，本期只做架构预留）

> **2026-08-24 更新：本章占位设计已被完整商业化方案取代**——见 [COMMERCIALIZATION-PLAN.zh.md](COMMERCIALIZATION-PLAN.zh.md)（账号体系/模型订阅/云同步/支付双通道/合规清单）。§1.2 中「不做云同步、多用户」的 Non-goal 在 M5 商业化阶段解除（商业化层为纯增量，本地模式与 BYOK 永久保留）。

### 7.1 模块边界（本期定义接口 + 入口占位，不实现）

- AccountService：登录态、用户资料（后续：手机号/华为账号）
- BillingService：套餐、余额、用量、订单列表（后续：对接计费网关）
- PaymentProvider 支付抽象（后续实现）：
  - HuaweiIapKit：华为应用内购买（订阅制首选）
  - WeChatPayOhos：微信支付鸿蒙 SDK
  - AlipayOhos：支付宝鸿蒙 SDK

### 7.2 后续方案的商业模式假设（待定稿）

- 订阅制（月/年）或按量套餐 → 网关换发模型访问凭证（见 6.2）
- 设置页「账户」入口本期渲染为「即将上线」占位；协议层预留 billing.* RPC 命名空间（打到我们自己的云端，不走 dsh Host）

---

## 8. 技术选型与工程结构

| 维度 | 选型 | 理由 |
|---|---|---|
| IDE/SDK | DevEco Studio 26；compatibleSdkVersion 6.0.0(20)（HarmonyOS 6.0）/ targetSdkVersion 26.0.0（HarmonyOS 7） | 已定稿落地并编译验证；API 21+ 能力（如 HarmonyOS 7 悬浮窗）仅作增强，基础功能不依赖 |
| 语言/UI | ArkTS + ArkUI（Stage 模型） | 方案C 本体 |
| 状态 | ObservedV2/Trace + MVVM | 大列表细粒度更新 |
| 网络 | ohos.net.http（RPC）+ ohos.net.webSocket（下行x2） | 协议适配层自建重连/代际 |
| 持久化 | RelationalStore（会话索引缓存）+ Preferences（设置） | 真相在 Host（~/.dsh），端侧只做缓存 |
| 凭据 | Asset Store（硬件级密钥库） | 见 6 |
| JSON/校验 | 自研轻量 schema validator（对齐投影 wire schema） | L2 契约 |
| 构建/分发 | hvigor CLI（scripts/build.sh，环境配方见 knowledge-base/build-recipe.md）+ 自动签名已通；侧载起步 → 应用市场 | 已跑通签名 HAP 产出 |

工程结构：

dsh-harmony/
  entry/                        # 主 App
    src/main/ets/
      app/                      # UIAbility 入口、生命周期、窗口管理
      pages/                    # 主窗口/设置/工作流
      components/               # MessageList、ToolCard/*、ApprovalSheet 等
      viewmodel/                # 会话/连接/审批/投影 Store
      protocol/                 # 协议适配层（3.1，独立无 UI 依赖，可单测）
        transport/  typert/  projections/  adapters/  capabilities/
      runtime/                  # Supervisor/Updater/EnvironmentDoctor
      platform/                 # 通知、Asset、文件、深链
      common/
  contract-tests/               # Node 工程：版本矩阵契约测试（4.3）
    fixtures/                   #   录制的事件流样本
    matrix/                     #   dsh 版本 x 协议层报告
  docs/

protocol/ 与 runtime/ 零 UI 依赖，可在 DevEco 单测环境 + Node 侧 contract-tests 双侧回归，是升级保险的载体。

---

## 9. 路线图（v1.1：双速计划，2026-08-23 定稿）

> v1.0 的 M0-M5 单线人力排期（16 周）已作废。现行路线为双速：工期估算模型（假设、P50/P90、关键路径、不可压缩项）见 SCHEDULE-AND-DECISIONS.zh.md 第 3 节。

**分支策略**：git main = 壳版发布线（Web 组件加载官方 UI + Supervisor 托管，抢鸿蒙首发卡位）；feature/protocol-native = 协议原生线（本方案 3-5 章全部设计）。协议 fixture 录制（本机 Mac 自主）与壳版 UI 开发**真并行**；原生模块逐个合流替换壳内 Web 视图——壳即 4.5 节 WebView 逃生舱，一石二鸟。

| 阶段 | 工期 P50 | 交付 | 验收标准 |
|---|---|---|---|
| P0 链路 Spike | 3-5 天 | 协议 fixture 录制（本机 dsh web + Playwright）；ArkTS HTTP+WS 客户端编译+单测；模拟器 Web 组件加载 dsh web 跑通（端口转发方案验证）；hnp 常驻服务自启方式验证（真机） | 技术不确定性清零 |
| P1 Web 壳首发版 | 6-9 天 | 工程骨架+Web 组件+生命周期；Supervisor（attach 探测 __DSH_BOOT__ + 端口策略 + 首启向导 + 0.2.1 移植清单）；daemon 控制通道 + 升级管家 v1（手动升级+冒烟回滚）；托盘/通知/签名打包 | **模拟器+真机可安装可演示（鸿蒙首发卡位）** |
| P2a 协议适配层 | 4-6 天 | Typert 编解码+投影分发+重连代际+契约 fixtures 全量+单测（90% 覆盖目标） | 协议层 DevEco/Node 双侧回归通过 |
| P2b 原生会话体验 | 8-10 天 | 消息流/Markdown 渲染器（最大单体）/工具卡片框架/审批弹层 | 日常可用，原生界面替换壳版主视图 |
| P2c 功能完整 | 4-6 天 | todo/goal/plan/子代理/jobs/附件引用/目录选择/设置/主题 | 对照 2.1 清单 P0+P1 全绿 |
| P2d 升级体系 | 3-4 天 | 契约矩阵 CI+版本适配器+能力协商+自动升级 | 官方发版 24h 内适配闭环演练通过 |
| P2e 打磨发布 | 3-4 天 | 性能（万级事件会话）/异常恢复/本地化/分发 | 7x24 attach 稳定（代际重建覆盖） |
| P3 支付阶段 | 后续另立方案 | 第 7 节全量实现 + 计费网关 | — |

**全程 P50 约 7-9 周（首发壳版 2-3 周内交付）**。

---

## 10. 风险与对策

| # | 风险 | 等级 | 对策 |
|---|---|---|---|
| R1 | 鸿蒙 App 内无法 spawn node 子进程 | 已落定（原评级：高） | 2026-08-23 SDK 源码证实（附录 B）：childProcessManager 仅支持 ArkTS 同步子进程。双轨托管（Attach + Guided Service）为唯一主路线；残余不确定性收窄为 hnp 常驻服务自启方式（P0 真机验证项） |
| R2 | Typert 协议无公开稳定性承诺（developer preview） | 高 | 契约矩阵 + 适配器 + 能力降级 + WebView 逃生舱（4），四层防御 |
| R3 | ArkTS 严格类型与 wire 动态 JSON 冲突 | 中 | 协议层收口为 JsonValue discriminated union + 生成式类型；卡片数据层 schema 校验先行 |
| R4 | Markdown 流式渲染性能（长代码块） | 中 | 分片缓冲 + 节流重排 + 只高亮可视区（M4 专项） |
| R5 | node-pty 缺失 → 无嵌入式终端 | 低 | Non-goal；命令输出以卡片形式完整展示；跟进 dsh-ohos-patch 的 PTY 适配进展 |
| R6 | rc 版本破坏性变更导致升级失败 | 中 | 冒烟 + 自动回滚 + 版本锁定选项（已验证模式平移） |
| R7 | npmmirror 与官方 registry 的包差异（esbuild shim 等） | 低 | 升级管家 pin 住已验证镜像路由；契约测试含安装冒烟 |
| R8 | 鸿蒙 PC API 迭代（桌面能力仍在快速演进） | 中 | UI 层隔离平台能力到 platform/；最低 API 已定为 6.0.0(20)，模拟器（API 26）无法验证 20 行为差异——编译期 compatible 检查作 CI 门禁 + 运行时 canUse 探测 + MatePad Edge 真机回归三重保障；HarmonyOS 7 悬浮窗等新能力仅作增强 |

---

## 11. 测试与质量保障

1. 协议层单测（DevEco）：信封编解码、重连代际、投影分发、schema 降级——目标 90%+ 覆盖（升级保险的核心资产）
2. 契约矩阵（Node CI）：dsh 版本 x 协议层全组合冒烟 + fixture 回放（4.3）
3. UI 快照测试：关键卡片（bash/edit/审批/todo）渲染快照，防样式回归
4. 端到端剧本：Playwright 驱动官方 Web UI 与原生端同剧本对照（同一 Host，双客户端一致性）
5. 升级演练：每次官方发版，在测试机演练「升级→冒烟→回滚」全链路
6. 稳定性 soak：7x24 attach + 周期性代际断连注入

---

## 12. 结论

方案C 的可行性建立在四个已验证的事实上：一，DSH wire 协议是明确的公开边界且官方为非浏览器壳预留了接入设计；二，会话状态以 schema 校验的整体值投影下发，天然适配「通用渲染 + 降级」；三，DSH 后端已在 OpenHarmony arm64 实测跑通（Node hnp + esbuild WASM）；四，「运行时升级管家」模式在 macOS 薄壳版上已经落地验证，可直接平移。

因此：全原生 ArkUI 界面 + 协议适配层 + npm 通道运行时升级三者组合，可以在不 fork 任何官方代码的前提下，实现「原生体验」与「随官方随时升级」兼得。R1（App 内进程托管）已于 2026-08-23 落定（否定 In-App Spawn，双轨托管即主线）；最大工程投入是协议契约体系（4.3），它同时是本产品相对社区桌面方案的核心壁垒——竞品调研（COMPETITIVE-RESEARCH.zh.md）证实：协议原生路线全网无先例，鸿蒙赛道完全空白，头部竞品 anywhere-labs（18.7k star）的「锁定固定版本」模式正是我们升级模型的打击面。

---

## 附录 A：协议稳定性评估（基于官方发版数据，2026-08-22 核实）

### 发版节奏（npm registry 实测）

| 日期 | 版本 |
|---|---|
| 2026-08-10 | 0.0.1-rc.1（首发） |
| 2026-08-11 | 0.0.1-rc.2 |
| 2026-08-12 | 0.0.1-rc.5 |
| 2026-08-13 | 0.1.0-rc.2 / rc.3 / rc.6 |
| 2026-08-17 | 0.1.0-rc.7 |
| 2026-08-19 | 0.1.0-rc.8 |
| 2026-08-21 | 0.1.1-rc.1 / rc.2 |

**11 天 10 个版本**（约每日一发）；项目处于 0.x-rc（developer preview），0.x 阶段 SemVer 惯例允许 minor 位承载破坏性变更（0.0.1→0.1.0→0.1.1 两次 minor 跳位均在一周内）。

### 判断

1. **增量变更（新增端点/投影 key/事件）**：随每个功能版本必然发生（概率 ~100%）。已被 4.4 通用渲染 + 能力协商设计为零成本吸收（未知 key 降级显示，不阻塞不崩溃）。
2. **破坏性变更（改名/语义变化/移除）**：rc 阶段**高频**——依据：官方文档明确 preview 期会有破坏性变更；源码可观察到协议迁移正在进行中（api-remotes 中「legacy API Proxy 方法与已迁移 Typert 方法共存」）；各协议包普遍存在「Deferred Work」清单。估计：每两周窗口内消费面被波动的概率 40–60%；一个季度累计接近必然。
3. **1.0 之后**：官方已内建契约纪律（严格 codec 校验、stateVersion 失效锚点、「撤回已观察的严格定义会显式失败而非静默弱化」），且浏览器/进程内/worker 三种传输消费者共存形成自我制衡——破坏性变更预计降至个位数百分比/版本。

### 对目标的影响

- 若协议长期不变：第 4.3 节契约体系退化为纯回归守卫，M3 由 3 周缩至约 1 周，维护成本趋零——目标全部可达。
- 若协议如预期频繁演进：破坏性变更的影响被四层防御限定在「局部降级 + O(天) 适配」范围，目标仍可达，代价是持续的协议适配人力（预估每两周 0.5–2 人日）。

**结论：不应以「协议冻结」为架构假设下注；应按「增量必然、破坏高频但有界」建模。契约测试体系是本方案中性价比最高的保险，不可因乐观而裁剪。**

---

## 附录 B：R1 风险调研进展（2026-08-23，本地 SDK 源码判定）

本地 SDK 26.0.0 的 @ohos.app.ability.childProcessManager.d.ts 源码阅读结论：官方子进程 API 仅支持启动 **ArkTS 源码子进程**（srcEntry 为 .ets 文件），且子进程只支持同步 ArkTS API、不能拉起任意二进制（node）。因此 3.2 节的 In-App Spawn 路线基本被否定，**双轨托管（Attach + Guided Service）确定为唯一主路线**，M0 验证项相应收窄为：hnp 终端常驻服务的开机自启方式。

同日竞品调研（见 COMPETITIVE-RESEARCH.zh.md）：全网不存在任何鸿蒙版 DSH 客户端，先发窗口以月计；头部桌面竞品 anywhere-labs（18.7k star，Electron 壳 + 锁定固定版本）因 Electron 在鸿蒙不可用，进入鸿蒙需整体重写壳。协议原生路线全网无先例——既是独占壁垒也是无先例可抄的风险。