给 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: 整数, y: 整数) : 整数 { 返回 x + y; }
函数 双(v: 整数) : 未来<整数> { 返回 v * 2; }   // 异步:返回 未来<T> 自动包装
类型 点 { x: 浮点数, y: 浮点数, }

// 语句写在 入口 里
函数 入口() {
    变量 名: 字符串 = "x";
    变量 数: 整数 = 1;
    常量 PI = 3.14;
    如果 (数 < 2) { IO.打印行("小"); } 否则 { IO.打印行("大"); }
    变量 i = 0;
    当 (i < 10) { i = i + 1; }
    对于 n 在 [1, 2, 3] { IO.打印(n); }   // 无区间语法,计数用 当
    变量 p = (点 { x: 1.0, y: 2.0 });     // 结构体字面量要括号包裹
    变量 r: 整数 = 等待 双(21);           // 等待 取 Future 值
    变量 行 = "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     # 编译运行
← 常见问题