doodle-mini/skills/update-age-config/SKILL.md

---
name: update-age-config
description: >-
    基于 cache/page-config.json 更新分龄页 age.config.ts 中的 AGE_ABILITIES 与
    AGE_WEEK_PLANS。在用户说「更新分龄页数据」「更新分龄config」「更新分龄学习计划」
    或同类表述时使用；每次执行须同时更新上述两个常量。
---

# Skill: update-age-config

> 一次性更新 `miniprogram/pages/age/age.config.ts` 中的 **`AGE_ABILITIES`** 与 **`AGE_WEEK_PLANS`**。

## 触发条件

当用户提到以下内容时**必须**使用本 Skill（不再使用已废弃的 `generate-age-abilities` / `generate-age-weekly-plans`）：

- 「更新分龄页数据」
- 「更新分龄 config」
- 「更新分龄学习计划」
- 含义相同的表述（更新分龄能力目标 + 周计划）

## 角色与范围

你是一位拥有 25 年经验的儿童早教专家，专注于 3-8 岁儿童的认知发展和学习能力培养。你需要基于当前系统中**已上线**的所有 worksheet（打印练习册）内容，为 **5 个固定年龄段**生成：

1. 精准的能力目标（`AGE_ABILITIES`）
2. 科学的 4 周学习路线（`AGE_WEEK_PLANS`）

**每次执行本 Skill，必须同时完成以上两部分**，不得只更新其一。

### 不可改动的约束

- **只修改** `AGE_ABILITIES` 与 `AGE_WEEK_PLANS` 两个常量的对象内容。
- **禁止修改**：`AGE_TAB_SUB`、类型定义、`age.ts` 逻辑、其他 export。
- 两个常量的 **key 必须且仅能**为以下 5 个（与 `AgeBandKey` 一致，顺序建议保持一致）：
    - `'3-4'`、`'4-5'`、`'5-6'`、`'6-7'`、`'7-8'`
- **禁止**新增、删除或重命名年龄段 key。

---

## Step 1：读取 worksheet 数据源

**唯一数据源（必须）：** `cache/page-config.json`（项目根目录下，非 `.cache`）。

1. 读取该文件；若不存在，提示用户先同步云存储到 `cache/page-config.json` 后重试，**不要**编造 worksheet。
2. 从 JSON 汇总全部 worksheet：
    - 优先遍历 `home.sections[].items[]`（按分类聚合的主列表）
    - 可对 `home.featured[]`、`home.hot[]` 做去重合并（以 `id` 为准，避免遗漏仅出现在推荐位的条目）
3. 从每个 item 提取：
    - `id`（写入周计划时作为 `_id`）
    - `title`、`subtitle`、`path`
    - `category`、`ageBand`、`difficulty`
    - 若有：`ageMin` / `ageMax`、`downloads`、`likes`

执行后**先向用户简报**：worksheet 总数、各 `category` 数量、各年龄段可匹配数量，请用户确认数据为最新。

### 年龄段匹配规则

数据源中 `ageBand` 多为「3-5岁」「4-6岁」等区间文案。映射到 config key 时：

- 使用 `core/data/difficulty.ts` 中 `AGE_BANDS` 的 `minAge` / `maxAge`
- 若 item 的适龄区间与某 `AgeBandKey` 有重叠，则归入该段（一条 worksheet 可属于多个年龄段）
- 无重叠时跳过，**不要**强行编造

### 分类体系（参考）

| category  | 含义     |
| --------- | -------- |
| `math`    | 数感启蒙 |
| `puzzle`  | 益智游戏 |
| `pinyin`  | 汉语拼音 |
| `chinese` | 识字练字 |
| `english` | 英语启蒙 |
| `craft`   | 创意手工 |

---

## Step 2：生成 `AGE_ABILITIES`

为每个年龄段生成 **3 个**核心能力维度（`AbilityItem[]`）。

### 生成原则

1. **基于实际内容**：必须反映该年龄段在数据源中**真实存在**的 worksheet，禁止空谈
2. **发展阶梯性**：5 个年龄段之间能力描述有明显递进
3. **具体可衡量**：落到可练习技能点，避免笼统
4. **简洁有力**：每个 `desc` ≤ 10 个汉字，顿号分隔 2–3 个技能点

### 能力维度选择参考（可按实际 worksheet 调整）

- 🔢 数感（数字认知、计算）
- ✏️ 书写（笔画、汉字、拼音书写）
- 🧩 思维（逻辑推理、空间想象、专注力）
- 🔤 语言（拼音、英语启蒙）
- 🎨 创造（手工、绘画，若该段有 craft 内容）

若某年龄段内容集中在特定领域，可调整维度名称以更贴合实际。

### 输出数据结构

```ts
export const AGE_ABILITIES: Record<AgeBandKey, AbilityItem[]> = {
    '3-4': [
        { icon: '🔢', title: '数感', desc: '认读 1-5、点数对应' },
        { icon: '✏️', title: '书写', desc: '涂鸦线条、简单描红' },
        { icon: '🧩', title: '思维', desc: '找相同、简单配对' },
    ],
    '4-5': [
        /* 3 项 */
    ],
    '5-6': [
        /* 3 项 */
    ],
    '6-7': [
        /* 3 项 */
    ],
    '7-8': [
        /* 3 项 */
    ],
};
```

### 能力目标验证

- [ ] 每个 key 下恰好 3 项
- [ ] `desc` 字数合规
- [ ] 五段递进合理
- [ ] `icon` 为合适 emoji
- [ ] 符合 `AbilityItem` 类型

---

## Step 3：生成 `AGE_WEEK_PLANS`

为每个年龄段设计 **4 周**学习计划（`WeekPlan[]`），每周 **3 个**练习（`WeekExercise`）。

### 编排原则

1. **由易到难**：第 1 周偏入门，逐周提升
2. **跨领域覆盖**：4 周合计覆盖该段可用的多个 `category`
3. **主题连贯**：每周有明确 `theme`（4–6 个汉字）
4. **基于实际内容**：每条练习必须来自数据源，**禁止**虚构 `_id` / `path`
5. **合理搭配**：每周 3 个练习尽量来自不同分类
6. **第 4 周综合**：综合巩固前 3 周核心技能

### 主题命名规范

- 4–6 个汉字，体现当周重点
- 示例：数感启蒙、形状与连线、趣味专注、综合练习、拼音入门

### worksheet 不足时

- 不足 12 条（4×3）时，允许同一条在不同周出现，但同一年龄段内尽量少重复
- 某段完全无匹配项时，可选用相邻年龄段且 **ageBand 最接近** 的真实条目，并在回复中说明
- 仍须使用数据源中的真实 `id` → `_id`、`title`、`subtitle`、`path`

### 选题优先级

在同一年龄段内，优先 `downloads + likes` 较高、难度与周次匹配的 worksheet。

### 输出数据结构

```ts
export type WeekExercise = {
    _id: string; // = 数据源 item.id
    title: string;
    subtitle: string;
    path: string; // 与数据源完全一致，可含 query
};

export const AGE_WEEK_PLANS: Record<AgeBandKey, WeekPlan[]> = {
    '3-4': [
        {
            week: 1,
            theme: '数感启蒙',
            exercises: [
                {
                    _id: 'number-find',
                    title: '找数字，涂一涂',
                    subtitle: '找出目标数字并涂色',
                    path: '/mathPages/mathDraw/mathDraw?id=number-find',
                },
                // 共 3 条
            ],
        },
        // week: 2, 3, 4
    ],
    // '4-5' … '7-8'
};
```

### 周计划数据规范

- 每个年龄段 **4** 个 `WeekPlan`，`week` 为 1–4
- 每个 `WeekPlan` **3** 个 `exercises`
- 四字段齐全：`_id`、`title`、`subtitle`、`path`
- `_id`、`path`、`subtitle` 与 `cache/page-config.json` **逐字一致**

### 周计划验证

- [ ] 结构：5 段 × 4 周 × 3 练习 = 60 条
- [ ] 抽查 `_id` / `path` 可在数据源中找到
- [ ] 难度与年龄段匹配
- [ ] 同段跨周尽量少重复同一 `_id`
- [ ] 符合 `WeekPlan` / `WeekExercise` 类型

---

## Step 4：写入 `age.config.ts`

1. 读取 `miniprogram/pages/age/age.config.ts`
2. **仅替换** `AGE_ABILITIES`、`AGE_WEEK_PLANS` 两个常量的完整对象字面量
3. 保持文件其余部分不变（import、类型、注释风格与周边代码一致）
4. 勿改动 `AGE_WEEK_PLANS` 上方关于数据源的注释含义，可将 `.cache` 字样改为 `cache/page-config.json`（若仍存在旧路径描述）

---

## Step 5：交付说明

完成后用中文简要汇报：

- 数据源 worksheet 数量
- 各年龄段入选周计划条数
- 能力目标是否有维度调整（相对旧版）
- 是否有个别年龄段 worksheet 不足及处理方式

---

## 相关文件

| 文件                                  | 说明                       |
| ------------------------------------- | -------------------------- |
| `cache/page-config.json`              | **唯一** worksheet 数据源  |
| `miniprogram/pages/age/age.config.ts` | 写入目标                   |
| `miniprogram/pages/age/age.ts`        | 分龄页引用（只读）         |
| `miniprogram/core/data/difficulty.ts` | `AGE_BANDS` / `AgeBandKey` |
| `miniprogram/core/data/categories.ts` | 分类定义                   |
| `docs/分龄页内容管理方案.md`          | 方案文档（若有）           |

## 已废弃 Skill（勿再使用）

- `skills/generate-age-abilities/` → 已合并至本 Skill
- `skills/generate-age-weekly-plans/` → 已合并至本 Skill