@harmonyos-arkts/d2h 0.1.27 → 0.1.29

package/dist/src/select-agent.js

@@ -0,0 +1,207 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { emitKeypressEvents, moveCursor, cursorTo, clearScreenDown } from 'node:readline';
+import { skillHosts } from './install-skills.js';
+import { locateVSCodeExtension } from './install-vscode.js';
+function executable(name, env, platform) {
+    const extensions = platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const directory of (env.PATH || '').split(platform === 'win32' ? ';' : ':').filter(Boolean)) {
+        for (const extension of extensions) {
+            const file = path.join(directory, name + extension);
+            try {
+                if (!fs.statSync(file).isFile())
+                    continue;
+                fs.accessSync(file, platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+                return file;
+            }
+            catch { /* Missing or inaccessible commands are not detection evidence. */ }
+        }
+    }
+    return undefined;
+}
+export function detectAgents({ home = os.homedir(), env = process.env, platform = process.platform, extensionDir } = {}) {
+    const configHome = env.XDG_CONFIG_HOME || path.join(home, '.config');
+    const hosts = [
+        { agent: 'opencode', label: 'OpenCode', root: env.OPENCODE_CONFIG_DIR || path.join(configHome, 'opencode'), commands: ['opencode'] },
+        { agent: 'vscode', label: 'VS Code (HarmonyOS Dev Assistant)', root: path.join(home, '.vscode'), commands: ['code'] },
+        { agent: 'deveco', label: 'DevEco Code', root: env.DEVECO_CONFIG_DIR || path.join(configHome, 'deveco'), commands: ['deveco'] },
+        ...Object.entries(skillHosts).map(([agent, host]) => ({
+            agent, label: host.label,
+            root: ('environment' in host && env[host.environment]) || path.join(home, host.directory),
+            commands: agent === 'qoder' ? ['qodercli', 'qoder'] : agent === 'trae-cn' ? ['trae-cn'] : [agent]
+        }))
+    ];
+    return hosts.map(host => {
+        const detected = [];
+        for (const command of host.commands) {
+            const file = executable(command, env, platform);
+            if (file) {
+                detected.push(`命令 ${file}`);
+                break;
+            }
+        }
+        try {
+            if (fs.statSync(host.root).isDirectory())
+                detected.push(`配置目录 ${host.root}`);
+        }
+        catch { /* Not present. */ }
+        if (host.agent === 'vscode') {
+            try {
+                const extension = locateVSCodeExtension(extensionDir, home);
+                const metadata = JSON.parse(fs.readFileSync(path.join(extension, 'package.json'), 'utf8'));
+                if (String(metadata.name).toLowerCase() === 'harmonyosdevassistantforvscode' &&
+                    String(metadata.publisher).toLowerCase() === 'huaweideveloperserviceplatform') {
+                    detected.push(`鸿蒙插件 ${extension}`);
+                }
+            }
+            catch { /* VS Code without the required extension remains selectable. */ }
+        }
+        return { agent: host.agent, label: host.label, detected };
+    });
+}
+export function formatAgentChoice(choice) {
+    const detected = choice.agent === 'vscode'
+        ? choice.detected.some(item => item.startsWith('鸿蒙插件 '))
+        : choice.detected.length > 0;
+    const status = detected ? '可配置' : '未检测到';
+    const label = ['opencode', 'vscode'].includes(choice.agent) ? choice.label : `${choice.label} (${choice.agent})`;
+    return `${label} — ${status}`;
+}
+export async function chooseAgent(choices, ask, write) {
+    write('选择安装目标 / Select agent（检测结果仅供参考）：\n');
+    choices.forEach((choice, index) => write(`  ${index + 1}. ${formatAgentChoice(choice)}\n`));
+    for (;;) {
+        const answer = (await ask('输入序号或 agent 名称，q 取消：')).trim().toLowerCase();
+        if (['q', 'quit', 'exit'].includes(answer))
+            throw new Error('Installation cancelled before making changes');
+        const choice = /^\d+$/.test(answer) ? choices[Number(answer) - 1] : choices.find(item => item.agent === answer);
+        if (choice)
+            return choice.agent;
+        write('请选择列表中的序号或 agent 名称。\n');
+    }
+}
+export function chooseAgentWithKeys(choices, input = process.stdin, output = process.stderr) {
+    return new Promise((resolve, reject) => {
+        let selected = 0;
+        let renderedLines = 0;
+        let answer = '';
+        const colorDepth = process.env.NO_COLOR === undefined ? (output.getColorDepth?.() || 1) : 1;
+        const wasRaw = Boolean(input.isRaw);
+        const wasFlowing = input.readableFlowing === true;
+        const rows = Math.max(1, Math.min(choices.length, (output.rows || 24) - 4));
+        function render() {
+            if (renderedLines) {
+                moveCursor(output, 0, -renderedLines);
+                cursorTo(output, 0);
+                clearScreenDown(output);
+            }
+            const start = Math.max(0, Math.min(selected - rows + 1, choices.length - rows));
+            const lines = ['选择安装目标 / Select agent（检测结果仅供参考）'];
+            for (let i = start; i < start + rows; i++) {
+                lines.push(`${i === selected ? '>' : ' '} ${i + 1}. ${formatAgentChoice(choices[i])}`);
+            }
+            lines.push(`↑↓ 选择，回车确认；也可输入序号或名称，q 取消：${answer}`);
+            // Keep every row within the terminal width so cursor movement stays aligned.
+            const width = Math.max(1, (output.columns || 80) - 1);
+            const clipped = lines.map(line => {
+                let cells = 0;
+                let result = '';
+                for (const char of line) {
+                    const size = char.codePointAt(0) >= 0x1100 ? 2 : 1;
+                    if (cells + size > width)
+                        break;
+                    result += char;
+                    cells += size;
+                }
+                return result;
+            });
+            const highlighted = clipped.map((line, index) => {
+                if (index !== selected - start + 1 || colorDepth < 4)
+                    return line;
+                // HarmonyOS-style blue (#0A59F7), with an ANSI blue fallback.
+                const color = colorDepth >= 24 ? '\x1b[1;38;2;255;255;255;48;2;10;89;247m' : '\x1b[1;97;44m';
+                return color + line + '\x1b[0m';
+            });
+            output.write(highlighted.join('\n') + '\n');
+            renderedLines = clipped.length;
+        }
+        function finish(agent) {
+            input.removeListener('keypress', onKey);
+            input.removeListener('end', onEnd);
+            input.removeListener('error', onError);
+            input.setRawMode(wasRaw);
+            if (!wasFlowing)
+                input.pause();
+            if (agent) {
+                output.write(`已选择：${choices.find(item => item.agent === agent).label}\n`);
+                resolve(agent);
+            }
+            else
+                reject(new Error('Installation cancelled before making changes'));
+        }
+        function onEnd() { finish(); }
+        function onError(error) { finish(); }
+        function onKey(text, key = {}) {
+            if ((key.ctrl && ['c', 'd'].includes(key.name || '')) || key.name === 'escape') {
+                finish();
+                return;
+            }
+            if (key.name === 'up' || key.name === 'down') {
+                selected = (selected + (key.name === 'up' ? -1 : 1) + choices.length) % choices.length;
+                answer = '';
+            }
+            else if (key.name === 'return' || key.name === 'enter') {
+                const value = answer.trim().toLowerCase();
+                if (['q', 'quit', 'exit'].includes(value)) {
+                    finish();
+                    return;
+                }
+                const choice = !value ? choices[selected] : /^\d+$/.test(value) ? choices[Number(value) - 1] : choices.find(item => item.agent === value);
+                if (choice) {
+                    finish(choice.agent);
+                    return;
+                }
+                answer = '';
+            }
+            else if (key.name === 'backspace')
+                answer = answer.slice(0, -1);
+            else if (text && !key.ctrl && !key.meta && /^[a-zA-Z0-9-]+$/.test(text))
+                answer = (answer + text).slice(0, 30);
+            else
+                return;
+            render();
+        }
+        emitKeypressEvents(input);
+        input.setRawMode(true);
+        input.on('keypress', onKey);
+        input.once('end', onEnd);
+        input.once('error', onError);
+        input.resume();
+        render();
+    });
+}
+export async function selectAgent(extensionDir) {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        throw new Error('Agent selection requires an interactive terminal; pass --agent <name> (for example --agent opencode)');
+    }
+    const choices = detectAgents({ extensionDir });
+    if (process.env.TERM !== 'dumb')
+        return chooseAgentWithKeys(choices);
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const controller = new AbortController();
+    rl.once('SIGINT', () => controller.abort());
+    rl.once('close', () => controller.abort());
+    try {
+        return await chooseAgent(choices, prompt => rl.question(prompt, { signal: controller.signal }), text => process.stderr.write(text));
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error('Installation cancelled before making changes');
+        throw error;
+    }
+    finally {
+        rl.close();
+    }
+}

package/docs/environment-check.md

@@ -11,11 +11,11 @@ npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --output-dir ./environment-repo
 本地构建后：`node dist/bin/install-opencode.js --check-env`。检查参数在 --check-env 后传入；使用 --check-env --help 查看。检查模式不执行 Agent/Skill 安装；不能与 --force、--agent、--config-dir 等安装参数混用，误用时返回参数错误。npx 自身可能下载并缓存 npm 包。
 
 ```powershell
-node scripts/check-environment.mjs --output-dir D:/reports/hmos-environment
+node tooling/scripts/check-environment.mjs --output-dir D:/reports/hmos-environment
 ```
 
 ```sh
-node scripts/check-environment.mjs --output-dir ~/reports/hmos-environment
+node tooling/scripts/check-environment.mjs --output-dir ~/reports/hmos-environment
 ```
 
 ## 当前检查项
@@ -99,5 +99,5 @@ npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --requirements ./environment-re
 测试：
 
 ```sh
-node --test --test-concurrency=1 scripts/tests/environment.test.mjs
+node --test --test-concurrency=1 tooling/scripts/tests/environment.test.mjs
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@harmonyos-arkts/d2h",
-  "version": "0.1.27",
-  "description": "Install Android-to-HarmonyOS migration agents and skills into OpenCode or DevEco Code",
+  "version": "0.1.29",
+  "description": "Install Android-to-HarmonyOS migration agents and skills into AI coding tools",
   "type": "module",
   "bin": {
     "d2h": "dist/bin/install-opencode.js"
@@ -15,10 +15,10 @@
     "schemas/",
     "workflow/",
     "contracts/",
-    "opencode/",
+    "tooling/opencode/",
     ".claude-plugin/",
-    "install-opencode.sh",
-    "scripts/check-environment.mjs",
+    "tooling/install-opencode.sh",
+    "tooling/scripts/check-environment.mjs",
     "docs/environment-check.md",
     "docs/incremental-spec-evaluation-design.md",
     "docs/spec-plan-guide.md",
@@ -32,7 +32,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit && npm run build && node dist/scripts/check-skill-refs.js && node dist/scripts/check-toolchain.js",
-    "test": "npm run build && node --test dist/test/*.test.js scripts/tests/*.test.mjs",
+    "test": "npm run build && node --test dist/test/*.test.js tooling/scripts/tests/*.test.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "npm run check && npm test"
   },

package/skills/arkts-mvvm-architecture/SKILL.md

@@ -20,6 +20,8 @@ tags: [arkts, mvvm, state-management-v2, navigation, architecture, harmonyos]
 
 ## 1. 目录结构规范
 
+优先遵循工程已有的目录、模块归属和共享边界，在其内部落实 MVVM 分层。以下目录树和模块拆分建议供新建工程或尚无明确约定的部分参考，不要求现有工程按示例重组。
+
 按「功能 + 分层」组织。`core/` 放跨模块共享资产，业务按 feature 内聚。
 
 ```

package/skills/d2h-architecture-plan/SKILL.md

@@ -1,45 +1,38 @@
 ---
 name: d2h-architecture-plan
 description: >-
-  用于 Android 转 HarmonyOS 的架构评估、目录规划和方案选型。读取 Android 源码，以 JSON 交付项目简介、原工程分析和三套嵌套目录，供看板展示推荐与用户选择；
-  看板确认或 question 工具回答统一落盘，目录实施读取 JSON 后复用或创建基础工程、补齐所选目录。
+  用于 Android 转 HarmonyOS 的目录级架构评估、三方案比较与选型。确认后交付规划 Markdown 和最终目录 JSON；
+  按授权创建或复用鸿蒙基础工程、补齐关键目录。
 ---
 
 # Android 源码 → 鸿蒙架构与目录规划
 
-基于 Android 工程结构与必要源码，为迁移确定职责归属、依赖方向和可落地的鸿蒙目录，兼顾原开发者维护便利性。默认做目录级架构分析，不开展完整业务理解、逐页行为分析或实现级迁移设计。
+基于 Android 工程结构与必要源码，确定职责归属、依赖方向和可落地的鸿蒙目录，兼顾原开发者维护便利性。默认做目录级架构分析，不开展完整业务理解、逐页行为分析或实现级迁移设计。
 
 ## 输入与边界
 
 - 必需输入只有 Android 源码根目录，可独立执行。按用户范围识别实际应用、运行时模块、技术栈和目标设备；源码缺失或目标能力未知时标明影响。
-- 默认读取 Android 工程源码及其相关资源、构建声明；不自动读取鸿蒙业务源码，也不为寻找鸿蒙参考实现扩大扫描范围。上下文已指向鸿蒙目标时，按 [source-review.md](references/source-review.md) 做最小辨别，区分自动生成的模板壳、已有业务工程和性质未明的工程。
-- 已确认仍为自动生成模板壳的工程（包括 Preflight 创建的工程）作为后续落地基础，不作为业务架构依据，不触发“是否结合现有鸿蒙工程”的询问。职责与目录由 Android 事实及目标要求决定，不能被空壳的默认结构限制。
-- 确认鸿蒙工程已存在，且含业务实现或最小辨别后性质仍不明确，用户又尚未决定是否结合时，询问一次：“是否结合现有鸿蒙工程的业务实现进行架构规划？默认仅分析 Android 工程。”仅提供输出路径或配置中的目标路径不单独证明已有业务工程或用户选择结合。
-- 用户明确要求结合/复用鸿蒙业务实现时，按约定范围读取；明确选择不结合时，只分析 Android。同一工程、同一任务范围内沿用已有明确选择，不重复询问；用户改变选择时据此调整。尚未答复期间可继续 Android 侧分析，不扩读鸿蒙业务源码，也不把沉默记为用户拒绝。复用基础工程、核对配置或创建目录的授权不自动扩大为分析已有业务实现。
-- 已有功能清单、Facts、规划可作导航线索，用当前源码核验。
-- 默认交付 `architecture-plan.json` 作为看板决策事实源，同时保留 `architecture-plan.md` 作为现有主流程使用的阅读视图；推荐、选择和目录以 JSON 为准，两者同步。不生成持久化的全量文件清单、源码快照、import/调用图或扫描基线。已有大型扫描产物按问题查询，不整体读入或为更新规划重新生成。
-- 源工程只读；默认在同级 `<工程名>-migration/.migration/architecture-plan/` 交付。已有文件先阅读，保留用户批注，修订时同步受影响部分。
-- 分析分支和目录组织依据本次读取范围内的工程事实与迁移目标确定，参考示例按实际需要选用。基础配置核对可用于工程复用判断；未读取的鸿蒙业务实现不作已核验的能力复用依据。
+- 默认读取 Android 源码及相关资源、构建声明。上下文已指向鸿蒙目标时，按 [source-review.md](references/source-review.md) 辨别其性质：模板壳仅作落地基础，无需询问是否结合业务；已有业务或性质未明且用户尚未决定时，询问是否结合其业务实现，默认仅分析 Android。
+- 沿用同工程、同范围的明确选择；等待答复时可继续 Android 分析，不扩读鸿蒙业务。配置核对与目录创建不自动扩大为业务分析；模板的默认目录不限制架构设计。
+- 已有功能清单、Facts、规划可作定位线索，用当前源码核验。不生成全量文件清单、源码快照、import/调用图或扫描基线；已有大型产物按问题查询。
+- 源工程只读；默认在同级 `<工程名>-migration/.migration/architecture-plan/` 交付。已有文件先阅读，保留用户批注，修订受影响部分。
 
-## 架构规划
+## 规划 → 确认 → 展示
 
-1. 按 [source-review.md](references/source-review.md) 从构建声明、入口/导航和主要源码目录建立结构地图，识别基础依赖、页面业务、共享业务及装配。仅当证据不足会改变拆合、归属或依赖方向时，定点读取相关源码；边界可解释后停止扩读。
-2. 按 [layout-reference.md](references/layout-reference.md) 设计原结构对照 `android-mirror`、鸿蒙优选 `harmony-practice`、融合 `hybrid`，共用范围地图；已有选定方案时围绕它修订并同步受影响的对照。融合结构以基础依赖保留原模块/包族、业务按 feature 承载页面为原则，需要详细展开时读 [hybrid-design.md](references/hybrid-design.md)，不展开逐页实施计划。
-3. 读取 [plan-contract.md](references/plan-contract.md) 和 [json-contract.md](references/json-contract.md)，JSON 聚焦三部分：项目简介、Android 工程分析与风险、三套可独立展开的目录树；推荐/选择及最小回传元数据沿用契约。每套仅 `id/name/summary/directoryTree`，不生成机器映射表、依赖图、共享所有者或逐方案收益成本数组。每个目录都有相对路径与简介，三套均展开到可选型、可创建的关键目录粒度，不用文字差异、通配符或引用另一套目录代替树。必要的归属/依赖/共享边界在 Markdown 简记，复核与目录一致。
-4. 运行 `python <本Skill目录>/scripts/architecture_plan.py validate <产物目录>/architecture-plan.json`，再同步 Markdown 阅读视图。向调用方交接 JSON/Markdown 路径、`planId` 和待决项；三套方案的选择单位是整套目录方案，展开/折叠及点击单个节点不改变选择。
+1. 按 [source-review.md](references/source-review.md) 从构建声明、入口/导航和主要源码目录建立结构地图，识别基础依赖、页面业务、共享业务及装配。仅当证据不足会改变拆合、归属或依赖时扩读；边界可解释后停止。
+2. 按 [layout-reference.md](references/layout-reference.md) 设计原结构对照 `android-mirror`、鸿蒙优选 `harmony-practice`、融合 `hybrid`，共用范围地图。在对话中展示三套目录结构、职责、取舍及推荐理由，供用户判断，暂不生成交付文件。融合方案设计时读 [hybrid-design.md](references/hybrid-design.md)。已有有效选择时围绕它修订，不重新强制选型。
+3. 用可用的 question 工具或对话询问方案选择，三个选项对应上述方案并标识推荐，说明本次只选型还是确认后落地。只接受实际回答，预选项、取消或超时不算选择；先处理修改意见，仅询问仍缺失的用户决定。技术核验由 Agent 完成。已有当前有效选择和授权直接沿用，不重复询问；仅比较、尚未选型时在对话中交付分析，不生成最终 JSON/Markdown。
+4. 用户回答完成后，按 [plan-contract.md](references/plan-contract.md) 生成 `architecture-plan.md`，保存三套目录及实际选型/授权；按 [json-contract.md](references/json-contract.md) 生成最终 `architecture-plan.json`，只含 `projectName`、`directoryTree`、`decisions`。两份产物使用同一组已确认的路径与决定；JSON 先在临时文件中生成，校验通过后替换正式文件，再交给只读看板。任一产物保存失败或不一致时，先修复，不进入实施。
+5. 有创建/复用授权时，读取 [directory-creation.md](references/directory-creation.md)，重新读取最终 JSON 和 Markdown 确认记录后实施。完整迁移已有创建要求并确认方案时直接继续；仅选型不扩大为创建授权。
 
-`androidAnalysis` 固定为简短的 `summary`、按语言/界面/存储/网络四类归纳的 `techStack`、最多五项的 `risks`。风险只含名称与迁移影响；字段与类型见 JSON 契约。用用户能理解的文字说明关键事实，不堆叠工具和架构缩写，不输出源码目录清单或独立未决清单；详细核验线索放 Markdown。
+校验命令：`python <本Skill目录>/scripts/architecture_plan.py validate <产物目录>/architecture-plan.json`。辅助脚本要求 Python 3.10+，只校验展示数据，不处理选择、写入文件或创建工程。
 
-本 Skill 交付架构与转换交接设计；并行候选表示具备独立转换的架构条件，实际派发、开发和验收由调用方的执行流程决定。
+## 交付与修订
 
-## 选型与可选落地
+`architecture-plan.md` 保存项目理解、三套对照、推荐、用户回答与范围、最终归属/依赖及风险；`architecture-plan.json` 是确认后生成的最终展示和目录实施输入，两者应一致。
 
-选型、接收回答和恢复实施时读取 [selection-flow.md](references/selection-flow.md)。仅规划时交付即可；需要选型时，模型填写推荐，`selectedProposalId` 初始为 `null`。有效选择不重复询问，风险仅展示、不要求逐项答复，也不因风险非空而阻塞选型或目录创建。
+用户通过对话修改时同步两份产物。影响目录、依赖、目标或授权范围时，先将旧展示 JSON 移为不覆盖历史文件的备份，注明待修订并暂停受影响的实施，处理后重新校验发布；明确授权的调整不再重复确认。缺少当前有效确认的旧产物不作为最终结果继续展示。
 
-看板“确定”和 OpenCode `question` 回答是同一个确认步骤的两个入口；已有明确对话授权也可沿用。真实提交先写独立请求文件，脚本校验后保存 `architecture-selection.json` 并更新规划选择。不得先覆盖已确认文件，不把默认项、未提交/取消或模型推荐当用户答案。主规划只保留 `selectedProposalId`，不嵌套完整确认。
+恢复实施须重读 Markdown 的实际确认与最终 JSON，核对项目、目标和目录；文件存在或校验通过不代表用户授权。看板只展示最终 JSON，加载、刷新及修订期间的缓存处理由调用方适配。
 
-创建流程的提示需明确“确定后创建或复用基础工程并补齐目录”，一次确认记为 `select-and-create`，不追加“是否继续”；只选型则记为 `select`。question 回答也必须落盘，不只留在上下文。实施前运行 `read-selection` 重新核对规划、确认及原始意见，再按选定 ID 读取目录树；写入失败、不一致或有未处理的布局修改时不执行旧树。记录恢复使用统一流程的显式恢复入口。
-
-用户通过对话调整 JSON，并同步 Markdown。仅修改说明或风险时保留有效确认；影响目录、目标位置或授权范围时，先清理当前确认和旧选择，再更新展示并按实际授权确认。技术未知由 Agent 在实施时核查；必要输入/授权缺失时只询问缺失项。
-
-需要落地时读取 [directory-creation.md](references/directory-creation.md)。沿用 Preflight 目标与基础工程，普通文件工具补齐选定目录，确实无基础工程时才用本机 DevEco CLI 创建；不生成业务实现、不构建或运行应用。看板服务器、提交端点与会话通知由外部适配方提供，本 Skill 不提供监听器，也不把“文件已写入”当作 Agent 已被唤醒。
+本 Skill 交付架构与转换交接设计。页面族是候选，目录壳子不是已实现能力；实际派发、开发和验收由调用方流程决定。