android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-design/SKILL.md

@@ -0,0 +1,330 @@
+---
+
+name: a2h-spec-design
+description: Generate concise SPEC_name_design.md for an input SPEC by using project_design.md, database_design.md, preferences_design.md, on-demand module_design.md, configurable engine (GitNexus, CodeGraph, or Homegraph) evidence, and directed source lookup. Only for the a2h scenario (Android-to-HarmonyOS migration); do not invoke for hmos-only or non-migration projects.
+argument-hint: <target_directory> <input_file> "<ui_operation_sequence>" [--task spec|ui] [--engine gitnexus|codegraph|homegraph] [--engine-mode auto|off|required] [--database-design <database_design_file>] [--preferences-design <preferences_design_file>] [--mvvm true|false] [--output-dir <output_directory>] [--output-file <output_file>]
+allowed-tools:
+
+* Read
+* Glob
+* Grep
+* Bash
+* Write
+
+---
+
+# Spec Design Skill
+
+## Purpose
+
+Generate `<SPEC_name>_design.md` for an input SPEC.
+
+Inputs are the SPEC file, the raw UI operation sequence, `<target_directory>/project_design.md`, optional `database_design.md`, optional `preferences_design.md`, selected `module_design.md`, configurable engine evidence (GitNexus, CodeGraph, **or** Homegraph — selected by `--engine`), and directed local source lookup when needed.
+
+All generated content in `<SPEC_name>_design.md` must be in Chinese.
+
+## Invocation
+
+```text
+/spec-design <target_directory> <input_file> "<ui_operation_sequence>" [--task spec|ui] [--engine gitnexus|codegraph|homegraph] [--engine-mode auto|off|required] [--database-design <database_design_file>] [--preferences-design <preferences_design_file>] [--mvvm true|false] [--output-dir <output_directory>] [--output-file <output_file>]
+```
+
+Arguments:
+
+* `target_directory`: project root directory.
+* `input_file`: task input file. For `--task spec`, this is the SPEC file.
+* `ui_operation_sequence`: original UI operation sequence. Preserve it verbatim.
+* `--task`: `spec` or `ui`. Default is `spec`. `ui` is reserved and not implemented.
+* `--engine`: code-analysis engine, `gitnexus`, `codegraph`, or `homegraph`. Default is `homegraph`. Selects which backend the skill invokes in Step 6.
+* `--engine-mode`: how strictly engine evidence is required, `auto`, `off`, or `required`. Default is `auto`. Behavior is identical for both engines (see Step 6).
+* `--database-design`: optional database design file. Default is `<target_directory>/database_design.md`.
+* `--preferences-design`: optional Preferences design file. Default is `<target_directory>/preferences_design.md`.
+* `--mvvm`: `true` or `false`. Default is `false`. When `true`, related UI files and related logic files must be orthogonal.
+* `--output-dir`: optional output directory. Default is the input file directory.
+* `--output-file`: optional exact output file path. When supplied, the design is written to this path instead of `<output-dir>/<SPEC_name>_design.md`. Useful when an orchestrator wants a fixed filename regardless of the input file's stem (e.g. `SPEC_DESIGN_<N>.md`).
+
+## Output
+
+Write the design file:
+
+```text
+<output_directory>/<SPEC_name>_design.md
+```
+
+`SPEC_name` is the `input_file` stem. If `--output-dir` is not provided, `output_directory` is the input file directory.
+
+If `<SPEC_name>_design.md` already exists, stop immediately and report that it already exists.
+
+After generation, run output validation. If deterministic output issues are detected, the validation script writes:
+
+```text
+<output_directory>/<SPEC_name>_design_issue.md
+```
+
+Do not silently modify the generated design file.
+
+## Workflow
+
+### Step 1: Validate Inputs
+
+Run:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/inspect_spec_design_inputs.mjs" "<target_directory>" "<input_file>" --task <task_type> --engine <engine> --engine-mode <engine_mode> --mvvm <mvvm_mode> [--database-design <database_design_file>] [--preferences-design <preferences_design_file>] [--output-dir <output_directory>] [--output-file <output_file>]
+```
+
+Stop if validation fails.
+
+If `database_design.md` or `preferences_design.md` is missing, report the script warning and continue.
+
+The validation script performs deterministic checks. Its output must include:
+
+* `path_display_root`
+* `has_database_design`
+* `has_preferences_design`
+* `is_mvvm`
+* `design_path`
+* `issue_path`
+
+### Step 2: Read Project Semantics
+
+Read the `project_design` path from the validation script's JSON output.
+
+Use only:
+
+* `## 项目结构`
+* `## 模块语义`
+
+The `模块语义` table is the source of candidate module paths, module semantic descriptions, and final module ownership.
+
+The final module-path table must use the same module granularity as `project_design.md`. For example, if `project_design.md` defines `model`, write `model`.
+
+### Step 3: Read Database/Preferences Evidence
+
+If `has_database_design=true`, read `database_design.md`.
+
+Use it as the first source for database files, table names, table dependencies, fields, field types, primary-key/foreign-key information, constraints, and table-entity relationships.
+
+If `has_preferences_design=true`, read `preferences_design.md`.
+
+Use it as the first source for Preferences files, keys, value types, and Preferences-entity relationships.
+
+If either file is missing or unrelated, continue with later evidence. If no related database table or Preferences key is found, write `不涉及`.
+
+### Step 4: Select Candidate Modules
+
+Select candidate modules from the `模块语义` table in `project_design.md`.
+
+Selection evidence includes:
+
+* SPEC content
+* original UI operation sequence
+* module paths and module semantic descriptions
+* database table evidence
+* Preferences key evidence
+* data entity evidence
+* UI and logic evidence
+
+Selected modules should cover related UI, data entity, database, Preferences, and logic evidence for the current SPEC.
+
+Selected modules are evidence modules. The final section `当前SPEC生成的代码所从属的模块路径` should include only module paths that actually need generated or modified code for the current SPEC.
+
+### Step 5: Load Module Semantics on Demand
+
+For each selected candidate module, read its `module_design.md` if it exists (try `<target_directory>/.hometrans/<candidate_module>/module_design.md` first, then `<target_directory>/<candidate_module>/module_design.md`).
+
+Use:
+
+* module semantic descriptions copied from `project_design.md`
+* file semantic descriptions copied from the `## 文件语义` table in `module_design.md`
+
+If `module_design.md` is missing, or no matching file row exists, use `None`.
+
+### Step 6: Collect Engine Evidence
+
+Use the code-analysis engine selected by `--engine` according to `--engine-mode`. All three engines share the same mode semantics:
+
+* `auto`: attempt the engine with timeout `120000ms`. If it times out, or starts but does not complete, retry once with timeout `300000ms`. Use the successful output as auxiliary evidence. If both attempts fail, continue with local analysis.
+* `off`: skip engine evidence entirely.
+* `required`: stop generation if the selected engine cannot provide usable evidence.
+
+**Homegraph (`--engine homegraph`, default):** the CLI binary is `homegraph`; ArkTS analysis additionally requires `arkanalyzer`. Resolve the CLI first (`homegraph` locally, else `npx -y -p homegraph@latest -p arkanalyzer@latest homegraph`), then run:
+
+```bash
+homegraph init -i "<target_directory>"
+```
+
+Once indexed, use `mcp__homegraph__search` / `explore` / `node` / `impact` / `callers` / `callees` / `files` for evidence, each scoped with `projectPath: "<target_directory>"`.
+
+**GitNexus (`--engine gitnexus`):** resolve the CLI first (`gitnexus` locally, else `npx -y gitnexus@latest`), inspect syntax with `gitnexus --help` if unclear, then run:
+
+```bash
+gitnexus analyze "<target_directory>"
+```
+
+**CodeGraph (`--engine codegraph`):** resolve the CLI first (`codegraph` locally, else `npx -y @agentllm/codegraph-arkts`), inspect syntax with `<resolved_runner> --help` if unclear, then run the resolved runner against `<target_directory>`.
+
+Engine evidence may only locate related UI, data entity, database, Preferences, logic files, table structures, Preferences keys, and their relationships. The engine **must not** rewrite semantic descriptions copied from `project_design.md` or `module_design.md`.
+
+### Step 7: Directed Source Lookup
+
+Use local source lookup only when `database_design.md`, `preferences_design.md`, engine evidence (Step 6), and selected `module_design.md` are insufficient.
+
+Rules:
+
+1. Search only inside candidate module directories derived from `project_design.md`.
+2. Search only with SPEC/UI-related keywords.
+3. Search keywords may include table names, database file names, entity names, Preferences file names, Preferences key names, UI component names, UI operation keywords, ViewModel names, Service names, Repository names, and Manager names.
+4. Prefer `Grep` before `Read`.
+5. Read only specific files needed to confirm paths, table structures, Preferences keys, data entities, file roles, or relationships.
+6. Do not scan or read the whole project indiscriminately.
+7. Do not use generated documentation files as implementation evidence.
+
+### Step 8: Generate `<SPEC_name>_design.md`
+
+Use this evidence order:
+
+* database-related content: `database_design.md` → engine evidence (Step 6) → selected `module_design.md` → directed source lookup
+* Preferences-related content: `preferences_design.md` → engine evidence (Step 6) → selected `module_design.md` → directed source lookup
+* UI, data entity, and logic files: `project_design.md` → selected `module_design.md` → engine evidence (Step 6) → directed source lookup
+
+All paths must use `path_display_root` returned by the validation script:
+
+```text
+<path_display_root>/<relative/path>
+```
+
+Do not write the full absolute `target_directory` or any literal placeholder.
+
+When `is_mvvm=true`, related UI files and related logic files must use different file paths.
+When `is_mvvm=false`, the same file may appear in both sections if it carries both UI and logic roles.
+
+Write the fixed format below and do not add extra sections:
+
+```md
+# XX Spec编码设计
+
+## 相关 UI
+
+### UI 操作序列
+
+{original_ui_operation_sequence}
+
+### 相关 UI 及文件路径
+
+| 相关 UI | 相关UI语义表述 | 文件路径 |
+|---|---|---|
+| xxx | module_design.md中的文件功能原文 | <path_display_root>/<relative/path> |
+
+## 相关数据
+
+### 数据库表
+
+**表名：xxx** (xxx)
+
+关联数据实体：xxx
+表依赖关系：xxx
+
+| 字段 | 类型 | 主键/外键 | 约束 |
+|------|------|------|------|
+| xxx | xxx | PK、FK(xxx)、PK/FK(xxx) 或 None | xxx |
+
+### Preferences 相关键
+
+| 文件 | key | 类型 |
+|---|---|---|
+| xxx | xxx | xxx |
+
+### 相关数据实体及文件路径
+
+| 数据实体 | 数据实体语义表述 | 文件路径 |
+|---|---|---|
+| xxx | module_design.md中的文件功能原文 | <path_display_root>/<relative/path> |
+
+## 相关逻辑
+
+### 相关逻辑模块及文件路径
+
+| 逻辑模块名字 | 模块语义描述 | 逻辑文件名字 | 文件语义描述 | 文件路径 |
+|---|---|---|---|---|
+| xxx | project_design.md中的模块功能原文 | xxx | module_design.md中的文件功能原文 | <path_display_root>/<relative/path> |
+
+## 当前SPEC生成的代码所从属的模块路径
+
+| 模块路径 |
+|---|
+| <path_display_root>/<relative/module/path> |
+```
+
+If no database table is found, write:
+
+```text
+不涉及
+```
+
+If no Preferences key is found, write:
+
+```text
+不涉及
+```
+
+If an entire file-path table has no content, write only:
+
+```text
+不涉及
+```
+
+If a table field has no value, write `None`.
+
+For database table metadata, omit `关联数据实体` when it is `None`, and omit `表依赖关系` when it is `None`.
+
+### Step 9: Relocate Technical Reference Section
+
+After writing `<SPEC_name>_design.md`, run:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/move_spec_technical_reference.mjs" "<input_file>" "<design_path>"
+```
+
+If the input SPEC contains an exact level-2 section named `## 技术参考`, the script moves the complete section from the input SPEC to `<SPEC_name>_design.md` immediately before `## 相关 UI`.
+
+If the section does not exist, leave both files unchanged.
+
+### Step 10: Validate Generated Output
+
+After Step 9, run:
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/validate_spec_design_output.mjs" "<target_directory>" "<design_path>"
+```
+
+If the script reports issues, keep the generated design file unchanged and report the issue file path.
+
+## Output Rules
+
+1. Names must be direct identifiers only: module name, class name, component name, file name, table name, entity name, database file name, or Preferences key.
+2. Do not append Chinese explanations inside name fields.
+3. `相关 UI` must be a direct UI identifier, such as a page/component/class/function/file name. Do not write descriptive UI phrases or names with parentheses.
+4. `模块语义描述` must be copied from `project_design.md`.
+5. `文件语义描述` must be copied from `module_design.md`.
+6. Preserve the original UI operation sequence verbatim.
+7. Each row in the final module-path table must be a module path selected from the `模块语义` table in `project_design.md`.
+8. The final module-path table may contain one or more rows, depending on which modules actually require generated or modified code for the current SPEC. Related UI, data, database, Preferences, and logic evidence should not be included unless their owning modules require generated or modified code.
+9. Ownership is resolved using the module granularity from `project_design.md`.
+10. For each database table, generate one table block.
+11. `表名` is the database table name. The parentheses contain the database file name or `None`.
+12. `关联数据实体` contains the related entity name. Omit this line if no related entity is found.
+13. `表依赖关系` contains the table-level relationship. Omit this line if no table relationship is found.
+14. Database field tables use `字段`, `类型`, `主键/外键`, and `约束`.
+15. `主键/外键` may contain `PK`, `FK(target_table.target_field)`, `PK/FK(target_table.target_field)`, or `None`.
+16. `FOREIGN KEY` only represents a physical SQLite foreign-key constraint when it is explicitly declared in source or `database_design.md`.
+17. If a relationship is only inferred from naming or usage and no physical foreign-key constraint is declared, write it in `表依赖关系`; do not write `FOREIGN KEY` as a field constraint.
+18. `约束` may contain `NOT NULL`, `UNIQUE`, `INDEX`, `DEFAULT`, `CHECK`, `FOREIGN KEY`, or `None`.
+19. `Preferences 相关键` uses only `文件`, `key`, and `类型`.
+20. Preferences key relationships are used as coverage evidence.
+21. Related data entities should appear in `### 相关数据实体及文件路径` when confirmed.
+22. In file-path tables, each row must point to an existing file. If the path is missing, nonexistent, a directory, or only inferred, omit the row.
+23. File-path table rows must not contain `None`. If the related file or description cannot be confirmed, omit the row.
+24. If no database table is involved, write `不涉及` under `### 数据库表`.
+25. If no Preferences key is involved, write `不涉及` under `### Preferences 相关键`.
+26. Run the output validation script after generation. The script only reports deterministic issues and writes an issue file; it must not modify the design file.

package/skills/a2h-spec-design/scripts/inspect_spec_design_inputs.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+import { homedir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+
+const VALUE_FLAGS = new Set([
+  'task',
+  'engine',
+  'engine-mode',
+  'database-design',
+  'preferences-design',
+  'mvvm',
+  'output-dir',
+  'output-file',
+]);
+
+function emit(payload, code = 0) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  process.exit(code);
+}
+
+function fail(message, extra = {}) {
+  emit({ ok: false, error: message, ...extra }, 1);
+}
+
+function expanduser(p) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function stem(p) {
+  return basename(p, extname(p));
+}
+
+function parseArgs(argv) {
+  const positionals = [];
+  const opts = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    let key = arg.slice(2);
+    let inlineValue;
+    const eq = arg.indexOf('=');
+    if (eq !== -1) {
+      key = arg.slice(2, eq);
+      inlineValue = arg.slice(eq + 1);
+    }
+
+    if (VALUE_FLAGS.has(key)) {
+      let value = inlineValue;
+      if (value === undefined) {
+        value = argv[++i];
+      }
+      opts[key] = value;
+    } else {
+      opts[key] = inlineValue !== undefined ? inlineValue : true;
+    }
+  }
+
+  return { positionals, opts };
+}
+
+function main() {
+  const { positionals, opts } = parseArgs(process.argv.slice(2));
+
+  const targetArg = positionals[0];
+  const inputFileArg = positionals[1];
+  if (targetArg === undefined || inputFileArg === undefined) {
+    fail('缺少 target_directory 或 input_file 参数。');
+  }
+
+  const task = opts.task ?? 'spec';
+  if (!['spec', 'ui'].includes(task)) {
+    fail(`argument --task: invalid choice: '${task}' (choose from 'spec', 'ui')`);
+  }
+  const engine = opts.engine ?? 'homegraph';
+  if (!['gitnexus', 'codegraph', 'homegraph'].includes(engine)) {
+    fail(`argument --engine: invalid choice: '${engine}' (choose from 'gitnexus', 'codegraph', 'homegraph')`);
+  }
+  const engineMode = opts['engine-mode'] ?? 'auto';
+  if (!['auto', 'off', 'required'].includes(engineMode)) {
+    fail(`argument --engine-mode: invalid choice: '${engineMode}' (choose from 'auto', 'off', 'required')`);
+  }
+  const mvvm = opts.mvvm ?? 'false';
+  if (!['true', 'false'].includes(mvvm)) {
+    fail(`argument --mvvm: invalid choice: '${mvvm}' (choose from 'true', 'false')`);
+  }
+
+  const root = resolve(expanduser(targetArg));
+  const inputFile = resolve(expanduser(inputFileArg));
+  const hometransDir = join(root, '.hometrans');
+
+  if (!isDir(root)) {
+    fail('target_directory 不存在或不是目录。', { target_directory: root });
+  }
+  if (!isFile(inputFile)) {
+    fail('input_file 不存在。', { input_file: inputFile });
+  }
+
+  let projectDesign = join(hometransDir, 'project_design.md');
+  if (!isFile(projectDesign)) {
+    projectDesign = join(root, 'project_design.md');
+  }
+  if (!isFile(projectDesign)) {
+    fail('未找到 project_design.md（已尝试 .hometrans/ 和项目根目录）', {
+      project_design: projectDesign,
+    });
+  }
+
+  if (task === 'ui') {
+    fail('task=ui 已预留，但当前未实现输出格式。', { task });
+  }
+
+  const outputDir = opts['output-dir']
+    ? resolve(expanduser(opts['output-dir']))
+    : dirname(inputFile);
+  if (!isDir(outputDir)) {
+    fail('output_dir 不存在或不是目录。', { output_dir: outputDir });
+  }
+
+  const designPath = opts['output-file']
+    ? resolve(expanduser(opts['output-file']))
+    : join(outputDir, `${stem(inputFile)}_design.md`);
+
+  if (opts['output-file'] && !isDir(dirname(designPath))) {
+    fail('output_file 的父目录不存在或不是目录。', { output_file: designPath });
+  }
+  if (existsSync(designPath)) {
+    fail(`${basename(designPath)} 已存在，停止生成。`, { design_path: designPath });
+  }
+
+  const issuePath = join(dirname(designPath), `${stem(designPath)}_issue.md`);
+
+  let databaseDesign = opts['database-design']
+    ? resolve(expanduser(opts['database-design']))
+    : resolve(join(hometransDir, 'database_design.md'));
+  if (!isFile(databaseDesign)) {
+    databaseDesign = resolve(join(root, 'database_design.md'));
+  }
+
+  let preferencesDesign = opts['preferences-design']
+    ? resolve(expanduser(opts['preferences-design']))
+    : resolve(join(hometransDir, 'preferences_design.md'));
+  if (!isFile(preferencesDesign)) {
+    preferencesDesign = resolve(join(root, 'preferences_design.md'));
+  }
+
+  const hasDatabaseDesign = isFile(databaseDesign);
+  const hasPreferencesDesign = isFile(preferencesDesign);
+
+  const warnings = [];
+  if (!hasDatabaseDesign) {
+    warnings.push(`database_design.md 不存在（已尝试 .hometrans/ 和根目录）：${databaseDesign}`);
+  }
+  if (!hasPreferencesDesign) {
+    warnings.push(`preferences_design.md 不存在（已尝试 .hometrans/ 和根目录）：${preferencesDesign}`);
+  }
+
+  const docLayout = isFile(join(hometransDir, 'project_design.md')) ? 'hometrans' : 'source';
+
+  emit({
+    ok: true,
+    task,
+    engine,
+    engine_mode: engineMode,
+    target_directory: root,
+    project_root_name: basename(root),
+    path_display_root: `/${basename(root)}`,
+    doc_layout: docLayout,
+    input_file: inputFile,
+    project_design: projectDesign,
+    database_design: databaseDesign,
+    has_database_design: hasDatabaseDesign,
+    preferences_design: preferencesDesign,
+    has_preferences_design: hasPreferencesDesign,
+    output_directory: outputDir,
+    design_path: designPath,
+    issue_path: issuePath,
+    warnings,
+    mvvm,
+    is_mvvm: mvvm === 'true',
+  });
+}
+
+main();