Imported from WhiteWorld/codepick (
AGENTS.md). Install upstream withnpx skills add WhiteWorld/codepick. Copyright stays with the author.
CodePick — AGENTS.md
面向开发者的 AI 编程工具选型静态网站。基于 Astro 7.2 SSG + YAML 数据 + 双语(中/英)+ Vercel 部署。
常用命令
npm run dev # 本地开发服务器
npm run build # 构建(每次改动后务必验证)
npm run preview # 预览构建结果
npm run monitor # Python 数据监控脚本
npm run dashboard # Python 数据 dashboard
npm run gen-og # 重新生成 OG 图片(需要 sharp)
npm run gen-social-post # 生成社交媒体发帖模板
npm run gen-juejin # 生成掘金发帖模板
npm run update-github-tools # 自动更新 GitHub 开源工具数据
npm run update-closed-source-tools # 自动更新闭源工具数据
npm run update-all-tools # 同时运行上面两个脚本
项目结构
data/
tools/*.yaml # 工具数据(每个工具一个文件,共 20 个)
apis/*.yaml # API 源数据(ark, bailian, ollama, openrouter)
plans/*.yaml # 方案数据(工具 + API 组合,共 14 个)
src/
lib/
data.ts # YAML 加载 + 归一化 + TypeScript 接口定义
i18n.ts # 双语翻译系统(150+ 翻译 key,t()、localePath() 等)
faq-data.ts # FAQ 内容数据
page-views/ # 页面模板组件(19 个,含所有页面 UI 逻辑)
HomePage.astro
ToolDetailPage.astro
ToolsIndexPage.astro
ToolsOverviewPage.astro # 全景图(比分矩阵 + 决策树)
ToolsFreePage.astro
ToolsChinaPage.astro
ToolsTerminalPage.astro
ToolsVscodePage.astro
ToolsBuilderPage.astro # 应用构建型工具(Bolt / v0 / Lovable 等)
ToolsComparePage.astro # 工具对比矩阵页
PlanDetailPage.astro
CompareArticlePage.astro
CompareIndexPage.astro
GuidesArticlePage.astro
GuidesIndexPage.astro
FaqPage.astro
CodingPlanPage.astro # Coding Plan 专题页
DealsPage.astro # 优惠/折扣汇总页
PromptsPage.astro # 提示词 / 规则模板页
pages/
index.astro # 根路径语言重定向(JS 检测 navigator.language)
api/openrouter.json.ts # OpenRouter API 端点
zh/ # 中文路由(薄包装,透传 lang="zh" 给 page-views)
index.astro / faq.astro / coding-plan.astro / deals.astro / prompts.astro
rss.xml.ts # 中文 RSS feed(聚合 compare + guides)
tool/[id].astro / plan/[id].astro
compare/index.astro / compare/[slug].astro
guides/index.astro / guides/[slug].astro
tools/index|free|china|vscode|terminal|overview|builder|compare.astro
en/ # 英文路由(结构与 zh/ 完全镜像,透传 lang="en")
rss.xml.ts # 英文 RSS feed
content/
config.ts # Content Collections 定义(4 个集合)
compare/*.md # 对比文章(中文,Astro Content Collections)
compare-en/*.md # 对比文章(英文版本)
guides/*.md # 使用指南(中文)
guides-en/*.md # 使用指南(英文版本)
layouts/
BaseLayout.astro # 主布局:OG/canonical/JSON-LD/hreflang/语言切换/Analytics
components/
ToolCard.astro # 工具卡片(复用于各分类页)
PlanCard.astro # 方案卡片(含组合预览)
ScenarioCard.astro # 首页场景速查卡片
QuickPicker.astro # 30 秒选型问卷(3 题 → 推荐方案)
ScoreBar.astro # 评分可视化条形图
CompareTable.astro # 功能对比矩阵
FilterBar.astro # 工具筛选控件
TableOfContents.astro # 文章目录组件
Comments.astro # 评论组件
ShareBar.astro # 文章/工具/方案底部分享栏(zh: X/微博/掘金/复制;en: X/LinkedIn/Reddit/HN/Copy)
styles/
global.css # 全局样式(TailwindCSS 指令)
scripts/
check-freshness.mjs # 检测 YAML 数据新鲜度,超期自动创建 GitHub Issue
gen-og-image.mjs # 生成 OG 图片(1200×630,需要 sharp)
gen-social-post.mjs # 生成社交发帖模板
gen-juejin-post.mjs # 生成掘金发帖模板
monitor.py # 检测工具版本/定价变化,创建 GitHub Issue
update-github-tools.mjs # 自动更新 GitHub 开源工具版本
update-closed-source-tools.mjs # 自动更新闭源工具数据
.github/workflows/
monitor.yml # 每周一 09:00(北京)运行 monitor.py
freshness.yml # 每周一 09:00(北京)运行 check-freshness.mjs
双语架构(i18n)
路由规则
- 所有页面都有
/zh/...和/en/...两个版本 - Astro i18n 配置:
defaultLocale: 'zh',prefixDefaultLocale: true - 根路径
/index.astro用 JS 检测navigator.language,自动跳转/zh/或/en/ vercel.json中配置了 15 条 301 重定向,将旧路径(如/tools)重定向到/zh/tools
page-views 模式
路由文件(src/pages/zh/ 和 src/pages/en/)只是薄包装:
---
import ToolDetailPage from '../../../page-views/ToolDetailPage.astro';
import { getToolLocalized } from '../../../lib/data';
// ...
---
<ToolDetailPage tool={tool} lang="zh" />
所有 UI 逻辑都在 src/page-views/ 中,路由文件仅负责传入 lang 属性和获取数据。
翻译系统
使用 src/lib/i18n.ts 中的 t(key, lang) 函数:
import { t, localePath, getLocaleFromUrl } from '../lib/i18n';
// 翻译
t('nav.tools', lang) // zh: "工具库",en: "Tools"
t('score.coding', lang) // zh: "编程",en: "Coding"
// 带 locale 前缀的路径
localePath('/tools/free', lang) // "/zh/tools/free" 或 "/en/tools/free"
// 获取当前语言
const lang = getLocaleFromUrl(Astro.url) // 'zh' 或 'en'
内容集合(Content Collections)
4 个集合定义在 src/content/config.ts:
compare— 中文对比文章guides— 中文使用指南compare-en— 英文对比文章guides-en— 英文使用指南
获取集合时使用 getCollectionName(base, lang) 工具函数:
import { getCollectionName } from '../lib/i18n';
const collection = getCollectionName('compare', lang); // 'compare' 或 'compare-en'
工作流偏好
- 写完改动后不要自动
git add/commit,等用户确认后再提交 - 提交前先运行
npm run build验证构建无报错
新增工具流程
- 在
data/tools/创建<tool-id>.yaml(参考下方字段规范) - 如需新增 API 源,在
data/apis/创建对应 YAML - 如需新增方案,在
data/plans/创建对应 YAML - 运行
npm run build确认/zh/tool/<id>和/en/tool/<id>页面正常生成 - 等用户确认后提交
工具 YAML 完整字段规范
id: tool-id # URL slug,唯一,英文小写+连字符
name: "工具名"
type: ide|cli|plugin|client|web|app|cloud_agent
logo: /images/tool-id.png
url: https://example.com
repo: https://github.com/org/repo # 开源工具填写;闭源为 null
current_version: '1.0'
version_tracked_at: 'YYYY-MM-DD'
pricing:
model: subscription|pay_as_you_go|free|open_source
currency: USD|CNY
plans:
- name: Free
price: 0 # 数字 0 = 免费工具落地页收录
limits: 有限额度 # 中文
limits_en: Limited quota # 英文(可选)
- name: Pro
price: 20
period: month
per_user: false # true = 按用户计费
limits: 无限额度
limits_en: Unlimited
price_updated_at: 'YYYY-MM-DD'
note: 备注(中文)
note_en: Note (English)
scores:
coding_ability: 0-10
cost_efficiency: 0-10
flexibility: 0-10
china_friendly: 0-10 # 国内可用性评分
privacy: 0-10
features:
code_completion: true|false
chat: true|false
agent_mode: true|false
multi_file_edit: true|false
mcp_support: true|false
ide_base: "VS Code Fork" # 分类落地页过滤依据
supported_models:
- Codex Sonnet 4.5
- GPT-5
supported_os: [macOS, Windows, Linux]
best_for:
- 全栈开发者(中文)
best_for_en:
- Full-stack developers (English)
not_for:
- JetBrains 用户
not_for_en:
- JetBrains users
changelog:
- date: 'YYYY-MM-DD'
type: feature|pricing|model|fix|announcement
summary: 更新内容(中文)
summary_en: Update description (English)
data_sources:
- url: https://example.com/pricing
type: pricing|changelog|docs
last_checked: 'YYYY-MM-DD'
last_full_review: 'YYYY-MM-DD' # 最后完整核查日期(用于 sitemap lastmod)
next_review_due: 'YYYY-MM-DD' # 下次核查截止日期
review_frequency_days: 30 # 核查频率(天)
confidence: high|medium|low
方案 YAML 字段规范
id: plan-id
name: "方案名(中文)"
name_en: "Plan Name (English)"
badge: "性价比之王" # 徽章标签(中文)
badge_en: "Best Value" # 徽章标签(英文)
type: ide|plugin|diy|cli
composition: # 或直接用 client/api 顶级字段
client: tool-id # 引用 data/tools/ 的 id
api: api-id # 引用 data/apis/ 的 id(内置模型填 null)
environment: VS Code
monthly_cost: "$20" # 字符串;或对象:
monthly_cost:
min: "¥9.9"
typical: "¥9.9"
max: "¥49.9"
currency: CNY|USD
scores:
coding_ability: 8.2
cost_efficiency: 9.6
flexibility: 9.5
china_friendly: 9.0
tags: [diy, budget, china, agent, vscode, ide, cli, privacy, power]
best_for:
- 预算有限的国内开发者
best_for_en:
- Budget-conscious developers in China
quick_start:
- 步骤一(中文)
quick_start_en:
- Step 1 (English)
pros:
- 优点(中文)
pros_en:
- Pros (English)
cons:
- 缺点(中文)
cons_en:
- Cons (English)
setup_difficulty: 简单|中等|复杂
分类落地页过滤逻辑
/tools/free:pricing.plans[].price === 0(数字零)/tools/china:scores.china_friendly >= 7/tools/vscode:features.ide_base含 "vs code" 或 "vscode"(大小写不敏感)/tools/terminal:type === 'cli'或features.ide_base含 "终端/tui/cli"/tools/builder:type === 'web'(AI 应用构建器:Lovable / Bolt.new / v0 / Youware)/tools/compare:客户端 JS 交互式对比矩阵(不过滤,展示全部工具)
内容文章规范
src/content/compare/*.md、src/content/guides/*.md(及对应 -en/ 目录)frontmatter:
---
title: "..."
description: "..."
date: "YYYY-MM-DD"
tags: [cursor, copilot, comparison]
draft: false # true 则不显示
---
新增文章时需同时创建中英文版本(compare/slug.md + compare-en/slug.md)。
数据工具函数(src/lib/data.ts)
// 基础 CRUD(不带 locale)
getAllTools() → Tool[]
getTool(id) → Tool | undefined
getAllPlans() → Plan[]
getPlan(id) → Plan | undefined
getAllApis() → Api[]
getApi(id) → Api | undefined
// 带 locale 的版本(自动解析 _en 字段)
getAllToolsLocalized(lang) → Tool[]
getToolLocalized(id, lang) → Tool | undefined
getAllPlansLocalized(lang) → Plan[]
getPlanLocalized(id, lang) → Plan | undefined
getAllApisLocalized(lang) → Api[]
// 组合查询
getPlanWithDetailsLocalized(id, lang) → { ...plan, clientDetail, apiDetail }
// 工具函数
overallScore(scores) → number # 计算综合分(各维度均值)
isFresh(dateStr) → boolean # 检查 next_review_due 是否未过期
技术栈
- Astro 7.2 SSG,i18n 双语路由(
/zh/+/en/),vite.ssr.noExternal: ['js-yaml'] - TailwindCSS v3 +
@tailwindcss/typography(对比文章 prose 样式) - @astrojs/sitemap(自动生成 sitemap,带 lastmod;site:
https://codepick.dev) - @vercel/analytics(Vercel 分析,嵌入 BaseLayout)
- js-yaml — 在 Astro 构建时加载 YAML 数据
- sharp — OG 图片生成
- Vercel 部署,push main 分支自动触发;
vercel.json定义重定向规则 - GitHub Actions — 每周一自动运行数据监控(
monitor.yml)和新鲜度检查(freshness.yml)
当前工具库
当前规模(以各目录实际内容为准,不在此维护完整清单):
- 39 个工具(
data/tools/) - 8 个 API / 模型源(
data/apis/) - 16 个方案(
data/plans/)
