feihong-code 0.2.3 → 0.6.0

package/docs//351/203/250/347/275/262/346/214/207/345/215/227.md

@@ -1,165 +1,165 @@
-# 飞虹 Code 部署指南
-
-> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-
-覆盖：环境要求、源码/全局安装、Docker、CI、npm 发布、内网部署。
-
----
-
-## 1. 环境要求
-
-- **Node.js >= 18**（CI 与 Docker 均使用 18）。
-- **Git**：`--parallel` 依赖 `git worktree` 隔离，必须可用（Docker 镜像已内置）。
-- 仅需运行时依赖 `zod`（dev 依赖 typescript/tsx 仅构建期需要）。
-
----
-
-## 2. 从源码部署
-
-```bash
-git clone https://github.com/wch887292/feihong-code.git
-cd feihong-code
-npm install
-npm run build
-node dist/cli/index.js --version
-```
-
-或直接用脚本：`bash install.sh`（自动 install + build + 全局安装）。
-
----
-
-## 3. 全局安装
-
-```bash
-npm install -g .          # 从本地源码装为全局命令 fhcode
-fhcode --version
-```
-
-发布到 npm 后：`npm install -g feihong-code`。
-
----
-
-## 4. Docker 部署
-
-```bash
-docker build -t feihong-code .
-```
-
-运行（离线）：
-
-```bash
-docker run --rm feihong-code --version
-```
-
-运行（真实模型，挂载密钥与日志）：
-
-```bash
-docker run --rm \
-  -v "$PWD/.env:/app/.env" \
-  -v feihong-data:/data/feihong-code \
-  feihong-code "把 src/utils 的日期格式化抽成独立模块并补测试"
-```
-
-- 镜像为多阶段构建：构建期装全依赖编译 `dist`，运行期仅 `npm install --omit=dev` + 复制 `dist`。
-- 运行期已 `apk add git`，支持 `--parallel` 的 worktree 隔离。
-- `FH_HOME` 默认 `/data/feihong-code`，建议挂载为卷以持久化目标与日志。
-
----
-
-## 5. CI / CD（M4 三流水线）
-
-`.github/workflows/ci.yml` 在 `push`/`pull_request` 触发，**全离线、零 Secrets**，fork PR 安全。分为三个 job：
-
-### 5.1 `build` — 构建与离线闭环
-
-- Node 18 / 20 / 22 矩阵；
-- `npm run typecheck` → `npm run build`；
-- 离线冒烟：`FH_OFFLINE=true fhcode "..."`；只读技能 `/plan` `/grill` 校验；
-- 目的：保证多版本 Node 下可构建、社区闭环可跑。
-
-### 5.2 `enterprise` — 企业能力断言
-
-- 运行 `npm run verify:m4`（`scripts/verify-m4.mjs`，**41 项全离线断言**）：
-  - RBAC 矩阵(5) / deny 优先(4) / 策略覆盖(4) / 审计哈希链(7) / 守卫链路(11) / 多租户(7) / 配额(3)；
-- CLI 冒烟：`whoami` / `policy` / `audit` / `audit verify` / `tenants`；
-- **租户隔离断言**：用 `beta` 租户执行任务后，断言其 `sessions` 读不到 `acme` 租户会话（物理目录互不串台）。
-
-### 5.3 `security` — 发布安全
-
-- `npm pack --dry-run` 白名单校验：禁止 `.env` / `src` / `policy.json` / `.workbuddy` 进入产物；
-- 仓库明文密钥扫描（`git grep` 规则集）：杜绝 accidental secret 入库；
-- `npm audit`：依赖漏洞检查。
-
-> 本地完整校验：`npm run verify`（= typecheck + build + verify:m4）。
-
-- **企业模式不触碰密钥**：CI 仅做离线冒烟、企业断言与发布安全，**绝不**读取或回显任何 API key。
-- 真实联调建议在本地或带加密 secret 的受控环境执行，切勿把密钥明文写入 CI 日志。
-
----
-
-## 5.1 企业合规部署建议（M4）
-
-- **多租户物理隔离**：为每个客户/团队分配独立 `FH_TENANT`，数据落 `<FH_HOME>/tenants/<tenantId>/`，互不串台。
-- **最小角色**：日常运行用 `developer`；仅可信运维用 `operator`/`admin`；只读巡检用 `viewer`。
-- **日预算硬上限**：为每个租户设 `FH_TENANT_BUDGET_USD`，超限即 `QUOTA_EXCEEDED` 拒绝，防成本失控。
-- **审计留存**：`audit-YYYY-MM.jsonl` 建议只读挂载或异地备份，并周期性 `fhcode audit verify` 巡检哈希链完整性。
-- **关闭企业模式**：纯社区/单机使用可设 `FH_ENTERPRISE=false`，行为与 M3 一致、零额外开销。
-
----
-
-## 6. 发布到 npm
-
-`package.json` 已做好发布安全：
-
-- `files` 白名单：`dist` + `README.md` + `LICENSE` + `CONTRIBUTING.md` + `docs`（**绝不**包含 `.env` / `src` / `.workbuddy`）。
-- `prepublishOnly`: `npm run build`（发布前自动构建，保证 `dist` 最新）。
-- `.npmignore` 作为冗余保险。
-
-发布步骤：
-
-```bash
-npm run build
-npm version patch          # 或 minor/major
-npm publish                # 仅携带 files 白名单内容
-```
-
-> ⚠️ **密钥安全铁律**：`.env` 含 API key，已被 `.gitignore` 与 `files` 白名单双重排除，永远不会进入 npm 包或 Git 仓库。
-
----
-
-## 7. 内网 / 离线部署建议
-
-- **完全离线**：不配 `FH_PROVIDERS`，用内置 Mock 闭环（演示/回归）。
-- **本地模型**：配 Ollama 供应商（`type: ollama`，`baseURL: http://<内网IP>:11434`），数据不出本机。
-- **代理网关**：OpenAI 兼容供应商的 `baseURL` 可指向企业内网网关。
-- **日志合规**：`FH_LOG_DIR` 指向受控存储，按敏感数据留存策略管理。
-
----
-
-## 8. 作为后台服务（可选 systemd）
-
-```ini
-[Unit]
-Description=飞虹 Code Agent
-After=network.target
-
-[Service]
-WorkingDirectory=/opt/feihong-code
-ExecStart=/usr/bin/fhcode "守护型需求"
-Environment=FH_HOME=/var/lib/feihong-code
-Restart=on-failure
-
-[Install]
-WantedBy=multi-user.target
-```
-
----
-
-## 9. 升级与回滚
-
-- 升级：`git pull && npm install && npm run build`（或 `npm update -g feihong-code`）。
-- 回滚：npm 包使用 `npm install -g feihong-code@<旧版本>`；源码用 `git checkout <tag>` 后重建。
-
----
-
-© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+# 飞虹 Code 部署指南
+
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+覆盖：环境要求、源码/全局安装、Docker、CI、npm 发布、内网部署。
+
+---
+
+## 1. 环境要求
+
+- **Node.js >= 18**（CI 与 Docker 均使用 18）。
+- **Git**：`--parallel` 依赖 `git worktree` 隔离，必须可用（Docker 镜像已内置）。
+- 仅需运行时依赖 `zod`（dev 依赖 typescript/tsx 仅构建期需要）。
+
+---
+
+## 2. 从源码部署
+
+```bash
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build
+node dist/cli/index.js --version
+```
+
+或直接用脚本：`bash install.sh`（自动 install + build + 全局安装）。
+
+---
+
+## 3. 全局安装
+
+```bash
+npm install -g .          # 从本地源码装为全局命令 fhcode
+fhcode --version
+```
+
+发布到 npm 后：`npm install -g feihong-code`。
+
+---
+
+## 4. Docker 部署
+
+```bash
+docker build -t feihong-code .
+```
+
+运行（离线）：
+
+```bash
+docker run --rm feihong-code --version
+```
+
+运行（真实模型，挂载密钥与日志）：
+
+```bash
+docker run --rm \
+  -v "$PWD/.env:/app/.env" \
+  -v feihong-data:/data/feihong-code \
+  feihong-code "把 src/utils 的日期格式化抽成独立模块并补测试"
+```
+
+- 镜像为多阶段构建：构建期装全依赖编译 `dist`，运行期仅 `npm install --omit=dev` + 复制 `dist`。
+- 运行期已 `apk add git`，支持 `--parallel` 的 worktree 隔离。
+- `FH_HOME` 默认 `/data/feihong-code`，建议挂载为卷以持久化目标与日志。
+
+---
+
+## 5. CI / CD（M4 三流水线）
+
+`.github/workflows/ci.yml` 在 `push`/`pull_request` 触发，**全离线、零 Secrets**，fork PR 安全。分为三个 job：
+
+### 5.1 `build` — 构建与离线闭环
+
+- Node 18 / 20 / 22 矩阵；
+- `npm run typecheck` → `npm run build`；
+- 离线冒烟：`FH_OFFLINE=true fhcode "..."`；只读技能 `/plan` `/grill` 校验；
+- 目的：保证多版本 Node 下可构建、社区闭环可跑。
+
+### 5.2 `enterprise` — 企业能力断言
+
+- 运行 `npm run verify:m4`（`scripts/verify-m4.mjs`，**41 项全离线断言**）：
+  - RBAC 矩阵(5) / deny 优先(4) / 策略覆盖(4) / 审计哈希链(7) / 守卫链路(11) / 多租户(7) / 配额(3)；
+- CLI 冒烟：`whoami` / `policy` / `audit` / `audit verify` / `tenants`；
+- **租户隔离断言**：用 `beta` 租户执行任务后，断言其 `sessions` 读不到 `acme` 租户会话（物理目录互不串台）。
+
+### 5.3 `security` — 发布安全
+
+- `npm pack --dry-run` 白名单校验：禁止 `.env` / `src` / `policy.json` / `.workbuddy` 进入产物；
+- 仓库明文密钥扫描（`git grep` 规则集）：杜绝 accidental secret 入库；
+- `npm audit`：依赖漏洞检查。
+
+> 本地完整校验：`npm run verify`（= typecheck + build + verify:m4）。
+
+- **企业模式不触碰密钥**：CI 仅做离线冒烟、企业断言与发布安全，**绝不**读取或回显任何 API key。
+- 真实联调建议在本地或带加密 secret 的受控环境执行，切勿把密钥明文写入 CI 日志。
+
+---
+
+## 5.1 企业合规部署建议（M4）
+
+- **多租户物理隔离**：为每个客户/团队分配独立 `FH_TENANT`，数据落 `<FH_HOME>/tenants/<tenantId>/`，互不串台。
+- **最小角色**：日常运行用 `developer`；仅可信运维用 `operator`/`admin`；只读巡检用 `viewer`。
+- **日预算硬上限**：为每个租户设 `FH_TENANT_BUDGET_USD`，超限即 `QUOTA_EXCEEDED` 拒绝，防成本失控。
+- **审计留存**：`audit-YYYY-MM.jsonl` 建议只读挂载或异地备份，并周期性 `fhcode audit verify` 巡检哈希链完整性。
+- **关闭企业模式**：纯社区/单机使用可设 `FH_ENTERPRISE=false`，行为与 M3 一致、零额外开销。
+
+---
+
+## 6. 发布到 npm
+
+`package.json` 已做好发布安全：
+
+- `files` 白名单：`dist` + `README.md` + `LICENSE` + `CONTRIBUTING.md` + `docs`（**绝不**包含 `.env` / `src` / `.workbuddy`）。
+- `prepublishOnly`: `npm run build`（发布前自动构建，保证 `dist` 最新）。
+- `.npmignore` 作为冗余保险。
+
+发布步骤：
+
+```bash
+npm run build
+npm version patch          # 或 minor/major
+npm publish                # 仅携带 files 白名单内容
+```
+
+> ⚠️ **密钥安全铁律**：`.env` 含 API key，已被 `.gitignore` 与 `files` 白名单双重排除，永远不会进入 npm 包或 Git 仓库。
+
+---
+
+## 7. 内网 / 离线部署建议
+
+- **完全离线**：不配 `FH_PROVIDERS`，用内置 Mock 闭环（演示/回归）。
+- **本地模型**：配 Ollama 供应商（`type: ollama`，`baseURL: http://<内网IP>:11434`），数据不出本机。
+- **代理网关**：OpenAI 兼容供应商的 `baseURL` 可指向企业内网网关。
+- **日志合规**：`FH_LOG_DIR` 指向受控存储，按敏感数据留存策略管理。
+
+---
+
+## 8. 作为后台服务（可选 systemd）
+
+```ini
+[Unit]
+Description=飞虹 Code Agent
+After=network.target
+
+[Service]
+WorkingDirectory=/opt/feihong-code
+ExecStart=/usr/bin/fhcode "守护型需求"
+Environment=FH_HOME=/var/lib/feihong-code
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+---
+
+## 9. 升级与回滚
+
+- 升级：`git pull && npm install && npm run build`（或 `npm update -g feihong-code`）。
+- 回滚：npm 包使用 `npm install -g feihong-code@<旧版本>`；源码用 `git checkout <tag>` 后重建。
+
+---
+
+© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹

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

@@ -0,0 +1,288 @@
+# 飞虹 Code（fhcode）部署说明书
+
+**版本**：v0.5.0-b
+**日期**：2026-08-16
+**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（Muse Code 参照复刻）
+**署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+---
+
+## 一、部署形态总览
+
+| 形态 | 场景 | 组件 |
+|------|------|------|
+| 单机 CLI | 个人开发 / 内网终端 | fhcode CLI（Node.js） |
+| Web 服务 | 团队共享 / 云执行 | fhcode serve + 任务队列 |
+| Docker | 容器化 / 私有化 | Dockerfile + docker-compose |
+| 企业私有化 | 多租户 / 审计 / 配额 | 企业模式（FH_ENTERPRISE） |
+| IDE 集成 | 编辑器内使用 | VSCode 扩展（薄壳） |
+
+---
+
+## 二、环境要求
+
+| 项 | 要求 | 说明 |
+|----|------|------|
+| Node.js | ≥ 18（推荐 20/22） | 运行时 |
+| npm | ≥ 9 | 包管理 |
+| git | 推荐 | diff/rollback/并行 worktree |
+| Docker | 可选 | `FH_SANDBOX_MODE=container` 与 Docker 部署 |
+| 网络 | 可选 | 真实模型 API / 技能市场 / HF 数据集（离线模式不需外网） |
+
+**离线部署要点**：未配置模型时自动进入离线模式（Mock 驱动），零外网依赖；模型接入可指向内网 Ollama 或私有 OpenAI 兼容网关。
+
+---
+
+## 三、安装部署
+
+### 3.1 npm 全局安装
+
+```bash
+npm install -g feihong-code
+fhcode --version
+```
+
+### 3.2 源码部署
+
+```bash
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build          # tsc + Web 静态资源复制
+npm test               # 164 单测自检
+node scripts/eval.mjs  # 本地跑分自检（10/10）
+```
+
+### 3.3 Docker 部署（Web 服务）
+
+```bash
+# 构建镜像
+docker build -t feihong-code .
+
+# 运行 Web 控制台（含任务队列）
+docker run -d --name fhcode \
+  -p 8080:8080 \
+  -e FH_WEB_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（推荐）
+
+```yaml
+# docker-compose.yml
+services:
+  fhcode:
+    build: .
+    ports: ["8080:8080"]
+    environment:
+      FH_WEB_TOKEN: ${FH_WEB_TOKEN}
+      FH_PROVIDERS: ${FH_PROVIDERS}          # 模型配置
+      FH_TASK_CONCURRENCY: "2"               # 任务并发上限
+      FH_TASK_PERSIST_DIR: /data/tasks       # 任务持久化（重启恢复）
+      FH_ENTERPRISE: "true"                  # 企业模式
+    volumes:
+      - fhcode-data:/data
+      - fhcode-home:/root/.feihong-code
+volumes:
+  fhcode-data:
+  fhcode-home:
+```
+
+---
+
+## 四、环境变量参考（完整）
+
+### 4.1 应用与路径
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `FH_HOME` | `~/.feihong-code` | 主目录（会话/审计/经验/统计/缓存） |
+| `FH_LOG_DIR` | `$FH_HOME/sessions` | 会话日志目录（支持 `~` 展开） |
+| `FH_CONFIG` | — | 配置文件路径（fhcode.config.json） |
+| `FHCODE_LANG` | 系统 locale | 界面语言 zh/en |
+
+### 4.2 模型路由
+
+| 变量 | 说明 |
+|------|------|
+| `FH_PROVIDERS` | JSON 数组（最高优先级）：`{name,type,baseURL,apiKey,tags[],costPer1k}` |
+| `FH_MODEL_NAME/TYPE/BASE_URL/API_KEY/TAGS/COST_PER_1K` | 单变量快速接入 |
+| `FH_MODEL_STRATEGY` | cost/capability/latency |
+| `FH_BUDGET_USD` | 单任务成本上限（熔断） |
+| `FH_TENANT_BUDGET_USD` | 租户日成本上限（覆盖策略） |
+
+### 4.3 安全
+
+| 变量 | 说明 |
+|------|------|
+| `FH_SANDBOX_MODE` | read-only / workspace-write / danger-full-access / container |
+| `FH_SANDBOX_IMAGE` | container 模式镜像（默认 node:22-alpine） |
+| `FH_SHELL_ALLOW` | shell 白名单（逗号分隔） |
+| `FH_REQUIRE_APPROVAL` | 审批开关（默认 true） |
+| `FH_NETWORK_ALLOW/DENY` | 网络域名规则（deny 全模式生效） |
+| `FH_HOOKS` | hooks JSON 数组（PreToolUse/PostToolUse/PostEdit） |
+| `FH_POLICY` | 内联策略 JSON（RBAC/黑名单，仅加严） |
+
+### 4.4 企业模式
+
+| 变量 | 说明 |
+|------|------|
+| `FH_ENTERPRISE` | 默认开启（false 关闭退化为社区版） |
+| `FH_TENANT` | 租户 id（缺省 default） |
+| `FH_USER` | 用户 id |
+| `FH_ROLE` | viewer/developer/operator/admin |
+
+### 4.5 Web / 云执行
+
+| 变量 | 说明 |
+|------|------|
+| `FH_WEB_TOKEN` | Web 控制台访问令牌（缺省自动生成） |
+| `FH_WEB_PORT` | 端口（缺省 8080） |
+| `FH_TASK_CONCURRENCY` | 任务并发上限（缺省 2） |
+| `FH_TASK_PERSIST_DIR` | 任务持久化目录（缺省 `$FH_HOME/tasks`） |
+| `FH_TASK_WEBHOOK_URL` | 任务状态 webhook（可动态注册） |
+
+### 4.6 消息渠道
+
+| 变量 | 说明 |
+|------|------|
+| `FH_CHANNEL_TELEGRAM_BOT_TOKEN/CHAT_ID` | Telegram 通知 |
+| `FH_CHANNEL_WECOM_KEY` | 企业微信机器人 key（可多个逗号分隔） |
+| `FH_CHANNEL_ALLOW` | 出站渠道白名单 |
+
+### 4.7 技能市场 / 基准
+
+| 变量 | 说明 |
+|------|------|
+| `FH_SKILL_MARKET` | 技能市场源（缺省 agentskills.io） |
+| `FH_SWEBENCH_DATA_URL` | SWE-bench 数据镜像/离线 JSON（国内网络友好） |
+
+---
+
+## 五、企业私有化部署
+
+### 5.1 目录结构（租户隔离）
+
+```
+$FH_HOME/
+├── tenants/<tenantId>/
+│   ├── sessions/          # 会话检查点
+│   ├── audit/             # 审计哈希链（audit-YYYY-MM.jsonl）
+│   └── goals/             # 目标文件
+├── policy.json            # 全局策略（RBAC/黑名单）
+├── experiences/           # 经验库
+├── model-stats.jsonl      # 模型统计
+├── skills/                # 用户级技能
+├── plugins/               # 用户级插件
+└── bench/                 # eval/SWE-bench 缓存与基线
+```
+
+### 5.2 生产建议
+
+1. **令牌管理**：`FH_WEB_TOKEN` 必须显式设置（缺省自动生成仅限本会话），通过密钥管理服务注入
+2. **审计合规**：`fhcode audit verify` 定期校验哈希链完整性；审计文件按月分片便于归档
+3. **配额治理**：`FH_TENANT_BUDGET_USD` 设租户日预算，超限 fail-fast 拒绝任务
+4. **备份**：`$FH_HOME`（会话/审计/经验）建议每日备份；任务队列 `FH_TASK_PERSIST_DIR` 独立卷
+5. **多实例**：任务队列按文件持久化，多实例共享持久化目录可交叉恢复（queued 重新入队、running 僵尸标记 failed）
+6. **内网模型**：`FH_PROVIDERS` 指向内网 Ollama/私有网关，可完全断外网运行
+
+### 5.3 安全基线（生产必须）
+
+```bash
+export FH_REQUIRE_APPROVAL=true
+export FH_SANDBOX_MODE=workspace-write     # 或 container
+export FH_NETWORK_DENY=...                 # 按需配置
+export FH_ENTERPRISE=true
+export FH_CHANNEL_ALLOW=telegram,wecom     # 渠道白名单（可选）
+```
+
+---
+
+## 六、Web 服务运维
+
+### 6.1 启动与健康检查
+
+```bash
+fhcode serve --port 8080
+curl http://localhost:8080/api/health   # 免鉴权健康检查
+```
+
+### 6.2 任务队列 API（Bearer 鉴权）
+
+```bash
+TOKEN=$FH_WEB_TOKEN
+# 提交 / 列表 / 查询 / webhook 注册
+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 重启恢复
+
+- 任务落盘 `$FH_HOME/tasks/<id>.json`（原子写）
+- 重启后：queued 重新入队执行、running 僵尸标记 failed、终态保留可查询
+- webhook/渠道通知在恢复时重新触发（queued 节点）
+
+---
+
+## 七、CI/CD 集成（回归门禁）
+
+```yaml
+# .github/workflows/ci.yml 片段
+- name: Build & test
+  run: |
+    npm ci
+    npm run typecheck
+    npm test
+    npm run build
+
+- name: eval 回归门禁（基线对比）
+  run: |
+    npm run build
+    node scripts/eval.mjs --baseline bench/eval-baseline.json
+  # 本次 pass 低于基线即失败
+
+- name: 更新基线（main 分支）
+  if: github.ref == 'refs/heads/main'
+  run: node scripts/eval.mjs --save-baseline bench/eval-baseline.json
+```
+
+### SWE-bench 基准接入（可选）
+
+```bash
+node scripts/eval-swebench.mjs --split lite --limit 20 --run --report report.md
+# 离线/内网：FH_SWEBENCH_DATA_URL 指向镜像 JSON
+```
+
+---
+
+## 八、升级与回滚
+
+| 操作 | 命令 |
+|------|------|
+| 升级 npm 包 | `npm install -g feihong-code@latest` |
+| 升级源码 | `git pull && npm install && npm run build` |
+| 检查版本 | `fhcode --version` / `fhcode doctor` |
+| 回滚 | npm 指定旧版本 / git checkout 旧 tag（数据目录不随代码回滚，兼容） |
+
+> 数据兼容：会话检查点/审计/经验均为 JSON/JSONL 文本格式，跨小版本向后兼容；升级前建议备份 `$FH_HOME`。
+
+---
+
+## 九、故障排查
+
+| 现象 | 排查 |
+|------|------|
+| 服务启动后 401 | `FH_WEB_TOKEN` 未设置或与调用方不一致（Bearer 头） |
+| 任务一直 queued | 并发满（`FH_TASK_CONCURRENCY`）或持久化目录不可写 |
+| 模型调用失败 | `fhcode doctor` 检查网络连通与 provider 配置 |
+| Docker 内无法执行 shell | 确认 `FH_SANDBOX_MODE` 与镜像；`FH_SANDBOX_IMAGE` 含所需工具 |
+| 重启后任务状态异常 | running 僵尸会被标记 failed（预期行为），queued 会自动续跑 |
+| 市场/数据集拉取失败 | 内网设镜像：`FH_SKILL_MARKET` / `FH_SWEBENCH_DATA_URL` |
+
+---
+
+*完整配置见《配置参考》；错误码与详细排查见《常见问题与故障排查》。*