系统架构

深入了解千手的双引擎 AI 架构、客户端-服务端分离模型、IPC 通信机制与数据流设计。

架构总览

千手采用客户端-服务端分离架构。桌面客户端基于 Electron 39.x 构建，内部分为 Main Process（主进程）和 Renderer Process（渲染进程）两层。主进程负责文件系统监控、数据库操作、邮件同步、AI 引擎调度和安全管理；渲染进程提供 React UI 界面，通过 IPC（进程间通信）与主进程交互。

企业服务端独立部署在 Docker 容器中，提供用户认证（JWT 双令牌）、模型管理、智能体配置同步和审计日志持久化。客户端通过 HTTPS 与服务端通信，AI 执行请求通过 SSE（Server-Sent Events）实现流式响应。

┌─────────────────────────────────────────────────────────────────────┐
│                        桌面客户端 (Electron)                         │
│  ┌──────────────────────────┐  ┌──────────────────────────────────┐ │
│  │     Renderer Process     │  │        Main Process              │ │
│  │                          │  │                                  │ │
│  │  Shell (TitleBar /       │  │  fileService    emailService     │ │
│  │   ActivityBar / Status / │  │  searchService   pdfService      │ │
│  │   NotificationCenter)    │◄─►  agentService    auditService    │ │
│  │  Activities (13 IDs)     │IPC│  credentialStore sessionService  │ │
│  │  design-system + Zustand │  │  webSearchService toolRuntime    │ │
│  │  Stores (17 个 / 6 切片)   │  │                                  │ │
│  └──────────────────────────┘  └───────────┬──────────────────────┘ │
└────────────────────────────────────────────┼────────────────────────┘
                                             │ HTTPS / SSE
                                             ▼
                          ┌──────────────────────────────────┐
                          │        企业服务端 (Docker)         │
                          │                                  │
                          │  Hono.js 4.x REST API            │
                          │  ├── /api/auth    (JWT)          │
                          │  ├── /api/models  (模型管理)      │
                          │  ├── /api/agents  (智能体同步)    │
                          │  ├── /api/ai/execute  (SSE 代理) │
                          │  └── /api/audit   (审计日志)      │
                          │                                  │
                          │  PostgreSQL 16 ◄─ Prisma ORM     │
                          │  Redis 7.x (缓存)                │
                          └──────────────────────────────────┘

双引擎 AI 架构

千手的 AI 系统采用双引擎架构，根据 API Key 的存储位置将模型分为两类引擎：

DirectEngine（直连引擎）：用户自有模型，API Key 存储在客户端本地 Keychain（Electron safeStorage），请求直接发送到 AI 厂商 API，不经过企业服务端。适用于个人模型或需要完全数据隔离的场景。
ProxyEngine（代理引擎）：组织统一管理的模型，API Key 以 AES-256 加密存储在服务端。客户端发送请求到 /api/ai/execute，服务端注入密钥后转发，实现零信任客户端架构。

此外，系统还提供两个扩展引擎：AgenticRAGEngine 在 DirectEngine 基础上增加多轮文档检索迭代，适用于知识密集型任务；PresentonEngine 对接独立的 PPT 生成服务，支持异步任务跟踪和模板库管理。

客户端架构

Main Process（主进程）

主进程运行 90+ 个服务模块，注册 550+ 个 IPC 处理器，负责所有需要系统级权限的操作。关键服务包括：

服务	职责	规模
fileService	文件系统监控（chokidar）、目录读取、文件操作	~30 个 IPC 处理器
emailService	IMAP 邮件同步、多账户管理、邮件线程；自动回复规则与 SMTP 出站队列	~30 个 IPC 处理器（含 SMTP outbox）
searchService	SQLite FTS5 全文检索、jieba-wasm 中文分词、LRU 缓存	~5 个 IPC 处理器
agentService	智能体执行调度、四引擎管理、流式输出、allowedTools 白名单	~10 个 IPC 处理器
auditService	审计日志记录、数据提取、报告生成	~40 个 IPC 处理器（含 audit project）
credentialStore	safeStorage 凭据隔离、API Key 安全存储、OAuth tokens	~5 个 IPC 处理器
sessionService	SQLite 会话持久化、消息存储、工件管理	~10 个 IPC 处理器
pdfService	PDF 文本提取、逐页渲染、OCR 集成	~5 个 IPC 处理器

集成服务（Integration）

把第三方协议与外部服务接入桌面工作台的服务层。详细行为见集成生态。

mcp	MCP 协议客户端：服务器管理、工具配置、OAuth 流
oauth	统一 OAuth 流（Google、Microsoft、自定义 IdP）
connector	通用连接器框架，桥接第三方数据源
calendar	日历事件同步与会议任务调度
knowledge / knowledgeGraph	本地知识库与知识图谱编译
urlFetchService / webSearchService	URL 抓取与多 Provider Web 搜索
presentonService	Presenton PPT 引擎适配（异步任务）
tool-runtime / skill-runtime	工具与技能运行时，统一治理外部能力

基础设施服务（Infrastructure）

支撑可靠性、可观测性与可演进性的横向能力，对功能产品域透明。

cacheService	统一 LRU 缓存与 cacheMaintenance 调度
metricsService	运行时性能指标采集与报告生成
featureFlagService	功能开关，支持灰度与 labs 通道
undo	编辑操作历史与回滚
traceService	Trace 链路记录，与 audit 共享数据
sessionCleanup	会话清理调度
mcp-export	把千手内部能力导出为 MCP / CLI 形式

渲染进程基于 React 18 构建，使用自研 design-system（23 个 headless 组件：14 primitives + 3 layout + 6 overlays，Tailwind 着色，无外部 UI 库依赖）。布局由 SplitView + Sidebar + WorkspaceHeader 三件套组合，配合 Activity 路由实现一栏 / 多栏可拖拽分屏。Zustand 5.0+ 管理 17 个状态 Store（含 6 切片架构），navigationStore + activityStore + viewRegistry 联合驱动 Activity 显隐与切换。

视图注册表（src/app/viewRegistry.ts，refactor-2026 §A.5.2）共定义 13 个 ActivityId：9 个默认可见 + Settings 固底 + 3 个默认隐藏（用户可在 CustomizeMenu 中显式开启）。

home

默认可见

主页与导航中枢，含首次启动引导

mail

默认可见

邮件管理：账户、文件夹、消息列表、撰写、自动回复规则

calendar

默认可见

日历视图、事件详情，与 Mail Workspace 共享 OAuth 凭据

chat

默认可见

AI 工作区：智能体选择、流式输出、RAG 显示、任务规划

files

默认可见

文件管理：监控目录、预览器（15+ 格式）、文档操作

aisearch

默认可见

AI 增强搜索：自然语言检索 + FTS5 索引

knowledge

默认可见

知识库浏览与图谱可视化、Wiki 抽屉与来源引用

intel

默认可见

情报采集（含远程 OctoReport handoff 面板）

library

默认可见

内置资产与模板库

settings

固底

模型 / 智能体 / 邮件 / 外观 / Lab / Provider 能力矩阵等系统设置

audit

默认隐藏

审计追踪面板，可在 CustomizeMenu 中开启

education

默认隐藏

使用教学与教程入口，可在 CustomizeMenu 中开启

presenton

默认隐藏

PPT 生成专属工作区，可在 CustomizeMenu 中开启

Shell Chrome（外壳层）

src/shell/ 下的组件构成应用外壳：跨 Activity 共享的 TitleBar、ActivityBar、StatusBar、NotificationCenter、CommandPalette 等，承载窗口控制、全局通知与命令分发。所有组件均消费 design-system primitives，与具体 Activity 解耦。

组件	职责
TitleBarV2	32px 平台自适应顶栏（macOS / Windows / Linux 各取所需），承载窗口控制 + 全局命令入口
ActivityBar	左侧垂直图标栏，按 activityStore.order 渲染默认 Activity，固底放 Settings + UserMenu
CustomizeMenu	ActivityBar 中段「…」按钮唤起，用于显隐 / 重排 Activity 与开启隐藏 Activity
StatusBar	底部状态栏，承载凭据 / 同步进度 / License 提示 / 通知小红点
NotificationCenter	通知中心抽屉：分类型通知列表 + 类型化 deep-link，配 NotificationBridge 统一调度 toast
CommandPalette	CMD+K 全局命令面板，跨 Activity 跳转与动作触发
DialogHost / ToastHost / UndoBridge	对话框 / Toast / 撤销操作的全局宿主，与 design-system Dialog/Toast 协同

服务端架构

企业服务端基于 Hono.js 4.x 构建，运行在 Docker 容器中。采用三容器部署模式：应用服务（Hono.js + Node.js 24）、数据库（PostgreSQL 16）和缓存（Redis 7.x）。Prisma ORM 5.x 提供类型安全的数据库访问层。

认证系统使用 JWT 双令牌机制（access token + refresh token），支持令牌自动刷新。管理后台提供 14 个管理端点，覆盖用户管理、角色权限、系统配置和审计查询。

API 端点概览

端点	描述	方法
/api/auth/*	用户认证（登录、令牌刷新、登出）	POST
/api/models/*	模型管理与同步	GET/POST
/api/agents/*	智能体配置 CRUD 与同步	GET/POST
/api/agents/dify, /api/agents/stats	Dify 平台桥接与运行统计	GET/POST
/api/ai/execute	AI 执行代理（SSE 流式响应）	POST → SSE
/api/audit/*	审计日志查询与统计	GET
/api/intel/*	情报源管理、内容聚合、报告、远程 handoff	GET/POST
/api/drafts	邮件 / 文档草稿同步	GET/POST
/api/knowledge	组织知识库与文档共享	GET/POST
/api/wiki	团队 Wiki 接口	GET/POST
/api/license	授权与许可校验	GET
/api/notifications	通知中心	GET/POST
/api/organization	组织、部门、角色管理	GET/POST
/api/proxy	上游模型与外部服务代理出口	POST
/api/trial, /api/homepage	试用申请与官网内容数据	GET/POST
/api/admin/*	管理后台（用户、角色、系统配置）	GET/POST
/health	健康检查端点	GET

数据流

文件处理流

文件系统 → chokidar 监控 → 变更检测 → SQLite 索引更新 → FTS5 全文检索 → 搜索结果

AI 处理流

用户输入 → 引擎选择（Direct/Proxy）→ 模型调用 → SSE 流式输出 → 人工确认（高风险操作）→ 审计日志记录

邮件处理流

IMAP 服务器 → 邮件同步 → 本地 SQLite 存储 → AI 辅助撰写 → 人工确认 → SMTP 发送 → 审计日志

完整技术栈

桌面客户端

类别	技术	说明
桌面框架	Electron 39.x	自带 Chromium，避免国产 Linux WebView 兼容问题
UI 框架	React 18.x	并发模式，流式渲染优化
UI 原语	@/design-system/*	自研 headless 组件，Tailwind 着色，无外部 UI 库依赖
样式	Tailwind CSS	主样式 API，对接 src/styles/tokens.css 设计变量
类型系统	TypeScript 5.0+	全项目严格类型检查
构建工具	Vite 6.x	HMR 热重载，ESBuild 编译
包管理	pnpm 10.x	硬链接存储，节省磁盘空间
布局	design-system SplitView + Sidebar + WorkspaceHeader	一栏 / 多栏可拖拽分屏，13 个 Activity（9 默认 + Settings 固底 + 3 隐藏可选）
外壳层	src/shell/* (ActivityBar / TitleBar / StatusBar / NotificationCenter / CommandPalette)	跨 Activity 共享 chrome，由 navigationStore + activityStore + viewRegistry 联合驱动
状态管理	Zustand 5.0+	轻量级状态管理，17 个 Store（含 6 切片架构）
本地数据库	SQLite + FTS5	better-sqlite3，支持千万级记录
邮件	imapflow + nodemailer	IMAP 同步 + SMTP 发送
文档提取	pdf-parse, mammoth	PDF / DOCX / XLSX 文本提取
OCR	macOS Vision Framework	编译为 Universal 二进制，12x 快于脚本模式
Markdown	react-markdown + remark-gfm	安全渲染，代码高亮
测试	Vitest 4.0 + Playwright	300+ 单元测试 + E2E 测试
打包	electron-builder 24.0	macOS/Windows/Linux 全平台

企业服务端

类别	技术	说明
Web 框架	Hono.js 4.x	超轻量 HTTP 框架，<1ms 路由
运行时	Node.js 24.x	最新 LTS 运行时
数据库	PostgreSQL 16	企业级关系数据库
ORM	Prisma 5.x	类型安全的数据库访问层
缓存	Redis 7.x	可选，会话与热数据缓存
认证	JWT	access + refresh 双令牌机制
加密	crypto-js (AES-256) + bcrypt	数据加密 + 密码哈希
AI SDK	OpenAI SDK	多厂商兼容（火山引擎、阿里云等）
部署	Docker + Docker Compose	server + postgres + redis 三容器

← 文档总览安全与合规

← 文档总览架构

系统架构

深入了解千手的双引擎 AI 架构、客户端-服务端分离模型、IPC 通信机制与数据流设计。

架构总览

┌─────────────────────────────────────────────────────────────────────┐
│                        桌面客户端 (Electron)                         │
│  ┌──────────────────────────┐  ┌──────────────────────────────────┐ │
│  │     Renderer Process     │  │        Main Process              │ │
│  │                          │  │                                  │ │
│  │  Shell (TitleBar /       │  │  fileService    emailService     │ │
│  │   ActivityBar / Status / │  │  searchService   pdfService      │ │
│  │   NotificationCenter)    │◄─►  agentService    auditService    │ │
│  │  Activities (13 IDs)     │IPC│  credentialStore sessionService  │ │
│  │  design-system + Zustand │  │  webSearchService toolRuntime    │ │
│  │  Stores (17 个 / 6 切片)   │  │                                  │ │
│  └──────────────────────────┘  └───────────┬──────────────────────┘ │
└────────────────────────────────────────────┼────────────────────────┘
                                             │ HTTPS / SSE
                                             ▼
                          ┌──────────────────────────────────┐
                          │        企业服务端 (Docker)         │
                          │                                  │
                          │  Hono.js 4.x REST API            │
                          │  ├── /api/auth    (JWT)          │
                          │  ├── /api/models  (模型管理)      │
                          │  ├── /api/agents  (智能体同步)    │
                          │  ├── /api/ai/execute  (SSE 代理) │
                          │  └── /api/audit   (审计日志)      │
                          │                                  │
                          │  PostgreSQL 16 ◄─ Prisma ORM     │
                          │  Redis 7.x (缓存)                │
                          └──────────────────────────────────┘

双引擎 AI 架构

千手的 AI 系统采用双引擎架构，根据 API Key 的存储位置将模型分为两类引擎：

DirectEngine（直连引擎）：用户自有模型，API Key 存储在客户端本地 Keychain（Electron safeStorage），请求直接发送到 AI 厂商 API，不经过企业服务端。适用于个人模型或需要完全数据隔离的场景。
ProxyEngine（代理引擎）：组织统一管理的模型，API Key 以 AES-256 加密存储在服务端。客户端发送请求到 /api/ai/execute，服务端注入密钥后转发，实现零信任客户端架构。

客户端架构

Main Process（主进程）

主进程运行 90+ 个服务模块，注册 550+ 个 IPC 处理器，负责所有需要系统级权限的操作。关键服务包括：

服务	职责	规模
fileService	文件系统监控（chokidar）、目录读取、文件操作	~30 个 IPC 处理器
emailService	IMAP 邮件同步、多账户管理、邮件线程；自动回复规则与 SMTP 出站队列	~30 个 IPC 处理器（含 SMTP outbox）
searchService	SQLite FTS5 全文检索、jieba-wasm 中文分词、LRU 缓存	~5 个 IPC 处理器
agentService	智能体执行调度、四引擎管理、流式输出、allowedTools 白名单	~10 个 IPC 处理器
auditService	审计日志记录、数据提取、报告生成	~40 个 IPC 处理器（含 audit project）
credentialStore	safeStorage 凭据隔离、API Key 安全存储、OAuth tokens	~5 个 IPC 处理器
sessionService	SQLite 会话持久化、消息存储、工件管理	~10 个 IPC 处理器
pdfService	PDF 文本提取、逐页渲染、OCR 集成	~5 个 IPC 处理器

集成服务（Integration）

把第三方协议与外部服务接入桌面工作台的服务层。详细行为见集成生态。

mcp	MCP 协议客户端：服务器管理、工具配置、OAuth 流
oauth	统一 OAuth 流（Google、Microsoft、自定义 IdP）
connector	通用连接器框架，桥接第三方数据源
calendar	日历事件同步与会议任务调度
knowledge / knowledgeGraph	本地知识库与知识图谱编译
urlFetchService / webSearchService	URL 抓取与多 Provider Web 搜索
presentonService	Presenton PPT 引擎适配（异步任务）
tool-runtime / skill-runtime	工具与技能运行时，统一治理外部能力

基础设施服务（Infrastructure）

支撑可靠性、可观测性与可演进性的横向能力，对功能产品域透明。

cacheService	统一 LRU 缓存与 cacheMaintenance 调度
metricsService	运行时性能指标采集与报告生成
featureFlagService	功能开关，支持灰度与 labs 通道
undo	编辑操作历史与回滚
traceService	Trace 链路记录，与 audit 共享数据
sessionCleanup	会话清理调度
mcp-export	把千手内部能力导出为 MCP / CLI 形式

Renderer Process（渲染进程）

home

默认可见

主页与导航中枢，含首次启动引导

mail

默认可见

邮件管理：账户、文件夹、消息列表、撰写、自动回复规则

calendar

默认可见

日历视图、事件详情，与 Mail Workspace 共享 OAuth 凭据

chat

默认可见

AI 工作区：智能体选择、流式输出、RAG 显示、任务规划

files

默认可见

文件管理：监控目录、预览器（15+ 格式）、文档操作

aisearch

默认可见

AI 增强搜索：自然语言检索 + FTS5 索引

knowledge

默认可见

知识库浏览与图谱可视化、Wiki 抽屉与来源引用

intel

默认可见

情报采集（含远程 OctoReport handoff 面板）

library

默认可见

内置资产与模板库

settings

固底

模型 / 智能体 / 邮件 / 外观 / Lab / Provider 能力矩阵等系统设置

audit

默认隐藏

审计追踪面板，可在 CustomizeMenu 中开启

education

默认隐藏

使用教学与教程入口，可在 CustomizeMenu 中开启

presenton

默认隐藏

PPT 生成专属工作区，可在 CustomizeMenu 中开启

Shell Chrome（外壳层）

组件	职责
TitleBarV2	32px 平台自适应顶栏（macOS / Windows / Linux 各取所需），承载窗口控制 + 全局命令入口
ActivityBar	左侧垂直图标栏，按 activityStore.order 渲染默认 Activity，固底放 Settings + UserMenu
CustomizeMenu	ActivityBar 中段「…」按钮唤起，用于显隐 / 重排 Activity 与开启隐藏 Activity
StatusBar	底部状态栏，承载凭据 / 同步进度 / License 提示 / 通知小红点
NotificationCenter	通知中心抽屉：分类型通知列表 + 类型化 deep-link，配 NotificationBridge 统一调度 toast
CommandPalette	CMD+K 全局命令面板，跨 Activity 跳转与动作触发
DialogHost / ToastHost / UndoBridge	对话框 / Toast / 撤销操作的全局宿主，与 design-system Dialog/Toast 协同

服务端架构

API 端点概览

端点	描述	方法
/api/auth/*	用户认证（登录、令牌刷新、登出）	POST
/api/models/*	模型管理与同步	GET/POST
/api/agents/*	智能体配置 CRUD 与同步	GET/POST
/api/agents/dify, /api/agents/stats	Dify 平台桥接与运行统计	GET/POST
/api/ai/execute	AI 执行代理（SSE 流式响应）	POST → SSE
/api/audit/*	审计日志查询与统计	GET
/api/intel/*	情报源管理、内容聚合、报告、远程 handoff	GET/POST
/api/drafts	邮件 / 文档草稿同步	GET/POST
/api/knowledge	组织知识库与文档共享	GET/POST
/api/wiki	团队 Wiki 接口	GET/POST
/api/license	授权与许可校验	GET
/api/notifications	通知中心	GET/POST
/api/organization	组织、部门、角色管理	GET/POST
/api/proxy	上游模型与外部服务代理出口	POST
/api/trial, /api/homepage	试用申请与官网内容数据	GET/POST
/api/admin/*	管理后台（用户、角色、系统配置）	GET/POST
/health	健康检查端点	GET

数据流

文件处理流

文件系统 → chokidar 监控 → 变更检测 → SQLite 索引更新 → FTS5 全文检索 → 搜索结果

AI 处理流

用户输入 → 引擎选择（Direct/Proxy）→ 模型调用 → SSE 流式输出 → 人工确认（高风险操作）→ 审计日志记录

邮件处理流

IMAP 服务器 → 邮件同步 → 本地 SQLite 存储 → AI 辅助撰写 → 人工确认 → SMTP 发送 → 审计日志

完整技术栈

桌面客户端

类别	技术	说明
桌面框架	Electron 39.x	自带 Chromium，避免国产 Linux WebView 兼容问题
UI 框架	React 18.x	并发模式，流式渲染优化
UI 原语	@/design-system/*	自研 headless 组件，Tailwind 着色，无外部 UI 库依赖
样式	Tailwind CSS	主样式 API，对接 src/styles/tokens.css 设计变量
类型系统	TypeScript 5.0+	全项目严格类型检查
构建工具	Vite 6.x	HMR 热重载，ESBuild 编译
包管理	pnpm 10.x	硬链接存储，节省磁盘空间
布局	design-system SplitView + Sidebar + WorkspaceHeader	一栏 / 多栏可拖拽分屏，13 个 Activity（9 默认 + Settings 固底 + 3 隐藏可选）
外壳层	src/shell/* (ActivityBar / TitleBar / StatusBar / NotificationCenter / CommandPalette)	跨 Activity 共享 chrome，由 navigationStore + activityStore + viewRegistry 联合驱动
状态管理	Zustand 5.0+	轻量级状态管理，17 个 Store（含 6 切片架构）
本地数据库	SQLite + FTS5	better-sqlite3，支持千万级记录
邮件	imapflow + nodemailer	IMAP 同步 + SMTP 发送
文档提取	pdf-parse, mammoth	PDF / DOCX / XLSX 文本提取
OCR	macOS Vision Framework	编译为 Universal 二进制，12x 快于脚本模式
Markdown	react-markdown + remark-gfm	安全渲染，代码高亮
测试	Vitest 4.0 + Playwright	300+ 单元测试 + E2E 测试
打包	electron-builder 24.0	macOS/Windows/Linux 全平台

企业服务端

类别	技术	说明
Web 框架	Hono.js 4.x	超轻量 HTTP 框架，<1ms 路由
运行时	Node.js 24.x	最新 LTS 运行时
数据库	PostgreSQL 16	企业级关系数据库
ORM	Prisma 5.x	类型安全的数据库访问层
缓存	Redis 7.x	可选，会话与热数据缓存
认证	JWT	access + refresh 双令牌机制
加密	crypto-js (AES-256) + bcrypt	数据加密 + 密码哈希
AI SDK	OpenAI SDK	多厂商兼容（火山引擎、阿里云等）
部署	Docker + Docker Compose	server + postgres + redis 三容器

← 文档总览安全与合规

← 文档总览架构

系统架构

深入了解千手的双引擎 AI 架构、客户端-服务端分离模型、IPC 通信机制与数据流设计。

架构总览

┌─────────────────────────────────────────────────────────────────────┐
│                        桌面客户端 (Electron)                         │
│  ┌──────────────────────────┐  ┌──────────────────────────────────┐ │
│  │     Renderer Process     │  │        Main Process              │ │
│  │                          │  │                                  │ │
│  │  Shell (TitleBar /       │  │  fileService    emailService     │ │
│  │   ActivityBar / Status / │  │  searchService   pdfService      │ │
│  │   NotificationCenter)    │◄─►  agentService    auditService    │ │
│  │  Activities (13 IDs)     │IPC│  credentialStore sessionService  │ │
│  │  design-system + Zustand │  │  webSearchService toolRuntime    │ │
│  │  Stores (17 个 / 6 切片)   │  │                                  │ │
│  └──────────────────────────┘  └───────────┬──────────────────────┘ │
└────────────────────────────────────────────┼────────────────────────┘
                                             │ HTTPS / SSE
                                             ▼
                          ┌──────────────────────────────────┐
                          │        企业服务端 (Docker)         │
                          │                                  │
                          │  Hono.js 4.x REST API            │
                          │  ├── /api/auth    (JWT)          │
                          │  ├── /api/models  (模型管理)      │
                          │  ├── /api/agents  (智能体同步)    │
                          │  ├── /api/ai/execute  (SSE 代理) │
                          │  └── /api/audit   (审计日志)      │
                          │                                  │
                          │  PostgreSQL 16 ◄─ Prisma ORM     │
                          │  Redis 7.x (缓存)                │
                          └──────────────────────────────────┘

双引擎 AI 架构

千手的 AI 系统采用双引擎架构，根据 API Key 的存储位置将模型分为两类引擎：

DirectEngine（直连引擎）：用户自有模型，API Key 存储在客户端本地 Keychain（Electron safeStorage），请求直接发送到 AI 厂商 API，不经过企业服务端。适用于个人模型或需要完全数据隔离的场景。
ProxyEngine（代理引擎）：组织统一管理的模型，API Key 以 AES-256 加密存储在服务端。客户端发送请求到 /api/ai/execute，服务端注入密钥后转发，实现零信任客户端架构。

客户端架构

Main Process（主进程）

主进程运行 90+ 个服务模块，注册 550+ 个 IPC 处理器，负责所有需要系统级权限的操作。关键服务包括：

服务	职责	规模
fileService	文件系统监控（chokidar）、目录读取、文件操作	~30 个 IPC 处理器
emailService	IMAP 邮件同步、多账户管理、邮件线程；自动回复规则与 SMTP 出站队列	~30 个 IPC 处理器（含 SMTP outbox）
searchService	SQLite FTS5 全文检索、jieba-wasm 中文分词、LRU 缓存	~5 个 IPC 处理器
agentService	智能体执行调度、四引擎管理、流式输出、allowedTools 白名单	~10 个 IPC 处理器
auditService	审计日志记录、数据提取、报告生成	~40 个 IPC 处理器（含 audit project）
credentialStore	safeStorage 凭据隔离、API Key 安全存储、OAuth tokens	~5 个 IPC 处理器
sessionService	SQLite 会话持久化、消息存储、工件管理	~10 个 IPC 处理器
pdfService	PDF 文本提取、逐页渲染、OCR 集成	~5 个 IPC 处理器

集成服务（Integration）

把第三方协议与外部服务接入桌面工作台的服务层。详细行为见集成生态。

mcp	MCP 协议客户端：服务器管理、工具配置、OAuth 流
oauth	统一 OAuth 流（Google、Microsoft、自定义 IdP）
connector	通用连接器框架，桥接第三方数据源
calendar	日历事件同步与会议任务调度
knowledge / knowledgeGraph	本地知识库与知识图谱编译
urlFetchService / webSearchService	URL 抓取与多 Provider Web 搜索
presentonService	Presenton PPT 引擎适配（异步任务）
tool-runtime / skill-runtime	工具与技能运行时，统一治理外部能力

基础设施服务（Infrastructure）

支撑可靠性、可观测性与可演进性的横向能力，对功能产品域透明。

cacheService	统一 LRU 缓存与 cacheMaintenance 调度
metricsService	运行时性能指标采集与报告生成
featureFlagService	功能开关，支持灰度与 labs 通道
undo	编辑操作历史与回滚
traceService	Trace 链路记录，与 audit 共享数据
sessionCleanup	会话清理调度
mcp-export	把千手内部能力导出为 MCP / CLI 形式

Renderer Process（渲染进程）

home

默认可见

主页与导航中枢，含首次启动引导

mail

默认可见

邮件管理：账户、文件夹、消息列表、撰写、自动回复规则

calendar

默认可见

日历视图、事件详情，与 Mail Workspace 共享 OAuth 凭据

chat

默认可见

AI 工作区：智能体选择、流式输出、RAG 显示、任务规划

files

默认可见

文件管理：监控目录、预览器（15+ 格式）、文档操作

aisearch

默认可见

AI 增强搜索：自然语言检索 + FTS5 索引

knowledge

默认可见

知识库浏览与图谱可视化、Wiki 抽屉与来源引用

intel

默认可见

情报采集（含远程 OctoReport handoff 面板）

library

默认可见

内置资产与模板库

settings

固底

模型 / 智能体 / 邮件 / 外观 / Lab / Provider 能力矩阵等系统设置

audit

默认隐藏

审计追踪面板，可在 CustomizeMenu 中开启

education

默认隐藏

使用教学与教程入口，可在 CustomizeMenu 中开启

presenton

默认隐藏

PPT 生成专属工作区，可在 CustomizeMenu 中开启

Shell Chrome（外壳层）

组件	职责
TitleBarV2	32px 平台自适应顶栏（macOS / Windows / Linux 各取所需），承载窗口控制 + 全局命令入口
ActivityBar	左侧垂直图标栏，按 activityStore.order 渲染默认 Activity，固底放 Settings + UserMenu
CustomizeMenu	ActivityBar 中段「…」按钮唤起，用于显隐 / 重排 Activity 与开启隐藏 Activity
StatusBar	底部状态栏，承载凭据 / 同步进度 / License 提示 / 通知小红点
NotificationCenter	通知中心抽屉：分类型通知列表 + 类型化 deep-link，配 NotificationBridge 统一调度 toast
CommandPalette	CMD+K 全局命令面板，跨 Activity 跳转与动作触发
DialogHost / ToastHost / UndoBridge	对话框 / Toast / 撤销操作的全局宿主，与 design-system Dialog/Toast 协同

服务端架构

API 端点概览

端点	描述	方法
/api/auth/*	用户认证（登录、令牌刷新、登出）	POST
/api/models/*	模型管理与同步	GET/POST
/api/agents/*	智能体配置 CRUD 与同步	GET/POST
/api/agents/dify, /api/agents/stats	Dify 平台桥接与运行统计	GET/POST
/api/ai/execute	AI 执行代理（SSE 流式响应）	POST → SSE
/api/audit/*	审计日志查询与统计	GET
/api/intel/*	情报源管理、内容聚合、报告、远程 handoff	GET/POST
/api/drafts	邮件 / 文档草稿同步	GET/POST
/api/knowledge	组织知识库与文档共享	GET/POST
/api/wiki	团队 Wiki 接口	GET/POST
/api/license	授权与许可校验	GET
/api/notifications	通知中心	GET/POST
/api/organization	组织、部门、角色管理	GET/POST
/api/proxy	上游模型与外部服务代理出口	POST
/api/trial, /api/homepage	试用申请与官网内容数据	GET/POST
/api/admin/*	管理后台（用户、角色、系统配置）	GET/POST
/health	健康检查端点	GET

数据流

文件处理流

文件系统 → chokidar 监控 → 变更检测 → SQLite 索引更新 → FTS5 全文检索 → 搜索结果

AI 处理流

用户输入 → 引擎选择（Direct/Proxy）→ 模型调用 → SSE 流式输出 → 人工确认（高风险操作）→ 审计日志记录

邮件处理流

IMAP 服务器 → 邮件同步 → 本地 SQLite 存储 → AI 辅助撰写 → 人工确认 → SMTP 发送 → 审计日志

完整技术栈

桌面客户端

类别	技术	说明
桌面框架	Electron 39.x	自带 Chromium，避免国产 Linux WebView 兼容问题
UI 框架	React 18.x	并发模式，流式渲染优化
UI 原语	@/design-system/*	自研 headless 组件，Tailwind 着色，无外部 UI 库依赖
样式	Tailwind CSS	主样式 API，对接 src/styles/tokens.css 设计变量
类型系统	TypeScript 5.0+	全项目严格类型检查
构建工具	Vite 6.x	HMR 热重载，ESBuild 编译
包管理	pnpm 10.x	硬链接存储，节省磁盘空间
布局	design-system SplitView + Sidebar + WorkspaceHeader	一栏 / 多栏可拖拽分屏，13 个 Activity（9 默认 + Settings 固底 + 3 隐藏可选）
外壳层	src/shell/* (ActivityBar / TitleBar / StatusBar / NotificationCenter / CommandPalette)	跨 Activity 共享 chrome，由 navigationStore + activityStore + viewRegistry 联合驱动
状态管理	Zustand 5.0+	轻量级状态管理，17 个 Store（含 6 切片架构）
本地数据库	SQLite + FTS5	better-sqlite3，支持千万级记录
邮件	imapflow + nodemailer	IMAP 同步 + SMTP 发送
文档提取	pdf-parse, mammoth	PDF / DOCX / XLSX 文本提取
OCR	macOS Vision Framework	编译为 Universal 二进制，12x 快于脚本模式
Markdown	react-markdown + remark-gfm	安全渲染，代码高亮
测试	Vitest 4.0 + Playwright	300+ 单元测试 + E2E 测试
打包	electron-builder 24.0	macOS/Windows/Linux 全平台

企业服务端

类别	技术	说明
Web 框架	Hono.js 4.x	超轻量 HTTP 框架，<1ms 路由
运行时	Node.js 24.x	最新 LTS 运行时
数据库	PostgreSQL 16	企业级关系数据库
ORM	Prisma 5.x	类型安全的数据库访问层
缓存	Redis 7.x	可选，会话与热数据缓存
认证	JWT	access + refresh 双令牌机制
加密	crypto-js (AES-256) + bcrypt	数据加密 + 密码哈希
AI SDK	OpenAI SDK	多厂商兼容（火山引擎、阿里云等）
部署	Docker + Docker Compose	server + postgres + redis 三容器

← 文档总览安全与合规