用 AI Agent 做可持续迭代的网页原型：React、SQLite 与项目规范入门

这篇教程教你用 Codex、Claude Code、Cursor 等编码 Agent，做一个能运行、能保存数据、也能继续修改的网页原型。我们不会停在“生成几张看起来像网页的静态页面”，而是从第一天就建立四样东西：可复用的前端组件、真实的本地数据层、项目事实源文档，以及约束 Agent 修改方式的项目级技能。

它适合这些场景：

• 产品经理要把需求做成可点击、可新增、可修改状态的评审原型，而且预计会经历多轮评审；
• 设计师或项目负责人希望不同页面保持同一套布局、字段、状态和交互，不想每次都重新解释；
• 个人开发者已经发现，原生 HTML、巨型 mock 文件和单个 server.js 在项目变大后很难让 Agent 精准修改；
• 团队会轮换使用 Codex、Claude Code 或其他 Agent，需要新对话快速接手，而不是重新读取整个项目。

完成后，你会得到一个“原型需求评审台账”：可以查看需求列表、新建需求、打开详情、更新评审状态；关闭服务再启动后，数据仍保存在 SQLite 中。更重要的是，你会得到一套可复用的原型工程结构，让 Agent 知道先读什么、改哪里、哪些文件不能顺手重写、完成后怎样验证。

这是本地评审原型，不是正式生产系统。教程不包含账号权限、云数据库、支付、文件上传、多人并发、生产部署或真实个人数据。

先看一个真实教训：原型能运行，不等于容易维护

我们复盘过一个持续迭代的真实企业原型。它做对了很多事：业务、页面、视觉、模拟数据分别有事实源文档；项目级技能规定了开发和一致性检查流程；不同终端独立分区；变更记录说明了当前完成范围和接手顺序。

但它的主 WEB 单元后来增长到数百个页面和脚本，核心运行数据文件超过三万行，并与重置基线保持一份完全相同的副本；模拟 API 和本地服务入口也分别膨胀到上万行。新增一个字段经常需要同时检查页面脚本、mock、重置基线、API、服务路由和多份文档。

这些数字只是一次本地代码审计快照，不是行业基准，也不代表框架一定节省多少 Token。它说明的是一种机制：

• 没有组件层时，相同表单、状态标签和表格结构会散落在许多页面；
• 没有真正的数据表和迁移时，超长 JavaScript 对象既充当数据，又充当重置备份；
• API 和业务逻辑集中在巨型文件时，Agent 每次修改都要读取更大的上下文；
• 文档和技能可以减少口径漂移，却无法替代合理的代码模块和数据结构。

因此，本教程保留“文档 + 技能 + 状态交接”的优点，同时把实现换成 React + TypeScript + Express + SQLite。如果你只做一次性、两三页、无共享数据的演示，静态 HTML 仍然合理；有关选择边界，可先看《[用 AI Agent 从零生成网页原型：静态 HTML、Vue、React 怎么选，才能少返工、少烧 Token](/tutorials/ai-agent-prototype-tech-stack-token-cost-guide)》。

你要做什么：一条小而完整的评审链路

本教程只实现一条垂直链路：

需求列表
  ├─ 按状态筛选
  ├─ 打开需求详情
  └─ 新建需求
       └─ 保存到 SQLite
            └─ 在详情页更新为“评审中”或“已确认”

固定字段如下：

第一版只有列表、新建、详情三个页面和四个 API，不做登录、删除、附件、富文本、分页、云同步和后台权限。

可维护原型的五层结构

*原理示意图，由 Image 2 根据本教程架构制作；不是官方架构图，也不是运行截图。*

这五层各自解决一个问题：

1. docs/ 说明业务、页面、设计和数据事实，防止 Agent 凭当前代码猜需求。
2. 项目级 skill 规定每次修改的读取顺序、影响分析和验证流程。
3. React 把状态标签、表单和页面框架做成组件，公共修改只需要落在少数文件。
4. Express 把路由、输入校验和数据服务分开，避免所有端点堆进一个入口。
5. SQLite 用表结构、约束和查询代替超长 mock 对象；种子数据和运行数据也不再复制整份 JavaScript 文件。

开始前检查：只在独立练习目录操作

本教程以 Windows PowerShell 为例。你需要：

• 已能打开本地文件夹并修改文件的编码 Agent；
• Node.js 24.15 或更新的 Node 24 LTS；
• Chrome 或 Edge；
• 一个全新的练习目录。

Vite 当前官方文档要求 Node.js 20.19+ 或 22.12+；本教程把下限提高到 Node 24.15，是因为该版本的内置 node:sqlite 已进入 release candidate 阶段。不要为了跟教程一致而直接升级公司项目的 Node 版本；只在独立练习目录使用已经确认的运行环境。

先做只读检查：

node --version
npm.cmd --version

预期第一行至少为 v24.15.0。如果命令不存在或版本过低，先按 Node.js 官方说明处理环境，不要让 Agent 自行修改系统 PATH 或全局安装未知工具。

创建练习目录：

$prototypePath = Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'ai-review-prototype'
New-Item -ItemType Directory -Path $prototypePath -Force | Out-Null
Set-Location -LiteralPath $prototypePath
Get-Location

把这个目录作为 Agent 的工作区。后续所有命令都在这里执行，不扫描其他盘符，不读取其他项目。

第一步：先让 Agent 写实施计划，暂不创建文件

把下面的原型合同交给 Agent：

我要在当前空目录中做一个“原型需求评审台账”，供产品评审使用。

用户：产品经理和评审者。
核心路径：查看需求列表 → 新建需求 → 打开详情 → 更新评审状态。
固定字段：标题、使用场景、优先级、状态、验收标准、创建时间、更新时间。
状态固定为：draft=草稿、review=评审中、confirmed=已确认。
优先级固定为：low=低、medium=中、high=高。

技术边界：
- 前端：React + TypeScript + Vite；
- 路由：React Router；
- 本地 API：Express；
- 数据库：Node 24.15+ 内置 node:sqlite，文件保存在 data/prototype.sqlite；
- Vite 通过 /api 代理到 http://127.0.0.1:3001；
- 只使用虚构测试数据。

第一版不做：登录、权限、删除、附件、富文本、分页、云服务、生产部署、真实个人数据。

先不要创建文件、不要安装依赖。请输出：
1. 页面与用户路径；
2. 项目目录树；
3. React 组件边界；
4. API 和 SQLite 表结构；
5. 文档与项目级 skill 清单；
6. 安装命令及其作用；
7. 自动验证和浏览器验收清单；
8. 你认为可能超出第一版范围的内容。
输出后停止，等待确认。

计划合格时，应满足三个条件：

• 页面只有列表、新建、详情，没有主动扩成账户、看板或复杂后台；
• 服务端至少拆出 routes / services / db，而不是把所有逻辑写进 server.js；
• 计划里先建立文档和项目技能，再实现业务页面。

第二步：只建立脚手架，再写项目事实源

确认计划后，先让 Agent 执行最小脚手架。依赖安装会联网下载公开 npm 包，应该在新的练习目录中由你明确批准；不要把命令改成全局安装。

npm.cmd create vite@latest . -- --template react-ts
npm.cmd install
npm.cmd install express react-router-dom

预期结果：

• 根目录出现 package.json、vite.config.ts、src/；
• package-lock.json 被保留，用于固定本次解析出的依赖版本；
• npm.cmd run dev 可以启动 Vite 默认页；
• 没有全局安装，也没有修改当前目录之外的文件。

脚手架验证：

npm.cmd run build

预期命令成功，并生成 dist/。如果失败，先保存完整错误信息，不要让 Agent 删除 node_modules、锁文件或重装全部环境。

接着要求 Agent 先创建规则，不写业务代码：

脚手架已通过构建。现在先创建项目事实源和项目级技能，不实现页面或 API。

需要创建：
- AGENTS.md：项目定位、事实源优先级、技术边界、修改流程、验证命令和禁止事项；
- docs/requirements.md：用户、场景、字段、状态、业务规则、第一版边界；
- docs/page-map.md：三个页面的职责、路由、入口、空状态、错误状态和验收路径；
- docs/design-system.md：颜色、字号、间距、按钮、表单、状态标签、桌面和窄屏规则；
- docs/data-model.md：requirements 表、字段约束、四个 API 和错误响应；
- docs/CHANGELOG.md：按日期记录已确认变更和待同步项；
- .agents/skills/prototype-feature-build/SKILL.md：后续新增或修改功能时的固定工作流。

规则要求：
1. 冲突优先级依次为 requirements → data-model → page-map → design-system → 当前实现。
2. 评审记录只有在用户确认后才能同步进事实源。
3. 修改前必须读取相关文档和现有实现，列出影响文件；修改后必须运行 lint、build、API 测试和对应浏览器路径。
4. 不允许把业务数据写死在 React 组件中，不允许绕过 service 直接在 route 中拼 SQL。
5. SQL 必须使用参数绑定；运行数据库 data/*.sqlite 不提交、不打包。
6. 不得顺手增加登录、删除、上传、云服务或生产部署。

完成后只汇报文件职责和关键规则，等待我检查。

事实源为什么要拆成四份

把所有规则塞进一个超长 README，也会增加 Agent 每次读取的上下文。四份文档按职责拆分后，修改按钮样式不需要读取数据库章节，修改状态字段也不会只看页面截图猜业务。

项目级 skill 也不是第二份需求文档。它只描述重复执行的流程：读什么、怎样分析影响、怎么验证。业务字段和页面内容仍在 docs/ 中维护。

第三步：让 Agent 按固定结构实现一条垂直链路

检查文档后，再发送实现任务：

规则文件已确认。现在实现“需求列表 → 新建 → 详情 → 更新状态”这一条垂直链路。

目标结构：
src/
  components/AppShell.tsx
  components/PageHeader.tsx
  components/StatusBadge.tsx
  components/RequirementForm.tsx
  domain/requirement.ts
  lib/api.ts
  pages/RequirementListPage.tsx
  pages/RequirementCreatePage.tsx
  pages/RequirementDetailPage.tsx
server/
  index.js
  routes/requirements.js
  services/requirements-service.js
  db/index.js
  db/init.js
  db/reset.js
  db/schema.sql
  tests/requirements-api.test.js
data/

API：
- GET /api/health
- GET /api/requirements?status=&priority=
- GET /api/requirements/:id
- POST /api/requirements
- PATCH /api/requirements/:id/status

实现要求：
1. server/index.js 只负责启动、JSON 中间件、挂载路由和统一错误处理。
2. route 负责读取参数和返回 HTTP 响应；service 负责业务校验；db 负责 SQL。
3. requirements 表使用 STRICT，status 和 priority 有 CHECK 约束。
4. 所有 SQL 使用 prepare 和参数绑定，不拼接用户输入。
5. init 只在表为空时写入 3 条虚构种子数据，不覆盖已有运行数据。
6. React 的状态中文显示集中在 domain/requirement.ts；StatusBadge 统一处理颜色。
7. 列表、新建、详情都必须有加载、错误和空状态；窄屏不出现横向滚动。
8. Vite 代理 /api 到 127.0.0.1:3001，不添加 cors 依赖。
9. package.json 增加 dev:client、dev:server、db:init、db:reset、test:api、verify；verify 串联 lint、build 和 API 测试。
10. db:reset 必须要求显式参数 --confirm-local，只允许处理当前项目 data/prototype.sqlite；重置前把旧数据库复制到 data/backups/ 的时间戳文件，不得接受项目外路径。
11. 不修改已确认的 docs，除非实现发现明确冲突；发现冲突先停止说明。

创建完成后运行自动验证，列出实际文件、验证命令、结果和仍需人工点击的路径。不要把“代码已生成”写成“浏览器已验收”。

建议的 SQLite 表结构应接近：

CREATE TABLE IF NOT EXISTS requirements (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL CHECK (length(trim(title)) BETWEEN 2 AND 80),
  scenario TEXT NOT NULL CHECK (length(trim(scenario)) >= 4),
  priority TEXT NOT NULL DEFAULT 'medium'
    CHECK (priority IN ('low', 'medium', 'high')),
  status TEXT NOT NULL DEFAULT 'draft'
    CHECK (status IN ('draft', 'review', 'confirmed')),
  acceptance_criteria TEXT NOT NULL DEFAULT '',
  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
) STRICT;

如果 Agent 用字符串拼接 SQL、把中文状态直接存进多处组件，或把全部 API 写进一个数千行文件，先让它按文档重构再继续。

第四步：初始化 SQLite，并分别启动前后端

在项目根目录执行：

npm.cmd run db:init

预期输出应说明数据库文件位置、表是否创建、种子数据是否写入。重复执行时不应覆盖你已经新增的数据。

如果评审前确实需要恢复虚构种子数据，先确认当前目录和数据库绝对路径，再运行：

npm.cmd run db:reset -- --confirm-local

预期脚本先把旧数据库复制到当前项目的 data/backups/，再重建 data/prototype.sqlite。这是一项有意清空本地演示数据的操作，不要交给 Agent 自动执行，也不要把路径改成其他项目或生产数据库。

打开两个 PowerShell 窗口，都进入同一项目目录。

窗口一：

npm.cmd run dev:server

预期看到 API 监听 http://127.0.0.1:3001。

窗口二：

npm.cmd run dev:client

预期看到 Vite 本地地址，通常是 http://127.0.0.1:5173 或终端实际显示的其他空闲端口。

先验证 API：

Invoke-RestMethod -Uri 'http://127.0.0.1:3001/api/health'
Invoke-RestMethod -Uri 'http://127.0.0.1:3001/api/requirements'

第一条应返回明确的健康状态；第二条应返回种子需求列表。若端口不同，以 Agent 实际配置为准，不要同时修改前端代理和后端端口来“碰碰运气”。

第五步：在浏览器完成六项人工验收

打开 Vite 地址，逐项记录“通过 / 不通过 / 未验证”：

再把浏览器缩窄到手机宽度，检查表单、按钮和内容是否溢出。原型面向桌面评审也不代表可以忽略窄屏。

最后运行自动检查：

npm.cmd run verify

只有当 lint、build、API 测试和六项人工路径都完成时，才能说这条原型链路已经验证。Agent 无法实际看到或点击浏览器时，必须如实标为“待人工验收”。

第六步：用一次小改动检验它是否真的可维护

让 Agent 把“草稿”显示文字改为“待评审”，但数据库值仍保持 draft：

先读取 AGENTS.md、相关 docs、项目级 prototype-feature-build skill 和当前实现。

需求：把界面中的 draft 中文显示从“草稿”改为“待评审”，数据库枚举值和 API 值仍保持 draft。

修改前先列出影响文件。只修改事实源中对应文案、集中状态映射和必要测试；不要全局盲目替换，不要改 SQLite 已存数据，不要顺手调整其他状态或样式。

完成后运行 npm.cmd run verify，并告诉我需要重新点击哪些浏览器路径。若发现状态文案散落在多个页面，请先说明重复点，再收口到共享映射。

理想结果是只需修改少数文档、一个集中状态映射和相应测试，而不是逐页搜索几十个 HTML 和 JavaScript 文件。这就是组件、事实源和数据编码分离带来的维护收益。

常见问题与排查

npm create vite 提示 Node 版本不支持

先重新运行：

node --version
npm.cmd --version

以 Vite 终端报错和官方当前要求为准。不要在现有公司项目里直接升级 Node；可以先为练习创建独立环境，或停止并让有权限的人处理。

node:sqlite 无法导入

确认 Node 至少是 24.15，并检查代码是否使用：

import { DatabaseSync } from 'node:sqlite';

不要看到错误就同时安装 sqlite3、better-sqlite3 和 ORM。驱动路线只能选一条；若项目必须支持旧 Node，应重新做技术选择并更新 docs/data-model.md。

前端页面能打开，但 /api 返回 404

分别检查三处：Express 是否监听 3001、vite.config.ts 是否代理 /api、前端是否使用相对地址 /api/...。不要把本地绝对地址复制到每个组件里。

重启后数据消失

检查数据库是否真的写到 data/prototype.sqlite，以及 db:init 是否错误地每次删除或覆盖数据库。初始化脚本只应建表，并在表为空时写种子数据。

Agent 每次仍然读取很多文件

让它先根据任务类型读取对应事实源和组件，不要机械加载整个 docs/。文档拆分的目标是精准取用，不是把上下文从代码换成另一批超长 Markdown。

页面风格开始漂移

要求 Agent 先复用 AppShell、PageHeader、StatusBadge 和 RequirementForm，并对照 docs/design-system.md。如果新页面必须出现新组件，先说明它与现有组件的差异，不能为一个页面复制一套平行样式。

风险边界：这个架构仍然只是本地原型

• SQLite 文件适合本地、单机、小团队评审，不等于可以直接承载高并发生产业务。
• DatabaseSync 的同步 API 对小型本地原型简单直接；正式高并发服务需要重新评估并发、连接和事务模型。
• 没有登录和权限时，任何能访问本地服务的人都可能修改原型数据。
• 文档和 skill 可能过期；代码行为变化后必须同步事实源，并运行真实验证。
• React、Express 和 SQLite 不能代替产品评审、类型检查、测试、代码审查和浏览器验收。
• 不要把客户资料、生产数据库、账号、Cookie、Token 或真实个人信息放进练习项目。
• 不要同时引入多个状态管理库、ORM、UI 组件库和重叠 Agent 工具；初学阶段每增加一层，都增加安装、上下文和排错成本。

可直接复制给 AI Agent 的安全任务书

你要在我明确指定的本地目录中，协助我构建和维护一个可评审的网页原型。

技术基线：
- React + TypeScript + Vite；
- React Router；
- Express 本地 API；
- Node 24.15+ 内置 node:sqlite；
- SQLite 文件位于 data/，只用于虚构演示数据。

开始任何修改前：
1. 读取 AGENTS.md；
2. 根据任务读取 docs/requirements.md、data-model.md、page-map.md、design-system.md 中相关章节；
3. 读取 .agents/skills/prototype-feature-build/SKILL.md；
4. 检查当前实现，列出目标、影响文件、数据/API 影响和验证范围；
5. 如果需求与事实源冲突，先停止并向我说明，不要自行选择。

实施规则：
- 页面复用公共布局、表单和状态组件；
- route、service、db 分层，入口文件不堆业务逻辑；
- SQL 使用 prepare 和参数绑定；
- 不在 React 组件写死业务列表；
- 一次只处理一个明确需求；
- 不扫描工作区外目录，不读取或上传私有文件；
- 不删除、批量清理、全局安装、升级运行环境或修改系统配置；
- 不增加登录、权限、上传、云服务、生产部署，除非我单独确认。

完成后：
1. 列出修改文件和原因；
2. 运行 npm.cmd run verify；
3. 给出需要人工点击的浏览器路径、操作和预期结果；
4. 标明哪些验证真实执行，哪些仍待人工完成；
5. 判断是否需要同步 docs、AGENTS.md、项目级 skill 或 CHANGELOG；
6. 不把“代码已生成”冒充“浏览器已验收”。

总结：初学不等于从一次性结构开始

初学者确实需要控制范围，但“控制范围”不等于禁止框架和数据库。真正合适的入门路线是：业务只做一条链路，工程上却从第一天建立清楚边界。React 负责复用界面，SQLite 负责持久化数据，文档负责表达事实，项目级 skill 负责让 Agent 重复执行同一套修改流程。

当原型只做一次展示时，静态 HTML 足够；当它会持续评审、增加页面、共享状态和反复修改时，尽早组件化和结构化数据，往往比后期在巨型 mock 和重复页面上继续补丁更省力。

官方参考

• React：从零构建应用：官方示例使用 Vite 创建 React TypeScript 项目，并说明组件、路由和数据获取的工程边界。
• Vite Getting Started：脚手架命令、开发服务器、构建能力和当前 Node.js 兼容要求。
• Express 安装指南：Express 5 的 Node.js 要求、安装方式和 TypeScript 类型说明。
• Node.js 24 LTS 的 SQLite 文档：node:sqlite、DatabaseSync、文件数据库、参数化语句和当前稳定性状态。
• React Router 官方文档：客户端路由的当前使用方式。

以上在线资料于 2026-07-26 核对。命令中的 @latest 会安装读者执行时的当前版本；请保留 package-lock.json，并以安装时的官方要求和终端输出为准。