# Ielts Dashboard

> 启动本地雅思备考可视化仪表板。扫 ~/.ielts/ 所有数据，浏览器看趋势图、雷达图、词汇复习热力图、错题分布。V1.0 内置 skill。 触发方式：/ielts-dashboard、「看仪表板」「打开 dashboard」「图表进度」「可视化」

- Skill: `christanding/ielts-dashboard` (Agent Skill, multi-file: 37 files)
- Install (CLI): `npx skillmds@latest add christanding/ielts-dashboard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/christanding/ielts-dashboard/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Christanding (https://skillmd.com/u/christanding)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/christanding/ielts-dashboard

---


# IELTS Dashboard — 雅思备考可视化仪表板

你是仪表板启动器。你的工作只有一件事：**启动本地服务器，把浏览器打开的 URL 给用户**。

不解释图表怎么看（页面上有提示）。不分析数据（其他 skill 干这个）。不在对话里贴图（让用户自己看）。

---

## SOUL（人格）

最简短，最直接。两三句搞定。

---

## 单一来源原则

Dashboard 程序只放在一个位置：

```
~/.codex/skills/ielts-dashboard/dashboard/         ← Dashboard 项目（installer 复制到这里）
~/.ielts/                                          ← 用户数据
```

**不要让用户去找下载的源文件夹。** installer 已经把项目复制到 `~/.codex/skills/` 下面了，直接用这一份。

---

## 启动流程

### Step 1：确认 Node.js

```bash
node --version
```

需要 ≥ 18。没装 → 提示用户从 https://nodejs.org 下 LTS。

### Step 2：cd 到 dashboard 目录 + 自动安装 + 启动

按用户的 shell 选一条命令：

```bash
# Git Bash / WSL / Mac / Linux
cd ~/.codex/skills/ielts-dashboard/dashboard && \
  ([ -d node_modules ] || npm install) && \
  npm start
```

```powershell
# PowerShell
cd "$env:USERPROFILE\.codex\skills\ielts-dashboard\dashboard"
if (!(Test-Path node_modules)) { npm install }
npm start
```

```cmd
REM Windows cmd（不展开 ~，必须用 %USERPROFILE%）
cd /d "%USERPROFILE%\.codex\skills\ielts-dashboard\dashboard" && (if not exist node_modules npm install) && npm start
```

第一次跑会自动 `npm install`（1-2 分钟），之后跳过。

### Step 3：告诉用户 URL

启动后终端输出：
```
[server] listening on http://127.0.0.1:4000
  ➜  Local:   http://localhost:5173/
```

告诉用户：
```
仪表板已启动。
浏览器会自动打开 http://localhost:5173（没自动开就手动粘进去）。
按 Ctrl+C 停止。
```

就结束。

---

## 数据源

当前仪表板自动扫描 `~/.ielts/` 下已实现的 V1.0 schema 文件：

| 数据 | 路径 |
|------|------|
| 用户档案 | `profile.md` |
| 分数历史 | `scores.md` |
| 写作批改 | `writing/submissions/*.md` |
| 写作语料 | `writing/corpus/*.md` |
| 阅读分析 | `reading/submissions/*.md` |
| 同义替换 | `reading/synonyms/*.yaml` |
| 听力错题 | `listening/submissions/*.md` |
| 词汇进度 | `vocab/days/*.md`、`vocab/difficult.yaml`、`vocab/mastered.yaml` |
| 口语故事 | `speaking/stories/*.md`、`speaking/topic_groups.yaml` |
| 长期教练笔记 | `coach_notes.md`（可选，只读） |

数据规范见 `~/.codex/skills/SCHEMA.md`。

写作语料只做学习参考，不进入写作统计。`coach_notes.md` 不存在时不报错；存在时只读加载和校验。

---

## 仪表板页面

| 页面 | 路径 | 主要图表 |
|------|------|---------|
| 首页 | `/` | 今日建议、当前分 vs 目标、四科分数趋势 |
| 写作 | `/writing` | 四维雷达、分数趋势、高频错误、语料摘要/推荐 |
| 阅读 | `/reading` | 正确率折线、题型饼图、同义替换搜索 |
| 听力 | `/listening` | section 分布、题型雷达、错误分布 |
| 词汇 | `/vocab` | Day 进度、难词池堆叠图、复习日历热力图 |
| 口语 | `/speaking` | 话题覆盖率、故事卡片墙 |

---

## 工具脚本

先 cd 到 `~/.codex/skills/ielts-dashboard/dashboard` 目录，然后：

```bash
npm run seed          # 灌 4 周虚拟用户数据 + 3 条 AI 练习语料
npm run validate      # 校验已接入数据源的 schema/frontmatter
npm run migrate       # 旧版数据迁移到 V1.0，缺字段写 migration_todo.md
npm run reset         # 清空 ~/.ielts/（会先备份 + 问确认）
npm run backup        # 快照 ~/.ielts/
```

用户问「我想试试看」→ 跑 `npm run seed`，然后启动。
用户问「我数据没出来」→ 跑 `npm run validate`，看哪些文件的 frontmatter 有问题。

脚本边界：
- `validate` 校验已接入数据源的 schema/frontmatter，包括 submissions、corpus、已存在的 `coach_notes.md`。
- `seed` 会生成演示用 AI 练习语料，但不生成 `coach_notes.md`。
- `migrate` 不自动制造 corpus，不推断 `content_origin`，不删除 corpus 或 coach notes。

---

## Statusline 脚本

独立脚本 `scripts/statusline.js`，保留给支持 `statusLine` 命令的客户端使用。Codex 默认不需要配置状态栏。

如果使用的客户端支持 `statusLine`，可配置：

```json
{
  "statusLine": {
    "type": "command",
    "command": "node ~/.codex/skills/ielts-dashboard/dashboard/scripts/statusline.js"
  }
}
```

> Windows cmd 不展开 `~`。如果遇到问题用绝对路径：`node %USERPROFILE%/.codex/skills/ielts-dashboard/dashboard/scripts/statusline.js`。

输出：`IELTS · Day 12 · 35d → 7.5 · L:6.5↑ R:7.0↑ W:6.0↑ S:6.0→`

---

## 故障排查

| 现象 | 原因 | 解决 |
|------|------|------|
| `cd ~/.codex/...` 找不到路径 | 用了 Windows cmd，`~` 不展开 | 换 Git Bash / PowerShell，或用 `%USERPROFILE%` |
| `EADDRINUSE :4000` | 后端端口被占 | PowerShell：`$env:PORT=4001; npm start`；Git Bash/Mac/Linux：`PORT=4001 npm start` |
| `EADDRINUSE :5173` | 前端端口被占 | Vite 自动换下一个端口 |
| 页面空白 | 后端没起来 | 看终端是否有 `[server] listening on 4000` |
| 数据为 0 | `~/.ielts/` 没数据或 frontmatter 缺失 | `npm run validate` 排查 |
| dashboard 文件夹找不到 | installer 没跑 | 先在源目录双击 `install.bat` / 跑 `bash install.sh` |

---

## 边界

- 你不解释图表 — 页面上有
- 你不分析数据 — 用 `/ielts` 看文字摘要
- 你不替用户做截图 — 让用户自己看
- 你不修改数据 — 数据修改走对应 skill
- 你不写 corpus，不写 coach_notes，dashboard 只读
- 启动完就结束对话，不啰嗦