﻿# FH_ 错误码完整参考

> 版本: v8.4.3 | 最后更新: 2026-09-14

---

## 错误码分类

| 分类 | 前缀 | 说明 |
|------|------|------|
| 配置错误 | FH_CFG_ | 配置相关错误 |
| 模型错误 | FH_MDL_ | 模型调用相关错误 |
| 代理错误 | FH_AGT_ | 代理执行相关错误 |
| 会话错误 | FH_SSN_ | 会话管理相关错误 |
| 工具错误 | FH_TL_ | 工具调用相关错误 |
| 安全错误 | FH_SEC_ | 安全相关错误 |
| 网络错误 | FH_NET_ | 网络连接相关错误 |
| 系统错误 | FH_SYS_ | 系统级错误 |

---

## 配置错误 (FH_CFG_)

### FH_CFG_001 - 配置文件缺失
- **原因**: `fhcode.config.json` 不存在或路径错误
- **解决**: 运行 `fhcode init` 初始化配置

### FH_CFG_002 - 配置验证失败
- **原因**: 配置文件格式错误或必填字段缺失
- **解决**: 检查配置文件 JSON 格式，确保必填字段存在

### FH_CFG_003 - 环境变量缺失
- **原因**: 必需的环境变量未设置
- **解决**: 设置所需环境变量（见环境变量表）

---

## 模型错误 (FH_MDL_)

### FH_MDL_001 - 模型提供商不可用
- **原因**: 配置的模型提供商连接失败
- **解决**: 检查网络连通性，验证 API Key 有效性

### FH_MDL_002 - 模型名称无效
- **原因**: 指定的模型名称在提供商中不存在
- **解决**: 查看提供商文档确认可用模型列表

### FH_MDL_003 - API 配额超限
- **原因**: API Key 配额已用完或达到速率限制
- **解决**: 等待配额重置或升级账户

### FH_MDL_004 - 模型响应超时
- **原因**: 模型响应时间超过设定阈值
- **解决**: 增加 `modelTimeout` 配置或检查网络延迟

---

## 代理错误 (FH_AGT_)

### FH_AGT_001 - 代理执行超时
- **原因**: 代理任务执行时间超过最大迭代次数
- **解决**: 
  - 增加 `maxIterations` 参数
  - 拆分复杂任务为多个子任务
  - 检查是否有无限循环

### FH_AGT_002 - 并行代理数量超限
- **原因**: 同时运行的代理数量超过限制
- **解决**: 减少 `maxParallelAgents` 配置

### FH_AGT_003 - 代理状态丢失
- **原因**: 恢复审计时找不到代理状态
- **解决**: 检查 `.fhcode/audit/` 目录权限

---

## 会话错误 (FH_SSN_)

### FH_SSN_001 - 会话 ID 无效
- **原因**: 提供的会话 ID 不存在
- **解决**: 使用 `fhcode session list` 查看有效会话

### FH_SSN_002 - 会话锁定
- **原因**: 会话正在进行中，无法访问
- **解决**: 等待当前任务完成或使用 `--force` 强制解锁

### FH_SSN_003 - 会话数据损坏
- **原因**: 会话文件损坏或不完整
- **解决**: 删除损坏的会话文件，重新开始

---

## 工具错误 (FH_TL_)

### FH_TL_001 - 工具调用失败
- **原因**: 工具执行过程中出错
- **解决**: 查看具体工具的错误日志

### FH_TL_002 - 工具权限不足
- **原因**: 工具需要额外权限但未授权
- **解决**: 使用 `--allow` 标志授权工具

### FH_TL_003 - 工具参数验证失败
- **原因**: 传递给工具的参数不符合要求
- **解决**: 检查工具文档确认参数格式

---

## 安全错误 (FH_SEC_)

### FH_SEC_001 - 操作被安全策略拦截
- **原因**: 操作违反了企业安全策略
- **解决**: 联系管理员调整安全策略配置

### FH_SEC_002 - 敏感数据检测
- **原因**: 检测到可能包含敏感信息的内容
- **解决**: 确认内容安全或添加白名单

### FH_SEC_003 - 未授权的操作类型
- **原因**: 当前用户角色无权执行该操作
- **解决**: 使用具有适当权限的账户

---

## 网络错误 (FH_NET_)

### FH_NET_001 - 网络连接失败
- **原因**: 无法连接到目标服务器
- **解决**: 
  - 检查网络连接
  - 验证代理设置
  - 检查防火墙规则

### FH_NET_002 - DNS 解析失败
- **原因**: 无法解析域名
- **解决**: 检查 DNS 设置或使用 IP 地址

### FH_NET_003 - SSL/TLS 握手失败
- **原因**: 证书验证失败
- **解决**: 
  - 检查系统时间
  - 更新 CA 证书
  - 必要时设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`（仅测试环境）

---

## 系统错误 (FH_SYS_)

### FH_SYS_001 - 文件系统错误
- **原因**: 文件读写操作失败
- **解决**: 检查文件权限和磁盘空间

### FH_SYS_002 - 内存不足
- **原因**: 进程占用内存超过限制
- **解决**: 
  - 增加 Node.js 内存限制: `export NODE_OPTIONS="--max-old-space-size=4096"`
  - 减少并行代理数量

### FH_SYS_003 - 进程被终止
- **原因**: 进程被系统或用户强制终止
- **解决**: 重新启动任务

---

## 环境变量参考

| 变量名 | 说明 | 必填 |
|--------|------|------|
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥 | 是（如使用 DeepSeek） |
| `DASHSCOPE_API_KEY` | 通义千问 API 密钥 | 是（如使用通义） |
| `OPENAI_API_KEY` | OpenAI API 密钥 | 是（如使用 OpenAI） |
| `OLLAMA_HOST` | Ollama 服务地址 | 否（默认 localhost:11434） |

---

## 排查流程图

```
遇到错误
    ↓
查看错误码前缀
    ↓
对应分类章节
    ↓
按照解决方案排查
    ↓
仍无法解决？
    ├─ 是 → 查看日志文件 ~/.fhcode/logs/
    └─ 否 → 问题解决 ✓
```

---

## 获取帮助

- GitHub Issues: https://github.com/wch887292/feihong-code/issues
- 文档: https://github.com/wch887292/feihong-code/tree/master/docs
- 联系我们: wch887292@gmail.com
