Skip to main content Início Criadores chthollyphile folia-sonnet reuse-project-utilities
reuse-project-utilities Use when implementing, refactoring, or reviewing code in this repository and the task may duplicate existing helpers, libraries, visualizer utilities, lyrics utilities, font/color helpers, list virtualization, icon usage, i18n, playback adapters, or service patterns. Trigger before writing new utility functions or installing/hand-rolling functionality already present in the project.
Ir para a instalação Skills Marketplace Descubra e explore skills de IA criadas pela comunidade.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Mostrar detalhes do prompt Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
npx skills add https://github.com/chthollyphile/folia-sonnet --skill reuse-project-utilitiesO comando permanece em uma só linha. Role horizontalmente para revisá-lo antes de copiar.
Prefere uma cópia local? Baixe os arquivos disponíveis atualmente no SkillsMP.
Baixar Zip Baixando... Explorador de arquivos
2 arquivos Mais deste repositório Use when adding or refactoring frontend features in this repository and you need to prevent large single-file changes, oversized entry files, mixed responsibilities, or giant App.tsx/Home.tsx style implementations. Apply it when a task risks stuffing UI, state, effects, data access, and helper logic into one file instead of splitting work into focused components, hooks, services, utils, and types.
frontend-runtime-guardrails Use when adding, refactoring, or reviewing frontend runtime behavior in this repository, especially visualizers, lyrics animation, Framer Motion usage, useMotionValueEvent, requestAnimationFrame, ResizeObserver, high CPU reports, jank, per-character or per-frame animation, React state update frequency, and performance-sensitive UI paths.
Use when the user refers to repository-specific terms such as home view, panel, local library, Navidrome view, visualizer mode, queue, current song, search state, or other spoken component/state names and you need to map them quickly to the concrete files, hooks, stores, and code ownership in this project.
Ocupações relacionadas SOC
Baseado na classificação ocupacional SOC
name reuse-project-utilities description Use when implementing, refactoring, or reviewing code in this repository and the task may duplicate existing helpers, libraries, visualizer utilities, lyrics utilities, font/color helpers, list virtualization, icon usage, i18n, playback adapters, or service patterns. Trigger before writing new utility functions or installing/hand-rolling functionality already present in the project.
Reuse Project Utilities
Purpose
这个 skill 用于防止“造一个颜色不同的轮子”。写代码前先查已有 helper、组件模式和项目已安装库，优先复用它们。
核心规则：
新增工具函数前，先用 rg 搜相同领域的现有函数。
外部库已经覆盖的能力，不要手写低配版。
复用项目里已经承载语义的 helper，而不是复制局部实现。
如果已有 helper 不够，优先扩展原 helper 并补测试，而不是另起相似名字。
Fast Lookup
按任务类型先查这些入口：
歌词解析、时序、render end：src/utils/lyrics/*
visualizer 运行时、背景、颜色：src/components/visualizer/*
设置 UI、导入导出、命令面板：src/components/modal/settings/*、src/stores/useSettingsUiStore.ts、src/components/command-palette/*
同步配置、主题同步和本地导出：src/services/sync/*、src/components/modal/settings/StorageSettingsSection.tsx
字体栈和自定义字体：src/utils/fontStacks.ts、src/services/customLyricsFont.ts
播放队列、播放适配：src/services/playbackAdapters.ts、src/utils/appPlaybackHelpers.ts
网易云 / Navidrome / 本地音乐 API：src/services/*
主题、封面、取色、缓存：src/hooks/themeControllerState.ts、src/utils/colorExtractor.ts、src/services/themeCache.ts、src/services/coverCache.ts
UI 图标、动画、弹窗、选择器：lucide-react、
framer-motion
components/shared/*
rg -n "目标词|函数名|相邻概念" src test
rg -n "prepareWithSegments|layoutWithLines|useVisualizerRuntime|getLineRenderEndTime|buildLineGraphemeTimeline|resolveThemeFontStack|colorWithAlpha|mixColors" src
Common Utilities
Text Layout And Measurement 已安装 @chenglou/pretext，用于文字准备、测量和排版。
import { prepareWithSegments, layoutWithLines } from '@chenglou/pretext' ;
const prepared = prepareWithSegments (text, fontSpec);
const layout = layoutWithLines (prepared, maxWidth, lineHeightPx);
const width = layout.lines [0 ]?.width ?? fallbackWidth;
visualizer 文本宽度测量
歌词自动换行
气泡、块状文本、canvas overlay 的排版
需要和 CJK / grapheme 排版更接近真实浏览器表现的场景
不要手写 text.length * fontSize 作为主测量逻辑；只能作为 fallback。
Visualizer Runtime visualizer 当前行、上一行、下一行、预热窗口已有共享入口：
useVisualizerRuntimeprepareActiveAndUpcomingshouldPreheatLinegetUpcomingLinegetUpcomingLines 位置：src/components/visualizer/runtime.ts
新增 visualizer 时优先使用它们，不要重新写“当前行/下一行/最近完成行”扫描逻辑。
Lyrics Timing Hints 歌词行显示结束时间和过短行处理已有统一 helper：
getLineRenderHintsgetLineRenderEndTimegetLineTransitionTimingensureLyricLinesRenderHints 位置：src/utils/lyrics/renderHints.ts
需要决定 line exit、subtitle 保留、短行 fast/instant reveal 时，先用这些 helper。不要直接假设 line.endTime 就是视觉渲染结束时间。
写 visualizer 时同时遵守 frontend-runtime-guardrails 里的歌词输入契约：renderer 消费统一 LyricData，不要重新处理原始歌词格式或翻译对齐。
Lyrics Layout Units CJK 语义分组、sticky 标点、英文 contraction 已有布局工具：
buildPostLyricLayoutUnitsbuildDisplayWordsFromLayoutUnitscreateSingleWordLayoutUnits 位置：src/utils/lyrics/cjkSemanticLayout.ts
新增按词/按块 visualizer 时，优先使用 layout units。不要在组件里临时拼接标点、撇号、CJK 字符。
Grapheme Timing 逐字或逐 grapheme 动画优先复用 src/utils/lyrics/graphemeTiming.ts：
buildLineGraphemeTimelinebuildWordGraphemeTimings 它们负责把 Line.words 的原始 timing 映射到可渲染字符；不要在 renderer 里用字符串搜索重新猜重复词、空格或标点的时间范围。
Font Stacks
resolveThemeFontStackresolveThemeTranslationFontStackgetBuiltinThemeFontStackresolveThemeFontWeightnormalizeFontWeight 位置：src/utils/fontStacks.ts
需要 CSS fontFamily、canvas font、pretext fontSpec 时，先用 resolver。不要手写一份新的 fallback font stack。
歌词和字幕的最终字重必须使用 resolveThemeFontWeight(theme, modeFallback)。模式自身的 300、400、500、700 等设计值只能作为 modeFallback：theme.fontWeight 有值时必须由用户值覆盖，没有值时才保留模式原设计。当用户在设置面板或快捷设置中清空/重置自定义字体栈时，系统会自动清空保存的自定义字重。DOM、Canvas、pretext 和光栅化文本必须复用同一个解析结果；测量规格、memo 依赖和布局缓存键也必须包含该最终字重。
不要在歌词或字幕渲染路径中使用 font-bold、font-medium、固定 style.fontWeight，也不要把固定字重直接写进 Canvas / pretext 字体规格。这些写法会绕开视觉设置，并造成测量与渲染不一致。
Visualizer Colors visualizer 颜色混合和 alpha 已有 helper：
colorWithAlpha(color, alpha)mixColors(from, to, amount, alpha?) 位置：src/components/visualizer/colorMix.ts
需要 rgba(...)、主题色混合、canvas gradient、shadow color 时，先用这些 helper。不要重复写 hex/rgb parser。
组件颜色必须来自当前 Theme / DualTheme 流程。新增 UI 或 visualizer 颜色时，不要把只适合单一明暗背景的固定 hex / rgba 当成主色长期写死；应从 theme.backgroundColor、theme.primaryColor、theme.accentColor、theme.secondaryColor 或由 buildBuiltinDualTheme / useThemeController 选出的当前明暗主题动态派生，并确保 light / dark 两套颜色都有可读对比。临时 alpha、shadow 和 gradient 也应基于主题色再用 colorWithAlpha / mixColors 生成。
Icons 项目使用 lucide-react。按钮、tab、控制项、状态动作优先从 lucide 导入图标。
不要手写 SVG，除非现有 icon 库没有合适图标或需要项目专属图形。
Animation
普通 enter/exit：motion、AnimatePresence
播放进度和时间值：MotionValue、useMotionValueEvent
派生动画值：useTransform、useSpring
新增动画先看相邻组件模式。涉及高频运行时，再结合 frontend-runtime-guardrails。
i18n const { t } = useTranslation ();
任何新增到 UI 上的用户可见文本都必须准备 i18n key，并同步写入 src/i18n/locales/en.ts 和 src/i18n/locales/zh-CN.ts。不要把按钮、标题、提示、空态、设置项、tooltip、toast 或模式文案只写成硬编码字符串；短 fallback 只能作为现有 registry / 兼容模式的兜底，不能替代字典项。
Settings And Commands 新增设置时先套用 settings-feature-integration：
视觉相关设置必须进入 AppearanceSettingsSubview.tsx 的导入导出链路。
功能性设置或可执行动作必须注册到 src/components/command-palette/commandRegistry.ts。
设置状态优先复用 src/stores/useSettingsUiStore.ts，不要在组件里另起一套 localStorage 读写。
Long Lists 项目已使用 react-window 的 List 和 useListRef。
需要渲染队列、字体列表、大量歌曲列表时，先查现有 react-window 用法。不要用普通 .map() 渲染大量可滚动项目。
Service And Data Patterns
网易云 API：src/services/netease.ts
Navidrome / Subsonic：src/services/navidromeService.ts
本地音乐：src/services/localMusicService.ts
在线歌曲搜索、播放、歌词、歌单、账户和 provider 路由：src/services/onlineMusic/omni.ts
在线播放编排：src/services/onlinePlayback.ts（内部在线数据仍须通过 Omni）
播放结构统一：src/services/playbackAdapters.ts
IndexedDB：src/services/db.ts
队列预取：src/services/prefetchService.ts
同步 HTTP / diff / 本地 registry：src/services/sync/syncClient.ts、syncRepository.ts、themeSyncRegistry.ts、syncCoordinator.ts
新增数据流时，先判断是 service、hook、util 还是 component：
请求、缓存、接口适配放 service。
React 生命周期和用户动作编排放 hook 或 app-level builder。
纯计算、映射、格式化放 util。
展示和交互结构放 component。
Extension Rule
优先扩展已有 helper 的参数或返回值。
保持现有调用兼容。
给扩展后的 helper 补单测。
避免创建同领域的第二套 formatXxx、parseXxx、measureXxx、mixXxx。
只有在职责确实不同、现有 helper 会变得混乱时，才新建工具。
Review Checklist
是否手写了已由 @chenglou/pretext、fontStacks、colorMix、lyrics utils 覆盖的逻辑？
是否复制了 visualizer runtime 的当前行/下一行扫描？
是否直接使用 line.endTime，但应该使用 getLineRenderEndTime？
是否手写 SVG，而 lucide 已有图标？
是否新建了 service 请求逻辑，但已有 service 已经封装同类 API？
是否绕过 src/services/sync/*，直接对同步服务发 fetch，或直接读写主题同步 registry / IndexedDB？
是否对大量列表使用普通 .map() 而不是虚拟列表？
是否新增硬编码文案却没有更新 i18n 字典？
是否新增设置却没有接入视觉配置导入导出或 command palette？
是否新增固定颜色却没有从 Theme / DualTheme 动态派生并检查明暗两套表现？
是否硬编码歌词或字幕字重，而没有使用 resolveThemeFontWeight 和模式 fallback？
DOM、Canvas、pretext、光栅化的最终字重以及布局缓存键是否一致？
是否创建了相似 helper，却没有搜索已有实现或测试？
Validation
纯工具、歌词、颜色、字体：优先补或跑相关 Vitest 单测。
visualizer UI：按 testing-strategy 判断是否需要 UI 截图测试。
service 改动：优先看现有 service 单测或相邻 mock 模式；不要直接打真实外部服务。
