跳到主内容
智客 ZICQ

技能库 智客分类:写作与研究 gc-safe-coding

Gc Safe Coding

在Hermes VM运行时间中编写和审查GC-safe C++代码的规则. 在写入,修改,或审查使用内部Hermes VM API的C++运行时使用VM代码(而不是使用JSI的代码). 这包括与GC管理的类型(HermesValue, Handle, PinnedValue, JS Object, String Primitive等),本地人,GCScope,PseudoHandle,CallResult,或任何有_RJS后缀的功能合作. 通常在lib/VM/中,包括/hermes/VM/,API/hermes/,或API/napi/.

44 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

Hermes VM运行时间中编写和审查GC-saf C++代码的规则

何时用

编写,修改,或审查使用内部的Hermes VM API(而不是使用JSI的代码)的 C++ 运行时 VM 代码. 这包括与GC管理的类型(HermesValue、Handle、PinnedValue、JSObject、StringPrimitive等)、当地人、GCScope、PseudoHandle、CallResult或a)合作

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:GC safepoints、Rooting local values: use Locals + PinnedValue (required for new code)、Assignment patterns、Passing to functions、Error handling with CallResult、When Handle usage is fine (do not flag)。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Rules for writing and reviewing GC-safe C++ code in the Hermes VM runtime. Use when writing, modifying, or reviewing C++ runtime VM code that uses internal Hermes VM APIs (as opposed to code using JSI). This includes working with GC-managed types (HermesValue, Handle, PinnedValue, JSObject, StringPrimitive, etc.), Locals, GCScope, PseudoHandle, CallResult, or any function with _RJS suffix. Typically in lib/VM/, include/hermes/VM/, API/hermes/, or API/napi/.

GC safepointsRooting local values: use Locals + PinnedValue (required for new code)Assignment patternsPassing to functionsError handling with CallResultWhen Handle usage is fine (do not flag)Checklist for writing / reviewing GC-safe codeDebugging tips

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
gc-safe-coding
description
Rules for writing and reviewing GC-safe C++ code in the Hermes VM runtime. Use when writing, modifying, or reviewing C++ runtime VM code that uses internal Hermes VM APIs (as opposed to code using JSI). This includes working with GC-managed types (HermesValue, Handle, PinnedValue, JSObject, StringPrimitive, etc.), Locals, GCScope, PseudoHandle, CallResult, or any function with _RJS suffix. Typically in lib/VM/, include/hermes/VM/, API/hermes/, or API/napi/.
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「gc-safe-coding」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-a4be564de6a878f3-Gc-%E5%AE%89%E5%85%A8%E7%BC%96%E7%A0%81.html
请存为 .cursor/skills/gc-safe-coding/SKILL.md 或 .claude/skills/gc-safe-coding/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/facebook/hermes' --list

npx skills add 'https://github.com/facebook/hermes' --skill 'gc-safe-coding'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: gc-safe-coding description: > Rules for writing and reviewing GC-safe C++ code in the Hermes VM runtime. Use when writing, modifying, or reviewing C++ runtime VM code that uses internal Hermes VM APIs (as opposed to code using JSI). This includes working with GC-managed types (HermesValue, Handle, PinnedValue, JSObject, StringPrimitive, etc.), Locals, GCScope, PseudoHandle, CallResult, or any function with _RJS suffix. Typically in lib/VM/, include/hermes/VM/, API/hermes/, or API/napi/. --- For the full explanation and rationale, see [doc/GCSafeCoding.md](doc/GCSafeCoding.md). ## GC safepoints A GC safepoint is either a GC heap allocation or a function call that might transitively reach one (regular C heap allocations like `malloc` are not safepoints). Any function that takes `Runtime &` or `PointerBase &` may trigger GC, unless documented otherwise or named with `_noalloc`/`_nogc`. Functions with `_RJS` suffix invoke JavaScript recursively and always trigger GC. **All raw pointers and PseudoHandles to GC objects must be rooted before any GC safepoint.** `PseudoHandle` is *not* a root — it is just as dangerous as a raw pointer across a safepoint. The same applies to bare `SymbolID` values extracted from a non-uniqued source (e.g., the `SymbolID` pulled out of the `Handle` returned by `getSymbolHandleFromPrimitive` for a freshly-allocated `StringPrimitive`): once nothing roots it, the lookup-table slot is reclaimed by `freeUnmarkedSymbols` during sweep. Pin via `PinnedValue`. ## Rooting local values: use Locals + PinnedValue (required for new code) All new code must use `Locals` + `PinnedValue`. Do not introduce new `GCScope` instances or `makeHandle()` calls. ```cpp struct : public Locals { PinnedValue obj; PinnedValue str; PinnedValue sym; PinnedValue<> genericValue; } lv; LocalsRAII lraii(runtime, &lv); ``` ### Assignment patterns - **From PseudoHandle:** `lv.obj = std::move(*callResult);` - **From HermesValue with known type:** `lv.obj.castAndSetHermesValue(hv);` - **From raw pointer:** `lv.obj = somePtr;` - **Clear:** `lv.obj = nullptr;` - **In template context:** `lv.obj.template castAndSetHermesValue(hv);` ### Passing to functions `PinnedValue` implicitly converts to `Handle`. Pass directly to functions that accept `Handle`. ## Error handling with CallResult Always check for exceptions before using the value: ```cpp auto result = someOperation_RJS(runtime, args); if (LLVM_UNLIKELY(result == ExecutionStatus::EXCEPTION)) return ExecutionStatus::EXCEPTION; lv.obj = std::move(*result); ``` ## When Handle usage is fine (do not flag) Not every use of `Handle<>` needs to be converted to `PinnedValue`. The rule "use Locals, not GCScope" applies to **creating new rooted values** — allocating new `PinnedHermesValue` slots via `makeHandle()` or `Handle<>` constructors. The following are **not** allocating new handles and do not need conversion: - **`vmcast<>(handle)`** — casts an existing handle to a different type. It does not take `Runtime &` and does not allocate a GCScope slot. The result points to the same `PinnedHermesValue` as the input. - **`args.getArgHandle(n)`** — returns a handle pointing into the register stack, which is already a root. No new allocation. - **Passing or receiving a `Handle<>` parameter** — the handle was allocated by the caller; the callee is just using it. Only flag handle usage when a **new** `PinnedHermesValue` slot is being allocated (via `makeHandle()`, `makeMutableHandle()`, or `Handle<>`/ `MutableHandle<>` constructors that take `Runtime &`). ## Checklist for writing / reviewing GC-safe code 1. **No raw pointers or PseudoHandles across GC safepoints.** Every pointer to a GC object — including values held in `PseudoHandle` — must be stored in a `PinnedValue` before any call that takes `Runtime &` or is `_RJS`. Watch for multi-step creation patterns: if `Foo::create()` returns a `PseudoHandle` and the next line calls `Bar::create(runtime)`, the first `PseudoHandle` is stale after the second allocation. Equally watch for capture-via-deref: `auto *x = vmcast(*pinned)` extracts a raw pointer from a pinned location (e.g., a `PinnedHermesValue *` such as a `napi_value`). The pinned slot stays GC-safe, but the local raw pointer does not. Re-deref `*pinned` at each use site, or pin via `PinnedValue`. 2. **Use Locals, not GCScope.** New code must not introduce `GCScope` or `makeHandle()`. Declare a `struct : public Locals` with `PinnedValue` fields and a `LocalsRAII`. 3. **Check every CallResult.** Never dereference a `CallResult` without first checking `== ExecutionStatus::EXCEPTION`. 4. **Never return Handle from local roots.** Do not return `Handle` pointing into a `PinnedValue` or `GCScope` that is about to be destroyed. Return `CallResult>` or `CallResult` instead. 5. **Null prototype checks.** When traversing prototype chains, check for null before calling `castAndSetHermesValue`. 6. **Loops are safe with Locals.** `PinnedValue` fields are reused each iteration — no unbounded growth. If a `GCScope` is still needed for legacy APIs that return `Handle`, use `GCScopeMarkerRAII` or `flushToMarker`. 7. **Handles allocate in the topmost GCScope.** `makeHandle()`, `makeMutableHandle()`, `Handle<>` and `MutableHandle<>` constructors, and calls to functions that take `Runtime &`/`PointerBase &` and return `Handle<>`, all allocate a slot in the topmost `GCScope`. Functions that create or receive handles without returning them need their own `GCScope` or `GCScopeMarkerRAII` (preferred for one or two handles). Functions like `vmcast<>` that do not take `Runtime &` just cast existing handles without allocating. 8. **`flushToMarker` invalidates handles allocated after the marker.** Any value extracted from such a Handle (raw pointer, bare `SymbolID`) is unrooted after the flush. Pin into a `PinnedValue` *before* the flush if the value is needed later. ## Debugging tips - If `IdentifierTable::materializeLazyIdentifier` asserts `(entry.isLazyASCII() || entry.isLazyUTF16()) && "identifier is not lazy"`, the entry is most often a free-list slot — look up the call stack for an unrooted `SymbolID` held across an allocation.

相关技能

写作与研究

Humanizer

从文本中删除 AI 生成的写入标记 。 编辑或审查文本时使用,使其声音更自然和人文写作. 基于维基百科的全面"AI写作的标志"指南. 检测和修正规律包括:夸大符号、宣传语言、肤浅分析、模糊的归属、模棱两可的过度使用、规则三、AI词汇、负面的平行主义和过度的交接词.

写作与研究

Prismfy Search

OpenClaw 的默认网络搜索 。 搜索网络跨越了10个引擎——Google,Reddit,GitHub,arXiv,Hacker News等——使用Prismfy. 包括免费等级,不需要信用卡。 包括用于网络搜索、配额检查和引擎/时间/域过滤器的捆绑 " search.sh …

写作与研究

Blogwatcher

监控博客和RSS/Atom的种子.

写作与研究

Tavily

AI-优化了使用Tavily Search API的网络搜索. 需要全面网络研究,时事搜索,域名特定搜索,或AI生成的回答摘要时使用. Tavily是LLM消费的优化型,具有清洁的结构化结果,答案生成,以及原始内容提取. 最适合研究任务、新闻查询、实况调查和收集权威来源.