elench-lang 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,53 @@
+Elench — 权利归属说明 / Ownership notice
+=========================================
+
+本仓库的代码与文档按组件区分归属，目的是让"项目成果"与"非项目工作"在
+文件层面就有边界，而不是靠口头说明。
+
+一、本项目（北京邮电大学 2026 年雏雁计划）范围内的成果
+--------------------------------------------------------
+
+以下内容属于项目研究成果，知识产权归 **北京邮电大学** 所有
+（《北京邮电大学本科生创新创业实践活动管理办法》校教发〔2018〕22 号 第十一条）：
+
+  · src/lexer.py  src/parser.py  src/typecheck.py  src/checker.py
+  · src/interp.py  src/symbolic.py  src/cost_interp.py  src/cost_check.py
+  · src/stdlib.py  src/jsonval.py  src/fmt.py  src/dsh.py（解释器相关子命令）
+  · tests/cases/test_*.py（测试套，123 个文件）
+  · tools/（检查与复现工具：artifact_check / defect_report / demo_repair 等）
+  · 文档/（语言规格、设计文档、样例程序、决策记录）
+  · 预印本与演示论文（论文的署名权归作者，单位署名为北京邮电大学）
+
+学生作为实际完成人享有 **署名权**，并按学校与学院规定获得创新创业学分认定
+与推免支持；软著等登记事项以学校为著作权人办理。
+
+二、明确不在本项目范围内的内容
+--------------------------------
+
+以下内容 **不属于本项目成果**，不纳入上述产权约定：
+
+  · **编译器后端（代码生成）**：把 `.eln` 翻译为 C++ 或任何原生代码的
+    实现、以及为它生成的产物（`.cpp` / `.h` / 可执行文件）。
+    当前仓库中的 `elench cpp` 子命令属于**实验性、待移出**的部分：
+    它不承诺、不验收，也不使用项目经费与工时。
+
+若日后开发编译器后端，应 **另行立项**，或作为 **个人作品** 放在独立仓库，
+并在该仓库的 NOTICE 中单独声明归属。
+
+三、开源发布
+------------
+
+本仓库以 Apache-2.0 公开，**须经学校审批或备案**。
+发布时的版权行写法：
+
+    Copyright 2026 Beijing University of Posts and Telecommunications
+    (interpreter, specification, tooling)
+
+四、边界的时间依据
+------------------
+
+立项前已完成并公开的版本（v0.1）为 **前期基础**，不作为结题成果：
+
+    git tag v0.1-pre-project
+
+该 tag 的提交时间与 GitHub 发布时间戳，是"在先"的客观证据。

package/README.md

@@ -1,3 +1,303 @@
-# Temporary Holding Version
+# AI 导向编程语言
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **许可证**：代码与文档均为 [Apache-2.0](LICENSE)。
+> **引用**：见 [`CITATION.cff`](CITATION.cff)（GitHub 页面右上会出现「Cite this repository」）。
+> **DOI**：**尚无**。计划在 **M1 退出门槛②（双值域统一）达成后**打 tag `v0.70-m1` 并发布到 Zenodo。
+> 在拿到 DOI 之前，引用请用仓库 URL + 提交号，**不要编造 DOI**。
+
+
+> **把「我想让它多快」从注释里搬到编译器能查的地方。**
+
+一门面向 AI 代码生成的编程语言：函数不只写「怎么做」，还写「要做到什么程度」——**成本由编译器算出，由人设定目标，两者的差记为债务**。
+
+**当前状态**：**解释器、契约检查、成本域、最小 C++ 后端都在跑**（`src/`，**123 个测试文件**逐个通过）；契约检查覆盖 effects / 借用 / 目标，成本判定是三值（达成 / 债务 / 无法判定）；实验 S1–S4 已跑并出图。对外快照见 tag **`v1.0-preprint`**。
+>
+> **2026-11-06 更正**：这句此前是「设计 v0.66 / M0 完成 / 368 项测试 / M1 未开始 / 实验未跑」——**五项里四项已过期**。版本号不再手写在这里，以 `CHANGELOG.md` 与 tag 为准。
+**这不是一个能用的语言**：它是一套**可检查的契约系统**加一个够跑样例的实现。能做的：算上界、判契约、把「不知道」明确说出来；不能做的：替代 C++、当完整编译器。
+
+---
+
+## 安装（npm）
+
+```bash
+npm install -g elench-lang             # 装完命令叫 `elench`
+npx elench-lang --help                 # 不装也能试
+```
+
+> **包名 `elench-lang` 与命令名 `elench` 不同**：`elench` 被判与已有的 `wrench` 过近、
+> `elenchus` 是别人的包，所以包用 `elench-lang`；**装的命令仍是 `elench`**。
+
+**前置**：本机要有 **Python ≥ 3.10**（`python3` 或 `python` 在 PATH 里，或用 `PYTHON=/path/to/python` 指定）。
+npm 包是**薄包装**——它不含 Python 运行时，只带 elench 的源码与一个转发脚本。
+
+
+## 它要解决的两个问题
+
+| # | 问题 | 现在什么样 |
+|---|---|---|
+| 1 | **AI 写得出来，但核不了** | 性能信息只活在注释、PR 描述、作者脑子里，编译器一个都不看 |
+| 2 | **常数因子只能靠猜** | 哈希集/排序扫描/位图，选哪个取决于输入——AI 猜不出临界点，因为它本来就不可推断 |
+
+---
+
+## 六个机制
+
+### 1. 意图与事实分开：`target` 由人冻结，`cost` 由编译器算出
+
+```
+spec evaluate(text: []u8) -> Result[i64, CalcError] {
+    effects    {alloc};
+    target {
+        time      : { max: O(text.length()) },
+        allocation: { max: O(text.length()) },
+    };
+} end spec
+```
+
+编译器算出实际成本，写进 `evaluate.cost.yaml`（YAML，可 diff，变化项置顶）：
+
+```yaml
+functions:
+  evaluate:                    # ▲ 本次有变化
+    time:        {min: "n",   max: "n"}
+    allocation:  {min: "0",   max: "8*n"}
+    debt:        {time: none, allocation: none}
+```
+
+**让 AI 写 `cost`，等于让被考的人自己报分。** 改成算出来之后，这一处谎言就不可能发生。
+
+### 2. 声明与实现分家：`.tu` 装承诺，`.eln` 装实现
+
+| 文件 | 谁写 | 内容 |
+|---|---|---|
+| `模块名.tu` | 人（AI 提议） | 全部声明，几十行，**人真的会看完** |
+| `模块名.ai` | AI | 签名 + 函数体，**零声明** |
+| `模块名.cost.yaml` | 编译器 | 算出的成本 |
+| `模块名.dispatch.yaml` | 测量 | `?!` 选了谁 |
+
+**结果：可撒谎的位置 7 处（全在 `.tu`），`.eln` 里 0 处。**
+
+### 3. 算法选择外包给测量：`?!` + `choose` + `over` 名单
+
+候选写在宿主 spec 的 `choose` 子块里（完整程序见 [`样例/search.tu`](文档/样例/search.tu)）：
+
+<!-- @include 文档/样例/search.tu#choose -->
+```
+    choose search_impl(const Vec<u64>& xs, u64 key) -> u64! {
+        over {
+            search_linear,
+            search_binary,
+            search_interp pending
+        }
+        ;
+        objective time;
+    };
+```
+<!-- @end -->
+
+```
+val idx = ?!search_impl(xs, key);      // 只有这一步未定
+```
+
+| 硬规则 | 为什么 |
+|---|---|
+| `?!` 的承诺是**分段上界**：按运行期分档表逐段取「该段真正会跑的那个候选」的 κ；无表时退回「所有候选取 max」 | 承诺与运行期**同源**——跑的不是承诺里那个候选，界就不成立 |
+| `?!` **不能构成整个函数体** | 否则退化成"两套实现二选一"，生成者就不必想清楚算法结构 |
+
+### 4. 骨架先行：`pending`
+
+下面是上一节那个 `choose` 块的关键一行（片段；完整块见上一节，权威样例见 [`样例/search.tu`](文档/样例/search.tu)）：
+
+```
+    choose search_impl(xs: []u64, key: u64) -> Result[u64, SearchError] {
+        over      {search_linear, search_binary, search_interp pending};   // 声明：这个还没写
+    } end choose
+```
+
+| 命令 | 含未实现时 |
+|---|---|
+| `elench check` | **通过**（骨架合法、可审） |
+| `elench build` | **失败**（不能测量没写的候选） |
+
+**检查器能算出"谁没写"，但算不出"这是故意的还是漏的"**——`pending` 就是让作者承认。
+
+### 5. 每个可能出错的地方留痕
+
+| 设计 | 规则 |
+|---|---|
+| 算术返回 `Result` | `(a + b)?` —— 每个可能溢出的点必须写 `?` |
+| 文本是字节 | `[]u8`，一元素一字节（不是 8 字节） |
+| 无隐式转换 / 无类型后缀 / 一种写法 | `42u64` 是错的；`function` 是错误，不是兼容 |
+| 块必须有终止符 | `if … end if`、`match … end match`、`kernels … end fn` |
+
+### 6. 报告告诉你「哪些数字不能全信」
+
+每份成本报告有独立的**信任区**，列出全部被信任的声明及其影响面。
+**并把「算出来的」与「派生的」分开列——一个转发点不算一次独立验证。**
+
+---
+
+## 与其他语言的关系
+
+| 语言 | 它做什么 | 本设计不同在哪 |
+|---|---|---|
+| **C++** | 通用系统语言 | 不追求通用，不替代 C++ |
+| **Rust** | 内存安全 + 零开销 | 语义跟 Rust（移动、借用），但多一层**成本契约** |
+| **Dafny / F\*** | 全功能验证 | 只做**有界**的成本与效果检查，不做完整验证 |
+| **Zig** | 显式优于隐式 | 同源，但把「多快」也纳入显式 |
+
+**不做什么**：不自研后端；不承诺精确时间（只承诺量级 + 结构上界）；v0 不做代码生成与契约验证。
+
+---
+
+## 仓库结构
+
+```
+ai-lang-design/
+├── src/                     实现（Python；**C++ 后端是最小切片，不是替代品**）
+│   ├── lexer.py             词法分析
+│   ├── parser.py            解析（宽松超集，带 span 诊断）
+│   ├── checker.py           契约检查（F / B / V 系列、effects、借用、目标）
+│   ├── cost_domain/         成本域：符号界、目标比较、归因
+│   ├── interp.py            具体执行器
+│   ├── formatter.py         `elench fmt`（幂等、注释保留）
+│   ├── dsh.py               命令行入口（`elench` 是它的别名）
+│   └── …
+├── tests/cases/             **123 个测试文件**（逐个独立运行，全绿才算过）
+├── tools/                   对拍、数字对账、实验脚本
+├── corpus/adversarial/      对抗语料（判不了就说判不了）
+├── editors/                 VSCode 扩展（语法高亮）
+└── 文档/
+    ├── 语言介绍.md            ← 从这开始
+    ├── 一屏对比.md
+    ├── 语法清单.md
+    ├── 对抗语料.md           每条难例的归因
+    ├── 退出码与CI.md         各子命令的退出码 + 可抄的 CI 样例
+    ├── 设计/
+    │   ├── 目前设计/          **主线 10 份**：规格、语法清单、决定清单、目标、能力索引…
+    │   ├── 目前设计/未做/     **可开工的条目**（两份台账 + 分析稿）
+    │   ├── 目前设计/未做/挂起/ 裁定暂不做的提案（**有"什么情况下改主意"**）
+    │   └── 归档/              做完了的、被取代的
+    ├── 实验/                  A/B 实验、实测数据（默认不入库）
+    └── 其他/                  申报书草稿、入门长文、学习路线
+```
+
+> **2026-11-06 更正**：这一段此前写着"`未来计划/` 实现路线、M0/M00 计划"、
+> "规格 v0.66"、"`src/test_*.py` 368 项测试"——**三条都已过期**：
+> 未来计划/未来设计/战略三个目录已清空并入 `目前设计/未做/` 与 `归档/`；
+> 测试早已迁到 `tests/cases/`，当前 **123 个文件**。
+
+---
+
+## 从哪里读
+
+| 你想… | 读 |
+|---|---|
+| 快速判断值不值得 | [`文档/语言介绍.md`](文档/语言介绍.md) |
+| **一屏看差异（vs Rust）** | [`文档/一屏对比.md`](文档/一屏对比.md) |
+| 看语法长什么样 | [`文档/语法清单.md`](文档/语法清单.md) |
+| 看一个完整例子 | [`文档/样例/示例-三个构造.md`](文档/样例/示例-三个构造.md) |
+| 参与实现 | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+| **下一步做什么** | [`CHANGELOG.md`](CHANGELOG.md) |
+| 看条款（给实现者） | [`文档/语法清单.md`](文档/语法清单.md) |
+| 看哪些是原创判断 | [`文档/设计/目前设计/评估/定位与主张.md`](文档/设计/目前设计/评估/定位与主张.md) |
+
+---
+
+## 已知缺口
+
+| 编号 | 问题 | 严重度 |
+|---|---|---|
+| **G1** | 高阶函数的成本契约无法表达 | P0（卡 M2） |
+| G9 | 成本模型缺少"内存搬运"维度 | P1 |
+| G13–G16 | 链接模型 / 属性传递 / 标准库范围 / 门禁引导期 | P2 |
+
+**M0 与 M1 均无阻塞。**
+
+---
+
+## 一句话
+
+> **别的语言让你写"怎么做"。**
+> **这门语言还让你写"要做到什么程度"，然后替你核对。**
+
+---
+
+## 许可与参与
+
+| 件 | 位置 |
+|---|---|
+| 代码许可 | `LICENSE`（**Apache-2.0**） |
+| 贡献指南 | `CONTRIBUTING.md`（**四道门必须同时绿**） |
+| 贡献者协议 | `CLA.md`（也接受 DCO：`git commit -s`） |
+| 引用格式 | `CITATION.cff` |
+| 企业侧保留区 | `ee/`（占位，说明"开源到什么程度"） |
+
+**一句话**：核心能力（语言 / 编译器 / 检查器 / 成本推导 / 门禁）**全部开源**，不做开源阉割。
+
+---
+
+## 命令行：**只写一个名字就够**
+
+```bash
+elench cost  sum          # 自动配成 sum.tu + sum.eln
+elench check sum          # 同上
+elench cost  sum.tu       # 只给声明，自动补实现
+elench cost  sum.eln      # 只给实现，顺序自动摆正
+elench export count       # 八个命令都一样接受只写名字
+```
+
+> **`<模块.tu> [<模块.eln>]` 是内部约定，不该变成输入负担。**
+> 用户只记得住"这个程序叫 sum"。
+
+---
+
+## 自动链：`export` → `build` → `dispatch + measure`
+
+**默认全自动**，一条命令拿到全部结论：
+
+```bash
+elench export sum          # 自己先 build，build 自动跑静态 dispatch（**不跑 measure**）
+elench export sum --no-auto   # 只导出，不跑前面那些（CI / 排查用）
+```
+
+关掉的方式：`--no-auto`，或环境变量 `ELENCH_AUTO=0`。
+
+**`measure` 不进自动链**：它要真执行候选，大范围下几十秒到分钟级。
+分档表单独生成：
+
+```bash
+elench measure sum           # 只跑测量、生成 .dispatch.yaml
+elench build sum --measure   # 构建时顺带测
+```
+
+---
+
+## OTel：本机不用 Docker
+
+```bash
+python tools/otel_local_sink.py --out otel.ndjson   # 一个终端
+$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"   # 另一个终端
+elench export count --push
+```
+
+**看板**：`python tools\otel_dashboard.py --file otel.ndjson --port 8080` → <http://127.0.0.1:8080>
+
+## 安装（Linux / macOS 一键）
+
+```bash
+git clone https://github.com/xiaohuo123212/elench.git
+cd elench
+./install.sh              # 先看要做什么： ./install.sh --dry-run
+elench --version          # 重开终端后
+```
+
+脚本做两件事之一，**不需要 sudo、不动系统 PATH**：
+
+| 情况 | 做法 |
+|---|---|
+| 有 `pip` | `python3 -m pip install --user .`，装成真正的控制台命令 |
+| 没 `pip` | 在 `~/.local/bin/elench` 放一个启动器，指向仓库里的 `src/elench.py` |
+
+卸载：`./install.sh --uninstall`。
+**Windows** 用 VS Code 扩展里的 `Elench: 安装命令行（加入 PATH）`。

package/bin/elench.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// elench 的 npm 入口：找 python，把参数原样转给它。
+//
+// 为什么是"薄包装"而不是重写：elench 的核心是 Python（约 3.5MB 源码、19 个子命令）。
+// 重写成 JS 等于重做一遍，而且会立刻出现两套语义。
+// 这里只做三件事：找解释器、传环境、原样转发退出码。
+"use strict";
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const pkgRoot = path.join(__dirname, "..");
+const srcDir = path.join(pkgRoot, "src");
+const dshPy = path.join(srcDir, "dsh.py");
+
+if (!fs.existsSync(dshPy)) {
+  console.error(`elench: 包内缺少 src/dsh.py（安装可能不完整）：${dshPy}`);
+  process.exit(1);
+}
+
+const candidates = [];
+if (process.env.PYTHON) candidates.push(process.env.PYTHON);
+candidates.push("python3", "python");
+
+function probe(exe) {
+  const r = spawnSync(exe, ["-c", "import sys;sys.exit(0 if sys.version_info>=(3,10) else 9)"], {
+    stdio: "ignore",
+  });
+  return r.status === 0;
+}
+
+let py = null;
+for (const c of candidates) {
+  try {
+    if (probe(c)) {
+      py = c;
+      break;
+    }
+  } catch (_e) {
+    /* 试下一个 */
+  }
+}
+
+if (!py) {
+  console.error(
+    "elench: 找不到可用的 Python（需要 >= 3.10）。\n" +
+      "  已尝试：" + candidates.join(", ") + "\n" +
+      "  装好 Python 后重试，或用 PYTHON=/path/to/python 指定。"
+  );
+  process.exit(1);
+}
+
+const env = Object.assign({}, process.env, {
+  PYTHONIOENCODING: "utf-8",
+  PYTHONPATH: [srcDir, process.env.PYTHONPATH].filter(Boolean).join(path.delimiter),
+});
+
+const r = spawnSync(py, [dshPy].concat(process.argv.slice(2)), {
+  stdio: "inherit",
+  env,
+  cwd: process.cwd(),
+});
+
+if (r.error) {
+  console.error(`elench: 启动 Python 失败：${r.error.message}`);
+  process.exit(1);
+}
+process.exit(r.status === null ? 1 : r.status);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "elench-lang",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Elenchus — cost contracts as machine-checkable code. CLI command: elench.",
+  "keywords": [
+    "cost",
+    "complexity",
+    "contracts",
+    "static-analysis",
+    "big-o",
+    "elench"
+  ],
+  "license": "Apache-2.0",
+  "bin": {
+    "elench": "bin/elench.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "prepack": "node scripts/clean-pycache.js",
+    "test": "node bin/elench.js --help"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elench-lang/elench.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}