feihong-code 8.0.2 → 8.3.0

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

@@ -1,146 +1,146 @@
-# 飞虹 Code（fhcode）使用说明书 · v8.0.1
-
-> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
-> 适用版本：v8.0.1（2026-09-08） · 对应 GitHub: wch887292/feihong-code · npm: feihong-code
-
----
-
-## 一、这是什么
-
-飞虹 Code 是一款终端 AI 编程智能体（对标 Muse Code / Claude Code / Cursor CLI），以自研内核实现差异化：
-多模型路由、企业级 RBAC/审计/多租户、全自动 SWE Agent、桌面手脚（Windows 原生操控）、AI 员工军团。
-
-**v8.0.1 定位**：在 v8.0.0 基础上，把「AI 操控电脑」与「企业 AI 员工军团」两条主线接进飞虹，
-形成「指挥中心 → 手脚」的完整闭环，并完成全仓脱敏与清理加固。
-
-## 二、安装
-
-```bash
-# 全局安装（CLI）
-npm install -g feihong-code
-fhcode --version          # v8.0.1
-
-# 或从源码运行（开发）
-git clone https://github.com/wch887292/feihong-code.git
-cd feihong-code
-npm install
-npm run build
-node dist/cli/index.js --version
-```
-
-环境要求：Node ≥ 22.5；Windows / Linux / macOS。
-
-## 三、快速开始
-
-```bash
-# 首次运行：配置模型（fhcode config 引导，或直接编辑 %USERPROFILE%\.feihong-code\fhcode.config.json）
-fhcode config
-
-# 开始任务（自动规划→工具→验证闭环）
-fhcode "修复 src/utils 里的类型错误并跑单测"
-
-# 交互模式
-fhcode
-```
-
-## 四、新能力一：桌面手脚（Windows 原生操控）
-
-让飞虹直接操作本机原生 app（记事本、WPS、剪映、客户 ERP 等），三步开启：
-
-1. **配置**（零代码）：`%USERPROFILE%\.feihong-code\fhcode.config.json` 已内置 `mcp.servers[0]`（name=desktop），
-   指向 desktop-touch MCP 运行时并带 11 个工具白名单。首次运行自动挂载。
-2. **使用**（3 个原生工具）：
-   | 工具 | 作用 |
-   |---|---|
-   | `feihong_desktop_see` | 只读勘察：看屏幕/窗口树/服务器状态，可 filter 精确窗口 |
-   | `feihong_desktop_act` | 写操作：launch / focus / click / type / drag / scroll / 终端命令，自动过守卫 |
-   | `feihong_desktop_verify` | 验证：截图 + 状态回读，断言 expectText / expectWindow |
-3. **安全护栏**（内置）：
-   - 写操作一律需审批（operator/admin），只读沙箱直接拦截；
-   - 危险窗口停手线：任务管理器 / 注册表编辑器 / UAC / Windows 安全中心 / 系统配置 / 设备管理器 / 磁盘管理 / 本地组策略，子串匹配管理员也拦；
-   - 环境变量 `FEIHONG_DESKTOP_BLOCK_WINDOWS` 可扩展黑名单；
-   - 每步操作取证留痕（JSONL + 截图），目录 `<FH_HOME>/forensics/<runId>/`，`FH_FORENSICS_DIR` 可覆盖。
-
-> 演示话术：「打开记事本，输入『你好飞虹』，截图验证」——飞虹会走 see→act→verify 全流程。
-
-## 五、新能力二：AI 员工军团（agent-team）
-
-17 个业务 AI 员工（五层体系）随仓库分发：
-
-| 层 | 员工 |
-|---|---|
-| L1 获客 | 01 获客线索雷达 / 06 每日精准获客选题官 / 07 外贸开发客户员工 / 08 小红书精准获客员工 |
-| L2 内容 | 05 同行爆款雷达 / 12 老板短视频获客脚本官 / 13 博主账号深度拆解官 / 14 AI短视频自动剪辑师 / 15 公众号自动运营发布官 |
-| L3 转化 | 02 AI销售跟进销冠 / 04 客户聊天成交分析官 / 09 私域客户分层跟进官 |
-| L4 决策 | 03 评论区商机识别官 / 10 GEO商机诊断官 / 16 行业深度分析师 / 17 投资研究咨询官 |
-| L5 管理 | 11 一人公司AI员工调度官 |
-
-使用方式：
-
-```bash
-# 飞虹原生工具（推荐）
-feihong_agents_list                     # 员工清单 / scope=stats 任务统计（只读）
-feihong_agents_submit agentId=1 input='{"channels":"[朋友圈,抖音]","keywords":"企业AI"}'  # 需审批
-
-# 或命令行直接跑（agent-team/ 目录内）
-python main.py list-agents
-python main.py submit --module 01 --input '{"channels":"[A,B]","keywords":"测试"}'
-python main.py run-once
-```
-
-- 模型路由：自动复用飞虹 `models.providers` 第一个 openai-compatible 带 key 的 provider；
-  无配置时回退 mock（本地确定性，全链路可跑）。
-- 17 个技能（SKILL.md + run.py）已安装到用户级技能目录，对话中按触发场景自动加载。
-- 技能也可独立跑：`python run.py --input '{...}'`（纯标准库，`--llm` 可接豆包 API）。
-
-## 六、模型配置
-
-`fhcode.config.json` 的 `models.providers`：
-
-```json
-{
-  "models": {
-    "providers": [
-      { "id": "ark", "type": "openai-compatible", "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
-        "model": "doubao-seed-1-6-250615", "apiKey": "sk-xxx", "tags": ["code-gen"] }
-    ]
-  }
-}
-```
-
-支持 openai-compatible（DeepSeek/通义/豆包/OpenAI 兼容网关）与 Ollama 本地模型。
-
-## 七、安全与合规
-
-- **权限**：RBAC 五角色（viewer/developer/operator/admin），写操作需审批，成本上限控制；
-- **脱敏**：审计日志自动脱敏 API Key / token（`sk-*` → `***`）；
-- **桌面手脚**：危险窗口停手线 + 写操作审批 + 取证留痕；
-- **AI 员工军团**：任务提交需审批，apiKey 只作为子进程环境变量传递，不回显不落盘；
-- **密钥管理**：所有密钥只从环境变量 / 用户级配置读取，禁止硬编码进代码或提交进仓库。
-
-## 八、常见问题
-
-**Q1：desktop 工具报「AutoGuardBlocked」？**
-键盘/鼠标动作被 desktop-touch 感知守卫拦截。先 `feihong_desktop_see` 拿到精确窗口标题再 act；
-type 时传 `windowTitle:'@active'` 瞄准当前前台窗口。
-
-**Q2：AI 员工提交后没执行？**
-`executeNow=false` 时任务入队，需 `run-once`（或 `feihong_agents_submit` 默认 executeNow=true 立即执行）。
-
-**Q3：npm 包 build 报 copy-web 崩溃？**
-v8.0.1 已修复：`fs.cpSync(recursive)` 在 Node 22 Windows 触发原生崩溃，已重写为手写递归复制。
-
-**Q4：历史提交过密钥怎么办？**
-本仓库已用 filter-branch 全历史清除泄露密钥并 force push；**请同步到对应平台后台轮换该密钥**。
-
-## 九、目录速查
-
-```
-feihong-code/
-├─ src/                     TS 内核（agent/ tools/ enterprise/ models/ runtime/ …）
-├─ agent-team/              AI 员工军团（Python：main.py + core/ + agents/ + llm/ + skills/）
-├─ docs/                    说明书 / 技术说明书 / 桌面手脚指南 / POC 脚本
-├─ scripts/                 构建与校验（copy-web / verify-m4…m9 / bump-version）
-├─ bench/                   评测脚本（运行产物已清理并 gitignore 加固）
-└─ tests/unit/              单测（269 例，v8.0.1 全绿）
-```
+# 飞虹 Code（fhcode）使用说明书 · v8.0.1
+
+> 晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心 · 负责人：吴赐虹
+> 适用版本：v8.0.1（2026-09-08） · 对应 GitHub: wch887292/feihong-code · npm: feihong-code
+
+---
+
+## 一、这是什么
+
+飞虹 Code 是一款终端 AI 编程智能体（对标 Muse Code / Claude Code / Cursor CLI），以自研内核实现差异化：
+多模型路由、企业级 RBAC/审计/多租户、全自动 SWE Agent、桌面手脚（Windows 原生操控）、AI 员工军团。
+
+**v8.0.1 定位**：在 v8.0.0 基础上，把「AI 操控电脑」与「企业 AI 员工军团」两条主线接进飞虹，
+形成「指挥中心 → 手脚」的完整闭环，并完成全仓脱敏与清理加固。
+
+## 二、安装
+
+```bash
+# 全局安装（CLI）
+npm install -g feihong-code
+fhcode --version          # v8.0.1
+
+# 或从源码运行（开发）
+git clone https://github.com/wch887292/feihong-code.git
+cd feihong-code
+npm install
+npm run build
+node dist/cli/index.js --version
+```
+
+环境要求：Node ≥ 22.5；Windows / Linux / macOS。
+
+## 三、快速开始
+
+```bash
+# 首次运行：配置模型（fhcode config 引导，或直接编辑 %USERPROFILE%\.feihong-code\fhcode.config.json）
+fhcode config
+
+# 开始任务（自动规划→工具→验证闭环）
+fhcode "修复 src/utils 里的类型错误并跑单测"
+
+# 交互模式
+fhcode
+```
+
+## 四、新能力一：桌面手脚（Windows 原生操控）
+
+让飞虹直接操作本机原生 app（记事本、WPS、剪映、客户 ERP 等），三步开启：
+
+1. **配置**（零代码）：`%USERPROFILE%\.feihong-code\fhcode.config.json` 已内置 `mcp.servers[0]`（name=desktop），
+   指向 desktop-touch MCP 运行时并带 11 个工具白名单。首次运行自动挂载。
+2. **使用**（3 个原生工具）：
+   | 工具 | 作用 |
+   |---|---|
+   | `feihong_desktop_see` | 只读勘察：看屏幕/窗口树/服务器状态，可 filter 精确窗口 |
+   | `feihong_desktop_act` | 写操作：launch / focus / click / type / drag / scroll / 终端命令，自动过守卫 |
+   | `feihong_desktop_verify` | 验证：截图 + 状态回读，断言 expectText / expectWindow |
+3. **安全护栏**（内置）：
+   - 写操作一律需审批（operator/admin），只读沙箱直接拦截；
+   - 危险窗口停手线：任务管理器 / 注册表编辑器 / UAC / Windows 安全中心 / 系统配置 / 设备管理器 / 磁盘管理 / 本地组策略，子串匹配管理员也拦；
+   - 环境变量 `FEIHONG_DESKTOP_BLOCK_WINDOWS` 可扩展黑名单；
+   - 每步操作取证留痕（JSONL + 截图），目录 `<FH_HOME>/forensics/<runId>/`，`FH_FORENSICS_DIR` 可覆盖。
+
+> 演示话术：「打开记事本，输入『你好飞虹』，截图验证」——飞虹会走 see→act→verify 全流程。
+
+## 五、新能力二：AI 员工军团（agent-team）
+
+17 个业务 AI 员工（五层体系）随仓库分发：
+
+| 层 | 员工 |
+|---|---|
+| L1 获客 | 01 获客线索雷达 / 06 每日精准获客选题官 / 07 外贸开发客户员工 / 08 小红书精准获客员工 |
+| L2 内容 | 05 同行爆款雷达 / 12 老板短视频获客脚本官 / 13 博主账号深度拆解官 / 14 AI短视频自动剪辑师 / 15 公众号自动运营发布官 |
+| L3 转化 | 02 AI销售跟进销冠 / 04 客户聊天成交分析官 / 09 私域客户分层跟进官 |
+| L4 决策 | 03 评论区商机识别官 / 10 GEO商机诊断官 / 16 行业深度分析师 / 17 投资研究咨询官 |
+| L5 管理 | 11 一人公司AI员工调度官 |
+
+使用方式：
+
+```bash
+# 飞虹原生工具（推荐）
+feihong_agents_list                     # 员工清单 / scope=stats 任务统计（只读）
+feihong_agents_submit agentId=1 input='{"channels":"[朋友圈,抖音]","keywords":"企业AI"}'  # 需审批
+
+# 或命令行直接跑（agent-team/ 目录内）
+python main.py list-agents
+python main.py submit --module 01 --input '{"channels":"[A,B]","keywords":"测试"}'
+python main.py run-once
+```
+
+- 模型路由：自动复用飞虹 `models.providers` 第一个 openai-compatible 带 key 的 provider；
+  无配置时回退 mock（本地确定性，全链路可跑）。
+- 17 个技能（SKILL.md + run.py）已安装到用户级技能目录，对话中按触发场景自动加载。
+- 技能也可独立跑：`python run.py --input '{...}'`（纯标准库，`--llm` 可接豆包 API）。
+
+## 六、模型配置
+
+`fhcode.config.json` 的 `models.providers`：
+
+```json
+{
+  "models": {
+    "providers": [
+      { "id": "ark", "type": "openai-compatible", "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
+        "model": "doubao-seed-1-6-250615", "apiKey": "sk-xxx", "tags": ["code-gen"] }
+    ]
+  }
+}
+```
+
+支持 openai-compatible（DeepSeek/通义/豆包/OpenAI 兼容网关）与 Ollama 本地模型。
+
+## 七、安全与合规
+
+- **权限**：RBAC 五角色（viewer/developer/operator/admin），写操作需审批，成本上限控制；
+- **脱敏**：审计日志自动脱敏 API Key / token（`sk-*` → `***`）；
+- **桌面手脚**：危险窗口停手线 + 写操作审批 + 取证留痕；
+- **AI 员工军团**：任务提交需审批，apiKey 只作为子进程环境变量传递，不回显不落盘；
+- **密钥管理**：所有密钥只从环境变量 / 用户级配置读取，禁止硬编码进代码或提交进仓库。
+
+## 八、常见问题
+
+**Q1：desktop 工具报「AutoGuardBlocked」？**
+键盘/鼠标动作被 desktop-touch 感知守卫拦截。先 `feihong_desktop_see` 拿到精确窗口标题再 act；
+type 时传 `windowTitle:'@active'` 瞄准当前前台窗口。
+
+**Q2：AI 员工提交后没执行？**
+`executeNow=false` 时任务入队，需 `run-once`（或 `feihong_agents_submit` 默认 executeNow=true 立即执行）。
+
+**Q3：npm 包 build 报 copy-web 崩溃？**
+v8.0.1 已修复：`fs.cpSync(recursive)` 在 Node 22 Windows 触发原生崩溃，已重写为手写递归复制。
+
+**Q4：历史提交过密钥怎么办？**
+本仓库已用 filter-branch 全历史清除泄露密钥并 force push；**请同步到对应平台后台轮换该密钥**。
+
+## 九、目录速查
+
+```
+feihong-code/
+├─ src/                     TS 内核（agent/ tools/ enterprise/ models/ runtime/ …）
+├─ agent-team/              AI 员工军团（Python：main.py + core/ + agents/ + llm/ + skills/）
+├─ docs/                    说明书 / 技术说明书 / 桌面手脚指南 / POC 脚本
+├─ scripts/                 构建与校验（copy-web / verify-m4…m9 / bump-version）
+├─ bench/                   评测脚本（运行产物已清理并 gitignore 加固）
+└─ tests/unit/              单测（269 例，v8.0.1 全绿）
+```