# Readme Reference

> Use when making code, workflow, testing, deployment, or documentation changes in this repository and you need targeted project-specific facts from README files before editing. Read only the relevant section, verify it against code, and repair stale documentation when the task includes documentation.

- Skill: `chthollyphile/readme-reference` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chthollyphile/readme-reference`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chthollyphile/readme-reference/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: chthollyphile (https://skillmd.com/u/chthollyphile)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chthollyphile/readme-reference

---


# README Reference

README 是导航线索，不是代码真相。先按任务读取相关小片段，再用 tracked paths、imports、package scripts 和实现文件确认；发现旧路径时顺手修正文档或明确标记它。

## Source selection

- 产品能力、脚本、Electron、Vercel、API：`README.md`（根 README 只读，不在本任务中修改）。
- `src/` 入口、模块职责、app-level 装配：`src/README.md`。
- visualizer 共享入口、模式、背景、性能约定：`src/components/visualizer/README.md`。
- Partita layout、sticky punctuation、预热和缓存：`src/components/visualizer/partita/README.md`。
- 在线歌曲 Omni/provider 边界：`src/services/onlineMusic/README.md` + `src/services/onlineMusic/omni.ts`。
- 同步 API、Node/Cloudflare/Docker 部署：`sync-server/README.md`。
- Docker Web stack、端口、环境变量和 smoke test：`deploy/docker/README.md`。
- Linux 便携包和 Electron 图形模式：`packaging/linux/README-LINUX.txt` + `electron/main.cjs`。
- Cappella 内置头像/表情资源：相邻 `cappella/avatar/README.md` 或 `emo/README.md`，只在涉及这些资源时读取。
- `test/manual/**/README.md` 属于测试/联调文档；按“排除测试文件”的任务要求不要把它们当作生产架构依据。

## Targeted reading

先用 `rg -n` 搜标题、脚本名、当前符号或路径，再打开命中位置附近 20-80 行。不要为了保险全文读取长 README。

```powershell
rg -n "components/app|services/|visualizer|scripts|部署|Node|Docker" src/README.md README.md
rg -n "VisualizerRenderer|registry|pendolo|sonnet|background" src/components/visualizer/README.md
rg -n "Omni|provider|lyrics|playback|catalog" src/services/onlineMusic/README.md
rg -n "Node|/health|/settings|/themes|compose" sync-server/README.md deploy/docker/README.md
```

## Verification protocol

1. 文档给出路径时，用 `git ls-files -- <path>` 验证路径存在。
2. 文档给出脚本时，核对根 `package.json`、领域 `package.json` 和 `vite.config.*` / `wrangler.*`。
3. 文档给出入口时，先看该文件的 imports 和 export，再沿一层调用关系，不要直接扫描整个目录。
4. 文档给出 API 时，核对 `sync-server/src/app.ts`、`worker/index.ts`、`api/` 或对应 bridge。
5. 文档给出 provider 能力时，先看 `src/services/onlineMusic/omni.ts` 和 `src/types/onlineMusic.ts`，再看 adapter/transport。
6. 代码与 README 冲突时，以代码为准，并在本次文档改动中更新对应说明。

## Repository-specific traps

- 当前 app-level 目录是 `src/components/app/*`，旧的 `components/app/views/*`、`SearchResultsOverlay`、`src/components/LocalMusicView.tsx`、`src/components/local/*` 和 `src/components/navidrome/*` 不应作为新入口。
- Visualizer 模式由 `src/components/visualizer/registry.tsx` 从各模式 `entry.tsx` 发现；当前不能只按旧文档中的 classic/cadenza/partita 列表理解。
- 在线歌曲普通调用必须经过 `src/services/onlineMusic/omni.ts`；Navidrome 是独立 `src/services/navidromeService.ts`，不能仅凭“在线”一词混为一谈。
- `src/App.tsx` 是历史大型编排文件；README 只提供入口关系，不代表新逻辑应继续写入其中。
- Sync Server 的 Node engine 当前以 `sync-server/package.json` 和根 `package.json` 为准，不要复制旧的 Node 18 说明。

## Editing rules

- 只更新与当前代码/部署状态有关的段落；保持 README 可搜索、短路径明确。
- 不要把完整源代码或大段接口响应复制进 README；给出第一入口和下一层即可。
- 保留所有 `@note` 注释原文，不翻译、不缩短、不删除。
- 文档任务的验证重点是路径、符号、命令、端口和配置值；不要为了 README 改动误跑完整构建。