EvanAgent/dsh-harmony/knowledge-base/cases.md

问题案例库

CASE-1：dsh-harmony（deveco）会话模型选择不可用（未解决，观察中）

• 现象：Web GUI 中该会话（session-9a1162e7，壳版任务对话）无法选择模型；刷新页面与重启服务后仍复现（2026-08-23 20:3x 用户确认）
• 已排除：服务端全链路健康——凭据（credentials.describe：BIGMODEL/MOONSHOTAI_CN/DEEPSEEK 全部 configured,file 源）、settings（agent-default-model 完好）、会话状态（16 轮全部完成、空闲）、宿主进程（DSH Desktop 托管 3080 端口正常）
• 剩余怀疑：客户端恢复态——DSH 转发事件「no replay after a reconnect」，llm 目录事件在重连前已发，模型选择组件错过后未再拉取；或该会话（bigmodel/glm-5.3）特有的目录恢复路径缺陷
• 处理：用户判定非严重，立案保留。后续排查切入点：新会话能否选模型（区分全局/会话级）；临时移除 mcp-harmonyos 二分；对 dsh-harmony 原生客户端的启示——协议适配层必须在重连后代际主动拉取目录/设置快照，不能依赖事件重放（已列入 P2a 设计约束）

CASE-2：语音设置模块浅色模式文字黑底（已修复，2026-08-23）

• 现象：浅色模式下，语音模式设置模块的下拉框（识别/朗读语言、引擎、说话方式等）背景为黑色，未适配浅色主题
• 根因：dsh-voice-client 插件 CSS 使用了不存在的主题变量名，var() 永不命中、永远走深色兜底值：
  • --dsw-alias-bg-l2（不存在）→ 正确名 --dsw-alias-bg-layer-2
  • --dsw-alias-hover（不存在）→ 正确名 --dsw-alias-interactive-bg-hover
• 修复：DSWorkSpace/dsh-voice-client/lib/client.js 两处变量名已改正（其余 9 处 label-*/border-l1 用法本就正确）；深色模式视觉不变，浅色模式跟随主题
• 验证：浏览器刷新页面（或硬刷新）后查看设置模块；若样式未更新则重启 dsh web
• 通用教训：给 DSH 写 web 插件时的官方主题 token 清单（从 index-.css 提取）：bg-base / bg-layer-1..2 / bg-mask-1 / border-l1..l4 / label-primary|secondary|tertiary|caption|dimmed|inverted / interactive-bg-hover|active / button--hover / state-*-primary|secondary。变量名必须以此清单为准，拼错不报错、静默走兜底

CASE-3 dsh web 禁止局域网暴露（2026-08-23，实证）

• 现象：dsh web --host 192.168.x.x 报 config 校验错（只接受 127.0.0.1|0.0.0.0）；--host 0.0.0.0 被显式拒绝（"intentionally not supported yet for safety: it would expose remote code execution"）
• 结论：真机连接唯一正路是 hdc rport 隧道（设备 127.0.0.1:3080 → 电脑）；任何 LAN 直连/反代方案都违背官方安全边界，勿再尝试
• 影响：壳版引导页文案与脚本已按 rport 模型重构（setup-device.sh 一键化）

CASE-4 hdc install 报 sign info inconsistent（2026-08-23）

• 现象：换过自动签名材料后覆盖安装报 code:9568332
• 根因：设备上旧包签名与新包不一致
• 解法：先 hdc uninstall com.dotouch.dshharmony 再装；setup-device.sh 已内置自动卸载

CASE-5 hap 包无法在真机双击安装（2026-08-24，平台事实）

• 现象：用户把 DSH-Harmony-1.0.0-arm64.hap 拷到真机，文件管理器双击无安装入口
• 根因：HarmonyOS NEXT 设计上关闭自由侧载，.hap 为开发态格式，系统未注册安装器（官方论坛问答确认）
• 合法通道：应用市场（含 AGC 内测/开放测试，唯一点击即装体验）/ hdc 安装（开发者模式，setup-device.sh 已自动化）/ 企业 MDM 分发
• 结论：勿再尝试本地安装方案；要市场体验走 AGC 内部测试通道（前置：华为开发者账号实名认证）

CASE-5 调试签名 Profile 的 UDID 绑定（2026-08-23，真机首装）

• 现象：真机安装报 code:9568423 device unauthorized / UDID not in signing profile；模拟器正常
• 根因：自动签名的调试 Profile 只含注册过的设备；新真机需先注册
• 设备：MatePad QXS-W10P（HarmonyOS 6.1.0.135 = API 24），UDID C393FFB572691036576084FA981FBE3FA0287AF2BB05516D4B4DBFC7AE6B36A6
• 解法：DevEco > File > Project Structure > Signing Configs > Register Device 一键注册重发 Profile → 重新自动签名 → 重建安装
• 附坑：hdc install 失败也 exit 0（须 grep successfully），setup-device.sh 已修复误报
• 发布证书（Release Profile）不做 UDID 绑定，应用市场分发无此问题

CASE-6 DevEco 自动签名勾选失败但已注册了应用+设备（2026-08-24）

• 现象：用户反复勾不上「自动生成签名/关联已注册应用」
• 事实：失败前 DevEco 已在 AGC 完成设备注册（auto_signdevice*）和应用记录（DSHharmony），只差最后生成 Profile
• 解法（已走通，勿重试 DevEco）：AGC 控制台手动建调试 Profile——证书选 autodebug*.cer（与本地 .p12 配对！dfwy 证书不配对会签名失败）、设备选目标真机、下载 .p7b 换到 build-profile.json5 的 profile 路径重建

CASE-7 浏览器自动化配方（CDP，2026-08-24 实战验证）

• 新版 Chrome 禁止默认配置开调试口：须 --user-data-dir=/tmp/xxx 独立配置 + 二进制直启（open --args 会丢参数；已有同配置实例会吞参数）
• 驱动脚本：/tmp/cdp.mjs（Runtime.evaluate）、/tmp/cdp-click.mjs（真实 Input 鼠标点击）、/tmp/cdp-key.mjs（键盘）
• AGC 控制台是 SPA+iframe（同源可穿透）：外层菜单 a.base-menu，内容在 iframe 内 el-plus 组件
• 合成 click() 对 el-plus 大部分组件无效，必须 CDP Input 真实点击；iframe 内坐标要加 iframe 偏移（marker div position:fixed 在 iframe 内坐标系）
• 坑：表单提交按钮对鼠标点击无响应（疑似遮挡），键盘路线生效：btn.focus() + Input.dispatchKeyEvent Enter
• 登录：独立配置目录无登录态，用户在窗口内自行扫码登录（AI 不接触密码），轮询 URL 离开登录页即完成

CASE-8 web 品牌替换全配方（2026-08-24，已验证）

• 目标：dsh web 界面 logo/标题/favicon 全部换成自有品牌，零分叉官方代码
• 机制：品牌走 dsh-client-ui-brand-official 客户端插件注册 3 个插槽（sidebar.brand.mark / sidebar.brand.name / conversation.hero.brand.mark）；sidebar.brand.name 在当前布局不渲染（26 个插槽清单实证），mark 双插槽渲染
• 配方：
  1. 仿 dsh-voice-client 写 dsh-brand-client（ModuleLoader bundle，package.json 需 dsh.client.platform=web，exports 路径必须 ./ 开头）
  2. profile 补丁停用官方品牌：同 id 重声明 - id: ui-brand-official + name + disabled: true（顶层 disable: 列表是无效语法！）
  3. insert 自有品牌插件
  4. document.title 会被 SPA 改回 → MutationObserver 守卫
• 坑：pnpm file: 依赖同版本不刷新（改插件要 bump version 或直接 cp 到 node_modules）
• 验证：CDP（9222 端口 Chrome）Runtime.evaluate 断言 title/favicon/aria-label 插槽/官方文案清零，全绿
• 桌面端：icns 用 sips+iconutil；托盘 template 字母用 Pillow 圆章描边法（沿路径盖圆模拟圆头笔画）

CASE-9 品牌替换二轮：插槽冲突/文案/locale 边界（2026-08-24，全绿）

• 冲突现象：双插件同插槽同 priority 0 → single slot already has a registration 报错横幅
• 正解：ctx.slots.register({ name, priority: -1 }, Comp)——数字小者渲染（slots 源码实证：c = n.priority ?? 0, lowest renders）；即使官方品牌因缓存页双加载也不报错、我方遮蔽
• 文案替换边界：slogan(hero.headline)/预览版(hero.preview) 是 conversation 插件的 locale 词条，而 LocaleRuntime.register 同 ns+locale 二次注册直接 throw（源码实证）→ 不能走注册覆盖，改用 DOM TreeWalker 文本替换 + MutationObserver 防抖重扫（排除 SCRIPT/STYLE/INPUT/OPTION）
• HARNESS 是启动屏 wordmark（[data-dsh-boot] 卡片，CSS module 类名不稳，用精确文本匹配替换）
• pnpm file: 依赖坑二连：同版本不刷新 + dsh web 启动会用 store 缓存覆盖手改的 node_modules → 正确更新姿势：bump version + rm -rf .pnpm/* + pnpm add file:…
• 验证基线（CDP 全量断言）：pluginError=false / slogan 新旧替换 / badge 新旧替换 / markCount=2 / title / favicon / dshText=false / harnessExact=0