dsh-skillflux
动态技能运行时管理器 适合需要动态激活、挂载和管理远程或本地技能运行时的用户。
安裝
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:YiyuZh/dsh-skillflux說明文件
閱讀完整 README ↗Configuration
SkillFlux accepts these plugin options:
maxActiveSkills: 3
minRouteScore: 8
approvalPolicy: always # always | session | automatic; gates lazy remote activation and explicit mounts
remoteDiscovery: automatic # automatic (adaptive) | on-demand | off
remoteProviders: [skills.sh, github]
remoteSearchLimit: 5
remoteAutoMountLimit: 3 # max remote candidates published for lazy activation; 1 disables fallback
remoteSearchTimeoutMs: 30000
remoteMinQualityScore: 35 # 0-100
remoteMinStars: 0
remoteRecentActivityDays: 30
remoteTrustPolicy: community # open | community | corroborated | trusted
remoteTrustedOwners: [] # e.g. [anthropics, openai, vercel-labs]
remoteBlockedOwners: []
remoteCacheTtlMs: 300000 # 0 disables
remoteCacheStaleIfErrorMs: 86400000 # additional stale window
remoteCacheMaxEntries: 100
remoteHealthFailureThreshold: 3 # consecutive failures before a source is degraded
remoteHealthCooldownMs: 60000 # degraded source skip window
cacheAutoPrune: true
cacheMaxEntries: 100
cacheMaxTotalBytes: 536870912 # 512 MiB across installed Skills
cacheMaxIdleDays: 90 # 0 disables idle eviction
catalogDescriptionMaxLength: 160
catalogTokenBudget: 0 # 0 disables; otherwise 64-1000000
maxSkillFiles: 1000
maxSkillBytes: 10485760
installTimeoutMs: 300000
routerMode: lexical # lexical | hybrid
embeddingProvider: ollama # ollama | openai-compatible
embeddingEndpoint: http://127.0.0.1:11434/api/embed
embeddingModel: embeddinggemma
embeddingApiKeyEnv: SKILLFLUX_EMBEDDING_API_KEY
embeddingTimeoutMs: 5000
embeddingCandidateLimit: 128
embeddingCacheSize: 512
minEmbeddingSimilarity: 0.45
usageTracking: true
usageMaxEntries: 1000
adaptiveRouting: false
adaptiveMaxBoost: 6
adaptiveMinUses: 2
adaptiveHalfLifeDays: 30
mcpDiscovery: automatic # automatic | off; gates registered MCP Skills sources
mcpTrustedServers: [] # host-assigned labels allowed trusted evidence
mcpBlockedServers: [] # host-assigned labels whose skills are always refused
registryDiscovery: off # off | automatic; experimental federated index ingestion
routes: []
Add ordered rules when a known task must prefer specific Skills:
routes:
- matchAll: [pdf, analyze]
skills: [pdf-reader, document-parser]
- matchAny: [react, frontend]
skills: [react-specialist]
A rule can contain matchAll, matchAny, or both. Rule results keep their
declared order, skip unavailable Skills, and still respect
maxActiveSkills.
Hybrid embedding router
Embedding routing is opt-in. The recommended private setup uses Ollama:
ollama pull embeddinggemma
routerMode: hybrid
embeddingProvider: ollama
embeddingEndpoint: http://127.0.0.1:11434/api/embed
embeddingModel: embeddinggemma
For an OpenAI-compatible embedding service, select the protocol and point at its exact embeddings endpoint:
routerMode: hybrid
embeddingProvider: openai-compatible
embeddingEndpoint: https://provider.example/v1/embeddings
embeddingModel: provider-embedding-model
embeddingApiKeyEnv: SKILLFLUX_EMBEDDING_API_KEY
Set the named environment variable in the process that launches DSH. SkillFlux never stores that value. Candidate vectors are kept in a bounded in-memory LRU and disappear when the plugin stops. An unavailable, malformed, timed-out, or reconfigured embedding endpoint fails open to the lexical result.
Usage statistics and adaptive routing
Usage tracking records successful mounts and successful skill({ name })
loads by exact candidate ID. It is enabled by default, while adaptive routing
is opt-in:
usageTracking: true
adaptiveRouting: true
adaptiveMaxBoost: 6
adaptiveMinUses: 2
adaptiveHalfLifeDays: 30
Records are stored atomically in
$DSH_HOME/storages/skillflux/usage.json (normally
~/.dsh/storages/skillflux/usage.json) and bounded by usageMaxEntries.
The file also has a hard 2 MiB limit; least-recently-useful records are evicted
first when either bound is reached.
SkillFlux stores only the candidate ID, Skill name, origin, source, counters,
token counts, and timestamps. It does not store task text, Skill instructions,
or resources.
The boost is capped by adaptiveMaxBoost, requires at least
adaptiveMinUses successful loads, and halves after
adaptiveHalfLifeDays without use. A telemetry read or write failure falls
open to normal routing. Set usageTracking: false to disable persistence; in
that case adaptiveRouting must also remain false.
Token telemetry
When the host mounts the DSH token-meter service, SkillFlux prices the catalog
entry lines and each loaded SKILL.md body with the native estimator. When the
service is absent, it falls back to the same portable estimate the catalog
budget uses (ceil(UTF-8 bytes / 3)). No package dependency is added for this:
the optional ctx.tokenMeter service is resolved at runtime and any failure
degrades silently to the portable estimate.
Per-skill token counts are appended to the usage records and shown by
/skillflux status and /skillflux usage: the catalog footprint at the last
mount, the loaded-body tokens at the last load, and their running total, plus
which estimator produced them. Only token counts are persisted; task text,
Skill instructions, and resources never reach usage.json. When two installed
cache versions are otherwise identical on recency, uses, and mounts, pruning
evicts the higher running body-token version first; the ordering is
deterministic and absent evidence leaves the historical order unchanged.
Token telemetry never changes routing or approval decisions.
Catalog context budget
catalogTokenBudget is an optional second bound in addition to
maxActiveSkills. The default 0 keeps existing behavior. A nonzero value
preflights each mount and rejects only the candidate that would exceed the
budget, allowing later smaller or same-name fallback candidates to continue:
maxActiveSkills: 3
catalogDescriptionMaxLength: 160
catalogTokenBudget: 512
The estimate covers the complete replacement-form Skill catalog prompt after
description truncation. It uses ceil(UTF-8 bytes / 3): intentionally
conservative for typical English and close to one token per CJK character, but
it is not a model-specific tokenizer result. /skillflux status reports the
current estimate and /skillflux explain marks rejected candidates as
budget-skipped.
Approval policies
| Policy | Behavior |
|---|---|
always | Request native DSH approval for every remote mount. This is the default. |
session | Request approval for the first successful install from a repository, then trust that repository for the current session. |
automatic | Try ranked remote candidates until one mounts, without approval. Use only in a trusted environment. |
If approval is unavailable, rejected, or canceled, the remote mount fails closed.
Automatic remote fallback
With approvalPolicy: automatic, a broken first result no longer blocks a
usable second result. SkillFlux tries at most remoteAutoMountLimit candidates
in discovery order (default 3, allowed 1–5), stopping after the first
successful mount. Set it to 1 for single-candidate behavior.
All attempts share one installTimeoutMs deadline, starting after discovery.
The next candidate is not started after this deadline, explicit cancellation,
or turn cleanup. In-flight lock acquisition and cleanup are awaited safely;
the deadline is not a strict wall-clock bound on their completion.
Every attempt still enforces current trust/owner policy, pinned-source
verification, installed-content integrity, and catalog limits.
/skillflux explain records mount-failed, mount-timeout, budget-skipped, or mounted.
Failed candidates are removed from this turn's hint; unattempted candidates
remain available. A new skillflux_search can retry a failure; failures are not
persisted as a blacklist. always, session, and explicit skillflux_mount
keep their existing approval behavior and never silently switch candidates.
MCP Skills sources
SkillFlux can serve skills published over the Model Context Protocol Skills
extension (io.modelcontextprotocol/skills, SEP-2640). A transport-agnostic
McpSkillsClient speaks skills/list, skills/get, and resources/read over
any injected transport; the host assigns each source a stable label, which is
the origin half of every skill identity:
import { McpSkillsClient, McpStdioTransport } from 'dsh-skillflux'
// The bundled zero-dependency stdio transport speaks LSP-style
// Content-Length framed JSON-RPC to a child MCP server process.
const transport = new McpStdioTransport({ command: 'node', args: ['server.mjs'] })
ctx.skillFlux.registerMcpSource('docs-server', new McpSkillsClient(transport))
SSE and Streamable HTTP transports remain consumer-provided: implement the
small McpTransport interface (request(method, params)) and pass it to
McpSkillsClient. pnpm test:mcp-live exercises the bundled stdio transport
against a checked-in conformance server, including a tampered-digest
fail-closed run.
Listings flow through the same trust and approval boundaries as remote
candidates. Every entry is validated against the extension contract, a skill
whose resources is "dynamic" is refused because it cannot be content-bound,
and approvals bind to the sorted [uri, digest, size] set. Files are fetched
lazily through resources/read, digest- and size-verified, frontmatter-verified
against the entry, and materialized under a cache id that encodes the server
label, SKILL.md URI, and content-bound key; changed content lands at a fresh
id and never overwrites an approved snapshot. MCP content is always tagged with
its server label, never executes during discovery or loading, and never
silently shadows a same-named skill from another origin. A source that cannot
be listed fails open for that turn and is reported as non-authoritative.
Federated registry indexes (experimental)
registryDiscovery: automatic (off by default) lets the host register a
federated ecosystem index whose entries flow into the same immutable-commit,
evidence, and approval pipeline as every other remote candidate:
import type { RegistryIndexTransport } from 'dsh-skillflux'
const transport: RegistryIndexTransport = { list: () => index.fetch() }
ctx.skillFlux.registerRegistryIndex('ds-ecosystem', transport)
Each entry is pinned to a 40-character commit and carries an advisory
official | verified | community | unreviewed tier. Tiers surface as quality
signals and warnings; they never grant trust, never bypass remoteTrustPolicy
or blocked owners, and never change the content-pinning requirements. A
partial or failing index listing degrades the discovery observation without
weakening the candidates that remain. Index queries are never persisted.
Usage statistics and adaptive routing
Usage tracking records successful mounts and successful skill({ name })
loads by exact candidate ID. It is enabled by default, while adaptive routing
is opt-in:
usageTracking: true
adaptiveRouting: true
adaptiveMaxBoost: 6
adaptiveMinUses: 2
adaptiveHalfLifeDays: 30
Records are stored atomically in
$DSH_HOME/storages/skillflux/usage.json (normally
~/.dsh/storages/skillflux/usage.json) and bounded by usageMaxEntries.
The file also has a hard 2 MiB limit; least-recently-useful records are evicted
first when either bound is reached.
SkillFlux stores only the candidate ID, Skill name, origin, source, counters,
token counts, and timestamps. It does not store task text, Skill instructions,
or resources.
The boost is capped by adaptiveMaxBoost, requires at least
adaptiveMinUses successful loads, and halves after
adaptiveHalfLifeDays without use. A telemetry read or write failure falls
open to normal routing. Set usageTracking: false to disable persistence; in
that case adaptiveRouting must also remain false.