Qi 语言 (奇语)

Qi（奇语）是一门 100% 中文关键字的编译型语言，经 LLVM（inkwell 后端，LLVM 21）编译为原生可执行文件。当前版本 2026.07.12-1，安装：brew tap qilang-project/qi https://github.com/qilang-project/homebrew-qi && brew install qi（布局 /usr/local/bin/qi + /usr/local/lib/qi/ 运行时，解压即用）。内存管理为 ARC（自动引用计数，默认开启）。

相关技能：qi-web（Web 框架）、qi-cli（命令行框架）、qi-harness（LLM Agent 框架）—— 均为 Qi 写的第三方包，用它们时先读对应技能。

何时使用此技能

• 编写 .qi 文件、理解/调试/修复 Qi 程序或编译错误
• 用语言级 LLM 原语写 AI 程序（询问/流式/嵌入/工具适配/磁带）
• 使用 Qi 标准库（HTTP、JSON、数学、哈希表、图形化 GUI、大模型等）
• 并发程序（启动/通道/未来/等待，真协程默认开）
• 组织多文件 Qi 项目、配置 qi.toml 依赖、qi get 拉包、qi test 跑测试
• 交叉编译 Linux/龙芯部署产物、排查内存（ARC）行为

程序结构速查

可执行程序必须 包 主程序; 开头 + 函数 入口() 入口（库包用自己的包名、不写入口）：

包 主程序;

函数 加法(x: 整数, y: 整数): 整数 {
    返回 x + y;
}

函数 入口() {
    变量 名字 = "Qi";              // 类型推断；不可变用 常量
    变量 年龄: 整数 = 10;          // 显式类型
    如果 年龄 > 8 且 年龄 < 15 {
        打印行(模板"你好，{名字}！结果={加法(1, 2)}");   // 模板插值，{}内任意表达式
    } 否则如果 年龄 > 5 {           // 干净的 else-if 链
        打印行("中");
    } 否则 {
        打印行("小");
    }
    对于 i 在 0..3 { 打印行(i); }   // 半开区间；0 到 2 闭区间等价
    对于 i 在 0 直到 3 { 打印行(i); } // 直到=半开关键字写法，等价 0..3（不含 3）；到=含端点。`0 直到 长度(数组)` 遍历全部下标
}

基础类型：整数(i64)、浮点数(f64)、字符串、布尔(真/假)、空。字符串拼接用 +（可直接拼数字）。类型转换用内建函数：整数转字符串 浮点数转字符串 字符串转整数 字符串转浮点数 整数转浮点数 浮点数转整数。

LLM 原语（语言核心差异点）

LLM 调用是语言级原语，不是库。会话先建（无隐式默认，参数顺序 URL→模型→密钥）：变量 会话 = 大模型.创建会话(URL, 模型, 密钥);

类型 天气 { 字符串 城市; 整数 温度; }

// ① 结构化输出：类型即 schema，自动校验重试 ≤2 次
变量 天: 天气 = 询问::<天气>(会话, "东京天气");

// ② 失败不炸版：结果<T, 字符串>
匹配 尝试询问::<天气>(会话, "…") { 成(t) => {} 败(e) => {} }

// ③ 真并行：立即发请求，等待 时才解码（多路并行 ≈ 单路耗时）
变量 f: 未来<天气> = 异步询问::<天气>(会话, "…");
变量 t: 天气 = 等待 f;

// ④ 一等流迭代（token 级片段，循环结束自动关流）
对于 片段 在 流式(会话, "介绍北京") { 打印(片段); }

// ⑤ 签名即工具：从函数签名生成 tool schema + JSON 实参适配器
工具模式(查天气)   // -> OpenAI tool 参数 schema 字符串
工具适配(查天气)   // -> 函数(字符串):字符串 适配器（配 qi-harness 添加工具）

// ⑥ 嵌入与余弦相似度
变量 v1: 数组<浮点数> = 嵌入(嵌入会话, "文本");
变量 近: 浮点数 = 相似度(v1, v2);

• 询问::<T> 的 T 支持：标量 / 无载荷枚举（分类）/ 带载荷枚举（分类+提取合一，匹配 解构 驳回(原因) =>）/ 嵌套结构体（≤5 层）/ 数组 of 结构体 / 选项<T> 可选字段（缺键或 null → 无；v1 内层仅标量）。
• 填充模板("…{城市}…", 实参…) 编译期洞校验；运行时插值用 模板"…{表达式}…"。
• 预算：大模型.设置预算(会话, token上限) 超限直接拒调（没有 在预算(){} 块语法）。
• 磁带：QI_LLM_RECORD/REPLAY/CACHE=1 + QI_LLM_TAPE=t.json 零改码录制/回放/缓存（CI 判分用 REPLAY 确定性零费用）。
• 工具函数 v1 限制：必须返回 字符串、形参仅标量。异步询问无校验重试。
• 详见 references/大模型.md。

真协程（默认开，2026.07.12 起）

「返回 未来<T> 且含 等待」的函数编译成 LLVM coroutine，多核 M:N 调度（worker = CPU 核数，QI_CORO_WORKERS 覆盖；QI_CORO=0 退 eager）。门控函数级——普通程序 IR 逐字节不变。协程内通道有 park-wake 背压 + 死锁检测（全挂起报错不 hang）；等待 让出() 显式让出、执行器运行全部() 统一推进。微基准 vs Go：上下文切换 2.6 倍胜、通道/创建/扇入胜，纯 CPU 密集暂负（优化档位）。启动 函数(…) goroutine、通道<T>（整数/字符串/浮点数/布尔）、选择{情况…} 见 references/并发异步.md。

高频坑清单（全部实证，2026.07.12-1）

1. 结构体字面量唯一写法 新建 类型{…}——旧括号包裹 (点{x:1}) 已删，解析错误（返回值位置同理 返回 新建 点{…};）。
2. else-if 是干净的 } 否则如果 条件 {——旧双写 否则如果 如果 现在是解析错误；链尾 否则 可选。
3. 插值用 模板"…{任意表达式}…"；f"..." 仍是 codegen 陷阱，永远别用。逻辑运算 且 或 非 与 && || ! 等价。
4. turbofish 只能跟函数名：最大::<整数>(7,4)；泛型结构体/枚举直接尖括号（新建 对<整数>{…}、变量 o: 选项值<整数> = 选项值.有值(7);——变体 turbofish 是编译错误）。嵌套泛型 >> 写空格 > >。
5. 特性三件套可用：特性（可带默认方法，体内 自己.抽象方法()）/ 实现 特性 对于 类型 / 约束 <T: 特性>；特性可作参数类型（动态派发）。按元数重载可用（同名不同参数个数；返回类型须一致，不能配默认参数/变参）。
6. 枚举：枚举 形状 { 圆(浮点数), 点 } 构造 形状.圆(3.14)、匹配解构可配守卫、穷尽性编译期强制。内建 选项/结果 用裸构造子 有/无/成/败。变体名不能用保留字。
7. 匹配 只能作语句不能作表达式；支持字面量/守卫/_/变量绑定；不支持或模式 |。选择 支持 默认/超时(毫秒)（Go 冒号语法）。
8. 保留字地雷（不能作变量/函数名）：结果 类型 尝试 继续 返回 到 直到 数组 释放 列表 选择 选项 除 新建 空 加 真 假 且 通道 未来 循环 乘 减 模板 特性 等——报错会提示换名（数组→数列）。长度 例外可用。全集见语法参考。
9. 打印行 逗号多参逐参各占一行（并发下还会交错）。永远 + 拼成单串再打印。
10. 同一函数里两个循环慎复用同名字符串局部变量——曾触发 RC 释放路径 bug（拿到已释放值；简单形态实测已不复现，但复杂拼接场景稳妥起见换名或提到循环外）。全局数组/全局 RC 变量泄漏已修（main 出口统一释放，QI_RC_REPORT=1 实测活跃对象=0）。
11. 模块别名后字符串返回类型会丢失：导入 标准库.输入输出 作为 IO; 后赋值要加 : 字符串 标注，否则打印出指针数字。
12. 无注解竖线闭包返回类型默认 空——写返回注解或用 闭包(x: 整数): 整数 {}。闭包存进变量后必须作为函数参数传递才能调。
13. 浮点数组字面量元素必须写 1.0：[1,2,3] 推成整数数组，传 向量.*/数学.* 是垃圾。
14. 文本.子串 按字节索引，切在多字节字符中间直接 panic（中文 3 字节/字）。
15. GUI 程序需要 gui feature 运行时：cd qi-runtime && cargo build --release --features gui；默认构建是桩版（应用创建 返回 0 报「GUI 库未安装」），不带 feature 重建会覆盖回桩版。
16. qi-web 发二进制静态文件发不出（UTF-8 字符串管道，图片会坏）——base64 内联或外部静态服务，详见 qi-web 技能。
17. 端口规范：示例严禁 8080/3000/8000，用 3000 以上随机高位如 6759、43719、46271。
18. 同目录同包的无导入文件会被自动并入编译；含 导入 的文件必须显式 导入 ./文件名;。跨包只支持 destructure：导入 Web::{创建应用, …}。

深入阅读路由

要做什么	读哪个文件
类型/控制流(否则如果/且或非)/函数(默认参数/变参/重载)/结构体与方法/特性/泛型/闭包/异常/字符串(模板插值)/数组/保留字	references/语法参考.md
LLM 原语全家：询问::/尝试询问/异步询问/工具模式/流式/嵌入/填充模板/预算/磁带	references/大模型.md
标准库各模块 API（输入输出/文本/JSON/HTTP/数学/哈希表/图形化 GUI/子进程…）与返回值约定	references/标准库.md
启动(goroutine)/通道/未来与等待/让出/选择/协程异常/同步原语/QI_CORO	references/并发异步.md
CLI 命令与中文别名/-O 优化/交叉编译(Linux/龙芯)/qi test/qifmt/qi doctor/FFI/ARC 环境变量	references/工具链.md
qi.toml 依赖三种写法/qi get 与缓存/qi.lock/导入解析顺序/多文件项目组织	references/包管理.md

CLI 速查

qi run 程序.qi          # 编译并运行（别名 qi 运行）
qi check 程序.qi        # 只查语法（别名 检查）
qi compile 程序.qi -o 出  # 编译（别名 编译）；-O maximum 最高优化
qi test .              # 发现并运行 *_测.qi（别名 测试）
qi get                 # 拉取 qi.toml 远程依赖（别名 拉取）
qi doctor 程序.qi       # 一体化诊断：环检测+CPU热点+RC（别名 诊断）
qifmt 文件.qi           # 格式化（只动空白；qi format 是未实现的桩）