Skip to content

Set up Cursor Cloud dev environment (AGENTS.md) #984

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
darknessomi merged 1 commit into from
Jul 10, 2026
Merged

Set up Cursor Cloud dev environment (AGENTS.md) #984

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# AGENTS.md

## Cursor Cloud specific instructions

NetEase-MusicBox is a Python 3.10+ command-line/curses TUI music player, managed with
[`uv`](https://docs.astral.sh/uv/). There is a single package (`NEMbox`) and one product
(the `musicbox` CLI/TUI). Dependencies are refreshed automatically by the startup update
script (`uv sync --frozen`); you do not need to reinstall them.

### Running the app
- Interactive TUI: `uv run musicbox` — this uses `curses` and requires a real interactive
terminal (TTY). It will not render in a non-TTY/headless shell; use the CLI subcommands
below for scripted/agent verification instead.
- Agent/CLI mode (no TTY needed): `uv run musicbox <command>`, e.g.
`search`, `song url`, `play`, `pause`, `status`, `queue`, `daemon`, `auth`.
Add `--json` for machine-readable output. See `README.md` for the full command list.
- Playback runs through a background daemon; `musicbox play --id <id>` auto-starts it and
`musicbox daemon stop` stops it.

### Audio backends (system deps, NOT in update script)
- `mpg123` (MP3) and `mpv` (FLAC / Hi-Res) are OS packages installed via `apt-get`
(`sudo apt-get install -y mpg123 mpv`). They are pre-installed in the snapshot; reinstall
only if `musicbox play` reports a missing backend. Playback selects `mpg123` by default.

### Network / API note
- Song search and playable URLs come from NetEase's public API, which only accepts
China-region access. From other regions requests can fail or return empty; set an HTTP
proxy (see README "配置") if search stops returning results. In this environment the API
was reachable and returned live results.
- Login is QR-code scan only (renders a QR block in the terminal); there is no
username/password login and no test-login secret is required for search/playback.

### Lint / test / build
Standard commands (already documented in `.cursor/rules/pre-commit-validation.mdc` and
`.github/workflows/ci.yml`); run them via `uv run`:
- `uv run ruff check`
- `uv run ruff format --check`
- `uv run ty check` — emits ~11 diagnostics that are configured as `warn` in
`pyproject.toml`; it exits 0 and is not a failure.
- `uv run pytest -q --tb=short`
- `uv build`
Loading