helixlife-v5-cli 1.1.3 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helixlife-v5-cli",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Helix（vip.helixlife.cn）精细化浏览器自动化命令行工具。",
   "main": "helix-cli.js",
   "bin": {

package/references/vip.helixlife.cn.site-ops.md

@@ -469,7 +469,7 @@ div.side-menu--item[to='/edu/courses']
 
 #### 数据分析 `/analysis/`（列表 · 拼图 · 全局设置）
 
-> **核验记录**（2026-05-13 / 2026-05-15 / 2026-05-21）：全局设置弹窗、顶区**主分类下拉**（如「分析工具」→「交互网络」；URL `primary=`）与「拼图工具」形态 Tab、搜索框 + 搜索按钮、**子分类**标签条「展开 ⇄ 收起」（URL `subcategory=` / `isExpanded`）、工具卡片「收藏 / 已收藏」互斥文案均已核验。主分类项（如「交互网络」）**不在**标签条内，须展开顶栏下拉才可见——见下文「分类体系」。工具详情（`/analysis/{toolId}`，D-1～D-11）、拼图工具子页（`/analysis/jigsaw`）见 S-28 / S-27。
+> **核验记录**（2026-05-13 / 2026-05-15 / 2026-05-21）：全局设置弹窗、顶区**主分类下拉**（固定 7 项：全部工具 / 基础绘图 / 表达差异 / 功能聚类 / 交互网络 / 临床意义 / 其他；URL `primary=`）与「拼图工具」形态 Tab、搜索框 + 搜索按钮、**子分类**标签条「展开 ⇄ 收起」（URL `subcategory=` / `isExpanded`）、工具卡片「收藏 / 已收藏」互斥文案均已核验。主分类项**不在**标签条内——见「分类体系」。工具详情（`/analysis/{toolId}`，D-1～D-11）、拼图工具子页（`/analysis/jigsaw`）见 S-28 / S-27。
 
 ##### URL / 路由形态
 
@@ -609,33 +609,48 @@ helixlife-v5-cli run-code --filename=scripts/analysis-detail-upload-file.js
 
 ##### 数据分析 · 分类体系（主分类 vs 子分类 · Agent 必读）
 
-> **核验记录**（2026-05-21）：列表页顶栏**最左侧**为**主分类下拉**（带下箭头；选中后 Tab 文案变为该主分类名，如「交互网络」）。「交互网络」等主分类项**不在**搜索框下方标签条内，须先 `click` 展开当前主分类名（默认「分析工具」）后才可见。URL `primary=` 对应该下拉；`subcategory=` 对应标签条。
+> **核验记录**（2026-05-21）：列表页顶栏**最左侧**为**主分类下拉**（带下箭头；选中后 Tab 文案变为该主分类名）。下拉内主分类为**固定 7 项**（见下表），**均不在**搜索框下方标签条内。URL `primary=` 对应该下拉；`subcategory=` 对应标签条。顶栏未切换时可能仍显示「分析工具」——这是模块入口文案，**勿**与主分类枚举混淆；切换主分类须**展开下拉**点选 7 项之一。
+
+###### 主分类枚举（固定 7 项 · 优先匹配）
+
+| # | 主分类名 | 说明 |
+| --- | --- | --- |
+| 1 | **全部工具** | 全量工具列表 |
+| 2 | **基础绘图** | |
+| 3 | **表达差异** | |
+| 4 | **功能聚类** | |
+| 5 | **交互网络** | |
+| 6 | **临床意义** | |
+| 7 | **其他** | |
+
+> 用户说「分析工具下的 XX」「切到 XX 分类」且 **XX 命中上表** → **一律按主分类处理**，**禁止**先去标签条找。仅当 XX **不在**上表、且出现在搜索框下方标签条时，才按子分类处理。
 
 ###### 页面分区
 
 ```
 顶栏左侧 [主分类 ▼]  [拼图工具]          顶栏右侧 [全局设置]
-         ↓ primary=
+         ↓ primary=          （下拉内：全部工具 / 基础绘图 / … / 其他）
 搜索框 [请输入搜索关键词] [搜索]
 标签条 [全部] [类别比较] [差异分析] …     [展开 | 收起]
-         ↓ subcategory=
+         ↓ subcategory=      （随当前主分类变化；≠ 上表 7 项）
 工具卡片列表
 ```
 
-| 层级 | UI 位置 | URL 参数 | 典型选项 | 用户常见说法 |
+| 层级 | UI 位置 | URL 参数 | 选项来源 | 用户常见说法 |
 | --- | --- | --- | --- | --- |
-| **主分类** | 顶栏**最左侧**带下箭头的文案（选中后显示为该主分类名） | `primary=` | 分析工具、交互网络、…（**以展开下拉 snapshot 为准**，勿写死枚举） | 「分析工具下的交互网络」「切到交互网络」 |
-| **子分类** | 搜索框**下方**横排可点标签 | `subcategory=` | 全部、差异分析、网络图相关、互作分析、…（**随当前主分类变化**） | 「切到差异分析」「网络图相关分类」 |
+| **主分类** | 顶栏**最左侧**带下箭头的文案 | `primary=` | **上表固定 7 项**（仅在下拉菜单内） | 「切到交互网络」「分析工具下的功能聚类」 |
+| **子分类** | 搜索框**下方**横排标签 | `subcategory=` | 随主分类变化（如差异分析、网络图相关、互作分析…） | 「切到差异分析」「网络图相关」 |
 | **形态 Tab** | 主分类右侧「拼图工具」 | 路由 → `/analysis/jigsaw` | 拼图工具 | 「去拼图工具」 |
 
-> **易混点**：「网络图相关」「互作分析」是**子分类标签**，与主分类「交互网络」**不是同一控件**；勿因语义相近而误点标签条或搜索。
+> **易混点**：「网络图相关」「互作分析」是**子分类**；「交互网络」是**主分类**——同名/近义也**不得**先查标签条。
 
 ###### 用户话术 → 操作映射
 
 | 用户说法 | 操作层 | 推荐操作 |
 | --- | --- | --- |
-| 「分析工具下的 XX」「切到 XX 主分类」 | 主分类 | 展开顶栏主分类下拉 → `click` → `getByText('XX', { exact: true })` |
-| 「XX 分类」「筛选 XX」且 XX 在标签条可见 | 子分类 | `click` → 标签条 `getByText('XX', { exact: true })` |
+| XX 为**主分类枚举 7 项之一** | 主分类 | 展开顶栏下拉 → `click` → `getByText('XX', { exact: true })` |
+| 「分析工具下的 XX」且 XX 在 7 项内 | 主分类 | 同上（「分析工具」是模块说法，不是下拉里的第 8 项） |
+| XX **不在** 7 项内，且 snapshot 标签条可见 XX | 子分类 | `click` → 标签条 `getByText('XX', { exact: true })` |
 | 「去拼图工具」 | 形态 Tab | `click` → `getByText('拼图工具', { exact: true })` |
 | 「找 Limma / 配对图 / 某工具名」 | 工具卡片 | 搜索或 `click` 卡片主标题（S-13 步骤 7） |
 
@@ -643,33 +658,36 @@ helixlife-v5-cli run-code --filename=scripts/analysis-detail-upload-file.js
 
 1. **`snapshot`（必做）**。
 2. 目标是**具体工具名**（卡片标题）→ 搜索或点卡片；**勿**当分类处理。
-3. 目标名是否出现在**搜索框下方标签条**（当前可见，或点「展开」后可见）→ 是：`click` 该标签 → 验收 URL `subcategory=` 变化。
+3. **将目标名与「主分类枚举 7 项」做精确匹配**（含用户说的「分析工具下的 XX」→ 取 XX 匹配）：
+   - **命中** → **直接走主分类**（步骤 4～5），**跳过**标签条检索。
+   - **未命中** → 继续步骤 6（子分类）。
 4. 顶栏主分类文案**已是**目标名 → 已选中，结束。
-5. 否则：`click` **顶栏当前主分类名**（带下箭头；以 snapshot 顶栏左侧块为准）展开下拉 → 若菜单含目标名：`click` → 验收 URL `primary=` 变化且顶栏文案更新为目标名。
-6. 下拉与标签条**均无**目标名 → **最后手段**用搜索找工具（非切换主分类）；仍无则向用户确认是「分类名」还是「工具名」。
-7. **切换主分类后**：若搜索框有残留关键词，先清空（搜索区清除钮或 `fill` 空串再搜），再 `snapshot` 验收列表。
+5. **主分类切换**：`click` 顶栏当前主分类块（带下箭头）展开下拉 → `click` → `getByText('<目标主分类>', { exact: true })` → 验收 URL `primary=` 变化且顶栏文案更新 → **清空搜索框残留** → `snapshot` 验收列表。
+6. **子分类**（仅当步骤 3 未命中主分类枚举）：目标名是否在搜索框下方标签条（不可见则先点「展开」）→ 是：`click` 该标签 → 验收 `subcategory=` 变化。
+7. 主分类下拉与标签条**均无**目标名 → 最后手段用搜索找**工具**；仍无则向用户确认是「主分类 / 子分类 / 工具名」。
 
 **何时才向用户追问**
 
 | 情况 | 处理 |
 | --- | --- |
-| 下拉与标签条**都有**同名项 | 问：「是顶栏主分类还是下方标签？」 |
-| 两处都找不到目标名 | 问：「是分类名还是具体工具名？」 |
-| 用户只说「切换分类」且语义不明 | 可先 `snapshot` 列出当前可见主分类/子分类供其选择 |
+| 目标名**同时**出现在主分类 7 项与标签条（极少见） | 问：「是顶栏主分类还是下方标签？」 |
+| 不在 7 项、也不在标签条 | 问：「是主分类、子分类还是具体工具名？」 |
+| 用户只说「切换分类」且未给名称 | `snapshot` 后列出 7 个主分类 + 当前可见子分类供选 |
 
 **反模式**
 
-- **禁止**未展开顶栏主分类下拉就假定目标在标签条。
-- **禁止**用搜索框切换**主分类**（搜索仅筛工具卡片）。
+- **禁止**对主分类 7 项中的名称**先查标签条**（这是上次误点的根因）。
+- **禁止**未展开顶栏下拉就假定目标在标签条。
+- **禁止**用搜索框切换主分类。
 - **禁止**因语义相近误点子分类（如用「网络图相关」代替「交互网络」）。
-- **禁止**把「展开/收起」当作切换主分类——它仅控制标签条 `isExpanded` 显示更多子分类。
+- **禁止**把标签条「展开/收起」当作切换主分类。
 
 ###### 分类 · 稳定定位器速查
 
 | 控件 | 推荐定位器 |
 | --- | --- |
-| 展开主分类下拉 | `click` snapshot 顶栏左侧主分类块（当前主分类名 + 箭头）；勿与标签条同名项混淆 |
-| 主分类菜单项 | 展开后 `getByText('<目标主分类>', { exact: true })` |
+| 展开主分类下拉 | `click` snapshot 顶栏左侧主分类块（当前显示名 + 箭头） |
+| 主分类菜单项 | 展开后 `getByText('<目标主分类>', { exact: true })`（7 项之一） |
 | 子分类标签 | 搜索框下方 `getByText('<子分类名>', { exact: true })` |
 | 拼图工具 Tab | `getByText('拼图工具', { exact: true })` |
 | 标签条展开/收起 | `getByText('展开', { exact: true })` / `getByText('收起', { exact: true })` |
@@ -679,7 +697,7 @@ helixlife-v5-cli run-code --filename=scripts/analysis-detail-upload-file.js
 | # | 语义 | 推荐操作 | 验收 / 备注 |
 | --- | --- | --- | --- |
 | 1 | **全局设置**（顶区右侧文案按钮） | `click` → `locator('main').getByText('全局设置')`（必须加 `main`） | 出现 `dialog`，可访问名为 `全局设置`。弹窗内可见「配色方案」「全局字体」「颜色面板」三块：配色为下拉 + 预览色块（示例 `NPG方案`）；全局字体、颜色面板各带 `combobox`（示例 `Arial`、`随机颜色`）。底部 button：「重置」「保存」。关闭：`click` → `getByRole('dialog', { name: '全局设置' }).getByRole('button', { name: 'Close' })` |
-| 2 | **顶区 · 主分类下拉** | `click` 顶栏当前主分类名展开菜单 → `click` → `getByText('<主分类名>', { exact: true })`。默认项为「分析工具」；选中后顶栏文案变为该主分类名（如「交互网络」） | URL `primary=` 变化；顶栏文案更新。细则见「分类体系 · Agent 决策树」 |
+| 2 | **顶区 · 主分类下拉** | `click` 顶栏当前主分类块展开菜单 → `click` → `getByText('<主分类名>', { exact: true })`。主分类**仅**为固定 7 项：全部工具、基础绘图、表达差异、功能聚类、交互网络、临床意义、其他 | URL `primary=` 变化；顶栏文案更新为目标主分类名。细则见「分类体系 · Agent 决策树」 |
 | 3 | **顶区 · 形态 Tab：拼图工具** | `click` → `getByText('拼图工具', { exact: true })`；从拼图回列表：`click` → `getByText('分析工具', { exact: true })` 或 `div.side-menu--item[to='/analysis']` | 拼图：`pathname === '/analysis/jigsaw'`，`title` 以 `拼图工具-` 开头。列表：`pathname` 为 `/analysis`/`/analysis/`，`title` 以 `数据分析-` 开头 |
 | 4 | **搜索（找工具，非切主分类）** | `fill` → `getByRole('textbox', { name: '请输入搜索关键词' })`；`click` → `getByRole('button', { name: '搜索' })` | 列表随关键字刷新（以 `snapshot`/卡片集合变化验收）。**勿**用搜索代替主分类切换 |
 | 5 | **子分类标签 + 展开 / 收起** | 搜索框下方为**子分类**可点文案（如「全部」「类别比较」「差异分析」「网络图相关」…），**仅在当前主分类下生效**。分类行右侧「展开」/「收起」：`click` → `getByText('展开', { exact: true })` → URL 中 `isExpanded=true`；再点 `getByText('收起', { exact: true })` → `isExpanded=false` | URL `subcategory=` / `isExpanded` 与选中标签、展开态一致 |
@@ -1052,8 +1070,8 @@ async page => {
 3. **（可选）形态 Tab**：`click` → `getByText('拼图工具', { exact: true })` → 验收 `/analysis/jigsaw`。回列表优先 `click` → `div.side-menu--item[to='/analysis']` 或顶栏主分类「分析工具」。
 4. **（可选）搜索**：`fill` → `getByRole('textbox', { name: '请输入搜索关键词' })` → `click` → `getByRole('button', { name: '搜索' })`（找工具，非切主分类）。
 5. **（可选）切换分类**（细则见「分类体系 · Agent 决策树」）：
-   - **子分类**：`click` 标签条文案 → 验收 `subcategory=`；按需点「展开」/「收起」验收 `isExpanded`。
-   - **主分类**：`click` 顶栏当前主分类名展开下拉 → `click` 目标 → 验收 `primary=` 且顶栏文案更新；**清空搜索框残留**后再验收列表。
+   - **主分类（优先）**：目标名命中 7 项枚举 → 展开顶栏下拉 → `click` 目标 → 验收 `primary=` 且顶栏文案更新；**清空搜索框残留**后再验收列表。
+   - **子分类（仅当未命中 7 项）**：`click` 标签条文案 → 验收 `subcategory=`；按需点「展开」/「收起」验收 `isExpanded`。
 6. **（可选）收藏/取消收藏**：目标卡片上 `click` → `收藏` → 验收 `已收藏`；再 `click` → `已收藏` → 回 `收藏`。
 7. **进入某一工具详情**：`main` 内 `click` → `getByText('<卡片主标题>', { exact: true })`。验收 `pathname` 为 `/analysis/{toolId}`；面包屑「数据分析 / {工具名}」。后续 → S-28（D-1～D-11）。