给 AI / Agent

这页是给 AI 编码助手看的浓缩规则。让 LLM 一次性读完就能正确生成奇语代码——避开所有已知陷阱。

纯文本版（适合喂给模型 / 抓取）：/llms.txt。可安装的 agent skill：npx skills add https://github.com/qilang-project/qi-lang。

一句话定位

奇语（Qi）= 100% 中文关键字、编译到 LLVM 原生码的系统级语言。语法像 Rust/Go 的中文化版本。

骨架（每个程序都要）

包 主程序;
导入 标准库.输入输出 作为 IO;
函数 入口() {
    IO.打印行("你好");
}

• 入口函数必须叫 入口（不是 主函数 / main）
• 打印用 IO.打印行 / IO.打印
• 语句以 ; 结尾；支持中英标点（；，：（） 都行）

最高频错误（务必避免）

1. 保留字当变量名：结果 类型 选项 通道 尝试 返回 等待 异步 新建 选择 情况 在 作为 未来 继续 跳出 捕获 抛出 最终 不能做标识符。要用就改名：结果值 类型名。
2. 整数是 i64 不是 i32。
3. 方法是 Go 风格：函数 (自己 类型) 方法名(...) { }，不是 方法 类型.名。
4. 读取文件失败返回空串（不是 NULL）；用 字符串::字节长度(x)==0 判失败。写入文件 返回 1=成功。
5. HTTP 模块大写 标准库.HTTP。
6. 跨包用 destructure 导入：导入 Web::{创建应用, 启动}，不支持 Web::函数()。
7. 端口用随机高位（3076/6759/43510），不要 8080/3000。

类型速查

整数(i64)  浮点数(f64)  布尔(真/假)  字符串  字节  短整数  空

常用模式

// 变量
变量 名: 字符串 = "x";
变量 数: 整数 = 1;
常量 PI = 3.14;
// 控制流
如果 (n < 2) { 返回 n; } 否则 { 返回 n - 1; }
当 (i < 10) { i = i + 1; }
对于 i 在 0..10 { IO.打印(i); }
// 函数
函数 加(x: 整数, y: 整数) : 整数 { 返回 x + y; }
// 结构体
类型 点 { x: 浮点数, y: 浮点数 }
变量 p = (点 { x: 1.0, y: 2.0 });
// 异步
函数 双(v: 整数) : 未来<整数> { 返回 v * 2; }
变量 r: 整数 = 等待 双(21);
// 数字转字符串拼接
变量 行 = "n=" + 整数转字符串(数);

三个框架（用奇语写）

• qi-web：导入 Web::{创建应用, 配置, 获取, 文本, 运行应用}，handler 签名 函数(上下文): 响应。
• qi-cli：导入 CLI::{创建应用, 创建命令, 执行}，handler 签名 函数(上下文): 整数，链式 API 要回写。
• qi-harness：导入 Harness::{大模型, 开启会话, 创建代理, 简单问, 关闭代理}，密钥从环境变量读。

每个框架带 SKILL.md，生成对应代码前先读：qi-web · qi-cli · qi-harness · 基础语言。

验证生成的代码

qi check 文件.qi   # 只查语法，报 rustc 风格错误
qi run 文件.qi     # 编译运行