codebuff-agent 2.1.74__py3-none-any.whl

jupyter_ext/agent/langchain_tools.py

@@ -0,0 +1,2673 @@
+"""
+Jupyter 노트북 조작을 위한 LangChain 호환 도구 모음.
+
+NotebookContextManager를 래핑하여 LangChain Agent에서 사용 가능한
+LangChain BaseTool 인터페이스를 제공합니다.
+"""
+
+from __future__ import annotations
+
+import ast
+import fnmatch
+import json
+import os
+import re
+import subprocess
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Any, Optional
+
+from codebuff_core.directory_policy import SEARCH_EXCLUDED_DIRS
+from langchain_core.tools import BaseTool, tool
+
+from ..tools.context import NotebookContextManager
+from .codex_autofix import RUFF_FIX, ruff_command
+
+# enterprise_tables 접근 제한 키워드 (모듈 레벨 1회 컴파일)
+_ENTERPRISE_KEYWORDS = re.compile(
+    r"전사|처리계|정보계|채널계|엔터프라이즈|enterprise|레거시|idc"
+    r"|adw|bcv|cms|dpweb|m포인트몰|빅쿼리|bq|bigquery"
+    r"|원천|dw|메타샵|meta샵|meta#",
+    re.IGNORECASE,
+)
+
+# 사용자 원본 메시지와 EDA 제한은 요청마다 달라진다. 모듈 전역 문자열이면 동시에
+# 실행되는 Chat/Q&A가 서로의 검색 범위를 바꾸므로 비동기 컨텍스트에 격리한다.
+_last_user_message: ContextVar[str] = ContextVar("last_user_message", default="")
+_eda_only_bdp: ContextVar[bool] = ContextVar("eda_only_bdp", default=False)
+
+
+def set_last_user_message(msg: str) -> None:
+    """사용자 원본 메시지 저장 (rag_chat_agent에서 호출)."""
+    _last_user_message.set(msg)
+
+
+def set_eda_only_bdp(enabled: bool) -> None:
+    """EDA 모드: enterprise_tables → bdp_tables 강제 치환."""
+    _eda_only_bdp.set(enabled)
+
+
+def create_jupyter_cell_tool(context: NotebookContextManager) -> BaseTool:
+    """
+    Jupyter 셀 조작용 LangChain 도구를 생성합니다.
+
+    Args:
+        context: 노트북 상태 접근을 위한 NotebookContextManager
+
+    Returns:
+        셀 조작용 LangChain BaseTool
+    """
+
+    @tool
+    def jupyter_cell(
+        code: Optional[str] = None,
+        description: Optional[str] = None,
+        execution_result: Optional[dict] = None,
+    ) -> str:
+        """Jupyter 노트북에 코드 셀을 생성하고 실행합니다.
+
+        Args:
+            code: 실행할 Python 코드
+            description: 코드 설명 (선택)
+            execution_result: 프론트엔드에서 전달된 실행 결과 (HITL edit decision 경유)
+
+        Returns:
+            연산 결과가 담긴 JSON 문자열
+        """
+        # 마크다운 펜스 정리
+        cleaned_code = (code or "").strip()
+        if cleaned_code.startswith("```python"):
+            cleaned_code = cleaned_code[9:]
+        elif cleaned_code.startswith("```"):
+            cleaned_code = cleaned_code[3:]
+        if cleaned_code.endswith("```"):
+            cleaned_code = cleaned_code[:-3]
+        cleaned_code = cleaned_code.strip()
+
+        response = {
+            "tool": "jupyter_cell",
+            "parameters": {"code": cleaned_code, "description": description},
+            "status": "pending_execution",
+            "message": "Code cell queued for execution",
+        }
+        if execution_result is not None:
+            response["execution_result"] = execution_result
+            response["status"] = "complete"
+            response["message"] = "Code cell executed with client-reported results"
+        return json.dumps(response)
+
+    return jupyter_cell
+
+
+def create_jupyter_markdown_tool(context: NotebookContextManager) -> BaseTool:
+    """
+    Jupyter 마크다운 셀 조작용 LangChain 도구를 생성합니다.
+
+    Args:
+        context: 노트북 상태 접근을 위한 NotebookContextManager
+
+    Returns:
+        마크다운 조작용 LangChain BaseTool
+    """
+
+    @tool
+    def jupyter_markdown(
+        operation: str,
+        content: str,
+        cell_index: Optional[int] = None,
+        insert_after: Optional[int] = None,
+    ) -> str:
+        """
+        Jupyter 노트북에서 마크다운 셀을 생성하거나 수정합니다.
+
+        문서화, 설명, 헤더 추가에 사용합니다.
+
+        Args:
+            operation: 수행할 연산 (CREATE 또는 UPDATE)
+            content: 마크다운 내용
+            cell_index: 셀 인덱스 (UPDATE용)
+            insert_after: 이 인덱스 뒤에 새 셀 삽입 (CREATE용)
+
+        Returns:
+            연산 결과가 담긴 JSON 문자열
+        """
+        # HITL 모드: 실제 마크다운 셀 추가는 프론트엔드에서 처리됨.
+        return json.dumps(
+            {
+                "success": True,
+                "message": "마크다운 셀이 노트북에 추가되었습니다.",
+            }
+        )
+
+    return jupyter_markdown
+
+
+def create_notebook_info_tool(context: NotebookContextManager) -> BaseTool:
+    """
+    노트북 정보 조회용 LangChain 도구를 생성합니다.
+
+    Args:
+        context: 노트북 상태 접근을 위한 NotebookContextManager
+
+    Returns:
+        노트북 정보 조회용 LangChain BaseTool
+    """
+
+    @tool
+    def notebook_info() -> str:
+        """
+        현재 Jupyter 노트북의 정보를 가져옵니다.
+
+        경로, 셀 개수, 커널 정보를 포함한 요약을 반환합니다.
+
+        Returns:
+            노트북 요약이 담긴 JSON 문자열
+        """
+        # NotebookContextManager가 설정되어 있으면 요약 반환, 아니면 기본값
+        if context.current_notebook:
+            try:
+                summary = context.get_summary()
+                return json.dumps({"success": True, "data": summary})
+            except Exception as e:
+                return json.dumps({"success": False, "error": str(e)})
+        return json.dumps(
+            {
+                "success": True,
+                "data": {
+                    "path": "unknown",
+                    "cell_count": 0,
+                    "kernel_name": "python3",
+                },
+            }
+        )
+
+    return notebook_info
+
+
+# =============================================================================
+# 파일 도구
+# =============================================================================
+
+
+def _walk(root: Path, skip_hidden: bool):
+    """root 아래 (경로, 디렉토리 여부) 를 낸다. 제외 디렉토리는 **보이되 들어가지 않는다**.
+
+    판정은 root 기준 상대 이름으로 한다 — 워크트리처럼 root 경로 자체에 점
+    디렉토리가 끼어 있어도 전부 걸러지지 않게 (이슈 #100). rglob 뒤에 거르면
+    node_modules 를 끝까지 순회하므로 os.walk 가지치기로 막는다.
+    """
+    for dirpath, dirnames, filenames in os.walk(root):
+        base = Path(dirpath)
+        for d in dirnames:
+            if not (skip_hidden and d.startswith(".")):
+                yield base / d, True
+        dirnames[:] = [
+            d
+            for d in dirnames
+            if d not in SEARCH_EXCLUDED_DIRS and not (skip_hidden and d.startswith("."))
+        ]
+        for name in filenames:
+            if not (skip_hidden and name.startswith(".")):
+                yield base / name, False
+
+
+def _glob_regex(pattern: str) -> "re.Pattern[str]":
+    """rglob(pattern) 과 같은 뜻의 정규식 — `**` 는 0단 이상, 앞은 어느 깊이든.
+
+    `PurePath.match` 는 `**` 를 한 구성요소로 읽어 `**/*.py` 가 루트 파일을
+    놓친다 (이슈 #100 셀프리뷰).
+    """
+    out, i = [], 0
+    while i < len(pattern):
+        if pattern.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+        elif pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            out.append("[^/]")
+            i += 1
+        elif pattern[i] == "[" and pattern.find("]", i + 2) > i:
+            j = pattern.find("]", i + 2)
+            body = pattern[i + 1 : j]
+            if body.startswith("!"):
+                body = "^" + body[1:]
+            out.append("[" + body.replace("\\", "\\\\") + "]")
+            i = j + 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+    return re.compile("(?:.*/)?" + "".join(out) + r"\Z")
+
+
+def _matches(path: Path, root: Path, pattern: str) -> bool:
+    if "/" in pattern:
+        rel = path.relative_to(root).as_posix()
+        return _glob_regex(pattern).match(rel) is not None
+    return fnmatch.fnmatch(path.name, pattern)
+
+
+def create_file_read_tool(workspace_root: str) -> BaseTool:
+    """
+    파일 내용 읽기용 LangChain 도구를 생성합니다.
+
+    Args:
+        workspace_root: 파일 작업의 루트 디렉토리
+
+    Returns:
+        파일 읽기용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def file_read(path: str, encoding: str = "utf-8") -> str:
+        """
+        파일 내용을 읽습니다.
+
+        파일 내용을 텍스트로 반환합니다. 바이너리 파일은 오류를 반환합니다.
+
+        Args:
+            path: 읽을 파일 경로 (워크스페이스 기준 상대 경로)
+            encoding: 파일 인코딩 (기본값: utf-8)
+
+        Returns:
+            파일 내용 또는 오류가 담긴 JSON 문자열
+        """
+        if not path:
+            return json.dumps({"success": False, "error": "경로가 필요합니다"})
+
+        try:
+            file_path = base_path / path
+            if not file_path.exists():
+                return json.dumps(
+                    {"success": False, "error": f"파일을 찾을 수 없음: {path}"}
+                )
+
+            if not file_path.is_file():
+                return json.dumps({"success": False, "error": f"파일이 아님: {path}"})
+
+            content = file_path.read_text(encoding=encoding)
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {"content": content, "path": str(path)},
+                    "metadata": {"size": len(content), "encoding": encoding},
+                }
+            )
+
+        except UnicodeDecodeError:
+            return json.dumps(
+                {"success": False, "error": f"텍스트로 읽을 수 없는 파일: {path}"}
+            )
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"파일 읽기 오류: {e}"})
+
+    return file_read
+
+
+def create_file_write_tool(workspace_root: str) -> BaseTool:
+    """
+    파일 내용 쓰기용 LangChain 도구를 생성합니다.
+
+    Args:
+        workspace_root: 파일 작업의 루트 디렉토리
+
+    Returns:
+        파일 쓰기용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def file_write(path: str, content: str, append: bool = False) -> str:
+        """
+        파일에 내용을 씁니다.
+
+        파일이 없으면 생성합니다. 필요시 상위 디렉토리도 생성합니다.
+        Python 파일(.py)은 자동으로 ruff check --fix(안 쓰인 import 는 남김)와 ruff format을 실행합니다.
+
+        경고: 이 도구는 파일을 수정할 수 있습니다. HITL 승인이 필요합니다.
+
+        Args:
+            path: 쓸 파일 경로 (워크스페이스 기준 상대 경로)
+            content: 쓸 내용
+            append: 덮어쓰기 대신 추가 (기본값: False)
+
+        Returns:
+            연산 결과가 담긴 JSON 문자열
+        """
+        if not path:
+            return json.dumps({"success": False, "error": "경로가 필요합니다"})
+
+        try:
+            file_path = base_path / path
+
+            # 필요시 상위 디렉토리 생성
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            mode = "a" if append else "w"
+            with open(file_path, mode, encoding="utf-8") as f:
+                f.write(content)
+
+            result = {
+                "success": True,
+                "data": {
+                    "path": str(path),
+                    "operation": "append" if append else "write",
+                },
+                "metadata": {"size": len(content)},
+            }
+
+            # Python 파일은 자동으로 ruff 실행
+            if path.endswith(".py"):
+                # PATH → wheel 이 깐 ruff 순 (이슈 #145). 둘 다 없으면 아래 FileNotFoundError
+                ruff = ruff_command() or ["ruff"]
+                try:
+                    ruff_fix = subprocess.run(
+                        [*ruff, *RUFF_FIX, str(file_path)],
+                        capture_output=True,
+                        timeout=30,
+                    )
+                    ruff_fmt = subprocess.run(
+                        [*ruff, "format", str(file_path)],
+                        capture_output=True,
+                        timeout=30,
+                    )
+                    result["metadata"]["ruff_applied"] = True
+                    result["metadata"]["ruff_fix_returncode"] = ruff_fix.returncode
+                    result["metadata"]["ruff_format_returncode"] = ruff_fmt.returncode
+                except FileNotFoundError:
+                    result["metadata"]["ruff_applied"] = False
+                    result["metadata"]["ruff_note"] = "ruff가 설치되지 않음"
+                except subprocess.TimeoutExpired:
+                    result["metadata"]["ruff_applied"] = False
+                    result["metadata"]["ruff_note"] = "ruff 시간 초과"
+
+            return json.dumps(result)
+
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"파일 쓰기 오류: {e}"})
+
+    return file_write
+
+
+def create_file_list_tool(workspace_root: str) -> BaseTool:
+    """
+    디렉토리 목록 조회용 LangChain 도구를 생성합니다.
+
+    Args:
+        workspace_root: 파일 작업의 루트 디렉토리
+
+    Returns:
+        디렉토리 목록 조회용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def file_list(
+        path: str = ".", recursive: bool = False, pattern: Optional[str] = None
+    ) -> str:
+        """
+        경로의 파일과 디렉토리를 나열합니다.
+
+        파일/디렉토리 이름과 타입 목록을 반환합니다.
+
+        Args:
+            path: 나열할 디렉토리 경로 (워크스페이스 기준 상대 경로, 기본값: ".")
+            recursive: 재귀적으로 나열 (기본값: False)
+            pattern: 파일 필터링용 글롭 패턴 (예: '*.py')
+
+        Returns:
+            항목 목록이 담긴 JSON 문자열
+        """
+        try:
+            dir_path = base_path / path
+            if not dir_path.exists():
+                return json.dumps(
+                    {"success": False, "error": f"경로를 찾을 수 없음: {path}"}
+                )
+
+            if not dir_path.is_dir():
+                return json.dumps(
+                    {"success": False, "error": f"디렉토리가 아님: {path}"}
+                )
+
+            entries = []
+
+            if recursive:
+                files = (
+                    p
+                    for p, _ in _walk(dir_path, skip_hidden=False)
+                    if not pattern or _matches(p, dir_path, pattern)
+                )
+            else:
+                files = dir_path.glob(pattern) if pattern else dir_path.iterdir()
+
+            for entry in files:
+                try:
+                    rel_path = entry.relative_to(base_path)
+                    entries.append(
+                        {
+                            "name": entry.name,
+                            "path": str(rel_path),
+                            "type": "directory" if entry.is_dir() else "file",
+                            "size": entry.stat().st_size if entry.is_file() else None,
+                        }
+                    )
+                except ValueError:
+                    # base_path 외부 항목은 건너뜀
+                    pass
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {"entries": entries, "path": str(path)},
+                    "metadata": {"count": len(entries)},
+                }
+            )
+
+        except Exception as e:
+            return json.dumps(
+                {"success": False, "error": f"디렉토리 목록 조회 오류: {e}"}
+            )
+
+    return file_list
+
+
+# =============================================================================
+# 검색 도구
+# =============================================================================
+
+
+def create_search_code_tool(workspace_root: str) -> BaseTool:
+    """
+    코드 검색용 LangChain 도구를 생성합니다.
+
+    Args:
+        workspace_root: 검색 작업의 루트 디렉토리
+
+    Returns:
+        코드 검색용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def search_code(
+        pattern: str,
+        path: str = ".",
+        file_pattern: str = "*",
+        max_results: int = 50,
+        case_sensitive: bool = True,
+    ) -> str:
+        """
+        코드 파일에서 패턴을 검색합니다.
+
+        정규식 패턴을 사용하여 파일들에서 일치 항목을 찾습니다.
+        파일 경로와 줄 번호가 포함된 일치하는 줄을 반환합니다.
+
+        Args:
+            pattern: 검색할 정규식 패턴
+            path: 검색할 디렉토리 (워크스페이스 기준 상대 경로, 기본값: ".")
+            file_pattern: 검색할 파일의 글롭 패턴 (예: '*.py')
+            max_results: 반환할 최대 결과 수 (기본값: 50)
+            case_sensitive: 대소문자 구분 검색 (기본값: True)
+
+        Returns:
+            일치하는 줄이 담긴 JSON 문자열
+        """
+        if not pattern:
+            return json.dumps({"success": False, "error": "패턴이 필요합니다"})
+
+        try:
+            flags = 0 if case_sensitive else re.IGNORECASE
+            regex = re.compile(pattern, flags)
+        except re.error as e:
+            return json.dumps({"success": False, "error": f"잘못된 정규식 패턴: {e}"})
+
+        search_path = base_path / path
+        if not search_path.exists():
+            return json.dumps(
+                {"success": False, "error": f"경로를 찾을 수 없음: {path}"}
+            )
+
+        results = []
+        try:
+            for file_path, is_dir in _walk(search_path, skip_hidden=True):
+                if is_dir or not _matches(file_path, search_path, file_pattern):
+                    continue
+                # FIFO·소켓을 read_text 하면 쓰는 쪽이 올 때까지 막힌다
+                if not file_path.is_file():
+                    continue
+
+                try:
+                    content = file_path.read_text(encoding="utf-8", errors="ignore")
+                    for line_num, line in enumerate(content.splitlines(), 1):
+                        if regex.search(line):
+                            rel_path = file_path.relative_to(base_path)
+                            results.append(
+                                {
+                                    "file": str(rel_path),
+                                    "line": line_num,
+                                    "content": line.strip()[:200],  # 긴 줄은 잘라냄
+                                }
+                            )
+
+                            if len(results) >= max_results:
+                                break
+                except Exception:
+                    # 읽을 수 없는 파일은 건너뜀
+                    continue
+
+                if len(results) >= max_results:
+                    break
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {"matches": results, "pattern": pattern},
+                    "metadata": {
+                        "count": len(results),
+                        "truncated": len(results) >= max_results,
+                    },
+                }
+            )
+
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"검색 오류: {e}"})
+
+    return search_code
+
+
+# =============================================================================
+# LSP 도구 (Grep 기반 대체 구현)
+# =============================================================================
+
+
+def create_diagnostics_tool(workspace_root: str) -> BaseTool:
+    """
+    코드 진단용 LangChain 도구를 생성합니다.
+
+    정적 분석 도구(ruff, mypy)가 있으면 사용하고,
+    없으면 기본 패턴 기반 진단을 제공하는 Python 기반 구현입니다.
+
+    Args:
+        workspace_root: 분석의 루트 디렉토리
+
+    Returns:
+        진단용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def diagnostics(
+        path: Optional[str] = None, severity_filter: Optional[str] = None
+    ) -> str:
+        """
+        파일 또는 전체 프로젝트의 코드 진단(오류, 경고)을 가져옵니다.
+
+        Python 파일의 문제를 탐지하기 위해 ruff를 실행합니다.
+        ruff가 없으면 기본 패턴 기반 검사로 대체합니다.
+
+        이 도구의 용도:
+        - 코드 실행 전 문법 오류 확인
+        - Python 파일의 타입 오류 및 린트 문제 찾기
+        - 사용하지 않는 import나 변수 식별
+
+        Args:
+            path: 선택적 파일 경로. 미지정시 프로젝트 루트 검사.
+            severity_filter: 선택적 필터 ('error', 'warning')
+
+        Returns:
+            진단 결과가 담긴 JSON 문자열
+        """
+        target = base_path / path if path else base_path
+        results = []
+
+        try:
+            # Python 진단을 위해 ruff 실행 시도
+            if target.is_file() and target.suffix == ".py":
+                ruff_target = str(target)
+            elif target.is_dir():
+                ruff_target = str(target)
+            else:
+                return json.dumps(
+                    {
+                        "success": True,
+                        "data": {
+                            "diagnostics": [],
+                            "message": "분석할 Python 파일 없음",
+                        },
+                    }
+                )
+
+            try:
+                ruff_result = subprocess.run(
+                    ["ruff", "check", "--output-format=json", ruff_target],
+                    capture_output=True,
+                    timeout=60,
+                    cwd=str(base_path),
+                )
+
+                if ruff_result.stdout:
+                    ruff_diagnostics = json.loads(ruff_result.stdout.decode("utf-8"))
+                    for diag in ruff_diagnostics:
+                        severity = (
+                            "error"
+                            if diag.get("code", "").startswith("E")
+                            else "warning"
+                        )
+                        if severity_filter and severity != severity_filter:
+                            continue
+
+                        results.append(
+                            {
+                                "file": diag.get("filename", ""),
+                                "line": diag.get("location", {}).get("row", 0),
+                                "character": diag.get("location", {}).get("column", 0),
+                                "severity": severity,
+                                "code": diag.get("code", ""),
+                                "message": diag.get("message", ""),
+                                "source": "ruff",
+                            }
+                        )
+
+            except FileNotFoundError:
+                # Ruff 미설치 - 기본 피드백 제공
+                return json.dumps(
+                    {
+                        "success": True,
+                        "data": {
+                            "diagnostics": [],
+                            "message": "ruff가 설치되지 않음. 설치: pip install ruff",
+                        },
+                        "metadata": {"tool_available": False},
+                    }
+                )
+            except subprocess.TimeoutExpired:
+                return json.dumps({"success": False, "error": "진단 검사 시간 초과"})
+
+            # 심각도순 정렬 (오류 우선)
+            results.sort(
+                key=lambda x: (
+                    0 if x["severity"] == "error" else 1,
+                    x["file"],
+                    x["line"],
+                )
+            )
+
+            # 개수 계산
+            errors = sum(1 for r in results if r["severity"] == "error")
+            warnings = sum(1 for r in results if r["severity"] == "warning")
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {
+                        "diagnostics": results[:50],  # 50개로 제한
+                        "summary": {
+                            "errors": errors,
+                            "warnings": warnings,
+                            "total": len(results),
+                        },
+                    },
+                    "metadata": {
+                        "truncated": len(results) > 50,
+                        "tool_available": True,
+                    },
+                }
+            )
+
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"진단 조회 오류: {e}"})
+
+    return diagnostics
+
+
+def _find_ast_references(source: str, symbol: str) -> list[tuple[int, int, str]]:
+    """AST를 사용해 Python 소스에서 심볼의 실제 코드 참조를 찾습니다.
+
+    문자열/주석 내 false positive를 제거하고 실제 코드 참조만 반환합니다.
+
+    Returns:
+        (line, col, preview) 튜플 리스트
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    lines = source.splitlines()
+    refs: list[tuple[int, int, str]] = []
+
+    for node in ast.walk(tree):
+        matched = False
+        line = 0
+        col = 0
+
+        if isinstance(node, ast.Name) and node.id == symbol:
+            matched, line, col = True, node.lineno, node.col_offset
+        elif isinstance(node, ast.Attribute) and node.attr == symbol:
+            matched, line, col = True, node.lineno, node.col_offset
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name == symbol:
+                matched, line, col = True, node.lineno, node.col_offset
+        elif isinstance(node, ast.ClassDef) and node.name == symbol:
+            matched, line, col = True, node.lineno, node.col_offset
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name == symbol or (alias.asname and alias.asname == symbol):
+                    matched, line, col = True, node.lineno, node.col_offset
+                    break
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                if alias.name == symbol or (alias.asname and alias.asname == symbol):
+                    matched, line, col = True, node.lineno, node.col_offset
+                    break
+
+        if matched and line > 0:
+            preview = lines[line - 1].strip()[:80] if line <= len(lines) else ""
+            refs.append((line, col, preview))
+
+    return refs
+
+
+_REFERENCES_MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
+_REFERENCES_SKIP_DIRS = frozenset(
+    {"__pycache__", ".git", "node_modules", ".venv", "venv", ".tox", ".mypy_cache"}
+)
+
+
+def create_references_tool(workspace_root: str) -> BaseTool:
+    """
+    심볼 참조 찾기용 LangChain 도구를 생성합니다.
+
+    Python 파일은 AST 기반으로 실제 코드 참조만 찾고,
+    비-Python 파일은 grep fallback을 사용합니다.
+
+    Args:
+        workspace_root: 검색 작업의 루트 디렉토리
+
+    Returns:
+        참조 찾기용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def references(
+        symbol: str,
+        path: Optional[str] = None,
+        file_pattern: str = "*.py",
+    ) -> str:
+        """
+        코드베이스 전체에서 심볼의 모든 참조를 찾습니다.
+
+        Python 파일은 AST 분석으로 실제 코드 참조만 정확하게 찾습니다.
+        (문자열/주석 내 false positive 제거)
+        비-Python 파일은 grep 기반 검색을 사용합니다.
+
+        다음 용도로 유용합니다:
+        - 이름 변경/삭제 전 함수/클래스 사용 여부 확인
+        - 코드 전체에서 변수가 어떻게 사용되는지 이해
+        - 리팩토링 전 모든 사용 위치 찾기
+
+        Args:
+            symbol: 찾을 심볼 이름 (함수, 클래스, 변수)
+            path: 검색할 선택적 하위 디렉토리 (기본값: 전체 워크스페이스)
+            file_pattern: 검색할 파일의 글롭 패턴 (기본값: '*.py')
+
+        Returns:
+            참조 위치 목록이 담긴 JSON 문자열
+        """
+        if not symbol:
+            return json.dumps({"success": False, "error": "심볼 이름이 필요합니다"})
+
+        search_path = base_path / path if path else base_path
+        if not search_path.exists():
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": f"경로를 찾을 수 없음: {path or workspace_root}",
+                }
+            )
+
+        results: list[dict] = []
+        by_file: dict[str, list[dict]] = {}
+        use_ast = file_pattern == "*.py"
+
+        try:
+            for file_path in search_path.rglob(file_pattern):
+                if not file_path.is_file():
+                    continue
+
+                # 숨김 디렉토리와 일반적인 비코드 디렉토리 건너뛰기
+                if any(
+                    part.startswith(".") or part in _REFERENCES_SKIP_DIRS
+                    for part in file_path.parts
+                ):
+                    continue
+
+                # 대용량 파일 건너뛰기
+                try:
+                    if file_path.stat().st_size > _REFERENCES_MAX_FILE_SIZE:
+                        continue
+                except OSError:
+                    continue
+
+                try:
+                    content = file_path.read_text(encoding="utf-8", errors="ignore")
+                    rel_path = str(file_path.relative_to(base_path))
+
+                    if use_ast:
+                        # AST 기반: 실제 코드 참조만 매칭
+                        for line_num, col, preview in _find_ast_references(
+                            content, symbol
+                        ):
+                            ref = {
+                                "file": rel_path,
+                                "line": line_num,
+                                "character": col,
+                                "preview": preview,
+                            }
+                            results.append(ref)
+                            by_file.setdefault(rel_path, []).append(ref)
+                    else:
+                        # grep fallback: 비-Python 파일
+                        escaped_symbol = re.escape(symbol)
+                        pattern = re.compile(rf"\b{escaped_symbol}\b")
+                        for line_num, line in enumerate(content.splitlines(), 1):
+                            for match in pattern.finditer(line):
+                                ref = {
+                                    "file": rel_path,
+                                    "line": line_num,
+                                    "character": match.start(),
+                                    "preview": line.strip()[:80],
+                                }
+                                results.append(ref)
+                                by_file.setdefault(rel_path, []).append(ref)
+
+                except Exception:
+                    continue
+
+            # 파일과 줄 기준 정렬
+            results.sort(key=lambda x: (x["file"], x["line"]))
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {
+                        "references": results[:100],  # 100개로 제한
+                        "by_file": {f: len(refs) for f, refs in by_file.items()},
+                        "symbol": symbol,
+                    },
+                    "metadata": {
+                        "count": len(results),
+                        "file_count": len(by_file),
+                        "truncated": len(results) > 100,
+                        "method": "ast" if use_ast else "grep",
+                    },
+                }
+            )
+
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"참조 찾기 오류: {e}"})
+
+    return references
+
+
+# =============================================================================
+# 보안 스캔 도구
+# =============================================================================
+
+
+def create_security_scan_tool(workspace_root: str) -> BaseTool:
+    """
+    보안 취약점 스캔용 LangChain 도구를 생성합니다.
+
+    bandit, semgrep, pip-audit, detect-secrets, 커스텀 우회 패턴 스캐너를
+    통합하여 코드 레벨 보안 취약점을 검사합니다.
+
+    Args:
+        workspace_root: 스캔의 루트 디렉토리
+
+    Returns:
+        보안 스캔용 LangChain BaseTool
+    """
+    base_path = Path(workspace_root)
+
+    @tool
+    def security_scan(
+        target_path: Optional[str] = None,
+        scan_type: str = "all",
+        severity_filter: str = "medium",
+        semgrep_ruleset: str = "p/owasp-top-ten",
+    ) -> str:
+        """
+        보안 취약점 스캔을 실행합니다.
+
+        여러 보안 스캐너를 통합하여 코드의 보안 취약점을 검사합니다:
+        - bandit: Python SAST (정적 분석)
+        - semgrep: 패턴 기반 SAST
+        - pip-audit: 의존성 취약점
+        - detect-secrets: 시크릿/크리덴셜 탐지
+        - custom evasion: 우회 패턴 탐지 (base64 인코딩, 변수명 난독화 등)
+
+        이 도구의 용도:
+        - 코드 보안 취약점 검사 (SQL 인젝션, 하드코딩된 크리덴셜 등)
+        - 의존성 패키지 CVE 취약점 확인
+        - 시크릿/API 키 노출 탐지
+        - 보안 도구 우회 패턴 탐지
+
+        Args:
+            target_path: 스캔 대상 파일/디렉토리 경로 (기본: 워크스페이스 전체)
+            scan_type: 스캔 유형 - "all", "sast", "bandit", "semgrep",
+                       "dependencies", "secrets", "evasion", "pii"
+            severity_filter: 최소 심각도 - "low", "medium" (기본), "high", "critical"
+            semgrep_ruleset: semgrep 규칙셋 (기본: "p/owasp-top-ten")
+
+        Returns:
+            보안 스캔 결과가 담긴 JSON 문자열
+        """
+        from ..tools.security_tools import (
+            finding_to_dict,
+            run_bandit,
+            run_custom_pattern_scan,
+            run_detect_secrets,
+            run_pii_scan,
+            run_pip_audit,
+            run_semgrep,
+        )
+
+        target = str(base_path / target_path) if target_path else str(base_path)
+
+        all_findings = []
+        scanners_used = []
+        scanners_unavailable = []
+
+        try:
+            # --- SAST 스캐너 ---
+            if scan_type in ("all", "sast", "bandit"):
+                results = run_bandit(target, str(base_path), severity_filter)
+                if results:
+                    all_findings.extend(results)
+                    scanners_used.append("bandit")
+                elif scan_type == "bandit":
+                    scanners_unavailable.append("bandit")
+                else:
+                    # bandit이 결과 없으면 미설치 가능성 체크
+                    try:
+                        subprocess.run(
+                            ["bandit", "--version"],
+                            capture_output=True,
+                            timeout=10,
+                        )
+                        scanners_used.append("bandit")
+                    except FileNotFoundError:
+                        scanners_unavailable.append("bandit")
+
+            if scan_type in ("all", "sast", "semgrep"):
+                results = run_semgrep(target, str(base_path), semgrep_ruleset)
+                if results:
+                    all_findings.extend(results)
+                    scanners_used.append("semgrep")
+                else:
+                    try:
+                        subprocess.run(
+                            ["semgrep", "--version"],
+                            capture_output=True,
+                            timeout=10,
+                        )
+                        scanners_used.append("semgrep")
+                    except FileNotFoundError:
+                        scanners_unavailable.append("semgrep")
+
+            # --- 의존성 스캐너 ---
+            if scan_type in ("all", "dependencies"):
+                results = run_pip_audit(str(base_path))
+                if results:
+                    all_findings.extend(results)
+                    scanners_used.append("pip-audit")
+                else:
+                    try:
+                        subprocess.run(
+                            ["pip-audit", "--version"],
+                            capture_output=True,
+                            timeout=10,
+                        )
+                        scanners_used.append("pip-audit")
+                    except FileNotFoundError:
+                        scanners_unavailable.append("pip-audit")
+
+            # --- 시크릿 스캐너 ---
+            if scan_type in ("all", "secrets"):
+                results = run_detect_secrets(target, str(base_path))
+                if results:
+                    all_findings.extend(results)
+                    scanners_used.append("detect-secrets")
+                else:
+                    try:
+                        subprocess.run(
+                            ["detect-secrets", "--version"],
+                            capture_output=True,
+                            timeout=10,
+                        )
+                        scanners_used.append("detect-secrets")
+                    except FileNotFoundError:
+                        scanners_unavailable.append("detect-secrets")
+
+            partial_scans = []
+
+            # --- 커스텀 우회 패턴 스캐너 (항상 실행 가능) ---
+            if scan_type in ("all", "sast", "evasion"):
+                results = run_custom_pattern_scan(target, str(base_path))
+                if results:
+                    all_findings.extend(results)
+                scanners_used.append("custom-evasion")
+                if results.truncated:
+                    partial_scans.append(
+                        {
+                            "scanner": "custom-evasion",
+                            "reason": results.truncation_reason,
+                        }
+                    )
+
+            # --- 개인정보(PII) 패턴 스캐너 (항상 실행 가능) ---
+            if scan_type in ("all", "pii"):
+                results = run_pii_scan(target, str(base_path))
+                if results:
+                    all_findings.extend(results)
+                scanners_used.append("custom-pii")
+                if results.truncated:
+                    partial_scans.append(
+                        {"scanner": "custom-pii", "reason": results.truncation_reason}
+                    )
+
+            # --- 심각도 필터링 ---
+            severity_order = {
+                "critical": 0,
+                "high": 1,
+                "medium": 2,
+                "low": 3,
+                "info": 4,
+            }
+            min_sev = severity_order.get(severity_filter, 2)
+            filtered = [
+                f for f in all_findings if severity_order.get(f.severity, 4) <= min_sev
+            ]
+
+            # 심각도 내림차순 정렬
+            filtered.sort(key=lambda f: severity_order.get(f.severity, 4))
+
+            # 최대 100개로 제한
+            truncated = len(filtered) > 100
+            filtered = filtered[:100]
+
+            # --- 요약 생성 ---
+            by_severity = {}
+            for sev in ("critical", "high", "medium", "low", "info"):
+                count = sum(1 for f in filtered if f.severity == sev)
+                if count > 0:
+                    by_severity[sev] = count
+
+            by_scanner: dict[str, int] = {}
+            for f in filtered:
+                by_scanner[f.scanner] = by_scanner.get(f.scanner, 0) + 1
+
+            owasp_ids = sorted({f.owasp_id for f in filtered if f.owasp_id})
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": {
+                        "findings": [finding_to_dict(f) for f in filtered],
+                        "summary": {
+                            "total": len(filtered),
+                            **by_severity,
+                            "by_scanner": by_scanner,
+                            "owasp_coverage": owasp_ids,
+                        },
+                        "scanners_used": scanners_used,
+                        "scanners_unavailable": scanners_unavailable,
+                    },
+                    "metadata": {
+                        "truncated": truncated,
+                        "scan_complete": not partial_scans,
+                        "partial_scans": partial_scans,
+                    },
+                }
+            )
+
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"보안 스캔 오류: {e}"})
+
+    return security_scan
+
+
+# =============================================================================
+# 파일 검색 도구 (fuzzy)
+# =============================================================================
+
+
+def create_file_find_tool(workspace_root: str) -> BaseTool:
+    """
+    Fuzzy 파일 검색용 LangChain 도구를 생성합니다.
+
+    Args:
+        workspace_root: 검색의 루트 디렉토리
+
+    Returns:
+        파일 검색용 LangChain BaseTool
+    """
+    from ..tools.file_finder import FileIndex
+
+    _index = FileIndex(workspace_root)
+
+    @tool
+    def file_find(
+        query: str,
+        path: str = ".",
+        file_pattern: Optional[str] = None,
+        max_results: int = 20,
+    ) -> str:
+        """Find files by name using fuzzy matching.
+
+        Use when you need to locate files by partial or approximate name.
+        Unlike glob_search (exact glob patterns), this finds files even with
+        typos or partial names.
+
+        Examples:
+            file_find(query="auth") → finds auth.py, authentication.ts, ...
+            file_find(query="main.py") → finds main.py, main_app.py, ...
+            file_find(query="config", file_pattern="*.yaml") → YAML configs only
+            file_find(query="src/hand") → files matching "hand" under src/
+
+        Args:
+            query: Filename or partial name to search for (e.g., "auth", "main.py")
+            path: Directory to search in (relative to workspace, default ".")
+            file_pattern: Optional extension filter (e.g., "*.py", "*.ts")
+            max_results: Maximum number of results (default 20)
+
+        Returns:
+            JSON with ranked matches [{path, score, type}, ...]
+        """
+        if not query:
+            return json.dumps({"success": False, "error": "query is required"})
+
+        try:
+            # Determine supported extensions from file_pattern
+            supported_exts: set[str] | None = None
+            if file_pattern:
+                # Extract extension from glob pattern like "*.py"
+                if file_pattern.startswith("*."):
+                    supported_exts = {"." + file_pattern[2:]}
+
+            # If path is not ".", create a sub-index for that directory
+            search_index = _index
+            if path and path != ".":
+                base = Path(workspace_root) / path
+                if not base.is_dir():
+                    return json.dumps(
+                        {"success": False, "error": f"Directory not found: {path}"}
+                    )
+                search_index = FileIndex(str(base))
+
+            results = search_index.fuzzy_search(
+                query=query,
+                max_results=max_results,
+                supported_exts=supported_exts,
+            )
+
+            # Prepend path prefix for sub-directory searches
+            if path and path != ".":
+                for r in results:
+                    r["path"] = str(Path(path) / r["path"])
+
+            return json.dumps(
+                {
+                    "success": True,
+                    "data": results,
+                    "metadata": {
+                        "query": query,
+                        "total": len(results),
+                    },
+                }
+            )
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"파일 검색 오류: {e}"})
+
+    return file_find
+
+
+def create_rag_search_tool() -> BaseTool:
+    """
+    RAG 검색용 LangChain 도구를 생성합니다.
+
+    4개 컬렉션(enterprise_tables, bdp_tables, guide_docs, ds_guide_docs)에서 벡터 검색.
+
+    Returns:
+        RAG 검색용 LangChain BaseTool
+    """
+
+    @tool
+    def rag_search(
+        query: str,
+        collection: Optional[str] = None,
+        top_k: int = 5,
+    ) -> str:
+        """Search the RAG knowledge base for relevant information.
+
+        Searches across enterprise tables, BDP tables, guide documents, and DS guide documents.
+        Use this tool to find table metadata, column definitions, or guide content.
+
+        Args:
+            query: 검색 쿼리 (예: "카드 거래 테이블", "BDP 데이터 조회 방법")
+            collection: 특정 컬렉션만 검색 ("enterprise_tables", "bdp_tables", "guide_docs", "ds_guide_docs"). None이면 전체.
+            top_k: 반환할 최대 결과 수 (기본 5)
+
+        Returns:
+            JSON with search results [{collection, score, payload}, ...]
+        """
+        import asyncio
+
+        try:
+            from ..handlers.rag_admin_handler import _ensure_manager
+
+            mgr = _ensure_manager()
+            # sync wrapper for async method
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                import concurrent.futures
+
+                with concurrent.futures.ThreadPoolExecutor() as pool:
+                    results = pool.submit(
+                        asyncio.run,
+                        mgr.search_test(
+                            query=query, collection=collection, top_k=top_k
+                        ),
+                    ).result()
+            else:
+                results = asyncio.run(
+                    mgr.search_test(query=query, collection=collection, top_k=top_k)
+                )
+
+            if not results:
+                return json.dumps(
+                    {"success": True, "results": [], "message": "검색 결과 없음"}
+                )
+
+            # payload에서 _embed_text 제거 (검색용으로만 사용, LLM에겐 구조화된 payload 제공)
+            for r in results:
+                r.get("payload", {}).pop("_embed_text", None)
+
+            return json.dumps(
+                {"success": True, "results": results, "total": len(results)},
+                ensure_ascii=False,
+            )
+        except ImportError:
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": "RAG 시스템이 초기화되지 않았습니다. qdrant-client를 설치하세요.",
+                }
+            )
+        except Exception as e:
+            return json.dumps({"success": False, "error": f"RAG 검색 오류: {e}"})
+
+    return rag_search
+
+
+def create_enhanced_rag_search_tool() -> BaseTool:
+    """배치 쿼리 + Qdrant pre-filtering 지원 RAG 검색 도구 (chat mode 전용).
+
+    Returns:
+        RAG 검색용 LangChain BaseTool
+    """
+
+    @tool
+    async def rag_search(queries: Any, top_k: int = 5) -> str:  # noqa: C901
+        """RAG 지식 베이스에서 정보를 검색합니다.
+
+        ## 사용 가능한 컬렉션
+
+        1. **enterprise_tables** — 전사 엔터프라이즈 테이블 메타데이터
+           - payload: table_name, korean_name, db_name, columns[{col_name, col_korean_name, col_type, pk}]
+           - 내용: 테이블명, 한글명, DB명, 컬럼 정보 등
+           - 필터 가능: table_name, korean_name, db_name
+
+        2. **bdp_tables** — BDP 빅데이터플랫폼 테이블 메타데이터
+           - payload: table_id, table_name, korean_name, storage_format, update_cycle, domain, owner_team, columns[...]
+           - 예시: 카드/여신/수신 도메인 테이블, 일/월 배치 적재
+           - 필터 가능: table_name, korean_name, domain, owner_team, storage_format, update_cycle
+
+        3. **guide_docs** — BDP/플랫폼 업무 가이드 + bdpengine API 레퍼런스
+           - payload: content, summary, source(파일명), title, section
+           - 포함: BDP 아키텍처, S3/Athena/EMR/SageMaker 가이드, bdpengine 함수(S3, MinIO, Spark, Athena)
+           - bdpengine: BDP 핵심 Python 패키지 (from bdpengine.functions import *). S3 파일관리, MinIO, Spark Job, Athena 쿼리 통합 인터페이스
+           - 필터 가능: source(파일명), title, section
+
+        4. **ds_guide_docs** — 데이터사이언스 기술 가이드
+           - payload: content, summary, source(파일명), title, section
+           - 포함: Pandas, PySpark, Dask, LightGBM 사용법/최적화
+           - 필터 가능: source(파일명), title, section
+
+        ## queries 형식
+
+        JSON 배열 문자열. 여러 쿼리를 보내면 병렬 처리.
+
+        각 요소: {"query": "...", "collection": "...", "match_text": ["검색어1", "검색어2"], "type": "table"|"columns"}
+        - match_text (선택): 텍스트 인덱스 보조 검색어 리스트. 인덱스된 전체 필드에 OR 조건으로 자동 매칭.
+          벡터 검색과 병합하여 매칭 결과를 우선 포함합니다.
+        - type (선택, 테이블 컬렉션 전용): 청크 타입 필터
+          - "table": 사용자가 **테이블명/한글명**으로 검색할 때 (예: "dtcn0003 테이블 조회", "거래내역 테이블")
+            → 테이블 메타가 강조된 청크만 검색 → 컬럼 dilution 없이 정확
+          - "columns": 사용자가 **컬럼명**으로 테이블을 찾을 때 (예: "tran_amt 컬럼이 있는 테이블", "거래금액 컬럼 가진 테이블")
+            → 컬럼 리스트가 강조된 청크만 검색
+          - 미지정(생략): 의도가 애매하면 **양쪽 모두** 검색 (TableConfirmation 후보)
+          - **헷갈리면 type을 지정하지 마세요** — 안전한 기본값.
+          - payload 결과는 type과 무관하게 100% 동일 (테이블 메타 + 전체 컬럼).
+            즉, type="table"로 검색해도 컬럼 정보를 그대로 받습니다.
+        - exclude (선택, 테이블 컬렉션 전용): 결과에서 제외할 테이블명 리스트. 후보를
+          보여준 뒤 사용자가 그 후보들 말고 다른/추가 테이블을 원하는 의도를 보이면(표현은
+          다양함), 이번 대화에서 지금까지 보여준 모든 테이블명(직전 배치만이 아니라 누적
+          전부)을 exclude에 넣고 같은 query로 재검색하면 중복 없이 다음 후보가 나옵니다
+          (벡터검색은 offset 페이징이 불가하므로 이 방식).
+
+        예시:
+        [{"query": "카드 거래 테이블", "collection": "enterprise_tables"}]
+        [{"query": "S3 파일 업로드", "collection": "guide_docs"}, {"query": "고객 테이블", "collection": "bdp_tables"}]
+        [{"query": "dtcn0003 테이블 조회", "collection": "bdp_tables", "type": "table", "match_text": ["dtcn0003"]}]
+        [{"query": "거래금액 컬럼", "collection": "bdp_tables", "type": "columns"}]
+        [{"query": "카드매출 스키마", "collection": "bdp_tables", "match_text": ["card_pchs", "카드매출"]}]
+        [{"query": "고객 테이블", "collection": "bdp_tables", "type": "table", "exclude": ["bdp_cust_snap", "bdp_cust_daily"]}]
+
+        Args:
+            queries: JSON 배열 문자열. 각 요소: {query: str, collection?: str, match_text?: list, type?: "table"|"columns", exclude?: list}
+            top_k: 쿼리당 최대 결과 수 (기본 5)
+
+        Returns:
+            JSON. "테이블 검색 결과"와 "가이드 검색 결과"로 그룹핑.
+        """
+        import asyncio
+
+        parsed = _parse_batch_input(queries)
+        if parsed is None:
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": f"queries 파싱 실패 (list 변환 불가): {str(queries)[:200]}",
+                },
+                ensure_ascii=False,
+            )
+
+        try:
+            from codebuff_core.services.rag_collections import get_manager
+
+            mgr = get_manager()
+            if mgr is None:
+                return json.dumps(
+                    {"success": False, "error": "RAG 매니저가 초기화되지 않았습니다."},
+                    ensure_ascii=False,
+                )
+
+            # async tool이므로 직접 await 가능 (데드락 없음)
+            tasks = []
+            regular_queries = []
+            task_collections = []  # tasks 와 같은 순서 — 실패 보고에 컬렉션을 싣는다
+
+            _seen_queries: set = set()  # (query, collection) 중복 제거
+
+            for i, q in enumerate(parsed):
+                query_text = q.get("query", "") if isinstance(q, dict) else str(q)
+                collection = q.get("collection") if isinstance(q, dict) else None
+                # EDA 모드: enterprise_tables → bdp_tables 강제 치환
+                if _eda_only_bdp.get() and collection == "enterprise_tables":
+                    collection = "bdp_tables"
+                raw_mt = q.get("match_text") if isinstance(q, dict) else None
+                match_text = (
+                    raw_mt
+                    if isinstance(raw_mt, list)
+                    else [raw_mt]
+                    if isinstance(raw_mt, str)
+                    else None
+                )
+
+                # enterprise_tables → 사용자 원본 메시지에 키워드 없으면 bdp_tables로 변환
+                if collection == "enterprise_tables":
+                    _check_text = f"{_last_user_message.get()} {query_text}"
+                    if not _ENTERPRISE_KEYWORDS.search(_check_text):
+                        print(
+                            f"[RAG] enterprise_tables → bdp_tables (no keyword): {query_text[:80]}",
+                            flush=True,
+                        )
+                        collection = "bdp_tables"
+
+                # 동일 (query, collection) 중복 스킵
+                dedup_key = (query_text.lower().strip(), collection)
+                if dedup_key in _seen_queries:
+                    print(
+                        f"[RAG] skipping duplicate query: {query_text[:80]} → {collection}",
+                        flush=True,
+                    )
+                    continue
+                _seen_queries.add(dedup_key)
+
+                # faq_docs 직접 호출은 차단 — guide_docs 검색 시 자동으로
+                # 병렬 검색되도록 redirect (LLM은 faq_docs를 모름)
+                if collection == "faq_docs":
+                    print(
+                        f"[RAG] redirecting faq_docs → guide_docs: {query_text[:80]}",
+                        flush=True,
+                    )
+                    collection = "guide_docs"
+
+                # 테이블 컬렉션은 top_k=3 (컬럼 정보가 커서 토큰 절약)
+                effective_top_k = (
+                    3 if collection in ("enterprise_tables", "bdp_tables") else top_k
+                )
+                # match_text는 테이블 컬렉션에서만 사용
+                effective_mt = (
+                    match_text
+                    if collection in ("enterprise_tables", "bdp_tables")
+                    else None
+                )
+                # type 필터는 테이블 컬렉션에서만 사용 (table | columns | None)
+                raw_type = q.get("type") if isinstance(q, dict) else None
+                effective_type = (
+                    raw_type
+                    if (
+                        isinstance(raw_type, str)
+                        and raw_type in ("table", "columns")
+                        and collection in ("enterprise_tables", "bdp_tables")
+                    )
+                    else None
+                )
+                # exclude: "다른 후보 보여줘"용 — 이미 뽑은 테이블명을 제외하고 재쿼리.
+                # 테이블 컬렉션에서만 사용.
+                raw_exclude = q.get("exclude") if isinstance(q, dict) else None
+                effective_exclude = (
+                    raw_exclude
+                    if (
+                        isinstance(raw_exclude, list)
+                        and collection in ("enterprise_tables", "bdp_tables")
+                    )
+                    else [raw_exclude]
+                    if (
+                        isinstance(raw_exclude, str)
+                        and raw_exclude
+                        and collection in ("enterprise_tables", "bdp_tables")
+                    )
+                    else None
+                )
+                regular_queries.append(i)
+                task_collections.append(collection)
+                tasks.append(
+                    mgr.search_with_filter(
+                        query=query_text,
+                        collection=collection,
+                        top_k=effective_top_k,
+                        match_text=effective_mt,
+                        chunk_type=effective_type,
+                        exclude_table_names=effective_exclude,
+                    )
+                )
+
+                # guide_docs 호출 시 같은 query로 faq_docs도 자동 병렬 검색
+                # (LLM은 faq_docs 존재를 모름. 결과는 "FAQ 검색 결과"로 그룹핑)
+                if collection == "guide_docs":
+                    regular_queries.append(i)
+                    task_collections.append("faq_docs")
+                    tasks.append(
+                        mgr.search_with_filter(
+                            query=query_text,
+                            collection="faq_docs",
+                            top_k=3,
+                            score_threshold=0.55,
+                        )
+                    )
+
+            all_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            # 결과 그룹핑
+            table_results = []
+            guide_results = []
+            faq_results = []
+
+            # 실패는 "결과 없음" 과 구별해 싣는다 — 섞이면 장애가 "정보 없음" 답으로 바뀐다
+            errors = []
+
+            for ri, result in enumerate(all_results):
+                orig_idx = regular_queries[ri]
+                query_info = parsed[orig_idx] if orig_idx < len(parsed) else {}
+                query_text = (
+                    query_info.get("query", "") if isinstance(query_info, dict) else ""
+                )
+                if isinstance(result, Exception):
+                    print(f"[RAG] search error for query {ri}: {result}", flush=True)
+                    errors.append(
+                        {
+                            "query": query_text,
+                            "collection": task_collections[ri],
+                            "error": str(result),
+                        }
+                    )
+                    continue
+                for r in result:
+                    r["_query"] = query_text
+                    col = r.get("collection", "")
+                    if col in ("enterprise_tables", "bdp_tables"):
+                        table_results.append(r)
+                    elif col == "faq_docs":
+                        faq_results.append(r)
+                    else:
+                        guide_results.append(r)
+
+            # LLM에 불필요한 키 제거 + columns를 header+rows로 압축 (토큰 절약)
+            _STRIP_KEYS = {"id", "_group_key", "_chunk"}
+            for r in table_results + guide_results + faq_results:
+                for k in _STRIP_KEYS:
+                    r.pop(k, None)
+                p = r.get("payload")
+                if isinstance(p, dict):
+                    for k in _STRIP_KEYS:
+                        p.pop(k, None)
+            # 컬럼 개수 캡: 후보 테이블 전체 합쳐 최대 300개 (후보 수로 균등 분배)
+            _truncate_table_columns(
+                [
+                    r["payload"]
+                    for r in table_results
+                    if isinstance(r.get("payload"), dict)
+                ]
+            )
+
+            # _warnings 수집 (match_text fallback 등)
+            warnings: list = []
+            for r in table_results + guide_results + faq_results:
+                for w in r.pop("_warnings", []):
+                    if w not in warnings:
+                        warnings.append(w)
+
+            if tasks and len(errors) == len(tasks):
+                return json.dumps(
+                    {
+                        "success": False,
+                        "error": "RAG 검색 오류: 모든 검색이 실패했습니다",
+                        "errors": errors,
+                    },
+                    ensure_ascii=False,
+                )
+
+            output = {"success": True}
+            if errors:
+                output["errors"] = errors
+            if warnings:
+                output["warnings"] = warnings
+            if table_results:
+                output["테이블 검색 결과"] = table_results
+            if guide_results:
+                output["가이드 검색 결과"] = guide_results
+            if faq_results:
+                output["FAQ 검색 결과"] = faq_results
+            if not table_results and not guide_results and not faq_results:
+                output["message"] = "검색 결과 없음"
+                output["results"] = []
+            output["total"] = len(table_results) + len(guide_results) + len(faq_results)
+
+            return json.dumps(output, ensure_ascii=False, default=str)
+
+        except Exception as e:
+            return json.dumps(
+                {"success": False, "error": f"RAG 검색 오류: {e}"},
+                ensure_ascii=False,
+            )
+
+    return rag_search
+
+
+def create_get_table_columns_tool() -> BaseTool:
+    """테이블 컬럼 목록 조회 도구.
+
+    Returns:
+        LangChain BaseTool
+    """
+
+    @tool
+    async def get_table_columns(
+        table_name: str,
+        collection: str = "bdp_tables",
+        start_index: int = 0,
+    ) -> str:
+        """테이블의 컬럼 목록을 조회합니다.
+
+        rag_search 결과에서 컬럼이 축약된 경우 이 도구로 전체 컬럼을 확인합니다.
+
+        Args:
+            table_name: 테이블 이름 (정확한 이름 또는 부분 매칭)
+            collection: 컬렉션 이름 (enterprise_tables 또는 bdp_tables, 기본: bdp_tables)
+            start_index: 컬럼 목록 시작 인덱스 (페이징용, 기본 0)
+
+        Returns:
+            JSON. table_name, collection, total_columns, start_index, columns, next_index, has_more
+        """
+        _MAX_COLUMNS = 100
+        _ALLOWED = ("enterprise_tables", "bdp_tables", "bdp_tables_l2")
+
+        if collection not in _ALLOWED:
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": f"collection은 {_ALLOWED} 중 하나여야 합니다.",
+                },
+                ensure_ascii=False,
+            )
+
+        # enterprise_tables 접근 제한: 사용자 원본 메시지에 키워드 없으면 bdp_tables로 변환
+        if collection == "enterprise_tables":
+            _check_text = f"{_last_user_message.get()} {table_name}"
+            if not _ENTERPRISE_KEYWORDS.search(_check_text):
+                print(
+                    f"[RAG] get_table_columns: enterprise → bdp (no keyword): {table_name}",
+                    flush=True,
+                )
+                collection = "bdp_tables"
+
+        try:
+            from codebuff_core.services.rag_collections import get_manager
+
+            mgr = get_manager()
+            if mgr is None:
+                return json.dumps(
+                    {"success": False, "error": "RAG 매니저가 초기화되지 않았습니다."},
+                    ensure_ascii=False,
+                )
+
+            client = mgr._client
+
+            # 테이블명 필드: table_name 또는 테이블명 (매핑 설정에 따라 다름)
+            _TABLE_NAME_FIELDS = ["table_name", "테이블명"]
+
+            def _lookup(coll: str):
+                """coll에서 MatchText → MatchValue fallback으로 테이블 포인트 검색."""
+                from qdrant_client.models import (
+                    FieldCondition,
+                    Filter,
+                    MatchText,
+                    MatchValue,
+                )
+
+                # 1) MatchText로 검색 (text index가 있는 필드에서)
+                mt_conditions = [
+                    FieldCondition(key=f, match=MatchText(text=table_name.lower()))
+                    for f in _TABLE_NAME_FIELDS
+                ]
+                mt_filter = Filter(should=mt_conditions)
+                scroll_result = client.scroll(
+                    collection_name=coll,
+                    scroll_filter=mt_filter,
+                    limit=100,
+                    with_payload=True,
+                    with_vectors=False,
+                )
+                points = scroll_result[0] if scroll_result else []
+
+                resolved = None
+                if points:
+                    # exact match 테이블명 결정 (대소문자 무시)
+                    for pt in points:
+                        for f in _TABLE_NAME_FIELDS:
+                            pt_name = (pt.payload or {}).get(f, "")
+                            if pt_name and pt_name.lower() == table_name.lower():
+                                resolved = pt_name
+                                break
+                        if resolved:
+                            break
+                    if resolved is None:
+                        for f in _TABLE_NAME_FIELDS:
+                            v = (points[0].payload or {}).get(f, "")
+                            if v:
+                                resolved = v
+                                break
+
+                # 2) MatchText 실패 시 MatchValue fallback
+                if not points:
+                    for f in _TABLE_NAME_FIELDS:
+                        for mv_val in (table_name, table_name.lower()):
+                            mv_filter = Filter(
+                                must=[
+                                    FieldCondition(
+                                        key=f,
+                                        match=MatchValue(value=mv_val),
+                                    )
+                                ]
+                            )
+                            scroll_result = client.scroll(
+                                collection_name=coll,
+                                scroll_filter=mv_filter,
+                                limit=100,
+                                with_payload=True,
+                                with_vectors=False,
+                            )
+                            points = scroll_result[0] if scroll_result else []
+                            if points:
+                                resolved = mv_val
+                                break
+                        if points:
+                            break
+
+                # 같은 테이블의 모든 청크 수집
+                resolved_lower = (resolved or "").lower()
+                matched = [
+                    pt
+                    for pt in points
+                    if pt.payload
+                    and any(
+                        (pt.payload.get(f) or "").lower() == resolved_lower
+                        for f in _TABLE_NAME_FIELDS
+                    )
+                ]
+                return matched, resolved
+
+            # 명시적 collection 지정 시 그것만, 기본값(bdp_tables)이면 L2까지 순서대로 시도
+            # (L1과 동일 UX — rag_search의 columns_truncated 안내가 이 도구로 이어지므로
+            #  L1에 없는 L2 전용 테이블도 별도 안내 없이 그대로 찾아져야 함)
+            _try_collections = (
+                [collection]
+                if collection != "bdp_tables"
+                else ["bdp_tables", "bdp_tables_l2"]
+            )
+            matched_points: list = []
+            resolved_table_name = None
+            resolved_collection = collection
+            try:
+                for _coll in _try_collections:
+                    matched_points, resolved_table_name = _lookup(_coll)
+                    if matched_points:
+                        resolved_collection = _coll
+                        break
+                print(
+                    f"[RAG] get_table_columns: {table_name} → "
+                    f"resolved={resolved_table_name}, collection={resolved_collection}, "
+                    f"points={len(matched_points)}",
+                    flush=True,
+                )
+            except Exception as e:
+                print(
+                    f"[RAG] get_table_columns search error: {e}",
+                    flush=True,
+                )
+
+            collection = resolved_collection
+
+            if not matched_points:
+                return json.dumps(
+                    {
+                        "success": False,
+                        "error": (
+                            f"테이블 '{table_name}'을(를) "
+                            f"{'/'.join(_try_collections)}에서 찾을 수 없습니다."
+                        ),
+                    },
+                    ensure_ascii=False,
+                )
+
+            # 청크 순서대로 정렬 후 컬럼 합치기
+            def _chunk_sort_key(pt):
+                chunk = (pt.payload or {}).get("_chunk", "1/1")
+                try:
+                    return int(str(chunk).split("/")[0])
+                except (ValueError, IndexError):
+                    return 0
+
+            matched_points.sort(key=_chunk_sort_key)
+            found_table_name = resolved_table_name or table_name
+            columns: list = []
+            for pt in matched_points:
+                pt_cols = (pt.payload or {}).get("columns", [])
+                if isinstance(pt_cols, list):
+                    columns.extend(pt_cols)
+
+            # columns 포맷팅
+            total = len(columns) if isinstance(columns, list) else 0
+            if start_index < 0:
+                start_index = 0
+
+            sliced = (
+                columns[start_index : start_index + _MAX_COLUMNS]
+                if isinstance(columns, list)
+                else []
+            )
+            end_index = start_index + len(sliced)
+            has_more = end_index < total
+
+            # col_headers + rows 형태로 압축 (토큰 절약)
+            col_headers: list = []
+            formatted_rows: list = []
+            for idx, col in enumerate(sliced):
+                if isinstance(col, dict):
+                    if not col_headers:
+                        col_headers = list(col.keys())
+                    formatted_rows.append([col.get(h, "") for h in col_headers])
+                elif isinstance(col, list):
+                    formatted_rows.append(col)
+                else:
+                    formatted_rows.append([str(col)])
+
+            result: dict = {
+                "success": True,
+                "table_name": found_table_name,
+                "collection": collection,
+                "total_columns": total,
+                "start_index": start_index,
+                "next_index": end_index if has_more else None,
+                "has_more": has_more,
+            }
+            if col_headers:
+                result["col_headers"] = col_headers
+            result["columns"] = formatted_rows
+            return json.dumps(result, ensure_ascii=False, default=str)
+
+        except Exception as e:
+            return json.dumps(
+                {"success": False, "error": f"컬럼 조회 오류: {e}"},
+                ensure_ascii=False,
+            )
+
+    return get_table_columns
+
+
+def _parse_batch_input(raw: Any) -> Optional[list]:
+    """list/dict(이미 파싱됨), str(JSON), str(repr), str(double-encoded) 모두 처리.
+
+    rag_search의 queries와 search_l2_table의 table_names가 공유하는 배치 입력
+    파서. 파싱 실패 시 None.
+    """
+    parsed = raw
+    if isinstance(parsed, str):
+        try:
+            parsed = json.loads(parsed)
+        except (json.JSONDecodeError, TypeError):
+            # Python repr 형식 (single quotes) 처리
+            try:
+                import ast as _ast
+
+                parsed = _ast.literal_eval(parsed)
+            except Exception:
+                parsed = None
+    if isinstance(parsed, str):
+        # double-encoded: json.loads 결과가 또 string인 경우
+        try:
+            parsed = json.loads(parsed)
+        except (json.JSONDecodeError, TypeError):
+            parsed = None
+    if isinstance(parsed, dict):
+        parsed = [parsed]
+
+    if not isinstance(parsed, list) or not parsed:
+        return None
+    return parsed
+
+
+def _truncate_table_columns(payloads: list, total_budget: int = 300) -> None:
+    """columns: [{key:val,...},...] → col_headers + columns([[val,...],...]) 압축 + 캡.
+
+    payloads 전체에 total_budget을 균등 분배(후보 1개면 전체, 3개면 각 1/3).
+    초과분은 잘라내고 payload에 columns_truncated 안내를 추가해 get_table_columns로
+    이어보게 함. payload를 in-place로 수정한다. rag_search와 search_l2_table이 공유.
+    """
+    n = max(1, len(payloads))
+    per_cap = max(1, total_budget // n)
+    for p in payloads:
+        if not isinstance(p, dict):
+            continue
+        cols = p.get("columns")
+        if not (cols and isinstance(cols, list) and isinstance(cols[0], dict)):
+            continue
+        headers = list(cols[0].keys())
+        total_cols = len(cols)
+        shown = cols[:per_cap]
+        rows = [[c.get(h, "") for h in headers] for c in shown]
+        del p["columns"]
+        p["col_headers"] = headers
+        p["columns"] = rows
+        if total_cols > per_cap:
+            tname = p.get("테이블명") or p.get("table_name") or p.get("table_id") or ""
+            p["columns_truncated"] = (
+                f"⚠️ 컬럼 축약됨: 전체 {total_cols}개 중 {per_cap}개만 표시. "
+                "전체 컬럼이 필요하면 반드시 get_table_columns 도구로 조회하세요"
+                + (f" (테이블명: {tname})" if tname else "")
+                + "."
+            )
+
+
+# L2(프로젝트) 테이블명 필드 후보. table 검색은 영문 테이블명(테이블명/table_name)
+# + 한글명(테이블한글명)까지 substring 매칭 — 영문/한글 어느 쪽으로 물어도 찾음.
+# 영문 필드를 앞에 둬서 결과 그룹핑/후보명 해석은 영문명을 우선한다.
+_L2_TABLE_NAME_FIELDS = ["테이블명", "table_name", "테이블한글명"]
+# columns[] 배열 내부 객체 필드의 dot-array 문법 — Qdrant는 인덱스 없는 필드에서
+# 배열 내부 특정 필드를 substring 매칭 지원 (columns[].컬럼명).
+_L2_COLUMN_NAME_FIELDS = [
+    "columns[].컬럼명",
+    "columns[].col_name",
+    "columns[].column_name",
+]
+# 한 번의 tool 호출에서 처리할 테이블명 상한. LLM 재호출 판단에 기대지 않고 tool
+# 내부에서 결정적으로 처리(L1+L2 혼합 SQL 튜닝 등 다건 요청의 조용한 누락 방지).
+_L2_MAX_TABLE_NAMES = 10
+# ambiguous 후보 노출 개수 — substring 매칭은 순위가 없어 "짧은 이름" 휴리스틱으로
+# 정렬 후 상위 N개만. 나머지는 개수만 안내하고 candidate_offset으로 이어본다.
+_L2_CANDIDATE_PAGE = 3
+
+
+def _l2_group_by_name(points: list) -> dict:
+    """point 리스트를 테이블명(영문 우선) 기준으로 그룹핑. 반환 {테이블명: payload}."""
+    by_name: dict = {}
+    for pt in points:
+        payload = pt.payload or {}
+        tname = None
+        for f in _L2_TABLE_NAME_FIELDS:
+            v = payload.get(f)
+            if v:
+                tname = v
+                break
+        if tname and tname not in by_name:
+            by_name[tname] = payload
+    return by_name
+
+
+def create_search_l2_table_tool() -> BaseTool:
+    """L2(프로젝트) 테이블 검색 도구 생성.
+
+    bdp_tables_l2는 벡터 없는(payload-only) 컬렉션 — 텍스트 인덱스도 없어
+    MatchText가 진짜 substring 매칭으로 동작한다(토큰 매칭 아님). L2는 이름이
+    제각각이라 벡터 검색보다 정확한 substring 매칭이 더 적합.
+    """
+
+    @tool
+    async def search_l2_table(
+        table_names: Any, type: str = "table", candidate_offset: int = 0
+    ) -> str:
+        """L2(프로젝트) 테이블을 이름 또는 컬럼명으로 검색합니다.
+
+        L1(bdp_tables, rag_search)과 별도 컬렉션(bdp_tables_l2)에서 substring
+        매칭으로 검색합니다. 한 번에 최대 10개까지 배치 처리됩니다(병렬 tool 호출은
+        지원되지 않지만, 이 도구가 내부에서 순차 처리하므로 한 번만 호출하면 됩니다).
+
+        Args:
+            table_names: 테이블명(영문 또는 한글명) 또는 컬럼명 목록. JSON 배열
+                문자열 또는 리스트. type=table이면 영문 테이블명·한글명 어느 쪽으로도
+                검색됩니다(예: "mart_card_sales" 또는 "카드매출 일별"). "db.table"
+                형식이면 db명은 자동으로 제거됩니다.
+                예: ["mart_card_sales", "카드매출 일별", "some_l2_db.mart_user_stat"]
+            type: "table"(기본, 테이블명/한글명 검색) 또는 "columns"(컬럼명으로 테이블 역추적)
+            candidate_offset: ambiguous 후보 이어보기용 오프셋(기본 0). 직전 응답의
+                next_candidate_offset 값을 넣어 같은 검색어로 재호출하면 다음 후보를 봅니다.
+
+        Returns:
+            JSON {"results": [...]}. 각 결과:
+            - 0건: {"query": str, "not_found": true}
+            - type=table 1건: 테이블 전체 payload (컬럼 축약 시 안내)
+            - type=table 2건+: {"query": str, "ambiguous": true, "candidates": [상위 3개],
+              "candidate_offset": int, "more_candidates_count"?: int, "next_candidate_offset"?: int}
+            - type=columns: {"query": str, "tables": [...]} (여러 건이 정상)
+        """
+        from codebuff_core.services.rag_collections import (
+            COLLECTION_BDP_L2,
+            get_manager,
+            strip_fqn_to_table_name,
+        )
+
+        parsed = _parse_batch_input(table_names)
+        if parsed is None:
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": f"table_names 파싱 실패 (list 변환 불가): {str(table_names)[:200]}",
+                },
+                ensure_ascii=False,
+            )
+
+        warnings: list = []
+        queries = [str(q) for q in parsed if str(q).strip()]
+        if len(queries) > _L2_MAX_TABLE_NAMES:
+            warnings.append(
+                f"최대 {_L2_MAX_TABLE_NAMES}개까지 처리했습니다. "
+                f"나머지 {len(queries) - _L2_MAX_TABLE_NAMES}개는 다시 호출하세요."
+            )
+            queries = queries[:_L2_MAX_TABLE_NAMES]
+
+        effective_type = type if type in ("table", "columns") else "table"
+        try:
+            _offset = max(0, int(candidate_offset))
+        except (TypeError, ValueError):
+            _offset = 0
+
+        try:
+            from qdrant_client.models import FieldCondition, Filter, MatchText
+
+            mgr = get_manager()
+            if mgr is None:
+                return json.dumps(
+                    {"success": False, "error": "RAG 매니저가 초기화되지 않았습니다."},
+                    ensure_ascii=False,
+                )
+            client = mgr._client
+
+            results: list = []
+            # 단일 매칭 payload는 나중에 한꺼번에 컬럼 예산(총 300개)을 나눠 축약 —
+            # 다건 요청이 통째로 거대해지지 않도록(rag_search와 동일 방식).
+            _single_payloads: list = []
+            for raw_q in queries:
+                q = (
+                    strip_fqn_to_table_name(raw_q)
+                    if effective_type == "table"
+                    else raw_q.strip()
+                )
+                fields = (
+                    _L2_TABLE_NAME_FIELDS
+                    if effective_type == "table"
+                    else _L2_COLUMN_NAME_FIELDS
+                )
+                scroll_filter = Filter(
+                    should=[
+                        FieldCondition(key=f, match=MatchText(text=q)) for f in fields
+                    ]
+                )
+                scroll_result = client.scroll(
+                    collection_name=COLLECTION_BDP_L2,
+                    scroll_filter=scroll_filter,
+                    limit=200,
+                    with_payload=True,
+                    with_vectors=False,
+                )
+                points = scroll_result[0] if scroll_result else []
+                print(
+                    f"[RAG] search_l2_table: query={q!r} type={effective_type} "
+                    f"points={len(points)}",
+                    flush=True,
+                )
+
+                by_name = _l2_group_by_name(points)
+
+                if effective_type == "columns":
+                    results.append({"query": raw_q, "tables": list(by_name.values())})
+                    continue
+
+                if not by_name:
+                    results.append({"query": raw_q, "not_found": True})
+                elif len(by_name) == 1:
+                    (_, payload) = next(iter(by_name.items()))
+                    payload = dict(payload)
+                    _single_payloads.append(payload)
+                    # payload 참조를 유지 — truncate가 in-place 변형하므로 축약 후 병합.
+                    results.append({"query": raw_q, "_payload_ref": payload})
+                else:
+                    # substring 매칭은 순위가 없음 → 매칭된 이름이 짧을수록 군더더기가
+                    # 적어 더 근접한 후보라는 휴리스틱. 동률은 알파벳순으로 고정해
+                    # candidate_offset 이어보기가 매 호출 동일 순서를 갖게 함.
+                    ranked = sorted(by_name.keys(), key=lambda n: (len(n), n))
+                    top = ranked[_offset : _offset + _L2_CANDIDATE_PAGE]
+                    more = len(ranked) - (_offset + len(top))
+                    res = {
+                        "query": raw_q,
+                        "ambiguous": True,
+                        "candidates": top,
+                        "candidate_offset": _offset,
+                    }
+                    if more > 0:
+                        res["more_candidates_count"] = more
+                        res["next_candidate_offset"] = _offset + len(top)
+                    results.append(res)
+
+            # 단일 매칭들에 총 300개 컬럼 예산을 균등 분배(초과분 축약+안내) 후 병합
+            if _single_payloads:
+                _truncate_table_columns(_single_payloads)
+            for r in results:
+                if "_payload_ref" in r:
+                    r.update(r.pop("_payload_ref"))
+
+            output: dict = {"success": True, "results": results}
+            if warnings:
+                output["warnings"] = warnings
+            return json.dumps(output, ensure_ascii=False, default=str)
+
+        except Exception as e:
+            return json.dumps(
+                {"success": False, "error": f"L2 테이블 검색 오류: {e}"},
+                ensure_ascii=False,
+            )
+
+    return search_l2_table
+
+
+# ---------------------------------------------------------------------------
+# Data Skill — 동적 필터 가이드 + 확장 도구 디스커버리
+# ---------------------------------------------------------------------------
+
+# 모듈 레벨 캐시: 최초 1회 Qdrant 조회 후 재사용
+_table_skill_cache: Optional[str] = None
+
+_EXCLUDED_PAYLOAD_KEYS = {
+    "content",
+    "_embed_text",
+    "summary",
+    "columns",
+    "embedding_text",
+}
+_MAX_SAMPLE_VALUES = 10
+
+
+def _build_filter_guide() -> str:
+    """Qdrant에서 테이블 컬렉션의 payload 키와 샘플 값을 조회."""
+    global _table_skill_cache
+    if _table_skill_cache is not None:
+        return _table_skill_cache
+
+    try:
+        from codebuff_core.services.rag_collections import (
+            COLLECTION_BDP,
+            COLLECTION_ENTERPRISE,
+            get_manager,
+        )
+
+        mgr = get_manager()
+        if mgr is None:
+            return "(RAG 매니저 미초기화)"
+
+        client = mgr._client
+        existing = {c.name for c in client.get_collections().collections}
+
+        # 테이블 컬렉션만 조회 (guide는 pre-filtering 불필요)
+        table_collections = [COLLECTION_ENTERPRISE, COLLECTION_BDP]
+        lines: list[str] = []
+
+        for col_name in table_collections:
+            if col_name not in existing:
+                continue
+
+            try:
+                scroll_result = client.scroll(
+                    collection_name=col_name,
+                    limit=30,
+                    with_payload=True,
+                    with_vectors=False,
+                )
+                points = scroll_result[0] if scroll_result else []
+            except Exception:
+                continue
+
+            if not points:
+                continue
+
+            # payload 키별 unique 값 수집
+            key_values: dict[str, set] = {}
+            for pt in points:
+                if not pt.payload:
+                    continue
+                for k, v in pt.payload.items():
+                    if k in _EXCLUDED_PAYLOAD_KEYS:
+                        continue
+                    if isinstance(v, (list, dict)):
+                        continue
+                    if k not in key_values:
+                        key_values[k] = set()
+                    key_values[k].add(str(v))
+
+            if not key_values:
+                continue
+
+            lines.append(f"\n**{col_name}** 필터 가능 필드:")
+            for key, values in sorted(key_values.items()):
+                sample = sorted(values)[:_MAX_SAMPLE_VALUES]
+                sample_str = ", ".join(f'"{v}"' for v in sample)
+                suffix = " ..." if len(values) > _MAX_SAMPLE_VALUES else ""
+                lines.append(f"  - `{key}`: {sample_str}{suffix}")
+
+            # MatchText 검색 가능 필드 (text index가 있는 필드)
+            try:
+                col_info = client.get_collection(col_name)
+                text_fields = [
+                    field_name
+                    for field_name, schema in (col_info.payload_schema or {}).items()
+                    if schema.data_type == "text"
+                    or getattr(schema, "lookup", None) == "text"
+                    or "text" in str(getattr(schema, "params", "")).lower()
+                ]
+                if text_fields:
+                    lines.append(f"\n**{col_name}** MatchText 검색 가능 필드:")
+                    for f in sorted(text_fields):
+                        lines.append(f"  - `{f}`")
+            except Exception:
+                pass
+
+        result = "\n".join(lines) if lines else "(테이블 컬렉션 없음)"
+        _table_skill_cache = result
+        print(f"[RAG] data_skill cache built ({len(result)} chars)", flush=True)
+        return result
+
+    except Exception as e:
+        print(f"[RAG] data_skill build failed: {e}", flush=True)
+        return f"(스키마 조회 실패: {e})"
+
+
+def _skill_key(name: str) -> str:
+    """파일 stem(`data_loading`)과 frontmatter name(`data-loading`)을 같은 스킬로 본다."""
+    from .custom_skills import skill_key
+
+    return skill_key(name)
+
+
+def create_load_skills_tool(workspace_root: Optional[str] = None) -> BaseTool:
+    """스킬 로드 도구. skills/ 디렉토리의 md 파일을 이름으로 로드.
+
+    워크스페이스를 주면 같은 이름의 커스텀(포털) 스킬이 내장 스킬을 이긴다 —
+    `SkillMiddleware` 와 같은 계약이다 (이슈 #134, #202).
+
+    Returns:
+        LangChain BaseTool
+    """
+
+    # 사용 가능한 스킬 목록을 skills/ 디렉토리에서 동적 생성
+    from .custom_skills import catalog, discover, read_body, with_builtin
+
+    _skill_dir = Path(__file__).parent / "skills"
+    _available = sorted(p.stem for p in _skill_dir.glob("*.md"))
+    _builtin_stems = {_skill_key(stem): stem for stem in _available}
+    # 이름만으로는 무엇을 언제 불러야 할지 모른다 — 설명까지 싣는다 (이슈 #219)
+    _skill_list = catalog(
+        with_builtin(discover(workspace_root) if workspace_root else [])
+    )
+
+    @tool
+    def load_skills(names: str) -> str:
+        """스킬을 로드합니다. 쉼표로 구분하여 여러 스킬을 한번에 로드 가능.
+
+        Args:
+            names: 스킬 이름 (쉼표 구분). 예: "table_filter,athena_sql"
+
+        Returns:
+            로드된 스킬 내용.
+        """
+        skill_dir = _skill_dir
+        skill_names = [n.strip() for n in names.split(",") if n.strip()]
+        results: list[str] = []
+        # 호출 때마다 다시 찾는다 — 대화 중에 사용자가 스킬을 더해도 보인다
+        custom: dict[str, Path] = {}
+        if workspace_root:
+            for s in discover(workspace_root):
+                custom.setdefault(_skill_key(s.name), s.path)
+
+        for name in skill_names:
+            key = _skill_key(name)
+            if key in custom:
+                results.append(read_body(custom[key]))
+                continue
+            md_path = skill_dir / f"{_builtin_stems.get(key, name)}.md"
+            if not md_path.is_file():
+                results.append(f"[스킬 '{name}' 없음]")
+                continue
+            # 다른 두 경로(SkillMiddleware·codex)와 같은 본문 — frontmatter 제외·상한 (이슈 #228)
+            template = read_body(md_path)
+
+            # 동적 플레이스홀더 치환
+            if "{filter_guide}" in template:
+                template = template.replace("{filter_guide}", _build_filter_guide())
+
+            results.append(template)
+
+        output = "\n\n---\n\n".join(results)
+        print(f"[RAG] load_skills({names}): {len(results)} loaded", flush=True)
+        return output
+
+    # tool description에 사용 가능한 스킬 목록 동적 추가
+    load_skills.description = (
+        f"스킬을 로드합니다. 쉼표로 구분하여 여러 스킬을 한번에 로드 가능. "
+        f"사용 가능:\n{_skill_list or '(없음)'}"
+    )
+    return load_skills
+
+
+# ====================================================================
+# get_iceberg_snapshots — Athena 기반 Iceberg 스냅샷(적재 이력) 조회 도구
+# cd1-agent의 동명 도구 포팅. client는 k8s secret(jupyterlab-secret)의 AWS 키로
+# 직접 boto3.client("athena")를 생성하고, 실행은 직접 start_query_execution 호출
+# (WorkGroup은 HDSP_ENV 기준 하드코딩: dev=wdd-bdp-ath-wg-dlk / else wdp-…).
+# Mock/Real 분기는 별도 환경변수 없이 bdpengine 모듈 path로 자동 판별.
+# ====================================================================
+
+# table_name 입력 검증 (영문/숫자/언더스코어만 허용 — SQL injection 차단)
+_ICEBERG_TABLE_NAME_RE = re.compile(r"^[A-Za-z0-9_]+$")
+
+
+def _iceberg_is_bdpengine_mock() -> bool:
+    """bdpengine이 mock_packages 경로의 mock 구현인지 자동 판별.
+
+    `bdpengine.__file__`은 namespace package라 None일 수 있어 `__path__`로 확인.
+    codebuff는 EDA agent도 동일 bdpengine 추상화를 통해 mock/real을 분기 —
+    별도 ATHENA_PROVIDER 환경변수 없음.
+    """
+    try:
+        import bdpengine
+
+        paths = list(getattr(bdpengine, "__path__", []) or [])
+        if any("mock_packages" in str(p) for p in paths):
+            return True
+        # __file__ fallback (일부 환경에서 namespace package 아닌 경우)
+        f = getattr(bdpengine, "__file__", "") or ""
+        return "mock_packages" in f
+    except Exception:
+        # bdpengine 자체가 import 안 되면 mock으로 간주 (안전)
+        return True
+
+
+def _iceberg_resolve_database(layer: str) -> str:
+    """layer("l1"/"l2") + HDSP_ENV → Iceberg snapshot 조회용 database 이름.
+
+    명명 규칙:
+    - HDSP_ENV=dev → wdd_bdp_db_dlk_{layer}_org
+    - 그 외 (운영/미설정): wdp_bdp_db_dlk_{layer}_org
+    """
+    import os as _os
+
+    env = _os.getenv("HDSP_ENV", "").lower()
+    prefix = "wdd" if env == "dev" else "wdp"
+    suffix = "l2" if str(layer).lower() == "l2" else "l1"
+    return f"{prefix}_bdp_db_dlk_{suffix}_org"
+
+
+def _iceberg_build_snapshots_sql(database: str, table_name: str, limit: int) -> str:
+    """Iceberg $snapshots 시스템 테이블 조회 SQL.
+
+    summary는 map<string,string> — Trino CAST AS JSON 으로 JSON 문자열화.
+    SQL에 fully-qualified name(`"db"."table$snapshots"`)을 박아서 bdpengine.start_query가
+    별도 database 컨텍스트 없이도 실행 가능.
+    """
+    return (
+        f"SELECT committed_at, snapshot_id, parent_id, operation, "
+        f"CAST(summary AS JSON) AS summary "
+        f'FROM "{database}"."{table_name}$snapshots" '
+        f"WHERE operation <> 'replace' "
+        f"ORDER BY committed_at DESC "
+        f"LIMIT {limit}"
+    )
+
+
+def _iceberg_is_table_not_found(err_msg: str) -> bool:
+    """Athena 에러 메시지에서 테이블 없음 여부 판정."""
+    if not err_msg:
+        return False
+    m = err_msg.lower()
+    return (
+        "table_not_found" in m
+        or "does not exist" in m
+        or "table not found" in m
+        or "schema_not_found" in m
+    )
+
+
+def _iceberg_mock_snapshots(table_name: str, limit: int) -> list:
+    """로컬 테스트용 mock — 테이블명 seed 기반으로 재현 가능한 최근 10개 스냅샷.
+
+    bdpengine mock의 일반 _mock_results_for는 `$snapshots` 시스템 테이블 형식을
+    모르므로 이 도구 전용 mock 데이터를 별도 생성한다 (cd1-agent와 동일 패턴).
+    """
+    from datetime import datetime, timedelta, timezone
+
+    base = datetime(2026, 6, 4, 9, 0, 0, tzinfo=timezone.utc)
+    seed = sum(ord(c) for c in table_name) % 1000
+    rows: list = []
+    n = min(int(limit), 10)
+    for i in range(n):
+        ts = base - timedelta(hours=i * 3 + (i // 3))
+        is_overwrite = i == 5
+        added = 0 if is_overwrite else 15234 + seed * 7 + i * 100
+        deleted = 98000 + seed * 50 if is_overwrite else 0
+        total = 98765 + seed * 10 + i * 15234 - (98000 + seed * 50 if i > 5 else 0)
+        summary = {
+            "added-records": str(added),
+            "deleted-records": str(deleted),
+            "total-records": str(total),
+            "added-data-files": "0" if is_overwrite else str(3 + i % 2),
+            "deleted-data-files": str(45 + seed % 10) if is_overwrite else "0",
+            "total-data-files": str(120 + seed % 30 + i * 3),
+            "added-files-size": str(added * 240),
+            "removed-files-size": str(deleted * 240),
+            "total-files-size": str(total * 240),
+            "changed-partition-count": "1",
+        }
+        rows.append(
+            {
+                "committed_at": ts.isoformat(),
+                "snapshot_id": str(7000000000000000 + seed * 1000 + i),
+                "parent_id": (
+                    str(7000000000000000 + seed * 1000 + i + 1) if i < n - 1 else None
+                ),
+                "operation": "overwrite" if is_overwrite else "append",
+                "summary": summary,
+            }
+        )
+    return rows
+
+
+def _iceberg_load_aws_creds_from_k8s() -> tuple:
+    """in-cluster k8s secret(jupyterlab-secret)에서 AWS 자격증명 로드.
+
+    Returns (access_key, secret_key, session_token|None).
+    키명: AWS_ACCESS_KEY / AWS_SECRET_KEY.
+    session token은 있으면 사용(임시 자격증명), 없으면 None.
+    """
+    import base64
+
+    from kubernetes import client as _k8s_client
+    from kubernetes import config as _kubeconfig
+
+    _kubeconfig.load_incluster_config()
+    v1 = _k8s_client.CoreV1Api()
+    secret = v1.read_namespaced_secret("jupyterlab-secret", namespace="jupyterhub-ns")
+    decoded = {k: base64.b64decode(v).decode("utf-8") for k, v in secret.data.items()}
+
+    access_key = decoded.get("AWS_ACCESS_KEY")
+    secret_key = decoded.get("AWS_SECRET_KEY")
+    if not (access_key and secret_key):
+        raise RuntimeError(
+            "AWS 자격증명을 k8s secret(jupyterlab-secret)에서 찾지 못했습니다 "
+            "(AWS_ACCESS_KEY / AWS_SECRET_KEY 확인)"
+        )
+    session_token = decoded.get("AWS_SESSION_TOKEN")
+    return access_key, secret_key, session_token
+
+
+def _iceberg_run_athena(sql: str, timeout_s: int = 60) -> list:
+    """직접 boto3 athena로 실행 (client 생성은 k8s secret AWS 키 사용).
+
+    client은 k8s secret(jupyterlab-secret)의 AWS 키로 직접 생성하고,
+    start_query_execution을 호출한다. WorkGroup은 HDSP_ENV 기준 하드코딩.
+    Polling은 1초 간격, 최대 timeout_s. 결과는 paginator로 수집.
+    """
+    import os as _os
+    import time as _time
+
+    import boto3
+
+    access_key, secret_key, session_token = _iceberg_load_aws_creds_from_k8s()
+    client_kwargs = {
+        "region_name": "ap-northeast-2",
+        "aws_access_key_id": access_key,
+        "aws_secret_access_key": secret_key,
+    }
+    if session_token:
+        client_kwargs["aws_session_token"] = session_token
+    client = boto3.client("athena", **client_kwargs)
+
+    # WorkGroup은 HDSP_ENV 기준 하드코딩 (database와 동일한 wdd/wdp 분기).
+    # 워크그룹에 output이 강제돼 있어 OutputLocation은 넘기지 않는다.
+    env = _os.environ.get("HDSP_ENV", "").lower()
+    prefix = "wdd" if env == "dev" else "wdp"
+    workgroup = f"{prefix}-bdp-ath-wg-dlk"
+
+    result = client.start_query_execution(QueryString=sql, WorkGroup=workgroup)
+    qid = result.get("QueryExecutionId")
+    if not qid:
+        raise RuntimeError("Athena: QueryExecutionId 없음")
+
+    state = "QUEUED"
+    for _ in range(timeout_s):
+        _time.sleep(1)
+        resp = client.get_query_execution(QueryExecutionId=qid)
+        state = resp["QueryExecution"]["Status"]["State"]
+        if state == "SUCCEEDED":
+            break
+        if state in ("FAILED", "CANCELLED"):
+            reason = resp["QueryExecution"]["Status"].get("StateChangeReason", state)
+            raise RuntimeError(f"Athena query {state}: {reason}")
+    else:
+        raise RuntimeError(f"Athena query timeout after {timeout_s}s")
+
+    # 페이지네이션으로 결과 수집 (paginator 사용 가능 시 우선)
+    rows: list = []
+    header: Optional[list] = None
+    try:
+        paginator = client.get_paginator("get_query_results")
+        for page in paginator.paginate(QueryExecutionId=qid):
+            for row in page["ResultSet"]["Rows"]:
+                values = [col.get("VarCharValue", "") for col in row.get("Data", [])]
+                if header is None:
+                    header = values
+                    continue
+                rows.append(dict(zip(header, values)))
+    except (AttributeError, NotImplementedError):
+        # mock client는 paginator 미지원 — 단일 호출로 처리
+        result_set = client.get_query_results(QueryExecutionId=qid).get("ResultSet", {})
+        for row in result_set.get("Rows", []):
+            values = [col.get("VarCharValue", "") for col in row.get("Data", [])]
+            if header is None:
+                header = values
+                continue
+            rows.append(dict(zip(header, values)))
+    return rows
+
+
+def create_iceberg_snapshots_tool() -> BaseTool:
+    """get_iceberg_snapshots tool 생성. Iceberg 테이블 적재 이력 조회.
+
+    Athena의 `{db}.{table}$snapshots` 시스템 테이블을 조회하여 최근 적재 이력 반환.
+    client은 k8s secret AWS 키로 직접 생성하고 실행은 직접 start_query_execution.
+    mock_packages/bdpengine을 사용 중인 환경에서는 도구 자체 mock 데이터 반환.
+    """
+    import asyncio as _asyncio
+
+    @tool
+    async def get_iceberg_snapshots(
+        table_name: str,
+        layer: str,
+        limit: int = 20,
+    ) -> str:
+        """Iceberg 테이블의 최근 적재 이력(스냅샷)을 Athena로 조회합니다.
+
+        Args:
+            table_name: 테이블 영문명(snake_case). 영문/숫자/언더스코어만 허용.
+            layer: "l1"(일반 BDP 테이블) 또는 "l2"(프로젝트/L2). 사용자가
+                명확히 지정한 경우에만 호출하세요. 모호하면 사용자에게 되물어보세요.
+            limit: 최근 N개 스냅샷 (기본 20, 최대 100). 빈도 분석 시에만 늘리세요.
+
+        Returns:
+            JSON 문자열.
+            - 성공: {database, table_name, layer, snapshot_count, snapshots: [...]}
+            - 테이블 없음: {success: false, table_not_found: true, ...}
+            - 기타 오류: {success: false, error: "..."}
+
+            각 snapshot 항목: committed_at, snapshot_id, parent_id, operation, summary(JSON)
+        """
+        # 1) 입력 검증
+        if not isinstance(table_name, str) or not _ICEBERG_TABLE_NAME_RE.match(
+            table_name or ""
+        ):
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": (
+                        f"잘못된 table_name: {table_name!r}. "
+                        "영문/숫자/언더스코어만 허용됩니다."
+                    ),
+                    "table_name": table_name,
+                },
+                ensure_ascii=False,
+            )
+
+        layer_norm = (layer or "").strip().lower()
+        if layer_norm not in ("l1", "l2"):
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": f"layer는 'l1' 또는 'l2'만 허용됩니다 (받은 값: {layer!r}).",
+                    "table_name": table_name,
+                },
+                ensure_ascii=False,
+            )
+
+        try:
+            clamped_limit = max(1, min(int(limit or 20), 100))
+        except (TypeError, ValueError):
+            clamped_limit = 20
+
+        database = _iceberg_resolve_database(layer_norm)
+
+        is_mock = _iceberg_is_bdpengine_mock()
+        try:
+            # 2) Mock vs Real 분기 (bdpengine 모듈 path 기반 자동 판별)
+            if is_mock:
+                # mock 모드에서 '_notfound' 포함 시 TABLE_NOT_FOUND 시뮬레이션
+                if "_notfound" in table_name.lower():
+                    raise RuntimeError(
+                        f"TABLE_NOT_FOUND: Table '{database}.{table_name}' "
+                        "does not exist"
+                    )
+                rows = _iceberg_mock_snapshots(table_name, clamped_limit)
+            else:
+                sql = _iceberg_build_snapshots_sql(database, table_name, clamped_limit)
+                rows = await _asyncio.to_thread(_iceberg_run_athena, sql)
+
+            return json.dumps(
+                {
+                    "database": database,
+                    "table_name": table_name,
+                    "layer": layer_norm,
+                    "snapshot_count": len(rows),
+                    "snapshots": rows,
+                    "mock": is_mock,
+                },
+                ensure_ascii=False,
+                default=str,
+            )
+
+        except Exception as e:  # noqa: BLE001
+            err_msg = str(e)
+            print(
+                f"[iceberg_snapshots] layer={layer_norm} table={table_name} "
+                f"failed: {err_msg}",
+                flush=True,
+            )
+            if _iceberg_is_table_not_found(err_msg):
+                return json.dumps(
+                    {
+                        "success": False,
+                        "table_not_found": True,
+                        "table_name": table_name,
+                        "layer": layer_norm,
+                        "database": database,
+                        "error": f"테이블이 존재하지 않습니다: {database}.{table_name}",
+                    },
+                    ensure_ascii=False,
+                )
+            return json.dumps(
+                {
+                    "success": False,
+                    "error": err_msg,
+                    "table_name": table_name,
+                    "layer": layer_norm,
+                    "database": database,
+                },
+                ensure_ascii=False,
+            )
+
+    return get_iceberg_snapshots