refactor: vá 4 hồi quy, tách 4 file chạm trần LOC, docstring lên 100%

Hồi quy đã vá ------------- F-12 Kéo–thả hoặc dán tệp vào ô chat ném NameError. R08 tách `_Input` sang `chat_input_box.py` nhưng để `_paths_from_mime()` ở lại `composer_widget.py`, nên hai hàm sự kiện Qt gọi một cái tên không tồn tại. Bốn hàm dùng chung chuyển sang `composer_mime.py` — module thứ ba là chỗ duy nhất không lặp lại được lỗi này. Đo lại: cả thả lẫn dán đều gắn 1 tệp, khớp bản trước refactor. F-01 Đổi provider thì bộ chọn model AI-Edit không làm gì. Hook cũ kiểm `folder.ai_model_combo`, thuộc tính R08-T12 đã dời sang `ai_panel.resolver`. Làm mới vô điều kiện, đúng như tab cũ: lần lấy đầu tiên hỏng thì đổi provider chính là lúc phải thử lại. F-07 Hàng chọn kỳ của Dashboard bị đẩy xuống dưới các thẻ số liệu. Hàng này lọc CẢ BA thẻ con chứ không riêng biểu đồ, nên để nó nằm dưới là bắt người dùng đọc con số trước khi thấy con số đó tính cho kỳ nào. Kèm theo: `TokenUsageCardWidget` bị bỏ sót `setContentsMargins(0,0,0,0)` mà hai thẻ con còn lại đã có, đẩy cả hàng thẻ lệch 9px. `check_layout_geometry` nay khớp TỪNG BYTE với bản trước refactor. F-11 Hai lớp khai trùng tên phương thức; Python giữ bản sau nên bản đầu là mã chết. `co4e_tab.py::showEvent` bản đầu gọi `_narrow_guard.attach()` và không bao giờ chạy. Tách file (F-09) ---------------- Bốn file chạm trần 400 dòng, mỗi lần cắt ra một trách nhiệm thật: graph_renderer.py -> graph_scene_builder.py + graph_export.py co4e_workflow_service.py -> co4e_run_history.py json_config_repository.py -> config_sections.py agents_admin_tab.py -> shared/agent_kind_visuals.py File cuối còn xoá 3 bản sao của hàm đã có trong `shared/formatters.py`, giống hệt đến từng dòng — nay định dạng thời gian và avatar không lệch nhau giữa các bảng Giám sát nữa. Docstring --------- 41,6% -> 100% (3.478/3.478 định nghĩa production), kể cả module dormant và phương thức dunder. Toàn bộ phần bổ sung viết bằng tiếng Việt; comment tiếng Anh có sẵn giữ nguyên — dịch ngược là một đợt riêng. Seam chưa nối dây (F-05) ------------------------ 9 seam mang nhãn `SEAM · dựng <ngày>` kèm hai câu: được nối khi nào, và để dormant thì hỏng gì. Ngày lấy từ lịch sử git, không phải hạn tự đặt. Gate O đọc nhãn đó và nhắc khi quá 30 ngày. 859 test xanh · 4/4 cổng CASAN · 19/24 checker khớp từng byte bản cũ. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-30 10:41:45 +09:00
parent d20306be08
commit e29a0ccdbd
264 changed files with 4593 additions and 359 deletions
@@ -0,0 +1,81 @@
+"""Xuất khung đồ thị đang xem ra file PNG — tách khỏi ``graph_renderer.py``.
+
+GraphRAG có hai khung xem: cảnh Qt 2D và trang D3 chạy trong WebEngine. Hai
+khung ấy chụp ảnh theo hai cách hoàn toàn khác nhau (``QWidget.grab()`` so
+với một lượt gọi JavaScript trả về data URL), nên chỗ này gom cả hai lại sau
+một hàm duy nhất và tự chọn đường đi.
+"""
+from __future__ import annotations
+
+import base64
+from typing import Callable, Optional
+
+from PySide6.QtWidgets import QFileDialog, QWidget
+
+from cowork_local.i18n import tr
+
+#: Bên gọi truyền vào để hiện kết quả trên thanh trạng thái.
+StatusFn = Callable[[str], None]
+
+
+def ask_export_path(parent: QWidget) -> str:
+    """Hỏi người dùng nơi lưu ảnh; trả về '' nếu họ bấm Huỷ."""
+    path, _ = QFileDialog.getSaveFileName(
+        parent, tr("structure.export_title"), "structure-graph.png", "PNG (*.png)")
+    return path or ""
+
+
+def export_widget_grab(widget: QWidget, path: str, status: StatusFn) -> None:
+    """Chụp thẳng widget đang hiện ra PNG.
+
+    Đây cũng là đường lui khi xuất từ D3 thất bại: chụp widget luôn cho ra
+    một tấm ảnh, dù không sắc nét bằng bản vẽ vector của D3.
+    """
+    if widget.grab().save(path, "PNG"):
+        status(tr("structure.export_done", path=path))
+    else:
+        status(tr("structure.export_failed", err="grab() returned no image"))
+
+
+def export_d3_png(web, path: str, fallback: QWidget, status: StatusFn) -> None:
+    """Xuất PNG từ trang D3 bằng cách nhờ chính trang đó vẽ ra data URL.
+
+    ``runJavaScript`` chạy bất đồng bộ nên kết quả về trong hàm gọi lại. Mọi
+    đường hỏng — trang chưa nạp xong, ``window.exportPng`` không tồn tại,
+    chuỗi trả về không phải data URL — đều quay sang chụp widget, để người
+    dùng bấm Xuất vẫn luôn nhận được một file thay vì im lặng không có gì.
+    """
+    def on_result(data_url) -> None:
+        """Nhận data URL từ trang D3 và ghi ra file; hỏng ở bất cứ đâu thì quay sang
+        chụp widget.
+        """
+        if not isinstance(data_url, str) or "," not in data_url:
+            export_widget_grab(fallback, path, status)
+            return
+        try:
+            with open(path, "wb") as f:
+                f.write(base64.b64decode(data_url.split(",", 1)[1]))
+            status(tr("structure.export_done", path=path))
+        except (OSError, ValueError) as exc:
+            status(tr("structure.export_failed", err=str(exc)))
+
+    web.page().runJavaScript("window.exportPng ? window.exportPng() : ''", on_result)
+
+
+def export_png(parent: QWidget, showing: QWidget, web: Optional[object],
+               is_web_visible: bool, status: StatusFn) -> None:
+    """Hỏi đường dẫn rồi xuất khung ĐANG hiện — D3 hay cảnh Qt tuỳ tab đang mở.
+
+    Chỉ dùng đường D3 khi trang D3 thật sự đang hiển thị; đang xem cảnh Qt mà
+    lại chụp D3 thì ảnh ra không khớp với thứ người dùng nhìn thấy.
+    """
+    path = ask_export_path(parent)
+    if not path:
+        return
+    if web is not None and is_web_visible:
+        export_d3_png(web, path, showing, status)
+    else:
+        export_widget_grab(showing, path, status)
+
+
+__all__ = ["export_png", "export_d3_png", "export_widget_grab", "ask_export_path"]
@@ -22,7 +22,15 @@ from cowork_local.i18n import tr


 class GraphMessagesView:
+    """Tab "Tin nhắn" của GraphRAG: cây hội thoại gom theo ngày, bấm vào xem JSON.
+
+    Một helper thuần (không phải widget) do ``GraphRenderer`` sở hữu; nó tự dựng
+    cây và đưa vào stack dùng chung của chủ sở hữu.
+    """
    def __init__(self, owner) -> None:
+        """Dựng cây tin nhắn và đưa vào stack dùng chung của chủ sở hữu — helper thuần,
+        không phải widget độc lập.
+        """
        self._owner = owner
        self.widget = QTreeWidget()
        self.widget.setHeaderHidden(True)
@@ -76,6 +84,9 @@ class GraphMessagesView:
            day_item.setExpanded(True)

    def _show_msg_json(self, item, _col: int = 0) -> None:
+        """Bấm một hội thoại trong cây: hiện toàn bộ nội dung của nó dưới dạng JSON đã
+        thoát HTML ở khung chi tiết.
+        """
        import html
        import json

@@ -41,6 +41,11 @@ class GraphQaWidget(QWidget):
    collapse_changed = Signal(bool)   # so the shell can resize its own splitter

    def __init__(self, ctx, renderer, parent=None):
+        """Panel Hỏi đáp bên phải màn GraphRAG.
+
+        Có cache trích xuất vì cùng một node hay bị hỏi lại nhiều lần trong một
+        phiên, mà mỗi lần trích lại phải đọc tệp.
+        """
        super().__init__(parent)
        self.ctx = ctx
        self._renderer = renderer
@@ -97,6 +102,7 @@ class GraphQaWidget(QWidget):
        self.retranslate()

    def retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho tiêu đề, ô hỏi và tooltip."""
        self._collapse_btn.setToolTip(tr("structure.collapse_agent_tooltip"))
        self._label.setText(tr("structure.agent_header"))
        self.ask_edit.setPlaceholderText(tr("structure.ask_placeholder"))
@@ -107,25 +113,30 @@ class GraphQaWidget(QWidget):

    # ---- collapse ------------------------------------------------------------- #
    def _set_collapsed(self, collapsed: bool) -> None:
+        """Gập/mở panel hỏi-đáp và báo ra ngoài để vỏ chỉnh lại splitter."""
        self._panel.setVisible(not collapsed)
        self._strip.setVisible(collapsed)
        self.collapse_changed.emit(collapsed)

    # ---- reacting to the renderer ----------------------------------------------- #
    def _on_node_selected(self, data) -> None:
+        """Chọn một node trên đồ thị: hiện chi tiết của node đó ở khung dưới."""
        self.detail.setPlainText(f"[{data.kind.upper()}] {data.label}\n\n{data.detail}")
        self._detail_mode = "node"

    def _show_raw_json(self, html_text: str) -> None:
+        """Hiện JSON thô của một hội thoại được chọn ở tab Tin nhắn."""
        self.detail.setHtml(html_text)

    def _preserve_answer(self) -> None:
+        """Vẽ lại câu trả lời AI sau khi khung chi tiết bị dùng cho việc khác — nếu"""
        if self._detail_mode == "answer" and self._answer.strip():
            self._render_answer()

    # ---- Q&A -------------------------------------------------------------------- #
    @staticmethod
    def _graph_context(graph) -> str:
+        """Tóm tắt đồ thị thành văn bản gọn để nhét vào prompt: gom node theo loại,"""
        from collections import defaultdict
        by_kind = defaultdict(list)
        for n in graph.nodes:
@@ -143,6 +154,7 @@ class GraphQaWidget(QWidget):
        return "\n".join(lines)[:7000]

    def _matched_sources(self, text: str):
+        """Các node có tên xuất hiện trong câu trả lời — dùng để gắn link nguồn kiểm"""
        graph = self._renderer.graph
        if graph is None or not text:
            return []
@@ -176,6 +188,7 @@ class GraphQaWidget(QWidget):
        return text

    def _render_answer(self) -> None:
+        """Vẽ câu trả lời dạng markdown kèm danh sách nguồn bấm mở được."""
        text = self._answer
        sources = self._matched_sources(text)
        if sources:
@@ -189,6 +202,9 @@ class GraphQaWidget(QWidget):
        self.detail.setMarkdown(text)

    def _on_detail_link(self, url: QUrl) -> None:
+        """Bấm một link trong khung chi tiết: là tệp thì mở tệp, còn lại mở bằng trình
+        duyệt.
+        """
        if url.isLocalFile():
            p = url.toLocalFile()
            if Path(p).is_file():
@@ -197,6 +213,7 @@ class GraphQaWidget(QWidget):
                open_folder(p)

    def _ask(self) -> None:
+        """Gửi câu hỏi về đồ thị tới model, chạy ở luồng nền."""
        question = self.ask_edit.text().strip()
        if not question:
            return
@@ -225,6 +242,7 @@ class GraphQaWidget(QWidget):
        selected_context = self._selection_context(selected_nodes, graph)

        def job(worker: AgentWorker):
+            """Chạy nền: ghép ngữ cảnh đồ thị + nội dung tệp đã trích rồi gọi model."""
            provider = self.ctx.build_active_provider()
            system = self._system_prompt(skill_prefix, active_project_id)
            user_content = f"Graph context:\n{context}"
@@ -261,6 +279,7 @@ class GraphQaWidget(QWidget):

    @staticmethod
    def _selection_context(selected_nodes, graph) -> str:
+        """Phần ngữ cảnh thêm cho các node người dùng đang chọn — câu hỏi "cái này là"""
        if not selected_nodes:
            return ""
        node_lines = []
@@ -284,6 +303,7 @@ class GraphQaWidget(QWidget):

    @staticmethod
    def _system_prompt(skill_prefix: str, active_project_id: str) -> str:
+        """Prompt hệ thống cho khung hỏi-đáp."""
        system = ("You answer questions about a code/document knowledge graph. Use the provided "
                  "graph context AND the extracted file contents to retrieve, synthesize and "
                  "explain the answer. Be concise. Answer ONLY from what is provided (graph "
@@ -321,6 +341,7 @@ class GraphQaWidget(QWidget):
        return system

    def _on_ask_event(self, ev: dict) -> None:
+        """Nhận từng mẩu trả lời đang phát dần và vẽ dần vào khung chi tiết."""
        if ev.get("type") == "text":
            if self._answer == "":
                self.detail.clear()
@@ -330,6 +351,7 @@ class GraphQaWidget(QWidget):
    def _on_ask_done(self, result: dict) -> None:
        # Keep the (temporary) extracted content so repeated questions reuse
        # it without re-extracting — dropped when leaving the tab.
+        """Trả lời xong: giữ lại nội dung tệp đã trích để câu hỏi sau không phải trích"""
        if isinstance(result, dict):
            self._extract_cache.update(result.get("extracted", {}) or {})
        self._render_answer()
@@ -352,6 +374,7 @@ class GraphQaWidget(QWidget):
        return out

    def _extract_tmp_dir(self) -> Path:
+        """Thư mục tạm chứa nội dung tệp đã trích, tạo lười ở lần cần đầu tiên."""
        if self._extract_dir is None:
            import tempfile
            from cowork_local.config import CONFIG_DIR
@@ -13,7 +13,6 @@ AI-edit panel either.
 """
 from __future__ import annotations

-import math
 from pathlib import Path
 from typing import List, Optional

@@ -26,7 +25,9 @@ from PySide6.QtWidgets import (

 from cowork_local.core.worker import AgentWorker
 from cowork_local.i18n import on_language_changed, tr
+from cowork_local.presentation.graph import graph_export
 from cowork_local.presentation.graph.graph_messages_view import GraphMessagesView
+from cowork_local.presentation.graph.graph_scene_builder import build_scene
 from cowork_local.presentation.graph.graph_scene_items import _Bridge, _Edge, _GraphView, _Node
 from cowork_local.presentation.shared import HAS_WEB_ENGINE
 from cowork_local.state import AppContext
@@ -35,6 +36,7 @@ from cowork_local.ui.icons import icon


 class GraphRenderer(QWidget):
+    """Nửa "đồ thị" của màn GraphRAG: thanh công cụ, khung xem và vòng đời quét."""
    status_message = Signal(str)
    node_selected = Signal(object)   # a node's .data, whenever the scene selection changes
    graph_rendered = Signal()        # a scan just finished rendering (fresh OR re-fit)
@@ -42,6 +44,12 @@ class GraphRenderer(QWidget):
    project_changed = Signal()       # a DIFFERENT project was selected (or cleared)

    def __init__(self, ctx: AppContext):
+        """Dựng thanh công cụ, khung xem 2D và chỗ chờ cho khung D3.
+
+        Khung D3 KHÔNG được dựng ở đây: ``QWebEngineView`` mất vài trăm mili giây
+        để khởi tạo, mà phần lớn người dùng mở màn này chỉ để xem cảnh Qt. Nó được
+        dựng muộn trong :meth:`_ensure_web`.
+        """
        super().__init__()
        self.ctx = ctx
        self._worker: Optional[AgentWorker] = None
@@ -118,6 +126,7 @@ class GraphRenderer(QWidget):
        on_language_changed(self._retranslate)

    def _retranslate(self) -> None:
+        """Áp lại chữ theo ngôn ngữ đang chọn cho thanh công cụ và tên tab."""
        self.path_edit.setPlaceholderText(tr("structure.path_placeholder"))
        self._pick_btn.setText(tr("structure.browse"))
        self._scan_btn.setText(tr("structure.scan"))
@@ -131,17 +140,23 @@ class GraphRenderer(QWidget):
    # ---- public read API for GraphQaWidget ----------------------------------- #
    @property
    def graph(self):
+        """Đồ thị đã quét gần nhất; ``None`` nếu chưa quét lần nào."""
        return self._graph

    @property
    def active_project_id(self) -> str:
+        """Id dự án đang chọn trong bộ chọn; '' nếu chưa chọn."""
        return self._active_project_id

    def selected_node_data(self) -> list:
+        """Dữ liệu của các node đang được chọn trên cảnh — panel Hỏi đáp đọc cái này
+        để biết người dùng đang hỏi về cái gì.
+        """
        return [item.data for item in self.scene.selectedItems() if isinstance(item, _Node)]

    # ---- project sandbox lock ------------------------------------------------- #
    def _refresh_project_combo(self) -> None:
+        """Nạp lại danh sách project vào bộ chọn, giữ nguyên project đang chọn."""
        from cowork_local.core.projects import list_projects

        keep = self._active_project_id
@@ -157,6 +172,7 @@ class GraphRenderer(QWidget):
        self.project_combo.blockSignals(False)

    def set_project(self, project_id: str) -> None:
+        """Khoá phạm vi quét vào một project (chuỗi rỗng là bỏ khoá)."""
        pid = project_id or ""
        self._refresh_project_combo()
        target = self.project_combo.findData(pid)
@@ -168,6 +184,7 @@ class GraphRenderer(QWidget):
            self.project_combo.setCurrentIndex(target)

    def _on_project_changed(self, _idx: int) -> None:
+        """Áp trạng thái khoá: đường dẫn chuyển sang chỉ đọc và trỏ vào thư mục"""
        from cowork_local.core.projects import load_project

        pid = self.project_combo.currentData() or ""
@@ -188,11 +205,13 @@ class GraphRenderer(QWidget):

    # ---- helpers ---------------------------------------------------------------- #
    def _pick(self) -> None:
+        """Mở hộp thoại chọn thư mục gốc để quét."""
        chosen = QFileDialog.getExistingDirectory(self, tr("structure.pick_folder_title"), self.path_edit.text())
        if chosen:
            self.path_edit.setText(chosen)

    def schedule_rescan(self, path: str = "") -> None:
+        """Hẹn quét lại sau khi có thay đổi trên đĩa."""
        if self._graph is None:
            self._needs_scan = True
            return
@@ -200,6 +219,7 @@ class GraphRenderer(QWidget):

    # ---- Messages (by day, as JSON) — see graph_messages_view.py --------------- #
    def _on_view_tab(self, index: int) -> None:
+        """Đổi giữa tab đồ thị và tab Tin nhắn."""
        self._messages.on_view_tab(index)

    def _toggle_messages(self) -> None:
@@ -217,6 +237,11 @@ class GraphRenderer(QWidget):
            self._scan()

    def _ensure_web(self) -> None:
+        """Dựng khung D3 nếu máy có WebEngine và chưa dựng.
+
+        Gọi được nhiều lần — lần thứ hai trở đi không làm gì. Máy không có
+        WebEngine thì bỏ qua im lặng và người dùng ở lại với cảnh Qt.
+        """
        if self.web is not None or not HAS_WEB_ENGINE:
            return
        from PySide6.QtWebChannel import QWebChannel
@@ -235,6 +260,7 @@ class GraphRenderer(QWidget):
            self._render_d3()

    def auto_scan_and_fit(self) -> None:
+        """Vào màn GraphRAG: hiện đồ thị, chỉ quét lại khi thật sự cần."""
        self._ensure_web()
        if not self.path_edit.text().strip():
            return
@@ -251,6 +277,11 @@ class GraphRenderer(QWidget):

    # ---- scan --------------------------------------------------------------------- #
    def _scan(self) -> None:
+        """Quét thư mục gốc ở luồng nền rồi vẽ kết quả.
+
+        Mỗi lượt quét mang một số thứ tự ``_scan_seq``; kết quả về mà số không còn
+        khớp thì bị bỏ, để lượt quét cũ không đè lên lượt mới.
+        """
        path = self.path_edit.text().strip() or str(Path.cwd())
        mode = "files"
        use_cmem = bool(self.ctx.config.codebase_memory.get("enabled"))
@@ -263,6 +294,11 @@ class GraphRenderer(QWidget):
        self.status_message.emit(tr("structure.scanning"))

        def job(worker: AgentWorker):
+            """Chạy nền: dựng đồ thị từ thư mục rồi tính toạ độ.
+
+            Ưu tiên đọc từ codebase-memory nếu có sẵn — nhanh hơn nhiều so với quét lại
+            cả cây thư mục; không có thì quét trực tiếp.
+            """
            from cowork_local.core.structure_graph import (
                build_from_codebase_memory, build_from_directory, force_layout,
            )
@@ -283,6 +319,12 @@ class GraphRenderer(QWidget):
        w.start()

    def _render(self, result: dict) -> None:
+        """Vẽ kết quả quét ra khung Qt 2D (và ra D3 nếu đang bật).
+
+        Lượt quét cũ về muộn thì bỏ: ``seq`` của nó không còn khớp
+        ``_scan_seq``. Không chặn ở đây thì người dùng đổi dự án nhanh sẽ thấy
+        đồ thị của dự án TRƯỚC đè lên dự án đang chọn.
+        """
        if result.get("seq") is not None and result["seq"] != self._scan_seq:
            return
        graph = result.get("graph")
@@ -291,36 +333,8 @@ class GraphRenderer(QWidget):
            return
        self._graph = graph

-        self.scene.clear()
-        self.scene.setBackgroundBrush(QColor(current_palette().bg))
-        self._node_items = []
-        self._edge_items = []
-        degree = {n.id: 0 for n in graph.nodes}
-        for e in graph.edges:
-            if e.source in degree:
-                degree[e.source] += 1
-            if e.target in degree:
-                degree[e.target] += 1
-        items = {}
-        sx = sy = 0.0
-        for node in graph.nodes:
-            radius = int(8 + min(20, 2.2 * math.sqrt(degree.get(node.id, 0))))
-            item = _Node(node, radius)
-            x, y = pos.get(node.id, (0, 0))
-            item.setPos(x, y)
-            self.scene.addItem(item)
-            items[node.id] = item
-            self._node_items.append(item)
-            sx += x
-            sy += y
-        for edge in graph.edges:
-            a, b = items.get(edge.source), items.get(edge.target)
-            if a and b:
-                e = _Edge(a, b, getattr(edge, "type", ""))
-                self.scene.addItem(e)
-                self._edge_items.append(e)
-        n = max(1, len(self._node_items))
-        self._centroid = QPointF(sx / n, sy / n)
+        self._node_items, self._edge_items, self._centroid = build_scene(
+            self.scene, graph, pos, current_palette().bg)
        self._fit()

        if self.web is not None:
@@ -332,6 +346,9 @@ class GraphRenderer(QWidget):
        self.graph_rendered.emit()

    def _render_d3(self) -> None:
+        """Nạp lại trang D3 từ đồ thị hiện có. Lỗi dựng HTML chỉ báo lên thanh trạng
+        thái chứ không ném ra — cảnh Qt vẫn xem được.
+        """
        if self.web is None or self._graph is None:
            return
        from cowork_local.core.d3_graph import build_html
@@ -342,12 +359,14 @@ class GraphRenderer(QWidget):

    # ---- native interactions ------------------------------------------------------- #
    def _on_selection(self) -> None:
+        """Chọn một node trên cảnh thì báo cho panel Hỏi đáp biết."""
        for item in self.scene.selectedItems():
            if isinstance(item, _Node):
                self.node_selected.emit(item.data)
                return

    def _fit(self) -> None:
+        """Canh toàn bộ đồ thị vừa khung nhìn."""
        if self.web is not None and self._stack.currentWidget() is self.web:
            self.web.page().runJavaScript("window.fitGraph && window.fitGraph();")
            return
@@ -356,36 +375,17 @@ class GraphRenderer(QWidget):
            self.view.fitInView(rect.adjusted(-40, -40, 40, 40), Qt.KeepAspectRatio)

    def _export(self) -> None:
-        path, _ = QFileDialog.getSaveFileName(
-            self, tr("structure.export_title"), "structure-graph.png", "PNG (*.png)")
-        if not path:
-            return
-        showing_d3 = (self.web is not None and self._stack.currentWidget() is self.web)
-        if showing_d3:
-            self._export_d3_png(path)
-        else:
-            self._export_widget_grab(path)
+        """Xuất khung đang xem ra PNG.

-    def _export_d3_png(self, path: str) -> None:
-        def on_result(data_url) -> None:
-            if not isinstance(data_url, str) or "," not in data_url:
-                self._export_widget_grab(path)
-                return
-            import base64
-            try:
-                with open(path, "wb") as f:
-                    f.write(base64.b64decode(data_url.split(",", 1)[1]))
-                self.status_message.emit(tr("structure.export_done", path=path))
-            except (OSError, ValueError) as exc:
-                self.status_message.emit(tr("structure.export_failed", err=str(exc)))
-        self.web.page().runJavaScript("window.exportPng ? window.exportPng() : ''", on_result)
-
-    def _export_widget_grab(self, path: str) -> None:
-        ok = self._stack.currentWidget().grab().save(path, "PNG")
-        if ok:
-            self.status_message.emit(tr("structure.export_done", path=path))
-        else:
-            self.status_message.emit(tr("structure.export_failed", err="grab() returned no image"))
+        Cách chụp tuỳ khung nào đang hiện — xem ``graph_export.py``.
+        """
+        graph_export.export_png(
+            parent=self,
+            showing=self._stack.currentWidget(),
+            web=self.web,
+            is_web_visible=self._stack.currentWidget() is self.web,
+            status=self.status_message.emit,
+        )


 __all__ = ["GraphRenderer"]
@@ -0,0 +1,95 @@
+"""Dựng các item Qt cho khung đồ thị 2D — tách khỏi ``graph_renderer.py``.
+
+Đây là phần "biến dữ liệu thành hình" của GraphRAG: nhận một đồ thị đã quét
+cùng bảng toạ độ, đổ ``_Node``/``_Edge`` vào ``QGraphicsScene`` rồi trả lại
+danh sách item và trọng tâm cho bên gọi.
+
+Tách ra vì nó không cần biết gì về widget: không đọc thuộc tính nào của
+``GraphRenderer``, không phát tín hiệu, không chạm cấu hình. Nhờ thế mà thử
+được bằng một ``QGraphicsScene`` trần, và ``graph_renderer.py`` bớt đi phần
+duy nhất trong nó có tính toán hình học thật sự.
+"""
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Tuple
+
+from PySide6.QtCore import QPointF
+from PySide6.QtGui import QColor
+from PySide6.QtWidgets import QGraphicsScene
+
+from cowork_local.presentation.graph.graph_scene_items import _Edge, _Node
+
+
+def node_degrees(graph) -> Dict[str, int]:
+    """Số cạnh chạm vào từng node.
+
+    Dùng để định cỡ node: node càng nhiều liên kết thì vẽ càng to, nên mắt
+    người nhìn vào là thấy ngay đâu là đầu mối của cả đồ thị.
+    """
+    degree = {n.id: 0 for n in graph.nodes}
+    for edge in graph.edges:
+        if edge.source in degree:
+            degree[edge.source] += 1
+        if edge.target in degree:
+            degree[edge.target] += 1
+    return degree
+
+
+def node_radius(degree: int) -> int:
+    """Bán kính vẽ của một node theo bậc của nó.
+
+    Lấy căn bậc hai chứ không lấy tuyến tính: bậc tăng gấp bốn thì bán kính
+    mới gấp đôi, nhờ vậy DIỆN TÍCH mới tỉ lệ với bậc — đó mới là thứ mắt
+    người thật sự so sánh. Chặn trên ở 28 để một node trung tâm không nuốt
+    mất phần còn lại của đồ thị.
+    """
+    return int(8 + min(20, 2.2 * math.sqrt(degree)))
+
+
+def build_scene(
+    scene: QGraphicsScene, graph, pos: Dict[str, Tuple[float, float]], bg: str
+) -> Tuple[List[_Node], List[_Edge], QPointF]:
+    """Xoá sạch ``scene`` rồi dựng lại toàn bộ node và cạnh của ``graph``.
+
+    ``pos`` là toạ độ đã tính sẵn ở luồng nền (``{node_id: (x, y)}``); node
+    không có trong đó rơi về gốc toạ độ thay vì bị bỏ, để không im lặng đánh
+    mất dữ liệu.
+
+    Cạnh chỉ được vẽ khi CẢ HAI đầu đều có item — đồ thị bị cắt bớt
+    (``truncated``) hay dữ liệu lệch có thể trỏ tới node không tồn tại, và
+    một ``_Edge`` treo lơ lửng sẽ làm hỏng cả phép tính khung nhìn.
+
+    Trả về ``(danh sách node, danh sách cạnh, trọng tâm)``. Trọng tâm là
+    trung bình cộng toạ độ các node, dùng làm tâm khi thu phóng.
+    """
+    scene.clear()
+    scene.setBackgroundBrush(QColor(bg))
+
+    degree = node_degrees(graph)
+    items: Dict[str, _Node] = {}
+    node_items: List[_Node] = []
+    sx = sy = 0.0
+    for node in graph.nodes:
+        item = _Node(node, node_radius(degree.get(node.id, 0)))
+        x, y = pos.get(node.id, (0, 0))
+        item.setPos(x, y)
+        scene.addItem(item)
+        items[node.id] = item
+        node_items.append(item)
+        sx += x
+        sy += y
+
+    edge_items: List[_Edge] = []
+    for edge in graph.edges:
+        a, b = items.get(edge.source), items.get(edge.target)
+        if a and b:
+            e = _Edge(a, b, getattr(edge, "type", ""))
+            scene.addItem(e)
+            edge_items.append(e)
+
+    n = max(1, len(node_items))
+    return node_items, edge_items, QPointF(sx / n, sy / n)
+
+
+__all__ = ["build_scene", "node_degrees", "node_radius"]
@@ -22,12 +22,25 @@ class _Bridge(QObject):

    @Slot(str)
    def openPath(self, path: str) -> None:  # noqa: N802 - JS-facing name
+        """Cầu nối JavaScript → Python: Shift+click một node trên khung D3 thì mở thư
+        mục hoặc link lưu trữ của nó.
+        """
        if path:
            open_location(path)


 class _Edge(QGraphicsLineItem):
+    """Một cạnh trên khung Qt 2D, kèm nhãn tên quan hệ ở điểm giữa.
+
+    Màu cạnh lấy theo LOẠI quan hệ (contains/defines/method…) để nhìn đồ thị
+    là biết mỗi liên kết nghĩa là gì; cạnh không có loại thì mượn màu nhạt của
+    node nguồn. Nằm ở z=-1, tức dưới mọi node.
+    """
    def __init__(self, a: "_Node", b: "_Node", type_: str = ""):
+        """Một cạnh trên khung đồ thị, tô màu theo LOẠI quan hệ (chứa/định nghĩa/phương
+        thức…) để nhìn là biết liên kết ấy nghĩa gì; cạnh không có loại thì lấy màu
+        của node nguồn.
+        """
        super().__init__()
        self.a, self.b = a, b
        self.type = type_
@@ -54,6 +67,7 @@ class _Edge(QGraphicsLineItem):
        self.adjust()

    def adjust(self) -> None:
+        """Vẽ lại đường thẳng theo vị trí hai node và đặt nhãn vào đúng điểm giữa."""
        pa, pb = self.a.scenePos(), self.b.scenePos()
        self.setLine(pa.x(), pa.y(), pb.x(), pb.y())
        if self._label is not None:
@@ -63,7 +77,18 @@ class _Edge(QGraphicsLineItem):


 class _Node(QGraphicsEllipseItem):
+    """Một node hình tròn; bán kính do chỗ gọi tính theo bậc của node.
+
+    ``NODE_KIND_COLORS`` là mã màu theo LOẠI dữ liệu (mỗi loại một sắc), cố ý
+    giữ nguyên ở cả theme sáng lẫn tối để một loại luôn là một màu. Chỉ phần
+    khung viền/chữ mới đi theo theme.
+    """
    def __init__(self, data, radius: int):
+        """Một node hình tròn, bán kính theo số liên kết.
+
+        Màu theo loại node là mã hoá dữ liệu chứ không phải trang trí, nên cố định
+        qua mọi giao diện — cùng một loại luôn cùng một màu.
+        """
        super().__init__(-radius, -radius, 2 * radius, 2 * radius)
        self.data = data
        self.edges = []
@@ -85,6 +110,7 @@ class _Node(QGraphicsEllipseItem):
        label.setPos(radius + 3, -8)

    def itemChange(self, change, value):  # noqa: N802
+        """Kéo node thì kéo theo mọi cạnh dính vào nó."""
        if change == QGraphicsEllipseItem.ItemPositionHasChanged:
            for edge in self.edges:
                edge.adjust()
@@ -92,17 +118,23 @@ class _Node(QGraphicsEllipseItem):


 class _GraphView(QGraphicsView):
+    """Khung xem đồ thị Qt 2D: lăn chuột để phóng, kéo nền để dời khung."""
    def __init__(self, scene):
+        """Khung xem đồ thị: kéo bằng chuột giữa để di chuyển, không kéo chọn vùng."""
        super().__init__(scene)
        self.setDragMode(QGraphicsView.NoDrag)
        self._panning = False
        self._pan_start = QPointF()

    def wheelEvent(self, e):  # noqa: N802
+        """Lăn chuột phóng to/thu nhỏ một nấc 1,15 lần."""
        self.scale(1.15 if e.angleDelta().y() > 0 else 1 / 1.15,
                   1.15 if e.angleDelta().y() > 0 else 1 / 1.15)

    def mousePressEvent(self, e):  # noqa: N802
+        """Nhấn trái vào chỗ TRỐNG thì bắt đầu kéo khung; nhấn trúng node thì để Qt
+        xử lý như chọn/kéo node bình thường.
+        """
        if e.button() == Qt.LeftButton and self.itemAt(e.pos()) is None:
            self._panning = True
            self._pan_start = e.position()
@@ -112,6 +144,7 @@ class _GraphView(QGraphicsView):
        super().mousePressEvent(e)

    def mouseMoveEvent(self, e):  # noqa: N802
+        """Đang kéo khung: dời hai thanh cuộn ngược chiều con trỏ."""
        if self._panning:
            delta = e.position() - self._pan_start
            self._pan_start = e.position()
@@ -122,6 +155,7 @@ class _GraphView(QGraphicsView):
        super().mouseMoveEvent(e)

    def mouseReleaseEvent(self, e):  # noqa: N802
+        """Thả chuột: kết thúc kéo khung, trả con trỏ về bình thường."""
        if self._panning:
            self._panning = False
            self.setCursor(Qt.ArrowCursor)
@@ -21,9 +21,18 @@ _COLLAPSED_SIZES_HINT = (840, 320)   # matches the original single-class default


 class StructureGraphView(QWidget):
+    """Màn GraphRAG: ghép khung đồ thị (:class:`GraphRenderer`) và khung hỏi-đáp
+    (:class:`GraphQaWidget`) vào một splitter.
+
+    Vỏ này chỉ lắp ráp và chuyển tiếp bốn phương thức mà ``app.py`` và
+    ``ui/workspace_tab.py`` gọi tới; toàn bộ phần việc thật nằm ở hai widget con.
+    """
    status_message = Signal(str)

    def __init__(self, ctx: AppContext):
+        """Ghép hai nửa của màn GraphRAG: bên trái là đồ thị, bên phải là panel Hỏi
+        đáp.
+        """
        super().__init__()
        self.ctx = ctx

@@ -44,10 +53,14 @@ class StructureGraphView(QWidget):
        on_language_changed(self._retranslate)

    def _retranslate(self) -> None:
+        """Chuyển lệnh dịch lại xuống cho cả hai widget con."""
        self.renderer._retranslate()
        self.qa.retranslate()

    def _on_qa_collapse_changed(self, collapsed: bool) -> None:
+        """Gập/mở khung hỏi-đáp: gập thì thu về đúng bề rộng dải nắm, mở thì trả
+        splitter về tỉ lệ mặc định.
+        """
        strip_w = CollapseStrip.WIDTH + 2
        if collapsed:
            self.qa.setMaximumWidth(strip_w)
@@ -60,19 +73,24 @@ class StructureGraphView(QWidget):

    # ---- public API (app.py / ui/workspace_tab.py) --------------------------- #
    def schedule_rescan(self, path: str = "") -> None:
+        """Hẹn quét lại đồ thị sau khi thư mục có thay đổi."""
        self.renderer.schedule_rescan(path)

    def auto_scan_and_fit(self) -> None:
+        """Vào màn GraphRAG: hiện đồ thị, chỉ quét lại khi thật sự cần."""
        self.renderer.auto_scan_and_fit()

    def set_project(self, project_id: str) -> None:
+        """Khoá phạm vi quét vào một project (chuỗi rỗng là bỏ khoá)."""
        self.renderer.set_project(project_id)

    def prewarm(self) -> None:
+        """Dựng sẵn khung đồ thị trước khi người dùng bấm vào, để lần mở đầu không giật."""
        self.renderer.prewarm()

    def hideEvent(self, e):  # noqa: N802
        # Leaving the GraphRAG tab → drop the temporary extracted info.
+        """Rời màn GraphRAG thì xoá phần trích xuất tạm của khung hỏi-đáp."""
        self.qa.clear_extracts()
        super().hideEvent(e)