From c30f4c152e40da51cf13be34e8fb9ea60407d2a0 Mon Sep 17 00:00:00 2001 From: wehub-skill-sync Date: Mon, 13 Jul 2026 21:36:30 +0800 Subject: [PATCH] chore: import zh skill fact-check --- README.wehub.md | 9 + SKILL.md | 649 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 658 insertions(+) create mode 100644 README.wehub.md create mode 100644 SKILL.md diff --git a/README.wehub.md b/README.wehub.md new file mode 100644 index 0000000..b936946 --- /dev/null +++ b/README.wehub.md @@ -0,0 +1,9 @@ +# WeHub 来源说明 + +- Skill 名称:`fact-check` +- 中文类目:技术学习资源策展与校验 +- 上游仓库:`leonardomso__33-js-concepts` +- 上游路径:`.claude/skills/fact-check/SKILL.md` +- 上游链接:https://github.com/leonardomso/33-js-concepts/blob/HEAD/.claude/skills/fact-check/SKILL.md +- 本仓库为 WeHub 中文 Skill 汉化包,基于 skill 市场筛选 Top200 清单整理 +- 原作者、版权和许可证信息以上游仓库为准 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..22bd225 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,649 @@ +--- +name: fact-check +description: 验证 JavaScript 概念页面的技术准确性,通过检查代码示例、MDN/ECMAScript 合规性以及外部资源来防止错误信息传播 +--- + +# 技能:JavaScript 事实核查器 + +使用此技能来验证 33 个 JavaScript 概念项目中的概念文档页面的技术准确性。这确保我们不会传播关于 JavaScript 的错误信息。 + +## 何时使用 + +- 发布新的概念页面之前 +- 对现有内容进行重大编辑之后 +- 审核社区贡献时 +- 使用新 JavaScript 特性更新页面时 +- 对现有内容进行定期准确性审计 + +## 我们要防范什么 + +- 错误的 JavaScript 行为声明 +- 过时的信息(将 ES6 之前的模式当作当前标准呈现) +- 无法产生所述输出的代码示例 +- 已损坏或具有误导性的外部资源链接 +- 被当作事实陈述的常见误解 +- 将特定于浏览器的行为描述为通用行为 +- 不准确的 API 描述 + +--- + +## 事实核查方法 + +按顺序执行以下五个阶段以完成完整的事实核查。 + +### 阶段 1:代码示例验证 + +概念页面中的每个代码示例都必须验证其准确性。 + +#### 分步流程 + +1. **识别文档中的所有代码块** +2. **针对每个代码块:** + - 阅读代码及任何输出注释(例如 `// "string"`) + - 在脑中执行代码或在 JavaScript 环境中测试 + - 验证输出是否与注释中所述一致 + - 检查变量名和逻辑是否正确 + +3. **针对"错误"示例(标记为 ❌):** + - 验证它们确实产生了错误/意外的行为 + - 确认关于错误原因的解释是准确的 + +4. **针对"正确"示例(标记为 ✓):** + - 验证它们按所述方式工作 + - 确认它们遵循当前最佳实践 + +5. **运行项目测试:** + ```bash + # Run all tests + npm test + + # Run tests for a specific concept + npm test -- tests/fundamentals/call-stack/ + npm test -- tests/fundamentals/primitive-types/ + ``` + +6. **检查测试覆盖率:** + - 查看 `/tests/{category}/{concept-name}/` + - 验证主要代码示例是否存在对应测试 + - 标记没有测试覆盖的示例 + +#### 代码验证清单 + +| 检查项 | 如何验证 | +|-------|---------------| +| `console.log` 输出与注释匹配 | 运行代码或在脑中跟踪 | +| 变量名正确且使用得当 | 通读逻辑 | +| 函数返回预期值 | 跟踪执行过程 | +| 异步代码按所述顺序解析 | 理解事件循环 | +| 错误示例确实抛出错误 | 在 try/catch 中测试 | +| 数组/对象方法返回正确类型 | 查阅 MDN | +| `typeof` 结果准确 | 测试常见情况 | +| 必要时注明严格模式行为 | 检查示例是否依赖严格模式 | + +#### 需要留意的常见输出错误 + +```javascript +// Watch for these common mistakes: + +// 1. typeof null +typeof null // "object" (not "null"!) + +// 2. Array methods that return new arrays vs mutate +const arr = [1, 2, 3] +arr.push(4) // Returns 4 (length), not the array! +arr.map(x => x*2) // Returns NEW array, doesn't mutate + +// 3. Promise resolution order +Promise.resolve().then(() => console.log('micro')) +setTimeout(() => console.log('macro'), 0) +console.log('sync') +// Output: sync, micro, macro (NOT sync, macro, micro) + +// 4. Comparison results +[] == false // true +[] === false // false +![] // false (empty array is truthy!) + +// 5. this binding +const obj = { + name: 'Alice', + greet: () => console.log(this.name) // undefined! Arrow has no this +} +``` + +--- + +### 阶段 2:MDN 文档验证 + +所有关于 JavaScript API、方法和行为的声明应与 MDN 文档保持一致。 + +#### 分步流程 + +1. **检查所有 MDN 链接:** + - 点击文档中的每个 MDN 链接 + - 验证链接返回 200(非 404) + - 确认链接页面与所引用内容匹配 + +2. **验证 API 描述:** + - 将方法签名与 MDN 进行对比 + - 检查参数名称和类型 + - 验证返回类型 + - 确认边界情况行为 + +3. **检查已弃用的 API:** + - 在 MDN 上查找弃用警告 + - 标记任何被当作现行标准教授的已弃用方法 + +4. **验证浏览器兼容性声明:** + - 与 MDN 兼容性表交叉对照 + - 查阅 Can I Use 获取更广泛的兼容性数据 + +#### MDN 链接模式 + +| 内容类型 | MDN URL 模式 | +|--------------|-----------------| +| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` | +| 全局对象 | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` | +| 语句 | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/{Statement}` | +| 运算符 | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/{Operator}` | +| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` | + +#### 需对照 MDN 验证的内容 + +| 声明类型 | 检查内容 | +|------------|---------------| +| 方法签名 | 参数、可选参数、返回类型 | +| 返回值 | 确切类型和可能的值 | +| 副作用 | 是否发生修改?影响什么? | +| 异常 | 可能抛出什么错误? | +| 浏览器支持 | 兼容性表 | +| 弃用状态 | 是否有弃用警告? | + +--- + +### 阶段 3:ECMAScript 规范合规性 + +对于微妙的 JavaScript 行为,需对照 ECMAScript 规范进行验证。 + +#### 何时检查规范 + +- 边界情况和异常行为 +- 关于"JavaScript 内部工作原理"的声明 +- 类型强制转换规则 +- 运算符优先级 +- 执行顺序保证 +- 使用"总是"、"从不"、"保证"等词语的声明 + +#### 如何浏览规范 + +ECMAScript 规范位于:https://tc39.es/ecma262/ + +| 概念 | 规范章节 | +|---------|--------------| +| 类型强制转换 | Abstract Operations (7.1) | +| 相等性 | Abstract Equality Comparison (7.2.14), Strict Equality (7.2.15) | +| typeof | The typeof Operator (13.5.3) | +| 对象 | Ordinary and Exotic Objects' Behaviours (10) | +| 函数 | ECMAScript Function Objects (10.2) | +| this 绑定 | ResolveThisBinding (9.4.4) | +| Promise | Promise Objects (27.2) | +| 迭代 | Iteration (27.1) | + +#### 规范验证示例 + +```javascript +// Claim: "typeof null returns 'object' due to a bug" +// Spec says: typeof null → "object" (Table 41) +// Historical context: This is a known quirk from JS 1.0 +// Verdict: ✓ Correct, though calling it a "bug" is slightly informal + +// Claim: "Promises always resolve asynchronously" +// Spec says: Promise reaction jobs are enqueued (27.2.1.3.2) +// Verdict: ✓ Correct - even resolved promises schedule microtasks + +// Claim: "=== is faster than ==" +// Spec says: Nothing about performance +// Verdict: ⚠️ Needs nuance - this is implementation-dependent +``` + +--- + +### 阶段 4:外部资源验证 + +所有外部链接(文章、视频、课程)都必须经过验证。 + +#### 分步流程 + +1. **检查链接可访问性:** + - 点击每个外部链接 + - 验证其能正常加载(非 404、非付费墙) + - 注意是否重定向到不同 URL + +2. **验证内容准确性:** + - 快速浏览资源,查找明显错误 + - 确认其聚焦于 JavaScript(而非 C#、Python、Java) + - 验证其未教授反模式 + +3. **检查发布日期:** + - 对于时效性强的主题(异步、模块等),优先选择近期内容 + - 针对 ES6+ 主题,标记 2015 年之前的资源 + +4. **验证描述准确性:** + - 我们的描述是否与实际资源内容相符? + - 描述是否具体(而非泛泛而谈)? + +#### 外部资源清单 + +| 检查项 | 通过标准 | +|-------|---------------| +| 链接可用 | 返回 200,内容可加载 | +| 非付费墙 | 可免费访问(或已明确标注) | +| 聚焦 JavaScript | 并非主要关于其他语言 | +| 不过时 | ES6+ 主题为 2015 年之后 | +| 描述准确 | 我们的描述与实际内容相符 | +| 无反模式 | 不教授不良实践 | +| 来源可靠 | 来自知名/可信的创作者 | + +#### 外部资源的警示信号 + +- 在 ES6+ 主题中到处使用 `var` +- 在涉及 Promise/async 的内容中使用回调 +- 将 jQuery 作为现代 DOM 操作方式教授 +- 包含关于 JavaScript 的事实性错误 +- 视频超过 2 小时且无时间戳链接 +- 内容主要关于其他语言 +- 使用已弃用的 API 但未注明弃用 + +--- + +### 阶段 5:技术声明审计 + +审查所有关于 JavaScript 行为的散文式声明。 + +#### 需要验证的声明类型 + +| 声明类型 | 如何验证 | +|------------|---------------| +| 性能声明 | 需要基准测试或附加说明 | +| 浏览器行为 | 指定浏览器,查阅 MDN | +| 历史声明 | 验证日期/版本 | +| "总是"或"从不"的表述 | 检查是否存在例外 | +| 对比(X 与 Y) | 准确验证双方 | + +#### 技术声明中的警示信号 + +- "总是"或"从不"未注明例外情况 +- 无基准测试支撑的性能声明 +- 未指定浏览器的浏览器行为声明 +- 过度简化差异的对比 +- 无日期的历史声明 +- 关于"JavaScript 工作原理"的声明但未引用规范 + +#### 需要验证的声明示例 + +```markdown +❌ "async/await is always better than Promises" +→ Verify: Not always - Promise.all() is better for parallel operations + +❌ "JavaScript is an interpreted language" +→ Verify: Modern JS engines use JIT compilation + +❌ "Objects are passed by reference" +→ Verify: Technically "passed by sharing" - the reference is passed by value + +❌ "=== is faster than ==" +→ Verify: Implementation-dependent, not guaranteed by spec + +✓ "JavaScript is single-threaded" +→ Verify: Correct for the main thread (Web Workers are separate) + +✓ "Promises always resolve asynchronously" +→ Verify: Correct per ECMAScript spec +``` + +--- + +## 常见的 JavaScript 误解 + +警惕以下被当作事实陈述的误解。 + +### 类型系统误解 + +| 误解 | 真相 | 如何验证 | +|---------------|---------|---------------| +| `typeof null === "object"` 是故意的 | 这是 JS 1.0 中因兼容性而无法修复的 bug | 历史背景、TC39 讨论 | +| JavaScript 没有类型 | JS 是动态类型语言,并非无类型 | ECMAScript 规范定义了类型 | +| `==` 总是错的 | `== null` 可同时检查 null 和 undefined,有合理用途 | 许多风格指南允许此模式 | +| `NaN === NaN` 为 false 是"搞错了" | 根据 IEEE 754 浮点规范,这是故意的 | IEEE 754 标准 | + +### 函数误解 + +| 误解 | 真相 | 如何验证 | +|---------------|---------|---------------| +| 箭头函数只是更短的语法 | 它们没有 `this`、`arguments`、`super` 或 `new.target` | MDN、ECMAScript 规范 | +| `var` 会被提升到函数作用域并带上其值 | 只有声明被提升,初始化不会 | 代码测试、MDN | +| 闭包是一种特殊的可选功能 | JS 中所有函数都是闭包 | ECMAScript 规范 | +| IIFE 已过时 | 对于一次性初始化仍有用途 | 现代代码库仍在使用它们 | + +### 异步误解 + +| 误解 | 真相 | 如何验证 | +|---------------|---------|---------------| +| Promise 是并行执行的 | JS 是单线程的;Promise 是异步的,不是并行的 | 事件循环解释 | +| `async/await` 与 Promise 不同 | 它是对 Promise 的语法糖 | MDN,可 await 任何 thenable | +| `setTimeout(fn, 0)` 会立即执行 | 在当前执行 + 微任务之后执行 | 事件循环、代码测试 | +| `await` 会暂停整个程序 | 只暂停 async 函数,不会暂停事件循环 | 代码测试 | + +### 对象误解 + +| 误解 | 真相 | 如何验证 | +|---------------|---------|---------------| +| 对象是"按引用传递"的 | 引用是按值传递的("按共享传递") | 重新赋值测试 | +| `const` 使对象不可变 | `const` 阻止重新赋值,而非阻止修改 | 代码测试 | +| JavaScript 中一切都是对象 | 基本类型不是对象(尽管它们有包装器) | `typeof` 测试、MDN | +| `Object.freeze()` 创建深度不可变性 | 它是浅层的——嵌套对象仍可被修改 | 代码测试 | + +### 性能误解 + +| 误解 | 真相 | 如何验证 | +|---------------|---------|---------------| +| `===` 总是比 `==` 快 | 取决于实现,规范不做保证 | 基准测试结果各异 | +| `for` 循环比 `forEach` 快 | 现代引擎对两者都优化;取决于使用场景 | 基准测试 | +| 箭头函数更快 | 无性能差异,只是行为不同 | 基准测试 | +| 避免 DOM 操作总是更快 | 有时批量修改比单独修改更慢 | 取决于浏览器和使用场景 | + +--- + +## 测试集成 + +运行项目的测试套件是事实核查的关键部分。 + +### 测试命令 + +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run tests with coverage +npm run test:coverage + +# Run tests for specific concept +npm test -- tests/fundamentals/call-stack/ +npm test -- tests/fundamentals/primitive-types/ +npm test -- tests/fundamentals/value-reference-types/ +npm test -- tests/fundamentals/type-coercion/ +npm test -- tests/fundamentals/equality-operators/ +npm test -- tests/fundamentals/scope-and-closures/ +``` + +### 测试目录结构 + +``` +tests/ +├── fundamentals/ # Concepts 1-6 +│ ├── call-stack/ +│ ├── primitive-types/ +│ ├── value-reference-types/ +│ ├── type-coercion/ +│ ├── equality-operators/ +│ └── scope-and-closures/ +├── functions-execution/ # Concepts 7-8 +│ ├── event-loop/ +│ └── iife-modules/ +└── web-platform/ # Concepts 9-10 + ├── dom/ + └── http-fetch/ +``` + +### 当测试缺失时 + +如果某个概念没有测试: +1. 在报告中标记为"需要测试覆盖" +2. 手动验证代码示例是否正确 +3. 考虑将添加测试作为后续任务 + +--- + +## 验证资源 + +### 主要来源 + +| 资源 | URL | 用途 | +|----------|-----|---------| +| MDN Web Docs | https://developer.mozilla.org | API 文档、指南、兼容性 | +| ECMAScript 规范 | https://tc39.es/ecma262 | 权威行为定义 | +| TC39 提案 | https://github.com/tc39/proposals | 新特性、各阶段 | +| Can I Use | https://caniuse.com | 浏览器兼容性 | +| Node.js 文档 | https://nodejs.org/docs | Node 特定 API | +| V8 博客 | https://v8.dev/blog | 引擎内部机制 | + +### 项目资源 + +| 资源 | 路径 | 用途 | +|----------|------|---------| +| 测试套件 | `/tests/` | 验证代码示例 | +| 概念页面 | `/docs/concepts/` | 当前内容 | +| 运行测试 | `npm test` | 执行所有测试 | + +--- + +## 事实核查报告模板 + +使用此模板记录你的发现。 + +```markdown +# Fact Check Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Reviewer:** [Name/Claude] +**Overall Status:** ✅ Verified | ⚠️ Minor Issues | ❌ Major Issues + +--- + +## Executive Summary + +[2-3 sentence summary of findings. State whether the page is accurate overall and highlight any critical issues.] + +**Tests Run:** Yes/No +**Test Results:** X passing, Y failing +**External Links Checked:** X/Y valid + +--- + +## Phase 1: Code Example Verification + +| # | Description | Line | Status | Notes | +|---|-------------|------|--------|-------| +| 1 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | +| 2 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | +| 3 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | + +### Code Issues Found + +#### Issue 1: [Title] + +**Location:** Line XX +**Severity:** Critical/Major/Minor +**Current Code:** +```javascript +// The problematic code +``` +**Problem:** [Explanation of what's wrong] +**Correct Code:** +```javascript +// The corrected code +``` + +--- + +## Phase 2: MDN/Specification Verification + +| Claim | Location | Source | Status | Notes | +|-------|----------|--------|--------|-------| +| [Claim made] | Line XX | MDN/Spec | ✅/⚠️/❌ | [Notes] | + +### MDN Link Status + +| Link Text | URL | Status | +|-----------|-----|--------| +| [Text] | [URL] | ✅ 200 / ❌ 404 | + +### Specification Discrepancies + +[If any claims don't match the ECMAScript spec, detail them here] + +--- + +## Phase 3: External Resource Verification + +| Resource | Type | Link | Content | Notes | +|----------|------|------|---------|-------| +| [Title] | Article/Video | ✅/❌ | ✅/⚠️/❌ | [Notes] | + +### Broken Links + +1. **Line XX:** [URL] - 404 Not Found +2. **Line YY:** [URL] - Domain expired + +### Content Concerns + +1. **[Resource name]:** [Concern - e.g., outdated, wrong language, anti-patterns] + +### Description Accuracy + +| Resource | Description Accurate? | Notes | +|----------|----------------------|-------| +| [Title] | ✅/❌ | [Notes] | + +--- + +## Phase 4: Technical Claims Audit + +| Claim | Location | Verdict | Notes | +|-------|----------|---------|-------| +| "[Claim]" | Line XX | ✅/⚠️/❌ | [Notes] | + +### Claims Needing Revision + +1. **Line XX:** "[Current claim]" + - **Issue:** [What's wrong] + - **Suggested:** "[Revised claim]" + +--- + +## Phase 5: Test Results + +**Test File:** `/tests/[category]/[concept]/[concept].test.js` +**Tests Run:** XX +**Passing:** XX +**Failing:** XX + +### Failing Tests + +| Test Name | Expected | Actual | Related Doc Line | +|-----------|----------|--------|------------------| +| [Test] | [Expected] | [Actual] | Line XX | + +### Coverage Gaps + +Examples in documentation without corresponding tests: +- [ ] Line XX: [Description of untested example] +- [ ] Line YY: [Description of untested example] + +--- + +## Issues Summary + +### Critical (Must Fix Before Publishing) + +1. **[Issue title]** + - Location: Line XX + - Problem: [Description] + - Fix: [How to fix] + +### Major (Should Fix) + +1. **[Issue title]** + - Location: Line XX + - Problem: [Description] + - Fix: [How to fix] + +### Minor (Nice to Have) + +1. **[Issue title]** + - Location: Line XX + - Suggestion: [Improvement] + +--- + +## Recommendations + +1. **[Priority 1]:** [Specific actionable recommendation] +2. **[Priority 2]:** [Specific actionable recommendation] +3. **[Priority 3]:** [Specific actionable recommendation] + +--- + +## Verification Checklist + +- [ ] All code examples verified for correct output +- [ ] All MDN links checked and valid +- [ ] API descriptions match MDN documentation +- [ ] ECMAScript compliance verified (if applicable) +- [ ] All external resource links accessible +- [ ] Resource descriptions accurately represent content +- [ ] No common JavaScript misconceptions found +- [ ] Technical claims are accurate and nuanced +- [ ] Project tests run and reviewed +- [ ] Report complete and ready for handoff + +--- + +## Sign-off + +**Verified by:** [Name/Claude] +**Date:** YYYY-MM-DD +**Recommendation:** ✅ Ready to publish | ⚠️ Fix issues first | ❌ Major revision needed +``` + +--- + +## 快速参考:验证命令 + +```bash +# Run all tests +npm test + +# Run specific concept tests +npm test -- tests/fundamentals/call-stack/ + +# Check for broken links (if you have a link checker) +# Install: npm install -g broken-link-checker +# Run: blc https://developer.mozilla.org/... -ro + +# Quick JavaScript REPL for testing +node +> typeof null +'object' +> [1,2,3].map(x => x * 2) +[ 2, 4, 6 ] +``` + +--- + +## 总结 + +对概念页面进行事实核查时: + +1. **先运行测试** — `npm test` 自动捕获代码错误 +2. **验证每个代码示例** — 输出注释必须与实际结果一致 +3. **检查所有 MDN 链接** — 失效链接和错误描述会损害可信度 +4. **验证外部资源** — 必须可访问、准确且聚焦于 JavaScript +5. **审计技术声明** — 留意误解和未经证实的表述 +6. **记录一切** — 使用报告模板进行一致、彻底的审核 + +**请记住:** 我们的读者信任我们来教授他们正确的 JavaScript。一条错误信息就可能造成需要数年才能纠正的困惑。请认真对待事实核查。