|
欢迎交流 如果你在使用 Vibe Coding、AI Coding 或这个 Skill 的过程中有想法，欢迎联系果汁哥。 微信号： guozhige2024果汁哥有 AI 交流群，欢迎私信说明来意，申请加入。 访问 vibecoding base · 查看配套 Skill |
 扫码添加微信 · 私信申请加入 AI 交流群 |
一个面向 Vibe Coding 的可视化术语图鉴、练习场和 Skill API。
这个项目有两个目的：让技术小白通过真实任务迅速掌握 Vibe Coding；也让专业使用者把术语、交互和视觉风格变成 AI 能准确理解的共同语言。当你对 AI 说“做成苹果风格”时，这里可以把一句模糊的方向拆成留白、层级、表面、动效和交互等可观察、可复用的语义标准。你可以浏览术语、看交互 Demo、做判断题、复制 Markdown，也可以让自己的 Skill 通过只读 API 查询术语。
本仓库是独立的 React + Vite 内容产品实现。项目名称、页面内容和素材仅在版权归属方拥有或获得授权的范围内发布；第三方内容、品牌元素和外部链接应以实际授权和最终替换结果为准。
配套的 Skill 仓库：Juicebro-star/vibecoding-base-skill
| 能力 | 当前状态 | 说明 |
|---|---|---|
| 术语图鉴 | 已实现 | 281 个术语路由，覆盖 Frontend、Backend、Product、Technology、AI、Git、Design |
| 术语详情 | 已实现 | 双语正文、结构化区块、语义 Demo、易混淆概念、练习题和 Agent Prompt |
| 判断练习 | 已实现 | 255 道题，支持选择、对错反馈、继续下一题和进入术语详情 |
| 课程路线 | 已实现 | 产品官网路线总览与 12 个章节页 |
| 双受众首页 | 已实现 | 面向技术小白的用中学习入口，以及面向专业用户的风格语义对齐说明 |
| 防止 AI 味儿 | 已实现 | 专题页、示例卡片和交互式说明 |
| 动效语义图鉴 | 已实现 | 43 个独立编写的实时动效模式、适用边界、AI 请求、CSS/React 代码和减少动态规则 |
| Skill 展示页 | 已实现 | 安装指令、能力说明和与 API 的联动约定 |
| Skill API | 已实现 | Manifest、术语搜索/详情、动效搜索/详情五个只读入口 |
| 中英文入口 | 已实现 | 中文默认入口与 /en 镜像路由 |
| 主题与收藏 | 已实现 | 8 种主题色、浏览器本地收藏和主题状态 |
| 生产运行 | 已实现 | 独立 Node 服务、SPA 回退、健康检查、静态资源缓存和基础安全响应头 |
当前版本更适合：个人品牌站、内容产品 Beta、演示站、Skill 配套文档站和后续继续扩展的工程底座。
当前版本还不是：带账号体系的 SaaS、带云端进度同步的学习平台、完整的后台 CMS，也没有加入未公开或未经授权的服务端能力。
先选一条路线，做一个真实页面
↓
用自己的话告诉 AI 想做什么
↓
跟着章节完成一个最小可见改动
↓
做完后让 AI 检查目标、反馈、手机和异常状态
↓
需要时再回到术语图鉴，把问题说得更准确
↓
Skill API：让 Agent 在自己的工作流中查询同一套术语知识
flowchart LR
A[React 页面] --> B[数据目录 src/data.js]
A --> C[按需详情资源 public/content]
A --> D[浏览器本地状态]
E[内容生成脚本] --> C
E --> F[练习题运行时数据]
G[Node 生产服务] --> A
G --> H[Skill API]
H --> C
I[vibecoding-base-skill] --> H
项目有意把“页面展示”和“术语内容”分开：目录页只携带短元数据，进入详情页后再加载对应的 JSON。这样新增或修订一条术语时，不必把全部长正文重新塞进首页首屏 JavaScript。
| 路由 | 用途 |
|---|---|
| / | 路线先行的“用中学习”起点 |
| /terms | 术语图鉴目录 |
| /topics/backend 等 | 按主题查看术语 |
| /button 等 | 单个术语详情 |
| /practice | 术语判断练习 |
| /courses | 学习路线总览 |
| /courses/product-website | 产品官网路线详情 |
| /courses/product-website/01-product-brief 至 /12-agent-request | 12 个课程章节 |
| /anti-ai-flavor | 防止 AI 味儿专题 |
| /motions | 动效语义图鉴：用实时演示把“顺滑一点”翻译成可执行的动效契约 |
| /vibecoding-base-skill | Skill 介绍与安装页 |
| /vibehub-skill | 兼容旧链接的 Skill 页面别名 |
| /en/* | 英文镜像入口 |
| /.well-known/vibecoding-base.json | Skill API 发现清单 |
| /api/vibecoding-base/search | 术语搜索 |
| /api/vibecoding-base/search?kind=motion | 动效模式搜索 |
| /api/vibecoding-base/lessons/:id | 术语详情 |
| /api/vibecoding-base/motions/:id | 动效模式详情，返回契约、AI 请求和 CSS/React 实现 |
| /healthz | 生产服务健康检查 |
- Node.js 20 或更高版本
- npm 10 或更高版本
- 可访问 GitHub 的浏览器不是运行本地页面的必要条件；已生成的内容资源已随仓库保存
npm ci
npm run dev如果需要让局域网内的其他设备访问：
npm run dev -- --host 0.0.0.0npm run build
npm start默认生产地址：http://127.0.0.1:4173/
也可以只启动 Vite 的静态预览：
npm run build
npm run preview两者区别是：npm run preview 只负责预览构建产物；npm start 还提供 /healthz、SPA 回退和 Skill API，更接近真正的部署形态。
复制 .env.example 作为本地配置参考即可。不要把真实密钥提交到 Git。
VITE_SITE_ORIGIN=https://example.com npm run buildVITE_SITE_ORIGIN 用于生成页面的 canonical URL 和 Open Graph URL。未设置时，页面仍可运行，但生产 SEO 地址需要由部署环境或反向代理补充。
HOST=127.0.0.1
PORT=4173
STATIC_ROOT=./dist
VIBECODING_CONTENT_DIR=./dist/content
VIBECODING_CONTENT_REVISION=production-20260825-v1
VIBECODING_CORS_ORIGINS=https://example.com,https://skill-client.exampleVIBECODING_CORS_ORIGINS 默认允许 *，适合本地调试；正式上线时建议改成明确的来源白名单。VIBECODING_CONTENT_DIR 只在内容资源需要单独挂载时设置，默认会从 dist/content 或项目内的 public/content 读取。
| 命令 | 作用 |
|---|---|
| npm run dev | 启动 Vite 开发服务器 |
| npm run build | 生成内容资源并构建生产包 |
| npm run preview | 预览 dist/ |
| npm start | 启动独立 Node 生产服务 |
| npm run prepare:content | 重新生成 562 个中英文详情 JSON 与练习题运行时数据 |
| npm run validate:data | 校验 281 个术语、255 道题、562 个内容文件 |
| npm run check:routes | 对照公开 sitemap 检查术语路由集合 |
| npm run test:smoke | 检查生产服务、API、SPA 回退和内容资源 |
| npm run check | 内容生成、数据校验、路由检查和生产构建的一键质量门禁 |
提交代码前建议至少运行：
npm run check
npm start > /tmp/vibecoding-base-server.log 2>&1 &
npm run test:smoke启动 npm start 后，可以直接调用：
curl http://127.0.0.1:4173/.well-known/vibecoding-base.json
curl 'http://127.0.0.1:4173/api/vibecoding-base/search?q=button&limit=5'
curl http://127.0.0.1:4173/api/vibecoding-base/lessons/button
curl 'http://127.0.0.1:4173/api/vibecoding-base/search?q=成功&kind=motion&limit=5'
curl http://127.0.0.1:4173/api/vibecoding-base/motions/success-feedback返回结果统一包含 revision，方便 Skill 客户端判断缓存是否需要刷新。术语详情接口返回术语摘要、别名、适用场景、边界、练习题、Agent Prompt、结构拆解、变体、场景、选择器和参考资料等字段；动效详情接口返回 trigger、target、motion、duration、easing、适用边界、减少动态规则以及 CSS/React 实现。
完整字段说明和错误约定见 docs/API.md。
当前仓库把可运行的内容资源直接保存在 public/content/{zh,en}/，构建时会生成到 dist/content/。源数据和生成入口如下：
src/data.js
├── 术语目录、主题和短元数据
└── 练习题关联关系
src/generated-original-content.js
└── 生成脚本读取的内容源
scripts/generate-content-assets.mjs
├── public/content/zh/*.json
├── public/content/en/*.json
└── src/generated-practice-questions.js
若有内容授权并且需要从公开页面刷新原始资料，可使用：
python scripts/fetch-original-content.py --refresh
npm run prepare:content
npm run validate:data该 Python 脚本需要 requests 与 beautifulsoup4。刷新前应先确认来源、使用范围和版权边界；内容抓取成功不等于获得再发布授权。
git clone <your-repository-url>
cd vibecoding-base
npm ci
npm run check
npm run build
HOST=127.0.0.1 PORT=4173 npm start生产环境建议在 Node 服务前面放 Nginx 或 Caddy，负责 HTTPS、域名、压缩和进程重启；反向代理只需要把请求转发到 127.0.0.1:4173，不要把 Node 服务直接暴露在公网。
上线前应至少完成：
- 域名和 HTTPS 配置；
- Node 进程守护与异常重启；
- /healthz 监控；
- API CORS 来源白名单；
- 访问日志和错误日志；
- 内容、品牌和二维码素材授权确认；
- 备份、回滚和版本记录。
更完整的 Nginx、systemd、容器化和回滚说明见 docs/DEPLOYMENT.md。
项目包含三层质量门禁：
数据层：281 术语 + 255 道练习题 + 562 个中英文内容资源
路由层：本地术语集合与公开 sitemap 对照
运行层：生产服务健康检查、API、SPA 回退、资源加载和 404
已经覆盖的回归维度包括：
- 桌面端 1470px 与移动端 390px 视口；
- 首页、术语详情、练习、课程、专题、Skill 和 404；
- 搜索、收藏、主题色、语言切换、交流群弹窗、复制反馈和选择题；
- 页面标题、canonical、Open Graph 基础信息；
- 关键页面无横向溢出；
- 构建无阻塞性错误，生产冒烟测试通过。
.
├── src/
│ ├── App.jsx 页面、路由和交互
│ ├── data.js 术语目录与短元数据
│ ├── content.js 详情资源按需加载
│ ├── generated-*.js 由脚本生成的运行时数据
│ ├── detail-styles.js 详情样式按需加载
│ └── *.css 全局、组件和 Demo 样式
├── public/
│ ├── content/{zh,en}/ 562 个详情 JSON
│ └── assets/ Logo、二维码及页面素材
├── server/
│ ├── production-server.mjs 独立静态/SPA/健康检查服务
│ ├── vibecoding-base-api.mjs Skill API
│ └── content-store.mjs 内容资源读取与版本
├── scripts/
│ ├── generate-content-assets.mjs 内容构建
│ ├── validate-data.mjs 数据完整性校验
│ ├── check-routes.mjs 路由集合校验
│ └── smoke-test.mjs 生产冒烟测试
├── docs/
│ ├── API.md API 字段与调用说明
│ ├── DEPLOYMENT.md 部署、监控和回滚
│ └── RELEASE_CHECKLIST.md 发布前检查单
├── .github/workflows/quality.yml CI 质量检查
└── LICENSE 代码许可证
- 当前实现优先保证页面结构、路由和主要交互的一致性，部分内容与品牌资源仍需人工确认。
- 后台账号、真实学习进度、外部统计和社区状态没有接入；当前收藏、主题等状态保存在浏览器本地。
- API 是只读查询接口，还没有鉴权、用户配额、写入能力、限流和持久化数据库。
- 纯静态托管只能部署页面和内容资源；要让 Skill API 可用，需要 npm start、云函数或其他后端运行时。
- 长正文、Logo、头像、二维码、插画和第三方链接的对外发布，需要逐项确认授权或替换为自有素材。
- 先完成公开发布前的品牌、内容和素材权利确认；
- 接入正式域名、HTTPS、进程守护、健康监控和错误告警；
- 将 CORS 从通配符改成白名单，并增加限流和请求日志；
- 继续拆分懒加载资源，降低首页 JavaScript 和卡片预览 chunk；
- 再考虑账号、学习进度、后台编辑和云端数据同步；
- 对 SEO 做服务端渲染或预渲染，补充 robots.txt、sitemap.xml 和分享图。
欢迎以小步提交的方式修改术语、Demo、练习题和文档。建议遵循：
- 一个提交只解决一个主题；
- 不直接手改生成文件，优先修改源数据或生成脚本；
- 新增术语时同时补中文、英文、练习题和路由校验；
- UI 修改同时检查桌面端、390px 移动端和键盘 focus；
- 提交前运行 npm run check，涉及生产服务时再运行 npm run test:smoke；
- 不提交 .env、访问令牌、账号 Cookie 或未经确认的私人二维码。
本仓库的代码使用 MIT License 发布。MIT License 只覆盖版权归属方拥有或有权授权的代码，不自动覆盖第三方内容、品牌元素、图片、二维码和外部链接；这些内容在对外发布或商业使用前仍需逐项确认授权或替换为自有素材。
- docs/API.md：Skill API 的发现清单、搜索、详情、版本和 CORS
- docs/DEPLOYMENT.md：生产部署、反向代理、监控和回滚
- docs/RELEASE_CHECKLIST.md：发布前技术、内容和合规检查
- LICENSE：代码许可证与使用条件
- vibecoding-base-skill：配套 Skill 仓库