@harmonyos-arkts/d2h 0.1.22 → 0.1.27-beta.202611022302

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "android-to-hmos-migration",
   "description": "基于确定性 facts、迁移报告与端到端验证的 Android 到 HarmonyOS 迁移插件",
-  "version": "0.1.22",
+  "version": "0.1.27",
   "license": "MIT",
   "keywords": [
     "android",

package/AGENTS.md

@@ -3,3 +3,5 @@
 处理迁移请求时，由当前正式主 Agent `agents/d2h.md` 统一编排专项 Skill。`agents/android-to-hmos-00-orchestrator.md`仅保留旧名称兼容，不是规则真源。
 
 以真实 HarmonyOS 应用质量为目标，以 AppGraph facts 和迁移报告降低遗漏风险。不要恢复已废弃的旧 SPEC/PLAN/TASK 多 Agent 文档流程或静态转译器；当前使用的 Kernel Task Plan（`droid2hmos task plan/validate/next/show` 派生计划）属于 Migration Kernel 协议，不在此列。
+
+`agents/`、`skills/` 用于迁移流程开发；安装器、宿主集成、检查脚本和对应测试集中在 `tooling/`。流程契约与运行支持仍在 `contracts/`、`schemas/`、`workflow/`。构建、检查和测试命令在仓库根目录运行。

package/README.md

@@ -20,7 +20,15 @@
 
 ## 安装
 
-默认安装到 OpenCode：
+不传 `--agent` 时，在终端用上下键选择安装目标，回车确认，也可输入序号或名称；前两项固定为 OpenCode、VS Code，不显示命令名或路径。检测到工具命令或配置目录时显示“可配置”，否则显示“未检测到”；VS Code 以发现鸿蒙插件为准。检测结果不代替安装校验。未检测到的工具仍可手动选择。
+
+```bash
+npx --yes @harmonyos-arkts/d2h@latest install
+```
+
+`install`、`upgrade` 默认执行 `--force` 行为，覆盖冲突的定义并更新受管理的工具链，无需额外传参。CI、管道等非交互环境必须显式传入 `--agent`。`upgrade` 同样支持交互选择，`doctor` 保留默认检查 OpenCode 的行为。
+
+直接安装到 OpenCode：
 
 ```bash
 npx --yes @harmonyos-arkts/d2h@latest install --agent opencode --force
@@ -46,6 +54,8 @@ npx --yes @harmonyos-arkts/d2h@latest install --agent vscode --force
 npx --yes @harmonyos-arkts/d2h@latest install --agent vscode --force --remote
 ```
 
+安装或升级时会自动清除指标插件缓存（`~/.cache/opencode/{packages,node_modules}`，macOS/Linux/Windows 路径一致；VS Code 场景为 `~/.harmonybot/opencode/vscode/cache/opencode/{packages,node_modules}`）中 `opencode-metrics-plugin*` 目录，OpenCode 会在下次启动时重新拉取最新版插件；`--dry-run` 只预览不删除。
+
 安装器会安装清单中验证过的 AppGraph 和 droid2hmos 版本，并安装迁移 Skill 和 `d2h` Agent。安装完成后请完全退出并重新启动对应应用。
 
 ## 检查与升级
@@ -102,10 +112,42 @@ npx --yes @harmonyos-arkts/d2h@latest upgrade --check --agent codex
 npx --yes @harmonyos-arkts/d2h@latest doctor --agent codex
 ```
 
-默认安装到 `~/.agents/skills/`，可用 `--config-dir <path>` 指定安装根目录（Skills 位于其 `skills/` 子目录）。新建 Codex 对话后调用 `$d2h` 开始或恢复迁移。迁移主入口由 `agents/d2h.md` 生成同名 Skill，专项 Skills 保留完整资源；`--link` 仅链接专项 Skills，主入口始终生成副本。安装器不改写 Codex 的 `config.toml` 或 `AGENTS.md`；模型、审批和沙箱权限由当前 Codex 会话配置继承。OpenCode 指标插件的 `--remote` 不适用于 Codex。
+默认安装到 `~/.codex/skills/`；设置 `CODEX_HOME` 时安装到其 `skills/` 子目录，可用 `--config-dir <path>` 指定安装根目录（Skills 位于其 `skills/` 子目录）。新建 Codex 对话后调用 `$d2h` 开始或恢复迁移。迁移主入口由 `agents/d2h.md` 生成同名 Skill，专项 Skills 保留完整资源；`--link` 仅链接专项 Skills，主入口始终生成副本。安装器不改写 Codex 的 `config.toml` 或 `AGENTS.md`；模型、审批和沙箱权限由当前 Codex 会话配置继承。OpenCode 指标插件的 `--remote` 不适用于 Codex。
+
+## Qoder、TRAE、Claude、DSH、ZCode、CodeBuddy、WorkBuddy
+
+使用 `--agent` 选择目标，无需指定 `--config-dir`：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@latest install --agent qoder --force
+npx --yes @harmonyos-arkts/d2h@latest upgrade --check --agent qoder
+npx --yes @harmonyos-arkts/d2h@latest doctor --agent qoder
+```
+
+将 `qoder` 替换为下表对应参数即可。各目标仅写入自己的技能目录及安装记录，主入口由 `agents/d2h.md` 生成 `skills/d2h/SKILL.md`，不改写宿主设置或安装 OpenCode 插件。
+
+| 工具 | `--agent` | 默认技能目录 | 调用入口 |
+| --- | --- | --- | --- |
+| [Qoder](https://docs.qoder.com/cli/Skills) | `qoder` | `~/.qoder/skills/` | `/d2h` |
+| [TRAE](https://docs.trae.ai/ide/skills) | `trae` | `~/.trae/skills/` | 在技能列表选择 d2h，或要求使用 d2h 技能 |
+| [TRAE 国内版](https://docs.trae.cn/ide_skills?lang=zh) | `trae-cn` | `~/.trae-cn/skills/` | 同上 |
+| [Claude Code](https://code.claude.com/docs/en/skills) | `claude` | `~/.claude/skills/` | `/d2h` |
+| [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/subsystems/skills.md) | `dsh` | `~/.dsh/skills/` | `/d2h` |
+| [ZCode](https://zcode.z.ai/en/docs/skill) | `zcode` | `~/.zcode/skills/` | `$d2h` |
+| [CodeBuddy](https://www.codebuddy.ai/docs/cli/skills) | `codebuddy` | `~/.codebuddy/skills/` | `/d2h` |
+| [WorkBuddy](https://www.workbuddy.cn/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/Skills-Market) | `workbuddy` | `~/.workbuddy/skills/` | 在技能列表选择 d2h，或要求使用 d2h 技能 |
+
+Claude Code、DSH 分别遵循 `CLAUDE_CONFIG_DIR`、`DSH_HOME`；`--config-dir` 优先于环境变量和默认目录。不同客户端版本的本地目录可能不同，可通过 `--config-dir` 指向实际技能目录的父目录。`--link`、`--dry-run`、`--force` 同 Codex；`--remote` 仅用于 OpenCode 系宿主，在这些工具上会提前拒绝。安装后新建会话查看技能列表；文件安装及校验通过不代表已完成各宿主内的迁移流程验收。
 
 ## 公共产物与执行工具
 
 `d2h workflow --help` 查看能力，`d2h workflow contract artifacts` 查看产物所有权。运行时与契约随 D2H 包分发，不再位于规划 Skill 内；只复制或删除某个 Skill 不影响公共工具。Python 解释器可用 `D2H_PYTHON` 显式指定。详见 [工作流解耦说明](docs/workflow-decoupling.md)。
 
 增量流程可先用 `d2h-spec-plan` 输出可评审波次计划，再由原 `d2h-spec-generate` 的 `from-plan` 模式展开所选成员，旧独立生成模式保留。新计划以 `spec_generation_policy=required-v1` 对未生成或失效正文阻止派发；评审用 `d2h workflow validate --planning-only`，生成交接见 `d2h workflow contract generation`。主入口 `d2h.md` 由人工适配。
+## 开发目录
+
+- `agents/`、`skills/`：迁移主流程与专项技能。
+- `tooling/`：安装器（`bin/`、`src/`）、宿主集成（`opencode/`）、检查与发布脚本（`scripts/`）及测试（`test/`）。
+- `contracts/`、`schemas/`、`workflow/`：流程契约、数据格式与运行支持。
+
+在仓库根目录运行 `npm run check` 和 `npm test`；编译产物仍输出到 `dist/`，CLI 入口保持不变。

package/agents/d2h.md

@@ -11,17 +11,18 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 必须覆盖所有页面、可见控件和状态、导航与 Dialog 流程、业务功能，以及影响行为的资源和配置。Android 源码与真实运行行为决定“做什么”，HarmonyOS 原生机制决定“怎么做”。无法等价的差异必须明确记录，不能静默省略或伪装成完成。
 
-迁移由 AI 读取 Facts、`.migration/utg/page.json`、页面 Spec、`batch_report.json`、Android 源码、HarmonyOS 代码和实际测试结果后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
+迁移由 AI 读取 Facts、`.migration/utg/page.json`、页面 Spec、`batch_report.json`、Android 源码、HarmonyOS 代码和实际测试结果后作出决策。
 
 ## 产物边界
 
-- `.migration/progress.json` 汇总七个阶段的进度。工作区就绪后执行 `droid2hmos progress init <ANDROID_PROJECT>`，恢复时保留已有记录；用 `progress update <ANDROID_PROJECT> --stage <STAGE_ID> --status <in_progress|completed|blocked>` 更新状态，阻塞原因用 `--blocker` 记录。按 CLI 的语义 ID 更新：架构规划为 `harmony-architecture`，Android 分析为 `android-analysis`；正文先规划架构，不按章节序号重排或改写 CLI 的阶段定义。仅在实际交付条件满足后标记完成，返工时同步受影响阶段；不手改 JSON。
+- `.migration/progress.json` 汇总七个阶段的进度。工作区就绪后执行 `droid2hmos progress init <ANDROID_PROJECT>`，恢复时保留已有记录；用 `progress update <ANDROID_PROJECT> --stage <STAGE_ID> --status <in_progress|completed|blocked>` 更新状态，阻塞原因用 `--blocker` 记录。 
+   按 CLI 的语义 ID 更新：架构规划为 `harmony-architecture`，Android 分析为 `android-analysis`。仅在实际交付条件满足后标记完成，返工时同步受影响阶段；不手改 JSON。
 - `.migration/architecture-plan/architecture-plan.md` 保存架构选项、推荐/选定方案、源到目标目录归属、主要依赖、共享所有者及风险。实际创建/复用基础工程与目录时才附 `shell-receipt.json`；规划或目录壳子不能作为目标能力已实现的证据。
 - `.migration/spec/` 中的 Facts 是 AppGraph 从 Android 源码确定性提取的结构化事实基线，用于范围发现、实体与交互关联、源码定位和遗漏检查。Facts 可能包含 unresolved 项或存在抽取遗漏，不能替代对 Android 源码及必要运行行为的阅读核验。
 - `.migration/utg/page.json` 是页面、到达路径和导航计划的输入，也是页面 Spec 使用的运行路径依据。
 - `.migration/page-specs/pages.json` 保存 AI 作出的页面范围、顺序、评分和证据决策。
-- 每个 `.migration/page-specs/page_NNNN_<name>-<id>/` 只包含 `spec.md`。不得生成 `ui-design.md`，也不得复制截图或 `view.xml` 到页面包。
-- `.migration/page-specs/batch_report.json` 是结构化页面账本，包含 `tasks[]`、`summary` 和 `regression`，记录页面状态、实现、证据、差异和回归结论。由 `d2h-spec-generate` 使用 `build_batch_report.py` 初始化；开发后原位更新任务、汇总和历史，不得重新生成覆盖。
+- 每个 `.migration/page-specs/page_NNNN_<name>-<id>/` 只包含 `spec.md`。
+- `.migration/page-specs/batch_report.json` 是唯一执行账本，记录逐 Spec 的实现、证据、差异和回归结论。主 Agent 在进入开发时按有效计划初始化，恢复时保留已有账本；后续原位更新并保留历史，不得重新生成覆盖。
 - Spec、账本、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
 
 ## 场景与 Skill 路由
@@ -35,10 +36,11 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 从源码生成可审计功能清单、MVP/core/full 阶段、逐功能技术栈/三方 SDK/SO/权限与跨仓实现状态 | `d2h-app-solution` |
 | 从 Android 源码生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json` | `d2h-utg-static-generate` |
 | 需要 AI 修复源码派生 UTG，或在 Android 设备上按已有计划采集运行时证据 | `d2h-utg-ai-generate` |
-| 根据 Facts、`.migration/utg/page.json` 和源码生成 `pages.json`、逐页 `spec.md` 与初始 `batch_report.json` | `d2h-spec-generate` |
-| 按 `batch_report.json` 串行完成单页面实现、构建、测试、提交和账本更新 | `d2h-spec-develop` |
+| 根据 Facts、源码和 UTG 生成页面计划、完整 `spec.md` 及初始账本 | `d2h-spec-generate` |
+| 根据已确认功能范围与已有页面任务规划里程碑和波次 | `d2h-spec-plan` |
+| 按固定 Spec 范围串行实施、构建、检查并返回提交与证据 | `d2h-spec-develop` |
 | 根据 Android 工程结构与必要源码做目录级架构规划，详列推荐方案并对照另两套；确认并要求创建后落地目录壳子 | `d2h-architecture-plan` |
-| 规划或编写 ArkTS 架构、状态、导航和页面代码 | `arkts-mvvm-architecture` |
+| 落实模块内 MVVM 分层、状态管理及 ArkTS 编码规范 | `arkts-mvvm-architecture` |
 | 生成或执行 Python Hypium 端到端功能测试 | `d2h-hypium-forge` |
 | 迁移应用名称、图标、版本号、包名等身份信息 | `arkts-app-identity` |
 | 迁移用户可见文案与多语言资源，或清理硬编码文案 | `arkts-i18n` |
@@ -46,7 +48,7 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 修复 HarmonyOS 图片或图标尺寸、比例失真 | `arkts-icon-sizing` |
 | 迁移 C/C++ 原生库（源码重编、带 patch 重放、三方预编译 .so/JNI 改写 NAPI），或判断现有 .so/.a 能否直接用于鸿蒙 | `d2h-native-library-build`（情况③查替代时配合 `native-library-substitution`） |
 | 诊断 ArkTS 构建、运行时、UI 自动化或迁移验证故障 | `harmonyos-migration-playbook` |
-| 实现涉及不确定的 @kit.* Kit / @ohos.* 模块 API、ArkUI 组件行为或平台能力（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等），构建/测试失败需核对 API 签名、权限、错误码，或核验已选型 ohpm 库用法 | `d2h-cloud-knowledge` |
+| 云侧鸿蒙知识库 | `d2h-cloud-knowledge` |
 | 迁移完整结束或本次运行明确中止后复盘流程 | `reviewing-migration-process` |
 | 首次安装、工具缺失、版本/能力不符或主动升级 | `managing-d2h-toolchain` |
 
@@ -54,80 +56,60 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 ### 一、启动或恢复
 
-加载 `managing-d2h-toolchain` skill 完成基础工具链预检和安装，仅需要执行一次
-
-加载 `preparing-migration-workspace`，完成工具链、Android/HarmonyOS 工程、迁移工作区、配置、基线和设备检查。迁移工作区使用 Android 工程父目录下的 `<工程名>-migration/.migration/`，不得写入 Android 工程内部。
-
-`.migration/progress.json` 就绪（`progress init` 首次创建或恢复时已存在）后，立即加载 `d2h-dashboard` 自动启动实时看板并用默认浏览器打开网页；看板启动或打开失败只记录，不阻塞迁移。
-
-设备暂不可用时可以继续静态分析、页面规划和不依赖设备的实现，但交互页面不能标记为验证通过，也不能进入最终完成门禁。
+1. 加载 `managing-d2h-toolchain` skill 完成基础工具链预检和安装，仅需要执行一次
+2. 加载 `preparing-migration-workspace`，完成工具链、Android/HarmonyOS 工程、迁移工作区、配置、基线和设备检查。迁移工作区使用 Android 工程父目录下的 `<工程名>-migration/.migration/`，不得写入 Android 工程内部。
+3. `.migration/progress.json` 就绪（`progress init` 首次创建或恢复时已存在）后，立即加载 `d2h-dashboard` 自动启动实时看板并用默认浏览器打开网页；看板启动或打开失败只记录，不阻塞迁移。
 
 ### 二、功能清单生成
 
 1. 加载 `d2h-app-solution`，直接读取 Android 源码完成功能清单、版本阶段及逐功能技术栈、三方 SDK/SO 和权限分析，产物写入 `.migration/feature-analysis/`，生成 `inventory.json` 功能清单。
+2. 功能范围确认后，评估已选功能是否实际依赖测试账号、环境地址、白名单、权限及第三方配置，仅将必需项作为前置条件；可选项允许留空，不阻塞流程，无需外部条件时不创建模板或要求填写。按需在迁移工作区的 `.migration/private/test-credentials.json`（账号、密码、API Key 等凭据）和 `test-environment.json`（环境、账号标识、准备事项）创建占位模板；先确认该私有目录被所在 Git 仓库忽略，不覆盖已有文件。告知开发者绝对路径、需填字段和受影响功能，请其本地填写后回复“已填写”；已有有效配置直接复用，不等待无关条件阻塞后续准备。
+3. 凭据仅供实际登录或测试步骤通过本地文件读取，不进入提示词、日志、Spec、账本、看板或测试代码。账本及看板只记录文件位置、账号标识、准备状态和影响；验证码、扫码等临时操作在实际登录时请求配合，不长期保存。
 
 ### 三、HarmonyOS 工程架构设计
 
-1. 加载 `d2h-architecture-plan`，输入 Android 工程根和第二阶段已有功能分析作为定位线索。遵循该 Skill 的默认 Android 阅读范围、鸿蒙工程结合选择及目录级分析深度，不另做全量扫描或完整业务链审计。
-2. 将规划写入 `.migration/architecture-plan/architecture-plan.md`：默认详列推荐方案目录与归属，另两套给结构差异对照。沿用该 Skill 的基础依赖/业务 feature 分层和共享所有权规则；候选页面族是目录设计依据，不是最终页面/Spec 清单。
-3. 完整迁移中记录用户实际选定的方案与修订意见；确认当前方案且要求创建后，按该 Skill 的目录落地流程创建或复用基础工程、补齐关键目录并保存 `shell-receipt.json`。已有“采用推荐并创建”授权直接执行；预检已有壳则复用，不把目录壳子当成注册完成的模块或业务实现。
+1. 加载 `d2h-architecture-plan`，输入 Android 工程目录、已确认功能范围和第二阶段已有功能分析作为定位线索。遵循该 Skill 的默认 Android 阅读范围、鸿蒙工程结合选择及目录级分析深度，不另做全量扫描或完整业务链审计。
+2. 按该 Skill 在对话中比较三套目录结构、职责与取舍，说明推荐理由并取得用户实际选择，处理修订意见；已有当前有效选择时直接沿用。用户回答完成后，写入 `.migration/architecture-plan/architecture-plan.md`（详列三套目录并标明最终方案）和 `architecture-plan.json`（项目名称、最终嵌套目录、主要决定与依赖说明），供只读看板展示。沿用该 Skill 的基础依赖/业务 feature 分层和共享所有权规则；候选页面族不是最终页面/Spec 清单。
+3. 确认当前方案且已要求创建后，按该 Skill 的目录落地流程重新读取最终 JSON 与 Markdown 的实际确认，创建或复用基础工程、补齐关键目录并保存 `shell-receipt.json`。完整迁移已有创建要求，或已有“采用推荐并创建”授权时，不追加确认；预检已有壳则复用，不把目录壳子当成注册完成的模块或业务实现。
 4. 创建/复用后核对 `.migration/config.json` 的 `harmonyProject` 与实际目标根一致；路径变化时通过现有 CLI 配置入口同步。向后续阶段交接当前规划路径、选定方案、目标根、模块/目录归属、共享所有者与必要前置，实际落地时再附 receipt 及未完成项。完整迁移的架构阶段须完成选型，以及本次要求的创建/复用后才能标记完成；仅请求规划则按 Skill 的规划交付条件结束。
+5. 目标工程和目录落地后，按场景完成资源迁移，再生成 Spec；仅请求架构规划时不执行资源迁移。
 
-选型尚未明确时，可以继续下一阶段不依赖目标结构的 Android 分析；确认前不据候选方案创建业务目录或固定 Spec 的目标归属。只影响实现的 SDK/Native 未知保留为相关能力前置；仍影响模块/目录的未知明确待决范围，不伪称结构已经确定。
+- 迁移应用身份时使用 `arkts-app-identity`。
+- 迁移字符串和多语言时使用 `arkts-i18n`，禁止用 `.ets` 硬编码代替字符串资源迁移。
+- 转换图片和 drawable 时使用 `android2hmos_resources_convert`；覆盖源码实际使用的资源目录，发现尺寸或比例问题时使用 `arkts-icon-sizing`。
 
 ### 四、Android 工程分析
 
 1. 加载 `d2h-utg-static-generate`，生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json`，并对照真实 Android 源码核验页面、入口、交互、数据流和 unresolved 项。
-2. 需要修复 UTG 或有 Android 设备可用于运行时采集时，加载 `d2h-utg-ai-generate`。运行时证据留在该 Skill 定义的位置，不复制进页面 Spec 包。
-3. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入页面 Spec，并在 `batch_report.json` 中记录发现与处理情况。
-4. 发现架构规划遗漏的职责、共享状态或依赖冲突时，返回架构阶段局部修订受影响归属，保留已有用户选择；涉及重要取舍时展示变更，不重做全部架构分析，也不由页面候选静默裁剪真实业务。
+2. 加载 `d2h-utg-ai-generate` 补充 utg 未识别的项目。
 
 ### 五、spec 设计与生成
-加载 `d2h-spec-generate`，由 AI 基于当前 Facts、`.migration/feature-analysis/` 的功能清单、`.migration/utg/page.json`、Android 源码、已选定架构和实际 HarmonyOS 工程状态完成：
-
-1. 识别所有页面、Dialog、Sheet 和具有独立行为的页面模式。
-2. 决定页面依赖、开发顺序、评分与证据账本，写入 `.migration/page-specs/pages.json`。
-3. 为每个 `page_NNNN_<name>-<id>` 生成且只生成一个 `spec.md`。
-4. 使用该 Skill 自带的 `build_batch_report.py` 生成初始 `batch_report.json`。
 
-`d2h-spec-generate` 是页面范围、顺序和 Spec 格式的规则真源；在已选目录/共享边界内细化页面与实现范围，不能直接把架构候选当最终页面身份，也不重新选一套目录。新证据需要改变边界时返回最小修订。主 Agent 不在本文重复实现页面拆分算法，也不使用其他静态脚本生成、选择或执行任务。
+1. 加载 `d2h-spec-generate`，根据 Facts、`.migration/utg/page.json`、源码和目标工程现状确定页面边界、依赖与顺序，生成 `pages.json`、页面 `spec.md` 和初始 `batch_report.json`。已有产物按该技能规则复用，不能覆盖执行历史。
+2. 将已确认功能范围、选定架构、已有页面产物及未满足的外部条件交给 `d2h-spec-plan`，规划范围映射、任务排序、里程碑和波次，将受影响任务及条件记入波次前置与风险；主 Agent 按技能要求核对规划结果。
+3. 执行顺序以 spec-plan 的里程碑、波次和任务排序为准；页面归属、生成时的顺序和依赖作为规划依据。排序不得违反实际前置，不拆合 Spec、不改变正文布局或账本任务身份。
 
 ### 六、代码转换
 
-1. 根据实际工程状态按场景加载专项完成代码规范和资源迁移
+1. 编写 ArkTS 前加载 `arkts-mvvm-architecture`，落实模块内分层与编码规范；目录和模块归属沿用已确认架构方案，不重新规划。沿用已迁移的资源，缺失时按对应专项 Skill 补齐；不得用 emoji 或字符替代已有图标资源。
 
-- 规划工程分层、状态管理、导航和共享能力时使用 `arkts-mvvm-architecture`。
-- 迁移应用身份时使用 `arkts-app-identity`。
-- 迁移字符串和多语言时使用 `arkts-i18n`，禁止用 `.ets` 硬编码代替字符串资源迁移。
-- 转换图片和 drawable 时使用 `android2hmos_resources_convert`；发现尺寸或比例问题时使用 `arkts-icon-sizing`。
-
-
-2. 加载 `d2h-spec-develop`，以严格串行方式执行 spec 开发。每个独立 page-worker 负责 3 个 spec 页面的开发；剩余不足 3 个时按实际数量派发，同一时间只运行一个 page-worker：
+2. 加载 `d2h-spec-develop`，主 Agent 按有效计划初始化或恢复 `batch_report.json`，按里程碑、波次和任务排序严格串行推进。任意时刻只运行一个独立 page-worker；可将同一波次内排序相邻、共享页面或模块上下文的 2～3 个 Spec 交给同一 worker，具体分组和逐项交接按该技能执行：
 
-a. 主 Agent 按 `batch_report.json` 选择顺序最前且未达到 `implemented/passed/passed` 的最多 3 个页面，作为当前 worker 的任务批次。
-b. 只派发一个独立 page-worker，由该 worker 按顺序逐页完成当前批次。worker 必须加载 `d2h-spec-develop`，同一时间只开发当前一个页面，不得提前预研或修改后续页面，也不得领取批次外页面。
-c. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产。先确认本次构建的 HAP 已安装到目标设备，再按该 Skill 执行当前页面及受影响功能的定向测试，保留实际结果、日志和必要截图。主 Agent 核对执行用例及其断言是否覆盖 Spec 功能项，不能仅凭进程退出码或汇总文案判定通过。
-d. 页面实现与测试通过后，在 `batch_report.json` 当前页面明细中记录真实实现文件、Android 源码依据、本次构建与 Forge 测试的实际结果及证据路径，以及差异或阻塞。未产出或未保存的结果、日志如实记录为缺失，不得填写假定存在的路径或据此标记通过。
-e. 主 Agent 完成当前页面的实现提交，原位更新 `batch_report.json`，并按 Skill 的页面完成清单复核实现、构建、测试、证据、提交和工作区状态。
-f. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，同一 worker 才能继续批次内下一页；当前批次全部闭环后，主 Agent 才能选择下一批页面并派发新的 worker。
+a. 主 Agent 按账本中的有效规划，只从纳入的任务中，根据实际前置证据选择当前波次内按任务排序最早未完成且前置满足的任务，固定本次任务 ID、版本和允许路径；未纳入任务不得因规格已生成而派发。进入相关波次前核对外部条件，区分实现与验收所需条件；仅阻塞实际依赖项，主 Agent 按依赖调整后继续其他可执行任务，不能用固定登录成功或伪造结果绕过验收。
+b. 向 page-worker 交接固定的有序任务 ID、当前 Spec、源码与目标工程、Git 基线、真实共享接口和检查要求。worker 加载 `d2h-spec-develop`，只实施当前获授权的 Spec；主 Agent 组织测试与验收，各 Spec 独立记录结果。
+c. 主 Agent 按页面流程组织检查；需要生成或更新 Python Hypium 测试资产时加载 `d2h-hypium-forge`。核对实际断言、执行结果和证据，未执行、缺失或过期的结果不能标记通过。
+d. 主 Agent 复核作用域提交和工作区，核对 `batch_report.json` 中记录的真实实现文件、来源、本次构建与测试证据、差异及阻塞，原位更新并保留历史。
+e. 当前任务闭环后，重新核对前置并评估上下文与宿主续会话能力，适合时复用同一 worker 继续组内下一项，否则明确调整分组并重新派发剩余任务；本组完成后再按计划派发下一组。受阻时继续修复当前任务或记录外部阻塞，不自动跳过或扩组。里程碑与波次组织交付顺序，不拆分页面闭环或改变验收要求。
 
 若当前环境不支持独立 page-worker，必须明确报告该开发模式无法执行，不能静默改成主 Agent 批量开发。
 
-### 七、测试与交付
-
-全部页面达到 `implemented/passed/passed` 后：
-
-1. 加载 `d2h-hypium-forge`，在已安装当前 HAP 的目标设备上执行覆盖全部迁移范围内功能场景的完整 Python Hypium 回归，保留本次实际执行结果和日志。核对用例范围、执行数和各项状态；零执行、失败、错误或必测场景被跳过、未执行时均不能通过，历史 PASS 不能替代本次完整回归。
-2. 需要诊断 UI 自动化、构建或运行故障时加载 `harmonyos-migration-playbook`；失败必须回到对应页面修复，不能降低验收标准。
-3. 主 Agent 对照各页 Spec、源码、实际实现和设备结果完成行为审查，将结论、被测 HAP 与设备、完整回归结果和实际证据路径、差异及未解决问题记录到 `batch_report.json` 的批次回归部分。直接核对账本队列、页面明细、汇总和引用证据的一致性，满足完成条件后才能宣布迁移完成。
-4. 完整结束或明确中止后加载 `reviewing-migration-process` 生成流程复盘；复盘不是完成条件。
-
 ## 持续执行与人工介入
 
 迁移开始后默认连续执行，不得在页面或阶段之间询问“是否继续”。只有以下情况允许暂停：
 
 - 禁止依据模型自行估算的“剩余 token”“上下文百分比”“本轮剩余容量”等决定停止、收尾、汇报后等待或要求用户开启新会话。此类估算不可信。
 - 用户主动中断、修改需求或发出新指令。
+- 首次范围尚未确认或用户正在调整功能清单；收到明确回答后从对应环节继续，已有有效选择不重复询问。
 - 架构选型或重要修订需要用户决定时，只等待依赖该选择的目标目录落地/Spec 分配；独立的 Android 分析可继续。仅请求架构规划则交付即可，不强求立即选型；已有“采用推荐并创建”明确授权时记录后继续，不重复询问。
 - 真机签名、开发者账号、权限或凭据必须由用户完成，且没有可用替代方案。
 - 设备、CLI、构建环境或外部服务持续不可用，完成自诊和有限重试后仍确认是外部问题。
@@ -153,12 +135,12 @@ f. 前页面未闭环、仍有页面所属未提交修改或复核失败时，
 
 ## 完成条件
 
-只有同时满足以下条件，才允许宣布迁移完成：
+以下条件按本次已确认开发范围核对；计划未纳入的任务保留规格和账本状态，不阻塞本次范围交付，也不得将本次完成表述为全量迁移完成。只有同时满足以下条件，才允许宣布本次范围完成：
 
 - Preflight、Facts、UTG、页面 Spec、`batch_report.json` 和证据对应当前源码。
 - `pages.json` 覆盖全部已知页面或明确记录排除原因。
 - 每个已知页面、Dialog、Sheet 和关键模式都有唯一 `spec.md`，页面包中没有额外产物。
-- `batch_report.json` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
+- `batch_report.json` 覆盖当前确认范围内的全部 Spec，逐项验收、波次目标和页面约定范围均已满足，没有未解决阻塞；以当前账本契约与实际证据核验，不以旧页面状态字段替代逐项验收。
 - 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现。
 - HarmonyOS 工程构建、安装、启动成功；当前 HAP 的 Forge 完整回归通过，没有失败、错误或必测场景未执行。
 - `batch_report.json` 已记录最终行为审查、完整回归结论及实际证据路径，队列、页面明细和汇总一致。

package/dist/bin/install-opencode.js

@@ -11,12 +11,15 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
 import { inspectInstallation, installOpenCode } from '../src/install-opencode.js';
+import { findMetricsPluginCacheDirs, metricsPluginCacheRoots } from '../src/metrics-plugin.js';
 import { inspectToolchain, installToolchain, loadToolchain } from '../src/toolchain.js';
 import fs from 'node:fs';
 import { inspectVSCodeInstallation, installVSCode } from '../src/install-vscode.js';
-import { codexConfigRoot, inspectCodexInstallation, installCodex } from '../src/install-codex.js';
+import { isSkillHost, skillHosts, skillHostConfigRoot, inspectSkillHostInstallation, installSkillHost } from '../src/install-skills.js';
+import { installTuiExtension, inspectTuiExtension } from '../src/install-tui-extension.js';
 import { runWorkflow } from '../src/workflow.js';
-const help = `Install this package's skills and agents into OpenCode, DevEco Code or Codex.
+import { selectAgent } from '../src/select-agent.js';
+const help = `Install this package's skills and agents into supported AI coding tools.
 
 Usage: d2h [options]
 
@@ -24,7 +27,7 @@ Usage: d2h [options]
   d2h upgrade         Reapply this package's tested toolchain and definitions
   d2h upgrade --check Preview version and installation status only
   d2h workflow       Validate artifacts, record execution and generate reports
-  d2h doctor [--agent opencode|deveco|vscode|codex] [--config-dir <path>]
+  d2h doctor [--agent <name>] [--config-dir <path>]
                       Check definitions, host environment and CLI capabilities
 
   --check-env         Check host tools and write reports without installing skills
@@ -32,14 +35,18 @@ Usage: d2h [options]
                        Use d2h --check-env --help for check options
 
   --source-dir <path>  Source root (defaults to this package)
-  --agent <name>       opencode (default), deveco, vscode or codex
+  --agent <name>       opencode, vscode, deveco, codex, qoder, trae,
+                       trae-cn, claude, dsh, zcode, codebuddy or workbuddy
+                       Omit for interactive selection with local detection hints
   --extension-dir <path>  VS Code HarmonyOS Dev Assistant extension root
   --config-dir <path>  Override the selected agent's config root
                        OPENCODE_CONFIG_DIR / DEVECO_CONFIG_DIR, or
                        $XDG_CONFIG_HOME/<agent>, or ~/.config/<agent>
-                       Codex: ~/.agents (skills under skills/; --config-dir overrides)
+                       Codex: $CODEX_HOME or ~/.codex; other skill hosts: ~/.<agent>
+                       Skills under skills/; trae-cn uses ~/.trae-cn
+                       Claude/DSH also honor CLAUDE_CONFIG_DIR/DSH_HOME
   --link              Create absolute symbolic links (development only)
-  --force             Replace conflicting definitions and managed CLI npm links
+  --force             Replace conflicting definitions and managed CLI npm links (default)
   --remote            Use opencode-metrics-plugin instead of the default lite plugin
   --dry-run           Print operations without writing files
   --skip-tools        Install definitions only (local development)
@@ -75,10 +82,10 @@ try {
             else
                 throw new Error(`unknown doctor option: ${arg}`);
         }
-        if (!['opencode', 'deveco', 'vscode', 'codex'].includes(agent))
+        if (!['opencode', 'deveco', 'vscode'].includes(agent) && !isSkillHost(agent))
             throw new Error(`unsupported agent: ${agent}`);
-        configDir ??= agent === 'codex' ? codexConfigRoot() : process.env[agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), agent);
-        const installation = agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : agent === 'codex' ? inspectCodexInstallation(configDir) : inspectInstallation(configDir);
+        configDir ??= isSkillHost(agent) ? skillHostConfigRoot(agent) : process.env[agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), agent);
+        const installation = agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : isSkillHost(agent) ? inspectSkillHostInstallation(agent, configDir) : inspectInstallation(configDir);
         const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
         const definitionsMatch = installation.status === 'passed' && installation.packageVersion === packageVersion &&
             (agent === 'vscode' || ('agent' in installation && installation.agent === agent));
@@ -86,7 +93,13 @@ try {
         const results = inspectToolchain(packageRoot);
         for (const item of results)
             console.log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}; capabilities ${JSON.stringify(item.capabilities)}`);
-        const checkerUrl = new URL('../../scripts/check-environment.mjs', import.meta.url);
+        const pluginCache = isSkillHost(agent) ? [] : findMetricsPluginCacheDirs(metricsPluginCacheRoots(agent));
+        console.log(`plugin cache: ${pluginCache.length ? `${pluginCache.join(', ')}; cleared by d2h install/upgrade` : 'none'}`);
+        if (agent === 'opencode' || agent === 'vscode') {
+            const tui = inspectTuiExtension({ agent: agent === 'vscode' ? 'vscode' : 'opencode', extensionDir });
+            console.log(`${tui.status}: opencode-tui-extension ${tui.summary}`);
+        }
+        const checkerUrl = new URL('../../tooling/scripts/check-environment.mjs', import.meta.url);
         const { main } = await import(__rewriteRelativeImportExtension(checkerUrl.href));
         const environmentExit = await main([]);
         if (environmentExit !== 0 || !definitionsMatch || results.some(item => item.status !== 'passed'))
@@ -95,7 +108,7 @@ try {
     else if (args.includes('--check-env')) {
         if (args.filter(arg => arg === '--check-env').length !== 1)
             throw new Error('--check-env may only be specified once');
-        const checkerUrl = new URL('../../scripts/check-environment.mjs', import.meta.url);
+        const checkerUrl = new URL('../../tooling/scripts/check-environment.mjs', import.meta.url);
         const { main } = await import(__rewriteRelativeImportExtension(checkerUrl.href));
         process.exitCode = await main(args.filter(arg => arg !== '--check-env'));
     }
@@ -109,7 +122,7 @@ try {
         let remote = false;
         const options = {
             sourceDir: packageRoot,
-            agent: 'opencode',
+            force: true,
         };
         for (let index = 0; index < installArgs.length; index++) {
             const arg = installArgs[index];
@@ -142,43 +155,50 @@ try {
                 throw new Error(`unknown option: ${arg}`);
             }
         }
-        if (!options.agent || !['opencode', 'deveco', 'vscode', 'codex'].includes(options.agent)) {
-            throw new Error(`unsupported agent: ${options.agent}; choose opencode, deveco, vscode or codex`);
+        options.agent ??= await selectAgent(extensionDir);
+        if (!options.agent || (!['opencode', 'deveco', 'vscode'].includes(options.agent) && !isSkillHost(options.agent))) {
+            throw new Error(`unsupported agent: ${options.agent}; choose opencode, deveco, vscode or ${Object.keys(skillHosts).join(', ')}`);
         }
-        if (options.agent === 'codex' && remote)
-            throw new Error('--remote is not supported by Codex');
+        if (isSkillHost(options.agent) && remote)
+            throw new Error(`--remote is not supported by ${skillHosts[options.agent].label}`);
         if (options.agent !== 'vscode' && extensionDir)
             throw new Error('--extension-dir requires --agent vscode');
         if (options.agent === 'vscode' && options.configDir)
             throw new Error('--config-dir is not used for VS Code; use --extension-dir');
-        options.configDir ??= options.agent === 'codex' ? codexConfigRoot() : process.env[options.agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), options.agent);
+        options.configDir ??= isSkillHost(options.agent) ? skillHostConfigRoot(options.agent) : process.env[options.agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), options.agent);
         if (checkOnly) {
-            const installation = options.agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : options.agent === 'codex' ? inspectCodexInstallation(options.configDir) : inspectInstallation(options.configDir);
+            const installation = options.agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : isSkillHost(options.agent) ? inspectSkillHostInstallation(options.agent, options.configDir) : inspectInstallation(options.configDir);
             console.log(`definitions ${installation.status}: ${installation.summary}`);
             for (const item of inspectToolchain(packageRoot))
                 console.log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}`);
+            const pluginCache = isSkillHost(options.agent) ? [] : findMetricsPluginCacheDirs(metricsPluginCacheRoots(options.agent));
+            console.log(`plugin cache: ${pluginCache.length ? `${pluginCache.join(', ')}; cleared by d2h install/upgrade` : 'none'}`);
         }
         else if (!skipTools)
             installToolchain(packageRoot, { dryRun: options.dryRun, force: options.force });
         else if (!explicitSource && !options.dryRun)
             console.log(`Skipped managed CLI installation (${Object.keys(loadToolchain(packageRoot).tools).join(', ')}).`);
         if (!checkOnly) {
-            if (options.agent === 'vscode')
-                installVSCode({ sourceDir: options.sourceDir, extensionDir, remote, dryRun: options.dryRun });
-            else if (options.agent === 'codex')
-                installCodex({ ...options, remote });
+            let vscodeExtensionRoot;
+            if (options.agent === 'vscode') {
+                vscodeExtensionRoot = installVSCode({ sourceDir: options.sourceDir, extensionDir, remote, dryRun: options.dryRun }).extensionRoot;
+            }
+            else if (isSkillHost(options.agent))
+                installSkillHost(options.agent, { ...options, remote });
             else
                 installOpenCode({ ...options, remote });
+            if ((options.agent === 'opencode' || options.agent === 'vscode') && !skipTools)
+                installTuiExtension({ dryRun: options.dryRun, force: options.force, extensionRoot: vscodeExtensionRoot });
             if (!options.dryRun) {
                 const target = options.agent === 'vscode' ? 'VS Code HarmonyOS Dev Assistant' :
-                    options.agent === 'deveco' ? 'DevEco Code' : options.agent === 'codex' ? 'Codex' : 'OpenCode';
+                    options.agent === 'deveco' ? 'DevEco Code' : isSkillHost(options.agent) ? skillHosts[options.agent].label : 'OpenCode';
                 const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
                 console.log('\n============================================================');
                 console.log(`[D2H] Installation successful / 安装成功`);
                 console.log(`Target / 目标: ${target}`);
                 console.log(`Version / 版本: ${packageVersion}`);
                 console.log('Agent: d2h');
-                console.log(options.agent === 'codex' ? 'Next / 下一步: start a new Codex conversation and invoke $d2h.' : `Next / 下一步: restart ${target}, then select the d2h Agent.`);
+                console.log(isSkillHost(options.agent) ? `Next / 下一步: start a new ${target} conversation and invoke ${skillHosts[options.agent].invocation}.` : `Next / 下一步: restart ${target}, then select the d2h Agent.`);
                 console.log('============================================================');
             }
         }

package/dist/src/install-codex.js

@@ -1,131 +1,10 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { stat, digest, sameTree, contains, resolvedLocation } from './install-opencode.js';
+import { installSkillHost, inspectSkillHostInstallation, skillHostConfigRoot } from './install-skills.js';
 export function codexConfigRoot() {
-    return path.join(os.homedir(), '.agents');
-}
-// Keep the orchestration prompt as an explicitly invokable skill: custom agents
-// are subagents in Codex, whereas D2H needs to drive the main conversation.
-function definitions(sourceRoot) {
-    const skills = path.join(sourceRoot, 'skills');
-    const entries = fs.readdirSync(skills).sort()
-        .filter(name => fs.existsSync(path.join(skills, name, 'SKILL.md')))
-        .map(name => ({ name, source: path.join(skills, name) }));
-    if (!entries.length)
-        throw new Error(`no skills found under ${skills}`);
-    if (entries.some(entry => entry.name === 'd2h'))
-        throw new Error('reserved Codex orchestration skill: d2h');
-    const prompt = fs.readFileSync(path.join(sourceRoot, 'agents', 'd2h.md'), 'utf8');
-    if (!/^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(prompt))
-        throw new Error('d2h agent front matter missing');
-    return [...entries, { name: 'd2h', content: prompt }];
+    return skillHostConfigRoot('codex');
 }
 export function inspectCodexInstallation(configDir = codexConfigRoot()) {
-    const root = path.resolve(configDir);
-    const receipt = path.join(root, '.d2h-codex-installation.json');
-    if (!fs.existsSync(receipt))
-        return { status: 'missing', summary: `installation record missing: ${receipt}` };
-    const record = JSON.parse(fs.readFileSync(receipt, 'utf8'));
-    if (record.schemaVersion !== 1 || record.agent !== 'codex' || !Array.isArray(record.entries) || !record.entries.length) {
-        throw new Error(`invalid installation record: ${receipt}`);
-    }
-    const changed = record.entries.filter(entry => {
-        if (!/^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$/.test(entry.name))
-            throw new Error(`invalid installation entry: ${entry.name}`);
-        const target = path.join(root, 'skills', entry.name);
-        return !stat(target) || digest(target) !== entry.digest;
-    });
-    return { status: changed.length ? 'failed' : 'passed', agent: 'codex', packageVersion: record.packageVersion,
-        summary: changed.length ? `changed or missing: ${changed.map(entry => entry.name).join(', ')}` : `${record.entries.length} installed skills verified` };
+    return inspectSkillHostInstallation('codex', configDir);
 }
-export function installCodex({ sourceDir, configDir = codexConfigRoot(), link = false, force = false, dryRun = false, remote = false, log = console.log }) {
-    if (remote)
-        throw new Error('--remote metrics plugins are not supported by Codex');
-    if (!configDir || ['.', '..'].includes(configDir))
-        throw new Error(`unsafe Codex config directory: ${configDir}`);
-    const sourceRoot = fs.realpathSync(path.resolve(sourceDir));
-    const root = resolvedLocation(path.resolve(configDir));
-    if (root === path.parse(root).root || root === fs.realpathSync(os.homedir()) ||
-        contains(sourceRoot, root) || contains(root, sourceRoot))
-        throw new Error(`unsafe Codex config directory: ${configDir}`);
-    const skillsRoot = path.join(root, 'skills');
-    if (stat(skillsRoot)?.isSymbolicLink())
-        throw new Error(`refusing linked installation directory: ${skillsRoot}`);
-    const receipt = path.join(root, '.d2h-codex-installation.json');
-    if (stat(receipt)?.isSymbolicLink())
-        throw new Error(`refusing linked installation record: ${receipt}`);
-    const entries = definitions(sourceRoot).map(entry => {
-        const target = path.join(skillsRoot, entry.name);
-        const existing = stat(target);
-        const unchanged = entry.source ? (link && existing?.isSymbolicLink()
-            ? path.resolve(path.dirname(target), fs.readlinkSync(target)) === entry.source
-            : !link && sameTree(entry.source, target))
-            : existing?.isDirectory() && !existing.isSymbolicLink() &&
-                fs.readdirSync(target).length === 1 && fs.existsSync(path.join(target, 'SKILL.md')) &&
-                fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8') === entry.content;
-        if (!unchanged && existing && !force)
-            throw new Error(`skill '${entry.name}' already exists at ${target}; rerun with --force`);
-        return { ...entry, target, unchanged };
-    });
-    if (dryRun) {
-        for (const entry of entries)
-            log(`would install Codex skill: ${entry.name} -> ${entry.target}`);
-        return { skills: entries.length, configRoot: root };
-    }
-    fs.mkdirSync(skillsRoot, { recursive: true });
-    if (!contains(root, fs.realpathSync(skillsRoot)))
-        throw new Error(`installation escaped config directory: ${skillsRoot}`);
-    for (const entry of entries) {
-        if (entry.unchanged) {
-            log(`unchanged Codex skill: ${entry.name}`);
-            continue;
-        }
-        const staging = fs.mkdtempSync(path.join(skillsRoot, '.d2h-install-'));
-        const staged = path.join(staging, 'new');
-        const backup = path.join(staging, 'backup');
-        try {
-            if (entry.source) {
-                if (link)
-                    fs.symlinkSync(entry.source, staged, process.platform === 'win32' ? 'junction' : 'dir');
-                else
-                    fs.cpSync(entry.source, staged, { recursive: true });
-            }
-            else {
-                fs.mkdirSync(staged);
-                fs.writeFileSync(path.join(staged, 'SKILL.md'), entry.content);
-            }
-            if (stat(entry.target))
-                fs.renameSync(entry.target, backup);
-            try {
-                fs.renameSync(staged, entry.target);
-            }
-            catch (error) {
-                if (stat(backup))
-                    fs.renameSync(backup, entry.target);
-                throw error;
-            }
-        }
-        finally {
-            if (stat(backup) && !stat(entry.target))
-                log(`installation backup retained: ${backup}`);
-            else
-                fs.rmSync(staging, { recursive: true, force: true });
-        }
-        log(`installed Codex skill: ${entry.target}`);
-    }
-    const packageFile = path.join(sourceRoot, 'package.json');
-    const packageVersion = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, 'utf8')).version : 'source';
-    const temporary = `${receipt}.${process.pid}.tmp`;
-    try {
-        fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, agent: 'codex', packageVersion,
-            entries: entries.map(entry => ({ name: entry.name, digest: digest(entry.target) })) }, null, 2) + '\n');
-        fs.renameSync(temporary, receipt);
-    }
-    finally {
-        if (fs.existsSync(temporary))
-            fs.rmSync(temporary);
-    }
-    log(`Codex installation complete: ${entries.length} skill(s). Start a new conversation and invoke $d2h.`);
-    return { skills: entries.length, configRoot: root };
+export function installCodex(options) {
+    return installSkillHost('codex', options);
 }

package/dist/src/install-opencode.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
-import { updateMetricsPlugin } from './metrics-plugin.js';
+import { clearMetricsPluginCache, findMetricsPluginCacheDirs, metricsPluginCacheRoots, updateMetricsPlugin } from './metrics-plugin.js';
 export function stat(file) {
     try {
         return fs.lstatSync(file);
@@ -136,7 +136,7 @@ export function resolvedLocation(directory) {
     const parent = path.dirname(directory);
     return parent === directory ? directory : path.join(resolvedLocation(parent), path.basename(directory));
 }
-export function installOpenCode({ sourceDir, configDir, agent = 'opencode', link = false, force = false, dryRun = false, remote = false, log = console.log }) {
+export function installOpenCode({ sourceDir, configDir, agent = 'opencode', link = false, force = false, dryRun = false, remote = false, pluginCacheRoots, log = console.log }) {
     if (!['opencode', 'deveco'].includes(agent))
         throw new Error(`unsupported agent: ${agent}`);
     const application = agent === 'deveco' ? 'DevEco Code' : 'OpenCode';
@@ -257,6 +257,16 @@ export function installOpenCode({ sourceDir, configDir, agent = 'opencode', link
                 fs.rmSync(temporary);
         }
     }
+    const pluginCacheRoot = pluginCacheRoots ?? metricsPluginCacheRoots(agent);
+    if (dryRun) {
+        for (const dir of findMetricsPluginCacheDirs(pluginCacheRoot))
+            log(`would remove metrics plugin cache: ${dir}`);
+    }
+    else {
+        const cleared = clearMetricsPluginCache({ roots: pluginCacheRoot, log });
+        for (const failure of cleared.failures)
+            log(`warning: failed to clear metrics plugin cache: ${failure}`);
+    }
     log(`${application} installation ${dryRun ? 'preview' : 'complete'}: ${skills} skill(s), ${agents} agent(s).`);
     log(`Config directory: ${configRoot}`);
     if (!dryRun)