伊库伊尔语工作台 SGorgeous/dsh-ithkuil

dsh-ithkuil

新伊库伊尔语（New Ithkuil / Ithkuil IV）翻译工作台 —— 一个 DeepSeek Harness（DSH）插件。

把 ithkuil.net 的官方语法、词典、词缀表做成一组离线工具：查词根、查词缀、查格、全文检索语法、找例句，还能按十个槽位把词形拼出来并做音位配列体检。

给 AI 助手装上它，翻译伊库伊尔语时就是「查着翻」，而不是凭印象编。

它能干什么

你：翻译「无数成方阵的无人飞行器正在偷袭大国东南部的一个省份」

ačphulogmümţíwa heňžaléi-ulvžáko eksmále huçtyáloi-ednyalí'a aksmalóxoi
'strike'-1/PRC-DYN-PRG-SUD/7-DSR/8-THM [arrangement]-2/PRC-ESS ⟵conc.⟶ 'aerial.drone'-3/PRC-MSC-ERG
'province'-2/PRC-ABS [southern.part]-3/PRC-OGN ⟵conc.⟶ [eastern.part]-2/PRC-LOC 'country'-1/PRC-SIZ/7-OGN

工具不会自己"生成译文"，但会把每一步都钉在官方文档上：

- 这个词根是哪个？（带 Lexicon 页码，可回原文核对）
- 这个词缀第 7 度是什么意思？
- 这个格用哪个元音？
- 「配置/关联/延展/视角/本质」拼出来的 CA 综合体是哪个辅音？
- 拼出来的词有没有违反音位配列？

安装

本地开发 / 源码安装
dsh plugin --profile desktop add link:/path/to/dsh-ithkuil

如果发布到 npm 之后：
dsh plugin --profile desktop add dsh-ithkuil

装完重启一次 DSH（bundle 层要重启才组装）。重启后会话里会出现 14 个 ithkuil_ 工具。

工具

| 工具 | 干什么 |
| ithkuil_root | 英文概念 → 词根（也接受 -ŢK-） |
| ithkuil_entry | 词根的完整条目 + STEM 1/2/3 明细原文 |
| ithkuil_affix | 按缩写/辅音形/关键词/主题查 422 个 VXCS 词缀 |
| ithkuil_affix_form | 辅音形 + 度 + 类型 → -VXCS- / -CSVX- |
| ithkuil_case | 68 个格：缩写/名字 → VC 形 + 语义角色 |
| ithkuil_grammar | 13 章 + 附录全文检索（BM25，带 § 号） |
| ithkuil_section | 读某一小节全文 |
| ithkuil_examples | 带 interlinear 标注的例句 |
| ithkuil_ca | 拼 CA 综合体（配置+关联+延展+视角+本质） |
| ithkuil_build | 按十槽拼一个词形（含重音、gloss、音位体检） |
| ithkuil_check | 音位配列体检 |
| ithkuil_quickref | 中文速查：槽位/术语/翻译流程/坑 |
| ithkuil_zh | 语法术语 → 中文统一译名 |
| ithkuil_stats | 语料规模与来源 |

语料

| 数据 | 数量 | 来源 |
| 词根 | 5,717 条（含 STEM 1/2/3 详解原文） | 《Lexicon for New Ithkuil》v1.0，570 页 |
| VXCS 词缀 | 422 条（每条 9 度释义 + 主题分类） | 《V_X_C_S Affixes》，140 页 |
| 语法全文 | 328 小节 ≈ 52.5 万字（13 章 + 附录） | ithkuil.net 各章 HTML |
| 格 | 68 条（缩写 + VC 元音形 + 角色说明） | 第 4 章正文 |

全部离线 JSON，零网络依赖，不调用任何外部 API。

⚠️ 版权：语言资料属于 John Quijada / ithkuil.net，本仓库只保留"检索索引"，不收原始 PDF/HTML。详见 NOTICE.md。

自己重建语料

pip install pdfplumber lxml
python tools/fetch_data.py # 从 ithkuil.net 下官方 HTML/PDF 到 data/
python tools/extract_text.py # 章节 HTML → 纯文本（表格按行展开）
python tools/build_grammar.py # 纯文本 → 328 个小节
python tools/parse_lexicon.py # 词典 PDF → 词根（双栏按 x 坐标分栏）
python tools/parse_affixes.py # 词缀 PDF → 词缀（每条词缀是一张表）

⚠️ 开发必读：工具 schema 的坑

第一版直接把 parameters: { 属性名: {...} } 丢给 ctx.tools.register()，结果整个 DSH 每次请求都被 OpenAI 兼容层拒掉：

Invalid schema for function 'ithkuil_affix':
schema must be a JSON Schema of 'type: "object"', got 'type: null'

原因：register() 收的是 defineTool() 的产物，其中 parameters 已经编译成
{type:"object", properties:{...}}。现在 lib/toolkit.mjs 负责这件事：

1. 先从宿主树里找真正的 defineTool（桌面版 @deepseek-ai/ 是 optional peer，不能裸 import）；
2. 找不到就用本地等价实现，按同一套规则编译；
3. 注册前 assertToolSchema() 逐个自检，坏的那条只跳过它自己。

改完工具必须跑闸门：

node validate.mjs --run
必须看到 ✅ 全部通过（14 个工具，参数根节点都是 type:"object"，且实跑不抛错）

目录

index.js 工具注册（14 个） lib/data.mjs 语料加载 + 检索（词根/词缀/格/BM25/例句） lib/morph.mjs VX 元音表、词缀拼写、十槽说明、中文术语 lib/assemble.mjs 词形拼装（VV/VR/CA/体/格/重音）+ 音位体检 lib/quickref.mjs 中文速查表（翻译流程、坑） lib/toolkit.mjs defineTool 解析 + schema 自检 validate.mjs 启用前闸门 data/.json 离线语料 tools/.py 语料生成脚本

已知边界

- 音位配列检查只覆盖能规则化的部分；三辅音以上的簇会提示人工对照官方表。
- Slot VIII 只实现了 36 个 Aspect；Valence/Mood/Phase/Level/Effect 还没做成接口。
- 拼接（第 10 章）支持 Type-1/Type-2 与格形转换，但case-frame（格框）嵌套还没实现。
- 词典是英文释义的；中文概念要先自己想成英文再查。

致谢

- 语言与全部语法/词典资料：John Quijada（ithkuil.net）
- 插件框架：DeepSeek Harness
- 数据解析：pdfplumber / lxml

License

代码 MIT（见 LICENSE）；语言资料版权归原作者（见 NOTICE.md）。