feihong-code

feihong-code

feihong-code is an open-source terminal AI programming agent benchmarking Meta Muse Code. It provides multi-model routing, parallel sub-agents, breakpoint recovery, enterprise RBAC and multi-tenant quota management. This framework is adopted by local manufacturing enterprises in Jinjiang to build AI applications. As the primary maintainer, I continuously manage issues, PR reviews, releases and security audits. License: Apache-2.0

English / 英文文档：README_EN.md · FAQ (English)

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/TECHNICAL-SPECIFICATION.md。

飞虹 Code（fhcode）

终端 AI 编程智能体 · 对标 Meta Muse Code / Claude Code / Cursor CLI · 自研内核实现差异化 · 全功能 M0→M9.1 完成 · 企业级 RBAC/审计/SWE Agent 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹

🔒 私有化部署与数据安全（为何选 fhcode 而非闭源 SaaS）

fhcode 从第一天起就为「数据不出域、代码可审计、合规可控」而设计，这与依赖云端积分的闭源桌面 AI 助手形成根本差异：

能力	fhcode（飞虹 Code）	闭源云端 SaaS 助手
源码与可审计性	Apache-2.0 开源，代码公开可自查、可二次审计	闭源，代码不可见
部署形态	支持完全私有化 / 离线部署，模型可走本地 Ollama	官方模型与积分多依赖云端
权限与审计	RBAC 权限矩阵 + 防篡改审计哈希链 + 多租户物理隔离	通常无细粒度审计
数据合规	数据不出域，满足政务 / 金融 / 保密场景	敏感代码 / 文档上云存在合规风险
安装可信	提供可校验的构建产物与发布流程	部分未做可信代码签名

适用场景：受监管行业、企业内部研发、涉密项目——需要「看清代码、掌控数据、留痕可溯」的团队，fhcode 的私有化 + 离线 + 审计链路是默认能力，而非增值插件。详见 部署指南。

🆕 v8.7.0 对标纳米Work 四大能力（2026-10-04）

对标 360 纳米Work（企业智能体工作平台），补齐「成本调度 / 专家创建 / 7x24 自动化 / 记忆复用」四项核心能力。运行模式从「工具等人用」升级为「系统按规则自己跑，人只管审批和纠偏」。

• ① 算力档位智能调度（轻量 / 省钱 / 满血）：按任务复杂度自动分档路由模型，fhcode tier set full 全局锁定、--tier 单次覆盖；省档优先低成本/本地模型。
• ② 对话式专家创建向导：4 步创建专属 AI 专家（选模板→填提示/工具→选档位→命名），fhcode agent-new 交互或 --name/--prompt/--tier 一键创建。
• ③ 自动化任务真实执行（云端 7x24）：fhcode routine add --cron "0 * * * *" --goal "..." 建定时任务，fhcode serve 常驻后台真实执行（AI 任务 / shell 命令均落地）。三级规则引擎 + 审批收件箱门控：硬红线（改密码/转账/永久删除/外发）恒拦截，ask 进审批收件箱，人工放行后执行。
• ④ 工作记忆增强（跨会话复用）：默认装配分层记忆——启动召回历史决策/产物注入上下文、过程自动压缩、结束沉淀项目记忆；fhcode memory profile 查看业务画像总览。

质量终态：单测 376/376 全绿（54.3s），typecheck / build / verify 链（m4·m6·m7·m8·m9·routines·policy）全绿。详见 CHANGELOG。

在 WorkBuddy IDE 内跑测试请用 NODE_OPTIONS="" npm test：IDE 注入的 shim 会拦截 fs.unlink，导致审计锁死锁、整轮挂死 20+ 分钟；绕过 shim 后 54 秒跑完全绿。

Web API：/api/routines 系列（增删查改 + 手动触发 + 审批收件箱），详见 API 文档。

🆕 v8.6.0「Always-on 飞虹 dots」（2026-10-02）

借鉴 OpenAI dots 范式完成四期升级，主打全天候 Agent 三块基石：知道自己能干什么、记住发生过什么、按计划自主干活且不越权。

• P1 Agent 自我认知：启动时把运行时工具注册表（21 工具）自省注入系统提示词，代码为单一事实源，来源损坏自动回退不阻断；scripts/gen-tool-schema.ts 可随时重新生成 schema。
• P2 透明记忆：Agent 记忆可读/可编辑/可导出（JSON/Markdown round-trip），导出默认脱敏，存储层 userId+id 双条件防越权——对比同类产品记忆封闭不可带走。
• P3 Routines 调度：五字段 cron（宏/步进/区间）+ 事件触发 + 错过窗口补偿恰好一次 + 运行中互斥/全局并发上限 + 指数退避重试，任务定义与状态原子写持久化。
• P4 三级规则引擎 + 审批收件箱：allow/ask/deny 三级判定（红线>精确>通配>fail-safe ask）；硬红线四类任何规则不可放行（改密码/转账/永久删除/外发）；审批闭环 submit→pending→approved/rejected/expired，裁决幂等、TTL 过期、事件入审计哈希链、落盘脱敏。

质量终态：单测 354/354；verify 链十项 165 项端到端全绿（m4 41 + m6 29 + m7 12 + m8 27 + m9 25 + routines 18 + policy 13）。详见 CHANGELOG 与 产品说明书。

🔍 关键词：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 商业智能体生态的核心组件，源代码采用 Apache-2.0 开源，企业版增值能力（激活码激活、私有化部署与商业支持）采用商业授权双轨模式。

• 🏠 官方网站：https://www.klai.top — 飞虹智 klAI · 泉州制造业 AI 服务商
• 📦 产品中心：https://www.klai.top
• 🤖 AI Agent 入口：https://www.klai.top/openclaw.html

零、For AI Agents（面向 AI 智能体）

本项目专为 AI Agent 设计，提供结构化 CLI 与明确工具契约。详见 AGENT-GUIDE.md 与 tool-schema.json。

快速评估项目是否适合你的 Agent：

fhcode --help                    # 查看所有命令
fhcode "你的目标"                # 单任务执行
fhcode --parallel "目标A 并且 目标B"  # 并行子任务
fhcode swe "修复仓库 X 的问题 Y"  # 全自动软件工程

推荐配置（生产环境）：

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）	✅	❌	❌	❌	❌
授权模式	✅ Apache-2.0 开源 + 商业授权（激活码/企业版）	❌	❌	✅ Apache-2.0	✅ MIT

最适合：数据不出内网、需要企业权限审计、希望混合调度多家大模型的团队与个人开发者。

🎯 差异化能力（自研内核）

上表说明"能力有无"，下表说明"同样的能力，fhcode 做得有何不同" —— 这部分是本项目独立设计与实现的结果，也是与对标对象形成区隔的核心。

差异化维度	fhcode 的实现	同类产品普遍现状
模型调度	统一网关抽象层，DeepSeek / 通义 / Ollama / 任意 OpenAI 兼容端点按成本与能力动态路由	多数绑定单一模型厂商，切换成本高
离线私有化	Ollama 本地推理 + 全链路断网可用，代码与数据不出内网	多数强依赖云端 API，无法满足内网合规
企业治理	RBAC 权限矩阵 + 防篡改审计哈希链 + 多租户物理隔离 + 配额成本熔断，四件套开箱即用	多为个人向工具，缺权限与审计体系
自我进化（M6）	经验库沉淀 + 自愈循环，失败模式跨会话复用，越用越准	基本无对应机制
并行隔离（M2）	git worktree 为每个子代理建立物理隔离工作区，并发推进零冲突	部分支持，隔离强度与冲突处理参差
可恢复性（M3）	append-only 事件日志为单一可信源，会话可断点恢复、可完整回放	会话状态多不可恢复，中断即重来
授权与自托管	代码 Apache-2.0 开源自托管；企业版增值能力（激活码、完全私有化部署与授权范围内的二次开发服务）采用商业授权	主流产品为闭源商业服务

一句话区分：对标产品解决"个人开发者如何更快写代码"，fhcode 额外解决"团队如何在合规边界内、可审计地、用可控成本把 AI 编程落地到生产"。

📸 产品截图

CLI 终端	Web 控制台	功能对比

二、核心特性

🔥 主要亮点

• ✅ 自然语言 → 代码闭环：描述需求，自动调用工具完成改码与验证
• ✅ 多模型路由：支持 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 纪律强化	✅ 完成
v8.6.0 P1-P4	Always-on 飞虹 dots：自我认知/透明记忆/Routines/规则引擎+审批	✅ 完成

🌟 技术亮点

• 核心依赖轻量：核心运行时仅依赖 express + zod，无框架包袱（另含 monaco-editor / playwright-core 等增强依赖）
• 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 第十三章。

三、安装

方式一：从源码构建（推荐开发 / 内网部署）

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 install.sh

方式二：全局安装（已发布到 npm）

# 官方源
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 >= 22.5.0。入口 dist/cli/index.js 已带 #!/usr/bin/env node shebang。 源码与问题反馈请前往 GitHub 仓库：https://github.com/wch887292/feihong-code

方式三：Docker

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）

node dist/cli/index.js "帮我写一个 hello.ts 并打印一句话"

未配置 FH_PROVIDERS 时，自动用内置 Mock 驱动器跑通完整闭环（规划 → 调工具写文件 → 总结）。

4.2 接入真实大模型

cp .env.example .env
# 编辑 .env，填入 FH_PROVIDERS（baseURL / apiKey / model 等）
fhcode "把 src/utils 的日期格式化抽成独立模块并补测试"

真实配置示例（已验证可用的 Agnes 网关）：

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 多子代理并行

fhcode --parallel "实现登录模块并且添加用户管理并且写集成测试"

自动拆成 3 个子任务，各自在 git worktree 隔离工作区并发执行，结束后清理。

⚠️ 真实并行的并发额度：--parallel 会并发调用 API。免费套餐（如 Agnes free tier）对并发请求有严格限流（HTTP 429），可能导致子任务失败。建议：① 升级 API 套餐；② 或改用单命令模式顺序执行大目标；③ 或用 FH_OFFLINE=true fhcode --parallel "..." 验证并行机制（离线不耗额度）。

4.4 交互 REPL

fhcode            # 不带参数进入 REPL，逐条输入需求；exit 退出

4.5 只读技能（不修改代码）

fhcode /plan  "实现登录并且添加支付并且写报表"   # 生成实现计划
fhcode /grill src                              # 红队式代码审查
fhcode /goal  "搭建多子代理体系并且完善文档"      # 分解并保存目标

4.6 恢复与审计（M3）

每次任务都会把完整对话、迭代计数、成本、被改动文件落盘为会话检查点（<runId>.session.json），可随时恢复与审计：

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 的命令自动通过，其余拒绝并留痕。

fhcode "删除临时缓存并重建"      # TTY 下每条 shell 命令会询问；非 TTY 仅白名单命令可过

4.8 企业能力：权限 / 审计 / 多租户 / 配额（M4）

企业模式默认开启（FH_ENTERPRISE=false 可关闭并退化为 M3 行为），身份由环境变量注入，便于容器与网关下发：

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，形成链式结构；任何改写、删除、插入都会导致链断裂：

$ 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，不产生任何模型费用：

$ 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 tier [get|set <档位>]	算力档位（light 轻量 / save 省钱 / full 满血）查看与全局锁定；--tier 单次覆盖
fhcode agent-new	对话式创建专属 AI 专家（4 步向导）；--name/--prompt/--tools/--tier/--category 非交互创建
fhcode routine list|add|run|enable|rm	自动化定时任务（云端 7x24 真实执行）：add --cron "0 * * * *" --goal "..."，fhcode serve 后台调度
fhcode memory profile|stats|clear	工作记忆：业务画像总览 / 分层记忆统计 / 清空项目记忆（clear 需 --yes）
fhcode approvals list|show|approve|reject	审批收件箱：查看待决审批 / 详情 / 批准放行 / 拒绝（list --all 含已裁决，--by<裁决人>）

Web 控制台同步可视化（fhcode serve）：右侧「⏱ 定时任务」tab可新建/立即执行/启停/删除 cron 任务并直接裁决待审批；左侧「记忆系统」页的「📊 业务画像」区块展示累计任务、时间跨度、高频领域、关键决策与产物——与 CLI 同源数据。 | 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 沙箱内。

七、安全模型

• 路径沙箱：safeJoin 校验每个文件路径不得超出 cwd，杜绝 ../ 越权。
• Shell 白名单：run_shell 仅在命令首词命中 FH_SHELL_ALLOW 时放行；非交互 CLI 下，命中白名单者由默认审批器自动通过，其余拒绝并留痕。
• 密钥脱敏：日志按 key 名（apikey|secret|token|...）将值替换为 [REDACTED]，且不回显完整 API key。
• 审批拦截：FH_REQUIRE_APPROVAL=true（默认）时，危险操作需审批通道；TTY 交互终端逐条弹 y/n 确认，非交互（CI/管道）则回退白名单审批器——命中 FH_SHELL_ALLOW 自动通过、其余拒绝并留痕。
• .env 不入库：已被 .gitignore 排除；package.json 的 files 白名单确保 npm publish 不会携带 .env。
• RBAC 策略引擎（M4）：角色-工具矩阵 + deny 优先的危险命令 / 敏感路径黑名单，admin 亦不可绕过；策略只能被下级配置加严。
• 防篡改审计（M4）：全量动作（allow/deny/approved/rejected）写入 sha256 哈希链，fhcode audit verify 可定位篡改位置；审计写失败即拒绝执行。
• 租户隔离与配额（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。.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。

v8.5.0 架构治理（B3 全链路）

为消除历史神文件（god-file）、提升可维护性，v8.5.0 对两大核心模块做了彻底拆分，全部 API 向后兼容（CLI 命令、Web 路由、配置格式均无 breaking change）：

• src/web/server.ts：从约 3585 行历史峰值降至约 690 行，路由按业务域下沉到 src/web/routes/：managers（三端同步 / 变更管理 / MCP / Git / 团队 / SOLO / 多智能体 / 事件驱动 / 自定义 Agent）、model-domain（代码补全 / 补全 Pro / 设计稿转代码 / 大模型配置 / 共享 ModelRouter）、filesystem（工作区与文件浏览 / 打开文件夹浏览器 / 上传 / 系统截图 / 自然语言指令直达）、cline（Cline 进程级嫁接）、cloud-bridge（手机指令 → 电脑执行云桥接全生命周期 + 授权激活，含暴力破解防护）、capability-source（节点系统 / 技能市场 / 自动化 / 模板库 / 办公助理）、computer（电脑操作）。采用 registerXxx(app, deps) + Deps 依赖注入接口；可变绑定（serverWorkspaceDir、sharedModelRouter）以 getter/setter 注入保活。
• src/cli/run.ts：从 1889 行改为 32 行薄转发层（export * 再导出），命令实现下沉到 src/cli/cmds/ 下 11 个模块：skills / sessions / enterprise / integrations / skill-market / self-evolve / code-write / swe / harness / computer-control / license。cli/index.ts、repl.ts 零改动。
• 循环依赖打断：新增中性模块 src/core/task-executor.ts 承载 executeTask，切断 cli/run → web/server → web/task-queue → cli/run 依赖环。
• 验证：类型检查 / 构建 / 运行时冒烟（CLI 入口、转发层 39 符号、18 个拆分模块加载）全部通过。

十、开发

npm install
npm run build      # tsc 编译到 dist/
npm run dev        # tsx 直接跑源码（免构建）
npm run typecheck  # 仅类型检查
npm test           # 全量单元测试（354 项）
npm run verify:m4  # M4 企业能力断言套件（41 项，全离线）
npm run verify     # 十项链：typecheck + check:version + build + m4/m6/m7/m8/m9 + routines(18) + policy(13)
node dist/cli/index.js --version

工程规范（全栈铁律）

• 边界必须校验（CLI 参数 / 模型响应 / 工具入参 → zod）。
• 集中配置（shared/config.ts，启动校验、fail-fast、懒加载）。
• 类型化错误（AppError 子类，禁止裸 throw）。
• 结构化日志（JSON + runId，密钥脱敏）。
• 单一可信源（行为以 runtime/event-log 为准）。

十一、部署

• npm 全局：npm install -g . 或发布后 npm install -g feihong-code。
• Docker：见 Dockerfile（多阶段，已含 git 以支持 --parallel）。
• CI：见 .github/workflows/ci.yml，三条流水线全离线、零 Secrets：
  • build：Node 22.5/24 矩阵 → typecheck → 编译 → 离线端到端 → 只读技能；
  • enterprise：M4 断言套件（41 项）+ CLI 企业命令冒烟 + 租户隔离断言（beta 租户不得读到其它租户会话）；
  • security：npm pack 白名单校验（禁止 .env/src/policy.json 入包）+ 仓库明文密钥扫描 + npm audit。
• 发布：npm publish 仅携带 files 白名单（dist + 文档），密钥安全。
• 部署细节见 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 — 面向 AI Agent 的使用指南（环境、配置、工具契约）
• tool-schema.json — 所有工具的 JSON Schema 定义
• GEO-AAO-STRATEGY.md — 生成式引擎优化与 Agent 优化策略

稳定版首选

• 产品说明书 v8.6.0 — 超详细一站式：安装→部署→授权激活→功能使用→v8.6.0 新功能→FAQ
• 技术说明书 — 架构、企业能力技术细节、数据契约、CLI/Web API、部署架构、安全模型、构建验证
• 使用说明书 — 安装、快速上手、命令总览、核心工作流、企业版/Web 控制台使用、配置、排错

补充参考

• 用户手册 — 各命令详解、工具说明、审批与安全、最佳实践
• 配置参考 — 全部 FH_* 环境变量与 FH_PROVIDERS 详解
• 架构与 API — 分层、编排循环、模型路由、工具协议、事件日志
• 部署指南 — npm / Docker / CI / 发布 / 密钥安全
• 企业部署与合规 — RBAC 角色设计、审计取证、多租户方案、配额治理（M4）
• 常见问题与故障排查 — FAQ 与排错
• 产品开发文档 — 需求/里程碑/设计决策（演进稿）

稳定部署产物：Dockerfile、docker-compose.yml、install.sh、CHANGELOG.md（见仓库根目录）。

🤝 社区支持

关注飞虹智 klAI 动态，获取最新开源项目更新与技术教程：

• 🏠 官网与开源矩阵：https://www.klai.top/opensource.html
• 🤖 AI Agent 入口：https://www.klai.top/openclaw.html

加入 飞虹智企微小助手，获取：

• 技术答疑与部署指导
• 开源项目更新通知
• 本地化服务预约（泉州地区）
• 企业 AI 数字化咨询

晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹

十四、版权与署名

• 公司：晋江市飞虹智科技企业管理有限公司
• 中心：飞扬企源研发中心
• 负责人：吴赐虹

© 2026 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹 源代码基于 Apache License 2.0 开源发布；企业版增值能力（激活码、私有化部署、商业支持）采用商业授权，详见 NOTICE 双轨授权说明。

组织与署名

公司：晋江市飞虹智科技企业管理有限公司 中心：飞扬企源研发中心 负责人：吴赐虹

• 官网：https://www.klai.top
• 知识库：https://kb.klai.top
• 开源矩阵：https://github.com/wch887292
• 实体权威声明（机器可读）：https://www.klai.top/entity.jsonld

本项目版权归 晋江市飞虹智科技企业管理有限公司 所有，由 飞扬企源研发中心 研发交付。