android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-generate/references/trace-template.md

@@ -0,0 +1,115 @@
+# Trace file template
+
+The trace is the machine-readable contract between code exploration (2.3) and spec synthesis (2.5). It is written to `<spec_output_dir>/.trace/<feature>.md`, using the same `<feature>` stem as the spec, and it is the **only** input 2.5 may synthesize from.
+
+The trace is an **evidence** document, not a deliverable. It keeps Android symbol names, package names, resource ids, `file:line` anchors, and original English strings verbatim — `## 平台中立化规则` and `## No-Vagueness Rules` govern the spec, never this file. De-platforming happens at 2.5.
+
+Every H2 section below is mandatory. A section with nothing to record is written with an explicit `None`; a missing section fails the 2.4 review.
+
+---
+
+## Field schema
+
+| Field | Meaning |
+|---|---|
+| `claim` | One sentence, the user-observable behavior this entry carries |
+| `layers` | Three fixed sub-fields — `code`, `resource`, `manifest`. Each is a `file:line` hit or `N/A: <reason>`. Omission = not checked, never = not present |
+| `interaction` | State writes, persistence keys (verbatim), in-memory mutations |
+| `data_flow` | trigger → state/coordination layer → repository/service → data source, **each hop carrying `file:line`** |
+
+`code` MUST anchor the **listener / callback registration line**, not only the handler body. Handler-only anchoring fails review.
+
+Every `file:line` is project-root-relative and resolves to exactly one file (see the anchor write-time resolution gate in 2.3).
+
+---
+
+## Template
+
+```markdown
+# Code trace · <feature>
+
+## Status
+status: ok | no_recall | error
+project-path: <android_project_dir>
+backend: homegraph-cli
+req-title: <原始需求标题行，逐字照抄>
+ui-sequence: <该需求的 UI 路径，与 spec 的 `## UI序列` 一字不差>
+terse-req: true | false
+candidate-hosts: [<仅在召回出现 ≥3 个候选宿主时列出>]
+owning-page: <规范化页面归属；同一批次所有 trace 必须一致；无页面归属时用 __shared_capability__>
+page-path: <自应用入口到 owning-page 的页面导航路径，只按页面边界拆分；__shared_capability__ 用 []>
+page-order: pending（Step 4 替换为页内唯一连续正整数，从 1 起）
+page-order-acceptance: pending（Step 4 替换为非空 UI 可见验收动作，需点名桩数据/被替换行为及观察方式）
+
+## Recalled entry points (Path 1 + Path 2 union, deduplicated)
+- Entry 1: <UI 路径 / 页面名> — <file:line> — recalled by: path 1 | path 2 | both
+- ...
+
+## Entry · <name>
+- claim: <一句话描述用户可观察行为>
+- layers:
+  - code:     <file:line>                  # 必填；命中或 `N/A: <reason>`
+  - resource: <file:line> | N/A: <reason>  # res/layout、res/menu、res/values、res/xml …
+  - manifest: <file:line> | N/A: <reason>  # AndroidManifest.xml / Gradle / BuildConfig
+- interaction: <状态写入、持久化 key（逐字）、内存态变更>
+- data_flow:   <trigger → state 层 → repository/service → data source，每跳带 file:line>
+
+## Entry · <name 2> … Entry · <name N>
+（每个入口重复上面的 claim / layers / interaction / data_flow 字段块）
+
+## Implicit triggers (non-UI state changes that activate this feature)
+- Trigger: <切歌 / 权限变化 / 前后台切换 / 网络变化 / 当前歌曲为空 / …> — <file:line> — behavior: <一句话>
+- （无则显式写 None）
+
+## User-visible literals (concrete values the spec must state)
+| 用途 | 值（逐字） | file:line | 备注 |
+|---|---|---|---|
+| toast / dialog / label 文案 | <resource 中的原文> | <res/values/strings.xml:NN> | 有无 values-zh 译文 |
+| 长度 / 数量 / 时长上限 | <100 字符 / 20 条 / 500 毫秒> | <file:line> | |
+| 默认值 / 开关默认态 | <关闭 / 150dp / 14.0dp> | <file:line> | 声明默认 vs 读侧生效默认 |
+| 排序规则与方向 | <按添加时间倒序> | <file:line> | |
+| 位置 / 尺寸 / 颜色 | <…> | <file:line> | 需布局属性坐实 |
+（这一节是 2.5 满足 `## No-Vagueness Rules` 的取值来源；无则写 None）
+
+## Core business entities (data model / persistence key / state machine)
+- Entity X: <file:line + 字段列表 + 语义>
+- 依赖型需求：<依赖的 key 名> 来自 feature `<被依赖 feature>`，见 <file:line>
+- ...
+
+## Cross-entry shared declarations
+- <多个入口共用的 AndroidManifest / Gradle 声明，带 file:line>
+- （无则显式写 None；单入口的 manifest 事实写在该入口的 `manifest` 层字段里）
+
+## Deviations from REQ_DESC
+1. <需求写 A，但 file:line 处代码行为是 B>
+2. ...
+（无则显式写 None，以确认这项检查执行过）
+
+## Scope / Boundary — Exhaustive entry enumeration
+### Touched entries (所有触达该功能/状态的 UI 路径，不限于需求原文提到的)
+（每条沿用与 `## Entry` 相同的 claim / layers / interaction / data_flow 字段块）
+
+### Consumers (谁读取该状态 / 数据)
+- Consumer: <组件名> — <file:line>
+
+### Non-consumers (带证据的边界反例)
+- claim:          <例："桌面小组件不读取该 key">
+  closure_layers: [code, resource, manifest]
+  tools:          [Grep "<pattern>", npx --yes homegraph callers "<symbol>", Read "<path>"]
+  zero_hits:      <逐字零命中证据：搜索的文件范围、使用的正则、命中数>
+
+## Claim evidence ledger (fabrication-prone classes)
+| claim（与 trace/spec 中措辞一致） | class（guard / retention / position / order / default / string-visibility / global-attribution / displayed-value / quantifier） | file:line | verbatim source quote |
+|---|---|---|---|
+（上述所有小节与 spec 草稿中，落入易伪造类别的每条声明各占一行；引文必须能推出该声明；无则显式写 None）
+```
+
+---
+
+## Notes
+
+- **`ui-sequence`** mirrors the spec's `## UI序列` body exactly — the requirement title copied verbatim. It is not re-derived here.
+- **`terse-req: true`** is set when the requirement body is under ~20 substantive characters or carries only topical keywords. It tells 2.4 to additionally verify that every settings screen discovered during the broad enumeration passes has at least one Entry or Touched-entry.
+- **`status: no_recall`** is written when both recall paths return zero and the user declines to name an entry point. 2.3's remaining sections, 2.4, and 2.5 are then skipped and the requirement is flagged in the Step 3 report. Never fabricate entry points to avoid this state.
+- **Library-source anchors**: facts read from a dependency's sources are replayable evidence, but the `path:line` colon format is reserved for files under the project root. Write library evidence as `«artifactId:version» path/inside/jar.kt line N` — the word `line`, never a colon.
+- **Ownership & order metadata**: `owning-page` and `page-path` are derived in Step 0 and never rewritten; `page-path: []` is the canonical empty spelling for `__shared_capability__`. `page-order` and `page-order-acceptance` start as `pending` and are replaced by Step 4 only after intra-page ordering. `a2h-spec-order` requires all four fields (non-pending) before it can include this trace in the global order. A trace that still carries `pending` means its page batch has not finished Step 4 — except for `no_recall` / `error` traces, which carry no Spec, are excluded from Step 4 and from `a2h-spec-order`, and legitimately keep `pending` after a completed run.

package/skills/a2h-spec-generate/scripts/parse_requirements.mjs

@@ -0,0 +1,537 @@
+#!/usr/bin/env node
+/**
+ * 需求表/需求文本解析工具 —— 把一个需求文件拆成「多条独立需求」，供 a2h-spec-generate
+ * skill 逐条生成 spec。一个输入文件包含多条需求，一条需求 = 一份 spec。
+ *
+ * 支持两种输入类型，拆分后结构完全一致：
+ *   - Excel 类型 (.xlsx / .xlsm / .csv)：一行 = 一条需求
+ *       第 1 列 = UI 路径（如「设置-歌词-悬浮窗状态栏歌词」）
+ *       第 2 列 = 功能描述（可含换行与缩进的多行文本）
+ *       第 3 列及之后的列会按行追加到功能描述末尾，不会被丢弃
+ *   - 文本类型 (.txt)：空行分隔的一段 = 一条需求
+ *       段落首行 = UI 路径，其余行 = 功能描述
+ * 参见 template/REQ.xlsx 与 template/REQ.txt，两者内容等价。
+ *
+ * 零第三方依赖：xlsx 本质是 ZIP + XML，这里用 node:zlib 手工解压 + 正则解析。
+ * 运行环境：Node ≥ 22（纯 JS，无需类型剥离，可直接 `node parse_requirements.mjs`）。
+ *
+ * 用法:
+ *   node parse_requirements.mjs --input REQ.xlsx --json      # 逐条需求（推荐，供 skill 迭代）
+ *   node parse_requirements.mjs --input REQ.xlsx             # 归一化文本 → stdout
+ *   node parse_requirements.mjs --input REQ.xlsx --out a.txt # 归一化文本 → 文件
+ *   node parse_requirements.mjs --input REQ.xlsx --split-dir ./out  # 每条需求一个 .txt
+ *   node parse_requirements.mjs --input REQ.xlsx --sheet 需求 # 指定工作表（名称或 1-based 序号）
+ *   node parse_requirements.mjs --input REQ.xlsx --list-sheets
+ *   node parse_requirements.mjs --input legacy.txt --single  # 整个文件当作单条需求
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as zlib from "node:zlib";
+// ---------------------------------------------------------------- ZIP 容器
+function findEndOfCentralDirectory(buf) {
+  const start = Math.max(0, buf.length - (22 + 0xffff));
+  for (let i = buf.length - 22; i >= start; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) return i;
+  }
+  return -1;
+}
+/** 读出 zip 中所有条目（名称 → 解压后的内容）。仅支持 stored / deflate，够覆盖 xlsx。 */
+function readZipEntries(buf) {
+  const eocd = findEndOfCentralDirectory(buf);
+  if (eocd < 0)
+    throw new Error("不是合法的 xlsx/zip 文件：找不到 ZIP 中央目录结束记录");
+  let entryCount = buf.readUInt16LE(eocd + 10);
+  let cdOffset = buf.readUInt32LE(eocd + 16);
+  // ZIP64：条目数或中央目录偏移溢出时改读 ZIP64 结束记录
+  if (entryCount === 0xffff || cdOffset === 0xffffffff) {
+    const locator = eocd - 20;
+    if (locator >= 0 && buf.readUInt32LE(locator) === 0x07064b50) {
+      const z64 = Number(buf.readBigUInt64LE(locator + 8));
+      if (
+        z64 >= 0 &&
+        z64 + 56 <= buf.length &&
+        buf.readUInt32LE(z64) === 0x06064b50
+      ) {
+        entryCount = Number(buf.readBigUInt64LE(z64 + 32));
+        cdOffset = Number(buf.readBigUInt64LE(z64 + 48));
+      }
+    }
+  }
+  const files = new Map();
+  let p = cdOffset;
+  for (let i = 0; i < entryCount; i++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== 0x02014b50) break;
+    const method = buf.readUInt16LE(p + 10);
+    const compressedSize = buf.readUInt32LE(p + 20);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const localOffset = buf.readUInt32LE(p + 42);
+    const name = buf.toString("utf8", p + 46, p + 46 + nameLen);
+    p += 46 + nameLen + extraLen + commentLen;
+    if (
+      localOffset + 30 > buf.length ||
+      buf.readUInt32LE(localOffset) !== 0x04034b50
+    )
+      continue;
+    const lNameLen = buf.readUInt16LE(localOffset + 26);
+    const lExtraLen = buf.readUInt16LE(localOffset + 28);
+    const dataStart = localOffset + 30 + lNameLen + lExtraLen;
+    const raw = buf.subarray(dataStart, dataStart + compressedSize);
+    if (method === 0) files.set(name, Buffer.from(raw));
+    else if (method === 8) files.set(name, zlib.inflateRawSync(raw));
+    else
+      throw new Error(`xlsx 内部条目 ${name} 使用了不支持的压缩方式 ${method}`);
+  }
+  return files;
+}
+// ---------------------------------------------------------------- XML 解析
+function decodeXmlText(s) {
+  return s
+    .replace(/_x000D_/g, "")
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, h) =>
+      String.fromCodePoint(parseInt(h, 16)),
+    )
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(Number(d)))
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&");
+}
+function attr(tag, name) {
+  const m = new RegExp(
+    `\\b${name.replace(/:/g, "\\:")}\\s*=\\s*"([^"]*)"`,
+  ).exec(tag);
+  return m ? decodeXmlText(m[1]) : undefined;
+}
+/** 取出片段内所有 <t> 文本并拼接（富文本多个 run 会被合并；忽略日文注音 <rPh>）。 */
+function collectTextNodes(xml) {
+  const cleaned = xml.replace(/<rPh[\s\S]*?<\/rPh>/g, "");
+  let text = "";
+  const tRe = /<t\b[^>]*\/>|<t\b[^>]*>([\s\S]*?)<\/t>/g;
+  let m;
+  while ((m = tRe.exec(cleaned)) !== null) text += decodeXmlText(m[1] ?? "");
+  return text;
+}
+function parseSharedStrings(xml) {
+  const out = [];
+  const siRe = /<si\b[^>]*\/>|<si\b[^>]*>([\s\S]*?)<\/si>/g;
+  let m;
+  while ((m = siRe.exec(xml)) !== null) out.push(collectTextNodes(m[1] ?? ""));
+  return out;
+}
+/** "AB12" → 27（0-based 列号） */
+function columnIndexFromRef(ref) {
+  const letters = /^([A-Z]+)/.exec(ref.toUpperCase());
+  if (!letters) return -1;
+  let n = 0;
+  for (const ch of letters[1]) n = n * 26 + (ch.charCodeAt(0) - 64);
+  return n - 1;
+}
+function parseSheet(xml, shared) {
+  const rows = [];
+  const rowRe = /<row\b[^>]*\/>|<row\b[^>]*>([\s\S]*?)<\/row>/g;
+  let rm;
+  while ((rm = rowRe.exec(xml)) !== null) {
+    const inner = rm[1] ?? "";
+    const cells = [];
+    let auto = 0;
+    const cellRe = /<c\b([^>]*)\/>|<c\b([^>]*)>([\s\S]*?)<\/c>/g;
+    let cm;
+    while ((cm = cellRe.exec(inner)) !== null) {
+      const attrs = cm[1] ?? cm[2] ?? "";
+      const body = cm[3] ?? "";
+      const ref = attr(attrs, "r");
+      const col = ref ? columnIndexFromRef(ref) : -1;
+      const index = col >= 0 ? col : auto;
+      auto = index + 1;
+      const type = attr(attrs, "t") ?? "n";
+      let value = "";
+      if (type === "inlineStr") {
+        value = collectTextNodes(body);
+      } else {
+        const v = /<v\b[^>]*>([\s\S]*?)<\/v>/.exec(body);
+        const rawValue = v ? decodeXmlText(v[1]) : "";
+        if (type === "s") {
+          const i = Number(rawValue);
+          value =
+            Number.isInteger(i) && i >= 0 && i < shared.length ? shared[i] : "";
+        } else if (type === "b") {
+          value =
+            rawValue === "1" ? "TRUE" : rawValue === "0" ? "FALSE" : rawValue;
+        } else {
+          value = rawValue;
+        }
+      }
+      while (cells.length < index) cells.push("");
+      cells[index] = value;
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+function resolveSheets(zip) {
+  const workbook = zip.get("xl/workbook.xml");
+  if (!workbook) throw new Error("xlsx 缺少 xl/workbook.xml，文件可能已损坏");
+  const relsBuf = zip.get("xl/_rels/workbook.xml.rels");
+  const rels = new Map();
+  if (relsBuf) {
+    const relRe =
+      /<Relationship\b[^>]*\/>|<Relationship\b[^>]*>[\s\S]*?<\/Relationship>/g;
+    let m;
+    const relXml = relsBuf.toString("utf8");
+    while ((m = relRe.exec(relXml)) !== null) {
+      const id = attr(m[0], "Id");
+      const target = attr(m[0], "Target");
+      if (id && target) rels.set(id, target);
+    }
+  }
+  const sheets = [];
+  const sheetRe = /<sheet\b[^>]*\/>|<sheet\b[^>]*>[\s\S]*?<\/sheet>/g;
+  let m;
+  const wbXml = workbook.toString("utf8");
+  let fallbackIndex = 0;
+  while ((m = sheetRe.exec(wbXml)) !== null) {
+    fallbackIndex++;
+    const name = attr(m[0], "name") ?? `Sheet${fallbackIndex}`;
+    const rid = attr(m[0], "r:id") ?? attr(m[0], "relationshipId");
+    let target = rid ? rels.get(rid) : undefined;
+    if (!target) target = `worksheets/sheet${fallbackIndex}.xml`;
+    const entry = target.startsWith("/")
+      ? target.slice(1)
+      : `xl/${target.replace(/^\.\//, "")}`;
+    sheets.push({ name, entry });
+  }
+  if (sheets.length === 0) throw new Error("xlsx 中没有找到任何工作表");
+  return sheets;
+}
+function readXlsx(file, sheetSelector) {
+  const zip = readZipEntries(fs.readFileSync(file));
+  const sheets = resolveSheets(zip);
+  let picked;
+  if (sheetSelector) {
+    const asIndex = Number(sheetSelector);
+    if (Number.isInteger(asIndex) && asIndex >= 1 && asIndex <= sheets.length)
+      picked = sheets[asIndex - 1];
+    else picked = sheets.find((s) => s.name === sheetSelector);
+    if (!picked) {
+      throw new Error(
+        `找不到工作表 "${sheetSelector}"。可用工作表：${sheets.map((s, i) => `${i + 1}. ${s.name}`).join("，")}`,
+      );
+    }
+  } else {
+    picked = sheets[0];
+  }
+  const sheetBuf = zip.get(picked.entry);
+  if (!sheetBuf) throw new Error(`xlsx 内部缺少工作表数据 ${picked.entry}`);
+  const sharedBuf = zip.get("xl/sharedStrings.xml");
+  const shared = sharedBuf
+    ? parseSharedStrings(sharedBuf.toString("utf8"))
+    : [];
+  return {
+    rows: parseSheet(sheetBuf.toString("utf8"), shared),
+    sheets,
+    picked,
+  };
+}
+// ---------------------------------------------------------------- CSV
+function parseCsv(text) {
+  const body = text.replace(/^/, "");
+  const firstLine = body.split(/\r?\n/, 1)[0] ?? "";
+  const delimiter = firstLine.includes("\t")
+    ? "\t"
+    : firstLine.includes(";") && !firstLine.includes(",")
+      ? ";"
+      : ",";
+  const rows = [];
+  let row = [];
+  let cell = "";
+  let quoted = false;
+  for (let i = 0; i < body.length; i++) {
+    const ch = body[i];
+    if (quoted) {
+      if (ch === '"') {
+        if (body[i + 1] === '"') {
+          cell += '"';
+          i++;
+        } else quoted = false;
+      } else cell += ch;
+      continue;
+    }
+    if (ch === '"') {
+      quoted = true;
+      continue;
+    }
+    if (ch === delimiter) {
+      row.push(cell);
+      cell = "";
+      continue;
+    }
+    if (ch === "\r") continue;
+    if (ch === "\n") {
+      row.push(cell);
+      rows.push(row);
+      row = [];
+      cell = "";
+      continue;
+    }
+    cell += ch;
+  }
+  if (cell !== "" || row.length > 0) {
+    row.push(cell);
+    rows.push(row);
+  }
+  return rows;
+}
+function isBlankRow(row) {
+  return row.every((c) => (c ?? "").trim() === "");
+}
+function looksLikeHeader(row) {
+  const first = (row[0] ?? "").trim();
+  const second = (row[1] ?? "").trim();
+  if (!first) return false;
+  if (
+    /^(ui\s*路径|ui\s*path|路径|界面路径|菜单路径|设置路径|功能路径)$/i.test(
+      first,
+    )
+  )
+    return true;
+  return (
+    /(路径|path)/i.test(first) && /(描述|说明|功能|需求|desc)/i.test(second)
+  );
+}
+/** 表格：一行 = 一条需求。去掉末尾空白行/空白列后逐行映射。 */
+function rowsToRawItems(rows, header) {
+  const data = rows.filter((r) => !isBlankRow(r));
+  if (data.length === 0) return [];
+  // auto 模式下，若跳过表头会把唯一一行数据也吃掉，则宁可不跳——单行需求表比表头更常见
+  const autoSkip =
+    header === "auto" && looksLikeHeader(data[0]) && data.length > 1;
+  const skipFirst = header === "yes" || autoSkip;
+  const body = skipFirst ? data.slice(1) : data;
+  return body
+    .map((row) => {
+      const cells = [...row];
+      while (cells.length > 0 && (cells[cells.length - 1] ?? "").trim() === "")
+        cells.pop();
+      const uiPath = (cells[0] ?? "").trim();
+      const description = cells
+        .slice(1)
+        .map((c) => (c ?? "").replace(/\s+$/, ""))
+        .filter((c) => c.trim() !== "")
+        .join("\n")
+        .trim();
+      return { uiPath, description };
+    })
+    .filter((item) => item.uiPath !== "" || item.description !== "");
+}
+/** 文本：空行分隔的一段 = 一条需求，段首行 = UI 路径，其余行 = 功能描述。 */
+function textToRawItems(text, single) {
+  const body = text.replace(/^/, "").replace(/\r\n?/g, "\n");
+  const blocks = single ? [body] : body.split(/\n[ \t]*\n+/);
+  return blocks
+    .map((b) => b.replace(/\s+$/, ""))
+    .filter((b) => b.trim() !== "")
+    .map((block) => {
+      const lines = block.split("\n");
+      return {
+        uiPath: (lines[0] ?? "").trim(),
+        description: lines.slice(1).join("\n").replace(/\s+$/, ""),
+      };
+    });
+}
+function sanitizeFileName(name) {
+  const cleaned = name
+    .replace(/[\\/:*?"<>|]+/g, "_")
+    .replace(/\s+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return (cleaned || "requirement").slice(0, 60);
+}
+/**
+ * 给每条需求编号并生成确定性的输出名：`<前缀>-<序号>-<UI路径>`。
+ * 只有一条需求时退化为 `<前缀>`，保持"一个文件一条需求"的旧命名不变。
+ */
+function withNames(items, prefix) {
+  const width = String(items.length).length;
+  return items.map((item, i) => {
+    const index = i + 1;
+    const name =
+      items.length === 1
+        ? sanitizeFileName(prefix)
+        : `${sanitizeFileName(prefix)}-${String(index).padStart(width, "0")}-${sanitizeFileName(item.uiPath || `requirement_${index}`)}`;
+    return { index, name, uiPath: item.uiPath, description: item.description };
+  });
+}
+/** 单条需求归一化为纯文本：UI 路径一行 + 功能描述若干行。 */
+function rawToText(item) {
+  return [item.uiPath, item.description].filter((s) => s !== "").join("\n");
+}
+/** 多条需求合并为纯文本：需求之间空一行（与等价的 .txt 逐字节一致）。 */
+function rawListToText(items) {
+  return items.map(rawToText).join("\n\n");
+}
+/** --single：把整份表格压成一条需求（UI 路径留空，描述是全表归一化文本）。 */
+function collapseToSingle(items) {
+  if (items.length <= 1) return items;
+  return [{ uiPath: "", description: rawListToText(items) }];
+}
+/** 整个文件归一化为纯文本，结尾补一个换行。 */
+function toNormalizedText(items) {
+  return items.map(rawToText).join("\n\n") + "\n";
+}
+// ---------------------------------------------------------------- CLI
+function parseArgs(argv) {
+  const opts = {
+    input: "",
+    json: false,
+    listSheets: false,
+    header: "auto",
+    single: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`参数 ${a} 缺少取值`);
+      return v;
+    };
+    switch (a) {
+      case "--input":
+      case "-i":
+        opts.input = next();
+        break;
+      case "--out":
+      case "-o":
+        opts.out = next();
+        break;
+      case "--json":
+        opts.json = true;
+        break;
+      case "--split-dir":
+        opts.splitDir = next();
+        break;
+      case "--sheet":
+        opts.sheet = next();
+        break;
+      case "--list-sheets":
+        opts.listSheets = true;
+        break;
+      case "--single":
+        opts.single = true;
+        break;
+      case "--prefix":
+        opts.prefix = next();
+        break;
+      case "--header": {
+        const v = next();
+        if (v !== "auto" && v !== "yes" && v !== "no")
+          throw new Error("--header 只能是 auto | yes | no");
+        opts.header = v;
+        break;
+      }
+      case "--help":
+      case "-h":
+        console.log(
+          [
+            "用法: node parse_requirements.mjs --input <REQ.xlsx|REQ.csv|REQ.txt> [选项]",
+            "",
+            "把一个需求文件拆成多条独立需求（一条需求 = 一份 spec）。",
+            "",
+            "  --input, -i <file>    需求文件（.xlsx / .xlsm / .csv / .txt）",
+            "  --json                输出 [{index, name, uiPath, description}]（推荐）",
+            "  --out,   -o <file>    归一化文本写入文件（默认写 stdout）",
+            "  --split-dir <dir>     每条需求单独写一个 <name>.txt 到该目录",
+            "  --prefix <stem>       覆盖 name 前缀（默认取输入文件名）",
+            "  --sheet <name|index>  指定工作表，名称或 1-based 序号（默认第一个）",
+            "  --list-sheets         只打印工作表列表",
+            "  --header auto|yes|no  表格是否跳过表头行（默认 auto，自动识别）",
+            "  --single              整个文件只算一条需求（不按空行/行拆分）",
+          ].join("\n"),
+        );
+        process.exit(0);
+      // eslint-disable-next-line no-fallthrough
+      default:
+        if (!opts.input && !a.startsWith("-")) opts.input = a;
+        else throw new Error(`无法识别的参数：${a}`);
+    }
+  }
+  if (!opts.input) throw new Error("缺少必需参数 --input <需求文件>");
+  return opts;
+}
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const input = path.resolve(opts.input);
+  if (!fs.existsSync(input)) throw new Error(`输入文件不存在：${input}`);
+  const ext = path.extname(input).toLowerCase();
+  if (ext === ".xls") {
+    throw new Error(
+      "不支持旧版二进制 .xls (BIFF) 格式，请在 Excel/WPS 中另存为 .xlsx 或 .csv 后重试",
+    );
+  }
+  let raw;
+  if (ext === ".txt" || ext === ".md") {
+    if (opts.listSheets) {
+      console.log("1\t(纯文本无工作表)");
+      return;
+    }
+    raw = textToRawItems(fs.readFileSync(input, "utf8"), opts.single);
+  } else if (ext === ".csv" || ext === ".tsv") {
+    if (opts.listSheets) {
+      console.log("1\t(CSV 无工作表)");
+      return;
+    }
+    const rows = rowsToRawItems(
+      parseCsv(fs.readFileSync(input, "utf8")),
+      opts.header,
+    );
+    raw = opts.single ? collapseToSingle(rows) : rows;
+  } else {
+    const parsed = readXlsx(input, opts.sheet);
+    if (opts.listSheets) {
+      console.log(
+        parsed.sheets.map((s, i) => `${i + 1}\t${s.name}`).join("\n"),
+      );
+      return;
+    }
+    const rows = rowsToRawItems(parsed.rows, opts.header);
+    raw = opts.single ? collapseToSingle(rows) : rows;
+  }
+  const prefix = opts.prefix ?? path.basename(input, path.extname(input));
+  const items = withNames(raw, prefix);
+  if (items.length === 0)
+    throw new Error(`需求文件 ${input} 中没有解析到任何需求`);
+  if (opts.splitDir) {
+    const dir = path.resolve(opts.splitDir);
+    fs.mkdirSync(dir, { recursive: true });
+    const written = [];
+    for (const item of items) {
+      const file = path.join(dir, `${item.name}.txt`);
+      fs.writeFileSync(file, rawToText(item) + "\n", "utf8");
+      written.push(file);
+    }
+    console.log(written.join("\n"));
+    return;
+  }
+  const output = opts.json
+    ? JSON.stringify(items, null, 2) + "\n"
+    : toNormalizedText(items);
+  if (opts.out) {
+    const file = path.resolve(opts.out);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, output, "utf8");
+    console.error(
+      `[parse_requirements] 已解析 ${items.length} 条需求 → ${file}`,
+    );
+  } else {
+    process.stdout.write(output);
+  }
+}
+try {
+  main();
+} catch (err) {
+  console.error(
+    `[parse_requirements] 错误：${err instanceof Error ? err.message : String(err)}`,
+  );
+  process.exit(1);
+}

package/skills/a2h-spec-generate/template/REQ.txt

@@ -0,0 +1,22 @@
+设置-歌词-歌词界面-卡拉OK歌词动画兼容策略（播放页歌词设置同步实现）
+逐字歌词效果，默认是当前行
+    1,当前行：只为前歌曲的歌词中有单字时间戳的歌词行显示逐字特效
+    2,扩展全部：当前歌曲的歌词中只要有一行歌词带单字时间戳，所有歌词行都显示逐字特效
+    3,总是：当前歌曲所有歌词行都显示逐字特效
+
+设置-用户界面-圆形播放封面（圆形支持旋转）
+开关，默认关闭，打开后，在播放页以圆形展示封面，并且自动旋转
+
+设置-用户界面-允许不规则封面（支持长方形封面，参考无归）
+开关，默认打开，播放页封面以大小一致的正方形展示，打开后，在播放页封面以原始样式展示
+
+设置-歌词-悬浮窗状态栏歌词
+开关 ，默认关闭，打开前需要申请悬浮窗权限，打开后在悬浮窗滚动展示歌词
+    1,左右位置：默认0%
+    2,上下位置：默认0px
+    3,宽度：默认150dp
+    4,大小：默认14.0dp
+    5,选择颜色：默认蓝色
+    6,歌词文本居左对齐：开关 默认关闭，歌词在设置的宽度内中对齐
+    7,状态栏歌词不显示翻译：开关 默认关闭
+    8,在播放界面隐藏：开关 默认关闭 打开后如果切换到播放页，则不在悬浮窗区域显示歌词