Codex Process Review 这次我是怎么把需求做成上线产品的
From idea to deployed product

从一句需求，到 GitHub + Vercel 真正上线。

这页不是在介绍最终网站，而是在拆解我这次实际的工作方式：我如何先收敛需求，再接管仓库、搭建工程骨架、实现数据抓取与自动更新、完成测试和构建，最后推送到 GitHub 并部署到 Vercel。

最终结果 已上线
核心模块 3 大榜单
自动刷新 6 小时
真实刷新验证 28 条信号

执行过程

这是我这次实际的工作顺序，不是事后包装。整个过程先做需求收敛，再进入实现，最后做构建、推送和部署。

真实执行链路
Step 01

先收敛产品定义

我没有上来就写代码，而是先把需求拆成几个关键决策：第三部分的 “skill” 指什么、社交媒体热榜要不要强依赖 X、这个站是只看今日还是支持历史与主题筛选、数据源是否允许第三方免费 API / RSS。这样做是为了把后续技术方案锁住，避免写了一半再返工。

Step 02

确认架构路线

在几个候选方案里，我收敛到 “GitHub 仓库 + GitHub Actions 定时更新 + Next.js 静态站 + Vercel 部署” 这条路线。原因很简单：成本低、稳定、适合个人产品，而且自动化链路清晰。

Step 03

接管仓库并搭工程骨架

拿到你的 GitHub 仓库后，我先克隆到本地，发现是空仓库，所以直接用官方 Next.js 脚手架初始化项目，再补上测试依赖、数据脚本依赖和视觉字体资源。因为空仓库没有历史包袱，这一步反而很顺。

Step 04

把数据模型先搭清楚

我先定义统一的 schema、打标规则、评分逻辑和快照结构，再写 GitHub / 社交媒体 / Agent Skills 三条抓取脚本。这样页面不会绑死在某个单一数据源上，后面换源或加源都比较轻松。

Step 05

实现 Today / History / Trends

前端没有做成普通博客页，而是做成一个偏情报驾驶舱的结构：首页看当天三榜，History 看历史快照，Trends 看重复出现的信号与高频标签。页面本身只读仓库里的 JSON，不需要数据库。

Step 06

把自动更新和部署闭环接好

最后我配置了 GitHub Actions：定时跑数据更新、写回 data 目录、再触发 Vercel 自动部署。然后我本地跑了 lint、test、build、build:data，确认通过后提交到 GitHub，再把项目和 Vercel scope 连接并发布上线。

用到的工具

这次不是只用一个“写代码工具”，而是组合了终端、补丁编辑、并行读取、Git、Vercel 和测试工具链。

工具不是目的，闭环才是目的

终端命令

  • 用 `git clone` 接管仓库
  • 用 `npm create next-app` 初始化项目
  • 用 `npm install` 补依赖
  • 用 `npm run lint / test / build / build:data` 做验证

代码编辑

  • 用补丁式编辑修改和创建文件
  • 把改动集中在 `src/`、`scripts/`、`data/`、`.github/workflows/`
  • 保证每次改动都有明确目的，而不是散改

并行读取与检查

  • 并行查看多个文件、配置和构建状态
  • 快速确认仓库结构、依赖、类型错误和构建输出
  • 减少来回等待，提高迭代速度

Git / GitHub

  • 本地提交首个版本
  • 推送到 `main` 分支
  • 把仓库作为代码和数据的统一来源

Vercel

  • 检查登录态 `vercel whoami`
  • 显式 `link` 到团队 scope
  • 触发生产部署并拿到稳定别名地址

测试与质量保障

  • Vitest 测 schema、评分、标签、数据构建
  • ESLint 保证基础代码质量
  • 生产构建确保静态路由和页面真实可生成

遇到的问题，以及怎么解决

这些都是真实碰到的工程问题。重点不是“没出问题”，而是出问题后如何快速定位并把链路继续往前推。

问题不可避免，卡住才是问题
脚手架初始化

`@/*` 被 shell 当成通配符

  • 第一次运行 `next-app` 时，`@/*` 没加引号，zsh 直接报模式匹配错误。
  • 解决方式：重跑命令并修正参数传递方式，让脚手架正常初始化。
补丁路径

补丁最开始打到了上一级目录

  • 第一次集中写文件时，补丁路径相对的是当前工作区，而不是 `news` 仓库。
  • 解决方式：把所有路径显式改成 `news/...`，再重打一遍补丁。
Next.js 构建边界

客户端组件间接引用了 `node:fs`

  • 历史页构建时报错，原因是客户端组件通过一个工具函数间接依赖了服务端文件系统模块。
  • 解决方式：把源状态汇总留在服务端页面计算，再作为 props 传给客户端组件。
TypeScript 类型

`import.meta.main` 和可选数组索引类型报错

  • Next 的类型检查对脚本文件也会检查，`import.meta.main` 不兼容当前配置。
  • GitHub 抓取脚本里直接写 `items[number]`，而 `items` 是可选数组。
  • 解决方式：改成 `process.argv + pathToFileURL` 判断入口，并抽出独立 `GithubRepository` 类型。
Vercel 部署

非交互环境缺少默认 scope

  • 第一次 `vercel --prod` 返回 `missing_scope`，提示需要显式指定团队。
  • 解决方式：先 `vercel link --scope zhengzhang`，再正式发起生产部署。
数据验证

不能只依赖种子数据

  • 如果只看预置 JSON，很容易误以为链路没问题。
  • 解决方式：我实际跑了 `npm run build:data`，确认真实数据能抓下来，并生成了 28 条信号。

我的工作原理

如果把这次工作抽象成一个方法论，它其实是一条很稳定的产品工程流水线：先定义边界，再搭骨架，再把数据与界面接起来，最后用测试和部署闭环收口。

从需求到上线的通用框架
需求澄清 先把模糊概念收敛成确定范围，比如 skill 的定义、数据源边界、历史回看是否需要。
→
架构选型 选一条最适合目标的路线：GitHub + Actions + Next.js + Vercel，而不是一味追求复杂能力。
→
骨架搭建 先把项目可运行、可测试、可部署，再在这个骨架上逐层加功能。
数据建模 统一 schema、标签、评分、快照结构，让不同来源的数据都能落到同一种形态。
→
UI 呈现 页面只消费标准化后的 JSON，所以 Today / History / Trends 都能稳定工作。
→
验证与上线 lint、test、build、真实抓取验证、git push、Vercel 部署，一个都不跳过。

为什么这种方式可靠

  • 先收敛需求，能显著减少返工。
  • 先搭底层数据模型，后做 UI，后续扩展成本低。
  • 每次出错都通过构建和日志迅速定位，而不是盲猜。
  • 把“开发完成”定义成“真实可部署、真实可更新”，而不是“代码看起来写完了”。
  • 仓库、数据、自动更新、部署在同一个闭环里，后续你自己接手也不难。

关键文件

如果你想从代码层面理解这次工作的结构，下面这些文件最值得先看。

先看结构，再看细节

前端入口

  • src/app/page.tsx
  • src/app/history/[date]/page.tsx
  • src/app/trends/page.tsx
  • src/components/dashboard-explorer.tsx

数据处理

  • src/lib/schema.ts
  • src/lib/normalize.ts
  • src/lib/scoring.ts
  • src/lib/tags.ts

抓取与自动化

  • scripts/build-dashboard.ts
  • scripts/fetch-github.ts
  • scripts/fetch-social.ts
  • .github/workflows/update-data.yml
你可以把这个页面理解成一份“可视化工程复盘”。它的目的不是展示漂亮界面本身，而是让你真正看懂这次我是怎么工作的：为什么先问问题、为什么先搭 schema、为什么要跑真实刷新、为什么最后还要自己把部署闭环验证一遍。