架构概览

WesCraft 的技术架构概览，面向需要理解系统内部运作的用户和开发者。

整体架构

WesCraft 采用 Electron 桌面应用架构，内嵌 Go 后端和 wesgine v1.0 引擎：

┌─────────────────────────────────────────────┐
│           Electron 桌面应用                   │
│  ┌────────────────────────────────────────┐  │
│  │     React 19 + Vite + Tailwind 4       │  │
│  │     (前端 UI 层)                        │  │
│  └────────────────┬───────────────────────┘  │
│                   │ HTTP                      │
│  ┌────────────────▼───────────────────────┐  │
│  │     Go 后端 (:3100)                     │  │
│  │  ┌──────────────────────────────────┐  │  │
│  │  │    wesgine v1.0 (go mod 嵌入)     │  │  │
│  │  │    Hypervisor + Cell             │  │  │
│  │  └──────────────────────────────────┘  │  │
│  └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

技术栈

层技术
框架React 19 + TypeScript
构建Vite 6.x
样式Tailwind 4
动画framer-motion
状态Zustand
路由React Router v7
组件基元Radix UI
块编辑器BlockNote
i18ni18next + react-i18next
AI 引擎wesgine v1.0（go mod 嵌入）
存储SQLite + FTS5

Go 后端模块

wescraft.git/
├── cmd/wescraft/          # 入口（serve / init）
├── internal/
│   ├── content/           # 内容管理引擎（页面 CRUD + Block CRUD）
│   ├── knowledge/         # 知识引擎（6-Stage 管线）
│   ├── fileintel/         # 文件智能引擎（本地文件索引）
│   ├── capture/           # 采集引擎（多源输入 → 收集箱）
│   ├── export/            # 输出引擎（PDF/Word/MD/公众号）
│   ├── tools/             # 19 个 wescraft 专属工具
│   ├── engine/            # wesgine 初始化（Hypervisor + Cell）
│   ├── deviceagent/       # Electron device agent MCP server
│   └── store/             # 应用层存储（wescraft.db）
├── builtinskills.go       # //go:embed skills
├── skills/                # 预装 Tier C 技能
└── extension/             # 浏览器扩展

Cell 模型

WesCraft 基于 wesgine 的 Cell 隔离模型，提供两种部署形态：

个人版

cell, _ := hyp.Cells().GetOrCreate(ctx, wesgine.CellSpec{
    ID:               "personal",
    Timezone:         "Asia/Shanghai",
    Locale:           "zh-CN",
    ProviderStrategy: "own_only",
    Compliance:       "standard",
})

团队版

cell, _ := hyp.Cells().GetOrCreate(ctx, wesgine.CellSpec{
    ID:               "team-" + teamID,
    Governance:       mapTeamGovernance(team),
    Compliance:       team.Compliance,
})

Cell 边界选型

选择 Cell 粒度的三个维度：

维度问题决策
数据边界一个人的数据 vs 一家公司的数据？选后者的粒度
合规边界GDPR 请求给一个人 vs 一家公司？选后者
计费边界谁付账？谁的粒度

五大引擎

1. 内容管理引擎（internal/content/）

负责页面和 Block 的 CRUD 操作：

2. 知识引擎（internal/knowledge/）

6-Stage 知识管线：

采集 → 清洗 → 分块 → 索引 → 标签 → 关联

3. 文件智能引擎（internal/fileintel/）

本地文件索引系统（per-cell 隔离）：

4. 采集引擎（internal/capture/）

多源内容采集：

5. 输出引擎（internal/export/）

多格式导出：

数据目录结构

$XDG_DATA_HOME/wescraft/              # macOS: ~/Library/Application Support/wescraft/
├── hypervisor.db                      # Cell 注册表
├── cells/personal/                    # 个人版 Cell
│   ├── meta.db                        # Cell 元数据
│   ├── sessions.db                    # 会话与记忆
│   ├── state.db                       # 运行时状态
│   ├── knowledge/                     # 知识库文件
│   └── skills/                        # Tier C 技能包
├── wescraft.db                        # 应用层数据（页面、Block、收集箱等）
└── db/wescode_auth.db                 # 登录 session（跨 Cell 共享）

工具体系

WesCraft 的 19 个专属工具通过 cell.Tools().Register() 装到 Cell：

类别工具名数量
Block 操作read_block / write_block / edit_block / delete_block / move_block / transform_block6
文件智能search_files / read_local_file / find_related_files / file_overview / assemble_from_files5
输出export_pdf / export_docx / export_wxpub3
其他capture_url / note_summarize / create_doc / db_query / db_insert / db_update5

所有工具都是 Tier C（Cell 级），装到对应的 Cell 中，不同 Cell 之间工具互不可见。

SDK 层关系

wesgine      引擎内核
wesui        前端渲染（零 fetch / 零 store / 零路由）
wesapp       公共 Go 库
weisyn/sdk   平台客户端
   ▲
产品：wesclaw | wescode | wescraft | teleclaw
     产品之间互不 import

WesCraft 通过 go mod replace 引用 wesgine 和 wesapp，不导入其他产品仓代码。公共 Go 能力只进 wesapp；公共 UI 能力进 wesui。

安全边界