feihong-code 0.6.1 → 7.2.0

package/docs/MODEL_FINETUNING.md

@@ -0,0 +1,405 @@
+# 飞虹 Code - 专用补全模型微调指南 (P3-1)
+
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+## 目录
+
+1. [概述](#1-概述)
+2. [环境准备](#2-环境准备)
+3. [数据准备](#3-数据准备)
+4. [模型训练](#4-模型训练)
+5. [模型评估](#5-模型评估)
+6. [模型导出与部署](#6-模型导出与部署)
+7. [集成到飞虹 Code](#7-集成到飞虹-code)
+
+---
+
+## 1. 概述
+
+飞虹 Code 支持使用专用微调的代码补全模型，通过 FIM (Fill-In-the-Middle) 格式训练，提升代码补全的准确率和上下文理解能力。
+
+### 1.1 技术方案
+
+| 组件 | 说明 |
+|---|---|
+| **基础模型** | bigcode/starcoderbase-1b（或其他代码生成模型） |
+| **微调方法** | LoRA (Low-Rank Adaptation)，仅训练少量参数 |
+| **训练格式** | FIM (Fill-In-the-Middle)，prefix/suffix/middle 三部分 |
+| **评估指标** | 精确匹配率、编辑相似度、前缀匹配率、延迟 |
+| **部署格式** | 合并模型 / GGUF / ONNX |
+
+### 1.2 硬件要求
+
+| 配置 | 最低 | 推荐 |
+|---|---|---|
+| GPU 显存 | 8GB (RTX 3060/4060) | 16GB+ (RTX 3090/4090/A10) |
+| 内存 | 16GB | 32GB+ |
+| 磁盘空间 | 20GB | 50GB+ |
+| 训练时间 | 4-8 小时 (1B 模型) | 1-2 小时 |
+
+---
+
+## 2. 环境准备
+
+### 2.1 安装 Python 依赖
+
+```bash
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate  # Linux/Mac
+# .venv\Scripts\activate   # Windows
+
+# 安装 PyTorch（根据 CUDA 版本选择）
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
+
+# 安装训练依赖
+pip install transformers peft datasets accelerate evaluate sentencepiece
+pip install tensorboard wandb  # 可选：可视化工具
+
+# 安装导出依赖（可选）
+pip install optimum onnxruntime  # ONNX 导出
+pip install llama-cpp-python     # GGUF 导出
+```
+
+### 2.2 验证环境
+
+```bash
+python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')"
+python -c "import transformers; print(f'Transformers: {transformers.__version__}')"
+python -c "import peft; print(f'PEFT: {peft.__version__}')"
+```
+
+---
+
+## 3. 数据准备
+
+### 3.1 使用飞虹 Code 内置数据准备工具
+
+飞虹 Code 提供了 TypeScript 版本的 FIM 数据准备工具，可以直接从代码库生成训练数据。
+
+```bash
+# 编译项目
+npm run build
+
+# 准备 FIM 训练数据
+node dist/cli/index.js fim-prepare \
+  --source-dir ./your-codebase \
+  --output ./data/fim/dataset.jsonl \
+  --samples-per-file 10 \
+  --languages typescript,javascript,python
+```
+
+### 3.2 数据格式
+
+输出为 JSONL 格式，每行一个样本：
+
+```json
+{
+  "prefix": "function calculateSum(a: number, b: number): number {\n  return ",
+  "suffix": "\n}\n\n// 其他代码...",
+  "middle": "a + b",
+  "file_path": "src/math.ts",
+  "language": "typescript",
+  "cursor_offset": 1234,
+  "middle_length": 5
+}
+```
+
+### 3.3 数据划分
+
+工具会自动生成三个文件：
+- `dataset.train.jsonl` - 训练集（90%）
+- `dataset.val.jsonl` - 验证集（10%）
+- `dataset.meta.json` - 元数据（统计信息、配置）
+
+### 3.4 数据质量建议
+
+1. **代码质量**：使用高质量的代码库作为数据源
+2. **语言覆盖**：确保覆盖目标编程语言
+3. **数据量**：建议至少 10,000+ 样本
+4. **去重**：避免重复或高度相似的样本
+5. **过滤**：排除自动生成的代码、minified 文件、测试快照
+
+---
+
+## 4. 模型训练
+
+### 4.1 配置训练参数
+
+编辑 `training/lora-config.json`：
+
+```json
+{
+  "base_model": "bigcode/starcoderbase-1b",
+  "output_dir": "./models/feihong-code-completion",
+  "num_train_epochs": 3,
+  "per_device_train_batch_size": 4,
+  "gradient_accumulation_steps": 4,
+  "learning_rate": 2e-4,
+  "max_seq_length": 2048,
+  "lora": {
+    "r": 16,
+    "lora_alpha": 32,
+    "lora_dropout": 0.05,
+    "target_modules": ["q_proj", "v_proj", "k_proj", "o_proj"]
+  }
+}
+```
+
+### 4.2 关键参数说明
+
+| 参数 | 说明 | 推荐值 |
+|---|---|---|
+| `num_train_epochs` | 训练轮数 | 2-5 |
+| `learning_rate` | 学习率 | 1e-4 ~ 3e-4 |
+| `per_device_train_batch_size` | 每设备批大小 | 2-8（根据显存） |
+| `gradient_accumulation_steps` | 梯度累积步数 | 2-8 |
+| `max_seq_length` | 最大序列长度 | 1024-4096 |
+| `lora.r` | LoRA 秩 | 8-32 |
+| `lora.lora_alpha` | LoRA alpha | 16-64（通常为 r 的 2 倍） |
+| `lora.lora_dropout` | LoRA dropout | 0.05-0.1 |
+
+### 4.3 开始训练
+
+```bash
+cd training
+
+# 使用默认配置训练
+python train.py --config lora-config.json
+
+# 指定基础模型
+python train.py --config lora-config.json --base_model bigcode/starcoderbase-3b
+
+# 从检查点恢复
+python train.py --config lora-config.json --resume ./models/feihong-code-completion/checkpoint-1000
+```
+
+### 4.4 监控训练
+
+```bash
+# TensorBoard
+tensorboard --logdir ./models/feihong-code-completion/runs
+
+# 查看训练日志
+tail -f ./models/feihong-code-complement/train_log.txt
+```
+
+### 4.5 训练技巧
+
+1. **梯度检查点**：启用 `gradient_checkpointing: true` 节省显存
+2. **混合精度**：启用 `bf16: true`（Ampere 及以上 GPU）或 `fp16: true`
+3. **学习率调度**：使用 cosine 调度器，warmup 比例 3%
+4. **早停**：监控验证损失，3 轮无提升则停止
+5. **保存最佳模型**：`load_best_model_at_end: true`
+
+---
+
+## 5. 模型评估
+
+### 5.1 使用飞虹 Code 评估工具
+
+飞虹 Code 提供了 TypeScript 版本的补全模型评估工具。
+
+```bash
+# 编译项目
+npm run build
+
+# 运行评估
+node dist/cli/index.js fim-evaluate \
+  --samples ./data/fim/dataset.val.jsonl \
+  --model ./models/feihong-code-completion \
+  --output ./evaluation/result.json \
+  --max-samples 500
+```
+
+### 5.2 评估指标
+
+| 指标 | 说明 | 目标值 |
+|---|---|---|
+| **精确匹配率** | 预测与期望完全一致的比例 | > 30% |
+| **编辑相似度** | 1 - 编辑距离/最大长度 | > 70% |
+| **前缀匹配率** | 预测前缀与期望前缀的匹配度 | > 60% |
+| **首 Token 匹配率** | 第一个 token 是否匹配 | > 50% |
+| **平均延迟** | 单次补全的平均耗时 | < 500ms |
+
+### 5.3 评估结果示例
+
+```
+=== 补全模型评估结果 ===
+样本数: 500
+精确匹配率: 32.40%
+编辑相似度: 74.56%
+前缀匹配率: 62.30%
+首Token匹配率: 54.80%
+平均延迟: 320.50ms
+
+--- 按语言统计 ---
+typescript: 200 样本, 精确匹配 35.0%, 编辑相似度 76.2%
+javascript: 150 样本, 精确匹配 30.7%, 编辑相似度 73.1%
+python: 100 样本, 精确匹配 28.0%, 编辑相似度 71.5%
+其他: 50 样本, 精确匹配 24.0%, 编辑相似度 68.3%
+```
+
+### 5.4 与基线模型对比
+
+建议在相同数据集上评估基线模型（未微调），对比提升效果：
+
+```bash
+# 评估基线模型
+node dist/cli/index.js fim-evaluate \
+  --samples ./data/fim/dataset.val.jsonl \
+  --model bigcode/starcoderbase-1b \
+  --output ./evaluation/baseline.json
+
+# 对比结果
+node dist/cli/index.js fim-compare \
+  --baseline ./evaluation/baseline.json \
+  --finetuned ./evaluation/result.json
+```
+
+---
+
+## 6. 模型导出与部署
+
+### 6.1 合并 LoRA 权重
+
+训练完成后，需要将 LoRA 权重合并到基础模型：
+
+```bash
+cd training
+
+# 合并 LoRA 并导出
+python export.py \
+  --model_path ./models/feihong-code-completion \
+  --output ./models/exported \
+  --format merged
+```
+
+### 6.2 导出格式
+
+| 格式 | 用途 | 命令 |
+|---|---|---|
+| **merged** | 通用部署（Transformers） | `--format merged` |
+| **GGUF** | llama.cpp 本地推理 | `--format gguf` |
+| **ONNX** | Web / 跨平台部署 | `--format onnx` |
+| **all** | 导出所有格式 | `--format all` |
+
+### 6.3 导出产物
+
+```
+models/exported/
+├── merged/                    # 合并后的模型
+│   ├── config.json
+│   ├── model.safetensors
+│   ├── tokenizer.json
+│   └── training_config.json
+├── gguf/                      # GGUF 格式（可选）
+│   └── model.gguf
+├── onnx/                      # ONNX 格式（可选）
+│   ├── model.onnx
+│   └── tokenizer.json
+└── feihong-model-config.json  # 飞虹 Code 模型配置
+```
+
+---
+
+## 7. 集成到飞虹 Code
+
+### 7.1 配置本地模型
+
+编辑飞虹 Code 配置文件（`~/.feihong-code/config.json`）：
+
+```json
+{
+  "completion": {
+    "provider": "local",
+    "model_path": "./models/exported/merged",
+    "model_config": "./models/exported/feihong-model-config.json",
+    "max_tokens": 100,
+    "temperature": 0.2,
+    "top_p": 0.95,
+    "context_window": 2048
+  }
+}
+```
+
+### 7.2 启动本地推理服务
+
+```bash
+# 使用飞虹 Code 内置的本地模型服务
+node dist/cli/index.js serve-local-model \
+  --model ./models/exported/merged \
+  --port 8081
+
+# 或使用 vLLM（推荐，性能更好）
+pip install vllm
+vllm serve ./models/exported/merged --port 8081 --dtype bfloat16
+```
+
+### 7.3 配置飞虹 Code 使用本地服务
+
+```json
+{
+  "completion": {
+    "provider": "openai-compatible",
+    "base_url": "http://localhost:8081/v1",
+    "model": "feihong-code-completion",
+    "api_key": "not-needed"
+  }
+}
+```
+
+### 7.4 验证集成
+
+```bash
+# 启动飞虹 Code Web 控制台
+node dist/cli/index.js serve --port 8080
+
+# 测试补全
+curl -X POST http://localhost:8080/api/completion \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filePath": "test.ts",
+    "fileContent": "function sum(a: number, b: number): number { return ",
+    "cursorOffset": 50,
+    "language": "typescript"
+  }'
+```
+
+---
+
+## 附录：常见问题
+
+### Q1: 训练时 OOM (Out of Memory) 怎么办？
+
+A: 
+1. 减小 `per_device_train_batch_size`（如 1 或 2）
+2. 增大 `gradient_accumulation_steps` 保持有效批大小
+3. 减小 `max_seq_length`（如 1024）
+4. 启用 `gradient_checkpointing: true`
+5. 使用更小的基础模型（如 350M 或 1B）
+
+### Q2: 训练后模型效果不好怎么办？
+
+A:
+1. 检查数据质量，确保样本多样化且高质量
+2. 增加训练轮数（如 5-10 轮）
+3. 调整学习率（如 1e-4 或 5e-5）
+4. 增大 LoRA rank（如 32 或 64）
+5. 增加 target_modules（包含更多层）
+6. 对比基线模型，确认确实有提升
+
+### Q3: 如何支持更多编程语言？
+
+A:
+1. 在数据准备时指定 `--languages` 参数
+2. 确保训练数据包含目标语言的代码
+3. 使用支持多语言的基础模型（如 StarCoder、CodeLlama）
+4. 评估时按语言分别统计，针对性优化
+
+### Q4: 可以在 CPU 上训练吗？
+
+A: 可以，但非常慢。建议：
+1. 使用 Google Colab (免费 T4 GPU)
+2. 使用云 GPU 服务（如 AutoDL、RunPod、Vast.ai）
+3. 使用更小的模型和数据集进行验证

package/docs/TECHNICAL_SPEC_en.md

@@ -0,0 +1,292 @@
+# Feihong Code v7.0.0 Technical Specification
+
+**Version**: 7.0.0
+**Date**: August 24, 2026
+**R&D Team**: Feihongzhi Technology Enterprise Management Co., Ltd. · Feiyang Qiyuan R&D Center
+
+---
+
+## 1. Product Overview
+
+Feihong Code (feihong-code) is a terminal AI coding agent, benchmarked against Muse Code / Cursor CLI, supporting multi-model routing, enterprise-grade RBAC auditing, fully automated SWE Agent, and offline private deployment.
+
+### 1.1 Core Capabilities
+
+- Natural Language to Code Changes: Transform user requirements into real, verifiable code repository changes
+- Multi-model Routing: Support DeepSeek, Tongyi Qianwen, Ollama, OpenAI, and other models
+- Fully Automated SWE Agent: Autonomous planning, execution, verification, and fixing
+- Enterprise-grade Security: RBAC permissions, audit logs, workspace isolation
+- Full Platform Support: Web console, Electron desktop, CLI command line
+
+### 1.2 Tech Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Runtime | Node.js | 18+ |
+| Language | TypeScript | 5.x |
+| Web Framework | Express | 4.x |
+| Data Validation | Zod | 3.x |
+| Frontend | Native HTML/CSS/JS | - |
+| Desktop | Electron | 41.x |
+| Packaging | electron-builder | 26.x |
+| Build | tsc | 5.x |
+
+---
+
+## 2. System Architecture
+
+### 2.1 Overall Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                  User Interface Layer           │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
+│  │Web Console│  │ Desktop  │  │ CLI          │  │
+│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
+└───────┼─────────────┼───────────────┼──────────┘
+        │             │               │
+        └─────────────┼───────────────┘
+                      │
+              ┌───────▼───────┐
+              │  Express API  │
+              │  Service Layer│
+              └───────┬───────┘
+                      │
+        ┌─────────────┼─────────────┐
+        │             │             │
+  ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
+  │Task Queue │ │Model Router│ │Audit      │
+  │TaskQueue  │ │Router      │ │Security   │
+  └─────┬─────┘ └─────┬─────┘ └───────────┘
+        │             │
+  ┌─────▼─────────────▼─────┐
+  │    SWE Agent Layer       │
+  │    Orchestrator          │
+  └─────┬───────────────────┘
+        │
+  ┌─────▼───────────────────┐
+  │    Tool Execution Layer  │
+  │  File Ops / Shell / Browser│
+  └─────────────────────────┘
+```
+
+### 2.2 Core Modules
+
+#### 2.2.1 Agent Layer (src/agent/)
+
+- **orchestrator.ts**: Core orchestrator, manages conversation loop, tool calls, error recovery
+- **prompts.ts**: System prompts, defines AI behavior boundaries and capability requirements
+- **self-heal.ts**: Self-healing module, error classification, fix suggestion generation
+- **code-writer.ts**: Code generation module
+- **swe-agent.ts**: SWE Agent implementation
+- **experience.ts**: Experience retrieval and reuse
+
+#### 2.2.2 Web Service Layer (src/web/)
+
+- **server.ts**: Express service, API routes, static file serving
+- **task-queue.ts**: Task queue, concurrency control, task persistence, state management
+- **public/**: Frontend static assets (HTML/CSS/JS)
+
+#### 2.2.3 CLI Layer (src/cli/)
+
+- **index.ts**: CLI entry, command parsing
+- **commands.ts**: Command implementation (serve/run/init etc.)
+- **version.ts**: Centralized version definition
+- **repl.ts**: Interactive REPL
+
+#### 2.2.4 Desktop (electron/)
+
+- **main.js**: Electron main process, window management, server startup, IPC communication
+- **preload.js**: Preload script, safely exposes API to renderer process
+
+#### 2.2.5 Local Speech Recognition (funasr-server/)
+
+- **app.py**: FastAPI service, based on faster-whisper
+- **requirements.txt**: Python dependencies
+- **启动语音识别服务.bat**: Windows one-click startup
+
+---
+
+## 3. Core Mechanisms
+
+### 3.1 Task Execution Flow
+
+1. **Task Submission**: User submits task via Web/Desktop/CLI
+2. **Task Enqueue**: TaskQueue receives task, sets status to queued
+3. **Task Execution**: Picks up task under concurrency control, calls Orchestrator
+4. **Orchestration Loop**: Orchestrator manages model calls, tool execution, result verification
+5. **Error Recovery**: Continuous errors trigger self-heal, generate fix suggestions and retry
+6. **Task Completion**: Result persisted, triggers webhook/notification
+
+### 3.2 Conversation Flow Rendering
+
+- **conversation**: Complete conversation history, limit 300 messages
+- **steps**: Thinking chain steps, limit 500
+- **Real-time Polling**: Frontend polls task status every 1 second
+- **Pure Text Output**: Frontend stripMarkdown hard defense, strips all formatting symbols
+- **Thinking Process Display**: Extract model.response content from steps for real-time display
+
+### 3.3 Self-healing Mechanism
+
+- **Error Classification**: 11 categories including compile-error / runtime-error / build-error / timeout
+- **Continuous Error Detection**: Traverse all continuous error messages for classification recording
+- **Fix Suggestion Generation**: Generate specific troubleshooting steps based on error type
+- **Max Retries**: Default 3, configurable
+- **Structured Report**: Error type + last error + fix suggestion + next step
+
+### 3.4 Permissions and Security
+
+- **RBAC Permissions**: Read scope, write permission, Shell permission, network permission, browser permission
+- **Workspace Isolation**: File operations limited to workspace scope
+- **Audit Logs**: All operations recorded to event-log
+- **Security Approval**: Dangerous operations require user confirmation
+
+---
+
+## 4. API Interfaces
+
+### 4.1 Core APIs
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /api/health | Health check |
+| POST | /api/auth/login | Login |
+| GET | /api/tasks | Task list |
+| POST | /api/tasks | Create task |
+| GET | /api/tasks/:id | Task detail |
+| POST | /api/tasks/:id/cancel | Cancel task |
+| DELETE | /api/tasks/:id | Delete task |
+| POST | /api/tasks/:id/continue | Continue task |
+| GET | /api/models | Available model list |
+| POST | /api/computer/screenshot | Computer screenshot |
+| POST | /api/computer/mouse/move | Mouse move |
+| POST | /api/computer/mouse/click | Mouse click |
+| POST | /api/computer/keyboard/type | Keyboard type |
+| POST | /api/computer/keyboard/press | Key press |
+
+### 4.2 Local Speech Recognition API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | /health | Health check |
+| POST | /api/recognize | Speech recognition (file upload) |
+| POST | /api/recognize-bytes | Speech recognition (byte stream) |
+
+---
+
+## 5. Deployment
+
+### 5.1 npm Global Install
+
+```bash
+npm install -g feihong-code
+fhcode serve
+```
+
+### 5.2 Source Deployment
+
+```bash
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build
+node dist/cli/index.js serve
+```
+
+### 5.3 Desktop Version
+
+```bash
+# One-click startup
+Double-click 一键启动桌面版.bat
+
+# Or manual
+npm run build
+npm run electron
+```
+
+### 5.4 Local Speech Recognition Service
+
+```bash
+cd funasr-server
+Double-click 启动语音识别服务.bat
+# Service URL: http://localhost:8082
+```
+
+---
+
+## 6. Configuration
+
+### 6.1 Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| FH_WEB_PORT | Web service port | 8080 |
+| FH_WEB_TOKEN | Access token | Auto-generated |
+| FH_HOME | Data directory | ~/.feihong-code |
+| FH_TASK_CONCURRENCY | Task concurrency | 2 |
+| FH_TASK_PERSIST_DIR | Task persistence dir | FH_HOME/tasks |
+| FH_TASK_WEBHOOK_URL | Task webhook | - |
+
+### 6.2 Model Configuration
+
+Supports multi-model routing, configurable in Web console:
+- DeepSeek (deepseek-chat / deepseek-coder)
+- Tongyi Qianwen (qwen-turbo / qwen-max)
+- Ollama (local models)
+- OpenAI compatible interfaces
+
+---
+
+## 7. Extension Development
+
+### 7.1 Add New Tool
+
+Add tool definition under `src/agent/tools/`, following Zod schema specification.
+
+### 7.2 Add New Skill
+
+Create skill directory under workspace `.feihong/skills/`, containing SKILL.md and scripts.
+
+### 7.3 Plugin System
+
+Template library supports custom sources, connects to external plugin systems through nodes.
+
+---
+
+## 8. Performance Metrics
+
+| Metric | Value |
+|--------|-------|
+| Startup Time | < 3 seconds |
+| Task Concurrency | Default 2, configurable |
+| Conversation History | 300 messages |
+| Thinking Steps | 500 |
+| Frontend Poll Interval | 1 second |
+| Build Time | < 10 seconds |
+| Desktop Memory | ~200MB |
+
+---
+
+## 9. Directory Structure
+
+```
+feihong-code/
+├── src/                    # Source code
+│   ├── agent/             # Agent core
+│   ├── cli/               # CLI
+│   ├── models/            # Model abstraction
+│   ├── runtime/           # Runtime
+│   ├── shared/            # Shared utilities
+│   └── web/               # Web service
+├── electron/              # Electron desktop
+├── funasr-server/         # Local speech recognition
+├── docs/                  # Documentation
+├── dist/                  # Build output
+├── package.json
+├── tool-schema.json
+└── README.md
+```
+
+---
+
+*Feihongzhi Technology Enterprise Management Co., Ltd. · Feiyang Qiyuan R&D Center*