king-bcolor / dsh-ncm-plugin

dsh-ncm-plugin

中文文档：README.zh-CN.md

A DeepSeek Harness plugin that wraps the ncm-cli NetEase Cloud Music command-line tool as model-callable tools.

What it is

dsh-ncm-plugin exposes NetEase Cloud Music CLI capabilities to DSH agents: account status, playlists, songs, lyrics, playable URLs, daily recommendations, play records, search, and playlist management/cleanup — all through structured, JSON-backed tools.

Features

• Account: login status, current user, version.
• Playlists: list/show/create/add/remove/rename/tags/desc/delete.
• Playlist tidy: inspect, filter, diff, apply, move, duplicates.
• Songs: metadata, lyrics, playable URL resolution, desktop playback.
• Discovery: daily recommendations, weekly/all play records.
• Search: suggestions, songs, playlists.
• Safe by default: destructive writes require explicit confirmation.
• JSON-first output for agents, readable text rendering for the UI.
• Built-in Web Settings panel: every tool is exposed as an auto-generated form (account, playlists, tidy, search, song/lyric/URL, recommendations).

Use cases

• Ask the agent "what's in my playlist 490155105?"
• Search for songs and add them to a playlist.
• Clean up duplicate songs in a large playlist.
• Look up lyrics and playable URLs.
• Check daily recommendations and play history.

See docs/用例目录/README.md for the full command/use-case/parameter catalog (Chinese).

Installation

Preconditions

• Node.js 22+, dsh CLI installed (npx @deepseek-ai/dsh web).
• No preinstalled ncm CLI is required. The plugin auto-downloads the platform release binary into $DSH_HOME/bin on first tool run, or when you click Install/update ncm in the UI. Download order: ghfast.top → gh-proxy.com → GitHub official, so mainland-China networks use mirrors first. Playwright driver downloads use npmmirror.com by default.

Install from GitHub

Install into the web profile so the browser UI is available:

dsh plugin --profile web add github:king-bcolor/dsh-ncm-plugin
# This package has no prepare/build step, so no pnpm build permission is needed.

For headless/agent-only use, install into a headless profile the same way.

Install from local checkout

git clone https://github.com/king-bcolor/dsh-ncm-plugin.git
cd dsh-ncm-plugin
dsh plugin --profile web add .

Usage

Start the browser UI:

dsh web

The first tool call downloads ncm automatically; you can also open Settings → NetEase Cloud Music and click Install/update ncm, then Log in to NetEase Cloud Music. Open Settings → NetEase Cloud Music. The panel exposes every ncm tool as a form: account status, playlist browse/manage, tidy, search, song/lyric/URL, recommendations, and records. Results are shown as readable text with a raw JSON toggle.

You can still ask the agent in the same web session:

# example prompts
Use ncm_me to check my NetEase Cloud Music login.
Search NetEase Cloud Music for the song "晴天" and show the first 5 results.

Configuration

# profile cordis.patch.yml or plugin row config
- id: ncm
  name: dsh-ncm-plugin
  config:
    ncmBin: ncm
    ncmInstallDir: $DSH_HOME/bin
    configDir: $DSH_HOME/ncm-config
    autoInstall: true
    ncmDownloadBaseUrl: https://ghfast.top/https://github.com/Davied-H/ncm-cli/releases/latest/download
    playwrightDownloadHost: https://npmmirror.com/mirrors/playwright
    timeoutMs: 30000
    confirmWrites: true

Development

TDD is mandatory for this project. The workspace is plain ESM JavaScript with node:test; there is no build step:

npm test          # red first, then implement until green

Local checkout quick start (no system ncm required):

./setup.sh
./start.sh

This creates a writable .dsh-home, bootstraps ncm into .dsh-home/bin, installs the plugin into the web profile, and starts the UI.

License

MIT