dsh-hmos-sidebar

English

Native presets — Both bundled presets now select the native tool presentation instead of ptc (2026-09-30). They are day-to-day HarmonyOS coding verticals whose loop is read → edit → test → verify, and under native the workflow-ptc / tool-workflow rows they carry are directly callable instead of reachable only as a nested SDK call inside run_code (whose inner dispatches are not durably recorded). The Liangshen preset keeps its promotion state machine and its native | ptc switch — it simply selects native now — and tool-ralph returns to the shipped default of disabled. The always-on persona was corrected with the switch: it no longer describes PTC execution, no longer tells the model to use the disabled ralph tool, and names the real goal tools (create_goal / update_goal) rather than a goal tool that does not exist — a persona that names an unmounted tool both burns attention and invites UNKNOWN_TOOL calls. test/package-contract.test.mjs now enforces that hygiene for the personas, and test/tools.test.mjs for the 41 tool descriptions (cross-references must carry the full dcli__ prefix — a bare auth_status reads like a callable tool and yields UNKNOWN_TOOL).

Dual-shape presets — Both bundled presets now ship in the two shapes DSH actually asks for: the ≤ 0.1.5 directory preset (presets/<id>/) and the ≥ 0.1.7-rc.1 declaration (presets/<id>.declarative.yml, one @deepseek-ai/dsh-agent-preset row). install-presets resolves @deepseek-ai/dsh-agent-preset from the profile to decide which one to install, so a DSH upgrade no longer silently drops the presets. On ≥ 0.1.7 nothing is copied into $DSH_HOME: the declaration stays in the package, and one small managed block in the profile's cordis.patch.yml mounts it with cordis:include. 0.3.14 carried the portable settings transport (settingsScope ≤ 0.1.5 / configForms ≥ 0.1.7-rc.1).

A Windows-only HarmonyOS development workbench for DeepSeek Harness Web. One package bundles the Host RPC, 41 dcli__* tools, floating Web UI, and two installable HarmonyOS agent presets: native-harmonyos and liangshen-native-harmonyos. The Liangshen preset uses a capability-detected compatibility layer: DSH 0.1.2+ uses session.snapshotEvents(), while older RC releases fall back to session.events.

Install with dsh plugin --profile web add dsh-hmos-sidebar, then run npx --yes dsh-hmos-sidebar install-presets from the Web profile directory. Windows only; restart the DSH Web Profile after installation. The installer picks the payload the host can actually mount: on DSH ≤ 0.1.5 it copies presets/<id>/ into $DSH_HOME/.agent-presets/<id>/; on ≥ 0.1.7-rc.1 it writes one cordis:include row per preset into the profile's cordis.patch.yml. --mode directory|declarative forces either shape and --dry-run prints what would be written.

中文

预设改回 native 呈现（2026-09-30）：两个内置预设不再使用 PTC 呈现。它们是鸿蒙日常编码向的预设，主循环是「读 → 改 → 跑测试 → 验结果」，native 下往返更短、失败更可归因；而且 preset 里启用的 workflow-ptc / tool-workflow 只有在 native 下才是模型可直接调用的工具——PTC 呈现下它们只能经 run_code 内的 SDK 嵌套调用，且内层 dispatch 不落日志。梁神预设的 promotion 状态机与 native | ptc 开关保持不变，只是选了 native；tool-ralph 回到官方默认的 disabled。常驻 persona 一并修正：不再描述 PTC 执行、不再叫模型用已禁用的 ralph，并把不存在的 goal 改成真实的 create_goal / update_goal——点名没挂载的工具既耗注意力又会招来 UNKNOWN_TOOL 调用。test/package-contract.test.mjs 现在会强制这条卫生规则（persona），test/tools.test.mjs 则对 41 个工具描述做同样的事：交叉引用必须带完整 dcli__ 前缀——光写 auth_status 会被模型当成可调用的工具，直接得到 UNKNOWN_TOOL。

预设双形态预适配：DSH 0.1.7-rc.1 移除了目录型 preset roster，改为在 profile patch 中用 @deepseek-ai/dsh-agent-preset 声明 identity + 子插件列表。两个内置预设现在各有两个逐行等价的 payload（presets/<id>/ 与 presets/<id>.declarative.yml），install-presets 按 profile 能否解析该包自动选择：≤ 0.1.5 仍复制目录，≥ 0.1.7 改为写托管块 + cordis:include。改写中只保留 rc.1 强制的三处差异：@deepseek-ai/dsh-workflow-worker-thread → @deepseek-ai/dsh-workflow-ptc（上游无别名，行 id 同步改为 workflow-ptc）、技能目录改由 createRequire(baseUrl).resolve('dsh-hmos-sidebar/package.json') 定位、两个 preset 本目录模块改为 package 子路径导出。

0.3.12 预设挂载修复：@deepseek-ai/dsh-persona 自 DSH 0.1.5-rc.1 起把 persona 配置改为必填 prefix（旧 text 键被删除，且报 $.prefix missing required value 导致预设无法切换），persona 提示段名也从 deployment:persona 拆为 deployment:persona-prefix / deployment:persona-suffix；两个内置预设与 tool-bootstrap.mjs 的段名白名单已同步。0.3.11 含同一修复但未发布成功（其发布跑因新契约测试的行尾假设在 CRLF 检出的 runner 上失败）。

0.3.2 兼容层：按能力检测选择 DSH 0.1.2 的 session.snapshotEvents() 或旧版 session.events，避免「梁神+鸿蒙」预设在会话回合启动时因 API 变更崩溃；并明确声明支持 DSH 0.1.2-rc.1。

HarmonyOS 开发工作台（DSH Web 悬浮窗，Windows-only）。一个 npm 包 = Host RPC + 41 个 dcli__* 模型工具 + 浏览器悬浮 UI。工具、界面、命令通道单一分发单元。

⚠️ 平台：Windows-only（package.json 的 "os": ["win32"]、cordis.patch.yml 与本文一致）。不提供 POSIX/Linux/macOS 支持。npm 对 os 不匹配会 EBADPLATFORM 硬拒安装；若用 git/link 绕过，工具模块（./tools）在非 win32 上不注册任何 dcli__*（运行时守卫 toolsSupportedOn），host RPC 仍会挂载但各动作返回缺 CLI 的可操作错误。

在 DSH Web 页面右下角提供一个可拖动的悬浮球（手机图标），点击展开非模态面板，分四个 Tab：

默认安静模式（v0.3+）：悬浮球永不隐藏——当前工作区未探测到鸿蒙工程（含探测进行中或探测链路不可用）时它显示为「待命」外观（变暗、略微缩小；悬停或键盘聚焦即恢复全不透明度），仍然可点击打开工作台；安静模式也绝不自动展开弹窗。探测到鸿蒙工程时悬浮球恢复全强度显示。两类行为都可在设置卡片里调整：≤ 0.1.5 在 设置 → 插件，≥ 0.1.7-rc.2 在左侧边栏第一个面板图标 「插件」 里打开 dsh-hmos-sidebar bundle 的 dsh-hmos-sidebar 行（见下文）。

| Tab | 功能 | | --- | --- | | 构建 | 环境检测（deveco-cli / DevEco Studio / json5 / hvigor，缺失可一键安装或跳官方下载页）、工程目录与 bundleName、构建 Debug/Release、清理、同步（hvigor）、HAP 包信息查看（含格式化原始 JSON） | | 部署 | HAP 产物下拉（自动探测并排序）、部署设备下拉（已连接真机/模拟器）、安装 HAP、启动应用 | | 设备 | 已连接设备列表、设备日志/崩溃日志、屏幕截图（默认路径由 host 提供） | | 速查 | 41 个 dcli__* 命令速查（搜索过滤、参数/必填/枚举） |

弹窗标题显示 bundleName + 工程应用图标 + 版本号；面板位置/大小、悬浮球位置均有记忆。

设置卡片：HarmonyOS 工作台（席位与导航随宿主版本不同）

插件注册一张可展开的设置卡片（设置命名空间 hmos-sidebar），两个开关默认均为开（安静模式）：

| 配置 | 默认 | 行为 | | --- | --- | --- | | 默认不展开弹窗（popup.keepCollapsed） | 开 | 即使当前工作区探测到鸿蒙工程也不自动展开面板；关闭后，探测到鸿蒙工程时自动展开一次 | | 在非鸿蒙工作区，悬浮球显示为待命状态（ball.hideWithoutProject） | 开 | 当前工作区未探测到鸿蒙工程（含探测进行中/探测链路不可用）时悬浮球变暗并略微缩小，但始终可见、可点击——它是打开工作台的唯一入口；悬停或键盘聚焦恢复全不透明度。关闭后悬浮球保持全强度显示 |

• 开关通过官方 settings 服务持久化（保存/放弃修改/恢复默认/只读提示与官方卡片一致）。两代宿主的通道不同：≤ 0.1.5 由 host 注册 hmos-sidebar 命名空间、客户端经 settingsScope 订阅；≥ 0.1.7 没有 register，命名空间就是本插件入口导出的 Config（键为 loader entry id dsh-hmos-sidebar，两个叶子标记 volatile），客户端经 configForms 读同一份值。卡片席位同样分两代：≤ 0.1.5 声明 settings.plugin.item（键 hmos-sidebar）；0.1.7-rc.2 删除了该槽位，bundle 行的配置席位是带键的 plugins.row.config，键为 dsh-hmos-sidebar#dsh-hmos-sidebar，只有该精确键在注册账本上时插件管理页才渲染该行的配置入口。≥ 0.1.7-rc.2 还额外声明根级列表席位 settings.section：本插件以 id yotk-hmos-sidebar、order 64、标签 YOTK · 鸿蒙工作台 把同一张卡片再作为设置里的一级页面露出（附加席位，不取代 bundle 行席位），行席位的配置页与该设置页这两类单卡片页面默认展开，≤ 0.1.5 的列表卡片保持折叠。
• 设置传输可能晚于卡片挂载到达（行席位只等 slots，插件管理页一打开就满足；configForms/settingsScope 可能更晚），所以卡片在快照就绪前也会渲染出来，并在表头显示 等待设置传输 / 加载中 / 设置不可用，展开后有对应说明——不再静默渲染空白；传输到达后卡片自行重渲染。未就绪时既不渲染开关也不显示用不了的「保存」。
• 设置服务不可用时整体回退到上表默认值，主功能不受影响。若卡片显示「设置不可用」，说明宿主设置服务里没有本插件的命名空间：0.1.7 走廊上宿主会整体跳过「入口 Config 里没有任何 volatile 字段」的插件（SettingsForms.describe() 静默丢弃，日志无错），按卡片提示在「插件」页重装/更新本包后刷新即可恢复。

工具与 RPC 的分离

• 41 个 dcli__* 模型工具：由预设单独挂载，不再由主入口全局注册。包导出 ./tools → lib/dcli-tools.mjs，预设以文件插件形式 insert 挂载即可。工具在每次调用时动态解析环境（lib/environment.js），CLI 缺失不阻止插件挂载，真正调用时才会报「可操作错误」；安装好 deveco-cli 后无需重启 DSH 即可识别。
• 主入口 lib/index.js：只服务浏览器 RPC /hmos/api/*，不注册任何模型工具。RPC 只暴露动作级方法，不接受任意 argv。

安装

从 npm 安装（推荐）

dsh plugin --profile web add dsh-hmos-sidebar

从 GitHub 源码安装

克隆本仓库后，在仓库根目录执行：

dsh plugin --profile web add .\packages\dsh-hmos-sidebar

官方 dsh plugin add 会自动完成：登记依赖 → 识别包内 dsh.bundle.patch → 注册进 dsh.profile.bundles（host 半 + client 半一起挂载）。安装后重启对应的 DSH Web Profile。卸载：dsh plugin --profile web remove dsh-hmos-sidebar。

41 个 dcli__* 工具需由包内的 native-harmonyos 或 liangshen-native-harmonyos 预设通过 ./tools 单独挂载；主插件不会向所有 Agent 全局注册工具。

安装插件后，在 profile 目录（本机为 ~/.dsh/profiles/<name>）中运行预设安装器（默认安装两个预设）：

pnpm exec dsh-hmos-sidebar install-presets --all
# 或：npx --yes dsh-hmos-sidebar install-presets --all

安装器按宿主形态自动选择 payload（探测 profile 能否解析 @deepseek-ai/dsh-agent-preset）：

| 宿主 | payload | 安装动作 | | --- | --- | --- | | ≤ 0.1.5 | presets/<id>/（目录型 preset） | 复制到 <DSH_HOME>/.agent-presets/<id>/；同名默认拒绝覆盖 | | ≥ 0.1.7-rc.1 | presets/<id>.declarative.yml（@deepseek-ai/dsh-agent-preset 声明行） | 在 profile 的 cordis.patch.yml 写入一段托管块，用 cordis:include 挂载包内声明文件 |

• ≥ 0.1.7 时不往 $DSH_HOME 复制任何文件：声明留在包内，dsh plugin 升级包即刷新预设，无需重跑安装器（重跑只会显示「已是最新」）。
• 托管块由 # >>> / # <<< 标记行界定，块外内容（含你自己的注释与条目）一律不动；块内也只替换安装器自己写的 hmos-preset-* 行，其余行逐字节保留——DSH 自己的配置编辑器会把新条目追加到补丁文件末尾，托管块恰好也在末尾时那些条目就落在块内，--force 不会再把它们刷掉。修改 cordis.patch.yml 前总是先写带时间戳的备份，且经同目录临时文件原子替换。
• 参数：--dry-run 只打印目标与将写入的内容；--force 刷新已存在的目标；--preset <id> 只装一个（装 liangshen-native-harmonyos 会自动带上 native-harmonyos —— 两者共用同一份技能库）；--mode auto|directory|declarative 强制形态；--profile-dir DIR 指定 profile 目录（默认当前目录）。
• ≤ 0.1.5 升到 ≥ 0.1.7 后：旧目录副本不会再被新 roster 读取（不是报错，是静默消失），重跑一次安装器即写成声明式；<DSH_HOME>/.agent-presets/ 下的旧目录可自行删除。
• 完成后重启 DSH Profile（≥ 0.1.7 的 profile 补丁层受 HMR 监听，通常热重载即可，但 roster 重建以重启最稳）。

包内运行时依赖仅 @deepseek-ai/schemastery，声明下限必须是 ^3.18.4：.volatile() 从 3.18.4 才有，而 profile 根通常 hoist 着旧的 3.18.2；若下限写成 ^3.18.1，pnpm 会认为根上那份 3.18.2 已满足范围、不再往包内物化一份支持 volatile 的副本，宿主 SettingsForms.describe() 就会静默丢掉本插件入口（没有任何 volatile 字段），设置卡片整个不存在且不报错（实测：同一 profile 里本包解析到 3.18.2，而三个兄弟胶囊各自解析到 3.18.4）。@deepseek-ai/dsh-tools 与 @modelcontextprotocol/sdk 都声明为可选 peerDependency（peerDependenciesMeta.optional: true），不随插件单独安装，两者都从 DSH profile 解析，避免在插件内复制并遮蔽宿主版本。@modelcontextprotocol/sdk 只被 ./tools 里的 LSP 工具（dcli__lsp_check / dcli__lsp_restart）使用，并且是受保护的动态 import：解析不到它不会阻止 ./tools（以及静态引用它的 host 半）加载，只有真正调用 LSP 工具时才报「请安装该可选 peer 依赖」的可操作错误。不要把它放回 dependencies：pnpm 会在包内嵌套一层 .pnpm 隔离仓库，DSH 的包闭包遍历在 Windows 上 realpath 会 EPERM 失败，整个 Web 启动前就崩。

包为 ESM-only（"type":"module"，exports 无 require 条件）：Node ≥22.12 可原生 require()，更早版本 require 会 ERR_REQUIRE_ESM；engines 要求 Node ≥18（npm test 使用 node --test，Node 18 兼容，自动发现 test/*.test.mjs）。./client 导出是浏览器专用 bundle，不可在 Node 中 import。

依赖脚本白名单：pnpm 11 若拦构建脚本，参照 dsh-better-sidebar 的安装脚本在 profile 的 pnpm-workspace.yaml 加 allowBuilds / minimumReleaseAgeExclude。本包自身不再安装任何带构建脚本的依赖；若 profile 因其他包安装 @modelcontextprotocol/sdk 而在 npm 12 报 EALLOWSCRIPTS，那是它→express 传递依赖的 prepare 脚本被 allow-scripts 白名单拦下，把相关包（path-to-regexp content-type eventsource express-rate-limit ip-address）加进 ~/.npmrc 的 allow-scripts，或直接走官方 dsh plugin add 的安装流程。

配置

lib/environment.js 统一解析 cli / DevEco Studio / hdc / hvigor / json5 / 工程根，优先级 config → 环境变量 → 常见安装位置探测，每次调用实时解析（不缓存，安装/变更路径后无需重启）。全部字段可省略。CLI 入口不写死路径：在每个 npm 全局根下读 @deveco/deveco-cli 自身的 package.json#bin 得到真实入口，因此 deveco-cli 的新旧布局（≥ 1.3.4 的 cli.js、≤ 1.3.3 的 dist/cli.js）都能识别；manifest 不可读时安静回退到旧布局候选，不报错。

| 字段 | 说明 | 缺省行为（探测源） | | --- | --- | --- | | cliPath | deveco-cli 入口文件（可省略） | 环境变量 DEVECO_CLI_PATH → 各 npm 全局根（%APPDATA%\npm 等）下 @deveco/deveco-cli 的 package.json#bin 指向的真实入口 | | projectPath | Host 默认鸿蒙工程根 | 环境变量 PROJECT_PATH → Host 进程 cwd；Web 浮窗会优先传当前 GUI session 的 cwd | | devEcoHome | DevEco Studio 安装目录 | DEVECO_HOME → DEVECO_SDK_HOME 父目录 → 常见安装路径（C:\Program Files\Huawei\DevEco Studio 等） | | projectRoots | 当前工作区以外的附加工程发现根目录列表 | 默认空；Web 浮窗仍会有界递归扫描当前 GUI session 的 cwd | | screenshotDir | 截图默认保存目录 | 工程下 .dsh-screenshots → OS 临时目录 dsh-hmos-screenshots |

包内不硬编码任何个人绝对路径。Web 浮窗通过官方 shell.overlay Slot 的 useSessions 标准属性取得当前 session cwd，并在首次挂载或切换会话时重新探测；若 cwd 是工程父目录，会跳过依赖/构建目录并进行有界递归查找。projectRoots 仅用于补充扫描当前工作区以外的位置。

RPC 动作级方法

POST /hmos/api/<method>，JSON body。不再接受任意 argv（删除了旧 hmos/run / hmos/hdc）：

| 方法 | 动作 | 主要参数 | | --- | --- | --- | | hmos/info | 环境信息 | — | | hmos/install-cli | 安装 deveco-cli | — | | hmos/tools | dcli 工具速查清单 | — | | hmos/devices | 已连接设备列表 | — | | hmos/probe | 工程探测（bundleName/HAP 产物） | path | | hmos/app-icon | 应用图标 | path | | hmos/hap-info | HAP 包信息 | path | | hmos/sync | hvigor 同步 | product,buildMode | | hmos/build | 构建 | buildMode (debug/release) | | hmos/clean | 清理构建产物 | — | | hmos/logs | 设备日志 | device,crash,tail | | hmos/screenshot | 屏幕截图 | device,path,display | | hmos/start | 启动应用 | bundleName,device,abilityName | | hmos/install | 安装 HAP | hapPath,device,bundleName |

安全边界：请求体上限 64KiB（超限 413）、非法 JSON 400、方法未注册 404、非 POST 405、同源 fence（loopback + http/https origin 与 Host 头完全一致，跨站拒绝）。

路径围栏：可信根只取显式来源——config.projectPath、环境变量 PROJECT_PATH、config.projectRoots（process.cwd() 兜底不作为可信根）。配置了可信根时，hmos/install（hapPath）、hmos/hap-info（path）、hmos/screenshot（path，含默认/配置目录生成的路径）的目标必须落在可信根内，否则拒绝；围栏用 path.win32.resolve + realpath/最近存在父目录策略，拒绝 C:\proj\..\outside\x.hap、UNC .. 逃逸与 junction/reparse point 逃逸。未配置可信根时保持后缀+存在校验。hmos/logs 的 tail 钳制在 1..10000。数据披露：hmos/info / hmos/devices / hmos/screenshot 会向页面返回本机绝对路径与设备序列号——仅同源页面（用户本人）可见，README 在此明示。

结构

lib/
  index.js         Host 半：webServer 路由 /hmos/api/*（动作级 RPC）+ loopback fence + 64KiB 限制
  dcli-tools.mjs   ./tools 导出点：41 个 dcli__* 工具子模块（含 managed-markers AGENTS 生成）
  environment.js   共享环境解析：cli/Studio/hdc/hvigor/json5/projectRoots（config→env→探测，动态）
  client.js        Client 半（web）：悬浮球 + 面板 UI（Shadow DOM，独立于 better-sidebar；层叠走官方 shell.overlay 层，可覆盖 shell 内容，菜单/dialog/toast 等更高 overlay 仍覆盖面板，禁止极端 z-index）+ 官方设置卡片（≤ 0.1.5 在 设置 → 插件；≥ 0.1.7-rc.2 在侧边栏「插件」面板的 bundle 行）
cordis.patch.yml   bundle patch（insert 行，无个人配置，Windows-only）
presets/
  <id>/                    ≤ 0.1.5 目录型 preset：agent.cordis.yml + preset.yml + skills/
  <id>.declarative.yml     ≥ 0.1.7-rc.1 声明式 preset：一行 @deepseek-ai/dsh-agent-preset，由 cordis:include 挂载
bin/
  dsh-hmos-sidebar.mjs     install-presets：按宿主形态安装目录型或声明式 preset，并维护 profile 补丁托管块
test/              node:test 单测（环境解析 / CLI 缺失挂载 / 工具定义 / managed AGENTS / RPC helper / preset 安装器与双形态契约）

双签名配置（dcli__configure_dual_signing）

dcli__configure_dual_signing 为工程根 build-profile.json5 合并 release（默认 default）与 debug 双签名、products 和模块 target 映射：

• 默认 apply=false，只校验材料并返回变更预览；apply=true 才写入。
• 写入前生成单份 build-profile.json5.dsh-backup，临时文件通过解析后再替换正式文件。
• .p12 / .p7b / .cer 必须存在且后缀正确；signAlg 固定为 SHA256withECDSA。
• 密码只写入目标配置，不在工具结果或错误中回显；备份同样包含签名配置，必须与正式文件按同等敏感级别保护且不得提交。
• 指定 modules 时为这些应用模块拆 release/debug targets；省略时优先处理 entry，其他模块复用现有 target 到两个 products。
• 当前版本写入时会把文件规范化为双引号、2 空格缩进；原始文本保存在备份中。

AGENTS.md（dcli__agents_md）

dcli__agents_md 生成/刷新工程根 AGENTS.md，以 managed markers 区分托管区与用户区：

<!-- DSH-HMOS-MANAGED:START -->
自动生成的事实：概览、模块、SDK、常用命令、结构约定、签名与构建
<!-- DSH-HMOS-MANAGED:END -->

• 默认 apply=false，只返回事实摘要和变更规模；apply=true 才写入。
• 只替换 marker 之间的托管块；marker 之外的用户内容在每次刷新时原样保留。首次接管无 marker 的既有文件时保留全文并在末尾追加托管块。
• marker 缺失配对、重复或反序时拒绝写入，不猜测修复；实际写入前创建单份 AGENTS.md.dsh-agents-backup，再通过同目录临时文件原子替换。
• 事实（module/bundleName/product/SDK/页面）全部来自 build-profile.json5 / AppScope/app.json5 / main_pages.json，不硬编码 debug/default/entry 产物路径。
• 静态检查命令用 dcli__lsp_check（而非 mcp__deveco__*）。

开发维护

• 改 lib/*.js / lib/*.mjs 后需重启 web 生效（client bundle 由 web 按需服务）。
• 改动后跑：

  npm run test                 # node --test
  node --check lib/index.js lib/dcli-tools.mjs lib/environment.js
  npm pack --dry-run           # 校验打包内容

• 环境要求：deveco-cli（UI 可一键 npm 全局安装）、DevEco Studio（UI 引导官方下载页）、hdc 随 Studio SDK。工具与 RPC 均在调用时动态解析，CLI/Studio 装好后无需重启 DSH。
• 已知限制：LSP 检查走原生子进程实例池（dcli__lsp_check），不复用 MCP 通道。
• 参考：安装/卸载/挂载机制与 dsh-better-sidebar、dsh-web-ui 一致（官方 dsh plugin add，识别 dsh.bundle.patch 自动挂载）。