nodejs-core

nodejs-core 技能概览

nodejs-core 适合做什么

nodejs-core skill 适用于在 Node.js 内部层做调试和构建：原生 addon、C++ binding、V8 行为、libuv 调度、构建失败，以及普通 JavaScript 提示词往往看不到的性能问题。它最适合用于需要 nodejs-core 的 Backend Development 场景，尤其是那些跨越 JS/C++ 边界，或依赖 Node 运行时机制的任务。

适合哪些读者和任务

如果你遇到的是以下情况，就适合用 nodejs-core skill：

• 修复 binding.gyp 或 node-gyp 构建错误
• 排查崩溃、segfault、内存泄漏，或不稳定的原生测试
• 编写或审查基于 N-API、node-addon-api 或 NAN 的代码
• 调优事件循环、worker thread 或线程池行为
• 诊断 V8 deopt、GC 压力，或 hidden class 回归

它有什么不同

这个 skill 不是泛泛介绍，而是围绕可执行的 Node core 规则来组织的。真正的价值在于配套的 rules/ 文件：它们把构建流程、V8、libuv、原生内存、CLI 选项和调试路径拆开，方便 agent 快速选对子系统。

如何使用 nodejs-core skill

正确安装并限定使用范围

先用 repository skill 命令安装 nodejs-core，然后只在任务确实需要运行时内部机制或原生构建推理时使用它。如果你的问题只是标准 Express、API 设计，或普通 TypeScript 逻辑，这个 skill 大概率层级太低，不合适。

从正确的文件开始读

在进行 nodejs-core 安装后的首次阅读时，先打开：

• SKILL.md，了解适用范围和入口
• rules/build-and-test-workflow.md，查看必须遵循的 edit-build-test 循环
• rules/build-system.md，了解编译和 binding.gyp 背景
• 与你问题匹配的子系统规则，例如 rules/napi.md、rules/libuv-event-loop.md、rules/v8-jit-compilation.md 或 rules/debugging-native.md

把粗略任务改写成可用提示词

像“帮我看看一个 Node addon 崩溃”这样的需求太宽泛。更强的 nodejs-core 使用提示应该包含：

• 平台：Linux/macOS/Windows
• Node 版本和构建类型
• 精确故障模式：编译错误、abort、卡死、deopt、泄漏、输出错误
• 子系统提示：N-API、libuv、V8、child process、streams 或 memory
• 最近改动了什么
• 能复现问题的命令或测试

示例形式：
Use nodejs-core to diagnose a native addon crash on Node 22. The addon uses N-API, fails only in release builds, and crashes after a GC cycle. Focus on likely root causes, what to inspect in rules/napi.md and rules/memory-debugging.md, and the fastest repro steps.

能产出更好结果的工作流

先从匹配的规则文件入手，再把症状映射到最小的子系统。构建问题先读 build workflow；运行时 bug 先读对应子系统规则，并将你的复现过程与预期 Node 行为对照。如果任务涉及改过 src/ 或 lib/，测试前务必重新构建，避免一直追着旧产物排查。

nodejs-core skill 常见问题

nodejs-core 只适合 Node core 贡献者吗？

不是。它同样适合 addon 作者、平台工程师，以及在 JavaScript 层以下排查生产问题的后端团队。你不需要参与 Node core 贡献，也可以使用 nodejs-core skill。

它和普通提示词有什么区别？

普通提示词可能会从 JavaScript 层面猜测修复方案。nodejs-core 更适合问题答案取决于 build flags、binary embedding、C++ binding、V8 优化行为，或 libuv 内部机制的场景。它会把流程引导到正确的子系统规则上，从而减少猜测。

它适合初学者吗？

适合，但前提是问题足够具体。对于含糊的“为什么 Node 很慢？”这类请求，它就不那么友好。初学者如果能提供复现命令、stack trace 和相关子系统，通常效果会好得多。这样使用 nodejs-core 会精确很多。

什么时候不该用它？

框架 bug、应用架构问题，或常规 API 用法，不要用它。另外，如果你连复现步骤都给不出来，至少也要给出明确的故障类别；这个 skill 最强的场景，是问题已经明显像运行时、构建或原生集成故障。

如何改进 nodejs-core skill

给 skill 提供正确的证据

最有用的输入一定要足够具体：stack traces、构建日志、node -p process.versions、编译标志，以及最小复现。对于用于 Backend Development 的 nodejs-core，还要说明服务是 CPU-bound、memory-bound，还是被 I/O 卡住，因为这会影响 V8、libuv 或 native memory 规则哪个最重要。

尽早指出子系统

不要让模型在脑中“搜索整个 repo”。直接告诉它问题最接近下面哪一类：

• rules/napi.md 或 rules/node-addon-api.md
• rules/v8-garbage-collection.md 或 rules/profiling-v8.md
• rules/libuv-event-loop.md 或 rules/libuv-thread-pool.md
• rules/debugging-native.md 或 rules/native-memory.md

注意常见失误模式

最常见的遗漏，是把构建问题当成运行时 bug，或者默认一个 JS 修复就能解决 C++/binding 问题。另一个常见问题，是在修改了 src/ 或 lib/ 之后忘记重新构建。如果第一次回答过于宽泛，就用一个更明确的复现、一个更小的代码样例，以及一句明确的“聚焦 build 还是 runtime”指令继续迭代。

把第一轮答案当作收敛步骤

把第一次输出当成分诊：让它给出最可能的子系统、下一条诊断命令，或者下一步要检查的准确文件。好的 nodejs-core 结果通常在一次收敛后会明显变好，尤其是你补上失败命令、平台信息和一个具体症状，而不是只给笼统描述。