菜单
Use when a cast needs to verify whether a package, type, or middleware exists in github.com/tink3rlabs/magic — the in-bounds surface for spellcasting templates
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Use when adding a complete resource to an existing magic-based service — emits migration, types, service layer, and route layer in one pass
Use when bootstrapping a brand-new microservice on github.com/tink3rlabs/magic — clones the service template, applies wizard answers, runs a smoke build
Use when adding domain logic (types + service interface + implementation) for a resource without HTTP — typically because the route is handled differently (worker, scheduled job, internal-only)
Use when the user asks to scaffold or extend a magic-based service and the right cast sequence is ambiguous — runs a question tree and emits a cast plan
Use when modifying an existing resource on a magic-based service — add a column, add a filter, add a role guard, add soft-delete, swap a storage adapter — enforces DTO-completeness on every field change
Use when a request involves creating, scaffolding, or extending a microservice built on github.com/tink3rlabs/magic — establishes which cast to invoke and the magic-only capability boundary
| name | magic-capabilities |
| description | Use when a cast needs to verify whether a package, type, or middleware exists in github.com/tink3rlabs/magic — the in-bounds surface for spellcasting templates |
The authoritative answer to "is X available in github.com/tink3rlabs/magic?". Pinned to v0.17.3. If your magic is newer, prefer upstream and note the drift in your cast output.
NOTE — reconciled against real magic v0.17.3 source on 2026-05-29. Three major corrections vs. previous content:
storage.NewStorageAdapter()does not exist → usestorage.StorageAdapterFactory{}.GetInstance(type, configMap).mql.Parse(string)does not exist → usemql.NewParser(input).Parse(); but service layers should pass raw Lucene tostorage.Search, not call the parser directly.- Migration YAML has no
id:field — the numeric ID is encoded in the filename prefix (0001__create_RESOURCETABLE.yaml). YAML fields aredescription:+migrations: [{migrate: ..., rollback: ...}].
Every cast template references only what's in this surface. If a generated file imports a package not listed here — or imports anything from a project-specific common library that wraps magic — the cast has failed. Revert and use an in-bounds equivalent.
github.com/tink3rlabs/magic/storageAdapter type constants (pass to StorageAdapterFactory.GetInstance):
| Constant | Value |
|---|---|
storage.MEMORY | in-process map; no persistence |
storage.SQL | PostgreSQL / MySQL via database/sql |
storage.COSMOSDB | Azure Cosmos DB |
storage.DYNAMODB | AWS DynamoDB |
Config shape (config/default.yaml):
storage:
type: memory # one of the constants above (lowercase string value)
config: # flat map[string]string passed to GetInstance
schema: myservice
host: localhost
port: "5432"
# ... adapter-specific keys
Symbols:
| Symbol | Kind | Signature / Use | Doc |
|---|---|---|---|
StorageAdapterFactory | struct | Factory; use {}.GetInstance(...) | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapterFactory |
StorageAdapterFactory.GetInstance | method | GetInstance(t StorageAdapterType, config map[string]string) (StorageAdapter, error) — constructs adapter from type constant + flat config map | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapterFactory.GetInstance |
StorageAdapterType | type | string alias; cast with storage.StorageAdapterType(viper.GetString("storage.type")) | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapterType |
StorageAdapter | interface | Common adapter contract implemented by every backend | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
StorageAdapter.List | method | List(dest any, sortKey string, filter map[string]any, limit int, cursor string, params ...map[string]any) (string, error) — returns next cursor | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
StorageAdapter.Search | method | Search(dest any, sortKey string, query string, limit int, cursor string, params ...map[string]any) (string, error) — accepts raw Lucene string; adapter parses and evaluates | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
StorageAdapter.Get | method | Get(dest any, filter map[string]any, params ...map[string]any) error | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
StorageAdapter.Create | method | Create(value any, params ...map[string]any) error | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
StorageAdapter.Update | method | Update(value any, filter map[string]any, params ...map[string]any) error | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
StorageAdapter.Delete | method | Delete(value any, filter map[string]any, params ...map[string]any) error | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#StorageAdapter |
NewDatabaseMigration | func | NewDatabaseMigration(adapter StorageAdapter) *DatabaseMigration — build a migration runner | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage#NewDatabaseMigration |
ConfigFs | var (embed.FS) | Set by main.go to expose embedded config/ to migrations | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/storage |
NewStorageAdapter does not exist — this is a common error in older docs. Always use StorageAdapterFactory{}.GetInstance.
github.com/tink3rlabs/magic/middlewaresgithub.com/tink3rlabs/magic/observability| Symbol | Kind | Use | Doc |
|---|---|---|---|
Observer | struct | The handle held by cmd/server.go, passed to middleware + /metrics | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability#Observer |
Init | func | Init(ctx, cfg) (*Observer, error) — boots Prometheus exporter + OTLP tracer | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability#Init |
DefaultConfig | func | Returns a Config with sensible defaults; service tunes fields after | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability#DefaultConfig |
Config | struct | {ServiceName, MetricsMode, EnableTracing, TracesOTLPEndpoint, TracesOTLPInsecure} | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability#Config |
MetricsModePrometheus | const | Metrics mode constant; sister value MetricsModeDisabled exists | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability |
Observer.MetricsHandler | method | http.Handler to mount at /metrics | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability#Observer.MetricsHandler |
Observer.Shutdown | method | Flush spans + exporters on graceful shutdown | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/observability#Observer.Shutdown |
github.com/tink3rlabs/magic/health| Symbol | Kind | Use | Doc |
|---|---|---|---|
NewHealthChecker | func | Build a checker bound to a StorageAdapter | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/health#NewHealthChecker |
HealthChecker.Check | method | Check(storageEnabled bool, deps []string) error — used in /health/readiness | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/health#HealthChecker.Check |
github.com/tink3rlabs/magic/leadership| Symbol | Kind | Use | Doc |
|---|---|---|---|
LeaderElectionProps | struct | {HeartbeatInterval, StorageAdapter, AdditionalProps} | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/leadership#LeaderElectionProps |
NewLeaderElection | func | Start a single-leader election against the storage adapter | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/leadership#NewLeaderElection |
LeaderElection.Start | method | Begin heartbeat loop in a goroutine | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/leadership |
github.com/tink3rlabs/magic/mql| Symbol | Kind | Use | Doc |
|---|---|---|---|
NewParser | func | NewParser(input string) *Parser — creates a parser for the given Lucene query string | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/mql#NewParser |
Parser.Parse | method | Parse() (Expr, error) — parses and returns the AST | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/mql#Parser.Parse |
| AST node types | structs | Query, Clause, Term, Range, Boolean for predicate construction | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/mql |
mql.Parse(string) does not exist — use mql.NewParser(input).Parse().
Preferred pattern: service layers pass the raw Lucene string directly to storage.Search(...) and let the adapter parse and evaluate it. Only call mql.NewParser when you need in-process AST evaluation (e.g. to validate, transform, or inspect the query before sending it to storage).
github.com/tink3rlabs/magic/errors| Symbol | Kind | Use | Doc |
|---|---|---|---|
BadRequest | struct | 400; {Message}; returned from handlers, mapped by ErrorHandler | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#BadRequest |
Unauthorized | struct | 401 | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#Unauthorized |
Forbidden | struct | 403 | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#Forbidden |
NotFound | struct | 404 | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#NotFound |
Conflict | struct | 409 | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#Conflict |
ServiceUnavailable | struct | 503 | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#ServiceUnavailable |
Internal | struct | 500 fallback | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/errors#Internal |
github.com/tink3rlabs/magic/logger| Symbol | Kind | Use | Doc |
|---|---|---|---|
| slog handler helpers | funcs | Configure structured logging with trace correlation | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/logger |
github.com/tink3rlabs/magic/pubsub| Symbol | Kind | Use | Doc |
|---|---|---|---|
Publisher, Subscriber | interfaces | Cross-adapter pub/sub contract | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/pubsub |
| adapter constructors | funcs | Backend-specific constructors selected via viper config | https://pkg.go.dev/github.com/tink3rlabs/magic@v0.17.3/pubsub |
casting-a-new-service)If a generated file imports or names any of the following categories, the cast has failed:
github.com/tink3rlabs/magicstorage.StorageAdapterFactory{}.GetInstance(...) / storage.NewDatabaseMigration(...).Migrate()middlewares.RequireRoleIn-bounds equivalents for common needs:
| You might want | In-bounds option |
|---|---|
| Structured request logging | chi's middleware.Logger, or magic's slog handler |
| Rate limiting | not in v0.1; user adds after the cast |
| Audit logging | not in v0.1; user adds after the cast |
| Response caching | not in v0.1; user adds after the cast |
| Tenant context on every request | middlewares.TenantRequestContext |
| Storage bootstrap + migrations | storage.StorageAdapterFactory{}.GetInstance(type, configMap) + storage.NewDatabaseMigration(adapter).Migrate() |
| Role-based authorization | middlewares.RequireRole |
| Per-resource ACL | not in v0.1; user adds after the cast |
When magic cuts a new tag:
Pinned to **v0.17.3** line at the top of this skill body.pkg.go.dev URL; any 404 → that symbol was renamed or removed; reconcile with upstream.storage.StorageAdapterFactory{}.GetInstance → something else), update templates/service/cmd/server.go to match.v0.1 is manually maintained. v0.2+ may auto-generate from go doc -all.