android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/merge.js

@@ -0,0 +1,605 @@
+import {
+  buildAreaContentTxt,
+  renderedPath,
+  serializeReqMarkdown,
+  serializeReqTxtAreaContent,
+} from "../generation/index.js";
+import { expandRenderItems } from "./orchestrate.js";
+// Verbatim port: models sometimes repeat the title on the first body line
+// even though the prompt forbids it.
+export function stripLeadingTitle(body, title) {
+  const trimmed = body.replace(/^\s+/, "");
+  if (!trimmed.startsWith(title)) return body;
+  return trimmed.slice(title.length).replace(/^\s*\n+/, "");
+}
+/** Feature ids `filterRenderableAreas` kept for this run (i.e. actually
+ * eligible to be sent to the Agent). A Feature outside this set was never
+ * attempted — it is omitted from the merged output rather than falling back
+ * to the Stage 1 draft, which is reserved for Features the Agent attempted
+ * and failed. */
+function collectFeatureIds(reqModel) {
+  return new Set(
+    reqModel.areas.flatMap((area) =>
+      area.features.map((feature) => feature.id),
+    ),
+  );
+}
+function selectEntry(
+  item,
+  results,
+  templateTitle,
+  templateBody,
+  renderableFeatureIds,
+) {
+  if (!renderableFeatureIds.has(item.feature.id)) return undefined;
+  const result = results.get(item.feature.id);
+  if (result?.status !== "ok" || result.body === undefined) {
+    return { title: templateTitle, body: templateBody };
+  }
+  const title =
+    result.titleValid === true && result.title !== undefined
+      ? result.title
+      : templateTitle;
+  return { title, body: result.body };
+}
+function selectEntryFromArea(
+  featureId,
+  areaResults,
+  templateTitle,
+  templateBody,
+  renderableFeatureIds,
+) {
+  if (!renderableFeatureIds.has(featureId)) return undefined;
+  // Find the feature result across all area results
+  for (const areaResult of areaResults.values()) {
+    if (areaResult.status !== "ok") continue;
+    const featureResult = areaResult.features.get(featureId);
+    if (featureResult === undefined) continue;
+    if (featureResult.status !== "ok" || featureResult.body === undefined) {
+      return { title: templateTitle, body: templateBody };
+    }
+    const title =
+      featureResult.titleValid === true && featureResult.title !== undefined
+        ? featureResult.title
+        : templateTitle;
+    return { title, body: featureResult.body };
+  }
+  return { title: templateTitle, body: templateBody };
+}
+function findFeatureAttemptResult(featureId, areaResults) {
+  for (const areaResult of areaResults.values()) {
+    if (areaResult.status !== "ok") continue;
+    const featureResult = areaResult.features.get(featureId);
+    if (featureResult !== undefined) return featureResult;
+  }
+  return undefined;
+}
+function addedEntriesForArea(areaId, areaResults) {
+  const result = areaResults.get(areaId);
+  if (result?.status !== "ok") return [];
+  return (result.addedFeatures ?? []).flatMap((feature) =>
+    feature.status === "ok" &&
+    feature.title !== undefined &&
+    feature.body !== undefined
+      ? [{ title: feature.title, body: feature.body }]
+      : [],
+  );
+}
+/** Feature ids whose own template slot must be skipped (never emitted) —
+ * every non-earliest member of a merge group the render Agent reported (see
+ * FeatureAttemptResult.mergedFeatureIds). A merge group's content is
+ * rendered exactly once, at the position of whichever member appears first
+ * in Area.features order; later members' 3-line slots are still consumed
+ * from the template (cursor still advances) but push nothing. Standalone
+ * (non-merged) Features are never in this set — selectEntryFromArea still
+ * decides per its own rules (draft fallback / renderableFeatureIds) whether
+ * they actually emit. */
+function planSkippedMergeSlots(area, areaResults) {
+  const skip = new Set();
+  const seenGroups = new Set();
+  for (const feature of area.features) {
+    const result = findFeatureAttemptResult(feature.id, areaResults);
+    const mergedIds =
+      result?.status === "ok" ? result.mergedFeatureIds : undefined;
+    if (mergedIds === undefined || mergedIds.length <= 1) continue;
+    const groupKey = [...mergedIds].sort().join(" ");
+    if (seenGroups.has(groupKey)) {
+      skip.add(feature.id);
+    } else {
+      seenGroups.add(groupKey);
+    }
+  }
+  return skip;
+}
+function assertTemplateShape(lines, index, areaId) {
+  if (lines[index] === undefined) {
+    throw new Error(`template REQ text ended unexpectedly at Area ${areaId}`);
+  }
+}
+/** Area heads are taken verbatim from the Stage 1 deterministic draft
+ * (renderReqDraft output, recomputed by the caller rather than read from
+ * req.md); Feature entries use the Agent title+body when the render
+ * succeeded, the draft when the Agent attempted and failed, and are omitted
+ * entirely when `renderableReqModel` never sent the Feature to the Agent in
+ * the first place (e.g. a navigation-only Feature dropped by
+ * filterRenderableAreas) — a Feature the Agent never saw does not get its
+ * draft text pasted in as if it had been considered. */
+export function mergeReqText(
+  fullReqModel,
+  renderableReqModel,
+  results,
+  templateText,
+) {
+  const lines = templateText.split("\n");
+  const items = expandRenderItems(fullReqModel);
+  const renderableFeatureIds = collectFeatureIds(renderableReqModel);
+  const out = [];
+  let cursor = 0;
+  let itemIndex = 0;
+  fullReqModel.areas.forEach((area, areaIndex) => {
+    while (!lines[cursor].startsWith("区域说明：")) {
+      assertTemplateShape(lines, cursor, area.id);
+      out.push(lines[cursor]);
+      cursor += 1;
+    }
+    out.push(lines[cursor]);
+    cursor += 1;
+    for (const feature of area.features) {
+      const item = items[itemIndex];
+      itemIndex += 1;
+      const templateTitle = lines[cursor + 1];
+      const templateBody = lines[cursor + 2];
+      assertTemplateShape(lines, cursor + 2, feature.id);
+      const entry = selectEntry(
+        item,
+        results,
+        templateTitle,
+        templateBody,
+        renderableFeatureIds,
+      );
+      if (entry !== undefined) out.push("", entry.title, entry.body);
+      cursor += 3;
+    }
+    if (areaIndex < fullReqModel.areas.length - 1) {
+      out.push("");
+      cursor += 1;
+    }
+  });
+  return `${out.join("\n")}\n`;
+}
+/** Same walk as mergeReqText, but returns the Area-blocked Markdown form
+ * (req.md) directly from the structured {title, body} entries, instead of
+ * flattening into a single string and re-parsing it — an Agent-rendered
+ * body may legitimately contain multiple lines or embedded blank lines
+ * (e.g. Law 4's 枚举行 per `options` entry in prompt.ts), which a re-parse
+ * of flat text cannot reliably un-flatten.
+ *
+ * Per-feature mode has no per-Area Agent reachability judgment, so
+ * isAgentJudgedUnreachable falls back to static analysis
+ * (canonicalPath.status === "unreachable") — the same default-drop
+ * behaviour as mergeAreaReqMarkdown, controlled by the same
+ * MergeAreaOptions.includeUnreachableAreas flag. */
+export function mergeReqMarkdown(
+  fullReqModel,
+  renderableReqModel,
+  results,
+  templateText,
+  options = {},
+) {
+  const includeUnreachableAreas = options.includeUnreachableAreas ?? false;
+  const lines = templateText.split("\n");
+  const items = expandRenderItems(fullReqModel);
+  const renderableFeatureIds = collectFeatureIds(renderableReqModel);
+  const blocks = [];
+  let cursor = 0;
+  let itemIndex = 0;
+  fullReqModel.areas.forEach((area, areaIndex) => {
+    const headerLines = [];
+    while (!lines[cursor].startsWith("区域说明：")) {
+      assertTemplateShape(lines, cursor, area.id);
+      headerLines.push(lines[cursor]);
+      cursor += 1;
+    }
+    headerLines.push(lines[cursor]);
+    cursor += 1;
+    const features = [];
+    for (const feature of area.features) {
+      const item = items[itemIndex];
+      itemIndex += 1;
+      const templateTitle = lines[cursor + 1];
+      const templateBody = lines[cursor + 2];
+      assertTemplateShape(lines, cursor + 2, feature.id);
+      const entry = selectEntry(
+        item,
+        results,
+        templateTitle,
+        templateBody,
+        renderableFeatureIds,
+      );
+      if (entry !== undefined) features.push(entry);
+      cursor += 3;
+    }
+    blocks.push({ headerLines, features });
+    if (areaIndex < fullReqModel.areas.length - 1) cursor += 1;
+  });
+  // Per-feature mode has no AreaAttemptResult — pass an empty Map so
+  // isAgentJudgedUnreachable falls back to static analysis.
+  const ordered = partitionAreaBlocks(
+    fullReqModel.areas,
+    blocks,
+    new Map(),
+    includeUnreachableAreas,
+  );
+  return serializeReqMarkdown(ordered);
+}
+function selectAreaDescriptionLine(areaId, areaResults, templateLine) {
+  const result = areaResults.get(areaId);
+  const description =
+    result?.status === "ok" ? result.areaDescription?.trim() : undefined;
+  return description === undefined || description.length === 0
+    ? templateLine
+    : `区域说明：${description}`;
+}
+/** The Agent owns the final source-grounded 访问路径 for every Area. Retain
+ * the deterministic draft only when that Agent response has no accessPath. */
+function selectAccessPathLine(area, areaResults, templateLine) {
+  const result = areaResults.get(area.id);
+  const accessPath =
+    result?.status === "ok" ? result.accessPath?.trim() : undefined;
+  return accessPath === undefined || accessPath.length === 0
+    ? templateLine
+    : `访问路径：${accessPath}`;
+}
+/** True for an Area that should sink to the end of req.md: it was
+ * statically unreachable AND the Agent either never confirmed a real access
+ * path (no result, a failed attempt, or an explicit "confirmed unreachable"
+ * judgment) — conservative default when there is no better information.
+ * Areas the Agent judged reachable (reachable: true, alongside a found
+ * accessPath) join the reachable group instead, ahead of any Area still
+ * judged unreachable. Never affects Areas that were reachable by static
+ * analysis in the first place — those are always in the reachable group. */
+function isAgentJudgedUnreachable(area, areaResults) {
+  if (area.canonicalPath.status !== "unreachable") return false;
+  const result = areaResults.get(area.id);
+  return !(result?.status === "ok" && result.reachable === true);
+}
+/** Stable partition of already-assembled per-Area blocks: Areas judged
+ * reachable first (original relative order), then — only when
+ * includeUnreachableAreas is true — Areas judged unreachable (original
+ * relative order) appended after them; otherwise those blocks are dropped
+ * — see isAgentJudgedUnreachable. Runs only after both the deterministic
+ * template and the per-Area merge walk have already matched every block to
+ * its source Area positionally, so it cannot desync that walk (it only
+ * reorders/drops whole, already-built blocks). */
+function partitionAreaBlocks(
+  originalAreas,
+  blocks,
+  areaResults,
+  includeUnreachableAreas,
+) {
+  const reachable = [];
+  const unreachable = [];
+  originalAreas.forEach((area, index) => {
+    (isAgentJudgedUnreachable(area, areaResults)
+      ? unreachable
+      : reachable
+    ).push(blocks[index]);
+  });
+  return includeUnreachableAreas ? [...reachable, ...unreachable] : reachable;
+}
+/** Merge per-Area rendering results into the Stage 1 deterministic draft
+ * (renderReqDraft output, recomputed by the caller rather than read from
+ * req.md): Area heads verbatim except 区域说明 (Agent-produced when the
+ * session succeeded, else draft fallback) and 访问路径 for unreachable Areas
+ * (Agent-produced access finding/confirmation when available, else draft
+ * fallback); Feature entries from Agent results when available, the draft
+ * when the Agent attempted and failed, and omitted entirely when
+ * `renderableReqModel` never sent the Feature to the Agent at all (see
+ * mergeReqText). Areas the Agent judges unreachable (see
+ * isAgentJudgedUnreachable) are dropped by default, or moved after every
+ * Area it judges reachable when `options.includeUnreachableAreas` is set
+ * (see MergeAreaOptions). */
+export function mergeAreaReqText(
+  fullReqModel,
+  renderableReqModel,
+  areaResults,
+  templateText,
+  options = {},
+) {
+  const includeUnreachableAreas = options.includeUnreachableAreas ?? false;
+  const lines = templateText.split("\n");
+  const renderableFeatureIds = collectFeatureIds(renderableReqModel);
+  const blocks = [];
+  let cursor = 0;
+  fullReqModel.areas.forEach((area) => {
+    const block = [];
+    while (!lines[cursor].startsWith("区域说明：")) {
+      assertTemplateShape(lines, cursor, area.id);
+      block.push(
+        lines[cursor].startsWith("访问路径：")
+          ? selectAccessPathLine(area, areaResults, lines[cursor])
+          : lines[cursor],
+      );
+      cursor += 1;
+    }
+    block.push(selectAreaDescriptionLine(area.id, areaResults, lines[cursor]));
+    cursor += 1;
+    const skippedMergeSlots = planSkippedMergeSlots(area, areaResults);
+    for (const feature of area.features) {
+      const templateTitle = lines[cursor + 1];
+      const templateBody = lines[cursor + 2];
+      assertTemplateShape(lines, cursor + 2, feature.id);
+      const entry = skippedMergeSlots.has(feature.id)
+        ? undefined
+        : selectEntryFromArea(
+            feature.id,
+            areaResults,
+            templateTitle,
+            templateBody,
+            renderableFeatureIds,
+          );
+      if (entry !== undefined) block.push("", entry.title, entry.body);
+      cursor += 3;
+    }
+    for (const entry of addedEntriesForArea(area.id, areaResults)) {
+      block.push("", entry.title, entry.body);
+    }
+    blocks.push(block);
+  });
+  const ordered = partitionAreaBlocks(
+    fullReqModel.areas,
+    blocks,
+    areaResults,
+    includeUnreachableAreas,
+  );
+  return `${ordered.map((block) => block.join("\n")).join("\n\n")}\n`;
+}
+/** Same walk as mergeAreaReqText, but returns the Area-blocked Markdown form
+ * directly from structured entries — see mergeReqMarkdown for why this
+ * avoids re-parsing a flattened, potentially multi-line Agent body. Areas
+ * the Agent judges unreachable are dropped by default, or moved after every
+ * Area it judges reachable when `options.includeUnreachableAreas` is set
+ * (see MergeAreaOptions, same as mergeAreaReqText). */
+export function mergeAreaReqMarkdown(
+  fullReqModel,
+  renderableReqModel,
+  areaResults,
+  templateText,
+  options = {},
+) {
+  const includeUnreachableAreas = options.includeUnreachableAreas ?? false;
+  const lines = templateText.split("\n");
+  const renderableFeatureIds = collectFeatureIds(renderableReqModel);
+  const blocks = [];
+  let cursor = 0;
+  fullReqModel.areas.forEach((area, areaIndex) => {
+    const headerLines = [];
+    while (!lines[cursor].startsWith("区域说明：")) {
+      assertTemplateShape(lines, cursor, area.id);
+      headerLines.push(
+        lines[cursor].startsWith("访问路径：")
+          ? selectAccessPathLine(area, areaResults, lines[cursor])
+          : lines[cursor],
+      );
+      cursor += 1;
+    }
+    headerLines.push(
+      selectAreaDescriptionLine(area.id, areaResults, lines[cursor]),
+    );
+    cursor += 1;
+    const features = [];
+    const skippedMergeSlots = planSkippedMergeSlots(area, areaResults);
+    for (const feature of area.features) {
+      const templateTitle = lines[cursor + 1];
+      const templateBody = lines[cursor + 2];
+      assertTemplateShape(lines, cursor + 2, feature.id);
+      const entry = skippedMergeSlots.has(feature.id)
+        ? undefined
+        : selectEntryFromArea(
+            feature.id,
+            areaResults,
+            templateTitle,
+            templateBody,
+            renderableFeatureIds,
+          );
+      if (entry !== undefined) features.push(entry);
+      cursor += 3;
+    }
+    features.push(...addedEntriesForArea(area.id, areaResults));
+    blocks.push({ headerLines, features });
+    if (areaIndex < fullReqModel.areas.length - 1) cursor += 1;
+  });
+  const ordered = partitionAreaBlocks(
+    fullReqModel.areas,
+    blocks,
+    areaResults,
+    includeUnreachableAreas,
+  );
+  return serializeReqMarkdown(ordered);
+}
+/** Build the suffix part of a txt-format title (without the access path
+ * prefix). The template title is `{path} - {areaName} - {controlName}`;
+ * this returns `{areaName} - {controlName}`. */
+function titleSuffix(templateTitle, path) {
+  const prefix = `${path} - `;
+  return templateTitle.startsWith(prefix)
+    ? templateTitle.slice(prefix.length)
+    : templateTitle;
+}
+/** Txt-format equivalent of selectEntryFromArea: returns the merged
+ * {title, body} for one Feature, preferring Agent output over the template.
+ * Agent titles are already complete navigation titles, so they are not
+ * prefixed with an independently rendered access path. */
+function selectEntryFromAreaTxt(
+  featureId,
+  areaResults,
+  templateTitle,
+  templateBody,
+  accessPath,
+  renderableFeatureIds,
+) {
+  if (!renderableFeatureIds.has(featureId)) return undefined;
+  for (const areaResult of areaResults.values()) {
+    if (areaResult.status !== "ok") continue;
+    const featureResult = areaResult.features.get(featureId);
+    if (featureResult === undefined) continue;
+    if (featureResult.status !== "ok" || featureResult.body === undefined) {
+      return { title: templateTitle, body: templateBody };
+    }
+    const agentTitle =
+      featureResult.titleValid === true && featureResult.title !== undefined
+        ? featureResult.title
+        : titleSuffix(templateTitle, accessPath);
+    return {
+      title:
+        featureResult.titleValid === true && featureResult.title !== undefined
+          ? agentTitle
+          : `${accessPath} - ${agentTitle}`,
+      body: featureResult.body,
+    };
+  }
+  return { title: templateTitle, body: templateBody };
+}
+/** Merge per-Area rendering results into per-area plain-text strings (one
+ * per Area). Operates on structured data (buildAreaContentTxt) rather
+ * than walking template text. Areas the Agent judges unreachable are
+ * dropped by default; pass includeUnreachableAreas to keep them. */
+export function mergeAreaReqTxt(
+  fullReqModel,
+  renderableReqModel,
+  areaResults,
+  graph,
+  options = {},
+) {
+  return mergeAreaReqContents(
+    fullReqModel,
+    renderableReqModel,
+    areaResults,
+    graph,
+    options,
+  ).map(({ content }) => serializeReqTxtAreaContent(content));
+}
+/**
+ * Merge per-Area rendering results without flattening them to text.  This is
+ * the canonical source for downstream adapters; `mergeAreaReqTxt` delegates
+ * to it so both paths have exactly the same fallback, reachability and
+ * Agent-added Feature semantics.
+ */
+export function mergeAreaReqContents(
+  fullReqModel,
+  renderableReqModel,
+  areaResults,
+  graph,
+  options = {},
+) {
+  const includeUnreachableAreas = options.includeUnreachableAreas ?? false;
+  const renderableFeatureIds = collectFeatureIds(renderableReqModel);
+  const contents = fullReqModel.areas.map((area) => {
+    const result = areaResults.get(area.id);
+    const template = buildAreaContentTxt(area, graph);
+    const detPath = renderedPath(area, graph);
+    // Use the Agent's complete source-grounded access path when available,
+    // otherwise keep the deterministic fallback path.
+    const accessPath =
+      (result?.status === "ok" && result.accessPath?.trim()) || detPath;
+    // Rebuild headerLines (preconditions only — area description is dropped).
+    const headerLines = template.headerLines;
+    // Features: prefer Agent output, fall back to template.
+    const skippedMergeSlots = planSkippedMergeSlots(area, areaResults);
+    const features = [];
+    for (let i = 0; i < area.features.length; i++) {
+      const feature = area.features[i];
+      if (skippedMergeSlots.has(feature.id)) continue;
+      const templateFeature = template.features[i];
+      // Rebuild template title with the (possibly overridden) access path.
+      const tplTitle = `${accessPath} - ${titleSuffix(templateFeature.title, detPath)}`;
+      const entry = selectEntryFromAreaTxt(
+        feature.id,
+        areaResults,
+        tplTitle,
+        templateFeature.body,
+        accessPath,
+        renderableFeatureIds,
+      );
+      if (entry !== undefined) features.push(entry);
+    }
+    features.push(...addedEntriesForArea(area.id, areaResults));
+    return { areaId: area.id, content: { headerLines, features } };
+  });
+  const ordered = partitionAreaBlocks(
+    fullReqModel.areas,
+    contents,
+    areaResults,
+    includeUnreachableAreas,
+  );
+  return ordered.filter((entry) => entry.content.features.length > 0);
+}
+/** Merge per-Feature rendering results into per-area plain-text strings.
+ * Like mergeAreaReqTxt but results are keyed by Feature id (per-feature
+ * rendering mode). Unreachable Areas are dropped by default (same as
+ * mergeAreaReqTxt), controlled by MergeAreaOptions.includeUnreachableAreas. */
+export function mergeReqTxt(
+  fullReqModel,
+  renderableReqModel,
+  results,
+  graph,
+  options = {},
+) {
+  return mergeReqContents(
+    fullReqModel,
+    renderableReqModel,
+    results,
+    graph,
+    options,
+  ).map(({ content }) => serializeReqTxtAreaContent(content));
+}
+/** Structured counterpart of `mergeReqTxt` for per-Feature rendering. */
+export function mergeReqContents(
+  fullReqModel,
+  renderableReqModel,
+  results,
+  graph,
+  options = {},
+) {
+  const includeUnreachableAreas = options.includeUnreachableAreas ?? false;
+  const renderableFeatureIds = collectFeatureIds(renderableReqModel);
+  const contents = fullReqModel.areas.map((area) => {
+    const template = buildAreaContentTxt(area, graph);
+    const detPath = renderedPath(area, graph);
+    const accessPath = detPath;
+    const headerLines = template.headerLines;
+    const features = [];
+    for (let i = 0; i < area.features.length; i++) {
+      const feature = area.features[i];
+      if (!renderableFeatureIds.has(feature.id)) continue;
+      const templateFeature = template.features[i];
+      const result = results.get(feature.id);
+      const tplTitle = `${accessPath} - ${titleSuffix(templateFeature.title, detPath)}`;
+      if (result?.status === "ok" && result.body !== undefined) {
+        const agentTitle =
+          result.titleValid === true && result.title !== undefined
+            ? result.title
+            : titleSuffix(templateFeature.title, accessPath);
+        features.push({
+          title:
+            result.titleValid === true && result.title !== undefined
+              ? agentTitle
+              : `${accessPath} - ${agentTitle}`,
+          body: result.body,
+        });
+      } else {
+        features.push({ title: tplTitle, body: templateFeature.body });
+      }
+    }
+    return { areaId: area.id, content: { headerLines, features } };
+  });
+  // Per-feature mode has no AreaAttemptResult — pass an empty Map so
+  // isAgentJudgedUnreachable falls back to static analysis.
+  const ordered = partitionAreaBlocks(
+    fullReqModel.areas,
+    contents,
+    new Map(),
+    includeUnreachableAreas,
+  );
+  return ordered.filter((entry) => entry.content.features.length > 0);
+}