illusion-code 0.1.0__py3-none-any.whl

illusion/services/file_history.py

@@ -0,0 +1,258 @@
+"""文件历史快照模块
+================
+
+本模块提供基于文件复制的快照管理，用于支持 /rewind 指令的文件回退。
+
+参考 Claude Code 的 copy-on-write 方案：在工具修改文件前备份其内容，
+rewind 时从备份恢复。不依赖 git，可跟踪任意路径的文件。
+
+存储位置：~/.illusion/data/file-history/{session_id}/{sha256(path)[:16]}@v{N}
+
+主要函数：
+    - track_edit: 在工具修改文件前备份（copy-on-write）
+    - make_snapshot: 创建快照边界（每条用户消息一次）
+    - rewind_to: 回退到指定快照，恢复文件
+
+使用示例：
+    >>> from illusion.services.file_history import FileHistoryState
+    >>> state = FileHistoryState(session_id="abc123", cwd="/project")
+    >>> track_edit(state, "/project/file.py")
+    >>> make_snapshot(state, "msg-uuid-1")
+    >>> rewind_to(state, "msg-uuid-1")
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from hashlib import sha256
+from pathlib import Path
+
+from illusion.config.paths import get_config_dir
+
+
+@dataclass
+class FileBackup:
+    """单个文件的备份记录。"""
+    backup_name: str | None  # 备份文件名，None 表示文件当时不存在
+    version: int
+
+
+@dataclass
+class FileSnapshot:
+    """一个快照：关联到一条用户消息，包含所有跟踪文件的备份映射。"""
+    message_id: str
+    turn_index: int = 0  # 轮次索引（0-based）
+    tracked_backups: dict[str, FileBackup] = field(default_factory=dict)
+
+
+@dataclass
+class FileHistoryState:
+    """文件历史状态。"""
+    session_id: str
+    cwd: str
+    snapshots: list[FileSnapshot] = field(default_factory=list)
+    tracked_files: set[str] = field(default_factory=set)
+    _turn_counter: int = 0  # 内部轮次计数器
+
+
+def _backup_dir(session_id: str) -> Path:
+    """返回备份存储目录。"""
+    return get_config_dir() / "file-history" / session_id
+
+
+def _backup_name(file_path: str, version: int = 1) -> str:
+    """生成备份文件名：sha256(路径@vN)[:16]。不同版本生成不同文件名。"""
+    return sha256(f"{file_path}@v{version}".encode("utf-8")).hexdigest()[:16]
+
+
+def _backup_path(session_id: str, backup_name: str) -> Path:
+    """返回备份文件的完整路径。"""
+    return _backup_dir(session_id) / backup_name
+
+
+def _resolve_path(file_path: str, cwd: str) -> str:
+    """将路径转为绝对路径。"""
+    p = Path(file_path)
+    if p.is_absolute():
+        return str(p)
+    return str(Path(cwd) / file_path)
+
+
+def track_edit(state: FileHistoryState, file_path: str) -> None:
+    """在工具修改文件前备份（copy-on-write）。
+
+    如果文件在当前快照中已被跟踪，跳过。否则：
+    - 文件存在：复制到备份目录
+    - 文件不存在：记录 None（标记为"文件当时不存在"）
+
+    Args:
+        state: 文件历史状态
+        file_path: 即将被修改的文件路径
+    """
+    abs_path = _resolve_path(file_path, state.cwd)
+    tracking_key = abs_path  # 使用绝对路径作为 key
+
+    # 检查是否已在当前快照中跟踪
+    if state.snapshots:
+        current = state.snapshots[-1]
+        if tracking_key in current.tracked_backups:
+            return  # 已跟踪，跳过
+
+    # 确定版本号：查找最近快照中此文件的备份版本
+    version = 1
+    for snap in reversed(state.snapshots):
+        if tracking_key in snap.tracked_backups:
+            version = snap.tracked_backups[tracking_key].version + 1
+            break
+
+    # 创建备份
+    bname = _backup_name(abs_path, version)
+    bpath = _backup_path(state.session_id, bname)
+
+    if Path(abs_path).exists():
+        # 文件存在：复制备份
+        bpath.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(abs_path, bpath)
+        backup = FileBackup(backup_name=bname, version=version)
+    else:
+        # 文件不存在（新文件）
+        backup = FileBackup(backup_name=None, version=version)
+
+    # 记录到当前快照
+    if state.snapshots:
+        state.snapshots[-1].tracked_backups[tracking_key] = backup
+
+    state.tracked_files.add(tracking_key)
+
+
+def make_snapshot(state: FileHistoryState, message_id: str) -> None:
+    """创建快照边界。
+
+    在用户发送消息时调用，为后续的工具编辑创建新的跟踪空间。
+
+    Args:
+        state: 文件历史状态
+        message_id: 关联的消息 ID
+    """
+    snapshot = FileSnapshot(message_id=message_id, turn_index=state._turn_counter)
+    state._turn_counter += 1
+    state.snapshots.append(snapshot)
+    # 最多保留 50 个快照
+    if len(state.snapshots) > 50:
+        evicted = state.snapshots[:-50]
+        state.snapshots = state.snapshots[-50:]
+        # 清理被驱逐快照的备份文件
+        _cleanup_evicted(state, evicted)
+
+
+def rewind_to(state: FileHistoryState, turn_index: int) -> list[str]:
+    """撤销指定轮次的所有文件修改，并移除该轮及之后的快照。
+
+    快照的备份记录的是工具执行前的文件状态，所以用目标快照自身的备份
+    来恢复文件，就能撤销该轮工具对文件的修改。
+
+    Args:
+        state: 文件历史状态
+        turn_index: 要撤销的轮次索引（0-based）
+
+    Returns:
+        list[str]: 被恢复的文件路径列表
+    """
+    # 找到目标快照（turn_index 匹配的最后一个）
+    target = None
+    target_idx = -1
+    for i, snap in enumerate(state.snapshots):
+        if snap.turn_index == turn_index:
+            target = snap
+            target_idx = i
+    if target is None:
+        return []
+
+    changed: list[str] = []
+    for tracking_key in state.tracked_files:
+        backup = target.tracked_backups.get(tracking_key)
+        if backup is None:
+            # 目标快照没有此文件的备份，找最早的备份
+            backup = _find_first_backup(state, tracking_key)
+            if backup is None:
+                continue
+
+        if backup.backup_name is None:
+            # 文件当时不存在：删除
+            p = Path(tracking_key)
+            if p.exists():
+                p.unlink()
+                changed.append(tracking_key)
+        else:
+            # 从备份恢复（备份内容 = 工具执行前的状态）
+            bpath = _backup_path(state.session_id, backup.backup_name)
+            if bpath.exists():
+                p = Path(tracking_key)
+                current_content = p.read_bytes() if p.exists() else None
+                backup_content = bpath.read_bytes()
+                if current_content != backup_content:
+                    p.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(bpath, tracking_key)
+                    changed.append(tracking_key)
+
+    # 移除目标快照及之后的所有快照
+    evicted = state.snapshots[target_idx:]
+    state.snapshots = state.snapshots[:target_idx]
+    _cleanup_evicted(state, evicted)
+
+    return changed
+
+
+def _find_first_backup(state: FileHistoryState, tracking_key: str) -> FileBackup | None:
+    """找到文件的最早备份。"""
+    for snap in state.snapshots:
+        backup = snap.tracked_backups.get(tracking_key)
+        if backup is not None:
+            return backup
+    return None
+
+
+def cleanup_file_history(session_id: str) -> None:
+    """删除指定会话的文件历史目录。"""
+    d = _backup_dir(session_id)
+    if d.exists():
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def cleanup_all_file_histories() -> int:
+    """删除所有文件历史目录，返回删除的目录数。"""
+    base = get_config_dir() / "file-history"
+    if not base.exists():
+        return 0
+    count = 0
+    for child in base.iterdir():
+        if child.is_dir():
+            shutil.rmtree(child, ignore_errors=True)
+            count += 1
+    # 如果 base 为空，删除它
+    try:
+        base.rmdir()
+    except OSError:
+        pass
+    return count
+
+
+def _cleanup_evicted(state: FileHistoryState, evicted: list[FileSnapshot]) -> None:
+    """清理被驱逐快照的孤立备份文件。"""
+    # 收集仍被引用的备份名
+    still_referenced: set[str] = set()
+    for snap in state.snapshots:
+        for backup in snap.tracked_backups.values():
+            if backup.backup_name:
+                still_referenced.add(backup.backup_name)
+
+    # 删除不再被引用的备份
+    for snap in evicted:
+        for backup in snap.tracked_backups.values():
+            if backup.backup_name and backup.backup_name not in still_referenced:
+                bpath = _backup_path(state.session_id, backup.backup_name)
+                try:
+                    bpath.unlink(missing_ok=True)
+                except OSError:
+                    pass

illusion/services/lsp/__init__.py

@@ -0,0 +1,455 @@
+"""
+轻量级代码智能辅助模块 — 用于 LSP 工具
+====================================
+
+本模块实现轻量级代码智能功能，比完整的语言服务器集成更小。
+为 Python 源文件提供稳定的只读操作，使模型能够执行类似 Claude Code 工作流程中的定义、引用、悬停和符号查询。
+
+主要功能：
+    - 列出文档符号
+    - 工作区符号搜索
+    - 跳转到定义
+    - 查找引用
+    - 悬停信息
+
+类说明：
+    - SymbolLocation: 符号位置数据类
+    - list_document_symbols: 列出文档符号
+    - workspace_symbol_search: 工作区符号搜索
+    - go_to_definition: 跳转到定义
+    - find_references: 查找引用
+    - hover: 悬停信息
+
+使用示例：
+    >>> from illusion.services.lsp import list_document_symbols, go_to_definition
+    >>> # 列出文件中的符号
+    >>> symbols = list_document_symbols(Path("src/main.py"))
+    >>> # 跳转到定义
+    >>> defs = go_to_definition(root=Path("."), file_path=Path("src/main.py"), symbol="my_function")
+"""
+
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# Python 文件模式
+_PYTHON_GLOB = "*.py"
+# 跳过的目录
+_SKIP_PARTS = {".git", ".hg", ".svn", ".venv", "venv", "__pycache__", "node_modules"}
+
+
+@dataclass(frozen=True)
+class SymbolLocation:
+    """工作区内的解析符号位置。"""
+
+    name: str
+    kind: str
+    path: Path
+    line: int
+    character: int
+    signature: str = ""
+    docstring: str = ""
+
+
+def list_document_symbols(path: Path) -> list[SymbolLocation]:
+    """从 Python 源文件中返回顶层和嵌套符号。"""
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    symbols: list[SymbolLocation] = []
+    _collect_symbols(tree, path, symbols, parent=None)
+    return symbols
+
+
+def workspace_symbol_search(root: Path, query: str) -> list[SymbolLocation]:
+    """返回名称包含 query 的符号。"""
+    needle = query.lower().strip()
+    if not needle:
+        return []
+    matches: list[SymbolLocation] = []
+    for file_path in iter_python_files(root):
+        for symbol in list_document_symbols(file_path):
+            if needle in symbol.name.lower():
+                matches.append(symbol)
+    return matches
+
+
+def go_to_definition(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> list[SymbolLocation]:
+    """解析符号的可能定义。"""
+    target = symbol or extract_symbol_at_position(file_path, line=line, character=character)
+    if not target:
+        return []
+    matches: list[SymbolLocation] = []
+    for candidate in iter_python_files(root):
+        for item in list_document_symbols(candidate):
+            if item.name == target:
+                matches.append(item)
+    return matches
+
+
+def find_references(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> list[tuple[Path, int, str]]:
+    """返回符号的行方向引用。"""
+    target = symbol or extract_symbol_at_position(file_path, line=line, character=character)
+    if not target:
+        return []
+    pattern = re.compile(rf"\b{re.escape(target)}\b")
+    matches: list[tuple[Path, int, str]] = []
+    for candidate in iter_python_files(root):
+        for lineno, raw_line in enumerate(candidate.read_text(encoding="utf-8").splitlines(), start=1):
+            if pattern.search(raw_line):
+                matches.append((candidate, lineno, raw_line.strip()))
+    return matches
+
+
+def hover(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> SymbolLocation | None:
+    """返回符号的最佳悬停目标。"""
+    matches = go_to_definition(
+        root=root,
+        file_path=file_path,
+        symbol=symbol,
+        line=line,
+        character=character,
+    )
+    return matches[0] if matches else None
+
+
+def extract_symbol_at_position(
+    file_path: Path,
+    *,
+    line: int | None,
+    character: int | None,
+) -> str | None:
+    """从 1 基数的行/字符位置提取可能的标识符。"""
+    if line is None:
+        return None
+    lines = file_path.read_text(encoding="utf-8").splitlines()
+    if line < 1 or line > len(lines):
+        return None
+    text = lines[line - 1]
+    if not text:
+        return None
+    index = max(0, min((character or 1) - 1, len(text) - 1))
+    for match in re.finditer(r"[A-Za-z_][A-Za-z0-9_]*", text):
+        if match.start() <= index < match.end():
+            return match.group(0)
+    for match in re.finditer(r"[A-Za-z_][A-Za-z0-9_]*", text):
+        return match.group(0)
+    return None
+
+
+def go_to_implementation(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> list[SymbolLocation]:
+    """查找类或方法的子类实现。
+
+    对于类：查找继承该类的子类。
+    对于方法：查找子类中重写该方法的位置。
+    """
+    target = symbol or extract_symbol_at_position(file_path, line=line, character=character)
+    if not target:
+        return []
+
+    is_method = "." in target
+    base_class = target.split(".")[0] if is_method else target
+    method_name = target.split(".")[-1] if is_method else None
+
+    matches: list[SymbolLocation] = []
+    for candidate in iter_python_files(root):
+        tree = ast.parse(candidate.read_text(encoding="utf-8"), filename=str(candidate))
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                for base in node.bases:
+                    base_name = _get_ast_name(base)
+                    if base_name and (base_name == base_class or base_name.endswith(f".{base_class}")):
+                        if method_name:
+                            for child in ast.iter_child_nodes(node):
+                                if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)) and child.name == method_name:
+                                    matches.append(SymbolLocation(
+                                        name=f"{node.name}.{child.name}",
+                                        kind="method",
+                                        path=candidate,
+                                        line=child.lineno,
+                                        character=child.col_offset + 1,
+                                        signature=f"def {child.name}(...)",
+                                        docstring=ast.get_docstring(child) or "",
+                                    ))
+                        else:
+                            matches.append(SymbolLocation(
+                                name=node.name,
+                                kind="class",
+                                path=candidate,
+                                line=node.lineno,
+                                character=node.col_offset + 1,
+                                signature=f"class {node.name}",
+                                docstring=ast.get_docstring(node) or "",
+                            ))
+    return matches
+
+
+def prepare_call_hierarchy(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> SymbolLocation | None:
+    """获取指定位置的调用层次节点。"""
+    target = symbol or extract_symbol_at_position(file_path, line=line, character=character)
+    if not target:
+        return None
+    matches = go_to_definition(root=root, file_path=file_path, symbol=target)
+    return matches[0] if matches else None
+
+
+def incoming_calls(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> list[tuple[Path, int, str, str]]:
+    """查找所有调用指定函数/方法的位置。
+
+    返回 (调用文件, 行号, 调用者函数名, 行文本) 列表。
+    """
+    target = symbol or extract_symbol_at_position(file_path, line=line, character=character)
+    if not target:
+        return []
+
+    # 方法名称可能包含类前缀，调用时只用方法名
+    call_name = target.split(".")[-1]
+
+    results: list[tuple[Path, int, str, str]] = []
+    for candidate in iter_python_files(root):
+        try:
+            tree = ast.parse(candidate.read_text(encoding="utf-8"), filename=str(candidate))
+        except SyntaxError:
+            continue
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                callee = _get_ast_name(node.func)
+                if callee == target or callee == call_name:
+                    caller = _find_enclosing_def(tree, node.lineno)
+                    results.append((candidate, node.lineno, caller or "(module level)", _get_source_line(candidate, node.lineno)))
+    return results
+
+
+def outgoing_calls(
+    *,
+    root: Path,
+    file_path: Path,
+    symbol: str | None = None,
+    line: int | None = None,
+    character: int | None = None,
+) -> list[tuple[str, Path, int]]:
+    """查找指定函数/方法内部调用的所有函数。
+
+    返回 (被调用名, 定义文件, 行号) 列表。
+    """
+    target = symbol or extract_symbol_at_position(file_path, line=line, character=character)
+    if not target:
+        return []
+
+    tree = ast.parse(file_path.read_text(encoding="utf-8"), filename=str(file_path))
+    func_node = _find_func_node(tree, target)
+    if func_node is None:
+        return []
+
+    seen: set[str] = set()
+    results: list[tuple[str, Path, int]] = []
+    for node in ast.walk(func_node):
+        if node is func_node:
+            continue
+        if isinstance(node, ast.Call):
+            callee = _get_ast_name(node.func)
+            if callee and callee not in seen:
+                seen.add(callee)
+                # 尝试找到被调用函数的定义位置
+                defs = go_to_definition(root=root, file_path=file_path, symbol=callee)
+                if defs:
+                    results.append((callee, defs[0].path, defs[0].line))
+                else:
+                    results.append((callee, Path(), 0))
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# 内部辅助函数
+# ---------------------------------------------------------------------------
+
+
+def _get_ast_name(node: ast.AST) -> str | None:
+    """从 AST 节点提取名称字符串（支持 a.b.c 形式的属性访问）。"""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        inner = _get_ast_name(node.value)
+        if inner is not None:
+            return f"{inner}.{node.attr}"
+        return node.attr
+    return None
+
+
+def _find_enclosing_def(tree: ast.AST, lineno: int) -> str | None:
+    """按行号查找所在的函数/类定义名。"""
+    best: str | None = None
+    best_end: int = -1
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            end = node.end_lineno or node.lineno
+            if node.lineno <= lineno <= end and end > best_end:
+                best_end = end
+                best = node.name
+    return best
+
+
+def _find_func_node(tree: ast.AST, target: str) -> ast.FunctionDef | ast.AsyncFunctionDef | None:
+    """在 AST 树中按名称或 ClassName.method 形式查找函数节点。"""
+    parts = target.split(".")
+    func_name = parts[-1]
+    class_name = parts[0] if len(parts) >= 2 else None
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.name == func_name:
+                if class_name:
+                    # 检查是否在正确的类内
+                    for parent in ast.walk(tree):
+                        if isinstance(parent, ast.ClassDef) and parent.name == class_name:
+                            # 检查 node 是否是 parent 的子节点
+                            for child in ast.walk(parent):
+                                if child is node:
+                                    return node
+                else:
+                    return node
+    return None
+
+
+def _get_source_line(file_path: Path, lineno: int) -> str:
+    """读取文件指定行的文本。"""
+    try:
+        lines = file_path.read_text(encoding="utf-8").splitlines()
+        if 1 <= lineno <= len(lines):
+            return lines[lineno - 1].strip()
+    except OSError:
+        pass
+    return ""
+
+
+def iter_python_files(root: Path) -> list[Path]:
+    """按稳定顺序返回 Python 源文件列表。"""
+    files: list[Path] = []
+    for path in root.rglob(_PYTHON_GLOB):
+        if any(part in _SKIP_PARTS for part in path.parts):
+            continue
+        if path.is_file():
+            files.append(path)
+    files.sort()
+    return files
+
+
+def _collect_symbols(
+    node: ast.AST,
+    path: Path,
+    bucket: list[SymbolLocation],
+    *,
+    parent: str | None,
+) -> None:
+    """递归收集 AST 中的符号。"""
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # 函数定义
+            name = f"{parent}.{child.name}" if parent else child.name
+            args = [arg.arg for arg in child.args.args]
+            signature = f"def {child.name}({', '.join(args)})"
+            bucket.append(
+                SymbolLocation(
+                    name=name,
+                    kind="function",
+                    path=path,
+                    line=child.lineno,
+                    character=child.col_offset + 1,
+                    signature=signature,
+                    docstring=ast.get_docstring(child) or "",
+                )
+            )
+            _collect_symbols(child, path, bucket, parent=name)
+        elif isinstance(child, ast.ClassDef):
+            # 类定义
+            name = f"{parent}.{child.name}" if parent else child.name
+            bucket.append(
+                SymbolLocation(
+                    name=name,
+                    kind="class",
+                    path=path,
+                    line=child.lineno,
+                    character=child.col_offset + 1,
+                    signature=f"class {child.name}",
+                    docstring=ast.get_docstring(child) or "",
+                )
+            )
+            _collect_symbols(child, path, bucket, parent=name)
+        elif isinstance(child, ast.Assign):
+            # 变量赋值
+            for target in child.targets:
+                if isinstance(target, ast.Name):
+                    name = f"{parent}.{target.id}" if parent else target.id
+                    bucket.append(
+                        SymbolLocation(
+                            name=name,
+                            kind="variable",
+                            path=path,
+                            line=target.lineno,
+                            character=target.col_offset + 1,
+                            signature=f"{target.id} = ...",
+                        )
+                    )
+        else:
+            _collect_symbols(child, path, bucket, parent=parent)
+
+
+__all__ = [
+    "SymbolLocation",
+    "extract_symbol_at_position",
+    "find_references",
+    "go_to_definition",
+    "go_to_implementation",
+    "hover",
+    "incoming_calls",
+    "iter_python_files",
+    "list_document_symbols",
+    "outgoing_calls",
+    "prepare_call_hierarchy",
+    "workspace_symbol_search",
+]