---
name: chatu-quickstart
description: 创建应用的标准流程（快速启动为主）。新会话首轮、从零开始做一个应用、用户描述了需求要出第一版时使用；含可直接复制的 recipes 预置代码（列表+详情 / 表单收集 / 落地页）。
---

# 快速启动：首轮就要有可看的东西

目标：**首轮对话结束时，预览里已经有一个能点的应用**。做到这一点的手段是"复制改造，而不是从零写"。

## 首轮流程（按顺序）

1. **不追问需求细节**。用户说"做个记账本"就直接做，含糊处用下面的默认选择填充，做完在总结里说明"我默认了 X，可以随时改"。
2. **选 recipe**：对照下表，把最接近的一套复制进 `src/app/`，没有匹配的才从零写。
3. **改文案与字段**：把 recipe 的示例改成用户的业务（标题、字段名、示例数据、配色微调）。
4. **跑自检**：`npx tsc --noEmit` 通过，并**真的把页面请求一遍**确认没有白屏/500（`curl -s -o /dev/null -w '%{http_code}' http://localhost:3001/`）——详见 `chatu-verify`。
5. **总结**：一句话说做了什么 + 默认了什么 + 建议的下一步（"要接真实存储/登录吗"）。用了简化做法代替平台计费能力时，在这里点明升级路径（见下面决策 3 的"后问"那一类）。带了后台页时，写明地址和"目前没有权限保护"（见下面「后台」）。

## 后台（管理视图）：先做极简版，后问要不要正式的

需求里有"**别人提交、我来看 / 我来处理**"结构的——报名、预约、留言、反馈、订单、申请——**首轮就默认带一个极简后台页**，不追问：

- 路径固定 `/admin`（多份就 `/admin/<资源>`），一张表格列出全部记录，能看就行（`form-collect` recipe 自带 `admin/page.tsx`，`list-detail` 类需求列表页本身就是后台，不再另做）。
- **默认没有权限保护**。总结里必须写明："后台在 /admin，目前任何人都能打开；要不要加登录、只允许管理员看？"——用户点头再读 `chatu-admin`（登录 + `ADMIN_EMAILS` 设管理员 + layout 守卫），不要首轮就加登录。
- 用户没有这种结构（纯展示页、个人工具）就不做后台，也不问。

## 推迟项（首轮不做）

| 项 | 首轮做法 | 何时升级 |
| --- | --- | --- |
| 登录（auth） | 不加，所有人可用 | 用户明说"要登录/每人只看自己的"时：**先问用哪种授权模式**（见上），再读 `chatu-auth` |
| 数据持久化（db/kv） | recipe 自带内存示例数据 | 首屏确认后下一轮接，recipe 里已标好改造点 |
| 安装依赖 | 不 `npm install` 任何东西 | 图表 recharts、动画 motion **已预装**直接用；其他包确有必要再装，避开超重依赖 |
| 完美样式 | 用 recipe 自带的干净默认样式 | 用户提出审美要求时，读 `chatu-ui` |

## recipes：预置代码

位置：本 SKILL 目录下 `recipes/`（工作区里是 `.claude/skills/chatu-quickstart/recipes/`）。每套自带 README 说明改造点。

| recipe | 适用需求 | 复制命令（目录名换成业务词） |
| --- | --- | --- |
| `list-detail` | 待办、记账、清单、订单、文章、库存……"一类记录"的增删改查 | `cp -r .claude/skills/chatu-quickstart/recipes/list-detail src/app/items` |
| `form-collect` | 报名、预约、问卷、反馈收集 | `cp -r .claude/skills/chatu-quickstart/recipes/form-collect src/app/signup` |
| `landing` | 官网、产品介绍、活动落地页 | `cp -r .claude/skills/chatu-quickstart/recipes/landing/* src/app/` |

复制后必做：
1. 全局搜 `TODO(改)` —— 每处都是要换成业务内容的点；
2. 如果复制成了应用首页，把 `src/app/page.tsx` 替换或做跳转；
3. recipe 只用模板已装依赖，复制后**不需要**任何安装。

## 必须先问用户的三个决策

绝大多数含糊处都按下面的默认值自己定、事后说明即可。**只有这三件事必须先问、拿到答复再动手**——问错了返工代价远大于问一句：

1. **登录/授权方案**：用户要"加登录/要账号/每人只看自己的数据"时，先问用哪一种（见 `chatu-auth` 的模式对比）：
   - 应用自己的用户体系（邮箱注册登录，面向不特定用户）；
   - 使用渠道已有账号登录（不注册，面向渠道内部既有用户）。
   问法示例：「登录用哪种账号？① 让访客用邮箱自行注册；② 用你们渠道现有的账号直接登录（不开放注册）」。
2. **数据持久化方式**：要把内存示例数据换成真实存储时，先确认存哪儿、存哪些字段（`chatu-db` 集合 vs `chatu-kv`）——数据结构定型后再改迁移成本高。
3. **能力选型（只有"会重做数据"的那类要先问）**：需求能用平台的**计费能力**实现、同时存在零成本简化做法时，判据只有一条——**换方案要不要重做已经存进去的数据**：

| 需求信号 | 方案 A（平台能力，按量计费） | 方案 B（简化做法，零额外成本） | 换方案的代价 | 什么时候问 |
| --- | --- | --- | --- | --- |
| 上传资料后问答、知识库、智能客服 | `ai.embed` + `vectorSearch` 检索问答（见 `chatu-ai` 的 `references/rag.md`） | 资料截断后直接塞进 prompt（几千字内够用） | **大**：上传流程、存储结构、检索三处都要改，已存的资料还得重新切段入库 | **先问再动手**（首轮命中也照问） |
| 发票 / 合同 / 证件 / 扫描件里的信息 | `ai.ocr` 解析成 Markdown 再抽字段（按页计费） | 让用户手工填表单 | 小：新增一条路径，不动已有数据 | 先按 B 出第一版，**拿着实物再问要不要升级** |
| "让 AI 帮我查订单 / 算价格再回答" | `ai.runTools` 工具调用 | 固定流程：先查好数据再连同问题喂给模型 | 小 | 同上 |
| 看图识别 / 截图问答 | `ai.chat` 多模态（图片按 token 计费） | 让用户用文字描述 | 小 | 同上 |
| 搜索 | 语义检索（向量） | 关键词过滤（`db.find` 的 filter） | 小 | 同上 |
| 海报 / 配图 / 短视频素材 | `ai.generateImage`（按张计费）、`ai.generateVideo`（按秒计费，一条约 2~8 元，异步） | 让用户自己上传图片、视频，或用占位素材 | 小 | 同上；视频在总结里**要写明单价**再问 |

- **先问的那一类**：一次只问这一个问题，两三个选项 + 一句话讲清差别 + 给推荐项，例如「资料问答要哪种？① 语义检索：资料多也能答准，按用量计费；② 直接把资料塞给模型：零额外成本，资料超过几千字会答不全（推荐先用 ②，不够再升级）」。用户没明确选就按推荐项做，并在总结里写明选了哪个、怎么换。
- **后问的那一类**：不要在动手前打断，先用方案 B 把能看的东西做出来，**在总结里点明升级路径**（"现在是让你手工填，要的话可以改成拍照自动识别，按页计费"），用户要再升级。指着实物问，用户答得准，也不会白花点数。

注意：决策 1、2 **首轮不涉及**（首轮不加登录、用内存示例数据），首轮照旧不追问。决策 3 里**只有"资料问答/知识库"这一档是首轮例外**——它命中就先问；其余能力一律先做便宜版本、事后再问。

## 需求含糊时的默认选择

- 界面语言：跟随用户输入语言（中文用户 → 中文文案）
- 布局：移动优先，`max-w-*` 容器居中，桌面自适应
- 数据：填 5~8 条贴合业务的示例数据，别用 "test1/test2"
- 单页够用就单页；超过两类核心对象才拆多页

## 后续轮次（迭代规则）

- 每轮只做用户本轮要求的事，**不做未被要求的重构**；顺手美化限于本轮触碰的文件。
- 改动前先读目标文件，小步修改，改完自检（同首轮第 4 步）。
- **SDK 参数看速查表，不试探**：`@chatu-ai/app-sdk` 所有方法的签名 / 参数 / 默认值在本目录 `references/sdk-api.md`（自动生成，与工作区安装的版本一致）。不确定就查它；查不到就不传用默认值。**禁止**为了摸清接口写试探代码、发试探请求、翻 `node_modules` 的 `.d.ts`。
- 接平台能力（db/auth/storage/ai）前先读对应 SKILL，不要凭印象猜 API。
- 用户反馈"坏了/白屏/报错"时，读 `chatu-debug` 按路径排查。
- **每轮汇报前按 `chatu-verify` 自检**（tsc + 请求本轮涉及的路由），没过就别说"已完成"。
- 用户问"怎么发布/上线/让别人访问"时，读 `chatu-deploy`（发布由用户在面板点，你不执行部署）。