DSH Harmony 项目交接文档（HANDOVER）

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

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

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

阅读顺序（按需）：

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

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

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 已挂载（mcpharmonyos*），含 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/

两条工作线

#	决策	依据/备注
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/ 点号形式 + 双 WS 下行
D6	指定模型：profile 层锁定 provider/model，UI 只读（未实施）	见方案 §6
D7	支付：后续阶段，本期只留接口占位	见方案 §7

线	分支	状态	下一棒
壳版（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. 环境事实与操作配方

构建

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）
运行期间全自动化：mcpharmonyosdevice_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. 工作规则（新会话必读纪律）

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

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

壳版线：Supervisor/首启向导收尾 → 模拟器部署验证（install+launch+screenshot）→ 里程碑 commit 到 main
协议线 P2a-m2：端点清单枚举（从 dsh 安装包源码提取全部 RPC）→ mock LLM 会话事件录制（本地 OpenAI 兼容假端点 + baseURL 注入，零 token）→ ArkTS 协议层骨架 + 单测
待用户动作：确认 CASE-2 修复生效（刷新页面）；OPEN-5（MatePad Edge 真机接入验证 compatible=20）
后续：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 卡片创建瞬间换字；初始

HANDOVER.md 16 KB Cronologia Originale