AI 大前端全栈架构师 · 学习地图

正文按「概念 → 落地 → 架构 → 工程化」的认知顺序排列。

**一、总览**：能力地图、技术栈、实战项目、原课程映射
**二、AI 应用基础**：核心概念、LLM、提示词工程、模型选型、流式输出
**三、AI 场景落地与平台形态**：按团队规模的落地、三个方向、平台盘点、六大模块、私有化部署
**四、RAG 与 Agent 原理**：RAG 全链路、ReAct、工具调用、智能体三分类、四阶闭环
**五、AI 应用开发框架**：为什么要框架、LangChain 标准化、LangChain vs LangGraph、分层架构、LangGraph 内核
**六、工作流与 AI 应用引擎架构**：三种形态、工作流类型、节点体系、DSL、编辑器选型、执行器、微服务拆分、沙箱
**七、协同编辑**：编辑器内核、三种格式化路线、CRDT vs OT、Yjs 实战、多端协同
**八、服务端渲染与前后端同构**：演进脉络、SSR/SSG/同构、AI 产品特殊性、Next.js、自研 SSR
**九、前端监控与可观测**：指标体系、上报策略、全链路架构、ClickHouse、预警、AI 根因分析
**十、工程化与架构**：Monorepo、包管理器、构建编排、脚手架、规范体系、组件库、Vite、Babel、公式编译器
**十一、桌面端与全栈整合**：Electron + LangGraph、Tauri + NestJS + LangChain
**十二、Vibe Coding 实践**：上下文控制、AI 开发 SOP、亿级表格交付
**十三、TypeScript 与 Zod 速查**：类型操作、Zod 要点、Agent 中的用法
**十四、音视频与 FFmpeg 基础**：容器/编码/协议、像素与色彩、命令结构、高频操作、滤镜链、视觉增强、色彩空间对接、前端落地
**十五、附录**：学习资源索引、本机案例路径索引
**十六、面试题库**：初中级 16 题 / 中高级 16 题 / 专业级 13 题 / 专家级 3 题 + 高频追问速答 + 项目介绍模板

一、总览：能力地图与技术栈

1.1 学习目标

实现思路：所有实战都是为了开拓思维，重点看「为什么这么做」。
算法：什么时候用什么算法最优。
架构：了解架构、灵活运用，什么情况用什么架构。
经验与技术储备。
Agent 相关知识：微调、Agent、RAG。
工具意识：插件版本号用 Version Lens 看，构建工具用 tsup。
拆解能力：无论面对什么问题，都能分析拆解出各个点，并对每个点分别分析。

公开课来源：妙码免费公开课

1.2 技能框架（重点往工程化、构建、架构精进）

分层	技术清单
基础核心	数据结构与算法；TS、Python、Java(Node)、SQL(PostgreSQL)
前端	React18 + zustand/jotai；Vue3 + pinia；Electron(Node)、Tauri(Rust)⭐；shadcn(Tailwind)⭐；pnpm monorepo；Vite / Rspack
后端	NestJS⭐；React 选 Next.js、Vue 选 Nuxt（SSR 方案，前后端同构场景）；PostgreSQL⭐（ORM：Prisma⭐ / TypeORM）；RESTful API；JWT 认证
AI 应用开发	编排能力（链式 / 图式）；LangChain⭐；LangGraph⭐；Mastra；RAGFlow；RAG + 向量数据库⭐；模型部署（Ollama + Qwen3）；模型微调
工程化 & DevOps	Git；pnpm monorepo；CI / CD；Docker⭐、Docker Compose⭐、K8s、K3s、minikube

1.3 实战项目地图（学习点）

① 微前端

在分拆原子应用场景下的落地与实践。

② 协同编辑器（从零到一）

文档编辑器：左侧为搜索、全部文档、文档图谱（均为新页面打开）、文档列表（+ 新增）、设置/关于、登录；右侧为文档内容区（上方标题 + 分享按钮，下方类飞书编辑区）。
- 效果：同一文档内实时看到他人操作（包含光标协同：用户 1 框选区域，用户 2 可见；用户 2 输入文字，用户 1 实时可见），并展示他人头像。
代码编辑器：带行号，双向实时同步；鼠标移到对方操作的代码上可显示对方名字。
- 进阶：代码补全、语法高亮、错误提示、自定义规则。
画板 / 白板：拖拽已写好的组件入场，协同可见。
协同表格：编辑时能看到编辑者头像与其选中的单元格（头像位于该行行首）。
数字孪生编辑器：协同 + 拖拽组件入场。

③ 团队基建与平台

推动团队基建落地。
数字孪生平台整体架构（Vanilla + WebAssembly + Vue3）
- 基于 Cesium 的 Web GIS 架构与实践
  - 表示层：物料编辑器、三维编辑器（Three.js）
  - 图表层（ECharts）：编排引擎（吸附线、标题、二维/三维图表等资源）、拖拽图表、数据可视化
  - 协同：用户 1 编辑图表时，用户 2 能实时看到用户 1 的头像停在编辑位置；反之亦然
  - 效果：进入后是空白图层（可新建），从组件/资源区拖出内容，调整尺寸与位置放到图层上；注意层级——后拖出的内容层级更高；图表可绑定数据源展示真实数据；三维可用 Yjs 或 Three.js 实现
- 基于 OpenLayers 的地图应用与可视化开发
- 基于 WebGL 的 3D 可视化开发实践
低代码平台：编排引擎、流程引擎、编辑器、代码执行器与 JavaScript 沙箱。
用户行为分析 SDK 及监控可视化整体实现。
可视化渲染引擎设计与实现。
基于 RAG、Agent 的前端 AI 应用流程编排平台。

1.4 原课程 → 本文档章节映射

原课程	主题	现位置
第一课	字节系 AI 场景落地与工作流编排	§2、§3
第二课	Ollama + DeepSeek AI 开发平台全链路	§3.4、§3.5、§5.6
第三课	类扣子 / Dify 应用引擎架构	§6
第四课	飞书智能协同文档全链路	§7.2 ~ §7.4
第五课	SSR 与前后端同构	§8
第六课	Yjs 协同实战	§7.5 ~ §7.6
第七课	前端 AI 智能体类 Dify（原注「与第十五课重复」，本篇已合并）	§2.3 ~ §2.5、§4.1、§16.6 案例 A
第八课	性能与异常监控平台 AI 化	§9
第九课	类扣子 Agent 平台私有化部署	§3.5、§5.1
第十课	LangChain.js 架构与 openclaw 引擎	§5
第十一课	TypeScript AI Agents 框架	§13、§5.5
第十二课	工作流编辑器 + Agent 引擎	§6.2 ~ §6.10
第十三课	Next.js AI Agents 最佳实践	§8.4、§12.4
第十四 / 二十三课	Nuxt、react-native（原笔记标注跳过）	未收录
第十六课	pnpm monorepo 工程化	§10.1 ~ §10.5
第十七课	前端监控 AI 智能化	§9、§10.7
第十八课	UI 组件库 + Rspress	§10.8
第十九课	Babel 进阶与飞书公式 parser	§10.10、§10.11
第二十课	Vite 工程智能化	§10.9
第二十一课	AI BI 自动化分析引擎	§2.6、§9.5
第二十二课	TS、Zod 速查	§13
第二十四课	Electron + LangGraph	§11.1
第二十五课	Tauri + NestJS + LangChain	§11.2
第二十六课	NodeJS 全栈 AI 实战	§10.6、§16.6 案例 A
第二十七课	openclaw 系统级 Agent	§4.4 ~ §4.6、§5.5
第二十八课	Vibe Coding 实践	§12
（无编号）	音视频基础与 FFmpeg	§14

二、AI 应用基础

2.1 核心概念

训练：需要大量数据，且必须是领域数据。
模型：用海量数据训练出来的产物。
Prompt 优化：决定输出质量的关键可变项。
输出：最终交付给用户或下游系统的结果。
知行合一：概念要能落到工程实现，才算真正掌握。

2.2 模型应用发展的三个阶段

阶段	含义	前端关注点
Prompt	用户输入提示词，模型按要求生成	提示词交互设计、参数暴露
RAG	外挂知识库辅助模型输出，结果更贴合期望	知识库管理界面、引用溯源
Agent	智能体，能编排「内容加工 → 输出」的完整流程	过程可视化、人机干预

2.3 LLM 基础

大语言模型是基于海量文本训练、拥有数千亿甚至万亿参数的深度神经网络。核心机制：给定上下文，预测下一个最可能的 token，不断预测即可生成连贯文本。

核心能力：概率预测。
关键特性：
- 涌现能力：规模达到阈值后表现出未被明确训练过的复杂能力。
- 上下文依赖：回答质量完全取决于提供的上下文。

基础模型（Foundation Models）

定义：通用领域海量数据预训练，具备广泛知识与多种能力，是所有垂类应用的「毛坯房」。
例子：GPT-4、GPT-3.5、Claude 3 Opus、Gemini 系列、Llama 系列。
场景：项目初期快速验证，或需要广泛知识、强推理与生成能力的场景。

微调模型（Fine-tuned Models）

定义：在基础模型上用特定领域、高质量、小规模数据集做额外训练，使其在特定任务或风格上表现更优。
场景：医疗文献、公司内部代码库等。

选型必须关注的三个差异点

上下文窗口：能处理的最大长度；过长也可能「大海捞针」。
成本：按 token 计费，输入输出价格不同，应避免携带不必要的长对话历史。
响应速度：不同模型推理速度差异很大，直接影响体验。

2.4 提示词工程四招

技巧	作用
角色扮演（Role-playing）	开头设定角色再带入问题，提高特定领域回答质量
思维链（Chain-of-Thought）	指令「分步思考」，提升数学、逻辑、复杂规划的准确率
结构化输出（Structured Output）	强制返回 JSON，免去字符串解析，直接用于数据绑定与状态管理——前端最实用的一招
指令与数据分离	用明确分隔符把指令与待处理数据隔开，减少模型混淆

2.5 模型选型与多模态能力对照

能力	国际模型	国内模型
文生文	GPT 系列、Claude 3.5 Sonnet	Qwen3、DeepSeek-V3、Kimi（长文本 / 逻辑推理强）
文生图	Flux 2 Pro、Midjourney v6.5	Qwen-Image 2.0 Pro、可灵 Image 3.0、通义万相
文生视频	Sora 2 Pro、Runway Gen4	Kling 可灵 2.6、通义万相 Wan2.6
图生图	Flux 2 Pro、Stable Diffusion 3.5（ControlNet 强）	Qwen-Image 2.0 Pro、可灵 Image
图生视频	Runway Gen4	Kling 可灵 2.6（国内首选，主体一致性强）、通义万相 Wan2.6 I2V
文生 PPT	—	「LLM + PPT 渲染引擎」组合：Kimi（PPT Skill）、通义千问 + DeepPresenter；开源：DeepSeek + Presenton
文生 UI	—	「LLM 生成前端代码 + 生图模型渲染界面」：GPT-4o / Qwen3 输出 React / HTML + Tailwind，Flux、Qwen-Image 做预览，专用 UI 模型 UIzard

Agent 常见能力清单：文生文、文生图、文生视频、图生图、图生视频、文生 PPT、文生 UI。

落地前先定三件事

是否私有化：本地 Ollama 部署，语音方向用 OpenAI Whisper。
智能体类型：工作流型 workflow agent / 通用型（Manus）/ 系统级（openclaw）。
模型服务方式：自己部署 or SaaS。

2.6 流式输出（SSE）与打字机效果

SSE（Server-Sent Events）：即 EventSource，服务端自有推送能力，允许在一次 HTTP 连接中持续向前端发送 text/event-stream 格式数据，无需客户端反复轮询。

打字机效果的完整链路：

客户端请求时将 responseType 设为 stream。
服务端用 SSE 实现流式响应，关键在响应头：
- Content-Type: text/event-stream
- Cache-Control: no-cache
- Connection: keep-alive
数据通过遍历逐块下发；客户端设置 UTF-8 编码，用 while 循环解码并拼接。
拼接结果实时追加渲染到页面。
接入 AI：把模型返回的增量数据写入服务端响应流，即得到 AI 打字机效果。

典型架构（自然语言 → 图表）：LLM + Text2SQL + DSL

sequenceDiagram
    actor User as 用户
    participant Front as 浏览器 (前端)
    participant Nuxt as Nuxt 服务器 (后端)
    participant Ollama as Ollama (LLM)

    User->>Front: 1. 输入自然语言查询
    Front->>Nuxt: 2. 发起 POST 请求 (/api/generatev2)
    Nuxt-->>Front: 3. 建立 SSE 连接（流式响应）
    Nuxt->>Ollama: 4. 调用 LLM（携带格式化后的 Prompt）
    Ollama-->>Nuxt: 5. 返回 ECharts Option（JSON 配置）
    Nuxt-->>Front: 6. 通过 SSE 推送图表数据
    Front->>Front: 7. Pinia 更新状态，Vue 响应式渲染
    Front-->>User: 8. 显示可视化图表

三、AI 场景落地与平台形态

3.1 按团队规模看落地场景

个人开发者

Prompt 工程。例如：以「前端专家」身份优化提示词，让其他使用者通过这个应用更好地咨询前端问题。
需要掌握：怎么设计 Prompt，并根据上下文做对应调整。
应用场景：写作助手、代码补全、学习辅助等。

小型团队 / 创业公司

客服机器人（RAG）。
内容生成工具：产品发布稿、changelog（发布日志）。
数据报告与分析：「我想看 XXX 的数据变化趋势」。

大型企业

现有业务集成：如飞书云表格接入 AI，用户说「帮我搭一个 CRM 表格」，AI 自动生成并创建，包含客户信息、订单信息、合同信息等字段。
- 需要掌握：用什么技术生成表格。表格生成等级：
  1. 用现成库
  2. 初级：table DOM
  3. 中级：虚拟表格
  4. 高级：Canvas Table
  5. 专业：Canvas + Tile 技术
  6. 高级专家：Skia + WebAssembly
AI 开发平台：
1. 网关平台
2. 数据开发平台：Hadoop、Hive、达梦
3. 大数据离线开发平台
4. 实时计算：Flume
5. 算法平台：算法包 + 算法流程编排

跨行业应用

SaaS 公司想办法把业务接入 AI。
场景：疾病预测、AI 分析患者数据、智能助教。

3.2 AI 大模型应用开发的三个核心方向

① AI 原生应用：用 AI 把自然语言转成设计图，再把设计图转成代码的完整流程（如 Figma）。

智能客服
代码生成工具
AI 驱动 UI 生成

② AI 赋能已有业务（AI SRM、AI CMS、AI HRM、AI OA）

自然语言搜索
自然语言生成图表
总结、润色

③ AI 应用开发平台（应用生成引擎：Coze、Dify、RAGFlow、FlowiseAI）

Agent 构建平台
可视化提示词编排
类 Dify 平台

3.3 主流平台盘点

平台	特点
字节扣子（Coze）	SaaS 在线化；Notion、飞书云表格存储知识库内容；插件生态健全，但模型选择不如 Dify 多
Dify	支持向量数据库、结构化/非结构化数据，可接入模型非常多
Flowise	比 Dify 更低代码，更偏开发者，更灵活
ChatBox	桌面端通用对话客户端
AnythingLLM	面向文档问答的一体化 LLM 应用

学习捷径：「抄」是最快的学习方式。做生成式 AI 应用可直接对标 Coze；追求纯技术与私有化则对标 Dify。

3.4 AI 应用引擎的六大核心模块

生成式 AI 应用引擎 = 在传统工作流基础上，集成大模型、智能体搭建、插件、工作流、触发器与辅助功能的综合平台。

模块	职责
插件（Plugins）	通过插件化机制把复用的处理逻辑抽象出来，扩展模型能力、对接外部系统。每个插件实现统一接口，可在不同模块中被调用
工作流（Workflows）	一系列可执行任务的自动化流程；每个任务封装为一个「节点」，按顺序（或图关系）执行
触发器（Triggers）	根据用户输入或系统状态自动触发某些操作；前端可依据用户行为、系统状态触发工作流或插件
知识库（Knowledge Base）	存储并管理知识，使引擎能针对不同查询给出准确答案
记忆（Memory）	保持与用户的历史交互与上下文，使响应更个性化、更有上下文相关性
用户输入 / 输出	前端收集信息并向引擎发起请求，引擎返回结果

Coze 核心业务视角（五件事）：人设（Prompt）、技能（插件化思维创建插件）、知识库、工作流、发布机制（发布到不同渠道，或作为插件插入网页）。

重难点五件事：① 流程编排引擎编辑器 ② 流程节点执行沙箱 ③ 日志系统 ④ 错误处理机制 ⑤ 服务化。

3.5 实操：私有化部署一套 AI 应用引擎

前置检查：CPU 至少 2 核、内存 4G 以上，安装 Docker。

方案 A：Coze Studio（开源版）

从 https://github.com/coze-dev/coze-studio 拉取源码。
按 README 用 Docker Compose 部署。
配置模型对接（如火山豆包模型的 API Key 与 Endpoint）。

方案 B：Ollama + Dify（本地模型 + 知识库）

安装 Ollama 与 deepseek-r1:latest、Docker。
模型：deepseek-r1:latest 残血版，通过 Ollama 部署。
知识库：Dify 向量数据库，Docker 部署。
- 下载 GitHub zip，解压后在 docker 目录执行 cp .env.example .env 与 docker compose up -d
- 检查容器是否齐全
- 浏览器访问 localhost；初次安装访问 localhost/install，配置邮箱、密码、管理员账户
在 Dify 引入模型：设置 → 模型供应商 → Ollama → 添加模型，配置名称（deepseek-r1:latest）、URL（http://IP:11434），其余默认。
- ⚠️ 容器化场景下 URL 不能写 localhost，必须写宿主机局域网 IP。
创建空白应用（对话 / 工作流编排），建知识库，按步骤发布；他人可通过 API（有文档）或网页版访问；智能体发布后相当于进了应用商城。

价值点（面试可直接用）：不仅能说清部署流程，还能从平台构建者视角说明一个 Agent 如何通过人设、插件、知识库（RAG）、工作流几大模块协作，从简单问答走到复杂业务流程自动化。

四、RAG 与 Agent 原理

4.1 RAG 全链路（前端视角拆解）

核心价值：给大模型外挂一个「实时、私有的知识大脑」。

阶段一：数据准备与索引（离线 / 后台）

文档加载（Loading）：从各种源加载原始文档。
文本切片（Splitting / Chunking）：长文档切成有意义的小块。常见策略：固定长度切块、按段落/标题切块、递归切片。
向量化（Embedding）：调用 Embedding 模型，把每个文本块转成高维向量——即该文本块在「语义空间」中的坐标。
入库（Storing）：将文本块原文与对应向量一并存入向量数据库。

阶段二：查询与生成（在线 / 实时）

用户提问：前端接收问题。
问题向量化：用与索引阶段相同的 Embedding 模型把问题转成向量。
向量检索（Retrieval）：在向量库中搜索语义最相似的文本块向量。
上下文增强（Augmentation）：把 Top-K（如最相关的 3 个）文本块与用户原问题组合成一个信息量更大的 Prompt。
生成答案（Generation）：把增强后的 Prompt 发给 LLM，基于给定材料生成最终答案。
前端呈现：
- 流式输出（Streaming）：逐字渲染答案。
- 引用溯源（Citation）：RAG 应用的黄金标准。界面必须清晰展示答案的每一部分基于哪个检索到的文档块——既建立信任，也提供深挖入口。

4.2 Agent 与 ReAct 循环

核心思想：自主循环。

Agent 本质公式

$Agent = LLM（大模型） + Planning（规划） + Memory（上下文记忆 / 持久化记忆） + Tool（工具） + User（MCP + Skills）$

ReAct（Reasoning and Acting）：目前系统级智能体最主流的推理框架，要求 LLM 在每一步都产出特定结构。

环节	说明
Thought（思想）	LLM 自我反思：目标是什么？已知什么？下一步做什么？需要什么工具？该过程对用户不可见，但在后台日志中至关重要
Action（行动）	基于思考决定调用某个工具并给出输入，格式通常结构化，如 `{ "tool": "weather_api", "tool_input": "北京" }`
Observation（观察）	系统真正执行该行动（如调用天气 API），把返回结果（如「北京今天晴，25℃」）作为观察再次输入 LLM
循环	接收观察结果后开始新一轮「思想 → 行动 → 观察」，直到认为目标达成，输出最终答案

核心价值：把 LLM 从「只会生成文本的模型」变成「能基于目标自主决策、调用工具、处理反馈的智能系统」。

flowchart TD
  U[用户输入目标] --> THINK[LLM 思考: 下一步要做什么?]
  THINK --> DECIDE{是否需要调用工具?}
  DECIDE -->|是| CALL[生成工具调用指令: Tool + Args]
  CALL --> EXEC[执行工具调用]
  EXEC --> OBS[获取工具返回结果: Observation]
  OBS --> INJ[将 Observation 注入上下文]
  INJ --> THINK
  DECIDE -->|否| RESP[LLM 生成最终答案]
  RESP --> OUT[输出结果]

  classDef loop fill:#f0f9ff,stroke:#0369a1;
  classDef done fill:#f6f6f6,stroke:#444;
  class THINK,DECIDE,CALL,EXEC,OBS,INJ loop;
  class RESP,OUT done;

4.3 工具（Tool）：智能体的手脚

本质：把 LLM 的文本生成能力映射为具体的函数、API、系统指令执行能力。

标准工具定义三要素

名称（Name）：唯一标识。
描述（Description）：说明这个工具做什么、什么时候用——这是 LLM 决策的关键依据。
参数（Args Schema）：输入参数定义，通常用 JSON Schema 描述。

常见工具类型

搜索引擎 API：查询实时信息。
计算器：精确数学运算。
代码解释器：执行 Python，做数据分析或绘图。
企业内部 API：查订单、取用户信息、操作 CRM。
RAG 本身也是一个工具：从私有库检索资料。

两个前端强相关点

过程可视化：Agent 执行是动态、多步骤的，优秀前端应实时清晰展示当前状态——对调试、监控、建立信任都至关重要。
交互式干预：允许用户在 Agent 执行过程中介入、修正方向。

4.4 智能体三分类与选型决策

① 工作流型智能体（DAG 有向无环图）

核心本质：流程优先的确定性智能体。
底层逻辑：人定义规则，AI 填充执行。
代表产品：Coze、Dify、Make、n8n。

flowchart LR
  U[用户输入目标] --> P[预定义 DAG 流程]
  P --> N1[节点1: LLM 任务拆解]
  N1 --> N2[节点2: API / 工具调用]
  N2 --> N3[节点3: LLM 内容生成]
  N3 --> N4[节点4: 数据格式化 / 校验]
  N4 --> OUT[结果输出]
  N2 -->|执行异常| ERR[异常处理节点]
  ERR --> N2

  classDef box fill:#F0F8FF,stroke:#334155,stroke-width:1px;
  classDef kb fill:#FFC0CB,stroke:#FF1493;
  class U,P,N1,N2,N3,N4,OUT box;
  class ERR kb;

② 通用型智能体（完全依赖 LLM Planning）

核心本质：目标优先的全自主智能体。
底层逻辑：人定义目标，AI 定义规则与执行。
代表产品：Manus、openManus、AutoGPT、GPT-4o。

flowchart TD
  USER[用户输入终极目标] --> DECOMP[LLM 任务拆解与步骤规划]
  DECOMP --> TOOLSEL[工具选择与指令生成]
  TOOLSEL --> ENV[环境感知与指令执行]
  ENV --> VERIFY[执行结果校验与反馈]
  VERIFY -->|目标达成| OUTPUT[最终结果输出]
  VERIFY -->|目标未达成 / 执行异常| REPLAN[重新规划与步骤调整]
  REPLAN --> DECOMP
  DECOMP <-->|上下文注入 / 历史存储| MEM[长程记忆模块]
  MEM <-->|执行日志存储| VERIFY

  classDef men fill:#7FFFD4,stroke:#B0C4DE;
  class MEM men;

③ 垂类智能体（深度定制）

三个特征：领域知识深度融合、专用工具极致封装、场景化交互深度适配。
核心本质：场景优先的专用型智能体。
底层逻辑：场景定义规则，领域知识赋能，AI 在边界内精准执行。
代表产品：剪映智能剪辑、Figma AI、GitHub Copilot、阿里云智能客服、墨问 AI。

flowchart LR
  IN[领域特定输入] --> UI[领域专属交互层]
  UI --> PROMPT["领域 Prompt 工程 + 规则引擎"]
  PROMPT --> FT[领域微调 LLM / 大模型]
  FT --> TOOLS[领域专属工具集]
  TOOLS --> OUT[领域精准结果输出]
  KB[领域知识库 / 数据集] -->|知识注入| PROMPT
  KB -->|微调训练| FT

  classDef box fill:#F0FFF0,stroke:#334155,stroke-width:1px;
  classDef kb fill:#fff0f6,stroke:#c026d3;
  class IN,UI,PROMPT,FT,TOOLS,OUT box;
  class KB kb;

选型决策树

flowchart TD
  Q1[业务需求是否有明确、固定的执行流程?]
  Q1 -->|是，流程可标准化、可复用| Q2[是否需要严格的执行可控性、无风险?]
  Q1 -->|否，流程不固定、步骤动态变化| Q3[是否需要跨多场景的通用自主能力?]
  Q2 -->|是| A1[首选：Coze 类工作流智能体]
  Q2 -->|否，需要一定灵活性| Q3
  Q3 -->|是，目标明确但执行路径不确定| A2[首选：Manus 类通用智能体]
  Q3 -->|否，仅针对单一垂直领域的高频场景| A3[首选：垂类场景智能体]

  classDef decision fill:#EEF2FF,stroke:#334155,stroke-width:1px;
  classDef result fill:#FEF3C7,stroke:#B45309,stroke-width:1px;
  class Q1,Q2,Q3 decision;
  class A1,A2,A3 result;

4.5 前端视角的智能体四阶闭环

感知层：智能体的「眼睛和耳朵」，采集用户输入、系统环境状态、外部数据反馈——对应前端的事件监听、数据订阅、环境状态采集，是前端的传统优势阵地。
决策层：智能体的「大脑」，基于 LLM 内核，结合感知输入与记忆上下文，完成任务拆解、步骤规划、工具选择、异常处理——前端负责决策逻辑封装、Prompt 编排、边界校验规则。
行动层：智能体的「手脚」，执行指令：调用 API、操作文件、执行代码、控制系统指令——对应前端工具封装、接口调用、Node 脚本执行、系统 API 适配，是全栈能力的核心体现。
记忆层：智能体的「知识库」，存储会话上下文、执行历史、用户偏好、领域知识——对应前端状态管理、本地持久化、向量库交互，决定长程任务能力。

flowchart TD
  A[感知层 Perception] -->|输入采集与环境同步| B[决策层 Decision]
  B -->|生成执行指令| C[行动层 Action]
  C -->|目标达成输出| D[用户 / 业务系统]
  C -->|执行结果反馈| E[记忆层 Memory]
  E -->|上下文注入| B

  classDef layer fill:#f8f9fa,stroke:#333,stroke-width:1px;
  class A,B,C,D,E layer;

4.6 长链条任务的三个硬难点

任务拆解策略与边界判定：三种智能体在 Prompt 工程与工具链调用上的本质区别。
长链条 ReAct 的自修复循环与跨进程通信
- 用 LangGraph 实现具备「状态机」属性的复杂 Agent 逻辑。
- 难点：设计健壮的 Commander 系统指令集封装层，把 AI 的模糊意图精准翻译成操作系统可执行的原子指令（CLI / API）。
- 重点：长链条任务中环境保存 / 变更时，如何通过 Error-Reflexion（错误反射） 实现自动纠错与路径重规划，避免死循环。
多 Agent 协作协议的复杂业务闭环
- 类似 openclaw 系统级架构，核心是 Multi-Agent 协同中的通讯协议（SOP）与资源竞争管理。
- 企业落地：私有化知识库（RAG）与实时工具调用（Function Calling）的深度融合策略，解决大规模并发下的幻觉控制。

五、AI 应用开发框架

5.1 直接调模型会遇到什么（为什么要框架）

模型只具备「分析与推测」能力，Agent Loop 则是不断调用工具拿结果、再从结果学习优化的反复过程。直接开发会撞上七个问题：

多模型接入需要适配器（Model Provider）——微内核设计思想，用统一标准化协议完成模型接入。
工具定义与调用机制（tool calling）。
循环：ReAct 框架。
模型输出形态：字符串、流式。
调用远程他人的 tool 需要一套标准化规则，即 MCP。
大量提示词优化：上下文压缩（compact）、Skills（元数据 + 可执行操作）。
生态适配。

LangChain.js 对以上都做了封装，所以选它。

小 Demo 技术栈

TypeScript（类型完备）+ Node.js 经验：脚本测试 → 服务化（Express、Koa、Next.js、Nuxt.js、NestJS）。
本地模型部署：Ollama、MStudio、Whisper。
AI 引擎：LangChain.js、LangGraph.js、DeepAgent.js、Mastra、RAGFlow……
方法论：问题分析 → 方案设计（MVP，抓住主要矛盾）。

5.2 LangChain 标准化接口：如何避免供应商锁定

LangChain 通过 BaseLLM / ChatModel 等核心抽象定义标准化模型接口，抹平了 Ollama（@langchain/ollama）、OpenAI、云厂商模型在调用协议、参数格式、返回结构上的差异。

现在用本地 Ollama，将来切云端大模型，只需替换模型实例化逻辑（OllamaChatModel → ChatOpenAI），无需改动提示工程、工具调用（d3-dsv 解析、pg 交互）、Agent 编排等核心业务代码。
标准化接口还统一了错误处理、上下文管理、流式输出等通用逻辑。
结果：降低切换成本，并支持多供应商混合调用（核心场景用云端、低成本场景用本地），规避单一供应商的定价、稳定性、合规风险。

5.3 LangChain 与 LangGraph 的选型

选型锚定业务复杂度与流程特性：

场景	选择	理由
轻量：线性流程、单轮简单多轮交互（基于 pg 数据的问答、d3-dsv 解析结果返回）	LangChain 核心套件	`AgentExecutor`、`PromptTemplate` 等开箱即用，开发效率高，适配中小规模、无复杂状态管理的业务
复杂：非线性流程、多角色协作、状态持久化 / 容错重试（「拆分 → 入库 → 推理 → 纠错」闭环）	LangGraph	基于 LangChain 核心扩展，主打「有状态的推理图」，支持节点拆分、条件分支、循环执行，能精准描述状态流转，且可嵌套复用 LangChain 的工具与提示组件

5.4 可解耦、可演进的 Agent 分层架构

按 接口层 → 原子能力层 → 编排层 → 业务层 分层，每层职责单一、依赖倒置：

接口层：封装统一的模型调用（基于 @langchain/core 抽象）与工具调用接口，屏蔽底层差异（pg 数据库、d3-dsv 解析均封装为标准 Tool）。
原子能力层：拆分提示模板、文本拆分、数据解析、数据库交互等原子能力，用 Zod 做参数校验，确保可复用、可独立迭代。
编排层：轻量场景用 LangChain AgentExecutor，复杂场景用 LangGraph 构建状态图；只负责流程编排，不耦合具体业务逻辑。
业务层：对接 Express 接口、业务规则等具体场景，通过配置化关联编排层与核心能力；新增业务只扩展这一层，无需改动底层。

5.5 LangGraph 专家级内核（对标自研的六要素）

LangGraph 作为工业级 Agent 框架，核心竞争力在于一套完整的「图执行 + 状态管理」体系：

状态机驱动：基于有限状态机（FSM）与有向无环图（DAG），保障执行的确定性与可追溯性。
图执行引擎：支持节点的顺序、分支、并发、嵌套组合。
异步安全与竞态避免：确保多异步任务执行时状态一致，无脏数据覆盖。
状态持久化与 Checkpoint：执行快照、断点续跑、跨实例恢复，适配长周期任务。
子图与嵌套图：复杂流程拆为子图，提升复用性与可读性。
执行监控与调试：完整执行轨迹、日志与状态回溯，降低排障成本。

前置知识：图论的基本概念——节点与边、有向图。

参考 openclaw 的五层分层架构

openclaw 分层	落地实现（LangChain.js + Express）	核心职责
集成层	封装 Ollama 模型、流式传输协议	屏蔽底层模型调用差异，统一流式输出/输入规范，对接 LangChain 核心抽象
知识层	极简内存知识载体 + 文本拆分（最小化）	提供基础文本处理能力，预留 PG 扩展接口，暂用内存实现
工具层	标准化 DSV 解析工具（d3-dsv）	原子化工具封装，统一输入输出校验（Zod），适配 Agent 工具调用规范
Agent 编排层	核心 Agent Loop（工具调用 + 流式循环）	实现「思考 → 调工具 → 生成响应」闭环，处理流式回调与状态管理
UI 层	Express SSE 接口	暴露流式交互端点，模拟 UI 层输入/输出入口

这一骨架的三条核心逻辑

流式输出：基于 SSE，对接 LangChain 模型的 stream 方法。
Agent Loop：基于 AgentExecutor 封装，实现「用户输入 → 模型决策 → 工具调用 → 流式响应」的最小闭环。
最小可运行：只保留核心依赖，屏蔽非必要扩展（PG 暂不接入，仅预留接口）。

5.6 AI 应用的整体架构

flowchart TD
    subgraph 用户端
        A[前端应用 Next.js / Vue]
    end
    subgraph AI与数据基础设施
        B[BFF/API 层 Express.js / NestJS]
        C[AI 核心编排层 LangChain.js]
        D[模型服务 Ollama Server 运行 Qwen3]
        E[数据访问层 PostgreSQL / pgvector]
    end
    A -- HTTP / WebSocket --> B
    B --> C
    C -- 调用模型 --> D
    C -- 读写数据 / 向量 --> E

五步落地法

本地模型部署：Ollama + Qwen3。
LangChain 三件套：LangChain、LangSmith、LangGraph。
Node.js 把命令脚本化：提示词（Chat Mode）、RAG（向量存储：PGVector、Milvus）、Agent（工具）。
将 AI 应用服务化。
观测与治理：CI/CD、Docker、监控告警、安全、日志。

依赖清单参考

生产：langchain、@langchain/community、@langchain/core、@langchain/ollama、pg
开发：@types/node（对齐当前 Node 版本）、@types/pg、typescript

六、工作流与 AI 应用引擎架构

本章是全篇的架构核心：所有「AI 应用平台 / 低代码 / 扣子类产品」的骨架，都是编辑器 + 执行器 + 协议。

6.1 三种平台形态

形态	实现方式	示例
无代码平台	把多个 action 串联执行，即 action flow，在前端页面自动执行，也称内存型工作流 / 内存流程引擎	Glide
低代码平台	借助工作流编排，涉及触发器、代码执行器、数据查询器、循环节点等	Retool
AI 应用生成引擎	生成式 AI 应用引擎（在传统工作流上叠加 LLM、Agent、插件、知识库）	Coze、Dify

无代码：glide
低代码：retool
AI 应用生成引擎：coze
本地部署：Dify（见 §3.5）

流程引擎的本质：自动化管理和执行既定的业务流程，涵盖自动化处理、批处理、AI 生成详细过程。
三大核心功能：

工作流流程建模（编辑器）
任务调度：异步处理、前后依赖、变量上下文
集成外部系统、插件化构建流程功能生态

6.2 常见工作流类型

线性流（Sequential）：最简单的逻辑，节点按 A → B → C 顺序执行。
有向无环图（DAG）：AI Agent 最常见的形态，允许分支与回合，但严禁形成环路（会死循环）。
状态机驱动流（State Machine）：侧重状态流转（审批通过、驳回、待补件），每个节点是一个状态，连线即触发动作。

6.3 节点体系

核心节点

节点	作用	配置要点
start 节点	工作流起点，由外部事件或用户输入触发	字段类型（文本/段落/下拉/数字）、变量名称、显示名称、最大长度、是否必填
模型节点	调用生成式 AI 模型做生成或理解	选择模型与参数（温度、Top P、存在惩罚、频率惩罚、最大标记、回复格式、停止序列）、上下文、提示词、记忆（记忆窗口）、输出变量
知识检索节点（可选）	检索已有知识库	查询变量（自动带入 start 变量）、知识库（选一篇或一个文件夹）、输出变量
条件节点	分支控制	if 区域可加多个条件；else 区域直接显示描述词
代码执行节点	自定义逻辑	输入变量（初始两个「名 / 值」，可增删改）、代码编辑器（可直接使用输入变量）、输出变量（变量名 + 类型）
直接回答节点	相当于当前最后节点，但仍可继续下一步	回复文本域可拿到所有回复节点的字段
更多节点	模板转换、变量聚合器、参数提取器、迭代、问题分类器、HTTP 请求（可写入飞书多维表格等）	—

扩展节点类型（平台生态视角）

插件节点：调用外部插件完成集成型任务（天气查询、支付处理）。
业务逻辑节点：执行条件判断或复杂算法（如选择支付时触发支付流程）。
子工作流节点：把一个工作流嵌套进另一个工作流，支持递归调用，提升可重用性。
结束节点：所有任务执行完毕，返回最终结果。

交互细节：每个节点连接下一节点时，右键可拿到当前节点可连接的所有节点（即类型校验后的候选集）。

6.4 数据协议与 DSL

两大构成要素

节点（Node）：定义功能。
边（Edge）：定义来源（from / source）与目的（to / target），约束节点关系与流程。

DSL（Domain Specific Language） 领域特定语言，可与 AST（Abstract Syntax Tree） 结合使用。

假设有三个节点：触发器 trigger、新建标签页 newTab、滚动执行器 scroll，从左往右连接成有向无环图。

const dsl = {
  nodes: [
    { id: 'trigger1', type: 'common', data: { node_type: 'trigger' } },
    { id: 'newTab1',  type: 'common', data: { node_type: 'newTab' } },
    { id: 'scroll1',  type: 'common', data: { node_type: 'scroll' } },
  ],
  edges: [
    { id: 'edge1', source: 'trigger1', target: 'newTab1' },
    { id: 'edge2', source: 'newTab1',  target: 'scroll1' },
  ],
}

协议设计四要求：数据兜底、降级、扩展、升级。

6.5 编辑器技术选型

选型方向	代表库	优点	缺点	适用场景
原生 SVG	React-Flow / X6	矢量不失真，易用 CSS 控制样式，DOM 节点易绑事件	节点过多（数千）时有性能瓶颈	首选：中小型 AI 工作流、低代码平台
Canvas	LogicFlow / LiteGraph	性能上限极高，适合超大规模节点	开发成本高，节点交互需手算坐标（Hit Testing）	大型工业监控、超复杂逻辑链路
纯 DOM / HTML	自研	上手最快，可用原生拖拽 API	连线算法（SVG Line）极难写，维护成本高	简单的垂直线性审批流

面试建议：以 React-Flow 或 AntV X6 为切入点，强调其高度可定制的插件系统与成熟生态。

工作流开发的四个细节

数据结构定义 → 引擎数据协议设计（兜底、降级、拓展、升级）。
引擎实现：Canvas、SVG、自研框架三选一。
节点 / 边定义与灵活拓展 → 物料体系灵活接入，基于插件化 / 微内核机制（可对接远程插件市场、MCP）。
编辑器协同 + 执行引擎实现：协同用 CRDT / OT 解决冲突；执行要处理建图、遍历、异步、日志、错误收集。

6.6 执行器：内存型 vs 服务型

维度	内存型工作流（In-memory）	服务型工作流（Service-based）
执行环境	浏览器端或单个 Node.js 进程内存	分布式微服务集群
状态存储	随进程结束释放，瞬时性	数据库持久化（MySQL / Redis），支持断点续传
适用场景	前端低代码预览、轻量 AI 助手、单纯数据转换	复杂审批流（需人工参与）、长时耗任务、支付链路
核心挑战	内存溢出与性能：节点过多导致浏览器卡死	幂等性与重试：节点执行一半服务宕机如何恢复

内存型执行机制

顶层设计：典型的事件驱动模型。
运行逻辑：引擎把整个 Graph 加载进内存，通过递归或循环消费任务队列。
关键点：快照同步（每行执行完直接更新 UI 状态）、轻量化（无需考虑网络延迟，节点间数据传递用引用或简单 Copy）。

服务型执行机制

顶层设计：任务队列 + 状态机持久化（类似 Temporal、Camunda 的简化版）。
运行逻辑：
1. 任务解耦：引擎把待执行节点推入消息队列（RabbitMQ / Redis）。
2. Worker 消费：不同 Worker 认领任务并执行，结果写回数据库。
3. 状态脱水与复活：需要「人工审批」的节点，引擎把流程挂起（Wait），上下文脱水（Serialize）入库，触发后再复活（Hydrate）。
关键点：必须处理分布式事务与超时重试。

6.7 执行器实现：从最小闭环到生产可用

① 最小实现（内存型）

编辑器 + 执行器都在前端时，三步走：

约定流程协议（节点与边的 JSON 数据）。
编辑器编排工作流数据。
开发执行器：从前到后按序执行，后面的节点可以拿到前面节点的上下文，通过链表串联。

async function executeWorkflow(nodeId: string) {
  const node = getNode(nodeId) // 通过节点 ID 获取节点
  switch (node.type) {
    case 'API_CALL': {
      const response = await callAPI(node.endpoint, node.params)
      return response
    }
    case 'UI_UPDATE': {
      updateUI(node.data)
      // 如果需要对 node.data 里的节点再做处理，可以进一步按节点类型分发执行
      switch (node.data.type) {
        case 'COPY':
          navigator.clipboard.writeText('123')
          break
        case 'SEND_EMAIL':
          // 调用发邮件的 API
          break
        case 'NOTIFICATION':
          // 通知函数
          break
      }
      return 'UI updated'
    }
    default:
      return 'Node type not recognized'
  }
}

② 生产级三项增强

1）完全稳定可靠的日志系统（基于异步实现）
在每个节点执行前后记录：节点开始时间、输入与输出数据（敏感数据需加密或遮盖）、执行状态（成功 / 失败）、错误信息。

2）上下文变量池

在整个流程执行期间保持全局有效，存储所有必要的状态信息。
内容包括输入数据、计算结果、外部调用响应等。
每个节点执行时，执行器按需从池中取数据或更新数据。

3）错误处理机制

全局错误捕获：兜住所有未处理错误并记录相关信息。
节点级错误处理：每个节点可定义自己的错误策略，如 API 报错重试。
错误通知：关键节点出错时通知管理员或用户。
错误恢复：可恢复错误（如网络请求）设计重试机制。

6.8 平台级架构：以 Coze 为例

从「单体作坊」到「工业化生产线」
开源的 coze-studio 用 Docker Compose 把所有功能打包在一起，适合快速体验和中小团队；要支撑大型企业或公有云，必须转向云原生、微服务化架构。

设计理念：「一个中心，四大体系」

一个中心：AI 编排与执行引擎（AI Orchestration & Execution Engine）——平台心脏，负责解析和运行由节点（Nodes）与边（Edges）组成的业务流程图（Workflow DAG）。
四大体系：
- a. 应用构建体系：面向开发者，提供极致体验的前端编排界面、调试工具与版本管理。
- b. 插件生态体系：平台能力扩展的基石，通过标准化 SDK、市场和沙箱环境，赋能开发者贡献工具。
- c. 多租户与数据管理体系：企业级服务基座，负责用户、组织、权限、数据隔离与知识库向量管理。
- d. 可观测与运维体系：日志、监控、告警与成本分析。

微服务拆分（服务间推荐 gRPC 内部通信，API Gateway 统一对外提供 RESTful / GraphQL）

服务	职责	与 coze-studio 的对应关系
API 网关	所有外部请求的统一入口，负责鉴权、路由、限流、协议转换。选型：Kong、Traefik、Spring Cloud Gateway	—
用户与租户中心	用户、组织（租户）、角色权限（RBAC），登录注册、SSO 单点登录	coze-studio 只有简单的用户概念，需增强为企业级多租户模型
Bot 配置中心	核心 CRUD：Bot 的创建/读取/更新/删除，含人设（Prompt）、插件配置、工作流静态定义（通常是一个大 JSON）	coze-server 中处理数据库交互的大部分逻辑
插件市场服务	插件生命周期：注册、审核、发布、版本控制与发现；存插件元信息（manifest：名称、描述、输入输出 schema）	—
数据与向量管理服务	解耦底层数据库，对上层提供统一数据访问；内部封装 PostgreSQL（业务）与 PGVector / Milvus（向量）；负责知识库文档的切分、向量化、存储	—
AI 编排与执行引擎	无状态计算服务：接收 Bot 配置中心传来的工作流 DAG，负责实时执行、状态追踪与结果返回。性能与稳定性的关键	—

6.9 前端编排 + 后端执行的关键难点

前端编排引擎：本质是一个面向 AI 工作流的、可视化的 DAG 编辑器。

状态管理与交互：用户拖拽节点（工具、LLM、判断逻辑）并连线，实时构建复杂图结构。需要强大的状态管理方案（Redux Toolkit、Zustand）维护完整数据结构——每个节点的位置、配置与连接关系。
图结构序列化：点击「调试」或「发布」时，前端必须把可视化图序列化成后端执行引擎能理解的标准 JSON，描述拓扑结构与每个节点的具体参数。
实时调试反馈：调试模式下后端逐节点执行时，前端要实时高亮当前节点并显示输入输出。这要求前后端建立长连接（WebSocket 或 SSE），由后端主动推送执行状态与日志。

后端流式节点执行引擎：整个架构的「技术之巅」。用 for 循环按序执行是天真实现，低效且无法处理流式输出。工业级引擎必须解决：

DAG 解析与执行调度：拿到工作流 JSON 后先做拓扑排序，确定执行顺序，并识别可并行执行的分支。
异步非阻塞 I/O：几乎所有节点（调 LLM、调 API、查数据库）都是 I/O 密集型，引擎必须完全异步非阻塞（Node.js 事件循环，或 Go 协程）。
流式处理（Streaming）：LLM 节点不能等全部生成完再返回。
- 调用大模型时明确要求流式返回（如 OpenAI API 的 stream: true）。
- 引擎收到的是数据流而非完整响应。
- 通过 WebSocket / SSE 把每个数据块（token）实时转发给前端，实现打字机效果。
- 同时把数据块拼接成完整输出，作为下一节点的输入。
安全沙箱（Sandbox）：执行社区开发者贡献的代码片段或插件时，绝不能在主服务直接运行。
- 方案一（重隔离）：为每个任务动态启动轻量 Docker 容器，隔离最好但冷启动慢。
- 方案二（轻隔离）：WebAssembly（WASM），启动极快、安全性高，是很有前景的方向。

工程化闭环五步：① 定义 DSL → ② 编辑层（状态管理 + 插件化架构）→ ③ 执行器（拓扑排序与动态调度、沙箱隔离）→ ④ AI 特化设计（变量提取与上下文流转、流式输出）→ ⑤ 测试与工程化闭环。

6.10 沙箱的两层理解

记忆方式：通过费曼学习法，记住一个，根据另一个进行推导。
微前端沙箱（如 qiankun 的三种 sandbox）：legacy sandbox、proxy sandbox、snapshot sandbox，目的在样式隔离、JS 隔离。
系统级沙箱：目的是系统环境隔离，保证执行安全性。deepagent 涉及文件操作、bash 执行、shell 提权，必须做隔离。
服务端隔离强度排序：Docker 容器（强隔离、冷启动慢）→ WASM（轻隔离、启动快）→ vm2 / isolated-vm（进程内隔离，性能好但需谨慎使用）。

七、协同编辑

协同系统的中级目标是维护多方数据的一致性。
本文只关注上层的数据同步与冲突处理；下层传输与持久化不是重点，可用 WebSocket 或其他方案替代。
编辑器内核选型：重量级代码编辑器（VS Code、Trae）用 Monaco Editor，其余多选 TipTap。

7.1 协同场景盘点

产品形态	协同数据特征	技术组合
协同文档（飞书文档、Notion）	带格式的、流式文本内容	TipTap（视图层）+ Yjs（数据模型）+ y-websocket（通信层）
协同代码编辑器（VS Code、Trae）	纯文本，对性能、语法高亮、开发体验要求极高	CodeMirror + Yjs + y-codemirror.next + y-websocket
可视化图表编辑器	结构化图表配置	智能协同可视化编辑引擎
在线白板（博思白板、飞书画板）	画布元素、层级、位置	画布引擎 + CRDT
协同视频编辑器（剪映）	时间轴轨道、片段属性	时间轴模型 + CRDT
多维表格（飞书云表格）	单元格、行列结构、公式	类 Skia/Canvas 渲染 + CRDT + 公式引擎
数字孪生低代码（DataWind）	组件树、场景图、节点属性	Vue3 + WebAssembly + VanillaJS
协同 AI 应用引擎（扣子）	DAG 节点与边、配置	图协议 + CRDT

7.2 编辑器内核与格式化实现的三种路线

竞品参考

飞书文档、Notion：丰富的文本格式、多媒体嵌入、实时协作；可用快捷命令（/、@）快速插入不同类型的块（Block）。
Google Docs、Word Online：复杂文档编辑能力——文本格式化、插图、撤销重做、表格与绘图。
Quill、Draft.js：开源富文本编辑器，可二次开发自定义方案，支持插件扩展与丰富 API。

文档编辑的核心清单
基础编辑、文本格式化、多媒体插入（图片、视频、@提及、引用跳转）、undo/redo（含 Ctrl+Z）、跨浏览器兼容、协作（协同）、AI 赋能。

① contenteditable 属性
在任意容器上设置该属性即可变为可编辑容器；可编辑容器内也可内嵌多个容器，不想编辑的部分设为 contenteditable="false"。

② 路线一：浏览器 execCommand（小白级，过时 / 即将废弃）

document.execCommand 是浏览器 API，用于在 HTML 文档中执行与内容相关的命令。
缺点：兼容性差、可维护性差。

③ 路线二：Selection + Range + Compiler（大神级）

单独用 selection（获取当前选中内容）+ range（精确操作选中内容）时会发现：每点击一下就被新的标签包裹。Compiler 负责切换——判断当前内容是否已有修饰标签，是则还原，否则添加修饰。
大部分编辑器都提供编译器：Markdown / MDX 有 hyper，TipTap 类基于 JSONContent 结构。取舍：
1. 基于 Markdown：性能更好、约束更强。
2. 基于 JSONContent：特性更灵活，自定义节点更便捷（如 TipTap custom node）。
内容 → 可存储格式 → 再解析回来：实现 JSON 与 HTML 双向转换，可参考 html2json。
- HTML 转 JSON：递归遍历 DOM 元素，构建结构化 JSON。
- JSON 转 HTML：从 JSON 数据生成 HTML 字符串，支持富文本格式。

④ 通用数据协议
用 Schema / DSL / 协议数据承载整个应用的物料体系，参考 BlockSuite。

7.3 个性化需求：@ 提及与 / 命令补全

document.querySelector('.editor-content').addEventListener('input', function (e) {
  const inputText = (e.target as HTMLElement).innerText

  if (inputText.endsWith('/')) {
    showCommandMenu(e.target)
  }
  if (inputText.endsWith('@')) {
    showMentionMenu(e.target)
  }
})

function showCommandMenu(target: EventTarget | null) {
  console.log('显示命令菜单')
}

function showMentionMenu(target: EventTarget | null) {
  console.log('显示提及菜单')
}

其他常见个性化能力

协同光标：前端用 WebSocket 实时通信，每个客户端收发光标位置与编辑内容；后端 WebSocket 服务器接收消息并广播给其他客户端，保证编辑状态一致。其他方案：Yjs 等。
知识图谱：graph、d3 forceGraph（力导向图）。
历史记录栈与 Undo/Redo：用命令模式 + 历史栈管理用户操作，把命令对象压栈；撤销时弹出最后一个命令对象并调用 undo，重做时调用 redo。
跨浏览器兼容：不同浏览器对 Range/Selection 的实现差异，是编辑器落地的主要坑之一。

7.4 协同架构：协议先行

协同前置，协议先行。

① 传输协议：WS、Socket.IO（下层也可用 WebRTC）。

② 协同数据分两类

交互式数据（业务无关）：头像、光标位置。
核心业务数据：文档内容、图结构、单元格数据。

③ 数据冲突与两大理论

OT（Operation Transformation，操作转换）：Google Docs、Etherpad 使用。集中式，强依赖中心服务器。
CRDT（Conflict-free Replicated Data Type，无冲突复制数据类型）：分布式友好，天然支持 P2P 与离线编辑。
- 进一步分类：面向状态的（state-based）、面向操作的（op-based）。

④ 协同方案对比

Yjs：基于 CRDT，支持实时同步与冲突处理，生态最成熟。
Automerge：偏 OT 思路，支持同步与冲突处理，但实时编辑体验较弱。
附录：CRDT 论文及实现方案

⑤ 服务层与存储

服务层：Node、NestJS、Redis、Kafka + ClickHouse（数据量大时使用）。
数据库：PostgreSQL（AI 向量化用 pgvector）。

⑥ OT 的工作原理

sequenceDiagram
    participant A as 客户端A
    participant S as 中心服务器
    participant B as 客户端B

    A->>S: 发送操作 OpA (基于 V1)
    Note over S: 校验版本, 执行 OpA, 版本变为 V2
    S-->>A: 确认 OpA
    S-->>B: 广播 OpA

    B->>S: 发送操作 OpC (基于 V1)
    Note over S: 冲突! 当前为 V2, 收到基于 V1 的 OpC
    Note over S: 转换操作: OpC' = Transform(OpC, OpA)
    Note over S: 执行 OpC', 版本变为 V3
    S-->>B: 确认 OpC'
    S-->>A: 广播 OpC'

⑦ CRDT 的工作流程

sequenceDiagram
    participant A as 客户端A (CRDT)
    participant S as 消息中继服务器 (可选)
    participant B as 客户端B (CRDT)

    Note over A: 用户插入 X, 生成 UpdateA
    A->>S: 发送 UpdateA
    S->>B: 转发 UpdateA
    Note over B: 应用 UpdateA, 与本地状态合并

    Note over B: 与此同时，用户插入 Y, 生成 UpdateB
    B->>S: 发送 UpdateB
    S->>A: 转发 UpdateB
    Note over A: 应用 UpdateB, 与本地状态合并

    Note over A,B: 最终 A 和 B 的文档状态完全一致

⑧ 架构师决策：OT vs CRDT

特性	OT	CRDT
核心思想	转换操作以适应上下文	设计可自动合并的数据结构
复杂度	实现极度复杂，尤其在转换函数	理论相对简单，实现门槛低
架构	强依赖中心化、有状态的服务器	天然支持去中心化、P2P、离线编辑
服务端	逻辑重，是系统核心	逻辑轻，通常是无状态的消息中转
性能	理论上元数据开销小	理论上元数据开销大（Yjs 已高度优化）
生态	Google Docs、Zoho、Etherpad	Yjs、Figma、Apple Notes、Automerge

结论：首选 CRDT。 OT 虽然强大，但在追求敏捷开发、高可用性和优秀离线体验的今天，已显得有些不合时宜。

7.5 Yjs 实战

① 协同原理

flowchart TB
    subgraph ClientA["Client A"]
        TA[TipTap Editor] --> YA[Y.Doc]
        YA --> WA[Websocket Provider]
    end
    subgraph ClientB["Client B"]
        TB[TipTap Editor] --> YB[Y.Doc]
        YB --> WB[Websocket Provider]
    end
    subgraph Backend["Backend Server"]
        NS[Node.js + WebSocket]
        PL{Persistence Layer}
        DB[(Database)]
        NS -->|Periodically saves| PL
        PL --> DB
    end
    WA <-->|WebSocket| NS
    NS -->|Broadcasts updates| WA
    NS -->|Broadcasts updates| WB
    WB <-->|WebSocket| NS

② Yjs 的五个重要特性

核心数据结构：Item 与双向链表。
全局唯一 ID + 逻辑时钟。
冲突解决：确定性排序规则。
删除即标记（Tombstones）。
性能优化：Struct 与高效二进制编码。

③ CRDT 的优缺点

优点：
- 实现简单：相比 OT，核心逻辑更简单，无需编写复杂转换函数。
- 天生去中心化：完美支持 P2P 与离线编辑，离线修改联网后无冲突合并。
- 服务端逻辑轻：通常只扮演无状态的消息中转站。
缺点：
- 元数据开销：为保证可合并性需存额外元数据，理论上比 OT 占更多内存（Yjs 已做大量优化）。
- 意图保留问题：极端场景无法完美保留「真实意图」——「剪切一段文本再粘贴到别处」会被看作「删除一串字符」+「插入一串字符」。绝大多数场景不构成问题。

④ 最小可运行代码（文档协同）

前端主页面：

import React, { ChangeEvent, useEffect, useState } from "react"
import * as Y from "yjs"
import { WebsocketProvider } from "y-websocket"

// 要实现无冲突数据，需要借助 Yjs 存储数据并处理冲突
const doc = new Y.Doc()
// 传输与协同：new WebsocketProvider(地址, 房间名, 绑定的 doc)
const provider = new WebsocketProvider('ws://localhost:1234', "collaborate-editor", doc)

provider.awareness.on('change', () => {
  // 可获取头像、光标的变化
})

const yText = doc.getText("content")

export const CollaborateEditor = () => {
  const [content, setContent] = useState('')

  useEffect(() => {
    provider.on('status', (event: unknown) => {
      console.log('状态：', event)
    })
    provider.on('sync', (isSynced: boolean) => {
      console.log('同步：', isSynced)
      setContent(yText.toString())
    })
  }, [])

  const handleChange = (ev: ChangeEvent<HTMLTextAreaElement>) => {
    const val = ev.target.value
    setContent(val)

    // 先删后追加
    yText.delete(0, yText.length)
    yText.insert(0, val) // 关键在光标的位置
  }

  return <textarea value={content} onChange={handleChange} />
  /**
   * 编辑器部分选型说明：
   * 1. 单纯用 contenteditable 实现富文本编辑，需要自己维护数据缓冲区（没有 onChange）
   * 2. 用 textarea，可直接从 onChange 拿到用户输入
   */
}

后端服务：

// dependencies: ws 与 y-websocket
import { WebSocketServer } from 'ws'
import { setupWSConnection } from 'y-websocket/bin/utils'

const PORT = 1234
const wss = new WebSocketServer({ port: PORT })

wss.on('connection', (ws) => {
  setupWSConnection(ws, wss)
})

console.log("yjs-docs-server is running on port", PORT)

⑤ 结构化数据的承载方式

// 基于 JSON 描述的 Block 数据结构
const blocks = [
  {
    type: 'heading',
    level: 1,
    content: 'Welcome to Feishu Docs',
  },
  {
    type: 'paragraph',
    content: [{ type: 'text', text: '这是一个段落' }],
  },
  {
    type: 'code',
    content: [{ type: 'text', text: 'console.log("hello world")' }],
  },
  {
    type: 'list',
    items: [{ type: 'text', text: 'Rich text' }],
  },
]

存入 Yjs Doc 时的类型选择：

复杂数据：Y.Array、Y.XmlFragment
富文本：Y.XmlElement、Y.XmlFragment
常用按需：Y.Text、Y.Array、Y.Map

⑥ 协同文档落地五步

平台数据协议统一。
存储到 Yjs Doc。
增量数据变化 → 同步。
传输：WS、Socket.IO、WebRTC。
协同双通道：光标/头像（awareness）+ 内容数据（document）。

⑦ TipTap 协同依赖清单

依赖	作用
`@tiptap/react`	TipTap 的 React 组件：渲染、事件处理
`@tiptap/core`	核心：节点 Node、修饰（加粗/斜体/下划线/删除线）Mark、命令
`@tiptap/starter-kit`	默认配置：节点、修饰、命令
`@tiptap/extension-collaboration`	绑定层：把 TipTap 内部的 ProseMirror 文档模型与 Yjs 的 `Y.Doc` 绑定
`@tiptap/extension-collaboration-cursor`	光标协同：位置、移动
`yjs`	CRDT 数据模型
`y-websocket`	Yjs 的 WebSocket 传输层

接入四步：① 创建 Y.Doc 代表整个协同文档数据 → ② 通过 Collaboration 扩展绑定编辑器状态与 Y.Doc → ③ 实现实时通信 → ④ 光标同步（Awareness）→ ⑤ 后端实现。

7.6 多端协同架构对照

文档编辑器（飞书文档）：核心是处理带格式的、流式的文本内容。
TipTap（视图层）+ Yjs（数据模型）+ y-websocket（通信层）

代码编辑器（VS Code、Trae）：核心是处理纯文本，对性能、语法高亮、开发体验要求极高。
CodeMirror（视图层）+ Yjs（数据模型）+ y-codemirror.next（绑定层）+ y-websocket（通信层）

数字孪生低代码平台（DataWind）：核心是结构化数据（组件树、场景图、节点属性）。
Vue3 + WebAssembly + VanillaJS

关键技术要素：IoT、AI、GIS、BIM；掌握用户故事映射等需求分析方法。
三维核心资产辨析：掌握 glTF/GLB、FBX 等主流格式的特性和适用场景；理解 PBR 材质原理与纹理贴图（漫反射、法线、金属度、粗糙度、环境遮蔽）的作用；理解 LOD 对性能优化的意义；能设计并实施从三维数据采集、处理、优化到发布的全流程；针对大规模高精度场景（含模型与地理影像）制定综合性能优化策略，熟练运用 LOD、Draco 压缩、UV 优化等手段。
编排引擎设计：独立设计低代码编排引擎的核心数据模型 DSL 与交互逻辑，具备设计与实现事件驱动、逻辑触发机制的能力。
三种设计模式：观察者模式、策略模式、工厂模式。
核心算法：智能吸附与网格吸附。

数字孪生的四个重难点

重难点	具体表现	解决思路
坐标系统与变换	多层级坐标变换、缩放因子、边界约束	统一坐标系管理、缩放因子正确应用、边界检查与约束处理
吸附算法	大量元素时的性能	阈值过滤减少计算、空间分割优化邻近元素查找、缓存计算结果
状态同步与一致性	Vue 响应式系统与引擎状态双向同步	单向数据流设计、事件驱动的状态更新、防抖避免频繁更新
内存管理与性能	大量元素的渲染与内存占用	虚拟滚动、事件监听器正确清理、对象池复用减少 GC 压力

八、服务端渲染与前后端同构

8.1 演进脉络

时期	形态	代表
初期	传统服务端渲染	EJS、JSP
中期	SPA 单页应用	React / Vue 客户端渲染
后期	SSR 与 SPA 结合	Next.js、Nuxt.js

答题技巧：遇到「了解过 XX 吗」这类问题，先抓重点（服务端渲染），再讲技术背景，最后讲核心设计思想。
背景要从大点到小点（含优化），避免同质化。可按时间维度（初期/中期/后期）或空间维度（广度）展开。

8.2 SSR / SSG / 前后端同构

方案	概念	特性
SSR	在服务端处理数据并生成完整 HTML 页面返回客户端，React / Vue 接管渲染	极致首屏优化、SEO 支持（sitemap）、交互性（内容渲染提前，事件绑定随后完成）
SSG	渲染工作大部分不依赖服务端，直接生成静态站点文件（网页静态技术）	高性能、SEO 优势、适合内容不频繁变动的场景（秒杀活动、抢购页）
前后端同构	定制化地把前端与后端开发工作流合并，完全统一的规范与管理模式	统一开发体验、SEO 与性能优化

SSR 全链路

flowchart TD
    A[用户请求页面] --> B[服务器查找对应组件]
    B --> C[服务器渲染页面生成 HTML]
    C --> D[服务器返回 HTML 到浏览器]
    D --> E[浏览器加载 JS 文件]
    E --> F[水合过程：绑定事件，恢复交互]
    F --> G[页面完全可交互]

8.3 为什么 AI 产品首选 SSR

AI 产品的特殊性

追求短平快（全栈）：一套框架同时解决页面与接口。
隐私和安全：
- 数据以 JSON 请求暴露在浏览器，只要拿到 token，就能在任何位置频繁调用你的接口。
- 很多第三方服务（OpenAI 等）的 token 若放前端会直接泄露。
动态响应与个性化：需要按用户、按会话动态生成内容。

SSR 的三点优势

用户体验（首屏更快）
减轻客户端压力
降低维护成本

典型的 AI 项目形态：Dify、Coze 类 AI 应用开发平台（Prompt、RAG、知识库、模型部署与接入、流程编排、function calling、MCP 接入，以及企业级模型调优 / 数据集 / 训练）；v0、bolt 等 AI 生成类产品。

8.4 Next.js 实战

① 创建项目

1	npx create-next-app@latest

关注路由：早期主要用 Pages Router，现在用 App Router。App Router 支持模块化、组件化，并在预渲染、服务端优先水合、布局与路由的服务端优先上做了架构优化。
创建过程中：TS、ESLint、App Router、Turbopack 必选；TailwindCSS、src/ 目录、路径别名按需。
约定式路由：按文件目录结构创建文件，浏览器输入对应 URL 即可进入，无需配置 router。如在 home 文件夹下放 page.tsx，访问 localhost:3000/home 即可。

② 请求流程（五步）

用户请求页面，Next.js 处理请求。
服务端渲染：根据请求渲染出 HTML（getServerSideProps 获取动态数据）。
返回 HTML：用户看到浏览器初步渲染结果。
React 水合（Hydration）：React 在客户端接管已渲染的 HTML，把静态 HTML 转为动态应用。
前端渲染：页面变为完整的 React 应用，用户可交互，React 接管后续界面更新与数据处理。

flowchart TD
   A[用户请求页面] --> B[服务端渲染 SSR]
   B --> C[获取数据 getServerSideProps]
   C --> B
   B --> D[返回 HTML 给客户端]
   D --> E[React 水合 Hydration]
   E --> F[用户交互]
   F --> G[前端渲染]
   G --> E

③ App Router 的关键约束

新的架构下 Server Component 优先：React Hook 只能用在客户端组件，不能用在服务端组件。
客户端组件：文件顶部加 "use client"。
服务端组件：默认即是。

④ 动态路由

user
├── page.tsx
└── [id]        // 动态路由
    └── page.tsx

访问 localhost:3000/user 或 localhost:3000/user/1。

// app/user/[id]/page.tsx
"use client"
import { useSearchParams, usePathname, useParams } from "next/navigation"

export default function UserDetail() {
  const searchParams = useSearchParams()
  const pathname = usePathname()
  const params = useParams()
  const id = searchParams.get("id") ?? params.id
  return <div>用户详情页，{String(id)}</div>
}

// app/user/page.tsx
export default function User() {
  return <div>用户列表页</div>
}

⑤ 编写 API

在 app 目录下创建 api 文件夹，文件名用 route.ts。

// app/api/route.ts
export async function GET(request: Request) {
  // 调用 OpenAI API
  // 操作数据库
  // 文件操作
  return Response.json({ message: "Hello World" })
}

export async function HEAD(request: Request) {}
export async function POST(request: Request) {}
export async function PUT(request: Request) {}
export async function DELETE(request: Request) {}
export async function PATCH(request: Request) {}
export async function OPTIONS(request: Request) {}

// 客户端使用：在 useEffect 中调用
// fetch("/api").then(res => res.json()).then(res => console.log(res))

Pages Router 的写法是 export default function handler(req, res)；App Router 改为按 HTTP 方法导出具名函数。

8.5 从零自研一套 SSR 体系

① API 结构四要素

React 水合 / renderToString
路由系统
状态同步
样式提取

② 设计时考虑的四个方面

路由设计与管理：需要一个简单的路由系统把 URL 映射到对应 React 组件。
SSR 与 SSG 的选择：按页面内容变化频率与 SEO 需求决定。
数据获取与传递：SSR 模式下数据可在服务端直接获取后传给组件；客户端可通过 getInitialProps 或 useEffect 加载。
客户端与服务端的水合：客户端拿到服务端渲染的 HTML 后执行水合，恢复组件状态并绑定事件。

③ 技术要点

技术	角色
Vite	现代构建工具，快速开发构建与 HMR，可与 SSR 构建良好集成
React	UI 构建框架
Express	轻量 Web 服务器，处理请求与响应，提供 SSR 所需 API
`ReactDOMServer.renderToString`	把 React 组件渲染成 HTML 字符串
`ReactDOM.hydrate`	在客户端接管服务端渲染页面，完成水合

④ 老 SPA 重构为 SSR 的实践路径

先做路由收敛：把散落的页面入口统一到约定式路由表。
抽数据预取层：把各页面原本在 useEffect 里的请求上移到服务端数据获取函数。
处理样式提取：服务端渲染时同步收集 CSS，避免首屏闪样式。
处理状态同步：把服务端数据序列化注入 HTML，客户端水合时复用，避免二次请求。
灰度切流：按路由维度逐步切换，而不是一次性全量。

参考实现：miaoma-tiny-ssr（手写一个类 Next 框架），可配合视频教程逐步跟做。

九、前端监控与可观测

一条完整的监控链路 = 采集 → 上报 → 接入缓冲 → 流式计算 → 存储 → 可视化 / 预警 → AI 化。

9.1 指标体系

性能指标

指标	全称	含义
PLT	Page Load Time	首页加载时间：导航开始到最终整屏内容加载完成
FP	First Paint	首次绘制
FCP	First Contentful Paint	首次内容绘制：第一个内容绘制的时间
FMP	First Meaningful Paint	首次有意义绘制：指标因产品而异，已被 LCP 取代
LCP	Largest Contentful Paint	最大内容绘制时间
TTI	Time To Interactive	可交互时间
CLS	Cumulative Layout Shift	视觉稳定性：加载时内容意外跳动的总分，≤0.1 为良好
INP	Interaction to Next Paint	交互响应速度：从点击 / 触摸 / 键盘输入到浏览器完成下一帧渲染的耗时（ms）

采集来源：Performance API、web-vitals 库、自定义指标计算。

异常指标

JS 运行时异常
Promise 未处理拒绝（unhandled rejection）
资源加载异常
接口请求异常
框架层异常：React 执行异常、Vue 执行异常

用户行为

新老用户判定：给 Cookie 加一个变量标记。
页面浏览量（PV）、独立访客数（UV）、点击 / 操作事件、停留时间。

工程化流程指标

构建时间
缓存利用率

9.2 采集与上报策略

上报通道

fetch / XHR：可能出现跨域，日志系统通过 CORS 解决（常规数据的首选）。
图片打点：new Image().src = url，天然跨域、不阻塞。
Navigator.sendBeacon：页面卸载时可靠发送。

分级上报策略（兼顾实时性与页面性能）

常规数据（AJAX / Fetch）：非阻塞日志，利用 HTTP/2 多路复用特性，用 fetch 批量上报。
高可靠数据（sendBeacon）：页面加载、可见性变化等关键节点埋点，确保页面关闭后数据仍能送达，解决「数据丢失」痛点。
实时交互（WebSocket）：需要双向通信或极低延迟的场景（协同编辑监控、实时热力图），建长连接。

9.3 全链路架构

话术（面试可直接背）

我主导并落地了一套端到端的全链路监控平台，覆盖从前端 SDK 无感采集（性能、异常、用户行为三类指标）、高吞吐消息队列缓冲、流式计算清洗，直到 OLAP 数据库（ClickHouse）落库与可视化的完整数据生命周期。

五段链路

端侧采集：自研埋点 SDK，sendBeacon + XHR 分级上报。
接入与缓冲：Nginx 负载均衡 → Node.js 网关 → Kafka 削峰填谷。
流式计算：Flink / Spark 实时清洗与聚合。
存储引擎：ClickHouse 列式存储，海量数据毫秒级查询。
数据应用：实时大屏 + 智能预警 + AI 根因分析。

接入层：高可用网关

Nginx：反向代理与负载均衡，承载海量并发，做 SSL 卸载与初步流量清洗。
Node.js（NestJS）：BFF / 接入服务，负责鉴权、数据格式校验，然后迅速把数据「甩」给 Kafka，不做耗时逻辑，保证接口 ms 级响应。

缓冲层：Kafka

架构决策：引入 Kafka 是为了解耦「生产」与「消费」的速度不匹配，实现流量削峰。

Topic 设计：按数据热度与结构拆分，如 topic_error_log（低频、高价值）、topic_performance（高频、海量）。
Partition 策略：按 session_id 或 user_id 做 Hash 分区，保证同一用户行为落在同一分区，从而保证时序性。

// Node.js Producer 示例
const { Kafka } = require('kafkajs')
const kafka = new Kafka({ brokers: ['kafka-broker:9092'] })
const producer = kafka.producer()

await producer.connect()
await producer.send({
  topic: 'monitoring-events',
  messages: [
    { key: event.user.session_id, value: JSON.stringify(eventData) },
  ],
})

9.4 存储层：ClickHouse

为什么是 ClickHouse：监控数据具有「写多读少、按时间查询、海量数据聚合」的特征。

写入性能：支持高吞吐批量写入。
查询性能：列式存储 + 向量化执行引擎，亿级数据聚合（Group By）秒级完成。
数据压缩：极高压缩比，节省大量存储成本。

CREATE TABLE monitoring_db.events
(
    `event_type` LowCardinality(String), -- 优化枚举值存储
    `timestamp`  DateTime,
    `user_id`    String,
    `session_id` String,
    `url`        String,
    `meta_data`  Map(String, String)     -- 灵活存储扩展字段
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(timestamp)         -- 按月分区，便于冷热数据管理
ORDER BY (event_type, timestamp)
TTL timestamp + INTERVAL 3 MONTH;        -- 数据生命周期，自动清理

写入优化铁律：千万不要单条插入。在 Consumer 层维护内存 Buffer，满足「数量达到 5000 条」或「时间间隔达到 5 秒」任一条件即批量 INSERT，最大限度减少 IO 开销。

9.5 可视化与智能预警

数据可视化
前端管理后台直连 ClickHouse（或经中间层 API），用 ECharts 渲染大屏：

趋势分析：按 toStartOfMinute(timestamp) 聚合，展示 PV / UV 曲线。
性能分布：用 quantile 函数计算 TP50、TP90、TP99。

多级预警

离线报警：CronJob 每分钟轮询 ClickHouse，对比昨日同比数据，波动超过 20% 触发邮件。
实时报警：在 Flink 流处理阶段直接对接 IM 机器人（飞书），捕获 FATAL 级错误立即把堆栈推送到研发群，实现秒级感知。

9.6 AI 化：从根因分析到自动修复

让 AI 懂你的团队：投喂开发规范、开发流程，让模型理解项目上下文。
精调模型：针对监控场景做微调。
RAG：把历史故障、值班手册、变更记录做成知识库，供根因分析检索。
多模态输入：用 rrweb 录屏、截图上传；凡需通过截图/录制分析的场景，都要按多模态（文本 + 图片 + 视频）设计。本地调试可用 Ollama + qwen3-vl:2b。
进一步：Code Agent（Vibe Coding）
- 根因定位后自动修复，自动提 PR。

十、工程化与架构

10.1 Monorepo：定义与四个核心特点

Monorepo（Monolithic Repository，单一代码仓库）

一种软件开发架构策略。
核心逻辑：把多个项目（Projects）、多个软件包（Packages）和公共组件库，全部放在同一个 Git 仓库中统一管理。
通俗说法：前端、后端、服务端、自定义工具插件都在同一个文件夹下，通过 pnpm-workspace.yaml 定义 packages，彼此可互相安装、独立运行，但只提交一个 Git 仓库。

特点	深度解读
单一仓库（One Repo）	所有代码资产在一个 Git 历史中，一次 `git clone` 拿到组织工程全貌
多项目共存（Multi-Project）	仓库内用文件夹隔离不同业务应用与基础设施
统一依赖管理（Shared Dependencies）	所有项目共用一套基础依赖（React、TS、Jest），升级时同步升级，避免版本割裂
原子化提交（Atomic Commits）	一个需求同时改「后端 API」和「前端调用」时，可在同一个 commit 中提交，保证逻辑完整

Monorepo 解决的四个痛点

代码复用性瓶颈 → 增强复用
依赖管理复杂化 → 更友好的依赖管理
跨项目原子性缺失 → 保证代码审查、持续集成与发布的一致性
工程规范分散化 → 团队规范化、流程化、自动化

10.2 Polyrepo vs Monorepo

以「repo-frontend 需要 repo-utils」为例，Polyrepo 的做法是：改 repo-utils 代码 → 发布 npm 包（npm publish）→ repo-frontend 执行 npm i 安装。有 bug 就重复上述流程，调试极难。

维度	Polyrepo	Monorepo
代码复用	困难：复制粘贴或发私有 npm 包	容易：本地物理路径引用，修改即生效
依赖管理	分散：各仓库各自维护 package.json，版本参差	统一：根目录控制核心版本，消除「依赖地狱」
开发流程	繁琐：跨库开发需 link 或发包	顺畅：无需发包，保存即热更新
工程配置	重复：每个仓库都配一遍 ESLint、Jest、CI	复用：根目录定义一套规范，所有子包继承

典型例子：Google、Vue 3、React；字节、美团、阿里的中台业务线与组件库。

10.3 包管理器对比

特性	pnpm ⭐	Yarn (v1 / Berry)	npm
磁盘占用	极低（Content-addressable）	高（复制多份）	高（复制多份）
安装速度	极快	快	慢
幽灵依赖	严格禁止（安全）	宽松	存在隐患
Workspace 支持	原生且配置简单	支持	基础支持

① 磁盘机制（硬链接）

npm / yarn：有几个项目就复制几份依赖到各自的 node_modules。
pnpm：用**硬链接（Hard Link）**只下载一份到磁盘全局，其他项目全部指向它。
硬链接特点：同一个文件多个入口，修改任意一个全部生效；删除其中一个链接，原文件仍在。

② 幽灵依赖（Phantom Dependencies）

现象：A 依赖 B，B 依赖 C。在项目 A 中直接使用 C 不会报错，但 package.json 里没写 C。
危害：若 B 后续不再依赖 C，代码立刻报错。
pnpm 的解法：通过非扁平化的 node_modules 结构，物理层面彻底屏蔽幽灵依赖。

10.4 构建编排工具

工具	简介	优势	劣势	推荐场景
Lerna	老牌霸主，已被 Nx 收购	擅长版本管理与 npm 发包	构建性能差，缺乏任务缓存	纯 npm 库维护
Nx	功能最全的企业级框架	极强，插件丰富，支持分布式计算	配置复杂，侵入性强，学习曲线陡	超大型全栈团队
Turborepo ⭐	Vercel 出品，后起之秀	配置极简，Go 编写、速度极快，开箱即用的远程缓存	插件生态不如 Nx 丰富	中小型及大厂新项目

中大型前端项目的「黄金标准」

pnpm：处理底层依赖链接，保证快和省。
Turborepo：处理上层任务调度，保证构建流水线效率（Caching、Remote Caching、Pipelines）。
TypeScript：提供全链路类型安全。

10.5 目录结构与子包引用规则

project
├── apps
│   ├── web/     package.json  // @monorepo-project/web
│   └── server/  package.json  // @monorepo-project/server
├── packages
│   ├── configs/        // 配置
│   │   ├── index.js    // 所有子包都要有入口，导出方法
│   │   ├── eslint.config.js
│   │   └── package.json  // @monorepo-project/configs  module: "index.js"
│   ├── ai-engine/      // AI 引擎层
│   │   ├── src/index.js
│   │   └── package.json
│   ├── utils/         // 通用工具
│   ├── types/         // 通用类型
│   └── shared/        // 共享模块
├── pnpm-workspace.yaml
└── package.json

# pnpm-workspace.yaml
packages:
  - "apps/**"      # 应用层
  - "packages/**"  # 子包

包名定义：统一为 @外层包名/当前包的文件夹名。

子包被引用的三个前提

有入口文件。
在入口文件中定好并向外部导出功能模块代码。
package.json 的 module（或 main）指向入口文件，向外暴露。

引用方式：在引用方的 dependencies 中写 "@monorepo-project/configs": "workspace:*"，然后执行安装命令。

注意：每个子包都需要打包（常见用 tsup）。

10.6 从零手搭脚手架（12 步）

需掌握的知识点

工程组织：monorepo（本质是架构约定、包的约定）
规范化：ESLint、Stylelint、cspell、commitlint
构建打包：Vite、esbuild、webpack
测试：Jest、Vitest、Playwright ⭐⭐⭐

搭建流程

创建项目。
pnpm init 初始化。
管理依赖 package.json：
- 运行时依赖："devDependencies": { "typescript": "版本号" }
- 编译脚本："scripts": { "compile": "tsc" }
创建 pnpm-workspace.yaml，划分子包结构（packages / apps）。
创建对应子包。
在 apps 下创建 client 与 server，先完成 server 配置。
server 内初始化，指定编译脚本（里层包共享外层包依赖，可省略类型依赖）。
创建 server/src/index.ts。
基本结构完成。
配置启动命令：server/package.json → "scripts": { "dev": "node dist/index.js" }。
启动验证：pnpm i → pnpm compile → npx tsc --init → 指定 outDir 与 rootDir 后重跑。
一个基本 Node.js 全栈骨架完成。

10.7 规范体系

工具	职责
ESLint	JS/TS 代码质量与规则检查
Prettier	代码格式化
cspell	拼写检查
commitlint	Git 提交信息规范
Biome	一体化工具链：Formatter + Linter + Import 排序，可替代 eslint + prettier

Biome 的边界：没有插件体系，且只支持部分 TS 类型感知的 Lint 规则，所以现实中是 ESLint + Biome 共存，而不是完全替换。

CI/CD 卡点设计

提交前：lint-staged + husky。
提交时：commitlint 校验 message。
PR 时：类型检查、单测、构建体积对比。

10.8 组件库与设计体系

原子化与组件化的三层约束

层	手段	作用
Design Tokens（设计契约）	定义语义化 CSS 变量	作为单一事实来源
Utility Class（原子实现）	Tailwind 读取 Tokens 生成原子类	把契约落到可组合的原子类
Component API（接口约束）	用 CVA（Class Variance Authority）把原子类封装为类型安全的组件变体	对业务暴露受控 API

文档站：Rspress

维度	Rspress（Rust 驱动）	Docusaurus / VitePress	核心收益
构建引擎	Rspack (Rust)	Webpack / Vite	冷启动快 10 倍，大型站点毫秒级 HMR
MDX 支持	原生内置	需插件 / 部分支持	无缝引入 React 组件，实现 Live Demo
类型提取	基于 TS AST	需复杂配置	自动从源码生成 API 表格，杜绝文档过时
多语言	原生路由支持	较繁琐	轻松支持 i18n

页面用 .mdx 配置实现；文档：https://rspress.rs/guide/start/getting-started

MCP 开发（组件库可顺带提供的能力）

MCP 服务端 + MCP 客户端，把二者连接起来，即可让 AI 直接使用你的组件库知识。

10.9 构建工具：Vite

初始化

1	npm create vite@latest my-app --template vanilla-ts

① Bundleless
基于 ESM 的模块化管理与加载，少打包甚至不打包。

1 2	<!-- bundleless 方案 --> <script type="module" src="/src/main.ts"></script>

为什么用 Native ESM 启动：利用浏览器原生解析 import 的能力，省去开发环境的 bundle 打包过程，把文件处理从 O(n) 降为 O(1)。

② 两个高频原理题

tsconfig.json 的 moduleResolution 为什么设为 Node 或 Bundler？
- 虽然 Vite 最终跑在浏览器，但开发阶段依赖 Node.js 环境去查找依赖（resolve node_modules）。
Path Alias 的底层原理？
- 它不只是 TS 的静态检查配置，更需要在 vite.config.ts 中配置 resolve.alias。本质上是在编译时用正则把 @/xxx 替换为绝对路径，否则浏览器运行时会报模块找不到。

③ 插件体系
微内核设计，插件本质是对象。常见插件：

CSS 编译：vite-plugin-postcss
TS 编译：vite-plugin-enhance-typescript
GLSL 编译：vite-plugin-glsl
文件处理：vite-plugin-babel、vite-plugin-legacy
启动服务：内置

④ 开发一个编译类插件的三条路径

正则表达式替换（最快，也最脆）。
Babel AST 做编译器（最稳）。
magic-string + estree-walker 遍历 AST 并实现编译（推荐）。

生态 AST 工具链

工具	说明
`acorn`	Vite / Rollup 内置解析器，用于生成 AST（太重，不推荐直接用）
`estree-walker`	轻量 AST 遍历工具
`magic-string` ⭐	不必重新生成整个 AST，可按索引修改字符串并自动生成 SourceMap

// 示例：删除 console.log 的插件，之后在 vite.config.ts 的 plugins 里注册
import MagicString from 'magic-string'
import { walk } from 'estree-walker'

export const removeConsoleLogPlugin = {
  name: "remove-console-log",
  apply: "build", // 仅在生产构建生效
  transform(code: string, id: string) {
    // 只处理 js / ts / jsx / tsx
    if (!/\.(js|ts|jsx|tsx)$/.test(id)) return

    const s = new MagicString(code)
    const ast = this.parse(code)

    walk(ast, {
      enter(node: any) {
        if (node.type === "CallExpression") {
          const callee = node.callee
          if (
            callee.type === "MemberExpression" &&
            callee.object.name === "console" &&
            callee.property.name === "log"
          ) {
            // 找到 console.log 的节点范围，在源码中移除
            s.remove(node.start, node.end)
          }
        }
      },
    })

    return {
      code: s.toString(),
      map: s.generateMap({ source: id, includeSources: true }),
    }
  },
}

⑤ 插件生命周期（钩子）
buildEnd（构建完成）→ transform（转换阶段）→ resolveId（解析阶段）→ load（加载阶段）……

10.10 编译原理：Babel

Babel 是什么

一个标准 LISP 风格编译器，本质是 JS 编译器。
用处：代码降级、polyfill、多端编译（Taro）。

编译的本质：把源代码加工成新代码（字符串操作）。通过词法、语法、语义分析加工代码，输出目标代码。
AST（Abstract Syntax Tree）：描述代码结构；类比 DOM 树描述 DOM 结构。

四阶段架构

flowchart LR
    Code["Code"] --> Lexer[Lexer 词法分析]
    Lexer -- tokens --> Parser[Parser 语法分析]
    Parser -- ast --> SemanticAnalysis[SemanticAnalysis 语义分析]
    SemanticAnalysis -- analyzedAst --> CodeGenerator[CodeGenerator 代码生成]
    SemanticAnalysis -- analyzedAst --> CodeInterpretor[CodeInterpretor 代码执行]
    CodeGenerator --> NewCode["New Code"]

    subgraph Compiler
        Lexer
        Parser
        SemanticAnalysis
        CodeGenerator
        CodeInterpretor
    end

① 解析（Parsing）—— @babel/parser
把非结构化字符串转为结构化数据，分两个子阶段：

词法分析（Lexical Analysis / Tokenization）
- 机制：扫描器逐字符读取源码，移除空白与注释，切割成 Token 流。
- 形态：const a = 1 → [Keyword(const), Identifier(a), Punctuator(=), Numeric(1)]
- 重难点：处理上下文相关语法（JSX、TypeScript）需按上下文切换 Tokenizer 状态。
语法分析（Syntactic Analysis）
- 机制：按 ECMAScript 语法规则把 Token 流组装成 AST。
- 形态：Token 流 → JSON 树结构（符合 ESTree 规范）

② 转换（Transformation）—— @babel/traverse
最复杂、最核心的阶段，也是插件唯一介入窗口。

机制：接收 AST，做深度优先遍历（DFS）。
架构：采用访问者模式（Visitor Pattern），解耦「数据结构（AST）」与「操作逻辑（插件）」。
形态：AST → Modified AST（被增删改查后的新树）

③ 生成（Generation）—— @babel/generator

机制：深度优先遍历转换后的 AST，按节点类型递归输出字符串。
代码还原：把 AST 节点转回 JS 代码。
SourceMap 生成：利用 AST 中保留的 loc（行列信息）映射回源码。

④ 最小流程

import * as parser from '@babel/parser'
import _traverse from '@babel/traverse'
import _generator from '@babel/generator'

const code = `const a = 1`

// 1. 生成语法树
const ast = parser.parse(code)

// 2. 加工语法树：树的加工（二叉树遍历同理，前中后序、层序）
// 2.1 访问者模式
const visitor = {
  VariableDeclaration(path) {
    console.log(path.node)
  },
}
_traverse.default(ast, visitor)

// 3. 代码生成
const res = _generator.default(ast, {}, code)

完整工程流程（src → compile.js → dist）

// compile.js
import fs from 'node:fs'
import path from 'node:path'
import * as parser from '@babel/parser'
import _traverse from '@babel/traverse'
import _generator from '@babel/generator'

// 1. 定义源码路径
const sourceCode = path.resolve(import.meta.dirname, 'src/index.js')
// 2. 定义输出路径
const dist = path.resolve(import.meta.dirname, 'dist/index.js')
// 3. 同步读取源码
const code = fs.readFileSync(sourceCode, { encoding: 'utf-8' })
// 4. 解析源码
const ast = parser.parse(code, { presets: ['@babel/preset-env'] })
// 5. 加工语法树
const visitor = {
  VariableDeclaration(path) {
    console.log(path.node)
  },
}
_traverse.default(ast, visitor)
// 6. 代码生成
const res = _generator.default(ast, {}, code)
// 7. 输出代码
fs.writeFileSync(dist, res.code)

插件化体系（微内核）

本质：一个 Babel 插件就是 Visitor 对象的工厂函数。Babel 遍历 AST 时每走到一个节点，就去查找所有已注册插件中是否定义了针对该节点类型的钩子。
插件：arrowFunctionPlugin（语法转换）、declarePlugin（声明插件）。
预设（Preset）：把多个 plugin 打包在一起。如 @babel/preset-env——把箭头函数转为普通函数、把 const 转为 var。

访问者模式的三条规则

生命周期：每个节点经历两次访问——Enter（向下遍历、触达时触发，大部分逻辑写这里）、Exit（向上回溯、离开时触发）。
插件在预设之前运行。
插件顺序：从前向后（First to Last）；预设顺序：从后向前（Last to First，为兼容性，先跑 loose 模式）。

写一个插件的流程：参考 transform-arrow-functions 实现 → 解析源码时把插件文件路径注册进去 → 安装即可。

10.11 实战：类飞书多维表公式编译器 + AI Agent 化

四步走（以 sum(a, b) 为例）

拆：sum ( a b ) —— 拆的过程就是词法分析（Tokenizer）。
转：转为标准 AST（DSL）—— Parser。中间可先转逆波兰式。
生成：Generator。
执行：Interpreter。

AI 公式编辑器的两条路线

路线	流程	风险
传统思路（Copilot）	用户输入「计算平均值」→ LLM 返回代码 → 扔进 `eval`	危险且不可控，存在注入风险
高阶思路（Agentic Flow）	① Generate：LLM 基于我们的 DSL 文法生成公式② Validate：复用 `parse()` 作为校验器③ Reflect：`parse()` 报语法错误时，把错误信息回传 LLM 让其重生成④ Execute：只有通过校验的公式才送进 Interpreter⑤ 返回结果⑥ 可视化结果	可控、可解释、可迭代

这个模式可迁移到所有「LLM 生成结构化产物」的场景：先约束文法 → 再让模型生成 → 用编译器校验 → 失败回传重试 → 最后才执行。这就是「给 AI 加一层枷锁」的低代码思路。

十一、桌面端与全栈整合

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）

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：

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 四步）

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

模型与 AI 层

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

六类节点的交互设计

开始节点：弹窗输入变量名、变量类型、默认值、描述。
结束节点：两种类型——返回变量（显示变量名与变量值，变量值含输出类型：字符串、数字、数组、对象、文件）与返回文本（以 Markdown 展示）。
大模型节点：下拉选择模型（模型列表可远程拉取）+ 输入提示词。
工具节点：进入插件市场搜索安装，或在节点中从已有 tools 列表选择。
条件节点：输入条件表达式，如「当前结果是否 > 10」。
串联：把 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 生成代码混乱

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

落地做法

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

AI 开发 SOP（Vibe Check）

Plan 策划
Coding 开发
Lint 检查
开发隔离：新特性隔离；设计文档、实施文档单独成文件

工具选择：Claude + Codex。

12.2 用 Vibe Coding 做亿级协同表格

先做三层约束

全局约束（工程规范先行）。
.clauderules：约束 AI 编码的技术实现。
.plan：规划。

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

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

.features：按新特性拆解开发

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

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

配套 MCP / Skill

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

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

基于问题，先分析出大致步骤。
按使用的工具建对应文件夹存放产物。
建一个 plan 框架文档，告诉 AI 如何做项目规划。
等 AI 产出规划。
检查规划是否合理。

# 项目规划（plan 框架示例）

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

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

## 产出
规划完成后，将规划文档输出至 .plan 文件

建「新特性开发文档」（开发遵循的规范），告诉 AI 接下来按这些规范开发。
等 AI 生成代码。
检查并测试。

# 具体新特性开发（示例）

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

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

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

基于「项目规划文档」+「新特性开发文档」，再建一个核心功能计划文档，指明用什么技术实现。
让 AI 基于核心功能文档生成新的开发规划文档。
按新规划生成项目。
测试。

## 核心功能
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

// 数组：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 的两种扩展方式

interface User {
  name: string
  age: number
}
type UserT = {
  name: string
  age: number
}

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

③ 联合类型 + 类型保护（类型收敛）

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
}

④ 泛型

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

⑤ 类型操作与工具类型

// 联合类型：节点协议
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 的三点沉淀

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

13.4 Zod 要点

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 中的三个用法

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

十四、音视频与 FFmpeg 基础

一句话定位：前端做 AI 音视频，90% 的时间不花在「编解码原理」上，而花在「参数放对位置 + 滤镜串对链」上。本章按「概念 → 命令结构 → 高频操作 → 滤镜 → 色彩空间 → 前端落地」六层展开，命令均可直接复制执行。

能力清单

能力	达到什么程度	对应
分清容器 / 编码 / 协议	拿到一个文件能说出「换盒子还是重压」	§14.1
像素格式与色彩参数	看懂 `yuv420p`、`bt709`、`color_range` 并会修偏色	§14.2
命令行结构与参数位置	不再出现「加了参数却没生效」	§14.3
高频操作	转码、切音频、无损切片、压体积、抽帧、GIF、合并、HLS	§14.4
滤镜链	能自己写 `-filter_complex` 做画中画/拼接/混音	§14.5
视觉增强	裁剪、缩放补边、水印、走马灯、字幕、打码	§14.6
色彩空间对接	Canvas 的 RGBA 帧能正确喂给编码器	§14.7
前端与 AI 场景	会选 MediaRecorder / WebCodecs / ffmpeg.wasm	§14.8

14.1 三个必须先分清的概念：容器、编码、协议

一句话：容器管「怎么装」，编码管「怎么压」，协议管「怎么传」。

层	职责	例子
容器 Container / Muxer	把视频流、音频流、字幕、元数据打包成一个文件，并写时间戳索引	`.mp4` `.mkv` `.flv` `.webm` `.ts`
编码 Codec	把原始画面与声音压缩成码流	H.264、H.265、VP9、AV1、AAC、Opus
协议 Protocol	决定码流怎么切块、怎么传输	HLS（`.m3u8` + `.ts`）、DASH、RTMP、WebRTC

核心结论：同一个 mp4 里可以放 H.264，也可以放 H.265；同一份 H.264 码流既能装进 mp4，也能装进 flv。容器与编码是两个正交维度——这是这块最常被追问的点。

容器	常见视频编码	常见音频编码	典型场景	浏览器兼容
MP4	H.264 / H.265 / AV1	AAC	通用点播、短视频	全平台（H.265 看终端）
WebM	VP8 / VP9 / AV1	Opus / Vorbis	Web 端开源方案	Chrome / Firefox；Safari 17+
FLV	H.264	AAC / MP3	老直播、HTTP-FLV	需 flv.js
MKV	几乎任意	几乎任意	本地播放、多音轨多字幕	不支持
TS	H.264 / H.265	AAC	HLS 切片载体	通过 hls.js
MOV	H.264 / ProRes	AAC / PCM	剪辑中间态、苹果生态	部分

编码	压缩率（相对 H.264）	编码耗时	授权	建议
H.264 / AVC	1x	快	需授权但已普及	默认选它，兼容性最好
H.265 / HEVC	约 1.5~2x	慢 2~5 倍	专利复杂	体积敏感且终端可控时用
VP9	约 1.3~1.5x	慢	免费	WebM 生态
AV1	约 2x	很慢（新硬件改善）	免费	趋势，但编码成本高
AAC	—	—	需授权	音频默认
Opus	低码率下优于 AAC	—	免费	WebM / WebRTC

转封装 ≠ 转码（这块最省钱的一条经验）

转封装：-c copy，只换盒子不重新编码，秒级完成、零画质损失。
转码：-c:v libx264，解码再编码，慢且必然有损。
判断顺序：先 ffprobe 看源编码 → 与目标容器兼容就直接 -c copy。

# 转封装：mp4 → mkv，秒级、无损
ffmpeg -i in.mp4 -c copy out.mkv

# 反例：本来只是换容器，却写了重编码，白等十分钟还掉画质
ffmpeg -i in.mp4 -c:v libx264 -crf 23 out.mkv

14.2 像素、色彩与压缩参数

像素格式（pixel format）——决定一帧画面在内存里怎么排。

格式	含义	每像素位宽	典型用途
`yuv420p`	亮度全采样，色度 2×2 下采样	12 bit	通用分发格式，H.264 硬解底线
`yuv422p`	色度水平减半	16 bit	采集卡、专业中间格式
`yuv444p`	色度不降采样	24 bit	抠像、色彩处理、无损
`nv12`	YUV420 的 UV 交错变体	12 bit	硬件编解码 / GPU 纹理
`rgba`	四通道 8 位，带 alpha	32 bit	Canvas / WebGL、需要透明

为什么用 4:2:0：人眼对亮度敏感、对色度迟钝，扔掉 3/4 的色度信息，体积直接砍一半而肉眼几乎无感。

RGB 与 YUV 的换算（BT.601 全范围，前端最常用）

1
2
3

Y =  0.299R + 0.587G + 0.114B
U = -0.169R - 0.331G + 0.500B + 128
V =  0.500R - 0.419G - 0.081B + 128

BT.709 的系数是 0.2126 / 0.7152 / 0.0722——系数用错，就是「偏色」的第一大原因。

色彩四件套

参数	取值	说明
`-color_range`	`tv`（16–235）/ `pc`（0–255）	视频默认 tv，Canvas 出来是 pc，不声明就发灰
`-colorspace`	`bt709` / `bt601` / `bt2020nc`	SD 用 601，HD 用 709，HDR 用 2020
`-color_primaries`	`bt709` / `bt2020`	色域
`-color_trc`	`bt709` / `smpte2084`(PQ) / `arib-std-b67`(HLG)	传输函数，HDR 的关键

1
2
3

# 显式声明，避免播放器各自猜
ffmpeg -i in.mp4 -c:v libx264 -pix_fmt yuv420p \
  -colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4

四个压缩参数

参数	含义	常见值	影响
位深	每通道比特数	8bit / 10bit	10bit 减少色带，HDR 必须
码率	每秒数据量	500k / 2.5M / 8M	画质与体积的主开关
帧率	每秒帧数	24 / 25 / 30 / 60	流畅度，同时抬高码率
GOP	两个 I 帧之间的间隔	30 / 48 / 250	越大越省码率，随机 seek 越慢

体积估算（面试爱考）

1 2	体积(Byte) ≈ (视频码率 + 音频码率) × 时长(s) / 8 目标视频码率 ≈ 目标体积(MB) × 8192 / 时长(s) − 音频码率

例：10 分钟视频压到 100 MB → 100 × 8192 / 600 ≈ 1365k，减掉音频 128k → -b:v 1237k。

I / P / B 帧：I 帧独立可解、P 帧参考前面、B 帧双向参考。B 帧越多压缩越好，但延迟越高——**直播要 -bf 0**。

分辨率	场景	H.264 30fps 推荐码率
640×360	移动端预览	500k ~ 800k
1280×720	通用	1.5M ~ 2.5M
1920×1080	主流程	4M ~ 6M
3840×2160	4K	15M ~ 25M

码控模式	参数写法	特点
CRF / CQP	`-crf 23`	恒定质量、码率浮动，点播首选
ABR	`-b:v 2M`	平均码率，体积可控
CBR	`-b:v -minrate -maxrate` 相等	直播推流
两遍编码	`-pass 1` / `-pass 2`	体积精确，耗时翻倍

14.3 命令结构与参数位置

三个可执行程序

程序	职责	典型用法
`ffmpeg`	转码 / 处理	`ffmpeg -i in.mp4 ...`
`ffprobe`	探测元信息	`ffprobe -v error -show_streams in.mp4`
`ffplay`	极简播放器	`ffplay in.mp4`

通用结构

1	ffmpeg [全局参数] [输入参数] -i 输入 [输出参数] 输出

位置决定语义：-ss / -t 放 -i 前是输入参数（快速定位，从关键帧开始读）；放 -i 后是输出参数（精确但慢，要解码到指定时间）。

⚠️ 最常见的坑：把 -c:v、-pix_fmt 写在 -i 之前，会被当成输入参数，结果「参数加了却没生效」。

参数	归类	作用
`-i`	输入	指定输入文件或 `-`（stdin）
`-y` / `-n`	全局	覆盖 / 不覆盖输出文件
`-hide_banner`	全局	隐藏版本与编译信息
`-loglevel error`	全局	只打错误，方便脚本抓报错
`-nostdin`	全局	后台运行时不抢 stdin
`-ss`	输入/输出	定位
`-t`	输入/输出	截取时长
`-c:v` / `-c:a`	输出	视频 / 音频编码器，`copy` 表示不重编码
`-b:v` / `-b:a`	输出	码率
`-crf`	输出	恒定质量，0–51，越小越好
`-preset`	输出	速度档位 `ultrafast`→`veryslow`
`-pix_fmt`	输出	像素格式
`-r` / `-s`	输出	帧率 / 分辨率（`-s` 等价于 scale）
`-vf` / `-af`	输出	视频 / 音频简单滤镜
`-filter_complex`	输出	多输入多输出滤镜图
`-map`	输出	选择或重排流
`-f`	输出	强制容器格式
`-movflags +faststart`	输出	moov 前置，Web 秒开
`-progress pipe:1`	输出	输出机器可读进度

ffprobe 探信息

# 关键视频参数
ffprobe -v error -select_streams v:0 \
  -show_entries stream=codec_name,profile,width,height,r_frame_rate,avg_frame_rate,bit_rate,pix_fmt,nb_frames \
  -of json in.mp4

# 时长 / 体积 / 总码率
ffprobe -v error -show_entries format=duration,size,bit_rate -of csv=p=0 in.mp4

Node 里统一封装：

import { execFile } from 'node:child_process'
import { promisify } from 'node:util'

const run = promisify(execFile)

export interface VideoMeta {
  duration: number
  width: number
  height: number
  fps: number
  codec: string
  bitrate: number
}

export async function probe(file: string): Promise<VideoMeta> {
  const { stdout } = await run('ffprobe', [
    '-v', 'error',
    '-select_streams', 'v:0',
    '-show_entries', 'stream=codec_name,width,height,avg_frame_rate,bit_rate:format=duration,bit_rate',
    '-of', 'json',
    file,
  ])
  const j = JSON.parse(stdout)
  const s = j.streams?.[0] ?? {}
  const [num, den] = String(s.avg_frame_rate ?? '0/1').split('/').map(Number)
  return {
    duration: Number(j.format?.duration ?? 0),
    width: s.width ?? 0,
    height: s.height ?? 0,
    fps: den ? num / den : 0,
    codec: s.codec_name ?? 'unknown',
    bitrate: Number(s.bit_rate ?? j.format?.bit_rate ?? 0),
  }
}

注意 -show_entries 只用一处，stream=... 与 format=... 之间用冒号连接；写成两个 -show_entries 会互相覆盖。

进度解析——长任务必须给前端反馈。

1	ffmpeg -nostdin -i in.mp4 -c:v libx264 -crf 23 -progress pipe:1 -nostats out.mp4

输出是 key=value 流：frame=、fps=、out_time_ms=、speed=、progress=continue|end。

import { spawn } from 'node:child_process'

const proc = spawn('ffmpeg', [
  '-nostdin', '-i', file, '-c:v', 'libx264', '-crf', '23',
  '-progress', 'pipe:1', '-nostats', out,
])

let buf = ''
proc.stdout.on('data', (chunk) => {
  buf += chunk.toString()
  const lines = buf.split('\n')
  buf = lines.pop() ?? ''
  for (const line of lines) {
    const [k, v] = line.split('=')
    // out_time_ms 实际单位是微秒（FFmpeg 历史遗留的命名错误）
    if (k === 'out_time_ms') onProgress(Math.min(1, Number(v) / 1e6 / duration))
  }
})

14.4 高频操作（可直接抄）

#	场景	关键参数	小节
1	通用转码	`-c:v libx264 -crf 23 -pix_fmt yuv420p`	下
2	提取 / 剥离音频	`-vn` / `-an`	下
3	无损切片	`-ss` + `-t` + `-c copy`	下
4	压到目标体积	`-b:v` 两遍编码	下
5	抽帧 / 封面 / 雪碧图	`-vf fps=`、`tile`	下
6	图片序列转视频	`-framerate`	下
7	转 GIF	`palettegen` + `paletteuse`	下
8	多段合并	`-f concat`	下
9	音视频合流	`-map` + `-shortest`	下
10	变速	`setpts` + `atempo`	下
11	HLS 切片	`-f hls`	下
12	硬件加速	`h264_nvenc` / `videotoolbox`	下

① 通用转码（兼容性拉满的默认档）

1 2	ffmpeg -i in.mov -c:v libx264 -preset medium -crf 23 -profile:v high -level 4.0 \ -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart out.mp4

-pix_fmt yuv420p 是硬解底线，+faststart 让首帧更快到达（moov 前置）。

② 提取 / 剥离音频

1
2
3

ffmpeg -i in.mp4 -vn -c:a copy out.m4a                  # 原样提取，无损且秒级
ffmpeg -i in.mp4 -vn -c:a libmp3lame -q:a 2 out.mp3      # 转 MP3
ffmpeg -i in.mp4 -an -c:v copy out.mp4                   # 只去音频

③ 无损切片

1	ffmpeg -ss 00:01:30 -i in.mp4 -t 30 -c copy out.mp4

坑：copy 只能在关键帧处切，实际起点会前移到最近的 I 帧，时长也可能多几帧。要帧级精确，就重编码，或「先精确定位一小段再 copy」。

1	ffmpeg -i in.mp4 -ss 00:01:30.500 -t 30 -c:v libx264 -crf 20 -c:a aac out.mp4

④ 压到目标体积（两遍编码）

1
2
3

# 第一遍只分析，输出丢弃；Windows 用 NUL，Linux / macOS 用 /dev/null
ffmpeg -y -i in.mp4 -c:v libx264 -b:v 1200k -pass 1 -an -f mp4 /dev/null
ffmpeg -i in.mp4 -c:v libx264 -b:v 1200k -pass 2 -c:a aac -b:a 128k out.mp4

⑤ 抽帧 / 封面 / 雪碧图

ffmpeg -i in.mp4 -vf fps=1 frames/%05d.jpg                                # 每秒一帧
ffmpeg -i in.mp4 -vf "select='eq(pict_type,I)'" -fps_mode vfr key/%05d.jpg # 只抽关键帧
ffmpeg -ss 3 -i in.mp4 -frames:v 1 -q:v 2 cover.jpg                        # 封面
ffmpeg -i in.mp4 -vf "fps=1/10,scale=160:-2,tile=5x4" -frames:v 1 sprite.jpg # 雪碧图

⑥ 图片序列转视频

1	ffmpeg -framerate 24 -i frames/%05d.png -c:v libx264 -pix_fmt yuv420p out.mp4

⑦ 转 GIF（必须走调色板）

1
2
3

ffmpeg -i in.mp4 -vf "fps=12,scale=480:-2:flags=lanczos,palettegen=stats_mode=diff" palette.png
ffmpeg -i in.mp4 -i palette.png -filter_complex \
  "[0:v]fps=12,scale=480:-2:flags=lanczos[v];[v][1:v]paletteuse=dither=bayer" out.gif

不生成调色板直接转，颜色会脏成 256 色抖动——这是 GIF 清晰度的决定性一步。

⑧ 多段合并

1 2	printf "file '%s'\n" a.mp4 b.mp4 c.mp4 > list.txt ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4

前提：编码、分辨率、帧率、像素格式全一致，否则先统一转码再合并。

⑨ 音视频合流

1	ffmpeg -i video.mp4 -i audio.m4a -c:v copy -c:a aac -shortest out.mp4

-shortest 以短的一路为准；不带它就会在流的末尾留下空画面或空音轨。

⑩ 变速

1 2	ffmpeg -i in.mp4 -filter_complex \ "[0:v]setpts=0.5*PTS[v];[0:a]atempo=2.0[a]" -map "[v]" -map "[a]" out.mp4

音频 atempo 单次只支持 0.5–2.0，超过要串联（4 倍速 = atempo=2.0,atempo=2.0）。

⑪ HLS 切片

1
2
3

ffmpeg -i in.mp4 -c:v libx264 -c:a aac -f hls \
  -hls_time 6 -hls_playlist_type vod \
  -hls_segment_filename "seg_%03d.ts" index.m3u8

⑫ 编码器的两个特例

# H.265：必须加 -tag:v hvc1，否则苹果生态不认
ffmpeg -i in.mp4 -c:v libx265 -crf 28 -preset medium -tag:v hvc1 -c:a copy out.mp4

# VP9：-b:v 0 让 CRF 生效
ffmpeg -i in.mp4 -c:v libvpx-vp9 -crf 32 -b:v 0 -row-mt 1 -c:a libopus -b:a 96k out.webm

⑬ 清元数据与硬件加速

ffmpeg -i in.mp4 -map_metadata -1 -map_chapters -1 -c copy out.mp4

ffmpeg -hwaccel cuda -i in.mp4 -c:v h264_nvenc -preset p5 -rc vbr -cq 23 -c:a copy out.mp4  # NVIDIA
ffmpeg -i in.mp4 -c:v hevc_videotoolbox -q:v 55 -c:a copy out.mp4                             # macOS

-cq / -q:v 是各家的质量档位，与 -crf 不等价，照抄数值会得到不同的画质曲线。

14.5 滤镜系统：线性链与非线性链

两套滤镜入口，先分清再动手：

维度	简单滤镜 `-vf` / `-af`	复杂滤镜 `-filter_complex`
输入数	1	多
输出数	1	多
链内分隔符	逗号 `,`	逗号 `,`
链间分隔符	无（一条链）	分号 `;`
典型场景	缩放、裁剪、加字幕、加文字	画中画、多路拼接、混音、多输出

非线性链的语法：[输入标签]滤镜=参数,滤镜=参数[输出标签]

1
2
3

[0:v]scale=1280:-2,format=yuv420p[v0];
[1:v]scale=320:-2[logo];
[v0][logo]overlay=W-w-16:16

[0:v] 第 0 个输入的视频流，[0:a] 音频，[0:s] 字幕
每条链 = 输入标签 → 滤镜序列 → 输出标签
没被下游消费的输出标签，由 -map 决定落到哪个输出文件

四条必踩的坑

-vf 与 -filter_complex 同时写，且抢同一条流——会报 Filter ... has an unconnected output。统一用 -filter_complex。
造了标签却没 -map——输出文件里干脆没有这条流，静默成功。
表达式里的逗号没转义——被当成滤镜分隔符，报参数错误。写成 \,，即使在双引号内。
scale 的宽高必须偶数（yuv420 要求），用 -2 而不是 -1（-1 可能算出奇数）。

# 画中画：右上角小窗，等比缩到主画面 1/3
ffmpeg -i main.mp4 -i pip.mp4 -filter_complex \
  "[1:v]scale=iw/3:-2[pip];[0:v][pip]overlay=W-w-16:16" -c:a copy out.mp4

# 横拼两路
ffmpeg -i a.mp4 -i b.mp4 -filter_complex \
  "[0:v]scale=640:-2[l];[1:v]scale=640:-2[r];[l][r]hstack=inputs=2" -c:a copy out.mp4

# 音频混音：背景乐压到 0.3，人声保持 1.0
ffmpeg -i bgm.mp3 -i voice.wav -filter_complex \
  "[0:a]volume=0.3[b];[1:a]volume=1.0[v];[b][v]amix=inputs=2:duration=longest[a]" \
  -map "[a]" out.m4a

# 只在 5~10 秒显示水印
ffmpeg -i in.mp4 -i logo.png -filter_complex \
  "[0:v][1:v]overlay=W-w-20:20:enable='between(t,5,10)'" -c:a copy out.mp4

14.6 视觉增强

裁剪 crop：参数顺序是 w:h:x:y。

1
2
3

ffmpeg -i in.mp4 -vf "crop=1280:720:0:0" out.mp4        # 从左上角取 1280x720
ffmpeg -i in.mp4 -vf "crop=in_w:in_h-120:0:0" out.mp4   # 裁掉底部 120px
ffmpeg -i in.mp4 -vf "cropdetect=24:16:0" -f null -      # 自动探测黑边，从日志读结果

缩放 scale + 补边 pad

# 等比缩到 1280 宽，高度自适应且保证偶数
ffmpeg -i in.mp4 -vf "scale=1280:-2" out.mp4

# 强制 1280x720 且不变形：先等比缩小再补黑边
ffmpeg -i in.mp4 -vf \
  "scale=1280:720:force_original_aspect_ratio=decrease,pad=1280:720:(ow-iw)/2:(oh-ih)/2:color=black" out.mp4

# 只缩不放（大图压小，小图保持原样）
ffmpeg -i in.mp4 -vf "scale=w='min(1920,iw)':h=-2" out.mp4

水印 overlay：位置用表达式，W/h 是主画面尺寸，w/h 是水印尺寸。

1 2	ffmpeg -i in.mp4 -i logo.png -filter_complex \ "[1:v]scale=120:-2[logo];[0:v][logo]overlay=W-w-20:H-h-20" -c:a copy out.mp4

位置	表达式
右下角	`W-w-20:H-h-20`
居中	`(W-w)/2:(H-h)/2`
跟随时间	`x='if(lt(t,5),20,W-w-20)':y=20`

走马灯（滚动文字）——用 drawtext 的 x 表达式做位移，比 overlay 更轻。

1
2
3

ffmpeg -i in.mp4 -vf \
  "drawtext=text='内部资料 禁止外传':fontsize=28:fontcolor=white@0.7:x=w-mod(t*200\,w+800):y=h-56" \
  -c:a copy out.mp4

要点：t*200 是滚动速度（像素/秒），800 是文字宽度的近似值（超出画面宽度才能滚出视野外）；mod() 让位移循环，从右侧画外进入。中文字体要指定 fontfile，Windows 上写 fontfile='C\:/Windows/Fonts/msyh.ttc'——盘符后的冒号必须转义。

打码：局部模糊或纯色遮挡

# 把区域裁出来模糊，再盖回原位置
ffmpeg -i in.mp4 -filter_complex \
  "[0:v]crop=200:80:100:60,boxblur=10:1[b];[0:v][b]overlay=100:60" -c:a copy out.mp4

# 纯色遮挡
ffmpeg -i in.mp4 -vf "drawbox=x=100:y=60:w=200:h=80:color=black@0.8:t=fill" out.mp4

字幕：软挂与硬压

# 硬压 srt，顺便指定字体样式
ffmpeg -i in.mp4 -vf \
  "subtitles=sub.srt:force_style='FontName=Microsoft YaHei,FontSize=20,PrimaryColour=&H00FFFFFF'" out.mp4

# ass 定位更自由（需要 libass）
ffmpeg -i in.mp4 -vf "ass=sub.ass" out.mp4

坑：subtitles 依赖编译时带 libass，很多精简版 FFmpeg 没有；Windows 路径要写成 C\:/x/sub.srt。

旋转与镜像

1
2
3

ffmpeg -i in.mp4 -vf "transpose=1" out.mp4   # 顺时针 90°
ffmpeg -i in.mp4 -vf "hflip" out.mp4         # 水平镜像
ffmpeg -i in.mp4 -vf "vflip" out.mp4         # 垂直翻转

手机拍摄的旋转信息存在容器元数据里，转码后可能「自动转正」或「反而歪掉」——统一用 -vf transpose 显式处理，别依赖元数据。

14.7 色彩空间：Canvas 帧 → 编码器

背景：Canvas 只给你 RGBA（sRGB，pc range），而视频编码器吃 YUV420P（tv range）。中间有三种对接路线。

方案	怎么拿帧	谁负责转 YUV	适用场景
MediaRecorder + Canvas	`canvas.captureStream()`	浏览器内部	纯录制，无需精修
WebCodecs	`VideoFrame` → `VideoEncoder`	指定 `format: 'I420'`	高性能、需要逐帧控制
ffmpeg.wasm / 原生 FFmpeg	`getImageData()` → RGBA 字节	FFmpeg 或自己写	需要滤镜、封装、兼容老浏览器

方案 A：交给 FFmpeg 转（最省事）

1
2
3

# 从 stdin 读 RGBA 原始帧，FFmpeg 自己转 yuv420p
ffmpeg -f rawvideo -pix_fmt rgba -s 1280x720 -r 30 -i - \
  -c:v libx264 -pix_fmt yuv420p -crf 20 out.mp4

方案 B：自己算 RGBA → YUV420P（BT.601 全范围，与 14.2 的公式一致）

const clamp = (v: number) => (v < 0 ? 0 : v > 255 ? 255 : v | 0)

/** RGBA(Uint8ClampedArray) → yuv420p 紧凑布局：Y 平面 + U 平面 + V 平面 */
export function rgbaToYuv420p(rgba: Uint8ClampedArray, w: number, h: number): Uint8Array {
  const ySize = w * h
  const uvW = w >> 1
  const uvH = h >> 1
  const out = new Uint8Array(ySize + uvW * uvH * 2)
  const uOff = ySize
  const vOff = ySize + uvW * uvH

  // 亮度：逐像素
  for (let j = 0; j < h; j++) {
    for (let i = 0; i < w; i++) {
      const p = (j * w + i) * 4
      const r = rgba[p], g = rgba[p + 1], b = rgba[p + 2]
      out[j * w + i] = clamp(0.299 * r + 0.587 * g + 0.114 * b)
    }
  }

  // 色度：2x2 下采样，先把四像素 RGB 平均再换算，避免边缘串色
  for (let j = 0; j < uvH; j++) {
    for (let i = 0; i < uvW; i++) {
      let r = 0, g = 0, b = 0
      for (const [dx, dy] of [[0, 0], [1, 0], [0, 1], [1, 1]]) {
        const p = ((j * 2 + dy) * w + (i * 2 + dx)) * 4
        r += rgba[p]; g += rgba[p + 1]; b += rgba[p + 2]
      }
      r /= 4; g /= 4; b /= 4
      out[uOff + j * uvW + i] = clamp(-0.169 * r - 0.331 * g + 0.5 * b + 128)
      out[vOff + j * uvW + i] = clamp(0.5 * r - 0.419 * g - 0.081 * b + 128)
    }
  }
  return out
}

把帧写进编码器

import { spawn } from 'node:child_process'

export function createEncoder(out: string, w: number, h: number, fps = 30) {
  const ff = spawn('ffmpeg', [
    '-f', 'rawvideo', '-pix_fmt', 'yuv420p', '-s', `${w}x${h}`, '-r', String(fps), '-i', '-',
    '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '20',
    '-pix_fmt', 'yuv420p', '-colorspace', 'bt709', '-color_range', 'tv',
    out,
  ])
  return {
    write: (plane: Uint8Array) => ff.stdin.write(plane),
    end: () =>
      new Promise<void>((resolve) => {
        ff.on('close', () => resolve())
        ff.stdin.end()
      }),
  }
}

背压要点：ff.stdin.write() 返回 false 时说明管道满了，必须等 drain 再写下一帧，否则内存会被帧数据堆爆。

偏色的三个根因

现象	根因	修法
整体发灰、黑色不黑	range 不一致（把 pc 当 tv 解码）	声明 `-color_range`，或用 `scale=in_range=full:out_range=tv`
肤色偏绿 / 偏紫	矩阵用错（把 601 当 709 解码）	统一 `-colorspace bt709`，或 `scale=in_color_matrix=bt709:out_color_matrix=bt709`
大面积色带、渐变断裂	8bit + 高压缩 + 无抖动	降低 CRF、用 10bit 中间格式、加 `dither`

一句话：Canvas 出来是「pc range + sRGB」，H.264 分发一般是「tv range + BT.709」，两头必须显式对齐，靠播放器猜一定偏色。

14.8 前端与 AI 场景落地

浏览器能力对照

能力	API	能做什么	限制
录制	`MediaRecorder`	摄像头 / 屏幕 / Canvas → WebM	码率控制粗，格式受限
逐帧编解码	`WebCodecs`	`VideoEncoder` / `VideoDecoder`	Chrome 94+，Safari 覆盖不全
播放	MSE + hls.js	拉 HLS / DASH	低延迟需 LL-HLS
转码	ffmpeg.wasm	浏览器内跑 FFmpeg	慢、吃内存，需要 COOP/COEP 响应头
采集	`getUserMedia` / `getDisplayMedia`	摄像头 / 屏幕	需权限，移动端限制多

四类真实场景

上传前压缩：弱网下先在本地降码率（WebCodecs 或 ffmpeg.wasm），服务端再统一转标准档，减少带宽也减少排队。
AI 视频理解：抽帧 → 多模态模型。不要按固定 fps 猛抽，先做场景切换检测再抽，帧数能降一个量级。
AI 视频生产的后处理：模型返回的分片 → concat 拼接 → 统一转码 → 生成封面与字幕。
录屏 / 会议回放：MediaRecorder 出 WebM → 服务端转 HLS 切片 → CDN 分发。

给多模态模型抽帧的两条命令

# 每 2 秒一帧，缩到 512 宽（控制 token 成本）
ffmpeg -i in.mp4 -vf "fps=1/2,scale=512:-2" -q:v 3 frames/%04d.jpg

# 按场景变化抽帧，去除大量重复画面
ffmpeg -i in.mp4 -vf "select='gt(scene,0.4)',scale=512:-2" -fps_mode vfr frames/%04d.jpg

14.9 踩坑与经验

参数位置错 → 静默失效：输出参数写在 -i 之前会被当成输入参数，命令照样成功，结果完全不对。
copy 切片起点不准：只能在关键帧切，起点会前移；要精确就重编码。
压完反而更大：源已是高压缩低码率，再压只会更差；或根本是 -b:v 设得比源码率还高。
奇数分辨率报错：yuv420p 要求偶数，用 scale=1280:-2，必要时补 pad=ceil(iw/2)*2:ceil(ih/2)*2。
Web 上拖进度条很久才出画：缺 -movflags +faststart，moov 在文件末尾。
Windows 下滤镜报参数错：路径冒号写 C\:/，表达式逗号写 \,。
批量任务不要拼 shell 字符串：用 execFile('ffmpeg', [...]) 传数组，避免空格与注入。
并发要限流：x264 默认吃满所有核，N 个并发必须 -threads 或队列串行，否则整机卡死。
失败了先看 stderr 末尾：-loglevel error 只留关键报错，比翻几百行 banner 快得多。
转码是 IO + CPU 双高：容器里要限 CPU、给足临时盘、设超时，避免僵尸任务堆积。

一句话总结：换不换容器看 -c copy，画质好坏看 -crf 与 -pix_fmt，复杂效果看 -filter_complex，偏色看 color_range 与 colorspace。

十五、附录

15.1 学习资源索引

平台与产品

模型与部署

Ollama · deepseek-r1 · qwen3:0.6b · mxbai-embed-large · qwen3-vl:2b
Docker

协同与编辑器

数字孪生与三维

IBM 数字孪生：https://www.ibm.com/cn-zh/think/topics/digital-twin
Mars3D 模板：https://www.mars3d.com/template
易知微数字孪生低代码：https://easyv.cloud
glTF：https://github.com/KhronosGroup/glTF
Cesium：https://cesium.com/ · OpenLayers：https://openlayers.org/ · Three.js：https://threejs.org/
3D 建模 Blender：https://www.blender.org/
天地图：https://www.tianditu.gov.cn/
QGIS（免费开源，生成瓦片）：https://www.qgis.org/

工程化

LangChain 生态

音视频与 FFmpeg

15.2 本机案例路径索引

主题	路径
AI 引擎全栈	`E:/practice/demo/1.ai-engine`
服务端 AI 编排	`E:/practice/demo/1.ai-engine/apps/server`
Prompt / 结构化输出	`E:/practice/demo/1.ai-engine/1.prompt.js`、`E:/practice/demo/1.ai-engine/9.structure.js`
TS / Zod 示例	`E:/practice/demo/1.ai-engine/10.typescript.ts`、`E:/practice/demo/1.ai-engine/11.zod.ts`
多模态 Agent	`E:/practice/demo/1.ai-engine/12.agent-image.ts`
服务型工作流引擎	`E:/practice/demo/1.ai-engine/13.flow-engine.ts`
监控 SDK 单体	`E:/practice/demo/案例/ai-monitor`
监控 monorepo 全栈	`E:/practice/demo/案例/ai-monitor-ful`
监控 AI 分析服务	`E:/practice/demo/案例/ai-monitor-ful/packages/ai`
监控 + AI 巡检	`E:/practice/demo/案例/ai-inspect`
编辑器三路线	`E:/practice/demo/案例/simple-editor/{contenteditable,execCommand,selection}.html`

十六、面试题库

用法：先看题干自测，能说出「骨架」再看要点。每题后附 → §x.x 指向正文的详细展开。
题目按 初中级 → 中高级 → 专业级 → 专家级 递增排列，共 48 题。

16.1 初中级（16 题）

Q1｜说说你对生成式 AI 应用引擎的整体理解和业务流程

本质：把 LLM、Agent、插件、工作流、触发器、知识库、记忆整合成一个平台。
六大模块：插件化抽象复用逻辑 → 工作流自动化编排 → 触发器驱动 → 知识库检索 → 记忆维持上下文 → 输入输出闭环。
业务流程：用户输入 → 引擎编排 → 模型 / 知识库 / 插件协同 → 流式输出。
三种前端集成方式：iframe、API、Agent 商城式发布。
→ §3.4、§2.2

Q2｜是否有过自动化、批处理或生成式 AI 相关业务？说说对流程引擎的理解和整体方案

自动化 / 批处理核心：重复性任务、抽象层次高，把期望的任务列成步骤逐步执行。
生成式 AI 的区别：用户控制整个流程，AI 去具体实现（搜索 → 提关键字 → 清洗 → 给模型分析 → RAG 优化 → 循环 → 判断）。
流程引擎三要素：流程建模（编辑器）、任务调度（异步 / 依赖 / 变量上下文）、插件化集成外部系统。
实现分型：内存型（前端全量执行）、服务端型（OA 审批、低代码、大数据平台）、生成式 AI 引擎（调模型、参数召回、上下文缓存、向量库操作）。
→ §6.1、§6.6

Q3｜开发一个类似飞书文档的知识库，文档编辑如何设计？重点说原理与技术实现

核心清单：基础编辑、文本格式化、多媒体插入、undo/redo、跨浏览器兼容、协同、AI 赋能。
三条技术路线：contenteditable 裸做 → execCommand（过时）→ Selection + Range + Compiler（推荐）。
Compiler 解决的核心问题：反复点击导致标签无限嵌套，需要判断已有修饰并做「加强 / 还原」。
数据层：Markdown 路线性能好约束强；JSONContent 路线更灵活，自定义节点方便（TipTap custom node）。
通用协议：Schema / DSL 承载物料体系（BlockSuite）。
个性化：/ 命令、@ 提及、协同光标、力导向图谱、命令栈 undo/redo。
→ §7.2、§7.3

Q4｜了解过服务端渲染吗？为什么当下 AI 辅助编程首选服务端渲染方案？

先讲演进：EJS/JSP → SPA → SSR + SPA 结合。
再讲 AI 特殊性：追求短平快（全栈一体）、隐私与安全（token 不能落前端，否则可被任意调用）、动态与个性化。
三点优势：体验（首屏）、减轻客户端压力、降低维护成本。
补充类比项目：Coze、Dify 这类平台，以及 v0、bolt 这类生成式产品。
→ §8.1、§8.2、§8.3

Q5｜简单描述协同文档编辑器的方案和核心实现

分层：编辑器内核（TipTap / ProseMirror）+ 协同算法（CRDT / OT）+ 具体实现（Yjs / Automerge）+ 传输（WS / WebRTC）+ 服务层（Node / NestJS / Redis / Kafka）+ 存储（PostgreSQL + pgvector）。
关键判断：CRDT 分布式友好，OT 依赖集中式；Yjs 是当前首选。
实现五步：建 Y.Doc → 绑定编辑器 → 实时通信 → 光标同步（Awareness）→ 后端接入。
依赖清单要能报出来：@tiptap/extension-collaboration 是绑定层。
→ §7.4、§7.5

Q6｜有没有做过 AI 相关业务？说说 AI 大模型应用开发的核心方向和重要技术点

三个方向：AI 原生应用、AI 赋能已有业务、AI 应用开发平台。
四大技术：LLM（概率预测、涌现、上下文依赖；基础模型 vs 微调模型）、Prompt 工程（角色 / 思维链 / 结构化输出 / 指令数据分离）、RAG（索引 + 查询两阶段）、Agent（ReAct + 工具 + 过程可视化 + 交互干预）。
选型三关注：上下文窗口、成本（token 计费）、响应速度。
前端两个黄金点：流式渲染、引用溯源。
→ §3.2、§2.3、§2.4、§4.1、§4.2

Q7｜做过前端监控？性能与异常监控指标是怎么算的？

性能：PLT、FP/FCP、FMP、LCP、TTI、CLS（≤0.1 良好）、INP。
异常：JS 运行时、Promise unhandled rejection、资源加载、接口请求、React/Vue 框架异常。
行为：PV、UV、点击/操作、停留时间；新老用户用 Cookie 标记。
上报：fetch/XHR（CORS 解决跨域）、图片打点、sendBeacon。
工程化指标：构建时间、缓存利用率。
→ §9.1、§9.2

Q8｜前端 AI 这块做过什么？了解过私有化 AI 平台部署和应用吗？

回答框架：技术广度 + 工程化能力（私有化部署）+ 业务思考。
硬前置：CPU ≥ 2 核、内存 ≥ 4G，装 Docker。
两条路：Coze Studio（Docker Compose 拉源码部署 + 配豆包 API Key/Endpoint）；Ollama + Dify（本地模型 + 向量库）。
关键坑：容器里的模型 URL 不能写 localhost，要用局域网 IP。
收尾升华：从「平台构建者视角」讲清人设、插件、知识库、工作流如何协作。
→ §3.5

Q9｜对 LangChain.js 这类框架有了解吗？用它搭过 Agent 吗？怎么看它降低门槛？

先答「不用框架的七个坑」：模型适配、tool calling、ReAct 循环、输出形态、MCP 远程工具、提示词优化（compact + skills）、生态。
框架的价值：把这七件事封装成标准抽象。
小 Demo 技术栈：TS + Node（脚本 → 服务化）+ Ollama + LangChain.js。
方法论：问题分析 → 方案设计（MVP，抓主要矛盾）。
→ §5.1

Q10｜你 TS 掌握得怎么样？TS 与 Zod 为什么在 Agent 开发中应用广泛？前端往 Agent 能有哪些沉淀？

TS：编译时静态检查，约束框架契约与协议数据结构。
Zod：运行时校验，做入参标准、输出结构化、参数提取 schema、工具入参防护。
TS 重点：基础类型/别名/接口、联合与交叉（面向协议编程）、类型守卫（类型收敛）、工具类型（Omit/Pick/Partial）、泛型与类型体操。
前端三点沉淀：TS AI SDK 工程化、Node/Nest/Nuxt 服务化、Prisma + PostgreSQL 持久化。
→ §13

Q11｜有没有参与过工作流编辑器开发？简述工作流类型、技术选型与实现细节

三种类型：线性流、DAG（AI 最常用，严禁环路）、状态机流。
选型：SVG（React-Flow/X6，首选）vs Canvas（LogicFlow/LiteGraph，超大规模）vs 纯 DOM（上手快但连线难写）。
四个细节：数据协议（兜底/降级/拓展/升级）、引擎实现三选一、节点边物料体系（插件化/微内核）、协同 + 执行（建图、遍历、异步、日志、错误收集）。
面试建议：以 React-Flow / AntV X6 切入，强调可定制插件系统。
→ §6.2、§6.5

Q12｜了解过什么服务端框架？最快实现 AI 全栈 POC，技术栈怎么选？

先分清 POC 与 MVP：POC 验证可行性、低成本试错、用于演示立项；MVP 在 POC 上补登录/页面/异常处理/打包 Docker，能交付测试。
前端：HTML/CSS（Tailwind）/TS + Zod/React/Next.js。
AI：LangChain.js / LangGraph.js / DeepAgent.js。
数据：PostgreSQL + Prisma。
部署：Docker，脱离平台绑定。
四层架构图：前端交互层 → AI 核心能力层 → 数据持久化层 → 部署环境层。
→ §5.6、§12

Q13｜了解 monorepo 架构？为什么大厂和开源项目都青睐这种架构？

定义 + 四特点：单一仓库、多项目共存、统一依赖、原子化提交。
解决四痛点：复用、依赖管理、跨项目原子性、规范分散。
对比 Polyrepo：改库要发 npm 包，调试链路长。
例子：Google、Vue 3、React、字节/美团/阿里的中台。
→ §10.1、§10.2

Q14｜基于 Node.js + TypeScript 以及 monorepo 的架构设计思路

先讲必备知识点：monorepo 组织、规范（eslint/stylelint/cspell/commitlint）、构建（vite/esbuild/webpack）、测试（jest/vitest/playwright）。
再讲优势四条（对应四个痛点）。
搭建三步：定 pnpm-workspace.yaml → 分子包（apps / packages）→ 配 tsc 编译与 dev 启动脚本。
强调「里层包共享外层包依赖」可省依赖声明。
→ §10.6、§10.5

Q15｜对 AI 智能体的理解：Coze 类工作流智能体、Manus 通用智能体、垂类智能体的区别

本质公式：Agent = LLM + Planning + Memory + Tool (+ MCP/Skills)。
Coze 类：DAG 确定性编排，人定规则 AI 填充，可控无风险。
Manus 类：LLM Planning 主导，人定目标 AI 定规则，路径不确定。
垂类：特定 Schema/场景优化，领域知识 + 专用工具 + 场景交互。
选型决策树：流程是否固定 → 是否需强可控 → 是否跨多场景。
→ §4.2、§4.4

Q16｜尝试过 Vibe Coding 吗？了解哪些模型和工具？怎么解决 AI 生成代码混乱？

一句话答案：上下文清晰控制策略。
两个抓手：开发手册（含 eslint/prettier 约束）+ 清晰规划（方案、步骤、风险、测试用例、反思）。
SOP：Plan → Coding → Lint → 开发隔离（新特性、设计文档、实施文档分开）。
工具：Claude + Codex。
→ §12.1

16.2 中高级（16 题）

Q17｜对智能体与生成式 AI 应用引擎业务的理解，以及具体落地实现

答题结构必须是：业务流程 → 核心架构 → 核心实现方案。
核心模块五项：插件、工作流、触发器、知识库、记忆 + 输入输出。
落地重难点五项：编排编辑器、节点执行沙箱、日志系统、错误处理、服务化。
学习捷径：Coze 生态更健全（功能与插件），Dify 模型选择更多。
→ §3.4、§3.4 重难点

Q18｜有低代码 / AI 应用引擎经验，说说流程引擎编辑器和执行的具体实现

编辑器定义：图形化界面 + 可视化操作（拖拽、配节点）+ 产出工作流蓝图；选型 React：xyflow / x6，Vue：vue-flow。
执行器定义：按蓝图实际运行，负责节点执行（含异步节点）、异步正确性与回调、流程监控与反馈。
内存型实现三步：约定协议（节点+边）→ 编辑器编排 → 执行器按序执行（链表串联上下文）。
三项生产级增强：异步日志系统、全局上下文变量池、四级错误处理（全局捕获 / 节点级 / 通知 / 恢复重试）。
→ §6.5、§6.7

Q19｜很多工具类产品都有协同编辑，说说协同编辑器的核心架构与方案

总纲：协同前置，协议先行。
盘点产品：富文本、可视化图表、白板、视频剪辑、AI 应用引擎、多维表格。
传输协议：WS、Socket.IO。
数据分两类：交互式（头像/光标，业务无关）、核心业务数据。
冲突方案：CRDT（面向状态 / 面向操作）与 OT。
Yjs 代码要能讲：Y.Doc + WebsocketProvider + yText 的删增同步；后端 setupWSConnection。
落地五步：协议统一 → 存 Yjs Doc → 增量同步 → 传输选型 → 双通道协同。
→ §7.4、§7.5

Q20｜详细说说 SSR、SSG 以及前后端同构，有没有了解过 Next / Nuxt，简述原理

三者概念 + 特性对比（首屏、SEO、内容变动频率）。
Next 请求五步：请求 → 服务端渲染（getServerSideProps）→ 返回 HTML → React 水合 → 前端渲染接管。
App Router：约定式路由（文件夹 + page.tsx）、Server Component 优先、Hook 只能在 "use client" 组件里用。
动态路由 [id] + useParams / useSearchParams。
API：app/api/route.ts 按 HTTP 方法导出具名函数。
→ §8.2、§8.4

Q21｜协同业务很多，文档、代码、数字孪生低代码编辑器的协同如何架构并落地？

统一公式：视图层 + 数据模型（Yjs）+ 绑定层 + 通信层。
文档：TipTap + Yjs + y-websocket。
代码：CodeMirror + Yjs + y-codemirror.next + y-websocket。
数字孪生：Vue3 + WASM + VanillaJS；核心是结构化数据（组件树、场景图、节点属性）。
数字孪生四重难点：坐标变换、吸附算法性能、状态双向同步、内存与渲染性能。
设计模式：观察者、策略、工厂。
算法：智能吸附 + 网格吸附。
→ §7.6

Q22｜AI 大模型应用开发的完整流程？如果要架构设计一个 AI 应用，你的思路？

四步：本地模型部署（Ollama + Qwen3）→ LangChain 三件套 → Node 脚本化（Prompt / RAG / Agent）→ 服务化。
架构图四层：用户端 → BFF/API → AI 编排层 → 模型服务 + 数据访问层。
数据层选型：PGVector / Milvus。
强调「脚本先跑通，再服务化」的开发节奏。
→ §5.6

Q23｜设计过大型实时数据流系统？详细说明监控平台的方案设计与落地

开场只讲核心方案概览（一句话覆盖全链路）。
五段：端侧采集 → 接入缓冲（Nginx → NestJS → Kafka）→ 流式计算（Flink/Spark）→ ClickHouse → 可视化与预警。
上报分级：fetch 批量（HTTP/2 多路复用）、sendBeacon（页面关闭不丢）、WebSocket（低延迟双向）。
Monorepo 拆分：apps/demo、packages/metrics（tsup 打包）、packages/ai，用 workspace:* 引用。
Kafka：按热度拆 Topic、按 session_id Hash 分区保时序。
ClickHouse：MergeTree、按月分区、LowCardinality、Map 扩展字段、TTL；禁止单条插入，5000 条或 5 秒批量。
→ §9.3、§9.4

Q24｜基于 TypeScript 落地 AI 大模型应用开发的最佳实践与核心重难点

四件套：TS + LangChain.js + Ollama 私有化 + pgvector。
依赖要说准：langchain、@langchain/community、@langchain/core、@langchain/ollama、pg。
三类踩坑：ESM（"type": "module" + nodenext）、@types/node 不生效（配 types: ["node"]）、MemoryVectorStore 迁到 @langchain/classic。
结论：TS 生态已足够承载 AI 应用，前端可直接全栈。
→ §5.6、§13.3

Q25｜聊聊 LangChain 标准化模型接口对避免供应商锁定的价值，以及 LangChain 与 LangGraph 如何选型、如何做可解耦可演进的 Agent 分层架构

标准化：BaseLLM / ChatModel 抹平协议、参数、返回结构差异；换模型只换实例化，不动业务代码；支持多供应商混合调用。
选型：线性轻量 → LangChain；非线性、多角色、状态持久化 → LangGraph。
分层四层：接口层 → 原子能力层（Zod 校验）→ 编排层 → 业务层，依赖倒置。
补充沙箱两层：微前端沙箱（legacy/proxy/snapshot）解决样式与 JS 隔离；系统级沙箱解决环境隔离。
→ §5.2、§5.3、§5.4、§6.10

Q26｜基于 TypeScript 搭建 AI Agents 基础框架（参考 LangGraph 核心能力），说核心设计与关键代码

先定能力边界：文生文/图/视频、图生图/视频、文生 PPT、文生 UI。
模型选型要能报出国内外对照。
智能体类型三分 + 是否私有化（Ollama、Whisper）。
框架核心：状态（State）+ 节点（Node）+ 边（Edge），Zod 做入参与输出结构化。
生态事实：主流框架都同时提供 Python 与 TS 版本。
→ §2.5、§4.4、§13

Q27｜怎么实现通用工作流编辑器与工作流执行引擎？说说内存型与服务型的顶层设计

对比四维度：执行环境、状态存储、适用场景、核心挑战。
内存型：事件驱动，加载整图进内存，递归/循环消费任务队列；关键在快照同步与轻量化。
服务型：任务队列 + 状态机持久化（类 Temporal/Camunda）；三步走——任务解耦（MQ）、Worker 消费、状态脱水与复活（挂起时序列化上下文入库，触发后 Hydrate）。
必须处理分布式事务与超时重试。
→ §6.6

Q28｜基于 Next.js、Docker、Prisma、LangChain.js 快速实现 AI Agents 应用基础架构

三条主线：基础交互层架构、前后端联调打通、容器化。
命令链：pnpm create next-app@latest → 装 langchain/prisma/dotenv → npx prisma init → 配 docker.compose.yml → prisma generate。
Docker 安装注意：--accept-license、--installation-dir、--wsl-default-data-root，默认安装需重启。
收尾：.env 配置、建表、起服务。
→ §8.4、§5.6

Q29｜设计一个 AI 前端驱动的全栈应用，pnpm monorepo 的架构细节

结构：apps/web + apps/server + packages/{configs, ai-engine, utils, types, shared}。
子包被引用四前提：入口文件、导出模块、入口导出方法、package.json 的 module 指向入口。
引用写法："@monorepo-project/configs": "workspace:*"。
每个子包都要打包（tsup）。
收益：前后端共享数据契约，改完立刻生效。
→ §10.5、§10.6

Q30｜主导公司 AI 应用赋能部分产品的全栈开发，说详细结构与核心流程拆解

先盘点可被 AI 协助的模块：CRM 数据分析、开发提效（自动审查）、Code Review 自动化、BI 报表（ChatDB + RAG）、后台管理与客服助手。
五条设计原则：业务目标对齐、最小化侵入、可观测性、迭代式演进、模型无关性与数据隐私。
宏观架构：前端 → BFF/API → AI 核心编排（LangChain.js）→ 数据访问（PG + pgvector）→ 模型服务（Ollama）。
流程四阶段：业务定义与场景选择 → 技术选型与 POC → 智能体编排 → 服务化接入。
交互两种：blocking / streaming。
→ §3.2、§5.6

Q31｜用类似 Claude 的工具，如何实现一个系统级 AI 智能体？基于 LangChain + Commander 说思路

前置：ReAct 闭环（Thought → Action → Observation → 循环）+ 工具调用机制。
工具三要素：Name、Description（决策依据）、Args Schema。
技术栈五件：Commander.js（CLI）、Node.js（运行时）、NestJS（服务层）、Next.js（可视化）、LangChain.js（编排）。
分层架构五层：前端交互层 → 服务编排层（API + WS）→ Agent 核心层（Agent / Memory / Tool Registry）→ 工具执行层（FS / 系统命令 / 代码执行 / 三方 API）→ 存储层（SQL + 向量库）。
→ §4.2、§4.3、§5.4

Q32｜基于 Vibe Coding 完成亿级协同表格全栈开发，怎么搞定性能瓶颈与代码质量？

三层约束：全局约束 → .clauderules → .plan。
.plan 用 STAR-L 法则（需求、方案、步骤、性能瓶颈、优化细节）+ 顶层数据协议抽象。
按特性拆：渲染引擎（千万行流畅）、公式引擎、WebWorker 多线程、协同（Yjs/OT + 协同服务 + 传输协议）、界面（登录 + 渲染）。
SOP 六步 + MCP 配套（deepwiki 查资料、context7 查上下文、playwright 集成测试、zcf 管模型与 MCP）。
→ §12.2、§12.3

16.3 专业级（13 题）

Q33｜开发一个类似 Coze 的企业内部 AI 开发平台，整体架构设计与核心点

核心点五项：LLM 接入、流程引擎编辑器（@xyflow/react）、工作流节点抽象、执行沙箱（Python）、业务侧服务端。
技术架构五条：模型接入（DeepSeek）、模型配置（复杂表单 react-hook-form）、上下文维持（PostgreSQL 向量）、流程编排（xyflow）、双端沙箱（前端 JS 低代码 + 服务端）。
一句话主线：编辑器 + 协议 + 执行器 + 沙箱 + 服务化。
→ §6.5、§6.7、§6.8

Q34｜要构建一个完整的生成式 AI 应用引擎，平台生态体系如何实现？

六大模块 + 六类节点 + 执行流程 + 三项优化（缓存、错误处理、并发执行）。
节点清单要完整：开始 / 模型 / 插件 / 业务逻辑 / 子工作流 / 结束。
执行流程：输入接收 → 节点顺序执行 → 数据传递 → 结束节点返回。
优化三条：高频插件加缓存、节点级错误兜底、可并行节点并发执行。
→ §3.4、§6.3

Q35｜从零到一将已有产品 AI 智能化，详细说明架构与实践流程

先做场景盘点：AI 应用引擎、文档 AI 助手、表格助手、低代码托管、智能客服、销售运营链、AIGC 产品。
六步开发流程：梳理业务关键节点 → 匹配模型 → 智能体/复合智能体搭建 → 技术实现（LangChain / LlamaIndex 或类扣子平台）→ 能力服务化 → 能力接入。
智能体编排两条路：低代码编排式 / 代码式（LangChain、LlamaIndex）。
交互方式：blocking / streaming。
→ §3.2、§5.6

Q36｜作为前端 Leader，从零到一设计服务端渲染体系，并完成老 SPA 重构，详述设计与实践

四要素：路由系统、SSR/SSG 选择、数据获取与传递、客户端水合；配 React hydrate / renderToString。
技术要点：Vite + React + Express + renderToString + hydrate。
重构路径五步：路由收敛 → 数据预取层上移 → 样式提取 → 状态序列化注入 → 灰度切流。
加分：能说出自研框架（类 Next）的目录与职责。
→ §8.5

Q37｜作为前端 Leader，设计类 Dify AI 应用引擎平台的完整闭环；公司 AI 项目从立项到落地你参与了多少？

用「立项阶段 + 研发落地阶段」双段式，每段分业务产出与技术产出。
业务产出用数字说话：审查时间 45 min → 15 min、满意度 95%、V2 Roadmap。
技术产出要具体：文档-视图-控制器分层、虚拟滚动、文本坐标体系做像素级高亮、流式解析与错误恢复。
沉淀：react-ai-stream-parser 组件库 + 《前端 AI 应用开发规范》。
→ §16.6 案例 A（完整模板）

Q38｜中大厂的前端 AI 化：基于 LangChain.js 与 Qwen-VL 的多模态根因分析引擎如何实现？

链路：监控数据 + 录屏/截图（rrweb）→ 多模态模型（qwen3-vl:2b）→ 根因定位 → 定位到代码 → 自动修复提 PR。
关键设计：把团队开发规范与流程投喂给模型；历史故障做 RAG；多模态输入按「文本 + 图像 + 视频」三类设计。
本地调试闭环：Ollama 起模型，先跑通再上服务。
→ §9.6

Q39｜如果让你负责 Coze 开发，说架构思路、微服务架构、关键业务流程与插件生态

起点：coze-studio 是「单体作坊」（Docker Compose 打包），面向企业/公有云必须转「工业化生产线」（云原生 + 微服务）。
理念：一个中心，四大体系（编排执行引擎；应用构建、插件生态、多租户数据、可观测运维）。
六个微服务：API 网关、用户租户中心、Bot 配置中心、插件市场、数据与向量服务、AI 编排执行引擎（gRPC 内部通信）。
两大重难点：前端 DAG 编排（状态管理、序列化、实时调试）；后端流式执行引擎（拓扑排序、异步非阻塞、流式处理、安全沙箱）。
→ §6.8、§6.9

Q40｜基于 openclaw 的分层架构理念，实现含 Agent Loop（工具调用 + 流式输出）的最小可运行骨架

五层表要能背：集成层（Ollama + 流式协议）、知识层（内存 + 文本拆分，预留 PG）、工具层（d3-dsv + Zod）、Agent 编排层（Agent Loop）、UI 层（Express SSE）。
三条核心逻辑：SSE 流式对接模型 stream、AgentExecutor 闭环、最小依赖可运行。
强调「预留接口但不实现」的克制，这是 POC 的正确形态。
→ §5.5

Q41｜实现一个对标 LangGraph 的 TypeScript AI Agents 框架，说架构、模块划分与源码级难点

前置：图论基础（节点、边、有向图）。
六要素：状态机驱动、图执行引擎、异步安全与竞态避免、状态持久化与 Checkpoint、子图嵌套、执行监控与调试。
难点按序展开：拓扑排序与并发调度、状态快照与恢复、断点续跑的幂等性、错误重规划。
→ §5.5

Q42｜如果你是 n8n / Dify / 扣子平台的作者，说工程化架构与编辑器执行器落地的完整链路

五步：定义 DSL → 编辑层（状态管理 + 插件化）→ 执行器（拓扑排序、动态调度、沙箱隔离）→ AI 特化（变量提取、上下文流转、流式输出）→ 工程化闭环（测试）。
每步都要能补一句「为什么这一步不能省」。
→ §6.4、§6.9

Q43｜假如你是 LangChain.js 框架，从零到一设计一个 AI Agent 开发框架，说架构与核心实现

分层：接口层（Model / Tool 抽象）→ 原子能力层（Prompt、Splitter、Parser、Retriever）→ 编排层（Chain / Graph 执行器）→ 扩展层（插件、MCP、Skills）。
关键决策：为什么要标准化接口（换供应商不动业务）、为什么要有两种编排（线性 vs 图）、如何做流式与回调（Callback + Stream）。
→ §5.2、§5.5

Q44｜字节、阿里等中大厂基于 monorepo 的 AI 全栈工程架构最佳实践，做多模态应用有哪些关键节点？

四步：确定业务（文生文/图/视频、text2sql、text2code、混排、自动剪辑、数字人）→ 选模型（自部署 / SaaS）→ 规划链路（workflow or agent）→ 选技术栈（前端框架、服务框架、PG + ORM、容器编排、AI 层）。
monorepo 收益要落到「数据契约不失联」上。
加分：能说出 Turborepo 的增量构建与远程缓存机制。
→ §10.4、§10.5、§2.5

Q45｜给你一个小时，用 Vibe Coding 从零交付一个类飞书亿级协同在线表格应用

三份文档递进：项目规划 → 新特性开发规范 → 核心功能计划（指明技术实现）。
核心功能要具体：Canvas 底层绘制 + 遮罩 div 借用滚动条做可视区渲染 + 单元格插件化协议；Next.js + shadcn + Tailwind；Prisma + PostgreSQL；docker compose 起基础设施。
收尾：测试 + lint + 检查规划执行偏差。
→ §12.3、§12.4

16.4 专家级（3 题）

Q46｜站在前端架构师角度，说明协同编辑器原理、Yjs 实现，以及 CRDT / OT 的概念与实现

从「一致性」这个目标切入，再讲两大理论。
OT：中心服务器 + 版本校验 + Transform(OpC, OpA) 转换（要能画出时序图）。
CRDT：生成 Update → 中转 → 本地合并；面向状态 vs 面向操作。
Yjs 五特性：Item + 双向链表、全局唯一 ID + 逻辑时钟、确定性排序、Tombstone、Struct 二进制编码。
优缺点各两条（元数据开销、意图保留问题）。
结论：首选 CRDT，OT 在敏捷、高可用、离线体验面前已不合时宜。
附带技术储备：算法、3D 数字孪生（WebGL/WASM、正射影像与倾斜摄影、Tile 与模型处理、PBR 与粒子）、全面性能优化（打包构建、资源、应用、缓存四层）。
→ §7.4、§7.5

Q47｜假设你是架构师，实现企业内部类 Coze / Dify 垂直业务 AI 应用开发平台，说明需求及实现

需求侧：先讲清业务痛点与角色（业务方、开发者、运维），再落到功能清单。
平台侧：插件机制（统一接口 + 协议生态）、工作流机制（节点顺序执行）、触发器机制、知识库节点。
节点体系与「如何选节点」四原则：任务类型、模块化、依赖关系、性能考虑。
编辑器三能力：拖拽节点、设置属性、连接节点。
最后用完整项目案例收尾（立项 → 研发 → 沉淀）。
→ §3.4、§6.3、§16.6 案例 A

Q48｜开发类似 openclaw 的系统级 AI 智能体，有明确实现方案吗？怎样让 AI 在企业工作流真正落地？

模块化：monorepo（shared / plugins / web / cli / core），core 内含 agent、plugin-system、utils。
五模块职责与扩展点：cli（多命令、交互配置）、core（沙箱、权限、长程记忆、可观测）、plugins（市场、权限分级、MCP 适配）、shared（统一 Schema、错误码、通信协议）、web（任务看板、执行追踪、人机干预、多租户）。
插件三件事：定义规范、扫描加载注册、动态注入。
企业级升级六项：权限管控（RBAC/ABAC）、安全沙箱（vm2/isolated-vm）、长程记忆（向量库）、可观测（日志/追踪/监控）、多模态感知（视觉/文档解析）、API 网关。
标准演进：MCP（统一工具与上下文协议，插件系统既可是 Client 也可是 Server）+ Skills（预定义多步流程与 Prompt 模板组合，含 SKILL.md + scripts + references）。
落地四条能力：脚手架、服务端、前端界面、AI 应用引擎层。
→ §4.6、§5.4、§5.5

16.5 高频追问速答表

追问	一句话答案
CRDT 还是 OT？	首选 CRDT：去中心化、支持离线、服务端轻；OT 转换函数太复杂且强依赖中心服务器
内存型还是服务型工作流？	前者快、无持久化，适合前端预览；后者可断点续传、能人工审批，适合长链路业务
SSE 还是 WebSocket？	单向流式推送用 SSE（简单、自动重连）；需要双向或低延迟交互用 WS
pnpm 为什么快？	硬链接只存一份 + 非扁平结构屏蔽幽灵依赖
Turborepo 凭什么快？	任务管线 + 本地/远程缓存命中，只重跑受影响的包
ClickHouse 为什么适合监控？	写多读少、按时间聚合；列存 + 向量化执行，亿级 Group By 秒级出结果
为什么要 Kafka？	解耦生产与消费速度，削峰填谷；按 session 分区保时序
为什么选 SSR 做 AI 应用？	token 不能落前端 + 首屏与 SEO + 全栈一体提效
沙箱怎么选？	强隔离用 Docker（慢）、轻隔离用 WASM（快）、进程内用 vm2/isolated-vm（需谨慎）
前端在 Agent 里的不可替代性？	过程可视化、人机干预、流式渲染、引用溯源——全是前端活
LCP / CLS / INP 分别衡量什么？	加载性能 / 视觉稳定性（≤0.1）/ 交互响应速度
LangChain 和 LangGraph 怎么选？	线性简单用 LangChain，有状态、分支、循环、可恢复用 LangGraph
为什么提示词要结构化输出？	免去字符串解析，直接绑定状态，前端最实用的一招
低代码为什么能约束 AI？	DSL 相当于给 AI 加一层枷锁，生成物可被编译器校验后再执行

16.6 案例 A：项目介绍模板（可直接背）

适用于「公司 AI 项目从立项到落地你参与了多少」这类题。结构固定：立项阶段（业务产出 + 技术产出）→ 研发落地阶段（业务产出 + 技术产出）→ 技术资产沉淀。

作为前端 Leader，我深度参与了公司级 AI 项目「智能合同分析助手」的全链路过程，主要产出如下：

立项阶段（参与度 80%）

业务产出：
- 与法务、销售团队共同做需求访谈，识别核心痛点：审查效率低、风险点易遗漏。
- 主导编写产品原型与交互设计稿，通过可交互 Demo 向管理层展示核心价值与体验，成功推动立项；强调「信息高亮」「风险可视化」「人机协同修订」等前端交互价值点。
技术产出：
- 技术预研（PoC），与后端架构师共同验证「RAG + 少量微调模型」方案的可行性。
- 输出《前端技术选型报告》，确定 React + SSE 技术栈，并预估人力成本与时间线。

研发与落地阶段（参与度 100%）

业务产出：
- V1 上线后，法务团队单份合同平均审查时间从约 45 分钟缩短至约 15 分钟。
- 上线「风险条款一键定位与解释」功能，用户满意度约 95%。
- 与产品经理共同制定 V2 Roadmap，规划「多版本合同对比分析」等高级功能。
技术产出：
- 主导前端架构：采用「文档 - 视图 - 控制器」分离。文档层负责与后端流式接口通信并管理原始数据；视图层高效渲染长篇合同文本与 AI 高亮结果；控制器层处理复杂交互逻辑。
- 攻克三个难点：
  - 长文档渲染性能：虚拟滚动，100 页以上 PDF 秒级加载与流畅滚动。
  - 高精度文本定位：与后端协作定义文本坐标体系，实现风险条款的像素级高亮。
  - 高并发流式解析：设计稳健的解析与错误恢复机制，网络抖动或响应缺失时前端平滑回退并提示。
技术资产沉淀：
- 封装内部 react-ai-stream-parser 组件库，统一处理各类 LLM 流式响应，已在公司另外两个项目复用。
- 编写《前端 AI 应用开发规范》，统一状态管理、API 调用、错误处理的最佳实践。

收尾句：通过这个项目，不仅交付了高价值业务产品，更在团队内部建立了可复用的前端 AI 工程化体系与方法论，为后续 AI 项目打下基础。

AI 大前端全栈架构师 · 知识体系与面试题库

UUOVO