Metadata-Version: 2.4
Name: jikuai
Version: 0.24.0
Summary: 极快 - 适合中国国情的中文编程语言
Author: skywalk163
License-Expression: MIT
Keywords: chinese,programming-language,中文编程
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: coverage[toml]>=7.0; extra == "dev"

# 极快 JiKuai

> 极简·极速·极中国

一门为中国开发者量身定制的中文编程语言。

## 设计理念

1. **极简语法** — 双字关键词，无空格分词，句号结语句
2. **极速上手** — 百家姓变量名，中文数字字面量，自然语序
3. **极中国** — 内置人民币运算、农历日期、中文正则、成语断言

## 语言特色

### 管道式数据流（逗号管道）
```
列1 2 3 4 5，皆乘2，只大6，归加0。
```
结果：`30`

逐段解释（每段的结果自动成为下一段的第一参数）：
1. `列1 2 3 4 5` → `[1, 2, 3, 4, 5]`
2. `皆乘2`（map）→ `[2, 4, 6, 8, 10]`
3. `只大6`（filter）→ 注意 `大` **不是**内建动词（内建比较动词是 `大于`），
   副词内部遇到未知动词时按原值透传，本段**不产生过滤效果** → `[2, 4, 6, 8, 10]`
4. `归加0`（reduce，初值 0）→ `0+2+4+6+8+10` = `30`

> 若想真正过滤「大于 6」，应写 `只大于6`：`列1 2 3 4 5，皆乘2，只大于6，归加0。` → `18`。

### 元数驱动解析
动词声明参数个数，免括号调用：
```
加 3 5。        -- 结果 8
打印 "你好"。   -- 输出：你好
```

### 无空格书写
```
定义张三=100。
如果张三大于60那么：
  打印"及格"。
否则：
  打印"不及格"。
```

### 百家姓标识符
变量名以百家姓开头，天然与关键字/动词区分：
```
定义赵甲=10。
定义李乙="程序员"。
打印赵甲加5。
```

### 中国特色内置

#### 人民币类型
```
定义王价格=￥99.90。
定义赵总价=王价格乘3。
打印赵总价。          -- ￥299.70
```

#### 农历日期
```
定义李今天=农历今日。
打印李今天。          -- 二〇二六年闰六月廿三
```

#### 中文数字
```
定义周数=三百六十五。
打印周数加1。         -- 366
```

### 面向对象
```
类 动物：
  构造 接收 姓名 年龄：
    自身.姓名=姓名。
    自身.年龄=年龄。
  。
  方法 叫声：
    返回 "..."。
  。
。

类 狗 继承 动物：
  方法 叫声：
    返回 "汪汪"。
  。
。

定义赵狗=新建狗("旺财", 3)。
打印赵狗.叫声。     -- 汪汪
```

### 异常处理
```
尝试：
  定义李结果=除10 0。
捕获 错误：
  打印"出错了：" 错误。
最终：
  打印"清理完毕"。
。
```

### 模块系统
```
导入 数学。
从 文件 导入 读取。
```

### Python 互操作（v0.4.0）

> ⚠️ **安全声明**：pybridge **不提供完整沙箱隔离**，`DENY_LIST` 只是黑名单缓解手段，
> `importlib` 等间接路径可绕过。它适用于运行**你自己或可信来源**的 Python 代码，
> **不适用于执行不受信任的第三方代码**。若必须承载不可信输入，须在其外叠加进程级
> 或容器级隔离。完整声明见 [`docs/安全边界.md`](docs/安全边界.md) 与
> [`docs/ADR-21-pybridge安全边界.md`](docs/ADR-21-pybridge安全边界.md)。

极快 → Python：
```
导入 蟒:math。
打印 math.sqrt(16)。    -- 输出 4.0
导入 蟒:json。
打印 json.dumps(列 1 2 3)。  -- 输出 [1, 2, 3]
```

Python → 极快：
```python
import jikuai

mod = jikuai.load("script.jk")
print(mod.某函数(3))     # 调用极快函数
print(mod.某变量)        # 读取极快变量
obj = mod.某类(参数)     # 实例化极快类
```

## 文件扩展名

`.jk`

## 示例与场景

`examples/` 下按主题组织了可直接运行的示例（全部 `退出码 0`）：

### 管道范式（`examples/pipelines/`）
| 文件 | 教学目标 |
|------|----------|
| `01_多级过滤映射聚合.jk` | 过滤→映射→聚合的多级逗号管道 |
| `02_条件分支管道.jk` | 管道结果结合 如果/否则 条件分支 |
| `03_字典结构化数据.jk` | 字典键值访问、`皆取值"键"` 字段投影 |
| `04_异常在管道中传播.jk` | 尝试/捕获/最终 拦截管道中的异常 |
| `05_副词组合.jk` | 皆/只/归 三副词的单用与组合 |
| `06_中国特色管道.jk` | 人民币金额、农历/干支/生肖进管道 |

### 场景脚本（`examples/scenarios/`）

平铺单文件脚本 **6 个**：

| 文件 | 场景 |
|------|------|
| `财务计算.jk` | 报销单：`￥` 字面量、税费、大写金额、汇总 |
| `农历工具.jk` | 公历→农历、干支纪年、生肖、甲子循环 |
| `管道数据清洗.jk` | 脏数据 → 多级管道（≥3 段）→ 干净结果 |
| `报销单演示.jk` | L3 聚合块 `报销单`：财务 + 历法 + 中文跨域 |
| `工资册演示.jk` | L3 聚合块 `工资册`：多人工资条批量 → 中文报表 |
| `客户对账演示.jk` | L3 聚合块 `客户对账`：载入 → 分组汇总 → 差异比对 |

另有 **4 个多文件场景**（各自一个目录，含 `main.jk` + `README.md` + `expected.txt` 快照）：
`财务报表/`、`农历日程/`、`文本批处理/`、`推理演示/`。


### Reasonix 推理引擎演示

用极快写一个完整的多阶段推理引擎，展示**多模块 OOP + 字典字面量 + Python 互操作（`蟒:` 桥）+ AI API 调用**的综合能力：

```bash
python -m jikuai examples/scenarios/推理演示/main.jk "为什么没有重量级的中文编程语言"
```

输出示例（DeepSeek deepseek-v4-flash 模型）：
```
========== 极快 Reasonix 推理引擎 ==========
╔══════════════════════════════════════════╗
║   极快 JiKuai Reasonix 推理引擎 v1.0     ║
║   基于 Chain-of-Thought 的多步推理演示   ║
╚══════════════════════════════════════════╝
  [AI 模式] 使用 deepseek-v4-flash 模型

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  问题：为什么没有重量级的中文编程语言
  开始推理...
┌─ 第1阶段/共4阶段 · 理解问题 ──────────┐
│ ...（AI 实时生成的分步推理）
└──────────────────────────────────────────────────────────┘
┌─ 第2阶段/共4阶段 · 信息提取 ──────────┐
│ ...
└──────────────────────────────────────────────────────────┘
┌─ 第3阶段/共4阶段 · 逻辑推理 ──────────┐
│ ...
└──────────────────────────────────────────────────────────┘
┌─ 第4阶段/共4阶段 · 验证答案 ──────────┐
│ ...
└──────────────────────────────────────────────────────────┘
════════════════════════════════════════════════════════════
║  最终答案
════════════════════════════════════════════════════════════
基于 4 个推理阶段，结论如下：
  1) 理解问题：...
  2) 信息提取：...
  3) 逻辑推理：...
  4) 验证答案：...
════════════════════════════════════════════════════════════
========== 推理结束 ==========
```

- 无需额外 pip 依赖（HTTP 用标准库 `urllib`）
- 配置 `.env`（API Key + Base URL）后自动走 AI 模式；不配则走离线模拟
- 问题可命令行传入，也可不传用默认题

运行示例：
```bash
jk examples/pipelines/01_多级过滤映射聚合.jk
jk examples/scenarios/财务计算.jk
jk examples/scenarios/管道数据清洗.jk
```

## 语法备注

### 全半角标点等价

极快语言对以下标点支持全角/半角双写，二者语义完全等价：

| 全角 | 半角 | 语义 |
|------|------|------|
| `（` | `(` | 左括号 |
| `）` | `)` | 右括号 |
| `【` | `[` | 左方括号 |
| `】` | `]` | 右方括号 |
| `：` | `:` | 冒号（块起始） |
| `，` | `,` | 逗号（管道 / 分隔符） |
| `、` | `,` | 顿号（同逗号） |

> **变更留痕**：ASCII 半角逗号 `,` 作为管道与参数分隔符的支持在 v0.3.0-beta 实现期追认，
> 与已有的全半角括号 `(` / `（` 双写策略同源。追认为「实现期追认的语义扩展」。


## 安装与使用

```bash
pip install jikuai
jk examples/hello.jk
jk              # 进入 REPL
```

`pip install jikuai jikuai-lsp jikuai-dap` 一并装上编辑器语言服务与调试适配器。

### 从源码开发

```bash
cd G:\jikuai
pip install -e .
jk examples/hello.jk
```

从源码开发时 `stdlib/` 在 `src/jikuai/stdlib/`，随包发行；也可用环境变量
`JIKUAI_STDLIB` 指向自定义 stdlib 根（值须是已存在目录，否则回落包内默认值）。

### 三种等价入口

以下三种方式完全一致，均归一到 `jikuai.main:main`：

```bash
jk examples/hello.jk           # pip install jikuai（或 -e .）后可用
python -m jikuai examples/hello.jk   # 无需安装，只要 PYTHONPATH 含 src/
python -m jikuai.main examples/hello.jk   # 不推荐：会打印 runpy RuntimeWarning
```

第三种写法功能等价，但 `jikuai/__init__.py` 会提前导入 `jikuai.main`，
runpy 因此报 `RuntimeWarning: 'jikuai.main' found in sys.modules ...`。
外部调用方（如 yanpub）请用 `python -m jikuai`。

无参数时均进入交互式 REPL；`-h` 显示帮助；`-v` 显示版本。

### v0.15.0 三通道 quickstart（选块 → 组代码 → 跑）

同一套「三段式设计语言」`[需求]→[候选]→[产出]`，三条通道共享同一 JSON 协议
（`docs/协议-三通道.md`）。

**CLI** —— 管道式一条龙：
```bash
jk 块 选 "月薪两万个税多少"      # 语义选块，出候选（--json 走机读协议）
jk 块 组 方案.json               # 候选拼成方案 → 生成 .jk 源码
jk 块 跑 方案.json --json        # 执行，出 {源码, 执行结果:{stdout,返回值,...}}
```

**LSP** —— 编辑器语言服务（stdio JSON-RPC，零第三方依赖）：
```powershell
pip install jikuai-lsp                # 装包用法（与主包同号发布）
# 或从源码：
$env:PYTHONPATH = "src;lsp"       # 或先 pip install -e . 与 lsp/
python -m jikuai_lsp               # completion/hover/definition/documentSymbol/
                                   # signatureHelp/references/rename/极快.选块
# VS Code 扩展安装指引见 docs/LSP-使用.md
```

**Web** —— 本地单页（标准库 `http.server`，不引框架；含方案存档与原地更新）：
```bash
python tools/web/server.py         # 默认 http://127.0.0.1:5000/
# 浏览器打开上述地址：需求框 → 候选卡片 → 代码+运行结果
```


## 项目结构

```
jikuai/
├── src/jikuai/               # 主包（解释器 + 前端 + 服务层）
│   ├── main.py               # CLI 与 REPL 入口
│   ├── lexer.py              # 无空格分词器
│   ├── parser.py             # 元数驱动解析器
│   ├── frontend.py           # 两遍分词前端（ADR-06 X2）
│   ├── evaluator.py          # 求值器/解释器
│   ├── keywords.py           # 关键字/动词/百家姓定义
│   ├── surnames.py           # 百家姓表（400+ 单姓 + 复姓）
│   ├── tokens.py             # Token 类型
│   ├── ast_nodes.py          # AST 节点
│   ├── module_loader.py      # 模块解析（.jk / stdlib / 包）
│   ├── pybridge.py           # 蟒: Python 互操作桥
│   ├── completion.py         # 补全/元数查询（LSP/REPL 共用）
│   ├── stdlib_contract.py    # 标准库导出契约
│   ├── diagnostics/          # 诊断内核（ADR-14，唯一真源）
│   ├── service/              # 三通道服务层（schema/session/position）
│   ├── ai/                   # 语义选块检索（纯标准库，ADR-25）
│   ├── pkg/                  # 块生态 + 包管理（jk 块 / jk 包）
│   ├── resources.py          # 标准库定位唯一入口（ADR-39）
│   └── stdlib/               # 标准库（包内资源，随 wheel 发行 · ADR-39）
│       ├── blocks/           # 块生态（112 块 · 索引.json + 向量索引.bin）
│       └── *.jk / *.py       # 分词/排版/校验/成语/正则/简繁/历法/工具
├── lsp/                      # Language Server（独立发行包，零依赖）
│   └── jikuai_lsp/           # server/capabilities/transport
├── dap/                      # Debug Adapter（独立发行包）
│   └── jikuai_dap/
├── tools/                    # 试验性 / 辅助工具（不随主包发行）
│   ├── aot/                  # AOT 子集编译（Experimental · ADR-19）
│   ├── web/                  # 本地 Web 单页（标准库 http.server）
│   └── ai-bridge/            # 神经检索/向量索引/粘合器（neural 依赖隔离于此）
├── editors/vscode/           # VS Code 扩展（语法高亮 + LSP 客户端 + 调试）
├── examples/                 # 示例程序
│   ├── pipelines/            # 管道范式示例（6 个）
│   └── scenarios/            # 场景化脚本（6 个平铺 .jk + 4 个多文件 demo）
├── benches/                  # 基准测试
├── scripts/                  # 门禁与工具脚本（契约校验 / 索引生成）
├── tests/                    # 测试
└── docs/                     # 文档（语法参考 / 包管理 / ADR / BACKLOG 等）
```

> 待办与已知边界的**唯一真源**是 [`docs/BACKLOG.md`](docs/BACKLOG.md)。
