feihong-code 0.2.3 → 0.6.0

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

@@ -1,358 +1,318 @@
-# 飞虹 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）权威文档集。*
+# 飞虹 Code（fhcode）使用说明书
+
+**版本**：v0.5.0-b
+**日期**：2026-08-16
+**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（Muse Code 参照复刻）
+**署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+---
+
+## 一、快速开始
+
+### 1.1 环境要求
+
+- Node.js ≥ 18（推荐 20/22）
+- npm ≥ 9
+- git（diff/rollback/并行 worktree 需要）
+- Docker（仅 `FH_SANDBOX_MODE=container` 时需要）
+
+### 1.2 安装
+
+```bash
+# 方式一：源码构建（推荐）
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build
+
+# 方式二：npm 全局安装
+npm install -g feihong-code
+fhcode --version   # 验证
+```
+
+### 1.3 三秒上手
+
+```bash
+# 未配置模型时自动进入离线模式（Mock 驱动闭环），可直接体验
+fhcode "写一个 hello.ts"
+
+# 配置真实模型（DeepSeek 示例）后走真实模式
+export FH_PROVIDERS='[{"name":"deepseek","type":"openai-compatible","baseUrl":"https://api.deepseek.com/v1","apiKey":"sk-...","tags":["code-gen","reasoning"],"priority":1}]'
+fhcode "修复 src/auth.ts 中的 token 校验 bug"
+```
+
+---
+
+## 二、命令速查
+
+```bash
+# 基础
+fhcode                              进入交互式 REPL（TTY 下自动启用 TUI）
+fhcode "<需求>"                      单命令执行一条需求
+fhcode --stream "<需求>"             流式输出（任务过程实时可见）
+fhcode --yes "<需求>"                跳过审批（危险操作需谨慎）
+fhcode --lang zh|en                  设置界面语言
+
+# 只读技能
+fhcode /plan "<目标>"                生成实现计划
+fhcode /grill [路径]                 红队式代码审查（文本）
+fhcode review [路径] [--json]        结构化代码审查（--json 供 IDE/CI 消费）
+fhcode /goal "<目标>"                分解并保存高层目标
+
+# 会话管理（M3）
+fhcode sessions                      列出历史会话
+fhcode resume <id>                   从检查点续跑
+fhcode diff [id]                     查看会话/工作区变更
+fhcode rollback <id> --yes           回滚会话改动（破坏性）
+
+# 企业能力（M4）
+fhcode whoami                        当前租户/用户/角色/配额
+fhcode policy                        查看生效 RBAC 策略
+fhcode audit [verify]                审计记录 / 哈希链校验
+fhcode tenants                       租户用量汇总
+
+# 自我进化（M6/M8/M9）
+fhcode model-stats                   模型性能统计
+fhcode experiences [路径]            经验库
+fhcode code-write "<目标>"            自主编程
+fhcode quality-gate [路径]           质量门禁审查
+fhcode self-improve                  自我改进统计
+fhcode swe "<目标>"                  全自动软件工程 Agent
+fhcode team "<目标>"                 多 agent 协作（共享任务板+消息总线）
+
+# 生态
+fhcode skill-market search "<关键词>" 搜索技能市场（agentskills.io）
+fhcode skill-market install <技能名>  安装技能
+fhcode skill-market list             列出本地技能
+fhcode plugin install <目录|git URL> 安装插件
+fhcode plugin list                   列出插件
+fhcode doctor                        环境自检
+```
+
+**常用 flag**：`--parallel`（并行 worktree）/ `--repo`（swe 目标仓库/市场源）/ `--context-file <path>`（附加文件上下文）/ `--max-iterations N` / `--max-retries N` / `--plan-only` / `--verify-only` / `--json`。
+
+---
+
+## 三、模型配置
+
+### 3.1 配置优先级
+
+1. `FH_PROVIDERS`（JSON 数组，最高优先级）
+2. `fhcode.config.json`（项目配置文件 `models.providers`）
+3. 单环境变量 `FH_MODEL_*`
+
+### 3.2 Ollama 本地模型
+
+```bash
+export FH_MODEL_NAME=qwen3:8b
+export FH_MODEL_TYPE=ollama
+export FH_MODEL_BASE_URL=http://localhost:11434
+export FH_MODEL_TAGS=code-gen,reasoning,local
+```
+
+### 3.3 DeepSeek / 通义
+
+```bash
+# DeepSeek
+export FH_PROVIDERS='[{"name":"deepseek","type":"openai-compatible","baseUrl":"https://api.deepseek.com/v1","apiKey":"sk-...","tags":["code-gen","reasoning"],"costPer1k":0.0001}]'
+# 通义千问
+export FH_PROVIDERS='[{"name":"qwen","type":"openai-compatible","baseUrl":"https://dashscope.aliyuncs.com/compatible-mode/v1","apiKey":"...","tags":["code-gen","long-context"]}]'
+```
+
+### 3.4 路由策略
+
+```bash
+export FH_MODEL_STRATEGY=cost        # cost | capability | latency
+export FH_BUDGET_USD=0.5             # 单任务成本上限（超限熔断）
+```
+低成本标签 `cheap` 的 provider 会优先承担 `swe`/并行子任务（P1-1 模型分工）。
+
+---
+
+## 四、典型工作流
+
+### 4.1 单任务
+
+```bash
+# 基础
+fhcode "实现一个 HTTP 服务器，监听 3000 端口"
+# 流式 + 指定上下文文件
+fhcode --stream --context-file src/auth.ts "审查并修复此文件中的安全问题"
+```
+
+### 4.2 全自动软件工程（swe）
+
+```bash
+fhcode swe "修复 src/calc.ts 的 add 函数 bug，让 tests/calc.test.ts 通过" \
+  --repo /path/to/project \
+  --max-tasks 3 --max-iterations 5
+# --plan-only 仅规划 / --verify-only 仅验证 / --max-retries N 自愈重试
+```
+
+### 4.3 多 agent 协作（team）
+
+```bash
+fhcode team "实现登录模块 并且 添加用户管理 并且 写集成测试"
+# 目标自动拆解 → 多 agent 并发认领 → 消息总线汇报 → 团队报告
+```
+
+### 4.4 技能市场与插件
+
+```bash
+# 从 agentskills.io 搜索并安装技能（安装后任务中自动发现）
+fhcode skill-market search "code review"
+fhcode skill-market install code-review
+# 安装插件（打包 skills+hooks+MCP）
+fhcode plugin install ./my-plugin
+```
+
+### 4.5 会话恢复与回滚
+
+```bash
+fhcode sessions                 # 找到会话 id
+fhcode resume <id>              # 中断后续跑
+fhcode diff <id>                # 查看改动
+fhcode rollback <id> --yes      # 回滚（破坏性）
+```
+
+### 4.6 环境自检
+
+```bash
+fhcode doctor
+# ✅ Node 版本 / git / 模型配置 / 网络连通 / 主目录可写 / 沙箱模式
+```
+
+---
+
+## 五、REPL / TUI 使用
+
+```bash
+fhcode          # 进入交互模式（TTY 自动启用 TUI）
+```
+- TUI：顶部 sticky header 显示 模式/runId/迭代/成本/状态；内容区滚动；滚轮可回看
+- 输入需求回车执行；`exit`/`quit`/Ctrl+D 退出
+- 支持 `/plan` `/grill` `/goal` 斜杠技能
+
+---
+
+## 六、VSCode 扩展
+
+在 `vscode-extension/` 目录打包（`npx @vscode/vsce package`）或 F5 调试加载：
+
+| 命令 | 说明 |
+|------|------|
+| `fhcode: 运行任务（附带选区上下文）` | 选中代码自动注入 `<selection>` 上下文 |
+| `fhcode: 内联评审当前文件` | `review --json` → 编辑器内联诊断（红/黄/蓝） |
+| `fhcode: 就地查看工作区 diff` | 原生 diff 编辑器 HEAD↔工作区 |
+| `fhcode: 查看最近任务输出` | 聚焦 Output Channel |
+
+配置：`fhcode.binaryPath` / `fhcode.offline` / `fhcode.reviewOnSave`（保存自动评审，默认开）。
+
+---
+
+## 七、Web 控制台（云执行）
+
+```bash
+fhcode serve --port 8080
+# 浏览器打开 http://localhost:8080
+```
+
+**任务面板**：输入 token（终端输出的 `FH_WEB_TOKEN`）→ 提交目标 → 轮询状态 → 展开结果详情。
+
+**API 调用**（Bearer 鉴权）：
+
+```bash
+TOKEN=$(echo $FH_WEB_TOKEN)
+# 提交任务
+curl -X POST http://localhost:8080/api/tasks \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"goal":"写一个 hello.ts"}'
+# 查询
+curl http://localhost:8080/api/tasks -H "Authorization: Bearer $TOKEN"
+curl http://localhost:8080/api/tasks/<id> -H "Authorization: Bearer $TOKEN"
+# 注册 webhook（任务状态回调，可被 CI 调度）
+curl -X POST http://localhost:8080/api/webhook \
+  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+  -d '{"url":"https://your-ci.example.com/hook"}'
+```
+
+---
+
+## 八、消息渠道
+
+```bash
+# Telegram 通知（任务状态变化推送）
+export FH_CHANNEL_TELEGRAM_BOT_TOKEN=bot:xxx
+export FH_CHANNEL_TELEGRAM_CHAT_ID=12345
+# 企业微信群机器人（可多个 key）
+export FH_CHANNEL_WECOM_KEY=key1,key2
+# 出站白名单（可选，配置后仅白名单渠道可发）
+export FH_CHANNEL_ALLOW=telegram,wecom
+```
+
+---
+
+## 九、沙箱与安全使用
+
+```bash
+# 沙箱模式
+export FH_SANDBOX_MODE=workspace-write      # 默认
+export FH_SANDBOX_MODE=read-only            # 只读勘察（禁写禁执行）
+export FH_SANDBOX_MODE=danger-full-access   # 全权限（危险命令仍拦截）
+export FH_SANDBOX_MODE=container            # Docker 容器内执行 shell
+export FH_SANDBOX_IMAGE=node:22-alpine      # 容器镜像
+
+# 网络域名规则
+export FH_NETWORK_DENY=evil.example.com
+# export FH_NETWORK_ALLOW=api.example.com
+
+# 确定性 hooks（PreToolUse 非零退出拦截）
+export FH_HOOKS='[{"event":"PreToolUse","command":"node scripts/guard.js","tools":["run_shell"]}]'
+```
+
+---
+
+## 十、eval 跑分与回归门禁
+
+```bash
+# 本地跑分（场景 5 + 验收 5，验证真实产物）
+npm run build && npm run eval
+
+# 存档基线 + 对比门禁（低于基线即失败，可接入 CI）
+node scripts/eval.mjs --save-baseline bench/eval-baseline.json
+node scripts/eval.mjs --baseline bench/eval-baseline.json
+
+# SWE-bench 数据集加载（HF 或镜像）
+node scripts/eval-swebench.mjs --split lite --limit 5
+node scripts/eval-swebench.mjs --split lite --limit 5 --run --report report.md
+FH_SWEBENCH_DATA_URL=https://mirror.example/swebench.json node scripts/eval-swebench.mjs --limit 3
+```
+
+---
+
+## 十一、常见问题速查
+
+| 问题 | 处理 |
+|------|------|
+| 未配置模型却想用真实模式 | `FH_PROVIDERS` 或 `FH_MODEL_NAME` 配置后自动进入真实模式 |
+| 任务超预算中止 | 调高 `FH_BUDGET_USD` 或角色策略 `maxCostUsd`，用 `resume` 续跑 |
+| 配额拒绝（QUOTA_EXCEEDED） | 调整 `FH_TENANT_BUDGET_USD` 或 policy 的 tenantDailyBudgetUsd |
+| review 输出为空 | 确认路径为文件或目录且含受支持扩展名（ts/js/tsx/jsx/json/md/py/go/java） |
+| 技能市场拉取失败 | 检查网络或设 `FH_SWEBENCH_DATA_URL`/`--repo` 镜像源 |
+| 中文/英文切换 | `fhcode --lang en` 或 `FHCODE_LANG=en` |
+
+---
+
+## 十二、故障排查与日志
+
+```bash
+export FH_LOG_LEVEL=debug        # 详细日志
+fhcode doctor                    # 环境自检（快速定位）
+fhcode audit verify              # 审计链完整性校验
+# 日志目录：~/.feihong-code/sessions/<runId>.jsonl（事件日志）
+# 检查点：~/.feihong-code/sessions/<runId>.session.json
+```
+
+---
+
+*完整配置清单见《配置参考》与《部署说明书》；常见错误码见《常见问题与故障排查》。*