# 奇语言 Qi (qilang)

> 100% 中文关键字、经 LLVM 21 编译为原生机器码的编译型编程语言。语法类似 Rust/Go 的中文化版本。
> 当前版本 2026.07.03-2。ARC 自动内存管理默认开启;完整异常机制(尝试/捕获/最终/抛出);包管理 qi get;-O 四档优化管线;macOS/Linux/Windows 三平台 + 交叉编译。
> 官网 https://qilang.org/ · 完整语言参考(LLM 可读): https://qilang.org/llms-full.txt

## 骨架
包 主程序;
函数 入口() { 打印行("你好"); }

## 关键规则
- 入口函数必须叫 入口。打印行/打印 是全局内建,无需导入。
- 保留字不能当标识符:结果 类型 选项 通道 未来 数组 列表 字典 集合 任务 循环 尝试 捕获 抛出 最终 返回 等待 异步 新建 选择 情况 在 作为 与 或 非 等。要用就改名(结果值/类型名)。
- 整数 = i64(不是 i32)。布尔字面量 真/假。字符串 + 可直接拼数字。
- 方法 Go 风格:函数 (自己 类型) 方法名(...) { }。结构体字面量必须括号包裹:(用户 { 姓名: "张三" })。
- 没有 0..10 区间语法;对于 x 在 数组 仅遍历数组。计数循环用 当。跳出/继续 可用(当/对于 内,嵌套只作用最内层)。
- 匹配(match)可用:分支体是块 `1 => { ... }`,支持守卫(k 如果 k>100)、_ 通配、变量绑定,块尾分号可选;只能作语句(不能 变量 x = 匹配 ...);不支持结构体解构/或模式 2|3。
- 选择(select)可用(2026.07.03+):非阻塞轮询多通道,支持 默认/超时(毫秒) 分支,皆无则阻塞;分支 Go 风格冒号 `情况 v := <-通道: 语句`,分支体不带花括号。
- 读取文件失败返回空串(不是 NULL),用 文本.字节长度(x)==0 判失败;写入文件 1=成功。
- HTTP 模块大写:标准库.HTTP。字符串模块是 标准库.文本(字符串 是类型关键字)。
- 跨包 destructure 导入:导入 Web::{创建应用, 运行应用}(「启动」是关键字不能作导入名)。不支持 Web::函数()。
- 通道只有 通道<整数> 可用;发送 信道 <- 值,接收 <- 信道。
- 端口用随机高位 3076/6759/43510,不要 8080/3000/8000。

## 类型
整数(i64) 浮点数(f64) 布尔(真/假) 字符串(ARC 管理) 字节 短整数 空
转换用内建:整数转字符串 浮点数转字符串 字符串转整数 字符串转浮点数 浮点数转整数 整数转浮点数

## 控制流
如果 cond {...} 否则 {...} | 当 cond {...} | 对于 x 在 [1,2,3] {...} | 匹配 n { 1 => {...} _ => {...} };

## 异常(完整可用)
函数 除法(a: 整数, b: 整数): 整数 { 如果 b == 0 { 抛出 "除数不能为零"; } 返回 a / b; }
尝试 { ... } 捕获 错误 { ... } 最终 { ... }   // 跨函数传播;goroutine 内异常进全局队列(协程异常数量/获取协程异常)

## 并发与异步
启动 函数调用(...);   // goroutine,主协程退出即进程退出,用 等待组/睡眠 收尾
函数 双(v: 整数): 未来<整数> { 返回 v*2; }  变量 r: 整数 = 等待 双(21);
等待组:创建等待组/添加等待/完成/等待组等待。同步原语:标准库.同步(原子/互斥锁)。

## 内存
ARC 默认开启:字符串/结构体/数组/闭包自动回收。句柄式资源(JSON/列表/哈希表/服务器/子进程)手动 删除/释放。
QI_RC_REPORT=1 退出打印活跃对象计数;QI_ARC=0 关闭(调试)。循环引用不回收(同 Swift)。

## 标准库(30+ 模块,导入 标准库.模块名)
输入输出 文本 JSON HTTP 网络(TCP/UDP) WebSocket 加密 正则 时间 哈希表 列表 随机 路径 操作系统 子进程 数据库(SQLite) 压缩 配置 大模型(LLM) MCP服务器/MCP客户端 命令行 测试 同步 环境 向量 图形化(GUI) TLS 信号 字节切片

## 包管理
qi.toml([包]/[依赖],键名中英皆可) + qi get 拉取 + qi.lock 锁 commit。编译期零联网。
qi get github.com/x/y@v1.0 ;缓存 ~/.qi/packages。

## 框架(用奇语言写)
qi-web(Web,147k RPS): 导入 Web::{创建应用,配置,获取,文本,运行应用}; handler=函数(上下文):响应
qi-cli(Cobra 风格): 导入 CLI::{创建应用,创建命令,执行}; handler=函数(上下文):整数
qi-harness(LLM agent): 导入 Harness::{大模型,开启会话,创建代理,简单问,关闭代理}

## Agent skills
npx skills add https://github.com/qilang-project/qi-lang  (基础语言)
各框架仓库根目录有 SKILL.md。

## 命令(全部有中文别名)
qi check 文件.qi(查语法,rustc 风格错误) | qi run 文件.qi(运行) | qi compile 文件.qi -o out
qi test(发现并运行 *_测.qi) | qi get(拉依赖) | qifmt 文件.qi(格式化)
-O none|basic|standard|maximum 优化;--target linux --arch x86_64 交叉编译(zig 链接,零 Docker)

## 下载
https://github.com/qilang-project/qi/releases 2026.07.03-2(macOS arm64 / Linux x64 / Windows x64,解压即用)