minimal-agent 0.8.2 → 0.10.0

package/skills/ui-design/scripts/normalize_design_json.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Conservatively normalize and validate PPT design.json.
+
+This gate exists because downstream deterministic scripts cannot operate on a
+broken design document. It intentionally fixes only mechanical JSON wrappers
+and trailing commas; it does not invent missing fields or repair arbitrary
+syntax.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass
+from json import JSONDecodeError
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class NormalizeResult:
+    ok: bool
+    data: dict[str, Any] | None = None
+    normalized_text: str = ""
+    error: str = ""
+    position: int | None = None
+    snippet: str = ""
+    source: str = ""
+
+
+def _strip_bom(text: str) -> str:
+    return text.lstrip("\ufeff")
+
+
+def _extract_fenced_json(text: str) -> str:
+    fence = re.search(r"```(?:json)?\s*(.*?)```", text, flags=re.IGNORECASE | re.DOTALL)
+    if fence and "{" in fence.group(1):
+        return fence.group(1).strip()
+    return text.strip()
+
+
+def _extract_first_json_object(text: str) -> str:
+    start = text.find("{")
+    if start < 0:
+        return text.strip()
+
+    depth = 0
+    in_string = False
+    escaped = False
+    for i, ch in enumerate(text[start:], start):
+        if in_string:
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            continue
+        if ch == '"':
+            in_string = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : i + 1].strip()
+    return text[start:].strip()
+
+
+def _remove_trailing_commas(text: str) -> str:
+    return re.sub(r",(\s*[}\]])", r"\1", text)
+
+
+def _escape_unescaped_inner_quotes(text: str) -> str:
+    """修 LLM 高频 JSON 错：字符串值里嵌英文双引号不转义（2026-07-02 真机 halt：
+    `"speaker_notes": "5层架构按"采集→…"自下而上。…"`）。
+
+    状态机扫描：**串内**遇到未转义 `"` 时向后看第一个非空白字符——
+    是 `,` `}` `]` `:` 之一 → 真终结符（键/值正常收尾）；否则视为内容引号，转义成 \\"。
+    修不动的花样（如内容引号后恰好跟逗号）parse 仍失败 → 走原有报错路径，保守不瞎猜。
+    """
+    out: list[str] = []
+    in_string = False
+    escaped = False
+    n = len(text)
+    for i, ch in enumerate(text):
+        if not in_string:
+            if ch == '"':
+                in_string = True
+            out.append(ch)
+            continue
+        if escaped:
+            escaped = False
+            out.append(ch)
+            continue
+        if ch == "\\":
+            escaped = True
+            out.append(ch)
+            continue
+        if ch == '"':
+            j = i + 1
+            while j < n and text[j] in " \t\r\n":
+                j += 1
+            if j >= n or text[j] in ',}]:':
+                in_string = False
+                out.append(ch)
+            else:
+                out.append('\\"')
+            continue
+        out.append(ch)
+    return "".join(out)
+
+
+def _error_snippet(text: str, position: int | None) -> str:
+    if position is None:
+        return text[:480]
+    start = max(0, position - 240)
+    end = min(len(text), position + 240)
+    marker = " " * (position - start) + "^"
+    return text[start:end] + "\n" + marker
+
+
+def _validate_design(data: Any) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(data, dict):
+        return ["top-level JSON must be an object"]
+    pages = data.get("pages")
+    if not isinstance(pages, list) or not pages:
+        return ["top-level object must contain a non-empty pages array"]
+
+    numbers: list[int] = []
+    for index, page in enumerate(pages, 1):
+        if not isinstance(page, dict):
+            errors.append(f"pages[{index - 1}] must be an object")
+            continue
+        number = page.get("page")
+        if not isinstance(number, int):
+            errors.append(f"pages[{index - 1}].page must be an integer")
+            continue
+        numbers.append(number)
+
+    expected = list(range(1, len(pages) + 1))
+    if len(numbers) == len(pages) and numbers != expected:
+        errors.append(f"page numbers must be continuous 1..{len(pages)}, got {numbers}")
+    return errors
+
+
+def normalize_design_text(text: str, source: str = "design.json") -> NormalizeResult:
+    raw = _strip_bom(text)
+    candidate = _extract_first_json_object(_extract_fenced_json(raw))
+    attempts = [candidate]
+    trailing_fixed = _remove_trailing_commas(candidate)
+    if trailing_fixed != candidate:
+        attempts.append(trailing_fixed)
+    quote_repaired = _escape_unescaped_inner_quotes(trailing_fixed)
+    if quote_repaired not in attempts:
+        attempts.append(quote_repaired)
+
+    last_error: JSONDecodeError | None = None
+    last_text = candidate
+    for attempt in attempts:
+        last_text = attempt
+        try:
+            data = json.loads(attempt)
+        except JSONDecodeError as exc:
+            last_error = exc
+            continue
+        errors = _validate_design(data)
+        if errors:
+            return NormalizeResult(
+                ok=False,
+                error="; ".join(errors),
+                snippet=_error_snippet(attempt, None),
+                source=source,
+            )
+        normalized = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+        return NormalizeResult(ok=True, data=data, normalized_text=normalized, source=source)
+
+    if last_error is None:
+        return NormalizeResult(
+            ok=False,
+            error="no JSON object found",
+            snippet=_error_snippet(last_text, None),
+            source=source,
+        )
+    return NormalizeResult(
+        ok=False,
+        error=f"{last_error.msg}: line {last_error.lineno} column {last_error.colno} (char {last_error.pos})",
+        position=last_error.pos,
+        snippet=_error_snippet(last_text, last_error.pos),
+        source=source,
+    )
+
+
+def _read_design_source(build: Path) -> tuple[str, str]:
+    for name in ("design.json", "design.draft.json", "design.md"):
+        path = build / name
+        if path.exists():
+            return path.read_text(encoding="utf-8", errors="replace"), name
+    raise FileNotFoundError("missing design.json/design.draft.json/design.md")
+
+
+def _write_report(build: Path, result: NormalizeResult) -> None:
+    payload = {
+        "ok": result.ok,
+        "source": result.source,
+        "error": result.error,
+        "position": result.position,
+        "snippet": result.snippet,
+        "page_count": len(result.data.get("pages", [])) if result.data else 0,
+    }
+    (build / "design_json_gate.json").write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    if result.ok:
+        text = (
+            "# 设计 JSON 硬验收\n\n"
+            f"- ok: true\n- source: {result.source}\n- pages: {payload['page_count']}\n"
+        )
+    else:
+        text = (
+            "# 设计 JSON 硬验收失败\n\n"
+            f"- ok: false\n- source: {result.source}\n- error: {result.error}\n\n"
+            "## 附近片段\n\n```text\n"
+            f"{result.snippet}\n"
+            "```\n"
+        )
+    (build / "design_json_gate.md").write_text(text, encoding="utf-8")
+
+
+def normalize_build(build: Path) -> NormalizeResult:
+    build.mkdir(parents=True, exist_ok=True)
+    ok_marker = build / "design_json_ok"
+    ok_marker.unlink(missing_ok=True)
+
+    raw_text, source = _read_design_source(build)
+    (build / "design.raw.json").write_text(raw_text, encoding="utf-8")
+    result = normalize_design_text(raw_text, source=source)
+    _write_report(build, result)
+    if result.ok:
+        (build / "design.json").write_text(result.normalized_text, encoding="utf-8")
+        ok_marker.touch()
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--build", default="./build", help="Build directory containing design.json")
+    args = parser.parse_args(argv)
+
+    try:
+        result = normalize_build(Path(args.build))
+    except Exception as exc:  # noqa: BLE001 - CLI should report all IO/setup failures.
+        print(f"DESIGN_JSON_INVALID: {exc}", file=sys.stderr)
+        return 1
+
+    if result.ok:
+        page_count = len(result.data.get("pages", [])) if result.data else 0
+        print(f"DESIGN_JSON_OK: {page_count} pages -> {Path(args.build) / 'design.json'}")
+        return 0
+
+    print(f"DESIGN_JSON_INVALID: {result.error}", file=sys.stderr)
+    if result.snippet:
+        print(result.snippet, file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/ui-design/scripts/normalize_design_json_test.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from normalize_design_json import normalize_build
+
+
+class NormalizeDesignJsonTest(unittest.TestCase):
+    def run_case(self, text: str):
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text(text, encoding="utf-8")
+            result = normalize_build(build)
+            return result, build
+
+    def test_pretty_json_passes_and_writes_marker(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text(
+                json.dumps({"pages": [{"page": 1, "title": "第一页"}]}, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+            result = normalize_build(build)
+            self.assertTrue(result.ok)
+            self.assertTrue((build / "design_json_ok").exists())
+            data = json.loads((build / "design.json").read_text(encoding="utf-8"))
+            self.assertEqual(data["pages"][0]["title"], "第一页")
+
+    def test_markdown_fence_is_extracted(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text(
+                '```json\n{"pages":[{"page":1,"title":"A"}]}\n```',
+                encoding="utf-8",
+            )
+            result = normalize_build(build)
+            self.assertTrue(result.ok)
+            self.assertTrue((build / "design_json_ok").exists())
+
+    def test_trailing_commas_are_removed(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text(
+                '{"pages":[{"page":1,"title":"A",},],}',
+                encoding="utf-8",
+            )
+            result = normalize_build(build)
+            self.assertTrue(result.ok)
+            data = json.loads((build / "design.json").read_text(encoding="utf-8"))
+            self.assertEqual(data["pages"][0]["page"], 1)
+
+    def test_malformed_json_fails_with_snippet(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text(
+                '{"pages":[{"page":1,"evidence":["a"]},"points":[{"k":"x"}]}',
+                encoding="utf-8",
+            )
+            result = normalize_build(build)
+            self.assertFalse(result.ok)
+            self.assertFalse((build / "design_json_ok").exists())
+            report = (build / "design_json_gate.md").read_text(encoding="utf-8")
+            self.assertIn("设计 JSON 硬验收失败", report)
+            self.assertIn("^", report)
+
+    def test_missing_pages_fails(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text('{"slides":[]}', encoding="utf-8")
+            result = normalize_build(build)
+            self.assertFalse(result.ok)
+            self.assertIn("pages", result.error)
+
+    def test_non_continuous_pages_fail(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            build = Path(tmp)
+            (build / "design.json").write_text(
+                '{"pages":[{"page":1},{"page":3}]}',
+                encoding="utf-8",
+            )
+            result = normalize_build(build)
+            self.assertFalse(result.ok)
+            self.assertIn("continuous", result.error)
+
+
+class UnescapedInnerQuoteRepairTest(unittest.TestCase):
+    """未转义内嵌引号修复（2026-07-02 真机 halt：speaker_notes 里 按"采集→…"自下而上 未转义）。"""
+
+    def test_unescaped_chinese_quoted_phrase_is_repaired(self) -> None:
+        from normalize_design_json import normalize_design_text
+        broken = (
+            '{"pages":[{"page":1,'
+            '"speaker_notes":"5层架构按"采集→网络→平台→应用→标准规范"自下而上。",'
+            '"blocks":[{"content":"五层架构","render":"text","role":"title"}]}]}'
+        )
+        result = normalize_design_text(broken)
+        self.assertTrue(result.ok, result.error)
+        self.assertIn("按\"采集", result.data["pages"][0]["speaker_notes"])
+
+    def test_valid_json_untouched_by_repair_path(self) -> None:
+        from normalize_design_json import normalize_design_text
+        ok_text = '{"pages":[{"page":1,"title":"含冒号: 与引号\\"转义\\"的合法串"}]}'
+        result = normalize_design_text(ok_text)
+        self.assertTrue(result.ok, result.error)
+        self.assertEqual(result.data["pages"][0]["title"], '含冒号: 与引号"转义"的合法串')
+
+    def test_unrepairable_still_fails_loudly(self) -> None:
+        from normalize_design_json import normalize_design_text
+        result = normalize_design_text('{"pages":[{"page":1,"t"::::}]}')
+        self.assertFalse(result.ok)
+
+
+if __name__ == "__main__":
+    unittest.main()