feihong-code 7.5.0 → 8.0.0

package/docs//344/275/277/347/224/250/350/257/264/346/230/216/344/271/246-v8.0.0.md

@@ -0,0 +1,922 @@
+# 飞虹 Code 详细使用说明书
+
+**文档版本**：v8.0.0
+**发布日期**：2026-09-03
+**适用版本**：飞虹 Code v8.0.0
+**开发团队**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心
+**负责人**：吴赐虹
+
+---
+
+## 目录
+
+1. [产品概述](#一产品概述)
+2. [快速开始](#二快速开始)
+3. [环境配置](#三环境配置)
+4. [CLI 命令行使用](#四cli-命令行使用)
+5. [Web 控制台](#五web-控制台)
+6. [移动端 APP](#六移动端-app)
+7. [核心能力详解](#七核心能力详解)
+8. [v8.0 新功能](#八v80-新功能)
+9. [多平台桥接](#九多平台桥接)
+10. [部署方式](#十部署方式)
+11. [常见问题与故障排查](#十一常见问题与故障排查)
+12. [版本历史与升级](#十二版本历史与升级)
+
+---
+
+## 一、产品概述
+
+飞虹 Code（feihong-code）是一款**终端 AI 编程智能体**，对标 Muse Code / Cursor CLI / Claude Code，具备多模型路由、企业级 RBAC 审计、全自动 SWE Agent、离线私有化部署等能力。
+
+### 1.1 核心定位
+
+| 维度 | 说明 |
+|------|------|
+| 产品形态 | CLI 终端 + Web 控制台 + Electron 桌面端 + Android APP |
+| 技术栈 | TypeScript + Node.js + Express + Electron + Capacitor + SQLite |
+| 模型支持 | DeepSeek / 通义 / Ollama / OpenAI / Agnes / 自定义 OpenAI 兼容 |
+| 核心能力 | 多 Agent 协作、持久记忆、自演化技能、自动化调度、Docker 沙盒 |
+| 部署方式 | 本地离线 / Docker / 服务器 / 移动端 |
+
+### 1.2 版本能力矩阵（v8.0.0）
+
+| 能力模块 | 说明 | 状态 |
+|----------|------|------|
+| 多模型路由 | 多提供商自动切换、流式输出、视觉模型 | ✅ |
+| 全自动 SWE Agent | 需求→规划→编码→验证→修复闭环 | ✅ |
+| 多 Agent 协作 | Solo / Multi / Event-Driven / Custom Agent | ✅ |
+| 持久记忆系统 | 短期记忆 + 长期 MEMORY.md + 自动摘要 | ✅ |
+| Honcho 语义记忆 | 用户建模 + 事实记忆 + 跨会话检索 | ✅ v8.0 |
+| 自演化技能 | 自动提炼可复用技能 + agentskills.io 兼容 | ✅ |
+| 自动化调度 | 自然语言定时任务（每天/每周/间隔/单次） | ✅ |
+| Docker 沙盒执行 | 容器隔离 + 禁网 + 资源限制 + 危险命令拦截 | ✅ v8.0 |
+| SQLite 数据存储 | 10 张表统一存储 + 模型 Key 加密 | ✅ v8.0 |
+| 免密网络层 | 5 节点环形轮转 + Ring Failover，开箱即用 | ✅ |
+| 多平台桥接 | 微信 / 飞书 / 元宝（配置后启用） | ✅ |
+| 企业级审计 | RBAC 权限 + 操作日志 + 密钥脱敏 | ✅ |
+| 移动端 APP | 对话 + 游戏中心 + 创作 + 文生图/视频 | ✅ |
+
+---
+
+## 二、快速开始
+
+### 2.1 环境要求
+
+| 组件 | 最低要求 | 推荐版本 |
+|------|----------|----------|
+| Node.js | v18+ | **v22.23.2**（内置 node:sqlite） |
+| npm | v9+ | v10+ |
+| 操作系统 | Windows 10 / macOS 12 / Linux | Windows 11 |
+| 内存 | 4GB | 8GB+ |
+| 磁盘 | 500MB | 2GB+ |
+| Docker（可选） | Docker 20+ | Docker 29.7.2（沙盒功能需要） |
+
+### 2.2 安装
+
+#### 方式一：npm 全局安装
+
+```bash
+npm install -g feihong-code
+fhcode --version
+```
+
+#### 方式二：源码安装
+
+```bash
+git clone <仓库地址> feihong-code
+cd feihong-code
+npm install
+npm run build
+node dist/cli/index.js --version
+```
+
+#### 方式三：Windows 一键启动
+
+双击项目根目录的 `一键启动Web控制台.bat`，自动启动 Web 控制台。
+
+### 2.3 首次使用（3 步上手）
+
+**第 1 步：启动 Web 控制台**
+
+```bash
+# Windows PowerShell
+$env:FH_WEB_PORT="8080"
+node dist/cli/index.js serve
+
+# 或使用一键脚本
+.\一键启动Web控制台.bat
+```
+
+启动后终端会显示自动生成的访问令牌（`FH_WEB_TOKEN`），浏览器打开 `http://localhost:8080`。
+
+**第 2 步：配置模型**
+
+在 Web 控制台 → 设置 → 模型配置中，添加你的大模型：
+
+| 字段 | 示例 |
+|------|------|
+| 模型名称 | Agnes-2.5-Flash |
+| API 地址 | https://api.agnes-ai.cn/v1 |
+| API Key | sk-xxxxxxxxxxxxxxxx |
+| 模型 ID | agnes-2.5-flash |
+| 上下文窗口 | 128000 |
+
+也可以通过环境变量配置：
+
+```bash
+$env:FH_PROVIDERS='[{"id":"agnes","name":"Agnes","apiBase":"https://api.agnes-ai.cn/v1","apiKey":"sk-xxx","model":"agnes-2.5-flash"}]'
+```
+
+**第 3 步：开始对话**
+
+在 Web 控制台输入你的需求，例如：
+
+> 帮我写一个 Python 脚本，读取当前目录下所有 .txt 文件并统计词频
+
+飞虹 Code 会自动规划、编码、验证并给出结果。
+
+---
+
+## 三、环境配置
+
+### 3.1 核心环境变量
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `FH_HOME` | `~/.feihong-code` | 数据根目录（任务/记忆/知识库/插件） |
+| `FH_WEB_PORT` | `3000` | Web 控制台端口 |
+| `FH_WEB_TOKEN` | 自动生成 | Web 控制台访问令牌（Bearer Token） |
+| `FH_PROVIDERS` | 空 | 模型提供商 JSON 数组 |
+| `FH_SECRET` | 自动生成 | 主密钥（用于加密敏感数据，>=16 字符） |
+| `FH_LOG_DIR` | `$FH_HOME/logs` | 日志目录 |
+| `FH_SHELL_ALLOW` | 空 | Shell 命令白名单（逗号分隔） |
+| `FH_REQUIRE_APPROVAL` | `false` | 是否需要审批才能执行危险命令 |
+
+### 3.2 v8.0 新增环境变量
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `FH_DB_PATH` | `$FH_HOME/feihong.db` | SQLite 数据库文件路径 |
+| `FH_HONCHO_USER` | `default` | Honcho 当前用户 ID |
+| `FH_HONCHO_URL` | 空 | 外部 Honcho 服务 URL（预留） |
+| `FH_HONCHO_API_KEY` | 空 | 外部 Honcho API Key（预留） |
+| `FH_SANDBOX_IMAGE` | `node:22-alpine` | Docker 沙盒镜像 |
+| `FH_SANDBOX_NETWORK` | `false` | 沙盒是否启用网络 |
+| `FH_SANDBOX_READONLY` | `true` | 沙盒工作区是否只读挂载 |
+| `FH_SANDBOX_TIMEOUT` | `60000` | 沙盒执行超时（毫秒） |
+
+### 3.3 模型配置详解
+
+支持多种模型提供商，配置格式：
+
+```json
+[
+  {
+    "id": "agnes",
+    "name": "Agnes-2.5-Flash",
+    "provider": "openai-compatible",
+    "apiBase": "https://api.agnes-ai.cn/v1",
+    "apiKey": "sk-xxxxxxxx",
+    "model": "agnes-2.5-flash",
+    "contextWindow": 128000,
+    "maxOutput": 8192,
+    "supportsStreaming": true,
+    "supportsVision": false
+  },
+  {
+    "id": "deepseek",
+    "name": "DeepSeek-V3",
+    "provider": "openai-compatible",
+    "apiBase": "https://api.deepseek.com/v1",
+    "apiKey": "sk-xxxxxxxx",
+    "model": "deepseek-chat",
+    "contextWindow": 64000
+  },
+  {
+    "id": "ollama-local",
+    "name": "本地 Ollama",
+    "provider": "openai-compatible",
+    "apiBase": "http://localhost:11434/v1",
+    "apiKey": "ollama",
+    "model": "qwen2.5:7b",
+    "contextWindow": 32768
+  }
+]
+```
+
+**免密网络层**：即使不配置任何模型，飞虹 Code 内置了 5 家厂商的免费模型接口（环形轮转 + Ring Failover），开箱即用，无需注册任何 API Key。
+
+---
+
+## 四、CLI 命令行使用
+
+### 4.1 基本命令
+
+```bash
+# 查看版本
+fhcode --version
+
+# 查看帮助
+fhcode --help
+
+# 单次对话（非交互式）
+fhcode "帮我写一个快速排序的 Python 实现"
+
+# 启动 REPL 交互式会话
+fhcode
+
+# 启动 Web 控制台
+fhcode serve
+
+# 指定端口启动
+FH_WEB_PORT=9090 fhcode serve
+```
+
+### 4.2 REPL 模式命令
+
+进入 REPL 后（输入 `fhcode` 回车），支持以下斜杠命令：
+
+| 命令 | 说明 |
+|------|------|
+| `/help` | 显示帮助 |
+| `/clear` | 清空当前会话上下文 |
+| `/memory` | 查看当前记忆状态 |
+| `/skills` | 列出已安装技能 |
+| `/models` | 列出已配置模型 |
+| `/status` | 查看 Agent 状态 |
+| `/exit` 或 `/quit` | 退出 REPL |
+
+### 4.3 常用场景示例
+
+**代码生成**：
+```bash
+fhcode "用 TypeScript 写一个带超时控制的 fetch 封装，支持重试"
+```
+
+**代码审查**：
+```bash
+fhcode "审查 src/utils/http.ts 的代码质量，指出潜在问题并给出修复建议"
+```
+
+**项目重构**：
+```bash
+fhcode "把 src/agent/ 目录下的回调风格代码改成 async/await，保持接口不变"
+```
+
+**文档生成**：
+```bash
+fhcode "为 src/web/server.ts 生成 API 文档，包含每个端点的请求/响应格式"
+```
+
+---
+
+## 五、Web 控制台
+
+### 5.1 启动与访问
+
+```bash
+# 启动
+$env:FH_WEB_PORT="8080"
+node dist/cli/index.js serve
+
+# 访问
+# 浏览器打开 http://localhost:8080
+# 首次访问需要输入终端显示的 FH_WEB_TOKEN
+```
+
+### 5.2 功能模块
+
+| 模块 | 路径 | 说明 |
+|------|------|------|
+| 对话主页 | `/` | 主对话界面，支持多轮对话、流式输出 |
+| 任务中心 | `/tasks` | 查看异步任务队列、进度、结果 |
+| 模型配置 | `/models` | 添加/编辑/删除模型提供商 |
+| 技能管理 | `/skills` | 查看/安装/管理技能包 |
+| 记忆中心 | `/memory` | 查看 MEMORY.md / USER.md / 历史摘要 |
+| 知识库 | `/knowledge` | 上传/管理知识库文档 |
+| 插件管理 | `/plugins` | 安装/管理第三方插件 |
+| 设置 | `/settings` | 系统设置、API 密钥、安全配置 |
+| API 文档 | `/api/docs` | OpenAPI 风格接口文档 |
+
+### 5.3 核心 API 接口
+
+#### 健康检查（公开）
+```
+GET /api/health
+```
+响应：
+```json
+{
+  "ok": true,
+  "product": "飞虹 Code",
+  "version": "8.0.0",
+  "storage": { "ok": true, "backend": "sqlite", "version": 1 },
+  "honcho": { "ok": true, "backend": "sqlite-local" },
+  "time": "2026-09-03T07:00:00.000Z"
+}
+```
+
+#### 对话接口（需认证）
+```
+POST /api/chat
+Authorization: Bearer <FH_WEB_TOKEN>
+Content-Type: application/json
+
+{
+  "message": "你的问题",
+  "modelId": "agnes",
+  "stream": true
+}
+```
+
+#### 任务接口
+```
+GET    /api/tasks              # 任务列表
+GET    /api/tasks/:id          # 任务详情
+POST   /api/tasks              # 创建任务
+DELETE /api/tasks/:id          # 删除任务
+```
+
+#### v8.0 新增接口
+```
+GET  /api/storage/stats        # SQLite 存储统计
+GET  /api/honcho/context       # Honcho 用户画像+记忆+上下文
+POST /api/honcho/remember      # 记录用户事实记忆
+GET  /api/honcho/recall?q=xxx # 关键词检索记忆
+```
+
+---
+
+## 六、移动端 APP
+
+### 6.1 安装
+
+Android APK 位于 `artifacts/` 目录，安装到手机即可。也可通过 Android Studio 打开 `android/` 工程自行构建。
+
+### 6.2 功能模块
+
+| 模块 | 说明 |
+|------|------|
+| 大模型对话 | 多轮对话、流式输出、支持图片/文件/截图/拍照上传 |
+| 自定义模型 | 配置任意 OpenAI 兼容模型接口，支持视觉模型 |
+| 游戏中心 | 12 款内置小游戏，直接打开即玩，适配手机屏幕 |
+| 文生图 | 输入描述生成图片，支持自定义模型 |
+| 文生视频 | 输入描述生成视频 |
+| 图生视频 | 上传图片生成视频 |
+| 技能中心 | 内置技能（内容摘要、中英互译、小红书文案等） |
+| Hermes Agent | 持久记忆 + 自演化技能 + 自动化调度 |
+| 免密网络层 | 5 节点环形轮转，无需配置 API Key 即可对话 |
+
+### 6.3 自定义模型配置
+
+在 APP → 设置 → 自定义模型中：
+
+| 字段 | 示例 |
+|------|------|
+| 模型名称 | Agnes-2.5-Flash |
+| API 地址 | https://api.agnes-ai.cn/v1 |
+| API Key | sk-xxxxxxxx |
+| 模型 ID | agnes-2.5-flash |
+
+视觉模型（图片理解）配置示例：
+| 字段 | 示例 |
+|------|------|
+| 模型名称 | DeepSeek-OCR |
+| API 地址 | https://api.siliconflow.cn/v1 |
+| 模型 ID | deepseek-ai/DeepSeek-OCR |
+| 支持视觉 | 开启 |
+
+---
+
+## 七、核心能力详解
+
+### 7.1 多 Agent 协作系统
+
+飞虹 Code 支持 4 种 Agent 模式：
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| Solo Agent | 单 Agent 独立完成任务 | 简单需求、代码生成 |
+| Multi Agent | 多 Agent 分工协作（规划/编码/审查/验证） | 复杂项目、全栈开发 |
+| Event-Driven Agent | 事件驱动，响应外部事件 | 自动化流程、CI/CD |
+| Custom Agent | 用户自定义 Agent 配置 | 特定领域、定制工作流 |
+
+### 7.2 持久记忆系统
+
+| 记忆类型 | 存储位置 | 说明 |
+|----------|----------|------|
+| 短期记忆 | 运行时内存 + `$FH_HOME/memory/short/` | 当前会话上下文，自动压缩 |
+| 长期记忆 | `$FH_HOME/memory/MEMORY.md` | 项目上下文、关键事实、历史任务摘要 |
+| 用户画像 | `$FH_HOME/memory/USER.md` | 用户偏好、习惯、专业领域 |
+| 自动摘要 | `$FH_HOME/memory/summaries/` | 每轮对话结束自动生成摘要 |
+| Honcho 语义记忆 | SQLite `users` + `user_memory` 表 | 用户建模、事实记忆、跨会话检索 |
+
+记忆会自动注入到每次对话的上下文中，无需手动重复交代背景。
+
+### 7.3 自演化技能系统
+
+- 从重复任务模式中自动提炼可复用技能
+- 兼容 **agentskills.io** 开放标准
+- 支持搜索、安装、删除、使用计数追踪
+- 内置技能：内容摘要、中英互译、代码审查、小红书文案
+- v7.9.1 新增 LLM 辅助技能提炼，提升提取准确率
+
+### 7.4 自动化调度
+
+自然语言设定定时任务，替代手写 cron：
+
+| 自然语言 | 解析结果 |
+|----------|----------|
+| `每天 9:00` | daily，每天 09:00 执行 |
+| `每周一 10:30` | weekly，每周一 10:30 执行 |
+| `每隔 30 分钟` | interval，每 30 分钟执行 |
+| `14:00` | once，今天 14:00 执行一次 |
+
+适用场景：定时备份、定时报表、定时巡检、定时推送。
+
+### 7.5 工具集
+
+| 工具类别 | 包含工具 |
+|----------|----------|
+| 文件操作 | 读文件、写文件、编辑文件、搜索文件、目录列表 |
+| Shell 执行 | 命令执行（白名单+审批+沙盒） |
+| 网页搜索 | 免密搜索（Brave/Tavily/Firecrawl 环形轮转） |
+| 浏览器自动化 | 页面导航、点击、输入、截图、元素提取 |
+| 代码执行 | Python/Node/Shell 代码执行（Docker 沙盒） |
+| TTS | 文本转语音 |
+| 文生图 | 输入描述生成图片 |
+| MCP | Model Context Protocol 外部工具接入 |
+
+---
+
+## 八、v8.0 新功能
+
+### 8.1 SQLite 数据存储
+
+**是什么**：基于 Node.js 内置 `node:sqlite` 的统一数据存储层，零外部依赖。
+
+**解决什么问题**：
+- 原文件/JSON 存储在大规模数据时性能下降、查询困难
+- 模型 API Key 明文存储有安全风险
+
+**核心能力**：
+- 10 张表统一管理：kv / tasks / models / agents / skills / memory / memory_history / users / user_memory / knowledge
+- 模型 API Key 自动 AES-256-GCM 加密落盘
+- 版本化迁移（SCHEMA_VERSION），启动自动建表
+- WAL 日志模式 + 外键约束
+
+**如何使用**：
+```bash
+# 无需额外配置，启动后自动创建 $FH_HOME/feihong.db
+# 查看存储统计
+curl -H "Authorization: Bearer $FH_WEB_TOKEN" http://localhost:8080/api/storage/stats
+```
+
+**环境变量**：
+- `FH_DB_PATH`：自定义数据库文件路径
+
+### 8.2 Docker 沙盒执行
+
+**是什么**：在 Docker 容器中隔离执行代码和命令，降低安全风险。
+
+**解决什么问题**：
+- 直接在宿主机执行 AI 生成的代码有安全风险
+- 不同项目依赖冲突
+
+**安全机制**：
+| 机制 | 默认值 | 说明 |
+|------|--------|------|
+| 网络隔离 | 禁用 | `--network none`，容器内无法访问网络 |
+| 只读挂载 | 启用 | 工作区只读挂载，防止容器修改宿主机文件 |
+| 内存限制 | 512MB | `-m 512m` |
+| CPU 限制 | 1 核 | `--cpus 1` |
+| 危险命令拦截 | 启用 | 拒绝 `rm -rf /`、`mkfs`、`dd 写块设备`、fork 炸弹 |
+| 超时强杀 | 60秒 | 超时自动 `docker kill` |
+
+**如何使用**：
+```bash
+# 需要本机安装 Docker Desktop / Docker Engine
+# 环境变量配置
+$env:FH_SANDBOX_IMAGE="node:22-alpine"
+$env:FH_SANDBOX_NETWORK="false"
+$env:FH_SANDBOX_READONLY="true"
+
+# 冒烟测试
+node tests/smoke-v8.js --only=docker
+```
+
+**国内镜像加速器配置**（解决 Docker Hub 无法访问）：
+编辑 `C:\Users\<用户名>\.docker\daemon.json`（**必须无 BOM 的 UTF-8**）：
+```json
+{
+  "registry-mirrors": [
+    "https://docker.1ms.run",
+    "https://docker.m.daocloud.io",
+    "https://hub-mirror.c.163.com",
+    "https://mirror.baidubce.com"
+  ]
+}
+```
+> 注意：PowerShell 的 `Set-Content -Encoding UTF8` 会写入 BOM，导致 Docker 解析失败。请用 VS Code 保存为 "UTF-8 without BOM"，或用 .NET `[System.IO.File]::WriteAllText` 写入。
+
+### 8.3 Honcho 云端记忆（本地部署）
+
+**是什么**：对标 Honcho（GetZep）的语义记忆系统，实现用户建模、事实记忆、跨会话检索。
+
+**解决什么问题**：
+- 原文件记忆只能按文件读写，无法按用户/重要度/关键词检索
+- 跨设备、跨会话的用户画像和偏好无法持久化
+
+**核心能力**：
+| 能力 | 说明 |
+|------|------|
+| 用户建模 | 姓名、偏好、特质画像，持久化存储 |
+| 事实记忆 | 用户说过的关键事实，带重要度（0~1）排序 |
+| 会话摘要 | 每轮对话自动摘要，跨会话检索 |
+| 语义检索 | 关键词匹配 + 重要度排序 + 时间加权 |
+| 记忆注入 | 自动生成个性化上下文提示词，注入每次对话 |
+| 自动沉淀 | 从用户消息自动提取偏好类事实 |
+
+**如何使用**：
+```bash
+# 无需额外配置，启动后自动启用（SQLite 本地持久化）
+# 查看用户画像和记忆
+curl -H "Authorization: Bearer $FH_WEB_TOKEN" http://localhost:8080/api/honcho/context
+
+# 记录用户事实
+curl -X POST -H "Authorization: Bearer $FH_WEB_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"用户偏好使用TypeScript","importance":0.9}' \
+  http://localhost:8080/api/honcho/remember
+
+# 关键词检索记忆
+curl -H "Authorization: Bearer $FH_WEB_TOKEN" \
+  "http://localhost:8080/api/honcho/recall?q=TypeScript"
+```
+
+**环境变量**：
+- `FH_HONCHO_USER`：当前用户 ID（默认 `default`）
+- `FH_HONCHO_URL`：外部 Honcho 服务 URL（预留，配置后走远程模式）
+- `FH_HONCHO_API_KEY`：外部 Honcho API Key（预留）
+
+---
+
+## 九、多平台桥接
+
+飞虹 Code 支持一套 Agent，多入口交互。
+
+### 9.1 微信桥接
+
+支持企业微信（wecom）和公众号（mp）两种模式。
+
+```bash
+# 企业微信模式
+$env:FH_WECHAT_MODE="wecom"
+$env:FH_WECHAT_CORP_ID="wwxxxxxxxx"
+$env:FH_WECHAT_AGENT_ID="1000002"
+$env:FH_WECHAT_SECRET="xxxxxxxx"
+$env:FH_WECHAT_TOKEN="xxxxxxxx"
+$env:FH_WECHAT_AES_KEY="xxxxxxxx"
+
+# 公众号模式
+$env:FH_WECHAT_MODE="mp"
+$env:FH_WECHAT_APP_ID="wxXXXXXXXX"
+$env:FH_WECHAT_APP_SECRET="xxxxxxxx"
+$env:FH_WECHAT_TOKEN="xxxxxxxx"
+$env:FH_WECHAT_AES_KEY="xxxxxxxx"
+```
+
+回调地址：`https://<你的域名>/api/wechat/callback`
+
+### 9.2 飞书桥接
+
+```bash
+$env:FH_FEISHU_ENABLED="true"
+$env:FH_FEISHU_APP_ID="cli_xxxxxxxx"
+$env:FH_FEISHU_APP_SECRET="xxxxxxxx"
+$env:FH_FEISHU_VERIFICATION_TOKEN="xxxxxxxx"
+$env:FH_FEISHU_ENCRYPT_KEY="xxxxxxxx"
+```
+
+事件订阅地址：`https://<你的域名>/api/feishu/callback`
+
+### 9.3 元宝桥接
+
+```bash
+$env:FH_YUANBAO_ENABLED="true"
+$env:FH_YUANBAO_APP_ID="xxxxxxxx"
+$env:FH_YUANBAO_APP_SECRET="xxxxxxxx"
+```
+
+---
+
+## 十、部署方式
+
+### 10.1 本地开发部署
+
+```bash
+git clone <仓库地址>
+cd feihong-code
+npm install
+npm run build
+$env:FH_WEB_PORT="8080"
+node dist/cli/index.js serve
+```
+
+### 10.2 Docker 部署
+
+```dockerfile
+# Dockerfile（项目根目录已提供）
+FROM node:22-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY dist/ ./dist/
+EXPOSE 8080
+ENV FH_WEB_PORT=8080
+CMD ["node", "dist/cli/index.js", "serve"]
+```
+
+```bash
+# 构建镜像
+docker build -t feihong-code:8.0.0 .
+
+# 运行容器
+docker run -d \
+  -p 8080:8080 \
+  -v ~/.feihong-code:/root/.feihong-code \
+  -e FH_WEB_TOKEN=your-secret-token \
+  --name feihong-code \
+  feihong-code:8.0.0
+```
+
+### 10.3 Docker Compose 部署
+
+项目根目录提供 `docker-compose.yml`：
+
+```bash
+docker-compose up -d
+```
+
+### 10.4 服务器部署（Nginx 反向代理）
+
+项目提供 `nginx-fhcode.conf` 配置模板：
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8080;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_read_timeout 300s;
+    }
+}
+```
+
+### 10.5 Electron 桌面端
+
+```bash
+# 启动桌面端
+npm run electron:dev
+
+# 打包桌面端
+npm run electron:build
+```
+
+### 10.6 Android APP 构建
+
+```bash
+# 同步移动端资源到 Android 工程
+npx cap sync android
+
+# 构建 Release APK
+cd android
+.\gradlew.bat assembleRelease --no-daemon
+
+# 产物位置
+# android/app/build/outputs/apk/release/app-release.apk
+```
+
+---
+
+## 十一、常见问题与故障排查
+
+### 11.1 启动相关
+
+**Q: 启动报错 `Error: listen EADDRINUSE: address already in use :::8080`**
+A: 端口被占用。更换端口：`$env:FH_WEB_PORT="9090"; node dist/cli/index.js serve`
+
+**Q: 启动后浏览器访问显示 401 Unauthorized**
+A: 需要在请求头携带 `Authorization: Bearer <FH_WEB_TOKEN>`。Web 控制台首次访问会提示输入令牌，令牌在启动终端的输出中。
+
+**Q: 启动时报 `node:sqlite` 相关错误**
+A: 需要 Node.js v22+。检查版本：`node --version`。升级 Node.js 后重新 `npm run build`。
+
+### 11.2 模型相关
+
+**Q: 对话没有回复，显示"已停止生成"**
+A: 可能原因：
+1. API Key 错误或过期 → 检查模型配置
+2. API 地址无法访问 → 检查网络，或换用免密网络层
+3. 模型 ID 错误 → 确认模型 ID 与提供商一致
+4. 上下文超限 → 清空会话或换用更大上下文的模型
+
+**Q: 如何不配置 API Key 就使用？**
+A: 飞虹 Code 内置免密网络层（5 家厂商免费模型环形轮转），不配置 `FH_PROVIDERS` 时自动启用，开箱即用。
+
+**Q: 图片上传后无法识别**
+A: 需要配置支持视觉的模型（如 DeepSeek-OCR、GPT-4o 等），并在模型配置中开启"支持视觉"。
+
+### 11.3 Docker 沙盒相关
+
+**Q: Docker 沙盒功能不可用**
+A: 需要本机安装 Docker Desktop / Docker Engine。检查：`docker info`。Windows 用户需启动 Docker Desktop。
+
+**Q: Docker Desktop 启动报错 `invalid character 'ï' looking for beginning of value`**
+A: `daemon.json` 文件包含 UTF-8 BOM。用 VS Code 打开文件，右下角编码选择 "UTF-8 without BOM" 保存，或删除该文件让 Docker 自动重建。
+
+**Q: 拉取镜像超时/失败（`failed to resolve reference`）**
+A: Docker Hub 在国内无法直接访问。配置国内镜像加速器（见 §8.2），或手动通过加速器拉取：
+```bash
+docker pull docker.1ms.run/library/node:22-alpine
+docker tag docker.1ms.run/library/node:22-alpine node:22-alpine
+```
+
+### 11.4 数据存储相关
+
+**Q: SQLite 数据库文件在哪里？**
+A: 默认 `~/.feihong-code/feihong.db`（Windows: `C:\Users\<用户名>\.feihong-code\feihong.db`）。可通过 `FH_DB_PATH` 自定义。
+
+**Q: 如何重置所有数据？**
+A: 停止服务后删除 `~/.feihong-code/` 目录（包含任务、记忆、知识库、SQLite 数据库等全部数据）。**注意：不可恢复。**
+
+**Q: 模型 API Key 是明文存储吗？**
+A: 不是。SQLite 存储中模型 API Key 自动 AES-256-GCM 加密落盘，主密钥来自 `FH_SECRET` 环境变量或 `$FH_HOME/.secret`。
+
+### 11.5 移动端相关
+
+**Q: APP 安装后闪退**
+A: 检查 Android 版本（要求 Android 8.0+），或尝试卸载后重新安装最新版 APK。
+
+**Q: 游戏画面超出屏幕/点击无反应**
+A: v8.0 已优化游戏适配。如仍有问题，更新到最新版 APK，或在游戏内使用"适配屏幕"按钮。
+
+**Q: APP 对话只有一轮就停止**
+A: 检查模型配置是否支持多轮对话（上下文窗口），确认 API Key 有效，或换用免密网络层。
+
+### 11.6 性能相关
+
+**Q: 响应速度慢**
+A: 
+1. 检查模型 API 延迟（换用更近的 API 端点）
+2. 减少上下文长度（清空历史或启用自动摘要）
+3. 换用更快的模型（如 Flash 系列）
+4. 检查本机资源占用（Docker/浏览器等）
+
+**Q: 内存占用高**
+A: 飞虹 Code 后端正常占用约 100-300MB。如过高，检查是否有大量任务堆积（`/api/tasks`），或重启服务。
+
+---
+
+## 十二、版本历史与升级
+
+### 12.1 版本历史
+
+| 版本 | 发布日期 | 核心变更 |
+|------|----------|----------|
+| v7.2.0 | 2026-08-26 | 基础架构、多模型路由、Web 控制台 |
+| v7.5.0 | 2026-08-27 | 企业级 RBAC、审计日志、安全加固 |
+| v7.6.0 | 2026-08-28 | SWE Agent、多 Agent 协作、知识库 |
+| v7.9.0 | 2026-09-03 | Hermes Agent 框架、免密网络层、移动端 APP |
+| v7.9.1 | 2026-09-03 | LLM 技能提炼、集成测试、API 文档、日志轮转 |
+| **v8.0.0** | **2026-09-03** | **SQLite 存储、Docker 沙盒、Honcho 语义记忆** |
+
+### 12.2 升级指南（v7.9.x → v8.0.0）
+
+```bash
+# 1. 拉取最新代码
+git pull
+
+# 2. 重新编译
+npm run build
+
+# 3. 停止旧服务（找到进程并停止）
+# Windows: 任务管理器结束 node 进程，或 Stop-Process -Name node
+
+# 4. 启动新服务
+$env:FH_WEB_PORT="8080"
+node dist/cli/index.js serve
+
+# 5. 验证升级
+curl http://localhost:8080/api/health
+# 应返回 version: "8.0.0", storage.ok: true, honcho.ok: true
+
+# 6. 运行冒烟测试
+node tests/smoke-v8.js
+# 预期：25/25 通过
+```
+
+**升级注意事项**：
+- SQLite 数据库首次启动自动创建，无需手动迁移
+- 原有文件存储（任务/记忆/知识库）保留，不影响使用
+- Docker 沙盒功能需要本机安装 Docker，不安装不影响其它功能
+- 如使用 Docker，建议配置国内镜像加速器（见 §8.2）
+
+### 12.3 相关文档
+
+| 文档 | 位置 | 说明 |
+|------|------|------|
+| 升级说明书 | `docs/UPGRADE-v8.0.0.md` | v8.0.0 详细升级说明 |
+| 技术说明书 | `docs/TECHNICAL-SPECIFICATION.md` | 架构设计、模块说明、技术选型 |
+| 项目分析与测试 | `docs/PROJECT-ANALYSIS-AND-TEST.md` | 客观分析、测试用例、改进建议 |
+| API 文档 | `docs/API.md` | OpenAPI 风格接口文档 |
+| 部署指南 | `docs/部署指南.md` | 各种部署方式详解 |
+| 贡献指南 | `CONTRIBUTING.md` | 开发协作规范 |
+| 行为准则 | `CODE_OF_CONDUCT.md` | 社区行为准则 |
+| 开源社区治理 | `GOVERNANCE.md` | 社区治理结构 |
+| 社区指南 | `COMMUNITY.md` | 社区参与指南 |
+
+---
+
+## 附录 A：快速命令速查
+
+```bash
+# 版本与帮助
+fhcode --version
+fhcode --help
+
+# 单次对话
+fhcode "你的需求"
+
+# 交互式 REPL
+fhcode
+
+# Web 控制台
+$env:FH_WEB_PORT="8080"; node dist/cli/index.js serve
+
+# 编译
+npm run build
+
+# 冒烟测试
+node tests/smoke-v8.js
+
+# 集成测试
+node tests/integration/api.test.js
+
+# Docker 沙盒测试
+node tests/smoke-v8.js --only=docker
+
+# 健康检查
+curl http://localhost:8080/api/health
+
+# Android 构建
+cd android; .\gradlew.bat assembleRelease --no-daemon
+```
+
+---
+
+## 附录 B：数据目录结构
+
+```
+~/.feihong-code/                    # 数据根目录（FH_HOME）
+├── feihong.db                      # SQLite 数据库（v8.0）
+├── feihong.db-wal                  # SQLite WAL 日志
+├── feihong.db-shm                  # SQLite 共享内存
+├── .secret                         # 主密钥（自动生成）
+├── rsa_private.pem                 # RSA 私钥
+├── tasks/                          # 任务队列文件
+│   ├── <task-id>.json
+│   └── ...
+├── memory/                         # 记忆文件
+│   ├── MEMORY.md
+│   ├── USER.md
+│   ├── short/
+│   └── summaries/
+├── knowledge/                      # 知识库文档
+│   ├── <doc-id>.md
+│   └── ...
+├── plugins/                        # 插件
+│   └── <plugin-name>/
+├── self-evolve/                    # 自我进化数据
+│   ├── failures/
+│   ├── skills/
+│   └── history/
+├── honcho/                         # Honcho 数据目录
+└── logs/                           # 日志文件
+    └── <date>.log
+```
+
+---
+
+*本文档随飞虹 Code 版本同步更新。如有疑问或建议，请通过 GitHub Issues 或社区渠道反馈。*
+
+© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹