feihong-code 0.2.1

package/docs//344/274/201/344/270/232/351/203/250/347/275/262/344/270/216/345/220/210/350/247/204.md

@@ -0,0 +1,267 @@
+# 飞虹 Code — 企业部署与合规指南（M4）
+
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+本文面向**企业管理员 / 平台工程 / 安全合规**角色，说明如何把飞虹 Code 以受控方式部署到团队、部门乃至多客户（多租户）环境中。
+
+---
+
+## 一、能力总览
+
+| 维度 | 能力 | 关键命令 |
+| --- | --- | --- |
+| 身份 | 租户 / 用户 / 角色由环境注入，容器与网关友好 | `fhcode whoami` |
+| 权限 | RBAC 角色矩阵 + deny 优先黑名单 + 沙箱越界拦截 | `fhcode policy` |
+| 审计 | sha256 哈希链、脱敏、按月切分、可验证 | `fhcode audit` / `fhcode audit verify` |
+| 隔离 | 会话 / 审计 / 目标物理分目录 | `fhcode tenants` |
+| 成本 | 单任务熔断 + 租户日预算 fail-fast | `FH_TENANT_BUDGET_USD` |
+| 交付 | 三条全离线 CI 流水线 + 发布包白名单 | `npm run verify` |
+
+企业模式默认开启。若需退回社区版行为（无租户、无审计链、无 RBAC）：`FH_ENTERPRISE=false`。
+
+---
+
+## 二、身份模型
+
+```bash
+export FH_TENANT=acme          # 租户 ID：^[A-Za-z0-9._-]{1,64}$
+export FH_USER=wuchihong       # 用户标识，写入审计 actor
+export FH_ROLE=developer       # viewer | developer | operator | admin
+```
+
+- 三者均可由**容器编排 / SSO 网关 / CI Runner** 注入，CLI 自身不做认证——认证是上游职责，飞虹 Code 只负责**授权与留痕**。
+- `FH_TENANT` 非法（含 `../`、超长、特殊字符）时启动即报 `TENANT_ID_INVALID`，杜绝路径穿越。
+- `FH_ROLE` 非法值直接报 `ROLE_INVALID`，不做"降级容错"——权限问题不允许猜。
+
+### 推荐角色分配
+
+| 场景 | 角色 | 理由 |
+| --- | --- | --- |
+| 代码审查 / 只读排障 | `viewer` | 仅能读取与检索，任何写入都被拒 |
+| 日常研发 | `developer` | 可写代码与跑测试，shell 需审批 |
+| 值班 / 运维处置 | `operator` | 全工具可用，shell 仍需审批，成本上限 $5 |
+| 平台管理员 | `admin` | 无成本上限，但**危险命令与敏感路径依旧拒绝** |
+
+---
+
+## 三、权限策略
+
+### 3.1 判定顺序（deny 优先）
+
+```
+1) 危险 shell 命令黑名单   → deny（admin 也拦）
+2) 敏感路径黑名单          → deny
+3) 沙箱越界（逃出 cwd）    → deny
+4) 角色-工具矩阵           → deny / approval / allow
+5) shell 白名单            → allow（否则 approval）
+```
+
+前三条是**硬底线**，不受角色影响，也不能被人工审批放行——批准了也不执行。
+
+### 3.2 内置黑名单
+
+- **危险命令（23 条）**：`rm -rf /`、`rm -rf ~`、`mkfs`、`dd if=`、fork 炸弹 `:(){`、`shutdown`、`reboot`、`format `、`del /s`、`rd /s`、`chown -R root`、`curl | sh`、`wget | sh`、`iptables -F`、`reg delete`、`history -c`、`shred ` 等。
+- **敏感路径（11 类）**：`.env`、`.git/config`、`.git/hooks`、`.npmrc`、`.ssh`、`id_rsa`、`id_ed25519`、`credentials`、`.aws`、`.kube/config`、`shadow`。
+
+### 3.3 策略覆盖（只能加严）
+
+优先级从低到高：
+
+```
+DEFAULT_POLICY
+  → <FH_HOME>/policy.json                 全局策略
+  → <FH_HOME>/tenants/<租户>/policy.json  租户策略
+  → FH_POLICY 内联 JSON                    临时覆盖（CI / 调试）
+```
+
+**黑名单取并集**——下级配置只能新增禁止项，无法删除上级的禁止项。这条设计确保"租户自定义策略"永远不能成为提权通道。
+
+`policy.json` 示例：
+
+```json
+{
+  "roles": {
+    "developer": { "maxCostUsd": 0.25, "approvalTools": ["run_shell", "write_file"] }
+  },
+  "denyShell": ["npm publish", "docker push", "kubectl delete"],
+  "denyPaths": ["config/secrets", "deploy/prod"],
+  "tenantDailyBudgetUsd": 20
+}
+```
+
+### 3.4 审批通道
+
+| 环境 | 行为 |
+| --- | --- |
+| TTY 交互终端 | 逐条弹出 `y/n`，用户显式批准才执行 |
+| 非交互（CI / 管道 / 守护进程） | 回退白名单审批器：命中 `FH_SHELL_ALLOW` 自动通过，其余拒绝并留痕 |
+
+> **守卫是唯一权威闸门**：策略判定、审批、审计在工具执行前一次性完成，工具层不会二次弹审批，杜绝重复询问与决策打架。
+
+---
+
+## 四、审计与取证
+
+### 4.1 存储
+
+```
+<FH_HOME>/tenants/<租户>/audit/audit-YYYY-MM.jsonl
+```
+
+append-only、按月切分、同步写入（不缓冲，进程崩溃不丢记录）。
+
+### 4.2 记录结构
+
+```json
+{
+  "seq": 2,
+  "ts": "2026-08-10T06:41:43.118Z",
+  "tenantId": "acme",
+  "userId": "wuchihong",
+  "role": "developer",
+  "runId": "2d1e3188-...",
+  "action": "tool:write_file",
+  "resource": "demo-output.txt",
+  "decision": "allow",
+  "reason": "rbac.allow — 角色 developer 允许调用 write_file",
+  "prevHash": "…",
+  "hash": "…"
+}
+```
+
+`decision` 取值：`allow` / `deny` / `approved`（人工批准）/ `rejected`（人工拒绝或无审批通道）/ `info`（会话起止等）。
+
+覆盖动作：`session:start`、`session:end`、`session:rollback`、`skill:goal`、`quota:block`、`tool:<工具名>`。
+
+### 4.3 防篡改验证
+
+```bash
+fhcode audit verify
+```
+
+链式校验三件事：**seq 连续**（防删除/插入）、**prevHash 衔接**（防重排）、**hash 自洽**（防内容改写）。任一失败会定位到具体条目：
+
+```
+❌ 审计链校验失败：共 5 条，断点在第 3 条
+   记录内容被篡改：hash 不自洽（期望 8b3a6990664e…）
+```
+
+退出码为 `2`，可直接接入监控告警：
+
+```bash
+fhcode audit verify || alertmanager-cli fire --name fhcode-audit-tampered
+```
+
+### 4.4 脱敏
+
+`resource` / `reason` 写入前统一脱敏：`apiKey=` / `secret=` / `token=` / `password=` / `Authorization: Bearer` 的值替换为 `***`，`sk-xxxxx` 形态密钥替换为 `sk-***`。**审计日志本身不会成为泄密源**。
+
+> 合规提示：审计目录建议单独挂载只读快照卷或定期归档至 WORM 存储；哈希链只能证明"是否被改"，不能阻止有权限者删除整个文件，物理保全仍需存储层配合。
+
+---
+
+## 五、多租户
+
+### 5.1 目录布局
+
+```
+<FH_HOME>/
+├── policy.json                     全局策略（可选）
+└── tenants/
+    ├── acme/
+    │   ├── sessions/               会话检查点 + 事件日志
+    │   ├── audit/                  审计链
+    │   ├── goals/                  /goal 产物
+    │   └── policy.json             租户策略（可选）
+    └── beta/
+        └── …
+```
+
+`sessions` / `resume` / `diff` / `rollback` / `audit` / `goal` 全部在当前租户目录内操作，**跨租户不可见**。
+
+### 5.2 用量汇总
+
+```bash
+$ fhcode tenants
+租户用量汇总:
+  租户ID                会话数   累计成本      审计条数   最近活跃
+  beta                     1   $  0.000000         3   2026-08-10T06:42:00.496Z
+  acme                     2   $  0.420000         6   2026-08-10T06:41:59.599Z
+```
+
+统计不反序列化整份对话（仅正则提取 `costUsd` / `updatedAt`），万级会话下依然秒回。
+
+### 5.3 升级兼容
+
+默认租户（`default`）在 `tenants/default` 尚未创建、而旧版 `<FH_HOME>/sessions` 存在时，会自动继续使用旧目录——**从 M3 升级到 M4 不丢历史会话**。
+
+### 5.4 部署形态建议
+
+| 形态 | 做法 | 适用 |
+| --- | --- | --- |
+| 单机多租户 | 同一 `FH_HOME`，靠 `FH_TENANT` 分目录 | 内部多团队 |
+| 容器一租户一实例 | 每租户独立容器 + 独立卷，`FH_TENANT` 与卷同名 | 对隔离要求高 / 对外服务 |
+| CI 每次任务一租户 | `FH_TENANT=ci-${{ github.run_id }}` | 流水线可追溯，任务间零串扰 |
+
+---
+
+## 六、成本治理
+
+| 层级 | 配置 | 行为 |
+| --- | --- | --- |
+| 单任务 | 角色 `maxCostUsd` | 达到上限立即中止本次任务，检查点保留，可调高后 `resume` 续跑 |
+| 租户日预算 | `FH_TENANT_BUDGET_USD` 或策略 `tenantDailyBudgetUsd` | 任务**启动前** fail-fast（`QUOTA_EXCEEDED`），不产生任何模型调用费用 |
+
+统计口径：该租户 `sessions` 目录下 `updatedAt` 为当天（UTC）的检查点 `costUsd` 之和。拒绝时同步写入 `quota:block` 审计记录。
+
+```bash
+$ FH_TENANT_BUDGET_USD=0.30 fhcode "超预算任务"
+[飞虹 Code] 运行失败 (QUOTA_EXCEEDED): 租户 acme 今日成本 $0.420000 已达上限 $0.3，任务被拒绝。
+```
+
+---
+
+## 七、CI 集成
+
+`.github/workflows/ci.yml` 三条流水线，**全程离线、零 Secrets**，fork PR 也能安全跑完：
+
+| Job | 内容 |
+| --- | --- |
+| `build` | Node 18 / 20 / 22 矩阵 → typecheck → 编译 → 离线端到端 → `/plan` `/grill` |
+| `enterprise` | `scripts/verify-m4.mjs` 41 项断言 + CLI 企业命令冒烟 + **租户隔离断言**（beta 租户读不到其它租户会话即通过） |
+| `security` | `npm pack --dry-run` 白名单校验（`.env`/`src`/`policy.json` 出现即失败）+ 仓库明文密钥扫描 + `npm audit` |
+
+本地一条命令跑齐：
+
+```bash
+npm run verify     # typecheck + build + M4 断言套件
+```
+
+### 断言覆盖（41 项）
+
+1. RBAC 角色矩阵（5 项）
+2. deny 优先危险动作（4 项）
+3. 策略文件覆盖与"只能加严"（4 项）
+4. 审计哈希链：写入 / 校验 / 脱敏 / 篡改定位 / 删除检测（7 项）
+5. 守卫接入工具链：拦截、放行、审批一次、危险命令批准也拒（11 项）
+6. 多租户：非法 ID、目录隔离、用量统计、不串台（7 项）
+7. 配额：当日统计、超限、充足（3 项）
+
+---
+
+## 八、上线检查清单
+
+- [ ] `FH_HOME` 指向持久卷，`tenants/` 已纳入备份策略
+- [ ] `FH_TENANT` / `FH_USER` / `FH_ROLE` 由上游身份系统注入，不由用户自填
+- [ ] 生产角色最小化：默认 `developer`，`admin` 仅限平台管理员
+- [ ] `policy.json` 已按业务补充禁止项（如 `kubectl delete`、生产配置目录）
+- [ ] `FH_TENANT_BUDGET_USD` 已设置，避免失控消耗
+- [ ] `FH_SHELL_ALLOW` 仅包含确需免审批的命令（建议 `git,npm,node,ls,cat`）
+- [ ] 定时任务执行 `fhcode audit verify`，失败即告警
+- [ ] 审计目录已归档至只读 / WORM 存储
+- [ ] `.env` 未入库（`git check-ignore .env` 应有输出）
+- [ ] 发布前执行 `npm pack --dry-run` 确认无密钥与源码泄漏
+
+---
+
+© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹

package/docs//344/275/277/347/224/250/350/257/264/346/230/216/344/271/246.md

@@ -0,0 +1,358 @@
+# 飞虹 Code（fhcode）使用说明书
+
+> 本文为飞虹 Code 的**权威用户文档**，面向使用者与运维人员。技术细节见《技术说明书》。
+> 版本 0.1.0（稳定版，含 M4 企业能力 + M5 Web 控制台 BETA + M6 自我进化 + M7 编程能力 + M8 自主迭代）。
+
+**署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+---
+
+## 1. 产品简介
+
+飞虹 Code（`fhcode`）是终端 AI 编程智能体。给它一个"目标"，它会自动规划、调用工具、反思并完成；支持多子代理并行、会话恢复与审计。企业版额外提供权限管控、防篡改审计、多租户隔离与成本治理，并可通过 Web 控制台可视化运维。
+
+---
+
+## 2. 安装
+
+### 环境要求
+- Node.js **≥ 18**（推荐 20 LTS）
+- 操作系统：Windows / macOS / Linux
+
+### 方式一：npm 全局安装（推荐）
+```bash
+npm install -g feihong-code
+fhcode --help
+```
+
+### 方式二：源码构建
+```bash
+git clone <repo> && cd feihong-code
+npm install
+npm run build
+node dist/cli/index.js --help
+```
+
+### 方式三：Docker（稳定部署推荐）
+```bash
+docker build -t feihong-code .
+docker run -p 8080:8080 -e FH_WEB_TOKEN=你的强随机令牌 feihong-code serve
+# 或一键编排：
+FH_WEB_TOKEN=你的强随机令牌 docker compose up -d
+```
+
+### 方式四：安装脚本
+```bash
+./install.sh
+```
+
+---
+
+## 3. 快速上手
+
+### 第一条目标（离线可用）
+```bash
+fhcode "创建一个说明文件 README-demo.md，写一句话介绍本项目"
+```
+未配置模型时自动进入**离线模式**（用本地 mock 完成闭环，成本恒为 0），适合体验与 CI。
+
+### 接入真实模型
+在项目根目录创建 `.env`（已被 gitignore，不会入库）：
+```
+FH_API_KEY=sk-你的密钥
+FH_MODEL=你的模型名
+FH_BASE_URL=https://你的模型网关
+```
+真实模式会按用量计量成本；密钥仅存 `.env`，日志中一律脱敏。
+
+---
+
+## 4. 命令总览
+
+| 命令 | 说明 |
+|------|------|
+| `fhcode "目标"` | 运行单条目标 |
+| `fhcode /plan "需求"` | 生成实现规划 |
+| `fhcode /grill <路径>` | 代码评审 |
+| `fhcode /goal` | 目标模式 |
+| `fhcode sessions` | 列出会话检查点 |
+| `fhcode resume <id>` | 断点续跑 |
+| `fhcode diff [id]` | 会话作用域 diff |
+| `fhcode rollback <id> [--yes]` | 回滚被改文件（需确认） |
+| `fhcode whoami` | 身份与用量 |
+| `fhcode policy` | 权限矩阵 |
+| `fhcode audit [--limit N]` | 审计链（脱敏） |
+| `fhcode audit verify` | 校验审计完整性 |
+| `fhcode tenants` | 租户用量汇总 |
+| `fhcode serve [--port 8080]` | 启动 Web 控制台（BETA） |
+| `fhcode model-stats` | 查看模型性能统计（M6） |
+| `fhcode experiences [路径]` | 列出经验库（M6） |
+| `fhcode code-write "<目标>"` | 自主编写代码（M8） |
+| `fhcode quality-gate [路径]` | 质量门禁审查（M8） |
+| `fhcode self-improve` | 自我改进统计（M8） |
+| `fhcode swe "<目标>"` | 全自动软件工程 Agent（M9）：读仓库→拆解→实现+验证+自愈→报告 |
+
+---
+
+## 5. 核心工作流
+
+### 5.1 目标运行
+```bash
+fhcode "为登录页增加手机号校验，并补充单元测试"
+```
+智能体将规划、编码、自检，最终给出答案与改动文件清单。
+
+### 5.2 规划与评审
+```bash
+fhcode /plan "实现支付回调验签"
+fhcode /grill src/payment/
+```
+
+### 5.3 会话恢复与审计（M3）
+任务中断后可续跑，不丢进度：
+```bash
+fhcode sessions          # 看有哪些检查点
+fhcode resume <id>       # 从断点继续
+fhcode diff <id>         # 本次会话改了哪些文件
+fhcode rollback <id>     # 回滚（未确认/非 git 仓库一律拒绝，防误删）
+```
+
+---
+
+## 6. 企业版使用（M4）
+
+### 6.1 启用企业模式
+默认在注入 guard 时启用；可用 `FH_ENTERPRISE=false` 关闭回到社区版。
+
+### 6.2 身份与用量
+```bash
+export FH_TENANT=acme
+export FH_USER=alice
+export FH_ROLE=developer
+fhcode whoami
+```
+输出当前租户、用户、角色、隔离目录与今日成本/预算。
+
+### 6.3 权限矩阵查看
+```bash
+fhcode policy
+```
+展示四角色（viewer/developer/operator/admin）的工具权限、危险命令与敏感路径黑名单。
+
+### 6.4 审计与取证
+```bash
+fhcode audit --limit 20     # 最近 20 条（脱敏）
+fhcode audit verify         # 校验哈希链是否被篡改，定位断点
+```
+
+### 6.5 多租户
+```bash
+fhcode tenants              # 所有租户用量汇总（物理目录隔离，互不串台）
+```
+数据落在 `<FH_HOME>/tenants/<tenantId>/`，租户 ID 经正则校验防穿越。
+
+### 6.6 成本治理
+- 单任务成本超限会**熔断**（终止并给答案）。
+- 租户日预算 `FH_TENANT_BUDGET_USD` 超限会**拒绝新任务**（HTTP 429 语义）并记入审计 `quota:block`。
+
+---
+
+## 7. Web 控制台（M5 BETA）
+
+> 仅观测、不执行，保持 guard 权威。
+
+### 启动
+```bash
+export FH_WEB_TOKEN=你的强随机令牌
+fhcode serve --port 8080
+```
+浏览器访问 `http://localhost:8080` 即可看到仪表盘（租户总览 / 策略矩阵 / 审计浏览+verify / 会话列表 / 配额进度条）。
+
+### 鉴权
+所有 `/api/*` 需 `Authorization: Bearer <FH_WEB_TOKEN>`；未设或错误令牌一律 401（fail-closed）。生产环境务必用强随机令牌并通过环境变量注入，勿用默认值。
+
+### 端点速查
+`/api/health`、`/api/tenants`、`/api/whoami`、`/api/policy`、`/api/audit`、`/api/audit/verify`、`/api/sessions`、`/api/quota`。
+
+---
+
+## 8. 自我进化能力（M6）
+
+### 模型性能统计
+```bash
+fhcode model-stats
+```
+查看各模型提供商的成功率、延迟、成本等性能指标，辅助模型路由决策。
+
+### 经验库管理
+```bash
+fhcode experiences [路径]
+```
+列出系统积累的经验记录，包括高效工具调用模式、错误规避模式等。指定路径可查看自定义经验库。
+
+---
+
+## 9. 自主编程能力（M8）
+
+### 自主编写代码
+```bash
+fhcode code-write "<目标描述>"
+```
+启动自主编写流程：规划→编写→测试生成→审查→修复→总结，全程自动化完成代码迭代。
+
+### 质量门禁审查
+```bash
+fhcode quality-gate [路径]
+```
+对指定目录进行质量门禁审查，包括安全审查、代码质量分析、测试覆盖检查，输出标准化报告。
+
+### 自我改进统计
+```bash
+fhcode self-improve
+```
+查看系统自我改进的统计信息，包括反思次数、成功率、平均耗时等指标。
+
+---
+
+## 9.1 全自动软件工程 Agent（M9）
+
+对标业界"全自动软件工程 Agent"：读取整个（大型）代码仓库 → 任务拆解规划 → 修改代码 → 执行命令、跑测试 → 验证结果，自主完成长链路开发。
+
+**核心四阶段（由 `src/agent/swe-agent.ts` 主编排）：**
+
+1. **仓库读取（repo-reader）**：扫描整个仓库（支持大型仓库，含文件数/体积限流与 `.gitignore` 解析），产出语言分布、关键文件、测试/构建命令、目录树与上下文串。
+2. **任务拆解（swe-planner）**：把目标拆解为有序、可独立验证的子任务（勘察→实现/修复/重构→测试→构建验证），每个子任务携带目标文件、验收标准、验证命令。
+3. **实现 + 验证（逐任务闭环）**：每个子任务委托 Orchestrator（ReAct + 工具系统 + 自愈）实现；随后自动跑构建与测试验证；**验证失败则把错误摘要注入下一轮实现，自我修复重试（最多 `--max-retries` 次）**。
+4. **报告（SweReport）**：汇总每个子任务状态、改动文件、验证结果，给出 overall（success/partial/failed）。
+
+**命令用法：**
+```bash
+# 全自动执行：读当前仓库 → 拆解 → 实现+验证+自愈 → 报告
+fhcode swe "新增用户登录接口并补充测试"
+
+# 指定仓库路径
+fhcode swe "重构工具模块" --repo /path/to/repo
+
+# 仅规划，不执行（适合先 review 计划）
+fhcode swe "重构工具模块" --plan-only
+
+# 仅跑验证，不实现（适合 CI 质量门禁）
+fhcode swe "检查构建与测试" --verify-only
+
+# 限制子任务数与自愈重试次数
+fhcode swe "实现新功能" --max-tasks 6 --max-retries 3
+
+# 限制每个子任务的模型推理轮数（真实模型建议 4~8，控制成本与耗时）
+fhcode swe "实现新功能" --max-iterations 6
+```
+
+**说明：**
+- 离线（`FH_OFFLINE=true` 或无任何模型配置）时，实现阶段由脚本化 Mock 驱动闭环，验证阶段跑真实构建/测试命令，可完整演示长链路。
+- 接入真实模型后，实现阶段的读/写/编辑/执行命令均由大模型自主决策。
+- `--plan-only` 与 `--verify-only` 非常适合在 CI 中分别做"计划评审"与"质量门禁"。
+- 真实模型接入方式见第 10 章《配置指南》；可用 `node scripts/verify-m9-real.mjs` 做"真实 HTTP provider 全链路"离线实测（不依赖任何外部模型）。
+
+---
+
+## 10. 配置指南
+
+### 真实模型接入（三种优先级，从高到低）
+
+**方式一：环境变量 `FH_PROVIDERS`（JSON 数组，最完整，可配多个供应商）**
+```bash
+export FH_PROVIDERS='[{"id":"deepseek","type":"openai-compatible","baseURL":"https://api.deepseek.com/v1","model":"deepseek-chat","apiKey":"sk-xxxx","tags":["code-gen","reasoning"]}]'
+```
+
+**方式二：配置文件 `fhcode.config.json`（项目根或 FH_HOME 下）**
+```json
+{
+  "models": {
+    "providers": [
+      { "id": "local", "type": "ollama", "baseURL": "http://localhost:11434", "model": "qwen2.5-coder:1.5b", "tags": ["code-gen","reasoning","local"] }
+    ]
+  }
+}
+```
+
+**方式三：单环境变量快速接入（无需写 JSON）**
+```bash
+export FH_MODEL_NAME=qwen2.5-coder:1.5b
+export FH_MODEL_TYPE=ollama            # 或 openai-compatible
+export FH_MODEL_BASE_URL=http://localhost:11434
+export FH_MODEL_API_KEY=               # openai-compatible 必填
+export FH_MODEL_TAGS=code-gen,reasoning
+```
+
+> 供应商类型：`ollama`（本地，零成本，数据不出机）或 `openai-compatible`（DeepSeek / 通义 / OpenRouter 等 OpenAI 协议接口）。
+> 标签必须含 `code-gen`，编排器才会把代码任务路由给它。网络可通 `api.deepseek.com`（需自备密钥）。
+
+### 常用环境变量
+| 变量 | 作用 |
+|------|------|
+| `FH_HOME` | 数据根目录 |
+| `FH_ENTERPRISE` | 企业模式（`false` 关） |
+| `FH_TENANT` / `FH_USER` / `FH_ROLE` | 租户/用户/角色 |
+| `FH_TENANT_BUDGET_USD` | 租户日预算 |
+| `FH_POLICY` | 策略 JSON 覆盖片段 |
+| `FH_WEB_PORT` / `FH_WEB_TOKEN` | Web 控制台端口/令牌 |
+| `FH_OFFLINE` | 强制离线（`true` 时忽略所有模型配置，使用 Mock） |
+| `FH_PROVIDERS` | 供应商 JSON 数组（方式一） |
+| `FH_CONFIG` | 指定配置文件路径 |
+| `FH_MODEL_NAME` / `FH_MODEL_TYPE` / `FH_MODEL_BASE_URL` / `FH_MODEL_API_KEY` / `FH_MODEL_TAGS` | 单环境变量快速接入（方式三） |
+| `FH_MODEL_STRATEGY` | 路由策略（`cost`/`capability`/`latency`，默认 `cost`） |
+| `FH_BUDGET_USD` | 单任务成本告警阈值 |
+
+---
+
+## 9. 常见问题与故障排查
+
+**Q1. 离线模式能做什么？**
+不请求模型，用本地 mock 完成闭环，适合体验、CI 与无网环境；成本恒为 0。
+
+**Q2. 危险命令被拒怎么办？**
+`rm -rf /`、`.env` 写入等命中黑名单会被直接拒绝（admin 也拦）。确属必要的运维操作请走受控流程，不要绕过 guard。
+
+**Q3. 配额超限（QUOTA_EXCEEDED）？**
+当日租户成本超过 `FH_TENANT_BUDGET_USD`。调高预算或次日再跑；`whoami` 可看已用/上限。
+
+**Q4. 审计校验失败（brokenAt）？**
+`audit verify` 返回断点行号，说明审计链在该处不连续或被篡改。检查该时间段的操作记录与文件权限。
+
+**Q5. 租户互相看得到会话？**
+不应发生。物理目录隔离 + ID 正则校验保障隔离；`tenants` 与 `sessions` 按租户作用域，CI 已做隔离断言。
+
+**Q6. 想关掉企业能力？**
+`FH_ENTERPRISE=false`，行为退回社区版（M3），无感降级。
+
+**Q7. Web 控制台起不来 / 401？**
+确认 `FH_WEB_TOKEN` 已设置且请求带 `Authorization: Bearer`；端口被占用换 `--port`。
+
+**Q8. 构建/编译被安全软件拦截？**
+本地 Windows 下 `tsc` 编译可能被 Defender 实时扫描短暂锁文件。属环境限制非代码问题；CI（GitHub Actions）是权威构建来源。
+
+**Q9. M8 自主编写功能如何使用？**
+通过 `fhcode code-write` 命令启动，系统会自动完成规划、编写、测试、审查、修复全流程。可使用 `quality-gate` 进行质量门禁检查。
+
+**Q10. 如何查看自我进化数据？**
+使用 `model-stats` 查看模型性能统计，使用 `experiences` 查看经验库，使用 `self-improve` 查看改进统计。
+
+---
+
+## 11. 安全与合规须知
+
+- 密钥仅存 `.env`（gitignore），不回显、不入库、日志脱敏。
+- 危险操作与敏感路径受 deny 优先策略保护；审批通道缺失即拒绝。
+- Web 控制台仅观测不执行，且 fail-closed 鉴权。
+- 发布包经白名单校验，`.env`/`src`/`.workbuddy` 不随 `npm publish` 泄露。
+- 审计链可验证、防篡改，满足合规取证基本要求。
+
+---
+
+## 12. 署名与版权
+
+- **公司**：晋江市飞虹智科技企业管理有限公司
+- **中心**：飞扬企源研发中心
+- **负责人**：吴赐虹
+- **许可证**：MIT
+
+*本文档与《技术说明书》共同构成飞虹 Code 稳定版（0.1.0）权威文档集。*