feihong-code 0.2.3 → 0.6.0

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

@@ -1,303 +1,216 @@
-# 飞虹 Code（fhcode）技术说明书
-
-> 本文为飞虹 Code 的**权威技术文档**，覆盖架构、企业级能力技术细节、数据契约、CLI/Web API、部署架构、安全模型与构建验证。
-> 用户侧操作请参见《使用说明书》。
-
-**版本**：0.2.0（含 M4 企业能力 + M5 Web 控制台 BETA + M6 自我进化 + M7 编程能力 + M8 自主迭代 + M9 全自动软件工程 Agent）
-**署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-
----
-
-## 1. 概述与定位
-
-飞虹 Code（命令名 `fhcode`）是终端 AI 编程智能体，以"目标"为入口，自动完成需求解析 → 规划 → 工具调用 → 反思的闭环，并支持多子代理并行、会话恢复审计，以及企业级权限/审计/多租户/成本治理。
-
-- **适用场景**：代码生成与修改、批量重构、离线脚本化任务、企业内多团队共享的智能体底座。
-- **能力边界**：不修改薪酬/股权/制度、不承诺效果、不伪造身份；危险操作一律人工审批或拒绝。
-- **两种形态**：
-  - **社区版（默认）**：CLI 闭环 + 并行 + 恢复审计。
-  - **企业版（注入 guard 或 `FH_ENTERPRISE!=='false'`）**：在 community 之上叠加 RBAC、防篡改审计、多租户隔离、成本治理、Web 控制台。未注入 guard 时行为同社区版（无感降级）。
-
----
-
-## 2. 系统架构
-
-### 2.1 分层架构
-
-```
-cli         命令解析 / 分发 / 交互入口（含 serve）
-  └─ agent  编排层（Orchestrator / 并行 / Planner / SubAgent）
-       └─ tools       工具集（file / search / shell / verify）+ 注册表 + 守卫接口
-            └─ runtime    会话持久化 / git diff·rollback / 成本计量
-                 └─ models      模型提供商适配 + 成本估算
-                      └─ shared     通用工具（日志/脱敏/错误）
-  enterprise  企业能力（tenant/policy/audit/quota/guard/index）—— 可选注入
-  skills      技能定义（plan/grill/goal 等）
-  web         Web 控制台（server/auth/public）—— M5 BETA
-```
-
-### 2.2 执行流（社区版 vs 企业版）
-
-- **社区版**：`cli` → `Orchestrator.run(goal)` → 循环「规划→选工具→`tool.registry.execute`→反思」→ 终态答案。
-- **企业版**：在「选工具 → 执行」之间插入**唯一权威闸门 `guard`**：
-  1. `guard.check(tool, args)` 调 `policy.evaluate` 做策略判定；
-  2. 命中审批项且无审批通道 → 拒绝；有通道 → 询问并记录 approved/rejected；
-  3. 审计留痕（allow/deny/approval）；审计写入失败 = 拒绝执行；
-  4. 通过后才进入 `tool.registry.execute`，且注入 `security` 置空以避免工具层二次弹审批（去重）。
-
-### 2.3 模块清单
-
-| 目录 | 职责 |
-|------|------|
-| `src/cli` | 命令解析（`commands.ts`）、分发（`index.ts`）、业务编排（`run.ts`）、版本与署名（`version.ts`） |
-| `src/agent` | `orchestrator.ts`（主循环+成本熔断）、`parallel-orchestrator.ts`、`planner.ts`、`subagent.ts`、`prompts.ts` |
-| `src/tools` | `tool.interface.ts`（含 `ToolGuard`）、`tool.registry.ts`（guard 接线）、`file/`、`search/`、`shell/`、`verify/` |
-| `src/runtime` | `session-persist.ts`（检查点落盘）、`git.ts`（diff/rollback）、`cost.ts` |
-| `src/models` | `providers/`（模型适配）、`cost.ts` |
-| `src/shared` | 日志、脱敏、通用错误 |
-| `src/skills` | 技能定义 |
-| `src/enterprise` | `tenant.ts` `policy.ts` `audit.ts` `quota.ts` `guard.ts` `index.ts` |
-| `src/web` | `server.ts` `auth.ts` `express.d.ts`（本地类型声明） `public/` |
-
----
-
-## 3. 企业级能力技术细节（M4）
-
-### 3.1 RBAC 与策略引擎（`policy.ts`）
-
-**判定顺序（deny 优先）**：
-
-1. `run_shell` 命中**危险命令黑名单** → `deny`（无论角色）。
-2. 命中**敏感路径黑名单**或**沙箱越界** → `deny`（admin 也拦）。
-3. 角色矩阵：`deny` / `approval`（需人工审批）/ `allow`。
-4. `run_shell` 命中**白名单** → 免审批 `allow`。
-
-**角色矩阵（`DEFAULT_POLICY.roles`）**：
-
-| 角色 | 允许工具 | 危险命令 | 单任务预算上限 |
-|------|----------|----------|----------------|
-| `viewer` | read / list / grep | — | $0.1 |
-| `developer` | + write / edit / tests / build | 需审批 | $1 |
-| `operator` | 全部 | 需审批 | $5 |
-| `admin` | 全部 | 需审批 | ∞ |
-
-**危险命令黑名单（23 条，`denyShell`）**：
-`rm -rf /`、`rm -rf ~`、`rm -rf *`、`mkfs`、`dd if=`、`fork bomb :(){`、`shutdown`、`reboot`、`halt`、`format `、`del /s`、`rd /s`、`chmod 777 /`、`chown -R root`、`curl | sh`、`curl|sh`、`wget | sh`、`wget|sh`、`iptables -F`、`net user`、`reg delete`、`history -c`、`shred `。
-
-**敏感路径黑名单（11 类，`denyPaths`）**：
-`.env`、`.git/config`、`.git/hooks`、`.npmrc`、`.ssh`、`id_rsa`、`id_ed25519`、`credentials`、`.aws`、`.kube/config`、`shadow`。
-
-**策略覆盖规则（仅加严）**：
-- 加载优先级：`DEFAULT_POLICY` → `<FH_HOME>/policy.json` → `<租户>/policy.json` → 环境变量 `FH_POLICY`（JSON 片段）。
-- 合并（`mergePolicy`）：**黑名单取并集**（不能放宽）；角色预算只能调低或持平；新增 deny 规则有效，移除 deny 无效。
-- 即：任何层级的覆盖只能让策略更严格，不能削弱内置安全基线。
-
-### 3.2 防篡改审计（`audit.ts`）
-
-**哈希链结构**：每条记录 `AuditRecord` 含 `seq`、`ts`、`tenant`、`user`、`role`、`runId`、`action`、`resource`、`decision`、`reason`、`prevHash`、`hash`。
-- `computeHash(r) = sha256([seq, ts, tenant, user, role, runId, action, resource, decision, reason, prevHash].join('|'))`
-- 创世哈希 `GENESIS = '0'.repeat(64)`（首条 `prevHash`）。
-- **按月切分**：`audit-YYYY-MM.jsonl`，每条一行 JSON，同步 `appendFileSync` 追加；写入失败抛错（上层拒绝执行）。
-
-**脱敏（`redact`）**：值中出现 `apiKey=`/`secret=`/`token=`/`password=`/`Authorization: Bearer`/`sk-*` 等一律替换为 `***`，写入前即脱敏。
-
-**校验（`verifyAudit`）**：
-- 检查 `seq` 连续、`prevHash` 与上一行 `hash` 衔接、`hash` 自洽（重算一致）；
-- 任一断点返回 `{ ok:false, brokenAt: <行号> }` 定位篡改位置。
-
-### 3.3 多租户隔离（`tenant.ts`）
-
-**物理目录隔离**：`<FH_HOME>/tenants/<tenantId>/{sessions,audit,goals}`。
-- 租户 ID 校验：`ID_RE = /^[A-Za-z0-9._-]{1,64}$/`，防路径穿越。
-- **默认租户兼容**：`FH_TENANT` 缺省且尚未建 `tenants/default` 但存在旧 `<FH_HOME>/sessions` 时，沿用旧目录（平滑升级，不丢历史）。
-- 用量统计（`listTenants`）：仅提取 `costUsd`/`updatedAt`，不反序列化整份对话。
-
-### 3.4 成本治理（`quota.ts`）
-
-- **单任务熔断**：`Orchestrator` 循环内 `if (maxCost>0 && cost>=maxCost)` 终止并给出终态答案（告警式，不抛错）。
-- **租户日预算 fail-fast**：任务启动前 `assertQuota()` 调 `checkQuota()`；超限抛 `QUOTA_EXCEEDED`（HTTP 429 语义）并审计 `quota:block`。
-- 日预算解析优先级：`FH_TENANT_BUDGET_USD` > 策略 `tenantDailyBudgetUsd`；缺省为 0（不限制）。
-- 当日统计：正则提取 `updatedAt` 前缀匹配当天 UTC。
-
----
-
-## 4. 数据契约与格式
-
-### 4.1 AuditRecord（审计记录）
-
-```json
-{
-  "seq": 1,
-  "ts": "2026-08-10T14:30:00.000Z",
-  "tenant": "acme",
-  "user": "alice",
-  "role": "developer",
-  "runId": "run_xxx",
-  "action": "tool:write_file",
-  "resource": "src/app.ts",
-  "decision": "allow",
-  "reason": "命中角色矩阵 allow",
-  "prevHash": "0000...0000",
-  "hash": "a1b2...ff"
-}
-```
-
-### 4.2 Policy（策略片段，可经 FH_POLICY / policy.json 覆盖）
-
-```json
-{
-  "roles": { "viewer": { "allow": ["read","list","grep"], "maxCostUsd": 0.1 } },
-  "denyShell": ["rm -rf /"],
-  "denyPaths": [".env"],
-  "tenantDailyBudgetUsd": 0
-}
-```
-
-### 4.3 TenantContext
-
-```ts
-interface TenantContext {
-  tenant: string;      // 校验后的租户 ID
-  user: string;        // FH_USER 或 'default'
-  role: Role;          // viewer|developer|operator|admin
-  home: string;        // FH_HOME
-  dirs: { sessions: string; audit: string; goals: string };
-}
-```
-
-### 4.4 配置变量全集
-
-| 变量 | 作用 | 默认 |
-|------|------|------|
-| `FH_HOME` | 数据根目录（会话/审计/租户） | 平台默认（如 `~/.fhcode`） |
-| `FH_ENTERPRISE` | 企业模式开关（`false` 关闭） | 开启（注入 guard 时） |
-| `FH_TENANT` / `FH_USER` / `FH_ROLE` | 租户/用户/角色身份 | `default`/`default`/`developer` |
-| `FH_TENANT_BUDGET_USD` | 租户日预算（优先于策略） | 0（不限制） |
-| `FH_POLICY` | 策略 JSON 片段（覆盖） | 空 |
-| `FH_WEB_PORT` / `FH_WEB_TOKEN` | Web 控制台端口/令牌 | `8080` / 空（禁用） |
-| `FH_OFFLINE` | 强制离线（不请求模型） | 未设 |
-| `FH_REQUIRE_APPROVAL` | 危险操作是否需审批 | `true` |
-| `FH_BUDGET_USD` | 单任务成本告警阈值 | 未设 |
-
----
-
-## 5. CLI 与 Web API 参考
-
-### 5.1 CLI 命令
-
-| 命令 | 说明 |
-|------|------|
-| `fhcode "目标"` | 运行单条目标（社区/企业） |
-| `fhcode /plan "需求"` | 生成实现规划 |
-| `fhcode /grill <路径>` | 代码评审（grill） |
-| `fhcode /goal` | 进入目标模式 |
-| `fhcode sessions` | 列出会话检查点 |
-| `fhcode resume <id>` | 断点续跑 |
-| `fhcode diff [id]` | 会话作用域 diff |
-| `fhcode rollback <id> [--yes]` | 回滚被改文件（需确认） |
-| `fhcode whoami` | 显示租户/用户/角色/隔离目录/用量 |
-| `fhcode policy` | 渲染 RBAC 角色矩阵与黑名单 |
-| `fhcode audit [--limit N]` | 查看审计链（脱敏） |
-| `fhcode audit verify` | 校验哈希链完整性 |
-| `fhcode tenants` | 列出全部租户与用量汇总 |
-| `fhcode serve [--port 8080]` | 启动 Web 管理控制台（BETA） |
-| `fhcode swe "<目标>" [--repo PATH] [--plan-only] [--verify-only] [--max-tasks N] [--max-retries N] [--max-iterations N]` | 全自动软件工程 Agent（M9） |
-
-通用标志：`--version`、`--help`、`--parallel`、`--yes`、`--limit N`。
-
-### 5.1.1 真实模型接入（M9.1）
-
-`swe` 及常规 `fhcode` 命令在真实模式下通过 `ModelRouter.fromConfig` 加载供应商，供应商配置支持三级解析（详见使用说明书第 10 章）：
-
-1. 环境变量 `FH_PROVIDERS`（JSON 数组，可多供应商）；
-2. 配置文件 `fhcode.config.json`（`models.providers`）；
-3. 单环境变量快速接入：`FH_MODEL_NAME` / `FH_MODEL_TYPE` / `FH_MODEL_BASE_URL` / `FH_MODEL_API_KEY` / `FH_MODEL_TAGS`。
-
-供应商类型支持 `ollama`（本地零成本）与 `openai-compatible`（DeepSeek / 通义 / OpenRouter 等）。
-**接入校验脚本** `scripts/verify-m9-real.mjs`：用本地 mock HTTP 服务（兼容 OpenAI / Ollama 协议）驱动 `swe` 走完整的"真实 HTTP provider → 编排器工具循环 → 验证器"链路，无需任何外部模型即可验证接入正确性（11 项断言）。
-
-### 5.2 Web REST API（M5 BETA，仅观测、不执行）
-
-所有端点需 `Authorization: Bearer <FH_WEB_TOKEN>`（未设令牌则全 401，fail-closed）。
-
-| 方法 | 路径 | 返回 |
-|------|------|------|
-| GET | `/api/health` | `{ product, version, signature, enterprise, time }` |
-| GET | `/api/tenants` | 全部租户与用量 |
-| GET | `/api/whoami` | 当前租户身份与配额 |
-| GET | `/api/policy` | 角色矩阵 + 黑名单 |
-| GET | `/api/audit?limit=N` | 脱敏审计记录（倒序） |
-| GET | `/api/audit/verify` | `{ ok, brokenAt? }` |
-| GET | `/api/sessions` | 会话检查点列表 |
-| GET | `/api/quota` | 配额状态（已用/上限） |
-
-静态仪表盘由 `dist/web/public/index.html` 提供（同源访问）。
-
----
-
-## 6. 部署架构
-
-### 6.1 CI 四流水线（`.github/workflows/ci.yml`，零 Secrets 全离线）
-
-1. **build**：Node 18/20/22 矩阵 + 类型检查 + 编译 + 离线端到端闭环 + `/plan` `/grill` 只读技能。
-2. **enterprise**：`verify-m4.mjs`（41 项全离线断言：RBAC/审计链/多租户/配额）+ CLI 企业命令冒烟 + **租户隔离断言**（beta 不得读到其他租户会话）。
-3. **security**：`npm pack --dry-run` 白名单校验（禁 `.env`/`src`/`.workbuddy`/`policy.json`/`id_rsa`）+ 仓库明文密钥扫描 + `npm audit`。
-4. **docker**：构建镜像（不推送）+ 容器内 `whoami` 冒烟 + Web 控制台 `/api/health` 健康检查（HTTP 200）。
-
-### 6.2 Docker 部署（稳定部署推荐）
-
-- **镜像**：多阶段 `Dockerfile`，构建阶段编译 `dist`，运行阶段仅 `express`+`zod` 生产依赖。
-- **数据卷**：`FH_HOME=/data/fhcode` 挂载命名卷，持久化会话/审计/租户。
-- **端口**：默认 `8080`（Web 控制台）。
-- **编排**：`docker-compose.yml` 提供一键 `docker compose up -d`，令牌经 `FH_WEB_TOKEN` 环境变量注入。
-- **反向代理建议**：前置 Nginx/Caddy 做 TLS 终止与限流；`FH_WEB_TOKEN` 务必为强随机值，勿用默认值。
-
-### 6.3 安装方式
-
-- npm 全局：`npm install -g feihong-code`（bin=`fhcode`）。
-- 源码：`git clone` → `npm install` → `npm run build` → `node dist/cli/index.js`。
-- Docker：`docker build -t feihong-code .` → `docker run -p 8080:8080 feihong-code serve`。
-- 安装脚本：`./install.sh`（封装 npm 全局安装）。
-
----
-
-## 7. 安全模型
-
-- **密钥**：仅存 gitignored `.env`；CLI 不回显完整 key；日志脱敏（`redact`）。
-- **最小权限**：`guard` 为唯一权威闸门，deny 优先；Web 仅观测不执行，保持 guard 权威。
-- **fail-closed**：Web 无令牌/错令牌 → 401；审批通道缺失 → 拒绝；审计写入失败 → 拒绝。
-- **发布包白名单**：`package.json` 的 `files`（仅 `dist`+元数据+`docs`）+ `.npmignore`（排除 `.env`/`src`/`.workbuddy`/脚本/日志）双重保障，`.env` 等绝不随 `npm publish` 泄露。
-
----
-
-## 8. 构建与验证
-
-| 脚本 | 作用 |
-|------|------|
-| `npm run typecheck` | `tsc --noEmit` 类型检查 |
-| `npm run build` | `tsc` 编译 + 拷贝 Web 静态资源到 `dist/web/public` |
-| `npm run verify:m4` | 41 项企业能力离线断言 |
-| `npm run verify` | typecheck + build + verify:m4 串联 |
-
-> **本地构建注意**：Windows 本地 `tsc` 编译可能被 Windows Defender 实时扫描短暂锁文件（表现为 emit 退出 1 或后台挂起），属环境限制非代码缺陷；GitHub Actions（windows/ubuntu runner）无此问题。CI 是权威构建来源。
-
-**verify-m4 断言覆盖（41/41）**：RBAC 矩阵(5) / deny 优先(4) / 策略覆盖加严(4) / 审计哈希链(7) / 守卫链路(11) / 多租户(7) / 配额(3)。
-
----
-
-## 9. 里程碑与路线图
-
-- **M0+M1**：CLI 骨架 + 单代理闭环 ✅
-- **M2**：多子代理并行编排 ✅
-- **M3**：恢复与审计（sessions/resume/diff/rollback + 交互式审批）✅
-- **M4**：企业级权限/审计/多租户/CI ✅（本稳定版）
-- **M5**：Web 管理控制台 —— S1 服务骨架+`serve` 已完成并验证（BETA）；S2 观测 API / S3 前端仪表盘 / S4 安全加固 / S5 文档与 verify-m5 待推进。
-- **M6**：自我进化核心 —— 自愈循环（self-heal）、上下文压缩（context-compactor）、经验学习（experience）、模型性能追踪（model-router stat）✅
-- **M7**：编程能力增强 —— 代码分析器（code-analyzer）、代码生成器（code-generator）、AI 代码审查器（code-review）、仓库理解器（repo-underwriter）、测试生成器（test-generator）✅
-- **M8**：自主编程迭代优化 —— CodeWriter 自主编写器（规划→编写→测试→审查→修复闭环）、QualityGate 质量门禁（安全+质量+测试覆盖）、SelfImprover 自我改进（反思→模式提取→经验融合）、CLI 命令（`code-write`/`quality-gate`/`self-improve`）✅
-- **M9**：全自动软件工程 Agent —— 读取整个（大型）代码仓库（repo-reader，限流+忽略规则）→ 任务拆解规划（swe-planner，有序可验证子任务）→ 逐任务（实现+构建/测试验证+自愈重试，swe-agent 主编排）→ 产出结构化报告；CLI 命令 `fhcode swe "<目标>"`（支持 `--repo`/`--plan-only`/`--verify-only`/`--max-tasks`/`--max-retries`/`--max-iterations`）✅
-- **M9.1 真实模型接入与实测调优** —— `loadConfig` 新增三级供应商解析（FH_PROVIDERS / `fhcode.config.json` / 单环境变量 `FH_MODEL_*`）；`swe` 新增 `--max-iterations` 控制每子任务推理轮数；针对真实模型强化执行纪律（强制工具落地、必须真跑验证、禁谎报、只改相关文件）与自愈注入（注入真实命令输出）；`scripts/verify-m9-real.mjs` 以 mock HTTP 服务实测"真实 provider 全链路"（11/11 通过）✅
-
----
-
-*晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹*
+# 飞虹 Code（fhcode）技术说明书
+
+**版本**：v0.5.0-b
+**日期**：2026-08-16
+**产品**：飞虹 Code（feihong-code）— 终端 AI 编程智能体（Muse Code 参照复刻）
+**署名**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+
+---
+
+## 一、产品概述
+
+飞虹 Code（fhcode）是一款运行在终端/Web/IDE 三端的 AI 编程智能体，以「自然语言 → 代码闭环」为核心，支持多模型路由、企业级安全、全自动软件工程与自我迭代。零第三方运行时依赖（仅 express + zod），离线可用，可私有化部署。
+
+**核心能力矩阵（v0.5.0）**：
+
+| 领域 | 能力 |
+|------|------|
+| 编排 | ReAct 循环、规划器、上下文压缩、检查点续跑、成本熔断、自愈循环 |
+| 模型 | 多模型路由（成本/能力/延迟策略 + fallback + 统计择优）、OpenAI 兼容 / Ollama / Mock |
+| 工具 | 文件读写编辑、搜索、受管 shell、构建检查、测试运行、web 检索、技能加载 |
+| 自我迭代 | 经验库（强化学习式 upsert/召回）、反思器回流、自愈闭环、eval 跑分、SWE-bench 基准 |
+| 安全 | 沙箱四档、网络域名规则、hooks 确定性控制、RBAC、审计哈希链、配额熔断、脱敏、入站签名校验 |
+| 生态 | SKILL.md 技能标准、Skills 市场（agentskills.io）、MCP、插件分发、Agent teams |
+| 交付 | CLI/TUI、Web 控制台（任务面板）、VSCode 扩展、跨进程任务队列、消息渠道 |
+
+---
+
+## 二、系统架构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         接入层                               │
+│  CLI (index/run/repl/TUI) · Web (server/task-queue) · IDE 扩展 │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+┌──────────────────────────────▼──────────────────────────────┐
+│                       编排层 agent/                          │
+│  Orchestrator(ReAct) · planner · repo-reader · swe-agent     │
+│  subagent(嵌套) · team(消息总线) · self-heal · experience     │
+│  quality-gate · code-writer · repo-context · symbol-index    │
+└──────────────┬───────────────────────────────┬──────────────┘
+               │                               │
+┌──────────────▼──────────────┐  ┌─────────────▼──────────────┐
+│       模型层 models/          │  │       工具层 tools/          │
+│  ModelRouter(策略+统计)      │  │  file/search/shell/verify   │
+│  OpenAICompatible/Ollama/Mock│  │  web(MCP) / skills(load)    │
+│  sandbox(四档+网络规则)      │  │  tool.registry(zod+守卫)    │
+└──────────────┬──────────────┘  └─────────────┬──────────────┘
+               │                               │
+┌──────────────▼───────────────────────────────▼──────────────┐
+│            安全层 enterprise/ + runtime/hooks               │
+│  tenant(多租户) · policy(RBAC) · audit(哈希链) · quota       │
+│  guard(守卫) · hooks(PreToolUse/PostEdit) · channels(渠道)  │
+└──────────────────────────────┬──────────────────────────────┘
+                               │
+┌──────────────────────────────▼──────────────────────────────┐
+│          基础设施 shared/ + runtime/                         │
+│  config(env 优先) · i18n(中英) · logger(脱敏JSON) · errors   │
+│  event-log(JSONL) · session-persist(检查点) · git · worktree │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**模块目录**（`src/`）：
+
+| 目录 | 职责 |
+|------|------|
+| `cli/` | 参数解析、命令分发、运行装配、REPL/TUI、版本 |
+| `agent/` | 编排器、规划器、SWE、子代理、团队、自愈、经验、符号索引、仓库上下文 |
+| `models/` | 模型路由、供应商（OpenAI 兼容/Ollama/Mock）、成本估算、DTO 校验 |
+| `tools/` | 工具系统：文件/搜索/shell/验证/web/MCP/技能加载/沙箱 |
+| `enterprise/` | 多租户、RBAC 策略、审计链、配额、守卫 |
+| `runtime/` | 事件日志、会话持久化、git 辅助、worktree、hooks |
+| `shared/` | 配置、i18n、日志（脱敏）、错误层级、类型 |
+| `skills/` | 技能标准（SKILL.md 加载）、技能市场（agentskills.io）、/plan /grill /goal |
+| `plugins/` | 插件分发（plugin.json 打包 skills+hooks+MCP） |
+| `web/` | Web 控制台、任务队列、消息渠道、入站签名校验 |
+
+---
+
+## 三、核心模块详解
+
+### 3.1 编排器（agent/orchestrator.ts）
+
+ReAct 主循环 `run(goal, resume?)`，单次迭代：
+1. `router.chat()` 调用模型（带能力标签路由）
+2. 无工具调用 → 任务完成；有 → `executeToolRound()` 执行工具并回填 tool 消息
+3. 错误检测：`roundErrors > 0` → `handleRecovery()`（分类 → 注入反思 → 重试，上限 `maxRetryErrors`）
+4. 上下文压缩：`shouldCompact()` 触发时保留 system 指令（H4 修复）
+5. 检查点落盘（`persist` 回调）+ 事件流（`onEvent`，P0-1 流式输出）
+
+**事件流（P0-1）**：`OrchestratorEvent` 判别联合——model.response / tool.call / tool.result / self-heal / context.compact / session.end，CLI 流式渲染、TUI header 驱动、eval 计数复用同一事件源。
+
+**成本熔断（M4）**：`cost >= maxCostUsd` 立即中止并提示 `resume` 续跑；`maxCostUsd=0` 不限。
+
+**经验回流（M6）**：会话结束 `extractExperience()`（表驱动 EXTRACTORS）→ `upsertExperience`（稳定 id 合并、sessionCount 累积、成功率加权平均）；自愈成功额外固化 `extractFixPattern`。
+
+### 3.2 模型路由（models/model-router.ts）
+
+- 策略：`cost`（按 costPer1k）/ `latency`（本地优先）/ `capability`（标签加权）
+- 择优：`rank(tags)` 能力过滤 + 历史成功率加权（≥3 次调用，最多 +0.3）
+- fallback：按序尝试，失败记 `p.model`（修复：不产生空模型名条目），全部失败抛最后错误
+- 统计：`updateStat()` 自动落盘（`statsHomeDir`，P5 闭环修复），`model-stats` 命令可查
+- 子任务分工（P1-1）：`tags: ['code-gen','cheap']` 让低成本模型承担子任务
+
+### 3.3 工具系统（tools/）
+
+- `ToolRegistry`：注册/查找/执行，zod 校验入参，错误归一为 `ToolResult`
+- 执行链顺序（纵深防御）：**沙箱 → PreToolUse hook → RBAC 守卫 → 工具 → PostToolUse/PostEdit hook**
+- 沙箱四档（P0-2/P5-4）：`read-only` / `workspace-write` / `danger-full-access` / `container`（Docker 挂载工作区执行 shell）
+- 网络域名规则：`FH_NETWORK_ALLOW/DENY` 对 run_shell 命令 URL 与 web 工具 URL 均生效
+- hooks（P2-1）：`FH_HOOKS` JSON 数组，PreToolUse 非零退出拦截、PostEdit 编辑后触发，占位符 `{cwd}{tool}{path}{runId}{ok}`
+
+### 3.4 SWE Agent（agent/swe-agent.ts + swe-planner + swe-verifier）
+
+仓库读取（`repo-reader`，限流/忽略规则）→ 任务拆解（`planSweTask`）→ 逐任务「实现（runSubTask）+ 验证（构建/测试）+ 自愈重试」→ 报告。支持 `--plan-only` / `--verify-only` / `--max-tasks` / `--max-retries`。
+
+**子代理（P3-4）**：`runSubAgent` 深度控制（默认 3 层），目标可拆解且未达上限时递归派生子代理（子目录隔离），逐层摘要回传（`summarizeSubTaskAnswer`，P2-2）。
+
+### 3.5 Agent teams（agent/team.ts，P4-2）
+
+- `TeamBus`：消息总线（send/receive/broadcast 定向与广播）
+- `TaskBoard`：共享任务清单（claim 原子认领防重复，状态+owner 双校验）
+- `runTeam`：多 agent 并发认领执行，`ok=false` 记 failed（修复），产出团队报告
+
+### 3.6 企业安全（enterprise/）
+
+| 模块 | 机制 |
+|------|------|
+| tenant | 租户隔离目录（`tenants/<id>/{sessions,audit,goals}`） |
+| policy | RBAC：角色-工具矩阵（viewer/developer/operator/admin）+ denyShell 黑名单 + denyPaths 敏感路径，deny 优先 |
+| audit | 哈希链（SHA-256，seq/prevHash 衔接），跨进程文件锁 + 指数退避，写入前脱敏，`audit verify` 校验 |
+| quota | 租户日成本预算（`FH_TENANT_BUDGET_USD`），启动前 fail-fast 实时复核（M14 修复） |
+| guard | 「策略→审批→审计」工具前置钩子，审计失败=拒绝 |
+
+### 3.7 技能与市场（skills/）
+
+- **SKILL.md 标准（P1-2）**：frontmatter（name/description）+ 正文；渐进式披露——索引（≤8KB）常驻 system prompt，正文由 `load_skill` 工具按需加载（Tier-2）
+- 发现位置：仓库 `.agents/skills` / `.claude/skills` 逐级回溯 + 打包 `skills/` + 用户级 `~/.feihong-code/skills` + 插件技能目录
+- **技能市场（P6）**：agentskills.io discovery 规范（`/.well-known/agent-skills/index.json`），`skill-market search/install/list`；RFC 3986 URL 解析、sha256 digest 校验、tar.gz 归档解包（零依赖手写，路径穿越防护）
+- **插件（P3-3）**：`plugin.json` 打包 skills+hooks+MCP，用户级/项目级双级发现，`plugin install`（本地目录/git clone）
+
+### 3.8 Web 与云执行（web/）
+
+| 端点 | 说明 |
+|------|------|
+| `GET /api/health` | 公开健康检查（免鉴权） |
+| `POST/GET /api/tasks`、`GET /api/tasks/:id` | 任务队列（Bearer 鉴权，P4-1） |
+| `POST/GET /api/webhook` | webhook 调度入口注册/查询（P5-2） |
+| `/api/...` 其它 | 需 `FH_WEB_TOKEN` Bearer（fail-closed，计时安全比较） |
+
+**任务队列（P4-1/P6-4）**：状态机 queued→running→done|failed；并发上限（`FH_TASK_CONCURRENCY`）；跨进程持久化（`FH_TASK_PERSIST_DIR`，每任务一文件原子写，重启恢复：queued 重新入队、running 僵尸标记 failed）；webhook 状态回调（携带状态快照，修复 queued 丢失时序缺陷）。
+
+**消息渠道（P5-6/O6）**：Telegram（`FH_CHANNEL_TELEGRAM_BOT_TOKEN`+`CHAT_ID`）与企业微信（`FH_CHANNEL_WECOM_KEY` 多 key）出站推送；出站白名单 `FH_CHANNEL_ALLOW`；入站签名校验工具 `verifyHmacSignature`（HMAC-SHA256 计时安全）/ `verifyWecomSignature`（企微 SHA1 排序）。
+
+### 3.9 IDE 扩展（vscode-extension/）
+
+薄壳设计（逻辑全在 CLI）：`fhcode.run`（选区上下文注入 `<selection>`）、`fhcode.review`（`review --json` → 编辑器内联诊断 DiagnosticCollection + CodeAction 建议）、`fhcode.diff`（原生 diff 编辑器 HEAD↔工作区，`fhcode-head` scheme）、`fhcode.output`；配置 `binaryPath` / `offline` / `reviewOnSave`。
+
+---
+
+## 四、协议与规范
+
+| 协议 | 说明 |
+|------|------|
+| 工具调用契约 | OpenAI 风格 `tool_calls`（name/arguments JSON），结果以 role=tool 回填（toolCallId 对应） |
+| MCP | stdio 传输（NDJSON JSON-RPC 2.0）：initialize → notifications/initialized → tools/list → tools/call；工具以 `<server>_<tool>` 前缀注册 |
+| SKILL.md | open agent skills 兼容（frontmatter name/description + 正文，渐进式披露） |
+| agentskills.io | discovery index 0.2.0：`$schema` 校验、skill-md/archive、digest `sha256:<hex>` |
+| webhook | `POST {url}` JSON：`{event:'task.status', task:{...}, ts}`（状态快照） |
+| 入站签名 | HMAC-SHA256（`sha256=<hex>` 头）或企微 SHA1 排序 |
+| 检查点 | `<runId>.session.json`（完整对话/迭代/成本/touchedFiles），resume 续跑 |
+
+---
+
+## 五、安全设计
+
+1. **纵深防御**：沙箱（技术边界）→ hooks（确定性控制）→ RBAC 策略（权限）→ 审计（留痕）→ 配额（成本）
+2. **沙箱**：四档 + 网络域名规则（deny 全模式生效、allow 未命中即拦截）；`container` 档 Docker 隔离
+3. **命令防护**：run_shell 注入元字符拦截（`[;&|`$(){}<>!]` 等）；受管命令（run_tests/build_check）仅允许包管理器脚本
+4. **路径安全**：`safeJoin`（词法 + realpath 符号链接校验）；策略 denyPaths 敏感路径黑名单（.env/.git/config/密钥等）
+5. **审计**：哈希链不可篡改（verifyAudit 检 seq/prevHash/hash 自洽）；写入前脱敏（SECRET_RE/Bearer/JWT/sk-）
+6. **日志脱敏**：敏感 key 整值遮蔽 + 值形态（sk-/JWT/长令牌）遮蔽
+7. **Web 鉴权**：Bearer token 计时安全比较（timingSafeEqual），fail-closed；body 限制 1MB
+8. **入站安全**：webhook 签名校验（HMAC/企微），渠道白名单
+9. **技能安全**：市场技能 digest 校验防投毒，tar.gz 路径穿越防护，SKILL.md 强制 name frontmatter
+
+---
+
+## 六、性能与质量基线（v0.5.0-b 实测）
+
+| 指标 | 值 |
+|------|----|
+| 单元测试 | 164/164 全绿（16 模块 + 10 特性域） |
+| 里程碑断言 | M4 41 · M6 29 · M7 12 · M8 27 · M9 25 = 134 全绿 |
+| eval 跑分 | 10/10（场景 5 + 验收 5，真实产物验证，整体通过率 100%） |
+| SWE-bench 加载器 | HF datasets-server / 镜像 / 缓存，mock 执行 + 报告 |
+| 复杂度 | 676 函数，cc≥10 热点 52 个（核心决策函数保持，规则类已表驱动化） |
+| 依赖 | 运行时仅 express + zod（零其它运行时依赖，离线可用） |
+
+---
+
+## 七、配置模型（铁律：一切配置来自环境变量，启动时校验，fail-fast）
+
+优先级：`FH_PROVIDERS`（JSON）> `fhcode.config.json` > 单环境变量 `FH_MODEL_*`；安全类（deny 黑名单）为并集只能加严。完整清单见《配置参考》《部署说明书》。
+
+---
+
+## 八、版本与演进
+
+- v0.4.0：P0-P5 全能力（流式/沙箱/MCP/Skills/插件/云队列/渠道/语义索引）
+- v0.5.0（2026-08-17 正式发布）：整合 IDE 深度集成首轮（review --json + 内联评审 + 上下文入参）、SWE-bench 基准接入（数据集加载 + mock 执行 + 报告）、eval 回归门禁、O6 入站签名校验与安全前置
+- 规划 v0.5.0-c/d：容器化 SWE 执行 + 真实模型跑分、消息渠道入站调度（详见《规划_v0.5.0.md》）
+
+---
+
+*本说明书随版本持续更新，能力以源码与 `fhcode --help` 为准。*