从战略规划到测试部署，AI正在重构传统软件开发的工作流与协作模式。本文完整展示从需求分析、数据建模到界面设计的全流程，演示如何用Cursor、Figma和Claude协同完成Markdown知识库开发。

01 工具准备

在开始实战之前，请确保完成以下工具的安装与注册：

1.1 Cursor 安装

Cursor 是一款基于 AI 的智能代码编辑器，它集成了强大的大语言模型，能够显著提升开发效率。

下载：访问 Cursor 官方网站https://cursor.sh

根据您的操作系统下载对应版本的安装包。

安装：运行安装程序并按照提示完成安装。

配置：首次启动时，可使用 GitHub 或 Google 账号登录，并根据个人习惯进行基础设置（如快捷键、主题等）。

1.2 Figma 注册与客户端安装

Figma 是本次项目中负责「界面与交互」设计的核心工具。

注册：访问 Figma 官方网站（https://www.figma.com/

使用邮箱或第三方账号进行免费注册。

安装桌面端：强烈建议下载并安装 Figma 桌面客户端。因为部分高级开发者功能（如本地 MCP Server 联动）必须在桌面客户端本地运行。

1.3API获取

用于 claude code/codex 的 API 对接渠道

https://www.aicodemirror.com/register?invitecode=W41BC7

02 实操环节

本次实操将通过四个核心步骤，利用 AI 模型、Figma 和 Cursor 工具，从 0 到 1 构建一个支持 Markdown 的个人知识库 Web 版。

步骤 1：战略与范围（需求分析）

使用工具：Claude 3.5 (或 Cursor 内置模型)

在此阶段，我们需要明确项目的核心目标和基本功能范围。

操作指南：在 Cursor 的 Chat 窗口中，选择 Claude 3.5，输入以下 Prompt：

“我想做一个支持 Markdown 的个人知识库 Web 版。请列出 MVP（最小可行性产品）功能列表，并生成 .cursorrules 文件。”

预期结果：AI 将梳理出 MVP 核心功能（如笔记的创建、编辑、分类等），并生成一份项目专属的 .cursorrules 文件，规范后续 AI 生成代码的风格。

如果 cursor 的初始效果不好，可以使用大模型做预处理

## Markdown 个人知识库 Web（MVP 功能清单）
遵循 **MVP（最小可行产品）原则**：
仅实现**验证核心价值所需的最少功能**。
核心价值：
**用户可以创建、编辑、保存并阅读 Markdown 笔记。**
—
# 一、核心功能（P0）
## 1. 笔记管理
* 新建笔记
* 编辑笔记
* 删除笔记
* 笔记列表展示
—
## 2. Markdown 编辑
* Markdown 文本编辑
* Markdown 语法支持（基础语法）
* 标题
* 加粗 / 斜体
* 列表
* 引用
* 代码块
* 链接
—
## 3. Markdown 预览
* Markdown 渲染展示
* 编辑区 + 预览区分栏显示
* 实时预览
—
## 4. 笔记查看
* 点击笔记打开
* 阅读模式展示
—
## 5. 数据存储
* 本地数据存储（浏览器本地）
* 页面刷新后自动加载笔记
—
# 二、MVP 功能总览

| 模块 | 功能 |
| ———– | —————- |
| 笔记管理 | 新建笔记 |
| 笔记管理 | 编辑笔记 |
| 笔记管理 | 删除笔记 |
| 笔记管理 | 笔记列表 |
| Markdown 编辑 | Markdown 编辑 |
| Markdown 编辑 | 基础 Markdown 语法支持 |
| Markdown 预览 | 实时 Markdown 渲染 |
| 笔记查看 | 阅读模式 |
| 数据存储 | 本地存储 |

**MVP 总功能数：9 个**
—
# 三、MVP 不包含的功能（刻意不做）

为保证开发效率，以下功能不进入 MVP：

* 文件夹 / 目录管理
* 标签（Tag）系统
* 全文搜索
* 图片上传
* 云同步
* 多用户账号
* 协作编辑
* AI 功能
* 插件系统

—

# 四、MVP 产品界面结构

“`
——————————–
| 笔记列表 | 编辑区 | 预览区 |
——————————–
“`

—

# 五、MVP 用户核心流程

“`
打开系统
↓
新建笔记
↓
编辑 Markdown
↓
实时预览
↓
自动保存
“`

—

如果要让这个项目**更像真实产品而不是练习项目**，下一步通常会设计：

1. **V1 功能扩展清单（10 个功能）**
2. **完整知识库产品架构（类似 Obsidian）**
3. **数据库结构设计**
4. **前端页面信息架构（IA）**

这样可以把这个项目直接升级为**一个完整的产品原型**。

下面是一套**可直接用于 Figma AI / Figma Make / 设计助手生成界面的提示词**。
设计目标是：**围绕 MVP 功能，仅设计最少必要页面**。

—

# Figma 页面设计提示词（Markdown 个人知识库 Web）

## 1. 产品整体设计提示词

提示词：

“`
设计一个简洁的 Web 应用界面，用于个人 Markdown 知识库。

产品特点：
– 面向个人用户
– 支持 Markdown 笔记编辑和阅读
– 界面风格简洁、现代、偏开发者工具风格

整体布局：
三栏布局
1. 左侧：笔记列表
2. 中间：Markdown 编辑器
3. 右侧：Markdown 预览

设计要求：
– 风格类似开发者工具
– 简洁现代
– 留白充足
– 使用浅色主题
– UI 风格接近技术产品

页面宽度：
1440px

字体：
– 标题：16-18px
– 正文：14px
– 等宽字体用于代码

颜色风格：
– 主色：蓝色
– 背景：浅灰
– 编辑区域白色

组件需要包括：
– 顶部导航栏
– 笔记列表
– Markdown 编辑区
– Markdown 预览区
– 新建笔记按钮
“`

—

# 2. 主页面（核心页面）

提示词：

“`
设计 Markdown 知识库 Web 应用的主页面。

页面布局：

顶部导航栏
– 产品名称：Knowledge Base
– 搜索框
– 设置按钮

主体为三栏布局：

左侧（240px）
笔记列表区域：
– 新建笔记按钮
– 笔记列表
– 当前笔记高亮

中间（Markdown 编辑区）
– Markdown 编辑器
– 支持多行输入
– 使用等宽字体
– 类似代码编辑器风格

右侧（Markdown 预览区）
– 渲染后的 Markdown 内容
– 标题
– 列表
– 代码块
– 引用
– 链接

视觉风格：
– 类似开发者工具
– 简洁
– 留白充足
“`

—

# 3. 笔记列表组件

提示词：

“`
设计一个笔记列表组件。

组件内容：

顶部
– 新建笔记按钮

列表内容：
– 笔记标题
– 创建时间
– 当前选中笔记高亮

交互：
– hover 状态
– 选中状态

设计风格：
– 类似 IDE 文件列表
– 简洁
– 垂直列表布局
“`

—

# 4. Markdown 编辑器组件

提示词：

“`
设计 Markdown 编辑器组件。

组件特点：

– 大型文本输入区域
– 等宽字体
– 支持多行输入
– 类似代码编辑器

界面元素：

顶部工具栏：
– 加粗按钮
– 斜体按钮
– 插入链接按钮
– 插入代码块按钮

编辑区：
– Markdown 原始文本
– 自动换行
– 行间距舒适

风格：
– 开发者工具风格
– 简洁
– 无复杂装饰
“`

—

# 5. Markdown 预览组件

提示词：

“`
设计 Markdown 预览区域。

展示内容：

– H1 / H2 / H3 标题
– 段落
– 列表
– 代码块
– 引用
– 链接

视觉效果：

标题：
– H1 大字体
– H2 中字体

代码块：
– 灰色背景
– 等宽字体

整体排版：
– 阅读舒适
– 类似技术文档
“`

—

# 6. 空状态页面

提示词：

“`
设计一个空状态界面。

场景：
用户还没有创建任何笔记。

界面内容：

– 插图（简单文档图标）
– 提示文字：
“还没有笔记，点击新建开始记录”
– 新建笔记按钮

风格：
– 简洁
– 居中布局
– 留白多
“`

—

# 7. Figma 页面结构（推荐）

在 Figma 中创建以下页面：

“`
01 Layout
02 Components
03 Main Page
04 Empty State
“`

组件库：

“`
Button
Sidebar
Editor
Preview
Note Item
Navbar
“`

—

# 8. 推荐参考 UI 风格

可以参考以下产品的 UI 风格：

* Obsidian
* Notion
* VS Code

设计风格关键词：

“`
developer tools
minimal
clean
markdown editor
knowledge management
“`

—

如果继续优化这个项目，我可以再给你一份**更高级的设计提示词**：

1️⃣ **一套完整的 Figma Design System 提示词**（按钮 / 输入框 / 列表组件）
2️⃣ **AI 自动生成完整 Web UI 的超级提示词（一次生成整个产品）**
3️⃣ **Markdown 知识库产品的完整页面结构（接近 Obsidian 架构）**

这样你基本可以 **5 分钟生成完整 UI 原型**。

步骤 2：结构与数据（数据建模）

使用工具：Cursor Chat

明确需求后，设计系统的数据结构。

操作指南：继续在 Cursor Chat 中输入以下 Prompt：

“根据功能列表，创建 prisma/schema.prisma，包含 Note， Tag， Folder 实体及其关联关系。”

预期结果：Cursor 将生成基于 Prisma 的数据库模型定义文件，明确表结构和外键关联关系。

步骤 3：界面与交互（Figma 设计与代码导入）

使用工具：Figma (Dev Mode/插件) + Cursor

在此阶段，我们将在 Figma 中完成视觉设计，并将设计稿转换为代码文件导入 Cursor 中。这里提供两种主流路径，您可以根据团队习惯和项目复杂度选择：

3.1 在 Figma 中完成界面设计

1. 打开 Figma 创建新文件，设计类似 Notion 的经典布局：左侧固定导航栏，右侧为自适应编辑器区。

2. 设计规范：强烈建议使用 Auto Layout（自动布局）、规范的 Components（组件）和 Variables（变量/Tokens），这能大幅提升导出代码的质量。

3.2 路径一：通过 Figma 插件直接下载代码文件（推荐快速起步）

如果您希望直接获取完整的 React/Tailwind/HTML 代码文件，使用 Figma 社区的第三方转换插件是最高效的方式。

操作步骤：

1. 安装插件：在 Figma 顶部菜单栏点击 Resources (Shift + I) -> Plugins，搜索并运行主流的 Code Export 插件（如 Anima、Figma to Code、Builder.io 或 Locofy）。

2. 选择并转换：选中您设计好的界面 Frame（画板），在插件面板中选择目标框架（如 React + Tailwind CSS）。

3. 下载代码压缩包：

• 插件解析完成后，通常会提供一个 Download ZIP 或 Export Code 按钮。
• 点击下载，您将获得一个包含完整组件代码、CSS 样式和静态资源（图片/SVG）的压缩包。

4. 导入 Cursor：

• 解压下载的 ZIP 文件。
• 在 Cursor 中打开您的项目，将解压后的代码文件（如 .jsx, .tsx, .css）直接拖拽或复制到项目的 components 或 app 目录下。
• 将静态资源文件复制到项目的 public 目录下。

5. 微调与联调：在 Cursor Composer 中输入 Prompt，让 AI 帮你将这些静态组件与你的项目架构融合：

“@<刚导入的组件文件> 帮我检查这个从 Figma 导出的 React 组件，将其调整为 Next.js App Router 规范，并提取出可复用的子组件。”

3.3 路径二：通过 Dev Mode 复制/导出 CSS 与资源（适合精准还原）

如果您只需要提取核心样式、变量或图片资源，Figma 原生的 Dev Mode 是最佳选择。

操作步骤：

1. 开启开发者模式：在 Figma 右上角点击 Dev Mode 开关（快捷键 Shift + D）。

2. 提取代码片段：

• 选中任意图层或组件，右侧的 Inspect（检查）面板会显示详细信息。
• 在 Code 区域，您可以选择语言（CSS、iOS、Android），直接复制生成的 CSS 或 Tailwind 代码片段，粘贴到 Cursor 的样式文件中。

3. 下载切图与资源：

• 在 Inspect 面板的 Assets 区域，Dev Mode 会自动识别并提取图标、图片。
• 设置好格式（PNG、SVG、JPG 等）后，点击下载按钮，将资源保存并放入 Cursor 项目的 public 文件夹中。

4. 使用 Code Connect（进阶）：如果团队有维护组件库，可以在 Dev Mode 中使用 Code Connect，直接查看该设计组件对应的真实代码库引用片段，复制到 Cursor 中使用。

(注：除了上述两种方式，您也可以配置 Figma 官方的 MCP Server，通过 Prompt 让 Cursor 直接读取 Figma 链接生成代码。)

步骤 4：逻辑实现（后端与联调）

使用工具：Cursor Composer

最后一步是实现业务逻辑，将导入的前端界面与后端数据进行对接。

操作指南：输入以下 Prompt：

“实现笔记的增删改查 API (Next.js App Router)，并与刚才导入的前端组件对接，处理加载状态和空状态。”

预期结果：Cursor 会分析全局项目结构，自动生成 API 路由，并更新前端组件调用这些接口，完成全栈联调。

步骤 5：项目测试

# MindMark 手工测试报告（2026-03-07）

## 1. 基本信息

– 项目：MindMark（Markdown 个人知识库 Web）
– 测试轮次：R1（MVP 功能联调后）
– 测试日期：2026-03-07
– 测试方式：手工测试（UI + API）
– 测试人：Yiyi
– 版本信息：
– Next.js `15.5.12`（Webpack）
– Node.js `v24.10.0`
– Prisma Client `v6.19.2`

## 2. 测试范围

– UI 主流程：
– 笔记创建、编辑、自动保存、删除、恢复、清空回收站
– 空状态、加载状态、搜索、设置重置
– API 主流程：
– `GET /api/notes`
– `POST /api/notes`
– `PATCH /api/notes/:id`
– `DELETE /api/notes/:id`
– `POST /api/notes/:id/restore`
– `DELETE /api/notes?hard=1`

## 3. 执行结果总览

– 用例总数：15
– 通过：15
– 失败：0
– 阻塞：0
– 总体结论：本轮 MVP 核心功能通过，可进入下一阶段（回归自动化与体验打磨）。

## 4. 详细结果

| 用例ID | 用例名称 | 结果 | 备注 |
| — | — | — | — |
| T01 | 首页渲染与启动稳定性 | PASS | 无白屏，无 `global-error` 运行时异常 |
| T02 | 空状态展示 | PASS | 首页/工作区/搜索/回收站空态正常 |
| T03 | 新建笔记 | PASS | 可创建并进入编辑态 |
| T04 | 自动保存与刷新持久化 | PASS | 刷新后数据保留 |
| T05 | 快速连续编辑一致性 | PASS | 最终内容与末次输入一致 |
| T06 | 删除到回收站 | PASS | 主列表移除，回收站可见 |
| T07 | 回收站恢复 | PASS | 恢复后主列表可见，内容完整 |
| T08 | 清空回收站 | PASS | 回收站被清空，不可恢复 |
| T09 | 搜索命中与空结果 | PASS | 命中准确，未命中空态正常 |
| T10 | 慢网加载状态 | PASS | Slow 3G 下加载态正常出现 |
| T11 | 设置页重置数据 | PASS | 重置后恢复默认状态 |
| T12 | API: GET /api/notes | PASS | 用户反馈通过 |
| T13 | API: POST /api/notes | PASS | 用户反馈通过 |
| T14 | API: PATCH /api/notes/:id | PASS | 用户反馈通过 |
| T15 | API: 删除/恢复/硬清空链路 | PASS | 用户反馈通过 |

## 5. 风险与备注

– T12-T14 未保留完整终端原始响应截图（如状态码/响应体快照），本报告按执行人最终“PASS”结论记录。
– 建议下一轮将 T12-T15 纳入 Vitest 集成测试，降低回归时的人工成本与遗漏风险。

## 6. 后续建议

1. 将手工用例沉淀为回归基线，每次发布前至少执行一次 T01-T11。
2. 将 API 用例 T12-T15 自动化（CI 可执行），并在 PR 阶段强制通过。
3. 增加异常流测试：非法参数、404 id、并发更新冲突、网络中断恢复。

# 手工测试模板（可复用）

> 用法：复制本文件，重命名为 `MANUAL_TEST_REPORT_YYYY-MM-DD.md`，替换占位符并填写执行结果。

## 1. 基本信息

– 项目：`<项目名>`
– 测试轮次：“
– 测试日期：“
– 测试方式：`手工测试 / 联合测试 / 冒烟测试`
– 测试人：`<姓名>`
– 版本信息：
– Next.js：“
– Node.js：“
– Prisma Client：“
– 其他：`<可选>`

## 2. 测试范围

– UI 范围：`<页面/流程>`
– API 范围：`<接口列表>`
– 非范围（可选）：`<本轮不覆盖内容>`

## 3. 执行结果总览

– 用例总数：“
– 通过：“
– 失败：“
– 阻塞：“
– 总体结论：`<可发布/需修复后复测/阻塞上线>`

## 4. 用例执行明细

| 用例ID | 用例名称 | 前置条件 | 执行步骤 | 预期结果 | 实际结果 | 结果(PASS/FAIL/BLOCK) | 证据 |
| — | — | — | — | — | — | — | — |
| T01 | `<示例：首页渲染>` | `<示例：服务已启动>` | `<步骤1;步骤2>` | `<预期>` | `<实际>` | “ | `<日志/截图路径>` |
| T02 | | | | | | | |
| T03 | | | | | | | |

## 5. 缺陷记录（若有）

| 缺陷ID | 严重级别 | 关联用例 | 问题描述 | 复现步骤 | 当前状态 |
| — | — | — | — | — | — |
| BUG-001 | “ | “ | `<描述>` | `<步骤>` | “ |

## 6. 风险与备注

– `<示例：本轮未覆盖移动端 Safari>`
– `<示例：部分接口缺少异常路径校验>`

## 7. 后续建议

1. `<建议1>`
2. `<建议2>`
3. `<建议3>`

## 8. 附录（可选）

– 启动命令：`pnpm -C UI dev`
– API 快测命令：
– `curl -i http://localhost:3000/api/notes`
– `curl -i -X POST http://localhost:3000/api/notes -H ‘Content-Type: application/json’ -d ‘{“title”:”x”,”content”:”y”}’`

项目运行与调试

完成上述开发步骤后，您可以在终端中运行项目以查看效果。

• 安装依赖：在项目根目录下运行 npm install 或 pnpm install。
• 初始化数据库：运行 npx prisma db push 同步数据库结构。
• 启动开发服务器：运行 npm run dev。
• 预览：在浏览器中打开 http://localhost:3000，体验您亲手构建的个人知识库。

github源码地址：

https://github.com/ZheXiangShen/Mindmaker-Driven-by-Natural-Language/tree/local-knowledge-base