nexforge-cli 0.2.7__tar.gz → 0.2.9__tar.gz

{nexforge_cli-0.2.7 → nexforge_cli-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexforge-cli
-Version: 0.2.7
+Version: 0.2.9
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge
@@ -21,10 +21,13 @@ Classifier: Topic :: Terminals
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
 Requires-Dist: openai>=1.40
+Requires-Dist: pillow>=10.0
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pyperclip>=1.8
 Requires-Dist: rich>=13.7
 Requires-Dist: textual>=0.60
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.50; extra == 'anthropic'
 Provides-Extra: dev
 Requires-Dist: build>=1.2; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'

nexforge_cli-0.2.9/doc//344/273/243/347/240/201/344/274/230/345/214/226/350/256/241/345/210/222.md

@@ -0,0 +1,142 @@
+# NexForgeCLI 代码优化计划
+
+> 审计日期: 2026-07-16 · 当前版本: v0.2.x · 目标: 稳定、可扩展
+
+---
+
+## 审计发现总结
+
+| 严重度 | 数量 | 说明 |
+|--------|------|------|
+| 🔴 致命 | 1 | `chat.py` 949行 God Screen,包含20+ slash命令/会话管理/审批/滚动等全部逻辑 |
+| 🟡 重要 | 4 | 死代码(12行)、重复方法体(8行)、未使用import、test gap 60% |
+| 🟢 优化 | 8 | 硬编码常量、静默异常吞噬、模块内聚性差 |
+
+---
+
+## 优化计划 (分3阶段)
+
+### 阶段1: 清理 (P0, 立即执行, ~30 min)
+
+**目标**: 消除死代码和安全隐患,不改变任何功能
+
+| # | 文件 | 操作 | 收益 |
+|---|------|------|------|
+| 1.1 | `chat.py` L298-311 | 删除 `/perm` 后不可达的12行死代码 | 减少混淆 |
+| 1.2 | `chat.py` L455-462 | 删除 `_set_follow` 重复方法体 | 修复潜在 bug |
+| 1.3 | `chat.py` L6 | 删除未使用的 `from pathlib import Path` | 清理导入 |
+| 1.4 | `chat.py` L19 | `import asyncio` 移到 stdlib 块顶部 | PEP 8 |
+| 1.5 | `stats/heartbeat.py` L53 | `except Exception: pass` → 至少日志记录 | 可观测性 |
+| 1.6 | `chat.py` `_refresh_status` | `query_one("#status")` 加 try/except | 防崩溃 |
+
+---
+
+### 阶段2: 拆分 (P1, 核心重构, ~2 hr)
+
+**目标**: 将 God Screen `chat.py` 拆分为5个独立模块
+
+#### 2.1 拆分 `SlashCommandHandler`
+
+```
+src/nexforge/ui/slash_handler.py  (新建, ~200 lines)
+```
+
+**迁移内容**:
+- `_handle_slash` 全部逻辑(159-370行)
+- `HELP` 字符串(建议改为 `slash_handler.HELP`)
+- 每个命令的处理函数独立为 `_cmd_xxx()` 方法
+
+**接口**: `SlashCommandHandler(screen)` — 依赖注入 screen
+
+#### 2.2 拆分 `SessionManager`
+
+```
+src/nexforge/ui/session_manager.py  (新建, ~130 lines)
+```
+
+**迁移内容**:
+- `_do_new_session`, `_do_delete_session`, `_do_switch_session`
+- `_auto_save`, `_auto_resume`, `_save_as`
+- 与 `store/session_store.py` 直接通信
+
+#### 2.3 拆分 `ApprovalManager`
+
+```
+src/nexforge/ui/approval_manager.py  (新建, ~70 lines)
+```
+
+**迁移内容**:
+- `_ask_approve`, `_make_diff`, `_unified`
+- 依赖于 `confirm_modal`, `diff_modal`
+
+#### 2.4 拆分 `ScrollController` (Mixin)
+
+```
+src/nexforge/ui/scroll_controller.py  (新建, ~60 lines)
+```
+
+**迁移内容**:
+- `_scroll`, `_set_follow`, `_scroll_to_bottom`, `_reset_scroll_safety`
+
+#### 2.5 精简后的 `ChatScreen`
+
+```
+src/nexforge/ui/screens/chat.py  (~250 lines)
+```
+
+**保留内容**:
+- compose, on_mount
+- _run_agent (Agent 事件流)
+- 组合上述4个组件
+- _init_provider, _refresh_status
+
+---
+
+### 阶段3: 加固 (P2, 质量提升, ~1 hr)
+
+| # | 操作 | 收益 |
+|---|------|------|
+| 3.1 | 7个硬编码常量提取到 `config.py`(`MAX_WIDGETS`, `MAX_HITS`, 等) | 可配置 |
+| 3.2 | 8处静默 `except: pass` 改 `except Exception: log.warning(...)` | 可调试 |
+| 3.3 | `tools/*.py` 加 `PluginBase` 抽象基类 | 可扩展 |
+| 3.4 | 添加 `src/nexforge/utils/logging.py` 统一日志模块 | 统一 |
+| 3.5 | `HELP` 字符串改为 `resources/help.md` 外部文件 | 可维护 |
+| 3.6 | `DEFAULT_SYSTEM` prompt 改为 `resources/system_prompt.md` | 可调整 |
+
+---
+
+## 涉及文件清单
+
+| 文件 | 阶段 | 改动类型 |
+|------|------|---------|
+| `src/nexforge/ui/screens/chat.py` | 1+2 | 删死代码 + 拆出200行 → 最终 ~250行 |
+| `src/nexforge/ui/slash_handler.py` | 2 | **新建** (~200行) |
+| `src/nexforge/ui/session_manager.py` | 2 | **新建** (~130行) |
+| `src/nexforge/ui/approval_manager.py` | 2 | **新建** (~70行) |
+| `src/nexforge/ui/scroll_controller.py` | 2 | **新建** (~60行) |
+| `src/nexforge/stats/heartbeat.py` | 1 | 静默异常 → 日志 |
+| `src/nexforge/config.py` | 3 | 加可配置常量 |
+| `src/nexforge/utils/logging.py` | 3 | **新建** |
+| `resources/help.md` | 3 | **新建** |
+| `resources/system_prompt.md` | 3 | **新建** |
+
+---
+
+## 风险控制
+
+- **阶段1 零风险**:纯删除/移动代码,不改变功能
+- **阶段2 低风险**:拆分后立即运行全量测试(47个),任一失败回滚
+- **阶段3 可分批**:常量提取和日志模块单独 commit,便于回退
+
+---
+
+## 预期效果
+
+| 指标 | 当前 | 目标 |
+|------|------|------|
+| `chat.py` 行数 | 949 | ~250 |
+| 单文件最大行数 | 949 | ~270 |
+| 死代码行数 | 20+ | 0 |
+| 静默异常 | 12处 | 0处(全部日志) |
+| 可配置常量 | 0 | 7个 |
+| 模块间依赖 | 全耦合在 Screen | 依赖注入 |

nexforge_cli-0.2.9/doc//347/211/271/346/200/247/346/250/241/345/235/227/346/263/250/345/206/214/345/210/266-/345/256/236/346/226/275/350/256/241/345/210/222.md

@@ -0,0 +1,37 @@
+# 特性模块注册制 实施计划
+
+## 目标
+
+将 ChatScreen 所有特性解耦为可插拔模块,后续新增功能无需改 ChatScreen。
+
+## 架构
+
+```
+ChatScreen (控制器, <200 行)
+  └── FeatureRegistry
+        ├── SlashFeature      → /commands
+        ├── GoalModeFeature   → 目标模式
+        ├── OpsModeFeature    → 运维模式
+        ├── StatsFeature      → 心跳
+        └── SessionFeature    → 会话管理
+```
+
+## 需要做的事情
+
+1. **创建 Feature 基类** (`src/nexforge/features/base.py`)
+2. **创建 FeatureRegistry** (`src/nexforge/features/registry.py`)
+3. **提取现有特性为 Feature**
+   - SlashFeature (已有 SlashCommandHandler)
+   - GoalModeFeature (目标循环)
+   - OpsModeFeature (运维模式)
+   - StatsFeature (心跳)
+   - SessionFeature (会话管理)
+4. **精简 ChatScreen** (只保留 compose/on_mount/_run_agent/_refresh_status)
+5. **ChatScreen.on_mount 注册所有 Feature**
+
+每个 Feature 只暴露 3 个钩子:
+- `register(screen)` → 注入引用
+- `on_mount()` → 启动时初始化
+- `bindings()` → 返回需要的快捷键
+
+新增功能: 只需写一个 Feature 类 + 注册,不改 ChatScreen。

nexforge_cli-0.2.9/doc//351/241/271/347/233/256/346/200/273/347/233/221/345/276/252/347/216/257-/345/274/200/345/217/221/350/256/241/345/210/222.md

@@ -0,0 +1,172 @@
+# 项目总监循环 开发计划
+
+> 版本: v1.0 · 创建: 2026-07-16 · 状态: 设计完成,待实现
+
+---
+
+## 概述
+
+在目标模式(`/goal`)下,引入"项目总监 + 开发者"双角色架构。项目总监负责制定计划、审核进展、分发任务;开发者负责具体执行。目标是让 AI 能够自主完成复杂的多轮开发任务,同时保证质量和可追溯性。
+
+---
+
+## 角色定义
+
+### 项目总监 (Director)
+
+- **职责**:审核开发者报告 → 判断进展 → 发布下一条指令
+- **审核维度**:代码质量、性能瓶颈、稳定性、用户体验、逻辑流程
+- **防僵局策略**:当开发者反复说"任务完成"时,从以下方向主动寻找新工作:
+  - 边界情况覆盖
+  - 测试补充
+  - 性能优化
+  - 文档/代码注释
+  - 代码重构整理
+  - 是否真正满足核心需求
+- **停止判断**:若目标已达成,回复 `GOAL_ACHIEVED` 关键词
+
+### 开发者 (Developer)
+
+- **职责**:执行项目总监的指令 → 完成后提交总结报告
+- **行为约束**:专注执行指令,不做多余的事
+
+---
+
+## 启动流程 (二步确认)
+
+```
+用户输入 /goal
+  → Step 1: 弹出风险警告弹窗(GoalModeModal)
+  → Step 2: 弹出多行输入框,用户输入目标描述
+  → Step 3: 显示目标预览,提示"回复确认开始"
+  → Step 4: 用户回复"确认"/"开始"/"ok"/"yes"
+  → Step 5: 正式启动
+```
+
+### 启动时操作
+1. `self.config.ui.goal_mode = True`
+2. `self.config.ui.mode = "auto"` (强制全自动)
+3. 保存到项目级 `config.toml`
+4. 创建 `.nexforge/goal/nfgoal.md` (记录最终目标)
+5. 发送首轮指令给 AI:"[项目总监] 制定开发计划并发布第一条指令"
+
+---
+
+## 循环流程
+
+```
+每个 AI 回合结束 (TURN_DONE)
+  → 如果 goal_mode == True:
+      → 调用 _goal_cycle_continue(last_response)
+      → 检查停止条件
+      → 显示项目总监金色消息
+      → 构造总监 prompt(包含目标+计划+开发者报告)
+      → 启动下一轮 AI
+```
+
+### 停止条件 (任一满足即停止)
+
+| 条件 | 检测方式 | 操作 |
+|------|---------|------|
+| 余额耗尽 | `_balance == "0.00"` | 显示"账户余额耗尽",退出目标模式 |
+| 总监判断达成 | `last_response` 含 `GOAL_ACHIEVED` | 显示"项目总监判断目标达成" |
+| 达到最大轮数 | `current >= max_rounds` (默认 100,可通过 `/max N` 设置) | 显示"达到最大轮数" |
+
+---
+
+## UI 显示
+
+### 项目总监消息 (金色)
+```python
+class DirectorNote(Static):
+    """👔 项目总监: 消息内容 (金色 #FFD700 加粗)"""
+```
+
+- 每轮开始前在聊天区显示金色提示条
+- 格式:`第 N/M 轮:项目总监审核`
+
+### 状态栏
+- 目标模式开启时显示 `🎯 目标`
+- 运维模式开启时显示 `🔧 运维`
+
+---
+
+## 快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| F7 | 切换运维模式 |
+| F8 | 切换目标模式(开启时强制全自动) |
+| Esc | 目标模式三级停止:停总监 → 停开发者 → 退出 |
+
+### Esc 三级停止逻辑
+```
+Esc 第1次:停止项目总监(goal_mode=False,开发者继续当前工作)
+Esc 第2次:取消开发者 worker
+Esc 第3次:弹出退出确认
+```
+
+---
+
+## 文件体系 (项目隔离,仅目标模式)
+
+```
+<项目>/.nexforge/goal/
+├── nfgoal.md           ← 最终目标
+├── plan.md             ← 项目总监编写的计划
+└── rounds/
+    ├── 001.md           ← 第1轮:开发者报告 + 总监审核
+    ├── 002.md           ← 第2轮
+    └── ...
+```
+
+- 非目标模式不创建此目录
+- 离开目标模式后不自动清理(保留历史)
+
+---
+
+## 配置项
+
+| 配置 | 默认 | 说明 |
+|------|------|------|
+| `ui.goal_mode` | `false` | 是否处于目标模式 |
+| `ui.ops_mode` | `false` | 是否处于运维模式 |
+| `ui.max_rounds` | `100` | 目标模式最大轮数,通过 `/max N` 修改 |
+| `ui.mode` | `review` | 审批模式(review/auto) |
+
+---
+
+## 涉及文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/nexforge/core/goal_manager.py` | **已创建** — GoalManager 类 |
+| `src/nexforge/ui/screens/chat.py` | 加 `_start_goal_mode`、`_confirm_goal_start`、`_goal_cycle_continue` |
+| `src/nexforge/ui/widgets/messages.py` | **已创建** — DirectorNote 金色组件 |
+| `src/nexforge/ui/widgets/mode_warning.py` | 已有 GoalModeModal、OpsModeModal |
+| `src/nexforge/config.py` | goal_mode/ops_mode/max_rounds 字段 |
+| `src/nexforge/store/session_store.py` | 会话保存过滤系统消息(已实现) |
+
+---
+
+## 实现注意事项
+
+1. **不要用 heredoc/多行字符串替换编辑 chat.py**——该文件已因反复编辑损坏多次
+2. **使用 `edit_file` 工具逐个精准替换**,每次编辑后编译验证
+3. **`_goal_cycle_continue` 必须独立为类方法**,不能嵌入其他方法中
+4. **字符串拼接用 `+` 而非 f-string 跨行**,避免语法错误
+5. **`save_config` 按项目保存**(`<cwd>/.nexforge/config.toml`),不污染全局
+6. **系统消息不保存到会话文件**(已在 session_store.py 实现)
+
+---
+
+## 测试验证
+
+- [ ] `/goal` → 弹窗 → 输入目标 → "确认" → 项目总监启动
+- [ ] F8 一键切换目标模式
+- [ ] F7 一键切换运维模式
+- [ ] Esc 三级停止(目标模式)
+- [ ] `GOAL_ACHIEVED` 自动停止
+- [ ] `/max 50` 修改轮数上限
+- [ ] 不同项目独立模式状态
+- [ ] 余额耗尽自动停止

nexforge_cli-0.2.9/manual/01-/345/256/211/350/243/205/344/270/216/351/205/215/347/275/256.md

@@ -0,0 +1,83 @@
+# 安装与配置
+
+> NexForgeCLI v0.2.9
+
+## 环境要求
+
+- Python **3.11+**
+- 终端：Windows Terminal / macOS Terminal / Linux 任意终端
+- 网络：能访问 API 端点
+
+## 安装
+
+```bash
+# 方式一：Pip 安装(推荐)
+pip install nexforge-cli
+
+# 方式二：源码安装(开发)
+git clone https://gitee.com/Lighthorn/nexforgecli.git
+cd nexforgecli
+pip install -e .
+```
+
+## 运行
+
+```bash
+nf
+# 或全称
+nexforge
+```
+
+## 配置 API Key
+
+首次启动会弹出 API Key 输入面板，直接粘贴 Key 即可。
+
+也可以手动配置：
+
+**通过命令行**
+```
+/key sk-你的密钥      # 在 nf 输入框里输入
+```
+
+**通过环境变量**
+```bash
+export DEEPSEEK_API_KEY="sk-你的密钥"       # Linux/macOS
+set DEEPSEEK_API_KEY=sk-你的密钥            # Windows CMD
+$env:DEEPSEEK_API_KEY="sk-你的密钥"         # PowerShell
+```
+
+**获取 Key**
+
+DeepSeek：https://platform.deepseek.com/api_keys
+
+其他模型（Kimi/GPT/Claude）：参见 [03-模型配置](03-模型配置.md)
+
+API Key 保存在 `~/.nexforge/auth.toml`，不会被 Git 追踪。
+
+## 首次运行自动生成
+
+首次运行 nf 会自动生成以下配置文件：
+
+| 文件 | 位置 | 内容 |
+|------|------|------|
+| models.toml | `~/.nexforge/` | 多模型配置模板（只读） |
+| config.toml | `~/.nexforge/` | 用户级 UI 配置 |
+| tools.json | `~/.nexforge/` | 外部工具清单模板 |
+
+均不会覆盖已有文件。
+
+## 升级
+
+```bash
+pip install --upgrade nexforge-cli
+```
+
+## 卸载
+
+```bash
+pip uninstall nexforge-cli -y
+```
+
+配置文件和数据保留在以下目录，需手动删除：
+- `~/.nexforge/`（用户级配置和会话）
+- 项目目录下的 `.nexforge/`（项目级配置和会话）

nexforge_cli-0.2.9/manual/02-/347/225/214/351/235/242/344/270/216/345/277/253/346/215/267/351/224/256.md

@@ -0,0 +1,110 @@
+# 界面与快捷键
+
+## 界面布局
+
+```
+┌── 顶部横幅 ──────────────────────────────────────────────┐
+│ 🧠 NexForgeCLI                              📁 项目名     │
+├── 对话区 ────────────────────────────────────────────────┤
+│  [用户消息]                                              │
+│  [AI 回复 · 思考面板(可折叠) · 工具调用卡片]           │
+│                                                          │
+│  ── 本轮结束 · F4 复制最后回复                          │
+├── 输入区 ────────────────────────────────────────────────┤
+│ > 请输入…                                                │
+│ F1帮助 · F2模式 · F3编辑器 · F5会话 · F6模型 · F10快捷回复│
+├── 状态栏 ────────────────────────────────────────────────┤
+│ 🔥 全自动 · deepseek · flash · 思考:开 · 8k token · ¥0.00│
+└──────────────────────────────────────────────────────────┘
+```
+
+## 状态栏信息
+
+| 信息 | 含义 |
+|------|------|
+| 🔥全自动 / ⚡半自动 / 🛡审核 | 当前权限级别 |
+| 模型名 | 正在使用的模型(deepseek/kimi/…) |
+| flash/pro/auto | 模型档位 |
+| 思考:开/关 | DeepSeek thinking 模式 |
+| context tokens | 当前会话的上下文长度 |
+| ¥xxx | 估算费用(实际 token × 固定汇率 7.2) |
+| 🟢绿色点 | AI 正在工作中(标题栏) |
+
+## 终端标签
+
+每个 nf 实例会将终端标题设置为 `NF-项目文件夹名`。多个项目同时开 tab 时一眼分辨。
+
+## 快捷键
+
+| 按键 | 功能 |
+|------|------|
+| `Enter` | 发送消息 |
+| `Esc` | AI 工作中：停止；空闲时：退出确认 |
+| `F1` | 帮助 |
+| `F2` | 切换审批模式(审批/半自动/全自动) |
+| `F3` | 系统默认编辑器编辑文本 |
+| `F4` | 复制最后一条 AI 回复 |
+| `F5` | 会话侧边栏(切换/重命名/删除) |
+| `F6` | 模型选择侧边栏 |
+| `F7` | 切换运维模式 |
+| `F8` | 切换目标模式(总监循环) |
+| `F9` | 粘贴截图 |
+| `F10` | 激活快捷回复 |
+| `Ctrl+C` | 复制最后 AI 回复(备选键) |
+| `Ctrl+L` | 清屏 |
+| `↑/↓` | 滚动对话 |
+| `PageUp/PageDown` | 上下翻页 |
+| `End` | 滚到底部 |
+
+## 斜杠命令
+
+**模型与账户**
+
+| 命令 | 说明 |
+|------|------|
+| `/key <key>` | 设置 API Key |
+| `/provider [<name>]` | 无参数列出提供者;带参数切换 |
+| `/model flash|pro|auto` | 切换模型档位(仅 DeepSeek) |
+| `/think on|off` | 开关思考模式(仅 DeepSeek) |
+| `/balance` | 查询账户余额(仅 DeepSeek) |
+| `/cost` | 显示累计费用 |
+
+**模式切换**
+
+| 命令 | 说明 |
+|------|------|
+| `/mode safe|supervised|auto` | 切换权限级别(审批模式) |
+| `/plan` | 切换计划模式(只读讨论) |
+| `/json` | 切换 JSON 输出模式 |
+| `/goal` | 切换目标模式(总监循环) |
+| `/ops` | 切换运维场景 |
+| `/max <N>` | 目标场景最大轮数(默认200) |
+
+**会话管理**
+
+| 命令 | 说明 |
+|------|------|
+| `/save [name]` | 保存并命名当前会话 |
+| `/rename <name>` | 重命名当前会话 |
+| `/sessions` | 列出历史会话 |
+| `/clear` | 清空当前会话 |
+
+**高级功能**
+
+| 命令 | 说明 |
+|------|------|
+| `/skill <name>` | 执行指定技能 |
+| `/skills` | 列出可用技能 |
+| `/qr <文本>` | 设置快捷回复(F10 激活) |
+| `/qrcount <N>` | 快捷回复循环次数(默认3) |
+| `/memory [view|add|search]` | 管理持久记忆 |
+| `/federation init|add|context|memory` | 联结体管理 |
+| `/map view|check|sync` | 项目地图管理 |
+| `/web start|stop` | Web 管理面板(端口8899) |
+
+**系统**
+
+| 命令 | 说明 |
+|------|------|
+| `/help` | 显示帮助 |
+| `/quit` | 退出 |

nexforge_cli-0.2.9/manual/03-/346/250/241/345/236/213/351/205/215/347/275/256.md

@@ -0,0 +1,98 @@
+# 模型配置
+
+NexForgeCLI 支持多模型：
+
+| 模型 | 支持方式 | 说明 |
+|------|----------|------|
+| **DeepSeek V4** | 内置 | flash/pro 双档位 + auto 自动路由，无需额外配置 |
+| **OpenAI 兼容** | models.toml | Kimi/GPT/通义千问/智谱等一切 OpenAI 兼容接口 |
+| **Anthropic** | models.toml | Claude 系列(需安装额外依赖) |
+
+## DeepSeek（内置默认）
+
+DeepSeek 是内置的默认模型，首次运行只需提供 API Key 即可使用。
+
+**档位**：
+
+| 档位 | 说明 | 适用场景 |
+|------|------|----------|
+| flash | 快速模型 | 常规编码、文件操作、日常问答 |
+| pro | 推理模型 | 复杂算法、架构设计、调试 |
+| auto | 自动路由 | 默认。小任务 flash，大任务自动升级 pro |
+
+auto 模式下的升级触发条件：
+- 关键词(重构/架构/算法/证明/调试/为什么/设计)
+- 上下文超过 200K tokens
+- 同一任务连续工具失败 2 次
+
+**思考模式**：
+- 默认开启，实时显示 AI 的推理过程(可折叠面板)
+- `/think off` 关闭思考(速度更快、费用更低)
+
+## 配置多模型（models.toml）
+
+编辑 `~/.nexforge/models.toml`（首次运行自动生成模板）：
+
+```toml
+# 示例：Kimi
+[[provider]]
+name = "kimi"
+type = "openai"
+api_key = "sk-your-key"
+base_url = "https://api.example.com/v1"
+models = ["kimi-k3"]
+```
+
+```toml
+# 示例：Claude
+[[provider]]
+name = "claude"
+type = "anthropic"
+api_key = "sk-ant-your-key"
+models = ["claude-sonnet-4-20250514"]
+# 安装依赖：pip install "nexforge-cli[anthropic]"
+```
+
+**配置要点**：
+- `name`：唯一标识符，用于切换
+- `type`：`openai` 或 `anthropic`
+- `api_key`：直接填写 Key；也可留空，改用 `api_key_env` 指定环境变量名
+- `api_key_env`：可选，指定从哪个环境变量读取 Key（如 `KIMI_API_KEY`）
+- `api_key` 和 `api_key_env` 都未配置 → 回退到全局保存的 Key（`~/.nexforge/auth.toml`）
+- `models`：可用模型 ID 列表
+- `default_model`：可选，指定默认模型，不填取 models 第一个
+
+软件只读不写此文件，不用担心 Key 被覆盖。
+
+## F6 模型侧边栏
+
+按 `F6` 打开模型侧边栏：
+
+```
+┌─ 模型选择 ──────────────┐
+│ ● deepseek  ✓            │  ← 当前使用(绿点)
+│   类型: deepseek          │
+│   ● 自动 · 闪速 · 专业   │  ← 档位切换
+│                          │
+│ ● kimi  ✓                │  ← 已验证(绿色✓)
+│   类型: openai           │
+│   ✓ 已验证                │  ← 可直接切换
+│                          │
+│   claude  ⚪             │  ← 未验证(灰色)
+│   [🔍 验证]              │  ← 先验证再使用
+```
+
+**操作**：
+1. 点击模型名 → 切换到该模型
+2. 点击「验证」→ 测试 API 能否连通。验证成功后模型名变绿色，可切换。
+3. 点击「验证全部」→ 批量验证所有未验证模型
+4. DeepSeek 子选项 → 切换 auto/flash/pro 档位
+
+切换后自动持久化，重启 nf 保持选中。
+
+## 自动路由 vs 多模型切换
+
+- **自动路由**（DeepSeek auto 档）：同一个模型内，根据任务复杂度自动选择 flash 或 pro
+- **模型切换**：选择完全不同的模型提供商(DeepSeek → Kimi → Claude)
+
+两者互不冲突。auto 路由是你对 DeepSeek 的智能调度；模型切换是在不同 API 提供商之间选择。