feihong-code 0.2.3 → 0.6.0

package/docs/error-codes.md

@@ -0,0 +1,198 @@
+# FH_ 错误码完整参考
+
+> 版本: v0.5.1 | 最后更新: 2026-08-22
+
+---
+
+## 错误码分类
+
+| 分类 | 前缀 | 说明 |
+|------|------|------|
+| 配置错误 | 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

package/docs/self-evolve-implementation.md

@@ -0,0 +1,165 @@
+# Self-Evolve 实现指南
+
+## 核心架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Self-Evolve Manager                      │
+├─────────────────────────────────────────────────────────────┤
+│  • failures.json  - 失败记录存储                              │
+│  • skills-index.json - 技能索引                               │
+│  • history.json   - 操作历史                                 │
+│  • config.json    - 配置参数                                 │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                       Hook System                            │
+├─────────────────────────────────────────────────────────────┤
+│  • onToolFailure() - 工具调用失败时触发                        │
+│  • onTaskComplete() - 任务完成时触发                          │
+│  • dailyReview()   - 每日自动复盘                            │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    CLI Interface                             │
+├─────────────────────────────────────────────────────────────┤
+│  • self-evolve init          - 初始化系统                     │
+│  • self-evolve status        - 查看状态                       │
+│  • self-evolve failures      - 管理失败记录                   │
+│  • self-evolve skills        - 管理技能库                     │
+│  • self-evolve review        - 定期复盘                       │
+│  • self-evolve analyze       - 分析错误模式                   │
+│  • self-evolve create-skill  - 创建新技能                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 数据模型
+
+### 失败记录 (failure.json)
+```json
+{
+  "id": "uuid",
+  "timestamp": "ISO时间",
+  "task": "任务描述",
+  "error_type": "错误类型",
+  "error_message": "错误信息",
+  "attempted_solutions": [],
+  "root_cause": "根本原因",
+  "solution": "解决方案",
+  "created_skill": false,
+  "skill_name": null,
+  "status": "pending|resolved|manual"
+}
+```
+
+### 技能索引 (skills-index.json)
+```json
+{
+  "name": "技能名称",
+  "description": "技能描述",
+  "triggers": ["触发词"],
+  "error_pattern": "错误模式",
+  "solution": "解决方案",
+  "created_at": "创建时间",
+  "usage_count": 0,
+  "version": "1.0.0"
+}
+```
+
+## 集成到主流程
+
+### 1. 在工具调用链中添加 Hook
+
+在 `src/tools/` 下的工具调用失败时：
+
+```typescript
+// 示例：在 shell 工具中
+try {
+  const result = await executeCommand(command);
+  // 成功处理
+} catch (error) {
+  // 记录失败
+  selfEvolveHook.onToolFailure({
+    tool: 'shell',
+    input: { command },
+    error: error.message,
+    attemptedSolutions: []
+  });
+  throw error;
+}
+```
+
+### 2. 在任务完成时检查
+
+```typescript
+// 在任务完成后
+selfEvolveHook.onTaskComplete({
+  success: isSuccess,
+  task: taskDescription,
+  error: error?.message
+});
+```
+
+### 3. 定期复盘
+
+可以设置 cron job 或定时任务：
+
+```bash
+# 每天凌晨2点复盘
+0 2 * * * fhcode self-evolve review --daily
+```
+
+## 扩展开发
+
+### 添加新的错误类型
+
+在 `manager.js` 的 `categorizeError` 方法中添加：
+
+```javascript
+if (msg.includes('新的错误关键词')) {
+  return 'new-error-type';
+}
+```
+
+### 创建自定义 Hook
+
+```typescript
+class CustomHook {
+  onToolFailure(context) {
+    // 自定义逻辑
+    this.manager.recordFailure(...);
+  }
+}
+```
+
+## 最佳实践
+
+1. **及时记录**：失败后立即记录，不要延迟
+2. **详细上下文**：记录完整的错误信息和复现步骤
+3. **尝试多种方案**：记录所有尝试过的解决方案
+4. **定期复盘**：每天至少一次复盘分析
+5. **渐进改进**：每次只优化一个方面
+
+## 故障排除
+
+### 数据丢失
+- 检查 `~/.feihong-code/self-evolve/` 目录权限
+- 确保有写入权限
+
+### 技能未生效
+- 检查技能索引是否正确更新
+- 确认 SKILL.md 文件格式正确
+- 重启系统重新加载技能
+
+### 复盘失败
+- 检查配置文件是否存在
+- 确认磁盘空间充足
+- 查看日志文件获取详细错误
+
+## 版本兼容性
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0
+- 飞虹 Code >= 0.5.0

package/docs/self-evolve.md

@@ -0,0 +1,166 @@
+# Self-Evolve 自我迭代系统
+
+## 概述
+
+Self-Evolve 是飞虹 Code 的自我学习与迭代升级系统，能够：
+- 自动记录任务执行中的失败
+- 分析错误模式并提取经验教训
+- 当遇到无法解决的问题时，自动生成新技能
+- 定期复盘优化系统行为
+
+## 快速开始
+
+### 1. 初始化系统
+
+```bash
+# 运行初始化脚本
+bash scripts/self-evolve-setup.sh
+
+# 或使用 CLI
+fhcode self-evolve init
+```
+
+### 2. 查看状态
+
+```bash
+fhcode self-evolve status
+```
+
+输出示例：
+```
+📊 自我迭代系统状态
+========================================
+总失败记录: 15
+已解决:     12
+待处理:     3
+解决率:     80.0%
+技能库:     5 个技能
+```
+
+### 3. 列出失败记录
+
+```bash
+# 列出所有失败
+fhcode self-evolve failures list
+
+# 按类型过滤
+fhcode self-evolve failures list --type compile-error
+
+# 最近7天
+fhcode self-evolve failures list --days 7
+```
+
+### 4. 查看技能库
+
+```bash
+fhcode self-evolve skills list
+```
+
+### 5. 每日复盘
+
+```bash
+fhcode self-evolve review --daily
+```
+
+### 6. 分析错误模式
+
+```bash
+# 分析最近7天
+fhcode self-evolve analyze
+
+# 分析最近30天
+fhcode self-evolve analyze --days 30
+```
+
+### 7. 创建新技能
+
+当遇到新的错误模式时：
+
+```bash
+fhcode self-evolve create-skill \
+  --name path-traversal-handler \
+  --description "处理路径穿越错误" \
+  --pattern path-error \
+  --solution "检查路径安全性，确保在workspace范围内" \
+  --triggers "path traversal, outside workspace, EACCES"
+```
+
+## 数据存储
+
+所有数据存储在 `~/.feihong-code/self-evolve/` 目录：
+
+```
+~/.feihong-code/self-evolve/
+├── config.json          # 配置文件
+├── failures.json        # 失败记录
+├── skills-index.json    # 技能索引
+├── history.json         # 操作历史
+├── version.txt          # 版本信息
+└── report-YYYY-MM-DD.json  # 每日报告
+```
+
+技能文件存储在 `~/.feihong-code/skills/<skill-name>/SKILL.md`
+
+## 工作原理
+
+### 失败记录流程
+
+1. 任务执行失败 → 自动记录到 failures.json
+2. 搜索已知解决方案 → 找到则应用
+3. 未找到 → 标记为待处理
+4. 用户手动解决或系统自动创建技能
+5. 定期复盘优化
+
+### 技能创建流程
+
+1. 检测新的错误模式
+2. 分析根因
+3. 生成解决方案
+4. 创建 SKILL.md 文件
+5. 更新技能索引
+6. 验证效果
+
+## 扩展开发
+
+### 添加自定义 Hook
+
+在 `src/self-evolve/hook.ts` 中扩展：
+
+```typescript
+export class SelfEvolveHook {
+  onToolFailure(context) { /* 自定义逻辑 */ }
+  onTaskComplete(context) { /* 自定义逻辑 */ }
+}
+```
+
+### 集成到主流程
+
+在工具调用链中添加钩子：
+
+```typescript
+// 在工具调用失败时
+selfEvolveHook.onToolFailure({
+  tool: 'shell',
+  input: { command: 'npm test' },
+  error: new Error('test failed')
+});
+```
+
+## 纪律
+
+- 诚实记录失败，不伪造成功
+- 每日至少一次复盘
+- 新技能必须经过验证
+- 所有变更可追溯
+
+## 与现有系统集成
+
+Self-Evolve 可以与以下技能配合：
+
+- `/self-heal`：自动创建修复技能
+- `/plan`：计划时参考历史失败
+- `/goal`：目标设定参考迭代进度
+
+## 版本历史
+
+- v1.0.0 (2026-08-16): 初始版本，基础功能完成