binding-architecture

Architecture rules for the polyglot binding layer and the C FFI boundary — crate naming, distribution paths, ownership and null-safety invariants, error-context propagation, and async patterns. Load when designing or editing language bindings, the C ABI, cbindgen headers, or FFI type/error conversions.

跳到安装

仓库: xberg-io/agent-conventions
最近来源活动: 2026年7月22日 15:14
检测到的 SKILL.md 语言: 英语
星标: 7
分支: 2

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

直接命令不会经过审查 Prompt；运行前请先检查来源。

npx skills add https://github.com/xberg-io/agent-conventions --skill binding-architecture

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

SKILL.md

来源说明 · 只读预览

返回搜索返回安装

xberg-brand-and-docs

Canonical xberg.io brand, product catalog, docs-site (Astro Starlight + @xberg-io/docs-theme), alef badge, docs task commands, prose style, Google Analytics IDs, brand assets, and README-template policy. Load when writing READMEs or docs, editing docs-site config, adding the ecosystem block or alef badge, or touching brand/analytics wiring.

2026-07-31

feature-flag-conventions

The shared Cargo feature-flag naming and semantics contract across xberg-io Rust libraries — the same flag names mean the same thing everywhere (otel, mcp/mcp-http, mimalloc/jemalloc, acceleration). Load when adding, renaming, or reviewing a crate's [features], or reconciling a library's flags with the rest of the stack.

2026-07-30

tracing-conventions

The canonical contract for tracing as a first-class product observability surface across xberg-io Rust libraries and services — level semantics, span/field naming, instrumentation patterns, and how xberg-enterprise consumes library spans over OTLP. Load when adding or reviewing tracing instrumentation, designing spans/events, wiring a subscriber, or reconciling observability features.

2026-07-30

查看这个仓库的全部 Skills

Binding Architecture

Bindings

Bindings are minimal glue: call Rust core, convert types, convert errors — no business logic

Canonical surface: Rust core API first, C FFI ABI second, language bindings third; integrations/adapters sit outside bindings

Crate naming: {lib}-py (PyO3), {lib}-node (NAPI-RS), {lib}-rb (Magnus), {lib}-php (ext-php-rs), {lib}-wasm (wasm-bindgen), {lib}-ffi (C FFI), {lib}-jni (JNI)

Distribution paths: packages/python/ (PyPI), typescript/ (npm), ruby/ (RubyGems), php/ (Composer), go/ (Go module), java/ (Maven), csharp/ (NuGet), dart/ (pub.dev), swift/ (SwiftPM), kotlin-android/ (Maven/Gradle), r/ (CRAN/GitHub), zig/ (Zig package)

Each binding has its own language-native test suite — 80%+ coverage

Generated e2e code lives under e2e/{language}/ and is not hand-edited

Error conversion must preserve context (message + numeric code) at every FFI boundary

Async: pyo3_asyncio (Python), native #[napi] async (TS), Fiber (Ruby), block on Tokio via FFI only at sync host boundaries

FFI and language interop

Every pointer has one owner, documented with SAFETY comments

Opaque handles only — never expose Rust types directly, use #[repr(transparent)] wrappers

Null safety: check ALL pointers before use, return null + error code on failure

Allocate/free pairs: every _new() has a matching _free(), caller owns *mut

Every unsafe block has a SAFETY comment: what invariant, why it holds, what breaks if violated

Generate C headers with cbindgen — CI verifies generated headers match committed

C ABI is the stable native contract for Go, Java/JNI, C#, Dart, Swift, Kotlin Android, Zig, and R wrappers

Semantic versioning for C headers, struct layouts frozen at MAJOR.MINOR boundaries

All exported functions use #[no_mangle] extern "C"

Rust Result<T, E> → host exceptions via dedicated conversion functions at every boundary

Preserve error context across boundaries: message, numeric code (1000+), source location, cause chain