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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexforge-cli
-Version: 0.2.6
+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/STATS_API.md

@@ -0,0 +1,209 @@
+# NexTech 软件统计 API 文档
+
+> 版本: 1.0
+> 基础路径: `https://nextech.club/api/stats.php`
+
+---
+
+## 概述
+
+轻量级软件在线统计服务，用于采集和查询软件客户端的下载量、在线用户数等指标。采用 **SQLite** 存储 + **POST 心跳** 机制，支持万级并发。
+
+### 设计原则
+
+- 最小资源消耗：单条 SQLite `INSERT OR REPLACE` 写入，无 MySQL 开销
+- 自动过期清理：120 秒无心跳自动标记离线
+- 批量清理：每 10 次心跳触发一次过期记录删除
+
+---
+
+## 接口列表
+
+### 1. 软件心跳上报
+
+```
+POST /api/stats.php?action=heartbeat
+Content-Type: application/json
+```
+
+上报软件客户端的在线状态，建议每 **60 秒** 调用一次。
+
+#### 请求参数
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `software` | string | 是 | 软件名称（如 `NexAgent`、`NexClient`） |
+| `client_id` | string | 是 | 客户端唯一标识（每台设备的 ID） |
+
+#### 请求示例
+
+```bash
+curl -X POST https://nextech.club/api/stats.php?action=heartbeat \
+  -H "Content-Type: application/json" \
+  -d '{"software":"NexAgent","client_id":"device-001"}'
+```
+
+#### 响应示例
+
+```json
+{
+    "ok": true,
+    "online_total": 42,
+    "cleaned": 3
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `ok` | bool | 是否成功 |
+| `online_total` | int | 当前总在线数 |
+| `cleaned` | int | 本次清理的过期记录数 |
+
+#### 错误响应
+
+```json
+{
+    "ok": false,
+    "error": "software 和 client_id 不能为空"
+}
+```
+
+HTTP 状态码: `400`
+
+---
+
+### 2. 获取统计
+
+```
+GET /api/stats.php
+```
+
+返回当前在线用户数（按软件分组）和今日软件下载量。
+
+#### 请求示例
+
+```bash
+curl https://nextech.club/api/stats.php
+```
+
+#### 响应示例
+
+```json
+{
+    "ok": true,
+    "time": "2026-07-21 06:48:00",
+    "online": {
+        "total": 42,
+        "by_software": {
+            "NexAgent": 30,
+            "NexClient": 12
+        }
+    },
+    "downloads": [
+        {
+            "name": "nexhttp-1.0.0.zip",
+            "count": 4,
+            "size_mb": 23.37
+        }
+    ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `online.total` | int | 总在线数（120 秒内有心跳） |
+| `online.by_software` | object | 按软件名称分组的在线数 |
+| `downloads[]` | array | 今日下载统计列表 |
+| `downloads[].name` | string | 下载文件名 |
+| `downloads[].count` | int | 今日下载次数 |
+| `downloads[].size_mb` | float | 文件大小（MB） |
+
+---
+
+## 客户端接入示例
+
+### Python
+
+```python
+import requests
+import time
+import uuid
+
+CLIENT_ID = str(uuid.uuid4())  # 每台设备固定一个 ID
+
+def heartbeat():
+    while True:
+        try:
+            r = requests.post(
+                "https://nextech.club/api/stats.php?action=heartbeat",
+                json={"software": "NexAgent", "client_id": CLIENT_ID},
+                timeout=5
+            )
+            print(f"心跳成功: {r.json()['online_total']} 在线")
+        except Exception as e:
+            print(f"心跳失败: {e}")
+        time.sleep(60)  # 每 60 秒上报一次
+```
+
+### JavaScript / Node.js
+
+```javascript
+const CLIENT_ID = 'device-' + Math.random().toString(36).substr(2, 9);
+
+setInterval(async () => {
+    try {
+        const res = await fetch('https://nextech.club/api/stats.php?action=heartbeat', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ software: 'NexClient', client_id: CLIENT_ID })
+        });
+        const data = await res.json();
+        console.log(`心跳成功: ${data.online_total} 在线`);
+    } catch (e) {
+        console.error('心跳失败:', e);
+    }
+}, 60000);
+```
+
+### C / C++（libcurl）
+
+```c
+#include <curl/curl.h>
+
+void heartbeat() {
+    CURL *curl = curl_easy_init();
+    if (!curl) return;
+    
+    char json[256];
+    snprintf(json, sizeof(json), 
+        "{\"software\":\"NexAgent\",\"client_id\":\"%s\"}", DEVICE_ID);
+    
+    curl_easy_setopt(curl, CURLOPT_URL, 
+        "https://nextech.club/api/stats.php?action=heartbeat");
+    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json);
+    curl_easy_setopt(curl, CURLOPT_TIMEOUT, 5);
+    curl_easy_perform(curl);
+    curl_easy_cleanup(curl);
+}
+```
+
+---
+
+## 性能参考
+
+| 并发数 | 每次心跳 | SQLite 写入 | 服务器负载 |
+|--------|----------|-------------|-----------|
+| 100    | 60 秒    | 1.7 次/秒   | < 0.1% CPU |
+| 1,000  | 60 秒    | 17 次/秒    | < 0.5% CPU |
+| 10,000 | 60 秒    | 167 次/秒   | ~3% CPU |
+| 50,000 | 60 秒    | 833 次/秒   | ~15% CPU |
+
+---
+
+## 技术细节
+
+- **数据库**: SQLite3 `/tmp/software_online.db`
+- **表结构**: `heartbeats(id, software, client_id, last_seen, ip)`
+- **过期 TTL**: 120 秒
+- **清理策略**: 每 10 次心跳批量 `DELETE WHERE last_seen < now - 120`
+- **索引**: `idx_last_seen`、`idx_software`

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/`（项目级配置和会话）