tunetidy 1.0.0__tar.gz

tunetidy-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: release
+
+# 推送 v* 标签时构建并发布到 PyPI。用 PyPI 可信发布（trusted publishing），仓库里不存任何 token；
+# 需要先在 PyPI 的项目设置里把本仓库的这个工作流、环境 pypi 登记为可信发布者。
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - name: 标签必须与版本号一致
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "标签 $GITHUB_REF_NAME 与版本 $version 不一致"; exit 1; }
+      - run: uv sync
+      - run: uv run pytest
+      - run: cd web && npm ci && npm run build
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tunetidy-1.0.0/.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.3
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: uv sync
+      - run: uv run ruff format --check . && uv run ruff check .
+      - run: uv run mypy src
+      # 默认不跑 live（真实接口）测试；钥匙串由 tests/conftest.py 强制换成假实现
+      - run: >-
+          uv run pytest --cov=tunetidy.classify --cov=tunetidy.apply --cov=tunetidy.storage
+          --cov-fail-under=80
+      - name: 构建前端和安装包，检查网页文件打进了包里
+        run: |
+          cd web && npm ci && npm run build && cd ..
+          uv build
+          python -c "import sys, zipfile, glob; names = zipfile.ZipFile(glob.glob('dist/*.whl')[0]).namelist(); sys.exit(0 if 'tunetidy/server/static/index.html' in names else 'wheel 里没有前端构建产物')"

tunetidy-1.0.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# 登录态与凭据：绝不提交
+*.cookie
+*cookie*.json
+storage-state*
+.env
+.env.*
+
+# 原始接口录制（未脱敏，绝不提交）
+.spike-data/
+.tunetidy-spike/
+*.qr.png
+
+# Node
+node_modules/
+
+# OS
+.DS_Store
+
+# 前端构建产物：发布时构建后打进安装包，不提交
+src/tunetidy/server/static/
+
+# 本地数据库（含个人歌单数据）：绝不提交
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3
+
+# Claude Code 本机设置
+.claude/settings.local.json

tunetidy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xhhhz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tunetidy-1.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: tunetidy
+Version: 1.0.0
+Summary: 理音：把网易云歌单按曲风拆成多个新歌单，本地生成整理结果，人工确认后再写回（非官方项目）。
+Project-URL: Homepage, https://github.com/xhhhz/tunetidy
+Project-URL: Issues, https://github.com/xhhhz/tunetidy/issues
+Author: xhhhz
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography
+Requires-Dist: fastapi
+Requires-Dist: httpx
+Requires-Dist: keyring
+Requires-Dist: mcp<3,>=2
+Requires-Dist: platformdirs
+Requires-Dist: qrcode
+Requires-Dist: rich
+Requires-Dist: typer
+Requires-Dist: uvicorn
+Description-Content-Type: text/markdown
+
+# 理音 TuneTidy
+
+中文 | [English](README.en.md)
+
+把网易云歌单按曲风拆成几个新歌单：先在本地生成整理结果，你看过、调整过、亲自确认后，才在账号里新建歌单。
+
+> **非官方项目**，与网易云音乐及其运营方无关，也未获其授权。只读写你自己账号里的歌单信息，不下载音频。详见文末[免责声明](#免责声明)。
+
+<!-- 演示动图：docs/demo.gif（由作者录制） -->
+
+## 30 秒上手
+
+```bash
+pipx install tunetidy
+tunetidy login                      # 用网易云 App 扫码登录，登录态存进系统钥匙串
+tunetidy playlists                  # 看看有哪些歌单
+tunetidy analyze "我喜欢的音乐"       # 读取曲风、生成整理（不改账号；首次约每首 1.5 秒，之后有缓存）
+tunetidy ui                         # 在网页里看结果、换拆法、改歌单名、把分错的歌挪走
+tunetidy approve <整理id>            # 你本人在终端确认（要输入屏幕上显示的确认码）
+tunetidy apply <整理id>              # 新建私密歌单并加歌；中断后再运行即续传
+```
+
+不满意可以撤销：`tunetidy undo <整理id或运行id>`。撤销前会先回读歌单，只删理音新建、你没改过的歌单；你改过的只移除理音加进去的歌。
+
+## 拆法
+
+默认按大类（一级曲风）拆。`analyze` 可以换拆法，标签已缓存时几秒出结果；在网页里也能随时切换：
+
+```bash
+tunetidy analyze "我喜欢的音乐" --only 流行               # 只分出流行，其余放进「其他」
+tunetidy analyze "我喜欢的音乐" --only 流行 --match any   # 带流行标签的都算
+tunetidy analyze "我喜欢的音乐" --level 2                 # 按细类（二级曲风）
+tunetidy analyze "我喜欢的音乐" --top 5                   # 最多建 5 个歌单（不算「其他」）
+tunetidy analyze "我喜欢的音乐" --groups my.toml --no-other  # 自己定怎么分，不建「其他」
+```
+
+自定义分组的写法见 [taxonomies/examples/](taxonomies/examples/)。网页里"自己定怎么分"可以导入、导出同样格式的文件。
+
+## 网页
+
+`tunetidy ui` 在浏览器里打开理音（只监听本机）。首页每个歌单一张卡片；点进去能看到将要新建哪几个歌单、各多少首，可以切换拆法、给歌单改名、把分错的歌移到别的歌单，再把"没分好"的歌一首首选好去处。这些都只改本地的整理结果，不访问网易云。确认和建歌单在终端里完成，网页的确认页会给出要运行的命令。
+
+## 在 Claude Code、Codex 里用（MCP）
+
+理音自带 MCP 服务，AI 助手可以帮你列歌单、生成整理、查看明细，并在你确认后建歌单：
+
+```bash
+claude mcp add tunetidy -- tunetidy mcp     # Claude Code
+```
+
+Codex 在 `~/.codex/config.toml` 里加：
+
+```toml
+[mcp_servers.tunetidy]
+command = "tunetidy"
+args = ["mcp"]
+```
+
+五个工具：`list_playlists`、`create_plan`、`get_job_status`、`get_plan_items`、`apply_plan`。分析和建歌单都在后台运行，工具立即返回任务 id，再用 `get_job_status` 查进度。**MCP 里没有确认工具**：确认只能由你本人在终端运行 `tunetidy approve`，`apply_plan` 只接受你确认过、之后内容没变的整理。
+
+## 效果
+
+作者自己的"我喜欢的音乐"（1033 首，2026-10-31），默认拆法（按大类）：
+
+| | 歌曲数 | 没分好 |
+| --- | --- | --- |
+| 全部 | 1033 | 2.7% |
+| 网易云给了曲风标签的 | 1026（99.3%） | 2.1% |
+| 没有曲风标签的 | 7 | 85.7% |
+
+"没分好"的歌不会放进新歌单，可以在网页里一首首选好去处。人工改动比例要等更多人用过才有意义，暂不列出。这些数字只来自一个歌单，你的歌单可能不同；用 `uv run python scripts/evaluate.py <整理id>` 可以算自己的。
+
+## 安全约定
+
+- 只新建歌单，绝不修改或删除你原有的歌单。新歌单默认私密。
+- `approve`、`apply`（包括 `--yes`）、`undo` 只能在交互式终端里由你本人完成。如果你使用 Claude Code、Codex 等 AI 助手，请不要在它们的权限设置里自动放行这几个命令。
+- 整理在确认后有任何改动，确认即作废；已建好的整理不能再建第二次。
+- 访问网易云带随机间隔限速，限速只读配置文件，任何命令或 MCP 工具都没有提速参数。默认直连，不使用系统代理。
+- 登录凭据存在系统钥匙串里；日志和报错信息里不打印凭据。网页服务只监听 127.0.0.1，并校验随机口令。
+
+## 常见问题
+
+**第一次分析为什么这么慢？** 网易云的曲风标签要逐首读取，为了不被限制，理音会放慢速度，1000 首约 25 分钟。读过的标签会缓存，之后换拆法、重新分析都只要几秒。
+
+**"没分好"是什么？** 网易云没给这首歌标曲风，或者几个曲风一样多、分不出主次。不处理的话它们不会放进新歌单；可以在网页的"没分好的歌"里一首首选好去处。
+
+**AI 助手能替我确认吗？** 不能。确认要在终端输入屏幕上显示的确认码，MCP 里也没有确认工具。助手只能执行你已经确认过的整理。
+
+**怎么撤销？** 在终端运行 `tunetidy undo <整理id或运行id>`。
+
+## 免责声明
+
+- 本项目是个人开源项目，与网易云音乐及其运营方没有任何关系。
+- 理音通过网易云网页版使用的非公开接口访问你的账号。这些接口随时可能变化或失效，使用它们可能违反平台的服务条款，账号因此受到限制的风险由使用者自行承担。
+- 理音只读写你自己账号里的歌单信息（歌单名、简介、歌曲列表），不下载、不分发任何音频。
+- 软件按"现状"提供，不提供任何担保，详见 [LICENSE](LICENSE)。
+
+## 开发
+
+这一节写给想改理音代码的人，只是使用的话不用看。
+
+从源码使用时，命令要通过 `uv run` 运行（如 `uv run tunetidy playlists`），或者先用 `uv tool install --editable .` 把源码装成全局命令。
+
+```bash
+uv sync
+uv run ruff format . && uv run ruff check .
+uv run mypy src
+uv run pytest                               # 离线测试，不访问网络，钥匙串用测试专用的假实现
+uv run pytest -m live                       # 只读的真实接口测试，需要先登录
+```
+
+前端在 `web/`（React + TypeScript + Vite + Tailwind），构建产物不提交。从源码运行 `tunetidy ui` 前先构建一次：
+
+```bash
+cd web && npm ci && npm run build            # 输出到 src/tunetidy/server/static/
+```
+
+改前端时可以用 `npm run dev`（另开终端运行 `uv run tunetidy ui --no-browser`，再用它打印的口令打开 `http://localhost:5173/#token=...`）。代码结构和关键设计见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

tunetidy-1.0.0/README.en.md

@@ -0,0 +1,122 @@
+# TuneTidy (理音)
+
+[中文](README.md) | English
+
+Split a NetEase Cloud Music playlist into several new playlists by genre. TuneTidy builds the result locally first; new playlists are created in your account only after you have reviewed it, adjusted it and confirmed it yourself.
+
+> **Unofficial project.** Not affiliated with, endorsed by or authorized by NetEase Cloud Music or its operator. TuneTidy only reads and writes playlist information in your own account and never downloads audio. See the [disclaimer](#disclaimer).
+
+<!-- Demo GIF: docs/demo.gif (recorded by the author) -->
+
+## Quick start
+
+```bash
+pipx install tunetidy
+tunetidy login                      # scan a QR code with the NetEase Cloud Music app; the session goes to the system keychain
+tunetidy playlists                  # list your playlists
+tunetidy analyze "我喜欢的音乐"       # read genres and build a plan (no account changes; first run about 1.5 s per song, cached afterwards)
+tunetidy ui                         # review in the browser: switch split modes, rename playlists, move misplaced songs
+tunetidy approve <plan-id>          # confirm in the terminal yourself (type the code shown on screen)
+tunetidy apply <plan-id>            # create private playlists and add songs; rerun to resume after an interruption
+```
+
+`我喜欢的音乐` ("My liked music") is the name NetEase gives to your liked-songs playlist; pass any playlist name or id.
+
+To undo: `tunetidy undo <plan-id or run-id>`. Before undoing, TuneTidy reads the playlists back: it deletes only the playlists it created that you haven't changed; from playlists you have changed it removes only the songs it added.
+
+## Split modes
+
+By default songs are split by top-level genre. `analyze` takes other split modes (seconds once tags are cached), and the web page can switch them at any time:
+
+```bash
+tunetidy analyze "我喜欢的音乐" --only 流行               # split out pop only; everything else goes to 其他 (Other)
+tunetidy analyze "我喜欢的音乐" --only 流行 --match any   # count every song that carries a pop tag
+tunetidy analyze "我喜欢的音乐" --level 2                 # split by second-level genre
+tunetidy analyze "我喜欢的音乐" --top 5                   # at most 5 playlists (not counting Other)
+tunetidy analyze "我喜欢的音乐" --groups my.toml --no-other  # your own groups, no Other playlist
+```
+
+Genre names are NetEase's Chinese genre names. For custom groups, see [taxonomies/examples/](taxonomies/examples/); the web page can import and export the same TOML format.
+
+## Web page
+
+`tunetidy ui` opens TuneTidy in your browser (listening on localhost only). The home page has one card per playlist. Open one to see which new playlists will be created and how many songs each gets. There you can switch split modes, rename playlists, move misplaced songs, and pick a home for each song TuneTidy couldn't sort. All of this changes only the local plan and never contacts NetEase. Confirming and creating playlists happen in the terminal; the confirm page shows the commands to run.
+
+The interface is in Chinese.
+
+## Use it from Claude Code or Codex (MCP)
+
+TuneTidy ships an MCP server, so an AI assistant can list playlists, build a plan, browse it, and create the playlists once you have confirmed:
+
+```bash
+claude mcp add tunetidy -- tunetidy mcp     # Claude Code
+```
+
+For Codex, add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.tunetidy]
+command = "tunetidy"
+args = ["mcp"]
+```
+
+Five tools: `list_playlists`, `create_plan`, `get_job_status`, `get_plan_items`, `apply_plan`. Analysis and playlist creation run in the background: the tools return a job id at once, and `get_job_status` reports progress. **There is no confirmation tool.** Only you can confirm, by running `tunetidy approve` in a terminal, and `apply_plan` accepts only plans you have confirmed and that haven't changed since.
+
+## Results
+
+The author's own liked-songs playlist (1033 songs, 2026-10-31), default split (top-level genre):
+
+| | Songs | Unsorted |
+| --- | --- | --- |
+| All | 1033 | 2.7% |
+| Tagged with a genre by NetEase | 1026 (99.3%) | 2.1% |
+| No genre tag | 7 | 85.7% |
+
+Unsorted songs are left out of the new playlists until you place them in the web page. The share of manual changes will mean something only once more people have used TuneTidy, so it isn't listed yet. These numbers come from a single playlist and yours may differ; run `uv run python scripts/evaluate.py <plan-id>` to compute your own.
+
+## Safety rules
+
+- TuneTidy only creates playlists. It never changes or deletes playlists you already have. New playlists are private by default.
+- `approve`, `apply` (including `--yes`) and `undo` work only in an interactive terminal, run by you. If you use an AI assistant such as Claude Code or Codex, don't auto-allow these commands in its permission settings.
+- Any change to a plan after you confirm it voids the confirmation. A plan that has been applied can't be applied a second time.
+- Requests to NetEase are rate-limited with random pauses. The limits come from the config file only; no command or MCP tool can speed them up. Connections go direct, without the system proxy.
+- Login credentials live in the system keychain and are never printed in logs or error messages. The web server listens on 127.0.0.1 only and checks a random token.
+
+## FAQ
+
+**Why is the first analysis so slow?** Genre tags have to be fetched one song at a time, and TuneTidy goes slowly to avoid being rate-limited: about 25 minutes for 1000 songs. Tags are cached, so switching split modes or analyzing again takes seconds.
+
+**What does "unsorted" (没分好) mean?** NetEase gave the song no genre, or several genres tie and TuneTidy can't tell which comes first. Unsorted songs are left out of the new playlists unless you place them on the web page's unsorted-songs view.
+
+**Can an AI assistant confirm for me?** No. Confirming means typing the code shown in your terminal, and the MCP server has no confirmation tool. An assistant can only apply plans you have already confirmed.
+
+**How do I undo?** Run `tunetidy undo <plan-id or run-id>` in a terminal.
+
+## Disclaimer
+
+- This is a personal open-source project with no connection to NetEase Cloud Music or its operator.
+- TuneTidy reaches your account through the non-public interfaces used by the NetEase Cloud Music website. They may change or stop working at any time, and using them may breach the platform's terms of service. Any restriction placed on your account as a result is your own risk.
+- TuneTidy only reads and writes playlist information in your own account (names, descriptions, song lists). It does not download or distribute any audio.
+- The software is provided "as is", without warranty of any kind; see [LICENSE](LICENSE).
+
+## Development
+
+This section is for people who want to work on TuneTidy's code; you don't need it to use the tool.
+
+From a source checkout, run commands through `uv run` (for example `uv run tunetidy playlists`), or install the checkout as a command once with `uv tool install --editable .`.
+
+```bash
+uv sync
+uv run ruff format . && uv run ruff check .
+uv run mypy src
+uv run pytest                               # offline tests: no network, a fake keychain
+uv run pytest -m live                       # read-only tests against the real service; log in first
+```
+
+The front end lives in `web/` (React, TypeScript, Vite, Tailwind). Its build output isn't committed, so build it once before running `tunetidy ui` from source:
+
+```bash
+cd web && npm ci && npm run build            # writes to src/tunetidy/server/static/
+```
+
+While working on the front end, use `npm run dev`: in another terminal run `uv run tunetidy ui --no-browser`, then open `http://localhost:5173/#token=...` with the token it prints. For the code layout and key design decisions, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) (in Chinese).

tunetidy-1.0.0/README.md

@@ -0,0 +1,118 @@
+# 理音 TuneTidy
+
+中文 | [English](README.en.md)
+
+把网易云歌单按曲风拆成几个新歌单：先在本地生成整理结果，你看过、调整过、亲自确认后，才在账号里新建歌单。
+
+> **非官方项目**，与网易云音乐及其运营方无关，也未获其授权。只读写你自己账号里的歌单信息，不下载音频。详见文末[免责声明](#免责声明)。
+
+<!-- 演示动图：docs/demo.gif（由作者录制） -->
+
+## 30 秒上手
+
+```bash
+pipx install tunetidy
+tunetidy login                      # 用网易云 App 扫码登录，登录态存进系统钥匙串
+tunetidy playlists                  # 看看有哪些歌单
+tunetidy analyze "我喜欢的音乐"       # 读取曲风、生成整理（不改账号；首次约每首 1.5 秒，之后有缓存）
+tunetidy ui                         # 在网页里看结果、换拆法、改歌单名、把分错的歌挪走
+tunetidy approve <整理id>            # 你本人在终端确认（要输入屏幕上显示的确认码）
+tunetidy apply <整理id>              # 新建私密歌单并加歌；中断后再运行即续传
+```
+
+不满意可以撤销：`tunetidy undo <整理id或运行id>`。撤销前会先回读歌单，只删理音新建、你没改过的歌单；你改过的只移除理音加进去的歌。
+
+## 拆法
+
+默认按大类（一级曲风）拆。`analyze` 可以换拆法，标签已缓存时几秒出结果；在网页里也能随时切换：
+
+```bash
+tunetidy analyze "我喜欢的音乐" --only 流行               # 只分出流行，其余放进「其他」
+tunetidy analyze "我喜欢的音乐" --only 流行 --match any   # 带流行标签的都算
+tunetidy analyze "我喜欢的音乐" --level 2                 # 按细类（二级曲风）
+tunetidy analyze "我喜欢的音乐" --top 5                   # 最多建 5 个歌单（不算「其他」）
+tunetidy analyze "我喜欢的音乐" --groups my.toml --no-other  # 自己定怎么分，不建「其他」
+```
+
+自定义分组的写法见 [taxonomies/examples/](taxonomies/examples/)。网页里"自己定怎么分"可以导入、导出同样格式的文件。
+
+## 网页
+
+`tunetidy ui` 在浏览器里打开理音（只监听本机）。首页每个歌单一张卡片；点进去能看到将要新建哪几个歌单、各多少首，可以切换拆法、给歌单改名、把分错的歌移到别的歌单，再把"没分好"的歌一首首选好去处。这些都只改本地的整理结果，不访问网易云。确认和建歌单在终端里完成，网页的确认页会给出要运行的命令。
+
+## 在 Claude Code、Codex 里用（MCP）
+
+理音自带 MCP 服务，AI 助手可以帮你列歌单、生成整理、查看明细，并在你确认后建歌单：
+
+```bash
+claude mcp add tunetidy -- tunetidy mcp     # Claude Code
+```
+
+Codex 在 `~/.codex/config.toml` 里加：
+
+```toml
+[mcp_servers.tunetidy]
+command = "tunetidy"
+args = ["mcp"]
+```
+
+五个工具：`list_playlists`、`create_plan`、`get_job_status`、`get_plan_items`、`apply_plan`。分析和建歌单都在后台运行，工具立即返回任务 id，再用 `get_job_status` 查进度。**MCP 里没有确认工具**：确认只能由你本人在终端运行 `tunetidy approve`，`apply_plan` 只接受你确认过、之后内容没变的整理。
+
+## 效果
+
+作者自己的"我喜欢的音乐"（1033 首，2026-10-31），默认拆法（按大类）：
+
+| | 歌曲数 | 没分好 |
+| --- | --- | --- |
+| 全部 | 1033 | 2.7% |
+| 网易云给了曲风标签的 | 1026（99.3%） | 2.1% |
+| 没有曲风标签的 | 7 | 85.7% |
+
+"没分好"的歌不会放进新歌单，可以在网页里一首首选好去处。人工改动比例要等更多人用过才有意义，暂不列出。这些数字只来自一个歌单，你的歌单可能不同；用 `uv run python scripts/evaluate.py <整理id>` 可以算自己的。
+
+## 安全约定
+
+- 只新建歌单，绝不修改或删除你原有的歌单。新歌单默认私密。
+- `approve`、`apply`（包括 `--yes`）、`undo` 只能在交互式终端里由你本人完成。如果你使用 Claude Code、Codex 等 AI 助手，请不要在它们的权限设置里自动放行这几个命令。
+- 整理在确认后有任何改动，确认即作废；已建好的整理不能再建第二次。
+- 访问网易云带随机间隔限速，限速只读配置文件，任何命令或 MCP 工具都没有提速参数。默认直连，不使用系统代理。
+- 登录凭据存在系统钥匙串里；日志和报错信息里不打印凭据。网页服务只监听 127.0.0.1，并校验随机口令。
+
+## 常见问题
+
+**第一次分析为什么这么慢？** 网易云的曲风标签要逐首读取，为了不被限制，理音会放慢速度，1000 首约 25 分钟。读过的标签会缓存，之后换拆法、重新分析都只要几秒。
+
+**"没分好"是什么？** 网易云没给这首歌标曲风，或者几个曲风一样多、分不出主次。不处理的话它们不会放进新歌单；可以在网页的"没分好的歌"里一首首选好去处。
+
+**AI 助手能替我确认吗？** 不能。确认要在终端输入屏幕上显示的确认码，MCP 里也没有确认工具。助手只能执行你已经确认过的整理。
+
+**怎么撤销？** 在终端运行 `tunetidy undo <整理id或运行id>`。
+
+## 免责声明
+
+- 本项目是个人开源项目，与网易云音乐及其运营方没有任何关系。
+- 理音通过网易云网页版使用的非公开接口访问你的账号。这些接口随时可能变化或失效，使用它们可能违反平台的服务条款，账号因此受到限制的风险由使用者自行承担。
+- 理音只读写你自己账号里的歌单信息（歌单名、简介、歌曲列表），不下载、不分发任何音频。
+- 软件按"现状"提供，不提供任何担保，详见 [LICENSE](LICENSE)。
+
+## 开发
+
+这一节写给想改理音代码的人，只是使用的话不用看。
+
+从源码使用时，命令要通过 `uv run` 运行（如 `uv run tunetidy playlists`），或者先用 `uv tool install --editable .` 把源码装成全局命令。
+
+```bash
+uv sync
+uv run ruff format . && uv run ruff check .
+uv run mypy src
+uv run pytest                               # 离线测试，不访问网络，钥匙串用测试专用的假实现
+uv run pytest -m live                       # 只读的真实接口测试，需要先登录
+```
+
+前端在 `web/`（React + TypeScript + Vite + Tailwind），构建产物不提交。从源码运行 `tunetidy ui` 前先构建一次：
+
+```bash
+cd web && npm ci && npm run build            # 输出到 src/tunetidy/server/static/
+```
+
+改前端时可以用 `npm run dev`（另开终端运行 `uv run tunetidy ui --no-browser`，再用它打印的口令打开 `http://localhost:5173/#token=...`）。代码结构和关键设计见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。

tunetidy-1.0.0/docs/ARCHITECTURE.md

@@ -0,0 +1,109 @@
+# 理音 TuneTidy · 架构说明
+
+写给想读懂或修改理音代码的人。使用方法见 [README](../README.md)。
+
+## 整体流程
+
+```
+读取歌单与曲风标签 ──► 分类 ──► 整理方案（本地） ──► 人工确认 ──► 写回账号 ──► 可撤销
+   analyze.py          classify/     plan.py            apply/approval   apply/writer   apply/undo
+```
+
+1. **读取**：通过后端接口拉取来源歌单的歌曲和每首歌的官方曲风标签。标签逐首写进本地数据库，中断后再运行会接着取，并按配置缓存一段时间。
+2. **分类**：只用本地数据完成，不访问网络。同一份输入一定得到同一份结果。
+3. **整理方案**：分类结果、将要新建的歌单、以及当时用到的全部输入（信号快照）一起存进数据库。之后切换拆法、移动歌曲、改歌单名，都基于这份快照重新计算，不再访问网络。
+4. **确认**：只能由人在交互式终端里输入确认码完成。确认时记下方案内容的哈希。
+5. **写回**：执行前重新核对哈希；先把"要建哪些歌单、各加哪些歌"写进数据库，再逐步执行，中断后可以续传。
+6. **撤销**：先回读歌单现状、和写入记录对比，再决定整删还是只移除理音加入的歌。
+
+命令行、网页和 MCP 服务是同一套核心库的三个入口。
+
+## 目录
+
+| 位置 | 作用 |
+| --- | --- |
+| `src/tunetidy/models.py` | 平台无关的数据类型（歌曲、歌单、标签等），歌曲主键一律是 `(platform, id)` |
+| `src/tunetidy/backends/` | 访问音乐平台的唯一位置。`base.py` 定义 `MusicBackend` 接口，`web/` 是网易云扫码登录后端 |
+| `src/tunetidy/signals/` | 把平台数据转成分类用的信号（目前是官方曲风标签） |
+| `src/tunetidy/classify/` | 曲风树、多标签规则、打分、拆分方式、小类合并 |
+| `src/tunetidy/analyze.py` | 串起读取、分类、生成方案；按快照重新分类、移动歌曲、改歌单名 |
+| `src/tunetidy/plan.py` | 方案、将要新建的歌单、内容哈希 |
+| `src/tunetidy/apply/` | 确认、写回、续传、撤销 |
+| `src/tunetidy/storage/` | SQLite 读写（WAL 模式）、表结构迁移 |
+| `src/tunetidy/jobs.py` | 后台任务（分析、写回），供 MCP 使用 |
+| `src/tunetidy/server/` | 本地网页服务（FastAPI）和接口 |
+| `src/tunetidy/mcp/` | MCP 服务：五个工具的逻辑和注册 |
+| `src/tunetidy/cli.py` | 命令行入口（Typer + Rich） |
+| `web/` | 网页前端（React + TypeScript + Vite + Tailwind），构建产物打进 Python 包 |
+| `taxonomies/` | 网易云曲风树快照与自定义分组示例 |
+| `scripts/` | 评估脚本、本地 pre-commit 钩子 |
+
+## 关键设计
+
+### 平台隔离
+
+上层模块只依赖 `MusicBackend` 接口，不直接发请求。后端按名字注册，用到时才导入，所以删掉 `backends/web/` 整个目录，其他模块仍能编译、测试仍能运行。以后接入其他平台，只需新增一个后端。
+
+### 确定性分类
+
+1. 每首歌的官方标签先按曲风树归到大类，再去掉用途类标签（原声带、二次元、儿童）和泛化标签（流行），前提是还剩别的曲风。
+2. 剩下的曲风按当前拆法映射到分类：按大类、按细类、只分一类、自定义分组。
+3. 只对应一个分类就放进去；对应多个分类、分不出主次，或者没有标签，就标为"没分好"，不写入。
+4. 再按设置把太小的分类并入「其他」、只保留最大的 N 类，或者不建「其他」。
+
+结果与歌曲顺序无关，同一份快照必然得到同一份方案。人工调整（移动歌曲）单独标记，重新分类时保留。
+
+### 方案状态与确认
+
+状态依次为：草稿 → 已确认 → 正在创建 → 已建好 → 已撤销。
+
+- 内容哈希只覆盖"会对账号做什么"：来源、每个新歌单的名称和歌曲顺序、不写入的歌。确认后内容有任何变化，确认自动作废，方案回到草稿。
+- `approve`，以及命令行里的 `apply`（不论带不带 `--yes`），都只在交互式终端下工作，并要求输入随机确认码。
+- 非交互地执行已确认的方案，只有 MCP 的 `apply_plan` 一条路径；它同样核对状态和哈希，没有确认工具。
+- 已建好的方案不能再执行一次。
+
+### 写回与撤销
+
+- 写回前先在 `runs`、`run_playlists`、`run_tracks` 三张表里记下意图，再建歌单、分批加歌。每个新歌单的简介里写入运行标记。
+- 中断后续传：按记录跳过已完成的部分，按运行标记找回已建的歌单，不会建出第二个。
+- 只新建歌单，从不修改或删除用户原有的歌单。
+- 撤销前回读歌单现状：和写入记录完全一致才整删；用户改过（或找不到运行标记）的，只移除理音加入的歌。
+
+### 存储与并发
+
+SQLite 开启 WAL 模式；命令行、网页服务、MCP 服务可能同时打开同一个库。写操作都是短事务（`BEGIN IMMEDIATE`），表结构变化通过只追加的迁移完成。
+
+后台任务记在 `jobs` 表里：
+
+- 同一时间只允许一个在运行，检查和插入在同一个写事务里完成，跨进程也成立；
+- 运行中每 10 秒刷新心跳；
+- 任何入口启动时，把进程已不在或心跳超时的任务标为"已中断"。
+
+### 本地网页服务
+
+- 只监听 `127.0.0.1`；
+- 每次启动生成随机口令，放在网址的 `#token=` 里（不会发给服务器、不进日志）；
+- 每个接口请求都要带口令请求头，并校验 `Host` 和 `Origin`；
+- 写接口只接受 POST；
+- 网页只能查看和修改本地方案，不能确认、写回或撤销。
+
+### MCP 服务
+
+`tunetidy mcp` 以 stdio 启动，五个工具：`list_playlists`、`create_plan`、`get_job_status`、`get_plan_items`、`apply_plan`。
+
+- 分析和写回都只启动后台任务、立即返回任务 id。
+- 默认只返回摘要，明细分页。
+- 参数里没有限速、间隔、并发之类的设置。
+- stdout 只输出协议消息。
+
+### 凭据与隐私
+
+- 登录态优先存系统钥匙串，不可用时存仅本人可读的文件；日志和报错不打印凭据。
+- 访问平台时按配置限速，并带随机间隔。
+- `scripts/hooks/` 提供一个本地 pre-commit 钩子：从本机数据库和钥匙串读出自己的歌单 id、用户 id、昵称和 Cookie，暂存内容命中就拒绝提交。启用方法：`git config core.hooksPath scripts/hooks`。
+
+## 测试
+
+- `uv run pytest` 全部离线：平台响应来自 `tests/fixtures/` 里脱敏后的录制数据，后端用 `tests/fakes.py` 的假实现，钥匙串在测试里被强制换成内存实现。
+- 真实接口测试在 `tests/live/`，标记为 `live`，默认不运行。
+- 写回、续传、撤销、确认失效、后台任务中断等边界情况都有测试。