feat(review): 审查结论改为结构化 JSON，移除二次 LLM 抽取

- checklist.py：系统提示加入结构化输出契约（只输出 {summary, issues[]}，引用 handle 必须真实存在、不得编造） - review.py：review_frame 返回 {summary, issues, raw}；仅在「不再请求工具」的回合解析结论，中间工具回合的 content 永不解析；强制收口那次 chat 不传 tools - report.py：删除 extract_issues 与 _EXTRACT_SYSTEM（不再需要第二次 LLM 调用）；新增 format_finding（用 .get，顺带修复缺 frame 键 KeyError）；save_report 的 issues 省略时从 findings 拍平 - __main__.py：主流程改为确定性检查 → review_frame → build_finding（合并+校验）， issues 由 flatten_issues 派生顺带修复既有 gap：summarize 硬下标 KeyError、extract_issues 单行围栏解析失败。
2026-10-14 19:53:41 +08:00
1 parent f6d61f8d07
commit f7fa8f14d9
@@ -6,6 +6,8 @@ import sys
 from pathlib import Path

 from . import config
+from . import checks as checks_phase
+from . import findings as findings_mod
 from .annotator import annotate, clear
 from .checklist import build_system_prompt, checklist_summary
 from .context import ReviewContext
@@ -80,25 +82,35 @@ def run_review(ctx, args):
        print(f"[evidence] 已写入 {path}")
        return 0

-    print("[3/4] 审查：逐图框 LLM 审查（含受控只读取证子循环） ...")
-    findings = []
+    print("[3/4] 审查：确定性检查前置 + 逐图框 LLM 审查（含受控只读取证子循环） ...")
+    frame_findings = []
    for ev in evidences:
        print(f"  - 审查图框 {ev['index']} ...")
-        text = review.review_frame(ctx, ev, system_prompt)
-        findings.append(
-            {
-                "frame": ev["index"],
-                "sheet": (ev.get("frame") or {}).get("sheet_size"),
-                "finding": text,
-            }
+        checks = (
+            checks_phase.run_deterministic_checks(ctx, ev)
+            if config.DETERMINISTIC_CHECKS
+            else []
+        )
+        conclusion = review.review_frame(ctx, ev, system_prompt)
+        finding = findings_mod.build_finding(
+            ev, conclusion, checks, validate_handles=config.VALIDATE_HANDLES
+        )
+        frame_findings.append(finding)
+
+        counts = finding["counts"]
+        preview = finding["summary"]
+        if len(preview) > 200:
+            preview = preview[:200] + "..."
+        print(
+            f"    结论：{preview}"
+            f"（确定性 {counts['deterministic']} / LLM {counts['llm']}"
+            f" / 未核实 {counts['unverified']}）"
        )
-        preview = text if len(text) <= 200 else text[:200] + "..."
-        print(f"    结论：{preview}")

    print("[4/4] 汇总报告 ...")
-    markdown = report.summarize(ctx, findings)
-    issues = report.extract_issues(ctx, findings)
-    report.save_report(markdown, findings, plan, issues)
+    markdown = report.summarize(ctx, frame_findings)
+    issues = findings_mod.flatten_issues(frame_findings)
+    report.save_report(markdown, frame_findings, plan, issues)
    print()
    print(markdown)

@@ -62,9 +62,27 @@ def build_system_prompt(checklist, *, allow_tools=True):
        "要求：",
        "- 只报告你**有依据**的问题，不要臆测；数据与截图冲突时以数据为准。",
        "- 按清单条目组织结论，未命中的条目可省略。",
-        "- 若该图框无任何明显问题，明确说“未发现明显问题”。",
        "- 不要复述输入数据。",
+        "",
+        "输出格式（**必须严格遵守**）：",
+        "在你完成全部取证、准备给出该图框的最终结论时，**只输出一个 JSON 对象**，"
+        "不要输出任何解释文字，也不要用 markdown 代码块包裹。结构如下：",
+        "{",
+        '  "summary": "<该图框的一句话整体结论；若未发现问题，写“未发现明显问题”>",',
+        '  "issues": [',
+        "    {",
+        '      "category": "<图层/文字/标注/几何/图面整体 之一>",',
+        '      "severity": "<high|medium|low>",',
+        '      "message": "<问题描述，简洁具体>",',
+        '      "handle": "<该问题对应的实体句柄；无法定位到具体实体时省略此字段>"',
+        "    }",
+        "  ]",
+        "}",
+        "其中 `handle` 必须是你**在取证数据或工具返回里真实见过**的句柄，不要编造；"
+        "无法确定具体实体时省略 `handle`，该问题仍会被记录。",
    ]
+    if allow_tools:
+        lines.append("（需要进一步确认时先调用工具；拿到结果后，最终再输出上述 JSON。）")
    return "\n".join(lines)


@@ -1,10 +1,37 @@
-"""阶段 4：汇总报告 + 结构化问题抽取。"""
+"""阶段 4：汇总报告 + 落盘。
+
+审查结论在阶段 3 已是结构化对象（`{summary, issues[]}`），
+因此这里**不再**需要第二次 LLM 调用来抽取结构。
+"""

 import json
 from datetime import datetime
 from pathlib import Path

 from .. import config
+from ..findings import flatten_issues
+
+_SUMMARY_SYSTEM = (
+    "你是图纸审查负责人。请把下面各图框的审查意见汇总为一份结构化的审查报告："
+    "先给整体结论，再按图框列出问题，最后给出整改建议。语言简洁、条目化。"
+)
+
+
+def format_finding(finding):
+    """把一个 findings 元素渲染成给汇总 LLM 的文本块。"""
+    lines = [f"【图框 {finding.get('frame')}（图幅 {finding.get('sheet')}）】"]
+    summary = finding.get("summary")
+    if summary:
+        lines.append(str(summary))
+    for issue in finding.get("issues") or []:
+        tag = "确定性" if issue.get("source") == "deterministic" else "LLM"
+        flag = "" if issue.get("verified", True) else "（未在证据中定位，仅供参考）"
+        handle = issue.get("handle")
+        where = f" handle={handle}" if handle else ""
+        lines.append(
+            f"- [{issue.get('severity', '?')}][{tag}] {issue.get('message', '')}{where}{flag}"
+        )
+    return "\n".join(lines)


 def summarize(ctx, findings, log=print):
@@ -12,54 +39,22 @@ def summarize(ctx, findings, log=print):
    if not findings:
        return "未识别到可审查的图框，或所有图框均无有效包围盒。"

-    report_input = "\n\n".join(
-        f"【图框 {f['frame']}（图幅 {f.get('sheet')}）】\n{f['finding']}" for f in findings
-    )
-    system = (
-        "你是图纸审查负责人。请把下面各图框的审查意见汇总为一份结构化的审查报告："
-        "先给整体结论，再按图框列出问题，最后给出整改建议。语言简洁、条目化。"
-    )
+    report_input = "\n\n".join(format_finding(f) for f in findings)
    try:
-        return ctx.llm.chat_text(system, report_input)
+        return ctx.llm.chat_text(_SUMMARY_SYSTEM, report_input)
    except Exception as exc:  # noqa: BLE001
        log(f"[汇总失败] {exc}")
        return report_input


-_EXTRACT_SYSTEM = (
-    "你是结构化信息抽取器。请把下面的图纸审查意见抽取为 JSON 数组，"
-    "每个元素形如："
-    '{"frame": <图框序号>, "handle": "<实体句柄，没有则省略>", '
-    '"category": "<图层/文字/标注/几何/图面整体>", '
-    '"severity": "<high|medium|low>", "message": "<问题描述>"}。'
-    "只输出 JSON 数组，不要输出任何解释、不要用 markdown 代码块包裹。"
-    "若某条意见无法定位到具体实体，省略 handle 字段。"
-)
-
-
-def extract_issues(ctx, findings, log=print):
-    """把自由文本的审查意见抽取为结构化问题列表（用于批注回写）。"""
-    if not findings:
-        return []
-    source = "\n\n".join(
-        f"图框 {f['frame']}：\n{f['finding']}" for f in findings
-    )
-    try:
-        text = ctx.llm.chat_text(_EXTRACT_SYSTEM, source)
-        text = text.strip()
-        if text.startswith("```"):
-            text = text.strip("`")
-            text = text.split("\n", 1)[1] if "\n" in text else text
-        data = json.loads(text)
-        if isinstance(data, list):
-            return data
-    except Exception as exc:  # noqa: BLE001
-        log(f"[结构化抽取失败] {exc}")
-    return []
-
-
 def save_report(markdown, findings, plan, issues=None, log=print):
-    """落盘 Markdown + JSON 报告，返回两个路径。"""
+    """落盘 Markdown + JSON 报告，返回两个路径。
+
+    `issues` 省略时从 findings 里拍平派生（供批注回写）。
+    """
+    if issues is None:
+        issues = flatten_issues(findings)
+
    out_dir = Path(config.REPORT_DIR)
    out_dir.mkdir(parents=True, exist_ok=True)
    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
@@ -72,7 +67,7 @@ def save_report(markdown, findings, plan, issues=None, log=print):
            {
                "generated_at": stamp,
                "findings": findings,
-                "issues": issues or [],
+                "issues": issues,
                "frames": plan.get("frames"),
            },
            ensure_ascii=False,
@@ -3,12 +3,16 @@
 流程：
  1. 用清单生成系统提示，喂入结构化证据 + 截图。
  2. LLM 若请求只读取证工具 → 执行后把观测回灌，再问（有界循环）。
-  3. LLM 不再请求工具时，其输出即为该图框的审查结论。
+  3. LLM 不再请求工具时，其输出（受约束的 JSON）即为该图框的审查结论。
+
+结论是**结构化对象** `{"summary": str, "issues": [dict], "raw": str}`，
+不再依赖第二次 LLM 调用来抽取结构（见 `findings.parse_conclusion`）。
 """

 import json

 from ..cad_tools import READ_ONLY_TOOLS, is_write_tool
+from ..findings import parse_conclusion
 from ..llm_client import LlmClient, downsample_image_b64
 from ..mcp_client import McpError, McpToolError, result_images, result_texts

@@ -59,7 +63,7 @@ def _run_readonly_tool(ctx, name, args, image_budget):


 def review_frame(ctx, evidence, system_prompt, log=print):
-    """审查单个图框，返回审查意见文本。"""
+    """审查单个图框，返回结构化结论 `{"summary", "issues", "raw"}`。"""
    payload = evidence_payload(evidence)
    user_content = [
        {
@@ -86,8 +90,9 @@ def review_frame(ctx, evidence, system_prompt, log=print):
        msg = resp.choices[0].message
        messages.append(msg)

+        # 仅在「不再请求工具」的回合解析结论；中间工具回合的 content 永不解析
        if not msg.tool_calls:
-            return msg.content or ""
+            return parse_conclusion(msg.content or "", log=log)

        for tool_call in msg.tool_calls:
            name = tool_call.function.name
@@ -101,12 +106,12 @@ def review_frame(ctx, evidence, system_prompt, log=print):
                {"role": "tool", "tool_call_id": tool_call.id, "content": content}
            )

-    # 达到回合上限：强制收口
+    # 达到回合上限：强制收口（不传 tools，保证不再请求工具，输出必为终稿 JSON）
    messages.append(
        {
            "role": "user",
-            "content": "已达到取证回合上限，请基于现有信息直接给出该图框的审查结论。",
+            "content": "已达到取证回合上限，请基于现有信息直接给出该图框的审查结论（JSON）。",
        }
    )
    resp = ctx.llm.chat(messages)
-    return resp.choices[0].message.content or ""
+    return parse_conclusion(resp.choices[0].message.content or "", log=log)