vibeglish 0.1.0

package/vibeglish-prd.md

@@ -0,0 +1,591 @@
+# VibeGlish — 在 Vibe Coding 中自然习得英语
+
+> 把你每天跟 Claude Code 说的"蹩脚英语"变成最好的学习素材
+
+---
+
+## 一、产品概述
+
+### 核心洞察
+
+开发者每天跟 Claude Code 用英语对话几十上百次，这些 prompt 是真实的、高频的、有上下文的英语输出——远比任何教材的例句更贴近你自己的表达习惯。但这些"蹩脚英语"说完就忘了，从未被系统性地利用。
+
+### 产品定义
+
+VibeGlish 是一个由 Claude Code Hook 驱动的**被动式英语学习系统**。它静默记录你发给 Claude Code 的每条 prompt，定期批量调用 AI 进行语法纠正与分析，最终通过一个本地 Web Dashboard 呈现你的英语成长轨迹。
+
+### 设计哲学
+
+- **零打扰**：采集阶段完全静默，不中断编码心流
+- **后置学习**：攒够素材后统一复习，而非实时打断纠错
+- **游戏化**：用数据可视化和成就系统让复习不枯燥
+- **开发者友好**：所有数据本地存储，CLI 优先，一切可 hack
+
+---
+
+## 二、用户画像与场景
+
+### 目标用户
+
+中国开发者（或其他非英语母语开发者），日常使用 Claude Code 进行开发，英语水平大致在 CEFR B1-B2 之间——能表达意图但存在系统性语法问题。
+
+### 典型场景
+
+| 场景 | 描述 |
+|------|------|
+| 日常编码 | 用户正常用英语跟 Claude Code 对话，完全不需要意识到 VibeGlish 的存在 |
+| 午休/下班复习 | 打开 Dashboard 查看今天的 prompt 被纠正后的样子，花 5-10 分钟快速浏览 |
+| 周末回顾 | 查看一周的统计报告，发现自己反复犯的错误类型 |
+| 长期成长 | 翻看几个月前的记录，发现当时的错误现在已经不犯了 |
+
+---
+
+## 三、系统架构
+
+### 3.1 整体数据流
+
+```
+┌──────────────┐    UserPromptSubmit     ┌─────────────────┐
+│  你输入 prompt │ ─────── Hook ────────▶ │  capture.sh      │
+│  (Claude Code) │                        │  写入 JSONL 日志  │
+└──────────────┘                         └────────┬────────┘
+                                                  │
+                                                  ▼
+                                         ~/.vibeglish/raw/
+                                         2026-04-03.jsonl
+                                                  │
+                         ┌────────────────────────┤
+                         │ CLI: vibeglish review   │
+                         │ (手动触发 or cron)       │
+                         └────────────────────────┘
+                                                  │
+                                   调用 Anthropic API
+                                   批量纠正 + 分析
+                                                  │
+                                                  ▼
+                                         ~/.vibeglish/reviewed/
+                                         2026-04-03.json
+                                                  │
+                                                  ▼
+                                      ┌───────────────────┐
+                                      │  本地 Web Dashboard │
+                                      │  vibeglish serve   │
+                                      └───────────────────┘
+```
+
+### 3.2 技术选型
+
+| 组件 | 技术 | 理由 |
+|------|------|------|
+| Hook 脚本 | Bash + jq | 极轻量，无需额外运行时依赖 |
+| 原始日志 | JSONL 文件（按天分片） | 追加写入性能最佳，无需数据库 |
+| AI 纠正引擎 | Anthropic Messages API (claude-sonnet-4-20250514) | 成本低、速度快、质量足够 |
+| 复习数据 | JSON 文件（按天分片） | 与原始日志一一对应，方便管理 |
+| Dashboard | 单文件 HTML + 内嵌 JS（由本地 HTTP server 提供） | 零前端构建依赖，一个 `python -m http.server` 即可 |
+| CLI 工具 | Node.js 单文件脚本 | 与 Claude Code 生态一致，用户大概率已装 Node |
+
+---
+
+## 四、功能模块详细设计
+
+### 4.1 模块一：静默采集（Hook）
+
+#### 4.1.1 Hook 配置
+
+在 `~/.claude/settings.json` 中注册 `UserPromptSubmit` hook：
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.vibeglish/hooks/capture.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+#### 4.1.2 capture.sh 行为
+
+脚本从 stdin 读取 JSON，提取用户 prompt 内容，追加写入日志文件。
+
+**输入格式**（由 Claude Code 通过 stdin 传入）：
+
+```json
+{
+  "session_id": "abc123",
+  "prompt": "help me fix the drift sync issue, it failed when offline",
+  "cwd": "/Users/jian/projects/tapdoki"
+}
+```
+
+**输出格式**（追加到 `~/.vibeglish/raw/2026-04-03.jsonl`）：
+
+```json
+{
+  "ts": "2026-04-03T14:32:01+08:00",
+  "session_id": "abc123",
+  "project": "tapdoki",
+  "prompt": "help me fix the drift sync issue, it failed when offline",
+  "char_count": 54,
+  "word_count": 10
+}
+```
+
+#### 4.1.3 过滤规则
+
+不是所有 prompt 都值得纠正。capture.sh 需要在写入前过滤：
+
+| 过滤条件 | 规则 | 理由 |
+|----------|------|------|
+| 纯代码粘贴 | 如果 prompt 中代码块（被 ``` 包裹的内容或缩进 4 格的行）占比 > 70%，跳过 | 代码不是英语学习素材 |
+| 过短 | word_count < 4 | "yes" "ok" "run it" 没有纠正价值 |
+| 纯中文 | 不包含任何 ASCII 字母 | 不属于英语练习 |
+| Slash command | 以 `/` 开头 | 这是 Claude Code 内置命令 |
+| 文件路径粘贴 | 整条 prompt 匹配路径模式（如纯 `/path/to/file`） | 无英语内容 |
+| 重复 | 与同一 session 内上一条完全相同 | 避免重试造成的重复记录 |
+
+#### 4.1.4 性能约束
+
+- capture.sh 必须在 **50ms 以内**完成，否则会拖慢 Claude Code 的响应
+- 仅做 I/O 追加写入，不做任何网络请求
+- 如果写入失败（磁盘满等），静默失败（exit 0），绝不阻塞 Claude Code
+
+#### 4.1.5 边缘情况
+
+| 情况 | 处理方式 |
+|------|----------|
+| 日志文件不存在 | 自动创建，包含日期目录 |
+| 磁盘满 | 捕获写入错误，静默退出 |
+| stdin 不是合法 JSON | 跳过，写入错误日志 `~/.vibeglish/error.log` |
+| prompt 字段缺失 | 跳过 |
+| 混合中英文 prompt | **保留**——这是真实场景，AI 纠正时会单独处理英语部分 |
+| 包含敏感信息（API key 等） | 不做脱敏——所有数据仅本地存储，后续 AI 调用用用户自己的 API key |
+| 并发写入（多个 Claude Code 实例） | 使用 `flock` 文件锁保证 JSONL 追加原子性 |
+| 跨天切换（午夜） | 以 prompt 发生时的本地日期为准分片 |
+
+---
+
+### 4.2 模块二：AI 批量纠正引擎
+
+#### 4.2.1 触发方式
+
+```bash
+# 纠正今天的记录
+vibeglish review
+
+# 纠正指定日期
+vibeglish review --date 2026-04-01
+
+# 纠正一个日期范围
+vibeglish review --from 2026-03-25 --to 2026-04-03
+
+# 仅纠正尚未处理的记录（默认行为）
+vibeglish review  # 自动跳过 reviewed/ 中已存在的日期
+```
+
+#### 4.2.2 Prompt 工程
+
+向 API 发送的 system prompt：
+
+```
+You are an English writing coach for non-native developers. You will receive
+a batch of prompts that a Chinese developer wrote to an AI coding assistant.
+
+For each prompt, provide:
+1. "corrected": The natural, idiomatic English version. Preserve technical
+   terms exactly. If the original mixes Chinese and English, only correct
+   the English parts and leave Chinese as-is.
+2. "issues": An array of specific corrections, each with:
+   - "type": one of "grammar", "vocabulary", "spelling", "punctuation",
+     "style", "word_order"
+   - "original": the problematic fragment (quote from original)
+   - "corrected": the fixed fragment
+   - "rule": a concise explanation in CHINESE (学习者的母语) so the
+     developer actually absorbs it. Use grammatical terminology sparingly.
+3. "score": 0-100 fluency score for the original. 100 = native-level.
+   Scoring rubric:
+   - 90-100: Minor style issues only
+   - 70-89: Understandable but has noticeable errors
+   - 50-69: Meaning is clear but grammar is systematically broken
+   - 30-49: Requires effort to understand
+   - 0-29: Largely incomprehensible
+4. "is_clean": boolean, true if no corrections needed (score >= 95)
+
+If a prompt is just a code snippet, a file path, or not meaningfully English,
+return {"skip": true} for that entry.
+
+Respond with a JSON array matching the input order. No markdown fences.
+```
+
+#### 4.2.3 批处理策略
+
+| 参数 | 值 | 理由 |
+|------|-----|------|
+| 每批大小 | 20 条 prompt | 平衡 token 用量与 API 调用次数 |
+| 并发数 | 3 | 避免触发 rate limit |
+| 模型 | claude-sonnet-4-20250514 | 性价比最优 |
+| max_tokens | 4096 | 20 条的纠正结果通常在 2000-3000 tokens |
+| temperature | 0 | 纠正任务需要确定性 |
+
+#### 4.2.4 输出格式
+
+写入 `~/.vibeglish/reviewed/2026-04-03.json`：
+
+```json
+{
+  "date": "2026-04-03",
+  "reviewed_at": "2026-04-03T22:15:00+08:00",
+  "model": "claude-sonnet-4-20250514",
+  "stats": {
+    "total_captured": 47,
+    "total_reviewed": 38,
+    "skipped": 9,
+    "avg_score": 61.3,
+    "issue_breakdown": {
+      "grammar": 42,
+      "vocabulary": 11,
+      "spelling": 3,
+      "punctuation": 8,
+      "style": 15,
+      "word_order": 5
+    }
+  },
+  "entries": [
+    {
+      "id": "20260403-143201-a1b2",
+      "ts": "2026-04-03T14:32:01+08:00",
+      "project": "tapdoki",
+      "original": "help me fix the drift sync issue, it failed when offline",
+      "corrected": "Help me fix the Drift sync issue — it fails when the device is offline.",
+      "score": 62,
+      "is_clean": false,
+      "issues": [
+        {
+          "type": "grammar",
+          "original": "it failed",
+          "corrected": "it fails",
+          "rule": "描述一个反复出现的问题用一般现在时，不用过去时"
+        },
+        {
+          "type": "grammar",
+          "original": "when offline",
+          "corrected": "when the device is offline",
+          "rule": "offline 是形容词，需要主语和系动词：the device is offline"
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### 4.2.5 成本估算
+
+| 场景 | 日 prompt 数 | 估算 input tokens | 估算 output tokens | 日均成本 (Sonnet) |
+|------|-------------|-------------------|--------------------|--------------------|
+| 轻度使用 | 30 | ~3,000 | ~4,500 | ~$0.03 |
+| 中度使用 | 80 | ~8,000 | ~12,000 | ~$0.08 |
+| 重度使用 | 200 | ~20,000 | ~30,000 | ~$0.20 |
+
+#### 4.2.6 边缘情况
+
+| 情况 | 处理方式 |
+|------|----------|
+| API key 未配置 | 清晰报错，引导用户设置 `ANTHROPIC_API_KEY` 环境变量 |
+| API 调用失败（网络/rate limit） | 指数退避重试 3 次，最终失败的批次标记为 `"status": "failed"`，下次 review 可重试 |
+| API 返回非法 JSON | 尝试修复（去 markdown 围栏、修复尾部截断），若仍失败则标记该批次为 failed |
+| 单条 prompt 极长（>2000 字） | 截断至前 500 词并标注 `"truncated": true` |
+| 同一天重复 review | 默认跳过已 reviewed 的日期，加 `--force` 覆盖 |
+| 原始文件正在被 hook 追加写入 | review 命令先复制一份快照再处理，避免读写冲突 |
+| AI 返回的数组长度与输入不匹配 | 通过 id 做 fallback 匹配，无法匹配的标记 `"review_status": "mismatch"` |
+
+---
+
+### 4.3 模块三：CLI 工具
+
+#### 4.3.1 命令列表
+
+```bash
+vibeglish init          # 初始化目录结构 + 安装 hook
+vibeglish status        # 显示今日采集数/待 review 数/总计数
+vibeglish review        # 触发 AI 纠正（参数见 4.2.1）
+vibeglish report        # 在终端打印统计摘要
+vibeglish serve         # 启动本地 Dashboard（默认 localhost:6188）
+vibeglish export        # 导出全部数据为单个 JSON 或 CSV
+vibeglish hook-test     # 模拟一条 prompt 输入，测试 hook 是否正常工作
+vibeglish uninstall     # 移除 hook 配置（保留数据）
+```
+
+#### 4.3.2 `vibeglish init` 详细流程
+
+1. 创建目录结构：
+   ```
+   ~/.vibeglish/
+   ├── raw/              # 原始 JSONL 日志
+   ├── reviewed/         # AI 纠正结果
+   ├── hooks/            # hook 脚本
+   │   └── capture.sh
+   ├── dashboard/        # 静态 Web 文件
+   │   └── index.html
+   ├── config.json       # 用户配置
+   └── error.log         # 错误日志
+   ```
+
+2. 生成 `capture.sh` 并设置 `chmod +x`
+
+3. 读取 `~/.claude/settings.json`：
+   - 如果文件不存在 → 创建并写入 hook 配置
+   - 如果文件存在但无 `hooks` 字段 → 追加
+   - 如果已有 `UserPromptSubmit` hook → **不覆盖**，提示用户手动合并，并输出需要添加的配置片段
+   - 如果已有 VibeGlish 的 hook → 提示已安装，跳过
+
+4. 输出安装成功信息及快速使用指引
+
+#### 4.3.3 `vibeglish report` 终端输出示例
+
+```
+📊 VibeGlish Weekly Report (Mar 28 - Apr 03)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Prompts captured:  287
+  Prompts reviewed:  263  (24 skipped)
+  Average score:     64.2  ▲ +3.1 vs last week
+
+  🔥 Top 3 recurring mistakes:
+  ┌──────────────────────────────────────────────────────┐
+  │ 1. 冠词缺失 (a/the)              37 次  ████████░░ │
+  │ 2. 时态错误 (现在时 vs 过去时)     24 次  █████░░░░░ │
+  │ 3. 主谓一致                       18 次  ████░░░░░░ │
+  └──────────────────────────────────────────────────────┘
+
+  💎 Clean prompts (score ≥ 95):  31 / 263 (11.8%)
+
+  📈 Score trend:
+  Mon  ██████░░░░  58
+  Tue  ███████░░░  65
+  Wed  ██████░░░░  61
+  Thu  ███████░░░  67
+  Fri  ████████░░  72  ← best day!
+
+  🏆 Achievements unlocked this week:
+     "Article Apprentice" — 连续 3 天冠词错误 < 5 次
+```
+
+#### 4.3.4 config.json 默认值
+
+```json
+{
+  "api_key_env": "ANTHROPIC_API_KEY",
+  "model": "claude-sonnet-4-20250514",
+  "locale": "zh-CN",
+  "min_word_count": 4,
+  "max_code_ratio": 0.7,
+  "batch_size": 20,
+  "concurrency": 3,
+  "dashboard_port": 6188,
+  "auto_review_cron": null,
+  "score_explanation_language": "zh-CN"
+}
+```
+
+---
+
+### 4.4 模块四：Web Dashboard
+
+#### 4.4.1 技术方案
+
+单个 `index.html` 文件，内嵌 CSS 和 JS，不依赖构建工具。通过 `vibeglish serve` 启动一个静态文件服务器 + 简易 API 代理（读取 `~/.vibeglish/reviewed/` 下的 JSON 文件）。
+
+#### 4.4.2 页面结构
+
+**页面一：Today（默认首页）**
+
+- 顶部大数字：今日得分（均值）、今日 prompt 数、clean prompt 占比
+- 时间线视图：按时间排列今天的每条 prompt
+  - 每条展示：原文 → 纠正后（diff 高亮）→ 错误详情（折叠）
+  - 点击可展开看每个 issue 的中文解释
+  - 左侧彩色竖条表示 score（绿 > 80，黄 60-80，红 < 60）
+- 底部：今日错误类型分布饼图
+
+**页面二：Trends（成长曲线）**
+
+- 主图：每日平均 score 折线图（可切换周/月/全部）
+- 副图：每日 prompt 数量柱状图
+- 错误类型堆叠面积图：展示各类错误随时间的变化趋势
+- "已消灭的错误"列表：曾经频繁出现但最近 30 天不再出现的错误类型
+
+**页面三：Mistakes（错题本）**
+
+- 按错误类型分 tab：grammar / vocabulary / spelling / punctuation / style / word_order
+- 每种类型下按频次排序展示：
+  - 错误模式（如"missing article before noun"）
+  - 出现次数及趋势迷你图
+  - 最近 3 个真实例句（original → corrected）
+- 支持搜索：按关键词搜索原始 prompt
+
+**页面四：Achievements（成就系统）**
+
+- 成就卡片墙，每个成就包含：图标、标题、描述、解锁条件、解锁时间
+- 已解锁的亮色显示，未解锁的灰色 + 进度条
+
+#### 4.4.3 成就系统设计
+
+| 成就名 | 条件 | 图标意象 |
+|--------|------|----------|
+| First Blood | 完成第一次 review | 🩸 |
+| Grammar Guru | 连续 7 天 grammar 类错误 ≤ 2 次/天 | 📐 |
+| Article Apprentice | 连续 3 天无冠词错误 | 🎓 |
+| Streak Master (×N) | 连续 N 天有记录（7/30/100） | 🔥 |
+| Century Club | 累计 review 100 条 prompt | 💯 |
+| Thousand Words | 累计 review 1000 条 prompt | 📚 |
+| Clean Coder | 单日 clean prompt 占比 > 50% | ✨ |
+| Perfect Day | 单日全部 prompt score ≥ 90 | 💎 |
+| Polyglot | 在 5 个不同 project 中留下记录 | 🌍 |
+| Night Owl | 凌晨 0-5 点仍在 coding 并留下 prompt | 🦉 |
+| Speed Learner | 某错误类型周频次从 >10 降至 <3 | ⚡ |
+| Vocabulary Voyager | 使用过 50 个不同的技术词汇 | 🧭 |
+
+#### 4.4.4 Diff 高亮规则
+
+原文与纠正后文本的对比展示：
+
+- 使用字符级 diff 算法（类似 `git diff --word-diff`）
+- 删除部分：红色背景 + 删除线
+- 新增部分：绿色背景
+- 未变化部分：正常显示
+- 中文部分：灰色显示，不参与 diff
+
+#### 4.4.5 Dashboard 边缘情况
+
+| 情况 | 处理方式 |
+|------|----------|
+| 无任何数据 | 显示友好的空状态引导页："开始用 Claude Code 写代码吧！" |
+| 只有 raw 没有 reviewed | 提示运行 `vibeglish review` |
+| 数据量极大（半年+） | 前端分页加载，Trends 页面默认只展示最近 30 天 |
+| 端口被占用 | 自动尝试 6189、6190...直到找到可用端口 |
+| 浏览器不支持某些 CSS 特性 | 使用渐进增强，核心功能不依赖现代 CSS |
+
+---
+
+## 五、安装与卸载
+
+### 5.1 安装
+
+```bash
+# 方式一：npx 直接运行（推荐）
+npx vibeglish init
+
+# 方式二：全局安装
+npm install -g vibeglish
+vibeglish init
+```
+
+`vibeglish init` 执行完毕后，用户需要**重启 Claude Code**（或新开一个 session）使 hook 生效。init 命令应在最后明确提示这一点。
+
+### 5.2 卸载
+
+```bash
+vibeglish uninstall
+```
+
+行为：
+- 从 `~/.claude/settings.json` 中移除 VibeGlish 的 hook 条目
+- **不删除** `~/.vibeglish/` 目录（保留用户数据）
+- 提示用户如需彻底删除数据，手动 `rm -rf ~/.vibeglish`
+
+### 5.3 升级
+
+```bash
+npm update -g vibeglish
+vibeglish init --upgrade  # 更新 hook 脚本和 dashboard，不影响数据
+```
+
+---
+
+## 六、数据安全与隐私
+
+| 关切 | 处理 |
+|------|------|
+| Prompt 可能包含敏感代码 | 所有数据仅存储在本地 `~/.vibeglish/`，不上传任何第三方服务 |
+| AI 纠正需调用 API | 使用用户自己的 Anthropic API key，走标准 API 通道 |
+| prompt 中的 API key/密码 | capture.sh 对明显的 secret 模式做基础脱敏（`sk-***`, `ghp_***` 等替换为 `[REDACTED]`） |
+| `.vibeglish` 目录权限 | init 时设为 `700`（仅用户可读写） |
+| git 忽略 | init 时不操作 `.gitignore`（因为数据在 home 目录，不在 repo 中） |
+
+---
+
+## 七、后续扩展方向（v2 及以后）
+
+以下功能**不在 MVP 范围内**，但架构设计时需预留空间：
+
+1. **实时模式（可选）**：通过 `UserPromptSubmit` hook 返回 `additionalContext`，在 Claude Code 的上下文中注入上一条 prompt 的纠正结果，让 Claude 在回复中顺带纠正你的英语（需用户主动开启，有延迟代价）
+
+2. **Anki 导出**：将高频错误模式导出为 Anki 卡片（正面：错误句，背面：纠正 + 解释）
+
+3. **团队排行榜**：团队成员的匿名化 score 排行（需后端服务，离 MVP 很远）
+
+4. **VS Code 侧边栏**：如果用户使用 Claude Code 的 VS Code 扩展，可以做一个侧边栏面板显示实时纠正
+
+5. **自定义纠正重点**：用户可配置"我想重点关注冠词"或"忽略标点问题"
+
+6. **语音输入分析**：如果未来 Claude Code 支持语音输入，可扩展到发音建议
+
+---
+
+## 八、验收标准（Definition of Done）
+
+### MVP 完成的定义
+
+- [ ] `vibeglish init` 可在 macOS/Linux 上一键完成安装
+- [ ] Hook 正确触发并写入 JSONL，不影响 Claude Code 响应速度（< 50ms）
+- [ ] `vibeglish review` 可批量纠正，输出结构化 JSON
+- [ ] `vibeglish serve` 可启动 Dashboard，Today/Trends/Mistakes 三个核心页面可用
+- [ ] `vibeglish report` 可在终端输出周报摘要
+- [ ] 成就系统至少实现 6 个成就
+- [ ] 所有边缘情况有合理处理（不崩溃、有友好提示）
+- [ ] README 包含安装指引、截图、和一个 2 分钟上手流程
+
+### 不在 MVP 范围内
+
+- Windows 支持（Hook 脚本是 bash）
+- 多语言 Dashboard UI（MVP 只做中文）
+- 自动定时 review（用户手动触发或自行配 cron）
+- 任何需要后端服务/数据库的功能
+
+---
+
+## 九、开发提示（给 Claude Code 的 CLAUDE.md 建议）
+
+将以下内容放入项目的 `CLAUDE.md`，帮助 Claude Code 理解项目上下文：
+
+```markdown
+# VibeGlish
+
+一个 Claude Code Hook 驱动的英语学习工具。
+
+## 架构
+- `src/hooks/capture.sh` — UserPromptSubmit hook，写入 ~/.vibeglish/raw/
+- `src/cli/index.mjs` — CLI 入口，子命令：init/review/report/serve/export
+- `src/review/engine.mjs` — Anthropic API 批量纠正引擎
+- `src/dashboard/index.html` — 单文件 Web Dashboard
+- `src/achievements.mjs` — 成就系统计算逻辑
+
+## 约束
+- capture.sh 必须 < 50ms 完成，不做网络请求
+- Dashboard 是单个 HTML 文件，不用框架，不用构建工具
+- 所有数据存储在 ~/.vibeglish/，不用数据库
+- CLI 用 Node.js ESM，最低支持 Node 18
+- API 调用用 claude-sonnet-4-20250514
+
+## 测试
+- `npm test` 运行全部测试
+- hook 测试用 `echo '{"prompt":"test"}' | bash src/hooks/capture.sh`
+- API 测试用 mock，不实际调用
+```