minimal-agent 0.9.0 → 0.10.0

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

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+draft_coverage_check.py —— 确定性检查：原文章节/图表结论是否被 draft.md 覆盖到（治「客户图配不上」根因）。
+
+为什么需要
+==========
+用户诊断（2026-07-03 真机复盘）：客户图和内容对不上、很多图被省略没用，根因追到更早的
+draft 撰写阶段——原文有些章节主要靠图片本身说话、文字写得模糊，LLM 写 draft.md 时被明确要求
+「不要整段复制材料原文、按知乎长文自由重组」，这类章节容易被判定「缺乏明确论点」而略过；
+design 阶段又完全不读原文全文（只读 draft.md + material.json），于是这些主题在 draft.md
+里彻底消失，后面自然没有页面可以承载对应的客户图。
+
+本脚本比对两类"理应体现在 draft.md 里的主题"，与 draft.md 全文做词元交集：
+  ① 原文档章节标题（从 source.md 的 Markdown 标题行解析，结构性小节如目录/封面豁免）
+  ② 图表类客户图的核心结论（material.json 里 content_type∈{chart,screenshot_slide,poster}
+     且 key_message 非空的图——这个字段是新增的，旧 material.json 没有则这一类零命中，不影响①）
+
+零交集 → WARNING（不阻断，只报告——本检查的价值在"报出遗漏"而非"强制覆盖率 100%"，
+真正的防线是设计 prompt 层的章节锚定 + 一次 best-effort 回填，见 ppt.yaml 对应两步）。
+
+诚实边界：词元交集是模糊判定，标题措辞与 draft 正文用词不同即可能误报「未覆盖」（内容其实在，
+只是换了说法）；也可能标题本身太泛而误判"覆盖"。只做提示，不做强制。
+
+用法
+====
+    python draft_coverage_check.py --build ./build
+    python draft_coverage_check.py --source ./build/source.md --draft ./build/draft.md --material ./build/material.json
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+
+CJK_RE = re.compile(r"[一-鿿]+")
+WORD_RE = re.compile(r"[A-Za-z0-9]{2,}")
+HEADING_RE = re.compile(r"^#{1,6}\s+(.+?)\s*$", re.MULTILINE)
+ENUM_PREFIX_RE = re.compile(r"^[\s（(]*[一二三四五六七八九十百千\d]+[、.．)）\s]*")
+# 原文里纯结构性的小节标题（非内容主题），不参与覆盖检查——否则「目录」这种词几乎必现于任何
+# draft.md 而误判"覆盖"，或反过来因 draft 不会写"目录"二字而误判"未覆盖"，两头都不准。
+STRUCTURAL_HEADINGS = {
+    "目录", "封面", "前言", "引言", "序言", "概述", "摘要", "结语", "结论", "总结",
+    "附录", "参考文献", "致谢", "封底", "感谢", "正文",
+}
+MIN_HEADING_LEN = 2
+CHART_LIKE_CONTENT_TYPES = {"chart", "screenshot_slide", "poster"}
+
+
+def _tokens(text):
+    """CJK 双字 bigram + ASCII 词（≥2 字符小写）——与 source_usage_check.py 同模式，脚本间不耦合各自拷贝。"""
+    out = set()
+    for seg in CJK_RE.findall(text or ""):
+        for i in range(len(seg) - 1):
+            out.add(seg[i : i + 2])
+    for w in WORD_RE.findall(text or ""):
+        out.add(w.lower())
+    return out
+
+
+def _heading_meaningful(heading):
+    stripped = ENUM_PREFIX_RE.sub("", heading).strip()
+    if len(stripped) < MIN_HEADING_LEN:
+        return False
+    if stripped in STRUCTURAL_HEADINGS:
+        return False
+    return True
+
+
+def parse_headings(source_md_text):
+    """从 source.md 解析章节标题（保序去重），过滤结构性小节。"""
+    seen = set()
+    out = []
+    for m in HEADING_RE.finditer(source_md_text or ""):
+        h = m.group(1).strip()
+        if not h or h in seen:
+            continue
+        seen.add(h)
+        if _heading_meaningful(h):
+            out.append(h)
+    return out
+
+
+def chart_key_messages(material):
+    """从 material.json 取图表类客户图的核心结论：[(file, key_message), ...]。"""
+    out = []
+    for img in (material.get("images") or []) if isinstance(material, dict) else []:
+        if not isinstance(img, dict):
+            continue
+        vision = img.get("vision")
+        if not isinstance(vision, dict):
+            continue
+        content_type = str(vision.get("content_type") or "").strip().lower()
+        key_message = str(vision.get("key_message") or "").strip()
+        if content_type in CHART_LIKE_CONTENT_TYPES and key_message:
+            out.append((img.get("file") or "?", key_message))
+    return out
+
+
+def check_coverage(source_md_path, draft_md_path, material_json_path=None):
+    """返回 (warnings, checked)。draft.md 缺失 → 空跑过（不报错，视为无需检查）。"""
+    warnings = []
+    checked = 0
+
+    if not os.path.isfile(draft_md_path):
+        return warnings, checked
+    with open(draft_md_path, encoding="utf-8") as f:
+        draft_text = f.read()
+    draft_tokens = _tokens(draft_text)
+
+    if os.path.isfile(source_md_path):
+        with open(source_md_path, encoding="utf-8") as f:
+            source_text = f.read()
+        for heading in parse_headings(source_text):
+            checked += 1
+            if _tokens(heading) & draft_tokens:
+                continue
+            warnings.append(
+                f"【原文主题未覆盖】章节「{heading}」在 draft.md 中找不到对应内容"
+                f"  ｜来源：原文章节标题 ｜可能是原文靠图表达、被判定缺乏论点而略过，建议回读 material.md 补一段"
+            )
+
+    if material_json_path and os.path.isfile(material_json_path):
+        try:
+            with open(material_json_path, encoding="utf-8") as f:
+                material = json.load(f)
+        except (OSError, json.JSONDecodeError):
+            material = {}
+        for file, key_message in chart_key_messages(material):
+            checked += 1
+            if _tokens(key_message) & draft_tokens:
+                continue
+            warnings.append(
+                f"【原文主题未覆盖】图表「{file}」的核心结论「{key_message[:40]}」在 draft.md 中找不到对应内容"
+                f"  ｜来源：图表结论（vision.key_message） ｜这张图的论点没被写进大纲，建议补一条论据或例子"
+            )
+
+    return warnings, checked
+
+
+def _write_report(build_dir, warnings, checked):
+    build_dir = os.path.abspath(build_dir)
+    os.makedirs(build_dir, exist_ok=True)
+    report = {"ok": not warnings, "checked": checked, "warnings": warnings}
+    with open(os.path.join(build_dir, "draft_coverage_report.json"), "w", encoding="utf-8") as f:
+        json.dump(report, f, ensure_ascii=False, indent=2)
+    lines = ["# draft.md 原文主题覆盖检查\n", f"- ok: {report['ok']}\n- checked: {checked}\n- warnings: {len(warnings)}\n"]
+    if warnings:
+        lines.append("\n## 未覆盖主题\n")
+        for w in warnings:
+            lines.append(f"- {w}")
+    with open(os.path.join(build_dir, "draft_coverage_report.md"), "w", encoding="utf-8") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--build", default="./build", help="产物目录（默认 ./build）")
+    parser.add_argument("--source", default=None, help="source.md 路径（覆盖 --build 推断）")
+    parser.add_argument("--draft", default=None, help="draft.md 路径（覆盖 --build 推断）")
+    parser.add_argument("--material", default=None, help="material.json 路径（覆盖 --build 推断）")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    args = parser.parse_args()
+
+    source_path = args.source or os.path.join(args.build, "source.md")
+    draft_path = args.draft or os.path.join(args.build, "draft.md")
+    material_path = args.material or os.path.join(args.build, "material.json")
+
+    warnings, checked = check_coverage(source_path, draft_path, material_path)
+    _write_report(args.build, warnings, checked)
+
+    if args.verbose or warnings:
+        for w in warnings:
+            print("WARNING: " + w)
+    if warnings:
+        print(f"DRAFT_COVERAGE_ISSUES: {len(warnings)}/{checked} 个主题未在 draft.md 中找到对应内容")
+        return 1
+    print(f"DRAFT_COVERAGE_OK: {checked} 个主题全部覆盖" if checked else "DRAFT_COVERAGE_OK: 无需检查的主题")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+draft_coverage_check_test.py —— draft_coverage_check.py 的回归锚（stdlib unittest）。
+
+运行：python skills/ui-design/scripts/draft_coverage_check_test.py
+"""
+
+import json
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import draft_coverage_check as dcc  # noqa: E402
+
+
+def _write(path, text):
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(text)
+
+
+class ParseHeadingsTest(unittest.TestCase):
+    def test_parses_headings_dedup_ordered(self):
+        text = "# 一、现场作业场景\n正文\n## 二、成本效益\n正文\n# 一、现场作业场景\n"
+        self.assertEqual(dcc.parse_headings(text), ["一、现场作业场景", "二、成本效益"])
+
+    def test_structural_headings_filtered(self):
+        text = "# 目录\n正文\n## 前言\n正文\n### 三、核心机制\n"
+        self.assertEqual(dcc.parse_headings(text), ["三、核心机制"])
+
+    def test_short_heading_filtered(self):
+        text = "# 一\n正文\n## 二、真实主题标题\n"
+        self.assertEqual(dcc.parse_headings(text), ["二、真实主题标题"])
+
+
+class ChartKeyMessagesTest(unittest.TestCase):
+    def test_extracts_chart_and_screenshot_with_key_message(self):
+        material = {"images": [
+            {"file": "src_1.jpg", "vision": {"content_type": "chart", "key_message": "巡检效率提升三倍"}},
+            {"file": "src_2.jpg", "vision": {"content_type": "photo", "key_message": "应该被忽略"}},
+            {"file": "src_3.jpg", "vision": {"content_type": "screenshot_slide", "key_message": ""}},
+            {"file": "src_4.jpg", "vision": {"content_type": "poster", "key_message": "全景相机替代九台监控"}},
+        ]}
+        out = dcc.chart_key_messages(material)
+        self.assertEqual(out, [("src_1.jpg", "巡检效率提升三倍"), ("src_4.jpg", "全景相机替代九台监控")])
+
+    def test_no_vision_or_missing_images(self):
+        self.assertEqual(dcc.chart_key_messages({}), [])
+        self.assertEqual(dcc.chart_key_messages({"images": [{"file": "a.jpg"}]}), [])
+
+
+class CheckCoverageTest(unittest.TestCase):
+    def setUp(self):
+        self.d = tempfile.mkdtemp(prefix="draftcov-")
+        self.source = os.path.join(self.d, "source.md")
+        self.draft = os.path.join(self.d, "draft.md")
+        self.material = os.path.join(self.d, "material.json")
+
+    def test_uncovered_section_warns(self):
+        _write(self.source, "# 三、现场作业场景\n巡检人员在高空平台开展检修作业\n")
+        _write(self.draft, "# 引子\n本文讨论成本效益与投入产出比。\n")
+        warnings, checked = dcc.check_coverage(self.source, self.draft, self.material)
+        self.assertEqual(checked, 1)
+        self.assertEqual(len(warnings), 1, warnings)
+        self.assertIn("现场作业场景", warnings[0])
+        self.assertIn("原文章节标题", warnings[0])
+
+    def test_covered_section_token_overlap_passes(self):
+        # 章节「系统平台建设」与 draft 正文共享 bigram「平台」→ 视为覆盖。
+        _write(self.source, "# 二、系统平台建设\n")
+        _write(self.draft, "本文围绕平台架构的演进展开讨论。\n")
+        warnings, checked = dcc.check_coverage(self.source, self.draft, self.material)
+        self.assertEqual((checked, warnings), (1, []))
+
+    def test_chart_key_message_uncovered_warns(self):
+        _write(self.source, "")
+        _write(self.draft, "# 引子\n讨论安全生产的重要性。\n")
+        _write(self.material, json.dumps({"images": [
+            {"file": "src_5.jpg", "vision": {"content_type": "chart", "key_message": "巡检效率提升三倍"}}
+        ]}, ensure_ascii=False))
+        warnings, checked = dcc.check_coverage(self.source, self.draft, self.material)
+        self.assertEqual(checked, 1)
+        self.assertEqual(len(warnings), 1, warnings)
+        self.assertIn("src_5.jpg", warnings[0])
+        self.assertIn("图表结论", warnings[0])
+
+    def test_chart_key_message_covered_passes(self):
+        _write(self.source, "")
+        _write(self.draft, "# 引子\n巡检效率相比过去提升明显。\n")
+        _write(self.material, json.dumps({"images": [
+            {"file": "src_5.jpg", "vision": {"content_type": "chart", "key_message": "巡检效率提升三倍"}}
+        ]}, ensure_ascii=False))
+        warnings, checked = dcc.check_coverage(self.source, self.draft, self.material)
+        self.assertEqual((checked, warnings), (1, []))
+
+    def test_missing_draft_returns_empty(self):
+        _write(self.source, "# 一、某章节\n")
+        warnings, checked = dcc.check_coverage(self.source, self.draft, self.material)
+        self.assertEqual((checked, warnings), (0, []))
+
+    def test_missing_source_and_material_skips_those_categories(self):
+        _write(self.draft, "# 引子\n随便写点什么。\n")
+        warnings, checked = dcc.check_coverage(self.source, self.draft, None)
+        self.assertEqual((checked, warnings), (0, []))
+
+    def test_write_report_json_and_md(self):
+        _write(self.source, "# 三、现场作业场景\n")
+        _write(self.draft, "# 引子\n无关内容。\n")
+        warnings, checked = dcc.check_coverage(self.source, self.draft, self.material)
+        dcc._write_report(self.d, warnings, checked)
+        with open(os.path.join(self.d, "draft_coverage_report.json"), encoding="utf-8") as f:
+            report = json.load(f)
+        self.assertEqual(report["ok"], False)
+        self.assertEqual(report["checked"], 1)
+        self.assertEqual(len(report["warnings"]), 1)
+        self.assertTrue(os.path.isfile(os.path.join(self.d, "draft_coverage_report.md")))
+
+    def test_all_covered_report_ok_true(self):
+        _write(self.source, "")
+        _write(self.draft, "# 引子\n无关内容。\n")
+        warnings, checked = dcc.check_coverage(self.source, self.draft, None)
+        dcc._write_report(self.d, warnings, checked)
+        with open(os.path.join(self.d, "draft_coverage_report.json"), encoding="utf-8") as f:
+            report = json.load(f)
+        self.assertEqual(report["ok"], True)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)