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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.7
+Version: 0.2.11
 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'
@@ -46,9 +49,9 @@ Description-Content-Type: text/markdown
 
 </div>
 
-NexForgeCLI 是一个运行在终端里的智能体助手,专为 **DeepSeek V4** 打造。既能作为全屏 TUI 交互式对话/编码,也能作为 one-shot 命令行工具嵌进脚本和管道。
+NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
 
-> 当前版本:**v0.2.5** · PyPI: `pip install nexforge-cli`
+> 当前版本:**v0.2.11** · PyPI: `pip install nexforge-cli`
 
 ---
 
@@ -78,14 +81,16 @@ API Key 获取: https://platform.deepseek.com/api_keys
 
 ## ✨ 特性
 
-- **DeepSeek V4 深度优化** —— thinking 模式、KV Cache、streaming、采样参数、JSON Mode、tool_choice 全适配
-- **TUI 全屏交互** —— Textual 驱动,流式 Markdown、可折叠思考面板、工具卡片、状态栏
-- **安全分级** —— safe/supervised/auto 三级权限,审批弹窗
+- **多模型底座** —— DeepSeek(内置) / 千问专用底座 / 通用 OpenAI 兼容 / Anthropic，`/provider` 即切
+- **插件宿主** —— `plugins/` 目录即插即用(工具/UI特性/技能)，无需改主程序
+- **三级知识库** —— 全局+项目+项目地图，kb_search 检索、kb_write 沉淀
+- **DeepSeek 深度优化** —— thinking 模式、KV Cache、streaming、采样参数、JSON Mode、tool_choice 全适配
+- **TUI 全屏交互** —— Textual 驱动，流式 Markdown、可折叠思考面板、工具卡片、状态栏
+- **安全分级** —— safe/supervised/auto 三级权限，审批弹窗
 - **会话管理** —— 自动保存/恢复、多会话切换、重命名/删除
-- **计划模式** —— 只读讨论,AI 生成计划后执行
+- **计划模式** —— 只读讨论，AI 生成计划后执行
 - **多行输入** —— F2 弹窗面板、F3 系统编辑器
 - **一键安装** —— `pip install nexforge-cli`
-- **性能优化** —— O(n²)→O(n) 流式渲染、DOM 查询缓存、I/O 异步化
 
 ---
 
@@ -122,14 +127,12 @@ nexforge -p "这个项目是做什么的?"
 
 | 文档 | 内容 |
 |------|------|
-| [总览](doc/总览.md) | 项目介绍 |
-| [安装与配置](doc/安装与配置.md) | 安装/配置/FAQ |
-| [命令与快捷键](doc/命令与快捷键.md) | 全部命令和快捷键 |
-| [工具参考](doc/工具参考.md) | AI 可调用工具说明 |
-| [会话管理](doc/会话管理.md) | 会话保存/恢复/切换 |
-| [计划模式](doc/计划模式.md) | 只读讨论模式 |
-| [权限系统](doc/权限系统.md) | 三级权限 |
-| [高级功能](doc/高级功能.md) | DeepSeek 集成/Web/技能 |
+| [01-安装与配置](manual/01-安装与配置.md) | 安装/配置/API Key |
+| [02-界面与快捷键](manual/02-界面与快捷键.md) | 全部命令和快捷键 |
+| [03-模型配置](manual/03-模型配置.md) | DeepSeek/千问/多模型接入 |
+| [04-工具参考](manual/04-工具参考.md) | AI 可调用工具说明 |
+| [08-自定义配置](manual/08-自定义配置.md) | config.toml/models.toml 全字段 |
+| [10-插件开发](manual/10-插件开发.md) | 插件宿主开发指南 |
 
 ---
 

nexforge_cli-0.2.11/README.md

@@ -0,0 +1,109 @@
+<div align="center">
+
+# ◆ NexForgeCLI
+
+**面向 DeepSeek V4 的终端智能体 · TUI + CLI 双模式**
+
+</div>
+
+NexForgeCLI 是一个运行在终端里的智能体助手，既支持 DeepSeek/千问等多模型，也是**插件宿主**（plugins 目录即插即用）。既能作为全屏 TUI 交互式对话/编码，也能作为 one-shot 命令行工具嵌进脚本和管道。
+
+> 当前版本:**v0.2.11** · PyPI: `pip install nexforge-cli`
+
+---
+
+## 📦 安装
+
+```bash
+# pipx 安装(推荐,自动管理 PATH)
+pipx install nexforge-cli
+
+# pip 安装
+pip install nexforge-cli
+
+# 开发版
+pip install git+https://gitee.com/Lighthorn/nexforgecli.git
+```
+
+设置 API Key:
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."
+# 或启动后在输入框输入: /key sk-...
+```
+
+API Key 获取: https://platform.deepseek.com/api_keys
+
+---
+
+## ✨ 特性
+
+- **多模型底座** —— DeepSeek(内置) / 千问专用底座 / 通用 OpenAI 兼容 / Anthropic，`/provider` 即切
+- **插件宿主** —— `plugins/` 目录即插即用(工具/UI特性/技能)，无需改主程序
+- **三级知识库** —— 全局+项目+项目地图，kb_search 检索、kb_write 沉淀
+- **DeepSeek 深度优化** —— thinking 模式、KV Cache、streaming、采样参数、JSON Mode、tool_choice 全适配
+- **TUI 全屏交互** —— Textual 驱动，流式 Markdown、可折叠思考面板、工具卡片、状态栏
+- **安全分级** —— safe/supervised/auto 三级权限，审批弹窗
+- **会话管理** —— 自动保存/恢复、多会话切换、重命名/删除
+- **计划模式** —— 只读讨论，AI 生成计划后执行
+- **多行输入** —— F2 弹窗面板、F3 系统编辑器
+- **一键安装** —— `pip install nexforge-cli`
+
+---
+
+## 🚀 使用
+
+```bash
+# 全屏 TUI(默认)
+nexforge
+
+# 或简写
+nf
+
+# one-shot 模式
+nexforge -p "这个项目是做什么的?"
+```
+
+### 快捷键
+
+| 快捷键 | 功能 |
+|--------|------|
+| `Enter` | 发送消息 |
+| `F1` | 帮助 |
+| `F2` | 多行输入弹窗 |
+| `F3` | 外部编辑器 |
+| `Ctrl+S` | 会话面板 |
+| `Ctrl+B` | 计划面板 |
+| `Ctrl+L` | 清屏 |
+| `Ctrl+Shift+C` | 复制 AI 回复 |
+| `Esc` | 停止/退出 |
+
+---
+
+## 📁 文档
+
+| 文档 | 内容 |
+|------|------|
+| [01-安装与配置](manual/01-安装与配置.md) | 安装/配置/API Key |
+| [02-界面与快捷键](manual/02-界面与快捷键.md) | 全部命令和快捷键 |
+| [03-模型配置](manual/03-模型配置.md) | DeepSeek/千问/多模型接入 |
+| [04-工具参考](manual/04-工具参考.md) | AI 可调用工具说明 |
+| [08-自定义配置](manual/08-自定义配置.md) | config.toml/models.toml 全字段 |
+| [10-插件开发](manual/10-插件开发.md) | 插件宿主开发指南 |
+
+---
+
+## 🧪 开发
+
+```bash
+git clone https://gitee.com/Lighthorn/nexforgecli.git
+cd nexforgecli
+pip install -e ".[dev]"
+python -m pytest -q
+```
+
+---
+
+## 📄 License
+
+MIT

nexforge_cli-0.2.11/_tmp_whl_check.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""临时: 验证 wheel 内容完整性, 验证后删除"""
+import glob
+import sys
+import zipfile
+
+sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+
+whl = glob.glob("dist/*.whl")[0]
+names = zipfile.ZipFile(whl).namelist()
+check = [
+    "plugin.py", "knowledge_base.py", "context.py", "qianwen.py",
+    "kb_tools.py", "summarizer.py", "goal_manager.py", "speech",
+]
+missing = [c for c in check if not any(n.endswith("/" + c) for n in names)]
+print("wheel:", whl)
+print("总文件数:", len(names))
+print("缺失:", missing or "无 ✓")
+assert not missing

nexforge_cli-0.2.11/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.11/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.11/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.11/docs/submission/README-/346/212/225/347/250/277/350/257/264/346/230/216.md

@@ -0,0 +1,67 @@
+# 投稿 NexForgeCLI 到 awesome-deepseek-agent
+
+## 已准备好的文件
+
+```
+docs/submission/
+  nexforge.md            ← 英文指南(可直接用)
+  nexforge.zh-CN.md      ← 简体中文指南(可直接用)
+```
+
+## 需要你手动做的 4 步(需要 GitHub 账号)
+
+### 第 1 步: Fork 仓库
+
+1. 打开 https://github.com/deepseek-ai/awesome-deepseek-agent
+2. 点右上角 **Fork** 到你的账号
+
+### 第 2 步: 上传两个指南文件
+
+在你的 fork 里进入 `docs/` 目录 → **Add file → Upload files**:
+
+```
+docs/nexforge.md           ← 内容取自 docs/submission/nexforge.md
+docs/nexforge.zh-CN.md     ← 内容取自 docs/submission/nexforge.zh-CN.md
+```
+
+### 第 3 步: 修改两个 README(插入表格条目)
+
+**README.md**(英文版): 在 `| **nanobot** |` 行之后、`| **Oh My Pi** |` 行之前插入:
+
+```markdown
+| **NexForgeCLI** | Open-source terminal AI coding assistant with 35 built-in tools, native DeepSeek-V4 support (1M context), data analysis, web search, and a director-loop goal mode. | [Guide](./docs/nexforge.md) |
+```
+
+**README.zh-CN.md**(中文版): 同样位置(在 nanobot 之后、Oh My Pi 之前)插入:
+
+```markdown
+| **NexForgeCLI** | 开源终端 AI 编程助手，内置 35 个工具，原生支持 DeepSeek-V4（100 万上下文）、数据分析、网络搜索与总监循环目标模式。 | [指南](./docs/nexforge.zh-CN.md) |
+```
+
+> 注意: 按字母序插入(Ne 在 na 和 Oh 之间), 不要追加到表格末尾, 否则合并冲突概率高。
+
+### 第 4 步: 提交 PR
+
+1. 在 fork 仓库页面点 **Contribute → Open Pull Request**
+2. Base: `deepseek-ai/awesome-deepseek-agent:main` ← Compare: `你的fork:main`
+3. PR 标题建议: `Add NexForgeCLI integration guide (EN + zh-CN)`
+4. 描述里注明: 双语指南在一个 PR 内、README 表格按字母序插入
+
+## 已满足的 CONTRIBUTING.md 硬性要求
+
+| 要求 | 状态 |
+|------|------|
+| 双语(英文 + 简体中文, 单 PR) | ✓ 两个文件同 PR |
+| README 表格按字母序插入 | ✓ nanobot 与 Oh My Pi 之间 |
+| 模型命名用新名 deepseek-v4-pro/flash | ✓ 全文无 v3 旧名 |
+| 1M 上下文提及/配置 | ✓ context_window = 1000000 |
+| max 思考档兼容 | ✓ auto 路由自动升级到 max |
+| 不写降级 workaround | ✓ 无 |
+| 配置字段真实存在 | ✓ 全部核实过代码 |
+| 截图 | 未涉及 |
+
+## 注意事项
+
+- 仓库托管在 **gitee**(https://gitee.com/Lighthorn/nexforgecli), PR 描述里说明即可, 不影响收录(README 表格中其他项目也有非 GitHub 托管的情况, 但多数为 GitHub; 若被要求 GitHub 镜像可再考虑)
+- 若 PR 被要求修改, 在 fork 里改对应文件, PR 会自动更新
+- 提交后把 PR 链接发我, 我可以帮你复核 diff