灵语（LingYu）完全手册

从入门到精通：彻底掌握这门「用中文写程序」的编程语言。
适用版本：灵语桌面工作室 v2 · 运行时 v1.0.0（Python 3.11 及以上）。
权威词表见 lingyu/keywords.py，速查表见同目录《别名对照表.md》。

目录

• 上卷·语言
• 1. 灵语是什么
• 2. 安装与运行环境
• 3. 第一个程序
• 4. 词法基础（注释 / 缩进 / 标识符 / 全角归一化）
• 5. 类型与字面量
• 6. 运算符
• 7. 关键字全表与逐条精讲
• 8. 控制流
• 9. 函数
• 10. 类与面向对象
• 11. 异常处理
• 12. 模块与多文件工程
• 13. 内置函数（99 个）
• 14. 标准库中文名与全局直用成员
• 15. 对象方法别名
• 16. 上下文管理器
• 17. 异步与生成器
• 下卷·平台
• 18. REPL 交互模式
• 19. 命令行工具（CLI）
• 20. 中文报错机制
• 21. 性能与缓存
• 22. i18n 汉化机制
• 23. 灵库（cnlib）：100 个中文库
• 24. 脂译器（lingku）
• 25. 与 Python 生态互编
• 26. LSP 语言服务与语法高亮
• 27. 灵语桌面工作室
• 28. 备用 IDE（lingyu_ide）
• 29. PyCharm 集成
• 30. 打包与分发
• 31. 官方示例逐例精讲（examples/）
• 32. 综合工程实战
• 33. 命名纪律与别名约束
• 34. 常见问题（FAQ）
• 35. 附录：词表与延伸阅读

上卷·语言

1. 灵语是什么

灵语是一门 用中文编写程序 的编程语言。它把 Python 的全部语法能力翻译成中文的关键字、内置函数、常用模块与成员名，让代码本身是中文的：若、否则、循环、打印、导入 数学……字符串、变量名、注释也都天然是中文。 核心设计哲学：

1. 中文优先，但不排斥英文。 关键字与常用 API 是中文的；但如果一行里某个英文标识符不在词表中，它原样保留、照常解析。中英混写合法。
2. 稳定契约，导出即真 Python。 灵语源码经过「token 级翻译」变成标准 Python，编译后直接运行在 CPython 上。翻译是确定性的：同一个源码永远得到同一份字节码（有缓存加持）。导出命令可以把 .灵 变成等价的 .py，交给不装灵语的机器跑。
3. 与 Python 生态无缝互通。 .灵 模块可以相互 导入，也可以 导入 任何第三方库；支持挂接外部 Python 解释器来使用 numpy、pandas、requests 等。
4. 容错与友好。 全角括号、全角运算符、全角数字字母写得再歪也能跑；语法错误、运行时错误给出全中文的报错和修复建议。
5. 教学让位。 灵语本身是解释器/编译器项目，但它刻意降低了编程的入门门槛——REPL 会提示你「中文写法」，错误信息会建议正确名称，让零基础学习者也能直接上手。

它不是什么：

• 不是 Python 的中文「翻译器」，把别人的 Python 库逐行转成中文——灵语只翻译自己认识的词，不认识的一律不动。
• 不是独立虚拟机——它复用的是 CPython 的成熟运行时，保证正确性与性能。
• 不是教学玩具——已经具备多文件工程、异常、类、异步、调试器、语言服务（LSP）、桌面 IDE 和打包发布能力。

2. 安装与运行环境

2.1 一键安装（最终用户，推荐）

1. 获取安装包 灵语桌面工作室-安装程序.exe（约 163 MB）。
2. 双击运行，按向导安装。目标电脑无需预装 Python——完整灵语运行时随包带上。
3. 通过开始菜单 / 桌面快捷方式打开「灵语桌面工作室」，发布者为 jzm。
4. 入门：在默认空白页输入 打印("你好，灵语！")，按 F5 运行。

2.2 绿色版（免安装）

dist\灵语桌面工作室\ 是 PyInstaller onedir 绿色版：把整个文件夹拷到任何 Windows 电脑，双击 lingyu-studio.exe 即用。可把它发送到桌面快捷方式。

2.3 源码 / 开发模式

set PYTHONPATH=项目根目录                # 源码模式：让 python 能 import lingyu
python -m lingyu --version
python -m lingyu_studio                  # 直接以源码方式启动桌面工作室
python -m lingyu                         # 命令行 REPL

灵语是语言，日常以源码/绿色版/安装包形态分发。源码模式无需任何安装：把项目根目录加进
PYTHONPATH（或在外部解释器 / PyCharm 解释器里指向该目录）即可。仓库同时提供 pyproject.toml，
也可 pip install -e . 安装（提供 lingyu / lingyu-lsp / lingyu-studio 三个命令），但不依赖 PyPI 分发。

2.4 版本与解释器要求

• 灵语 IDE 支持 Python 3.11 及以上。
• 内置运行时 = 打包进安装程序的那份 Python 3.x（零配置）。
• 需要调用第三方库（numpy / pandas / requests / torch…）时，在「设置 → 解释器」切换到外部 Python 解释器，脚本将跑在外部解释器中并自动获得其全部已安装库（详见 27.8 节）。

2.5 目录速览（源码布局）

lingyu/             # 语言引擎核心（关键字表、翻译、编译、跨文件导入 importer、REPL、CLI、缓存、i18n、灵库 cnlib/lib_catalog、脂译 lingku、LSP）
lingyu_studio/      # 桌面工作室 v2（PySide6：编辑器、调试、主题、设置、帮助阅读器、运行器）
lingyu_ide/         # 备用轻量 IDE（tkinter，零第三方依赖；含核心调试器纯逻辑）
lingyu_ide/core/    # 备用 IDE 的 Document / 设置模块
examples/           # 官方示例（13 个 .灵 文件）
tools/              # lingyu.spec（打包）、灵语安装器.iss、build_inno.ps1、build_lib.py、install_lingyu_lsp.py、lingyu_run.py（PyCharm 包装）
editors/            # TextMate 语法高亮：lingyu.tmbundle / lingyu.tmLanguage.json / language-configuration.json
docs/               # 本手册、别名对照表、INSTALL、PyCharm指南、教程-快速上手、公测说明、IDE架构方案
tests/              # 全量回归测试（225 项，含 3 项性能基准）

3. 第一个程序

新建 hello.灵：

打印("你好，灵语！")
打印("1 + 1 =", 1 + 1)

三种运行方式，结果都一样：

命令行运行时，输出完会提示全角归一化次数（有的话）；出错时给出中文回溯。再来一个标准骨架（--new 生成的东西你会立刻认识）：

导入 系统

定义 主():
    打印("你好，灵语！")

若 __名__ == "__main__":
    主()

要点速记：

• 打印(...) 就是 print(...)；若 / 否则若 / 否则 就是 if / elif / else。
• 代码块用 4 空格缩进；: 不能省（半角全角都可以）。
• __名__ 是 __name__，__主__ 是 __main__——这是特殊名，写法固定如上。

4. 词法基础

4.1 注释

# 开头是注释（全角 ＃ 也会被归一化）。注释里的中文、全角字符永远不会被翻译器污染：

# 这是一条注释，可以写任何内容，包括 # ￥%……&*
打印("能运行")  # 行尾注释

4.2 缩进

• 块体（函数 / 循环 / 条件 / 类 / try 等）必须缩进，建议 4 个空格。
• 全文件的缩进要保持一致（同一块内对齐）。
• 不要混用 Tab 和空格，否则报「缩进混用了 Tab 与空格」。
• 缩进错了，报错会提示「意外的缩进（多了空格？）」或「缩进与外层不对齐」，并给出列号与插入符位置。

4.3 标识符与命名

• 变量、函数、类名可以用中文：名字 = "小明"、定义 主函数():。
• 也可以是英文：name = "le"。两者可混用。
• 保留名不可用（见 33 节《命名纪律》）：若、打印、范围、数学……这些都是词表里的名字，不能拿来做变量名/参数名/类名/属性名（翻译是 token 级的，写在函数体里的裸 若/打印 会被替换掉）。

4.4 全角归一化（灵语的"宽容模式"）

这是灵语最有亲和力的特性之一：全角符号、全角数字、全角字母自动归一为半角，无需切换输入法。

总和 ＝ 0                   # 全角 ＝
循环 x 于 范围（5）：          # 全角（）与 ：
    总和 ＋＝ x               # 全角 ＋＝
打印（"总和 ="， 总和）       # 全角（）与 ，
若 总和 ＝＝ 10：             # 全角 ＝＝ 与 ：
    打印（"正确！"）

可以归一化的内容（翻译器 _FULLWIDTH 表 + 数字/字母族）：

安全边界（都发生在 token 层）：

• 字符串里的全角字符不动：打印("＝ ＋ 你好") 原样输出。
• 注释里的全角字符不动。
• 行尾/文件结尾多余的空格、空白行都无碍。

运行含全角内容的脚本后，CLI 会提示「已自动归一化 N 处全角符号到半角」。全角计数结果同时由 run_script_file 作为第一个返回值给出，供工具链使用。

4.5 BOM 与编码

• 文件一律 UTF-8 编码读写（桌面工作室保存即 UTF-8）。
• 源码开头的 BOM（\ufeff）会被自动剥掉，不会干扰首行。

5. 类型与字面量

灵语拥有 Python 全部内置类型，中文名在词表里有对应（整数、浮点数、字符串…既是类型名也是转换函数）：

名字 = "小明"            # 字符串
年龄 = 16               # 整数
身高 = 1.72             # 浮点数
是学生 = 真             # 布尔（真 / True，假 / False，空 / None）

字面量写法与 Python 完全一致：

a = 0b1010                  # 二进制（前缀也可用中文名 二进制()）
b = 0o17                    # 八进制
c = 0xff                    # 十六进制
d = 1.5e3                   # 科学计数
s = "双引号" '单引号'        # 字符串两种引号
长文本 = """三引号
多行原文"""
fms = f"今年 {年龄} 岁"      # f-string（插值表达式里的中文名也能翻译）
原始 = r"a\nb"              # 原始字符串

三种类型转换函数族的写法都来自词表（整数("42")、浮点数("3.14")、字符串(123)、列表(...)、字典(...)…），和 Python 的 int(...) 完全同义。

6. 运算符

其余算术/比较/位/赋值运算符与 Python 完全一致，且全角版也能用：

x = 10
x += 5          # ＋＝ 亦可
打印(10 // 3)    # 整除
打印(10 % 3)     # 取余
打印(2 ** 10)    # 幂
打印(7 & 3, 7 | 3, 7 ^ 3, ~7, 1 << 4, 16 >> 2)
打印(a == b, a != b, a < b, a > b, a <= b)

提醒：并集/交集 这类没有中文别名；集合运算仍用符号 | & - ^。词表里「集合」是 set 类型名本身。

7. 关键字全表与逐条精讲

共 38 个关键字（KEYWORDS）+ 4 个特殊名（DUNDERS + DUNDER_METHODS）。下面分组精讲。

7.1 全表速览

7.2 条件：若 / 否则若 / 否则

分数 = 85
若 分数 >= 90:
    打印("优")
否则若 分数 >= 60:
    打印("中")
否则:
    打印("差")

7.3 循环：当 / 循环 / 于

当 次数 < 3:
    打印(次数)
    次数 += 1

循环 i 于 范围(5):
    打印(i)

循环 名 于 ["甲", "乙", "丙"]:
    打印(名)

循环 序号, 名 于 枚举(["甲", "乙"]):      # 枚举 → enumerate
    打印(序号, 名)

退出循环（break）、继续（continue）在 当/循环 内可用；在循环外用会报错：「在循环外用到了『退出循环』」。

7.4 匹配：匹配 / 情形（Python 3.10+ 结构模式匹配）

匹配 命令:
    情形 1:
        打印("刷新")
    情形 2:
        打印("退出")
    情形 _:                     # 兜底
        打印("未知命令")

7.5 字面量与作用域：真 / 假 / 空 / 全局 / 非本地

计数 = 0
定义 增加():
    全局 计数
    计数 += 1

定义 外层():
    a = 1
    定义 内层():
        非本地 a
        a = 2

7.6 杂项：占位 / 删除 / 断言 / 匿名函数

若 尚未完成:
    占位                     # pass：留空占位

删除 xs[0]                  # del：删下标
删除 临时                    # del：删名字

断言 x > 0, "x 必须为正"     # assert

平方 = 匿名函数 x: x * x     # lambda
打印(平方(5))

7.7 特殊名（DUNDERS）

若 __名__ == "__main__":
    主()

7.8 特殊方法（DUNDER_METHODS）

注意：这两个是方法名字，写在类体里用中文；打印(x) 触发对 __str__ 的调用是 Python 协议自动进行，与翻译无关。

8. 控制流

综合示例（对应 examples/语法全览.灵）：

导入 数学
导入 随机

名字 = "小明"
年龄 = 16

若 年龄 >= 18:
    打印("已成年")
否则:
    打印("未成年")

循环 序号 于 范围(3):
    打印("第", 序号 + 1, "次")

尝试:
    打印(10 / 0)
捕获 零除错误:
    打印("除零错误已被捕获")

要点：

• 条件表达式：若 x:、若 x 是 空:、若 x 于 列表:、若 非 x: 都合法。
• 块标记：每个控制头以 :（或全角 ：）结尾。
• 嵌套无限：当 里套 循环 套 若 都行（九九乘法表示例）。
• 匹配 / 情形 支持元组/序列/守卫各种 Python 模式匹配写法。

9. 函数

9.1 定义与调用

定义 面积(宽, 高):
    返回 宽 * 高

打印(面积(3, 4))

• 参数可以是中文名或英文名。
• 默认参数、关键字参数、解包 *args / **kwargs 与 Python 一致：

定义 打招呼(名字, 语气="！", *额外, 次数=1, **选项):
    循环 _ 于 范围(次数):
        打印(名字 + 语气)

打招呼("小明", 次数=3)

• 参数类型注解可用中文类型名：

定义 翻倍(x: 整数) -> 整数:
    返回 x * 2

9.2 返回值

• 返回 不带值返回 空。
• 没有 返回 的函数返回 空。

9.3 匿名函数（lambda）

加法 = 匿名函数 a, b: a + b
排序列表 = 排序(项目们, 键=匿名函数 x: x[1])

9.4 生成器：产出 / 产出自

定义 斐波那契(n):
    a, b = 0, 1
    循环 _ 于 范围(n):
        产出 a
        a, b = b, a + b

循环 项 于 斐波那契(8):
    打印(项)

定义 打平(嵌套):
    循环 子 于 嵌套:
        产出自 子        # yield from：把子迭代器的产出摊平

产出 对应 yield，产出自 对应 yield from。

9.5 作用域

计数 = 0

定义 增加():
    全局 计数
    计数 += 1

定义 制造计数器():
    初始 = 0
    定义 计数():
        非本地 初始
        初始 += 1
        返回 初始
    返回 计数

10. 类与面向对象

10.1 定义与构造

类 动物():
    定义 初始化(自身, 名字):
        自身.名字 = 名字

    定义 叫声(自身):
        返回 "……"

    定义 字符串表示(自身):
        返回 f"动物({自身.名字})"

10.2 继承与 父类

类 猫(动物):
    定义 叫声(自身):
        返回 "喵"

    定义 初始化(自身, 名字, 毛色):
        父类().__初始化__(名字)       # 父类(super) 的初始化
        自身.毛色 = 毛色

10.3 多态

动物们 = [猫("小白"), 狗("大黄")]
循环 动物 于 动物们:
    打印(动物.名字 + "说：" + 动物.叫声())

10.4 方法与属性声明式

类 圆():
    定义 初始化(自身, r):
        自身._r = r

    @属性
    定义 面积(自身):
        返回 数学.圆周率 * 自身._r * 自身._r

    @静态方法
    定义 说明():
        返回 "圆"

    @类方法
    定义 创建(自身类, r):
        返回 自身类(r)

    定义 字符串表示(自身):
        返回 f"圆(r={自身._r})"

把大写写成 自身（self）是惯例，但不是必须；Python 里它就是个普通参数名。

10.5 类型判定

是实例(小猫, 猫)     # isinstance
是子类(猫, 动物)     # issubclass
类型(小猫)            # type

11. 异常处理

11.1 语法

尝试:
    数值 = 整数(输入("请输入一个数字："))
捕获 值错误:
    打印("不是数字！")
最终:
    打印("无论是否出错都执行")

尝试 / 捕获 / 最终 / 抛出 / 使用 = try / except / finally / raise / with。

11.2 捕获多个与捕获全部

尝试:
    处理()
捕获 （值错误, 键错误）:
    打印("值或键错误")
捕获 异常:
    打印("其他异常")

# 带异常变量（可选英文/中文名）：
捕获 零除错误 作为 e:
    打印("除零：", e)

11.3 主动抛出

抛出错 = 值错误("余额不足")
抛出 抛出错

抛出中文异常也是 Python 异常对象，可被上层捕获或回溯展示。

11.4 异常类名（词表内置 20+）

异常、异常组、值错误、类型错误、键错误、索引错误、属性错误、运行时错误、零除错误、文件未找到、停止迭代、停止异步迭代、断言错误、算术错误、名称错误、语法错误、导入错误、模块未找到、内存错误、超时错误、递归错误、未实现错误、未绑定局部错误、系统错误、系统退出、键盘中断、连接错误、文件已存在、EOF错误、生成器结束。等。 异常名不需要 import，翻译阶段直接替换为 Python 对应异常（值错误 → ValueError），可直接写 捕获、直接 抛出。

12. 模块与多文件工程

12.1 导入

导入 数学
导入 随机
导入 操作系统
导入 (数学, 时间)                    # 括号一次导入多个模块（等价两条 `导入`）
导入 子模块 作为 别名              # import 某模块 as 乙 ——「作为」绑定中文名
导入 数学工具箱                     # 自己写的 .灵 模块同名文件

翻译策略（重要）：采用 import eng as 中文名——只在导入处绑定中文名，不占用用户普通变量名，块内其余用法自然解析。

12.2 从…导入…

从 数学 导入 圆周率
从 数学 导入 平方根 作为 开根         # from 某模块 import 成员 as 别名
从 lingyu.i18n 导入 汉化, 注册词表   # 从任意 Python 包导入

中文成员名在词表里全局唯一（如 睡眠 只有 时间 模块有，异步睡眠 只有 异步库 有），所以 124 个成员名 + 8 个方法名全部进入「全局可直用集」、都可直接当全局名用。假如将来词表补入同一个中文名对应两个库的成员，重名者将不再进入直用集，只能用 模块.成员 或 从…导入 原名 as 新名 指定来源。

12.3 导入 *

从 数学 导入 *

12.4 子模块

导入 路径系统          # os.path（整链中文名）
从 操作系统 导入 环境变量

12.5 .灵 跨文件导入（meta_path 钩子）

• 主程序运行时自动注册导入钩子（run_script_file 内 ensure_importer()），默认从 sys.path（含脚本所在目录）下找 模块名.灵 文件。
• 找到后：翻译 → 同目录生成 <名>_gen.py → 按 Python 模块加载（并走字节码缓存）。
• 目录分隔用 .：导入 我的项目.工具 会去找 我的项目/工具.灵。

# 数学工具箱.灵
导入 数学

定义 平方(x):
    返回 x * x

定义 斜边(a, b):
    返回 数学.平方根(平方(a) + 平方(b))

# 多文件示例.灵
导入 数学工具箱
打印("3 的平方 =", 数学工具箱.平方(3))
打印("半径 2 圆的面积 =", 数学工具箱.圆面积(2))

（这也正是 examples/多文件示例.灵 的标准形态。）

12.6 模块级变量与命令行参数

从 系统 导入 参数        # 等价 from sys import argv
打印(参数[1:])           # 第一个参数之后的都算脚本参数

参数 必须先显式导入才生效（#68 纪律）：
- 从 系统 导入 参数 === from sys import argv，此后本文件内所有 参数 都会被翻译成 argv（脚本参数列表）。
- 未导入时 参数 是普通标识符——你可以在脚本里自由命名 参数 = 5、定义 参数(x):，它们不会被静默改写成 argv，也不会报错。
- 不要写成 导入 参数：import 参数 并没有这样一个模块（argv 是 sys 的属性，不是可导入模块名）；正确的写法只有上面这种 从 系统 导入 参数。

12.7 第三方库与中文库名

• 标准 33 个常用 Python 库有固定中文名（见第 14 节），直接 导入 数学。
• 其它第三方库：导入 请求库（= requests）、导入 数据框库（= pandas）…——这是灵库（cnlib）的 100 个中文库名（见第 23 节）。也可以写 导入 numpy 作为 数。

13. 内置函数（99 个）

内置函数在任何位置直接可用，不需要 import。以下按用途分组（中文名 → 英文名）。注：99 个内置名中有 30 个是异常类（值错误/类型错误/文件未找到…，见 11.4）；本节分组只收录 69 个函数/类型名，异常类不在此重复。

13.1 输出与输入

打印(print)、输入(input)、帮助(help)、断点(breakpoint)、表示(repr)、转义表示(ascii)、格式化(format)。

打印("sep 与 end 都可定制", "第二段", sep=" | ", end="\n\n")
输入("按回车继续…")

13.2 序列与容器规划

长度(len)、范围(range)、列表(list)、元组(tuple)、集合(set)、冻结集合(frozenset)、字典(dict)、迭代(iter)、下一个(next)、枚举(enumerate)、压缩(zip)、映射(map)、过滤(filter)、排序(sorted)、反转(reversed)、切片(slice)。

打印(长度([1, 2, 3]))
打印(列表(范围(5)))
打印(排序([3, 1, 2], 反转=真))
打印(压缩([1, 2], ["a", "b"]))          # zip
打印(映射(平方, [1, 2, 3]))
打印(过滤(lambda x: x > 1, [1, 2, 3]))

13.3 数学

求和(sum)、最小值(min)、最大值(max)、绝对值(abs)、取整(round)、幂(pow)、整除(divmod)、二进制(bin)、八进制(oct)、十六进制(hex)。

13.4 类型与判定

类型(type)、是实例(isinstance)、是子类(issubclass)、可调用(callable)、哈希(hash)、布尔(bool)、整数(int)、浮点数(float)、字符串(str)、字节(bytes)、字节数组(bytearray)、复数(complex)、对象(object)、内存视图(memoryview)、数据类(dataclass)。

13.5 属性与作用域

getattr/setattr/hasattr/delattr → 取属性/设属性/有属性/删属性；全局变量(globals)、局部变量(locals)、命名空间(vars)、属性列表(dir)、属性(property)、类方法(classmethod)、静态方法(staticmethod)、父类(super)。

13.6 动态执行

动态执行(exec)、动态求值(eval)、编译(compile)。

动态执行("打印(1 + 1)")
值 = 动态求值("2 * 21")

13.7 字符与编码

字符(chr)、字符码(ord)、地址(id)、表示(repr，见 13.1)、转义表示(ascii，见 13.1)。

13.8 逻辑

任何(any)、所有(all)。

13.9 文件

打开(open)——全文见 16 节。

完整 99 个中文内置的一栏表见《别名对照表.md》，此处不重复罗列。

14. 标准库中文名与全局直用成员

14.1 模块名（33 个）

成员访问两种写法都行：

导入 数学
打印(数学.圆周率)              # 中文模块名.中文成员
打印(数学.pi)                 # 原英文成员照样能用

从 时间 导入 睡眠
睡眠(1)

14.2 全局可直用成员（GLOBAL_MEMBERS）

词表纪律：只在单一来源出现的中文成员名，可以直接当全局名用（不需要 从…导入）。当前词表的 124 个模块成员 + 8 个方法名全部全局唯一、无跨模块重名，故全部进入直用集；将来若补入重名词，则只保留最先定义的来源进入直用集（重名者只能 模块.成员 或显式 import）。 可直接书写的常用例：圆周率、平方根、随机整数、计数器（需要 从 容器 导入 计数器 才行？不——GLOBAL 只收唯一命中的）。

判据见 keywords.py 底部的 GLOBAL_MEMBERS 生成逻辑；具体清单直接看 .py 或用 REPL 帮助。

14.3 明明内置还要不要 import？

不需要。数学.圆周率 是「导入 数学」之后用成员名；打印 / 长度 / 求和 等内置在任何地方直接可用。两者不冲突（翻译按 token 类型区分）。

15. 对象方法别名

8 个高频容器/字符串/文件方法有固定中文别名（METHODS 表），覆盖列表、字典、字符串、文件对象的方法调用：

水果 = 列表()
水果.追加("苹果")
水果.追加("香蕉")

分数 = 字典()
分数["小明"] = 92
打印(分数.键列表())
打印(分数.值列表())
打印(分数.条目())
打印("abc".大写())
打印("a-b".字符替换("-", "·"))

这些别名与「从模块导入成员」合并去重后再判定是否进入直用集；因此 追加、值列表 等在这里直接可用，例如 打印(分数.值列表()) 无需任何 import。其余未收录的方法名（如 split、join、strip）请用英文原样——它们不是灵语词表的一部分（字符串内容不受翻译器影响，方法名照样能不翻译地解析）。

想要更多对象方法中文名？见 22.3 节「通用词袋」（含 打开/关闭/读取/写入/保存/加载 等 34 项，作用于任何库对象）与 25 节 i18n 机制。

16. 上下文管理器

使用 … 作为 …: 对应 with … as …:，自动管理资源（关闭文件、释放锁等）。

使用 打开("临时.txt", "w", encoding="utf-8") 作为 文件对象:
    文件对象.写("灵语文件示例")

使用 打开("临时.txt", encoding="utf-8") 作为 文件对象:
    打印(文件对象.读())

• 打开 是内置 open；其它参数（模式、编码）与 Python 相同。
• 使用 也适用于其它上下文管理器对象：锁、临时文件库.临时文件、事务等。
• 多管理器：使用 A 作为 a, B 作为 b:（与 Python 一致）。
• 文件路径建议用 路径 模块：路径.路径类型("a/b.txt").读()。

17. 异步与生成器

17.1 惰性 循环 于 + 生成器

生成器（见 9.4）配 循环 逐个取：内存友好。产出/产出自 与 Python yield 语义一致，生成器也是迭代器，类型(g) 为 generator。

17.2 协程：异步 / 等待

导入 异步库

异步 定义 任务(n):
    打印("开始", n)
    等待 异步库.异步睡眠(0.1)
    打印("结束", n)

异步 定义 主协程():
    任务们 = [异步库.异步任务(任务(i)) 于 i 于 范围(3)]
    等待 任务们  # 等待全部完成（Python 语法上是 await 列表）

异步库.异步运行(主协程())

对应关系：异步 定义 = async def；等待 = await；异步库.异步运行/异步任务/异步睡眠 = asyncio.run/create_task/sleep。f-string、注解、异常、上下文管理器等异步配套语法都生效。

下卷·平台

18. REPL 交互模式

启动：python -m lingyu（无参数）；桌面工作室命令行也可进入。REPL 是全交互环境，支持累积语句块与表达式回显。

18.1 基本操作

示例会话：

灵语> 1 + 2
3
灵语> 名字 = "灵语"
灵语> f"你好，{名字}"
'你好，灵语'
灵语> 定义 呃(x):
.....    返回 x * 2
.....
灵语> 呃(21)
42

• 单行纯表达式会被 eval 并回显（与 Python REPL 一致）；变量赋值、语句则执行不回显。
• 中文写法提示：输入英文（print(...)）回车后，REPL 会在下方打印 中文写法：打印(...)，这是「教学让位」——提醒你记住中文词。
• 块判定支持括号平衡（([{）与字符串闭合；坏语法在块内会立刻报中文错误并清空缓冲。

18.2 把脚本跑进 REPL

python -m lingyu --repl 我的脚本.灵 [参数...]

先完整执行脚本，随后进入 REPL 且 命名空间共享——脚本里定义的变量/函数在会话里直接可用：

python -m lingyu --repl examples/数学工具箱.灵
灵语> 斜边(3, 4)
5.0

19. 命令行工具（CLI）

python -m lingyu <文件.灵> [参数...]        运行脚本（异常给中文回溯）
python -m lingyu -                            从标准输入读取并运行（管道/CI 用）
python -m lingyu -c "代码串"                运行一行代码（等价 --command）
python -m lingyu --repl <文件.灵> [参数...]  运行脚本后进交互 REPL
python -m lingyu --trace <文件.灵> [参数...]  逐行追踪执行的源码行（调试）
python -m lingyu --new <名称> [名称...]      生成脚本骨架（自动补 .灵）
python -m lingyu --clean [目录]             清理生成的 *_gen.py
python -m lingyu                            启动 REPL
python -m lingyu --export <文件.灵> [输出.py]  导出等价 Python 源码
python -m lingyu --version                  显示版本
python -m lingyu --help / -h                显示用法

细项说明：

• --new Hello：生成带主函数骨架的 Hello.灵，多个名称可一次创建。
• --clean：默认清理当前目录（可给目录参数）下所有 *_gen.py 翻译产物；逐一打印删了谁。
• --export：输出格式为 # 此文件由灵语 LingYu 自动生成… 头部 + 纯 Python；给第二个参数写文件，否则打到 stdout。导出的 .py 可直接交给只装了 Python 的机器运行。
• --trace：运行同时打印 执行 ·第 N 行：源行文本，逐行看代码走向（等价于一个简单的 line 调试器）。
• stdin 管道：echo 打印(1) | python -m lingyu -（CI/管道友好）。
• 运行脚本带全角内容时打印归一化提示；所有错误路径都走中文 format_traceback。
• 环境要求：PYTHONUTF8=1 或灵语入口自动 reconfigure 为标准 IO 的 UTF-8。

20. 中文报错机制

灵语把三类错误都翻译成中文，并附位置信息与修复建议。

20.1 编译期（SyntaxError）

见 compiler.py 的 _MSGS 映射（示例）：

报错还会附上传真排障三件套：

语法错误（非法语法）（第 3 行，列 9）
  打印("hi"
          ^

（源码行 + 插入符定位列号，1:1 行号映射。）

20.2 运行时细分中文（translate_error）

常见异常被直译为精确中文并给出可操作建议：

20.3 中文回溯（format_traceback）

回溯（最近一次调用）：
  文件 我的脚本.灵，第 5 行
    print(1 / 0)
  除零错误

• 自动把内部 *_gen.py 帧映射回 .灵 文件名，行号 1:1。
• 跨模块异常会把链上的 .灵 帧全部列出。
• 桌面工作室、CLI、PyCharm（运行模式）统一走这份回溯。

21. 性能与缓存

灵语 = 翻译（token 级、确定性）→ Python 编译 → 字节码运行。大量中文代码运行开销 ≈ 原生 Python，仅在翻译/编译阶段有一次廉价成本。这由两层机制抹平：

21.1 源码字节码缓存（.lingyu_cache/）

• run_script_file 会在脚本旁建立缓存目录 .lingyu_cache/。
• 缓存键 = sha256(源码)[:16] + Python 小版本 + 灵语版本；任意一项变化即自动失效重编。
• 产物带 LYC2 魔数头（+ marshal 化的 code object），读缓存任何异常都当作未命中、安全回退重新编译。
• 写缓存用「临时文件 + os.replace」原子替换，防并发撕裂；目录建不了只静默降级。
• 被 导入 的自写 .灵 模块同样走该缓存（跨进程多次 import 收益最大）。

手动清理：删除脚本旁的 .lingyu_cache/，或 python -m lingyu --clean（清 _gen.py）。

21.2 翻译层 lru_cache

• translate 对纯 ASCII 源直接原样返回（跳过 tokenize——英文源码零开销）。
• 翻译结果带 64 项 LRU 缓存；表达式翻译 4096 项；REPL 场景热路径友好。

21.3 运行时还是 Python

浮点、列表、正则、io 都是 CPython 本体——性能特征、并发模型（threading/multiprocessing/asyncio）、C 扩展互通全部继承。基准测试也证实如此（tests/test_perf_bench.py：同算法中文灵语与原生 Python 运行时间持平；偶发 8/9 是其环境计时噪声，单独重跑即绿）。

22. i18n 汉化机制

第三方库对象上的成员名默认是英文：窗口.title()。i18n 层让.中文 也合法，两种机制互补：

22.1 注册词表（全局中文成员词表）

from lingyu.i18n import 注册词表
注册词表({"标题": "title", "几何": "geometry", "关闭": "destroy", "主循环": "mainloop"})

默认词表已合并「跨库通用词袋」（34 项），注册词表 按需永续扩充，同名后到覆盖先到。

22.2 汉化(类, 词表=None)：类级别名注入（主推）

把词表里的「中文→英文」对作为同名属性注入类，之后实例直接 .中文（等价 .英文）：

从 lingyu.i18n 导入 汉化, 注册词表
导入 tkinter 作为 界面库

注册词表({"标题": "title", "几何": "geometry", "关闭": "destroy",
          "主循环": "mainloop", "更新": "update", "打包": "pack",
          "按钮": "Button", "标签": "Label",  …})
汉化(界面库.Tk)

根 = 界面库.Tk()
根.标题("灵语窗口")        # → root.title(...)
根.几何("240x120")
根.更新()
打印("窗口标题 =", 根.标题())
根.关闭()                  # → destroy()

规则：中文名与类已有属性不冲突才注入；词表项在类上解析不到就跳过（宁缺毋滥）。返回原类，可链式。

22.3 中文(对象)：代理兜底

from lingyu.i18n import 中文
w = 中文(window)
w.标题("你好")     # 代理 getattr/setattr，中文名→英文映射
w.title            # 不在词表的名字按原名放行

适合动态/未知实例；对字典/列表等本源集合类型仍走原生访问，不破坏。

22.4 通用词袋（lib_catalog.通用词袋）

跨库最高频 34 项默认可用：打开 关闭 读取 写入 保存 加载 创建 添加 移除 更新 获取 设置 删除 清空 启动 停止 计数 长度 编码 解码 解析 序列化 反序列化 绘制 展示 标题 文本 颜色 大小 路径 名称 转换 格式化 初始化。任何库对象上都能写 .中文。

22.5 汉化入口写入 PRO 的普适 API

灵库（cnlib，见下节）装载中文库时自动对官方库类调用 汉化 注入各自词袋；自己写小脚本时按 22.2/22.3 按需启用即可。

23. 灵库（cnlib）：100 个中文库

「导入 请求库」就跑，背后是 LIB_CN：100 个常用第三方库的中文调用名。构成了两级中文 API：

23.1 使用方式

import lingyu 时 cnlib.安装() 已自动注册——官方中文字典无需额外导入：

# 数据框示例.灵（examples/数据框示例.灵 原样）
导入 数据框库

表 = 数据框库.数据框({"甲": [1, 2, 3], "乙": [4, 5, 6]})

打印("—— 数据表头部 ——")
打印(表.头部(2))          # 实例中文方法 .头部 → pandas.DataFrame.head
打印("—— 中文 API ——")
打印("平均 =", 表.平均())   # .平均 → mean
打印("求和 =", 表.求和())   # .求和 → sum

23.2 命名规律

• 数据科学：数值计算库(numpy)、数据框库(pandas)、科学计算库(scipy)、符号计算库(sympy)、类表库(polars)、数组库(xarray)、并行数据库(dask)、统计模型库(statsmodels)。
• 绘图：绘图库(matplotlib)、统计绘图库(seaborn)、交互绘图库(plotly)、词云库(wordcloud)、可视化库(bokeh)。
• 图像：图像库(pillow)、计算机视觉库(opencv-python)、图像处理库(scikit-image)。
• 机器学习：机器学习库(scikit-learn)、张量库(torch)、张量流库(tensorflow)、梯度提升库(xgboost)、机器学习加速库(lightgbm)、自然语言库(transformers)。
• 网络：请求库(requests)、异步请求库(httpx)、异步IO库(aiohttp)、网页解析库(beautifulsoup4)、浏览器自动化库(selenium)、爬虫框架库(scrapy)。
• Web：轻量服务器库(flask)、异步接口库(fastapi)、重型框架库(django)、模板引擎库(jinja2)。
• 数据库：对象关系库(sqlalchemy)、MySQL驱动库(pymysql)、Mongo驱动库(pymongo)、缓存数据库库(redis)、小型ORM库(peewee)、轻量数据库库(sqlite3)。
• 办公：电子表格库(openpyxl)、Excel写库(xlsxwriter)、YAML库(pyyaml)、TOML库(toml)、Word文档库(python-docx)、演示文稿库(python-pptx)、PDF库(fpdf2)、表格库(tabulate)。
• 文本：中文分词库(jieba)、拼音库(pypinyin)、语法高亮库(pygments)、Markdown解析库(markdown)。
• 时间：时间增强库(arrow)、人性化时间库(humanize)、时区库(pytz)、日期解析库(python-dateutil)。
• 终端/界面：窗口库(tkinter)、命令行框架库(click)、命令行库(typer)、进度条库(tqdm)、轻量GUI库(easygui)、桌面GUI库(pywebview)。
• 系统：系统进程库(psutil)、文件监控库(watchdog)、任务调度库(schedule)、压缩库(zstandard)。

完整 100 条见 lingyu/lib_catalog.py 的 LIB_CN。

23.3 每库中文 API（API_词表 节选）

• numpy：数组 零数组 一数组 单位数组 等差 等距 点积 排序 求和 最大 最小 扁平 拼接 堆叠。
• pandas：数据框 序列 读表(read_csv) 读取表(read_excel) 合并 透视 交叉表。
• matplotlib：绘图 显示 标题 X轴标签 Y轴标签 图例 网格 保存图 横条 散点 直方图 子图 X范围 Y范围。
• requests：获取 发布 放置 删除 会话 获取文本 头部请求。
• flask：应用 请求 回应 重定向 渲染模板 会话 JSON回应。
• jieba：分词 清单分词 添加词。
• PIL（图像库）：图像 指向加载到的 Image 子模块本体（而非 Image 类）——图像库.图像.new(...)/图像库.图像.打开(...) 等模块级函数可直接使用；Image 类成员（.保存/.裁剪/...）见 23.4 类词表。
• cv2：读图像 写图像 转颜色 改变大小 画矩形 画圆 放文字 高斯模糊。
• ……

23.4 类成员级中文（类词表 节选）

• pandas.DataFrame：头部 尾部 描述 信息 形状 索引 列集 值 求和 平均 分组 排序 转置 重命名 填充 删除 检查空值 绘图 转为csv 取行(iloc)。
• pandas.Series：头部/尾部/求和/平均/值/索引。
• requests.Session：获取/发布/放置/删除/关闭；Response：文本/关闭。
• BeautifulSoup：查找 查找全部 选择 纯文本 子节点 字符串。
• openpyxl.Workbook：激活 保存 创建表 移除表。
• PIL.Image：保存 显示 裁剪 调整大小 旋转 复制。
• wordcloud.WordCloud：生成 生成文本 转为数组。
• arrow.Arrow：格式 时间戳 偏移；pdfplumber.Page：取表格。

23.5 守卫纪律（重要）

词表每一项注入前都会在真实官方模块/类上解析校验，解析不到就静默跳过——保证「宁缺毋滥、绝不注入幻觉词、绝不动官方库已有名字」（tests/test_m10_cnlib.py 全量校验）。这带来两个推论：

• 某中文化对象方法用不了 = 该词不在词表（口子已预留，欢迎向仓库补 API_词表/类词表——「有多少转多少」）。
• 官方库任何英文名、任何行为都不会被改动：中文库名只是给官方模块加别名。

23.6 scipy / aiohttp 为什么是空词表

顶层几乎没有按库可用的函数（都在子模块），宁可空词也不写幻觉词。需要时按库子模块用英文写，或补进词表。

同类空/极少词表库还有：tkinter（窗口库）、watchdog（文件监控库）、rich（丰富输出库）、scikit-image（图像处理库，导入名 skimage）以及 sqlalchemy（对象关系库，仅类词表）；它们的顶层同样没有可按库直用的函数，规则一致。

24. 脂译器（lingku）

目标：把一段「纯英文 Python 库源码」脂译为中文，产物直接进 translate → compile → exec 的原生管道。

• 词级替换：import → 导入、def → 定义、print → 打印、os → 操作系统、.mean → .平均……全表来自 BUILTINS/MODULES/METHODS/MODULES_MEMBERS 的反向索引（首个优先）。
• 安全纪律：

1. 只替换 NAME token，语言关键字保持英文原样（灵语兼容英文，语义不变）；
2. __init__、__name__、__main__ 等 dunder 一律豁免（协议契约名）；
3. 点号后的成员名（re.compile、str.join）是 API 契约，一律豁免；
4. 字符串/注释在 token 层天然不受污染；未入表的自定义名保留英文。

标准库上层脚本的典型脂解例（把 Python 库主体转成中文名稀疏但仍 100% 等价的版本）。工具函数：

from lingyu.lingku import lingify, replaced_name_count
源码 = open("某英文.py", encoding="utf-8").read()
中文源码 = lingify(源码)
# replaced, total = replaced_name_count(源码, 中文源码)

含义：灵语能读纯英文第三方库代码（并从中吸收中文别名），这是「有多少转多少」的编程观里最高效的增量路径。

25. 与 Python 生态互编

25.1 边界保证（为什么翻译是安全的）

• 字符串与注释永不被污染；全角归一化只在 NAME/NUMBER/OP/ERRORTOKEN token 上发生。
• 词表外标识符原样通过（用户英文变量名、库英文 API、双下划线协议）。
• f-string 花括号内的表达式会被单独 token 级翻译（含字符串则整段原样）。
• BOM、坏缩进、多行字符串等极端输入都有逐行兜底填充（多个 feed 阶段覆盖）。

25.2 双向读写

25.3 区分「名字」与「成员」

.标题/.title 等成员中文化属于 i18n/灵库层（22/23 节），与编译器无关。这是设计分界：翻译器管语法词，运行时管成员词。同理，_gen.py 是「已翻译的 Python」，永远和 .灵 严丝合缝（行号 1:1），这也是 PyCharm 断点能直接落在 .灵 上的原因。

26. LSP 语言服务与语法高亮

26.1 lingyu-lsp（stdio JSON-RPC）

零依赖、纯 Python，任何一种支持 LSP 的 IDE 都能接（PyCharm + LSP4IJ、VS Code、Neovim…）：

python -m lingyu.lsp      # 服务器本体（读 Content-Length 帧、写 stdio）
# 直接跑也能活着：echo | python -m lingyu.lsp

initialize 宣告的能力与行为：

真机验证路径见 docs/PyCharm指南.md（LSP4IJ 注册服务 lingyu-lsp 或 python -m lingyu.lsp，映射到项目）。

26.2 语法高亮

灵语高亮的权威实现在 lingyu_ide/highlight.py：直接复用 tokenize + keywords 词表把源码切分成 9 类 token——关键字 / 内置 / 成员 / 名称 / 中文名 / 字符串 / 注释 / 数字 / 操作符。输入不完整（正在打字）也不会炸。

• 桌面工作室：PySide6 的 QSyntaxHighlighter 整文档重算着色，同一套分类（颜色表见 27.6）。
• PyCharm / VS Code：提供 TextMate 语法（editors/lingyu.tmbundle/、lingyu.tmLanguage.json），已含 .灵 fileTypes，见 29 节。

26.3 词表索引（lsp._doc_index）

悬停/补全背后是保存在词典里的 300+ 词与英文对照（含模块归属提示 平均值 → mean(module statistics)）。自动生成、权威定义在 keywords.py。

工具链

27. 灵语桌面工作室

官方 IDE（PySide6），面向最终用户，一键安装、内置运行时、拖拽停靠、断点调试。以下全覆盖其界面与能力。

27.1 界面布局

菜单栏  文件(&F) 编辑(&E) 视图(&V) 工具(&T) 运行(&R) 帮助(&H)
工具栏  新建 · 打开 · 保存 ｜ ▶运行 ■停止 ｜ ▶调试 ▶▶继续 步过 步出 ■结束调试
───────── 标签页（多文档 · 未保存带 ●）前有行号区（点行号切换断点）
状态栏  文件路径 · 行/列 · 语言：灵语 · 当前消息
底部停靠 输出 ／ 问题（可互相叠放 tabify），右侧停靠 变量（调试时出现）

所有停靠面板（输出/问题/变量）都可拖动成独立窗口再拖回，多显示器顺手。窗口布局（geometry）在关闭时保存，重启还原。

27.2 快捷键总表

27.3 编辑器能力

• 语法高亮：整文档分词着色，分类见 26.2；关键字加粗防色彩堆叠。
• 实时诊断：输入停顿 0.4 秒后自动跑诊断（langsrv.诊断）；语法错误/未定义名等以红色波浪线标到词尾，同时出现在底部「问题」面板（级别 / 行:列 / 消息），双击条目跳转到对应行。
• 内嵌补全：Ctrl+Space → 前缀匹配全部保留名+成员名（含中文与英文），选中即插入；未输入时给出全量 2000 项截断列表。
• 跳转定义：F12 在 定名 名字(…/类 名字 定义间定位（含翻译改名兜底的双轨索引）。
• 状态栏词义：光标落在中文词上时，状态栏显示其英文对应（轻量 词义，不走全行 zhify）。
• 行号区：默认显示；当前行号加粗高亮；点击某行号切换断点；有断点的行显示红点。
• 当前行高亮：黄色琥珀底（浅色主题）可关。
• 标签页：可拖动排序；关闭带 ● 未保存的标签会询问（保存/取消/放弃）；全部关闭自动补一张空白页；「最近打开」记录 6 条。
• 字号 9–26、制表符宽度 2–8（默认 4）、自动换行 开关——全在「设置 → 编辑器 / 主题&字体」。

27.4 运行与输出

• 运行：F5。内部运行器把 stdout/stderr 重定向并入「输出」面板（UTF-8，含中文回溯）。
• 临时脚本：未保存就运行的文档落到 ~/.lingyu_studio/临时运行.灵，行为与正式保存完全一致。
• 运行前自动保存：默认开启（可在设置关掉）。
• 自动化：运行器 支持脚本参数（未来传参）、退出码在状态栏显示（运行完成 / 运行结束（返回值 N））。
• 停止：Shift+F5。内置模式用 PyThreadState_SetAsyncExc 向脚本线程注入 SystemExit（失败会提醒手动结束）；外部解释器模式 terminate()，1.5 秒没退再 kill()。
• 运行超时：设置「运行和调试 → 脚本运行超时（秒，0=不限时）」；到点自动停止，防死循环占住编辑器。

27.5 断点调试

• F7 进调试。无断点时，脚本先暂停在首个可执行行；有断点时停在命中的断点行。
• 暂停后：F8 继续、F10 步过、Shift+F10 步出、工具栏 ■ 结束调试 立即终止。
• 右侧「变量」面板以 名称/类型/值 树列出当前帧可见变量（过滤 __dunder__、值过长截断），每步自动刷新。
• 当前正在执行的行以高亮底标记；调试结束后自动清除并隐藏变量面板。
• 调试基于 sys.settrace 纯逻辑核心（见 28.3），断点/单步在脚本线程挂起、主线程 QTimer 30ms 轮询命中与结束——不依赖 GUI 手势，测试也能驱动。
• 调试始终使用内置运行时（外部解释器仅用于运行模式）。

27.6 主题与配色

两套主题继承 GitHub Primer 设计语言（白纸底 + 发丝边框 + 链接蓝/金色强调）：

语法色（关键字/内置/成员/名称/中文名/字符串/注释/数字/操作符）：浅色取 Primer 表 #cf222e/#0550ae/#e36209/#1f2328/#8250df/#0a3069/#6e7781/#0550ae/#cf222e；深色取 GitHub Dark #ff7b72/#79c0ff/#ffa657/#e6edf3/#d2a8ff/#a5d6ff/#8b949e/#79c0ff/#ff7b72。整窗 QSS 随主题切换，帮助阅读器也取自同一角色色（随主题自适应）。

27.7 设置（工具 → 设置，Ctrl+,）

左侧分类导航，右侧内容页，改动即时应用并持久化（QSettings("灵语","灵语桌面工作室")）：

• 常规：启动时恢复上次会话（打开最近文档）；关闭时保存窗口布局。
• 解释器：运行时版本展示；运行方式 = 内置运行时（随包，零配置）或外部 Python 解释器（可同步第三方库）；选外部后可「浏览…」选 python.exe、「重新检测」版本（要求 Python 3.11+；-VV 探测）。说明文字明示：内置已随包、外部解释器环境里的 numpy/pandas/requests 等直接可用、调试仍用内置运行时。
• 编辑器：显示行号 / 高亮当前行 / 自动换行 / 制表符宽度（2–8）。
• 主题&字体：浅色 / 深色 主题；字号（9–26，生效即时；Ctrl++/Ctrl+- 微调）。
• 运行和调试：运行/调试前自动保存当前文档；脚本运行超时（0–3600 秒，0=不限时）。
• 终端&shell：输出面板自动滚动到底（仅展示行为；灵语运行在内置 Shell，无外部终端依赖）。
• 关于：灵语 logo 行、灵语桌面工作室 v2 · 运行时 vX、能力简介、版权。
• 恢复默认：把上述全部还原为默认值（主题=浅色、字号=12、解释器=内置等）。

27.8 解释器模式（含第三方库工作流）

切换入口：设置 → 解释器。例如：pip install numpy pandas requests 到外部解释器 → 切「外部」、浏览选其 python.exe → 脚本里 导入 数值计算库 即用。外部模式同样输出到「输出」面板（stdout/stderr 合并回灌）。

27.9 帮助与指南

• 帮助菜单内置四篇 Markdown 文档（不使用网络，离线可查）：快速上手 / 界面介绍 / 深入使用 / 帮助与常见问题。
• 帮助 → 指南：动态发现安装目录与工作目录下 docs/ 的 Markdown（当前把含「对照表」的文档挂出来，即 别名对照表.md），随安装/工作目录变化自动列出。
• 阅读器用 Qt QTextDocument::setMarkdown 渲染，样式随当前主题自适应；支持外链点击跳转。

28. 备用 IDE（lingyu_ide）

零第三方依赖的轻量 tkinter IDE（纯官方标准库），在你的环境装不了 PySide6 时兜底使用，也承载了语言/调试的核心纯逻辑。

28.1 界面

文件树 · 编辑器 · 控制台 三区布局；多标签编辑（Document 为逻辑真源：打开置换、保存回写）。

28.2 键位表（与桌面工作室不同处已标注）

28.3 调试核心（lingyu_ide/debugger.py，纯逻辑可单测）

• 实现：sys.settrace + 脚本线程；断点/单步命中 → 线程挂起（10ms 睡眠循环）；主线程 继续/单步_步过/单步_步出/停止 解除、等待() 等命中防死锁。
• 脚本以 __lingyu_debug__ 命名空间 exec 执行，源码行与帧行 1:1。
• 能力：设置断点/移除断点/切换断点、调用栈()（格式「函数名 于行 N」）、变量 帧局部字典、求值(表达式) 在暂停帧求值、变量_格式化 值截断 200 字符防卡。

28.4 其它配套

• highlight.py：统一高亮实现（26.2，桌面工作室复用同一套）。
• runner.py：子进程运行器，输出进控制台面板。
• lsp_client.py + core/：轻量 LSP 客户端与会话/设置持久化。

29. PyCharm 集成

PyCharm 是灵语的主 IDE 之一（社区版可用），完整图文指南在 docs/PyCharm指南.md，这里给出精华四步：

1. 前置：在「项目解释器」使用能 import lingyu 的 Python（桌面工作室内置运行时，或把项目根目录加进该解释器的 PYTHONPATH / 作为源码目录关联），lingyu、lingyu-lsp 命令才能被 IDE 内部找到。
2. 语法高亮：启用内置「TextMate Bundles」插件 → 部署 editors/lingyu.tmbundle/（一键脚本 python tools/install_lingyu_lsp.py，或手动拷到 %APPDATA%\JetBrains\PyCharm<版本>\textmate\）→ 重启。.灵 自动识别为「灵语」语言。
3. LSP（诊断/补全/悬停/跳转定义）：Marketplace 装 LSP4IJ → Tools → LSP → Language Servers 新建：Name=lingyu-lsp、Command=lingyu-lsp（不稳则 python -m lingyu.lsp）→ 映射到项目。打印( 触发补全，未知名红波浪，F12/Ctrl+点击 跳转，悬停得中文写法提示。
4. 运行/断点调试：Run → Edit Configurations → Python。方式 A（推荐）：Module name = lingyu，Parameter = 脚本.灵；方式 B：Script path = tools/lingyu_run.py，Parameters = 脚本.灵 参数…。之后 F5 运行、Debug（虫子图标）调试——灵语编译时用 .灵 源路径作 co_filename，翻译行号 1:1，断点直接打在 .灵 行号上，变量面板显示中文名。

排障速查：控制台乱码加环境变量 PYTHONIOENCODING=utf-8；断点不中先确认运行配置走 run_script_file、删 .lingyu_cache/ 重试；LSP 不生效查 Server state/日志（先开 verbose）。

30. 打包与分发

30.1 桌面工作室的产物链

Python 源码（lingyu_studio/ 等）
   │  PyInstaller（tools/lingyu.spec）
   ▼
dist\灵语桌面工作室\          ← onedir 绿色版：拷走即用，双击 lingyu-studio.exe
   │  Inno Setup（灵语安装器.iss）
   ▼
dist\灵语桌面工作室-安装程序.exe   ← ~163 MB 一键安装包

• 目标电脑无需 Python：内置完整灵语运行时与 PySide6。
• 安装后：开始菜单 / 桌面快捷方式「灵语桌面工作室」，发布者 jzm。
• 安装器与 exe 的产品信息（CompanyName=jzm、版本等）走 tools/lingyu_version.txt 的 VSVersionInfo 脚手架（全部 \u 转义）。
• 重新打包：python -m PyInstaller tools/lingyu.spec；然后重跑 Inno 编译即可（源码开发模式就 python -m lingyu_studio）。

30.2 语言本身的"分发"

• .灵 源码 + 运行时：目标机器装灵语（桌面工作室安装包或绿色版目录），python -m lingyu 脚本.灵 直跑。
• 纯 Python：python -m lingyu --export 脚本.灵 成品.py — 产出等价 .py，任何有 Python 的机器都能跑。

实战

31. 官方示例逐例精讲（examples/）

仓库自带 13 个 .灵，覆盖语言全部主干特性：

运行方式（全部）：cd examples 后 python -m lingyu <文件名>.灵，或在桌面工作室打开按 F5。

32. 综合工程实战

32.1 命令行工具：中文标签文本词频统计

导入 数学
从 容器 导入 计数器

文本 = 打开("文章.txt", encoding="utf-8").读()
词们 = 文本.字符替换("\n", " ").字符替换("，", " ").split(" ")

出现 = 计数器(词们)
打印("总词数：", 长度(词们))
打印("前十高频词：")
循环 词, 次 于 出现.most_common(10):
    打印(词, 次)

（.字符替换 走灵语方法别名；split/most_common 是官方英文 API，直接调用即可——词表外一律原样保留。）

32.2 Web 小服务（外部解释器模式 + 中文库）

从 轻量服务器库 导入 应用, JSON回应

应用对象 = 应用(__名__)

@应用对象.路由("/")
定义 首页():
    返回 JSON回应({"消息": "你好，灵语！"})

若 __名__ == "__main__":
    应用对象.run(port=5000)

（路由 是 flask 的装饰器，JSON回应 是灵库词表里的 jsonify；run 属官方英文 API，原样调用。）

32.3 数据科学流程（numpy + pandas + matplotlib）

导入 数值计算库
导入 数据框库
导入 绘图库

数组 = 数值计算库.零数组((3, 3))
打印("数组 =", 数组)

表 = 数据框库.数据框({"x": [1, 2, 3, 4], "y": [2, 4, 6, 8]})
打印(表.描述())

绘图库.绘图(表["x"], 表["y"])
绘图库.标题("示例曲线")
绘图库.保存图("曲线.png")
绘图库.显示()

32.4 带进度条的批量任务

导入 进度条库
导入 时间

循环 i 于 进度条库.进度(范围(100)):
    时间.睡眠(0.01)
打印("完成！")

（进度条库.进度 = tqdm；第三方库请先切换外部解释器安装。）

32.5 模式学习建议路线

入门（第 3–8 章）→ 数据容器（13–15 章）→ 函数与类（9–10 章）→ 异常/文件/异步（11、16、17）→ REPL+CLI 冒烟（18–19）→ 报错破解（20）→ 第三方库实战（22–23）→ 换 IDE（27–29）→ 打包分发（30）。

33. 命名纪律与别名约束

语言层面的守则，写代码前请记住：

1. 保留名不可作标识符：keywords.py 聚合 _ALL（中文别名均为保留名）。词表总量与分类口径见《别名对照表.md》头部自动统计：「关键字 38 · 特殊名 4 · 内置 99 · 模块 33 · 模块成员 124 · 方法 8 · 合计 305（全局唯一成员 132）」（另含导入名 参数→argv，须显式 从 系统 导入 参数 后才生效，未导入时按普通标识符保留，见 12.6）。is_reserved(name) 可判定。变量/参数/函数/类/属性/导入名不要用这些中文词（或对应英文也不要用，会被翻译替换），唯一例外是 参数：未 从 系统 导入 参数 时它可当普通标识符用。
2. 匹配顺序：翻译按 KEYWORDS > DUNDERS > DUNDER_METHODS > BUILTINS > IMPORTABLES > 模块成员 > 模块名别名 > GLOBAL_MEMBERS 依次尝试；先到先得。所以 列表、字典、类型、范围 等永远是内置，不是普通名。
3. 成员重名规则：当前词表的模块成员（124）与方法名（8）全部全局唯一、全部进入全局直用集，尚无跨模块重名。若将来词表补入同一个中文名对应多个来源，重名者将排除在直用集之外，只能用 模块.成员 或 从…导入 原名 as 新名 指定来源。
4. import 别名粘合：导入 某模块 作为 中文名 用「as」方言在导入头部就地绑定；块内其余位置写中文名即可。
5. 全角：能归一化的都是符号类；中文汉字作为普通文本参与标识符/字符串，不受影响。
6. 守卫纪律：任何运行时词表（i18n/灵库）的注入项都要在真实对象上可解析，解析不到就静默跳过——宁缺毋滥、绝不注入幻觉词、绝不动官方库已有名字。
7. 文件约定：.灵 后缀、UTF-8 编码、4 空格缩进（写模板与报错均强调）。

34. 常见问题（FAQ）

• 这台电脑没有编程环境能用吗？ 能，安装包自带运行时与编辑器，安装即用（无需 Python）。
• 运行报错怎么办？ 输出面板/CLI 以中文回溯给出出错行与建议；多数是名字拼写/未定义——回溯会直接提示「您是否想用：xxx」。桌面工作室更可双击「问题」面板条目自动跳到出错行。
• 想中途停掉死循环？ Shift+F5；或在设置里给脚本设运行超时（秒），到点自动停。
• 中文能不能和英文混用？ 完全能：关键词与常用 API 中文，字符串、变量名、库英文 API 可混写；纯英文源码也原样编译。
• 第三方库怎么用？ 二选一：①标准库中文名直接 导入（数学/系统/JSON…）；②切外部解释器装库后 导入 请求库/数据框库/…（100 个中文库名）。需要的小库名不在 LIB_CN？用 导入 pip名 作为 名 也一样。
• .标题 为什么还报错？ 成员中文化不属于编译器，需要走 i18n：注册词表({…}) + 汉化(类)（推荐）或 中文(对象) 代理；或用灵库已对的库里已有的中文类成员（如 pandas 头部）。窗口示例见 31 节窗口示例.灵。
• 断点不命中？ 确认运行配置走了 run_script_file（桌面工作室/方式A/方式B），没走其它；删 .lingyu_cache/ 重试。
• 控制台乱码？ 加 PYTHONIOENCODING=utf-8（PyCharm 环境变量），或桌面工作室直接看内置输出面板（已 UTF-8）。
• _gen.py 是什么？能删吗？ 每次运行 .灵 会在同目录落一份「已翻译的 Python」，供调试/报错对齐行号（目录只读/不可写时自动跳过落盘、直接从内存运行，不影响执行）；--clean 可清理，_gen.py 会被重新生成，不必见它慌。
• .lingyu_cache/ 是什么？ 字节码缓存目录，可整目录删除，只是重新编译一次。
• 性能会比 Python 慢吗？ 不会明显慢；翻译/编译开销有缓存，运行期就是 Python 字节码（21 节）。

35. 附录：词表与延伸阅读

• 完整 305 项对照表：docs/别名对照表.md（由 tools/gen_keywords_doc.py 自动生成，4 列排版速查；权威在代码里）。
• 权威定义：lingyu/keywords.py（KEYWORDS / DUNDERS / DUNDER_METHODS / BUILTINS / MODULES / MODULES_MEMBERS / IMPORTABLES / METHODS / GLOBAL_MEMBERS / is_reserved）。
• 翻译器：lingyu/translate.py（含全角表与 f-string 安全翻译、反向展示 zhify）。
• 编译与运行：lingyu/compiler.py（报错映射 _MSGS/_TYPE_MSGS/_VALUE_MSGS/_IMPORT_MSGS、format_traceback、run_script_file）。
• 缓存：lingyu/cache.py（LYC2、sha256+版本键、原子写）。
• 多文件：lingyu/importer.py（.灵 meta_path 钩子）。
• i18n：lingyu/i18n.py + lingyu/lib_catalog.py（通用词袋/LIB_CN）。
• 灵库：lingyu/cnlib.py（API_词表/类词表/安装()）。
• 脂译：lingyu/lingku.py（lingify / replaced_name_count）。
• LSP：lingyu/lsp.py；高亮：lingyu_ide/highlight.py；调试核心：lingyu_ide/debugger.py。
• 桌面工作室源码：lingyu_studio/（app/editor/theme/settings_dlg/mdview/langsrv/runner/debugsess/main）。
• 其它文档：docs/INSTALL.md（安装）、docs/PyCharm指南.md（PyCharm 全流程）、docs/教程-快速上手.md、docs/公测说明.md、docs/IDE架构方案.md、根目录《中文编程语言项目建议书》。
• 测试：tests/ 全量 225 项（python -X utf8 -m pytest tests -q；其中性能基准 3 项单独跑，日常门禁 --ignore=tests/test_perf_*.py），覆盖翻译、编译、REPL、CLI、缓存、i18n、灵库、LSP、工作室、调试。
• GitHub 关联：github.com/jzm/lingyu（发布者 jzm）。

祝你在灵语里写下第一行真正属于中文的代码。有词表缺口，请按「有多少转多少」补进 keywords.py / lib_catalog.py / cnlib.py——这门语言的生长靠每一位使用者。