English OS

为程序员设计的英语学习工具。核心能力是将英文文本解析为「结构化理解」，用「谁 + 做什么 + 对什么 + 状态/条件」的逻辑方式帮助零基础用户理解英语。

项目结构

englishOS/
├── os-admin/        # 后端 API (Node.js + Express + Prisma)
├── os-home/         # 前端应用 (Nuxt 3)
└── openspec/        # 规格文档

快速开始

前置条件

• Node.js 18+
• MySQL 8.0+
• DeepSeek API Key

1. 克隆项目

git clone <repository-url>
cd englishOS

2. 配置后端

cd os-admin

# 安装依赖
npm install

# 复制环境变量配置
cp .env.example .env

# 编辑 .env 文件，配置以下内容：
# - DATABASE_URL: MySQL 连接字符串
# - JWT_SECRET: JWT 密钥
# - DEEPSEEK_API_KEY: DeepSeek API 密钥

# 生成 Prisma Client
npm run db:generate

# 同步数据库结构
npm run db:push

# 启动开发服务器
npm run dev

3. 配置前端

cd os-home

# 安装依赖
npm install

# 复制环境变量配置（可选，默认连接 localhost:3001）
cp .env.example .env

# 启动开发服务器
npm run dev

4. 访问应用

• 前端: http://localhost:3000
• 后端 API: http://localhost:3001

技术栈

后端

• Node.js + Express
• TypeScript
• Prisma ORM
• MySQL
• JWT 认证
• DeepSeek API

前端

• Nuxt 3
• Vue 3 Composition API
• Pinia 状态管理
• TailwindCSS

---

API 端点

认证模块 /api/auth

Method	Path	Description	Auth
POST	/api/auth/register	用户注册	No
POST	/api/auth/login	用户登录	No
GET	/api/auth/me	获取当前用户信息	Yes

句子解析模块 /api/parse

Method	Path	Description	Auth
POST	/api/parse	解析英文句子（结构 + 思维路径）	Yes
POST	/api/parse/complete	统一完整解析（结构 + 思维 + 简化 + 表达）	Yes

POST /api/parse 请求体：

{
  "text": "英文句子",
  "simplifyLevel": "both"  // 可选: both / simple / normal / none
}

POST /api/parse/complete 请求体：

{
  "text": "英文句子"
}

思维路径模块 /api/explain

Method	Path	Description	Auth
POST	/api/explain	解释英语句子的信息展开顺序	Yes

响应示例：

{
  "inputText": "This feature is deprecated.",
  "explanation": "句子先说'这个'(This)，再说'特性'(feature)，最后说'状态是过时的'(is deprecated)。英语习惯先明确主语，再给出判断。",
  "keyInsight": "英语先说'谁'，再说'是什么状态'"
}

表达提取模块 /api/extract

Method	Path	Description	Auth
POST	/api/extract	从句子中提取可复用的英语表达	Yes

响应示例：

{
  "inputText": "This feature is deprecated.",
  "expressions": [
    { "expression": "is deprecated", "meaning": "已弃用、不再推荐使用" }
  ]
}

历史记录模块 /api/history

Method	Path	Description	Auth
GET	/api/history	获取解析历史（分页）	Yes
GET	/api/history/:id	获取单条历史详情	Yes
DELETE	/api/history/:id	删除历史记录	Yes

GET /api/history 查询参数：

• page: 页码（默认 1）
• limit: 每页条数（默认 20，最大 100）

ASR 发音检测模块 /api/asr

Method	Path	Description	Auth
POST	/api/asr/check	ASR 对齐检查（判断发音是否可理解）	Yes
POST	/api/asr/calibration-trigger	校准触发决策（是否需要进入音标模式）	Yes

POST /api/asr/check 请求体：

{
  "expectedText": "This feature is deprecated.",
  "asrText": "This future is deprecated."
}

响应示例：

{
  "understandable": false,
  "problematicWords": ["feature"],
  "briefReason": "该词发音不清，被识别为 'future'，可能影响理解"
}

POST /api/asr/calibration-trigger 请求体：

{
  "problematicWords": ["feature", "deprecated"],
  "repeatCount": true
}

响应示例：

{
  "needCalibration": true,
  "reason": "该单词多次发音不清，已影响系统理解"
}

音素定位模块 /api/phoneme

Method	Path	Description	Auth
POST	/api/phoneme/localize	音素级问题定位（定位发音难点）	Yes

POST /api/phoneme/localize 请求体：

{
  "word": "feature",
  "asrText": "future",
  "expectedWord": "feature"
}

响应示例：

{
  "problematicSound": "长元音",
  "explanation": "该词包含 /iː/ 长元音，与中文发音习惯不同，容易被读短或混淆为其他元音"
}

系统端点

Method	Path	Description	Auth
GET	/api/health	健康检查	No

---

解析结果格式

基础解析结果

{
  "subject": "谁",
  "action": "核心动作",
  "object": "动作对象（可为 null）",
  "context": "补充信息（可为 null）",
  "sentenceType": "陈述 / 请求 / 解释 / 结论",
  "importance": "core / support / detail",
  "simpleEnglish": "极简版英文（可选）",
  "normalEnglish": "清晰版英文（可选）"
}

完整解析结果 (POST /api/parse/complete)

{
  "structure": {
    "subject": "谁",
    "action": "核心动作",
    "object": "动作对象",
    "context": "补充信息",
    "sentenceType": "陈述 / 请求 / 解释 / 结论"
  },
  "thinking": {
    "explanation": "信息展开顺序解释",
    "keyInsight": "核心思维模式总结"
  },
  "simplify": {
    "simpleEnglish": "极简版英文",
    "normalEnglish": "清晰版英文"
  },
  "importance": "core / support / detail",
  "expressions": [
    { "expression": "英语表达", "meaning": "中文说明" }
  ]
}

importance 字段说明

级别	含义	判定特征
core	核心信息，不理解就无法正确使用	定义/声明/结论、行为变化（deprecated/removed）、约束（must/cannot）
support	补充说明，帮助理解但不阻断主线	原因说明、解释展开、使用场景
detail	细节信息，可跳过不影响决策	例子、背景信息、非约束性描述

---

前端功能状态

✅ 已实现功能

页面	功能	状态
/	首页 - 句子输入与解析	✅ 完成
/login	用户登录	✅ 完成
/register	用户注册	✅ 完成
/history	解析历史列表	✅ 完成
/history/:id	历史详情页	✅ 完成
/speak	发音校准模式	✅ 完成

/speak 页面功能

功能	描述	状态
语音识别	使用 Web Speech API 实时识别用户语音	✅ 已集成
音素定位	调用 /api/phoneme/localize 分析发音难点	✅ 已集成
模式切换	支持语音输入和手动输入两种模式	✅ 已实现
发音示范	TTS 播放标准发音	❌ 待实现

浏览器兼容性

语音识别功能使用 Web Speech API，需要以下浏览器支持：

浏览器	支持状态
Chrome (桌面/Android)	✅ 支持
Edge	✅ 支持
Safari (macOS/iOS)	✅ 支持
Firefox	❌ 不支持（自动切换到手动输入模式）

注意：语音识别需要 HTTPS 或 localhost 环境才能使用麦克风

---

前端布局规范

⚠️ 修改 UI 时必须遵守以下规范，避免破坏整体样式。

结果卡片布局

┌─────────────────────────────────────────────┐
│  谁 (Subject)      │  值                    │
│  做什么 (Action)    │  值                    │
│  对什么 (Object)    │  值                    │
│  补充信息 (Context) │  值                    │
├─────────────────────────────────────────────┤
│  类型 [标签]    重要性 [标签]                │  ← 元数据行，标签并排
└─────────────────────────────────────────────┘

布局原则

1. 结构字段区：使用 grid-cols-[100px_1fr] 两列布局
2. 元数据区：用 border-t 分隔，标签使用 flex 水平排列
3. 新增字段：优先融入现有行，避免增加额外垂直空间
4. 标签样式：统一使用 text-[10px] font-black uppercase tracking-widest

许可证

ISC