# Readme Reference

> Use when making code, workflow, testing, or documentation changes in this repository and you need targeted project-specific facts from README files before editing. Read only relevant snippets from root README.md or src/README.md; do not load whole README files unless the user explicitly asks for a full document review.

- Skill: `chthollyphile/readme-reference-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chthollyphile/readme-reference-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chthollyphile/readme-reference-2/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-22
- Page: https://skillmd.com/skills/chthollyphile/readme-reference-2

---


# README Reference

这个 skill 用于在修改前从仓库内 README 定位仍然有效的项目上下文，但必须控制读取范围，避免把长 README 整段灌入上下文。

## When To Use

以下情况优先使用：

- 修改前端架构、组件职责、服务层调用关系
- 修改测试策略、测试入口、运行命令
- 修改部署、开发、Electron、workflow 相关内容
- 修改文档、issue template、贡献说明
- 需要确认某个模块在项目中的定位，而不是只看当前文件猜测

## Primary Sources

优先在这些项目文档里定位片段：

- `README.md`
- `src/README.md`
- `sync-server/README.md`（仅当任务涉及同步服务端、Token、D1、Docker 或 Node 部署）

不要默认完整读取这些文件。除非用户明确要求全文审阅，否则每次只读取和当前任务直接相关的小片段。

## Read Budget

默认读取预算：

- 先用 `rg -n` 定位标题、关键词、脚本名、文件名或模块名。
- 每个 README 单次只打开 20-80 行相关片段。
- 同一任务通常不要从 README 读取超过 160 行。
- 如果片段不够，再追加下一个最相关片段，而不是整文件打开。

推荐命令模式：

```bash
rg -n "关键词|脚本名|模块名" README.md src/README.md
sed -n '起始行,结束行p' README.md
sed -n '起始行,结束行p' src/README.md
```

如果不确定关键词，先读目录或标题片段：

```bash
rg -n "^##|^###|components/visualizer|services/|utils/lyrics|部署|脚本" README.md src/README.md
```

## How To Read Them

### `README.md`

主要提取这些信息：

- 项目目标和支持的能力边界
- Web / Electron / Vercel / API 的运行方式
- 当前对外暴露的常用脚本
- 本地音乐、网易云、Navidrome 的产品层说明

适合回答这些问题：

- 这个功能在产品上应该怎么描述
- 这个改动会不会影响既有运行方式
- 某个脚本或部署流程是不是已经对外说明过

读取方式：

- 涉及脚本：先 `rg -n "npm run|常用脚本|部署与开发|build|test" README.md`
- 涉及产品能力：先 `rg -n "核心能力|本地音乐|Navidrome|网易云|AI|Stage API" README.md`
- 涉及 Electron / Vercel / API：先 `rg -n "Electron|Vercel|API|环境变量|部署" README.md`

### `src/README.md`

主要提取这些信息：

- 当前 `src/` 架构图
- 组件、hooks、services、utils 的职责边界
- 推荐阅读顺序
- 模块间依赖关系和真实分工

适合回答这些问题：

- 应该改哪个模块，而不是随便往 `App.tsx` 里塞逻辑
- 某段逻辑更适合放 service、hook、component 还是 util
- 某个现有模块是否已经承担类似职责

读取方式：

- 涉及模块归属：先 `rg -n "Module Boundaries|Where Changes Usually Belong|components/|hooks/|services/|utils/" src/README.md`
- 涉及 visualizer：先 `rg -n "visualizer|歌词可视化|components/visualizer" src/README.md`
- 涉及歌词解析：先 `rg -n "parserCore|lyrics|utils/lyrics|worker" src/README.md`
- 涉及 app-level 装配：先 `rg -n "components/app|App.tsx|PlayerPanel|Home" src/README.md`

### `sync-server/README.md`

主要提取这些信息：

- 当前支持的部署方式和安装脚本
- Token、端口、数据库路径和客户端连接方式
- 同步服务公开的 API 路径

涉及同步服务时，先用 README 了解面向用户的部署约定，再核对 `sync-server/package.json`、`sync-server/install.*`、`sync-server/src/app.ts` 和 `sync-server/src/node.ts`；不要只根据 README 推断后端行为。

## Editing Rule

如果 README 中的信息和代码现状明显不一致：

- 不要盲信 README
- 先以代码真实结构为准
- 在最终修改中顺手修正文档，或者明确指出 README 已经过时

### Strict Constraint: Protect Project Comments

- Keep all comments prefixed with `@note` exactly as they are. These comments mark critical annotations and must not be translated, shortened, modified, or removed.
- If refactoring significantly changes the code structure, preserve these comments as close as possible to the code they are logically associated with.

## Practical Workflow

1. 先判断任务是否涉及项目约定、架构边界或运行方式。
2. 如果涉及，先用 `rg -n` 在对应 README 中找关键词或标题；同步服务任务同时检查 `sync-server/README.md`。
3. 只打开命中的相关行附近片段。
4. 用 README 提供方向，用真实代码确认细节。
5. 如果 README 失真，明确指出并补文档，而不是默默忽略。

## Repository-Specific Heuristics

- 涉及前端主流程，优先看 `src/README.md` 对 `App.tsx`、`Home.tsx`、`services/*` 的职责描述。
- 如果 `src/README.md` 提到的 app-level 装配目录已经演进，优先核对 `components/app/*`、`build*.ts`、`create*.ts` 的现状，旧版的 `components/app/views/*`、`SearchResultsOverlay`、单视图 `Home.tsx` 已经完全清理。
- 涉及测试、开发、部署、脚本，优先看 `README.md` 的“部署与开发”“常用脚本”。
- 涉及在线音乐（网易云、酷狗）、Navidrome 和本地音乐多来源的边界，先看 README 对各个来源的产品说明与 Omni facade 契约，再回到代码实现确认。
- 涉及同步服务时，先看根 README 的产品层说明，再看 `sync-server/README.md` 的运维说明，最后回到 `src/services/sync/*` 和 `sync-server/src/*` 核对实际协议。

## What To Avoid

- 不读相关 README 片段就直接重构模块边界
- 为了“保险”完整读取 `README.md` 或 `src/README.md`
- 在已经有具体文件线索时，仍然大范围读 README
- 把 README 当成绝对真相，不核对实际代码
- 明明发现 README 已经过时，却不说明也不修