# she

**Repository Path**: ledao/she

## Basic Information

- **Project Name**: she
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-06-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# She

> Go 体验 · Python 语法 · Rust 安全 · 原生编译

She 是一门面向"教学 + AI 工程"的小语言。语法接近 Python(冒号 + 缩进、`def`、类型注解),
工具链布局接近 Cargo,后端走 [Cranelift] 直接生成 ELF / Mach-O,核心数据类型(包含 `Tensor`)
内置在 Rust 实现的运行时里。

[Cranelift]: https://cranelift.dev/

> **当前方向与状态(2026-06-01 暂停)**:项目定位已锁定为「**Rust crate 胶水语言**」——
> 用 RC 当胶水、crates.io 当标准库、链接期进程内拼装(见 [ADR 0004](plans/adr/0004-glue-language.md))。
> 暂停时的完整交接见 **[`plans/STATUS.md`](plans/STATUS.md)**(两条线程:crate 胶水 / stackless 协程)。

## 快速开始

```bash
# 构建工具链
cargo build --release -p she-cli -p she-lsp -p she-runtime

# 把二进制加到 PATH(或创建符号链接)
export PATH="$PWD/target/release:$PATH"

# 创建项目
she init hello
cd hello

# 构建并执行(`she run` = build + exec,0.9 起无解释器)
she run

# 仅编译为原生二进制
she build
./target/hello
```

## CLI 子命令

| 命令 | 作用 |
|---|---|
| `she init <name>` | 创建新项目(`she.toml` + `src/main.py` + `.gitignore`) |
| `she run [file]` | 构建并执行(build + exec)。无参数时读 `she.toml` 跑 `src/main.py` |
| `she check [file]` | 类型检查,不执行 |
| `she build [file]` | 编译为原生二进制。manifest 模式输出到 `target/<name>` |
| `she add --rust <n> --path <dir>` | 加 Rust crate 胶水依赖到 `[rust-deps]`(见 STATUS.md) |
| `she bindgen <file.rs> --type <T>` | 从 Rust API 自动生成 C-ABI shim + She 句柄绑定 |
| `she build --target <triple>` | 交叉编译(支持 `x86_64-apple-darwin`、`x86_64-unknown-linux-gnu` 等) |
| `she ast <file>` | 打印 AST(调试用) |
| `she lex <file>` | 打印 token 流(调试用) |

## 项目结构

```
myproj/
├── she.toml         # 包元数据(name / version)
├── src/main.py      # 入口源文件
└── target/<name>    # `she build` 产物
```

## 当前能力

- **类型**:`int / float / bool / str / None`
- **复合**:`List[T]` / `Dict[K, V]`(解释器)/ `Tuple[T, ...]`
- **错误**:`Result[T, E]` + `?` 错误传播运算符
- **Tensor**:N 维 f64,`+ - * / @` + 标量运算 + `.shape` + `.dtype`
- **泛型**:目前仅 stdlib 类型(`List` / `Dict` / `Tuple` / `Result`)
- **编译**:Cranelift → ELF / Mach-O。strict 模式拒绝未注解 `Any`

## 开发阶段(见 `plans/0.1.md`)

| Phase | 状态 | 主要交付 |
|---|---|---|
| 0 | ✅ | Lexer / Parser / Tree-walking 解释器 |
| 1 | ✅ | 类型系统、Dict、`Result[T,E]` + `?`、循环检查、漂亮诊断 |
| 2 | ✅ | Cranelift 原生编译(int/float/bool/str/list/result/tensor) |
| 3.1 | ✅ | Tensor + ndarray 后端 |
| 3.2-3.4 | ⏳ | slice 语法、`std` 模块、`with grad:` 自动微分 |
| 4 | ⏳ | `nn` 神经网络库 |
| 5 (基础) | ✅ | 项目脚手架、交叉编译、最小 LSP、VS Code 扩展 |
| 5 (深) | ⏳ | GC、完整包管理器、完整 LSP 能力、LLVM 后端 |

## 仓库结构

```
crates/
├── she-ast/         # AST 节点(每个节点带 Span)
├── she-lexer/       # 词法分析(缩进敏感)
├── she-parser/      # 手写递归下降 + Pratt
├── she-typeck/      # 类型检查 + 诊断渲染
├── she-runtime/     # Tensor / heap types / C-ABI exports / 协程堆帧(coro_frame)
├── she-ir/          # 中端 IR(stackless 协程变换:AST→IR→堆帧分析)
├── she-codegen/     # AST → Cranelift IR → object file(+ coro_cg:IR→resume)
├── she-cli/         # `she` 主命令
├── she-bindgen/     # Rust crate API → C-ABI shim + She 句柄绑定 自动生成
└── she-lsp/         # `she-language-server`(LSP over stdio)

editors/
└── vscode/          # VS Code 扩展骨架

examples/            # 教学示例
plans/               # 开发计划
```

## 测试

```bash
cargo test --workspace          # 所有单测 + 集成测试
cargo build --workspace         # 构建所有 crate(应 0 warnings)
```

测试覆盖:
- 单元测试(lexer / parser / typeck / runtime tensor)
- `she run` 集成(`crates/she-cli/tests/run-pass/*.py`)
- `she check` 集成(`crates/she-cli/tests/check-{pass,fail}/*.py`)
- `she build` + 执行集成(`crates/she-cli/tests/build-pass/*.py`)
- `she run` 失败路径(`crates/she-cli/tests/fail/*.py`)

## 设计原则

1. **教学优先**:错误信息友好,失败路径有完整测试
2. **解释器 + 编译器双轨**:`she run` 用于开发(快),`she build` 用于发布(快+小)
3. **gradual typing**:无注解函数允许 `Any`;`she check` 给出建议但不强制;`she build` 严格要求注解
4. **零依赖运行时**:产物只链接 libSystem / glibc,不依赖外部 C++ 运行时

## License

MIT OR Apache-2.0