# forge-shell

**Repository Path**: forgemaster/forge-shell

## Basic Information

- **Project Name**: forge-shell
- **Description**: 以意为炉，以语为锤，铸代码之剑
- **Primary Language**: Unknown
- **License**: CC-BY-SA-4.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-17
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 熔炉 (ForgeShell)

> 面向中文开发者、成本极致、自我进化的 AI 编程终端

[![版本](https://img.shields.io/badge/version-0.25.0-blue)]()
[![Rust](https://img.shields.io/badge/rust-1.85+-orange)]()
[![许可](https://img.shields.io/badge/license-AGPLv3-blue)]()
[![平台](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-purple)]()

## 项目简介

熔炉 (ForgeShell) 是一款基于 DeepSeek V4 API 的 AI 编程终端。以"意为炉，以语为锤，铸代码之剑"为理念，采用三阶段架构（Pro 生成 → 语法校验 → Flash 分段修复），根治 DeepSeek 长文生成的质量问题。

## 核心特性

### 架构创新

| 特性 | 说明 |
|------|------|
| **三阶段架构** | Pro 生成代码 → 后端语法校验 → Flash 分段修复（>300 行自动切段，每段 ≤200 行） |
| **Coordinator/Worker** | ≥3 文件任务自动激活：Coordinator(Pro) 拆解任务 → Worker(Flash) 逐文件独立生成 |
| **智能 thinking 控制** | 仅架构选型/Bug 根因/安全审查等 5 大类启用 thinking，代码生成一律关闭 |
| **流超时全覆盖** | 每个流读取循环均有 no-content 硬超时（20-45s），根治 DeepSeek Pro 无限卡死 |

### 工程可靠性

| 特性 | 说明 |
|------|------|
| **L4 tool_call_id 重编号** | 全局唯一化重编号 `call_1, call_2, ...`，消灭 API 400 重复错误 |
| **失败重试+降级** | 网络错误自动重试（干净上下文），Pro 空响应降级 Flash |
| **分段修复** | >300 行文件按段独立 Flash 修复，避免单次修复质量衰减 |
| **cargo 缓存根治** | build.rs 嵌入源文件哈希 + .git/HEAD 监听，改代码无需 cargo clean |
| **edit old_string 匹配** | 内容精确匹配替换，行号偏移自动拒绝，防止误修改 |

### UI 体验

| 特性 | 说明 |
|------|------|
| **三栏布局** | 左栏：文件树(📁) / 会话历史(💬) 双模式切换 |
| **右侧动态面板** | 任务看板(📋) + LSP 诊断(🩺) + 费用(💰) + 进化引擎(🧬) |
| **diff 着色** | edit 结果绿(+)/红(-) 渲染，GitHub 风格 |
| **回退按钮** | 底部栏 ↩ 一键撤销上一步修改 |
| **文件注入上下文** | 点击文件树任意文件 → 内容注入对话 |
| **项目监控** | 构建状态 + 测试状态 + 路径手动/自动切换 |

### 工具生态

| 特性 | 说明 |
|------|------|
| **16 个工具** | read/write/edit/search/glob/exec/lsp/web/web-fetch/todo/ask/semantic/snap/save/community-fix/share-fix |
| **工具智能筛选** | Flash 根据用户意图关键词动态精简工具列表（16→≤10） |
| **进化引擎** | 本地经验收集 + 反思提炼 SOP + 匿名分享社区 |

## 快速开始

### 环境要求

- Rust 1.85+
- DeepSeek API Key ([获取地址](https://platform.deepseek.com))

### 安装构建

```bash
git clone https://gitee.com/forgemaster/forge-shell
cd forge-shell
cargo build --release
```

### 启动运行

```bash
# 启动 Web UI（默认，自动打开浏览器）
./target/release/forge-shell

# 命令行传入 API Key
./target/release/forge-shell --key sk-your-api-key

# 启动 TUI 终端模式
./target/release/forge-shell --tui
```

首次启动后在 Web UI 输入 API Key，之后自动保存，无需重复输入。

## 工作模式

| 模式 | 说明 | 模型 |
|------|------|------|
| **互动** (interactive) | 默认模式，Router 自动选 Pro/Flash | 自动 |
| **速办** (quick) | 强制 Flash（¥0.1/M），自动执行 | Flash |

模型偏好：**智能**(auto) / **Pro** / **Flash**

## API 接口

| 端点 | 方法 | 说明 |
|------|------|------|
| /api/chat | POST | 流式对话 (SSE) |
| /api/check-key | GET | 检查 API Key |
| /api/setup | POST | 初始化配置 |
| /api/update-check | GET | 版本更新检查 |
| /api/update-now | POST | 执行更新 |
| /api/status | GET | 获取运行状态 |
| /api/project | GET | 项目信息 |
| /api/tasks | GET | 任务看板 |
| /api/files | GET | 文件树 |
| /api/evolution | GET | 进化引擎统计 |
| /api/session/latest | GET | 获取最近会话 |
| /api/sessions | GET | 获取会话列表 |
| /api/session/clear | POST | 清空当前会话 |
| /api/session/delete | POST | 删除指定会话 |
| /api/set-project-path | POST | 切换监控目录 |
| /api/rollback | POST | 回退修改 |
| /api/logs | GET | 错误日志查询 |

## 项目结构

```
forge-shell/
├── src/
│   ├── main.rs              # 入口 + PID 管理 + 日志
│   ├── config.rs            # 配置管理 + 设备指纹
│   ├── system_prompt.rs     # AI 系统提示词（生成器/写入器/紧凑版）
│   ├── error.rs             # 错误类型
│   ├── error_log.rs         # 错误日志（环形缓冲+持久化）
│   ├── engine/
│   │   ├── inference/       # DeepSeek API 调用 + SSE 解析 + 消息校验
│   │   ├── router.rs        # 模型路由 + 创建检测 + thinking判断 + 文件数估计
│   │   ├── stream.rs        # StreamAccumulator（流式累积器）
│   │   ├── session.rs       # SessionManager（原子保存/加载）
│   │   ├── conversation.rs  # Conversation 构建器（类型安全）
│   │   ├── context.rs       # 上下文管理 + 缓存命中
│   │   ├── semantic_index.rs # 语义索引
│   │   ├── prompt_optimizer.rs # UCB1 提示词优化器
│   │   └── tools/           # 工具执行 + 沙箱
│   ├── web/
│   │   ├── api.rs           # 主要 API + 工具定义执行 + 三阶段/CW 架构
│   │   ├── mod.rs           # 路由注册 + AppState
│   │   └── static_files.rs  # 嵌入静态资源
│   ├── agent/
│   │   ├── orchestrator.rs  # 任务分解
│   │   ├── dispatcher.rs    # 任务调度
│   │   └── agent_executor.rs # 子任务执行
│   └── evolution/           # 进化引擎（收集/反思/SOP）
├── assets/web/              # 前端资源（HTML/CSS/JS）
├── .github/workflows/       # CI/CD（构建+同步）
└── build.rs                 # 版本号生成 + 源文件哈希
```

## 架构流程

```
用户消息 → Router 分级
              │
    ┌─────────┼─────────┐
    ▼         ▼         ▼
  简单      中等/复杂    大型文件
  Flash     Flash      │
                       ├── ≥3 文件 → C/W 模式
                       │     Coordinator(Pro) 拆任务
                       │     Worker(Flash) 逐文件独立生成
                       │
                       └── <3 文件 → 三阶段架构
                             Phase1: Pro 生成（thinking 关，零工具）
                             Phase2: 语法校验
                             Phase3: >300 行分段 Flash 修复
```

## 费用优势

| 指标 | 熔炉 (DeepSeek V4) | Claude Code |
|------|---------------------|-------------|
| Flash 输入/输出 | ¥0.1/M / ¥0.4/M | **200 倍** |
| Pro 输入/输出 | ¥1/M / ¥4/M | **20 倍** |

## 许可证

AGPLv3 许可证。

## 相关链接

- **官网**: https://forgeshell.cn
- **仓库 (Gitee)**: https://gitee.com/forgemaster/forge-shell
- **仓库 (GitHub)**: https://github.com/xiongshiguo/forge-shell
- **DeepSeek API**: https://platform.deepseek.com