nuphus-modules

Nuphus 项目模块知识

自包含的 Nuphus 项目模块摘要库：32 个模块的结构与作用，一问即答。 数据在本技能 data/ 目录（与技能同目录，自包含）——不引用仓库 docs/（该目录不被 git 跟踪、不在发布包内）。

---

0. 使用协议（给 AI 执行者）

1. skill_query 命中本技能 → 命中条目即答案骨架（定位 / 结构 / 功能作用 / 规则与坑），先答再补；
2. 需要行级细节或「现在怎样」→ 读源码（提示词「代码地图」已给目录：src/ src-tauri/ frontend/src/）；摘要内已带的关键 文件:行号 可直接转引；
3. 答案引用 源码路径:行号；摘要为 2026-11-04 提炼，可能与最新代码有漂移，行级断言以源码复核为准；
4. 本技能随版本发布（plugin/skills/builtin/，编译期内嵌进二进制、首启落盘到用户数据目录），任何装机环境可用。

---

1. 项目骨架速答（高频问题的快速答案）

1.1 Nuphus 是什么

Tauri v2 + Rust + React 18 的桌面 AI Agent（协同共生桌面助手），「统一 Runtime + ReactAgent」架构。三层职责边界：

层	目录	职责
前端	frontend/	UI、交互、状态展示、i18n、主题
壳	src-tauri/	窗口、IPC 命令注册、AppState、事件转发（无业务逻辑）
核心	src/	Runtime、Agent、LLM、Memory、Tools、Security（全部业务逻辑）

IPC 层约 177 个命令（实测 268 个命令属性 / 308 注册项）；核心引擎 32+ 子模块。外部能力：LLM Provider 12+ 家多协议、桌面自动化（Win32/UIA/OCR）、浏览器 CDP（chromiumoxide）、外部 Agent（门铃 HTTP）。

1.2 Cargo workspace：5 个 crate

Crate	路径	角色
nuphus	src/	核心引擎（lib），32+ 模块
nuphus-desktop	src-tauri/	Tauri 桌面壳（bin nuphus）
desktop-api	src-tauri/crates/desktop-api/	底层桌面 API（鼠标/键盘/窗口/截图/OCR/输入模拟）
nuphus-index	crates/nuphus-index/	知识库内存索引引擎（扫描/解析/检索）
nuphus-browser	crates/nuphus-browser/	浏览器自动化（Chrome DevTools Protocol）

前端是独立 npm 工程（frontend/，pnpm）：React 18.3 + TypeScript 5.8 + Vite 6 + @xyflow/react 12（工作流画布）+ pdfjs-dist + Vitest 4。

1.3 一次用户请求的生命周期

用户输入（主窗口 ChatInputBar）
  → invoke("send_message_cmd")                       [src-tauri/commands/process.rs]
  → busy 并发锁 + 读取 soul/relation/known_paths
  → 注入记忆上下文（memory → store，FTS5 + 语义双通路）
  → run_leader_with_config（复用或新建 ReactAgent）   [process/leader.rs]
  → Runtime::react_loop() —— ReAct 主循环            [src/runtime/react_loop.rs]
        ├─ llm → transports → Provider（SSE 流式）
        ├─ agent::exec_tool —— 五层安全链
        │     ├─ permissions（ToolCategory 授权）
        │     ├─ security（SecurityGuard / 注入检测 / 审批）
        │     └─ tools（ToolRegistry 分发执行）
        ├─ session（上下文窗口管理）
        ├─ memory → store（双通路检索 + 沉淀）
        ├─ skill（按需知识检索，不占 prompt）
        ├─ workflow / browser / desktop / mcp / handoff
        └─ protection（ProtectionGuard 断路器）
  → 流式事件 → event_seq 推送前端（useEvents hook 消费）