nexforge-cli 0.2.16__tar.gz → 0.2.17__tar.gz

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.16
+Version: 0.2.17
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -51,7 +51,7 @@ Description-Content-Type: text/markdown
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.16** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.2.17** · PyPI: `pip install nexforge-cli`
 
 ---
 

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/README.md

@@ -8,7 +8,7 @@
 
 NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.16** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.2.17** · PyPI: `pip install nexforge-cli`
 
 ---
 

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/manual/01-/345/256/211/350/243/205/344/270/216/351/205/215/347/275/256.md

@@ -1,6 +1,6 @@
 # 安装与配置
 
-> NexForgeCLI v0.2.16
+> NexForgeCLI v0.2.17
 
 ## 环境要求
 

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/manual/03-/346/250/241/345/236/213/351/205/215/347/275/256.md

@@ -109,6 +109,10 @@ models = ["claude-sonnet-4-20250514"]
 - `api_key` 和 `api_key_env` 都未配置 → 回退到全局保存的 Key（`~/.nexforge/auth.toml`）
 - `models`：可用模型 ID 列表
 - `default_model`：可选，指定默认模型，不填取 models 第一个
+- `multimodal`：可选（默认 `false`）。该 provider 挂载的模型**原生支持图片输入**时设为 `true`：
+  用户贴图会直接发给模型（更快、更准，且可保留思考模式），而非降级走识图工具。
+  适用于名字不含 "vision" 但实际能读图的模型（如 `deepseek-v4.1` 系列）。
+  内置 vision 档位无需设置（按模型名自动识别）；声明只对该 provider 列出的模型生效。
 
 软件只读不写此文件，不用担心 Key 被覆盖。
 

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/manual/05-/346/225/260/346/215/256/344/270/216/346/220/234/347/264/242.md

@@ -54,6 +54,12 @@ HTTP GET 抓取指定 URL，返回正文（截断至 20000 字符）。带浏览
 - `mode=auto`（默认）：优先用当前对话 provider 的视觉模型（如 deepseek-vision，共用对话 key），失败回退阿里云千问 qwen-vl
 - `mode=cross`：**双模型交叉验证**——deepseek-vision 与 qwen-vl 并行识别同一张图，返回双答案供交叉印证，减少单一模型的视觉误差（适合 GUI 验收/关键判断）
 
+**何时直接贴图、何时用本工具**（两条通道互补，不是二选一）：
+- **用户贴图**（剪贴板截图 / 拖入）→ 当前模型原生多模态时（vision 档位 / 千问 / `models.toml` 里声明 `multimodal = true` 的模型），图片直接发给模型理解，更快更准且可保留思考模式，此时不需要本工具；
+- **AI 自己产出的图片**（`window_screenshot` / `web_screenshot` 等截图工具落盘后）→ **必须用本工具**：
+  AI 不能把本地文件"贴"进对话，本工具是它读取本地图片的唯一通道，GUI 验收闭环依赖这一点；
+- 当前模型**不支持**图片输入时（如纯文本 flash/pro），用户贴图也会自动降级走本工具。
+
 ### image_gen（图片生成）
 
 提供文字描述，调用阿里云通义万相生成图片并保存到本地。

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/manual/08-/350/207/252/345/256/232/344/271/211/351/205/215/347/275/256.md

@@ -125,3 +125,7 @@ engine = "bing"              # bing | duckduckgo | google | searxng
 AI 收到系统提示后会优先查阅地图来快速定位代码，而不是反复 list_dir/search_content 全量扫描。
 
 每轮对话结束自动同步地图。
+
+**大项目友好**：地图扫描自动跳过 `node_modules`/`.git`/`.venv`/`dist`/`build` 等噪音目录(整棵子树不下钻)，
+且生成与同步都在**后台线程**执行——面对超大工程(如前端 monorepo 的数十万文件)也不会卡住启动界面。
+待分析代码超过 2000 个文件时按路径排序截断，保证界面快速可用。

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/manual/README.md

@@ -1,4 +1,4 @@
-# NexForgeCLI 用户手册 · v0.2.16
+# NexForgeCLI 用户手册 · v0.2.17
 
 ## 这是什么
 

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nexforge-cli"
-version = "0.2.16"
+version = "0.2.17"
 description = "NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)"
 readme = "README.md"
 requires-python = ">=3.11"

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/__init__.py

@@ -3,5 +3,5 @@
 TUI(全屏交互)+ CLI(one-shot / 管道)双模式。
 """
 
-__version__ = "0.2.16"
+__version__ = "0.2.17"
 __all__ = ["__version__"]

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/config.py

@@ -51,6 +51,10 @@ class ProviderDef(BaseModel):
     api_key: str | None = None
     models: list[str] = []                         # 可用模型 ID 列表
     default_model: str = ""                        # 默认模型,为空则取 models[0]
+    # 该 provider 挂的模型是否支持图片输入(原生多模态)。
+    # 用于名字不含 "vision" 但实际支持读图的模型(如 deepseek-v4.1 系列),
+    # 显式声明后: 用户贴图直达模型(展开为 image_url), 无需走识图工具。
+    multimodal: bool = False
     pricing: dict[str, PricingTier] = {}           # model_id → PricingTier
     timeout: float = 120.0
     max_retries: int = 2

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/core/knowledge_base.py

@@ -105,8 +105,12 @@ class KnowledgeBase:
             try:
                 st = f.stat()
                 rel = f.relative_to(d).as_posix()
+                # 只读文件头(取标题用), 避免大 md 全量读入:
+                # read_text()[:N] 是"先全读再切片", 此处按字符读前 N 个
+                with f.open("r", encoding="utf-8", errors="replace") as fh:
+                    head = fh.read(4000)
                 result[rel] = {
-                    "title": self._title_of(f.read_text(encoding="utf-8")[:4000]),
+                    "title": self._title_of(head),
                     "size": st.st_size,
                     "mtime": st.st_mtime,
                 }

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/core/project_mapper.py

@@ -24,6 +24,7 @@ from __future__ import annotations
 import ast
 import hashlib
 import json
+import os
 from collections import defaultdict
 from datetime import datetime
 from pathlib import Path
@@ -49,6 +50,33 @@ _EXCLUDED_DIRS: set[str] = {
 
 _EXCLUDED_PATTERNS: set[str] = {"test_", "_test", "conftest"}
 
+# 单次分析的文件数上限: 超大项目(数千模块)AST 解析会拖慢启动,
+# 按路径排序截断并在地图中注明, 保证 UI 快速可用。
+_MAX_FILES = 2000
+
+
+def _iter_files_pruned(base: Path, suffix: str = "") -> list[Path]:
+    """剪枝遍历: 排除目录直接不下钻(替代 Path.rglob)。
+
+    rglob 的目录过滤发生在遍历**之后**——它必须先走完每个子目录
+    (包括 node_modules/.git/.venv 这类噪音目录)才能产出结果。
+    超大前端项目 node_modules 可达数十万文件, Windows 上单次遍历
+    耗时数分钟(实测某项目 rglob 超 120s, 剪枝 0.17s), 而该遍历原本
+    同步发生在启动的 on_mount 里, 直接冻结 UI → 表现为"卡在启动黑屏"。
+
+    改用 os.walk(topdown=True) 原地改写 dirnames 剪枝, 排除目录的
+    子树完全不进入, 成本只与真实需分析的文件数相关。
+    """
+    out: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(base, topdown=True):
+        # 原地剪枝: 排除目录不再下降(必须在遍历 filenames 前改写)
+        dirnames[:] = [d for d in dirnames if d not in _EXCLUDED_DIRS]
+        for fn in filenames:
+            if suffix and not fn.endswith(suffix):
+                continue
+            out.append(Path(dirpath) / fn)
+    return out
+
 
 def _file_hash(path: Path) -> str | None:
     """快速文件指纹: mtime+size(仅 stat, 不读字节)。
@@ -215,15 +243,14 @@ class ProjectMapper:
         if not src.is_dir():
             src = self.root
         files: list[Path] = []
-        for f in sorted(src.rglob("*.py")):
-            if any(part in _EXCLUDED_DIRS for part in f.parts):
-                continue
+        # 剪枝遍历(排除目录不下钻), 替代原 rglob——见 _iter_files_pruned 说明
+        for f in sorted(_iter_files_pruned(src, ".py")):
             if any(p in f.name for p in _EXCLUDED_PATTERNS):
                 continue
             if f.name.startswith("_") and f.name not in ("__init__.py", "__main__.py"):
                 continue
             files.append(f)
-        return files
+        return files[:_MAX_FILES]
 
     def _analyze_all(self) -> list[_Analyzer]:
         files = self._walk()
@@ -269,7 +296,13 @@ class ProjectMapper:
                    if fp in old_f and old_f[fp] != h]
         added = [fp for fp in now_f if fp not in old_f]
         removed = [fp for fp in old_f if fp not in now_f]
-        return {"in_sync": not changed and not added and not removed,
+        in_sync = not changed and not added and not removed
+        # 边界: 地图输出被删除(.nexforge/map/ 或 map.md 没了)而哈希缓存还在时,
+        # 只比哈希会误判"已同步"→ 永不重建, AI 从此看不到地图。
+        # 故代码未变但输出缺失时, 也视为需要重建。
+        if in_sync and not self.index_content():
+            in_sync = False
+        return {"in_sync": in_sync,
                 "changed": changed, "added": added, "removed": removed,
                 "n_files": now["n_files"], "generated_at": old.get("generated_at", "(无)")}
 
@@ -474,9 +507,7 @@ class ProjectMapper:
                 continue
             lines.append(f"## {d}/")
             found = False
-            for md in sorted(base.rglob("*.md")):
-                if any(part in _EXCLUDED_DIRS for part in md.parts):
-                    continue
+            for md in sorted(_iter_files_pruned(base, ".md")):
                 rel = md.relative_to(self.root).as_posix()
                 size_kb = max(1, md.stat().st_size // 1024)
                 heads = self._extract_headings(md, max_heads=6)

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/core/provider.py

@@ -36,6 +36,23 @@ class BaseProvider(ABC):
         """
         return self.supports_multimodal
 
+    def _pdef_declares_multimodal(self, model: str) -> bool:
+        """models.toml 显式声明的多模态是否适用于该模型。
+
+        语义: ``pdef.multimodal = true`` 声明的是"**该 provider 挂载的**
+        模型支持图片输入"。若传入的模型名不在该 provider 的 models/
+        default_model 列表里(例如同一个 provider 实例被要求跑别的模型),
+        声明不适用, 交由调用方的名字启发式判断——否则会把纯文本模型
+        也误判为多模态, 导致贴图发给看不懂图的模型。
+        """
+        p = getattr(self, "pdef", None)
+        if p is None or not getattr(p, "multimodal", False):
+            return False
+        declared = [x.lower() for x in (getattr(p, "models", None) or [])]
+        if getattr(p, "default_model", ""):
+            declared.append(p.default_model.lower())
+        return (not declared) or (model.lower() in declared)
+
     async def list_models(self) -> list[str]:
         """拉取当前 API key 下可用的模型 ID 列表。
 

nexforge_cli-0.2.17/src/nexforge/features/map_feature.py

@@ -0,0 +1,91 @@
+"""项目地图特性——每轮结束自动同步 + 注入地图提示。"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from nexforge.core.project_mapper import ProjectMapper
+from nexforge.core.system_inject import MAP_MARKER, inject_system
+from nexforge.i18n import t
+
+if TYPE_CHECKING:
+    from nexforge.ui.screens.chat import ChatScreen
+
+
+_MAP_MARKER = MAP_MARKER  # 区分旧 [项目地图] 单文件格式,避免旧会话去重误判
+_MAP_PROMPT = (
+    f"{_MAP_MARKER} 项目结构分析存于 .nexforge/map/ 目录(分层索引体系)。\n"
+    "总索引见下方(已注入本会话): 各层模块清单 + 详细文件导航。\n"
+    "定位函数/追踪调用/查依赖/查文档时:\n"
+    "1. 先看总索引判断属于哪一层/哪个文件\n"
+    "2. 再 read_file 读对应详细文件(.nexforge/map/symbols-<层>.md 等)\n"
+    "3. 避免大范围 list_dir/search_content 扫描全项目。"
+)
+
+
+class MapFeature:
+    name = "map"
+
+    def register(self, screen: ChatScreen) -> None:
+        self.screen = screen
+        from nexforge.core.context import get_project_root
+        self._mapper = ProjectMapper(get_project_root())
+        self._syncing = False  # 防重入: 后台同步进行中不重复触发
+
+    def on_mount(self) -> None:
+        """首次启动自动生成地图,并注入总索引到会话(先传索引, AI 按需读详细文件)。
+
+        关键: sync() 必须走后台线程。它要遍历项目树 + AST 解析全部模块,
+        超大项目(如前端工程 node_modules 数十万文件)同步执行会冻结事件循环,
+        表现为"卡在启动黑屏"(实测某项目单次遍历 >120s)。
+        故先用已有地图注入(保证 AI 立即可用), 同步完成后再刷新注入。
+        """
+        s = self.screen
+        self._inject_index()
+        s._spawn(self._sync_and_inject())
+
+    def _inject_index(self) -> None:
+        """注入当前地图总索引(inject_system 按 marker 去重, 重复调用即替换)。"""
+        s = self.screen
+        idx = self._mapper.index_content()
+        content = _MAP_PROMPT if not idx else _MAP_MARKER + "\n" + idx
+        inject_system(s.session.messages, content, _MAP_MARKER)
+
+    async def _sync_and_inject(self) -> None:
+        """后台线程同步地图, 完成后回主线程刷新注入与提示。"""
+        import asyncio
+        if self._syncing:
+            return  # 已有同步在跑(避免并发写地图文件)
+        self._syncing = True
+        try:
+            await asyncio.to_thread(self._mapper.sync)
+        except Exception:
+            return  # 地图同步失败不影响主流程
+        finally:
+            self._syncing = False
+        self._inject_index()
+        self.screen._note(t("note.map_generated"), scroll=True)
+
+    def on_turn_done(self, content: str) -> None:
+        """每轮结束快速哈希比对,有变化则自动同步(后台线程, 不阻塞回合)。"""
+        if self._syncing:
+            return  # 上一轮同步未完成, 跳过本轮(变更下轮再比对)
+        self._syncing = True
+        self.screen._spawn(self._check_and_sync())
+
+    async def _check_and_sync(self) -> None:
+        import asyncio
+        try:
+            report = await asyncio.to_thread(self._mapper.check)
+            if report["in_sync"]:
+                return
+            n = len(report["changed"]) + len(report["added"]) + len(report["removed"])
+            await asyncio.to_thread(self._mapper.sync)
+            self.screen._note(t("note.map_autosynced", n=str(n)), scroll=True)
+        except Exception:
+            pass  # 自动同步失败不影响主流程
+        finally:
+            self._syncing = False
+
+    def bindings(self) -> list[tuple[str, str, str]]:
+        return []

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/provider/deepseek.py

@@ -106,9 +106,22 @@ class DeepSeekProvider(BaseProvider):
         return self._resolve_model(self.config.models.default_tier)
 
     def supports_model_multimodal(self, model: str = "") -> bool:
-        """视觉模型(模型名含 vision)支持图片输入。"""
+        """该模型是否支持图片输入(原生多模态)。
+
+        判定顺序:
+        1. 模型名含 "vision" → 支持(内置 vision 档位, 如 deepseek-v4-flash-vision-exp);
+        2. models.toml 里该 provider 显式声明 ``multimodal = true`` → 支持。
+           用于名字不含 vision 但实际能读图的模型(如 deepseek-v4.1 系列,
+           实测: 对已知内容的图能准确回答圆/三角颜色与文字, 且不编造图中没有的元素);
+        3. 否则不支持——纯文本模型(如 deepseek-v4-flash)收到图片会返回空。
+
+        判为支持后, 用户贴图走 ``[图片附件: 路径]`` 通道直发达模型;
+        判为不支持则降级走识图工具(image_vision)。
+        """
         m = (model or self.current_model).lower()
-        return "vision" in m
+        if "vision" in m:
+            return True
+        return self._pdef_declares_multimodal(m)
 
     def _expand_image_attachments(
         self, messages: list[dict], model: str | None

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/provider/openai.py

@@ -90,8 +90,14 @@ class OpenAIProvider(BaseProvider):
         return ""
 
     def supports_model_multimodal(self, model: str = "") -> bool:
-        """按模型名判断图片输入能力(如 qwen3.8-max 支持, kimi-k3 不支持)。"""
+        """按模型名判断图片输入能力(如 qwen3.8-max 支持, kimi-k3 不支持)。
+
+        显式声明(models.toml 的 ``multimodal = true``)优先于名字启发式——
+        名字列表不可能穷举所有新模型。
+        """
         m = (model or self.current_model).lower()
+        if self._pdef_declares_multimodal(m):
+            return True
         if any(h in m for h in self._TEXT_HINTS):
             return False
         if any(h in m for h in self._MULTIMODAL_HINTS):

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/store/session_store.py

@@ -424,7 +424,10 @@ def list_sessions() -> list[SessionInfo]:
 def _read_title(path: Path) -> str | None:
     from nexforge.tools._paths import sanitize
     try:
-        first = path.read_text(encoding="utf-8").split("\n", 1)[0]
+        # 只读首行即可: 原实现 read_text() 会把整个会话文件读进内存,
+        # 会话多/大时(历史越长文件越大)纯属浪费。
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            first = fh.readline()
         title = first.lstrip("# ").strip()
         return sanitize(title) or None
     except Exception:
@@ -433,8 +436,13 @@ def _read_title(path: Path) -> str | None:
 
 def _count_messages(path: Path) -> int:
     try:
-        text = path.read_text(encoding="utf-8")
-        return text.count("### ❯ 用户")
+        # 流式逐行统计(不整体载入): 大会话文件下内存友好
+        n = 0
+        with path.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if "### ❯ 用户" in line:
+                    n += 1
+        return n
     except Exception:
         return 0
 

{nexforge_cli-0.2.16 → nexforge_cli-0.2.17}/src/nexforge/tools/image_tools.py

@@ -51,8 +51,15 @@ def _provider_vision_channel(image_b64: str, mime: str, question: str) -> tuple[
         from nexforge.provider import create_provider
 
         cfg = load_config()
-        # 视觉模型名(如 deepseek-v4-flash-vision-exp)
-        model = cfg.models.vision
+        # 模型选择: 优先当前 provider 声明的多模态模型(如 deepseek-v4.1),
+        # 否则回退内置 vision 档位模型(deepseek-v4-flash-vision-exp)。
+        # 两者都走该 provider 的 base_url/key, 保持一致。
+        cur_pdef = cfg.providers.get(cfg.provider.default)
+        model = ""
+        if cur_pdef is not None and getattr(cur_pdef, "multimodal", False):
+            model = cur_pdef.default_model or (
+                cur_pdef.models[0] if cur_pdef.models else "")
+        model = model or cfg.models.vision
         if not model:
             return False, "", ""
         provider = create_provider(cfg)

nexforge_cli-0.2.17/tests/test_project_map_prune.py

@@ -0,0 +1,105 @@
+"""项目地图遍历剪枝测试。
+
+背景(启动黑屏根因): 原实现用 ``Path.rglob("*.py")`` 收集待分析文件,
+目录过滤发生在遍历**之后**——rglob 必须先走进每个子目录(含 node_modules/
+.git/.venv 等噪音目录)才能产出结果。超大项目单次遍历实测 >300s
+(同一项目剪枝遍历仅 0.17s), 而该遍历同步发生在启动的 on_mount 里,
+直接冻结事件循环 → 表现为"卡在启动黑屏"。
+
+修复: 改用 os.walk(topdown=True) 原地改写 dirnames 剪枝, 排除目录的
+子树完全不进入。本文件锁定该行为, 防止回归成 rglob。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from nexforge.core.project_mapper import ProjectMapper, _iter_files_pruned
+
+
+def _mk(p: Path, text: str = "x = 1\n") -> None:
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(text, encoding="utf-8")
+
+
+class TestPrunedIter:
+    def test_skips_noisy_dirs(self, tmp_path: Path) -> None:
+        _mk(tmp_path / "app" / "main.py")
+        _mk(tmp_path / "node_modules" / "left-pad" / "index.py")
+        _mk(tmp_path / ".git" / "hooks" / "hook.py")
+        _mk(tmp_path / "__pycache__" / "cached.py")
+        _mk(tmp_path / ".venv" / "lib" / "vendored.py")
+
+        got = {p.name for p in _iter_files_pruned(tmp_path, ".py")}
+        assert got == {"main.py"}
+
+    def test_prune_at_any_depth(self, tmp_path: Path) -> None:
+        """关键: 嵌套深处的排除目录也不下钻(而非只剪顶层)。"""
+        _mk(tmp_path / "packages" / "web" / "node_modules" / "x" / "y.py")
+        _mk(tmp_path / "packages" / "web" / "src" / "ok.py")
+
+        got = {p.name for p in _iter_files_pruned(tmp_path, ".py")}
+        assert got == {"ok.py"}
+
+    def test_suffix_filter(self, tmp_path: Path) -> None:
+        _mk(tmp_path / "a.py")
+        _mk(tmp_path / "b.md")
+        assert {p.name for p in _iter_files_pruned(tmp_path, ".md")} == {"b.md"}
+
+    def test_empty_suffix_returns_all_files(self, tmp_path: Path) -> None:
+        _mk(tmp_path / "a.py")
+        _mk(tmp_path / "b.md")
+        assert {p.name for p in _iter_files_pruned(tmp_path)} == {"a.py", "b.md"}
+
+    def test_missing_dir_returns_empty(self, tmp_path: Path) -> None:
+        assert _iter_files_pruned(tmp_path / "nope") == []
+
+
+class TestWalk:
+    def test_uses_pruning_and_filters(self, tmp_path: Path) -> None:
+        _mk(tmp_path / "src" / "nexforge" / "core" / "agent.py")
+        _mk(tmp_path / "src" / "nexforge" / "__init__.py")
+        _mk(tmp_path / "src" / "nexforge" / "core" / "_private.py")
+        _mk(tmp_path / "src" / "nexforge" / "tests" / "test_x.py")
+        _mk(tmp_path / "node_modules" / "pkg" / "mod.py")
+
+        names = {p.name for p in ProjectMapper(tmp_path)._walk()}
+        # 私有模块(非 __init__/__main__)与 test_*.py 被过滤; 噪音目录不下钻
+        assert names == {"agent.py", "__init__.py"}
+
+    def test_falls_back_to_root_without_src_nexforge(self, tmp_path: Path) -> None:
+        """无 src/nexforge 时退化为项目根——大项目正是因此扫描整树。"""
+        _mk(tmp_path / "pkg" / "a.py")
+        _mk(tmp_path / "node_modules" / "b.py")
+        _mk(tmp_path / ".git" / "c.py")
+
+        names = {p.name for p in ProjectMapper(tmp_path)._walk()}
+        assert names == {"a.py"}
+
+    def test_respects_max_files_cap(self, tmp_path: Path, monkeypatch) -> None:
+        import nexforge.core.project_mapper as pm
+
+        monkeypatch.setattr(pm, "_MAX_FILES", 3)
+        for i in range(10):
+            _mk(tmp_path / "pkg" / f"m{i}.py")
+
+        assert len(ProjectMapper(tmp_path)._walk()) == 3
+
+
+class TestMissingMapOutput:
+    """地图输出被删而哈希缓存残留时, 必须能自愈重建。"""
+
+    def test_check_requests_rebuild_when_map_deleted(self, tmp_path: Path) -> None:
+        import shutil
+
+        _mk(tmp_path / "pkg" / "a.py")
+        m = ProjectMapper(tmp_path)
+        m.sync()
+        assert m.check()["in_sync"] is True
+
+        # 只删地图输出, 保留 map_cache.json
+        shutil.rmtree(tmp_path / ".nexforge" / "map")
+        (tmp_path / ".nexforge" / "map.md").unlink()
+
+        assert m.check()["in_sync"] is False, "输出缺失时必须视为需重建"
+        m.sync()
+        assert m.index_content() != "", "重建后索引应可用"

nexforge_cli-0.2.17/tests/test_vision_model.py

@@ -0,0 +1,130 @@
+"""deepseek vision 模型接入测试: 档位/多模态判定/图片展开。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from nexforge.config import NexForgeConfig
+
+
+def test_config_vision_tier():
+    """config: vision 档位模型名 + 价格。"""
+    cfg = NexForgeConfig()
+    assert cfg.models.vision == "deepseek-v4-flash-vision-exp"
+    assert cfg.model_id("vision") == "deepseek-v4-flash-vision-exp"
+    assert cfg.model_id("flash") != cfg.model_id("vision")
+    assert cfg.price("vision") is not None
+
+
+def test_vision_multimodal_detection(tmp_path):
+    """provider: vision 模型判定为多模态, flash 不是。"""
+    from nexforge.provider.deepseek import DeepSeekProvider
+    cfg = NexForgeConfig()
+    # 用 _from_key 避免 resolve_api_key 失败
+    prov = DeepSeekProvider._from_key(cfg, "sk-test")
+    assert prov.supports_model_multimodal("deepseek-v4-flash-vision-exp") is True
+    assert prov.supports_model_multimodal("deepseek-v4-flash") is False
+    assert prov.supports_model_multimodal("deepseek-v4-pro") is False
+    assert prov.supports_model_multimodal("") is False  # 默认 flash
+
+
+def test_expand_image_attachments(tmp_path):
+    """图片附件文本展开为 base64 image_url(仅视觉模型)。"""
+    from nexforge.provider.deepseek import DeepSeekProvider
+    cfg = NexForgeConfig()
+    prov = DeepSeekProvider._from_key(cfg, "sk-test")
+    # 造一张假 png
+    img = tmp_path / "shot.png"
+    img.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 64)
+    msgs = [
+        {"role": "user", "content": f"看一下 [图片附件: {img}] 这是什么"},
+    ]
+    # vision 模型: 展开
+    expanded = prov._expand_image_attachments(msgs, "deepseek-v4-flash-vision-exp")
+    content = expanded[0]["content"]
+    assert isinstance(content, list), "应展开为 content 数组"
+    assert content[0]["type"] == "text"
+    assert content[1]["type"] == "image_url"
+    assert "data:image/png;base64," in content[1]["image_url"]["url"]
+    # 非 vision 模型: 保持原文
+    kept = prov._expand_image_attachments(msgs, "deepseek-v4-flash")
+    assert kept[0]["content"] == msgs[0]["content"]
+
+
+def test_vision_stream_forces_thinking_off():
+    """vision 模型请求强制 thinking off。"""
+    from nexforge.provider.deepseek import DeepSeekProvider
+    cfg = NexForgeConfig()
+    prov = DeepSeekProvider._from_key(cfg, "sk-test")
+    # 直接验证 _build_kwargs 的 extra_body(thinking 显式传 False 时)
+    kwargs = prov._build_kwargs(
+        [{"role": "user", "content": "hi"}],
+        None, "vision", thinking=False, effort=None,
+    )
+    assert kwargs["model"] == "deepseek-v4-flash-vision-exp"
+    assert kwargs["extra_body"]["thinking"]["type"] == "disabled"
+
+
+# ── 声明式多模态(models.toml 的 multimodal = true) ──────────────
+# 背景: deepseek-v4.1 系列原生支持读图, 但模型名不含 "vision",
+# 原判定(名字含 vision)会把它当纯文本模型 → 用户贴图被降级到识图工具通道。
+# 实测: 该类模型对已知内容的图能准确回答元素颜色/文字, 且不编造不存在的元素。
+
+
+def _prov_with_pdef(models: list[str], default_model: str, multimodal: bool):
+    from nexforge.config import ProviderDef
+    from nexforge.provider.deepseek import DeepSeekProvider
+    prov = DeepSeekProvider._from_key(NexForgeConfig(), "sk-test")
+    prov.pdef = ProviderDef(
+        type="deepseek", models=models,
+        default_model=default_model, multimodal=multimodal,
+    )
+    return prov
+
+
+def test_providerdef_multimodal_defaults_false():
+    """未声明时默认非多模态(向后兼容, 不改变既有行为)。"""
+    from nexforge.config import ProviderDef
+    assert ProviderDef(type="deepseek").multimodal is False
+
+
+def test_declared_multimodal_model_detected():
+    model = "deepseek-v4.1-flash-expires-on-0910"
+    prov = _prov_with_pdef([model], model, multimodal=True)
+    assert prov.supports_model_multimodal(model) is True
+    assert prov.supports_model_multimodal("") is True  # 默认模型即它
+
+
+def test_declared_multimodal_not_leaking_to_other_models():
+    """声明只覆盖该 provider 挂载的模型, 不能把纯文本模型也判成多模态。"""
+    model = "deepseek-v4.1-flash-expires-on-0910"
+    prov = _prov_with_pdef([model], model, multimodal=True)
+    assert prov.supports_model_multimodal("deepseek-v4-flash") is False
+    assert prov.supports_model_multimodal("deepseek-v4-pro") is False
+
+
+def test_declared_multimodal_disabled_keeps_text_behaviour():
+    """multimodal=false 时即使名字像新模型也不放行。"""
+    model = "deepseek-v4.1-flash-expires-on-0910"
+    prov = _prov_with_pdef([model], model, multimodal=False)
+    assert prov.supports_model_multimodal(model) is False
+
+
+def test_declared_multimodal_expands_image_attachments(tmp_path):
+    """端到端: 声明为多模态后, [图片附件:] 才真正展开为 image_url。"""
+    model = "deepseek-v4.1-flash-expires-on-0910"
+    prov = _prov_with_pdef([model], model, multimodal=True)
+    img = tmp_path / "shot.png"
+    img.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 64)
+    msgs = [{"role": "user", "content": f"看图 [图片附件: {img}] 有什么"}]
+
+    expanded = prov._expand_image_attachments(msgs, model)
+    content = expanded[0]["content"]
+    assert isinstance(content, list), "声明多模态后应展开为 content 数组"
+    assert content[1]["type"] == "image_url"
+    assert "data:image/png;base64," in content[1]["image_url"]["url"]
+
+    # 未声明多模态的 provider → 保持原文(走识图工具通道)
+    prov2 = _prov_with_pdef([model], model, multimodal=False)
+    assert prov2._expand_image_attachments(msgs, model)[0]["content"] == msgs[0]["content"]
+