@harmonyos-arkts/d2h 0.1.20 → 0.1.21

package/dist/src/workflow.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const contracts = {
+    plan: 'plan.md', scope: 'scope.md', execution: 'execution.md',
+    dispatch: 'dispatch.md', artifacts: 'artifacts.md',
+    orchestration: 'orchestration.md', delivery: 'delivery.md', overview: 'overview.md', generation: 'generation.md',
+};
+export function runWorkflow(packageRoot, args) {
+    if (args[0] === 'contract') {
+        const name = args[1];
+        if (args.length !== 2 || !Object.hasOwn(contracts, name)) {
+            throw new Error(`Usage: d2h workflow contract <${Object.keys(contracts).join('|')}>`);
+        }
+        process.stdout.write(fs.readFileSync(path.join(packageRoot, 'contracts', 'workflow', contracts[name]), 'utf8'));
+        return 0;
+    }
+    if (!args.length || ['--help', '-h'].includes(args[0])) {
+        console.log(`D2H artifact workflow tools (no Skill directory required).
+Usage: d2h workflow <validate|init|derive|context|event|reconcile|render|dashboard|generation> [options]
+       d2h workflow validate-scope <features.json> [--previous <file>] [--require-delivery]
+       d2h workflow metrics --project <source-project>
+       d2h workflow contract <${Object.keys(contracts).join('|')}>
+
+Use d2h workflow <action> --help for artifact arguments.
+init/event/reconcile synchronize execution.json, batch_report.json and batch_report.md.
+Python 3.10+ required; set D2H_PYTHON to select an interpreter.`);
+        return 0;
+    }
+    const action = args[0];
+    const scripts = { 'validate-scope': 'feature_plan.py', metrics: 'collect_code_metrics.py' };
+    const runtimeActions = ['validate', 'init', 'derive', 'context', 'event', 'reconcile', 'render', 'dashboard', 'generation'];
+    if (!Object.hasOwn(scripts, action) && !runtimeActions.includes(action)) {
+        throw new Error(`unknown workflow action: ${action}`);
+    }
+    const explicit = process.env.D2H_PYTHON || process.env.PYTHON;
+    const candidates = explicit ? [explicit] : ['python3', 'python'];
+    const python = candidates.find(command => {
+        const probe = spawnSync(command, ['-c', 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)'], {
+            encoding: 'utf8', timeout: 5000, windowsHide: true,
+        });
+        return !probe.error && probe.status === 0;
+    });
+    if (!python)
+        throw new Error('D2H workflow requires Python 3.10+; set D2H_PYTHON to its executable path');
+    const file = path.join(packageRoot, 'workflow', scripts[action] ?? 'spec_runtime.py');
+    const result = spawnSync(python, [file, ...(scripts[action] ? args.slice(1) : args)], {
+        stdio: 'inherit', windowsHide: true,
+        env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' },
+    });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+}

package/docs/architecture-plan-guide.zh-CN.md

@@ -0,0 +1,70 @@
+# d2h-architecture-plan 使用说明
+
+当前Skill由模型直接查找、阅读和交叉核对Android源码，交付三套鸿蒙架构与目录方案。执行规则以[SKILL.md](../skills/d2h-architecture-plan/SKILL.md)为准；不需要专用Python分析器、扫描JSON、渲染命令或前置功能报告。
+
+## 输入与启动
+
+提供Android源码根目录，以及已有的目标设备/范围约束即可。混合应用应能定位Android宿主和实际业务源码；缺失部分先分析可见内容并标明影响。已有功能清单、Facts、鸿蒙参考工程或历史方案均为可选线索，用当前源码核验。
+
+可直接向Agent提出：
+
+> 使用d2h-architecture-plan分析指定Android工程，输出安卓原结构对照、鸿蒙优选架构和融合结构三套完整目录方案，并推荐一套，考虑原开发者的维护便利性。只做规划。
+
+独立规划直接进入该Skill，不要求启动完整迁移的工具准备、Facts、设备采集或构建流程。原工程及参考工程只读；已有规划先读取并保留用户批注。
+
+## 分析与设计
+
+先从构建、Manifest、源码/资源根和入口建立范围地图，再沿影响边界的真实链路查调用、状态所有者、数据、平台接口及生命周期。单模块、多模块、不同设备和混合技术栈走同一主线，按源码证据展开专项，不套某个项目的业务清单。
+
+三套共用一次源理解，分别说明目标决定：
+
+| 方案 | 要点 |
+|---|---|
+| android-mirror | 保留运行时模块、关键包族及内部模块依赖，含原有扁平组织；平台必需适配单列，外部SDK保留能力对照，不照搬Android包坐标 |
+| harmony-practice | 根据业务内聚、状态、平台与共享边界重组，按需参考products/features/commons |
+| hybrid | 保留原作者熟悉且合理的边界，有证据地拆合或改名，说明收益和维护代价 |
+
+每套均有完整关键目录、职责/依赖、源码定位、关键链所有者和风险；树只列目录，不逐类造目录或预定实现文件。简单工程可以三套均为单HAP，不为制造差异拆空库，也不设独立顶层components类别。
+
+## 产物与评审
+
+默认写入Android同级 `<工程名>-migration/.migration/architecture-plan/`：
+
+| 文件 | 何时需要 | 用途 |
+|---|---|---|
+| architecture-plan.md | 默认 | 当前规划真源：共享项目理解、三套目录/职责/依赖、状态与平台承接、成本及推荐 |
+| source-map.md | 映射较长时 | 一张源到三套目标的对照表，覆盖已知业务、支撑、资源与入口 |
+| shell-receipt.json及CLI日志 | 实际创建时 | 记录选中方案、实际目标、授权、创建/复用目录和未完成项 |
+
+不默认输出多份重复JSON、扫描基线或树文件。有明确下游schema时，按其真实契约提供必要结构化数据，不能把历史ready字段当作当前复核或用户确认。
+
+模型把三套分别代入真实调用复核：每个已知区域有去向，导航与数据/事件契约能闭合，状态和资源所有权清楚，树/映射/依赖一致；未确认项按影响标明。目录完整不代表可构建或已完成迁移。
+
+只请求分析时，交付推荐与取舍即可完成；用户可随后批注或选型。源码可回答的问题由模型继续查证，不转成无必要的确认题。
+
+## 用户确认后的创建
+
+只有用户实际选定当前方案并要求创建/搬迁时，才读取[目录创建说明](../skills/d2h-architecture-plan/references/directory-creation.md)。已有“采用推荐并创建”的明确委托直接记录后执行，不重复索取确认。
+
+使用本机DevEco CLI，先通过当前帮助核对创建参数；已有工程检查注册模块、设备配置与本地依赖，保留模板和用户文件。普通文件工具只补齐选中方案目录，不一次创建三套，不生成业务实现或额外模块配置，不构建运行。
+
+执行后核对实际配置/目录并保存receipt，区分complete、partial、blocked以及未注册的目录壳子。CLI缺失或目标设备不支持时如实记录，空目录不能冒充基础工程。
+
+## 参考文件分工
+
+| 文件 | 负责内容 |
+|---|---|
+| [source-review.md](../skills/d2h-architecture-plan/references/source-review.md) | 范围地图、代表链、条件分支、反证与停止扩读条件 |
+| [layout-reference.md](../skills/d2h-architecture-plan/references/layout-reference.md) | 架构方法、三套差别、粒度与目录字典、官方依据 |
+| [plan-contract.md](../skills/d2h-architecture-plan/references/plan-contract.md) | Markdown交付内容、一致性复核及选型交接 |
+| [directory-creation.md](../skills/d2h-architecture-plan/references/directory-creation.md) | 确认后的CLI/已有工程检查、目录落地和实际记录 |
+
+按当前步骤读取相应参考，不要求一开始加载全部内容。控制成本依靠局部搜索、按风险深读、共享事实、紧凑对照与局部修订；发现矛盾或高影响未知仍须追踪，不以节约为由伪称全面，也不承诺固定token或耗时下降比例。
+
+## 旧流程与验证边界
+
+旧的inspect/query/audit/render及Python壳子命令已移除，不再提供脚本兼容层；历史JSON和评估文档只作参考。应按本说明调用当前Skill，而不是恢复旧解析器或改用历史测试驱动规划。
+
+工作流可选inputs.architecturePlan保存当前Markdown路径；inputs.shellReceipt只在实际创建后填写。调用方仍须核验最终选择、模块/目录、共享边界和风险。公共workflow不解析架构Markdown，不自动证明用户确认、SDK可用性或架构正确。
+
+自动测试检查Markdown资源可达、实际安装/更新和公共工作流的可选上下文交接；模型判断质量通过真实源码前向评审验证。安装或测试通过均不能替代架构语义复核。