feihong-code 7.2.0 → 7.6.0

package/docs//346/212/200/346/234/257/350/257/264/346/230/216/344/271/246.md

@@ -1,216 +1,307 @@
-# 飞虹 Code（fhcode）技术说明书
+# 飞虹 Code（fhcode）技术设计说明书
 
-**版本**：v0.5.0-b
-**日期**：2026-08-16
-**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（Muse Code 参照复刻）
+**版本**：v7.6.0
+**日期**：2026-08-28
+**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（对标 Muse Code，自研内核）
 **署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+**配套文档**：`docs/使用说明书.md`（使用）、`docs/UPGRADE_GUIDE_7_6.md`（升级）、`README.md`（总览）
 
 ---
 
 ## 一、产品概述
 
-飞虹 Code（fhcode）是一款运行在终端/Web/IDE 三端的 AI 编程智能体，以「自然语言 → 代码闭环」为核心，支持多模型路由、企业级安全、全自动软件工程与自我迭代。零第三方运行时依赖（仅 express + zod），离线可用，可私有化部署。
+飞虹 Code（fhcode）是一款运行在 **CLI / Web / Electron 桌面 / Android APK / VS Code** 五端的 AI 编程智能体，以「自然语言 → 代码闭环」为核心，覆盖对话编程、代码补全、全自动软件工程（SWE）、团队协作与自我迭代。零第三方运行时依赖（仅 express + zod），支持离线私有化部署与企业级安全治理。
 
-**核心能力矩阵（v0.5.0）**：
+**核心能力矩阵（v7.6.0）**：
 
 | 领域 | 能力 |
 |------|------|
-| 编排 | ReAct 循环、规划器、上下文压缩、检查点续跑、成本熔断、自愈循环 |
-| 模型 | 多模型路由（成本/能力/延迟策略 + fallback + 统计择优）、OpenAI 兼容 / Ollama / Mock |
-| 工具 | 文件读写编辑、搜索、受管 shell、构建检查、测试运行、web 检索、技能加载 |
-| 自我迭代 | 经验库（强化学习式 upsert/召回）、反思器回流、自愈闭环、eval 跑分、SWE-bench 基准 |
-| 安全 | 沙箱四档、网络域名规则、hooks 确定性控制、RBAC、审计哈希链、配额熔断、脱敏、入站签名校验 |
-| 生态 | SKILL.md 技能标准、Skills 市场（agentskills.io）、MCP、插件分发、Agent teams |
-| 交付 | CLI/TUI、Web 控制台（任务面板）、VSCode 扩展、跨进程任务队列、消息渠道 |
+| 编排 | ReAct 循环、规划器（planner）、并行 orchestrator、检查点续跑、成本熔断、自愈循环、多 agent 团队协作 |
+| 模型 | 多模型路由（成本/能力/延迟策略 + fallback + 统计择优）、OpenAI 兼容 / Ollama / Mock、成本记账 |
+| 工具 | 文件读写编辑、搜索、受管 shell、构建检查、测试运行、web 检索、技能（SKILL.md）加载、MCP 服务 |
+| 代码智能 | 补全引擎（多候选 Top3 + temperature 分层）、LSP 语义诊断、代码 RAG、符号索引、类型检查、质量门禁 |
+| 软件工程 | SWE Agent（读取→规划→实现→验证→自愈重试）、SWE-bench harness（差分语义校验）、git 集成（diff/rollback/worktree） |
+| 自我迭代 | 统一经验库（self-evolve + self-improve 收敛）、反思回流、自愈闭环、eval 跑分 |
+| 语音 | voice-programming：语音/口头指令 → 编辑器/终端命令（自然语言 → 结构化动作） |
+| 安全 | 沙箱四档、网络域名规则、hooks 确定性控制、RBAC、审计哈希链、配额熔断、脱敏、入站签名校验、SBOM |
+| 生态 | SKILL.md 技能标准、技能市场（本地种子源）、插件分发、MCP、Agent teams |
+| 交付 | CLI/TUI、Web 控制台（任务面板/监控）、Electron 桌面、Android APK、VS Code 扩展、跨进程任务队列 |
 
 ---
 
-## 二、系统架构
+## 二、总体架构
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                         接入层                               │
-│  CLI (index/run/repl/TUI) · Web (server/task-queue) · IDE 扩展 │
-└──────────────────────────────┬──────────────────────────────┘
-                               │
-┌──────────────────────────────▼──────────────────────────────┐
-│                       编排层 agent/                          │
-│  Orchestrator(ReAct) · planner · repo-reader · swe-agent     │
-│  subagent(嵌套) · team(消息总线) · self-heal · experience     │
-│  quality-gate · code-writer · repo-context · symbol-index    │
-└──────────────┬───────────────────────────────┬──────────────┘
-               │                               │
-┌──────────────▼──────────────┐  ┌─────────────▼──────────────┐
-│       模型层 models/          │  │       工具层 tools/          │
-│  ModelRouter(策略+统计)      │  │  file/search/shell/verify   │
-│  OpenAICompatible/Ollama/Mock│  │  web(MCP) / skills(load)    │
-│  sandbox(四档+网络规则)      │  │  tool.registry(zod+守卫)    │
-└──────────────┬──────────────┘  └─────────────┬──────────────┘
-               │                               │
-┌──────────────▼───────────────────────────────▼──────────────┐
-│            安全层 enterprise/ + runtime/hooks               │
-│  tenant(多租户) · policy(RBAC) · audit(哈希链) · quota       │
-│  guard(守卫) · hooks(PreToolUse/PostEdit) · channels(渠道)  │
-└──────────────────────────────┬──────────────────────────────┘
-                               │
-┌──────────────────────────────▼──────────────────────────────┐
-│          基础设施 shared/ + runtime/                         │
-│  config(env 优先) · i18n(中英) · logger(脱敏JSON) · errors   │
-│  event-log(JSONL) · session-persist(检查点) · git · worktree │
-└─────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────┐
+│                          接入层 delivery                           │
+│   CLI(index/run/repl/tui) · Web(server/task-queue) · Electron     │
+│   Android(Capacitor H5) · VS Code 扩展 · 语音(voice-programming)   │
+└───────────────────────────────┬──────────────────────────────────┘
+                                 │
+┌───────────────────────────────▼──────────────────────────────────┐
+│                       编排层 agent/                               │
+│   Orchestrator(ReAct) · parallel-orchestrator · planner           │
+│   repo-reader · swe-agent · swe-planner · swe-verifier            │
+│   subagent(嵌套) · custom-agent · solo-agent · event-driven       │
+│   team / multi-agent / team-collaboration(协作可视化)              │
+│   self-heal · self-correction · quality-gate · code-writer        │
+│   completion-engine · code-rag · symbol-index · repo-context      │
+│   experience(统一经验库) · self-improver · layered-memory          │
+└───────────────────────────────┬──────────────────────────────────┘
+                                 │
+┌───────────────────────────────▼──────────────────────────────────┐
+│                        工具层 tools/                              │
+│   文件读写编辑 · 受管 shell(sandbox) · 构建检查 · 测试运行          │
+│   web 检索 · 技能加载 · MCP · 代码审查 · 类型检查                  │
+└───────────────────────────────┬──────────────────────────────────┘
+                                 │
+┌───────────────────────────────▼──────────────────────────────────┐
+│                        模型层 models/                             │
+│   model-router(成本/能力/延迟策略) · provider 适配 · cost 记账      │
+│   OpenAI 兼容 / Ollama / Mock                                    │
+└───────────────────────────────┬──────────────────────────────────┘
+                                 │
+┌───────────────────────────────▼──────────────────────────────────┐
+│       安全/治理/支撑层  shared · runtime · enterprise · harness   │
+│   沙箱四档 · 网络规则 · hooks · RBAC · 审计链 · 配额熔断 · 脱敏     │
+│   会话持久化 · 事件日志 · 配置中心 · 错误码 · SWE harness          │
+└──────────────────────────────────────────────────────────────────┘
 ```
 
-**模块目录**（`src/`）：
-
-| 目录 | 职责 |
-|------|------|
-| `cli/` | 参数解析、命令分发、运行装配、REPL/TUI、版本 |
-| `agent/` | 编排器、规划器、SWE、子代理、团队、自愈、经验、符号索引、仓库上下文 |
-| `models/` | 模型路由、供应商（OpenAI 兼容/Ollama/Mock）、成本估算、DTO 校验 |
-| `tools/` | 工具系统：文件/搜索/shell/验证/web/MCP/技能加载/沙箱 |
-| `enterprise/` | 多租户、RBAC 策略、审计链、配额、守卫 |
-| `runtime/` | 事件日志、会话持久化、git 辅助、worktree、hooks |
-| `shared/` | 配置、i18n、日志（脱敏）、错误层级、类型 |
-| `skills/` | 技能标准（SKILL.md 加载）、技能市场（agentskills.io）、/plan /grill /goal |
-| `plugins/` | 插件分发（plugin.json 打包 skills+hooks+MCP） |
-| `web/` | Web 控制台、任务队列、消息渠道、入站签名校验 |
+**分层职责**：
+- **接入层**：把 CLI 参数、HTTP 请求、IDE 事件、语音输入统一归一化为「任务目标 + 上下文」，经 `executeTask / runSwe / runTeam` 等入口进入编排层。
+- **编排层**：核心大脑。`orchestrator` 跑 ReAct 循环（思考→工具→观察），`swe-agent` 跑「读取仓库→规划→实现→验证→自愈重试」的软件工程闭环，`team` 支持多 agent 消息总线协作。
+- **工具层**：把文件/shell/网络/搜索能力封装为统一 Tool 接口，全部经过 `sandbox`（权限/网络/白名单）拦截。
+- **模型层**：多供应商路由，按成本/能力/延迟策略选模型，失败自动 fallback，全程成本记账。
+- **支撑层**：安全治理（RBAC/审计/配额）、运行时（会话/事件日志/持久化）、评测（SWE harness）。
 
 ---
 
-## 三、核心模块详解
+## 三、模块设计
 
-### 3.1 编排器（agent/orchestrator.ts）
+### 3.1 编排核心（src/agent/）
 
-ReAct 主循环 `run(goal, resume?)`，单次迭代：
-1. `router.chat()` 调用模型（带能力标签路由）
-2. 无工具调用 → 任务完成；有 → `executeToolRound()` 执行工具并回填 tool 消息
-3. 错误检测：`roundErrors > 0` → `handleRecovery()`（分类 → 注入反思 → 重试，上限 `maxRetryErrors`）
-4. 上下文压缩：`shouldCompact()` 触发时保留 system 指令（H4 修复）
-5. 检查点落盘（`persist` 回调）+ 事件流（`onEvent`，P0-1 流式输出）
+| 模块 | 职责 |
+|------|------|
+| `orchestrator.ts` | ReAct 主循环：规划、工具调用、观察整合、上下文压缩、检查点续跑、成本熔断 |
+| `planner.ts` | 任务规划器：把目标拆解为可执行步骤 |
+| `parallel-orchestrator.ts` | 并行任务编排（含默认 Mock 实现） |
+| `repo-reader.ts` | 仓库预读：结构、入口、依赖、配置提取 |
+| `swe-agent.ts` | 全自动软件工程：读取仓库→规划→实现+验证+自愈重试→报告 |
+| `swe-planner.ts` | SWE 子任务规划与拆解 |
+| `swe-verifier.ts` | SWE 结果验证（测试/构建/静态检查） |
+| `subagent.ts` / `custom-agent.ts` / `solo-agent.ts` / `event-driven-agent.ts` | 不同执行模式的 agent |
+| `team.ts` / `multi-agent.ts` / `team-collaboration.ts` | 多 agent 协作：消息总线、任务分配、协作可视化 |
+| `self-heal.ts` / `self-correction.ts` | 失败自愈：错误识别→修复→重试；自我纠错 |
+| `quality-gate.ts` | 产出质量门禁（构建/测试/类型检查通过才放行） |
+| `code-writer.ts` / `change-manager.ts` | 代码生成与变更管理（diff/回滚） |
+| `completion-engine.ts` | 补全引擎：多候选 Top3、temperature 分层、跨文件上下文 |
+| `code-rag.ts` / `symbol-index.ts` / `repo-context.ts` | 代码检索：RAG、符号索引、仓库上下文 |
+| `experience.ts` | **统一经验库**：稳定 id + upsert 合并 + 加权检索，供 orchestrator 注入 |
+| `self-improver.ts` | 新一代自我改进：任务反思→经验回流 |
+| `layered-memory.ts` / `context-compactor.ts` / `context-budget.ts` | 记忆分层与上下文管理 |
+| `type-checker.ts` / `lint.ts` / `code-review.ts` | 静态质量校验 |
+
+### 3.2 SWE 评测（src/harness/）
+
+SWE-bench 语义评测管道，四段式：
 
-**事件流（P0-1）**：`OrchestratorEvent` 判别联合——model.response / tool.call / tool.result / self-heal / context.compact / session.end，CLI 流式渲染、TUI header 驱动、eval 计数复用同一事件源。
+```
+loader.ts     → 加载任务（problem_statement / FAIL_TO_PASS / PASS_TO_PASS）
+executor.ts   → 在沙箱中 checkout 仓库并执行测试命令
+verifier.ts   → 三段式差分校验：
+                 ① beforeCommand：修复前确认 FAIL_TO_PASS 原本失败（防假阳性）
+                 ② 修复后 FAIL_TO_PASS 全部通过（问题确实被修复）
+                 ③ PASS_TO_PASS 回归通过（未修坏既有功能）
+reporter.ts   → 输出可复现的跑分报告（markdown/json）
+```
 
-**成本熔断（M4）**：`cost >= maxCostUsd` 立即中止并提示 `resume` 续跑；`maxCostUsd=0` 不限。
+- `types.ts` 定义任务与结果类型；`harness.ts` 编排管道；`index.ts` 导出入口。
+- `verifier.ts` 对测试 id 做 shell 安全转义（`quoteTestId`），受管命令白名单 `sanitizeManagedCommand` 只放行 `npm/pnpm/yarn/bun`，杜绝注入。
+- 跑分现状：自建任务集真实模型跑分 5/5 全过；mock 管道 1/1 通过（`bench/run-2026-08-28-mock.md`，诚实标注口径）。官方 SWE-bench（Python/pytest）受限于 HF 网络不可达与 Docker 环境，见 `docs/SWE_BENCH_REPORT.md`。
 
-**经验回流（M6）**：会话结束 `extractExperience()`（表驱动 EXTRACTORS）→ `upsertExperience`（稳定 id 合并、sessionCount 累积、成功率加权平均）；自愈成功额外固化 `extractFixPattern`。
+### 3.3 语音编程（src/voice/voice-programming.ts）
 
-### 3.2 模型路由（models/model-router.ts）
+把自然语言口头指令转译为编辑器/终端动作：
 
-- 策略：`cost`（按 costPer1k）/ `latency`（本地优先）/ `capability`（标签加权）
-- 择优：`rank(tags)` 能力过滤 + 历史成功率加权（≥3 次调用，最多 +0.3）
-- fallback：按序尝试，失败记 `p.model`（修复：不产生空模型名条目），全部失败抛最后错误
-- 统计：`updateStat()` 自动落盘（`statsHomeDir`，P5 闭环修复），`model-stats` 命令可查
-- 子任务分工（P1-1）：`tags: ['code-gen','cheap']` 让低成本模型承担子任务
+- 命令类型：`new_file`、`open_file`、`edit`、`copy`、`paste`、`cut`、`close_file`、`replace`、`uncomment`、`stop_code`、`toggle_terminal`、`toggle_sidebar`、`toggle_fullscreen`、`explain_code`、`switch_file` 等。
+- 规则匹配：正则 + 置信度排序；等置信度时**数组顺序即优先级**（语义更具体的规则前置，避免「打开终端」被 `open_file` 抢占）。
+- 随 v7.6.0 补齐死类型规则（copy/paste/cut/close_file/replace/uncomment）、修复 `new_file`「创建一个叫 X 的文件」识别、`explain_code` 放宽「解释」，并新增 7 项单元测试。
 
-### 3.3 工具系统（tools/）
+### 3.4 自我迭代（src/self-evolve/ + src/agent/experience.ts）
 
-- `ToolRegistry`：注册/查找/执行，zod 校验入参，错误归一为 `ToolResult`
-- 执行链顺序（纵深防御）：**沙箱 → PreToolUse hook → RBAC 守卫 → 工具 → PostToolUse/PostEdit hook**
-- 沙箱四档（P0-2/P5-4）：`read-only` / `workspace-write` / `danger-full-access` / `container`（Docker 挂载工作区执行 shell）
-- 网络域名规则：`FH_NETWORK_ALLOW/DENY` 对 run_shell 命令 URL 与 web 工具 URL 均生效
-- hooks（P2-1）：`FH_HOOKS` JSON 数组，PreToolUse 非零退出拦截、PostEdit 编辑后触发，占位符 `{cwd}{tool}{path}{runId}{ok}`
+**v7.6.0 关键设计：双系统收敛为单一经验库。**
 
-### 3.4 SWE Agent（agent/swe-agent.ts + swe-planner + swe-verifier）
+| 系统 | 职责 | 数据 |
+|------|------|------|
+| self-evolve（旧式，运维视图） | 失败记录、技能沉淀、每日复盘报告 | `~/.feihong-code/self-evolve/{failures,skills-index,history}.json` |
+| self-improve（新式，学习闭环） | 任务反思 → 经验回流 → orchestrator 检索注入 | `~/.feihong-code/experiences/experiences.jsonl` |
 
-仓库读取（`repo-reader`，限流/忽略规则）→ 任务拆解（`planSweTask`）→ 逐任务「实现（runSubTask）+ 验证（构建/测试）+ 自愈重试」→ 报告。支持 `--plan-only` / `--verify-only` / `--max-tasks` / `--max-retries`。
+**收敛机制**（`src/self-evolve/manager.js`）：
+- `recordFailure` → 写入 `error-pattern` 经验（含错误类型/任务描述/规避建议）
+- `markResolved` → 写入 `success-pattern` 经验（含解决方案）
+- `createSkill` → 写入 `success-pattern` 经验（含技能名/触发词/方案）
+- 经验 id 由 `shortHash(type:key)`（djb2 变体，base36）生成，与 `experience.ts` 算法一致，保证跨系统 id 对齐；upsert 语义（同 id 合并 sessionCount、加权成功率、标签合并、刷新 lastUsedAt）防膨胀。
 
-**子代理（P3-4）**：`runSubAgent` 深度控制（默认 3 层），目标可拆解且未达上限时递归派生子代理（子目录隔离），逐层摘要回传（`summarizeSubTaskAnswer`，P2-2）。
+**检索**（`experience.ts`）：`retrieveRelevantExperiences` 加权打分（标签重叠×3 + 成功率×2 + 子串 +2 + token×0.5 + 新鲜度衰减），`generateExperiencePrompt` 分组注入（成功模式优先/失败模式警示）。
 
-### 3.5 Agent teams（agent/team.ts，P4-2）
+### 3.5 模型路由（src/models/）
 
-- `TeamBus`：消息总线（send/receive/broadcast 定向与广播）
-- `TaskBoard`：共享任务清单（claim 原子认领防重复，状态+owner 双校验）
-- `runTeam`：多 agent 并发认领执行，`ok=false` 记 failed（修复），产出团队报告
+- `model-router.ts`：按策略（cost 成本 / capability 能力 / latency 延迟）选模型；失败 fallback；按标签过滤（code-gen/cheap/local/long-context）。
+- `cost.ts`：每 1k token 成本记账，支持单任务预算熔断（`FH_BUDGET_USD`）。
+- provider 支持：OpenAI 兼容（DeepSeek/通义 Qwen 等）、Ollama 本地、Mock（离线演示）。
 
-### 3.6 企业安全（enterprise/）
+### 3.6 工具层与沙箱（src/tools/）
 
-| 模块 | 机制 |
-|------|------|
-| tenant | 租户隔离目录（`tenants/<id>/{sessions,audit,goals}`） |
-| policy | RBAC：角色-工具矩阵（viewer/developer/operator/admin）+ denyShell 黑名单 + denyPaths 敏感路径，deny 优先 |
-| audit | 哈希链（SHA-256，seq/prevHash 衔接），跨进程文件锁 + 指数退避，写入前脱敏，`audit verify` 校验 |
-| quota | 租户日成本预算（`FH_TENANT_BUDGET_USD`），启动前 fail-fast 实时复核（M14 修复） |
-| guard | 「策略→审批→审计」工具前置钩子，审计失败=拒绝 |
+统一 `Tool` 接口（`tool.interface.ts`）+ 注册表（`tool.registry.ts`）：
 
-### 3.7 技能与市场（skills/）
+- 文件：读写/编辑（`safe-path.ts` 路径安全校验）
+- Shell：受管执行，`sandbox.ts` 四档模式拦截
+- 网络：域名规则（`FH_NETWORK_DENY/ALLOW`）
+- 搜索/检索：web 检索、代码 RAG
 
-- **SKILL.md 标准（P1-2）**：frontmatter（name/description）+ 正文；渐进式披露——索引（≤8KB）常驻 system prompt，正文由 `load_skill` 工具按需加载（Tier-2）
-- 发现位置：仓库 `.agents/skills` / `.claude/skills` 逐级回溯 + 打包 `skills/` + 用户级 `~/.feihong-code/skills` + 插件技能目录
-- **技能市场（P6）**：agentskills.io discovery 规范（`/.well-known/agent-skills/index.json`），`skill-market search/install/list`；RFC 3986 URL 解析、sha256 digest 校验、tar.gz 归档解包（零依赖手写，路径穿越防护）
-- **插件（P3-3）**：`plugin.json` 打包 skills+hooks+MCP，用户级/项目级双级发现，`plugin install`（本地目录/git clone）
+**沙箱四档**（Codex 对齐）：
 
-### 3.8 Web 与云执行（web/）
+| 模式 | 写限制 | Shell | 网络 |
+|------|--------|-------|------|
+| `read-only` | 禁止 | 只读勘察 | 按规则 |
+| `workspace-write`（默认） | 仅工作区 | 白名单 + 审批 | 按规则 |
+| `danger-full-access` | 放开 | 白名单（危险命令黑名单仍生效） | 按规则 |
+| `container` | Docker 隔离 | `--network none` + 内存/pids 上限 + `--cap-drop ALL` + `no-new-privileges` | 断网 |
 
-| 端点 | 说明 |
-|------|------|
-| `GET /api/health` | 公开健康检查（免鉴权） |
-| `POST/GET /api/tasks`、`GET /api/tasks/:id` | 任务队列（Bearer 鉴权，P4-1） |
-| `POST/GET /api/webhook` | webhook 调度入口注册/查询（P5-2） |
-| `/api/...` 其它 | 需 `FH_WEB_TOKEN` Bearer（fail-closed，计时安全比较） |
+### 3.7 安全与治理（src/enterprise/ + src/shared/ + src/runtime/）
 
-**任务队列（P4-1/P6-4）**：状态机 queued→running→done|failed；并发上限（`FH_TASK_CONCURRENCY`）；跨进程持久化（`FH_TASK_PERSIST_DIR`，每任务一文件原子写，重启恢复：queued 重新入队、running 僵尸标记 failed）；webhook 状态回调（携带状态快照，修复 queued 丢失时序缺陷）。
+- **RBAC**：`whoami` / `policy` 命令，角色与权限策略
+- **审计**：`audit` 命令，审计哈希链（篡改可检测），`audit --verify` 校验
+- **多租户**：`tenants` 命令
+- **hooks**：确定性控制（`FH_HOOKS`），事前/事后回调
+- **脱敏**：日志与输出的敏感信息脱敏
+- **配额熔断**：成本/时长/轮次限额
+- **入站签名校验**：Web 控制台请求验签
+- **SBOM**：`npm run security`（npm audit + CycloneDX SBOM + osv-scanner 可选）
+- **错误码**：统一错误分类（`docs/error-codes.md`）
 
-**消息渠道（P5-6/O6）**：Telegram（`FH_CHANNEL_TELEGRAM_BOT_TOKEN`+`CHAT_ID`）与企业微信（`FH_CHANNEL_WECOM_KEY` 多 key）出站推送；出站白名单 `FH_CHANNEL_ALLOW`；入站签名校验工具 `verifyHmacSignature`（HMAC-SHA256 计时安全）/ `verifyWecomSignature`（企微 SHA1 排序）。
+---
 
-### 3.9 IDE 扩展（vscode-extension/）
+## 四、数据设计
 
-薄壳设计（逻辑全在 CLI）：`fhcode.run`（选区上下文注入 `<selection>`）、`fhcode.review`（`review --json` → 编辑器内联诊断 DiagnosticCollection + CodeAction 建议）、`fhcode.diff`（原生 diff 编辑器 HEAD↔工作区，`fhcode-head` scheme）、`fhcode.output`；配置 `binaryPath` / `offline` / `reviewOnSave`。
+### 4.1 数据目录（`~/.feihong-code/`，可用 `FH_HOME` 覆盖）
 
----
+```
+~/.feihong-code/
+├── config/                 # 配置
+├── sessions/               # 会话持久化 + 事件日志（FH_LOG_DIR）
+├── self-evolve/            # 失败记录/技能索引/历史/每日复盘报告（运维视图）
+├── skills/                 # 用户技能（SKILL.md）
+├── experiences/
+│   └── experiences.jsonl   # ★ 统一经验库（self-evolve + self-improve 共用）
+├── bench/                  # SWE 跑分缓存与报告
+└── ...
+```
 
-## 四、协议与规范
+### 4.2 统一经验库 schema（experiences.jsonl，每行一条）
+
+```jsonc
+{
+  "id": "exp-<base36 shortHash(type:key)>",   // 稳定 id，跨 run 合并
+  "type": "success-pattern",                   // success-pattern | error-pattern | path-planning | tool-efficiency | performance-tip
+  "key": "fix:compile-error",
+  "title": "自愈修复经验: compile-error",
+  "content": "…具体方案与建议…",
+  "tags": ["compile-error", "self-heal", "fix", "success"],
+  "metadata": {
+    "sessionCount": 2,          // 出现次数（同 id 累加）
+    "successRate": 0.85,        // 加权成功率
+    "createdAt": "ISO 时间",
+    "lastUsedAt": "ISO 时间"
+  }
+}
+```
 
-| 协议 | 说明 |
-|------|------|
-| 工具调用契约 | OpenAI 风格 `tool_calls`（name/arguments JSON），结果以 role=tool 回填（toolCallId 对应） |
-| MCP | stdio 传输（NDJSON JSON-RPC 2.0）：initialize → notifications/initialized → tools/list → tools/call；工具以 `<server>_<tool>` 前缀注册 |
-| SKILL.md | open agent skills 兼容（frontmatter name/description + 正文，渐进式披露） |
-| agentskills.io | discovery index 0.2.0：`$schema` 校验、skill-md/archive、digest `sha256:<hex>` |
-| webhook | `POST {url}` JSON：`{event:'task.status', task:{...}, ts}`（状态快照） |
-| 入站签名 | HMAC-SHA256（`sha256=<hex>` 头）或企微 SHA1 排序 |
-| 检查点 | `<runId>.session.json`（完整对话/迭代/成本/touchedFiles），resume 续跑 |
+### 4.3 会话与事件
+
+- 每次运行生成 `runId`（UUID），`EventLog` 记录全量事件，`SessionStore` 持久化会话；支持 `sessions` 列出、`resume` 续跑、`diff` 查看变更、`rollback` 回滚。
 
 ---
 
-## 五、安全设计
+## 五、接口设计
+
+### 5.1 CLI 命令（`fhcode <command>`）
 
-1. **纵深防御**：沙箱（技术边界）→ hooks（确定性控制）→ RBAC 策略（权限）→ 审计（留痕）→ 配额（成本）
-2. **沙箱**：四档 + 网络域名规则（deny 全模式生效、allow 未命中即拦截）；`container` 档 Docker 隔离
-3. **命令防护**：run_shell 注入元字符拦截（`[;&|`$(){}<>!]` 等）；受管命令（run_tests/build_check）仅允许包管理器脚本
-4. **路径安全**：`safeJoin`（词法 + realpath 符号链接校验）；策略 denyPaths 敏感路径黑名单（.env/.git/config/密钥等）
-5. **审计**：哈希链不可篡改（verifyAudit 检 seq/prevHash/hash 自洽）；写入前脱敏（SECRET_RE/Bearer/JWT/sk-）
-6. **日志脱敏**：敏感 key 整值遮蔽 + 值形态（sk-/JWT/长令牌）遮蔽
-7. **Web 鉴权**：Bearer token 计时安全比较（timingSafeEqual），fail-closed；body 限制 1MB
-8. **入站安全**：webhook 签名校验（HMAC/企微），渠道白名单
-9. **技能安全**：市场技能 digest 校验防投毒，tar.gz 路径穿越防护，SKILL.md 强制 name frontmatter
+| 命令 | 说明 |
+|------|------|
+| `fhcode <goal>` | 直接执行自然语言任务（默认入口） |
+| `sessions` / `resume <id>` / `diff <id>` / `rollback <id>` | 会话管理：列出/续跑/变更/回滚 |
+| `whoami` / `policy` | RBAC 身份与策略 |
+| `audit [--verify]` / `tenants` | 审计（哈希链校验）/ 多租户 |
+| `doctor` | 环境自检 |
+| `tui` | 多面板终端 UI |
+| `serve [port]` | 启动 Web 控制台 |
+| `plugin` / `skill-market` / `skill-new` | 插件与技能管理 |
+| `review <path>` | 代码审查 |
+| `team <goal>` | 多 agent 团队协作 |
+| `code-write <goal>` / `quality-gate <path>` | 代码生成与质量门禁 |
+| `self-improve` / `self-evolve <action>` | 自我迭代（统一经验库） |
+| `model-stats` / `experiences` | 模型用量统计 / 经验库浏览 |
+| `harness` / `swe <goal>` | SWE 评测与软件工程执行 |
+| `/plan` `/grill` `/self-heal` | 内置技能（规划/拷问/自愈） |
+
+### 5.2 HTTP API（`fhcode serve`）
+
+- `/api/health`：健康检查（返回版本号）
+- `/api/task` 等任务面板接口：Web 控制台任务下发与状态查询
+- `/api/lint`：补全接受后轻量语法校验
+- 入站请求签名校验；CORS/权限控制
+
+### 5.3 LSP / 编辑器协议
+
+- Monaco 语义诊断：编辑时 LSP 诊断波浪线 + hover 详情
+- VS Code 扩展：补全、跨文件上下文、accept 后 lint
+
+### 5.4 语音输入
+
+- `voice-programming`：语音识别文本 → 命令规则匹配 → 结构化动作（open/edit/toggle/explain 等）
 
 ---
 
-## 六、性能与质量基线（v0.5.0-b 实测）
+## 六、部署形态
 
-| 指标 | 值 |
-|------|----|
-| 单元测试 | 164/164 全绿（16 模块 + 10 特性域） |
-| 里程碑断言 | M4 41 · M6 29 · M7 12 · M8 27 · M9 25 = 134 全绿 |
-| eval 跑分 | 10/10（场景 5 + 验收 5，真实产物验证，整体通过率 100%） |
-| SWE-bench 加载器 | HF datasets-server / 镜像 / 缓存，mock 执行 + 报告 |
-| 复杂度 | 676 函数，cc≥10 热点 52 个（核心决策函数保持，规则类已表驱动化） |
-| 依赖 | 运行时仅 express + zod（零其它运行时依赖，离线可用） |
+| 形态 | 入口 | 说明 |
+|------|------|------|
+| CLI / npm | `npm i -g feihong-code` → `fhcode` | 全功能，离线可用 |
+| 源码构建 | `npm install && npm run build` | `dist/` 产物，`node dist/cli/index.js` |
+| Web 控制台 | `fhcode serve` | 浏览器访问，任务面板 |
+| Electron 桌面 | `npm run electron:build` | Windows 桌面，系统托盘、截图、语音 |
+| Android APK | Capacitor 构建（versionCode 8） | 移动端 H5，配套桌面端 |
+| Docker / 私有化 | 镜像部署 + `FH_HOME` 挂载 | 企业内网隔离 |
 
 ---
 
-## 七、配置模型（铁律：一切配置来自环境变量，启动时校验，fail-fast）
+## 七、工程与质量
+
+- **构建**：`tsc` + `scripts/copy-web.cjs`（复制 Web 静态资源与 self-evolve CLI 到 dist）
+- **测试**：`npm test`（tsx --test，tests/unit/*.test.ts），**v7.6.0 全量 243/243 通过**（含 harness 11、voice 7、symbol-index 等）
+- **类型**：`npm run typecheck`（tsc --noEmit 零错误）
+- **验证门禁**：`npm run verify`（typecheck + build + verify:m4/m6/m7/m8/m9）
+- **安全**：`npm run security`（npm audit + SBOM）
+- **跑分**：`npm run eval`、`fhcode harness`
+- **冒烟**：`scripts/_smoke-full.mjs`（v7.6.0 版本断言）
 
-优先级：`FH_PROVIDERS`（JSON）> `fhcode.config.json` > 单环境变量 `FH_MODEL_*`；安全类（deny 黑名单）为并集只能加严。完整清单见《配置参考》《部署说明书》。
+**依赖原则**：运行时仅 express + zod，其余为标准库；所有第三方依赖仅用于开发/构建，保障离线可交付与企业私有化部署。
 
 ---
 
-## 八、版本与演进
+## 八、版本历史与演进
 
-- v0.4.0：P0-P5 全能力（流式/沙箱/MCP/Skills/插件/云队列/渠道/语义索引）
-- v0.5.0（2026-08-17 正式发布）：整合 IDE 深度集成首轮（review --json + 内联评审 + 上下文入参）、SWE-bench 基准接入（数据集加载 + mock 执行 + 报告）、eval 回归门禁、O6 入站签名校验与安全前置
-- 规划 v0.5.0-c/d：容器化 SWE 执行 + 真实模型跑分、消息渠道入站调度（详见《规划_v0.5.0.md》）
+| 版本 | 日期 | 关键里程碑 |
+|------|------|-----------|
+| v0.4.0 → v0.6.1 | 2026-08-10~24 | 对话流、多模型路由、RBAC、SWE agent、Web 控制台 |
+| v7.0.0 | 2026-08-24 | 产品成熟标志：Electron 桌面、对话流重构、记忆系统 |
+| v7.2.0 | 2026-08-25 | 硬伤清零：SWE harness、LSP、Docker 沙箱、合规材料 |
+| v7.5.0 | 2026-08-27 | SWE-bench 官方 harness、容器沙箱加固、SBOM、合规售前 |
+| **v7.6.0** | **2026-08-28** | **verifier 差分语义、voice 加固、双系统经验库收敛、仓库卫生、全库版本对齐** |
 
 ---
 
-*本说明书随版本持续更新，能力以源码与 `fhcode --help` 为准。*
+*晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹*
+*2026-08-28 · 技术设计说明书 v7.6.0*

package/docs//351/203/250/347/275/262/350/257/264/346/230/216/344/271/246.md

@@ -1,8 +1,8 @@
 # 飞虹 Code（fhcode）部署说明书
 
-**版本**：v0.5.0-b
+**版本**：v7.6.0
 **日期**：2026-08-16
-**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（Muse Code 参照复刻）
+**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（对标 Muse Code，自研内核）
 **署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
 
 ---