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
@@ -55,6 +55,11 @@ def _sandbox_python(ctx: ToolContext, cancel: Optional[CancelFn] = None,
 def run_command(ctx: ToolContext, args: Dict[str, Any],
                 cancel: Optional[CancelFn] = None,
                 on_output=None) -> Dict[str, Any]:
+    """Chạy một lệnh shell trong thư mục làm việc, có hạn giờ và có sandbox.
+
+    Biến môi trường được lọc và mạng bị chặn theo cấu hình an toàn — agent chạy
+    lệnh không được thừa hưởng toàn bộ môi trường của người dùng.
+    """
    from cowork_local.core.deps import network_blocked_env, run_cancellable, sandbox_env
    from cowork_local.core.sandbox_manager import ExecutionConfig, SandboxManager
    from cowork_local.security.command_risk_classifier import classify_command
@@ -96,6 +101,11 @@ def run_command(ctx: ToolContext, args: Dict[str, Any],
 def install_package(ctx: ToolContext, args: Dict[str, Any],
                     cancel: Optional[CancelFn] = None,
                     on_output=None) -> Dict[str, Any]:
+    """Cài một gói Python vào môi trường phụ trợ của lượt chạy.
+
+    Cài vào venv riêng chứ không vào Python của hệ thống — một task không được
+    phép làm hỏng môi trường của cả máy.
+    """
    from cowork_local.core.deps import pip_install

    package = str(args.get("package", "")).strip()
@@ -14,6 +14,17 @@ exactly what it always was. It exists so a caller (an application service,
 R06-T05's ``FileWorkspaceService``, or a future turn-cleanup step) can ask
 for "the output dir" / "the scratch dir" instead of hand-building the path
 and hoping the convention hasn't drifted.
+
+SEAM · dựng 2026-08-21 · chưa nối dây (F-05)
+------------------------------------------------------------
+Được nối khi: một chỗ gọi thật hỏi ``output_dir``/``scratch_dir`` thay vì tự ghép ``workdir / ".scratch"``.
+Để dormant thì sao: Quy ước ``.scratch`` vẫn nằm rải trong ``file_tools.py``
+và ``core/chat_agent.py``. File này đặt tên cho nó nhưng chưa ai dùng, nên
+quy ước vẫn trôi được.
+
+Cổng ``scripts/check_orphan_modules.py`` đếm tuổi seam từ ngày trên
+và nhắc khi quá ``SEAM_MAX_AGE_DAYS``. Đổi nội dung dòng đó thì cổng
+đọc theo — đừng sửa ngày để làm im lời nhắc.
 """
 from __future__ import annotations

@@ -51,10 +62,12 @@ class ExecutionWorkspace:

    @property
    def output_dir(self) -> Path:
+        """Thư mục agent được phép ghi kết quả — chính là gốc của phiên làm việc."""
        return self.session.workspace_root

    @property
    def scratch_dir(self) -> Path:
+        """Thư mục nháp bên trong phiên, cho file tạm không phải kết quả cuối."""
        return self.session.workspace_root / SCRATCH_DIRNAME

    def ensure_dirs(self) -> None:
@@ -36,6 +36,7 @@ def fetch_url(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:


 def jira_search(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Tìm issue trên Jira bằng JQL."""
    from cowork_local.core import jira_tool

    out = jira_tool.search(ctx.jira, str(args.get("jql", "")),
@@ -45,6 +46,7 @@ def jira_search(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:


 def jira_get_issue(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Lấy chi tiết một issue Jira theo mã."""
    from cowork_local.core import jira_tool

    out = jira_tool.get_issue(ctx.jira, str(args.get("key", "")))
@@ -52,6 +52,10 @@ def _check_python_syntax(target: Path, content: str) -> str:


 def read_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Đọc một tệp trong thư mục làm việc, cắt ở ``MAX_READ_BYTES``.
+
+    Đường dẫn được ``ctx.resolve`` kiểm trước — thoát ra ngoài thư mục là bị từ chối.
+    """
    target = ctx.resolve(str(args.get("path", "")))
    if not target.exists():
        return {"ok": False, "output": f"File not found: {args.get('path')}"}
@@ -61,6 +65,7 @@ def read_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:


 def list_dir(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Liệt kê tệp và thư mục con tại một đường dẫn (mặc định là gốc thư mục làm việc)."""
    rel = str(args.get("path", ".") or ".")
    target = ctx.resolve(rel)
    # A missing/not-yet-created path is NOT a tool failure — report it as an
@@ -79,6 +84,11 @@ def list_dir(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:


 def write_file(ctx: ToolContext, args: Dict[str, Any]) -> Dict[str, Any]:
+    """Tạo mới hoặc ghi đè một tệp, tự tạo thư mục cha.
+
+    ``ctx.flatten_writes`` ép mọi tệp ghi thẳng vào gốc — dùng cho lượt chạy mà
+    cấu trúc thư mục do agent bịa ra không có ý nghĩa gì.
+    """
    rel = str(args.get("path", ""))
    if ctx.flatten_writes:
        rel = _flatten_rel(rel)
@@ -18,11 +18,17 @@ CancelFn = Callable[[], bool]


 class ToolError(Exception):
+    """Lỗi khi chạy một tool — thông điệp được đưa thẳng cho model đọc."""
    pass


@dataclass
 class ToolContext:
+    """Bối cảnh một lượt chạy tool: thư mục làm việc và các quy tắc ghi.
+
+    ``flatten_writes`` ép mọi tệp ghi thẳng vào gốc — dùng cho Cowork, nơi cấu
+    trúc thư mục do model bịa ra không có ý nghĩa với người dùng.
+    """
    workdir: Path
    flatten_writes: bool = False  # Cowork: force every write into the workdir root
    sandbox: bool = False  # Code tab: isolate run_command/install_package into <workdir>/.venv