feihong-code 0.2.2 → 0.5.1

package/docs/User_Manual_EN.md

@@ -0,0 +1,314 @@
+# Feihong Code (fhcode) — User Manual
+
+**Version**: v0.5.0-b
+**Date**: 2026-08-16
+**Product**: Feihong Code (feihong-code) — a terminal AI coding agent (a Muse Code reimplementation)
+**Attribution**: Jinjiang Feihongzhi Tech Enterprise Management Co., Ltd. · Feiyang Qiyuan R&D Center · Lead: Wu Cihong
+
+---
+
+## 1. Quick Start
+
+### 1.1 Requirements
+
+- Node.js ≥ 18 (20/22 recommended)
+- npm ≥ 9
+- git (needed for diff/rollback/parallel worktrees)
+- Docker (only for `FH_SANDBOX_MODE=container`)
+
+### 1.2 Installation
+
+```bash
+# Option A: build from source (recommended)
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build
+
+# Option B: npm global install
+npm install -g feihong-code
+fhcode --version   # verify
+```
+
+### 1.3 Up and Running in Seconds
+
+```bash
+# Without a model configured, offline mode (Mock-driven loop) is used automatically
+fhcode "write a hello.ts"
+
+# Configure a real model (DeepSeek example) to go live
+export FH_PROVIDERS='[{"name":"deepseek","type":"openai-compatible","baseUrl":"https://api.deepseek.com/v1","apiKey":"sk-...","tags":["code-gen","reasoning"],"priority":1}]'
+fhcode "fix the token validation bug in src/auth.ts"
+```
+
+---
+
+## 2. Command Reference
+
+```bash
+# Basics
+fhcode                              Enter interactive REPL (TUI enabled on TTY)
+fhcode "<request>"                  Run a single request
+fhcode --stream "<request>"         Stream output (live task progress)
+fhcode --yes "<request>"            Skip approvals (use with care)
+fhcode --lang zh|en                 Set UI language
+
+# Read-only skills
+fhcode /plan "<goal>"               Generate an implementation plan
+fhcode /grill [path]                Red-team code review (text)
+fhcode review [path] [--json]       Structured code review (--json for IDE/CI)
+fhcode /goal "<goal>"               Decompose and save a high-level goal
+
+# Session management (M3)
+fhcode sessions                     List historical sessions
+fhcode resume <id>                  Resume from checkpoint
+fhcode diff [id]                    Show session/workspace diff
+fhcode rollback <id> --yes          Roll back session changes (destructive)
+
+# Enterprise (M4)
+fhcode whoami                       Current tenant/user/role/quota
+fhcode policy                       Show active RBAC policy
+fhcode audit [verify]               Audit records / hash-chain verification
+fhcode tenants                      Tenant usage summary
+
+# Self-evolution (M6/M8/M9)
+fhcode model-stats                  Model performance stats
+fhcode experiences [path]           Experience library
+fhcode code-write "<goal>"          Autonomous coding
+fhcode quality-gate [path]          Quality-gate review
+fhcode self-improve                 Self-improvement stats
+fhcode swe "<goal>"                 Fully autonomous SWE agent
+fhcode team "<goal>"                Multi-agent collaboration (shared board + message bus)
+
+# Ecosystem
+fhcode skill-market search "<keyword>"   Search the skills marketplace (agentskills.io)
+fhcode skill-market install <name>       Install a skill
+fhcode skill-market list                 List local skills
+fhcode plugin install <dir|git-url>      Install a plugin
+fhcode plugin list                       List plugins
+fhcode doctor                            Environment self-check
+```
+
+**Useful flags**: `--parallel` (parallel worktrees) / `--repo` (swe target repo / marketplace source) / `--context-file <path>` (attach a file as context) / `--max-iterations N` / `--max-retries N` / `--plan-only` / `--verify-only` / `--json`.
+
+---
+
+## 3. Model Configuration
+
+### 3.1 Priority
+
+1. `FH_PROVIDERS` (JSON array, highest priority)
+2. `fhcode.config.json` (project config `models.providers`)
+3. Single env vars `FH_MODEL_*`
+
+### 3.2 Local Ollama
+
+```bash
+export FH_MODEL_NAME=qwen3:8b
+export FH_MODEL_TYPE=ollama
+export FH_MODEL_BASE_URL=http://localhost:11434
+export FH_MODEL_TAGS=code-gen,reasoning,local
+```
+
+### 3.3 DeepSeek / Qwen
+
+```bash
+# DeepSeek
+export FH_PROVIDERS='[{"name":"deepseek","type":"openai-compatible","baseUrl":"https://api.deepseek.com/v1","apiKey":"sk-...","tags":["code-gen","reasoning"],"costPer1k":0.0001}]'
+# Qwen (Alibaba)
+export FH_PROVIDERS='[{"name":"qwen","type":"openai-compatible","baseUrl":"https://dashscope.aliyuncs.com/compatible-mode/v1","apiKey":"...","tags":["code-gen","long-context"]}]'
+```
+
+### 3.4 Routing Strategy
+
+```bash
+export FH_MODEL_STRATEGY=cost        # cost | capability | latency
+export FH_BUDGET_USD=0.5             # per-task cost cap (circuit breaker)
+```
+Providers tagged `cheap` are preferred for `swe`/parallel sub-tasks (P1-1 model split).
+
+---
+
+## 4. Typical Workflows
+
+### 4.1 Single Task
+
+```bash
+fhcode "implement an HTTP server listening on port 3000"
+# Streaming + attach a file as context
+fhcode --stream --context-file src/auth.ts "review and fix the security issues in this file"
+```
+
+### 4.2 Fully Autonomous SWE (swe)
+
+```bash
+fhcode swe "fix the add function bug in src/calc.ts so tests/calc.test.ts passes" \
+  --repo /path/to/project \
+  --max-tasks 3 --max-iterations 5
+# --plan-only / --verify-only / --max-retries N (self-heal retries)
+```
+
+### 4.3 Multi-Agent Collaboration (team)
+
+```bash
+fhcode team "implement a login module and a user management module and write integration tests"
+# Goal auto-decomposed → agents claim concurrently → message bus reports → team report
+```
+
+### 4.4 Skills Marketplace & Plugins
+
+```bash
+fhcode skill-market search "code review"
+fhcode skill-market install code-review     # auto-discovered in tasks after install
+fhcode plugin install ./my-plugin           # packages skills+hooks+MCP
+```
+
+### 4.5 Session Resume & Rollback
+
+```bash
+fhcode sessions                 # find the session id
+fhcode resume <id>              # continue after interruption
+fhcode diff <id>                # inspect changes
+fhcode rollback <id> --yes      # roll back (destructive)
+```
+
+### 4.6 Environment Self-Check
+
+```bash
+fhcode doctor
+# ✅ Node version / git / model config / network / home dir / sandbox mode
+```
+
+---
+
+## 5. REPL / TUI
+
+```bash
+fhcode          # interactive mode (TUI enabled automatically on TTY)
+```
+- TUI: sticky header shows mode/runId/iterations/cost/state; content scrolls; wheel to scroll back
+- Type a request and press Enter; `exit`/`quit`/Ctrl+D to leave
+- Slash skills supported: `/plan` `/grill` `/goal`
+
+---
+
+## 6. VSCode Extension
+
+Package in `vscode-extension/` (`npx @vscode/vsce package`) or load via F5:
+
+| Command | Description |
+|---------|-------------|
+| `fhcode: Run task (with selection context)` | Selected code auto-injected as `<selection>` context |
+| `fhcode: Inline review current file` | `review --json` → inline diagnostics (red/yellow/blue) |
+| `fhcode: View workspace diff` | Native diff editor HEAD↔workspace |
+| `fhcode: Show recent task output` | Focus the Output Channel |
+
+Settings: `fhcode.binaryPath` / `fhcode.offline` / `fhcode.reviewOnSave` (auto-review on save, default on).
+
+---
+
+## 7. Web Console (Cloud Execution)
+
+```bash
+fhcode serve --port 8080
+# open http://localhost:8080 in a browser
+```
+
+**Task panel**: enter the token (printed by the terminal as `FH_WEB_TOKEN`) → submit a goal → poll status → expand result details.
+
+**API usage** (Bearer auth):
+
+```bash
+TOKEN=$(echo $FH_WEB_TOKEN)
+# submit a task
+curl -X POST http://localhost:8080/api/tasks \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"goal":"write a hello.ts"}'
+# query
+curl http://localhost:8080/api/tasks -H "Authorization: Bearer $TOKEN"
+curl http://localhost:8080/api/tasks/<id> -H "Authorization: Bearer $TOKEN"
+# register a webhook (task-status callback, schedulable by CI)
+curl -X POST http://localhost:8080/api/webhook \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"url":"https://your-ci.example.com/hook"}'
+```
+
+---
+
+## 8. Message Channels
+
+```bash
+# Telegram notifications (task status changes)
+export FH_CHANNEL_TELEGRAM_BOT_TOKEN=bot:xxx
+export FH_CHANNEL_TELEGRAM_CHAT_ID=12345
+# WeCom group bot (multiple keys)
+export FH_CHANNEL_WECOM_KEY=key1,key2
+# Outbound allowlist (optional; once set, only allowlisted channels may send)
+export FH_CHANNEL_ALLOW=telegram,wecom
+```
+
+---
+
+## 9. Sandbox & Safe Usage
+
+```bash
+export FH_SANDBOX_MODE=workspace-write      # default
+export FH_SANDBOX_MODE=read-only            # read-only survey (no writes/exec)
+export FH_SANDBOX_MODE=danger-full-access   # full access (dangerous commands still blocked)
+export FH_SANDBOX_MODE=container            # run shell inside a Docker container
+export FH_SANDBOX_IMAGE=node:22-alpine      # container image
+
+# Network domain rules
+export FH_NETWORK_DENY=evil.example.com
+# export FH_NETWORK_ALLOW=api.example.com
+
+# Deterministic hooks (PreToolUse non-zero exit blocks)
+export FH_HOOKS='[{"event":"PreToolUse","command":"node scripts/guard.js","tools":["run_shell"]}]'
+```
+
+---
+
+## 10. eval Benchmark & Regression Gate
+
+```bash
+# Local benchmark (5 scenarios + 5 acceptance tasks, real-artifact verification)
+npm run build && npm run eval
+
+# Save baseline + compare gate (fails when below baseline; CI-ready)
+node scripts/eval.mjs --save-baseline bench/eval-baseline.json
+node scripts/eval.mjs --baseline bench/eval-baseline.json
+
+# SWE-bench dataset loading (HF or mirror)
+node scripts/eval-swebench.mjs --split lite --limit 5
+node scripts/eval-swebench.mjs --split lite --limit 5 --run --report report.md
+FH_SWEBENCH_DATA_URL=https://mirror.example/swebench.json node scripts/eval-swebench.mjs --limit 3
+```
+
+---
+
+## 11. FAQ
+
+| Problem | Solution |
+|---------|----------|
+| Real mode wanted without model config | Set `FH_PROVIDERS` or `FH_MODEL_NAME` to leave offline mode |
+| Task aborted by cost cap | Raise `FH_BUDGET_USD` or role `maxCostUsd`, resume with `fhcode resume` |
+| Quota rejected (QUOTA_EXCEEDED) | Adjust `FH_TENANT_BUDGET_USD` or policy `tenantDailyBudgetUsd` |
+| review returns empty | Confirm the path is a file/dir with supported extensions (ts/js/tsx/jsx/json/md/py/go/java) |
+| Marketplace fetch fails | Check network or set `FH_SWEBENCH_DATA_URL` / `--repo` mirror |
+| Switch language | `fhcode --lang en` or `FHCODE_LANG=en` |
+
+---
+
+## 12. Troubleshooting & Logs
+
+```bash
+export FH_LOG_LEVEL=debug        # verbose logs
+fhcode doctor                    # environment self-check
+fhcode audit verify              # audit chain integrity
+# Event logs: ~/.feihong-code/sessions/<runId>.jsonl
+# Checkpoints: ~/.feihong-code/sessions/<runId>.session.json
+```
+
+---
+
+*Full configuration reference: see Configuration Reference and Deployment Guide; error codes: see FAQ & Troubleshooting.*

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): 初始版本，基础功能完成