# DSH Harmony 项目交接文档（HANDOVER）

> 目的：新会话开工前先读本文，10 分钟建立完整上下文。最后更新：2026-08-23 深夜（会话：dsh-harmony（plan) (mcp验证)）

---

## 0. 一句话使命与阅读顺序

**使命**：在 HarmonyOS PC 上做 DSH（DeepSeek Harness）客户端——双速路线：先出 Web 壳版抢鸿蒙首发卡位，协议原生版并行分支推进，最终全原生 ArkUI + 永远跟随官方升级。

阅读顺序（按需）：
1. 本文（全局状态与规则）
2. DEVELOPMENT-PLAN.zh.md（技术方案 v1.1，含状态板）
3. 干活前：knowledge-base/ 里与你任务相关的文件

---

## 1. 关键决策记录（已定稿，勿重议）

| # | 决策 | 依据/备注 |
|---|---|---|
| D1 | 双速路线：壳版先行（main 分支）+ 协议原生并行（feature/protocol-native 分支） | 竞品 anywhere-labs 18.7k★ 证明壳路线有市场；鸿蒙赛道完全空白 |
| D2 | 命名：工程目录 dsh-harmony；bundleName com.dotouch.dshharmony；vendor dotouch；显示名 DSH Harmony | 已落地编译验证 |
| D3 | API 版本：compatibleSdkVersion 6.0.0(20) / targetSdkVersion 26.0.0 | API 20 = HarmonyOS 6.0（用户要求支持鸿蒙 6 以上）；hvigor 要求 API 10-25 用 X.Y.Z(API) 格式 |
| D4 | 全程 AI 开发；工期 P50 约 7-9 周（壳版 2-3 周内首发） | 估算模型见 SCHEDULE-AND-DECISIONS.zh.md |
| D5 | 协议原生 = 方案C：只消费官方 wire 协议，零分叉官方代码 | 协议已实证：POST /api/<method> 点号形式 + 双 WS 下行 |
| D6 | 指定模型：profile 层锁定 provider/model，UI 只读（未实施） | 见方案 §6 |
| D7 | 支付：后续阶段，本期只留接口占位 | 见方案 §7 |

## 2. 当前状态（2026-08-23 深夜）

### 已就绪的基础设施
- ✅ 工程 /Users/eastudio/DevEcoStudioProjects/dsh-harmony：改名+API 配置+签名全部落地，scripts/build.sh 可产签名 HAP（已验证）
- ✅ 本地 git：main（基线 2913ad6）+ feature/protocol-native（P2a-m1 提交 f3fefca）
- ✅ MCP 工具链：harmonyos-mcp 0.3.0 已挂载（mcp__harmonyos__*），含 build/install/launch/screenshot/ui_dump 等
- ✅ 模拟器：DSH_MB6 实例（HarmonyOS 6.0.0.48 / API 20 / 2in1），hdc 127.0.0.1:5555，完整闭环已验证（install→launch→app_state 前台确认）
- ✅ 协议实证（P2a-m1）：信封/端点格式/WS 帧结构全部破解，fixture 在 contract-tests/fixtures/

### 两条工作线
| 线 | 分支 | 状态 | 下一棒 |
|---|---|---|---|
| 壳版（P0/P1） | main（WIP 未提交） | 另一会话开发中：Supervisor.ets + Index.ets(+206行) + INTERNET 权限已存在 | 里程碑 commit 到 main；模拟器部署验证 |
| 协议原生（P2a 起） | feature/protocol-native | m1 完成 | m2：端点清单枚举 + mock LLM 会话录制 + ArkTS 协议层骨架 |

### 已知未解决问题
- CASE-1（cases.md）：deveco 会话模型选择不可用——服务端全绿，疑客户端重连不重放事件；用户判定非严重，观察中
- CASE-2（cases.md）：语音插件浅色模式黑底——**已修复**，等用户刷新验证

## 3. 文件地图（全部精确路径）

```
工作区 /Users/eastudio/Documents/EvanAgent/dsh-harmony/
├── DEVELOPMENT-PLAN.zh.md      # 技术方案 v1.1（§0 状态板 + 双速路线图）
├── SCHEDULE-AND-DECISIONS.zh.md # AI 工期估算 + 三项决策依据
├── COMPETITIVE-RESEARCH.zh.md  # 竞品调研（anywhere-labs 18.7k★ 等）
└── knowledge-base/
    ├── README.md               # 库索引 + 更新纪律
    ├── build-recipe.md         # CLI 构建配方（Java/SDK 环境变量）
    ├── emulator-notes.md       # 模拟器约束（账号鉴权）+ MCP 工具映射
    ├── local-sdk-api-map.md    # SDK API 权威映射（含子进程限制结论）
    ├── huawei-docs-catalog.md  # 官方文档 URL 目录（SPA，需浏览器读）
    ├── cases.md                # 问题案例库（根因+教训）
    ├── ecosystem-tracker.md    # 竞品数据快照
    ├── fetch-ecosystem.py      # 生态数据刷新脚本
    └── open-questions.md       # 待用户判断问题清单

工程 /Users/eastudio/DevEcoStudioProjects/dsh-harmony/
├── scripts/build.sh            # 一键构建签名 HAP
└── contract-tests/
    ├── capture/probe.mjs       # 协议探测脚本（Node 22+，零依赖）
    ├── fixtures/               # P2a-m1 录制的协议 fixture
    └── capture-workspace/      # 录制用 dsh web 实例的工作目录（空）
```

## 4. 环境事实与操作配方

### 构建
```bash
cd /Users/eastudio/DevEcoStudioProjects/dsh-harmony && bash scripts/build.sh
# 产出 entry/build/default/outputs/default/entry-default-signed.hap
# 坑：必须注入 DevEco 自带 JAVA_HOME + DEVECO_SDK_HOME（脚本已固化）；工程目录在工作区外，沙箱需提权
```

### 模拟器与部署
- 模拟器实例 DSH_MB6（API 20）。**启动/重启需用户从 DevEco Device Manager 操作**（账号鉴权，CLI 走不通，见 emulator-notes.md）
- 运行期间全自动化：mcp__harmonyos__device_list / install / launch / app_state / screenshot / ui_dump / wait_for_ui
```

### 协议探测（P2a 用）
```bash
# 拉起录制实例（独立端口，勿动 3080 的 GUI）
cd /Users/eastudio/DevEcoStudioProjects/dsh-harmony/contract-tests/capture-workspace && dsh web --port 3099 &
DSH_BASE=http://127.0.0.1:3099 node ../capture/probe.mjs
```

### 沙箱规则（重要）
- 本会话沙箱 workspace-write：写 /Users/eastudio/Documents/EvanAgent 内无需提权；**写工程目录/DSWorkSpace/~/.dsh 等工作区外路径必须 sandbox_permissions: danger-full-access + 一句话理由**（用户已习惯批准，授权先例充分）
- bash 的 ps 命令被沙箱禁（Operation not permitted），查进程需提权

## 5. 工作规则（新会话必读纪律）

1. **先查知识库再动手**：knowledge-base/ 没有的查官方文档；官方不明的记 open-questions.md 找用户判断，不得猜
2. **git 纪律**：只提交自己负责的路径（壳版线：entry/ 壳相关；协议线：contract-tests/ + protocol/ ets 目录），绝不 git add -A（工作区有另一任务的 WIP）；里程碑即 commit
3. **会话开始先跑**：python3 knowledge-base/fetch-ecosystem.py 看 dsh 官方是否发新版（协议契约相关）；git log + git status 看另一线进展
4. **官方协议事实**（已实证，勿重验）：POST /api/<method>（点号形式）；信封 {type:client-request|server-response, rpcId, method, payload}；WS 下行 /api/events.mux + /api/events.host 帧为 server-request 信封；host.describe 返回能力描述（version/provider/model/attachedSessions）
5. **协议适配层设计约束**（CASE-1 教训）：重连后必须主动拉取目录/设置快照，不能依赖事件重放（官方明确 no replay after reconnect）
6. **升级管家移植清单**：对照 macOS dsh-desktop 0.2.1（spawn 前重解析路径 + ENOENT 重试 + childEnv PATH 增强）

## 6. 下一步待办（按优先级）

1. 壳版线：Supervisor/首启向导收尾 → 模拟器部署验证（install+launch+screenshot）→ 里程碑 commit 到 main
2. 协议线 P2a-m2：端点清单枚举（从 dsh 安装包源码提取全部 RPC）→ mock LLM 会话事件录制（本地 OpenAI 兼容假端点 + baseURL 注入，零 token）→ ArkTS 协议层骨架 + 单测
3. 待用户动作：确认 CASE-2 修复生效（刷新页面）；OPEN-5（MatePad Edge 真机接入验证 compatible=20）
4. 后续：P1 壳版首发 → P2b 原生会话体验（Markdown 渲染器是最大单体）→ 商业化（指定模型+支付，方案已预留）

## 7. 常见坑速查（都已踩过，勿重复）

| 坑 | 解法 |
|---|---|
| hvigor 报 Unable to locate Java Runtime | 注入 DevEco 自带 JBR（build.sh 已处理） |
| compatibleSdkVersion 写 "20" 报 Specification Limit Violation | API 10-25 必须写 "6.0.0(20)" 格式 |
| npm 装包 EPERM（~/.npm root 属主） | 用 --cache /tmp/xxx 独立缓存 |
| 模拟器 CLI 启动报需登录账号 | 死路，走 Device Manager GUI 启动 |
| Emulator -license accept 不能持久化全部协议 | 死路，勿再试 |
| yes \| cmd & 挂住 bash 会话 | 用 nohup bash -c 完全脱离 |
| macOS 无 timeout 命令 | 用 (cmd & sleep N; kill) 模式 |
| run_code 长命令间歇性 description 丢失报错 | 拆小重试；写文件用 write 工具 + 数组拼接（勿用模板字符串） |
| 华为文档站 SPA 抓不到正文 | 浏览器阅读 + 本地 SDK d.ts 为权威 |
| DSH web 插件主题变量拼错不报错 | 对照 cases.md 里的官方 token 清单 |

---

## 附：本会话完成事件时间线（2026-08-23）

方案调研（竞品/协议/工期）→ 三项决策落地（改名/API/双速）→ 构建链打通（build.sh + 签名）→ git 双分支 → P2a-m1 协议实证（f3fefca）→ MCP 工具链接入（harmonyos-mcp）→ 6.0.0 镜像下载+DSH_MB6 实例 → 完整部署闭环验证 → 修复语音插件浅色主题 bug → 立案 CASE-1 → 本交接文档

---

## 附：2026-08-23 深夜·安装包会话增量

- **milestone-3（b74e93b）**：真机安装体验包完成。host+port 可配置、窗口标题修复、rport 隧道模型落地（LAN 直连被官方禁止，CASE-3）、引导页 15s 自动重连（已验证）
- 交付物：工作区 dsh-harmony/dist/（DSH-Harmony-1.0.0-arm64.hap + INSTALL-GUIDE.zh.md）
- 脚本：setup-device.sh（一键装机+隧道+启动，--fresh 切独立实例 3099）、dev-server.sh（隔离工作区实例）
- 待用户：真机（MatePad Edge/PC）走完安装流程反馈体验；图标仍为模板默认（正式版待设计）

## 附：2026-08-24 凌晨·真机安装通关会话增量

- **milestone-4（24ac231）**：真机安装全链路打通（设备 6DP0225C08000520 运行中）
- 路径：AGC 手动建调试 Profile（证书 auto_debug_19772439.cer + 真机 UDID）→ .p7b 换入 build-profile → 重建安装
- 重大能力沉淀（CASE-7）：CDP 浏览器自动化全配方（登录态引导/iframe 穿透/真实事件/键盘兜底），未来 AGC 操作均可复用
- 用户侧事实：华为账号为企业认证（深圳大方无隅科技）——上架应用市场无账号门槛
- 自动化 Chrome 可能还在运行（--user-data-dir=/tmp/agc-automation，调试口 9222），闲置可关

## 附：2026-08-24·品牌替换会话增量

- **web 端**：dsh-brand-client 插件上线（3099 验证全绿：字母标双插槽/favicon/title 守卫/官方文案清零）；官方品牌经 profile 补丁同 id 重声明停用（CASE-8 全配方）。**用户 3080 GUI 需重启生效**
- **macOS 桌面端**：DSH Desktop 0.2.2 重建（icns+托盘字母标，dist/DSH-Desktop-0.2.2-arm64.dmg），需重启 App 生效
- 遗留：鸿蒙 App 图标仍为鲸鱼版（违反侵权规避清单），待换 assets/logo/exports/icon-1024

## 附：2026-08-24·DoTouchAI 命名会话增量

- 命名定稿落地（依据 assets/store/monetization-design.zh.md 商标分析）：应用显示名 **DoTouchAI**（备选 Agent鸿蒙端仅兜底），品牌背书 **智价云**（kailin 标，assets/logo/appicon/）
- **web 端**（dsh-brand-client v0.1.3，3099 全绿）：kailin 标双插槽/title/favicon/文案全部 DoTouchAI，旧品牌清零
- **鸿蒙端**：显示名与窗口标题已改 DoTouchAI，图标换 kailin 标（白底+透明前景分层），模拟器部署验证通过（自动重连正常）
- **macOS 桌面端**：改名操作被用户拒绝，保持 DSH Desktop 原名——如需改名请明确指示
- 3099 验证实例运行中；3080 主实例重启后生效

## 附：2026-08-24·会话冲突排查与分工（02:08）

- **撞车事件**：DoTouchAI 改名被两个会话同时执行（string.json 双改、构建重复）。结果一致无损坏，已对齐
- **分工边界（后续会话遵守）**：
  - 鸿蒙工程（strings/图标/构建/部署/深色资源）→ 命名会话收尾（dark/ 目录为其 WIP，kailin 深色适配，勿动勿提交他人文件）
  - web 品牌插件（DSWorkSpace/dsh-brand-client）→ 品牌会话独占，v0.1.4 DoTouchAI 已全绿（title/mark×2/文案/旧名清零/无插件错误）
  - macOS 桌面端改名被用户否决，保持 DSH Desktop
- **冲突排查方法沉淀**：读文件前先 stat mtime；编辑报 file changed since read = 有会话正在动同一文件，先重读再决定，勿盲目重试；构建产物 mtime 突新 = 他会话正在部署，让行

## 附：2026-08-24·C 版定稿会话增量（02:55）

- **Logo 终稿**：DoTouchAI_icon_C_1024.png（dotouchai_logo/ 目录，深蓝紫底+亮蓝主图形），三端已统一（milestone-6）
- 鸿蒙：分层/启动/深色图标全换 C 版，真机已部署验证（标题 DoTouchAI + Web 加载正常）
- web：插件 v0.1.5（C 版圆角标 mark/favicon），3099 验证绿
- macOS：DoTouchAI 0.2.4（C 版圆角 icns + 亮度剪影托盘），dist/DoTouchAI-0.2.4-arm64.dmg
- **新机品牌未更新的根因**：3080 主进程是 22:57 启动的老进程（品牌插件之前）→ App 内网页内容为官方品牌。**须重启 3080 服务**（AI 不能自杀宿主，用户操作）后 App 内即刻变 DoTouchAI
- 与命名会话的图标分歧：milestone-5 的消息块图标被用户否决，C 版为准

## 附：2026-08-24·boot 闪屏品牌修复（03:10）

- 问题：进入页面瞬间闪现 HARNESS（boot 卡片在插件 apply 之前渲染，apply 期替换来不及）
- 解法（dsh-brand-client v0.1.6）：替换逻辑提前到**脚本顶层执行**（HTML 解析期即装 MutationObserver），boot 卡片创建瞬间换字；初始 <title> 闪变同修；boot 卡片移除后观察器自动撤退（不耗运行时性能）
- 覆盖文案：HARNESS→DoTouchAI、Loading plugins…→正在启动 DoTouchAI…、Failed to load plugins→插件加载失败
- 验证：CDP 独立 tab（避开另一会话的 AGC 操作）导航后 150ms×22 高频采样，harnessFlash=false / dotouchaiSeen=true / title=DoTouchAI
- 注意：自动化 Chrome 被上架会话占用中（AGC 页面），共用时开独立 tab 且用完关闭

## 附：2026-08-24·上架材料收尾与会话统一（版本管理）

- **命名统一**：全项目显示名统一为 **DoTouchAI**（连写），修正早期「Dotouch AI」带空格写法——覆盖 `assets/store/` 全部文档 + 本交接文档早期「命名会话增量」段落（已 sed 全局替换，无残留）
- **上架材料交付**（`assets/store/`，均已定稿并加版本头）：
  - `appgallery-listing.md` v3.0 — 上架文案（DoTouchAI 定名 + 上架前核对进度表）
  - `promo-copy.zh.md` v2.0 — 推广文案
  - `monetization-design.zh.md` v2.0 — 商业化设计（与 `dsh-harmony/COMMERCIALIZATION-PLAN.zh.md`、`PRICING.zh.md` 互补）
  - `privacy-policy.zh.md` / `user-agreement.zh.md` v1.0 — 隐私政策/用户协议模板
  - `launch-checklist.zh.md` v1.1 — 上架执行时间线
  - `MIT-LICENSE.txt` + `about-page-copy.md` — 开源合规物料（DeepSeek Harness MIT 全文 + 关于页文案）
  - `screenshots/01/02/03` — 改名后重拍的 3 张交互截图
  - `CHANGELOG.md` — 版本记录（单一事实源，可回溯）
- **版本管理约定**：`assets/store/` 文档采用 `v<major>.<minor> + 日期 + 摘要` 版本头，历史见 `CHANGELOG.md`；工程侧仍以 git milestone 为准
- **遗留待办**（详见 `appgallery-listing.md` 上架前核对表）：
  1. MIT 关于页工程落地（内容已备，`about-page-copy.md`，待接）
  2. 隐私政策/用户协议托管到 kailin.com.cn
  3. 完全干净截图：3080 主进程须重启（品牌插件才生效）后，用全新空工作区重拍
- **分工边界重申**：本会话只负责 `assets/store/` + `assets/logo/`（文档/合规/素材），不碰鸿蒙工程（dark/ 为命名会话 WIP）、web 品牌插件（品牌会话）、macOS 工程