33-js-concepts 资源策展方法论：为 JavaScript 概念页构建、审计与维护高质量学习资源库

这篇文章基于 33-js-concepts 项目中的技能文档 .opencode/skill/resource-curator/SKILL.md 编写，完整讲解该项目如何为每一篇 JavaScript 概念文档寻找、评估、撰写描述并持续维护外部学习资源（参考文档、文章、视频、课程），包括五阶段策展方法、可信来源优先级、质量红线、链接审计流程与 MDX Card 排版规范。读完本文，你可以独立对一个概念页执行完整的资源策展与审计，产出符合项目标准的资源区块（Reference / Articles / Videos）和结构化审计报告。

一、Resource Curator 在项目中的定位

33-js-concepts 是一个 JavaScript 核心概念教学项目，全部概念页位于 docs/concepts/ 与 docs/beyond/concepts/。每一篇概念页在正文之后都带有固定的资源区块：官方参考（Reference）、文章（Articles）、视频（Videos），以及可选的课程（Courses）与书籍（Books）。以 docs/concepts/promises.mdx 为例，其页尾依次使用 <CardGroup cols={2}> 包裹若干 <Card> 组件，分别挂载 book、newspaper、video 三种图标，链接到 MDN、javascript.info、web.dev 等外部资源。

这些资源区块并非手工随意堆砌，而是由一套标准化的策展流程产出的。项目通过 opencode 的技能（Skill）系统来沉淀这套流程：

• .opencode/skill/resource-curator/SKILL.md：资源策展与链接审计的完整方法论，即本文主体；
• .opencode/skill/write-concept/SKILL.md：概念页写作规范，其中“Resource Curation Guidelines”一节与 resource-curator 的质量标准互相印证；
• .opencode/skill/concept-workflow/SKILL.md：端到端工作流，将资源策展编排为整个概念页生产流程的第一阶段；
• opencode.jsonc：启用 skill 工具，并对 resource-curator、write-concept、fact-check、seo-review、test-writer、concept-workflow 六个技能统一设置 "allow" 权限，其余技能默认 "ask"。

从源码结构看，资源策展被明确定位为概念页生产五阶段工作流的 Phase 1（RESEARCH）：先于写作（Phase 2）、测试（Phase 3）、事实核查（Phase 4）、SEO 审查（Phase 5）执行，且各阶段之间存在质量门（Quality Gates）——只有通过全部门检才允许进入下一阶段。文档站本身构建于 Mintlify 之上，package.json 中的脚本 docs（cd docs && npx mintlify dev）与 docs:build 说明了 CardGroup/Card 这类组件的渲染环境。

二、适用场景

根据技能文档的 “When to Use” 章节，资源策展流程适用于以下五类场景：

• 为新建的概念页添加资源；
• 刷新现有概念页上的资源；
• 审计失效链接与过期内容；
• 审阅社区贡献的资源（配合项目的 CONTRIBUTING.md 流程）；
• 周期性链接维护（Periodic link maintenance）。

概念工作流技能中还特别区分了“全流程”与“单技能”的使用边界：仅补充资源时直接用 resource-curator，而不是启动完整的 concept-workflow。

三、五阶段资源策展方法

方法论的核心是五个按序执行的阶段：先审计存量，再找差距，然后找新资源、写描述、最后排版入库。

Phase 1：审计现有资源

在添加任何新资源之前，先审计页面上已有的资源，逐项检查五件事：

1. 检查链接可达性（Check link accessibility） — 每个链接是否返回 200；
2. 验证内容准确性（Verify content accuracy） — 内容是否仍然正确；
3. 检查发布日期（Check publication dates） — 对这个主题而言是否过于陈旧；
4. 识别过期内容（Identify outdated content） — 是否使用了过时的语法或模式；
5. 审阅描述（Review descriptions） — 描述是具体的还是泛泛而谈的。

Phase 2：识别资源缺口

将现有资源与每个区块的目标数量对比。技能文档给出的目标是：

区块（Section）	目标数量（Target Count）	图标（Icon）
Reference	2–4 个 MDN 链接	book
Articles	4–6 篇文章	newspaper
Videos	3–4 个视频	video
Courses	1–3 个（可选）	graduation-cap
Books	1–2 本（可选）	book

同时自问四个问题，判断资源组合是否完整：

• 是否同时覆盖了初学者与进阶者的资源？
• 是否有视觉型内容（图解、动画）？
• 是否包含官方参考（MDN）？
• 教学风格是否有多样性（diversity in teaching styles）？

Phase 3：寻找新资源

通过定向搜索在可信来源中检索。技能文档为三类资源分别给出了查询模板（[concept] 替换为具体概念名）：

文章类（For Articles）：

[concept] javascript tutorial site:javascript.info
[concept] javascript explained site:freecodecamp.org
[concept] javascript site:dev.to
[concept] javascript deep dive site:2ality.com
[concept] javascript guide site:css-tricks.com

视频类（For Videos，YouTube 站内搜索）：

YouTube: [concept] javascript explained
YouTube: [concept] javascript tutorial
YouTube: jsconf [concept]
YouTube: [concept] javascript fireship
YouTube: [concept] javascript web dev simplified

MDN 参考类（For MDN）：

[concept] site:developer.mozilla.org
[API name] MDN

Phase 4：撰写描述

每一条资源都需要一段具体且有价值的描述。公式为两句话：

Sentence 1: What makes this resource unique OR what it specifically covers
Sentence 2: Why reader should click (what they'll gain, who it's best for)

第一句说明该资源的独特性或其具体覆盖范围；第二句说明读者点击的理由（能得到什么、适合谁）。完整的描述写作规范见本文第七节。

Phase 5：格式化与组织

• 使用正确的 Card 语法并搭配对应图标；
• 按逻辑顺序排列资源（基础内容在前，进阶内容在后）；
• 保持格式一致性。

四、可信来源清单

技能文档为三类来源分别建立了优先级表，这是筛选资源时的“白名单”。

参考来源（Reference Sources，优先级顺序）

优先级	来源	URL	最适用场景（Best For）
1	MDN Web Docs	developer.mozilla.org	API 文档、指南、兼容性
2	ECMAScript Spec	tc39.es/ecma262	权威行为定义
3	Node.js Docs	nodejs.org/docs	Node 专属 API
4	Web.dev	web.dev	性能、最佳实践
5	Can I Use	caniuse.com	浏览器兼容性

文章来源（Article Sources，优先级顺序）

优先级	来源	受信任原因
1	javascript.info	全面、含练习、维护良好
2	MDN Guides	官方、准确、定期更新
3	freeCodeCamp	对初学者友好、实用
4	2ality（Dr. Axel）	深度技术剖析、聚焦规范
5	CSS-Tricks	DOM、视觉主题、行文质量高
6	dev.to（Lydia Hallie）	视觉化讲解、动画
7	LogRocket Blog	实用教程、贴近实战
8	Smashing Magazine	深入、研究充分
9	Digital Ocean	教程清晰、示例丰富
10	Kent C. Dodds	测试、React、最佳实践

视频创作者（Video Creators，优先级顺序）

优先级	创作者	风格	最适用场景
1	Fireship	快节奏、现代、有趣	快速概览、现代 JS
2	Web Dev Simplified	清晰、对初学者友好	初学者、基础知识
3	Fun Fun Function	深度剖析、有个性	理解“为什么”
4	Traversy Media	全面速成课程	完整覆盖一个主题
5	JSConf/dotJS	专家级会议演讲	进阶、深入
6	Academind	讲解彻底	完整理解
7	The Coding Train	创意、视觉化	视觉型学习者
8	Wes Bos	实用、贴近实战	应用性学习
9	The Net Ninja	分步教程	跟着做
10	Programming with Mosh	专业、清晰	职业导向

课程来源（Course Sources）

来源	类型	备注
javascript.info	免费	全面、含练习
Piccalilli	免费	行文好、现代
freeCodeCamp	免费	项目制
Frontend Masters	付费	专家讲师
Egghead.io	付费	短小、聚焦
Udemy（高评分）	付费	仔细查看评论
Codecademy	免费增值	交互式

五、资源质量准则

质量准则分为三层：必须满足（Must Have）、优先满足（Should Have）、以及一票否决的红旗（Red Flags）。

必须满足（Required）

• 链接可用 — 返回 200（不是 404、301、5xx）；
• 聚焦 JavaScript — 不是主要讲 C#、Python、Java 等语言的内容；
• 技术上准确 — 没有事实错误或反模式（anti-patterns）；
• 可访问 — 免费或有实质性的免费预览。

优先满足（Preferred）

• 足够新 — 参见下一节的发布日期指引；
• 来源可信 — 来自可信来源清单或知名创作者；
• 视角独特 — 不是现有资源的重复；
• 深度匹配 — 与概念复杂度相称；
• 互动良好 — 评论区正面、播放量高（针对视频）。

红旗（出现即拒绝）

红旗	为何重要
通篇使用 var	对 ES6+ 主题而言已过时
教授反模式	对学习者有害
主要讲其他语言	主题错位
硬性付费墙（无预览）	不可访问
现代主题的内容早于 2015 年	很可能过期
评论区质量低	往往意味着内容有问题
事实性错误	会传播错误信息
标题党、内容单薄	浪费读者时间

六、发布日期指引

不同主题对资源时效性的要求不同。技能文档按主题类别给出了“最低可接受年份”：

主题类别	最低年份	依据
ES6+ 特性	2015+	ES6 于 2015 年 6 月发布
Promises	2015+	原生 Promise 属于 ES6
async/await	2017+	ES2017 特性
ES Modules	2018+	浏览器支持趋于稳定
可选链（?.）	2020+	ES2020 特性
空值合并（??）	2020+	ES2020 特性
顶层 await	2022+	ES2022 特性
基础概念（闭包、作用域、this）	不限	核心概念不随时间变化
DOM 操作	2018+	优先使用现代 API
Fetch API	2017+	支持面广泛

经验法则（Rule of thumb）：对时效敏感的主题，优先选择最近 3–5 年的内容；对基础概念，年代久远的经典内容往往同样优秀。

七、资源描述写作指南

描述是资源区块中最容易被忽视、却最影响读者体验的部分。技能文档对它有专门的规范。

两句话公式

Sentence 1: What makes this resource unique OR what it specifically covers
Sentence 2: Why reader should click (what they'll gain, who it's best for)

优秀示例（Good Examples）

<Card title="JavaScript Visualized: Promises & Async/Await — Lydia Hallie" icon="newspaper" href="https://…">
  Animated GIFs showing the call stack, microtask queue, and event loop in action.
  The visuals make Promise execution order finally click for visual learners.
</Card>

<Card title="What the heck is the event loop anyway? — Philip Roberts" icon="video" href="https://…">
  The legendary JSConf talk that made the event loop click for millions of developers.
  Philip Roberts' live visualizations are the gold standard — a must-watch.
</Card>

<Card title="You Don't Know JS: Scope & Closures — Kyle Simpson" icon="book" href="https://…">
  Kyle Simpson's deep dive into JavaScript's scope mechanics and closure behavior.
  Goes beyond the basics into edge cases and mental models for truly understanding scope.
</Card>

<Card title="JavaScript Promises in 10 Minutes — Web Dev Simplified" icon="video" href="https://…">
  Quick, clear explanation covering Promise creation, chaining, and error handling.
  Perfect starting point if you're new to async JavaScript.
</Card>

<Card title="How to Escape Async/Await Hell — Aditya Agarwal" icon="newspaper" href="https://…">
  The pizza-and-drinks ordering analogy makes parallel vs sequential execution crystal clear.
  Essential reading once you know async/await basics but want to write faster code.
</Card>

这五条示例分别展示了五种“独特价值点”的写法：可视化呈现（动画 GIF）、历史地位（传奇演讲）、深度与心智模型、时长与覆盖范围、以及独特类比（披萨与饮料的并行/顺序执行）。

反面示例（应避免）

<!-- TOO GENERIC：过于笼统 -->
<Card title="Promises Tutorial" icon="newspaper" href="...">
  A comprehensive guide to Promises in JavaScript.
</Card>

<!-- NO VALUE PROPOSITION：没有价值主张 -->
<Card title="Learn Closures" icon="video" href="...">
  This video explains closures in JavaScript.
</Card>

<!-- VAGUE, NO SPECIFICS：含糊、没有具体信息 -->
<Card title="JavaScript Guide" icon="newspaper" href="...">
  Everything you need to know about JavaScript.
</Card>

<!-- JUST RESTATING THE TITLE：只是在复述标题 -->
<Card title="Understanding the Event Loop" icon="video" href="...">
  A video about understanding the event loop.
</Card>

应避免的词语与短语

避免（Avoid）	原因	替代做法
“comprehensive guide to...”	含糊、用滥	具体说明覆盖了什么
“learn all about...”	泛泛	他们具体能学到什么？
“everything you need to know...”	夸张	要具体
“great tutorial on...”	主观填充词	它好在哪里？
“explains X”	过于基础	如何讲解的？独特之处是什么？
“in-depth look at...”	含糊	什么深度？哪个方面？

有效的表达

好的表达	示例
“step-by-step walkthrough”	“Step-by-step walkthrough of building a Promise from scratch”
“visual explanation”	“Visual explanation with animated diagrams”
“deep dive into”	“Deep dive into V8's optimization strategies”
“practical examples of”	“Practical examples of closures in React hooks”
“the go-to reference for”	“The go-to reference for array method signatures”
“finally makes X click”	“Finally makes prototype chains click”
“perfect for beginners”	“Perfect for beginners new to async code”
“covers X, Y, and Z”	“Covers creation, chaining, and error handling”

这套词汇规范与写作技能 write-concept/SKILL.md 中“避免 AI 腔”的准则一脉相承：描述与正文一样，都要用具体信息替代空洞形容词。

八、链接审计流程（Link Audit Process）

对存量资源做体检时，按四个步骤执行。

步骤 1：逐个检查链接

对概念页中的每个资源：点击链接确认能否加载，并记录 HTTP 状态：

状态	含义	处理动作
200	OK	保留，继续做内容检查
301/302	重定向	更新为最终 URL
404	未找到	删除或寻找替代品
403	禁止访问	人工核查，可能是地域封锁
5xx	服务器错误	稍后重试，可能是暂时性故障

步骤 2：内容验证

对每个可访问的链接：

1. 略读内容 — 是否仍然准确？
2. 检查日期 — 何时发布/更新的？
3. 确认 JavaScript 聚焦 — 是否主要讲 JS？
4. 查找红旗 — 反模式、错误、过时语法。

步骤 3：描述审查

对每个资源：

1. 读当前描述 — 是否具体？
2. 与实际内容对比 — 是否相符？
3. 检查套话 — 如 “comprehensive guide” 等；
4. 找出改进点 — 如何让它更具体？

步骤 4：缺口分析

审计完所有资源后：

1. 按区块计数 — 是否达到目标数量？
2. 检查多样性 — 初学者与进阶都有吗？视觉与文字都有吗？
3. 找出缺失类型 — 没有 MDN？没有视频？
4. 记录建议 — 应该补充什么？

九、资源区块的 MDX 模板与真实落地

策展产出最终以 Mintlify 的 Card 组件写入概念页。技能文档为每个区块提供了标准模板。

Reference 区块

## Reference

<CardGroup cols={2}>
  <Card title="[Main Topic] — MDN" icon="book" href="https://…">
    Official MDN documentation covering [specific aspects].
    The authoritative reference for [what it's best for].
  </Card>
  <Card title="[Related API/Concept] — MDN" icon="book" href="https://…">
    [What this reference covers].
    Essential reading for understanding [specific aspect].
  </Card>
</CardGroup>

Articles 区块

## Articles

<CardGroup cols={2}>
  <Card title="[Article Title]" icon="newspaper" href="...">
    [What makes it unique/what it covers].
    [Why read this one/who it's for].
  </Card>
  <Card title="[Article Title]" icon="newspaper" href="...">
    [Specific coverage].
    [Value proposition].
  </Card>
</CardGroup>

Videos 区块

## Videos

<CardGroup cols={2}>
  <Card title="[Video Title] — [Creator]" icon="video" href="https://…">
    [What it covers/unique approach].
    [Why watch/who it's for].
  </Card>
</CardGroup>

Books 区块（可选）与 Courses 区块（可选）

<Card title="[Book Title] — [Author]" icon="book" href="...">
  [What the book covers and its approach].
  [Who should read it and what they'll gain].
</Card>

<CardGroup cols={2}>
  <Card title="[Course Title] — [Platform]" icon="graduation-cap" href="...">
    [What the course covers].
    [Format and who it's best for].
  </Card>
</CardGroup>

这些模板在本仓库的概念页中已有真实落地。以 docs/concepts/promises.mdx 为例：Reference 区块给出 6 个 book 图标 MDN 链接（覆盖 Promise 对象、Promise.all()、Promise.allSettled()、ES2024 的 Promise.withResolvers() 等）；Articles 区块给出 6 篇 newspaper 图标文章；Videos 区块给出 4 个 video 图标视频。区块划分、图标取值、cols={2} 两栏布局与描述的两句话结构，均与技能文档的模板和数量目标（2–4 refs、4–6 articles、3–4 videos）逐条对应。

十、资源审计报告模板

审计完成后，用统一模板把发现记录下来。技能文档给出的完整模板如下（占位符需按实际情况填写）：

# Resource Audit Report: [Concept Name]

**File:** `/docs/concepts/[slug].mdx`
**Date:** YYYY-MM-DD
**Auditor:** [Name/Claude]

## Summary

| Metric | Count |
|--------|-------|
| Total Resources | XX |
| Working Links (200) | XX |
| Broken Links (404) | XX |
| Redirects (301/302) | XX |
| Outdated Content | XX |
| Generic Descriptions | XX |

## Resource Count vs Targets

| Section | Current | Target | Status |
|---------|---------|--------|--------|
| Reference (MDN) | X | 2-4 | ✅/⚠️/❌ |
| Articles | X | 4-6 | ✅/⚠️/❌ |
| Videos | X | 3-4 | ✅/⚠️/❌ |
| Courses | X | 0-3 | ✅/⚠️/❌ |

## Broken Links (Remove or Replace)

| Resource | Line | URL | Status | Action |
|----------|------|-----|--------|--------|
| [Title] | XX | [URL] | 404 | Remove |
| [Title] | XX | [URL] | 404 | Replace with [alternative] |

## Redirects (Update URLs)

| Resource | Line | Old URL | New URL |
|----------|------|---------|---------|
| [Title] | XX | [old] | [new] |

## Outdated Resources (Consider Replacing)

| Resource | Line | Issue | Recommendation |
|----------|------|-------|----------------|
| [Title] | XX | Published 2014, uses var throughout | Replace with [modern alternative] |
| [Title] | XX | Pre-ES6, no mention of let/const | Find updated version or replace |

## Description Improvements Needed

| Resource | Line | Current | Suggested |
|----------|------|---------|-----------|
| [Title] | XX | "A guide to closures" | "[Specific description with value prop]" |
| [Title] | XX | "Learn about promises" | "[What makes it unique]. [Why read it]." |

## Missing Resources (Recommendations)

| Type | Gap | Suggested Resource | URL |
|------|-----|-------------------|-----|
| Reference | No main MDN link | [Topic] — MDN | [URL] |
| Article | No beginner guide | [Title] — javascript.info | [URL] |
| Video | No visual explanation | [Title] — [Creator] | [URL] |
| Article | No advanced deep-dive | [Title] — 2ality | [URL] |

## Non-JavaScript Resources (Remove)

| Resource | Line | Issue |
|----------|------|-------|
| [Title] | XX | Primarily about C#, not JavaScript |

## Action Items

### High Priority (Do First)
1. **Remove broken link:** [Title] (line XX)
2. **Add missing MDN reference:** [Topic]
3. **Replace outdated resource:** [Title] with [alternative]

### Medium Priority
1. **Update redirect URL:** [Title] (line XX)
2. **Improve description:** [Title] (line XX)
3. **Add beginner-friendly article**

### Low Priority
1. **Add additional video resource**
2. **Consider adding course section**

## Verification Checklist

After making changes:

- [ ] All broken links removed or replaced
- [ ] All redirect URLs updated
- [ ] Outdated resources replaced
- [ ] Generic descriptions rewritten
- [ ] Missing resource types added
- [ ] Resource counts meet targets
- [ ] All new links verified working
- [ ] All descriptions are specific and valuable

报告的显著特点是按行号（Line）定位问题：失效链接、重定向、过期资源、待改描述都记录在“第几行”，配合优先级分级的行动项（High / Medium / Low），使审计结果可以直接转化为可执行的修改清单。

十一、快速参考：图标、字数与排序

图标对照表（Icon Reference）

内容类型	图标取值
MDN/官方文档	book
文章/博客	newspaper
视频	video
课程	graduation-cap
书籍	book
相关概念	视上下文选用

条目要素规范（Character Guidelines）

要素	规范
Card 标题	保持简洁，视频需带上创作者名
描述第一句	覆盖了什么 / 独特之处
描述第二句	为何阅读/观看 / 适合谁

资源排序规则（Resource Ordering）

在每个区块内部，资源按以下规则排列：

1. 最基础/最适合初学者的在前；
2. 官方参考排在社区内容之前；
3. 最推荐的放在显著位置；
4. 进阶/小众内容放在最后。

十二、质量检查清单与全流程集成

四维质量清单（Quality Checklist）

技能文档末尾给出四组检查项，策展完成后逐项核对：

链接验证：

• [ ] 所有链接返回 200（不是 404、301）
• [ ] 没有重定向链
• [ ] 没有未注明的硬性付费墙
• [ ] 尽量使用 HTTPS

内容质量：

• [ ] 所有资源聚焦 JavaScript
• [ ] 没有教授反模式的资源
• [ ] 发布日期与主题相称
• [ ] 初学者与进阶内容兼备
• [ ] 视觉与文字资源兼备

描述质量：

• [ ] 所有描述都是具体的（非泛泛）
• [ ] 描述解释了独特价值
• [ ] 没有 “comprehensive guide to...” 之类的套话
• [ ] 每条描述为两句话
• [ ] 描述与实际内容相符

完整性：

• [ ] 2–4 个 MDN/官方参考
• [ ] 4–6 篇优质文章
• [ ] 3–4 个优质视频
• [ ] 资源按逻辑排序
• [ ] 教学风格多样

在概念工作流中的位置

从 .opencode/skill/concept-workflow/SKILL.md 可以看到，资源策展的交付物（2–4 个带描述的 MDN/参考链接、4–6 篇带描述的文章、3–4 个带描述的视频、可选的课程/书籍）在进入写作阶段前必须先通过四项质量门：

• [ ] 所有链接验证可用（200 响应）
• [ ] 所有资源聚焦 JavaScript
• [ ] 描述具体而非泛泛
• [ ] 初学者与进阶内容兼有

工作流文档同时给出了依赖关系：Phase 1（Resources）必须先于 Phase 2（Writing），因为“资源决定了要写什么”；整体五阶段（资源 → 写作 → 测试 → 事实核查 → SEO）预计总耗时 2–5 小时，其中资源策展约 15–30 分钟，是投入产出比最高的一环。此外，write-concept/SKILL.md 中的“Resource Curation Guidelines”一节复述了同样的五条质量标准（聚焦 JS、链接可达、来源可信、内容新、无错误）与两句话描述公式，从写作侧再次约束了资源区块的最终形态。

十三、核心原则

技能文档以一段话收尾，点出了整套方法论的价值观：

Remember: Resources should enhance learning, not pad the page. Every link should offer genuine value. Quality over quantity — a few excellent resources beat many mediocre ones.

资源应该增强学习，而不是给页面凑数；每个链接都应有真实价值。宁缺毋滥——几个优秀资源胜过一堆平庸资源。这条原则贯穿全文：从审计时敢于删除失效与过期条目，到寻找时限定可信来源与发布日期，到写描述时要求两句话讲清独特价值，再到排序时把最推荐的内容放在显著位置，资源策展的最终目标只有一个——让读者在 docs/concepts/ 的任意一篇概念页末尾，都能拿到一份可信、具体、值得点击的学习资源清单。