feihong-code 0.2.3 → 0.5.1

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/Technical_Manual_EN.md

@@ -0,0 +1,216 @@
+# Feihong Code (fhcode) — Technical 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. Product Overview
+
+Feihong Code (fhcode) is an AI coding agent that runs across terminal / Web / IDE surfaces, centered on the "natural language → code loop". It supports multi-model routing, enterprise-grade security, fully autonomous software engineering and self-improvement. It has zero third-party runtime dependencies (only express + zod), works offline, and can be privately deployed.
+
+**Capability matrix (v0.5.0)**:
+
+| Area | Capabilities |
+|------|--------------|
+| Orchestration | ReAct loop, planner, context compaction, checkpoint resume, cost circuit breaker, self-healing loop |
+| Models | Multi-model routing (cost/capability/latency strategies + fallback + stats-based ranking), OpenAI-compatible / Ollama / Mock |
+| Tools | File read/write/edit, search, managed shell, build check, test run, web retrieval, skill loading |
+| Self-improvement | Experience library (RL-style upsert/recall), reflector feedback loop, self-healing, eval benchmark, SWE-bench harness |
+| Security | Four-tier sandbox, network domain rules, deterministic hooks, RBAC, audit hash chain, quota circuit breaker, redaction, inbound signature verification |
+| Ecosystem | SKILL.md skill standard, Skills marketplace (agentskills.io), MCP, plugin distribution, Agent teams |
+| Delivery | CLI/TUI, Web console (task panel), VSCode extension, cross-process task queue, message channels |
+
+---
+
+## 2. System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       Access Layer                          │
+│  CLI (index/run/repl/TUI) · Web (server/task-queue) · IDE ext │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+┌──────────────────────────────▼──────────────────────────────┐
+│                     Orchestration agent/                    │
+│  Orchestrator(ReAct) · planner · repo-reader · swe-agent     │
+│  subagent(nested) · team(message bus) · self-heal · experience│
+│  quality-gate · code-writer · repo-context · symbol-index    │
+└──────────────┬───────────────────────────────┬──────────────┘
+               │                               │
+┌──────────────▼──────────────┐  ┌─────────────▼──────────────┐
+│        Model Layer models/   │  │         Tool Layer tools/   │
+│  ModelRouter(strategy+stats) │  │  file/search/shell/verify   │
+│  OpenAICompatible/Ollama/Mock│  │  web(MCP) / skills(load)    │
+│  sandbox(4 tiers+net rules)  │  │  tool.registry(zod+guard)   │
+└──────────────┬──────────────┘  └─────────────┬──────────────┘
+               │                               │
+┌──────────────▼───────────────────────────────▼──────────────┐
+│     Security enterprise/ + runtime/hooks                    │
+│  tenant(multi-tenant) · policy(RBAC) · audit(hash chain)    │
+│  guard · hooks(PreToolUse/PostEdit) · channels              │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+┌──────────────────────────────▼──────────────────────────────┐
+│        Infrastructure shared/ + runtime/                    │
+│  config(env-first) · i18n(zh/en) · logger(redacting JSON)   │
+│  event-log(JSONL) · session-persist · git · worktree        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Module layout** (`src/`):
+
+| Directory | Responsibility |
+|-----------|----------------|
+| `cli/` | Arg parsing, command dispatch, run assembly, REPL/TUI, version |
+| `agent/` | Orchestrator, planner, SWE, subagents, teams, self-heal, experience, symbol index, repo context |
+| `models/` | Model router, providers (OpenAI-compatible/Ollama/Mock), cost estimation, DTO validation |
+| `tools/` | Tool system: file/search/shell/verify/web/MCP/skill loading/sandbox |
+| `enterprise/` | Multi-tenancy, RBAC policy, audit chain, quota, guard |
+| `runtime/` | Event log, session persistence, git helpers, worktree, hooks |
+| `shared/` | Config, i18n, logger (redacting), error hierarchy, types |
+| `skills/` | Skill standard (SKILL.md loading), skill marketplace (agentskills.io), /plan /grill /goal |
+| `plugins/` | Plugin distribution (plugin.json packaging skills+hooks+MCP) |
+| `web/` | Web console, task queue, message channels, inbound signature verification |
+
+---
+
+## 3. Core Modules
+
+### 3.1 Orchestrator (agent/orchestrator.ts)
+
+ReAct main loop `run(goal, resume?)`, per iteration:
+1. `router.chat()` calls the model (with capability-tag routing)
+2. No tool calls → task complete; otherwise `executeToolRound()` executes tools and feeds back tool messages
+3. Error detection: `roundErrors > 0` → `handleRecovery()` (classify → inject reflection → retry, cap `maxRetryErrors`)
+4. Context compaction: when `shouldCompact()` triggers, the system instruction is preserved (H4 fix)
+5. Checkpoint persistence (`persist` callback) + event stream (`onEvent`, P0-1 streaming output)
+
+**Event stream (P0-1)**: `OrchestratorEvent` discriminated union — model.response / tool.call / tool.result / self-heal / context.compact / session.end. The CLI stream renderer, TUI header driver and eval counters all consume the same event source.
+
+**Cost circuit breaker (M4)**: `cost >= maxCostUsd` aborts immediately with a `resume` hint; `maxCostUsd=0` means unlimited.
+
+**Experience feedback (M6)**: at session end, `extractExperience()` (table-driven EXTRACTORS) → `upsertExperience` (stable id merge, sessionCount accumulation, success-rate weighted average); self-healed sessions additionally persist `extractFixPattern`.
+
+### 3.2 Model Router (models/model-router.ts)
+
+- Strategies: `cost` (by costPer1k) / `latency` (local-first) / `capability` (tag-weighted)
+- Ranking: `rank(tags)` capability filter + historical success-rate weight (≥3 calls, up to +0.3)
+- Fallback: try in order; failures recorded under `p.model` (fix: no empty model-name entries); throw last error if all fail
+- Stats: `updateStat()` auto-persists (`statsHomeDir`, P5 loop-closure fix); `model-stats` command reads them
+- Sub-task split (P1-1): `tags: ['code-gen','cheap']` routes sub-tasks to low-cost models
+
+### 3.3 Tool System (tools/)
+
+- `ToolRegistry`: register/find/execute, zod argument validation, errors normalized to `ToolResult`
+- Execution chain (defense in depth): **sandbox → PreToolUse hook → RBAC guard → tool → PostToolUse/PostEdit hook**
+- Four-tier sandbox (P0-2/P5-4): `read-only` / `workspace-write` / `danger-full-access` / `container` (Docker-mount workspace for shell)
+- Network domain rules: `FH_NETWORK_ALLOW/DENY` apply to run_shell command URLs and web tool URLs alike
+- Hooks (P2-1): `FH_HOOKS` JSON array; PreToolUse non-zero exit blocks, PostEdit fires after edits; placeholders `{cwd}{tool}{path}{runId}{ok}`
+
+### 3.4 SWE Agent (agent/swe-agent.ts + swe-planner + swe-verifier)
+
+Repository read (`repo-reader`, throttled/ignored rules) → task decomposition (`planSweTask`) → per-task "implement (runSubTask) + verify (build/test) + self-heal retry" → report. Supports `--plan-only` / `--verify-only` / `--max-tasks` / `--max-retries`.
+
+**Subagents (P3-4)**: `runSubAgent` depth control (default 3 levels); decomposable goals recursively spawn subagents (sub-directory isolation) when depth is not exhausted, with per-level summarized results (`summarizeSubTaskAnswer`, P2-2).
+
+### 3.5 Agent Teams (agent/team.ts, P4-2)
+
+- `TeamBus`: message bus (send/receive/broadcast, directed and fan-out)
+- `TaskBoard`: shared task list (atomic claim to prevent duplicates, status+owner double check)
+- `runTeam`: multiple agents claim and execute concurrently; `ok=false` marks failed (fix); produces a team report
+
+### 3.6 Enterprise Security (enterprise/)
+
+| Module | Mechanism |
+|--------|-----------|
+| tenant | Tenant-isolated directories (`tenants/<id>/{sessions,audit,goals}`) |
+| policy | RBAC: role-tool matrix (viewer/developer/operator/admin) + denyShell blacklist + denyPaths sensitive paths, deny-first |
+| audit | Hash chain (SHA-256, seq/prevHash linkage), cross-process file lock + exponential backoff, redaction before write, `audit verify` |
+| quota | Tenant daily cost budget (`FH_TENANT_BUDGET_USD`), fail-fast live re-check before start (M14 fix) |
+| guard | "Policy → approval → audit" pre-tool hook; audit failure = deny |
+
+### 3.7 Skills & Marketplace (skills/)
+
+- **SKILL.md standard (P1-2)**: frontmatter (name/description) + body; progressive disclosure — index (≤8KB) resident in system prompt, body loaded on demand via `load_skill` tool (Tier-2)
+- Discovery: repo `.agents/skills` / `.claude/skills` upward walk + bundled `skills/` + user `~/.feihong-code/skills` + plugin skill dirs
+- **Marketplace (P6)**: agentskills.io discovery spec (`/.well-known/agent-skills/index.json`); `skill-market search/install/list`; RFC 3986 URL resolution, sha256 digest verification, tar.gz unpack (zero-dep hand-written, path-traversal protected)
+- **Plugins (P3-3)**: `plugin.json` packaging skills+hooks+MCP; user/project two-level discovery; `plugin install` (local dir/git clone)
+
+### 3.8 Web & Cloud Execution (web/)
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/health` | Public health check (unauthenticated) |
+| `POST/GET /api/tasks`, `GET /api/tasks/:id` | Task queue (Bearer auth, P4-1) |
+| `POST/GET /api/webhook` | Webhook scheduling registration/query (P5-2) |
+| other `/api/...` | Require `FH_WEB_TOKEN` Bearer (fail-closed, timing-safe comparison) |
+
+**Task queue (P4-1/P6-4)**: state machine queued→running→done|failed; concurrency cap (`FH_TASK_CONCURRENCY`); cross-process persistence (`FH_TASK_PERSIST_DIR`, one file per task with atomic writes; on restart queued tasks re-enqueue, running zombies marked failed); webhook status callbacks (status snapshot, fixing the lost-queued race).
+
+**Message channels (P5-6/O6)**: Telegram (`FH_CHANNEL_TELEGRAM_BOT_TOKEN`+`CHAT_ID`) and WeCom (`FH_CHANNEL_WECOM_KEY`, multiple keys) outbound push; outbound allowlist `FH_CHANNEL_ALLOW`; inbound signature tools `verifyHmacSignature` (HMAC-SHA256 timing-safe) / `verifyWecomSignature` (WeCom SHA1 sort).
+
+### 3.9 IDE Extension (vscode-extension/)
+
+Thin-shell design (all logic in the CLI): `fhcode.run` (selection context injection `<selection>`), `fhcode.review` (`review --json` → editor inline diagnostics via DiagnosticCollection + CodeAction suggestions), `fhcode.diff` (native diff editor HEAD↔workspace via `fhcode-head` scheme), `fhcode.output`; settings `binaryPath` / `offline` / `reviewOnSave`.
+
+---
+
+## 4. Protocols & Standards
+
+| Protocol | Description |
+|----------|-------------|
+| Tool-call contract | OpenAI-style `tool_calls` (name/arguments JSON); results fed back as role=tool messages (toolCallId matched) |
+| MCP | stdio transport (NDJSON JSON-RPC 2.0): initialize → notifications/initialized → tools/list → tools/call; tools registered as `<server>_<tool>` |
+| SKILL.md | open agent skills compatible (frontmatter name/description + body, progressive disclosure) |
+| agentskills.io | discovery index 0.2.0: `$schema` validation, skill-md/archive, digest `sha256:<hex>` |
+| webhook | `POST {url}` JSON: `{event:'task.status', task:{...}, ts}` (status snapshot) |
+| inbound signature | HMAC-SHA256 (`sha256=<hex>` header) or WeCom SHA1 sort |
+| checkpoint | `<runId>.session.json` (full dialogue/iterations/cost/touchedFiles), resume continues |
+
+---
+
+## 5. Security Design
+
+1. **Defense in depth**: sandbox (technical boundary) → hooks (deterministic control) → RBAC policy (permission) → audit (trace) → quota (cost)
+2. **Sandbox**: four tiers + network domain rules (deny effective in all modes, allow blocks non-matching in workspace-write); `container` tier Docker isolation
+3. **Command protection**: run_shell injection metacharacter blocking (`[;&|`$(){}<>!]` etc.); managed commands (run_tests/build_check) allow only package-manager scripts
+4. **Path safety**: `safeJoin` (lexical + realpath symlink validation); policy denyPaths sensitive-path blacklist (.env/.git/config/keys etc.)
+5. **Audit**: tamper-evident hash chain (`verifyAudit` checks seq/prevHash/hash); redaction before write (SECRET_RE/Bearer/JWT/sk-)
+6. **Log redaction**: sensitive keys masked whole-value + value patterns (sk-/JWT/long tokens)
+7. **Web auth**: Bearer token timing-safe comparison, fail-closed; 1MB body limit
+8. **Inbound security**: webhook signature verification (HMAC/WeCom), channel allowlist
+9. **Skill security**: marketplace digest verification against tampering, tar.gz path-traversal protection, mandatory name frontmatter
+
+---
+
+## 6. Performance & Quality Baseline (measured at v0.5.0-b)
+
+| Metric | Value |
+|--------|-------|
+| Unit tests | 164/164 green (16 modules + 10 feature areas) |
+| Milestone assertions | M4 41 · M6 29 · M7 12 · M8 27 · M9 25 = 134 green |
+| eval benchmark | 10/10 (5 scenarios + 5 acceptance, real-artifact verification, 100% pass) |
+| SWE-bench loader | HF datasets-server / mirror / cache, mock execution + report |
+| Complexity | 676 functions, 52 hotspots with cc≥10 (core decision functions kept; rule-based ones table-driven) |
+| Dependencies | Runtime only express + zod (no other runtime deps, offline-capable) |
+
+---
+
+## 7. Configuration Model (iron rule: all config from env, validated at startup, fail-fast)
+
+Priority: `FH_PROVIDERS` (JSON) > `fhcode.config.json` > single env vars `FH_MODEL_*`; security lists (deny blacklists) are unions that can only be tightened. Full reference: see Configuration Reference and Deployment Guide.
+
+---
+
+## 8. Versioning & Roadmap
+
+- v0.4.0: P0-P5 full capabilities (streaming/sandbox/MCP/Skills/plugins/cloud queue/channels/symbol index)
+- v0.5.0 (released 2026-08-17): consolidates IDE deep integration first round (review --json + inline review + context input), SWE-bench harness integration (dataset loading + mock execution + report), eval regression gate, O6 inbound signature verification & security hardening
+- Planned v0.5.0-c/d: containerized SWE execution + real-model benchmark; inbound channel scheduling (see planning doc)
+
+---
+
+*This manual is updated with each release; capabilities are authoritative in the source code and `fhcode --help`.*