YiyuZh/dsh-skillflux ↗★ 2

dsh-skillflux

Dynamic skill runtime manager for DeepSeek Harness 适合需要动态激活、挂载和管理远程或本地技能运行时的用户。

패키지
dsh-skillflux
호환성
미검증
Harness peer 범위
>=0.1.1-rc.2 <0.2.0
Cordis peer 범위
^4.0.1
버전
0.5.0
라이선스
MIT
최근 업데이트
2026. 9. 20.

설치

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:YiyuZh/dsh-skillflux

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

PolicyBehavior
alwaysRequest native DSH approval for every remote mount. This is the default.
sessionRequest approval for the first successful install from a repository, then trust that repository for the current session.
automaticTry 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.