西语练习 liuyize-CHE/dsh-spanish-tutor

dsh-spanish-tutor · 西语练习

DeepSeek Harness（dsh）的西语学习插件。六类本地判分的练习，外加一类模型批改的情景造句，覆盖「认词 → 变形 → 用句 → 表达」：

| 题型 | 练什么 | 判分 |
| 动词变位 | 11 个时态 × 6 人称 | 本地引擎 |
| 名词阴阳性 | 阳性/阴性（含 mano、día 这类特例） | 本地引擎 |
| 名词复数 | 含 luz→luces、joven→jóvenes | 本地引擎 |
| 认词 | 词义选择（西→中、中→西） | 本地引擎 |
| 句子填空 | 挖变位/冠词/介词/形容词的整句 | 本地引擎 |
| 语法专项 | ser/estar、虚拟式、por/para | 本地引擎 + 自带规则说明 |
| 情景造句 | 给场景写一句西语 | 模型批改 |

规则层是为西语写的，不是套用英语词库改几个词：11 个时态（含虚拟式、命令式、四种完成时）、ser/estar/ir 这类完全不规则动词、mano（阴性却是 -o 结尾）、 el agua（阴性却用 el）、luz → luces 这类坑都在引擎里处理。

界面

左侧栏「西语」一行点开就是练习页；右上角 ✕ 回到会话。

设计：混合引擎

职责分工是刻意划的：

| 部分 | 由谁做 | 为什么 |
| 机械练习：变位、阴阳性、复数、认词、填空、语法辨析 | 本地规则引擎（词库） | 答案唯一、可离线、毫秒出题、零 token |
| 自由表达：情景造句 | 模型 | 没有唯一答案，只能靠理解判断 |
| 教学：讲规则、给例句、指出易错点 | 模型 | 需要理解与表达，规则引擎做不了 |
| 讲解：为什么错 | 模型 | 同上 |
| 判分 | 本地引擎（host 端） | 不烧 token；且服务端重算答案，改前端作弊无效 |

词库只服务基础练习，不做它做不了的事。 真正需要「教你」的部分全交给模型。

一个刻意的设计：语法题自带规则

ser/estar、虚拟式 这类题的每道题都带一句 rule（如「来源/国籍用 ser」）。
答错时本地规则先显示，不管模型是否可用 —— 不让学习完全押在模型上。

「学」和「练」是两条路

这是关键设计：不是只有做题。

- 先学：点「先学一下」，模型讲清这个知识点 + 2 个例句 + 易错点，然后你再作答
- 看答案：卡住时点「看答案」，直接揭晓（不烧 token）
- 先练：直接作答，答错时模型讲为什么错

三种力度在设置里可切：先学后练 / 只给最短答案 / 关闭讲解。选「关闭」后完全不调模型（情景造句也随之不可用）。

模型选择

默认跟随你在 DSH 里选的模型，不用额外配置。

也可以指定别的 —— 比如主对话用大模型、讲解用便宜的小模型：

设置 → 进度页 → 「讲解用哪个模型」→ 选 指定模型 → 选 provider 和 model。

模型不可用时（没配置/超时/报错）一律降级：照样给答案，只是没有讲解，不影响练习。

能力

动词变位

- 11 个时态：现在时、简单过去时、过去未完成时、将来时、条件式、虚拟式现在时、现在完成时、过去完成时、将来完成时、条件完成时、命令式
- 处理了这些规则：
- 词干变化（pensar→pienso、poder→puedo、pedir→pido、dormir→duermo）
- 正字法变化（llegar→llegué、buscar→busqué、empezar→empecé）
- 完全不规则（ser、estar、ir、haber、tener、hacer、decir、saber、caber、valer、oír…）
- 元音词干（leer→leyó、construir→construyó、reír→río）
- 命令式的 tú / vosotros / usted / nosotros / ustedes 五种形式

名词

- 阴阳性：词尾规则 + 例外表（mano/foto 是阴性，día/mapa/problema 是阳性）
- 复数：含 -z→-ces（luz→luces）、重音位移（canción→canciones、joven→jóvenes）
- 冠词：el agua / un agua（重读 a 开头的阴性名词单数用 el，但仍是阴性）
- 形容词一致：性别 + 数

间隔重复

8 级 SRS。答对升级、答错退两级、只差重音不升不降（重音错≠不会这个词）。
到期的卡片优先出题，其次才是新词。

安装

从 GitHub 装：

dsh plugin --profile web add github:liuyize-CHE/dsh-spanish-tutor

或者用插件管理面板「浏览更多插件」搜索 spanish，一条命令装好。

⚠️ 如果你的 DSH 只有 desktop 一个 profile，不要用 --profile desktop—— CLI 会拒绝（profile "desktop" is managed exclusively by the Electron application）。
用插件管理面板安装。

装完必须完全退出 DSH 再打开：客户端模块清单在启动时扫描并缓存，刷新页面不生效。

用法

界面

- 左侧栏的「西语」一行：点这一行任意位置（图标或文字）在中间栏打开练习面板
- 输入框右侧的旗标胶囊：打开同一个面板（有到期卡片时显示数字角标）
- 面板右上角的 ✕ 回到会话面板是宿主 root 作用域 main keyed slot 里的一页，不是浮窗。这决定了两个细节：

- sidebar.panellist 的注册项只提供图标——那一整行按钮（图标 + 文字 + 选中态 + 收起时的 tooltip）都是宿主画的，点行由宿主调 layout.selectPanel(id)。
- 所以 panellist 的 id 必须与 main 的 key 完全相同（dsh-spanish）。
不一致时宿主找不到面板、抛错并保留原选中态，表现就是「只有我们能画的那一小块能点」。
test/client.test.mjs 里有断言守着这一条。

- 面板四个页签：
- 练习：出题、作答、看讲解
- 情景造句：给场景，写一句，模型批改
- 查表：查任意动词的变位全表，或名词的阴阳性/复数/冠词
- 进度：掌握度统计、难度/题型/时态设置、清空进度

对话里

四个模型工具：
- spanish_conjugate — 查变位表
- spanish_noun — 查阴阳性、复数、冠词
- spanish_quiz — 出一组题
- spanish_progress — 看学习进度

直接说「考考我西语」「tener 的虚拟式怎么变」「mano 是阳性还是阴性」就行。

数据

学习进度存在 ~/.dsh/spanish-tutor/progress.json（或 $DSH_HOME/spanish-tutor/），和插件目录分离，更新插件不丢进度。写入用「临时文件 + 改名」的原子写。

HTTP 接口

host 半身在 /dsh-spanish 前缀下提供：

| 方法 | 路径 | 作用 |
| GET | /state | 进度 + 设置 + 统计 |
| POST | /settings | 改设置 |
| POST | /session | 出一局题（下发时剥掉答案） |
| POST | /answer | 交一题，判分（服务端重算答案） |
| POST | /teach | 「学」：讲知识点 / 给例句 / 指易错点 |
| POST | /reveal | 「看答案」：直接揭晓 |
| GET | /models | 可用模型列表（供设置页选择） |
| GET | /scenarios | 情景造句的场景列表 |
| POST | /scenario | 情景造句出题（参考答案不下发，只给 refToken） |
| POST | /scenario/grade | 批改（按 refToken 取回参考答案） |
| POST | /reset | 清空进度（需 confirm: true） |
| GET | /table?verb= | 变位全表 |
| GET | /noun?word= | 名词信息 |
| GET | /bank?level= | 词库 |
| GET | /meta | 时态/人称/题型/学习方式等元信息 |

防作弊

/session 下发的题目不含 answer 字段。/answer 判分时按题目里的动词/时态/人称/名词在服务端重新算一遍答案，词库标注优先于词尾规则（所以 mano 永远不会被规则误判成阳性）。

情景造句的参考答案也不下发：出题时存进服务端暂存区（TTL 30 分钟），只给客户端一个随机 refToken；批改时按 token 取回，且场景必须对上。
伪造 token、跨场景用 token 都会被拒（有测试守着）。

开发

离线：不需要 DSH 在跑
node test/all.mjs # 1530 条断言（10 个套件）
node test/standalone-server.mjs # 75 条：六类题型走真实 HTTP（也不用重启 DSH）

实机：DSH 得在跑，且必须已加载最新代码
node test/live-all.mjs [baseUrl] # 一条命令跑完所有端到端检查

三层验证，各管一段

| 层 | 命令 | 验什么 | 要重启 DSH？ |
| 引擎 | test/all.mjs | 变位/名词/出题/判分的纯逻辑 | 不用 |
| 路由 | test/standalone-server.mjs | 真实 HTTP 下六类题型的出题+判分 | 不用 |
| 宿主 | test/live-all.mjs | 装进真 DSH 后的集成、client 加载、真模型 | 要 |

中间的 standalone-server 是后来补的，因为踩过一个坑：只测引擎函数（直接调 judge()）会绕开 HTTP 路由，于是 resolveAnswer() 漏了新题型的分支、判分全 400 也没被发现。
现在它起一个真的 node:http 服务，跑完整请求。

live-all.mjs 会先检查进程有没有加载最新代码：

- 版本不一致 → 直接告诉你去重启，不用猜后面那些失败是不是真 bug
- 版本一致但还失败 → 那才是真的代码问题

单独跑某个实机套件：

node test/version-check.mjs [baseUrl] # 版本一致性（指纹比对）
node test/live.mjs [baseUrl] # 练习 + 判分
node test/live-learn.mjs [baseUrl] # 学 + 模型
node test/live-kinds.mjs [baseUrl] # 六类题型 + 情景造句

⚠️ 改了 host 代码（lib/index.js）必须重启 DSH，刷新页面没用 —— host 半身跑在 DSH 进程里。version-check 通过 /meta 的 fingerprint 比对「进程加载时的文件 mtime」和「磁盘当前 mtime」，连「只改函数逻辑、题型没变」这种更新也能识别（这个坑踩过）。

离线套件（不需要 DSH 在跑）：

| 套件 | 断言 | 守什么 |
| conjugator.test.mjs | 409 | 变位是否正确 |
| nouns.test.mjs | 90 | 阴阳性/复数/冠词 |
| session.test.mjs | 280 | SRS 调度、出题、判分 |
| vocab.test.mjs | 78 | 认词：干扰项质量、同义词去重 |
| cloze.test.mjs | 179 | 填空：例句答案与变位引擎交叉验证 |
| grammar.test.mjs | 198 | 语法专项：答案必在选项里、规则正确 |
| scenario.test.mjs | 43 | 情景造句：JSON 解析健壮性、token 防篡改 |
| host.test.mjs | 131 | 路由、工具、落盘、防作弊、降级 |
| host-llm.test.mjs | 38 | 模型集成：跟随/覆盖/不烧 token/报错降级 |
| client.test.mjs | 84 | 客户端能否被宿主激活、面板接线是否正确 |

实机套件 live.mjs 需要 DSH 正在运行，验证的是「装进去之后真的能用」：路由可达、出题判分、防作弊、设置持久化等。

⚠️ 两个 live 套件都必须单独运行。它们不能和离线套件同进程混跑： host.test.mjs 会改 DSH_HOME，client.test.mjs 会改全局 window/process.exit，都会污染紧接着跑的 live 测试。

⚠️ 改过 host 端代码（lib/index.js）后，必须重启 DSH 才会生效 ——客户端 bundle 刷新页面能重载，但 host 半身跑在 DSH 进程里，不重启就还是旧代码。

测试用真实西语答案断言，不是「跑出来什么就记什么」。已做过变异测试：故意把「-z 结尾是阴性」改成阳性、把 flor 从阴性例外表移除，测试都会红并指出具体词。

lib/
engine/
conjugator.js 变位引擎（规则 + 不规则表） nouns.js 阴阳性 / 复数 / 冠词 / 形容词一致 bank.js 种子词库（人工核对性别） session.js SRS + 出题 + 判分 index.js host 半身（路由 / 工具 / LLM 讲解 / 落盘） client.js 浏览器半身（__ModuleLoader__ + React） test/ *.test.mjs 五个离线套件 all.mjs 统一入口 live.mjs 实机端到端验证

已知边界

- 词库是种子库（约 60 个动词、60 个名词、16 个形容词），覆盖 A1–B1 高频词，不是完整西语词库。查表功能对任意标准动词都有效（规则引擎按需推导）。
- 部分时态（将来完成时、条件完成时）只在查表里出现，默认练习设置不含它们。
- 命令式的人称语义与陈述式不同（tú 的命令式和 usted 的），界面按「人称槽位」展示。
- 不处理 vosotros 的地区差异（拉美不用 vosotros），但引擎会算，练习时可在设置里避开。
- 讲解质量取决于当前会话模型；模型不可用时讲解降级为 null，不影响判分。

许可

MIT