nodejs-core

nodejs-core 技能總覽

nodejs-core 是用來做什麼的

nodejs-core 技能適合處理 Node.js 內部層級的除錯與開發：原生 addon、C++ binding、V8 行為、libuv 排程、建置失敗，以及一般 JavaScript 提示通常看不到的效能問題。當你需要 nodejs-core 來處理跨越 JS/C++ 邊界的 Backend Development，或是依賴 Node 執行階段機制的問題時，它特別有用。

最適合的讀者與任務

如果你正在做以下事情，就適合使用 nodejs-core 技能：

• 修正 binding.gyp 或 node-gyp 建置錯誤
• 追查 crash、segfault、記憶體洩漏，或不穩定的原生測試
• 撰寫或審查 N-API、node-addon-api、或基於 NAN 的程式碼
• 調校 event loop、worker thread，或 thread pool 的行為
• 診斷 V8 deopt、GC 壓力，或 hidden class regression

這個技能有什麼不同

這個技能是圍繞可直接採取行動的 Node core 規則來組織，不是泛用總覽。它的價值主要在 rules/ 目錄下的支援檔案：它們把建置流程、V8、libuv、原生記憶體、CLI 選項，以及除錯路徑拆開，讓 agent 能快速選到正確的子系統。

如何使用 nodejs-core 技能

正確安裝並限定使用範圍

先用 repository 的 skill command 安裝 nodejs-core，然後只在你的任務需要執行階段內部機制或原生建置推理時使用它。如果你的問題只是標準 Express、API 設計，或純 TypeScript 邏輯，這個技能大多太底層了。

從正確的檔案開始

在安裝 nodejs-core 並第一次閱讀時，先開這些檔案：

• SKILL.md：看範圍與入口點
• rules/build-and-test-workflow.md：看必要的 edit-build-test 迴圈
• rules/build-system.md：看編譯與 binding.gyp 的上下文
• 與你問題相符的 subsystem 規則，例如 rules/napi.md、rules/libuv-event-loop.md、rules/v8-jit-compilation.md，或 rules/debugging-native.md

把模糊任務改寫成可用提示

像「幫我看 Node addon crash」這種請求太寬。更好的 nodejs-core 使用提示應包含：

• 平台：Linux/macOS/Windows
• Node 版本與建置型態
• 明確失敗模式：compile error、abort、hang、deopt、leak、輸出錯誤
• 子系統線索：N-API、libuv、V8、child process、streams，或 memory
• 最近變更了什麼
• 可重現問題的 command 或 test

範例如下：
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.

能帶來更好結果的工作流程

先從對應的 rule 檔開始，再把症狀對應到最小的子系統。若是建置問題，先讀 build workflow；若是 runtime bug，先讀子系統規則，並把你的重現結果和 Node 預期行為對照。若任務涉及修改過的 src/ 或 lib/，測試前先重新建置，避免一直追逐舊輸出。

nodejs-core 技能 FAQ

nodejs-core 只適合 Node core 貢獻者嗎？

不是。它也很適合 addon 作者、平台工程師，以及正在排查發生在 JavaScript 層以下的 production 問題的 backend 團隊。你不需要正在為 Node core 貢獻，才能使用 nodejs-core skill。

它和一般提示有什麼不同？

一般提示可能只會猜 JavaScript 層的修法。當答案取決於 build flags、binary embedding、C++ bindings、V8 最佳化行為，或 libuv 內部機制時，nodejs-core 會更合適。它會把工作流程導向正確的子系統規則，減少猜測。

這個技能適合初學者嗎？

可以，只要問題夠具體。對於模糊的「為什麼 Node 很慢？」這類問題，它就沒那麼友善。初學者如果提供重現 command、stack trace，以及相關子系統，通常效果會好很多。這會讓 nodejs-core 的使用更精準。

什麼情況下不該使用？

框架 bug、應用架構，或例行 API 使用，就不用它。另外，如果你無法提供重現方式，至少也要能說清楚失敗類型；這個技能最強的時候，是問題已經很像 runtime、build，或原生整合問題。

如何改進 nodejs-core 技能

提供正確的證據

最有用的輸入都要具體：stack trace、建置 log、node -p process.versions、compile flags，以及最小可重現範例。若是 nodejs-core 用於 Backend Development，也請一起說明服務是 CPU-bound、memory-bound，還是卡在 I/O，因為這會影響 V8、libuv，或原生記憶體規則哪個最重要。

盡早指向子系統

不要讓模型在腦中掃完整個 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

留意常見失敗模式

最常見的錯誤，是把建置問題當成 runtime bug，或以為用 JS 修法就能解掉 C++/binding 問題。另一個常見錯誤，是忘了在修改 src/ 或 lib/ 後重新建置。如果第一個回答太廣，就用一個更精準的重現、一段更小的程式碼範例，並明確要求「聚焦 build 還是 runtime」來迭代。

把第一個回答當成縮小範圍的起點

把第一次輸出視為初步分流：請它指出最可能的子系統、下一個要跑的診斷 command，或下一個應該查看的確切檔案。好的 nodejs-core 結果通常會在一輪精煉後明顯變好，尤其是當你加入失敗的 command、平台，以及一個具體症狀，而不是籠統描述時。