android2harmony 0.1.0

package/skills/hmos-spec-generate/SKILL.md

@@ -0,0 +1,413 @@
+---
+name: hmos-spec-generate
+description: "Generate requirement specification (spec) documents for Android-to-HarmonyOS migration. For each .txt requirement file in a folder, explore the Android codebase via homegraph and decompose the requirement into atomic user scenarios, emitting one markdown spec per file. Use when generating spec docs from a folder of raw requirement descriptions, decomposing requirements into atomic scenarios, or preparing scenario-based specs for HarmonyOS migration. Triggers: spec generation, 生成spec, requirement to spec, atomic scenarios, 拆分场景, scenario decomposition, 需求转spec."
+license: MIT
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+  - mcp__homegraph__search
+  - mcp__homegraph__explore
+  - mcp__homegraph__node
+  - mcp__homegraph__impact
+  - mcp__homegraph__callers
+  - mcp__homegraph__callees
+  - mcp__homegraph__files
+---
+
+# Spec Generator Skill
+
+You are a **Spec Generator** that produces high-quality requirement specification (spec) documents for Android-to-HarmonyOS migration projects. Given a folder of raw requirement `.txt` files, explore the corresponding Android codebase via homegraph and emit a clean, atomic-scenario-based spec markdown for every requirement.
+
+## Quick Reference
+
+| Item | Value |
+|------|-------|
+| **Input** | `requirement-description-dir` + `android-project-path` + `spec-output-dir` |
+| **Output** | One `<source_filename_without_ext>.md` per input `.txt` under `spec-output-dir` |
+| **homegraph (Index CLI)** | `homegraph` CLI via `Bash` (`status` / `init` / `sync` / `index`) |
+| **homegraph (Code queries)** | `mcp__homegraph__*` tools (`search` / `explore` / `node` / `impact` / `callers` / `callees` / `files`) |
+| **Processing Mode** | Per-file end-to-end loop (no batch pre-read) |
+
+## Expected Input
+
+- `requirement-description-dir`: Absolute path to a directory containing one or more `.txt` files. Each `.txt` file's content is the raw requirement description of a single requirement (required).
+- `android-project-path`: Absolute path to the Android project root (required).
+- `spec-output-dir`: Absolute path to the directory where the generated spec files (`xxx.md`) will be written (required).
+
+## Expected Output
+
+- One markdown spec file per input `.txt` requirement file, written under `spec-output-dir`. The spec filename mirrors the source filename with `.md` extension (e.g. `create_playlist.txt` → `create_playlist.md`).
+
+---
+
+## Principles
+
+These are the authoring rules the final spec MUST follow:
+
+1. Requirements must be decomposed into atomic scenarios. Atomic scenarios combine to form a requirement.
+2. Each atomic scenario corresponds to one normal case or one edge/boundary case.
+3. Atomic scenarios must be comprehensive and non-redundant.
+4. The spec document must include a requirement semantic description, scenario semantic descriptions, and scenario flow descriptions.
+5. The scenario flow description in the spec document must include the trigger operation sequence and the logical execution steps for that scenario.
+6. The spec document must not contain any Android-related knowledge descriptions, design descriptions, or code descriptions.
+
+---
+
+## Spec Few-shot Samples
+
+### Sample 1
+```
+# 新建歌单SPEC
+
+创建新歌单
+
+## 场景一
+
+### 场景概述
+
+用户点击创建歌单，但输入的歌单名称为空并且创建歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在“歌单页面”点击“更多菜单”中的“新建歌单按钮”或者用户在“添加到歌单弹窗”中点击“新建歌单按钮”
+- 2. 弹出“新建歌单对话框”
+- 3. 用户在输入框中输入空白歌单名称并点击确定按钮
+- 4. 弹出toast”歌单名称不得为空“并且关闭“新建歌单对话框”
+
+## 场景二
+
+### 场景概述
+
+用户点击创建歌单，但输入的歌单名称超过最大长度并且创建歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在“歌单页面”点击“更多菜单”中的“新建歌单按钮”或者用户在“添加到歌单弹窗”中点击“新建歌单按钮”
+- 2. 弹出“新建歌单对话框”
+- 3. 用户在输入框中输入歌单名称并且歌单名称超过100个字符，然后点击确定按钮
+- 4. 弹出toast“歌单名称过长”并且关闭“新建歌单对话框”
+
+## 场景三
+
+### 场景概述
+
+用户点击创建歌单，输入有效歌单名称并且创建歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在“歌单页面”点击“更多菜单”中的“新建歌单按钮”或者用户在“添加到歌单弹窗”中点击“新建歌单按钮”
+- 2. 弹出“新建歌单对话框”
+- 3. 用户在输入框中输入有效歌单名称，即用户输入到歌单名称不为空并且歌单名称没有超过100个字符，然后点击确定按钮
+- 4. 去除歌单名称首尾空白字符
+- 5. 把新建的歌单数据写入数据库中的歌单数据库表
+- 6. 如果是在“歌单页面”，那么从数据库中读取新建歌单的数据，并且在“歌单页面”创建新建歌单item，实时刷新歌单页面，在歌单页面列表中的第一个位置上显示新建的歌单
+- 7. 如果是在“添加到歌单弹窗”，那么从数据库中读取新建歌单的数据，并且在“添加到歌单弹窗”创建新建歌单item，实时刷新歌单页面，在添加到歌单弹窗列表中的第一个位置上显示新建的歌单
+
+## 场景四
+
+### 场景概述
+
+用户点击创建歌单，输入或者不输入歌单名称，然后点击取消按钮
+
+### 场景逻辑步骤
+
+- 1. 用户在“歌单页面”点击“更多菜单”中的“新建歌单按钮”或者用户在“添加到歌单弹窗”中点击“新建歌单按钮”
+- 2. 弹出“新建歌单对话框”
+- 3. 无论用户是否在输入框中输入歌单名称，只要用户点击取消按钮，那么就关闭“新建歌单对话框”，无需执行其他操作
+```
+
+### Sample 2
+```
+# 歌曲信息页信息展示与信息更新SPEC
+
+歌曲信息页展示音频信息、出自专辑、参与创作的艺术家，以及播放界面保持屏幕唤醒、沉浸模式内容。
+
+## 场景一
+
+### 场景概述
+
+进入歌曲信息页后，展示当前播放歌曲的信息及相关功能入口
+
+### 场景逻辑步骤
+
+- 1. 在播放页右滑进入歌曲信息页
+- 2. 歌曲信息页读取信息并展示：
+  - 2.1 音频信息展示：
+    - 当当前播放歌曲的音频格式存在时，显示当前播放歌曲的音频格式
+    - 当当前播放歌曲的音频格式缺失时，显示当前播放歌曲的文件扩展名；若文件扩展名也为空，则显示为空白
+    - 当当前播放歌曲的声道数存在时，显示声道数
+    - 当当前播放歌曲的声道数缺失时，隐藏该字段
+    - 当当前播放歌曲的采样率存在时，显示采样率
+    - 当当前播放歌曲的采样率缺失时，隐藏该字段
+    - 当当前播放歌曲的比特率存在时，显示比特率
+    - 当当前播放歌曲的比特率缺失时，显示 0 Kbps
+  - 2.2 出自专辑展示：
+    - 当当前播放歌曲的专辑封面存在时，显示专辑封面
+    - 当当前播放歌曲的专辑封面缺失时，显示默认专辑封面图标
+    - 当当前播放歌曲的专辑标题存在时，显示专辑标题
+    - 当当前播放歌曲的专辑标题缺失时，显示“未知专辑标题”
+    - 当当前播放歌曲的专辑艺术家存在时，显示专辑艺术家
+    - 当当前播放歌曲的专辑艺术家缺失时，显示“未知专辑艺术家”
+  - 2.3 参与创作的艺术家展示：
+    - 当当前播放歌曲的艺术家头像存在时，显示艺术家头像
+    - 当当前播放歌曲的艺术家头像缺失时，显示默认歌曲封面图标
+    - 当当前播放歌曲的艺术家名称存在时，显示艺术家名称
+    - 当当前播放歌曲的艺术家名称缺失时，显示“未知艺术家”
+    - 当当前播放歌曲的艺术家音轨数量（歌曲数量）存在时，显示艺术家音轨数量（歌曲数量）
+    - 当当前播放歌曲的艺术家音轨数量（歌曲数量）缺失时，显示 0
+
+
+## 场景二
+
+### 场景概述
+
+切换播放歌曲后，歌曲信息页面同步刷新
+
+### 场景逻辑步骤
+
+- 1. 在播放页右滑进入歌曲信息页
+- 2. 用户通过上一首、下一首、播放队列切歌或自动切歌等方式切换当前播放歌曲
+- 3. 歌曲信息页中的音频信息、专辑信息、艺术家信息同步刷新为新歌曲对应内容
+```
+
+### Sample 3
+```
+# 添加到歌单SPEC
+
+用户可通过多种入口将单首或多首歌曲添加到歌单，歌单详情页按配置的排序规则展示歌曲，并新增"按添加到歌单时间排序"选项。
+
+## 场景一
+
+### 场景概述
+
+用户从歌曲列表页，通过单首歌曲的更多操作-添加到歌单，将一首歌曲添加到歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在歌曲列表页点击某首歌曲的"更多操作"按钮
+- 2. 用户在弹出菜单中点击"添加到歌单"，弹出歌单选择弹窗
+- 3. 歌单选择弹窗中包含当前所有已经创建好的歌单以及新建歌单按钮
+	- 3.1 用户可以在歌单选择弹窗中点击已有的歌单将歌曲添加到歌单中，触发toast提示“已添加到歌单”
+	- 3.2 用户可以点击新建歌单按钮创建新歌单，歌单创建成功后返回歌单选择弹窗，弹窗的当前歌单列表刷新后，新创建的歌单位于最上面，点击新歌单将歌曲添加到新创建的歌单中，触发toast提示“已添加到歌单”
+- 4. 歌曲被添加到目标歌单，并按目标歌单当前的排序规则刷新歌曲列表
+	- 4.1 如果目标歌单排序规则为"按添加到歌单时间排序"，则该歌曲直接添加到歌曲列表最上方
+	- 4.2 如果目标歌单排序规则为其他规则，则按相应规则刷新歌曲列表进行排序
+- 5. 歌单封面刷新为该歌曲对应的封面
+
+## 场景二
+
+### 场景概述
+
+用户从歌曲列表页，通过多选操作-添加到歌单，将多首歌曲同时添加到歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在歌曲列表页进入多选模式，依次选中多首歌曲
+- 2. 用户点击"添加到歌单"按钮，弹出歌单选择弹窗
+- 3. 歌单选择弹窗中包含当前所有已经创建好的歌单以及新建歌单按钮
+	- 3.1 用户可以在歌单选择弹窗中点击已有的歌单将歌曲添加到歌单中，触发toast提示“已添加到歌单”
+	- 3.2 用户可以点击新建歌单按钮创建新歌单，歌单创建成功后返回歌单选择弹窗，弹窗的当前歌单列表刷新后，新创建的歌单位于最上面，点击新歌单将歌曲添加到新创建的歌单中，触发toast提示“已添加到歌单”
+- 4. 所选歌曲添加到目标歌单，并按目标歌单当前的排序规则刷新歌曲列表
+	- 4.1 如果目标歌单排序规则为"按添加到歌单时间排序"，则按用户多选过程中每首歌的选中顺序决定添加次序，最先选中的歌曲在最上方（即添加到歌单的时间最晚）
+	- 4.2 如果目标歌单排序规则为其他规则，则按相应规则刷新歌曲列表进行排序
+- 5. 歌单封面刷新为最后添加到歌单中的歌曲对应的封面
+
+## 场景三
+
+### 场景概述
+
+用户从专辑详情页，通过单首歌曲的更多操作入口，将一首歌曲添加到歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在专辑详情页点击某首歌曲的"更多操作"按钮
+- 2. 用户在弹出菜单中点击"添加到歌单"，弹出歌单选择弹窗
+- 3. 歌单选择弹窗中包含当前所有已经创建好的歌单以及新建歌单按钮
+	- 3.1 用户可以在歌单选择弹窗中点击已有的歌单将歌曲添加到歌单中，触发toast提示“已添加到歌单”
+	- 3.2 用户可以点击新建歌单按钮创建新歌单，歌单创建成功后返回歌单选择弹窗，弹窗的当前歌单列表刷新后，新创建的歌单位于最上面，点击新歌单将歌曲添加到新创建的歌单中，触发toast提示“已添加到歌单”
+- 4. 歌曲被添加到目标歌单，并按目标歌单当前的排序规则刷新歌曲列表
+	- 4.1 如果目标歌单排序规则为"按添加到歌单时间排序"，则该歌曲直接添加到歌曲列表最上方
+	- 4.2 如果目标歌单排序规则为其他规则，则按相应规则刷新歌曲列表进行排序
+- 5. 歌单封面刷新为该歌曲对应的封面
+
+## 场景四
+
+### 场景概述
+
+用户从艺术家详情页，通过单首歌曲的更多操作入口，将一首歌曲添加到歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在艺术家详情页点击某首歌曲的"更多操作"按钮
+- 2. 用户在弹出菜单中点击"添加到歌单"，弹出歌单选择弹窗
+- 3. 歌单选择弹窗中包含当前所有已经创建好的歌单以及新建歌单按钮
+	- 3.1 用户可以在歌单选择弹窗中点击已有的歌单将歌曲添加到歌单中，触发toast提示“已添加到歌单”
+	- 3.2 用户可以点击新建歌单按钮创建新歌单，歌单创建成功后返回歌单选择弹窗，弹窗的当前歌单列表刷新后，新创建的歌单位于最上面，点击新歌单将歌曲添加到新创建的歌单中，触发toast提示“已添加到歌单”
+- 4. 歌曲被添加到目标歌单，并按目标歌单当前的排序规则刷新歌曲列表
+	- 4.1 如果目标歌单排序规则为"按添加到歌单时间排序"，则该歌曲直接添加到歌曲列表最上方
+	- 4.2 如果目标歌单排序规则为其他规则，则按相应规则刷新歌曲列表进行排序
+- 5. 歌单封面刷新为该歌曲对应的封面
+
+## 场景五
+
+### 场景概述
+
+用户从文件夹详情页，通过单首歌曲的更多操作入口，将一首歌曲添加到歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在文件夹详情页点击某首歌曲的"更多操作"按钮
+- 2. 用户在弹出菜单中点击"添加到歌单"，弹出歌单选择弹窗
+- 3. 歌单选择弹窗中包含当前所有已经创建好的歌单以及新建歌单按钮
+	- 3.1 用户可以在歌单选择弹窗中点击已有的歌单将歌曲添加到歌单中，触发toast提示“已添加到歌单”
+	- 3.2 用户可以点击新建歌单按钮创建新歌单，歌单创建成功后返回歌单选择弹窗，弹窗的当前歌单列表刷新后，新创建的歌单位于最上面，点击新歌单将歌曲添加到新创建的歌单中，触发toast提示“已添加到歌单”
+- 4. 歌曲添加到目标歌单，并按目标歌单当前的排序规则刷新歌曲列表
+	- 4.1 如果目标歌单排序规则为"按添加到歌单时间排序"，则该歌曲直接添加到歌曲列表最上方
+	- 4.2 如果目标歌单排序规则为其他规则，则按相应规则刷新歌曲列表进行排序
+- 5. 歌单封面刷新为该歌曲对应的封面
+
+## 场景六
+
+### 场景概述
+
+用户从文件夹详情页，通过多选操作，将多首歌曲同时添加到歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在文件夹详情页进入多选模式，依次选中多首歌曲
+- 2. 用户点击"添加到歌单"按钮，弹出歌单选择弹窗
+- 3. 歌单选择弹窗中包含当前所有已经创建好的歌单以及新建歌单按钮
+	- 3.1 用户可以在歌单选择弹窗中点击已有的歌单将歌曲添加到歌单中，触发toast提示“已添加到歌单”
+	- 3.2 用户可以点击新建歌单按钮创建新歌单，歌单创建成功后返回歌单选择弹窗，弹窗的当前歌单列表刷新后，新创建的歌单位于最上面，点击新歌单将歌曲添加到新创建的歌单中，触发toast提示“已添加到歌单”
+- 4. 所选歌曲添加到目标歌单，并按目标歌单当前的排序规则刷新歌曲列表
+	- 4.1 如果目标歌单排序规则为"按添加到歌单时间排序"，则按用户多选过程中每首歌的选中顺序决定添加次序，最先选中的歌曲在最上方（即添加到歌单的时间最晚）
+	- 4.2 如果目标歌单排序规则为其他规则，则按相应规则刷新歌曲列表进行排序
+- 5. 歌单封面刷新为最后添加到歌单中的歌曲对应的封面
+
+## 场景七
+
+### 场景概述
+
+用户进入歌单详情页，查看歌单名称及歌曲列表
+
+### 场景逻辑步骤
+
+- 1. 用户点击某个歌单进入歌单详情页
+- 2. 页面顶部展示歌单名字
+- 3. 页面下方展示歌单包含的歌曲列表，歌曲按照当前歌单配置的排序规则进行展示
+- 4. 新建歌单的默认排序规则为"按添加到歌单时间排序"（后添加到歌单的歌曲排在上面）
+
+## 场景八
+
+### 场景概述
+
+用户在歌单详情页切换排序规则为"按添加到歌单时间排序"以外的其他规则
+
+### 场景逻辑步骤
+
+- 1. 用户在歌单详情页点击排序选项入口
+- 2. 用户选择其他排序规则（如标题、艺术家等）
+- 3. 歌曲列表按所选规则重新排序并刷新展示
+- 4. 该排序规则在用户再次切换前保持生效，后续新添加的歌曲按该规则插入对应位置
+
+## 场景九
+
+### 场景概述
+
+当用户尝试将已存在于目标歌单中的歌曲再次添加到该歌单时，不会重复添加
+
+### 场景逻辑步骤
+
+- 1. 用户通过任意入口（单首或多选）选择歌曲并添加到目标歌单，触发toast提示“已添加到歌单”
+- 2. 如果所选歌曲中存在已在目标歌单中的歌曲，该歌曲不会被重复添加，其原有的添加时间保持不变
+- 3. 对于本次操作中尚未在目标歌单中的歌曲，按对应排序规则正常添加
+
+## 场景十
+
+### 场景概述
+
+用户在歌单选择弹窗中取消添加到歌单操作
+
+### 场景逻辑步骤
+
+- 1. 用户通过任意入口触发"添加到歌单"，弹出歌单选择弹窗
+- 2. 用户通过点击弹窗外部区域关闭弹窗
+- 3. 歌单内容不发生任何变化，用户返回操作前的页面状态
+
+
+## 场景十一
+
+### 场景概述
+
+歌单选择弹窗需要包含当前所有已创建的歌单及歌曲信息
+
+### 场景逻辑步骤
+
+- 1. 用户通过添加到歌单操作触发歌单选择弹窗
+- 2. 歌单选择弹窗通过列表形式展示当前所有已经创建好的歌单，每个歌单对应的歌曲数目是准确的
+
+## 场景十二
+
+### 场景概述
+
+添加歌曲到歌单后，歌单的歌曲数量需要实时刷新
+
+### 场景逻辑步骤
+
+- 1. 用户将歌曲添加到歌单
+- 2. 歌单列表页，歌单详情页，歌单选择弹窗中该歌单对应的歌曲数目需要实时刷新
+```
+
+---
+
+## Workflow
+
+### Step 0 — Validate inputs
+
+1. Verify `requirement-description-dir` exists and is a directory. List all `.txt` files directly under it (collect the list of filenames only — do NOT read their contents yet). If there are no `.txt` files, stop and report the error.
+2. Verify `android-project-path` exists and is a directory.
+3. Ensure `spec-output-dir` exists (create it if it does not).
+
+### Step 1 — Ensure homegraph has a fresh index for the project
+
+homegraph exposes two surfaces:
+
+- **Index management** (`status`, `init`, `sync`, `index`) → run the `homegraph` CLI via `Bash`.
+- **Code queries** (`search`, `explore`, `node`, `impact`, `callers`, `callees`, `files`) → call `mcp__homegraph__*` tools directly.
+
+homegraph indexes per-project into a local `.homegraph/` directory; there is no central repo registry. Scope every code query to the Android project with `projectPath: "<android-project-path>"` (this skill's working directory is the spec project, NOT the Android project, so the parameter is mandatory — omitting it queries the wrong project).
+
+Procedure:
+
+1. Run `homegraph status <android-project-path>` to inspect the index state.
+2. Decide based on the output:
+   - **Not indexed** (no `.homegraph/`) → run `homegraph init -i <android-project-path>`, wait for completion.
+   - **Stale** (`homegraph status` output does NOT contain `[OK] Index is up to date`) → run `homegraph sync <android-project-path>` (incremental; use `homegraph index <android-project-path> --force` for a full rebuild), wait for completion.
+   - **Fresh** → proceed to Step 2.
+
+**Hard fail policy** — any of the following stops the skill and surfaces the error to the user; do NOT degrade to `Read` + `Grep`:
+
+- `homegraph` CLI is not found on PATH → ask the user to install it (`npm install -g homegraph`).
+- `homegraph status`, `init`, `sync`, or `index` returns an error → surface the error verbatim and stop. Do not attempt spec generation without an index — the resulting spec would miss code-grounded scenarios.
+- Any `mcp__homegraph__*` call reports the project is not indexed → verify `init -i` ran against `android-project-path`.
+
+### Step 2 — Process each requirement file independently, one at a time
+
+For each `.txt` filename collected in Step 0, in order, run 2.1 → 2.4 end-to-end before moving to the next file. Do NOT pre-read all `.txt` files.
+
+- **2.1 Read**: Read this file's content verbatim. If empty, warn and skip to the next file.
+- **2.2 Analyze**: Explore the Android codebase for this requirement using the `mcp__homegraph__*` tools to retrieve the complete code implementation (entry points, end-to-end call chains, state writes / persistence keys, manifest declarations). Use `search` → `explore` / `node` to locate and read symbols; `callers` / `callees` / `impact` to walk call chains up and down; `files` to enumerate; and `Grep` for exact literals (settings keys, DAO columns, `android:key`) that live outside the code graph. Scope EVERY `mcp__homegraph__*` call with `projectPath: "<android-project-path>"` (a missing or wrong `projectPath` queries the wrong project). Use these tools directly — do NOT invoke any nested exploration skill. If any `mcp__homegraph__*` call fails unexpectedly, surface the error and stop.
+- **2.3 Decompose**: Using the raw requirement + code from 2.2, generate the spec per `## Principles` and `## Spec Few-shot Samples`.
+- **2.4 Write**: Write the spec to `<spec-output-dir>/<source_filename_without_ext>.md` (overwrite if exists), then move on to the next file.
+
+### Step 3 — Report
+
+After all requirement files have been processed (or skipped with a warning), report a brief summary listing each generated spec file path and any files that were skipped.

package/skills/hmos-spec-generate/references/android-platform-tokens.md

@@ -0,0 +1,105 @@
+# Android Platform Tokens — Strip List
+
+**Read when**: 3.5 Synthesize, for the platform-token strip list (Principle 6).
+
+The spec MUST NOT contain Android platform tokens. During 3.5 synthesis, strip every match from the trace's natural-language behavior text and replace with behavior-level Chinese vocabulary. The trace itself may use these tokens (they live in `file:line` anchors and code-layer notes); only the **final spec** must be platform-token-free.
+
+## Strip list (by category)
+
+### Components
+`Activity`, `Fragment`, `Composable`, `Service`, `ForegroundService`, `BroadcastReceiver`, `ContentProvider`, `Application`, `Worker`, `IntentService`, `JobIntentService`, `JobScheduler`
+
+### IPC / data carriers
+`Intent`, `PendingIntent`, `Bundle`, `Parcelable`, `Messenger`, `AIDL`, `Binder`, `IBinder`
+
+### State / architecture
+`ViewModel`, `LiveData`, `MutableLiveData`, `StateFlow`, `SharedFlow`, `Flow` (when meaning Kotlin Flow), `mutableStateOf`, `ViewBinding`, `DataBinding`, `Repository`, `UseCase`, `Presenter`
+
+### Persistence
+`Room`, `RoomDatabase`, `DAO`, `@Entity`, `DataStore`, `Preferences DataStore`, `Proto DataStore`, `SharedPreferences`, `MMKV`, `SQLiteOpenHelper`, `ContentResolver`
+
+### Lifecycle
+`onCreate`, `onStart`, `onResume`, `onPause`, `onStop`, `onDestroy`, `Lifecycle`, `LifecycleOwner`, `ProcessLifecycleOwner`, `viewLifecycleOwner`, `lifecycleScope`
+
+### UI containers / widgets
+`RecyclerView`, `Adapter`, `ViewHolder`, `ConstraintLayout`, `LinearLayout`, `FrameLayout`, `RelativeLayout`, `ScrollView`, `ListView`, `Spinner`, `ViewPager`, `TabLayout`
+
+### UI feedback
+`Toast`, `Snackbar`, `Dialog`, `AlertDialog`, `BottomSheetDialog`, `ProgressDialog`, `FloatingActionButton`
+
+### Navigation
+`NavController`, `NavGraph`, `NavHostFragment`, `Navigation Component`, `startActivity`, `startActivityForResult`
+
+### Resources / IDs
+`R.id.*`, `R.layout.*`, `R.string.*`, `R.drawable.*`, `R.color.*`, `R.dimen.*`, `R.menu.*`, `R.xml.*`, `R.array.*`, `R.style.*`, `@+id/...`, `@string/...`, `@drawable/...`, `@color/...`
+
+### Coroutines / threading
+`Coroutine`, `suspend`, `CoroutineScope`, `Job`, `viewModelScope`, `withContext`, `Dispatchers.*`, `async`, `await`, `launch`, `Handler`, `Looper`, `HandlerThread`, `AsyncTask`, `Executor`
+
+### Compose (lifecycle / state)
+`@Composable`, `remember`, `derivedStateOf`, `rememberSaveable`, `MutableState`, `LaunchedEffect`, `DisposableEffect`, `SideEffect`, `CompositionLocal`, `produceState`
+
+### Compose Shape
+`CircleShape`, `RoundedCornerShape`, `RectangleShape`, `CutCornerShape`
+
+### Compose Animation
+`LinearEasing`, `FastOutSlowInEasing`, `EaseInOut`, `EaseOut`, `tween`, `spring`, `keyframes`, `infiniteRepeatable`, `animateXxxAsState`, `Animatable`, `AnimationSpec`
+
+### Compose Layout / Modifier
+`ContentScale` (Fit / Crop / FillBounds / Inside / None), `Alignment`, `Arrangement`, `Modifier.clip`, `Modifier.background`, `Modifier.size`, `Modifier.padding`, `Modifier.fillMaxSize`, `Modifier.wrapContentSize`, `Modifier.aspectRatio`, `Modifier.weight`
+
+### Build / Manifest
+`AndroidManifest`, `build.gradle`, `gradle`, `BuildConfig`, `applicationId`, `versionCode`, `minSdkVersion`, `targetSdkVersion`, `compileSdkVersion`, `ProGuard`, `R8`
+
+### DI
+`Hilt`, `Dagger`, `@Inject`, `@Module`, `@Provides`, `@Singleton`, `Koin`, `ServiceLocator`
+
+### System services / media
+`ContextCompat`, `getSystemService`, `NotificationManager`, `NotificationChannel`, `AlarmManager`, `PowerManager`, `ConnectivityManager`, `AudioManager`, `MediaSession`, `MediaPlayer`, `ExoPlayer`, `MediaBrowserServiceCompat`
+
+### Implementation constants (NEVER appear in spec)
+
+- **Hardcoded dimensions** (`8dp`, `48.dp`, `16.sp`, `2.dp`) — strip entirely. Spec describes shape/size semantically: "圆形" / "小圆点" / "歌词字号比正文略大". 不要保留单位 ("8 dp" 也不行).
+- **Hardcoded durations** (`25000ms`, `300L`, `Duration.seconds(2)`) — restate as semantic time: "约 25 秒一圈" / "短暂淡入". 不要写原始数值.
+- **Persistence key literals** (`circle_playback_cover`, `karaoke_mode_compat`, `floating_lyric_enabled`) — NEVER. Describe the user-visible setting, not the storage key.
+
+## Critical: Chinese translations of platform concepts are ALSO forbidden
+
+The strip list above uses English API names. But platform concepts translated into Chinese (e.g. `活动基类` for Activity / `主活动页面` for MainActivity / `媒体会话信息` for MediaSession / `短边模式` for DISPLAY_CUTOUT_MODE / `广播接收器` for BroadcastReceiver / `视图模型` for ViewModel) are STILL platform tokens — restate them in user-facing behavior language per the replacement vocabulary below. Translating a platform concept does NOT make it user-facing.
+
+## Replacement vocabulary (behavior-level Chinese)
+
+| Stripped token | Spec vocabulary |
+|---|---|
+| Activity / Fragment / Composable | 页面 |
+| Dialog / AlertDialog / BottomSheet | 弹窗 / 对话框 |
+| Toast / Snackbar | toast 提示 / 浮动提示 |
+| ViewModel / LiveData / StateFlow / mutableStateOf | 状态 / 状态写入 / 状态刷新 |
+| Room / DAO / DataStore / SharedPreferences / MMKV | 持久化 / 数据库 / 配置存储 |
+| RecyclerView + Adapter / ListView | 列表 / 列表项 |
+| onClick / onLongClick / onTap | 点击 / 长按 |
+| Intent / startActivity / Navigation | 跳转 / 进入<目标页> |
+| BroadcastReceiver / sendBroadcast | 系统事件监听 / 广播 |
+| Service / ForegroundService | 后台服务 / 前台服务 |
+| Coroutine / launch / withContext | 异步 / 异步执行 |
+| MediaPlayer / ExoPlayer / MediaSession | 播放器 / 播放控制 |
+| Notification / NotificationManager / NotificationChannel | 通知 / 通知栏 / 通知分组 |
+| ContentResolver / ContentProvider | 数据访问 / 数据共享 |
+| build.gradle flag / BuildConfig | 编译开关 / 配置项 |
+| ConnectivityManager | 网络状态 / 网络可达性 |
+| AudioManager / audio focus | 音频焦点 / 音频通道 |
+| PowerManager / WakeLock | 屏幕唤醒 / 锁屏唤醒 |
+| CircleShape / RoundedCornerShape / RectangleShape / CutCornerShape | 圆形 / 圆角矩形 / 矩形 / 切角矩形 |
+| LinearEasing / FastOutSlowInEasing / EaseInOut / EaseOut | 线性 / 减速 / 缓入缓出 / 减速出 |
+| tween / spring / keyframes / infiniteRepeatable / Animatable | 持续N秒动画 / 弹性动画 / 关键帧动画 / 循环动画 / 动画对象 |
+| ContentScale.Fit / Crop / FillBounds / Inside / None | 等比缩放适配 / 裁剪填充 / 拉伸填充 / 等比居中 / 不缩放 |
+| Modifier.clip / .size / .padding / .fillMaxSize / .aspectRatio | 裁剪为X形 / 设定尺寸 / 内边距 / 填满父容器 / 宽高比 |
+| Modifier.wrapContentSize / .weight / .background | 内容自适应 / 权重占比 / 背景 |
+| animateXxxAsState | 动画过渡到目标值 |
+
+## Items to keep verbatim (do NOT strip)
+
+- **Business entity names** (歌单, 歌曲, 专辑, 艺术家, 播放页, ...) — these are domain language, not platform tokens.
+- **User-visible resource string content** (toast text, button labels, error messages) — translate the displayed content into the spec; strip the `R.string.xxx` reference but keep the message text.
+- **Standard permission semantics** — describe permissions in user language ("录音权限", "通知权限", "存储访问权限"), NOT by code constant (`RECORD_AUDIO`, `POST_NOTIFICATIONS`, ...).
+- **Persistence key literals** are usually internal — do NOT surface them in the spec unless they appear in user-visible UI (rare). If a key appears in the trace's `interaction` field, describe its behavior, not its name.

package/skills/hmos-spec-generate/references/spec-sample-1.md

@@ -0,0 +1,78 @@
+# Spec Sample 1 — Boundary-and-happy-path Decomposition
+
+**Style focus**: how to slice one feature into `empty / over-length / valid / cancel` atomic scenarios on a single-entry trigger flow. Mimic the voice, scenario granularity, and structure — NOT the vocabulary or domain.
+
+**Read when**: 3.5 Synthesize.
+
+---
+
+# 新建歌单SPEC
+
+创建新歌单
+
+## 场景一
+
+### 场景概述
+
+用户点击创建歌单，但输入的歌单名称为空并且创建歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在"歌单页面"点击"更多菜单"中的"新建歌单按钮"或者用户在"添加到歌单弹窗"中点击"新建歌单按钮"
+- 2. 弹出"新建歌单对话框"
+- 3. 用户在输入框中输入空白歌单名称并点击确定按钮
+- 4. 弹出toast"歌单名称不得为空"并且关闭"新建歌单对话框"
+
+## 场景二
+
+### 场景概述
+
+用户点击创建歌单，但输入的歌单名称超过最大长度并且创建歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在"歌单页面"点击"更多菜单"中的"新建歌单按钮"或者用户在"添加到歌单弹窗"中点击"新建歌单按钮"
+- 2. 弹出"新建歌单对话框"
+- 3. 用户在输入框中输入歌单名称并且歌单名称超过100个字符，然后点击确定按钮
+- 4. 弹出toast"歌单名称过长"并且关闭"新建歌单对话框"
+
+## 场景三
+
+### 场景概述
+
+用户点击创建歌单，输入有效歌单名称并且创建歌单
+
+### 场景逻辑步骤
+
+- 1. 用户在"歌单页面"点击"更多菜单"中的"新建歌单按钮"或者用户在"添加到歌单弹窗"中点击"新建歌单按钮"
+- 2. 弹出"新建歌单对话框"
+- 3. 用户在输入框中输入有效歌单名称，即用户输入到歌单名称不为空并且歌单名称没有超过100个字符，然后点击确定按钮
+- 4. 去除歌单名称首尾空白字符
+- 5. 把新建的歌单数据写入数据库中的歌单数据库表
+- 6. 如果是在"歌单页面"，那么从数据库中读取新建歌单的数据，并且在"歌单页面"创建新建歌单item，实时刷新歌单页面，在歌单页面列表中的第一个位置上显示新建的歌单
+- 7. 如果是在"添加到歌单弹窗"，那么从数据库中读取新建歌单的数据，并且在"添加到歌单弹窗"创建新建歌单item，实时刷新歌单页面，在添加到歌单弹窗列表中的第一个位置上显示新建的歌单
+
+> [偏差] 需求要求歌单名为空时禁用"确定"按钮，但实际代码允许点击后弹出 toast 提示（参见场景一步骤 4）。
+
+## 场景四
+
+### 场景概述
+
+用户点击创建歌单，输入或者不输入歌单名称，然后点击取消按钮
+
+### 场景逻辑步骤
+
+- 1. 用户在"歌单页面"点击"更多菜单"中的"新建歌单按钮"或者用户在"添加到歌单弹窗"中点击"新建歌单按钮"
+- 2. 弹出"新建歌单对话框"
+- 3. 无论用户是否在输入框中输入歌单名称，只要用户点击取消按钮，那么就关闭"新建歌单对话框"，无需执行其他操作
+
+## 场景五
+
+### 场景概述
+
+"新建歌单"功能的作用范围与不作用范围
+
+### 场景逻辑步骤
+
+- 1. **仅作用于** 以下入口: "歌单页面"的"更多菜单 - 新建歌单"按钮; "添加到歌单弹窗"的"新建歌单"按钮
+- 2. **不作用于** 以下位置: "歌单详情页"(无新建入口) / "播放页" / "首页推荐区域" / "搜索结果页" / "我的页面" — 这些位置既不显示新建歌单入口, 也不响应新建歌单事件

package/skills/hmos-spec-generate/references/spec-sample-2.md

@@ -0,0 +1,58 @@
+# Spec Sample 2 — Nested Sub-bullet Decomposition
+
+**Style focus**: how to express per-field present/absent fallback rules as nested sub-bullets within a single scenario's flow. Mimic the structure, NOT the vocabulary or domain.
+
+**Read when**: 3.5 Synthesize.
+
+---
+
+# 歌曲信息页信息展示与信息更新SPEC
+
+歌曲信息页展示音频信息、出自专辑、参与创作的艺术家，以及播放界面保持屏幕唤醒、沉浸模式内容。
+
+## 场景一
+
+### 场景概述
+
+进入歌曲信息页后，展示当前播放歌曲的信息及相关功能入口
+
+### 场景逻辑步骤
+
+- 1. 在播放页右滑进入歌曲信息页
+- 2. 歌曲信息页读取信息并展示：
+  - 2.1 音频信息展示：
+    - 当当前播放歌曲的音频格式存在时，显示当前播放歌曲的音频格式
+    - 当当前播放歌曲的音频格式缺失时，显示当前播放歌曲的文件扩展名；若文件扩展名也为空，则显示为空白
+    - 当当前播放歌曲的声道数存在时，显示声道数
+    - 当当前播放歌曲的声道数缺失时，隐藏该字段
+    - 当当前播放歌曲的采样率存在时，显示采样率
+    - 当当前播放歌曲的采样率缺失时，隐藏该字段
+    - 当当前播放歌曲的比特率存在时，显示比特率
+    - 当当前播放歌曲的比特率缺失时，显示 0 Kbps
+  - 2.2 出自专辑展示：
+    - 当当前播放歌曲的专辑封面存在时，显示专辑封面
+    - 当当前播放歌曲的专辑封面缺失时，显示默认专辑封面图标
+    - 当当前播放歌曲的专辑标题存在时，显示专辑标题
+    - 当当前播放歌曲的专辑标题缺失时，显示"未知专辑标题"
+    - 当当前播放歌曲的专辑艺术家存在时，显示专辑艺术家
+    - 当当前播放歌曲的专辑艺术家缺失时，显示"未知专辑艺术家"
+  - 2.3 参与创作的艺术家展示：
+    - 当当前播放歌曲的艺术家头像存在时，显示艺术家头像
+    - 当当前播放歌曲的艺术家头像缺失时，显示默认歌曲封面图标
+    - 当当前播放歌曲的艺术家名称存在时，显示艺术家名称
+    - 当当前播放歌曲的艺术家名称缺失时，显示"未知艺术家"
+    - 当当前播放歌曲的艺术家音轨数量（歌曲数量）存在时，显示艺术家音轨数量（歌曲数量）
+    - 当当前播放歌曲的艺术家音轨数量（歌曲数量）缺失时，显示 0
+
+
+## 场景二
+
+### 场景概述
+
+切换播放歌曲后，歌曲信息页面同步刷新
+
+### 场景逻辑步骤
+
+- 1. 在播放页右滑进入歌曲信息页
+- 2. 用户通过上一首、下一首、播放队列切歌或自动切歌等方式切换当前播放歌曲
+- 3. 歌曲信息页中的音频信息、专辑信息、艺术家信息同步刷新为新歌曲对应内容