feihong-code 0.2.3 → 0.6.0

package/docs/Deployment_Guide_EN.md

@@ -0,0 +1,288 @@
+# Feihong Code (fhcode) — Deployment Guide
+
+**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. Deployment Shapes
+
+| Shape | Scenario | Components |
+|-------|----------|------------|
+| Standalone CLI | Personal dev / intranet terminal | fhcode CLI (Node.js) |
+| Web service | Team sharing / cloud execution | fhcode serve + task queue |
+| Docker | Containerized / private deployment | Dockerfile + docker-compose |
+| Enterprise private | Multi-tenant / audit / quota | Enterprise mode (FH_ENTERPRISE) |
+| IDE integration | In-editor usage | VSCode extension (thin shell) |
+
+---
+
+## 2. Requirements
+
+| Item | Requirement | Notes |
+|------|-------------|-------|
+| Node.js | ≥ 18 (20/22 recommended) | Runtime |
+| npm | ≥ 9 | Package manager |
+| git | Recommended | diff/rollback/parallel worktrees |
+| Docker | Optional | `FH_SANDBOX_MODE=container` and Docker deployment |
+| Network | Optional | Real model APIs / skills marketplace / HF datasets (offline mode needs no internet) |
+
+**Offline deployment notes**: without a model configured, offline mode (Mock-driven) is used automatically with zero external dependencies; model access can point to an intranet Ollama or a private OpenAI-compatible gateway.
+
+---
+
+## 3. Installation & Deployment
+
+### 3.1 npm Global Install
+
+```bash
+npm install -g feihong-code
+fhcode --version
+```
+
+### 3.2 From Source
+
+```bash
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build          # tsc + Web static asset copy
+npm test               # 164 unit tests self-check
+node scripts/eval.mjs  # local benchmark self-check (10/10)
+```
+
+### 3.3 Docker Deployment (Web service)
+
+```bash
+# build image
+docker build -t feihong-code .
+
+# run the Web console (with task queue)
+docker run -d --name fhcode \
+  -p 8080:8080 \
+  -e FH_WEB_TOKEN=<your-token> \
+  -e FH_PROVIDERS='[{"name":"deepseek","type":"openai-compatible","baseUrl":"https://api.deepseek.com/v1","apiKey":"sk-...","tags":["code-gen"]}]' \
+  -v fhcode-data:/root/.feihong-code \
+  feihong-code
+```
+
+### 3.4 docker-compose (recommended)
+
+```yaml
+# docker-compose.yml
+services:
+  fhcode:
+    build: .
+    ports: ["8080:8080"]
+    environment:
+      FH_WEB_TOKEN: ${FH_WEB_TOKEN}
+      FH_PROVIDERS: ${FH_PROVIDERS}          # model config
+      FH_TASK_CONCURRENCY: "2"               # task concurrency cap
+      FH_TASK_PERSIST_DIR: /data/tasks       # task persistence (resume after restart)
+      FH_ENTERPRISE: "true"                  # enterprise mode
+    volumes:
+      - fhcode-data:/data
+      - fhcode-home:/root/.feihong-code
+volumes:
+  fhcode-data:
+  fhcode-home:
+```
+
+---
+
+## 4. Environment Variable Reference (full)
+
+### 4.1 App & Paths
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FH_HOME` | `~/.feihong-code` | Home dir (sessions/audit/experience/stats/cache) |
+| `FH_LOG_DIR` | `$FH_HOME/sessions` | Session log dir (`~` expansion supported) |
+| `FH_CONFIG` | — | Config file path (fhcode.config.json) |
+| `FHCODE_LANG` | system locale | UI language zh/en |
+
+### 4.2 Model Routing
+
+| Variable | Description |
+|----------|-------------|
+| `FH_PROVIDERS` | JSON array (highest priority): `{name,type,baseURL,apiKey,tags[],costPer1k}` |
+| `FH_MODEL_NAME/TYPE/BASE_URL/API_KEY/TAGS/COST_PER_1K` | Quick single-var setup |
+| `FH_MODEL_STRATEGY` | cost/capability/latency |
+| `FH_BUDGET_USD` | Per-task cost cap (circuit breaker) |
+| `FH_TENANT_BUDGET_USD` | Tenant daily cost cap (overrides policy) |
+
+### 4.3 Security
+
+| Variable | Description |
+|----------|-------------|
+| `FH_SANDBOX_MODE` | read-only / workspace-write / danger-full-access / container |
+| `FH_SANDBOX_IMAGE` | container mode image (default node:22-alpine) |
+| `FH_SHELL_ALLOW` | Shell allowlist (comma-separated) |
+| `FH_REQUIRE_APPROVAL` | Approval switch (default true) |
+| `FH_NETWORK_ALLOW/DENY` | Network domain rules (deny effective in all modes) |
+| `FH_HOOKS` | Hooks JSON array (PreToolUse/PostToolUse/PostEdit) |
+| `FH_POLICY` | Inline policy JSON (RBAC/blacklists, tighten-only) |
+
+### 4.4 Enterprise Mode
+
+| Variable | Description |
+|----------|-------------|
+| `FH_ENTERPRISE` | On by default (false reverts to community mode) |
+| `FH_TENANT` | Tenant id (default: default) |
+| `FH_USER` | User id |
+| `FH_ROLE` | viewer/developer/operator/admin |
+
+### 4.5 Web / Cloud Execution
+
+| Variable | Description |
+|----------|-------------|
+| `FH_WEB_TOKEN` | Web console access token (auto-generated if unset) |
+| `FH_WEB_PORT` | Port (default 8080) |
+| `FH_TASK_CONCURRENCY` | Task concurrency cap (default 2) |
+| `FH_TASK_PERSIST_DIR` | Task persistence dir (default `$FH_HOME/tasks`) |
+| `FH_TASK_WEBHOOK_URL` | Task-status webhook (dynamically registrable) |
+
+### 4.6 Message Channels
+
+| Variable | Description |
+|----------|-------------|
+| `FH_CHANNEL_TELEGRAM_BOT_TOKEN/CHAT_ID` | Telegram notifications |
+| `FH_CHANNEL_WECOM_KEY` | WeCom bot keys (comma-separated, multiple) |
+| `FH_CHANNEL_ALLOW` | Outbound channel allowlist |
+
+### 4.7 Marketplace / Benchmark
+
+| Variable | Description |
+|----------|-------------|
+| `FH_SKILL_MARKET` | Skills marketplace source (default agentskills.io) |
+| `FH_SWEBENCH_DATA_URL` | SWE-bench data mirror/offline JSON (intranet-friendly) |
+
+---
+
+## 5. Enterprise Private Deployment
+
+### 5.1 Directory Layout (tenant isolation)
+
+```
+$FH_HOME/
+├── tenants/<tenantId>/
+│   ├── sessions/          # session checkpoints
+│   ├── audit/             # audit hash chain (audit-YYYY-MM.jsonl)
+│   └── goals/             # goal files
+├── policy.json            # global policy (RBAC/blacklists)
+├── experiences/           # experience library
+├── model-stats.jsonl      # model stats
+├── skills/                # user-level skills
+├── plugins/               # user-level plugins
+└── bench/                 # eval/SWE-bench cache & baselines
+```
+
+### 5.2 Production Recommendations
+
+1. **Token management**: always set `FH_WEB_TOKEN` explicitly (auto-generated is session-only); inject via a secrets manager
+2. **Audit compliance**: run `fhcode audit verify` periodically to validate hash-chain integrity; audit files are monthly-sharded for archiving
+3. **Quota governance**: set `FH_TENANT_BUDGET_USD` for tenant daily budgets; tasks are fail-fast rejected when exceeded
+4. **Backups**: back up `$FH_HOME` (sessions/audit/experience) daily; keep `FH_TASK_PERSIST_DIR` on a separate volume
+5. **Multi-instance**: the task queue persists per file; instances sharing the persist dir cross-recover (queued re-enqueues, running zombies marked failed)
+6. **Intranet models**: point `FH_PROVIDERS` at an intranet Ollama/private gateway to run fully offline
+
+### 5.3 Security Baseline (production must)
+
+```bash
+export FH_REQUIRE_APPROVAL=true
+export FH_SANDBOX_MODE=workspace-write     # or container
+export FH_NETWORK_DENY=...                 # as needed
+export FH_ENTERPRISE=true
+export FH_CHANNEL_ALLOW=telegram,wecom     # channel allowlist (optional)
+```
+
+---
+
+## 6. Web Service Operations
+
+### 6.1 Start & Health Check
+
+```bash
+fhcode serve --port 8080
+curl http://localhost:8080/api/health   # unauthenticated health check
+```
+
+### 6.2 Task Queue API (Bearer auth)
+
+```bash
+TOKEN=$FH_WEB_TOKEN
+# submit / list / query / webhook register
+curl -X POST http://localhost:8080/api/tasks -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"goal":"..."}'
+curl http://localhost:8080/api/tasks -H "Authorization: Bearer $TOKEN"
+curl http://localhost:8080/api/tasks/<id> -H "Authorization: Bearer $TOKEN"
+curl -X POST http://localhost:8080/api/webhook -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"url":"https://ci.example.com/hook"}'
+```
+
+### 6.3 Restart Recovery
+
+- Tasks persist to `$FH_HOME/tasks/<id>.json` (atomic writes)
+- After restart: queued tasks re-enqueue, running zombies are marked failed, terminal states remain queryable
+- webhook/channel notifications re-fire on the queued node during recovery
+
+---
+
+## 7. CI/CD Integration (regression gate)
+
+```yaml
+# .github/workflows/ci.yml excerpt
+- name: Build & test
+  run: |
+    npm ci
+    npm run typecheck
+    npm test
+    npm run build
+
+- name: eval regression gate (baseline compare)
+  run: |
+    npm run build
+    node scripts/eval.mjs --baseline bench/eval-baseline.json
+  # fails when current pass is below baseline
+
+- name: Update baseline (main branch)
+  if: github.ref == 'refs/heads/main'
+  run: node scripts/eval.mjs --save-baseline bench/eval-baseline.json
+```
+
+### SWE-bench harness (optional)
+
+```bash
+node scripts/eval-swebench.mjs --split lite --limit 20 --run --report report.md
+# offline/intranet: point FH_SWEBENCH_DATA_URL at a mirror JSON
+```
+
+---
+
+## 8. Upgrades & Rollback
+
+| Action | Command |
+|--------|---------|
+| Upgrade npm package | `npm install -g feihong-code@latest` |
+| Upgrade from source | `git pull && npm install && npm run build` |
+| Check version | `fhcode --version` / `fhcode doctor` |
+| Rollback | npm install a previous version / git checkout an old tag (data dir is compatible and does not roll back with code) |
+
+> Data compatibility: session checkpoints/audit/experience are JSON/JSONL text formats, backward compatible across minor versions; back up `$FH_HOME` before upgrading.
+
+---
+
+## 9. Troubleshooting
+
+| Symptom | Diagnosis |
+|---------|-----------|
+| 401 after service start | `FH_WEB_TOKEN` unset or mismatched with the caller (Bearer header) |
+| Tasks stuck queued | Concurrency full (`FH_TASK_CONCURRENCY`) or persist dir not writable |
+| Model calls fail | Run `fhcode doctor` to check network reachability and provider config |
+| Shell fails inside Docker | Confirm `FH_SANDBOX_MODE`/image; `FH_SANDBOX_IMAGE` must include required tools |
+| Abnormal task states after restart | Running zombies are marked failed (expected); queued tasks auto-resume |
+| Marketplace/dataset fetch fails | Use a mirror on intranet: `FH_SKILL_MARKET` / `FH_SWEBENCH_DATA_URL` |
+
+---
+
+*Full configuration: see Configuration Reference; error codes and detailed troubleshooting: see FAQ & Troubleshooting.*

package/docs/SELF-EVOLVE-GUIDE.md

@@ -0,0 +1,313 @@
+# 自我进化系统使用指南
+
+> 版本: v0.5.1 | 最后更新: 2026-08-22
+
+---
+
+## 概述
+
+自我进化（Self-Evolve）是 feihong-code 的核心能力之一，使系统能够从失败中学习、积累经验并持续优化。该系统包含三个主要组件：
+
+1. **失败记录** - 自动捕获执行过程中的错误
+2. **经验学习** - 分析历史失败，生成解决方案
+3. **每日复盘** - 总结当日工作，优化策略
+
+---
+
+## 快速开始
+
+### 启用自我进化
+
+```bash
+# CLI 模式
+fhcode "你的任务" --self-evolve
+
+# Web 控制台
+# 在设置中启用 "Self-Evolve" 开关
+```
+
+### 查看进化状态
+
+```bash
+# 查看当前进化状态
+fhcode evolve status
+
+# 查看失败记录
+fhcode evolve failures
+
+# 查看学习经验
+fhcode evolve lessons
+```
+
+---
+
+## 核心功能
+
+### 1. 失败记录机制
+
+系统自动记录以下类型的失败：
+
+| 错误类型 | 触发条件 | 记录内容 |
+|----------|----------|----------|
+| `MODEL_TIMEOUT` | 模型响应超时 | 超时时长、模型名称 |
+| `AUTH_FAILURE` | API 认证失败 | 错误代码、提供商 |
+| `RATE_LIMIT` | 请求频率限制 | 限制值、重置时间 |
+| `EXECUTION_ERROR` | 工具执行失败 | 工具名、错误信息 |
+| `PERMISSION_DENIED` | 权限不足 | 操作类型、所需权限 |
+
+**存储位置**: `~/.fhcode/evolve/failures.jsonl`
+
+### 2. 经验学习引擎
+
+系统会分析失败记录，生成可复用的解决方案：
+
+```typescript
+// 经验数据结构
+interface LearnedLesson {
+  errorType: string;           // 错误类型
+  pattern: string;             // 问题模式
+  solution: string;            // 解决方案
+  confidence: number;          // 置信度 (0-1)
+  usageCount: number;          // 应用次数
+  createdAt: Date;             // 创建时间
+}
+```
+
+**查看学习经验**:
+```bash
+fhcode evolve lessons --recent  # 查看最近学习的经验
+fhcode evolve lessons --type MODEL_TIMEOUT  # 按类型筛选
+```
+
+### 3. 每日复盘报告
+
+系统每天自动生成复盘报告：
+
+```bash
+# 手动生成复盘报告
+fhcode evolve report --date 2026-08-22
+
+# 查看今日报告
+fhcode evolve report --today
+```
+
+**报告内容**:
+- 今日失败统计
+- 已应用的解决方案
+- 未解决的问题
+- 优化建议
+
+---
+
+## 配置选项
+
+### 基本配置
+
+编辑 `~/.fhcode/config.json`:
+
+```json
+{
+  "selfEvolve": {
+    "enabled": true,
+    "maxFailuresToRemember": 100,
+    "lessonConfidenceThreshold": 0.7,
+    "dailyReportEnabled": true,
+    "autoApplyLessons": true
+  }
+}
+```
+
+### 配置参数说明
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `enabled` | `true` | 是否启用自我进化 |
+| `maxFailuresToRemember` | `100` | 最大保留失败记录数 |
+| `lessonConfidenceThreshold` | `0.7` | 经验应用的最低置信度 |
+| `dailyReportEnabled` | `true` | 是否生成每日报告 |
+| `autoApplyLessons` | `true` | 是否自动应用学习到的经验 |
+
+---
+
+## 高级用法
+
+### 强制重新学习
+
+```bash
+# 清除所有学习经验，重新开始
+fhcode evolve reset --lessons
+
+# 仅清除失败记录
+fhcode evolve reset --failures
+
+# 完全重置（谨慎使用）
+fhcode evolve reset --all
+```
+
+### 导出学习数据
+
+```bash
+# 导出失败记录
+fhcode evolve export --type failures --format json
+
+# 导出学习经验
+fhcode evolve export --type lessons --format json
+
+# 导出复盘报告
+fhcode evolve export --type report --format markdown
+```
+
+### 导入外部经验
+
+```bash
+# 从 JSON 文件导入经验
+fhcode evolve import --file lessons.json
+
+# 从 GitHub Gist 导入
+fhcode evolve import --url https://gist.github.com/...
+```
+
+---
+
+## 与企业安全集成
+
+自我进化系统完全兼容企业安全策略：
+
+- **审计链**: 所有失败记录和解决方案变更都会记录到审计日志
+- **权限控制**: 可通过 RBAC 控制谁可以查看/修改学习经验
+- **数据隔离**: 多租户场景下，各租户的学习经验相互隔离
+
+### 安全配置示例
+
+```json
+{
+  "selfEvolve": {
+    "enabled": true,
+    "auditEnabled": true,
+    "dataIsolation": "tenant",
+    "maxRetentionDays": 90
+  }
+}
+```
+
+---
+
+## 故障排查
+
+### 常见问题
+
+**Q: 自我进化没有正常工作？**
+
+检查项:
+1. 确认 `selfEvolve.enabled` 为 `true`
+2. 检查 `~/.fhcode/evolve/` 目录权限
+3. 查看日志: `cat ~/.fhcode/logs/evolve.log`
+
+**Q: 学习经验没有生效？**
+
+检查项:
+1. 确认 `autoApplyLessons` 为 `true`
+2. 检查经验的 `confidence` 是否达到阈值
+3. 查看应用日志: `fhcode evolve lessons --verbose`
+
+**Q: 每日报告没有生成？**
+
+检查项:
+1. 确认 `dailyReportEnabled` 为 `true`
+2. 报告在每天 23:59 自动生成，检查当时系统是否运行
+3. 手动生成测试: `fhcode evolve report --today`
+
+### 日志位置
+
+| 日志类型 | 路径 |
+|----------|------|
+| 主日志 | `~/.fhcode/logs/main.log` |
+| 进化日志 | `~/.fhcode/logs/evolve.log` |
+| 审计日志 | `~/.fhcode/audit/audit.jsonl` |
+
+---
+
+## 最佳实践
+
+### 1. 定期审查学习经验
+
+```bash
+# 每周审查一次
+fhcode evolve lessons --review
+
+# 清理低置信度经验
+fhcode evolve clean --confidence < 0.5
+```
+
+### 2. 分享成功经验
+
+将学习到的经验分享给团队：
+
+```bash
+# 导出团队可用的经验
+fhcode evolve export --scope team --format json
+```
+
+### 3. 监控进化指标
+
+关注以下指标评估自我进化效果：
+
+- **失败率下降趋势**: 同类错误重复发生次数应逐渐减少
+- **经验应用成功率**: 自动应用的解决方案成功率应 > 80%
+- **问题解决时长**: 从首次失败到解决方案生成的时间
+
+---
+
+## 技术架构
+
+### 数据流
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  任务执行    │ ──→ │  失败捕获    │ ──→ │  经验学习    │
+└─────────────┘     └─────────────┘     └─────────────┘
+                                       ┌─────────────┐
+                                       │  每日复盘    │
+                                       └─────────────┘
+                                             │
+                                             ↓
+                                       ┌─────────────┐
+                                       │  策略优化    │
+                                       └─────────────┘
+```
+
+### 核心类
+
+```typescript
+// 自我进化管理器
+class SelfEvolveManager {
+  init(): void;
+  recordFailure(errorType: string, error: any, attemptedSolutions?: string[]): void;
+  searchSolution(errorType: string, errorMessage: string): Lesson[];
+  generateDailyReport(): Report;
+}
+
+// 经验数据模型
+interface LearnedLesson {
+  id: string;
+  errorType: string;
+  pattern: string;
+  solution: string;
+  confidence: number;
+  usageCount: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+---
+
+## 相关链接
+
+- [错误码参考](./error-codes.md)
+- [企业部署指南](../DEPLOYMENT-GUIDE.md)
+- [自我进化实现细节](./self-evolve-implementation.md)
+
+---
+
+*本系统由飞扬企源研发中心 (FyqyRDC) 开发*