jarvis-ai-assistant 0.7.16__py3-none-any.whl → 1.0.2__py3-none-any.whl

jarvis/jarvis_c2rust/llm_module_agent_apply.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+"""LLM 模块规划 Agent 的项目结构应用模块。"""
+
+import re
+from pathlib import Path
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Set
+from typing import Union
+
+from jarvis.jarvis_c2rust.llm_module_agent_utils import parse_project_json_entries
+
+
+def ensure_pub_mod_declarations(existing_text: str, child_mods: List[str]) -> str:
+    """
+    在给定文本中确保存在并升级子模块声明为 `pub mod <name>;`：
+    - 解析已有的 `mod`/`pub mod`/`pub(...) mod` 声明；
+    - 已存在但非 pub 的同名声明就地升级为 `pub mod`，保留原行的缩进；
+    - 不存在的模块名则在末尾追加一行 `pub mod <name>;`；
+    - 返回更新后的完整文本（保留结尾换行）。
+    """
+    try:
+        lines = (existing_text or "").splitlines()
+    except Exception:
+        lines = []
+    mod_decl_pattern = re.compile(
+        r"^\s*(pub(?:\s*\([^)]+\))?\s+)?mod\s+([A-Za-z_][A-Za-z0-9_]*)\s*;\s*$"
+    )
+    name_to_indices: Dict[str, List[int]] = {}
+    name_has_pub: Set[str] = set()
+    for i, ln in enumerate(lines):
+        m = mod_decl_pattern.match(ln.strip())
+        if not m:
+            continue
+        mod_name = m.group(2)
+        name_to_indices.setdefault(mod_name, []).append(i)
+        if m.group(1):
+            name_has_pub.add(mod_name)
+    for mod_name in sorted(set(child_mods or [])):
+        if mod_name in name_to_indices:
+            if mod_name not in name_has_pub:
+                for idx in name_to_indices[mod_name]:
+                    ws_match = re.match(r"^(\s*)", lines[idx])
+                    leading_ws = ws_match.group(1) if ws_match else ""
+                    lines[idx] = f"{leading_ws}pub mod {mod_name};"
+        else:
+            lines.append(f"pub mod {mod_name};")
+    return "\n".join(lines).rstrip() + ("\n" if lines else "")
+
+
+def apply_entries_with_mods(entries: List[Any], base_path: Path) -> None:
+    """
+    根据解析出的 entries 创建目录与文件结构（不在此阶段写入/更新任何 Rust 源文件内容）：
+    - 对于目录项：创建目录，并递归创建其子项；
+    - 对于文件项：若不存在则创建空文件；
+    约束与约定：
+    - crate 根的 src 目录：不生成 src/mod.rs，也不写入 src/lib.rs 的模块声明；
+    - 非 src 目录：不创建或更新 mod.rs；如需创建 mod.rs，请在 YAML 中显式列出；
+    - 模块声明的补齐将在后续 CodeAgent 阶段完成（扫描目录结构并最小化补齐 pub mod 声明）。
+    """
+
+    def apply_item(item: Any, dir_path: Path) -> None:
+        if isinstance(item, str):
+            # 文件
+            file_path = dir_path / item
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            if not file_path.exists():
+                try:
+                    file_path.touch(exist_ok=True)
+                except Exception:
+                    pass
+            return
+
+        if isinstance(item, dict) and len(item) == 1:
+            dir_name, children = next(iter(item.items()))
+            name = str(dir_name).rstrip("/").strip()
+            new_dir = dir_path / name
+            new_dir.mkdir(parents=True, exist_ok=True)
+
+            child_mods: List[str] = []
+            # 是否为 crate 根下的 src 目录
+            is_src_root_dir = new_dir == base_path / "src"
+
+            # 先创建子项
+            for child in children or []:
+                if isinstance(child, str):
+                    apply_item(child, new_dir)
+                    # 收集 .rs 文件作为子模块
+                    if child.endswith(".rs") and child != "mod.rs":
+                        stem = Path(child).stem
+                        # 在 src 根目录下，忽略 lib.rs 与 main.rs 的自引用
+                        if is_src_root_dir and stem in ("lib", "main"):
+                            pass
+                        else:
+                            child_mods.append(stem)
+                    if child == "mod.rs":
+                        pass
+                elif isinstance(child, dict):
+                    # 子目录
+                    sub_name = list(child.keys())[0]
+                    sub_mod_name = str(sub_name).rstrip("/").strip()
+                    child_mods.append(sub_mod_name)
+                    apply_item(child, new_dir)
+
+            # 对 crate 根的 src 目录，使用 lib.rs 聚合子模块，不创建/更新 src/mod.rs
+            if is_src_root_dir:
+                # 不在 src 根目录写入任何文件内容；仅由子项创建对应空文件（如有）
+                return
+
+            # 非 src 目录：
+            # 为避免覆盖现有实现，当前阶段不创建或更新 mod.rs 内容。
+            # 如需创建 mod.rs，应在 JSON 中显式指定为文件项；
+            # 如需补齐模块声明，将由后续的 CodeAgent 阶段根据目录结构自动补齐。
+            return
+
+    for entry in entries:
+        apply_item(entry, base_path)
+
+
+def ensure_cargo_toml(base_dir: Path, package_name: str) -> None:
+    """
+    确保在 base_dir 下存在合理的 Cargo.toml：
+    - 如果不存在，则创建最小可用的 Cargo.toml，并设置 package.name = package_name
+    - 如果已存在，则不覆盖现有内容（避免误改）
+    """
+    cargo_path = base_dir / "Cargo.toml"
+    if cargo_path.exists():
+        return
+    try:
+        cargo_path.touch(exist_ok=True)
+    except (OSError, PermissionError):
+        # 如果无法创建文件，记录错误但不中断流程
+        # 后续 CodeAgent 可能会处理 Cargo.toml 的创建
+        pass
+
+
+def apply_project_structure_from_json(
+    json_text: str, project_root: Union[Path, str] = "."
+) -> None:
+    """
+    基于 Agent 返回的 <PROJECT> 中的目录结构 JSON，创建实际目录与文件（不在此阶段写入或更新任何 Rust 源文件内容）。
+    - project_root: 目标应用路径；当为 "."（默认）时，将使用"父目录/当前目录名_rs"作为crate根目录
+    注意：模块声明（mod/pub mod）补齐将在后续的 CodeAgent 步骤中完成。按新策略不再创建或更新 workspace（构建直接在 crate 目录内进行）。
+    """
+    entries, parse_error = parse_project_json_entries(json_text)
+    if parse_error:
+        raise ValueError(f"JSON解析失败: {parse_error}")
+    if not entries:
+        # 严格模式：解析失败直接报错并退出，由上层 CLI 捕获打印错误
+        raise ValueError("[c2rust-llm-planner] 从LLM输出解析目录结构失败。正在中止。")
+    requested_root = Path(project_root).resolve()
+    try:
+        cwd = Path(".").resolve()
+        if requested_root == cwd:
+            # 默认crate不能设置为 .，设置为 父目录/当前目录名_rs（与当前目录同级）
+            base_dir = cwd.parent / f"{cwd.name}_rs"
+        else:
+            base_dir = requested_root
+    except Exception:
+        base_dir = requested_root
+    base_dir.mkdir(parents=True, exist_ok=True)
+    # crate name 与目录名保持一致（用于 Cargo 包名，允许连字符）
+    crate_pkg_name = base_dir.name
+    apply_entries_with_mods(entries, base_dir)
+    # 确保 Cargo.toml 存在并设置包名
+    ensure_cargo_toml(base_dir, crate_pkg_name)
+
+    # 已弃用：不再将 crate 添加到 workspace（按新策略去除 workspace）
+    # 构建与工具运行将直接在 crate 目录内进行

jarvis/jarvis_c2rust/llm_module_agent_executor.py

@@ -0,0 +1,288 @@
+"""LLM 模块规划 Agent 的执行器。"""
+
+import os
+import subprocess
+
+from jarvis.jarvis_utils.output import PrettyOutput
+
+# -*- coding: utf-8 -*-
+from pathlib import Path
+from typing import List
+from typing import Optional
+from typing import Union
+
+from jarvis.jarvis_c2rust.llm_module_agent_apply import (
+    apply_project_structure_from_json,
+)
+from jarvis.jarvis_c2rust.llm_module_agent_utils import parse_project_json_entries
+from jarvis.jarvis_c2rust.llm_module_agent_utils import resolve_created_dir
+
+
+def execute_llm_plan(
+    out: Optional[Union[Path, str]] = None,
+    apply: bool = False,
+    crate_name: Optional[Union[Path, str]] = None,
+    llm_group: Optional[str] = None,
+    non_interactive: bool = True,
+) -> List:
+    """
+    返回 LLM 生成的目录结构原始 JSON 文本（来自 <PROJECT> 块）。
+    不进行解析，便于后续按原样应用并在需要时使用更健壮的解析器处理。
+    """
+    # execute_llm_plan 是顶层入口，需要执行清理（skip_cleanup=False）
+    # 延迟导入以避免循环依赖
+    from jarvis.jarvis_c2rust.llm_module_agent import plan_crate_json_text
+
+    json_text = plan_crate_json_text(llm_group=llm_group, skip_cleanup=False)
+    entries, parse_error = parse_project_json_entries(json_text)
+    if parse_error:
+        raise ValueError(f"JSON解析失败: {parse_error}")
+    if not entries:
+        raise ValueError("[c2rust-llm-planner] 从LLM输出解析目录结构失败。正在中止。")
+
+    # 2) 如需应用到磁盘
+    if apply:
+        target_root = crate_name if crate_name else "."
+        try:
+            apply_project_structure_from_json(json_text, project_root=target_root)
+            PrettyOutput.auto_print("[c2rust-llm-planner] 项目结构已应用。")
+        except Exception as e:
+            PrettyOutput.auto_print(f"[c2rust-llm-planner] 应用项目结构失败: {e}")
+            raise
+
+        # Post-apply: 检查生成的目录结构，使用 CodeAgent 更新 Cargo.toml
+        from jarvis.jarvis_code_agent.code_agent import (
+            CodeAgent,
+        )  # 延迟导入以避免全局耦合
+
+        # 解析 crate 目录路径（与 apply 逻辑保持一致）
+        try:
+            created_dir = resolve_created_dir(target_root)
+        except Exception:
+            # 兜底：无法解析时直接使用传入的 target_root
+            created_dir = Path(target_root)
+
+        # 在 crate 目录内执行 git 初始化与初始提交（按新策略）
+        try:
+            # 初始化 git 仓库（若已存在则该命令为幂等）
+            subprocess.run(["git", "init"], check=False, cwd=str(created_dir))
+            # 添加所有文件并尝试提交
+            subprocess.run(["git", "add", "-A"], check=False, cwd=str(created_dir))
+            subprocess.run(
+                ["git", "commit", "-m", "[c2rust-llm-planner] init crate"],
+                check=False,
+                cwd=str(created_dir),
+            )
+        except Exception:
+            # 保持稳健，不因 git 失败影响主流程
+            pass
+
+        # 构建用于 CodeAgent 的目录上下文（简化版树形）
+        def _format_tree(root: Path) -> str:
+            lines: List[str] = []
+            exclude = {".git", "target", ".jarvis"}
+            if not root.exists():
+                return ""
+            for p in sorted(root.rglob("*")):
+                if any(part in exclude for part in p.parts):
+                    continue
+                rel = p.relative_to(root)
+                depth = len(rel.parts) - 1
+                indent = "  " * depth
+                name = rel.name + ("/" if p.is_dir() else "")
+                lines.append(f"{indent}- {name}")
+            return "\n".join(lines)
+
+        dir_ctx = _format_tree(created_dir)
+        crate_pkg_name = created_dir.name
+
+        requirement_lines = [
+            "目标：在该 crate 目录下确保 `cargo build` 能成功完成；如失败则根据错误最小化修改并重试，直到构建通过为止。",
+            f"- crate_dir: {created_dir}",
+            f"- crate_name: {crate_pkg_name}",
+            "目录结构（部分）：",
+            dir_ctx,
+            "",
+            "执行与修复流程（务必按序执行，可多轮迭代）：",
+            "1) 先补齐 Rust 模块声明（仅最小化追加/升级，不覆盖业务实现）：",
+            "   - 扫描 src 目录：",
+            "     * 在每个子目录下（除 src 根）创建或更新 mod.rs，仅追加缺失的 `pub mod <child>;` 声明；",
+            "     * 在 src/lib.rs 中为顶级子模块追加 `pub mod <name>;`；不要创建 src/mod.rs；忽略 lib.rs 与 main.rs 的自引用；",
+            "   - 若存在 `mod <name>;` 但非 pub，则就地升级为 `pub mod <name>;`，保留原缩进与其他内容；",
+            "   - 严禁删除现有声明或修改非声明代码；",
+            '2) 在 Cargo.toml 的 [package] 中设置 edition："2024"；若本地工具链不支持 2024，请降级为 "2021" 并在说明中记录原因；保留其他已有字段与依赖不变。',
+            "3) 根据当前源代码实际情况配置入口：",
+            "   - 仅库：仅配置 [lib]（path=src/lib.rs），不要生成 main.rs；",
+            "   - 单一可执行：存在 src/main.rs 时配置 [[bin]] 或默认二进制；可选保留 [lib] 以沉淀共享逻辑；",
+            "   - 多可执行：为每个 src/bin/<name>.rs 配置 [[bin]]；共享代码放在 src/lib.rs；",
+            "   - 不要创建与目录结构不一致的占位入口。",
+            "4) 对被作为入口的源文件：若不存在 fn main() 则仅添加最小可用实现（不要改动已存在的实现）：",
+            '   fn main() { println!("ok"); }',
+            "5) 执行一次构建验证：`cargo build -q`（或 `cargo check -q`）。",
+            "6) 若构建失败，读取错误并进行最小化修复，然后再次构建；重复直至成功。仅允许的修复类型：",
+            "   - 依赖缺失：在 [dependencies] 中添加必要且稳定版本的依赖（优先无特性），避免新增未使用依赖；",
+            "   - 入口/crate-type 配置错误：修正 [lib] 或 [[bin]] 的 name/path/crate-type 使之与目录与入口文件一致；",
+            "   - 语言/工具链不兼容：将 edition 从 2024 调整为 2021；必要时可添加 rust-version 要求；",
+            "   - 语法级/最小实现缺失：仅在入口文件中补充必要的 use/空实现/feature gate 以通过编译，避免改动非入口业务文件；",
+            "   - 不要删除或移动现有文件与目录。",
+            "7) 每轮修改后必须运行 `cargo build -q` 验证，直到构建成功为止。",
+            "",
+            "修改约束：",
+            "- 允许修改的文件范围：Cargo.toml、src/lib.rs、src/main.rs、src/bin/*.rs、src/**/mod.rs（仅最小必要变更）；除非为修复构建与模块声明补齐，不要修改其他文件。",
+            "- 尽量保持现有内容与结构不变，不要引入与构建无关的改动或格式化。",
+            "",
+            "交付要求：",
+            "- 以补丁方式提交实际修改的文件；",
+            "- 在最终回复中简要说明所做变更与最终 `cargo build` 的结果（成功/失败及原因）。",
+        ]
+        requirement_text = "\n".join(requirement_lines)
+
+        prev_cwd = os.getcwd()
+        try:
+            # 切换到 crate 目录运行 CodeAgent 与构建
+            os.chdir(str(created_dir))
+            PrettyOutput.auto_print(
+                f"[c2rust-llm-planner] 已切换到 crate 目录: {os.getcwd()}，执行 CodeAgent 初始化"
+            )
+            if llm_group:
+                PrettyOutput.auto_print(f"[c2rust-llm-planner] 使用模型组: {llm_group}")
+            try:
+                # 验证模型配置在切换目录后是否仍然有效
+                from jarvis.jarvis_utils.config import get_normal_model_name
+                from jarvis.jarvis_utils.config import get_normal_platform_name
+
+                if llm_group:
+                    resolved_model = get_normal_model_name(llm_group)
+                    resolved_platform = get_normal_platform_name(llm_group)
+                    PrettyOutput.auto_print(
+                        f"[c2rust-llm-planner] 解析的模型配置: 平台={resolved_platform}, 模型={resolved_model}"
+                    )
+            except Exception as e:
+                PrettyOutput.auto_print(
+                    f"[c2rust-llm-planner] 警告: 无法验证模型配置: {e}"
+                )
+
+            try:
+                agent = CodeAgent(
+                    need_summary=False,
+                    non_interactive=non_interactive,
+                    model_group=llm_group,
+                    enable_task_list_manager=False,
+                    disable_review=True,
+                )
+                # 验证 agent 内部的模型配置
+                if hasattr(agent, "model") and agent.model:
+                    actual_model = getattr(agent.model, "model_name", "unknown")
+                    actual_platform = type(agent.model).__name__
+                    PrettyOutput.auto_print(
+                        f"[c2rust-llm-planner] CodeAgent 内部模型: {actual_platform}.{actual_model}"
+                    )
+                agent.run(requirement_text, prefix="[c2rust-llm-planner]", suffix="")
+                PrettyOutput.auto_print(
+                    "[c2rust-llm-planner] 初始 CodeAgent 运行完成。"
+                )
+            except Exception as e:
+                error_msg = str(e)
+                if "does not exist" in error_msg or "404" in error_msg:
+                    PrettyOutput.auto_print(
+                        f"[c2rust-llm-planner] 模型配置错误: {error_msg}"
+                    )
+                    PrettyOutput.auto_print(
+                        f"[c2rust-llm-planner] 提示: 请检查模型组 '{llm_group}' 的配置是否正确"
+                    )
+                    PrettyOutput.auto_print(
+                        f"[c2rust-llm-planner] 当前工作目录: {os.getcwd()}"
+                    )
+                    # 尝试显示当前解析的模型配置
+                    try:
+                        from jarvis.jarvis_utils.config import get_normal_model_name
+                        from jarvis.jarvis_utils.config import get_normal_platform_name
+
+                        if llm_group:
+                            PrettyOutput.auto_print(
+                                f"[c2rust-llm-planner] 当前解析的模型: {get_normal_platform_name(llm_group)}/{get_normal_model_name(llm_group)}"
+                            )
+                    except Exception:
+                        pass
+                raise
+
+            # 进入构建与修复循环：构建失败则生成新的 CodeAgent，携带错误上下文进行最小修复
+            iter_count = 0
+            while True:
+                iter_count += 1
+                PrettyOutput.auto_print(
+                    f"[c2rust-llm-planner] 在 {os.getcwd()} 执行: cargo build -q"
+                )
+                build_res = subprocess.run(
+                    ["cargo", "build", "-q"],
+                    capture_output=True,
+                    text=True,
+                    check=False,
+                )
+                stdout = build_res.stdout or ""
+                stderr = build_res.stderr or ""
+                output = (stdout + "\n" + stderr).strip()
+
+                if build_res.returncode == 0:
+                    PrettyOutput.auto_print("[c2rust-llm-planner] Cargo 构建成功。")
+                    break
+
+                PrettyOutput.auto_print(
+                    f"[c2rust-llm-planner] Cargo 构建失败 (iter={iter_count})。"
+                )
+                # 打印编译错误输出，便于可视化与调试
+                PrettyOutput.auto_print("[c2rust-llm-planner] 构建错误输出:")
+                PrettyOutput.auto_print(output)
+                # 将错误信息作为上下文，附加修复原则，生成新的 CodeAgent 进行最小修复
+                repair_prompt = "\n".join(
+                    [
+                        requirement_text,
+                        "",
+                        "请根据以下构建错误进行最小化修复，然后再次执行 `cargo build` 验证：",
+                        "<BUILD_ERROR>",
+                        output,
+                        "</BUILD_ERROR>",
+                    ]
+                )
+
+                if llm_group:
+                    PrettyOutput.auto_print(
+                        f"[c2rust-llm-planner][iter={iter_count}] 使用模型组: {llm_group}"
+                    )
+                try:
+                    repair_agent = CodeAgent(
+                        need_summary=False,
+                        non_interactive=non_interactive,
+                        model_group=llm_group,
+                        enable_task_list_manager=False,
+                        disable_review=True,
+                    )
+                    repair_agent.run(
+                        repair_prompt,
+                        prefix=f"[c2rust-llm-planner][iter={iter_count}]",
+                        suffix="",
+                    )
+                except Exception as e:
+                    error_msg = str(e)
+                    if "does not exist" in error_msg or "404" in error_msg:
+                        PrettyOutput.auto_print(
+                            f"[c2rust-llm-planner][iter={iter_count}] 模型配置错误: {error_msg}"
+                        )
+                        PrettyOutput.auto_print(
+                            f"[c2rust-llm-planner][iter={iter_count}] 提示: 请检查模型组 '{llm_group}' 的配置"
+                        )
+                    raise
+                # 不切换目录，保持在原始工作目录
+        finally:
+            # 恢复之前的工作目录
+            os.chdir(prev_cwd)
+
+    # 3) 输出 JSON 到文件（如指定），并返回解析后的 entries
+    if out is not None:
+        out_path = Path(out)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        # 使用原始文本写出，便于可读
+        out_path.write_text(json_text, encoding="utf-8")
+        PrettyOutput.auto_print(f"[c2rust-llm-planner] JSON 已写入: {out_path}")
+
+    return entries

jarvis/jarvis_c2rust/llm_module_agent_loader.py

@@ -0,0 +1,170 @@
+# -*- coding: utf-8 -*-
+"""LLM 模块规划 Agent 的图加载器。"""
+
+from pathlib import Path
+from typing import Any
+from typing import Dict
+from typing import List
+from typing import Set
+from typing import Tuple
+
+from jarvis.jarvis_c2rust.llm_module_agent_types import FnMeta
+from jarvis.jarvis_utils.jsonnet_compat import loads as json_loads
+
+
+class GraphLoader:
+    """
+    仅从 symbols.jsonl 读取符号与调用关系，提供子图遍历能力：
+    - 数据源：<project_root>/.jarvis/c2rust/symbols.jsonl 或显式传入的 .jsonl 文件
+    - 不再支持任何回退策略（不考虑 symbols_raw.jsonl、functions.jsonl 等）
+    """
+
+    def __init__(self, db_path: Path, project_root: Path):
+        self.project_root = Path(project_root).resolve()
+
+        def _resolve_data_path(hint: Path) -> Path:
+            p = Path(hint)
+            # 仅支持 symbols.jsonl；不再兼容 functions.jsonl 或其他旧格式
+            # 若直接传入文件路径且为 .jsonl，则直接使用（要求内部包含 category/ref 字段）
+            if p.is_file() and p.suffix.lower() == ".jsonl":
+                return p
+            # 目录：仅支持 <dir>/.jarvis/c2rust/symbols.jsonl
+            if p.is_dir():
+                return p / ".jarvis" / "c2rust" / "symbols.jsonl"
+            # 默认：项目 .jarvis/c2rust/symbols.jsonl
+            return self.project_root / ".jarvis" / "c2rust" / "symbols.jsonl"
+
+        self.data_path = _resolve_data_path(Path(db_path))
+        if not self.data_path.exists():
+            raise FileNotFoundError(f"未找到 symbols.jsonl: {self.data_path}")
+        # Initialize in-memory graph structures
+        self.adj: Dict[int, List[str]] = {}
+        self.name_to_id: Dict[str, int] = {}
+        self.fn_by_id: Dict[int, FnMeta] = {}
+
+        # 从 symbols.jsonl 加载符号元数据与邻接关系（统一处理函数与类型，按 ref 构建名称邻接）
+        rows_loaded = 0
+        try:
+            with open(self.data_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        obj = json_loads(line)
+                    except Exception:
+                        # 跳过无效的 JSON 行，但记录以便调试
+                        continue
+                    # 不区分函数与类型，统一处理 symbols.jsonl 中的所有记录
+                    rows_loaded += 1
+                    fid = int(obj.get("id") or rows_loaded)
+                    nm = obj.get("name") or ""
+                    qn = obj.get("qualified_name") or ""
+                    sg = obj.get("signature") or ""
+                    fp = obj.get("file") or ""
+                    refs = obj.get("ref")
+                    # 不兼容旧数据：严格要求为列表类型，缺失则视为空
+                    if not isinstance(refs, list):
+                        refs = []
+                    refs = [c for c in refs if isinstance(c, str) and c]
+                    self.adj[fid] = refs
+                    # 建立名称索引与函数元信息，供子图遍历与上下文构造使用
+                    if isinstance(nm, str) and nm:
+                        self.name_to_id.setdefault(nm, fid)
+                    if isinstance(qn, str) and qn:
+                        self.name_to_id.setdefault(qn, fid)
+                    try:
+                        rel_file = self._rel_path(fp)
+                    except (ValueError, OSError):
+                        rel_file = fp
+                    self.fn_by_id[fid] = FnMeta(
+                        id=fid,
+                        name=nm,
+                        qname=qn,
+                        signature=sg,
+                        file=rel_file,
+                        refs=refs,
+                    )
+        except FileNotFoundError:
+            raise
+        except (OSError, IOError) as e:
+            raise RuntimeError(f"读取 symbols.jsonl 时发生错误: {e}") from e
+        except Exception as e:
+            raise RuntimeError(f"解析 symbols.jsonl 时发生未知错误: {e}") from e
+
+    def _rel_path(self, abs_path: str) -> str:
+        """将绝对路径转换为相对于项目根的相对路径。"""
+        try:
+            p = Path(abs_path).resolve()
+            return str(p.relative_to(self.project_root))
+        except Exception:
+            return abs_path
+
+    def collect_subgraph(self, root_id: int) -> Tuple[Set[int], Set[str]]:
+        """
+        从 root_id 出发，收集所有可达的内部函数 (visited_ids) 与外部调用名称 (externals)
+
+        Args:
+            root_id: 根函数 ID
+
+        Returns:
+            (visited_ids, externals) 元组
+        """
+        visited: Set[int] = set()
+        externals: Set[str] = set()
+        stack: List[int] = [root_id]
+        visited.add(root_id)
+        while stack:
+            src = stack.pop()
+            for callee in self.adj.get(src, []):
+                cid = self.name_to_id.get(callee)
+                if cid is not None:
+                    if cid not in visited:
+                        visited.add(cid)
+                        stack.append(cid)
+                else:
+                    externals.add(callee)
+        return visited, externals
+
+    def build_roots_context(
+        self,
+        roots: List[int],
+        max_functions_per_ns: int = 200,  # 保留参数以保持兼容性，但当前未使用
+        max_namespaces_per_root: int = 50,  # 保留参数以保持兼容性，但当前未使用
+    ) -> List[Dict[str, Any]]:
+        """
+        为每个根函数构造上下文（仅函数名的调用关系，且不包含任何其他信息）：
+        - root_function: 根函数的简单名称（不包含签名/限定名）
+        - functions: 该根函数子图内所有可达函数的简单名称列表（不包含签名/限定名），去重、排序、可选截断
+        注意：
+        - 不包含文件路径、签名、限定名、命名空间、外部符号等任何其他元信息
+        """
+        root_contexts: List[Dict[str, Any]] = []
+        for rid in roots:
+            meta = self.fn_by_id.get(rid)
+            root_label = (meta.name or f"fn_{rid}") if meta else f"fn_{rid}"
+
+            visited_ids, _externals = self.collect_subgraph(rid)
+            # 收集所有简单函数名
+            fn_names: List[str] = []
+            for fid in sorted(visited_ids):
+                m = self.fn_by_id.get(fid)
+                if not m:
+                    continue
+                simple = m.name or f"fn_{fid}"
+                fn_names.append(simple)
+
+            # 去重并排序（优先使用 dict.fromkeys 保持顺序）
+            try:
+                fn_names = sorted(list(dict.fromkeys(fn_names)))
+            except (TypeError, ValueError):
+                # 如果 dict.fromkeys 失败（理论上不应该），回退到 set
+                fn_names = sorted(list(set(fn_names)))
+
+            root_contexts.append(
+                {
+                    "root_function": root_label,
+                    "functions": fn_names,
+                }
+            )
+        return root_contexts