android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: a2h-app-req-gen
+description: Analyze an Android application with Android Lint/UAST and source evidence, render page-scoped Chinese REQ documents, hand them to $a2h-spec-generate, and produce traceable HarmonyOS specs without requiring a UTG workspace.
+argument-hint: "[concurrency=8]"
+---
+
+# Android App REQ（Android-Lint → Spec）
+
+本 skill 从 Android 项目源码、Manifest、资源和 Android Lint/UAST 事实开始，生成页面级
+REQ，再按页面批次交给 `$a2h-spec-generate`。它不要求 UTG、`click_paths.json` 或 StageM
+输入，也不生成或修改 UTG。
+
+## 运行根目录和前置条件
+
+本 skill 的运行根目录固定为当前目录下的 `scripts/reqgen/`，其中包含 `package.json`、
+`src/`、`analyzer-jvm/`、`gradle/` 和运行所需脚本。不要要求调用方填写这个内部路径，
+也不要从仓库外寻找另一个 reqgen checkout。
+
+运行前确认：
+
+- Node.js 22 或更高；
+- JDK 17（构建并运行内置 JVM analyzer）；
+- 目标 Android 项目自身所需的 JDK、Gradle 和 Android SDK；
+- 目标 Android 项目根目录的 `local.properties` 或有效的
+  `ANDROID_HOME`/`ANDROID_SDK_ROOT`。
+
+`src/` 下是纯 ESM JavaScript（`.js`），零第三方运行时依赖，**不需要安装步骤，也没有构建
+步骤** —— 直接 `node src/<entry>.js` 即可。下文的 `pnpm <script>` 只是 `package.json` 里
+的脚本别名；没有 pnpm 时把它换成等价的 `node src/<entry>.js` 直接调用。
+
+优先把运行输出放在目标项目或调用方指定的输出目录；未显式指定时，CLI 会在运行根目录下
+创建 `.build/` 临时目录。`.build/`、依赖目录和其他运行产物只属于运行时，不能提交回本
+skill 的源码包。
+
+## 确定 Android 分析目标
+
+1. 指定 Android application module 和 build variant；只有 Gradle 模型中存在唯一候选时，
+   才能省略其中一个。
+2. 默认资源配置为 `zh-CN/portrait/notnight/API36/xhdpi/360dp`，可用
+   `--locale`、`--orientation`、`--ui-mode`、`--api-level`、`--density` 和
+   `--smallest-width-dp` 分别覆盖。
+3. Stage 1 每次从当前源码和工程配置重新分析，不读取或伪造 UTG 工件。
+
+## Stage 1：构建 Android-Lint 事实包
+
+从 `scripts/reqgen/` 执行：
+
+```bash
+pnpm stage1 -- --project <android-project> \
+  [--module <:application-module>] [--variant <build-variant>] \
+  [--output <new-run-directory>]
+```
+
+Windows PowerShell 中使用等价的 `cmd /c "pnpm stage1 -- ..."`，确保 `--` 参数原样传递。
+
+项目、Gradle、Manifest、UAST 或分析器基础设施失败时停止并报告原因。源码歧义记录为
+有证据位置的 `unresolved`，不得猜测补全。
+
+成功运行至少应包含：
+
+- `run-report.json`；
+- `source-facts.json`、`area-graph.json`、`req-model.json`、`gap-audit.json`、
+  `diagnostics.json`；
+- `generation/req.draft.md`、`generation/quality-report.json`、
+  `generation/name-traceability.json`。
+
+`semanticCompleteness: incomplete-known` 是可审阅的已知缺口，不等于基础设施失败；只有
+`run-report.json` 仍为 `succeeded`、validation 已完成且工件属于同一次运行时，Stage 2 才能
+继续使用该目录。
+
+## Stage 2：按页面渲染 REQ
+
+Stage 2 只消费同一次完整 Stage 1 运行。不要手改结构化工件、`task.md` 或 `expected.json`。
+完整的派发、self-check、finalize 和恢复协议见
+[references/subagent-render.md](./references/subagent-render.md)。
+
+默认先准备 Area 任务（不启动后端）：
+
+```bash
+pnpm stage2 -- --input <stage1-run-directory> \
+  --project-root <android-project> [--output <output-directory>]
+```
+
+主 Agent 读取生成的 `render-manifest.json`，把每个 `task.md` 交给一个隔离 subagent；宿主
+支持命名 profile 时可使用 `reqgen-renderer`，否则直接使用普通隔离 subagent。每个 subagent
+只能写自己的 `output.json`，并必须执行 task 中给出的 `reqgen-selfcheck.mjs check` 和
+`finalize`。
+
+所有已完成任务定稿后，离线合并：
+
+```bash
+pnpm stage2 -- --input <stage1-run-directory> --snapshot \
+  --output <stage2-output-directory> [--per-feature] [--with-unreachable-area]
+```
+
+没有 subagent 派发能力时，可使用 shell 后端：
+
+```bash
+pnpm stage2 -- --mode shell --input <stage1-run-directory> \
+  --project-root <android-project> --output <stage2-output-directory>
+```
+
+`--mode shell-legacy` 只在统一 task/self-check 协议不可用时使用。任何模型或后端失败都要
+保留可观察的失败信息，不用空正文或虚构结果掩盖。
+
+## Stage 3：生成 Spec 输入批次
+
+Stage 2 的旧 `req-<idx>.txt` 是兼容快照格式，不能把多个页面文件拼成一个全局 REQ。执行
+handoff，将每个 Area/page 变成独立批次：
+
+```bash
+pnpm spec-handoff -- \
+  --input <stage1-run-directory> \
+  --stage2-output <stage2-output-directory> \
+  --output <spec-input-directory>
+```
+
+也可以在 Stage 2 snapshot 时直接传入 `--spec-output`：
+
+```bash
+pnpm stage2 -- --input <stage1-run-directory> --snapshot \
+  --output <stage2-output-directory> \
+  --spec-output <spec-input-directory>
+```
+
+handoff 输出：
+
+```text
+<spec-input-directory>/
+├── manifest.json
+├── 001-<页面名>/REQ.txt
+└── 002-<页面名>/REQ.txt
+```
+
+每个 `REQ.txt` 的第一行是 UI 路径标题，需求段落之间使用一个空行。文件名本身没有特殊
+协议含义；`REQ.txt` 是页面批次的约定名称，`REQ-N.txt` 只是旧包装器的命名方式。
+handoff 会去除会被下游误判为需求边界的 Area 元数据和正文空行，并在 `manifest.json` 中
+记录 `requirementFile`、`owningPage`、`pagePath`、Area ID、需求数和警告。
+
+不要把不同 `owningPage` 的批次合并，也不要把 Lint 事实标记为 UTG/StageM 事实。来源对
+下游 Spec 解析是透明的，但产物中的来源状态必须保持真实。
+
+## Stage 4：逐批调用 `$a2h-spec-generate`
+
+端到端流程的终点是 Spec，而不是只生成 `REQ.txt`。主 Agent 读取
+`<spec-input-directory>/manifest.json`，对每个批次单独调用 `$a2h-spec-generate`：
+
+```text
+requirement_description_file = <spec-input-directory>/<requirementFile>
+android_project_dir          = <原 Android 项目根目录>
+spec_output_dir              = <spec-output-directory>/<batchId>
+```
+
+每次调用只传一个 `requirementFile`，并为不同批次使用独立的 Spec 输出目录。不要把多个批次
+拼接成一个扁平的 `req-<idx>.txt` 再只调用一次；`$a2h-spec-generate` 要求单次调用内的所有
+需求归属同一个 `owning-page`，混入多个页面会让它在 Step 0.6 直接停止。遍历 manifest 批次
+是本 handoff 唯一的输入合同。
+
+最终验收应能看到每个成功批次对应的 Spec 和 `.trace` 文件，并且 Spec 的页面归属、UI 路径
+和需求数量与对应 `REQ.txt`/manifest 批次一致。`incomplete-known`、unresolved 和 handoff
+警告必须继续保留在可审阅的运行产物中。
+
+## 输出和范围约束
+
+- 不修改 Android 业务源码、Manifest、资源、UTG 或已经定稿的 worker 输出；
+- 不创建或替换 UTG；
+- 不把外部 App、网页或系统设置当作本 App Area；
+- 不修改冻结的 `expected.json` 来使 self-check 通过；
+- 所有运行输出、缓存和依赖安装都应位于调用方输出目录或运行时目录，不提交到 skill 源码；
+- Android-Lint/JDK/Gradle/SDK 基础设施不可用时必须直接报告，不降级为伪造的业务
+  `unresolved`。
+
+交接字段和兼容解析的详细说明见
+[references/spec-handoff.md](./references/spec-handoff.md)。

package/skills/a2h-app-req-gen/references/spec-handoff.md

@@ -0,0 +1,99 @@
+# Android-Lint REQ 到 UI Spec 的交接格式
+
+`a2h-app-req-gen` 使用 Android Lint/UAST、Manifest 和资源文件生成 Stage 1 事实，
+再由 Stage 2 根据目标 Android 项目源码渲染 REQ 正文。这个流程不需要 UTG 或
+StageM 产物。下游 `$a2h-spec-generate` 不关心事实由哪一种分析器产生，但它对
+输入文本的分段方式和页面边界有明确要求，因此 Stage 2 结果需要经过 handoff。
+
+## 下游实际读取什么
+
+`$a2h-spec-generate` 接受 `.xlsx`、`.xlsm`、`.csv`、`.txt` 和 `.md`。对于文本
+文件，它把空行分隔的每个段落当作一条需求：段落第一行是 UI 路径标题，其余
+行是需求正文。文件名没有协议含义，所以 `REQ.txt`、`req-1.txt` 或其他 `.txt`
+名称都能被解析。
+
+一次 spec 调用中的所有需求必须属于同一个 `owning-page`。Stage 2 的每个 Area
+通常对应一个页面、弹窗或其他独立 UI surface，因此 handoff 默认生成一个 Area
+一个批次，不生成跨页面的总 `REQ.txt`。
+
+## 为什么不能直接使用旧 `req-{idx}.txt`
+
+旧文件可能以 `前置条件：` 开头。这个头部和第一条需求之间存在空行时，下游
+解析器会把它当成一条标题为“前置条件”的需求。Stage 2 的 Agent 正文也可以
+包含段落空行；这些空行会被同一个解析器误判为新的需求边界。多个旧文件还不能
+直接拼成一个总输入，否则会把不同 Area 的页面混在同一次 spec 调用中。
+
+handoff 执行以下确定性转换：
+
+- 从 finalized `rendering/<unit>/output.json` 读取结构化 Stage 2 结果；旧运行只
+  剩 `req-{idx}.txt` 或 `req.md` 时，使用兼容解析并在 manifest 中记录警告。
+- 每个 Area 生成一个 `<batch>/REQ.txt`，不把不同 Area 合并到同一文件。
+- 把 Area 的前置条件放进该 Area 每条需求的正文。
+- 删除 Area 级的 `访问路径：` 和 `区域说明：` 元数据。
+- 保留正文的普通换行和列表缩进，同时删除空白行，保证空行只承担需求分隔作用。
+- 写文件前按下游文本解析规则重新计算段落数；段落数与需求数不一致时停止。
+
+## 运行方式
+
+Stage 2 使用 shell 后端时，可以在同一次运行结束后直接导出：
+
+```bash
+pnpm stage2 -- --mode shell \
+  --input <stage1-run-directory> \
+  --project-root <android-project> \
+  --spec-output <spec-input-directory>
+```
+
+默认 subagent 模式完成所有渲染任务后，在 snapshot 命令中导出：
+
+```bash
+pnpm stage2 -- --input <stage1-run-directory> --snapshot \
+  --output <stage2-output-directory> \
+  --spec-output <spec-input-directory>
+```
+
+已有 Stage 2 结果也可以单独转换：
+
+```bash
+pnpm spec-handoff -- \
+  --input <stage1-run-directory> \
+  --stage2-output <stage2-output-directory> \
+  --output <spec-input-directory>
+```
+
+输出目录非空时，独立命令会停止。确认目录只保存上一次 handoff 生成的内容后，
+可以增加 `--replace` 重新生成。
+
+## 输出与下一步
+
+```text
+<spec-input-directory>/
+├── manifest.json
+├── 001-<页面名>/REQ.txt
+└── 002-<页面名>/REQ.txt
+```
+
+`manifest.json` 为每个批次记录 `requirementFile`、`owningPage`、`pagePath`、Area
+ID 和需求数量。运行 `$a2h-spec-generate` 时，需要遍历 manifest 中的批次，
+每次只传一个 `requirementFile`，并始终把原 Android 项目根目录作为
+`android_project_dir`。不同批次应使用彼此独立的 spec 输出子目录，避免多个
+页面的 trace 和页内顺序信息互相混入。
+
+调用参数对应关系如下（这是对下游 skill 的调用约定，不是另一个 REQ 文件格式）：
+
+```text
+requirement_description_file = <spec-input-directory>/<requirementFile>
+android_project_dir          = <android-project>
+spec_output_dir              = <spec-output-directory>/<batchId>
+```
+
+先处理 `manifest.json` 中的一个批次，再处理下一个批次；不要把多个批次的
+`REQ.txt` 拼接后只调用一次 `$a2h-spec-generate`。
+
+`owningPage` 和 `pagePath` 来自 Stage 1 的 Area 图，用于说明 handoff 如何划分
+批次。下游 skill 仍会根据 REQ 和源码重新确认页面归属，并通过自己的 trace
+生成最终 spec。handoff 不创建 UTG 字段，也不会把 Lint 结果标记成 StageM 结果。
+
+Stage 1 报告为 `incomplete-known` 时，handoff 仍可生成输入，但会把这个状态写入
+manifest 的 `warnings`。如果找不到 finalized Stage 2 输出，handoff 只在存在有效
+Stage 1 工件时生成确定性草稿，并明确记录“尚未完成 Stage 2”的警告。

package/skills/a2h-app-req-gen/references/subagent-render.md

@@ -0,0 +1,115 @@
+# Stage 2 子代理渲染协议
+
+在成功且已完成校验的 Stage 1 运行后使用本协议。它规定默认 subagent 模式下，
+运行 `a2h-app-req-gen` 的主 Agent 如何完成渲染。顺序不可倒置：先续跑与派发，
+再快照合并，最后才全文审校。
+
+## 运行模式
+
+| 模式 | 谁启动渲染器 | 渲染协议 |
+|---|---|---|
+| 默认 / `--mode subagent` | 运行本 skill 的主 Agent | 程序生成 `task.md`，主 Agent 为每个单元派发子代理。 |
+| `--mode shell` | Stage 2 Node 进程 | 统一的 `task.md` 与 self-check/finalize 协议，适合自动化。 |
+| `--mode shell-legacy` | Stage 2 Node 进程 | inline prompt 与进程内校验；仅在统一协议不可用时使用。 |
+
+`--mode shell` 和 `--mode shell-legacy` 都需要 `--project-root`；默认
+`--concurrency 8`、`--max-retries 5`、`--backoff-ms 5000`。默认 subagent
+模式没有渲染并发 CLI 参数：本 skill 的 `concurrency` 参数控制主 Agent 的派发
+上限，默认 8。
+
+## 1. Prepare 或续跑
+
+```bash
+pnpm stage2 -- --input <stage1-run-directory> \
+  --project-root <android-project> --output <output-directory>
+```
+
+Prepare 为每个可渲染 Area 创建这些程序拥有的文件：
+
+- `rendering/<unit>/task.md`
+- `rendering/<unit>/expected.json`
+- `render-manifest.json`：每个单元的 task、expected、output 与 self-check 路径
+- `render-list.md`：由当前磁盘输出推导出的可读队列
+
+不要编辑 `task.md` 或 `expected.json`。中断后重新执行同一条 prepare 命令即可续跑；
+它不修改已有 `output.json`，而是重新读取每个单元的输出并生成 `render-list.md`。
+
+`render-list.md` 是方便阅读的视图，不是事实源。单元完成的唯一依据是它自己的
+`output.json` 同时包含 `status: "ok"` 和 `finalized: true`。手工勾选列表不会让
+单元完成，也不会影响 snapshot；下一次 prepare 会按 `output.json` 覆盖这些勾选。
+
+## 2. 派发、验收、重试或停止
+
+同时运行的子代理不超过 `concurrency`。对每个未完成的 manifest 条目，只传递它的
+`taskPath`；子代理自行读取该文件，并且只写其中指定的 `outputPath`。
+
+子代理先写原始判断，执行任务给出的 `check` 命令，依据问题修正；只在最后一次
+check 输出 `ok: true` 时执行原地 `finalize`。主 Agent 仅在 `output.json` 满足上述
+完成条件后接受单元，不能用手写摘要替代子代理输出。
+
+输出缺失或未完成时，对同一任务重试一次；再次未完成则保持 pending，并在本次派发
+会话中计为 skipped。skipped 超过 3 个时停止派发，报告 completed、skipped、
+unstarted 单元及原因。后续 resume 是新的派发会话，可以再次尝试此前 pending 单元。
+
+## 3. Snapshot 已完成内容和回退内容
+
+派发完成或停止后，只合并已持久化的输出：
+
+```bash
+pnpm stage2 -- --input <stage1-run-directory> --snapshot \
+  --output <output-directory> [--per-feature] [--with-unreachable-area] \
+  [--spec-output <spec-input-directory>]
+```
+
+Snapshot 不连接任何后端。缺失或未成功渲染的单元使用确定性的 Stage 1 模板正文；
+它写出 `req-<timestamp>.md` 与 `req-<index>.txt`，将选定的 Markdown 快照复制为
+`<output-directory>/req.md`。如果需要交给 `$a2h-spec-generate`，同时传入
+`--spec-output`；它会在快照合并后生成页面批次和 `manifest.json`，不需要再次解析
+手工编辑的 Markdown。
+
+有两项刻意的范围规则：
+
+- 只导航到本 App Area 的 Feature 不会进入渲染，并从最终 REQ 省略；导航到外部或
+  未确认目标的 Feature 仍会渲染。
+- 未确认可达的 Area 默认省略；使用 `--with-unreachable-area` 才在所有可达 Area
+  之后保留它们。
+
+## 4. 全文审校
+
+本节只在快照已复制为 `req.md` 后开始。它不是续跑或派发的一部分：若渲染单元需要
+返工，回到第 1–2 节，完成后重新 snapshot。
+
+只通读一次 `req.md`，检查跨单元的呈现问题：
+
+- 标题和列表格式是否统一；
+- 措辞是否通顺、是否存在明显的前后矛盾；
+- 同一概念的术语是否一致。
+
+不要在此重新做逐单元源码探索或证据核验。只能对 `req.md` 做非并发的呈现层编辑；
+若要修改渲染单元，应重新 snapshot，而不是在全文审校中修补。
+
+## Shell 命令
+
+无子代理派发能力时，使用统一自动化路径：
+
+```bash
+pnpm stage2 -- --mode shell --input <stage1-run-directory> \
+  --project-root <android-project> --concurrency 8
+```
+
+只有统一协议不可用时，才使用 inline-prompt 回退：
+
+```bash
+pnpm stage2 -- --mode shell-legacy --input <stage1-run-directory> \
+  --project-root <android-project> --backend <claude|opencode>
+```
+
+两个 shell 模式都可使用 Stage 2 CLI 支持的 `--backend`、`--agent-name`、
+`--ai-command`、`--max-retries`、`--backoff-ms`、`--per-feature`、
+`--with-unreachable-area` 参数。
+
+> **注意：** 通过 `--output` 显式指定输出目录时，目标目录必须为空或不存在，
+> 否则 Stage 2 会直接报错退出（防止意外覆盖已有的渲染结果）。`--snapshot`
+> 模式豁免此检查——快照必须读取已有 `output.json`。默认路径不受限制。
+> 在自动化派发流程中，请确保每次运行使用不同的 `--output` 目录，或先清空
+> 目标目录。

package/skills/a2h-app-req-gen/scripts/reqgen/analyzer-jvm/build.gradle.kts

@@ -0,0 +1,41 @@
+plugins {
+    `java-library`
+}
+
+group = "dev.reqgen"
+version = "0.1.0"
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+    withSourcesJar()
+}
+
+dependencies {
+    compileOnly("com.android.tools.lint:lint-api:31.13.2")
+    compileOnly("com.android.tools.lint:lint-checks:31.13.2")
+
+    testImplementation("com.android.tools.lint:lint-api:31.13.2")
+    testImplementation("com.android.tools.lint:lint-checks:31.13.2")
+    testImplementation("com.android.tools.lint:lint-tests:31.13.2")
+    testImplementation("junit:junit:4.13.2")
+}
+
+tasks.withType<JavaCompile>().configureEach {
+    options.release.set(17)
+    options.encoding = "UTF-8"
+    options.compilerArgs.addAll(listOf("-Xlint:all", "-Xlint:-processing"))
+}
+
+tasks.test {
+    useJUnit()
+    maxParallelForks = 1
+}
+
+tasks.jar {
+    manifest {
+        attributes["Lint-Registry-v2"] =
+            "dev.reqgen.analyzer.jvm.RawIssueRegistry"
+    }
+}

package/skills/a2h-app-req-gen/scripts/reqgen/analyzer-jvm/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,8 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-bin.zip
+distributionSha256Sum=20f1b1176237254a6fc204d8434196fa11a4cfb387567519c61556e8710aed78
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

package/skills/a2h-app-req-gen/scripts/reqgen/analyzer-jvm/gradle.properties

@@ -0,0 +1,3 @@
+org.gradle.jvmargs=-Xmx2g -Dfile.encoding=UTF-8
+org.gradle.daemon=false
+org.gradle.parallel=false