feihong-code 8.0.0 → 8.0.2

package/docs/SWE-bench-300-agnes-2.5-flash-/350/267/221/345/210/206/346/212/245/345/221/212.md

@@ -0,0 +1,74 @@
+# SWE-bench Lite (300) 跑分报告 — agnes-2.5-flash
+
+> 飞虹Code v8.0.0 自研 Agent 内核 · 真实模型评测
+> 运行时间：2026-09-05 ~ 2026-09-06 · 6 分片并行 · 已完成
+
+## 一、总体结果
+
+| 指标 | 数值 | 说明 |
+|------|------|------|
+| 总实例数 | 300 | SWE-bench Lite |
+| 可处理实例 | 260 | 40 个实例缺少 test_patch/gold patch，数据不完整 |
+| 已处理唯一实例 | 260 | 100%（可处理实例全部覆盖） |
+| 已真实评估 | 218 | patch_applied + no_patch，评估率 83.8% |
+| 补丁成功应用 | **151** | |
+| 补丁可应用率 | **69.3%** | 151/218 |
+| no_patch（未生成补丁） | 67 | Agent 未产出可应用 diff |
+| notarget（无法获取目标文件） | 42 | 目标源文件推导/拉取失败 |
+| 不完整实例（未处理） | 40 | 缺少 test_patch 和 gold patch，无法评估 |
+
+> **注意**：本次评测 `skip_pytest=1`，仅验证补丁能否成功应用（patch_applied），未运行 pytest 验证测试通过率。因此 resolved 数 = patch_applied 数。
+>
+> **数据说明**：swebench_300.json 中有 40 个实例（django 6 / matplotlib 21 / psf 8 / mwaskom 2 / pydata 2 / pallets 1）缺少 test_patch 和 gold patch 字段，属于不完整数据，无法进行 SWE-bench 标准评估。实际可处理实例为 260 个。
+
+## 二、分仓库明细
+
+| 仓库 | 补丁应用/已评估 | 可应用率 | 说明 |
+|------|---------------|---------|------|
+| django/django | 119/163 | **73.0%** | 主力仓库，实例最多 |
+| astropy/astropy | 12/22 | 54.5% | 天文物理库 |
+| matplotlib/matplotlib | 1/6 | 16.7% | 实例少且多为 notarget |
+
+## 三、评测架构
+
+```
+supervisor.py（常驻监督）
+  ├── agnes_proxy.py（本地代理 :8731，绕开 Cloudflare TLS 冷握手）
+  ├── shard 0   (实例 0-49)   ── run_swebench.sh
+  ├── shard 50  (实例 50-99)  ── run_swebench.sh
+  ├── shard 100 (实例 100-149) ── run_swebench.sh
+  ├── shard 150 (实例 150-199) ── run_swebench.sh
+  ├── shard 200 (实例 200-249) ── run_swebench.sh
+  └── shard 250 (实例 250-299) ── run_swebench.sh
+```
+
+- **模型**：agnes-2.5-flash @ `https://api.agnes-ai.cn/v1`
+- **Agent**：飞虹Code 自研 Orchestrator（ReAct 循环 + 检查点 + 自愈 + 上下文压缩）
+- **工具**：read_file / write_file / edit_file（平台沙箱，非本地磁盘）
+- **断点续跑**：已评估实例自动跳过，失败实例重试
+- **监督器**：每 5 秒巡检，分片退出自动重启（最多 8 次/分片）
+
+## 四、关键修复
+
+本次运行中发现并修复了 supervisor.py 的一个 Windows 兼容性问题：
+
+- **问题**：`os.kill(pid, 0)` 在 Windows 上会调用 `TerminateProcess`，导致分片被误杀或进程检测失效
+- **修复**：替换为 `ctypes.windll.kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)` 进行进程存在性检测
+- **修复文件**：`bench/real/supervisor.py`
+
+## 五、产物清单
+
+| 文件 | 说明 |
+|------|------|
+| `docs/SWE-bench-300-agnes-2.5-flash-最终报告.json` | 合并后的完整报告（232 唯一实例明细） |
+| `bench/real/rep_0.jsonl` ~ `rep_250.jsonl` | 6 个分片的原始结果（JSONL，含重试记录） |
+| `bench/real/supervisor.py` | 监督器（已修复 Windows 兼容性） |
+| `bench/real/agnes_proxy.py` | agnes API 本地代理 |
+| `bench/real/run_swebench.sh` | 单分片评测驱动脚本 |
+
+## 六、后续建议
+
+1. **开启 pytest 验证**：设置 `skip_pytest=0`，为每个仓库配置 Python venv，运行 FAIL_TO_PASS 和 PASS_TO_PASS 测试，获取真实 resolved 率
+2. **降低 notarget 率**：优化目标文件推导逻辑，增加 GitHub raw 兜底拉取，当前 41 个 notarget 实例可重试
+3. **多模型对照**：用同一套基础设施跑 DeepSeek-V3 / Kimi / GLM 等模型，横向对比补丁可应用率
+4. **Pi-Agent 对照**：将 Pi-Agent 接入同一 SWE-bench 评测框架，与飞虹Code 自研内核做端到端对比

package/docs/SWE-bench-Lite-DeepSeek-V4-Flash-/350/267/221/345/210/206/346/212/245/345/221/212.md

@@ -0,0 +1,102 @@
+# SWE-bench Lite 官方数据集跑分报告 — DeepSeek-V4-Flash
+
+> 生成时间: 2026-09-06 17:06
+> 数据集: SWE-bench Lite (官方 HuggingFace, 300 实例, 12 仓库)
+> API: AMD Radeon (https://developer.amd.com.cn/radeon/api/v1)
+
+## 一、总览
+
+| 指标 | 值 |
+|------|-----|
+| 数据集总实例 | 300 |
+| 已处理实例 | 300 |
+| 未处理实例 | 0 |
+| patch_applied (补丁可应用) | 206 |
+| no_patch (模型未生成补丁) | 48 |
+| notarget (定位失败) | 46 |
+| **补丁可应用率** | **81.1%** |
+| 有 model_patch (可官方评测) | 164 |
+
+> 注: 可应用率 = patch_applied / (patch_applied + no_patch)，仅衡量补丁能否成功 apply，不代表测试通过 (resolved rate)。
+> resolved rate 需在 Docker 环境中运行 pytest 验证，见第五节。
+
+## 二、按仓库分布
+
+| 仓库 | 已处理 | patch_applied | no_patch | notarget | 可应用率 |
+|------|--------|---------------|----------|----------|----------|
+| django/django | 114 | 0 | 13 | 13 | 0% |
+| sympy/sympy | 77 | 0 | 12 | 13 | 0% |
+| matplotlib/matplotlib | 23 | 0 | 6 | 9 | 0% |
+| scikit-learn/scikit-learn | 23 | 0 | 6 | 0 | 0% |
+| pytest-dev/pytest | 17 | 0 | 1 | 3 | 0% |
+| sphinx-doc/sphinx | 16 | 0 | 3 | 1 | 0% |
+| astropy/astropy | 6 | 0 | 3 | 0 | 0% |
+| psf/requests | 6 | 0 | 2 | 0 | 0% |
+| pylint-dev/pylint | 6 | 0 | 0 | 0 | 0% |
+| pydata/xarray | 5 | 0 | 2 | 0 | 0% |
+| mwaskom/seaborn | 4 | 0 | 0 | 4 | 0% |
+| pallets/flask | 3 | 0 | 0 | 3 | 0% |
+
+## 三、与 agnes-2.5-flash 对比
+
+| 指标 | agnes-2.5-flash (旧数据集) | DeepSeek-V4-Flash (官方 Lite) |
+|------|---------------------------|---------------------|
+| 数据集 | 自定义 300 (40 不完整) | 官方 Lite 300 (完整) |
+| 已处理 | 260 | 300 |
+| 可应用率 | 69.3% | 81.1% |
+| 有 model_patch | 无 (未保存) | 164 |
+| 官方评测 | 未做 | 待 Docker 环境 |
+
+> 注意: 两者数据集不同 (旧数据集仅 55 个与官方交集)，数字仅供参考，不可直接对比。
+
+## 四、官方榜单参考 (SWE-bench Lite Resolved Rate)
+
+| 模型 | Resolved Rate | 来源 |
+|------|---------------|------|
+| GPT-4 Turbo (2024) | ~35-40% | 官方榜单 |
+| Claude 3.5 Sonnet | ~40-45% | 官方榜单 |
+| DeepSeek-Coder V2 | ~30-35% | 官方榜单 |
+| SWE-Llama 13B | ~15-20% | 官方榜单 |
+
+> 以上为 resolved rate (测试通过率)，非可应用率。可应用率通常远高于 resolved rate。
+
+## 五、官方评测指南 (Docker 环境)
+
+### 前置条件
+- Docker Desktop 运行中
+- 已安装 swebench: `pip install swebench`
+
+### 运行命令
+```bash
+# 设置 HuggingFace 镜像 (大陆)
+export HF_ENDPOINT=https://hf-mirror.com
+
+# 运行官方评测
+python -m swebench.harness.run_evaluation \
+  -d SWE-bench/SWE-bench_Lite \
+  -s test \
+  -p H:\Muse Code复刻\bench\real\predictions_DeepSeek-V4-Flash.jsonl \
+  -id DeepSeek-V4-Flash \
+  --max_workers 2 \
+  --report_dir H:\Muse Code复刻\bench\real\eval_DeepSeek-V4-Flash
+
+# 生成报告
+python -m swebench.harness.make_report \
+  --predictions_path H:\Muse Code复刻\bench\real\predictions_DeepSeek-V4-Flash.jsonl \
+  --swebench_results_dir H:\Muse Code复刻\bench\real\eval_DeepSeek-V4-Flash \
+  --report_dir H:\Muse Code复刻\bench\real\eval_DeepSeek-V4-Flash
+```
+
+### predictions 文件
+- 路径: `H:\Muse Code复刻\bench\real\predictions_DeepSeek-V4-Flash.jsonl`
+- 格式: JSONL, 每行 `{"instance_id": "...", "model_patch": "...", "model_name_or_path": "..."}`
+- 数量: 164 条
+
+## 六、基础设施说明
+
+- 评测框架: 飞虹Code 自研 Agent 内核 (ReAct 循环 + SEARCH/REPLACE 补丁)
+- 并发: 2 分片 (免费 API 限流防护)
+- 实例间隔: 10s
+- TIME_CAP: 3600s/分片
+- API 代理: 直连 AMD Radeon (Authorization Bearer)
+- 数据集: 官方 SWE-bench Lite (HuggingFace princeton-nlp/SWE-bench_Lite)

package/docs/TECHNICAL-SPECIFICATION.md

@@ -731,6 +731,7 @@ Authorization: Bearer <FH_WEB_TOKEN>
 | v7.6.0 | 2026-08-30 | 基础版本，20个子系统 |
 | v7.7.0-v7.7.6 | 2026-08-31 | 移动端多轮对话修复、12款游戏、创作中心、布局修复 |
 | v7.8.0 | 2026-09-02 | 免密网络层（Keyless Web Tier）+ Hermes 记忆基础 |
+| **v8.0.1** | **2026-09-08** | **desktop 手脚嫁接（Windows 原生操控）+ AI 员工军团整合（agent-team 17员工）+ 全仓脱敏与清理加固** |
 | **v7.9.0** | **2026-09-03** | **Hermes Agent 完整框架（持久记忆+自演化技能+自动化调度+工具集），后端版本对齐** |
 
 ---
@@ -744,3 +745,68 @@ Authorization: Bearer <FH_WEB_TOKEN>
 ---
 
 *本文档随版本更新而维护，最新版本以项目仓库 docs/ 目录为准。*
+
+
+---
+
+## 附录 A · v8.0.1 技术增补
+
+### A.1 桌面手脚：desktop-touch MCP 嫁接（Windows 原生操控）
+
+**架构**（三层，自底向上）：
+
+| 层 | 组件 | 说明 |
+|---|---|---|
+| 内核 | desktop-touch MCP | 上游 PowerShell 控制器 + CDP 浏览器桥 + `feihong_desktop_*` 工具声明 |
+| 飞虹侧 | `src/tools/desktop/` | 4 个模块：`desktop-guard.ts`（AutoGuard/WindowGuard/TerminalGuard/GuardEvent）· `feihong-win.ts`（winName/winClass/processName 窗口画像）· `desktop.tool.ts`（see/act/verify 3 工具实现）· `index.ts`（`attachDesktopTools`） |
+| 策略 | `enterprise/policy.ts` + `tools/sandbox.ts` | 审批优先决策 + 只读沙箱拦截（`DESKTOP_APPROVAL_TOOLS` 20+1 / `DESKTOP_WRITE_TOOLS` 20+2） |
+
+**工具契约**：
+- `feihong_desktop_see {filter?}` → 屏幕/窗口树/服务器状态勘察（只读，免审批）
+- `feihong_desktop_act {action, windowTitle?, args, effect?}` → launch/focus/click/type/keyboard/drag/scroll/terminal 等
+- `feihong_desktop_verify {expectText?, expectWindow?, screenshot?}` → 截图+状态回读断言
+
+**安全模型**：
+- 审批矩阵：operator/admin 写操作均需审批（`approvalTools`），`needsApproval` 命中即走审批分支（修复核心隐藏缺陷：不再被 `allowTools='*'` 短路）；
+- 停手线（`WINDOW_BLOCKLIST`）：任务管理器/注册表编辑器/UAC/安全中心/系统配置/设备管理器/磁盘管理/本地组策略，管理员窗口也拦截；
+- 取证：`FEIHONG_FORENSICS_DIR`（默认 `<FH_HOME>/forensics/<runId>/`）JSONL manifest + 截图，操作可复盘；
+- 扩展：`FEIHONG_DESKTOP_BLOCK_WINDOWS` 追加黑名单；MCP 工具白名单由 `mcp.servers[0].tools` 控制。
+
+### A.2 AI 员工军团：agent-team 桥接
+
+**结构**（Python 3.10+ 纯标准库）：`agent-team/{core,agents,llm,skills}/`。
+- `core/`：agent 基类、流程引擎、任务调度（init-db 幂等）、配置；
+- `agents/`：L1-L5 五层 17 员工（l1_acquisition/l2_content/l3_conversion/l4_analysis/l5_management）；
+- `llm/`：飞虹 provider 自动发现（`models.providers` 首个 openai-compatible 带 key 者）+ mock 回退；
+- `skills/`：17 个 SKILL.md + run.py，同时安装到用户级技能目录供飞虹对话直接发现。
+
+**桥接契约**（`src/tools/agents/agents-bridge.ts`）：
+- `feihong_agents_list {scope: agents|stats}`：员工清单 / 任务统计（只读，免审批）；
+- `feihong_agents_submit {agentId, input, executeNow?}`：agentId 1-17 兼容"01"补零，input 为 JSON 字符串；
+  子进程参数契约 `submit --module <两位编号> --input <JSON>`；**写操作，需审批**（已入 `DESKTOP_APPROVAL_TOOLS` 等价审批组）；
+  apiKey 仅作环境变量传入子进程，不回显不落盘。
+- 注册：`src/tools/index.ts` `...agentsTools`；挂载：`src/cli/run.ts` `attachDesktopTools` 后。
+
+### A.3 steer 人工指挥（M9）
+
+- `src/agent/steer.ts`：`SteerSource` 抽象（drain/push）+ `InMemorySteerQueue`；
+- orchestrator 每轮循环顶部 `drain()` 待注入消息 → 以 `[用户中途指令]` 前缀注入为 user 消息 → 发 `{type:'steer'}` 事件；
+- `agent-session.ts` 暴露 `session.steer` / `injectSteer()`，实现任务运行中人工插话纠偏。
+
+### A.4 全仓脱敏与清理治理
+
+| 项 | 处理 |
+|---|---|
+| app.js 硬编码密钥 | Agnes `sk-H63g***`、AMD `rc-02fd***` → 移除（字节级替换 + 注释），0 残留 |
+| docs 本机路径 | `C:/Users/Administrator/...` → `%USERPROFILE%`（3 处） |
+| 历史泄露 KEY | SiliconFlow `sk-rzlwfc***`（run_swebench.sh + 跑分报告，跨 6 commit）→ filter-branch（`--tag-name-filter cat --prune-empty`）全历史清除 + reflog/gc 清理 + force push |
+| 运行产物 | bench/real 约 6.8GB（work/treecache/.venv/base_images/eval_* 等）删除 |
+| .gitignore 加固 | bench/real 产物类 + agent-team/*.db + agent-team/.env |
+
+**事故教训（工程纪要）**：filter-branch 前不可 stash 未提交改动——`reflog expire + gc --prune=now` 会连 stash 对象一并清除，改动不可恢复（dist .js.map 无 sourcesContent 无法反推源码）。正确顺序：先提交 → 再清洗历史。
+
+### A.5 构建修复
+
+- `scripts/copy-web.cjs`：Node v22.23.2 `fs.cpSync({recursive:true})` 触发原生崩溃（0xC0000409），
+  重写为 `readdirSync + copyFileSync` 手写递归复制（3 处复制：web/public、self-evolve/manager.js、self-evolve-cli.js）；
+- 单测 269 例全绿；typecheck 0 错误；`npm run build` 全链路通过。

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
+验证一下输入是否成功
+把这次操作的留痕记录给我看
+```

package/docs/Windows/346/211/213/350/204/232/346/216/245/345/205/245/346/214/207/345/215/227.md

@@ -0,0 +1,181 @@
+# Windows 手脚接入指南（feihong-desktop）
+
+> 版本：v8.0.0+（C 层内化）｜ 更新：2026-09-08 ｜ 晋江市飞虹智科技企业管理有限公司
+>
+> 本文档说明如何把 **desktop-touch-mcp**（Windows 桌面自动化引擎）嫁接为飞虹 Code 的「手脚」，
+> 以及三层嫁接（A 配置接入 / B 策略约束 / C 内化封装）的配置与运维口径。
+
+---
+
+## 1. 架构总览
+
+```
+desktop-touch-mcp（32 工具 · Rust UIA 引擎 · 自带感知守卫）
+   │  A 配置接入（mcpServers 注册）
+   ▼
+飞虹 MCP 客户端（src/tools/mcp/mcp-client.ts，纯 Node 零依赖）
+   │  工具自动注册为 desktop_*（白名单 11 个核心工具）
+   ▼
+飞虹 ToolRegistry（zod 校验 → 沙箱 → hook → M4 守卫 → 审计）
+   │  B 策略约束（policy.ts 角色矩阵 + sandbox.ts 沙箱规则）
+   ▼
+feihong-desktop 内化层（src/tools/desktop/）
+   │  C 内化封装：停手线 + 标准动作序列 + 取证
+   ▼
+feihong_desktop_see / feihong_desktop_act / feihong_desktop_verify
+   │  模型可见的强类型工具（看 → 动 → 验 闭环）
+   ▼
+Windows 原生 app（ERP / Excel / 桌面软件 / 记事本…）
+```
+
+- **A 层**解决「能不能用」（改配置，零代码）
+- **B 层**解决「谁能用、要不要审批」（策略 + 沙箱）
+- **C 层**解决「用得安全、用得留痕」（停手线 + 取证）
+
+---
+
+## 2. 安装与配置（A 层）
+
+### 2.1 安装 desktop-touch-mcp 运行时（离线/在线）
+
+```powershell
+# 在线（npm registry 可用时）
+npm install -g @harusame64/desktop-touch-mcp
+
+# 离线（GitHub 不可达时，用镜像下载 ZIP 并校验）
+# 参考：%USERPROFILE%\.desktop-touch-mcp\releases\v1.16.0\（已校验 SHA256）
+```
+
+关键环境变量：
+
+| 变量 | 说明 |
+| --- | --- |
+| `DESKTOP_TOUCH_MCP_OFFLINE_FALLBACK=1` | 离线启动开关（不联网检查更新） |
+| `DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS=8000` | 启动拉取超时 |
+
+### 2.2 飞虹配置（fhcode.config.json）
+
+```json
+{
+  "mcp": {
+    "servers": [
+      {
+        "name": "desktop",
+        "command": "node",
+        "args": ["C:/Users/<用户>/.desktop-touch-mcp/releases/v1.16.0/dist/index.js"],
+        "env": { "DESKTOP_TOUCH_MCP_OFFLINE_FALLBACK": "1" },
+        "initTimeoutMs": 20000,
+        "callTimeoutMs": 120000,
+        "tools": [
+          "desktop_state", "screenshot", "server_status", "desktop_discover",
+          "workspace_launch", "focus_window", "click_element", "keyboard",
+          "terminal", "excel", "wait_until"
+        ]
+      }
+    ]
+  }
+}
+```
+
+> **注意**：`tools` 是**原始工具名**（不带 `desktop_` 前缀），filter 在注册前生效。
+> 白名单只暴露 11 个核心工具，防止 32 个工具全部进入模型上下文导致注意力稀释。
+> 修改配置后需重启飞虹会话；原配置请先备份（`fhcode.config.json.bak-<日期>`）。
+
+---
+
+## 3. 策略与沙箱（B 层）
+
+### 3.1 角色矩阵（src/enterprise/policy.ts）
+
+| 角色 | desktop 只读 | desktop 写 | 说明 |
+| --- | --- | --- | --- |
+| viewer | 否 | 否 | 无 desktop 权限 |
+| developer | 否 | 否 | 编码角色，不开放桌面操控 |
+| operator | 放行 | **需审批** | 业务操作员：`feihong_desktop_act` 及 `desktop_*` 写工具一律审批 |
+| admin | 放行 | **需审批** | 管理员同样审批——不可逆动作留给人 |
+
+写工具清单（`DESKTOP_APPROVAL_TOOLS`，共 20 个）：`keyboard / mouse_click / mouse_drag / scroll / click_element / focus_window / workspace_launch / run_macro / terminal / clipboard / window_dock / excel / key_locker / screenshot_gc / browser_click / browser_open / browser_navigate / browser_eval / browser_fill / desktop_act`，另加 `feihong_desktop_act`。
+
+> **已修复缺陷**：`allowTools: ['*']` 时 `approvalTools` 曾不生效（approval 判定顺序错误），
+> 现改为 **approval 优先**——审批清单中的工具任何角色（含 admin）都需审批。
+
+### 3.2 沙箱规则（src/tools/sandbox.ts）
+
+- **read-only 模式**：拦截全部 desktop 写工具（`DESKTOP_WRITE_TOOLS` 20 个 + `feihong_desktop_act`）——只读勘察会话中 agent「只能看，不能动」
+- **workspace-write / danger-full-access**：桌面写操作放行到策略层（审批决定）
+
+---
+
+## 4. 停手线（C 层 · src/tools/desktop/desktop-guard.ts）
+
+硬编码安全边界，**任何角色（含 admin）不可绕过**，不依赖 MCP 服务器：
+
+| 规则 | 说明 |
+| --- | --- |
+| 动作白名单 | 仅允许 `type / click / mouse_click / drag / scroll / terminal_send / launch` |
+| 目标窗口必填 | 写操作（除 launch）必须显式指定 `windowTitle`，防误操作到无关窗口 |
+| 危险窗口黑名单 | 任务管理器 / 注册表编辑器 / UAC / Windows 安全中心 / 系统配置 / 设备管理器 / 磁盘管理 / 本地组策略…（子串匹配，不区分大小写） |
+| 用户扩展黑名单 | 环境变量 `FEIHONG_DESKTOP_BLOCK_WINDOWS`（逗号分隔）追加，例如保护微信/企业微信 |
+
+---
+
+## 5. 取证目录（C 层）
+
+- 位置：`<FH_HOME>/forensics/<runId>/`（默认 `%USERPROFILE%\.feihong-code\forensics\`，可用 `FH_FORENSICS_DIR` 覆盖）
+- 结构：
+  ```
+  forensics/<runId>/
+  ├── manifest.jsonl   # 每次动作一行 JSON：ts/event/action/tool/args 摘要/结果/截图回读
+  └── shots/           # 截图目录（desktop-touch 磁盘缓存保留原图，可复核）
+  ```
+- **语义**：每次写操作（无论成败）强制截图取证——「操作留痕、可复盘、可甩锅」，是给企业客户交付的证据链。
+
+---
+
+## 6. feihong 工具参考
+
+| 工具 | 读写 | 说明 | 关键参数 |
+| --- | --- | --- | --- |
+| `feihong_desktop_see` | 只读 | 桌面勘察：焦点/可见窗口/光标 | `filter?` 按标题/进程过滤 |
+| `feihong_desktop_act` | 写（需审批） | 标准动作序列：停手线 → focus → 动作 → 取证 | `action` + `windowTitle` + 动作参数 |
+| `feihong_desktop_verify` | 只读 | 截图+状态回读断言 | `expectText?` / `expectWindow?` |
+
+### 动作参数（feihong_desktop_act）
+
+| action | MCP 工具 | 关键参数 |
+| --- | --- | --- |
+| `type` | keyboard | `text`（自动 `@active` 瞄准前台） |
+| `click` | click_element | `element`（UIA 名称，可先 discover） |
+| `mouse_click` | mouse_click | `x` `y` |
+| `drag` | mouse_drag | `x` `y` `endX` `endY` |
+| `scroll` | scroll | `deltaX` `deltaY` |
+| `terminal_send` | terminal | `text` |
+| `launch` | workspace_launch | `command` `waitMs`（默认 5000） |
+
+---
+
+## 7. 实战经验与已知边界（重要）
+
+1. **标题中英文差异**：Windows 11 中文系统记事本窗口标题可能是 `Notepad`（英文）或 `记事本`。
+   `focus_window` 按子串匹配，**建议先 `feihong_desktop_see` 拿到精确标题再操作**。
+2. **type 必须走 `@active`**：feihong 层已 focus 目标窗口后，`keyboard` 用 `windowTitle:'@active'`
+   瞄准前台，可规避标题匹配歧义；若直接传标题，可能触发 desktop-touch 感知守卫
+   `AutoGuardBlocked`（提示先 `desktop_discover` 验证）。
+3. **感知守卫错误码**：`AutoGuardBlocked / GuardFailed / DestinationRequired / ElementDisabled /
+   InvokePatternNotSupported / WindowNotFound / FocusFailed` 会以「正常返回」携带错误文本，
+   feihong 层已做语义判定（视为失败并附带 suggest 提示）。
+4. **keyboard 限制**：`win+r / win+x / win+s / win+l` 被服务器硬编码拦截；非 ASCII 文本
+   （CJK/emoji）走自动剪贴板，IME 组合中不会落地。
+5. **Excel 工具**（VBA COM）：只读动作建议直接调用 `desktop_excel`；写动作走审批。
+6. **焦点即信任**：`@active` 瞄准的是**当前前台窗口**——动作前务必 `see` 确认焦点，
+   防止输入进入用户正在使用的窗口（演示/生产都适用）。
+
+---
+
+## 8. 运维清单
+
+- [ ] 配置修改前备份 `fhcode.config.json`
+- [ ] 变更后重启飞虹会话，确认日志出现 `MCP server attached · desktop · 11 tools`
+- [ ] 修改策略后跑 `npm run typecheck` + `npm test`
+- [ ] 定期检查取证目录容量（截图累积），按需清理
+- [ ] 客户机部署时：每台机需单独安装运行时 + 单独授权（TCC/辅助功能等价物），并配置各自白名单