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

jarvis/jarvis_c2rust/library_replacer.py

@@ -42,6 +42,41 @@ from jarvis.jarvis_c2rust.scanner import (
     find_root_function_ids,
 )
 
+# ============================================================================
+# 常量定义
+# ============================================================================
+
+# LLM评估重试配置
+MAX_LLM_RETRIES = 3  # LLM评估最大重试次数
+
+# 源码片段读取配置
+DEFAULT_SOURCE_SNIPPET_MAX_LINES = 200  # 默认源码片段最大行数
+SUBTREE_SOURCE_SNIPPET_MAX_LINES = 120  # 子树提示词中源码片段最大行数
+
+# 子树提示词构建配置
+MAX_SUBTREE_NODES_META = 200  # 子树节点元数据列表最大长度
+MAX_SUBTREE_EDGES = 400  # 子树边列表最大长度
+MAX_DOT_EDGES = 200  # DOT图边数阈值（超过此值不生成DOT）
+MAX_CHILD_SAMPLES = 2  # 子节点采样数量
+MAX_SOURCE_SAMPLES = 3  # 代表性源码样本最大数量（注释说明）
+
+# 显示配置
+MAX_NOTES_DISPLAY_LENGTH = 200  # 备注显示最大长度
+
+# 输出文件路径配置
+DEFAULT_SYMBOLS_OUTPUT = "symbols_library_pruned.jsonl"  # 默认符号表输出文件名
+DEFAULT_MAPPING_OUTPUT = "library_replacements.jsonl"  # 默认替代映射输出文件名
+SYMBOLS_PRUNE_OUTPUT = "symbols_prune.jsonl"  # 兼容符号表输出文件名
+ORDER_PRUNE_OUTPUT = "translation_order_prune.jsonl"  # 剪枝阶段转译顺序输出文件名
+ORDER_ALIAS_OUTPUT = "translation_order.jsonl"  # 通用转译顺序输出文件名
+DEFAULT_CHECKPOINT_FILE = "library_replacer_checkpoint.json"  # 默认检查点文件名
+
+# Checkpoint配置
+DEFAULT_CHECKPOINT_INTERVAL = 1  # 默认检查点保存间隔（每评估N个节点保存一次）
+
+# JSON格式化配置
+JSON_INDENT = 2  # JSON格式化缩进空格数
+
 
 def _resolve_symbols_jsonl_path(hint: Path) -> Path:
     """解析symbols.jsonl路径"""
@@ -60,18 +95,18 @@ def _setup_output_paths(
 ) -> tuple[Path, Path, Path, Path, Path]:
     """设置输出路径，返回(符号表路径, 映射路径, 兼容符号表路径, 顺序路径, 别名顺序路径)"""
     if out_symbols_path is None:
-        out_symbols_path = data_dir / "symbols_library_pruned.jsonl"
+        out_symbols_path = data_dir / DEFAULT_SYMBOLS_OUTPUT
     else:
         out_symbols_path = Path(out_symbols_path)
     if out_mapping_path is None:
-        out_mapping_path = data_dir / "library_replacements.jsonl"
+        out_mapping_path = data_dir / DEFAULT_MAPPING_OUTPUT
     else:
         out_mapping_path = Path(out_mapping_path)
     
     # 兼容输出
-    out_symbols_prune_path = data_dir / "symbols_prune.jsonl"
-    order_prune_path = data_dir / "translation_order_prune.jsonl"
-    alias_order_path = data_dir / "translation_order.jsonl"
+    out_symbols_prune_path = data_dir / SYMBOLS_PRUNE_OUTPUT
+    order_prune_path = data_dir / ORDER_PRUNE_OUTPUT
+    alias_order_path = data_dir / ORDER_ALIAS_OUTPUT
     
     return out_symbols_path, out_mapping_path, out_symbols_prune_path, order_prune_path, alias_order_path
 
@@ -245,7 +280,7 @@ def _process_candidate_scope(
     return filtered_roots, scope_unreachable_funcs
 
 
-def _read_source_snippet(rec: Dict[str, Any], max_lines: int = 200) -> str:
+def _read_source_snippet(rec: Dict[str, Any], max_lines: int = DEFAULT_SOURCE_SNIPPET_MAX_LINES) -> str:
     """读取源码片段"""
     path = rec.get("file") or ""
     try:
@@ -270,11 +305,13 @@ def _read_source_snippet(rec: Dict[str, Any], max_lines: int = 200) -> str:
 
 
 def _check_llm_availability() -> tuple[bool, Any, Any, Any]:
-    """检查LLM可用性，返回(是否可用, PlatformRegistry, get_normal_platform_name, get_normal_model_name)"""
+    """检查LLM可用性，返回(是否可用, PlatformRegistry, get_smart_platform_name, get_smart_model_name)
+    使用smart平台，适用于代码生成等复杂场景
+    """
     try:
         from jarvis.jarvis_platform.registry import PlatformRegistry  # type: ignore
-        from jarvis.jarvis_utils.config import get_normal_platform_name, get_normal_model_name  # type: ignore
-        return True, PlatformRegistry, get_normal_platform_name, get_normal_model_name
+        from jarvis.jarvis_utils.config import get_smart_platform_name, get_smart_model_name  # type: ignore
+        return True, PlatformRegistry, get_smart_platform_name, get_smart_model_name
     except Exception:
         return False, None, None, None
 
@@ -289,6 +326,21 @@ def _normalize_disabled_libraries(disabled_libraries: Optional[List[str]]) -> tu
     return disabled_norm, disabled_display
 
 
+def _load_additional_notes(data_dir: Path) -> str:
+    """从配置文件加载附加说明"""
+    try:
+        from jarvis.jarvis_c2rust.constants import CONFIG_JSON
+        config_path = data_dir / CONFIG_JSON
+        if config_path.exists():
+            with config_path.open("r", encoding="utf-8") as f:
+                config = json.load(f)
+                if isinstance(config, dict):
+                    return str(config.get("additional_notes", "") or "").strip()
+    except Exception:
+        pass
+    return ""
+
+
 def _normalize_list(items: Optional[List[str]]) -> List[str]:
     """规范化列表，去重并排序"""
     if not isinstance(items, list):
@@ -376,10 +428,10 @@ def _create_llm_model(
     disabled_display: str,
     _model_available: bool,
     PlatformRegistry: Any,
-    get_normal_platform_name: Any,
-    get_normal_model_name: Any,
+    get_smart_platform_name: Any,
+    get_smart_model_name: Any,
 ) -> Optional[Any]:
-    """创建LLM模型"""
+    """创建LLM模型，使用smart平台，适用于代码生成等复杂场景"""
     if not _model_available:
         return None
     try:
@@ -387,20 +439,20 @@ def _create_llm_model(
         model = None
         if llm_group:
             try:
-                platform_name = get_normal_platform_name(llm_group)  # type: ignore
+                platform_name = get_smart_platform_name(llm_group)  # type: ignore
                 if platform_name:
                     model = registry.create_platform(platform_name)  # type: ignore
             except Exception:
                 model = None
         if model is None:
-            model = registry.get_normal_platform()  # type: ignore
+            model = registry.get_smart_platform()  # type: ignore
         try:
             model.set_model_group(llm_group)  # type: ignore
         except Exception:
             pass
         if llm_group:
             try:
-                mn = get_normal_model_name(llm_group)  # type: ignore
+                mn = get_smart_model_name(llm_group)  # type: ignore
                 if mn:
                     model.set_model_name(mn)  # type: ignore
             except Exception:
@@ -409,7 +461,7 @@ def _create_llm_model(
             "你是资深 C→Rust 迁移专家。任务：给定一个函数及其调用子树（依赖图摘要、函数签名、源码片段），"
             "判断是否可以使用一个或多个成熟的 Rust 库整体替代该子树的功能（允许库内多个 API 协同，允许多个库组合；不允许使用不成熟/不常见库）。"
             "如可替代，请给出 libraries 列表（库名），可选给出代表性 API/模块与实现备注 notes（如何用这些库协作实现）。"
-            "输出格式：仅输出一个 <yaml> 块，字段: replaceable(bool), libraries(list[str]), confidence(float 0..1)，可选 library(str,首选主库), api(str) 或 apis(list)，notes(str)。"
+            "输出格式：仅输出一个 <SUMMARY> 块，块内直接包含 JSON 对象（不需要额外的标签），字段: replaceable(bool), libraries(list[str]), confidence(float 0..1)，可选 library(str,首选主库), api(str) 或 apis(list)，notes(str)。"
         )
         return model
     except Exception as e:
@@ -421,9 +473,9 @@ def _create_llm_model(
         return None
 
 
-def _parse_agent_yaml_summary(text: str) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
+def _parse_agent_json_summary(text: str) -> Tuple[Optional[Dict[str, Any]], Optional[str]]:
     """
-    解析Agent返回的YAML/JSON摘要
+    解析Agent返回的JSON摘要
     返回(解析结果, 错误信息)
     如果解析成功，返回(data, None)
     如果解析失败，返回(None, 错误信息)
@@ -431,76 +483,24 @@ def _parse_agent_yaml_summary(text: str) -> Tuple[Optional[Dict[str, Any]], Opti
     if not isinstance(text, str) or not text.strip():
         return None, "摘要文本为空"
     import re as _re
-    import json as _json
-    try:
-        import yaml  # type: ignore
-    except Exception:
-        yaml = None  # type: ignore
+    from jarvis.jarvis_utils.jsonnet_compat import loads as _json_loads
 
+    # 提取 <SUMMARY> 块
     m_sum = _re.search(r"<SUMMARY>([\s\S]*?)</SUMMARY>", text, flags=_re.IGNORECASE)
     block = (m_sum.group(1) if m_sum else text).strip()
 
-    m_yaml = _re.search(r"<yaml>([\s\S]*?)</yaml>", block, flags=_re.IGNORECASE)
-    if m_yaml:
-        raw = m_yaml.group(1).strip()
-        if raw and yaml:
-            try:
-                data = yaml.safe_load(raw)
-                if isinstance(data, dict):
-                    return data, None
-            except Exception as yaml_err:
-                return None, f"YAML 解析失败: {str(yaml_err)}"
-        elif raw and not yaml:
-            return None, "PyYAML 未安装，无法解析 YAML"
-
-    m_code = _re.search(r"```(?:yaml|yml)\s*([\s\S]*?)```", block, flags=_re.IGNORECASE)
-    if m_code:
-        raw = m_code.group(1).strip()
-        if raw and yaml:
-            try:
-                data = yaml.safe_load(raw)
-                if isinstance(data, dict):
-                    return data, None
-            except Exception as yaml_err:
-                return None, f"YAML 解析失败: {str(yaml_err)}"
-        elif raw and not yaml:
-            return None, "PyYAML 未安装，无法解析 YAML"
-
-    m_json = _re.search(r"\{[\s\S]*\}", block)
-    if m_json:
-        raw = m_json.group(0).strip()
-        try:
-            data = _json.loads(raw)
-            if isinstance(data, dict):
-                return data, None
-        except Exception as json_err:
-            return None, f"JSON 解析失败: {str(json_err)}"
-
-    # 宽松键值
-    def _kv(pattern: str) -> Optional[str]:
-        m = _re.search(pattern, block, flags=_re.IGNORECASE)
-        return m.group(1).strip() if m else None
-
-    rep_raw = _kv(r"replaceable\s*:\s*(.+)")
-    lib_raw = _kv(r"library\s*:\s*(.+)")
-    api_raw = _kv(r"(?:api|function)\s*:\s*(.+)")
-    conf_raw = _kv(r"confidence\s*:\s*([0-9\.\-eE]+)")
-    if any([rep_raw, lib_raw, api_raw, conf_raw]):
-        result: Dict[str, Any] = {}
-        if rep_raw is not None:
-            rep_s = rep_raw.strip().strip("\"'")
-            result["replaceable"] = rep_s.lower() in ("true", "yes", "y", "1")
-        if lib_raw is not None:
-            result["library"] = lib_raw.strip().strip("\"'")
-        if api_raw is not None:
-            result["api"] = api_raw.strip().strip("\"'")
-        if conf_raw is not None:
-            try:
-                result["confidence"] = float(conf_raw)
-            except Exception:
-                pass
-        return (result if result else None, None)
-    return None, "未找到有效的YAML/JSON格式或键值对"
+    if not block:
+        return None, "未找到 <SUMMARY> 或 </SUMMARY> 标签，或标签内容为空"
+
+    # 直接解析 <SUMMARY> 块内的内容为 JSON
+    # jsonnet_compat.loads 会自动处理 markdown 代码块标记（如 ```json5、```json、``` 等）
+    try:
+        data = _json_loads(block)
+        if isinstance(data, dict):
+            return data, None
+        return None, f"JSON 解析结果不是字典，而是 {type(data).__name__}"
+    except Exception as json_err:
+        return None, f"JSON 解析失败: {str(json_err)}"
 
 
 def _build_subtree_prompt(
@@ -509,6 +509,7 @@ def _build_subtree_prompt(
     by_id: Dict[int, Dict[str, Any]],
     adj_func: Dict[int, List[int]],
     disabled_display: str,
+    additional_notes: str = "",
 ) -> str:
     """构建子树评估提示词"""
     root_rec = by_id.get(fid, {})
@@ -527,19 +528,19 @@ def _build_subtree_prompt(
             nodes_meta.append(f"- {nm} | {sg}")
         else:
             nodes_meta.append(f"- {nm}")
-    if len(nodes_meta) > 200:
-        nodes_meta = nodes_meta[:200] + [f"...({len(desc)-200} more)"]
+    if len(nodes_meta) > MAX_SUBTREE_NODES_META:
+        nodes_meta = nodes_meta[:MAX_SUBTREE_NODES_META] + [f"...({len(desc)-MAX_SUBTREE_NODES_META} more)"]
     
-    # 选取部分代表性叶子/内部节点源码（最多 3 个）
+    # 选取部分代表性叶子/内部节点源码（最多 MAX_SOURCE_SAMPLES 个）
     samples: List[str] = []
     sample_ids: List[int] = [fid]
-    for ch in adj_func.get(fid, [])[:2]:
+    for ch in adj_func.get(fid, [])[:MAX_CHILD_SAMPLES]:
         sample_ids.append(ch)
     for sid in sample_ids:
         rec = by_id.get(sid, {})
         nm = rec.get("qualified_name") or rec.get("name") or f"sym_{sid}"
         sg = rec.get("signature") or ""
-        src = _read_source_snippet(rec, max_lines=120)
+        src = _read_source_snippet(rec, max_lines=SUBTREE_SOURCE_SNIPPET_MAX_LINES)
         samples.append(f"--- BEGIN {nm} ---\n{sg}\n{src}\n--- END {nm} ---")
     
     # 构建依赖图（子树内的调用有向边）
@@ -553,14 +554,14 @@ def _build_subtree_prompt(
             if v in desc:
                 edges_list.append(f"{_label(u)} -> {_label(v)}")
     edges_text: str
-    if len(edges_list) > 400:
-        edges_text = "\n".join(edges_list[:400] + [f"...({len(edges_list) - 400} more edges)"])
+    if len(edges_list) > MAX_SUBTREE_EDGES:
+        edges_text = "\n".join(edges_list[:MAX_SUBTREE_EDGES] + [f"...({len(edges_list) - MAX_SUBTREE_EDGES} more edges)"])
     else:
         edges_text = "\n".join(edges_list)
     
     # 适度提供 DOT（边数不大时），便于大模型直观看图
     dot_text = ""
-    if len(edges_list) <= 200:
+    if len(edges_list) <= MAX_DOT_EDGES:
         dot_lines: List[str] = ["digraph subtree {", "  rankdir=LR;"]
         for u in sorted(desc):
             for v in adj_func.get(u, []):
@@ -578,7 +579,7 @@ def _build_subtree_prompt(
         "请评估以下 C/C++ 函数子树是否可以由一个或多个成熟的 Rust 库整体替代（语义等价或更强）。"
         "允许库内多个 API 协同，允许多个库组合；如果必须依赖尚不成熟/冷门库或非 Rust 库，则判定为不可替代。\n"
         f"{disabled_hint}"
-        "输出格式：仅输出一个 <yaml> 块，字段: replaceable(bool), libraries(list[str]), confidence(float 0..1)，"
+        "输出格式：仅输出一个 <SUMMARY> 块，块内直接包含 JSON 对象（不需要额外的标签），字段: replaceable(bool), libraries(list[str]), confidence(float 0..1)，"
         "可选字段: library(str,首选主库), api(str) 或 apis(list), notes(str: 简述如何由这些库协作实现的思路)。\n\n"
         f"根函数(被评估子树的根): {root_name}\n"
         f"签名: {root_sig}\n"
@@ -595,6 +596,7 @@ def _build_subtree_prompt(
         + "代表性源码样本（部分节点，可能截断，仅供辅助判断）:\n"
         + "\n".join(samples)
         + "\n"
+        + (f"\n【附加说明（用户自定义）】\n{additional_notes}\n" if additional_notes else "")
     )
 
 
@@ -607,35 +609,102 @@ def _llm_evaluate_subtree(
     disabled_display: str,
     _model_available: bool,
     _new_model_func: Callable,
+    additional_notes: str = "",
 ) -> Dict[str, Any]:
-    """使用LLM评估子树是否可替代"""
+    """使用LLM评估子树是否可替代，支持最多3次重试"""
     if not _model_available:
         return {"replaceable": False}
     model = _new_model_func()
     if not model:
         return {"replaceable": False}
     
-    prompt = _build_subtree_prompt(fid, desc, by_id, adj_func, disabled_display)
+    base_prompt = _build_subtree_prompt(fid, desc, by_id, adj_func, disabled_display, additional_notes)
+    last_parse_error = None
     
-    try:
-        result = model.chat_until_success(prompt)  # type: ignore
-        parsed, parse_error = _parse_agent_yaml_summary(result or "")
-        if parse_error:
-            # YAML解析失败，将错误信息反馈给模型
-            print(f"[c2rust-lib-replace] YAML解析失败: {parse_error}")
-            # 更新提示词，包含解析错误信息
-            prompt_with_error = (
-                prompt
-                + f"\n\n**格式错误详情（请根据以下错误修复输出格式）：**\n- {parse_error}\n\n"
-                + "请确保输出的YAML格式正确，包括正确的缩进、引号、冒号等。"
-            )
-            result = model.chat_until_success(prompt_with_error)  # type: ignore
-            parsed, parse_error = _parse_agent_yaml_summary(result or "")
+    for attempt in range(1, MAX_LLM_RETRIES + 1):
+        try:
+            # 构建当前尝试的提示词
+            if attempt == 1:
+                prompt = base_prompt
+            else:
+                # 重试时包含之前的错误信息
+                error_hint = ""
+                if last_parse_error:
+                    error_hint = (
+                        f"\n\n**格式错误详情（请根据以下错误修复输出格式）：**\n- {last_parse_error}\n\n"
+                        + "请确保输出的JSON格式正确，包括正确的引号、逗号、大括号等。仅输出一个 <SUMMARY> 块，块内直接包含 JSON 对象（不需要额外的标签）。"
+                    )
+                prompt = base_prompt + error_hint
+            
+            # 调用LLM
+            result = model.chat_until_success(prompt)  # type: ignore
+            parsed, parse_error = _parse_agent_json_summary(result or "")
+            
             if parse_error:
-                # 仍然失败，使用默认值
-                print(f"[c2rust-lib-replace] 重试后YAML解析仍然失败: {parse_error}，使用默认值")
-                parsed = None
-        if isinstance(parsed, dict):
+                # JSON解析失败，记录错误并准备重试
+                last_parse_error = parse_error
+                typer.secho(
+                    f"[c2rust-library] 第 {attempt}/{MAX_LLM_RETRIES} 次尝试：JSON解析失败: {parse_error}",
+                    fg=typer.colors.YELLOW,
+                    err=True,
+                )
+                # 打印原始内容以便调试
+                result_text = str(result or "").strip()
+                if result_text:
+                    typer.secho(
+                        f"[c2rust-library] 原始LLM响应内容（前1000字符）:\n{result_text[:1000]}",
+                        fg=typer.colors.RED,
+                        err=True,
+                    )
+                    if len(result_text) > 1000:
+                        typer.secho(
+                            f"[c2rust-library] ... (还有 {len(result_text) - 1000} 个字符未显示)",
+                            fg=typer.colors.RED,
+                            err=True,
+                        )
+                if attempt < MAX_LLM_RETRIES:
+                    continue  # 继续重试
+                else:
+                    # 最后一次尝试也失败，使用默认值
+                    typer.secho(
+                        f"[c2rust-library] 重试 {MAX_LLM_RETRIES} 次后JSON解析仍然失败: {parse_error}，使用默认值",
+                        fg=typer.colors.YELLOW,
+                        err=True,
+                    )
+                    return {"replaceable": False}
+            
+            # 解析成功，检查是否为字典
+            if not isinstance(parsed, dict):
+                last_parse_error = f"解析结果不是字典，而是 {type(parsed).__name__}"
+                typer.secho(
+                    f"[c2rust-library] 第 {attempt}/{MAX_LLM_RETRIES} 次尝试：{last_parse_error}",
+                    fg=typer.colors.YELLOW,
+                    err=True,
+                )
+                # 打印解析结果和原始内容以便调试
+                typer.secho(
+                    f"[c2rust-library] 解析结果类型: {type(parsed).__name__}, 值: {repr(parsed)[:500]}",
+                    fg=typer.colors.RED,
+                    err=True,
+                )
+                result_text = str(result or "").strip()
+                if result_text:
+                    typer.secho(
+                        f"[c2rust-library] 原始LLM响应内容（前1000字符）:\n{result_text[:1000]}",
+                        fg=typer.colors.RED,
+                        err=True,
+                    )
+                if attempt < MAX_LLM_RETRIES:
+                    continue  # 继续重试
+                else:
+                    typer.secho(
+                        f"[c2rust-library] 重试 {MAX_LLM_RETRIES} 次后结果格式仍然不正确，视为不可替代。",
+                        fg=typer.colors.YELLOW,
+                        err=True,
+                    )
+                    return {"replaceable": False}
+            
+            # 成功解析为字典，处理结果
             rep = bool(parsed.get("replaceable") is True)
             lib = str(parsed.get("library") or "").strip()
             api = str(parsed.get("api") or parsed.get("function") or "").strip()
@@ -688,12 +757,37 @@ def _llm_evaluate_subtree(
                 result_obj["apis"] = apis
             if notes:
                 result_obj["notes"] = notes
+            
+            # 成功获取结果，返回
+            if attempt > 1:
+                typer.secho(
+                    f"[c2rust-library] 第 {attempt} 次尝试成功获取评估结果",
+                    fg=typer.colors.GREEN,
+                    err=True,
+                )
             return result_obj
-        typer.secho("[c2rust-library] LLM 结果解析失败，视为不可替代。", fg=typer.colors.YELLOW, err=True)
-        return {"replaceable": False}
-    except Exception as e:
-        typer.secho(f"[c2rust-library] LLM 评估失败，视为不可替代: {e}", fg=typer.colors.YELLOW, err=True)
-        return {"replaceable": False}
+            
+        except Exception as e:
+            # LLM调用异常，记录并准备重试
+            last_parse_error = f"LLM调用异常: {str(e)}"
+            typer.secho(
+                f"[c2rust-library] 第 {attempt}/{MAX_LLM_RETRIES} 次尝试：LLM评估失败: {e}",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+            if attempt < MAX_LLM_RETRIES:
+                continue  # 继续重试
+            else:
+                # 最后一次尝试也失败，返回默认值
+                typer.secho(
+                    f"[c2rust-library] 重试 {MAX_LLM_RETRIES} 次后LLM评估仍然失败: {e}，视为不可替代",
+                    fg=typer.colors.YELLOW,
+                    err=True,
+                )
+                return {"replaceable": False}
+    
+    # 理论上不会到达这里，但作为保险
+    return {"replaceable": False}
 
 
 def _is_entry_function(
@@ -843,7 +937,7 @@ def apply_library_replacement(
     disabled_libraries: Optional[List[str]] = None,
     resume: bool = True,
     checkpoint_path: Optional[Path] = None,
-    checkpoint_interval: int = 1,
+    checkpoint_interval: int = DEFAULT_CHECKPOINT_INTERVAL,
     clear_checkpoint_on_done: bool = True,
     non_interactive: bool = True,
 ) -> Dict[str, Path]:
@@ -872,7 +966,7 @@ def apply_library_replacement(
 
     # Checkpoint 默认路径
     if checkpoint_path is None:
-        checkpoint_path = data_dir / "library_replacer_checkpoint.json"
+        checkpoint_path = data_dir / DEFAULT_CHECKPOINT_FILE
 
     # 读取符号
     all_records, by_id, name_to_id, func_ids, id_refs_names = _load_symbols(sjsonl)
@@ -898,8 +992,11 @@ def apply_library_replacement(
     # 预处理禁用库
     disabled_norm, disabled_display = _normalize_disabled_libraries(disabled_libraries)
 
+    # 读取附加说明
+    additional_notes = _load_additional_notes(data_dir)
+
     # 断点恢复支持：工具函数与关键键构造
-    ckpt_path: Path = Path(checkpoint_path) if checkpoint_path is not None else (data_dir / "library_replacer_checkpoint.json")
+    ckpt_path: Path = Path(checkpoint_path) if checkpoint_path is not None else (data_dir / DEFAULT_CHECKPOINT_FILE)
     checkpoint_key = _make_checkpoint_key(sjsonl, library_name, llm_group, candidates, disabled_libraries, max_funcs)
 
     def _new_model() -> Optional[Any]:
@@ -910,6 +1007,7 @@ def apply_library_replacement(
     pruned_dynamic: Set[int] = set()  # 动态累计的"将被剪除"的函数集合（不含选中根）
     selected_roots: List[Tuple[int, Dict[str, Any]]] = []  # 实时选中的可替代根（fid, LLM结果）
     processed_roots: Set[int] = set()  # 已处理（评估或跳过）的根集合
+    root_funcs_processed: Set[int] = set()  # 已处理的初始根函数集合（用于进度显示）
     last_ckpt_saved = 0  # 上次保存的计数
 
     # 若存在匹配的断点文件，则加载恢复
@@ -935,6 +1033,11 @@ def apply_library_replacement(
             selected_roots = sr_list
         except Exception:
             selected_roots = []
+        # 恢复已处理的初始根函数集合（从 processed_roots 中筛选出在 root_funcs 中的）
+        try:
+            root_funcs_processed = {fid for fid in processed_roots if fid in root_funcs}
+        except Exception:
+            root_funcs_processed = set()
         typer.secho(
             f"[c2rust-library] 已从断点恢复: 已评估={eval_counter}, 已处理根={len(processed_roots)}, 已剪除={len(pruned_dynamic)}, 已选中替代根={len(selected_roots)}",
             fg=typer.colors.YELLOW,
@@ -962,17 +1065,17 @@ def apply_library_replacement(
         try:
             interval = int(checkpoint_interval)
         except Exception:
-            interval = 1
+            interval = DEFAULT_CHECKPOINT_INTERVAL
         need_save = force or (interval <= 0) or ((eval_counter - last_ckpt_saved) >= interval)
         if not need_save:
             return
         try:
-            _atomic_write(ckpt_path, json.dumps(_current_checkpoint_state(), ensure_ascii=False, indent=2))
+            _atomic_write(ckpt_path, json.dumps(_current_checkpoint_state(), ensure_ascii=False, indent=JSON_INDENT))
             last_ckpt_saved = eval_counter
         except Exception:
             pass
 
-    def _evaluate_node(fid: int) -> None:
+    def _evaluate_node(fid: int, is_root_func: bool = False) -> None:
         nonlocal eval_counter
         # 限流
         if max_funcs is not None and eval_counter >= max_funcs:
@@ -985,8 +1088,22 @@ def apply_library_replacement(
         desc = _collect_descendants(fid, adj_func, desc_cache)
         rec_meta = by_id.get(fid, {})
         label = rec_meta.get("qualified_name") or rec_meta.get("name") or f"sym_{fid}"
+        # 计算进度：区分初始根函数和递归评估的子节点
+        total_roots = len(root_funcs)
+        total_evaluated = len(processed_roots) + 1  # +1 因为当前这个即将被处理
+        if is_root_func:
+            # 初始根函数：显示 (当前根函数索引/总根函数数)
+            root_progress = len(root_funcs_processed) + 1
+            progress_info = f"({root_progress}/{total_roots})" if total_roots > 0 else ""
+        else:
+            # 递归评估的子节点：显示 (当前根函数索引/总根函数数, 总评估节点数)
+            root_progress = len(root_funcs_processed)
+            if total_roots > 0:
+                progress_info = f"({root_progress}/{total_roots}, 总评估={total_evaluated})"
+            else:
+                progress_info = f"(总评估={total_evaluated})"
         typer.secho(
-            f"[c2rust-library] 正在评估: {label} (ID: {fid}), 子树函数数={len(desc)}",
+            f"[c2rust-library] {progress_info} 正在评估: {label} (ID: {fid}), 子树函数数={len(desc)}",
             fg=typer.colors.CYAN,
             err=True,
         )
@@ -994,10 +1111,12 @@ def apply_library_replacement(
         # 执行 LLM 评估
         res = _llm_evaluate_subtree(
             fid, desc, by_id, adj_func, disabled_norm, disabled_display,
-            _model_available, _new_model
+            _model_available, _new_model, additional_notes
         )
         eval_counter += 1
         processed_roots.add(fid)
+        if is_root_func:
+            root_funcs_processed.add(fid)
         res["mode"] = "llm"
         _periodic_checkpoint_save()
 
@@ -1016,12 +1135,26 @@ def apply_library_replacement(
                     conf = 0.0
                 libs_str = ", ".join(libs) if libs else "(未指定库)"
                 apis_str = ", ".join([str(a) for a in apis]) if isinstance(apis, list) else (api if api else "")
-                msg = f"[c2rust-library] 可替换: {label} -> 库: {libs_str}"
+                # 计算进度：区分初始根函数和递归评估的子节点
+                total_roots = len(root_funcs)
+                if is_root_func:
+                    # 初始根函数：显示 (当前根函数索引/总根函数数)
+                    root_progress = len(root_funcs_processed)
+                    progress_info = f"({root_progress}/{total_roots})" if total_roots > 0 else ""
+                else:
+                    # 递归评估的子节点：显示 (当前根函数索引/总根函数数, 总评估节点数)
+                    root_progress = len(root_funcs_processed)
+                    total_evaluated = len(processed_roots)
+                    if total_roots > 0:
+                        progress_info = f"({root_progress}/{total_roots}, 总评估={total_evaluated})"
+                    else:
+                        progress_info = f"(总评估={total_evaluated})"
+                msg = f"[c2rust-library] {progress_info} 可替换: {label} -> 库: {libs_str}"
                 if apis_str:
                     msg += f"; 参考API: {apis_str}"
                 msg += f"; 置信度: {conf:.2f}"
                 if notes:
-                    msg += f"; 备注: {notes[:200]}"
+                    msg += f"; 备注: {notes[:MAX_NOTES_DISPLAY_LENGTH]}"
                 typer.secho(msg, fg=typer.colors.GREEN, err=True)
 
                 # 入口函数保护：不替代 main（保留进行转译），改为深入评估其子节点
@@ -1032,7 +1165,7 @@ def apply_library_replacement(
                         err=True,
                     )
                     for ch in adj_func.get(fid, []):
-                        _evaluate_node(ch)
+                        _evaluate_node(ch, is_root_func=False)
                 else:
                     # 即时剪枝（不含根）
                     to_prune = set(desc)
@@ -1050,13 +1183,13 @@ def apply_library_replacement(
             else:
                 # 若不可替代，继续评估其子节点（深度优先）
                 for ch in adj_func.get(fid, []):
-                    _evaluate_node(ch)
+                    _evaluate_node(ch, is_root_func=False)
         except Exception:
             pass
 
     # 对每个候选根进行评估；若根不可替代将递归评估其子节点
     for fid in root_funcs:
-        _evaluate_node(fid)
+        _evaluate_node(fid, is_root_func=True)
 
     # 剪枝集合来自动态评估阶段的累计结果
     pruned_funcs: Set[int] = set(pruned_dynamic)
@@ -1118,5 +1251,4 @@ def apply_library_replacement(
     return result
 
 
-__all__ = ["apply_library_replacement"]
 __all__ = ["apply_library_replacement"]