# E-Language 编码手册 (LLM Coding Reference)

> 本手册是写给大模型（和人类）的权威编码参考。写E代码前必读。
> 版本：v1.0（2026-09-05）| 语法契约基线：e_contract_v0 + EB08双轨编译器

## 0. 快速上手：30行看懂E

```e
space<8> std {
  fn gcd(a: u64, b: u64) -> u64
}

fn std::gcd(a: u64, b: u64) -> u64 {
  // @augment: 欧几里得辗转相除法
}

fn main() -> i32 {
  x: u64 = 462
  y: u64 = 1071
  x | std::gcd(y) | assert_eq(21)
  return 0
}
```

这就是一个完整的E程序：声明空间 → 签名 → 实现体（LLM填） → main入口 → 管道调用+断言验收。

## 1. 语法规则（确定性骨架，编译器100%处理，零LLM）

| 语法 | 含义 | 示例 |
|------|------|------|
| `space<N> 名字 { ... }` | 内存域声明，N=字节对齐 | `space<8> std { ... }` |
| `fn name(参数) -> 返回类型` | 函数签名 | `fn gcd(a: u64, b: u64) -> u64` |
| `fn 空间::name(...)` | 带空间限定实现 | `fn std::gcd(a: u64, b: u64) -> u64` |
| `变量: 类型 = 值` | 变量声明 | `x: u64 = 462` |
| `expr \| f(参数)` | 管道：等价 f(expr, 参数) | `x \| std::gcd(y)` |
| `// @augment: 提示词` | LLM填充指令，只作用于紧邻的空函数体 | `// @augment: 快排+随机枢轴` |
| `assert_eq(期望值)` | 断言验收（接在管道尾部） | `\| assert_eq(21)` |
| `return 值` | 返回 | `return 0` |

### 类型系统
- 整数：`u8 u16 u32 u64` / `i8 i16 i32 i64`
- 浮点：`f32 f64`
- 其他：`bool str`
- main约定：`fn main() -> i32`，返回0=成功

### LLM边界（铁律，越界=编译期拒绝）
- ✅ LLM只能填空函数体 `{}` 内的代码（C语句风格）
- ❌ 不得改动签名/space声明/管道结构/assert
- 编译器校验签名一致后才采纳LLM产物

## 2. 双轨编译模型（怎么从.e到可执行文件）

```
.e源码
  ↓ 确定性前端（词法/解析/骨架AST/类型契约）— 100%确定性，零LLM
  ↓ LLM语义增强（只填@augment标记的空函数体）
  ↓ C发射器（EB05）
  ↓ GCC编译 + ASan沙盒
  ↓ 三轮运行验收（签名比对）
可执行文件 ✅
```

验收标准：GCC编译通过 + 3轮运行 + 签名输出匹配。

## 3. 语义算子层（空间/流形操作，见API.md全集）

| 算子 | 语义 | 示例 |
|------|------|------|
| `space<N>("描述")` | 开辟张量语义空间 | `Ω = space<256>("Analytics")` |
| `\| create("意图")` | 增：流形锚定 | `A = Ω \| create("初始化")` |
| `\| update("增量")` | 改：流形演化 | `B = A \| update("登录")` |
| `\| read()` | 查：签名坍缩 | `sig = B \| read()` |
| `\| delete()` | 删：拓扑剪枝 | `C = B \| delete()` |

## 4. 编码守则（写给LLM的实战经验）

1. **@augment提示要具体**：写"欧几里得辗转相除,位运算优化"比写"求最大公约数"通过率高得多
2. **函数体用C子集**：EB05发射器当前接受C语句级语法，勿用C++特性/变长数组/复杂宏
3. **一个函数一个职责**：超过40行的函数体容易超时或被ASan拦
4. **先想验收再写代码**：assert_eq的期望值要和goal里的criteria一致
5. **类型提前算好**：u64做中间量防溢出；除法注意除零；数组访问先判界
6. **管道从左到右读**：`x | f(y) | g(z)` = `g(f(x,y),z)`，嵌套别超过3层

## 5. 完整示例库（可复制改造）

### 示例1：算法函数（池任务标准模板）
```e
space<8> std {
  fn max_subarray(arr: &i64, n: u64) -> i64
}

fn std::max_subarray(arr: &i64, n: u64) -> i64 {
  // @augment: 卡丹算法,单扫O(N),全局/局部最大交替维护,全负数边界处理
}

fn main() -> i32 {
  // 测试数据+断言
  return 0
}
```

### 示例2：数据管线（语义算子流）
```e
Ω = space<128>("Task Queue Stats")
s1 = Ω | create("队列初始化")
s2 = s1 | update("生产者入队 100")
sig = s2 | read()
```

### 示例3：NE原生替换（生产接线模板）
```e
// 对标cron任务: 池统计器(NE03实物)
space<8> poolstat {
  fn count_str(path: &str, needle: &str) -> i64
}
fn poolstat::count_str(path: &str, needle: &str) -> i64 {
  // @augment: 64KB缓冲流式读文件,memmem计数,防跨块漏匹配
}
```

## 6. 常见错误与规避

| 错误 | 症状 | 规避 |
|------|------|------|
| 改了签名 | "编译期拒绝: 签名不一致" | 只填函数体 |
| @augment太模糊 | LLM产物偏离意图 | 写算法名+关键优化点 |
| 溢出 | 断言值对但ASan报UB | 中间量用u64/i64 |
| 管道嵌套过深 | 解析失败 | 拆中间变量 |
| 函数体过长 | 900s超时 | 拆函数 |

## 7. 路线与边界声明（诚实口径）

- 当前编译器：Python骨架（M4后换E自举=第一相抛Python）
- 当前后端：发射C→GCC（ET03 IR直发=第二相抛C）
- libc仍为C实现（E-VM原语重写在路线图）
- 本手册随语法演进同步更新，以仓库 `elang_frontend/e_contract_v0.md` 为真源

---
*生成：EOS进化流水线 | 手册真源：projects/elang/docs/E_LANG_GUIDE.md*