菜单
Grafema release procedure for publishing new versions to npm. Covers happy path, pitfalls, rfdb binary lifecycle, and rollback. Use when user says "release", "publish", "bump version".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Fix RFDB V2 graph data silently not persisting to disk after analysis. Use when: (1) rfdb-server reports "0 nodes, 0 edges" on restart despite successful analysis, (2) segment directories exist but are empty (no .bin files), (3) manifest_index.json shows total_nodes: 0 despite analysis logging 70k+ nodes, (4) Docker builds produce empty graph databases, (5) --clear flag used before analyze command. Root cause: GraphEngineV2::clear() replaces the store with MultiShardStore::ephemeral() which has path: None, causing all flush operations to write to in-memory buffers only.
Fix missing theorem proof terms when analyzing Lean 4 environments via importModules. Use when: (1) ConstantInfo.value? returns none for theorems despite TheoremVal.value being Expr, (2) building code graph / dependency extractor for Lean 4 and getting 0 proof dependency edges, (3) Lean 4.30+ project where theorem proofs appear missing from loaded environment, (4) analyzing Mathlib or any Lean 4 project and proof terms are empty. Root cause: breaking change in Lean 4.30 — value? treats theorems as opaque by default.
Fix silent metadata issues in RFDB node storage. Covers two traps: (1) metadata flattening — nested metadata fields become top-level after serialization, so node.metadata.field is undefined but node.field works. (2) reserved keys — fields named "type", "id", "name", "file", "exported" are silently stripped from metadata by _parseNode() to prevent overwriting top-level node fields.
Diagnose React + Three.js (or any browser canvas) frame stutter by capturing a CDP CPU profile via Playwright instead of guessing from `[perf]` console logs. Use when: (1) frame time is bad but `[perf]` instrumentation doesn't pinpoint the offender, (2) you've spent more than ~30 minutes "fixing" suspects without measuring, (3) hot paths involve animation systems, allocation bursts, or invisible scene-graph traversal, (4) you need self-time per function with line numbers, not aggregate "render slow". The `console.warn` pattern is good for monitoring; CDP is needed for diagnosis. Covers script template, sourcemap setup so minified function names are decoded, and interactive variant where the user drives the interaction and signals stop via `touch /tmp/<flag>`.
Force `rust-embed` to re-embed assets from `$GRAFEMA_UI_DIST` (or any env-driven path) when cargo's incremental compilation skips the macro re-expansion. Use when: (1) you rebuilt the GUI bundle but the rust-server binary still serves the OLD bundle, (2) `cargo build --release` finishes in seconds (incremental hit) and `strings target/release/binary | grep <new-hash>` finds nothing, (3) any rust-embed pipeline where assets live outside the cargo source tree and are picked up via env var or symlink. Cargo only re-runs the proc macro when the rust file declaring `#[derive(RustEmbed)]` changes — env var changes alone don't trigger it.
Verify which process actually owns a TCP port before assuming your fresh restart succeeded. Use when: (1) you killed an old server and started a new one but behaviour matches the OLD code/data, (2) `pkill -f pattern` returned 0 but old behaviour persists, (3) you embedded a new asset/binary but the served version is stale, (4) any "I just restarted X but I'm getting old results" situation. `pkill -f` matches against the process command line — if the live old process was started with `--port 0` (auto-assigned) and got the port you now want, the pattern won't match it. Always verify with `lsof -i :PORT` before debugging deeper.
| name | grafema-release |
| description | Grafema release procedure for publishing new versions to npm. Covers happy path, pitfalls, rfdb binary lifecycle, and rollback. Use when user says "release", "publish", "bump version". |
| author | Claude Code |
| version | 3.0.0 |
| date | "2026-05-03T00:00:00.000Z" |
./scripts/release.sh patch --dry-run # Preview
./scripts/release.sh patch # Bump only
./scripts/release.sh 0.2.5-beta --publish # Bump and publish
main branch, clean working directorypnpm build — MUST run before tests (tests import from dist/)pnpm test — verify tests passnpm whoami — verify npm authIf releasing @grafema/rfdb, download prebuilt binaries BEFORE publishing:
git log $(git tag -l 'rfdb-v*' | sort -V | tail -1)..HEAD -- packages/rfdb-server/src/
git tag rfdb-v0.X.Y && git push origin rfdb-v0.X.Y./scripts/download-rfdb-binaries.sh rfdb-v0.X.Yls -la packages/rfdb-server/prebuilt/*/rfdb-server — must show 4 binariesnpm tags (v0.2.12-beta) and rfdb CI tags (rfdb-v0.2.12-beta) are independent. The release script doesn't check if binaries match current Rust source.
| Type | npm dist-tag |
|---|---|
patch / minor / major / 0.3.0 | latest |
prerelease / 0.2.5-beta | beta |
@grafema/types → @grafema/rfdb-client → @grafema/util → @grafema/mcp → @grafema/api → @grafema/cli → @grafema/rfdb
.gitignore pattern .grafema/* is anchored to root. Use **/.grafema/graph.rfdb/ for nested matches.
Release script runs tests BEFORE building. dist/ is stale. Fix: run pnpm build manually first.
macOS vs Linux rfdb-server may produce different graph output. Workaround: --skip-ci-check.
release.sh packages whatever is in prebuilt/. See "MANDATORY" section above.
release-validate.yml runs automatically (5-10 min)release-publish.yml manuallynpx @grafema/cli@<version> --versionnpm unpublish @grafema/cli@0.2.5-beta # within 72 hours
# or
npm deprecate @grafema/cli@0.2.5-beta "Use 0.2.4-beta instead"
git revert HEAD && git push origin main stable
git tag -d v0.2.5-beta && git push origin :refs/tags/v0.2.5-beta
## [0.X.Y-beta] - YYYY-MM-DD
### Highlights
### Features
### Bug Fixes
### Infrastructure
### Known Issues
npx @grafema/cli@latest --versionstable branch auto-updated by release script