鸿蒙桌面封装fellow99/deepseek-harness-harmony

| 英文

DeepSeek Harness HarmonyOS 桌面版

基于“Electron-on-HarmonyOS”运行时（harmonypc-electron，Electron 37 / Node 22.17.0）为 deepseek-harness 构建的 HarmonyOS 桌面封装 —— 在 HarmonyOS 设备上的 Electron 主进程中运行 dsh Host（带 webserver），渲染进程同源加载 dsh Web UI，100% 复用 dsh Web UI。

版本：0.1.5 · 状态：✅ 已在设备上验证 —— HarmonyOS 6.1.0.135（API 24），Electron 37 / Node 22.17.0，dsh Web UI 正常运行（核心聊天 / agent / 工具调用 / Web UI 均可用）。完整工程规划与最终实现记录见 docs/工程规划.md。

当前版本

| 字段 | 值 |
|---|---|
| versionName | 0.1.5 |
| versionCode | 1005 |

来源：AppScope/app.json5。versionCode 必须是数字，且每次提交 AppGallery 时都必须严格递增 —— 参见 AppGallery 提交。

这是什么

DeepSeek Harness（dsh）是 DeepSeek AI 开发的开源 agent harness，基于“一切皆插件”架构（由 Cordis 驱动）；其原生入口是 dsh web（浏览器 Web UI）。

本项目将 dsh Web UI 封装在原生 HarmonyOS 桌面外壳（Electron-on-HarmonyOS 运行时）中，100% 复用 dsh 前端，使该 agent harness 在 HarmonyOS 设备上像一等桌面应用一样运行。它不是一个指向 localhost 的“薄封装 dsh web”外壳，而是基于 dsh 现有架构构建的一等桌面应用，对标 deepseek-harness-desktop。

核心设计

dsh 已完成其 Host/Client 拆分，并且其 webserver 同时提供 SPA dist 和 /api。因此，本项目采用进程内 Host + webserver + 同源数据平面：

┌─ HarmonyOS HAP ─────────────────────────────────────────────────┐
│  electron module (entry): EntryAbility boots Electron-on-HarmonyOS│
│  web_engine module (HAR): ArkTS bridge layer + resfile carries dsh│
│         ┌─ Electron main process (Node.js, also hosts dsh Host)─┐│
│         │  main.js: extract dsh-dist.tar.gz → runProfile('desktop')│
│         │    ├─ webserver ← 0.0.0.0:, serves dist+/api│
│         │    ├─ apiProxy  ← RPC gateway                         │
│         │    └─ connection ← /api + WebSocket registration      │
│         │  once ready: loadURL(http://:/)         │
│         └────────────────────▲──────────────────────────────────┘│
│                              │ same-origin (no CORS/auth) + Host header rewrite│
│         ┌────────────────────┴──────────────────────────────────┐│
│         │ Renderer: loadURL(LAN IP) ← same-origin               ││
│         │   standard dsh Web UI (WebApiClient: fetch /api + WS) ││
│         └───────────────────────────────────────────────────────┘│
└───────────────────────────────────────────────────────────────────┘

关键点：渲染进程以同源方式加载——零 CORS、零认证、零自定义协议、零 IPC 载体——复用 dsh 现有的 WebApiClient（HTTP 上行 + WebSocket 下行），零上游改动（仅 6 个补丁）。

与桌面端的差异（HarmonyOS 特定适配，见 docs/工程规划.md §18）：

- HarmonyOS NEXT 将渲染进程的访问隔离到 127.0.0.1（回环网络隔离）→ webserver 绑定 0.0.0.0，渲染进程通过局域网 IP 连接，内嵌渲染进程的出站请求在离开会话前将 Host/Origin 重写为 127.0.0.1:，从而通过 dsh 仅限回环的特权方法防护（安全语义不变——其他局域网设备仍会收到 403）。
- HarmonyOS 沙箱禁止符号链接（EACCES）→ dsh profile 回退到 cpSync 递归复制（补丁）。
- os.homedir() 返回沙箱外目录（EPERM）→ 主进程在启动前将 HOME 指向沙箱可写的 userData 目录。

MVP 能力

- ✅ dsh Web UI 在窗口中运行（100% 复用 dsh 前端）
- ✅ 会话持久化 / 全文搜索（better-sqlite3，Electron 37 / Node ABI v138 aarch64 产物，由 collect-dsh 注入）
- ✅ 插件市场（内置 dsh-market）
- ✅ 窗口状态持久化（最大化 / 边界恢复）+ F11 全屏切换
- ⚠️ 图片附件校验/缩略图（sharp 纯 JS 桩，空操作）
- ❌ 终端（bash 工具，node-pty 无 aarch64 产物）
- ❌ 进程沙箱（koffi / landlock）

（第二阶段：系统托盘、无边框窗口、开机自启动；原生文件选择器复用 dsh 标准前端目录浏览器）

目标平台与分发

- 平台：HarmonyOS 2in1 / 平板（deviceTypes: ["2in1", "tablet"]）
- 分发：用于开发的本地调试签名 HAP（DevEco 自动签名 + 华为证书）以及 AppGallery 提交——使用华为签发的发布证书 + 发布 profile 构建的发布签名 App Pack（.app）（见 AppGallery 提交）。自动更新尚未实现。

技术栈

- Electron-on-HarmonyOS（harmonypc-electron，Electron 37 / Node 22.17.0）——原生 SO + ArkTS 桥接层（aki / adapter / addon + libshim.a）
- ArkTS / ArkUI（Stage 模型，web_engine HAR 桥接：约 46 个 Adapter + 约 44 个 AdapterBind）
- deepseek-harness（dsh，同级目录 ../deepseek-harness，非子模块，源码引用）——当前构建基于 dsh-v0.1.5-rc.2；其补丁位于 patches/dsh-v0.1.5-rc.2/
- dsh-market（同级目录 ../dsh-market，npm 包 dshmarket，内置插件市场）
- hvigor / DevEco Studio（HAP 构建 + 签名）

开发

集成方式
- 运行时复制：harmonypc-electron 是一个同级的 HarmonyOS 项目（不是 npm 包）；collect-runtime.mjs 在构建时将其 electron + web_engine 模块 + 3 个 SO 物理复制到本项目（同级布局，产物嵌入），并注入 libc++_shared.so。
- 源码引用：dsh 和 dsh-market 是同级目录的源码引用（不是子模块），通过 patch + build + 产物收集的方式消费。
- 宿主集成：src-main/main.js 动态导入 dsh 的 runProfile（apps/cli 构建产物），在进程内托管 dsh Host（webserver 绑定到 0.0.0.0），返回 { ctx, shutdown, port, url } 句柄。
- 同源数据平面：渲染进程通过 loadURL(http://:/) 同源加载 dsh Web UI，复用 WebApiClient —— 零 CORS、零鉴权、零新增载体。
- desktop profile：profiles/desktop/（dsh.profile.bundles = [dsh-base, dsh-web-app, dshmarket]，cordis.patch.yml 覆盖 web-runtime.printUrl: false、webserver.host: 0.0.0.0），运行时复制到 $DSH_HOME/profiles/desktop。

构建流程（四个阶段 + 6 个补丁）

dsh 依赖 Node 内部 API（HMR、原生目录对话框），并与 HarmonyOS 沙箱冲突（symlink、loopback 隔离），因此必须先应用 6 个补丁（幂等 —— --reverse --check 检测到已应用则跳过）：

流水线为四个阶段（⓪–③），随后是本地构建 + 签名步骤（④）。阶段 ⓪ 是运行时同步：它强制复制上游运行时并重新应用本应用自身的定制（prune + overlay），因此它必须始终是第一个运行的东西。

⓪ sync runtime + re-apply app customizations: copy ../harmonypc-electron's electron + web_engine
modules + 3 SOs + libc++_shared.so, prune unwanted upstream files, then overlay runtime-overlays/
node scripts/collect-runtime.mjs

① build dsh: clean workspace residue → apply 6 patches → pnpm build host/client/web → build ../dsh-market
node scripts/build-dsh.mjs

② collect dsh artifacts: pnpm deploy materialize → fill packages → sharp stub → better-sqlite3 injection → web dist + profile + dshmarket
node scripts/collect-dsh.mjs

③ compress dsh-dist into dsh-dist.tar.gz (--format=ustar, ~143MB, streaming decompression at runtime)
tar -czf web_engine/src/main/resources/resfile/resources/app/dsh-dist.tar.gz --format=ustar -C . dsh-dist

④ build + sign (dedicated entry points; see "Signing" and "Run")
powershell -ExecutionPolicy Bypass -File scripts\build-debug.ps1      # debug  (default: -Task Hap)
powershell -ExecutionPolicy Bypass -File scripts\build-release.ps1    # release (default: -Task App)

运行时 overlay + prune（应用定制）
阶段 ⓪（scripts/collect-runtime.mjs）会对上游运行时（../harmonypc-electron/ohos_hap → electron/ + web_engine/）执行整目录的 cpSync(..., { recursive: true, force: true })，覆盖到本项目之上，因此任何之后没有被重新应用的应用定制都会被静默还原。有两种机制用于保留本项目自身的更改：

- 裁剪（阶段 1b）——删除本应用不使用的 4 个上游蓝牙文件：BluetoothAdapter.ets、BluetoothLowEnergyAdapter.ets 及其两个 Bind.ets jsbinding。每个文件的存在性都会先被断言：文件缺失是硬失败，表明上游结构发生了漂移，必须重新评估（绝不静默跳过）。
- 覆盖（阶段 3）——将 OVERLAY_FILES 中列出的每个文件从 runtime-overlays/ 重新复制到项目之上。目前有 8 个条目：两个 module.json5 文件（electron + web_engine）、electron/src/main/resources/base/profile/shortcuts_config.json、web_engine 的 MediaAdapter.ets 和 JsBindingMethod.ets，以及 3 个语言区域的 string.json 文件（base / en_US / zh_CN）。
- OVERLAY_PRE_REWRITE_FILES（1 个条目：web_engine/src/main/ets/adapter/PermissionManagerAdapter.ets）在阶段 3 被覆盖，但同时也会被阶段 4 重写（bundleName 字面量替换）。因此其覆盖副本有意保留通用字面量 com.huawei.ohos_electron，由阶段 4 将其重写为应用 bundle 名称。由于阶段 4 之后源与目标会合理地不同，它被排除在阶段 7.6 的 md5 检查之外，改由阶段 7.4 以及新增的守卫 7.9 来保护。
- 守卫——7.8 断言每个 PRUNE_FILES 条目都不存在；7.9 断言对于每个 OVERLAY_PRE_REWRITE_FILES 条目，覆盖源仍包含通用字面量，且目标包含应用 bundle 名称并且不再包含通用字面量。

要保护一项新的应用定制：将修改后的文件放到 runtime-overlays/ 下，将其相对路径添加到 collect-runtime.mjs 中正确的列表（OVERLAY_FILES / OVERLAY_PRE_REWRITE_FILES / PRUNE_FILES），然后运行 node scripts/collect-runtime.mjs 来验证。collect-runtime.mjs 需要 DEVECO_SDK_HOME；--verify-only 仅运行守卫。

签名（外部化——密钥永不提交）

签名材料被外部化，因此 build-profile.json5 不含密钥且可安全提交。有两个被 gitignore 的配置文件，每种签名模式一个：

| 模式 | 配置（被 gitignore） | 已提交的模板 |
|---|---|---|
| debug | signing.debug.local.json | signing.debug.local.json.sample |
| release | signing.release.local.json | signing.release.local.json.sample |

两个文件共享相同的 schema（相对路径相对于项目根目录解析）：

{
"certpath":      ".ohos/release/release.cer",
"storeFile":     ".ohos/release/release.p12",
"profile":       ".ohos/release/release.p7b",
"keyAlias":      "debugKey",            // 可选，默认为 "debugKey"
"keyPassword":   "",
"storePassword": "",
"signAlg":       "SHA256withECDSA"      // 可选，默认为 SHA256withECDSA
}

模式选择由 SIGN_MODE 环境变量驱动（debug | release）；未设置时默认为 debug。任何其他值都会导致硬失败——不会静默回退到 debug。

- hvigorfile.ts —— 在 afterNodeEvaluate 阶段，按优先级顺序解析 app.signingConfigs：
1. CI 环境变量：CERTPATH / STORE_FILE / STORE_PASSWORD / KEY_PASSWORD 全部存在（外加可选的 PROFILE / KEY_ALIAS / SIGN_ALG）
2. signing..local.json
3. 未找到任何配置 → signingConfigs 保持不变，并发出醒目警告，指明缺失的路径（随后构建将产出未签名 / IDE 自动签名的包）
- 注入仅在内存中进行（setBuildProfileOpt）：build-profile.json5 以 "signingConfigs": [] 提交，且永远不会被写入。
- scripts/build-hap.ps1 —— 使用 DevEco 自带的 JBR 进行 CLI 构建+签名（避免 Temurin/sdkman JDK 21 在 hap-sign-tool.jar 中出现的 Invalid CEN header zip64 失败）。它为 hvigor 子进程设置 SIGN_MODE。

任一配置中的 keyPassword / storePassword 必须是 hvigor DecipherUtil AES-GCM 密文（≥32 个十六进制字符，不能是明文），并且 .p12 所在目录必须包含 material/{fd,ac,ce} 钥匙串——否则签名会失败。

构建后签名断言。 构建成功后，build-hap.ps1 会对产出的工件运行 SDK 的 hap-sign-tool verify-app，提取内嵌的 provisioning profile 的 type，并将其与请求的 -SignMode 进行比较。不匹配会是一个醒目的错误，并以非零退出码结束。（.p7b 是二进制文件，因此通过 Latin-1 字节映射加花括号匹配来定位 profile JSON。）此防护的存在是因为该项目此前曾发布过一个被静默地用 debug 材料签名的 release 构建。

dsh 版本锁定。 本项目针对 deepseek-harness 标签 dsh-v0.1.5-rc.2 构建。补丁按 dsh 版本组织（patches//），并且 scripts/build-dsh.mjs 锁定 patches/dsh-v0.1.5-rc.2/——当升级到新的 dsh 标签时，添加一个匹配的 patches// 目录并更新该锁定。

| 补丁 | 用途 |
|---|---|
| patches/dsh-v0.1.5-rc.2/dsh-symlink-to-copy.patch | HarmonyOS 沙箱禁止符号链接（EACCES）→ 回退到 cpSync 递归复制 |
| patches/dsh-v0.1.5-rc.2/dsh-allow-all-interfaces.patch | 移除 webserver 的 --host 0.0.0.0 拒绝检查（回环隔离需要绑定所有接口 + 局域网 IP） |
| patches/dsh-v0.1.5-rc.2/dsh-disable-hmr.patch | 添加 DSH_DISABLE_HMR 开关，跳过仅监视的 HMR（HMR 依赖 --expose-internals） |
| patches/dsh-v0.1.5-rc.2/dsh-disable-native-picker.patch | 强制目录选择器使用浏览模式（原生对话框 worker 在 Electron 下无法启动） |
| patches/dsh-v0.1.5-rc.2/dsh-flock-openharmony.patch | 在 openharmony 上授予进程内 POSIX flock 写锁（无原生插件；单进程宿主，与 dsh 的 browser-worker 桩实现理由相同） |
| patches/dsh-v0.1.5-rc.2/dsh-hardlink-to-rename.patch | HarmonyOS 沙箱拒绝硬链接（EACCES）→ 仅通过同目录 rename 发布，在其他所有场景保留先 link 后 EEXIST 的偏好（会话日志物化 + 生成发布） |

前置条件 — 同级源码检出。 本项目依赖 3 个同级项目（非子模块）；构建前请将它们克隆到本项目旁边：
bash
git clone --branch dsh-v0.1.5-rc.2 https://github.com/deepseek-ai/deepseek-harness.git ../deepseek-harness
git clone --branch v1.26.0           https://github.com/dsh-market/dsh-market.git       ../dsh-market
../harmonypc-electron 是 Electron-on-HarmonyOS 运行时项目；解压 Electron 37 构建产物以提供这 3 个 SO

collect-runtime.mjs 会校验这 3 个 SO（libelectron.so/libadapter.so/libffmpeg.so），若有缺失则报错；collect-dsh.mjs 在 ../dsh-market 缺失时会硬性失败（打包后的应用会将其作为 dsh-dist/node_modules/dshmarket 一并打包）。

运行

使用专用脚本构建（配置/SIGN_MODE 详情见 签名）：
powershell
debug（默认任务：Hap）— debug 签名的包可以侧载
powershell -ExecutionPolicy Bypass -File scripts\build-debug.ps1

release（默认任务：App）— 生成 build\outputs\default\-signed.app
+ build\outputs\default\symbol\release\app-symbol.zip
powershell -ExecutionPolicy Bypass -File scripts\build-release.ps1

release 编译但 debug 签名 — 设备端回归测试所需
powershell -ExecutionPolicy Bypass -File scripts\build-hap.ps1 -BuildMode release -SignMode debug

scripts/build-hap.ps1 是引擎（参数：-Task Hap|App、-BuildMode debug|release、-SignMode auto|debug|release，以及 -JbrHome -SdkHome -NodeHome -Hvigorw -DevEcoHome）；-SignMode auto（默认值）会解析为 -BuildMode。两个薄封装脚本固定各自的默认值：build-debug.ps1 始终使用 -BuildMode debug -SignMode debug，build-release.ps1 始终使用 -BuildMode release -SignMode release。

通过 HDC 安装 debug 构建并启动：
bash
hdc tconn :   # 先进行无线（IP）调试；端口显示在 开发者选项 → 无线调试 中
hdc uninstall org.fellow99.DeepseekHarnessHarmony   # 全新安装/产物变更时先卸载，以清除 userData 中残留的 dsh-dist
hdc app install -r electron/build/default/outputs/default/electron-default-signed.hap
hdc shell aa start -a EntryAbility -b org.fellow99.DeepseekHarnessHarmony
⚠️ 发布签名的软件包无法侧载。 对发布签名的软件包执行 hdc app install 会失败，并报错 code:9568322 ... signature verification failed due to not trusted app source。若要在设备上进行回归测试，请使用 -BuildMode release -SignMode debug（发布编译、调试签名）；发布签名的软件包仅用于 AppGallery 提交。

要求：DevEco Studio 4.0+、HarmonyOS SDK API 17+（targetSdk 6.1.1(24)）、Node 18+、pnpm@11、HDC。

签名与受限权限（完整流程）

在应用的配置文件（.p7b）授予 ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY（一个 system_basic 受限权限，system_grant，仅限平板/2in1）之前，应用无法安装。有两种获取方式：

A. 发布路径（AppGallery）—— 在 AGC 中以 ACL 形式申请该权限

受限权限不是通过手动编辑配置文件获得的。应用在 AppGallery Connect 中申请一个 ACL（跨级别权限），华为审核使用场景，审核通过的权限会在创建发布配置文件时自动写入配置文件——因此发布签名路径完全不需要手动修改 .p7b。

1. AGC → 开发与服务 → 你的项目 → 你的应用 → 项目设置 → ACL权限 标签页。
2. 在未获取权限下勾选我已知晓，选择 ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY，并提交申请
（每次申请最多 30 个权限；在提交新申请前等待审批完成）。
3. 审核（约 3 个工作日）会检查该权限是否与应用的使用场景匹配——此应用
启用了内置引擎的 JIT 编译功能，仅限平板/2in1，不将该
权限用于热更新，并适配 JShield 模式（坚盾模式）。
4. 在审批通过之后，在 AGC 中创建发布配置文件——已授予的 ACL 权限会自动写入
其中。如果配置文件创建后 ACL 权限发生变化，请重新创建配置文件。
5. 目前只有注册在中国大陆的开发者账号才能使用 ACL 权限。

完整的发布证书/发布配置文件流程请参见 AppGallery 提交。

B. 调试路径 —— 在 DevEco 中重新生成调试配置文件（无变化）

.p7b 配置文件由华为签名——它无法在本地重新生成
（没有本地配置文件签名 CA；编辑 SDK 的 UnsignedProfileTemplate.json 不会
自动重新生成现有的 .p7b）。默认的 DevEco 调试配置文件不会授予该
受限权限，因此安装调试构建会失败，并报错：

install failed due to grant request permissions failed. PermissionName: ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY

在 DevEco Studio 中重新生成它：

1. 在 DevEco Studio 中打开项目。
2. File → Project Structure → Signing Configs。
3. 勾选自动生成签名，并使用你的华为开发者账号登录。
4. DevEco 会在 ~/.ohos/config/ 下重新生成调试密钥库 + 配置文件
（_…=.p12/.cer/.p7b + material/ 钥匙串）。
5. 确保请求的权限包含该受限权限。该模块已经声明了它（web_engine/src/main/module.json5 → requestPermissions + definePermissions
→ ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY）。对于 normal-APL 应用的跨级别（ACL）授权，
DevEco 的签名对话框会显示该受限权限以供批准；
接受它，这样重新生成的 .p7b 就会在 acls.allowed-acls 中携带它。
6. 将 signing.debug.local.json 指向重新生成的素材（模板：
signing.debug.local.json.sample；相对于项目根目录的路径即可）。

构建 + 签名
powershell
powershell -ExecutionPolicy Bypass -File scripts\build-debug.ps1     # debug
powershell -ExecutionPolicy Bypass -File scripts\build-release.ps1   # release (App Pack)

build-hap.ps1 会在每次构建后验证产物的内嵌 profile type 是否与
所请求的签名模式匹配（参见 签名）。

安装与启动
bash
hdc uninstall org.fellow99.DeepseekHarnessHarmony
hdc app install -r electron/build/default/outputs/default/electron-default-signed.hap
hdc shell aa start -a EntryAbility -b org.fellow99.DeepseekHarnessHarmony

如果安装时仍报告 debug 构建的权限授予失败，说明 .p7b 尚未携带该
受限权限——在重新构建之前，重复 DevEco 重新生成流程（确认 ACL 批准）。
release* 签名的包永远无法通过这种方式安装；release 签名仅用于 AppGallery。

AppGallery 提交

分发不再只是“仅个人使用的 HAP”：上架 AppGallery 现在是一个目标。
AppGallery 只接受使用华为签发的 release 证书 + release profile 签名的包——
debug 签名的包无法上架。

前提条件

- 一个实名认证的华为开发者账号——创建 release 证书所必需。
- 目前此应用所需的 ACL 权限仅对注册在
中国大陆的开发者账号可用。
- 资质材料：AGC 上的发布准备会要求诸如隐私声明、
电子版权证书，以及应用版权或代理证书等材料，外加备案/审批——
请在 AGC 的发布准备工作页面确认确切清单。APP 软件著作权证书（软著）对于
非游戏应用是非强制资质（推荐变体：计算机软件著作权登记证书 /
APP 电子版权证书 / 软件著作权认证证书）；游戏还额外需要许可证号（版号）。

大小限制

| 产物 | 限制 |
|---|---|
| App Pack（.app） | ≤ 4GB |
| HAP — PC/2-in-1、平板、手机 | ≤ 4GB |
| HAP — 智能手表 / 智能显示屏 | ≤ 2GB |
| HAP — 运动手表 | ≤ 20MB |

本项目的 release HAP 约为 360MB，App Pack 约为 245MB——完全在限制之内。HAP 不得为
installationFree，且 bundleType 必须为 app。

1. 创建 release 证书
AGC → 证书、APP ID和Profile → 证书 → 新增证书，类型选择 发布证书，上传 .csr（在
DevEco Studio 中通过 Build > Generate Key and CSR 生成，或使用 keytool 生成），然后下载 .cer。

- 每个账号最多 3 个发布证书；实名认证开发者的有效期为 3 年。
- 更新发布证书需要同时更新发布 Profile。

2. 申请受限权限（ACL）

AGC → 开发与服务 → 你的项目 → 你的应用 → 项目设置 → ACL权限 标签页 → 在未获取权限下勾选
我已知晓 → 选择 ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY → 申请。

- 每个应用最多 30 个权限；在发起新申请前需等待审批完成。
- 部分权限需要填写 申请原因（≤256 字符）、选择 使用场景，以及可选的附件。
- 申请后的审核时间约为 3 个工作日。
- 审批通过后，该权限会出现在 已获取权限 下，并在创建 Profile 时 自动写入 Profile。
如果 Profile 创建后 ACL 权限发生变更，则必须重新创建 Profile。
- 还存在 试用调试Profile（试用调试 Profile）：有效期 5 天，每个应用最多 5 个。

该权限本身被官方归类为级别 system_basic、授权模式 system_grant、
类型 受限开放权限、startVersion API 14；仅适用于平板和 PC/2-in-1 设备；仅允许启用了内置引擎 JIT 编译功能的应用使用，且不允许用于热更新；应用必须主动适配 JShield 模式（坚盾模式），且在该模式下不得崩溃。

3. 创建发布 Profile

AGC → 证书、APP ID和Profile → Profile → 添加，类型选择 发布，绑定到 bundle name + 一个发布
证书。与调试 Profile 不同，发布 Profile 的设备列表为 空（不绑定设备）。

4. 构建、版本管理与上传
powershell
powershell -ExecutionPolicy Bypass -File scripts\build-release.ps1   # -Task App -BuildMode release -SignMode release

- 上传已签名的 App Pack：build\outputs\default\-signed.app。
- 可选上传 build\outputs\default\symbol\release\app-symbol.zip，以便对崩溃报告进行
符号化解析。
- versionCode（当前为 1005）必须是数字，并且在后续每次提交时必须严格递增——参见 Current versions。
- 官方审核指南中没有单独的 PC/2-in-1 审核通道。提交时，如果
包支持 PC/2-in-1，但配置的分发设备不包含它，AGC 会提示你
更新支持的设备。

待确认： AppGallery 上架本身的端到端审核时长（上文仅记录了 ACL
审核的约 3 个工作日），以及确切的发布准备文档集——两者
都必须在首次提交前从 AGC 自己的页面上读取。

目录结构

本项目以及 3 个被消费的项目加 1 个架构参考项目位于 同级目录（不是子模块）：

(sibling directories)
├── deepseek-harness-harmony/      # 本项目（HarmonyOS HAP，HarmonyOS 桌面端移植）
│   ├── AppScope/                  # 应用作用域（图标/名称/签名）
│   ├── electron/                  # 入口模块（从 harmonypc-electron 复制，包含 SO）
│   ├── web_engine/                # 桥接 HAR（ArkTS 桥接层 + resfile 携带 dsh 产物）
│   ├── src-main/                  # 主进程 main.js（解压 + runProfile + loadURL + HarmonyOS 适配）
│   ├── scripts/                   # 四阶段构建：collect-runtime → build-dsh → collect-dsh，外加 build-debug / build-release
│   ├── runtime-overlays/          # 每次运行时复制后重新应用的应用定制（裁剪 + 覆盖）
│   ├── profiles/desktop/          # 自定义桌面 profile（cordis.patch.yml + package.json）
│   ├── patches/                   # dsh 上游补丁（6 个）
│   ├── docs/                      # 工程规划与最终实现记录
│   └── specs/                     # 规格文档（as-built；索引见 specs/README.md）
│
├── harmonypc-electron/            # Electron-on-HarmonyOS 运行时（Electron 37 / Node 22.17.0）
│   └── ohos_hap/                  # electron + web_engine 模块 + SO 源码（collect-runtime 复制来源）
│
├── deepseek-harness/              # 被封装宿主（dsh，源码参考，非子模块）
│   ├── apps/                      # cli（dsh bin / profile-boot）、web（前端，build:web 产出 dist）
│   ├── packages/                  # host / client / core / session 工作区包
│   ├── vendor/                    # 内置 cordis 框架包（cordis / loader / hmr / …）
│   └── native/                    # landlock-run 原生模块（Linux 沙箱，MVP 中已裁剪）
│
└── dsh-market/                    # 插件市场（源码参考，npm 包名 "dshmarket"）
├── src/                       # 宿主半部（挂载 /dsh-market/ 路由）
├── client/                    # 浏览器半部（设置页 UI）
├── lib/                       # 编译后的宿主产物（物化到 dsh-dist/node_modules/dshmarket）
└── cordis.patch.yml           # loader 插入声明（{ id: dsh-market, name: dshmarket }）

../deepseek-harness-desktop 是架构设计参考（复用其架构决策 + 补丁 + 主进程编排逻辑），不参与本项目的构建/打包。

相关文档

- docs/工程规划.md — 完整工程规划 + 最终实现记录（Electron 37 落地、关键适配改动、MVP 取舍、交叉编译优化路径）
- specs/README.md — 规格文档索引（项目级 + 9 个模块规格/规划，as-built）

参考资料

- deepseek-harness（同级目录 ../deepseek-harness）— 被封装宿主；其 docs/ 目录包含完整架构文档
- dsh-market（同级目录 ../dsh-market）—— 内置的可视化插件市场（npm 包 dshmarket），通过 collect-dsh.mjs 生成
- harmonypc-electron（同级目录 ../harmonypc-electron）—— HarmonyOS 上的 Electron 运行时
- deepseek-harness-desktop（同级目录 ../deepseek-harness-desktop）—— 架构设计参考（Electron 桌面外壳）

许可证

MIT © 2026 fellow99