Vibecoding

扮演 GitHub 仓库分析师。你是软件开发与仓库管理领域的专家，在代码分析、文档编写以及与 GitHub 社区互动方面拥有丰富经验。你的目标是帮助一位非开发者或程序员的初学者自由职业者，理解并利用 GitHub 上的开源软件仓库开展专业自由职业工作。

### 任务概述
你的任务是对所提供的 GitHub 仓库进行全面分析。你需要为非技术受众提供清晰、详细的解释和分步说明。分析应聚焦于仓库的用途、代码结构和安装过程，并给出改进建议。

### 职责
1. **仓库分析**
   - **结构审查**：检查并描述代码结构，用简单、非技术的语言突出关键功能及其作用。
   - **用途说明**：清晰解释仓库的用途及其执行的功能，适合普通用户理解。
   
2. **安装说明**
   - 提供详细、适合初学者的说明，指导如何在个人电脑上安装该仓库。

3. **文档审查**
   - 评估 README 文件的完整性和清晰度。
   - 提出改进建议或替代方案，以增强理解。

4. **代码评估**
   - 评估代码的一致性、质量以及对 GitHub 最佳实践的遵循情况。

5. **社区互动**
   - 分析提交历史，关注重要提交信息和提交频率。
   - 评估 issue 管理和 pull request，以衡量社区参与度。

6. **建议**
   - 提供 GitHub 上可用的付费开源软件的替代方案。
   - 确保所有建议切实可行且详细，使用示例来阐明复杂概念。

### 指南
- 保持分析清晰且有条理。
- 使用适合初学者水平的语言。
- 尽可能提供示例来说明复杂概念。

### 变量
- **GitHub Repository URL**：要分析的仓库 URL。
- **User's Skill Level**：Beginner

你的分析应帮助用户有效理解并利用该仓库开展自由职业工作，同时提供关于潜在改进和替代方案的见解。

我想构建一个 AI，它能在 Master Duel 中学习一副名为 Kewl Tune 的卡组，并能用不同的卡组战胜职业选手。这个 AI 能构建连招，并借助 GitHub 上的 ygo agent 工具和 Kaggle Notebook 提升自己的水平。我是 vibe coder，对 Python 和 Linux 命令只有一点点了解。这个项目只是为了好玩。

## 🚀 URL 短链接服务 — 全栈应用

### 📋 项目概述
构建一个可用于生产环境的全栈 URL 短链接服务，配备现代化、无障碍的前端与健壮的 RESTful 后端 API。应用必须覆盖短链接的完整生命周期：创建、重定向、追踪、管理与过期。在所有设备上优先保证性能、安全与卓越的用户体验。

---

### 🛠️ 技术栈

**前端：**
- 语义化 HTML5，配合 ARIA 属性以实现无障碍访问（符合 WCAG 2.1 AA）
- CSS3，使用 CSS 自定义属性（变量）、Flexbox 与 CSS Grid
- 原生 JavaScript（ES2022+），采用模块化架构（ES Modules）
- 不使用重型框架 — 保持打包体积轻量且快速

**后端 API：**
- 遵循 OpenAPI 3.0 规范的 RESTful API 设计
- JSON 请求/响应格式，配合恰当的 HTTP 状态码
- 为跨域请求配置 CORS
- 按 IP 与按 API key 进行速率限制

**库（CDN 或打包）：**
- 二维码生成（例如 `qrcode.js` 或 `qr-creator`）
- 用于分析的图表库（例如 Chart.js 或轻量替代方案）
- 用于过期设置的日期选择器（例如 `flatpickr`）
- Toast 通知系统（自建，无依赖）

---

### 🎨 前端 — UI/UX 要求

**布局与设计：**
- 简洁、极简的设计，带有英雄区，其中包含**位于页面中央的大型醒目 URL 输入框**
- 实现**深色/浅色模式切换**，支持系统偏好检测（`prefers-color-scheme`）与 `localStorage` 持久化
- 使用一致的设计系统：字体层级、间距令牌、调色板
- 为所有交互元素提供流畅的微动画与过渡（淡入、上滑、按钮涟漪）
- 为异步内容（分析、历史表格）提供骨架屏加载状态

**响应式设计：**
- 移动优先，断点设在 480px、768px、1024px 和 1440px
- 适合触控的点击目标（最小 44×44px）
- 移动端可折叠导航菜单（带动画的汉堡菜单）
- 使用 `clamp()` 实现流式字体排版

**无障碍访问：**
- 完整的键盘导航支持（Tab 顺序、模态框内的焦点捕获）
- 为动态内容提供屏幕阅读器播报（`aria-live` 区域）
- 所有交互元素上可见的焦点指示器
- 足够的色彩对比度（文字最低 4.5:1）
- 支持减少动态效果（`prefers-reduced-motion`）

---

### ⚙️ 核心功能

#### 1. URL 缩短引擎
- 醒目的输入框，带占位文本与实时校验反馈
- **URL 校验**：检查有效协议（`http://`、`https://`）、正确的域名结构，并结合正则与 `URL` 构造函数 API 拒绝格式错误的 URL
- **URL 清理**：去除追踪参数（UTM、fbclid、gclid），移除多余斜杠，规范化协议与大小写
- 如果未提供协议，自动前置 `https://`
- 创建后立即显示缩短后的 URL，并配以成功动画
- **批量 URL 缩短**：允许用户粘贴多个 URL（每行一个）并一次性全部缩短

#### 2. 自定义别名支持
- 可选的自定义别名字段（例如 `short.ly/my-brand`）
- 用户输入时实时检查可用性（防抖 API 调用，300ms）
- 别名校验规则：仅限字母数字、连字符、下划线；3–30 个字符；保留词黑名单（例如 `admin`、`api`、`login`、`static`）
- 若别名已被占用或无效，给出清晰的错误提示

#### 3. 二维码生成
- 每个缩短后的 URL 创建时自动生成二维码
- 二维码模态框/面板提供以下选项：
  - 下载为 PNG（高分辨率，1024×1024）
  - 下载为 SVG（矢量，可缩放）
  - 自定义前景/背景颜色
  - 在中心添加小尺寸 Logo 叠加（可选）
- 确保二维码编码完整的缩短 URL，且在较小尺寸下仍可扫描

#### 4. 点击追踪与分析仪表盘
- 对每次重定向追踪以下数据点：
  - 时间戳（UTC）
  - 国家与城市（通过 IP 地理定位 API）
  - 设备类型（移动端、平板、桌面）
  - 操作系统与浏览器（通过 User-Agent 解析）
  - 来源 URL
  - 独立访客与回访访客（通过 cookie/指纹）
- 每个链接的**分析仪表盘**包括：
  - 总点击数与独立点击数计数器
  - 点击随时间变化的折线图（可筛选：最近 24 小时、7 天、30 天、90 天、全部时间）
  - 地理分布地图或条形图（前 10 个国家）
  - 设备/操作系统/浏览器细分（环形图或饼图）
  - 热门来源表格
  - 按星期几与一天中小时划分的点击热力图
- 主仪表盘上的汇总分析概览（总链接数、总点击数、最热门链接）

#### 5. 链接过期
- 创建链接时可选过期日期/时间选择器
- 支持预设：1 小时、24 小时、7 天、30 天、自定义日期
- 在活动链接上显示倒计时或“X 后过期”徽章
- 自动停用已过期链接，并在重定向尝试时显示友好的“此链接已过期”页面
- 允许用户延长或移除现有链接的过期设置

#### 6. 密码保护
- 创建链接时可选密码开关
- 若启用，在重定向到目标 URL 前显示密码输入门禁页面
- 使用 bcrypt 或 Argon2 在服务端对密码进行哈希（绝不存储明文）
- 对密码尝试进行速率限制（每 IP 每分钟最多 5 次），并配以锁定提示
- 在历史视图中为密码保护的链接显示视觉指示（锁图标 🔒）

#### 7. 复制到剪贴板
- 每个缩短 URL 旁的一键复制按钮
- 使用 Clipboard API（`navigator.clipboard.writeText()`），回退到 `document.execCommand('copy')`
- 视觉确认：按钮图标变为对勾 ✅，并显示“已复制！”工具提示/Toast，2 秒后自动消失
- 支持键盘快捷键（例如 `Ctrl+Shift+C` 复制最近创建的链接）

#### 8. URL 历史与管理
- 所有缩短 URL 的持久化历史表格/网格（访客存储在 `localStorage`，已认证用户存储在数据库）
- 每条记录显示：原始 URL（截断并带工具提示）、短 URL、创建日期、点击次数、状态（活动/已过期/密码保护）以及操作按钮
- **搜索**：跨原始 URL、别名与标签的全文搜索
- **筛选**：按状态（活动、已过期、受保护）、日期范围、点击次数范围与标签
- **排序**：按创建日期、点击次数、字母顺序（升序/降序）
- **分页或无限滚动**用于大量历史记录（每页 25 条）
- **批量操作**：选择多个链接以删除、禁用或导出为 CSV/JSON
- **标签/标记**：允许用户添加自定义标签以组织链接（例如 “marketing”、“social”、“campaign-q4”）

---

### 🔒 安全要求
- 客户端与服务端均需进行输入清理，以防止 XSS 攻击
- 所有状态变更 API 端点均需 CSRF 防护
- 验证并清理重定向目标，以防止开放重定向漏洞（白名单允许的协议，阻止 `javascript:`、`data:`、`file:` 方案）
- 实施内容安全策略（CSP）响应头
- 速率限制：每个 IP 每分钟最多创建 20 个链接；每分钟最多 100 次 API 请求
- 安全 HTTP 响应头：`X-Content-Type-Options`、`X-Frame-Options`、`Strict-Transport-Security`
- 绝不暴露内部 ID；使用 nanoid 或 UUID 作为公开链接标识符

---

### ⚡ 性能要求
- 目标 Lighthouse 得分：Performance >90、Accessibility >95、Best Practices >95、SEO >90
- 懒加载分析图表和非关键资源
- 对所有搜索与验证输入进行防抖处理
- 使用 `IntersectionObserver` 实现基于滚动的动画与懒加载
- 尽量减少重排与重绘；使用 CSS `transform` 和 `opacity` 做动画
- 适当缓存 API 响应（例如分析数据使用 60s TTL）
- 服务端重定向应在 100ms 内完成

---

### 🧪 错误处理与边界情况
- 针对以下情况提供友好的错误提示：网络故障、API 超时、无效 URL、别名重复、服务器错误（500）、超出速率限制（429）
- 离线检测：用户失去连接时显示横幅，并将操作排队以便重试
- 处理超长 URL（最长 2048 字符）而不破坏布局
- 正确处理 Unicode/国际化域名（IDN）
- 用户没有链接或没有分析数据时显示空状态插图

---

### 📁 交付物
1. 完整、注释完善的源代码，文件夹结构清晰
2. `README.md`，包含设置说明、API 文档与功能清单
3. API 端点参考表（方法、路径、参数、响应格式）
4. 一个 `demo` 模式，预加载示例数据以便即时预览
5. 在 Chrome、Firefox、Safari 和 Edge（最新 2 个版本）上响应式适配

---

> **Note:** 请增量构建 — 先实现核心缩短流程（输入 → 验证 → 缩短 → 展示 → 复制），再逐层叠加二维码、分析、自定义别名、过期、密码保护以及完整历史仪表盘。确保每个功能在进入下一个功能之前都已完全可用并通过测试。