feihong-code 8.0.0 → 8.0.2

package/README.md

@@ -1,636 +1,656 @@
-> **English / 英文文档**：[README_EN.md](README_EN.md) · [FAQ (English)](FAQ_EN.md)
-
-<!-- Schema.org JSON-LD for GEO optimization -->
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@type": "SoftwareSourceCode",
-  "name": "飞虹 Code (fhcode)",
-  "description": "终端 AI 编程智能体，对标 Meta Muse Code / Claude Code / Cursor CLI 等国际同类产品，以自研内核实现差异化。多模型路由、企业级 RBAC/审计/多租户、全自动 SWE Agent、离线私有化。支持 DeepSeek/通义/Ollama/OpenAI 兼容网关。",
-  "url": "https://github.com/wch887292/feihong-code",
-  "license": "https://opensource.org/licenses/MIT",
-  "programmingLanguage": {
-    "@type": "ProgrammingLanguage",
-    "name": "TypeScript"
-  },
-  "operatingSystem": "Cross-platform (Windows, Linux, macOS)",
-  "softwareVersion": "7.6.0",
-  "dateCreated": "2026-08-12",
-  "datePublished": "2026-08-22",
-  "author": {
-    "@type": "Organization",
-    "name": "晋江市飞虹智科技企业管理有限公司",
-    "url": "https://www.klai.top"
-  },
-  "developer": {
-    "@type": "Organization",
-    "name": "飞扬企源研发中心",
-    "url": "https://www.klai.top"
-  },
-  "keywords": [
-    "AI Agent", "SWE Agent", "CLI", "多模型路由", "DeepSeek", "Ollama",
-    "企业级权限", "RBAC", "审计链", "多租户", "自我进化", "自愈循环",
-    "代码生成", "typescript", "nodejs", "open source"
-  ],
-  "sameAs": [
-    "https://www.npmjs.com/package/feihong-code",
-    "https://www.klai.top/opensource.html"
-  ],
-  "featureList": [
-    "核心能力里程碑 M0-M9.1 全部交付",
-    "多模型路由 (DeepSeek/通义/Ollama/OpenAI)",
-    "企业级 RBAC 权限矩阵",
-    "防篡改审计哈希链",
-    "多租户物理隔离",
-    "配额成本熔断",
-    "自我进化与自愈循环",
-    "上下文智能压缩",
-    "多子代理并行 (git worktree)",
-    "Web 管理控制台 (BETA)",
-    "全自动 SWE Agent",
-    "离线私有化部署"
-  ]
-}
-</script>
-
-# 飞虹 Code（fhcode）
-
-> **终端 AI 编程智能体** · 对标 Meta Muse Code / Claude Code / Cursor CLI · 自研内核实现差异化 · 全功能 M0→M9.1 完成 · 企业级 RBAC/审计/SWE Agent
-> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://typescriptlang.org)
-[![GitHub stars](https://img.shields.io/github/stars/wch887292/feihong-code?style=social)](https://github.com/wch887292/feihong-code/stargazers)
-[![GitHub issues](https://img.shields.io/github/issues/wch887292/feihong-code)](https://github.com/wch887292/feihong-code/issues)
-[![npm version](https://img.shields.io/npm/v/feihong-code.svg)](https://www.npmjs.com/package/feihong-code)
-[![npm downloads (monthly)](https://img.shields.io/npm/dm/feihong-code.svg)](https://www.npmjs.com/package/feihong-code)
-[![npm downloads (total)](https://img.shields.io/npm/dt/feihong-code.svg)](https://www.npmjs.com/package/feihong-code)
-[![CI Status](https://github.com/wch887292/feihong-code/actions/workflows/ci.yml/badge.svg)](https://github.com/wch887292/feihong-code/actions)
-
-**🔍 关键词**：AI Agent · 代码生成 · SWE Agent · CLI · 多模型路由 · 企业级权限 · 离线可用
-
-**📦 一键安装**：`npm install -g feihong-code` · 国内镜像：`npm install -g feihong-code --registry=https://registry.npmmirror.com`
-**🚀 5 分钟上手**：`fhcode --version` → `fhcode chat`（离线模式免 API Key 即可对话）
-
-**🌐 中英文双语界面**：`fhcode --lang zh|en` 切换 CLI 语言，或设置环境变量 `FHCODE_LANG=zh|en`（默认按系统 locale 自动检测）。Web 控制台（`fhcode serve`）同样支持中英文一键切换。
-
-
----
-
-## 🌐 品牌与官网
-
-本项目由 **晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心** 开发维护，是飞虹智 klAI 开源生态的核心组件。
-
-- 🏠 **官方网站**：[https://www.klai.top](https://www.klai.top) — 飞虹智 klAI · 泉州制造业 AI 服务商
-- 📦 **开源矩阵**：[https://www.klai.top/opensource.html](https://www.klai.top/opensource.html)
-- 🤖 **AI Agent 入口**：[https://www.klai.top/openclaw.html](https://www.klai.top/openclaw.html)
-
-
-
-## 零、For AI Agents（面向 AI 智能体）
-
-本项目专为 AI Agent 设计，提供结构化 CLI 与明确工具契约。详见 [`AGENT-GUIDE.md`](./AGENT-GUIDE.md) 与 [`tool-schema.json`](./tool-schema.json)。
-
-**快速评估项目是否适合你的 Agent**：
-```bash
-fhcode --help                    # 查看所有命令
-fhcode "你的目标"                # 单任务执行
-fhcode --parallel "目标A 并且 目标B"  # 并行子任务
-fhcode swe "修复仓库 X 的问题 Y"  # 全自动软件工程
-```
-
-**推荐配置（生产环境）**：
-```bash
-export FH_MODEL_NAME=qwen3:8b
-export FH_MODEL_TYPE=ollama
-export FH_MODEL_BASE_URL=http://localhost:11434
-export FH_ENTERPRISE=true
-export FH_TENANT=my-org
-export FH_USER=agent-sa
-export FH_ROLE=developer
-```
-
----
-
-## 一、产品定位
-
-**飞虹 Code（fhcode）** 是一款运行在终端的 **AI 编程智能体**，以 Meta Muse Code、Claude Code、Cursor CLI 等国际同类产品为**对标参照系**，独立自研内核：用自然语言描述需求，智能体自主完成**规划 → 读写代码 → 运行验证 → 汇报结果**的闭环。
-
-> **关于"对标"的措辞基线**：本项目对外统一使用 **「对标 / 对比 / 参考 / 差异化」** 四种表述 —— **对标**指以同类产品作为行业参照系来校准能力水位；**参考**指借鉴已被验证的交互范式与产品形态；**差异化**指本项目自研实现、与参照对象形成区隔的独有能力。本项目是**独立设计与实现的原创工程**，非分叉、非移植、非克隆，代码库不包含任何第三方闭源或受限制代码。
-
-**🎯 适用场景**：
-- 代码生成与修改（函数、模块、完整功能）
-- 批量重构与代码审查
-- 离线脚本化任务与自动化工作流
-- 企业内多团队共享的智能体底座
-- 全自动软件工程（SWE Agent）：读取仓库 → 拆解任务 → 实现 + 测试验证 → 报告
-
-- 不绑定任何单一大模型厂商，通过**多模型路由层**在 DeepSeek / 通义 / Ollama（本地）/ 任意 OpenAI 兼容网关之间按需调度。
-- 所有行为以 **append-only 事件日志**为单一可信源，完全可审计、可恢复。
-- 遵循**安全合规底线**：文件沙箱、shell 白名单、密钥脱敏、危险操作审批。
-- **M2 多子代理并行**：用 `git worktree` 物理隔离多个子代理工作区，并发推进互不干扰。
-
----
-
-### 🆚 对标对比矩阵
-
-> 下表为**功能性对标参考**，用于说明能力覆盖水位差异，非性能跑分；信息依据各产品公开文档与本项目实测整理，供选型时对照参考。
-
-| 能力 | **fhcode（飞虹 Code）** | Claude Code | Cursor CLI | Aider | OpenCode |
-|---|---|---|---|---|---|
-| 终端原生 CLI | ✅ | ✅ | ⚠️（编辑器内） | ✅ | ✅ |
-| 多模型路由（DeepSeek/通义/Ollama/OpenAI） | ✅ | ❌（仅 Anthropic） | ⚠️ | ⚠️ | ✅ |
-| 离线 / 私有化（数据不出内网） | ✅（Ollama 本地） | ❌ | ❌ | ⚠️ | ✅ |
-| 企业级 RBAC / 审计链 | ✅ | ❌ | ❌ | ❌ | ❌ |
-| 全自动 SWE Agent（M0→M9.1） | ✅ | ✅ | ⚠️ | ✅ | ⚠️ |
-| 多子代理并行（M2） | ✅ | ✅ | ❌ | ❌ | ❌ |
-| 自我进化（M6） | ✅ | ❌ | ❌ | ❌ | ❌ |
-| 开源可自托管（MIT） | ✅ | ❌ | ❌ | ✅ Apache-2.0 | ✅ MIT |
-
-> 最适合：**数据不出内网**、需要**企业权限审计**、希望**混合调度多家大模型**的团队与个人开发者。
-
-### 🎯 差异化能力（自研内核）
-
-上表说明"能力有无"，下表说明"同样的能力，fhcode 做得有何不同" —— 这部分是本项目**独立设计与实现**的结果，也是与对标对象形成区隔的核心。
-
-| 差异化维度 | fhcode 的实现 | 同类产品普遍现状 |
-|---|---|---|
-| 模型调度 | 统一网关抽象层，DeepSeek / 通义 / Ollama / 任意 OpenAI 兼容端点按成本与能力动态路由 | 多数绑定单一模型厂商，切换成本高 |
-| 离线私有化 | Ollama 本地推理 + 全链路断网可用，代码与数据不出内网 | 多数强依赖云端 API，无法满足内网合规 |
-| 企业治理 | RBAC 权限矩阵 + 防篡改审计哈希链 + 多租户物理隔离 + 配额成本熔断，四件套开箱即用 | 多为个人向工具，缺权限与审计体系 |
-| 自我进化（M6） | 经验库沉淀 + 自愈循环，失败模式跨会话复用，越用越准 | 基本无对应机制 |
-| 并行隔离（M2） | `git worktree` 为每个子代理建立物理隔离工作区，并发推进零冲突 | 部分支持，隔离强度与冲突处理参差 |
-| 可恢复性（M3） | append-only 事件日志为单一可信源，会话可断点恢复、可完整回放 | 会话状态多不可恢复，中断即重来 |
-| 授权与自托管 | MIT 许可，源码开放，支持完全私有化部署与二次开发 | 主流产品为闭源商业服务 |
-
-> **一句话区分**：对标产品解决"个人开发者如何更快写代码"，fhcode 额外解决"**团队如何在合规边界内、可审计地、用可控成本把 AI 编程落地到生产**"。
-
-### 📸 产品截图
-
-| CLI 终端 | Web 控制台 | 功能对比 |
-|---------|-----------|---------|
-| ![CLI Demo](docs/screenshots/cli-demo.png) | ![Web Console](docs/screenshots/web-console.png) | ![Feature Comparison](docs/screenshots/feature-comparison.png) |
-
-## 二、核心特性
-
-### 🔥 主要亮点
-- ✅ **自然语言 → 代码闭环**：描述需求，自动调用工具完成改码与验证
-- ✅ **多模型路由**：支持 DeepSeek / 通义 / Ollama / OpenAI 兼容网关，自动选优+fallback
-- ✅ **离线可用**：无需 API Key 即可演示完整闭环（内置 Mock 驱动）
-- ✅ **企业级安全**：RBAC 权限矩阵、防篡改审计链、多租户隔离、配额熔断
-- ✅ **全自动 SWE Agent**：读取仓库 → 任务拆解 → 实现 + 测试验证 → 自愈重试 → 报告
-
-### 🛠️ 功能矩阵
-| 里程碑 | 能力 | 状态 |
-|--------|------|------|
-| **M0-M1** | CLI 基础、模型路由、文件/Shell 工具、离线闭环 | ✅ 完成 |
-| **M2** | 多子代理并行（git worktree 隔离）+ `/plan` `/grill` `/goal` 技能 | ✅ 完成 |
-| **M3** | 会话恢复、diff/rollback、交互式审批流 | ✅ 完成 |
-| **M4** | RBAC 权限、哈希链审计、多租户、配额治理、CI 三流水线 | ✅ 完成 |
-| **M5** | Web 管理控制台（BETA） | ✅ BETA |
-| **M6** | 自愈循环、上下文压缩、经验学习、模型性能追踪 | ✅ 完成 |
-| **M7** | 静态代码分析、模板化生成、AI 代码审查、仓库理解、测试生成 | ✅ 完成 |
-| **M8** | CodeWriter 六步闭环、QualityGate 质量门禁、SelfImprover 自我改进 | ✅ 完成 |
-| **M9** | 全自动软件工程 Agent（swe 命令） | ✅ 完成 |
-| **M9.1** | 真实模型接入（三级 provider 解析）、exec 纪律强化 | ✅ 完成 |
-
-### 🌟 技术亮点
-- **零依赖侵入**：仅依赖 `express` + `zod`，无框架包袱
-- **TypeScript 全量类型安全**：tsc --noEmit 零错误
-- **完整测试覆盖**：42 单元测试 + 145 集成验证断言（M4/M6/M7/M8/M9/M9-real 全离线）
-- **CI/CD 就绪**：GitHub Actions 三流水线（build/enterprise/security），零 Secrets 可跑
-- **Docker 多阶段构建**：支持容器化部署
-
-### 🎯 SWE-bench 真实跑分（v7.6.0 复测，诚实口径）
-- **测试通过率 100%（5/5）**：自建 SWE-bench 格式任务集（problem_statement + FAIL_TO_PASS，5 个自包含 JS 任务），真实模型（agnes-2.5-flash）驱动 Orchestrator 修复 + **预定义测试 `node --test` 真实断言**（测试不交给模型，防作弊）。2026-08-27 复测：5 例全过，平均迭代 2.2 次/例。（v7.2.0 首测为 80%/4-5，本次模型稳定性提升至全过。）
-- **harness 闭环 2/2 = 100%**：loader→executor→verifier→reporter 全链路真实可执行。
-- **官方 SWE-bench Verified 数据集已验证可达**：`node scripts/_swe-fetch.mjs` 成功从 HuggingFace datasets-server 拉取官方实例（django/django-11099），官方 harness（`--verifier test` 跑 FAIL_TO_PASS）已就绪。
-- **复现**：`node scripts/_swe-bench-real.mjs`（真实跑分）、`node scripts/_swe-smoke.mjs`（mock 闭环）、`node scripts/_swe-fetch.mjs`（拉取官方数据集）。
-- **诚实说明**：以上 100% 为自建 JS 任务集实测，**非官方 SWE-bench Verified 500 任务集成绩**；官方集为 Python 大仓库（django/sympy/astropy 等），需 Docker+pytest 环境逐例 clone 执行，耗时较长，尚未出全量分数，故不对官方榜单声明成绩。官方跑分命令见 `docs/SWE_BENCH_REPORT.md`。行业参考（SWE-bench Verified，2026 公开）：Claude Opus 4.8=88.6%、豆包 Doubao-Seed-Code+TRAE=78.80%。详见 `docs/BENCHMARK_REPORT_zh.md` 第十三章。
-
----
-
-## 三、安装
-
-### 方式一：从源码构建（推荐开发 / 内网部署）
-
-```bash
-git clone https://github.com/wch887292/feihong-code.git
-cd feihong-code
-npm install
-npm run build              # 编译到 dist/
-node dist/cli/index.js --version
-```
-
-或一行安装（已提供脚本）：
-
-```bash
-bash install.sh
-```
-
-### 方式二：全局安装（已发布到 npm）
-
-```bash
-# 官方源
-npm install -g feihong-code
-# 国内镜像（加速）
-npm install -g feihong-code --registry=https://registry.npmmirror.com
-fhcode --version           # 直接调用 bin（Windows 下为 fhcode.cmd）
-> 也支持别名包：`npm install -g feihong-cli`（与 feihong-code 同源，bin 同为 `fhcode`）。
-```
-
-> 要求 Node.js >= 18。入口 `dist/cli/index.js` 已带 `#!/usr/bin/env node` shebang。
-> 源码与问题反馈请前往 GitHub 仓库：<https://github.com/wch887292/feihong-code>
-### 方式三：Docker
-
-```bash
-docker build -t feihong-code .
-docker run --rm feihong-code --version
-# 挂载密钥与日志卷以启用真实模型：
-docker run --rm -v "$PWD/.env:/app/.env" -v feihong-data:/data/feihong-code feihong-code "你的需求"
-```
-
----
-
-## 四、快速开始
-
-### 4.1 离线模式（无需任何 API Key）
-
-```bash
-node dist/cli/index.js "帮我写一个 hello.ts 并打印一句话"
-```
-
-未配置 `FH_PROVIDERS` 时，自动用内置 Mock 驱动器跑通完整闭环（规划 → 调工具写文件 → 总结）。
-
-### 4.2 接入真实大模型
-
-```bash
-cp .env.example .env
-# 编辑 .env，填入 FH_PROVIDERS（baseURL / apiKey / model 等）
-fhcode "把 src/utils 的日期格式化抽成独立模块并补测试"
-```
-
-真实配置示例（已验证可用的 Agnes 网关）：
-
-```json
-FH_PROVIDERS='[{"id":"agnes","type":"openai-compatible","baseURL":"https://api.agnes-ai.cn/v1","apiKey":"<你的key>","model":"agnes-2.5-flash","tags":["code-gen"],"costPer1k":0.001}]'
-```
-
-### 4.3 多子代理并行
-
-```bash
-fhcode --parallel "实现登录模块并且添加用户管理并且写集成测试"
-```
-
-自动拆成 3 个子任务，各自在 `git worktree` 隔离工作区并发执行，结束后清理。
-
-> ⚠️ **真实并行的并发额度**：`--parallel` 会并发调用 API。免费套餐（如 Agnes free tier）对并发请求有严格限流（HTTP 429），可能导致子任务失败。建议：① 升级 API 套餐；② 或改用单命令模式顺序执行大目标；③ 或用 `FH_OFFLINE=true fhcode --parallel "..."` 验证并行机制（离线不耗额度）。
-
-### 4.4 交互 REPL
-
-```bash
-fhcode            # 不带参数进入 REPL，逐条输入需求；exit 退出
-```
-
-### 4.5 只读技能（不修改代码）
-
-```bash
-fhcode /plan  "实现登录并且添加支付并且写报表"   # 生成实现计划
-fhcode /grill src                              # 红队式代码审查
-fhcode /goal  "搭建多子代理体系并且完善文档"      # 分解并保存目标
-```
-
-### 4.6 恢复与审计（M3）
-
-每次任务都会把**完整对话、迭代计数、成本、被改动文件**落盘为会话检查点（`<runId>.session.json`），可随时恢复与审计：
-
-```bash
-fhcode sessions                                  # 列出历史会话（状态/迭代/成本/文件数）
-fhcode resume <id>                              # 从检查点续跑中断的任务（离线/真实皆可）
-fhcode diff <id>                                # 展示该会话相对基线的变更（会话作用域）
-fhcode rollback <id> --yes                      # 回滚该会话产生的改动（危险，需 --yes 确认）
-```
-
-- `resume`：任务被中断（进程崩溃 / 达到最大迭代）后，加载检查点重建对话并继续 ReAct 循环，直到产出最终结果。
-- `diff`：仅对**本会话 touchedFiles** 生成 git diff（未跟踪文件用 `--no-index` 展示新增内容），绝不整仓比对。
-- `rollback`：已跟踪文件 `git checkout --`，未跟踪文件直接删除；**未确认（--yes）或非 git 仓库时拒绝执行**，避免误删。
-
-> 会话 id 支持 8 位前缀（即 `sessions` 列表所展示的前缀），无需完整 uuid。
-> 离线模式下会话落在临时目录、工作区为独立 git 仓库，同样支持完整的 diff / rollback 演示。
-
-### 4.7 交互式审批（M3）
-
-`FH_REQUIRE_APPROVAL=true`（默认）时，危险操作需审批：
-
-- **TTY 交互终端**：运行期逐条弹出 `y/n` 确认（`run_shell`、写文件等高危动作须显式批准）。
-- **非交互（CI / 管道）**：无 TTY 时回退到白名单审批器——命中 `FH_SHELL_ALLOW` 的命令自动通过，其余拒绝并留痕。
-
-```bash
-fhcode "删除临时缓存并重建"      # TTY 下每条 shell 命令会询问；非 TTY 仅白名单命令可过
-```
-
-### 4.8 企业能力：权限 / 审计 / 多租户 / 配额（M4）
-
-企业模式**默认开启**（`FH_ENTERPRISE=false` 可关闭并退化为 M3 行为），身份由环境变量注入，便于容器与网关下发：
-
-```bash
-export FH_TENANT=acme        # 租户 ID（缺省 default）
-export FH_USER=wuchihong     # 用户标识（缺省系统用户名）
-export FH_ROLE=developer     # viewer | developer | operator | admin
-
-fhcode whoami                # 当前租户/用户/角色/隔离目录/今日用量
-fhcode policy                # 生效的 RBAC 策略与四角色矩阵
-fhcode audit --limit 20      # 审计记录（默认最近 20 条）
-fhcode audit verify          # 校验审计哈希链是否被篡改
-fhcode tenants               # 全部租户用量汇总（会话数/成本/审计条数）
-```
-
-**① 权限（RBAC + deny 优先）**
-
-| 角色 | 直接允许 | 需审批 | 单任务上限 |
-| --- | --- | --- | --- |
-| `viewer` | `read_file` `list_dir` `grep` | — | $0.1 |
-| `developer` | 上述 + `write_file` `edit_file` `run_tests` `build_check` | `run_shell` | $1 |
-| `operator` | 全部 | `run_shell` | $5 |
-| `admin` | 全部 | `run_shell` | 不限 |
-
-判定顺序为 **危险命令黑名单 → 敏感路径黑名单 → 沙箱越界 → 角色矩阵 → shell 白名单**。前三条 **deny 优先，admin 也无法绕过**：`rm -rf /`、`mkfs`、`curl | sh` 等 23 条危险命令，`.env`、`.ssh/id_rsa`、`.npmrc`、`.kube/config` 等 11 类敏感路径一律拒绝并留痕。
-
-策略可用 `policy.json` 覆盖（全局 `<FH_HOME>/policy.json` → 租户 `<租户目录>/policy.json` → `FH_POLICY` 内联 JSON），**黑名单取并集，只能加严不能放松**。
-
-**② 审计（防篡改哈希链）**
-
-每条审计记录携带 `prevHash` 与自身 `sha256`，形成链式结构；任何改写、删除、插入都会导致链断裂：
-
-```bash
-$ fhcode audit verify
-✅ 审计链完整：3 条记录，哈希链自洽未被篡改。
-# 若被篡改：
-❌ 审计链校验失败：共 5 条，断点在第 3 条
-   记录内容被篡改：hash 不自洽（期望 8b3a6990664e…）
-```
-
-记录内容自动脱敏（`apiKey=` / `Bearer` / `sk-xxx` → `***`），审计写入失败时**工具执行一律拒绝**——宁可不做，不可无痕。
-
-**③ 多租户（物理目录隔离）**
-
-```
-<FH_HOME>/tenants/<tenantId>/
-├── sessions/     会话检查点与事件日志
-├── audit/        审计链（按月切分 audit-YYYY-MM.jsonl）
-├── goals/        /goal 产物
-└── policy.json   租户级策略覆盖（可选）
-```
-
-租户 ID 经 `^[A-Za-z0-9._-]{1,64}$` 校验，杜绝 `../` 穿越；租户之间 `sessions` / `audit` / `goals` 完全互不可见。默认租户在旧版目录存在时自动沿用，升级不丢历史会话。
-
-**④ 配额（成本熔断）**
-
-- **单任务**：超过角色 `maxCostUsd` 立即中止，可调高后 `resume` 续跑。
-- **租户日预算**：`FH_TENANT_BUDGET_USD`（或策略 `tenantDailyBudgetUsd`）在任务启动前 fail-fast，**不产生任何模型费用**：
-
-```bash
-$ FH_TENANT_BUDGET_USD=0.30 fhcode "超预算任务"
-[飞虹 Code] 运行失败 (QUOTA_EXCEEDED): 租户 acme 今日成本 $0.420000 已达上限 $0.3，任务被拒绝。
-```
-
----
-
-## 五、命令参考
-
-| 命令 | 说明 |
-| --- | --- |
-| `fhcode` | 进入交互式 REPL（逐条需求） |
-| `fhcode "<需求>"` | 单命令模式执行一条需求 |
-| `fhcode --parallel "<需求>"` | 多子代理并行（git worktree 隔离） |
-| `fhcode /plan "<目标>"` | 生成结构化实现计划（只读） |
-| `fhcode /grill [路径]` | 红队式代码审查（只读，默认当前目录） |
-| `fhcode /goal "<目标>"` | 分解并保存高层目标到 `~/.feihong-code/goals` |
-| `fhcode sessions` | 列出历史会话检查点（状态/迭代/成本/文件数） |
-| `fhcode resume <id>` | 从检查点恢复并续跑中断的任务 |
-| `fhcode diff [<id>]` | 展示会话作用域（或当前工作区）变更 |
-| `fhcode rollback <id> [--yes]` | 回滚会话改动（危险操作，需 `--yes` 确认） |
-| `fhcode whoami` | 当前租户 / 用户 / 角色 / 隔离目录 / 今日用量（M4） |
-| `fhcode policy` | 查看生效 RBAC 策略与角色矩阵（M4） |
-| `fhcode audit [--limit N]` | 查看审计记录，默认最近 20 条（M4） |
-| `fhcode audit verify` | 校验审计哈希链完整性（M4） |
-| `fhcode tenants` | 列出全部租户与用量汇总（M4） |
-| `fhcode model-stats` | 查看各模型性能统计（M6） |
-| `fhcode experiences` | 列出经验库（M6） |
-| `fhcode code-write "<目标>"` | 自主编写代码：规划→编写→测试→审查→修复（M8） |
-| `fhcode quality-gate [路径]` | 质量门禁审查：安全+质量+测试覆盖（M8） |
-| `fhcode self-improve` | 自我改进统计与历史（M8） |
-| `fhcode swe "<目标>"` | 全自动软件工程 Agent：读仓库→拆解→实现+验证+自愈→报告（M9，支持 `--max-iterations` 等） |
-| `fhcode --version` / `-v` | 显示版本与署名 |
-| `fhcode --help` / `-h` | 显示帮助 |
-
-> 未配置 `FH_PROVIDERS`（或 `FH_OFFLINE=true`）时自动离线模式。
-
----
-
-## 六、工具系统
-
-| 分类 | 工具 | 说明 |
-| --- | --- | --- |
-| 文件 | `read_file` / `write_file` / `edit_file` / `list_dir` | 沙箱内读写，防 `../` 穿越 |
-| 搜索 | `grep` | 代码内容递归检索（忽略 node_modules/.git） |
-| Shell | `run_shell` | 白名单 + 危险拦截 + 审批 |
-| 验证 | `run_tests` / `build_check` | 运行测试套件 / 构建校验（默认 `npm test` / `npm run build`） |
-
-所有工具入参经 **zod 校验**，错误归一为 `ToolError`；文件操作一律限制在 `cwd` 沙箱内。
-
----
-
-## 七、安全模型
-
-1. **路径沙箱**：`safeJoin` 校验每个文件路径不得超出 `cwd`，杜绝 `../` 越权。
-2. **Shell 白名单**：`run_shell` 仅在命令首词命中 `FH_SHELL_ALLOW` 时放行；非交互 CLI 下，命中白名单者由默认审批器自动通过，其余拒绝并留痕。
-3. **密钥脱敏**：日志按 key 名（`apikey|secret|token|...`）将值替换为 `[REDACTED]`，且不回显完整 API key。
-4. **审批拦截**：`FH_REQUIRE_APPROVAL=true`（默认）时，危险操作需审批通道；**TTY 交互终端逐条弹 `y/n` 确认**，非交互（CI/管道）则回退白名单审批器——命中 `FH_SHELL_ALLOW` 自动通过、其余拒绝并留痕。
-5. **`.env` 不入库**：已被 `.gitignore` 排除；`package.json` 的 `files` 白名单确保 `npm publish` 不会携带 `.env`。
-6. **RBAC 策略引擎（M4）**：角色-工具矩阵 + **deny 优先**的危险命令 / 敏感路径黑名单，`admin` 亦不可绕过；策略只能被下级配置**加严**。
-7. **防篡改审计（M4）**：全量动作（allow/deny/approved/rejected）写入 sha256 哈希链，`fhcode audit verify` 可定位篡改位置；**审计写失败即拒绝执行**。
-8. **租户隔离与配额（M4）**：会话 / 审计 / 目标物理分目录，租户 ID 严格校验；单任务成本熔断 + 租户日预算 fail-fast。
-
-> M4 起守卫（guard）是**唯一权威闸门**：策略判定、人工审批、审计留痕都在工具执行前一次性完成，工具层不再重复弹审批，避免"审批打架"与重复询问。
-
----
-
-## 八、配置参考（.env）
-
-| 变量 | 说明 | 默认 / 示例 |
-| --- | --- | --- |
-| `FH_HOME` | 应用主目录（可缺省） | `~/.feihong-code` |
-| `FH_LOG_DIR` | 会话日志目录 | `~/.feihong-code/sessions` |
-| `FH_PROVIDERS` | 模型供应商 JSON 数组 | 见 `docs/配置参考.md` |
-| `FH_MODEL_STRATEGY` | 路由策略：`cost`/`capability`/`latency` | `cost` |
-| `FH_BUDGET_USD` | 单任务预算上限（美元，仅告警不阻断） | `0.5` |
-| `FH_SHELL_ALLOW` | shell 白名单（逗号分隔，命中即免审批） | `git,npm,node,ls,cat` |
-| `FH_REQUIRE_APPROVAL` | 危险操作是否需审批 | `true` |
-| `FH_ENTERPRISE` | 企业模式开关（权限/审计/多租户/配额） | `true` |
-| `FH_TENANT` | 租户 ID（决定隔离目录） | `default` |
-| `FH_USER` | 用户标识（写入审计 actor） | 系统用户名 |
-| `FH_ROLE` | 角色：`viewer`/`developer`/`operator`/`admin` | `developer` |
-| `FH_TENANT_BUDGET_USD` | 租户日成本上限（0 = 不限） | `0` |
-| `FH_POLICY` | 内联策略 JSON（优先级最高） | 未设置 |
-
-> 完整配置说明见 [`docs/配置参考.md`](./docs/配置参考.md)。`.env` 含密钥，切勿提交。
-
----
-
-## 九、架构（feature-first 分层）
-
-```
-src/
-├── cli/          入口、参数解析、REPL、运行时装配（run.ts）
-├── shared/       基础设施：config / errors / logger / types
-├── agent/        Orchestrator（ReAct 循环）/ Planner / Prompts / 并行编排 / 子代理
-├── tools/        工具实现（file / shell / search / verify）+ registry + 安全沙箱
-├── models/       模型路由 ModelRouter + providers（openai-compatible / ollama / mock）
-├── runtime/      事件日志 EventLog、会话状态 SessionStore、会话检查点持久化、git diff/rollback、git worktree 隔离
-├── enterprise/   M4 企业能力：tenant（多租户）/ policy（RBAC）/ audit（哈希链）/ quota（配额）/ guard（守卫）
-└── skills/       高级技能：/plan /grill /goal
-```
-
-**单命令执行流**：`CLI → Orchestrator → ModelRouter（选模型）→ 模型返回工具调用 → ToolRegistry（校验+执行）→ 结果回填模型 → 循环至完成 → 每轮落盘检查点 + 事件日志归档`。
-
-**并行执行流**：`CLI --parallel → 分解目标 → 为每子任务创建 git worktree（独立分支）→ Promise.allSettled 并发子代理 → 收集结果 → 强制清理 worktree`。
-
-**恢复执行流（M3）**：`sessions 列出检查点 → resume <id> 加载检查点重建对话 → 续跑 ReAct 循环 → 产出最终结果`；`diff/rollback` 基于检查点的 touchedFiles 做会话作用域的 git 比对与回退。
-
-**企业管控流（M4）**：`环境注入身份（tenant/user/role）→ 加载策略（默认→全局→租户→内联）→ 配额前置校验 → 每次工具调用经 guard：策略判定 → 必要时人工审批 → 写入哈希链审计 → 放行/拒绝`。
-
-> 架构详解见 [`docs/架构与API.md`](./docs/架构与API.md)。
-
----
-
-## 十、开发
-
-```bash
-npm install
-npm run build      # tsc 编译到 dist/
-npm run dev        # tsx 直接跑源码（免构建）
-npm run typecheck  # 仅类型检查
-npm run verify:m4  # M4 企业能力断言套件（41 项，全离线）
-npm run verify     # typecheck + build + M4 断言，一条命令过全链路
-node dist/cli/index.js --version
-```
-
-### 工程规范（全栈铁律）
-
-1. 边界必须校验（CLI 参数 / 模型响应 / 工具入参 → zod）。
-2. 集中配置（`shared/config.ts`，启动校验、fail-fast、懒加载）。
-3. 类型化错误（`AppError` 子类，禁止裸 `throw`）。
-4. 结构化日志（JSON + `runId`，密钥脱敏）。
-5. 单一可信源（行为以 `runtime/event-log` 为准）。
-
----
-
-## 十一、部署
-
-- **npm 全局**：`npm install -g .` 或发布后 `npm install -g feihong-code`。
-- **Docker**：见 `Dockerfile`（多阶段，已含 `git` 以支持 `--parallel`）。
-- **CI**：见 `.github/workflows/ci.yml`，三条流水线全离线、零 Secrets：
-  - `build`：Node 18/20/22 矩阵 → typecheck → 编译 → 离线端到端 → 只读技能；
-  - `enterprise`：M4 断言套件（41 项）+ CLI 企业命令冒烟 + **租户隔离断言**（beta 租户不得读到其它租户会话）；
-  - `security`：`npm pack` 白名单校验（禁止 `.env`/`src`/`policy.json` 入包）+ 仓库明文密钥扫描 + `npm audit`。
-- **发布**：`npm publish` 仅携带 `files` 白名单（dist + 文档），密钥安全。
-- 部署细节见 [`docs/部署指南.md`](./docs/部署指南.md)，企业落地见 [`docs/企业部署与合规.md`](./docs/企业部署与合规.md)。
-
----
-
-## 十二、里程碑进度
-
-> **📌 版本号与里程碑是两套编号，相互解耦**
->
-> - **M0→M9.1** 是**能力里程碑**（工程开发阶段编号）：2026-08 上旬全部交付后**冻结，不再扩展**。它回答"哪些核心能力已建成"。
-> - **7.x** 是**产品化成熟度版本号**（SemVer）：M 里程碑交付完成后（v7.0.0 起）进入持续产品化迭代——桌面版、Web 控制台、SWE-bench 差分验证 harness、企业治理、自进化经验库、语音编程等均以 7.x 版本号发布。它回答"产品打磨到了什么程度"。
-> - 因此**不存在"版本 7.6 却只有 M9"的矛盾**：M 编号停止增长是设计使然，能力演进体现在 7.x 的次版本号中。
-
-| 里程碑 | 内容 | 状态 |
-| --- | --- | --- |
-| **M0 脚手架** | 工程结构、shared 基础设施、CLI 入口 | ✅ 完成 |
-| **M1 P0 闭环** | 模型路由、文件/shell 工具、REPL、事件日志、离线闭环验证 | ✅ 完成 |
-| **M2 多子代理** | `git worktree` 隔离、并行子代理、`/plan` `/grill` `/goal` 技能 | ✅ 完成 |
-| **M2 真实联调（B）** | 接入 OpenAI 兼容真实模型（Agnes），ReAct 闭环跑通 | ✅ 完成 |
-| **M3 恢复与审计** | `sessions`/`resume` 断点续跑、`diff`/`rollback` 会话作用域变更管理、交互式审批流 | ✅ 完成 |
-| **M4 企业级** | RBAC 策略引擎、防篡改审计链、多租户隔离与配额、三流水线 CI | ✅ 完成 |
-| **M5 Web 控制台** | 只读观测面板（租户/策略/审计/配额可视化）| ✅ BETA |
-| **M6 自我进化** | 自愈循环、上下文压缩、经验学习、模型性能追踪 | ✅ 完成 |
-| **M7 编程能力** | 代码分析/生成/审查/仓库理解/测试生成 | ✅ 完成 |
-| **M8 自主迭代** | CodeWriter 六步闭环、QualityGate、SelfImprover | ✅ 完成 |
-| **M9 全自动 SWE** | 仓库读取→任务拆解→实现+验证→自愈→报告 | ✅ 完成 |
-| **M9.1 真实模型** | 三级 provider 接入、exec 纪律强化、mock 全链路验证 | ✅ 完成 |
-
----
-
-## 十三、文档导航
-
-> **AI Agent 快速上手**
-- [AGENT-GUIDE.md](./AGENT-GUIDE.md) — 面向 AI Agent 的使用指南（环境、配置、工具契约）
-- [tool-schema.json](./tool-schema.json) — 所有工具的 JSON Schema 定义
-- [GEO-AAO-STRATEGY.md](./GEO-AAO-STRATEGY.md) — 生成式引擎优化与 Agent 优化策略
-
-> **权威文档（稳定版首选）**
-- [技术说明书](./docs/技术说明书.md) — 架构、企业能力技术细节、数据契约、CLI/Web API、部署架构、安全模型、构建验证
-- [使用说明书](./docs/使用说明书.md) — 安装、快速上手、命令总览、核心工作流、企业版/Web 控制台使用、配置、排错
-
-> **补充参考**
-- [用户手册](./docs/用户手册.md) — 各命令详解、工具说明、审批与安全、最佳实践
-- [配置参考](./docs/配置参考.md) — 全部 `FH_*` 环境变量与 `FH_PROVIDERS` 详解
-- [架构与 API](./docs/架构与API.md) — 分层、编排循环、模型路由、工具协议、事件日志
-- [部署指南](./docs/部署指南.md) — npm / Docker / CI / 发布 / 密钥安全
-- [企业部署与合规](./docs/企业部署与合规.md) — RBAC 角色设计、审计取证、多租户方案、配额治理（M4）
-- [常见问题与故障排查](./docs/常见问题与故障排查.md) — FAQ 与排错
-- [产品开发文档](./docs/产品开发文档.md) — 需求/里程碑/设计决策（演进稿）
-
-> 稳定部署产物：`Dockerfile`、`docker-compose.yml`、`install.sh`、`CHANGELOG.md`（见仓库根目录）。
-
----
-
-
----
-
-## 🤝 社区支持
-
-关注飞虹智 klAI 动态，获取最新开源项目更新与技术教程：
-
-- 🏠 官网与开源矩阵：[https://www.klai.top/opensource.html](https://www.klai.top/opensource.html)
-- 🤖 AI Agent 入口：[https://www.klai.top/openclaw.html](https://www.klai.top/openclaw.html)
-
-加入 **飞虹智企微小助手**，获取：
-- 技术答疑与部署指导
-- 开源项目更新通知
-- 本地化服务预约（泉州地区）
-- 企业 AI 数字化咨询
-
----
-
-*晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹*
-
-## 十四、版权与署名
-
-- **公司**：晋江市飞虹智科技企业管理有限公司
-- **中心**：飞扬企源研发中心
-- **负责人**：吴赐虹
-
-© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-Released under the [MIT License](./LICENSE).
-
----
-
-## 组织与署名
-
-<!-- FYQY-ENTITY-BLOCK v1 -->
-
-**公司**：晋江市飞虹智科技企业管理有限公司
-**中心**：飞扬企源研发中心
-**负责人**：吴赐虹
-
-- 官网：https://www.klai.top
-- 知识库：https://kb.klai.top
-- 开源矩阵：https://github.com/wch887292
-- 实体权威声明（机器可读）：https://www.klai.top/entity.jsonld
-
-> 本项目版权归 晋江市飞虹智科技企业管理有限公司 所有，由 飞扬企源研发中心 研发交付。
+> **English / 英文文档**：[README_EN.md](README_EN.md) · [FAQ (English)](FAQ_EN.md)
+
+<!-- Schema.org JSON-LD for GEO optimization -->
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "SoftwareSourceCode",
+  "name": "飞虹 Code (fhcode)",
+  "description": "终端 AI 编程智能体，对标 Meta Muse Code / Claude Code / Cursor CLI 等国际同类产品，以自研内核实现差异化。多模型路由、企业级 RBAC/审计/多租户、全自动 SWE Agent、离线私有化。支持 DeepSeek/通义/Ollama/OpenAI 兼容网关。",
+  "url": "https://github.com/wch887292/feihong-code",
+  "license": "https://opensource.org/licenses/MIT",
+  "programmingLanguage": {
+    "@type": "ProgrammingLanguage",
+    "name": "TypeScript"
+  },
+  "operatingSystem": "Cross-platform (Windows, Linux, macOS)",
+  "softwareVersion": "8.0.2",
+  "dateCreated": "2026-08-12",
+  "datePublished": "2026-08-22",
+  "author": {
+    "@type": "Organization",
+    "name": "晋江市飞虹智科技企业管理有限公司",
+    "url": "https://www.klai.top"
+  },
+  "developer": {
+    "@type": "Organization",
+    "name": "飞扬企源研发中心",
+    "url": "https://www.klai.top"
+  },
+  "keywords": [
+    "AI Agent", "SWE Agent", "CLI", "多模型路由", "DeepSeek", "Ollama",
+    "企业级权限", "RBAC", "审计链", "多租户", "自我进化", "自愈循环",
+    "代码生成", "typescript", "nodejs", "open source"
+  ],
+  "sameAs": [
+    "https://www.npmjs.com/package/feihong-code",
+    "https://www.klai.top/opensource.html"
+  ],
+  "featureList": [
+    "核心能力里程碑 M0-M9.1 全部交付",
+    "多模型路由 (DeepSeek/通义/Ollama/OpenAI)",
+    "企业级 RBAC 权限矩阵",
+    "防篡改审计哈希链",
+    "多租户物理隔离",
+    "配额成本熔断",
+    "自我进化与自愈循环",
+    "上下文智能压缩",
+    "多子代理并行 (git worktree)",
+    "Web 管理控制台 (BETA)",
+    "全自动 SWE Agent",
+    "离线私有化部署"
+  ]
+}
+</script>
+## v8.0.1 新能力（2026-09-08）
+
+**1. 桌面手脚（Windows 原生操控）**
+- 嫁接 desktop-touch MCP：`feihong_desktop_see / act / verify` 三个强类型工具，可看屏、操作、验证原生 app。
+- 三层结构：A 配置接入（fhcode.config.json 零代码）/ B 策略约束（审批 + 只读沙箱 + 危险窗口停手线）/ C 内化封装（守卫 + 取证）。
+- 停手线：任务管理器/注册表编辑器/UAC/安全中心等危险窗口硬拦截，`FEIHONG_DESKTOP_BLOCK_WINDOWS` 可扩展。
+- 取证：每步操作留痕（JSONL manifest + 截图），交付客户可复盘、可审计。
+
+**2. AI 员工军团（agent-team）**
+- 17 个业务 AI 员工（L1 获客 / L2 内容 / L3 转化 / L4 决策 / L5 管理）随仓库分发，`agent-team/`。
+- 飞虹原生工具：`feihong_agents_list`（员工/统计）、`feihong_agents_submit`（提交任务，需审批）。
+- 模型路由打通：自动复用飞虹 models.providers（openai-compatible），无配置时回退 mock 全链路可跑。
+- 17 个技能同时安装到用户级技能目录，`discoverSkills` 可直接发现调用。
+
+**3. 安全治理（脱敏 + 清理）**
+- 移除 app.js 硬编码 API Key、docs 本机路径；历史泄露密钥已通过 filter-branch 全历史清除（force push 交付）。
+- 清理 bench/real 约 6.8GB 评测运行产物；.gitignore 加固防再污染。
+
+> 完整使用见 [docs/使用说明书-v8.0.1.md](docs/使用说明书-v8.0.1.md)；技术细节见 [docs/TECHNICAL-SPECIFICATION.md](docs/TECHNICAL-SPECIFICATION.md)。
+
+
+# 飞虹 Code（fhcode）
+
+> **终端 AI 编程智能体** · 对标 Meta Muse Code / Claude Code / Cursor CLI · 自研内核实现差异化 · 全功能 M0→M9.1 完成 · 企业级 RBAC/审计/SWE Agent
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://typescriptlang.org)
+[![GitHub stars](https://img.shields.io/github/stars/wch887292/feihong-code?style=social)](https://github.com/wch887292/feihong-code/stargazers)
+[![GitHub issues](https://img.shields.io/github/issues/wch887292/feihong-code)](https://github.com/wch887292/feihong-code/issues)
+[![npm version](https://img.shields.io/npm/v/feihong-code.svg)](https://www.npmjs.com/package/feihong-code)
+[![npm downloads (monthly)](https://img.shields.io/npm/dm/feihong-code.svg)](https://www.npmjs.com/package/feihong-code)
+[![npm downloads (total)](https://img.shields.io/npm/dt/feihong-code.svg)](https://www.npmjs.com/package/feihong-code)
+[![CI Status](https://github.com/wch887292/feihong-code/actions/workflows/ci.yml/badge.svg)](https://github.com/wch887292/feihong-code/actions)
+
+**🔍 关键词**：AI Agent · 代码生成 · SWE Agent · CLI · 多模型路由 · 企业级权限 · 离线可用
+
+**📦 一键安装**：`npm install -g feihong-code` · 国内镜像：`npm install -g feihong-code --registry=https://registry.npmmirror.com`
+**🚀 5 分钟上手**：`fhcode --version` → `fhcode chat`（离线模式免 API Key 即可对话）
+
+**🌐 中英文双语界面**：`fhcode --lang zh|en` 切换 CLI 语言，或设置环境变量 `FHCODE_LANG=zh|en`（默认按系统 locale 自动检测）。Web 控制台（`fhcode serve`）同样支持中英文一键切换。
+
+
+---
+
+## 🌐 品牌与官网
+
+本项目由 **晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心** 开发维护，是飞虹智 klAI 开源生态的核心组件。
+
+- 🏠 **官方网站**：[https://www.klai.top](https://www.klai.top) — 飞虹智 klAI · 泉州制造业 AI 服务商
+- 📦 **开源矩阵**：[https://www.klai.top/opensource.html](https://www.klai.top/opensource.html)
+- 🤖 **AI Agent 入口**：[https://www.klai.top/openclaw.html](https://www.klai.top/openclaw.html)
+
+
+
+## 零、For AI Agents（面向 AI 智能体）
+
+本项目专为 AI Agent 设计，提供结构化 CLI 与明确工具契约。详见 [`AGENT-GUIDE.md`](./AGENT-GUIDE.md) 与 [`tool-schema.json`](./tool-schema.json)。
+
+**快速评估项目是否适合你的 Agent**：
+```bash
+fhcode --help                    # 查看所有命令
+fhcode "你的目标"                # 单任务执行
+fhcode --parallel "目标A 并且 目标B"  # 并行子任务
+fhcode swe "修复仓库 X 的问题 Y"  # 全自动软件工程
+```
+
+**推荐配置（生产环境）**：
+```bash
+export FH_MODEL_NAME=qwen3:8b
+export FH_MODEL_TYPE=ollama
+export FH_MODEL_BASE_URL=http://localhost:11434
+export FH_ENTERPRISE=true
+export FH_TENANT=my-org
+export FH_USER=agent-sa
+export FH_ROLE=developer
+```
+
+---
+
+## 一、产品定位
+
+**飞虹 Code（fhcode）** 是一款运行在终端的 **AI 编程智能体**，以 Meta Muse Code、Claude Code、Cursor CLI 等国际同类产品为**对标参照系**，独立自研内核：用自然语言描述需求，智能体自主完成**规划 → 读写代码 → 运行验证 → 汇报结果**的闭环。
+
+> **关于"对标"的措辞基线**：本项目对外统一使用 **「对标 / 对比 / 参考 / 差异化」** 四种表述 —— **对标**指以同类产品作为行业参照系来校准能力水位；**参考**指借鉴已被验证的交互范式与产品形态；**差异化**指本项目自研实现、与参照对象形成区隔的独有能力。本项目是**独立设计与实现的原创工程**，非分叉、非移植、非克隆，代码库不包含任何第三方闭源或受限制代码。
+
+**🎯 适用场景**：
+- 代码生成与修改（函数、模块、完整功能）
+- 批量重构与代码审查
+- 离线脚本化任务与自动化工作流
+- 企业内多团队共享的智能体底座
+- 全自动软件工程（SWE Agent）：读取仓库 → 拆解任务 → 实现 + 测试验证 → 报告
+
+- 不绑定任何单一大模型厂商，通过**多模型路由层**在 DeepSeek / 通义 / Ollama（本地）/ 任意 OpenAI 兼容网关之间按需调度。
+- 所有行为以 **append-only 事件日志**为单一可信源，完全可审计、可恢复。
+- 遵循**安全合规底线**：文件沙箱、shell 白名单、密钥脱敏、危险操作审批。
+- **M2 多子代理并行**：用 `git worktree` 物理隔离多个子代理工作区，并发推进互不干扰。
+
+---
+
+### 🆚 对标对比矩阵
+
+> 下表为**功能性对标参考**，用于说明能力覆盖水位差异，非性能跑分；信息依据各产品公开文档与本项目实测整理，供选型时对照参考。
+
+| 能力 | **fhcode（飞虹 Code）** | Claude Code | Cursor CLI | Aider | OpenCode |
+|---|---|---|---|---|---|
+| 终端原生 CLI | ✅ | ✅ | ⚠️（编辑器内） | ✅ | ✅ |
+| 多模型路由（DeepSeek/通义/Ollama/OpenAI） | ✅ | ❌（仅 Anthropic） | ⚠️ | ⚠️ | ✅ |
+| 离线 / 私有化（数据不出内网） | ✅（Ollama 本地） | ❌ | ❌ | ⚠️ | ✅ |
+| 企业级 RBAC / 审计链 | ✅ | ❌ | ❌ | ❌ | ❌ |
+| 全自动 SWE Agent（M0→M9.1） | ✅ | ✅ | ⚠️ | ✅ | ⚠️ |
+| 多子代理并行（M2） | ✅ | ✅ | ❌ | ❌ | ❌ |
+| 自我进化（M6） | ✅ | ❌ | ❌ | ❌ | ❌ |
+| 开源可自托管（MIT） | ✅ | ❌ | ❌ | ✅ Apache-2.0 | ✅ MIT |
+
+> 最适合：**数据不出内网**、需要**企业权限审计**、希望**混合调度多家大模型**的团队与个人开发者。
+
+### 🎯 差异化能力（自研内核）
+
+上表说明"能力有无"，下表说明"同样的能力，fhcode 做得有何不同" —— 这部分是本项目**独立设计与实现**的结果，也是与对标对象形成区隔的核心。
+
+| 差异化维度 | fhcode 的实现 | 同类产品普遍现状 |
+|---|---|---|
+| 模型调度 | 统一网关抽象层，DeepSeek / 通义 / Ollama / 任意 OpenAI 兼容端点按成本与能力动态路由 | 多数绑定单一模型厂商，切换成本高 |
+| 离线私有化 | Ollama 本地推理 + 全链路断网可用，代码与数据不出内网 | 多数强依赖云端 API，无法满足内网合规 |
+| 企业治理 | RBAC 权限矩阵 + 防篡改审计哈希链 + 多租户物理隔离 + 配额成本熔断，四件套开箱即用 | 多为个人向工具，缺权限与审计体系 |
+| 自我进化（M6） | 经验库沉淀 + 自愈循环，失败模式跨会话复用，越用越准 | 基本无对应机制 |
+| 并行隔离（M2） | `git worktree` 为每个子代理建立物理隔离工作区，并发推进零冲突 | 部分支持，隔离强度与冲突处理参差 |
+| 可恢复性（M3） | append-only 事件日志为单一可信源，会话可断点恢复、可完整回放 | 会话状态多不可恢复，中断即重来 |
+| 授权与自托管 | MIT 许可，源码开放，支持完全私有化部署与二次开发 | 主流产品为闭源商业服务 |
+
+> **一句话区分**：对标产品解决"个人开发者如何更快写代码"，fhcode 额外解决"**团队如何在合规边界内、可审计地、用可控成本把 AI 编程落地到生产**"。
+
+### 📸 产品截图
+
+| CLI 终端 | Web 控制台 | 功能对比 |
+|---------|-----------|---------|
+| ![CLI Demo](docs/screenshots/cli-demo.png) | ![Web Console](docs/screenshots/web-console.png) | ![Feature Comparison](docs/screenshots/feature-comparison.png) |
+
+## 二、核心特性
+
+### 🔥 主要亮点
+- ✅ **自然语言 → 代码闭环**：描述需求，自动调用工具完成改码与验证
+- ✅ **多模型路由**：支持 DeepSeek / 通义 / Ollama / OpenAI 兼容网关，自动选优+fallback
+- ✅ **离线可用**：无需 API Key 即可演示完整闭环（内置 Mock 驱动）
+- ✅ **企业级安全**：RBAC 权限矩阵、防篡改审计链、多租户隔离、配额熔断
+- ✅ **全自动 SWE Agent**：读取仓库 → 任务拆解 → 实现 + 测试验证 → 自愈重试 → 报告
+
+### 🛠️ 功能矩阵
+| 里程碑 | 能力 | 状态 |
+|--------|------|------|
+| **M0-M1** | CLI 基础、模型路由、文件/Shell 工具、离线闭环 | ✅ 完成 |
+| **M2** | 多子代理并行（git worktree 隔离）+ `/plan` `/grill` `/goal` 技能 | ✅ 完成 |
+| **M3** | 会话恢复、diff/rollback、交互式审批流 | ✅ 完成 |
+| **M4** | RBAC 权限、哈希链审计、多租户、配额治理、CI 三流水线 | ✅ 完成 |
+| **M5** | Web 管理控制台（BETA） | ✅ BETA |
+| **M6** | 自愈循环、上下文压缩、经验学习、模型性能追踪 | ✅ 完成 |
+| **M7** | 静态代码分析、模板化生成、AI 代码审查、仓库理解、测试生成 | ✅ 完成 |
+| **M8** | CodeWriter 六步闭环、QualityGate 质量门禁、SelfImprover 自我改进 | ✅ 完成 |
+| **M9** | 全自动软件工程 Agent（swe 命令） | ✅ 完成 |
+| **M9.1** | 真实模型接入（三级 provider 解析）、exec 纪律强化 | ✅ 完成 |
+
+### 🌟 技术亮点
+- **零依赖侵入**：仅依赖 `express` + `zod`，无框架包袱
+- **TypeScript 全量类型安全**：tsc --noEmit 零错误
+- **完整测试覆盖**：42 单元测试 + 145 集成验证断言（M4/M6/M7/M8/M9/M9-real 全离线）
+- **CI/CD 就绪**：GitHub Actions 三流水线（build/enterprise/security），零 Secrets 可跑
+- **Docker 多阶段构建**：支持容器化部署
+
+### 🎯 SWE-bench 真实跑分（v7.6.0 复测，诚实口径）
+- **测试通过率 100%（5/5）**：自建 SWE-bench 格式任务集（problem_statement + FAIL_TO_PASS，5 个自包含 JS 任务），真实模型（agnes-2.5-flash）驱动 Orchestrator 修复 + **预定义测试 `node --test` 真实断言**（测试不交给模型，防作弊）。2026-08-27 复测：5 例全过，平均迭代 2.2 次/例。（v7.2.0 首测为 80%/4-5，本次模型稳定性提升至全过。）
+- **harness 闭环 2/2 = 100%**：loader→executor→verifier→reporter 全链路真实可执行。
+- **官方 SWE-bench Verified 数据集已验证可达**：`node scripts/_swe-fetch.mjs` 成功从 HuggingFace datasets-server 拉取官方实例（django/django-11099），官方 harness（`--verifier test` 跑 FAIL_TO_PASS）已就绪。
+- **复现**：`node scripts/_swe-bench-real.mjs`（真实跑分）、`node scripts/_swe-smoke.mjs`（mock 闭环）、`node scripts/_swe-fetch.mjs`（拉取官方数据集）。
+- **诚实说明**：以上 100% 为自建 JS 任务集实测，**非官方 SWE-bench Verified 500 任务集成绩**；官方集为 Python 大仓库（django/sympy/astropy 等），需 Docker+pytest 环境逐例 clone 执行，耗时较长，尚未出全量分数，故不对官方榜单声明成绩。官方跑分命令见 `docs/SWE_BENCH_REPORT.md`。行业参考（SWE-bench Verified，2026 公开）：Claude Opus 4.8=88.6%、豆包 Doubao-Seed-Code+TRAE=78.80%。详见 `docs/BENCHMARK_REPORT_zh.md` 第十三章。
+
+---
+
+## 三、安装
+
+### 方式一：从源码构建（推荐开发 / 内网部署）
+
+```bash
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build              # 编译到 dist/
+node dist/cli/index.js --version
+```
+
+或一行安装（已提供脚本）：
+
+```bash
+bash install.sh
+```
+
+### 方式二：全局安装（已发布到 npm）
+
+```bash
+# 官方源
+npm install -g feihong-code
+# 国内镜像（加速）
+npm install -g feihong-code --registry=https://registry.npmmirror.com
+fhcode --version           # 直接调用 bin（Windows 下为 fhcode.cmd）
+> 也支持别名包：`npm install -g feihong-cli`（与 feihong-code 同源，bin 同为 `fhcode`）。
+```
+
+> 要求 Node.js >= 18。入口 `dist/cli/index.js` 已带 `#!/usr/bin/env node` shebang。
+> 源码与问题反馈请前往 GitHub 仓库：<https://github.com/wch887292/feihong-code>
+### 方式三：Docker
+
+```bash
+docker build -t feihong-code .
+docker run --rm feihong-code --version
+# 挂载密钥与日志卷以启用真实模型：
+docker run --rm -v "$PWD/.env:/app/.env" -v feihong-data:/data/feihong-code feihong-code "你的需求"
+```
+
+---
+
+## 四、快速开始
+
+### 4.1 离线模式（无需任何 API Key）
+
+```bash
+node dist/cli/index.js "帮我写一个 hello.ts 并打印一句话"
+```
+
+未配置 `FH_PROVIDERS` 时，自动用内置 Mock 驱动器跑通完整闭环（规划 → 调工具写文件 → 总结）。
+
+### 4.2 接入真实大模型
+
+```bash
+cp .env.example .env
+# 编辑 .env，填入 FH_PROVIDERS（baseURL / apiKey / model 等）
+fhcode "把 src/utils 的日期格式化抽成独立模块并补测试"
+```
+
+真实配置示例（已验证可用的 Agnes 网关）：
+
+```json
+FH_PROVIDERS='[{"id":"agnes","type":"openai-compatible","baseURL":"https://api.agnes-ai.cn/v1","apiKey":"<你的key>","model":"agnes-2.5-flash","tags":["code-gen"],"costPer1k":0.001}]'
+```
+
+### 4.3 多子代理并行
+
+```bash
+fhcode --parallel "实现登录模块并且添加用户管理并且写集成测试"
+```
+
+自动拆成 3 个子任务，各自在 `git worktree` 隔离工作区并发执行，结束后清理。
+
+> ⚠️ **真实并行的并发额度**：`--parallel` 会并发调用 API。免费套餐（如 Agnes free tier）对并发请求有严格限流（HTTP 429），可能导致子任务失败。建议：① 升级 API 套餐；② 或改用单命令模式顺序执行大目标；③ 或用 `FH_OFFLINE=true fhcode --parallel "..."` 验证并行机制（离线不耗额度）。
+
+### 4.4 交互 REPL
+
+```bash
+fhcode            # 不带参数进入 REPL，逐条输入需求；exit 退出
+```
+
+### 4.5 只读技能（不修改代码）
+
+```bash
+fhcode /plan  "实现登录并且添加支付并且写报表"   # 生成实现计划
+fhcode /grill src                              # 红队式代码审查
+fhcode /goal  "搭建多子代理体系并且完善文档"      # 分解并保存目标
+```
+
+### 4.6 恢复与审计（M3）
+
+每次任务都会把**完整对话、迭代计数、成本、被改动文件**落盘为会话检查点（`<runId>.session.json`），可随时恢复与审计：
+
+```bash
+fhcode sessions                                  # 列出历史会话（状态/迭代/成本/文件数）
+fhcode resume <id>                              # 从检查点续跑中断的任务（离线/真实皆可）
+fhcode diff <id>                                # 展示该会话相对基线的变更（会话作用域）
+fhcode rollback <id> --yes                      # 回滚该会话产生的改动（危险，需 --yes 确认）
+```
+
+- `resume`：任务被中断（进程崩溃 / 达到最大迭代）后，加载检查点重建对话并继续 ReAct 循环，直到产出最终结果。
+- `diff`：仅对**本会话 touchedFiles** 生成 git diff（未跟踪文件用 `--no-index` 展示新增内容），绝不整仓比对。
+- `rollback`：已跟踪文件 `git checkout --`，未跟踪文件直接删除；**未确认（--yes）或非 git 仓库时拒绝执行**，避免误删。
+
+> 会话 id 支持 8 位前缀（即 `sessions` 列表所展示的前缀），无需完整 uuid。
+> 离线模式下会话落在临时目录、工作区为独立 git 仓库，同样支持完整的 diff / rollback 演示。
+
+### 4.7 交互式审批（M3）
+
+`FH_REQUIRE_APPROVAL=true`（默认）时，危险操作需审批：
+
+- **TTY 交互终端**：运行期逐条弹出 `y/n` 确认（`run_shell`、写文件等高危动作须显式批准）。
+- **非交互（CI / 管道）**：无 TTY 时回退到白名单审批器——命中 `FH_SHELL_ALLOW` 的命令自动通过，其余拒绝并留痕。
+
+```bash
+fhcode "删除临时缓存并重建"      # TTY 下每条 shell 命令会询问；非 TTY 仅白名单命令可过
+```
+
+### 4.8 企业能力：权限 / 审计 / 多租户 / 配额（M4）
+
+企业模式**默认开启**（`FH_ENTERPRISE=false` 可关闭并退化为 M3 行为），身份由环境变量注入，便于容器与网关下发：
+
+```bash
+export FH_TENANT=acme        # 租户 ID（缺省 default）
+export FH_USER=wuchihong     # 用户标识（缺省系统用户名）
+export FH_ROLE=developer     # viewer | developer | operator | admin
+
+fhcode whoami                # 当前租户/用户/角色/隔离目录/今日用量
+fhcode policy                # 生效的 RBAC 策略与四角色矩阵
+fhcode audit --limit 20      # 审计记录（默认最近 20 条）
+fhcode audit verify          # 校验审计哈希链是否被篡改
+fhcode tenants               # 全部租户用量汇总（会话数/成本/审计条数）
+```
+
+**① 权限（RBAC + deny 优先）**
+
+| 角色 | 直接允许 | 需审批 | 单任务上限 |
+| --- | --- | --- | --- |
+| `viewer` | `read_file` `list_dir` `grep` | — | $0.1 |
+| `developer` | 上述 + `write_file` `edit_file` `run_tests` `build_check` | `run_shell` | $1 |
+| `operator` | 全部 | `run_shell` | $5 |
+| `admin` | 全部 | `run_shell` | 不限 |
+
+判定顺序为 **危险命令黑名单 → 敏感路径黑名单 → 沙箱越界 → 角色矩阵 → shell 白名单**。前三条 **deny 优先，admin 也无法绕过**：`rm -rf /`、`mkfs`、`curl | sh` 等 23 条危险命令，`.env`、`.ssh/id_rsa`、`.npmrc`、`.kube/config` 等 11 类敏感路径一律拒绝并留痕。
+
+策略可用 `policy.json` 覆盖（全局 `<FH_HOME>/policy.json` → 租户 `<租户目录>/policy.json` → `FH_POLICY` 内联 JSON），**黑名单取并集，只能加严不能放松**。
+
+**② 审计（防篡改哈希链）**
+
+每条审计记录携带 `prevHash` 与自身 `sha256`，形成链式结构；任何改写、删除、插入都会导致链断裂：
+
+```bash
+$ fhcode audit verify
+✅ 审计链完整：3 条记录，哈希链自洽未被篡改。
+# 若被篡改：
+❌ 审计链校验失败：共 5 条，断点在第 3 条
+   记录内容被篡改：hash 不自洽（期望 8b3a6990664e…）
+```
+
+记录内容自动脱敏（`apiKey=` / `Bearer` / `sk-xxx` → `***`），审计写入失败时**工具执行一律拒绝**——宁可不做，不可无痕。
+
+**③ 多租户（物理目录隔离）**
+
+```
+<FH_HOME>/tenants/<tenantId>/
+├── sessions/     会话检查点与事件日志
+├── audit/        审计链（按月切分 audit-YYYY-MM.jsonl）
+├── goals/        /goal 产物
+└── policy.json   租户级策略覆盖（可选）
+```
+
+租户 ID 经 `^[A-Za-z0-9._-]{1,64}$` 校验，杜绝 `../` 穿越；租户之间 `sessions` / `audit` / `goals` 完全互不可见。默认租户在旧版目录存在时自动沿用，升级不丢历史会话。
+
+**④ 配额（成本熔断）**
+
+- **单任务**：超过角色 `maxCostUsd` 立即中止，可调高后 `resume` 续跑。
+- **租户日预算**：`FH_TENANT_BUDGET_USD`（或策略 `tenantDailyBudgetUsd`）在任务启动前 fail-fast，**不产生任何模型费用**：
+
+```bash
+$ FH_TENANT_BUDGET_USD=0.30 fhcode "超预算任务"
+[飞虹 Code] 运行失败 (QUOTA_EXCEEDED): 租户 acme 今日成本 $0.420000 已达上限 $0.3，任务被拒绝。
+```
+
+---
+
+## 五、命令参考
+
+| 命令 | 说明 |
+| --- | --- |
+| `fhcode` | 进入交互式 REPL（逐条需求） |
+| `fhcode "<需求>"` | 单命令模式执行一条需求 |
+| `fhcode --parallel "<需求>"` | 多子代理并行（git worktree 隔离） |
+| `fhcode /plan "<目标>"` | 生成结构化实现计划（只读） |
+| `fhcode /grill [路径]` | 红队式代码审查（只读，默认当前目录） |
+| `fhcode /goal "<目标>"` | 分解并保存高层目标到 `~/.feihong-code/goals` |
+| `fhcode sessions` | 列出历史会话检查点（状态/迭代/成本/文件数） |
+| `fhcode resume <id>` | 从检查点恢复并续跑中断的任务 |
+| `fhcode diff [<id>]` | 展示会话作用域（或当前工作区）变更 |
+| `fhcode rollback <id> [--yes]` | 回滚会话改动（危险操作，需 `--yes` 确认） |
+| `fhcode whoami` | 当前租户 / 用户 / 角色 / 隔离目录 / 今日用量（M4） |
+| `fhcode policy` | 查看生效 RBAC 策略与角色矩阵（M4） |
+| `fhcode audit [--limit N]` | 查看审计记录，默认最近 20 条（M4） |
+| `fhcode audit verify` | 校验审计哈希链完整性（M4） |
+| `fhcode tenants` | 列出全部租户与用量汇总（M4） |
+| `fhcode model-stats` | 查看各模型性能统计（M6） |
+| `fhcode experiences` | 列出经验库（M6） |
+| `fhcode code-write "<目标>"` | 自主编写代码：规划→编写→测试→审查→修复（M8） |
+| `fhcode quality-gate [路径]` | 质量门禁审查：安全+质量+测试覆盖（M8） |
+| `fhcode self-improve` | 自我改进统计与历史（M8） |
+| `fhcode swe "<目标>"` | 全自动软件工程 Agent：读仓库→拆解→实现+验证+自愈→报告（M9，支持 `--max-iterations` 等） |
+| `fhcode --version` / `-v` | 显示版本与署名 |
+| `fhcode --help` / `-h` | 显示帮助 |
+
+> 未配置 `FH_PROVIDERS`（或 `FH_OFFLINE=true`）时自动离线模式。
+
+---
+
+## 六、工具系统
+
+| 分类 | 工具 | 说明 |
+| --- | --- | --- |
+| 文件 | `read_file` / `write_file` / `edit_file` / `list_dir` | 沙箱内读写，防 `../` 穿越 |
+| 搜索 | `grep` | 代码内容递归检索（忽略 node_modules/.git） |
+| Shell | `run_shell` | 白名单 + 危险拦截 + 审批 |
+| 验证 | `run_tests` / `build_check` | 运行测试套件 / 构建校验（默认 `npm test` / `npm run build`） |
+
+所有工具入参经 **zod 校验**，错误归一为 `ToolError`；文件操作一律限制在 `cwd` 沙箱内。
+
+---
+
+## 七、安全模型
+
+1. **路径沙箱**：`safeJoin` 校验每个文件路径不得超出 `cwd`，杜绝 `../` 越权。
+2. **Shell 白名单**：`run_shell` 仅在命令首词命中 `FH_SHELL_ALLOW` 时放行；非交互 CLI 下，命中白名单者由默认审批器自动通过，其余拒绝并留痕。
+3. **密钥脱敏**：日志按 key 名（`apikey|secret|token|...`）将值替换为 `[REDACTED]`，且不回显完整 API key。
+4. **审批拦截**：`FH_REQUIRE_APPROVAL=true`（默认）时，危险操作需审批通道；**TTY 交互终端逐条弹 `y/n` 确认**，非交互（CI/管道）则回退白名单审批器——命中 `FH_SHELL_ALLOW` 自动通过、其余拒绝并留痕。
+5. **`.env` 不入库**：已被 `.gitignore` 排除；`package.json` 的 `files` 白名单确保 `npm publish` 不会携带 `.env`。
+6. **RBAC 策略引擎（M4）**：角色-工具矩阵 + **deny 优先**的危险命令 / 敏感路径黑名单，`admin` 亦不可绕过；策略只能被下级配置**加严**。
+7. **防篡改审计（M4）**：全量动作（allow/deny/approved/rejected）写入 sha256 哈希链，`fhcode audit verify` 可定位篡改位置；**审计写失败即拒绝执行**。
+8. **租户隔离与配额（M4）**：会话 / 审计 / 目标物理分目录，租户 ID 严格校验；单任务成本熔断 + 租户日预算 fail-fast。
+
+> M4 起守卫（guard）是**唯一权威闸门**：策略判定、人工审批、审计留痕都在工具执行前一次性完成，工具层不再重复弹审批，避免"审批打架"与重复询问。
+
+---
+
+## 八、配置参考（.env）
+
+| 变量 | 说明 | 默认 / 示例 |
+| --- | --- | --- |
+| `FH_HOME` | 应用主目录（可缺省） | `~/.feihong-code` |
+| `FH_LOG_DIR` | 会话日志目录 | `~/.feihong-code/sessions` |
+| `FH_PROVIDERS` | 模型供应商 JSON 数组 | 见 `docs/配置参考.md` |
+| `FH_MODEL_STRATEGY` | 路由策略：`cost`/`capability`/`latency` | `cost` |
+| `FH_BUDGET_USD` | 单任务预算上限（美元，仅告警不阻断） | `0.5` |
+| `FH_SHELL_ALLOW` | shell 白名单（逗号分隔，命中即免审批） | `git,npm,node,ls,cat` |
+| `FH_REQUIRE_APPROVAL` | 危险操作是否需审批 | `true` |
+| `FH_ENTERPRISE` | 企业模式开关（权限/审计/多租户/配额） | `true` |
+| `FH_TENANT` | 租户 ID（决定隔离目录） | `default` |
+| `FH_USER` | 用户标识（写入审计 actor） | 系统用户名 |
+| `FH_ROLE` | 角色：`viewer`/`developer`/`operator`/`admin` | `developer` |
+| `FH_TENANT_BUDGET_USD` | 租户日成本上限（0 = 不限） | `0` |
+| `FH_POLICY` | 内联策略 JSON（优先级最高） | 未设置 |
+
+> 完整配置说明见 [`docs/配置参考.md`](./docs/配置参考.md)。`.env` 含密钥，切勿提交。
+
+---
+
+## 九、架构（feature-first 分层）
+
+```
+src/
+├── cli/          入口、参数解析、REPL、运行时装配（run.ts）
+├── shared/       基础设施：config / errors / logger / types
+├── agent/        Orchestrator（ReAct 循环）/ Planner / Prompts / 并行编排 / 子代理
+├── tools/        工具实现（file / shell / search / verify）+ registry + 安全沙箱
+├── models/       模型路由 ModelRouter + providers（openai-compatible / ollama / mock）
+├── runtime/      事件日志 EventLog、会话状态 SessionStore、会话检查点持久化、git diff/rollback、git worktree 隔离
+├── enterprise/   M4 企业能力：tenant（多租户）/ policy（RBAC）/ audit（哈希链）/ quota（配额）/ guard（守卫）
+└── skills/       高级技能：/plan /grill /goal
+```
+
+**单命令执行流**：`CLI → Orchestrator → ModelRouter（选模型）→ 模型返回工具调用 → ToolRegistry（校验+执行）→ 结果回填模型 → 循环至完成 → 每轮落盘检查点 + 事件日志归档`。
+
+**并行执行流**：`CLI --parallel → 分解目标 → 为每子任务创建 git worktree（独立分支）→ Promise.allSettled 并发子代理 → 收集结果 → 强制清理 worktree`。
+
+**恢复执行流（M3）**：`sessions 列出检查点 → resume <id> 加载检查点重建对话 → 续跑 ReAct 循环 → 产出最终结果`；`diff/rollback` 基于检查点的 touchedFiles 做会话作用域的 git 比对与回退。
+
+**企业管控流（M4）**：`环境注入身份（tenant/user/role）→ 加载策略（默认→全局→租户→内联）→ 配额前置校验 → 每次工具调用经 guard：策略判定 → 必要时人工审批 → 写入哈希链审计 → 放行/拒绝`。
+
+> 架构详解见 [`docs/架构与API.md`](./docs/架构与API.md)。
+
+---
+
+## 十、开发
+
+```bash
+npm install
+npm run build      # tsc 编译到 dist/
+npm run dev        # tsx 直接跑源码（免构建）
+npm run typecheck  # 仅类型检查
+npm run verify:m4  # M4 企业能力断言套件（41 项，全离线）
+npm run verify     # typecheck + build + M4 断言，一条命令过全链路
+node dist/cli/index.js --version
+```
+
+### 工程规范（全栈铁律）
+
+1. 边界必须校验（CLI 参数 / 模型响应 / 工具入参 → zod）。
+2. 集中配置（`shared/config.ts`，启动校验、fail-fast、懒加载）。
+3. 类型化错误（`AppError` 子类，禁止裸 `throw`）。
+4. 结构化日志（JSON + `runId`，密钥脱敏）。
+5. 单一可信源（行为以 `runtime/event-log` 为准）。
+
+---
+
+## 十一、部署
+
+- **npm 全局**：`npm install -g .` 或发布后 `npm install -g feihong-code`。
+- **Docker**：见 `Dockerfile`（多阶段，已含 `git` 以支持 `--parallel`）。
+- **CI**：见 `.github/workflows/ci.yml`，三条流水线全离线、零 Secrets：
+  - `build`：Node 18/20/22 矩阵 → typecheck → 编译 → 离线端到端 → 只读技能；
+  - `enterprise`：M4 断言套件（41 项）+ CLI 企业命令冒烟 + **租户隔离断言**（beta 租户不得读到其它租户会话）；
+  - `security`：`npm pack` 白名单校验（禁止 `.env`/`src`/`policy.json` 入包）+ 仓库明文密钥扫描 + `npm audit`。
+- **发布**：`npm publish` 仅携带 `files` 白名单（dist + 文档），密钥安全。
+- 部署细节见 [`docs/部署指南.md`](./docs/部署指南.md)，企业落地见 [`docs/企业部署与合规.md`](./docs/企业部署与合规.md)。
+
+---
+
+## 十二、里程碑进度
+
+> **📌 版本号与里程碑是两套编号，相互解耦**
+>
+> - **M0→M9.1** 是**能力里程碑**（工程开发阶段编号）：2026-08 上旬全部交付后**冻结，不再扩展**。它回答"哪些核心能力已建成"。
+> - **7.x** 是**产品化成熟度版本号**（SemVer）：M 里程碑交付完成后（v7.0.0 起）进入持续产品化迭代——桌面版、Web 控制台、SWE-bench 差分验证 harness、企业治理、自进化经验库、语音编程等均以 7.x 版本号发布。它回答"产品打磨到了什么程度"。
+> - 因此**不存在"版本 7.6 却只有 M9"的矛盾**：M 编号停止增长是设计使然，能力演进体现在 7.x 的次版本号中。
+
+| 里程碑 | 内容 | 状态 |
+| --- | --- | --- |
+| **M0 脚手架** | 工程结构、shared 基础设施、CLI 入口 | ✅ 完成 |
+| **M1 P0 闭环** | 模型路由、文件/shell 工具、REPL、事件日志、离线闭环验证 | ✅ 完成 |
+| **M2 多子代理** | `git worktree` 隔离、并行子代理、`/plan` `/grill` `/goal` 技能 | ✅ 完成 |
+| **M2 真实联调（B）** | 接入 OpenAI 兼容真实模型（Agnes），ReAct 闭环跑通 | ✅ 完成 |
+| **M3 恢复与审计** | `sessions`/`resume` 断点续跑、`diff`/`rollback` 会话作用域变更管理、交互式审批流 | ✅ 完成 |
+| **M4 企业级** | RBAC 策略引擎、防篡改审计链、多租户隔离与配额、三流水线 CI | ✅ 完成 |
+| **M5 Web 控制台** | 只读观测面板（租户/策略/审计/配额可视化）| ✅ BETA |
+| **M6 自我进化** | 自愈循环、上下文压缩、经验学习、模型性能追踪 | ✅ 完成 |
+| **M7 编程能力** | 代码分析/生成/审查/仓库理解/测试生成 | ✅ 完成 |
+| **M8 自主迭代** | CodeWriter 六步闭环、QualityGate、SelfImprover | ✅ 完成 |
+| **M9 全自动 SWE** | 仓库读取→任务拆解→实现+验证→自愈→报告 | ✅ 完成 |
+| **M9.1 真实模型** | 三级 provider 接入、exec 纪律强化、mock 全链路验证 | ✅ 完成 |
+
+---
+
+## 十三、文档导航
+
+> **AI Agent 快速上手**
+- [AGENT-GUIDE.md](./AGENT-GUIDE.md) — 面向 AI Agent 的使用指南（环境、配置、工具契约）
+- [tool-schema.json](./tool-schema.json) — 所有工具的 JSON Schema 定义
+- [GEO-AAO-STRATEGY.md](./GEO-AAO-STRATEGY.md) — 生成式引擎优化与 Agent 优化策略
+
+> **权威文档（稳定版首选）**
+- [技术说明书](./docs/技术说明书.md) — 架构、企业能力技术细节、数据契约、CLI/Web API、部署架构、安全模型、构建验证
+- [使用说明书](./docs/使用说明书.md) — 安装、快速上手、命令总览、核心工作流、企业版/Web 控制台使用、配置、排错
+
+> **补充参考**
+- [用户手册](./docs/用户手册.md) — 各命令详解、工具说明、审批与安全、最佳实践
+- [配置参考](./docs/配置参考.md) — 全部 `FH_*` 环境变量与 `FH_PROVIDERS` 详解
+- [架构与 API](./docs/架构与API.md) — 分层、编排循环、模型路由、工具协议、事件日志
+- [部署指南](./docs/部署指南.md) — npm / Docker / CI / 发布 / 密钥安全
+- [企业部署与合规](./docs/企业部署与合规.md) — RBAC 角色设计、审计取证、多租户方案、配额治理（M4）
+- [常见问题与故障排查](./docs/常见问题与故障排查.md) — FAQ 与排错
+- [产品开发文档](./docs/产品开发文档.md) — 需求/里程碑/设计决策（演进稿）
+
+> 稳定部署产物：`Dockerfile`、`docker-compose.yml`、`install.sh`、`CHANGELOG.md`（见仓库根目录）。
+
+---
+
+
+---
+
+## 🤝 社区支持
+
+关注飞虹智 klAI 动态，获取最新开源项目更新与技术教程：
+
+- 🏠 官网与开源矩阵：[https://www.klai.top/opensource.html](https://www.klai.top/opensource.html)
+- 🤖 AI Agent 入口：[https://www.klai.top/openclaw.html](https://www.klai.top/openclaw.html)
+
+加入 **飞虹智企微小助手**，获取：
+- 技术答疑与部署指导
+- 开源项目更新通知
+- 本地化服务预约（泉州地区）
+- 企业 AI 数字化咨询
+
+---
+
+*晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹*
+
+## 十四、版权与署名
+
+- **公司**：晋江市飞虹智科技企业管理有限公司
+- **中心**：飞扬企源研发中心
+- **负责人**：吴赐虹
+
+© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+Released under the [MIT License](./LICENSE).
+
+---
+
+## 组织与署名
+
+<!-- FYQY-ENTITY-BLOCK v1 -->
+
+**公司**：晋江市飞虹智科技企业管理有限公司
+**中心**：飞扬企源研发中心
+**负责人**：吴赐虹
+
+- 官网：https://www.klai.top
+- 知识库：https://kb.klai.top
+- 开源矩阵：https://github.com/wch887292
+- 实体权威声明（机器可读）：https://www.klai.top/entity.jsonld
+
+> 本项目版权归 晋江市飞虹智科技企业管理有限公司 所有，由 飞扬企源研发中心 研发交付。