WPS灵犀Claw功能深度分析
一、整体架构
灵犀是一个基于 Electron+ Chromium 构建的桌面 AI Agent 应用，其架构采用前端-本地服务-云端三层分离模式：
层级 | 技术栈 | 职责 |
Electron 前端 | Chromium + Electron | UI 渲染、用户交互、会话管理 |
本地 Python Server | FastAPI + Uvicorn + Jupyter Kernel | 代码执行、文件操作、定时任务 |
云端服务 | lingxi.wps.cn (HTTPS/WSS) | 任务编排与调度、向本地下发操作指令、向前端推送流式文本、触发网络搜索、会话中断控制、认证与路由 |
核心可执行文件为 WPS 灵犀.exe，本质上是一个 Electron shell，内嵌 Chromium 和 Node.js。
二、通信与协议层
2.1 WebSocket 双向通信
灵犀的消息流转遵循 AGUI v3 协议，完整链路为：
用户输入 → 前端 (WS) → 本地 Python Server (FastAPI /ws) → 云端 lingxi.wps.cn (WSS)
↑ ↓
←───── 事件流式推送（文本/工具调用/组件渲染） ←────────────────────消息协议（message_protocol.py）定义了三类核心消息：
FrontendAction：前端上行消息，包含 action（chat 等）、session_id、prompt、model、refs（引用文件）等字段
RemoteMessage：云端双向消息，格式为 {event, data}，涵盖 user.input、run.start、component.start、client.operation.*、error、done 等事件
ClientOperation：云端下发的本地操作指令，包含 type（如 jupyter_exec、fs_read_file）、id、group_id、payload
2.2 本地服务端口
本地 Python Server 通过动态端口启动（如 50308、58549），端口记录在 serverdir/logs/localserver.port；使用 FastAPI + WebSocket (/ws) 与前端通信，而非 Electron 的 ipcMain/ipcRenderer，前端连接本地服务的方式可能是 WebSocket 而非 IPC。
三、代码执行引擎（Jupyter Kernel Pool）
这是灵犀的核心计算能力，由 kernel_pool.py + jupyter_executor.py 实现。
3.1 Kernel 池管理
特性 | 实现 |
按 workspace 隔离 | 每个工作目录（如 D:\WPS灵犀\20260415-22-25-39）独享一个 Kernel |
跨会话变量保留 | 同一 workspace 的 Kernel 在空闲期间不被销毁，支持上下文延续 |
并发控制 | 每个 Kernel 通过 asyncio.Lock 串行化 ZMQ 通信 |
空闲回收 | 5 分钟无操作自动回收 Kernel，释放内存 |
健康检查 | 不健康的 Kernel 自动重启 |
超时保护 | 默认 600 秒超时，SIGINT 中断 + asyncio.wait_for 双重兜底 |
3.2 沙箱隔离
环境隔离：移除 PYTHONHOME/PYTHONPATH，禁用 user site-packages，强制 UTF-8 I/O
线程限制：OMP_NUM_THREADS=8、MKL_NUM_THREADS=8 防止 CPU 过载
输出截断：最大 500,000 字符输出限制
审计钩子（audit_lite.py）：拦截 os.remove/os.rmdir，强制使用 send2trash 走回收站
3.3 权限请求机制
当 Kernel 中的代码需要执行敏感操作时，会通过 __PERM_REQ__<json> 前缀的 input() 调用触发权限请求，经由 stdin 通道传递到前端，用户选择"允许"或"拒绝"后继续执行。
四、文件操作系统（File Executor）
file_executor.py 实现了完整的文件操作能力，支持的操作类型包括：
操作 | 功能 |
read_file | 读取文件内容（文本/二进制） |
write_file | 写入文件 |
edit_file | 编辑文件（查找替换） |
list_dir | 列出目录内容 |
download_file | 文件下载 |
路径策略（PathPolicy）：
相对路径基于 workspace_dir 解析
写操作通过白名单机制限制（writable_dirs）
图片自动压缩（超过 5MB 触发）
音频文件支持（最大 50MB），支持 mp3/wav/pcm 等格式
五、Python 运行时环境
灵犀内嵌了完整的 Python 3.12.13 环境，预装了 125 个第三方包，按功能域分类如下：
5.1 Office 文档处理
包 | 用途 |
python-docx | Word 文档读写 |
python-pptx | PPT 生成/编辑 |
openpyxl | Excel 读写 |
lxml | XML/HTML 解析 |
pillow | 图像处理 |
formulas | Excel 公式引擎 |
cairosvg | SVG 渲染 |
5.2 PDF 处理
包 | 用途 |
PyMuPDF | PDF 解析/操作（高性能） |
pypdf | PDF 合并/拆分 |
pdfplumber | PDF 表格提取 |
reportlab | PDF 生成 |
pypdfium2 | PDF 渲染 |
pytesseract | OCR 文字识别 |
5.3 数据分析与可视化
包 | 用途 |
numpy + scipy | 科学计算 |
pandas | 数据分析 |
matplotlib | 图表绑定 |
numpy-financial | 财务计算 |
5.4 Web 与网络
包 | 用途 |
requests + aiohttp | HTTP 客户端 |
beautifulsoup4 | HTML 解析 |
playwright + selenium | 浏览器自动化 |
websockets | WebSocket 客户端/服务端 |
PySocks | SOCKS 代理支持 |
5.5 服务端框架
包 | 用途 |
fastapi + uvicorn | 本地 HTTP/WS 服务 |
jupyter_client + ipykernel | Jupyter Kernel 管理 |
六、定时任务系统
6.1 数据库架构
定时任务通过 SQLite 持久化，每个用户一个数据库（local-db/<user_id>/scheduled-tasks.sqlite）：
scheduled_tasks 表：
字段 | 说明 |
id | 任务唯一标识 |
name | 任务名称 |
enabled | 是否启用 |
schedule_json | 调度配置（cron 表达式或一次性时间） |
prompt | Agent 执行的任务描述 |
extra_json | 扩展参数 |
created_at_ms / updated_at_ms | 时间戳 |
effective_from_ms / effective_until_ms | 有效期 |
scheduled_task_runs 表：记录每次执行的 trigger（触发方式）、started_at_ms、finished_at_ms、status、session_id、error_message 等。
6.2 调度引擎
依赖 apscheduler==3.11.2 + croniter==6.2.2，支持 cron 周期任务和一次性定时任务。
七、IM 渠道集成（即时通讯）
我配置了三个渠道（QQ、微信和企业微信），通过HTTP通道或者WebSocket通道连接。
八、用户与认证系统
8.1 认证流程
WPS 账号登录：通过 wps_sid Cookie 实现身份认证
SID 缓存：sid-cache 模块维护 SID 的本地缓存，避免重复登录
启动检测：[webLogin] 检测到已有 wps_sid，视为已登录，跳过打开登录页
用户资料缓存：user-profile-cache 缓存用户 ID 和名称
会话管理：session 模块管理 cookie 同步（copilot_branch、copilot_server_branch 等）
8.2 设备安全
DIPS（Device-bound Session Credential）：SQLite 格式数据库，存储设备绑定的会话凭据
加密密钥：Local State 中的 os_crypt.encrypted_key 使用 DPAPI 加密
Transport Security：HSTS 策略存储
九、用户记忆系统
9.1 持久化记忆
serverdir/memory/USER.md 存储用户画像信息，包括：
身份信息（称呼、部门、职位、公司）
工作习惯（常用文档类型、常见任务）
文档偏好（格式偏好、语言偏好）
工具偏好（已安装的本地工具路径）
强制加载技能列表和强制规则
9.2 IndexedDB 存储
Partitions/lingxi.wps.cn/IndexedDB 中有两个 IndexedDB 实例：
https_account.wps.cn_0 — WPS 账号相关数据
https_lingxi.wps.cn_0 — 灵犀主应用数据（含 blob 存储）
十、沙箱更新与自动更新
10.1 沙箱更新机制
版本管理：resources/sandbox/.version 记录当前版本
哈希校验：.hash 文件记录 pythonServer 和 skills 的 SHA-256 哈希
定时检查：启动 3 秒后首次检查，之后每 600 秒（10 分钟）检查一次更新
渐进应用：sandbox-update 模块支持 pending 更新的渐进式应用
10.2 应用自动更新
app-update.yml 配置 Electron 自动更新
force-update-guard 模块管理强制更新策略
十一、系统监控与日志
11.1 系统信息采集
指标 | 说明 |
cpuUsage | CPU 使用率 |
memoryFree / memoryTotal | 内存（单位 MB） |
diskFree | 磁盘可用空间（单位 MB） |
networkInterfaces | 网络接口（IP、MAC） |
dns | DNS 配置 |
proxy | 代理设置 |
connectivity | 网络连通性检测 |
11.2 日志体系
日志文件 | 内容 |
app.*.log | Electron 主进程日志（31 个功能模块） |
service_*_YYYY-MM-DD.log | Python Server 运行日志（7 天保留） |
system-info.*.log | 系统监控数据 |
十二、GPU 与渲染加速
灵犀配置了三种 GPU 缓存方案，兼容不同硬件环境：
缓存 | 用途 |
GPUCache/ | Chromium 通用 GPU 缓存 |
DawnGraphiteCache/ | Dawn Graphite 后端（软件渲染） |
DawnWebGPUCache/ | Dawn WebGPU 后端（硬件加速） |
同时内置了 d3dcompiler_47.dll、dxcompiler.dll、dxil.dll（DirectX 编译器）、vk_swiftshader.dll（Vulkan 软件渲染器）、libEGL.dll + libGLESv2.dll（OpenGL ES），确保在不同 GPU 环境下都能正常渲染。
十三、其他
语音输入：灵犀内嵌了语音转文字能力，mic-permission 模块在每次语音交互前执行麦克风权限检查。
