jarvis-ai-assistant 0.1.222__py3-none-any.whl → 0.7.0__py3-none-any.whl

jarvis/jarvis_c2rust/optimizer.py

@@ -0,0 +1,960 @@
+# -*- coding: utf-8 -*-
+"""
+Rust 代码优化器：对转译或生成后的 Rust 项目执行若干保守优化步骤。
+
+目标与策略（保守、可回退）:
+1) unsafe 清理：
+   - 识别可移除的 `unsafe { ... }` 包裹，尝试移除后执行 `cargo check`
+   - 若编译失败，回滚该处修改，并在该块或相邻函数前添加 `/// SAFETY: ` 说明
+2) 代码结构优化（重复代码提示/最小消除）：
+   - 基于文本的简单函数重复检测（签名 + 主体文本），为重复体添加 TODO 文档提示
+   - 在 CodeAgent 阶段，允许最小化抽取公共辅助函数以消除重复（若易于安全完成）
+3) 可见性优化（尽可能最小可见性）：
+   - 对 `pub fn` 尝试降为 `pub(crate) fn`，变更后执行 `cargo check` 验证
+   - 若失败回滚
+   - 在 CodeAgent 阶段，允许在不破坏 API 的前提下进一步减少可见性（保持对外接口为 pub）
+4) 文档补充：
+   - 为缺少文档的模块/函数添加基础占位文档
+
+实现说明：
+- 以文件为粒度进行优化，每次微小变更均伴随 cargo check 进行验证
+- 所有修改保留最小必要的文本变动，失败立即回滚
+- 结果摘要与日志输出到 <crate_dir>/.jarvis/c2rust/optimize_report.json
+- 进度记录（断点续跑）：<crate_dir>/.jarvis/c2rust/optimize_progress.json
+  - 字段 processed: 已优化完成的文件（相对 crate 根的路径，posix 斜杠）
+
+限制：
+- 未依赖 rust-analyzer/LSP，主要使用静态文本 + `cargo check` 验证
+- 复杂语法与宏、条件编译等情况下可能存在漏检或误判，将尽量保守处理
+- 提供 CodeAgent 驱动的“整体优化”阶段，参考 transpiler 的 CodeAgent 使用方式；该阶段输出补丁并进行一次 cargo check 验证
+
+使用入口：
+- optimize_project(crate_dir: Optional[Path], ...) 作为对外简单入口
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple, Iterable, Set
+import fnmatch
+
+# 引入 CodeAgent（参考 transpiler）
+from jarvis.jarvis_code_agent.code_agent import CodeAgent
+
+
+@dataclass
+class OptimizeOptions:
+    enable_unsafe_cleanup: bool = True
+    enable_structure_opt: bool = True
+    enable_visibility_opt: bool = True
+    enable_doc_opt: bool = True
+    max_checks: int = 0  # 0 表示不限；用于限制 cargo check 次数（防止过慢）
+    dry_run: bool = False
+    # 大项目分批优化控制
+    include_patterns: Optional[str] = None  # 逗号分隔的 glob，相对 crate 根（支持 src/**.rs）
+    exclude_patterns: Optional[str] = None  # 逗号分隔的 glob
+    max_files: int = 0  # 本次最多处理的文件数（0 不限）
+    resume: bool = True  # 断点续跑：跳过已处理文件
+    reset_progress: bool = False  # 重置进度（清空 processed 列表）
+    build_fix_retries: int = 3  # 构建失败时的修复重试次数
+    # Git 保护：优化前快照 commit，失败时自动 reset 回快照
+    git_guard: bool = True
+    llm_group: Optional[str] = None
+    cargo_test_timeout: int = 300  # cargo test 超时（秒）
+    non_interactive: bool = True
+
+
+@dataclass
+class OptimizeStats:
+    files_scanned: int = 0
+    unsafe_removed: int = 0
+    unsafe_annotated: int = 0
+    duplicates_tagged: int = 0
+    visibility_downgraded: int = 0
+    docs_added: int = 0
+    cargo_checks: int = 0
+    errors: List[str] = None
+
+    def __post_init__(self):
+        if self.errors is None:
+            self.errors = []
+
+
+def _run_cmd(cmd: List[str], cwd: Path, env: Optional[Dict[str, str]] = None, timeout: Optional[int] = None) -> Tuple[int, str, str]:
+    p = subprocess.Popen(
+        cmd,
+        cwd=str(cwd),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        env=dict(os.environ, **(env or {})),
+    )
+    try:
+        out, err = p.communicate(timeout=timeout if timeout and timeout > 0 else None)
+        return p.returncode, out, err
+    except subprocess.TimeoutExpired:
+        p.kill()
+        out, err = p.communicate()
+        err_msg = f"Command '{' '.join(cmd)}' timed out after {timeout} seconds."
+        if err:
+            err_msg += f"\n{err}"
+        return -1, out, err_msg
+
+
+def _cargo_check(crate_dir: Path, stats: OptimizeStats, max_checks: int, timeout: Optional[int] = None) -> Tuple[bool, str]:
+    # 统一使用 cargo test 作为验证手段
+    if max_checks and stats.cargo_checks >= max_checks:
+        return False, "cargo test budget exhausted"
+    code, out, err = _run_cmd(["cargo", "test", "-q"], crate_dir, timeout=timeout)
+    stats.cargo_checks += 1
+    ok = code == 0
+    diag = err.strip() or out.strip()
+    # 取首行作为摘要
+    first_line = next((ln for ln in diag.splitlines() if ln.strip()), "")
+    return ok, first_line
+
+def _cargo_check_full(crate_dir: Path, stats: OptimizeStats, max_checks: int, timeout: Optional[int] = None) -> Tuple[bool, str]:
+    """
+    执行 cargo test，返回是否成功与完整输出（stdout+stderr）。
+    会计入 stats.cargo_checks，并受 max_checks 预算限制。
+    """
+    if max_checks and stats.cargo_checks >= max_checks:
+        return False, "cargo test budget exhausted"
+    try:
+        res = subprocess.run(
+            ["cargo", "test", "-q"],
+            capture_output=True,
+            text=True,
+            check=False,
+            cwd=str(crate_dir),
+            timeout=timeout if timeout and timeout > 0 else None,
+        )
+        stats.cargo_checks += 1
+        ok = (res.returncode == 0)
+        out = (res.stdout or "")
+        err = (res.stderr or "")
+        msg = (out + ("\n" + err if err else "")).strip()
+        return ok, msg
+    except subprocess.TimeoutExpired as e:
+        stats.cargo_checks += 1
+        out_s = e.stdout.decode("utf-8", errors="ignore") if e.stdout else ""
+        err_s = e.stderr.decode("utf-8", errors="ignore") if e.stderr else ""
+        msg = f"cargo test timed out after {timeout} seconds"
+        full_output = (out_s + ("\n" + err_s if err_s else "")).strip()
+        if full_output:
+            msg += f"\nOutput:\n{full_output}"
+        return False, msg
+    except Exception as e:
+        stats.cargo_checks += 1
+        return False, f"cargo test exception: {e}"
+
+def _git_is_repo(root: Path) -> bool:
+    try:
+        code, out, err = _run_cmd(["git", "rev-parse", "--is-inside-work-tree"], root)
+        return code == 0 and (out.strip() == "true" or (not out.strip() and "true" in (err or "")))
+    except Exception:
+        return False
+
+def _git_toplevel(start: Path) -> Optional[Path]:
+    """
+    返回包含 start 的 Git 仓库根目录（--show-toplevel）。若不在仓库中则返回 None。
+    """
+    try:
+        code, out, err = _run_cmd(["git", "rev-parse", "--show-toplevel"], start)
+        if code == 0:
+            p = (out or "").strip()
+            if p:
+                return Path(p)
+        return None
+    except Exception:
+        return None
+
+def _git_head_commit(root: Path) -> Optional[str]:
+    try:
+        code, out, err = _run_cmd(["git", "rev-parse", "--verify", "HEAD"], root)
+        if code == 0:
+            return out.strip()
+        return None
+    except Exception:
+        return None
+
+def _git_reset_hard(root: Path, commit: str) -> bool:
+    try:
+        code, _, _ = _run_cmd(["git", "reset", "--hard", commit], root)
+        if code != 0:
+            return False
+        return True
+    except Exception:
+        return False
+
+
+def _iter_rust_files(crate_dir: Path) -> Iterable[Path]:
+    src = crate_dir / "src"
+    if not src.exists():
+        # 仍尝试遍历整个 crate 目录，但优先 src
+        yield from crate_dir.rglob("*.rs")
+        return
+    # 遍历 src 优先
+    yield from src.rglob("*.rs")
+
+
+def _read_file(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def _write_file(path: Path, content: str) -> None:
+    path.write_text(content, encoding="utf-8")
+
+
+def _backup_file(path: Path) -> Path:
+    bak = path.with_suffix(path.suffix + ".bak_opt")
+    shutil.copy2(path, bak)
+    return bak
+
+
+def _restore_file_from_backup(path: Path, backup: Path) -> None:
+    shutil.move(str(backup), str(path))
+
+
+def _remove_backup(backup: Path) -> None:
+    if backup.exists():
+        backup.unlink(missing_ok=True)
+
+
+def _ensure_report_dir(crate_dir: Path) -> Path:
+    report_dir = crate_dir / ".jarvis" / "c2rust"
+    report_dir.mkdir(parents=True, exist_ok=True)
+    return report_dir
+
+
+def detect_crate_dir(preferred: Optional[Path]) -> Path:
+    """
+    选择 crate 目录策略：
+    - 若提供 preferred 且包含 Cargo.toml，则使用
+    - 否则：优先 <cwd>/<cwd.name>_rs；若存在 Cargo.toml 则用之
+    - 否则：在当前目录下递归寻找第一个包含 Cargo.toml 的目录
+    - 若失败：若当前目录有 Cargo.toml 则返回当前目录，否则抛错
+    """
+    if preferred:
+        preferred = preferred.resolve()
+        if (preferred / "Cargo.toml").exists():
+            return preferred
+
+    cwd = Path(".").resolve()
+    candidate = cwd / f"{cwd.name}_rs"
+    if (candidate / "Cargo.toml").exists():
+        return candidate
+
+    # 搜索第一个包含 Cargo.toml 的目录（限制深度2以避免过慢）
+    for p in [cwd] + [d for d in cwd.iterdir() if d.is_dir()]:
+        if (p / "Cargo.toml").exists():
+            return p
+
+    if (cwd / "Cargo.toml").exists():
+        return cwd
+    raise FileNotFoundError("未找到 Cargo.toml，对应 crate 目录无法确定。")
+
+
+class Optimizer:
+    def __init__(self, crate_dir: Path, options: OptimizeOptions):
+        self.crate_dir = crate_dir
+        self.options = options
+        self.stats = OptimizeStats()
+        # 进度文件
+        self.report_dir = _ensure_report_dir(self.crate_dir)
+        self.progress_path = self.report_dir / "optimize_progress.json"
+        self.processed: Set[str] = set()
+        self._target_files: List[Path] = []
+        self._load_or_reset_progress()
+        self._last_snapshot_commit: Optional[str] = None
+        self.log_prefix = "[c2rust-优化器]"
+
+    def _snapshot_commit(self) -> None:
+        """
+        在启用 git_guard 时记录当前 HEAD commit（仅记录，不提交未暂存更改）。
+        统一在仓库根目录执行 git 命令，避免子目录导致的意外。
+        """
+        if not self.options.git_guard:
+            return
+        try:
+            repo_root = _git_toplevel(self.crate_dir)
+            if repo_root is None:
+                return
+            head = _git_head_commit(repo_root)
+            if head:
+                self._last_snapshot_commit = head
+        except Exception:
+            # 忽略快照失败，不阻塞流程
+            pass
+
+    def _reset_to_snapshot(self) -> bool:
+        """
+        在启用 git_guard 且存在快照时，将工作区 reset --hard 回快照。
+        统一在仓库根目录执行 git 命令，避免子目录导致的意外。
+        返回是否成功执行 reset。
+        """
+        if not self.options.git_guard:
+            return False
+        snap = getattr(self, "_last_snapshot_commit", None)
+        if not snap:
+            return False
+        repo_root = _git_toplevel(self.crate_dir)
+        if repo_root is None:
+            return False
+        ok = _git_reset_hard(repo_root, snap)
+        return ok
+
+    # ---------- 进度管理与文件选择 ----------
+
+    def _load_or_reset_progress(self) -> None:
+        if self.options.reset_progress:
+            try:
+                self.progress_path.write_text(json.dumps({"processed": []}, ensure_ascii=False, indent=2), encoding="utf-8")
+            except Exception:
+                pass
+            self.processed = set()
+            return
+        try:
+            if self.progress_path.exists():
+                obj = json.loads(self.progress_path.read_text(encoding="utf-8"))
+                if isinstance(obj, dict):
+                    arr = obj.get("processed") or []
+                    if isinstance(arr, list):
+                        self.processed = {str(x) for x in arr if isinstance(x, str)}
+                    else:
+                        self.processed = set()
+        except Exception:
+            self.processed = set()
+
+    def _save_progress_for_batch(self, files: List[Path]) -> None:
+        try:
+            rels = []
+            for p in files:
+                try:
+                    rel = p.resolve().relative_to(self.crate_dir.resolve()).as_posix()
+                except Exception:
+                    rel = str(p)
+                rels.append(rel)
+            self.processed.update(rels)
+            data = {"processed": sorted(self.processed)}
+            self.progress_path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+        except Exception:
+            pass
+
+    def _parse_patterns(self, s: Optional[str]) -> List[str]:
+        if not s or not isinstance(s, str):
+            return []
+        parts = [x.strip() for x in s.replace("\n", ",").split(",")]
+        return [x for x in parts if x]
+
+    def _match_any(self, rel: str, patterns: List[str]) -> bool:
+        if not patterns:
+            return False
+        return any(fnmatch.fnmatch(rel, pat) for pat in patterns)
+
+    def _compute_target_files(self) -> List[Path]:
+        include = self._parse_patterns(self.options.include_patterns)
+        exclude = self._parse_patterns(self.options.exclude_patterns)
+        maxn = int(self.options.max_files or 0)
+        take: List[Path] = []
+        for p in sorted(_iter_rust_files(self.crate_dir), key=lambda x: x.as_posix()):
+            try:
+                rel = p.resolve().relative_to(self.crate_dir.resolve()).as_posix()
+            except Exception:
+                rel = p.as_posix()
+            # include 过滤（若提供，则必须命中其一）
+            if include and not self._match_any(rel, include):
+                continue
+            # exclude 过滤
+            if exclude and self._match_any(rel, exclude):
+                continue
+            # resume：跳过已处理文件
+            if self.options.resume and rel in self.processed:
+                continue
+            take.append(p)
+            if maxn > 0 and len(take) >= maxn:
+                break
+        self._target_files = take
+        return take
+
+    # ---------- 主运行入口 ----------
+
+    def run(self) -> OptimizeStats:
+        report_path = self.report_dir / "optimize_report.json"
+        print(f"{self.log_prefix} 开始优化 Crate: {self.crate_dir}")
+        try:
+            # 计算本次批次的目标文件列表（按 include/exclude/resume/max_files）
+            targets = self._compute_target_files()
+            if not targets:
+                # 无文件可处理：仍然写出报告并返回
+                print(f"{self.log_prefix} 根据当前选项，无新文件需要处理。")
+                pass
+            else:
+                print(f"{self.log_prefix} 本次批次发现 {len(targets)} 个待处理文件。")
+                # 批次开始前记录快照
+                self._snapshot_commit()
+
+                if self.options.enable_unsafe_cleanup:
+                    # 步骤前快照
+                    print(f"\n{self.log_prefix} 第 1 步：unsafe 清理")
+                    self._snapshot_commit()
+                    self._opt_unsafe_cleanup(targets)
+                    # Step build verification
+                    if not self.options.dry_run:
+                        print(f"{self.log_prefix} unsafe 清理后，正在验证构建...")
+                        ok, diag_full = _cargo_check_full(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+                        if not ok:
+                            # 循环最小修复
+                            fixed = self._build_fix_loop(targets)
+                            if not fixed:
+                                first = (diag_full.splitlines()[0] if isinstance(diag_full, str) and diag_full else "failed")
+                                self.stats.errors.append(f"test after unsafe_cleanup failed: {first}")
+                                # 回滚到快照并结束
+                                try:
+                                    self._reset_to_snapshot()
+                                finally:
+                                    return self.stats
+
+                if self.options.enable_structure_opt:
+                    # 步骤前快照
+                    print(f"\n{self.log_prefix} 第 2 步：结构优化 (重复代码检测)")
+                    self._snapshot_commit()
+                    self._opt_structure_duplicates(targets)
+                    # Step build verification
+                    if not self.options.dry_run:
+                        print(f"{self.log_prefix} 结构优化后，正在验证构建...")
+                        ok, diag_full = _cargo_check_full(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+                        if not ok:
+                            fixed = self._build_fix_loop(targets)
+                            if not fixed:
+                                first = (diag_full.splitlines()[0] if isinstance(diag_full, str) and diag_full else "failed")
+                                self.stats.errors.append(f"test after structure_opt failed: {first}")
+                                try:
+                                    self._reset_to_snapshot()
+                                finally:
+                                    return self.stats
+
+                if self.options.enable_visibility_opt:
+                    # 步骤前快照
+                    print(f"\n{self.log_prefix} 第 3 步：可见性优化")
+                    self._snapshot_commit()
+                    self._opt_visibility(targets)
+                    # Step build verification
+                    if not self.options.dry_run:
+                        print(f"{self.log_prefix} 可见性优化后，正在验证构建...")
+                        ok, diag_full = _cargo_check_full(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+                        if not ok:
+                            fixed = self._build_fix_loop(targets)
+                            if not fixed:
+                                first = (diag_full.splitlines()[0] if isinstance(diag_full, str) and diag_full else "failed")
+                                self.stats.errors.append(f"test after visibility_opt failed: {first}")
+                                try:
+                                    self._reset_to_snapshot()
+                                finally:
+                                    return self.stats
+
+                if self.options.enable_doc_opt:
+                    # 步骤前快照
+                    print(f"\n{self.log_prefix} 第 4 步：文档补充")
+                    self._snapshot_commit()
+                    self._opt_docs(targets)
+                    # Step build verification
+                    if not self.options.dry_run:
+                        print(f"{self.log_prefix} 文档补充后，正在验证构建...")
+                        ok, diag_full = _cargo_check_full(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+                        if not ok:
+                            fixed = self._build_fix_loop(targets)
+                            if not fixed:
+                                first = (diag_full.splitlines()[0] if isinstance(diag_full, str) and diag_full else "failed")
+                                self.stats.errors.append(f"test after doc_opt failed: {first}")
+                                try:
+                                    self._reset_to_snapshot()
+                                finally:
+                                    return self.stats
+
+                # CodeAgent 驱动的整体优化（参考 transpiler 使用模式）
+                # 在静态优化后执行一次 CodeAgent 以最小化进一步提升（可选：dry_run 时跳过）
+                if not self.options.dry_run:
+                    try:
+                        print(f"\n{self.log_prefix} 第 5 步：CodeAgent 整体优化")
+                        self._codeagent_optimize_crate(targets)
+                    except Exception as _e:
+                        self.stats.errors.append(f"codeagent: {_e}")
+
+                # 标记本批次文件为“已处理”
+                self._save_progress_for_batch(targets)
+
+        except Exception as e:
+            self.stats.errors.append(f"fatal: {e}")
+        finally:
+            # 写出简要报告
+            print(f"{self.log_prefix} 优化流程结束。报告已生成于: {report_path.relative_to(Path.cwd())}")
+            try:
+                _write_file(report_path, json.dumps(asdict(self.stats), ensure_ascii=False, indent=2))
+            except Exception:
+                pass
+        return self.stats
+
+    # ========== 1) unsafe cleanup ==========
+
+    _re_unsafe_block = re.compile(r"\bunsafe\s*\{", re.MULTILINE)
+
+    def _opt_unsafe_cleanup(self, files: List[Path]) -> None:
+        for i, path in enumerate(files):
+            try:
+                rel_path = path.relative_to(self.crate_dir)
+            except ValueError:
+                rel_path = path
+            print(f"{self.log_prefix} [unsafe 清理] 正在处理文件 {i + 1}/{len(files)}: {rel_path}")
+            try:
+                content = _read_file(path)
+            except Exception:
+                continue
+            self.stats.files_scanned += 1
+
+            # 简单逐处尝试：每次仅移除一个 unsafe 以保持回滚粒度
+            pos = 0
+            while True:
+                m = self._re_unsafe_block.search(content, pos)
+                if not m:
+                    break
+
+                # 准备试移除（仅移除 "unsafe " 关键字，保留后续块）
+                start, end = m.span()
+                trial = content[:start] + "{" + content[end:]  # 将 "unsafe {" 替换为 "{"
+
+                if self.options.dry_run:
+                    # 仅统计
+                    self.stats.unsafe_removed += 1  # 计为潜在可移除
+                    pos = start + 1
+                    continue
+
+                # 备份并写入尝试版
+                bak = _backup_file(path)
+                try:
+                    _write_file(path, trial)
+                    ok, diag = _cargo_check(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+                    if ok:
+                        # 保留修改
+                        content = trial
+                        self.stats.unsafe_removed += 1
+                        # 不需要移动 pos 太多，继续搜索后续位置
+                        pos = start + 1
+                    else:
+                        # 回滚，并在 unsafe 前添加说明
+                        _restore_file_from_backup(path, bak)
+                        content = _read_file(path)  # 还原后的内容
+                        self._annotate_safety_comment(path, content, start, diag)
+                        # 重新读取注释后的文本，以便继续
+                        content = _read_file(path)
+                        self.stats.unsafe_annotated += 1
+                        pos = start + 1
+                finally:
+                    _remove_backup(bak)
+
+            # 若最后的 content 与磁盘不同步（dry_run 时不会），这里无需写回
+
+    def _annotate_safety_comment(self, path: Path, content: str, unsafe_pos: int, diag: str) -> None:
+        """
+        在 unsafe 块前注入一行文档注释，格式：
+        /// SAFETY: 自动清理失败，保留 unsafe。原因摘要: <diag>
+        """
+        # 寻找 unsafe 所在行首
+        line_start = content.rfind("\n", 0, unsafe_pos)
+        if line_start == -1:
+            insert_at = 0
+        else:
+            insert_at = line_start + 1
+
+        annotation = f'/// SAFETY: 自动清理失败，保留 unsafe。原因摘要: {diag}\n'
+        new_content = content[:insert_at] + annotation + content[insert_at:]
+
+        if not self.options.dry_run:
+            _write_file(path, new_content)
+
+    # ========== 2) structure duplicates ==========
+
+    _re_fn = re.compile(
+        r"(?P<leading>\s*(?:pub(?:\([^\)]*\))?\s+)?(?:async\s+)?(?:unsafe\s+)?(?:extern\s+\"[^\"]*\"\s+)?fn\s+"
+        r"(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\([^)]*\)\s*(?:->\s*[^ \t\r\n\{]+)?\s*)\{",
+        re.MULTILINE,
+    )
+
+    def _opt_structure_duplicates(self, files: List[Path]) -> None:
+        # 建立函数签名+主体的简易哈希，重复则为后出现者添加 TODO 注释
+        print(f"{self.log_prefix} [结构优化] 正在扫描 {len(files)} 个文件以查找重复函数...")
+        seen: Dict[str, Tuple[Path, int]] = {}
+        for path in files:
+            try:
+                content = _read_file(path)
+            except Exception:
+                continue
+
+            for m in self._re_fn.finditer(content):
+                name = m.group("name")
+                body_start = m.end() - 1  # at '{'
+                body_end = self._find_matching_brace(content, body_start)
+                if body_end is None:
+                    continue
+                sig = m.group(0)[: m.group(0).rfind("{")].strip()
+                body = content[body_start: body_end + 1]
+                key = f"{name}::{self._normalize_ws(sig)}::{self._normalize_ws(body)}"
+                if key not in seen:
+                    seen[key] = (path, m.start())
+                else:
+                    # 重复：在该函数前添加 TODO
+                    if self.options.dry_run:
+                        self.stats.duplicates_tagged += 1
+                        continue
+                    bak = _backup_file(path)
+                    try:
+                        insert_pos = content.rfind("\n", 0, m.start())
+                        insert_at = 0 if insert_pos == -1 else insert_pos + 1
+                        origin_path, _ = seen[key]
+                        try:
+                            origin_rel = origin_path.resolve().relative_to(self.crate_dir.resolve()).as_posix()
+                        except Exception:
+                            origin_rel = origin_path.as_posix()
+                        todo = f'/// TODO: duplicate of {origin_rel}::{name}\n'
+                        new_content = content[:insert_at] + todo + content[insert_at:]
+                        _write_file(path, new_content)
+                        content = new_content
+                        self.stats.duplicates_tagged += 1
+                    finally:
+                        _remove_backup(bak)
+
+    def _find_matching_brace(self, s: str, open_pos: int) -> Optional[int]:
+        """
+        给定 s[open_pos] == '{'，返回匹配的 '}' 位置；简单计数器，忽略字符串/注释的复杂性（保守）
+        """
+        if open_pos >= len(s) or s[open_pos] != "{":
+            return None
+        depth = 0
+        for i in range(open_pos, len(s)):
+            if s[i] == "{":
+                depth += 1
+            elif s[i] == "}":
+                depth -= 1
+                if depth == 0:
+                    return i
+        return None
+
+    def _normalize_ws(self, s: str) -> str:
+        return re.sub(r"\s+", " ", s).strip()
+
+    # ========== 3) visibility optimization ==========
+
+    _re_pub_fn = re.compile(
+        r"(?P<prefix>\s*)pub\s+fn\s+(?P<name>[A-Za-z_][A-Za-z0-9_]*)\s*\(",
+        re.MULTILINE,
+    )
+
+    def _opt_visibility(self, files: List[Path]) -> None:
+        for i, path in enumerate(files):
+            try:
+                rel_path = path.relative_to(self.crate_dir)
+            except ValueError:
+                rel_path = path
+            print(f"{self.log_prefix} [可见性优化] 正在处理文件 {i + 1}/{len(files)}: {rel_path}")
+            try:
+                content = _read_file(path)
+            except Exception:
+                continue
+
+            for m in list(self._re_pub_fn.finditer(content)):
+                start, end = m.span()
+                name = m.group("name")
+                candidate = content[:start] + f"{m.group('prefix')}pub(crate) fn {name}(" + content[end:]
+                if self.options.dry_run:
+                    self.stats.visibility_downgraded += 1
+                    continue
+                bak = _backup_file(path)
+                try:
+                    _write_file(path, candidate)
+                    ok, _ = _cargo_check(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+                    if ok:
+                        content = candidate
+                        self.stats.visibility_downgraded += 1
+                    else:
+                        _restore_file_from_backup(path, bak)
+                        content = _read_file(path)
+                finally:
+                    _remove_backup(bak)
+
+    # ========== 4) doc augmentation ==========
+
+    _re_mod_doc = re.compile(r"(?m)^\s*//!")  # 顶部模块文档
+    _re_any_doc = re.compile(r"(?m)^\s*///")
+
+    def _opt_docs(self, files: List[Path]) -> None:
+        for i, path in enumerate(files):
+            try:
+                rel_path = path.relative_to(self.crate_dir)
+            except ValueError:
+                rel_path = path
+            print(f"{self.log_prefix} [文档补充] 正在处理文件 {i + 1}/{len(files)}: {rel_path}")
+            try:
+                content = _read_file(path)
+            except Exception:
+                continue
+
+            changed = False
+            # 模块级文档：若文件开头不是文档，补充
+            if not self._re_mod_doc.search(content[:500]):  # 仅检查开头部分
+                header = "//! TODO: Add module-level documentation\n"
+                content = header + content
+                changed = True
+                self.stats.docs_added += 1
+
+            # 函数文档：为未有文档注释的函数前补充
+            new_content = []
+            last_end = 0
+            for m in self._re_fn.finditer(content):
+                fn_start = m.start()
+                # 检查前一行是否有 /// 文档
+                line_start = content.rfind("\n", 0, fn_start)
+                prev_line_start = content.rfind("\n", 0, line_start - 1) if line_start > 0 else -1
+                segment_start = last_end
+                segment_end = line_start + 1 if line_start != -1 else 0
+                new_content.append(content[segment_start:segment_end])
+
+                doc_exists = False
+                if line_start != -1:
+                    prev_line = content[prev_line_start + 1: line_start] if prev_line_start != -1 else content[:line_start]
+                    if self._re_any_doc.search(prev_line):
+                        doc_exists = True
+
+                if not doc_exists:
+                    new_content.append("/// TODO: Add documentation\n")
+                    changed = True
+                    self.stats.docs_added += 1
+
+                new_content.append(content[segment_end: m.end()])  # 包含到函数体起始的部分
+                last_end = m.end()
+
+            new_content.append(content[last_end:])
+            new_s = "".join(new_content)
+
+            if changed and not self.options.dry_run:
+                _write_file(path, new_s)
+
+    # ========== 5) CodeAgent 整体优化（参考 transpiler 的 CodeAgent 使用方式） ==========
+
+    def _codeagent_optimize_crate(self, target_files: List[Path]) -> None:
+        """
+        使用 CodeAgent 对 crate 进行一次保守的整体优化，输出补丁并进行一次 cargo check 验证。
+        仅限本批次的目标文件（target_files）范围内进行修改，以支持大项目分批优化。
+        包含：
+        - unsafe 清理与 SAFETY 注释补充（范围最小化）
+        - 重复代码最小消除（允许抽取公共辅助函数），或添加 TODO 标注
+        - 可见性最小化（尽量使用 pub(crate)，保持对外接口为 pub）
+        - 文档补充（模块/函数缺失文档添加占位）
+        约束：
+        - 保持最小改动，避免大范围重构或格式化
+        - 不得删除公开 API；跨 crate 接口保持 pub
+        - 仅在 crate_dir 下进行修改（Cargo.toml、src/**/*.rs）；不得改动其他目录
+        - 仅输出补丁（由 CodeAgent 控制），不输出解释
+        """
+        crate = self.crate_dir.resolve()
+        file_list: List[str] = []
+        for p in target_files:
+            try:
+                rel = p.resolve().relative_to(crate).as_posix()
+            except Exception:
+                rel = p.as_posix()
+            file_list.append(rel)
+
+        prompt_lines: List[str] = [
+            "你是资深 Rust 代码工程师。请在当前 crate 下执行一次保守的整体优化，并以补丁形式输出修改：",
+            f"- crate 根目录：{crate}",
+            "",
+            "本次优化仅允许修改以下文件范围（严格限制）：",
+            *[f"- {rel}" for rel in file_list],
+            "",
+            "优化目标（按优先级）：",
+            "1) unsafe 清理：",
+            "   - 移除不必要的 unsafe 包裹；若必须使用 unsafe，缩小范围并在紧邻位置添加 `/// SAFETY: ...` 文档注释说明理由。",
+            "2) 代码结构优化（重复消除/提示）：",
+            "   - 检测重复函数实现（签名+主体近似），如能安全抽取公共辅助函数进行复用，进行最小化重构；否则在重复处添加 `/// TODO: duplicate of ...` 注释。",
+            "3) 可见性优化：",
+            "   - 优先将 `pub fn` 降为 `pub(crate) fn`；保持对外接口（跨 crate 使用的接口）为 `pub`；在 lib.rs 中的顶层导出保持现状。",
+            "4) 文档补充：",
+            "   - 为缺少模块/函数文档的位置添加占位注释（//! 或 ///）。",
+            "",
+            "约束与范围：",
+            "- 仅修改上述列出的文件；除非必须（如修复引用路径），否则不要修改其他文件。",
+            "- 保持最小改动，不要进行与上述优化无关的重构或格式化。",
+            "- 修改后需保证 `cargo test` 可以通过；如需引入少量配套改动，请一并包含在补丁中以确保通过。",
+            "- 输出仅为补丁，不要输出解释或多余文本。",
+            "",
+            "自检要求：在每次输出补丁后，请使用 execute_script 工具在 crate 根目录执行 `cargo test -q` 进行验证；",
+            "若未通过，请继续输出新的补丁进行最小修复并再次自检，直至 `cargo test` 通过为止。"
+        ]
+        prompt = "\n".join(prompt_lines)
+        prev_cwd = os.getcwd()
+        print(f"{self.log_prefix} [CodeAgent] 正在调用 CodeAgent 进行整体优化...")
+        try:
+            os.chdir(str(crate))
+            agent = CodeAgent(need_summary=False, non_interactive=self.options.non_interactive, plan=False, model_group=self.options.llm_group)
+            agent.run(prompt, prefix="[c2rust-optimizer][codeagent]", suffix="")
+        finally:
+            os.chdir(prev_cwd)
+        # 运行一次 cargo check 验证；若失败则进入本地最小修复循环
+        ok, diag = _cargo_check_full(self.crate_dir, self.stats, self.options.max_checks, timeout=self.options.cargo_test_timeout)
+        if not ok:
+            fixed = self._build_fix_loop(target_files)
+            if not fixed:
+                first = (diag.splitlines()[0] if isinstance(diag, str) and diag else "failed")
+                self.stats.errors.append(f"codeagent test failed: {first}")
+                try:
+                    self._reset_to_snapshot()
+                finally:
+                    return
+
+    def _build_fix_loop(self, scope_files: List[Path]) -> bool:
+        """
+        循环执行 cargo check 并用 CodeAgent 进行最小修复，直到通过或达到重试上限或检查预算耗尽。
+        仅允许（优先）修改 scope_files（除非确有必要），以支持分批优化。
+        返回 True 表示修复成功构建通过；False 表示未能在限制内修复。
+        """
+        maxr = int(self.options.build_fix_retries or 0)
+        if maxr <= 0:
+            return False
+        crate = self.crate_dir.resolve()
+        allowed: List[str] = []
+        for p in scope_files:
+            try:
+                rel = p.resolve().relative_to(crate).as_posix()
+            except Exception:
+                rel = p.as_posix()
+            allowed.append(rel)
+
+        attempt = 0
+        while True:
+            # 检查预算
+            if self.options.max_checks and self.stats.cargo_checks >= self.options.max_checks:
+                return False
+            # 执行构建
+            output = ""
+            try:
+                res = subprocess.run(
+                    ["cargo", "test", "-q"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                    cwd=str(crate),
+                    timeout=self.options.cargo_test_timeout if self.options.cargo_test_timeout > 0 else None,
+                )
+                self.stats.cargo_checks += 1
+                if res.returncode == 0:
+                    print(f"{self.log_prefix} 构建修复成功。")
+                    return True
+                output = ((res.stdout or "") + ("\n" + (res.stderr or ""))).strip()
+            except subprocess.TimeoutExpired as e:
+                self.stats.cargo_checks += 1
+                out_s = e.stdout.decode("utf-8", errors="ignore") if e.stdout else ""
+                err_s = e.stderr.decode("utf-8", errors="ignore") if e.stderr else ""
+                output = f"cargo test timed out after {self.options.cargo_test_timeout} seconds"
+                full_output = (out_s + ("\n" + err_s if err_s else "")).strip()
+                if full_output:
+                    output += f"\nOutput:\n{full_output}"
+            except Exception as e:
+                self.stats.cargo_checks += 1
+                output = f"cargo test exception: {e}"
+
+            # 达到重试上限则失败
+            attempt += 1
+            if attempt > maxr:
+                print(f"{self.log_prefix} 构建修复重试次数已用尽。")
+                return False
+
+            print(f"{self.log_prefix} 构建失败。正在尝试使用 CodeAgent 进行修复 (第 {attempt}/{maxr} 次尝试)...")
+            # 生成最小修复提示
+            prompt_lines = [
+                "请根据以下测试/构建错误对 crate 进行最小必要的修复以通过 `cargo test`：",
+                f"- crate 根目录：{crate}",
+                "",
+                "本次修复优先且仅允许修改以下文件（除非确有必要，否则不要修改范围外文件）：",
+                *[f"- {rel}" for rel in allowed],
+                "",
+                "约束与范围：",
+                "- 保持最小改动，不要进行与错误无关的重构或格式化；",
+                "- 仅输出补丁，不要输出解释或多余文本。",
+                "",
+                "自检要求：在每次输出补丁后，请使用 execute_script 工具在 crate 根目录执行 `cargo test -q` 进行验证；",
+                "若未通过，请继续输出新的补丁进行最小修复并再次自检，直至 `cargo test` 通过为止。",
+                "",
+                "构建错误如下：",
+                "<BUILD_ERROR>",
+                output,
+                "</BUILD_ERROR>",
+            ]
+            prompt = "\n".join(prompt_lines)
+            prev_cwd = os.getcwd()
+            try:
+                os.chdir(str(crate))
+                agent = CodeAgent(need_summary=False, non_interactive=self.options.non_interactive, plan=False, model_group=self.options.llm_group)
+                agent.run(prompt, prefix=f"[c2rust-optimizer][build-fix iter={attempt}]", suffix="")
+            finally:
+                os.chdir(prev_cwd)
+
+        return False
+
+def optimize_project(
+    crate_dir: Optional[Path] = None,
+    enable_unsafe_cleanup: bool = True,
+    enable_structure_opt: bool = True,
+    enable_visibility_opt: bool = True,
+    enable_doc_opt: bool = True,
+    max_checks: int = 0,
+    dry_run: bool = False,
+    include_patterns: Optional[str] = None,
+    exclude_patterns: Optional[str] = None,
+    max_files: int = 0,
+    resume: bool = True,
+    reset_progress: bool = False,
+    build_fix_retries: int = 3,
+    git_guard: bool = True,
+    llm_group: Optional[str] = None,
+    cargo_test_timeout: int = 300,
+    non_interactive: bool = True,
+) -> Dict:
+    """
+    对指定 crate 执行优化。返回结果摘要 dict。
+    - crate_dir: crate 根目录（包含 Cargo.toml）；为 None 时自动检测
+    - enable_*: 各优化步骤开关
+    - max_checks: 限制 cargo check 调用次数（0 不限）
+    - dry_run: 不写回，仅统计潜在修改
+    - include_patterns/exclude_patterns: 逗号分隔的 glob；相对 crate 根（如 src/**/*.rs）
+    - max_files: 本次最多处理文件数（0 不限）
+    - resume: 启用断点续跑（跳过已处理文件）
+    - reset_progress: 清空进度（processed 列表）
+    """
+    crate = detect_crate_dir(crate_dir)
+    opts = OptimizeOptions(
+        enable_unsafe_cleanup=enable_unsafe_cleanup,
+        enable_structure_opt=enable_structure_opt,
+        enable_visibility_opt=enable_visibility_opt,
+        enable_doc_opt=enable_doc_opt,
+        max_checks=max_checks,
+        dry_run=dry_run,
+        include_patterns=include_patterns,
+        exclude_patterns=exclude_patterns,
+        max_files=max_files,
+        resume=resume,
+        reset_progress=reset_progress,
+        build_fix_retries=build_fix_retries,
+        git_guard=git_guard,
+        llm_group=llm_group,
+        cargo_test_timeout=cargo_test_timeout,
+        non_interactive=non_interactive,
+    )
+    optimizer = Optimizer(crate, opts)
+    stats = optimizer.run()
+    return asdict(stats)