banner
banner
banner
NEWS LETTER

AI 应用知识体系(五):桌面端、全栈整合与 TypeScript 速查

Scroll down

本篇是系列第 5 篇,包含桌面端整合、Vibe Coding 和 TypeScript/Zod 速查。

十一、桌面端与全栈整合

11.1 Electron + LangGraph:AI 工作流编排桌面端

桌面端的优势:数据安全、系统能力、本地算力。

Electron 的优势

  • 数据保存在用户本地。
  • 赋予 Node.js 能力:文件系统深度交互、系统级集成。
  • 无缝集成本地部署的 AI 模型。

技术栈:Node.js + React / Vue(TailwindCSS、shadcn-ui)+ Electron。

工作流编排:从 AI 助手到 AI 员工
LangGraph 的图状结构支持循环、分支、回溯;状态持久化;多 Agent 协作。

初始化(Electron Forge + Vite + TS)

1
2
3
4
5
pnpx create-electron-app@latest 3.ai-flow-app --template=vite-typescript
pnpm install
pnpm start # 启动后加载一段时间,弹出桌面端
pnpm package # 构建
pnpm make # 打包

依赖补充

  • @types/react、@types/react-dom
  • 样式:TailwindCSS + shadcn
    • pnpm add tailwindcss tailwind-merge tw-animate-css @tailwindcss/vite
    • ⚠️ 坑:在 vite.renderer.config.ts 定义 tailwindcss 插件时可能报 Unable to resolve path to module '@tailwindcss/vite'。
    • 替代方案:pnpm install -D tailwindcss @tailwindcss/postcss postcss,创建 postcss.config.mjs:
1
2
3
4
5
export default {
plugins: {
"@tailwindcss/postcss": {},
},
}
  • 然后在 index.css 里 @import "tailwindcss";,创建 tailwind.config.js,并在 renderer.tsx 引入 CSS。
  • 构建:@vitejs/plugin-react

工作流画布

  • 用 @xyflow/react:本身已实现连接,只需定义节点与边的关系。
  • 自定义节点:开始节点、结束节点、条件节点、大模型节点、工具节点。
  • 自定义 handle(XFFlowHandle),把自定义节点与 handle 组合后初始化。
  • ⚠️ 连接校验:有些节点之间不允许连接。
  • 参考:React Flow、React Flow 中文

打通前后端(Electron IPC 四步)

  1. preload 中定义方法:ipcRenderer.send。
  2. main 中监听方法:ipcMain.on。
  3. 新建全局声明文件 name.d.ts(模块命名空间与 exposeInMainWorld 的 name 保持一致),并在 tsconfig.json 中 "types": ["./name.d.ts"]。
  4. 前端通过「模块命名.xxx 方法」调用。

模型与 AI 层

  • 本地部署:Ollama;模型:qwen3:0.6b、mxbai-embed-large:latest。
  • AI 层:LangGraph(@langchain/core、@langchain/langgraph、@langchain/ollama)。
  • 三个核心点:状态与记忆、节点、边。参考 Use the Graph API。

六类节点的交互设计

  1. 开始节点:弹窗输入变量名、变量类型、默认值、描述。
  2. 结束节点:两种类型——返回变量(显示变量名与变量值,变量值含输出类型:字符串、数字、数组、对象、文件)与返回文本(以 Markdown 展示)。
  3. 大模型节点:下拉选择模型(模型列表可远程拉取)+ 输入提示词。
  4. 工具节点:进入插件市场搜索安装,或在节点中从已有 tools 列表选择。
  5. 条件节点:输入条件表达式,如「当前结果是否 > 10」。
  6. 串联:把 invoke 的输出传给结束节点展示,然后测试整条工作流。

11.2 Tauri + NestJS + LangChain:全栈 AI 服务中台

技术栈盘点

层 选型 为什么
前端 React(Hooks) + TypeScript + Tauri + shadcn/ui + TailwindCSS Tauri 用 Rust 做后端、前端渲染到系统原生 WebView,带来极致性能(秒级启动)、极小体积(几 MB)与更高安全性;对需要访问本地文件、调用系统能力的 AI 助手类应用,是降维打击。shadcn/ui 是「复制粘贴即拥有」的组合式范式,对组件有 100% 控制权
服务端 Node.js + NestJS + PostgreSQL + TypeORM NestJS 提供企业级骨架:依赖注入、模块化、AOP,强制 Module / Controller / Service 分层,规范性与可测试性对长期迭代的 AI 服务中台极有价值。pgvector 让 PostgreSQL 原生支持向量存储与检索——一套库同时搞定业务数据与 AI 数据,运维复杂度骤降,且能在同一事务里操作业务与向量数据
AI 应用层 LangChain.js + Vector DB + OpenAI API 把复杂的编排工作抽象、标准化:用 Chains 串多步操作,用 Agents 让模型自主决策与使用工具

Tauri vs Electron 的对比维度:性能、体积、安全性。

前端开发要点

  • 初始化 Tauri 项目并与 React 集成。
  • 核心通信:React 调用 Rust Commands 并处理回调。
  • 系统原生能力:窗口、菜单、系统托盘、文件对话框的定制与调用。
  • UI:shadcn/ui + TailwindCSS 最佳实践,从零构建聊天界面与文件管理界面。
  • 表单:react-hook-form + zod 校验。
  • 状态管理:Zustand 轻量实践。
  • 交互联调:封装 API 请求模块(axios / fetch);用 WebSocket 与 NestJS 建立实时通信,接收 AI 流式数据。

服务端开发要点

  • NestJS 核心:IoC / DI 思想、Module / Controller / Service 架构。
  • 数据库:TypeORM 连接 PostgreSQL,定义 Entity 与 Migration。
  • 核心接口:文件上传/解析/存储、知识库 CRUD、DTO + class-validator 请求校验、Guards + JWT 认证授权。
  • WebSocket Gateway:处理连接与消息,实现从 AI Service 到客户端的实时推送。

AI 应用开发要点

  • LangChain 六大核心模块:Modules、Prompts、Chains、Indexes、Memory、Agents。
  • RAG 全流程:Document Loaders(PDF/TXT/MD)→ Text Splitters → Embeddings → Vector Stores(内存 / Chroma)→ RetrievalQA 链 → PromptTemplate → 流式输出。
  • 注入 NestJS:封装 AIService 承载完整 RAG 链路,由 Controller 与 WebSocket Gateway 对外服务。
  • 进阶:Memory 多轮对话、Tools/Agents 调用外部 API、Function Calling 返回结构化数据;再用 LangGraph 解决线性链的局限(StatefulGraph、Nodes、Edges、Multi-Agent 协作)。

Monorepo 面试重难点

  • 如何解决 Monorepo 的「依赖地狱」?
  • Turborepo 如何实现增量构建与缓存?
  • 如何设计可扩展的 Monorepo CI/CD 流水线?

十二、Vibe Coding 实践

用自然语言让 AI 生成目标代码的编程方法。
流程主线:工程规范 → 方案设计 → 代码审查。

12.1 如何解决 AI 生成代码混乱

答案只有一句:上下文清晰控制策略。

落地做法

  1. 建开发手册:强调怎么做、不能怎么做;用工程规范约束(ESLint、Prettier 等)。
  2. 清晰规划(五个必答项):
    • 探讨新特性方案(拿到需求,详细调研,方案对比评审)
    • 具体实施步骤(每一步开发做什么)
    • 可能存在的风险(需要攻破的难点)
    • 最终单测、集成测试用例(测试驱动,先写 case)
    • 反思优化

AI 开发 SOP(Vibe Check)

  1. Plan 策划
  2. Coding 开发
  3. Lint 检查
  4. 开发隔离:新特性隔离;设计文档、实施文档单独成文件

工具选择:Claude + Codex。

12.2 用 Vibe Coding 做亿级协同表格

先做三层约束

  1. 全局约束(工程规范先行)。
  2. .clauderules:约束 AI 编码的技术实现。
  3. .plan:规划。

.plan 的需求描述用 STAR-L 法则

  1. 描述需求
  2. 探讨方案
  3. 实施步骤拆解
  4. 存在性能瓶颈点
  5. 优化细节
  6. 核心数据协议设计:先做顶层数据协议抽象

.features:按新特性拆解开发

  • 表格渲染引擎:支持千万行数据流畅渲染,沉淀到 monorepo 子包
  • 公式引擎、WebWorker 多线程架构
  • 协同实现:① Yjs(CRDT)/ OT,基于 Yjs 实现 ② 协同服务 ③ 协同层传输协议
  • 界面:登录、表格渲染

SOP 六步:规范 Spec → 代码生成 → 补测试用例 → 测试 + lint → 收尾 → check 过程。

配套 MCP / Skill

  • 通用工具协议调用 MCP。
  • 查资料:deepwiki MCP。
  • 查上下文:context7 MCP。
  • 集成测试:playwright MCP。
  • 工具管理:zcf(管理模型、管理 MCP)。

12.3 从零到一交付的操作序列

  1. 基于问题,先分析出大致步骤。
  2. 按使用的工具建对应文件夹存放产物。
  3. 建一个 plan 框架文档,告诉 AI 如何做项目规划。
  4. 等 AI 产出规划。
  5. 检查规划是否合理。
1
2
3
4
5
6
7
8
9
10
# 项目规划(plan 框架示例)

## 功能拆解
尽可能详细,按新特性逐步开发

## 性能优化
设计需求实现时,尽量考虑性能瓶颈点,并探讨性能优化方案

## 产出
规划完成后,将规划文档输出至 .plan 文件
  1. 建「新特性开发文档」(开发遵循的规范),告诉 AI 接下来按这些规范开发。
  2. 等 AI 生成代码。
  3. 检查并测试。
1
2
3
4
5
6
7
8
9
10
# 具体新特性开发(示例)

基于 .plan 规划,逐步开发新特性

严格遵循当前项目规范:
- eslint 规范
- prettier 规范
- commitlint 规范
- cspell 规范
- 单测规范

12.4 一小时交付:核心功能计划文档

  1. 基于「项目规划文档」+「新特性开发文档」,再建一个核心功能计划文档,指明用什么技术实现。
  2. 让 AI 基于核心功能文档生成新的开发规划文档。
  3. 按新规划生成项目。
  4. 测试。
1
2
3
4
5
6
7
8
9
10
11
## 核心功能
1. 表格渲染器
- 基于 canvas 实现底层绘制引擎
- 滚动通过遮罩 div 借用滚动条,实现 canvas table 的可视区渲染逻辑
- 单元格需用插件化协议设计,支持动态扩充不同类型
2. 前端架构
- next.js + shadcn + tailwindcss
3. 服务端
- prisma + PostgreSQL
4. 运维层
- docker compose 启动 pg,完成基础设施启动

十三、TypeScript 与 Zod 速查

13.1 为什么 TS + Zod 在 Agent 开发中应用广泛

工具 检查时机 在 Agent 中的角色
TypeScript 开发阶段 / 编译时,静态类型检查 约束框架契约、节点类型、协议数据结构
Zod 生产阶段 / 运行时 ① Agent 开发时作为入参标准;② Agent 开始时作为标准化输出的定义;③ 参数提取的 schema 定义;④ 输出结果的结构化处理

13.2 TS 基础与类型操作

① 基础类型
number、string、boolean、array、enum、tuple、any、unknown、never、undefined、null

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 数组:Array<{ type: 'ai' | 'user' | 'system'; text: string }>
const msg: { type: 'ai' | 'user' | 'system'; text: string }[] = [
{ type: 'ai', text: '你好' },
{ type: 'user', text: '你好' },
{ type: 'system', text: '你好' },
]

// 元组
const vector: [number, number, number] = [1, 2, 3]

// any / unknown / never
const a: any = 1
const u: unknown = 1
// never 表示「永不存在的值」,通常用于抛错函数或永远不返回的分支
function fail(msg: string): never {
throw new Error(msg)
}

② interface 与 type 的两种扩展方式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
interface User {
name: string
age: number
}
type UserT = {
name: string
age: number
}

// 扩展方式不同
interface NewUser extends User {
email: string
}
type NewUserT = UserT & {
email: string
}

③ 联合类型 + 类型保护(类型收敛)

1
2
3
4
5
6
7
8
9
type Prompt = string | { type: 'ai' | 'user' | 'system'; text: string }[]

function joinText(prompt: Prompt): string {
if (typeof prompt === 'object') {
// 类型保护,类型收敛为数组
return prompt.map((item) => item.text).join('')
}
return prompt
}

④ 泛型

1
2
3
4
5
6
function stringify<T>(input: T): string {
if (typeof input === 'object' && input !== null) {
return JSON.stringify(input)
}
return String(input)
}

⑤ 类型操作与工具类型

1
2
3
4
5
6
7
8
9
10
11
12
13
// 联合类型:节点协议
type Node = StartNode | EndNode | LLMNode

// 交叉类型:类似面向对象的继承,是「面向协议编程」的基础
type IdProtocol = { id: string }
type NameProtocol = { name: string }
type PersonProtocol = IdProtocol & NameProtocol

// 工具类型
type User0 = { name: string; age: number }
type WithoutAge = Omit<User0, 'age'> // 剔除
type OnlyName = Pick<User0, 'name'> // 摘取
type PartialUser = Partial<User0> // 全部转可选

⑥ 类型体操练习:type-challenges。从 README 选任意标签看示例,点「Take the Challenge」即可开练,目标是亲手实现常用工具类型。

13.3 TS 在 AI 框架中的地位

  • TypeScript 是 AI 框架的首选支持语言,与 Python 地位相当。
  • 主流框架几乎都同时提供 Python 与 TS 版本:LangChain.js、LangGraph.js、DeepAgent.js、Mastra……

前端深耕 AI Agent 的三点沉淀

  1. TS + AI 框架的工程化能力。
  2. TS AI SDK 开发 + Node.js / NestJS / Nuxt.js 的服务化能力。
  3. 数据持久化层:Prisma + PostgreSQL。

13.4 Zod 要点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import { z } from 'zod'

// 用户协议定义
const userSchema = z
.object({
name: z.string().describe('用户名'),
age: z.number().describe('用户年龄'),
})
.describe('用户基础协议')

// 从 schema 反推类型(单一事实来源)
type User = z.infer<typeof userSchema>

const result: User = userSchema.parse({
name: '张三',
age: 18,
})

// 宽容模式:自动纠错('18' -> 18)
const flexibleSchema = z.object({
age: z.coerce.number().describe('用户年龄'),
})
const res = flexibleSchema.safeParse({ age: '18' })

// 时间区间 + refine 约束
const timeSchema = z
.object({
start: z.iso.date().describe('开始时间'),
end: z.iso.date().describe('结束时间'),
})
.refine((data) => new Date(data.start) < new Date(data.end), '开始时间不能晚于结束时间')

在 Agent 中的三个用法

  1. 参数提取的 schema 定义(让模型按 schema 返回结构化参数)。
  2. 输出结果的结构化处理(safeParse 兜底,失败可回传模型重试)。
  3. 工具入参校验(运行时防护)。

其他文章
目录导航 置顶
  1. 1. 十一、桌面端与全栈整合
    1. 1.1. 11.1 Electron + LangGraph:AI 工作流编排桌面端
    2. 1.2. 11.2 Tauri + NestJS + LangChain:全栈 AI 服务中台
  2. 2. 十二、Vibe Coding 实践
    1. 2.1. 12.1 如何解决 AI 生成代码混乱
    2. 2.2. 12.2 用 Vibe Coding 做亿级协同表格
    3. 2.3. 12.3 从零到一交付的操作序列
    4. 2.4. 12.4 一小时交付:核心功能计划文档
  3. 3. 十三、TypeScript 与 Zod 速查
    1. 3.1. 13.1 为什么 TS + Zod 在 Agent 开发中应用广泛
    2. 3.2. 13.2 TS 基础与类型操作
    3. 3.3. 13.3 TS 在 AI 框架中的地位
    4. 3.4. 13.4 Zod 要点
请输入关键词进行搜索