chthollyphile README Reference
这个 skill 用于在修改前从仓库内 README 定位仍然有效的项目上下文，但必须控制读取范围，避免把长 README 整段灌入上下文。
When To Use
以下情况优先使用：
- 修改前端架构、组件职责、服务层调用关系
- 修改测试策略、测试入口、运行命令
- 修改部署、开发、Electron、workflow 相关内容
- 修改文档、issue template、贡献说明
- 需要确认某个模块在项目中的定位，而不是只看当前文件猜测
Primary Sources
优先在这些项目文档里定位片段：
README.mdsrc/README.mdsync-server/README.md（仅当任务涉及同步服务端、Token、D1、Docker 或 Node 部署）
不要默认完整读取这些文件。除非用户明确要求全文审阅，否则每次只读取和当前任务直接相关的小片段。
Read Budget
默认读取预算：
- 先用
rg -n定位标题、关键词、脚本名、文件名或模块名。 - 每个 README 单次只打开 20-80 行相关片段。
- 同一任务通常不要从 README 读取超过 160 行。
- 如果片段不够，再追加下一个最相关片段，而不是整文件打开。
推荐命令模式：
rg -n "关键词|脚本名|模块名" README.md src/README.md
sed -n '起始行,结束行p' README.md
sed -n '起始行,结束行p' src/README.md
如果不确定关键词，先读目录或标题片段：
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
@noteexactly 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
- 先判断任务是否涉及项目约定、架构边界或运行方式。
- 如果涉及，先用
rg -n在对应 README 中找关键词或标题；同步服务任务同时检查sync-server/README.md。 - 只打开命中的相关行附近片段。
- 用 README 提供方向，用真实代码确认细节。
- 如果 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 已经过时，却不说明也不修