dsh-ncm-plugin

Readme

# dsh-ncm-plugin

> **中文文档**：[README.zh-CN.md](./README.zh-CN.md)

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that wraps the [ncm-cli](https://github.com/Davied-H/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](./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:
```bash
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
```bash
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:
```bash
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:
```bash
# 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
```yaml
# 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:
```bash
npm test          # red first, then implement until green
```

Local checkout quick start (no system ncm required):
```bash
./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