快速入门

第一次使用工作台，按顺序完成下面 5 步，大约 20 分钟。之后每次做需求，只需要打开 AI 说话。

准备清单

只需要向管理员要 2 样东西，其余由脚本自动完成。

准备什么	找谁要	放在哪里	说明
GitHub 只读 key 文件（`github_readonly`）	研发负责人	`git/keys/github_readonly`	配置获取指南 · GitHub
Cloudflare 两个参数：账号 ID、API Token（项目会自动创建）	Cloudflare 管理员，或自己注册免费账号	填进 `deploy/cloudflare.json`	配置获取指南 · Cloudflare
一台 Mac 电脑，剩余磁盘 ≥ 5GB	—	—	每个需求的 demo 约占 1–2GB（含依赖）
AI 工具：Claude Code 桌面版或 Codex（二选一）	—	—	两个工具读同一套规范，可以随时切换

第 1 步：拿到工作台

向研发负责人要工作台文件夹（或压缩包），放在任意位置，例如「桌面 / fanzy-product-workspace」。不要放进有中文空格的深层目录或 iCloud 同步目录。

第 2 步：一键安装环境

推荐在 AI 中说：「帮我运行 scripts/setup.sh 安装环境」。AI 会先解释操作，再打开终端启动安装，并跟进到最后的自检。你不需要输入命令。

AI 会安装管理开发工具的 Homebrew、Git、Node、pnpm、工作台依赖和测试浏览器，已有工具会复用。
如果系统弹窗问是否允许 AI 控制「终端」，选择「允许」。这只是打开终端的授权，后续可能还需要下面两步。
终端出现 Password: 时，输入电脑开机密码并按回车。输入时不会显示字符，这是正常现象。不要把密码发给 AI。
出现 Press RETURN/ENTER to continue 时按回车。之后安装会继续，AI 会检查进展；你不用反复问下一步。
AI 会在结束后说明：哪些已装好、自检是否通过、还缺哪些配置。网络下载失败会明确告知，不会把已点击「允许」当成安装成功。

需要自己启动时（备用方式）

打开「终端」：按 ⌘ 空格，输入「终端」回车
输入 cd （cd 后面有个空格），然后把工作台文件夹拖进终端窗口，回车
复制下面这行，粘贴进终端，回车：
```
bash scripts/setup.sh
```
过程中如果要求输入密码，输入电脑开机密码（输入时不显示字符，正常）
等待最后的自检结果。只有「安装及自检全部通过」才代表环境完全就绪；若提示自检未通过，告诉 AI 检查剩余问题。key 和 Cloudflare 仍需按第 3 步配置。

第 3 步：放 key、填参数

如果工作台已带有 git/github_readonly，安装或自检发现尚未配置只读认证时，AI 会先问「是否使用 ifanzy-web 的默认配置只读认证？」。你回复「使用默认只读认证」后，AI 会更新密钥路径并自动检查仓库连接；未同意时不会更改。已有有效自定义密钥会保留。密钥内容不需要发给 AI。

把管理员给的 github_readonly 文件放进工作台的 git/keys/ 文件夹
用文本编辑器打开 deploy/cloudflare.json，把两个「填…」替换成账号 ID 和 Token（获取路径见配置获取指南 ④⑤）：
```
{
  "accountId": "32 位账号 ID",
  "apiToken": "API Token",
  "projectName": "fanzy-product",
  "siteUrl": ""
}
```
git/github.json 一般不用改（仓库地址、默认分支、key 路径已经写好）

这两个文件是密钥，不要发到群里、不要截图外传。它们不会被发布到网站上。

第 4 步：用 AI 打开工作台

Claude Code 桌面版

打开 Claude 桌面应用 → Code → 选择文件夹 → 选中工作台文件夹。

Codex

打开 Codex → 打开文件夹 / 新建项目 → 选中工作台文件夹。

进去之后说的话完全一样。AI 会自动读取工作台的规范（AGENTS.md）。

第 5 步：自检

你帮我自检一下工作台

AI准备检查全部通过 ✔ · Node / pnpm / git 正常 · GitHub 仓库可以访问 · Cloudflare 配置有效（项目 fanzy-product） · 没有未完成的需求可以开始需求了。

有 ✘ 时，AI 会告诉你原因和该看哪本手册。全部通过后，照着最小例子完整走一遍；以后每次开新需求，先填一份新需求问卷发给 AI。

备份与换电脑

首次正式发布时，AI 会检查默认演示「登录页新人福利提示」，线上没有就自动补发已完成的三件套；以后发布也会检查，已有则保留。发布完成并核验后，会列出首页、demo、需求文档、测试报告/录像的完整网址。详见默认模板初始化和完整交付路径。

工作台是纯本地的，历史版本只保存在这台电脑上。线上站点只是展示，不能用来恢复。建议每次发布后，把下面 3 个文件夹复制到网盘或移动硬盘：

prd/   demo/   testcases/

换电脑时：拿到新的工作台，按本页第 2、3 步配置好，再把这 3 个文件夹覆盖回去，然后对 AI 说「继续上次的需求」。demo 的代码工作区可以通过 source.patch 自动恢复。

工作台里有什么

位置	是什么	你需要碰吗
`index.html`	版本首页（也是线上预览地址的首页）	只看
`prd/` `demo/` `testcases/`	三类交付物：手册 · 规范 · 例子 + 每个需求的版本包	只看
`git/`	拉代码的手册和配置，`keys/` 放只读 key	放 key 一次
`deploy/`	发布的手册和配置，`history.json` 是发布记录	填参数一次
`project/`	fanzy-web 代码（自动拉取）和每个需求的 demo 工作区	不用碰
`scripts/` `.claude/` `.agents/` `AGENTS.md`	AI 使用的脚本和规范	不用碰