feihong-code 7.6.0 → 8.0.1

package/docs/UPGRADE-v7.9.0.md

@@ -0,0 +1,291 @@
+# 飞虹 Code v7.9.0 升级说明书
+
+**文档版本**：v1.0  
+**发布日期**：2026-09-03  
+**适用版本**：v7.6.0 → v7.9.0  
+**负责人**：飞扬企源研发中心  
+
+---
+
+## 一、版本概述
+
+飞虹 Code v7.9.0 是一次重要的架构升级版本，核心目标是引入 **Hermes Agent 自我进化智能体框架**，实现持久记忆、自演化技能、自动化调度三大核心能力，同时完成后端服务与移动端 APP 的版本对齐。
+
+| 维度 | v7.6.0 | v7.9.0 |
+|------|--------|--------|
+| 后端版本 | 7.6.0 | **7.9.0** |
+| 移动端版本 | 7.8.0 | **7.9.0** |
+| 持久记忆 | 基础分层记忆 | **MEMORY.md + USER.md + 自动摘要** |
+| 技能系统 | 技能加载器 | **自演化技能 + agentskills.io 兼容** |
+| 自动化调度 | 自愈调度器 | **自然语言定时任务** |
+| 免密网络层 | 无 | **5节点环形轮转 + Ring Failover** |
+| 工具集 | 基础工具 | **TTS + 搜索 + 文件 + 记忆查询** |
+| 子系统数量 | 20个 | **21个（新增 Hermes Agent）** |
+
+---
+
+## 二、升级内容详解
+
+### 2.1 后端升级（TypeScript 全栈）
+
+#### 2.1.1 版本号统一
+- `package.json`：7.6.0 → **7.9.0**
+- `src/cli/version.ts`：`VERSION = '7.6.0'` → **`VERSION = '7.9.0'`**
+- 健康检查接口 `/api/health` 返回版本同步更新
+
+#### 2.1.2 编译验证
+- TypeScript 编译：**0 错误**
+- `dist/` 构建产物：全部重新编译
+- 核心文件：`dist/cli/index.js`、`dist/web/server.js`（130KB）、`dist/cli/version.js`
+
+#### 2.1.3 后端已有能力确认（v7.9.0 保持并增强）
+- **Agent 核心**（38个文件）：orchestrator、multi-agent、solo-agent、self-heal、self-correction、self-improver、event-driven-agent
+- **持久记忆**：layered-memory、context-compactor、experience、auto-summarize
+- **技能系统**：skill-loader、skill-market、pua-hooks
+- **自我进化**：self-evolve manager（17KB）、hook、self-heal-scheduler
+- **多平台桥接**：微信（wecom/mp）、飞书、元宝（配置后启用）
+- **工具集**（22个文件）：search、shell、file、browser（8个工具）、mcp、sandbox
+- **Web 服务器**（16个文件）：server.ts（122KB）、auth、channels、task-queue、extra-apis
+- **知识库**：14个文档加载
+- **插件系统**：动态插件管理
+- **SSO 认证**：多提供商支持
+- **任务队列**：98个任务持久化恢复
+
+### 2.2 移动端升级（Android APP）
+
+#### 2.2.1 新增核心模块：`js/hermes-agent.js`（24KB）
+参照 Nous Research Hermes Agent 架构，实现 5 大子系统：
+
+**① MemoryManager — 持久记忆系统**
+- `MEMORY.md`：项目上下文 + 长期记忆 + 关键事实，自动沉淀
+- `USER.md`：用户画像 + 偏好习惯 + 专业领域，从交互中自动学习
+- `digestConversation()`：每轮对话结束自动提取关键事实和用户偏好
+- `recall(query)`：关键词检索历史摘要，近期对话加权，最多返回5条
+- `setContext/getContext`：项目级键值存储
+
+**② SkillManager — 自演化技能系统**
+- 4个内置技能：内容摘要、中英互译、代码审查、小红书文案
+- `match(input)`：输入含触发词时自动匹配对应技能
+- `execute(skill, content)`：应用技能的增强 prompt 模板
+- `extractFromTask()`：从重复任务模式中自动提取可复用技能
+- 兼容 **agentskills.io** 开放标准，支持 JSON 安装新技能
+- 技能管理：搜索、安装、删除、使用计数追踪
+
+**③ Scheduler — 自动化调度**
+- 自然语言时间解析：
+  - `每天 9:00` → daily
+  - `每周一 10:30` → weekly
+  - `每隔 30 分钟` → interval
+  - `14:00` → once
+- 每30秒后台检查到期任务
+- 到期触发 `hermes-scheduled-task` 自定义事件
+- 任务管理：启用/禁用/删除/运行计数/下次运行时间
+
+**④ ToolRegistry — 工具集**
+- `tts`：文字转语音（浏览器内置 SpeechSynthesis，中文朗读）
+- `tts_stop`：停止语音朗读
+- `web_search`：免密网页搜索（复用 keyless.js 双源搜索）
+- `read_file`：文件读取
+- `recall_memory`：持久记忆查询
+
+**⑤ AgentCore — 统一执行循环**
+```
+用户输入 → 技能匹配 → 记忆注入 → 工具检测 → 大模型回复 → 记忆沉淀
+```
+- 发送消息时自动检测技能，匹配到则 toast 提示
+- 对话结束后自动调用 `onConversationEnd()` 沉淀记忆
+- 定时任务到期时触发事件通知主界面
+
+#### 2.2.2 设置面板新增：Hermes Agent 管理区
+- **📝 记忆 Tab**：查看/编辑 MEMORY.md 和 USER.md，显示历史任务数和项目上下文数
+- **⚡ 技能 Tab**：查看所有技能（内置/自动/自定义），支持 JSON 安装新技能
+- **⏰ 调度 Tab**：查看定时任务列表，支持自然语言新建、启用/禁用/删除
+
+#### 2.2.3 免密网络层（Keyless Web Tier，v7.8.0 引入，v7.9.0 保持）
+- 5节点环形轮转池：GPT-4o Mini / Claude 3 Haiku / Llama 3.1 70B / Mixtral 8x7B / Wikipedia
+- Ring Failover：失败自动轮转下一家，连续失败3次冷却30秒
+- 免密搜索：DuckDuckGo HTML + Wikipedia API 双源并行
+- 用户未配置模型时自动启用免密层
+
+#### 2.2.4 其他移动端能力（v7.9.0 保持）
+- 12款内置 Canvas 小游戏（贪吃蛇/打砖块/弹跳小鸟/飞机射击/2048/打地鼠/俄罗斯方块/记忆翻牌/消消乐/井字棋/跳一跳/五子棋）
+- AI 创作中心：文生图/文生视频/图生视频
+- 视觉模型：硅基流动 DeepSeek-OCR
+- 灵光式闪应用
+- 多轮对话（发送锁 + 防抖 + 上下文管理）
+- 附件支持：图片/文件/截图/拍照
+
+---
+
+## 三、升级步骤
+
+### 3.1 后端升级
+
+#### 方式一：重新编译（推荐）
+```bash
+# 1. 进入项目目录
+cd H:\Muse Code复刻
+
+# 2. 确认 package.json 版本为 7.9.0
+node -e "console.log(require('./package.json').version)"
+
+# 3. 编译 TypeScript
+npx tsc
+
+# 4. 验证编译产物
+node dist/cli/index.js --version  # 应输出 7.9.0
+
+# 5. 启动服务
+$env:FH_WEB_PORT="8080"
+node dist/cli/index.js serve
+
+# 6. 验证健康检查
+curl http://localhost:8080/api/health
+# 应返回 {"ok":true,"version":"7.9.0",...}
+```
+
+#### 方式二：一键启动脚本
+```bash
+node start-web.js
+# 自动检查编译 → 清理端口 → 启动服务
+```
+
+### 3.2 移动端升级
+
+#### 方式一：安装已构建 APK
+```
+直接安装 artifacts/fhcode-v7.9.0-release.apk
+```
+
+#### 方式二：重新构建 APK
+```bash
+# 1. 同步前端资源到 android assets
+Copy-Item app-mobile\index.html android\app\src\main\assets\public\index.html -Force
+Copy-Item app-mobile\css\style.css android\app\src\main\assets\public\css\style.css -Force
+Copy-Item app-mobile\js\app.js android\app\src\main\assets\public\js\app.js -Force
+Copy-Item app-mobile\js\game-templates.js android\app\src\main\assets\public\js\game-templates.js -Force
+Copy-Item app-mobile\js\keyless.js android\app\src\main\assets\public\js\keyless.js -Force
+Copy-Item app-mobile\js\hermes-agent.js android\app\src\main\assets\public\js\hermes-agent.js -Force
+
+# 2. 设置 JDK 21
+$env:JAVA_HOME = "C:\Program Files\Microsoft\jdk-21.0.12.101-hotspot"
+$env:Path = "$env:JAVA_HOME\bin;" + $env:Path
+
+# 3. 构建
+cd android
+.\gradlew.bat assembleRelease --no-daemon
+
+# 4. 产物位置
+# android\app\build\outputs\apk\release\app-release.apk
+```
+
+---
+
+## 四、兼容性说明
+
+### 4.1 运行环境
+| 组件 | 最低要求 | 推荐版本 |
+|------|----------|----------|
+| Node.js | >= 18.0.0 | 22.x LTS |
+| 操作系统 | Windows 10+ / Linux / macOS | Windows 11 |
+| 浏览器（Web控制台） | Chrome 90+ / Edge 90+ | 最新版 |
+| Android（APP） | Android 8.0+ | Android 12+ |
+| JDK（APK构建） | JDK 17+ | JDK 21 |
+
+### 4.2 数据兼容性
+- **localStorage 数据**：v7.6.0 → v7.9.0 完全兼容，现有对话记录、模型配置、游戏进度全部保留
+- **Hermes 记忆数据**：新增 `fh.hermes.memory.md`、`fh.hermes.user.md`、`fh.hermes.history`、`fh.hermes.skills` 等 key，首次启动自动初始化
+- **后端任务队列**：98个历史任务自动恢复，无需迁移
+- **知识库**：14个文档自动加载，无需迁移
+
+### 4.3 API 兼容性
+- `/api/health`：公开接口，返回字段新增 `version`（已更新为 7.9.0）
+- 其他 `/api/*` 接口：保持向后兼容，认证机制不变
+- 新增 Hermes Agent 相关接口：通过 Web 控制台前端调用，不影响现有 API
+
+---
+
+## 五、回滚方案
+
+### 5.1 后端回滚
+```bash
+# 1. 停止当前服务
+# 找到占用 8080 端口的进程并终止
+netstat -ano | findstr :8080
+taskkill /PID <进程ID> /F
+
+# 2. 恢复旧版本代码
+git checkout v7.6.0  # 或从备份恢复
+
+# 3. 重新编译
+npx tsc
+
+# 4. 启动旧版本
+node dist/cli/index.js serve
+```
+
+### 5.2 移动端回滚
+- 安装历史版本 APK：`artifacts/fhcode-v7.8.0-release.apk`
+- 或 `artifacts/fhcode-v7.7.6-release.apk`
+
+### 5.3 数据回滚
+- Hermes Agent 新增的 localStorage key 不影响现有功能，删除即可：
+  ```javascript
+  localStorage.removeItem('fh.hermes.memory.md');
+  localStorage.removeItem('fh.hermes.user.md');
+  localStorage.removeItem('fh.hermes.history');
+  localStorage.removeItem('fh.hermes.skills');
+  localStorage.removeItem('fh.hermes.scheduled');
+  ```
+
+---
+
+## 六、已知问题与限制
+
+| # | 问题 | 影响 | 状态 |  workaround |
+|---|------|------|------|------------|
+| 1 | 免密层 DuckDuckGo AI 在电脑端网络环境不可达 | 免密聊天在电脑端测试可能失败 | 已知 | 手机端 WebView 跨域限制更宽松，实际以手机实测为准 |
+| 2 | 不存在的 API 路径返回 401 而非 404 | 无（安全设计） | 预期行为 | 认证中间件优先，不暴露 API 存在性 |
+| 3 | favicon.ico / robots.txt 404 | 无（可选资源） | 已知 | 后续版本补充 |
+| 4 | 微信/飞书/元宝桥接默认 disabled | 多平台消息网关不可用 | 预期 | 配置环境变量后启用 |
+| 5 | 后端日志中文在 PowerShell 显示乱码 | 仅显示问题，不影响功能 | 已知 | 日志文件本身为 UTF-8 编码 |
+| 6 | Hermes 技能自动提炼基于简单规则 | 复杂任务模式可能无法准确提取 | 已知 | 后续版本引入 LLM 辅助提炼 |
+| 7 | 自动化调度依赖 APP 前台运行 | APP 后台被杀时定时任务不执行 | 已知 | 后续版本引入后台 Service 或推送唤醒 |
+
+---
+
+## 七、验证清单
+
+升级完成后，请逐项验证：
+
+### 后端验证
+- [ ] `node dist/cli/index.js --version` 输出 `7.9.0`
+- [ ] 服务启动后端口 8080 正常监听
+- [ ] `curl http://localhost:8080/api/health` 返回 `version: "7.9.0"`
+- [ ] 首页 `http://localhost:8080/` 返回 200，标题含"飞虹 Code"
+- [ ] 未认证访问 `/api/tasks` 返回 401
+- [ ] 启动日志显示 11 个子系统全部初始化
+- [ ] 无严重错误日志
+
+### 移动端验证
+- [ ] APP 版本显示 v7.9.0
+- [ ] 设置 → Hermes Agent 面板可正常打开
+- [ ] 记忆 Tab 显示 MEMORY.md 和 USER.md 内容
+- [ ] 技能 Tab 显示 4 个内置技能
+- [ ] 调度 Tab 可创建"每天 9:00"定时任务
+- [ ] 发送"帮我翻译这段话"自动匹配"中英互译"技能
+- [ ] 多轮对话正常（第二轮能记住第一轮内容）
+- [ ] 12 款小游戏全部可玩
+- [ ] 创作中心文生图/文生视频/图生视频入口正常
+
+---
+
+## 八、联系方式
+
+- **项目负责人**：吴赐虹
+- **研发团队**：晋江市飞虹智科技企业管理有限公司 · 飞扬企源研发中心
+- **技术支持**：通过飞虹 Code Web 控制台提交反馈
+
+---
+
+*本文档随版本更新而维护，最新版本以项目仓库 docs/ 目录为准。*

package/docs/UPGRADE-v8.0.0.md

@@ -0,0 +1,237 @@
+# 飞虹 Code v8.0.0 升级说明书
+
+**文档版本**：v1.0
+**发布日期**：2026-09-03
+**适用版本**：v7.9.1 → v8.0.0
+**负责人**：飞扬企源研发中心
+
+---
+
+## 一、版本概述
+
+飞虹 Code v8.0.0 是**中期架构改进版本（v8.0 预研落地）**，依据《项目客观分析与测试说明书》的三项中期改进建议实施：
+
+| 改进项 | 状态 | 说明 |
+|--------|------|------|
+| ① SQLite 数据存储 | ✅ 已落地 | 本地电脑部署，基于 Node 内置 `node:sqlite`，零外部依赖 |
+| ② Docker 沙盒执行 | ✅ 代码已落地 | 本地电脑部署，补全 sandbox.ts 的 container 模式真实执行层 |
+| ③ Honcho 云端记忆 | ✅ 已落地 | 本地配置，SQLite 持久化 + 用户建模 + 语义检索 |
+
+| 维度 | v7.9.1 | v8.0.0 |
+|------|--------|--------|
+| 后端版本 | 7.9.1 | **8.0.0** |
+| 数据存储 | 文件/JSON（tasks/memory/knowledge） | **SQLite 统一存储（feihong.db）** |
+| 沙盒执行 | container 模式框架（未实现） | **Docker 容器真实执行层** |
+| 记忆系统 | 文件记忆（短期+长期） | **文件记忆 + Honcho 用户建模语义记忆** |
+| 新模块 | — | **sqlite-store.ts / docker-sandbox.ts / honcho-store.ts** |
+| 新 API | — | **/api/storage/stats、/api/honcho/** | 
+| 集成测试 | 33 用例 100% | **34 用例 100%** |
+| 冒烟测试 | 51 项 | **+19 项（v8.0 专项）** |
+
+---
+
+## 二、升级内容详解
+
+### 2.1 ① SQLite 数据存储（本地电脑部署）
+
+**新增文件**：`src/shared/sqlite-store.ts`（21KB，独立模块，不覆盖现有文件存储）
+
+#### 技术选型
+- 使用 **Node.js v22 内置 `node:sqlite`**（`DatabaseSync`），**零 npm 外部依赖**，无安装成本
+- 数据库文件：默认 `$FH_HOME/feihong.db`（可 `FH_DB_PATH` 覆盖）
+- WAL 日志模式 + 外键约束，启动自动建表 + 版本化迁移（SCHEMA_VERSION=1）
+
+#### 数据表设计（10 张表）
+| 表名 | 用途 | 替代原文件存储 |
+|------|------|----------------|
+| `meta` | Schema 版本管理 | — |
+| `kv` | 通用键值（models/config/settings） | `models.json` |
+| `tasks` | 任务持久化 | `~/.feihong-code/tasks/<id>.json` |
+| `models` | 模型配置（API Key 加密） | `models.json` |
+| `agents` | Agent 注册表 | — |
+| `skills` | 技能库 | 技能 JSON |
+| `memory` | 记忆键值（MEMORY.md 等） | `memory/*.md` |
+| `memory_history` | 会话摘要历史 | auto-summarize 摘要 |
+| `users` + `user_memory` | Honcho 用户建模 | — |
+| `knowledge` | 知识库文档 | `knowledge/*.md` |
+
+#### 安全特性
+- **敏感字段 AES-256-GCM 加密**：`models.api_key`、`config.value` 落盘前用 `secure-store` 主密钥加密（`v1:iv:cipher:tag` 格式）
+- 加密/解密自动透明处理，调用方无感知
+- 解密失败自动回退（兼容旧明文数据）
+
+#### 与现有文件存储的关系
+- SQLite 作为**新增统一存储层**，原文件存储（tasks/memory/knowledge）保留不破坏
+- 任务队列等可选用 SQLite 落盘或原文件落盘
+
+### 2.2 ② Docker 沙盒执行（本地电脑部署）
+
+**新增文件**：`src/tools/docker-sandbox.ts`（8KB，补全 sandbox.ts 的 container 模式）
+
+#### 技术实现
+- 通过子进程调用 **Docker CLI**（不依赖 dockerode，减少依赖）
+- 执行模式：`docker run --rm` 一次性容器，执行完自动销毁
+- 工作区挂载：bind mount 宿主机目录 → 容器 `/workspace`
+
+#### 安全加固
+| 机制 | 说明 |
+|------|------|
+| 网络禁用 | 默认 `--network none`（可 `FH_SANDBOX_NETWORK=true` 开启） |
+| 只读挂载 | 默认 `readonly`（可 `FH_SANDBOX_READONLY=false` 关闭） |
+| 资源限制 | 内存 `-m 512m`、CPU `--cpus 1`（可配置） |
+| 危险命令拦截 | 拒绝 `rm -rf /`、`mkfs`、`dd 写块设备`、fork 炸弹 |
+| 超时强杀 | 默认 60s，超时 `docker kill` 强杀 |
+
+#### 配置项
+| 环境变量 | 默认值 | 说明 |
+|----------|--------|------|
+| `FH_SANDBOX_IMAGE` | `node:22-alpine` | 沙盒镜像 |
+| `FH_SANDBOX_NETWORK` | `false` | 是否启用网络 |
+| `FH_SANDBOX_READONLY` | `true` | 工作区是否只读 |
+| `FH_SANDBOX_TIMEOUT` | `60000` | 执行超时（毫秒） |
+
+> **环境依赖**：需要本机 Docker daemon 可用（`docker info` 能返回 ServerVersion）。若本机 Docker Desktop / WSL2 未就绪，执行会返回明确错误提示，不影响其它功能。
+
+### 2.3 ③ Honcho 云端记忆（本地配置）
+
+**新增文件**：`src/memory/honcho-store.ts`（8KB，对标 Honcho/GetZep 语义记忆）
+
+#### 能力对标
+| Honcho 能力 | 本地实现 |
+|-------------|----------|
+| 用户建模 | `users` 表：姓名/偏好/特质画像 |
+| 事实记忆 | `user_memory` 表：内容 + 重要度（0~1） |
+| 会话摘要 | `memory_history` 表：跨会话检索 |
+| 语义检索 | 关键词匹配 + 重要度排序 + 时间加权 |
+| 记忆注入 | `buildContextPrompt()` 生成个性化上下文提示词 |
+
+#### 本地部署策略
+- 默认 **SQLite 持久化**（复用 sqlite-store），零外部服务依赖
+- 可选 `FH_HONCHO_URL` 指向外部 Honcho 服务（API 兼容预留）
+- 数据目录 `$FH_HOME/honcho/`
+- 与现有文件记忆（`memory/index.ts`）互补共存
+
+#### 记忆自动沉淀
+`digestConversation()` 从用户消息自动提取：
+- 偏好类事实（"我喜欢/我偏好/我习惯..."）
+- 自我介绍（"我叫/我是/我从事..."）
+- 自动生成会话摘要并入库
+
+### 2.4 后端 API 新增
+
+| API | 方法 | 说明 |
+|-----|------|------|
+| `/api/storage/stats` | GET | SQLite 各表统计（tasks/models/skills/...） |
+| `/api/honcho/context` | GET | 用户画像 + 记忆 + 上下文提示词 |
+| `/api/honcho/remember` | POST | 记录用户事实记忆 |
+| `/api/honcho/recall` | GET | 关键词检索记忆 |
+
+**健康检查增强**：`/api/health` 新增 `storage`（SQLite 状态）和 `honcho`（记忆状态）字段。
+
+---
+
+## 三、版本号变更
+
+| 文件 | 变更 |
+|------|------|
+| `package.json` | `"version": "7.9.1"` → `"8.0.0"` |
+| `src/cli/version.ts` | `VERSION = '7.9.1'` → `'8.0.0'` |
+| `tests/integration/api.test.js` | 版本断言更新 + 新增 v8.0 存储状态断言 |
+
+---
+
+## 四、编译与测试验证
+
+### 4.1 编译
+```
+npx tsc    # 0 错误（本机环境可用 node_modules/.bin/tsc.cmd）
+```
+产物：
+- `dist/shared/sqlite-store.js`（21KB）
+- `dist/tools/docker-sandbox.js`（8.6KB）
+- `dist/memory/honcho-store.js`（9.5KB）
+
+### 4.2 冒烟测试（新增 `tests/smoke-v8.js`，25 项）
+| 模块 | 通过 | 说明 |
+|------|------|------|
+| SQLite 存储 | 11/11 | KV/任务/模型加密/技能/记忆/用户建模/统计 |
+| Docker 沙盒 | 6/6 | 可用性/配置/容器执行/输出/Node版本/危险命令拦截 |
+| Honcho 记忆 | 8/8 | 画像/事实/检索/提示词/自动沉淀 |
+| **合计** | **25/25** | **100% 通过** |
+
+### 4.3 集成测试
+`tests/integration/api.test.js`：**34/34 通过（100%）**，含新增存储状态断言。
+
+### 4.4 运行时验证
+- 后端启动：`$env:FH_WEB_PORT="8080"; node dist/cli/index.js serve`
+- 健康检查：`version=8.0.0`、`storage.ok=true`、`honcho.ok=true`
+- 新 API 实测：storage/stats、honcho/remember、honcho/context 全部正常
+
+---
+
+## 五、Docker 沙盒环境说明
+
+**代码已完成、编译通过、冒烟测试 6/6 全部通过。**
+
+环境配置过程中遇到并解决的问题：
+- **问题**：Docker Desktop 启动报错 `invalid character 'ï' looking for beginning of value`，daemon 无法启动
+- **根因**：PowerShell `Set-Content -Encoding UTF8` 写入 `daemon.json` 时带了 UTF-8 BOM（`EF BB BF`），Docker JSON 解析器无法识别
+- **修复**：改用 .NET `[System.IO.File]::WriteAllText` + `UTF8Encoding($false)` 无 BOM 写入
+- **镜像加速器**：配置 4 个国内源（docker.1ms.run / docker.m.daocloud.io / hub-mirror.c.163.com / mirror.baidubce.com），解决 Docker Hub 网络不可达问题
+- **验证结果**：`node:22-alpine` 镜像拉取成功，容器执行 `echo` + `node -v` 正常，危险命令（`rm -rf /etc`）被拦截
+
+**后续验证方法**：
+```powershell
+node tests/smoke-v8.js --only=docker
+```
+预期输出：`✅ Docker 可用`、`✅ 容器执行成功`、`✅ 危险命令拦截`（6/6 通过）
+
+---
+
+## 六、升级步骤
+
+```powershell
+# 1. 拉取最新代码
+git pull
+
+# 2. 编译
+node_modules\.bin\tsc.cmd
+
+# 3. 重启后端（先停旧进程）
+Stop-Process -Name node -Force
+$env:FH_WEB_PORT="8080"
+node dist/cli/index.js serve
+
+# 4. 验证
+Invoke-RestMethod http://localhost:8080/api/health   # version=8.0.0, storage.ok=true, honcho.ok=true
+
+# 5. 可选：验证 Docker 沙盒（需 Docker daemon 就绪）
+node tests/smoke-v8.js --only=docker
+```
+
+---
+
+## 七、环境变量速查（v8.0 新增）
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `FH_DB_PATH` | `$FH_HOME/feihong.db` | SQLite 数据库路径 |
+| `FH_HONCHO_USER` | `default` | Honcho 当前用户 ID |
+| `FH_HONCHO_URL` | 空 | 外部 Honcho 服务 URL（预留） |
+| `FH_HONCHO_API_KEY` | 空 | 外部 Honcho API Key（预留） |
+| `FH_SANDBOX_IMAGE` | `node:22-alpine` | 沙盒镜像 |
+
+---
+
+## 八、风险与后续
+
+| 项 | 说明 |
+|----|------|
+| `node:sqlite` 实验性 | Node v22 标注 experimental，可能随版本调整 API；已用独立模块封装，影响可控 |
+| Docker 环境 | 需本机 Docker daemon 可用；后续可增加"未就绪自动降级本地 shell"策略 |
+| 迁移范围 | 当前 SQLite 为新增存储层，未强制替换文件存储；后续可逐步迁移任务队列/知识库 |
+| v8.1 展望 | 任务队列 SQLite 落盘、知识库 SQLite 全文检索、Honcho 远程模式联调 |
+
+---
+
+*本文档由飞扬企源研发中心编制，随代码同步更新。*

package/docs/Windows/346/211/213/350/204/232-POC/346/274/224/347/244/272/350/204/232/346/234/254.md

@@ -0,0 +1,131 @@
+# 客户 POC 演示脚本：AI 操控 Windows 桌面（端到端闭环）
+
+> 用途：给企业客户演示「飞虹 Code 指挥中心 → AI 手脚 → 操控 Windows 原生应用 → 全程留痕」
+> 时长：约 3 分钟 ｜ 前置：已完成《Windows 手脚接入指南》安装配置 ｜ 更新：2026-09-08
+
+---
+
+## 0. 演示前检查（30 秒 · 安全第一）
+
+```powershell
+# 1. 确认 desktop MCP 已挂载（启动飞虹时日志出现）
+#    MCP server attached · desktop · 11 tools / feihong-desktop 已挂载
+
+# 2. 确认取证目录可写
+dir %USERPROFILE%\.feihong-code\forensics
+
+# 3. 【关键】确认当前桌面没有用户正在使用的敏感窗口（尤其输入类）
+#    演示的 type 动作瞄准「当前前台窗口」——先确认前台是演示目标
+```
+
+> ⚠️ **安全红线**：演示全程遵循「先 see 确认焦点 → 再 act」。
+> 输入动作瞄准的是前台窗口，若前台是客户的微信/文档，输入会进入客户窗口！
+
+---
+
+## 1. 开场（30 秒 · 讲价值）
+
+> 客户您好，接下来 3 分钟您会看到：**AI 不只是聊天，它能直接操作您电脑里的软件**——
+> 打开程序、输入内容、验证结果，而且每一步都有留痕记录，出了问题可以复盘、可以追责。
+> 这就是飞虹企业 AI 底座的「手脚」能力。
+
+---
+
+## 2. 演示动作（90 秒 · 对话即操作）
+
+### 2.1 勘察桌面（看）
+
+**对话**：「看看当前桌面有哪些窗口」
+
+**预期**：AI 调用 `feihong_desktop_see`，返回焦点窗口/可见窗口列表。
+
+**给客户讲**：这是「眼睛」——AI 先看清楚环境，不盲目操作。
+
+### 2.2 打开记事本（动）
+
+**对话**：「打开记事本」
+
+**预期**：AI 调用 `feihong_desktop_act { action: 'launch', command: 'notepad.exe' }`，
+返回启动结果 + 取证记录。
+
+### 2.3 确认窗口（看 · 二次确认）
+
+**对话**：「确认记事本窗口出现了」
+
+**预期**：`feihong_desktop_see { filter: 'Notepad' }` 返回窗口标题。
+
+> **给客户讲**：AI 操作前会先确认目标窗口存在——这是「先瞄准，再开枪」。
+
+### 2.4 输入内容（动）
+
+**对话**：「在记事本里输入：飞虹 Code 企业 AI 底座演示 2026-09-08」
+
+**预期**：`feihong_desktop_act { action: 'type', windowTitle: 'Notepad', text: '...' }`，
+返回 `typed: N` 成功。
+
+### 2.5 验证结果（验）
+
+**对话**：「验证一下输入是否成功」
+
+**预期**：`feihong_desktop_verify { expectWindow: 'Notepad' }` 返回「验证通过：窗口焦点命中」。
+
+**给客户讲**：AI 会截图回读、核对焦点——**做完了还自己检查**，不是"做完就完事"。
+
+### 2.6 展示取证（留痕）
+
+**对话**：「把这次操作的留痕记录给我看」
+
+**预期**：展示 `%USERPROFILE%\.feihong-code\forensics\<runId>\manifest.jsonl`，
+逐条显示 launch / type / snapshot 记录。
+
+**给客户讲**：**每一步都有时间戳、动作、结果、截图**——这就是企业合规要的「可审计、可复盘」。
+
+---
+
+## 3. 安全护栏演示（60 秒 · 讲信任）
+
+| 演示 | 对话 | 预期 |
+| --- | --- | --- |
+| 审批拦截 | 「用记事本输入文字」配合审批流 | 写操作弹审批 → 拒绝 → 审计记录 `rejected` |
+| 停手线 | 「操作任务管理器」 | `停手线：目标窗口命中危险窗口黑名单` |
+| 只读沙箱 | 切换 read-only 会话后尝试输入 | `read-only 模式禁止写类操作` |
+
+---
+
+## 4. 演示后清理（30 秒）
+
+```powershell
+# 关闭演示打开的记事本（只关本次新增进程，不动客户原有窗口）
+powershell -Command "Get-Process notepad | Where-Object { $_.Id -notin @(<演示前进程ID>) } | Stop-Process -Force"
+```
+
+> 若演示前无 notepad 进程，直接：`Stop-Process -Name notepad -Force`
+
+---
+
+## 5. 常见问题（给客户的答疑口径）
+
+- **Q：AI 会不会乱动我的电脑？**
+  A：三层防护——① 写操作全部需人工审批；② 危险窗口（任务管理器/系统设置等）硬编码拦截；
+  ③ 每一步截图取证，随时可复盘。
+- **Q：能操作我们公司的 ERP / Excel 吗？**
+  A：能。Excel 内置 VBA 直连（可读写单元格/宏）；ERP 等桌面软件通过 UIA 语义点击，
+  不需要对方开放 API。
+- **Q：部署在我们公司电脑上安全吗？**
+  A：飞虹离线私有化部署，运行时装在本机，不依赖外网；权限按角色划分（operator/admin），
+  审计全量留痕。
+- **Q：中文软件能操作吗？**
+  A：能。UIA 引擎支持中文界面元素定位；键盘输入支持 CJK（自动剪贴板）。
+
+---
+
+## 6. 演示脚本（可复制）
+
+```
+看看当前桌面有哪些窗口
+打开记事本
+确认记事本窗口出现了
+在记事本里输入：飞虹 Code 企业 AI 底座演示 2026-09-08
+验证一下输入是否成功
+把这次操作的留痕记录给我看
+```