jarvis-ai-assistant 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

jarvis/jarvis_c2rust/cli.py

@@ -0,0 +1,405 @@
+# -*- coding: utf-8 -*-
+"""
+C2Rust 独立命令行入口。
+
+提供分组式 CLI，将扫描能力作为子命令 scan 暴露：
+  - jarvis-c2rust scan --root <path> [--dot ...] [--only-dot] [--subgraphs-dir ...] [--only-subgraphs] [--png]
+
+实现策略：
+- 复用 scanner.cli 的核心逻辑，避免重复代码。
+- 使用 Typer 分组式结构，便于后续扩展更多子命令（如 analyze/export 等）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, List
+
+import typer
+from jarvis.jarvis_c2rust.scanner import run_scan as _run_scan
+from jarvis.jarvis_c2rust.scanner import (
+    compute_translation_order_jsonl as _compute_order,
+)
+from jarvis.jarvis_c2rust.library_replacer import (
+    apply_library_replacement as _apply_library_replacement,
+)
+from jarvis.jarvis_utils.utils import init_env
+from jarvis.jarvis_c2rust.llm_module_agent import (
+    execute_llm_plan as _execute_llm_plan,
+    entries_to_yaml as _entries_to_yaml,
+)
+
+app = typer.Typer(help="C2Rust 命令行工具")
+
+# 显式定义根回调，确保为命令组而非单函数入口
+@app.callback()
+def _root():
+    """
+    C2Rust 命令行工具
+    """
+    # 不做任何处理，仅作为命令组的占位，使 'scan' 作为子命令出现
+    init_env("欢迎使用 Jarvis C2Rust 工具")
+    pass
+
+
+@app.command("scan")
+def scan(
+    dot: Optional[Path] = typer.Option(
+        None,
+        "--dot",
+        help="扫描后将引用依赖图写入 DOT 文件（或与 --only-dot 一起使用）",
+    ),
+    only_dot: bool = typer.Option(
+        False,
+        "--only-dot",
+        help="不重新扫描。读取现有数据 (JSONL) 并仅生成 DOT（需要 --dot）",
+    ),
+    subgraphs_dir: Optional[Path] = typer.Option(
+        None,
+        "--subgraphs-dir",
+        help="用于写入每个根函数引用子图 DOT 文件的目录（每个根函数一个文件）",
+    ),
+    only_subgraphs: bool = typer.Option(
+        False,
+        "--only-subgraphs",
+        help="不重新扫描。仅生成每个根函数的引用子图 DOT 文件（需要 --subgraphs-dir）",
+    ),
+) -> None:
+    """
+    进行 C/C++ 函数扫描并生成引用关系 DOT 图；PNG 渲染默认启用（无需参数）。
+    """
+    _run_scan(
+        dot=dot,
+        only_dot=only_dot,
+        subgraphs_dir=subgraphs_dir,
+        only_subgraphs=only_subgraphs,
+        png=True,
+    )
+
+@app.command("prepare")
+def prepare(
+    llm_group: Optional[str] = typer.Option(
+        None, "-g", "--llm-group", help="指定用于规划的 LLM 模型组（仅影响本次运行）"
+    ),
+) -> None:
+    """
+    使用 LLM Agent 基于根函数子图规划 Rust crate 模块结构并直接应用到磁盘。
+    需先执行: jarvis-c2rust scan 以生成数据文件（symbols.jsonl）
+    默认使用当前目录作为项目根，并从 <root>/.jarvis/c2rust/symbols.jsonl 读取数据
+    """
+    try:
+        _execute_llm_plan(apply=True, llm_group=llm_group)
+    except Exception as e:
+        typer.secho(f"[c2rust-llm-planner] 错误: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command("transpile")
+def transpile(
+    llm_group: Optional[str] = typer.Option(
+        None, "-g", "--llm-group", help="指定用于翻译的 LLM 模型组"
+    ),
+    only: Optional[str] = typer.Option(
+        None, "--only", help="仅翻译指定的函数（名称或限定名称），以逗号分隔"
+    ),
+) -> None:
+    """
+    使用转译器按扫描顺序逐个函数转译并构建修复。
+    需先执行: jarvis-c2rust scan 以生成数据文件（symbols.jsonl 与 translation_order.jsonl）
+    默认使用当前目录作为项目根，并从 <root>/.jarvis/c2rust/symbols.jsonl 读取数据。
+    未指定目标 crate 时，使用默认 <cwd>/<cwd.name>_rs。
+    """
+    try:
+        # Lazy import to avoid hard dependency if not used
+        from jarvis.jarvis_c2rust.transpiler import run_transpile as _run_transpile
+        only_list = [s.strip() for s in str(only).split(",") if s.strip()] if only else None
+        _run_transpile(
+            project_root=Path("."),
+            crate_dir=None,
+            llm_group=llm_group,
+            only=only_list,
+        )
+    except Exception as e:
+        typer.secho(f"[c2rust-transpiler] 错误: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command("lib-replace")
+def lib_replace(
+    llm_group: Optional[str] = typer.Option(
+        None, "-g", "--llm-group", help="用于评估的 LLM 模型组"
+    ),
+    root_list_file: Optional[Path] = typer.Option(
+        None, "--root-list-file", help="根列表文件：按行列出要参与评估的根符号名称或限定名（忽略空行与以#开头的注释）"
+    ),
+    root_list_syms: Optional[str] = typer.Option(
+        None, "--root-list-syms", help="根列表内联：以逗号分隔的符号名称或限定名（仅评估这些根）"
+    ),
+    disabled_libs: Optional[str] = typer.Option(
+        None, "--disabled-libs", help="禁用库列表：逗号分隔的库名（评估时禁止使用这些库）"
+    ),
+) -> None:
+    """
+    Root-list 评估模式（必须走 LLM 评估）：
+    - 必须提供根列表（--root-list-file 或 --root-list-syms，至少一种）
+    - 仅对根列表中的符号作为评估根执行 LLM 子树评估
+    - 若可替代：替换该根的 ref 为库占位，并剪除其所有子孙函数（根本身保留）
+    - 需先执行: jarvis-c2rust scan 以生成数据文件（symbols.jsonl）
+    - 默认库: std（仅用于对后续流程保持一致的默认上下文）
+    - 可选：--disabled-libs 指定评估时禁止使用的库列表（逗号分隔）
+    """
+    try:
+        data_dir = Path(".") / ".jarvis" / "c2rust"
+        curated_symbols = data_dir / "symbols.jsonl"
+        raw_symbols = data_dir / "symbols_raw.jsonl"
+        if not curated_symbols.exists() and not raw_symbols.exists():
+            typer.secho("[c2rust-lib-replace] 未找到符号数据（symbols.jsonl 或 symbols_raw.jsonl），正在执行扫描以生成数据...", fg=typer.colors.YELLOW)
+            _run_scan(dot=None, only_dot=False, subgraphs_dir=None, only_subgraphs=False, png=False)
+            if not curated_symbols.exists() and not raw_symbols.exists():
+                raise FileNotFoundError(f"未找到符号数据: {curated_symbols} 或 {raw_symbols}")
+
+        # 使用默认库: std
+        library = "std"
+
+        # 读取根列表（必填，至少提供一种来源）
+        root_names: List[str] = []
+        # 文件来源
+        if root_list_file is not None:
+            try:
+                txt = root_list_file.read_text(encoding="utf-8")
+                root_names.extend([ln.strip() for ln in txt.splitlines() if ln.strip() and not ln.strip().startswith("#")])
+            except Exception as _e:
+                typer.secho(f"[c2rust-lib-replace] 读取根列表失败: {root_list_file}: {_e}", fg=typer.colors.RED, err=True)
+                raise typer.Exit(code=1)
+        # 内联来源
+        if isinstance(root_list_syms, str) and root_list_syms.strip():
+            parts = [s.strip() for s in root_list_syms.replace("\n", ",").split(",") if s.strip()]
+            root_names.extend(parts)
+        # 去重
+        try:
+            root_names = list(dict.fromkeys(root_names))
+        except Exception:
+            root_names = sorted(list(set(root_names)))
+        if not root_names:
+            typer.secho("[c2rust-lib-replace] 错误：必须提供根列表（--root-list-file 或 --root-list-syms）。", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=2)
+
+        # 解析禁用库列表（可选）
+        disabled_list: Optional[List[str]] = None
+        if isinstance(disabled_libs, str) and disabled_libs.strip():
+            disabled_list = [s.strip() for s in disabled_libs.replace("\n", ",").split(",") if s.strip()]
+            if disabled_list:
+                typer.secho(f"[c2rust-lib-replace] 禁用库: {', '.join(disabled_list)}", fg=typer.colors.YELLOW)
+
+        # 必须走 LLM 评估：仅评估提供的根（candidates），不启用强制剪枝模式
+        ret = _apply_library_replacement(
+            db_path=Path("."),
+            library_name=library,
+            llm_group=llm_group,
+            candidates=root_names,          # 仅评估这些根
+            out_symbols_path=None,
+            out_mapping_path=None,
+            max_funcs=None,
+            disabled_libraries=disabled_list,
+        )
+        # 输出简要结果摘要（底层已写出新的符号表与可选转译顺序）
+        try:
+            order_msg = f"\n[c2rust-lib-replace] 转译顺序: {ret['order']}" if 'order' in ret else ""
+            typer.secho(
+                f"[c2rust-lib-replace] 替代映射: {ret['mapping']}\n"
+                f"[c2rust-lib-replace] 新符号表: {ret['symbols']}"
+                + order_msg,
+                fg=typer.colors.GREEN,
+            )
+        except Exception as _e:
+            typer.secho(f"[c2rust-lib-replace] 结果输出时发生非致命错误: {_e}", fg=typer.colors.YELLOW, err=True)
+    except Exception as e:
+        typer.secho(f"[c2rust-lib-replace] 错误: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
+
+@app.command("collect")
+def collect(
+    files: List[Path] = typer.Argument(..., help="一个或多个 C/C++ 头文件路径（.h/.hh/.hpp/.hxx）"),
+    out: Path = typer.Option(..., "-o", "--out", help="输出文件路径（写入唯一函数名，每行一个）"),
+) -> None:
+    """
+    收集指定头文件中的函数名（使用 libclang 解析），并写入指定输出文件（每行一个）。
+    示例:
+      jarvis-c2rust collect a.h b.hpp -o funcs.txt
+    说明:
+      非头文件会被跳过（仅支持 .h/.hh/.hpp/.hxx）。
+    """
+    try:
+        from jarvis.jarvis_c2rust.collector import collect_function_names as _collect_fn_names
+        _collect_fn_names(files=files, out_path=out)
+        typer.secho(f"[c2rust-collect] 函数名已写入: {out}", fg=typer.colors.GREEN)
+    except Exception as e:
+        typer.secho(f"[c2rust-collect] 错误: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+@app.command("run")
+def run(
+    files: Optional[List[Path]] = typer.Option(
+        None,
+        "--files",
+        help="用于 collect 阶段的头文件列表（.h/.hh/.hpp/.hxx）；提供则先执行 collect",
+    ),
+    out: Optional[Path] = typer.Option(
+        None,
+        "-o",
+        "--out",
+        help="collect 输出函数名文件；若未提供且指定 --files 则默认为 <root>/.jarvis/c2rust/roots.txt",
+    ),
+    llm_group: Optional[str] = typer.Option(
+        None,
+        "-g",
+        "--llm-group",
+        help="用于 LLM 相关阶段（lib-replace/prepare/transpile）的模型组",
+    ),
+    root_list_file: Optional[Path] = typer.Option(
+        None,
+        "--root-list-file",
+        help="兼容占位：run 会使用 collect 的 --out 作为 lib-replace 的输入；当提供 --files 时本参数将被忽略；未提供 --files 时，本命令要求使用 --root-list-syms",
+    ),
+    root_list_syms: Optional[str] = typer.Option(
+        None,
+        "--root-list-syms",
+        help="lib-replace 的根列表内联（逗号分隔）。未提供 --files 时该参数为必填",
+    ),
+    disabled_libs: Optional[str] = typer.Option(
+        None,
+        "--disabled-libs",
+        help="lib-replace 禁用库列表（逗号分隔）",
+    ),
+) -> None:
+    """
+    依次执行流水线：collect -> scan -> lib-replace -> prepare -> transpile
+
+    约束:
+    - collect 的输出文件就是 lib-replace 的输入文件；
+      当提供 --files 时，lib-replace 将固定读取 --out（或默认值）作为根列表文件，忽略 --root-list-file
+    - 未提供 --files 时，必须通过 --root-list-syms 提供根列表
+    - scan 始终执行以确保数据完整
+    - prepare/transpile 会使用 --llm-group 指定的模型组
+    """
+    try:
+        data_dir = Path(".") / ".jarvis" / "c2rust"
+        default_roots = data_dir / "roots.txt"
+
+        # Step 1: collect（可选）
+        roots_path: Optional[Path] = None
+        if files:
+            try:
+                if out is None:
+                    out = default_roots
+                out.parent.mkdir(parents=True, exist_ok=True)
+                from jarvis.jarvis_c2rust.collector import (
+                    collect_function_names as _collect_fn_names,
+                )
+                _collect_fn_names(files=files, out_path=out)
+                typer.secho(f"[c2rust-run] collect: 函数名已写入: {out}", fg=typer.colors.GREEN)
+                roots_path = out
+            except Exception as _e:
+                typer.secho(f"[c2rust-run] collect: 错误: {_e}", fg=typer.colors.RED, err=True)
+                raise
+
+        # Step 2: scan（始终执行）
+        typer.secho("[c2rust-run] scan: 开始", fg=typer.colors.BLUE)
+        _run_scan(dot=None, only_dot=False, subgraphs_dir=None, only_subgraphs=False, png=False)
+        typer.secho("[c2rust-run] scan: 完成", fg=typer.colors.GREEN)
+
+        # Step 3: lib-replace（强制执行，依据约束获取根列表）
+        root_names: List[str] = []
+
+        if files:
+            # 约束：collect 的输出文件作为唯一文件来源
+            if not roots_path or not roots_path.exists():
+                typer.secho("[c2rust-run] lib-replace: 未找到 collect 输出文件，无法继续", fg=typer.colors.RED, err=True)
+                raise typer.Exit(code=2)
+            try:
+                txt = roots_path.read_text(encoding="utf-8")
+                root_names.extend([ln.strip() for ln in txt.splitlines() if ln.strip() and not ln.strip().startswith("#")])
+                typer.secho(f"[c2rust-run] lib-replace: 使用根列表文件: {roots_path}", fg=typer.colors.BLUE)
+            except Exception as _e:
+                typer.secho(f"[c2rust-run] lib-replace: 读取根列表失败: {roots_path}: {_e}", fg=typer.colors.RED, err=True)
+                raise
+            # 兼容参数提示
+            if root_list_file is not None:
+                typer.secho("[c2rust-run] 提示: --root-list-file 已被忽略（run 会固定使用 collect 的 --out 作为输入）", fg=typer.colors.YELLOW)
+        else:
+            # 约束：未传递 files 必须提供 --root-list-syms
+            if not (isinstance(root_list_syms, str) and root_list_syms.strip()):
+                typer.secho("[c2rust-run] 错误：未提供 --files 时，必须通过 --root-list-syms 指定根列表（逗号分隔）", fg=typer.colors.RED, err=True)
+                raise typer.Exit(code=2)
+            parts = [s.strip() for s in root_list_syms.replace("\n", ",").split(",") if s.strip()]
+            root_names.extend(parts)
+
+        # 去重并校验非空
+        try:
+            root_names = list(dict.fromkeys(root_names))
+        except Exception:
+            root_names = sorted(list(set(root_names)))
+        if not root_names:
+            typer.secho("[c2rust-run] lib-replace: 根列表为空，无法继续", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=2)
+
+        # 可选禁用库列表
+        disabled_list: Optional[List[str]] = None
+        if isinstance(disabled_libs, str) and disabled_libs.strip():
+            disabled_list = [s.strip() for s in disabled_libs.replace("\n", ",").split(",") if s.strip()]
+            if disabled_list:
+                typer.secho(f"[c2rust-run] lib-replace: 禁用库: {', '.join(disabled_list)}", fg=typer.colors.YELLOW)
+
+        # 执行 lib-replace（默认库 std）
+        library = "std"
+        typer.secho(f"[c2rust-run] lib-replace: 开始（库: {library}，根数: {len(root_names)}）", fg=typer.colors.BLUE)
+        ret = _apply_library_replacement(
+            db_path=Path("."),
+            library_name=library,
+            llm_group=llm_group,
+            candidates=root_names,
+            out_symbols_path=None,
+            out_mapping_path=None,
+            max_funcs=None,
+            disabled_libraries=disabled_list,
+        )
+        try:
+            order_msg = f"\n[c2rust-run] lib-replace: 转译顺序: {ret['order']}" if 'order' in ret else ""
+            typer.secho(
+                f"[c2rust-run] lib-replace: 替代映射: {ret['mapping']}\n"
+                f"[c2rust-run] lib-replace: 新符号表: {ret['symbols']}"
+                + order_msg,
+                fg=typer.colors.GREEN,
+            )
+        except Exception as _e:
+            typer.secho(f"[c2rust-run] lib-replace: 结果输出时发生非致命错误: {_e}", fg=typer.colors.YELLOW, err=True)
+
+        # Step 4: prepare
+        typer.secho("[c2rust-run] prepare: 开始", fg=typer.colors.BLUE)
+        _execute_llm_plan(apply=True, llm_group=llm_group)
+        typer.secho("[c2rust-run] prepare: 完成", fg=typer.colors.GREEN)
+
+        # Step 5: transpile
+        typer.secho("[c2rust-run] transpile: 开始", fg=typer.colors.BLUE)
+        from jarvis.jarvis_c2rust.transpiler import run_transpile as _run_transpile
+        _run_transpile(
+            project_root=Path("."),
+            crate_dir=None,
+            llm_group=llm_group,
+            only=None,
+        )
+        typer.secho("[c2rust-run] transpile: 完成", fg=typer.colors.GREEN)
+    except Exception as e:
+        typer.secho(f"[c2rust-run] 错误: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
+def main() -> None:
+    """主入口"""
+    app()
+
+
+if __name__ == "__main__":
+    main()

jarvis/jarvis_c2rust/collector.py

@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+"""
+C/C++ 头文件函数名收集器（基于 libclang）。
+
+功能:
+- 接受一个或多个头文件路径（.h/.hh/.hpp/.hxx），使用 libclang 精确解析，收集这些头文件中声明或定义的函数名。
+- 优先输出限定名（qualified_name），回退到普通名称（name）。
+- 自动逐层向上查找 compile_commands.json（直到文件系统根目录）；若未找到则跳过并使用基础 -I 参数；失败时回退为空参数。
+- 自动为头文件设置语言选项 (-x c-header 或 -x c++-header)，提升解析成功率。
+
+输出:
+- 将唯一的函数名集合写入指定输出文件（每行一个函数名，UTF-8 编码）。
+
+与现有实现的关系:
+- 复用 jarvis.jarvis_c2rust.scanner 中的能力：
+  - _try_import_libclang: 兼容多版本 libclang 的加载器
+  - find_compile_commands / load_compile_commands: compile_commands.json 解析与逐层向上搜索
+  - get_qualified_name / is_function_like: 统一限定名生成和函数节点类型判断
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+# 复用 scanner 内的核心能力
+from jarvis.jarvis_c2rust.scanner import (  # type: ignore
+    _try_import_libclang,
+    find_compile_commands,
+    load_compile_commands,
+    get_qualified_name,
+    is_function_like,
+)
+
+
+HEADER_EXTS = {".h", ".hh", ".hpp", ".hxx"}
+
+
+def _resolve_compile_args_map(files: List[Path]) -> Dict[str, List[str]]:
+    """
+    逐文件尝试向上查找 compile_commands.json（直到根目录），并合并解析为:
+      file_abs_path_str -> compile_args(list[str])
+    若未找到任何 compile_commands.json，则返回空映射。
+    """
+    mapping: Dict[str, List[str]] = {}
+    visited_cc_paths: Set[Path] = set()
+
+    for f in files:
+        try:
+            cc_path = find_compile_commands(f.parent)
+        except Exception:
+            cc_path = None
+        if cc_path and cc_path.exists() and cc_path not in visited_cc_paths:
+            try:
+                m = load_compile_commands(cc_path)
+                if isinstance(m, dict):
+                    mapping.update(m)
+                visited_cc_paths.add(cc_path)
+            except Exception:
+                # ignore parse errors, continue searching next file's tree
+                pass
+
+    return mapping
+
+
+def _ensure_lang_header_args(file_path: Path, base_args: List[str]) -> List[str]:
+    """
+    确保为头文件设置合适的语言选项：
+    - C 头文件: -x c-header
+    - C++ 头文件: -x c++-header
+    若 base_args 已包含 -x，则尊重现有设置，不再强制覆盖。
+    """
+    args = list(base_args or [])
+    has_x = any(a == "-x" or a.startswith("-x") for a in args)
+    if has_x:
+        return args
+    ext = file_path.suffix.lower()
+    if ext in {".hpp", ".hxx", ".hh"}:
+        args.extend(["-x", "c++-header"])
+    else:
+        args.extend(["-x", "c-header"])
+    return args
+
+
+def _scan_header_for_names(cindex, file_path: Path, args: List[str]) -> List[str]:
+    """
+    扫描单个头文件，返回该文件中声明或定义的函数的限定名/名称列表。
+    - 不要求 is_definition()，以捕获函数原型声明
+    - 仅收集位于该文件本身的符号（根据 location.file 判断）
+    """
+    index = cindex.Index.create()
+    tu = index.parse(
+        str(file_path),
+        args=args,
+        options=0,
+    )
+    names: List[str] = []
+
+    def visit(node):
+        # 只收集属于当前文件的节点
+        loc_file = node.location.file
+        if loc_file is None or Path(loc_file.name).resolve() != file_path.resolve():
+            for ch in node.get_children():
+                visit(ch)
+            return
+
+        if is_function_like(node):
+            try:
+                qn = get_qualified_name(node)
+                nm = node.spelling or ""
+                label = (qn or nm or "").strip()
+                if label:
+                    names.append(label)
+            except Exception:
+                nm = (node.spelling or "").strip()
+                if nm:
+                    names.append(nm)
+
+        for ch in node.get_children():
+            visit(ch)
+
+    visit(tu.cursor)
+    return names
+
+
+def collect_function_names(
+    files: List[Path],
+    out_path: Path,
+) -> Path:
+    """
+    收集给定头文件中的函数名并写入指定文件。
+
+    参数:
+    - files: 一个或多个 C/C++ 头文件路径（.h/.hh/.hpp/.hxx）
+    - out_path: 输出文件路径（将创建目录）
+
+    返回:
+    - 写入的输出文件路径
+    """
+    if not files:
+        raise ValueError("必须至少提供一个头文件路径")
+
+    # 归一化与存在性检查，仅保留头文件
+    file_list: List[Path] = []
+    for p in files:
+        rp = Path(p).resolve()
+        if not rp.exists():
+            print(f"[c2rust-collector] 警告: 文件不存在，已跳过: {rp}")
+            continue
+        if not rp.is_file():
+            print(f"[c2rust-collector] 警告: 非普通文件，已跳过: {rp}")
+            continue
+        if rp.suffix.lower() not in HEADER_EXTS:
+            print(f"[c2rust-collector] 警告: 非头文件（仅支持 .h/.hh/.hpp/.hxx），已跳过: {rp}")
+            continue
+        file_list.append(rp)
+
+    if not file_list:
+        raise FileNotFoundError("提供的文件列表均不可用或不包含头文件（支持 .h/.hh/.hpp/.hxx）")
+
+    # 准备 libclang
+    cindex = _try_import_libclang()
+    if cindex is None:
+        # 与 scanner 的防御式处理保持一致：尽量不让 None 向下游传播
+        from clang import cindex as _ci  # type: ignore
+        cindex = _ci
+
+    # 预检 Index 创建
+    try:
+        _ = cindex.Index.create()
+    except Exception as e:
+        raise RuntimeError(f"libclang 初始化失败: {e}")
+
+    # 逐层向上自动查找 compile_commands.json，构建参数映射
+    cc_args_map = _resolve_compile_args_map(file_list)
+
+    # 收集唯一函数名（优先限定名）
+    names: Set[str] = set()
+
+    for f in file_list:
+        # 优先使用 compile_commands 的精确参数；若无则提供基础 -I 与头文件语言选项
+        base_args = cc_args_map.get(str(f), ["-I", str(f.parent)])
+        args = _ensure_lang_header_args(f, base_args)
+        try:
+            fn_names = _scan_header_for_names(cindex, f, args)
+        except Exception:
+            # 回退到无参数解析（仍添加语言选项）
+            try:
+                fn_names = _scan_header_for_names(cindex, f, _ensure_lang_header_args(f, []))
+            except Exception as e2:
+                print(f"[c2rust-collector] 解析失败，已跳过 {f}: {e2}")
+                continue
+
+        for label in fn_names:
+            if label:
+                names.add(label.strip())
+
+    # 写出结果
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with out_path.open("w", encoding="utf-8") as fo:
+            for nm in sorted(names):
+                fo.write(nm + "\n")
+    except Exception as e:
+        raise RuntimeError(f"写入输出文件失败: {out_path}: {e}")
+
+    print(f"[c2rust-collector] 已收集到 {len(names)} 个函数名（来自头文件） -> {out_path}")
+    return out_path