菜单
Use when bumping a bun-managed dependency in interface/, docs/, packages/api-client/, or spaceui/. Avoids the "lockfile updated, manifest spec stale" drift class that opened PRs
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
Specialized Spacebot development skill with deep architectural knowledge. Use when working on any Spacebot feature, bug fix, refactor, or investigation. Covers the five-process agent model (Channel, Branch, Worker, Compactor, Cortex), memory system (SQLite + LanceDB + redb), task lifecycle, 60+ tool definitions, Rig framework integration, prompt templates, identity system, messaging adapters, config hot-reload, security/sandbox, and API server. Activate for any Rust code changes in src/, prompt template edits in prompts/, migration work, tool additions, or architectural questions.
Use this skill when preparing a release bump or updating release notes. It writes a launch-style release story from the actual change set, then runs `cargo bump` so the generated GitHub notes and the marketing copy land together in `CHANGELOG.md`.
Use when auditing project documentation for drift, stale claims, missing changelog entries, completed-but-still-listed TODOs, or when the user asks to review/refresh/cleanup docs across interface/, spaceui/, docs/, or repo-root markdown files. Complements session-sync (which handles CLAUDE.md + memories only).
Pre-stage the fastembed BGESmallENV15 ONNX model cache so the 4 memory::search integration tests can run reliably. Call when the user reports `EmbeddingFailed("Failed to retrieve onnx/model.onnx")`, when memory::search tests fail with `native-tls` cert errors, or before a `cargo test --lib` run on a fresh checkout / clean target/.
Use this skill when adding a new REST handler under `src/api/`. Scaffolds the full utoipa + typegen dance: handler function with correct extractor ordering (State → Path → Query → Json), request/response structs with `#[derive(utoipa::ToSchema)]`, `#[utoipa::path(...)]` annotation, router registration in `src/api/server.rs`, and the `utoipa::OpenApi` registration block. Reminds to run `just typegen` + `just check-typegen` before commit. Canonical rule: `.claude/rules/api-handler.md`.
Reference knowledge about the Talos Kubernetes cluster that Spacebot deploys into. Use PROACTIVELY when working on containerization, Dockerfile changes, deployment configuration, health checks, environment variables, networking, storage, secrets, database connections, or any work that touches how Spacebot runs in production. Also use when the user mentions the cluster, Kubernetes, k8s, Talos, Flux, namespaces, pods, or asks about Spacebot's production environment.
基于 SOC 职业分类
| name | bun-deps-bump |
| description | Use when bumping a bun-managed dependency in interface/, docs/, packages/api-client/, or spaceui/. Avoids the "lockfile updated, manifest spec stale" drift class that opened PRs |
Bump a bun-managed dependency so that both package.json (the spec range) and bun.lock (the resolved version) move. The lockfile alone is not enough. Dependabot scans package.json and will reopen PRs forever if the spec range still allows the old version.
bun update has three behaviors depending on the spec format. This is the table that bit us in 2026-04-26 (cost ~30 minutes + 4 reopened dependabot PRs):
| Spec format | bun update <pkg> | bun update <pkg> --latest |
|---|---|---|
"^3.2.4" | Bumps lockfile to latest within ^3.x. Spec stays. | Bumps to latest on npm + rewrites spec to new major. |
"3.2.4" (exact) | No-op. Cannot move within zero range. | Bumps to latest + rewrites spec to exact-of-new-version. |
"~3.2.4" | Bumps lockfile to latest within ~3.2.x. Spec stays. | Same as ^. |
Rule of thumb: use --latest for any major-version bump OR for exact-pinned packages. Plain bun update is only correct for "pull patches within current spec range."
| Workspace | Where to run | Test command |
|---|---|---|
interface/ | cd interface && bun update <pkg> --latest | bunx vitest run |
docs/ | cd docs && bun update <pkg> --latest | bun run build |
packages/api-client/ | cd packages/api-client && bun update <pkg> --latest | bun run test |
spaceui/ | cd spaceui && bun update <pkg> --latest (then just spaceui-build) | just spaceui-gate |
Note: spaceui has its own bun.lock and its own root manifest. interface/ declares ../spaceui/packages/* and ../packages/* as workspace members, so bun resolves @spacedrive/* and @spacebot/* via local symlink. Do not bump packages from inside interface/ if they belong to spaceui or packages/api-client.
# 1. Bump the spec + lockfile in one shot
cd <workspace>
bun update <pkg> --latest
# 2. Verify BOTH moved (catches the silent-no-op case for exact pins)
grep '"<pkg>"' package.json
grep -E '"<pkg>@' bun.lock | head -1
# 3. If only bun.lock moved, the spec was an exact pin and `bun update`
# silently no-op'd. Edit package.json by hand to the new version and
# re-run `bun install`.
# 4. Run workspace-appropriate tests (see table above)
# 5. Commit BOTH package.json AND bun.lock
git add <workspace>/package.json <workspace>/bun.lock
git commit -m "deps(<workspace>): bump <pkg> <old> → <new>"
Major bumps (e.g., 3.x → 4.x) need investigation BEFORE merge. Check:
@radix-ui/* under @spacedrive/primitives) hit React-resolution issues at runtimePast sessions surface in .serena/memories/phase11_dual_backend.md and the feat-/dependabot-/... commit log. The vitest 3 → 4 upgrade in PR #125/#130 (commit 2b63a14) needed a custom reactSingletonPlugin in interface/vitest.config.ts because of a workspace-symlink interaction with spaceui/node_modules/.bun/react@19.2.5. Read that commit message before any future Vite-ecosystem major bump.
bunx tsc --noEmit validates against the type defs in node_modules/.bun/<pkg>@<version>/. After a major-version bump, the local node_modules cache may still hold the OLD version's type defs even after bun.lock resolves to the new version. Two failure modes:
node_modules/.bun/<pkg>@<oldver>/ is still on disk and gets resolved before the new version. CI does a clean install → uses only the new defs → catches stricter typing.Always run a clean tsc verification after a major bump:
cd <workspace>
bun install --force # rebuild node_modules from lockfile
bunx tsc --noEmit # validates against the new type defs
Concrete example (caught at commit 4f6c1c8, 2026-04-26): vitest 4 made mock.calls typing stricter than v3. A test using consoleErrorSpy.mock.calls.find((call) => ...) had a callback param that auto-inferred under v3 but fell back to implicit any under v4. Local tsc passed (vitest 3 type defs still cached); CI failed with TS7006: Parameter 'call' implicitly has an 'any' type. Fix: explicit (call: unknown[]) annotation at the call site, matching the as string cast on the next line.
If a major bump cannot land cleanly, document the deferral in .github/dependabot.yml with an ignore rule + an inline comment that names the unblock condition. Pattern from commit faca85b (jsonwebtoken + nom) and 2b63a14 (jsdom):
ignore:
# <pkg> X.x has breaking API changes in <areas>. Migration tracked
# for after <unblock condition>. See PR #N for the failure surface.
- dependency-name: "<pkg>"
update-types: ["version-update:semver-major"]
dependabot-response — triages individual dependabot PRs (SAFE-FOLD / DEFER / SKIP verdict)dep-spec-auditor (subagent) — parallel-audits all workspaces for manifest/lockfile drift at PR timepr-gates — final pre-push gate that includes cd interface && bun run build