Metadata-Version: 2.4
Name: cnsh
Version: 2.2.1
Summary: CNSH 中文原生脚本语言 · 运行时 + 多目标编译器 + CNSH→C 通用转译器（严格 C99 · DNA 追溯 · 三色审计）+ 龍魂字体（Chinese Native Script for Harmony）
Author-email: "Zhuge Xin (UID9622)" <uid9622@longhun.system>
License: MulanPSL-2.0
Project-URL: Homepage, https://gitee.com/uid9622/longhun-cnsh
Project-URL: Repository, https://gitee.com/uid9622/longhun-cnsh
Project-URL: Issue Tracker, https://gitee.com/uid9622/longhun-cnsh/issues
Project-URL: Changelog, https://gitee.com/uid9622/longhun-cnsh/blob/main/CHANGELOG.md
Project-URL: Documentation, https://gitee.com/uid9622/longhun-cnsh/blob/main/docs/LH-CNSH-LANGUAGE-SPEC-v4.0.md
Project-URL: Contributing, https://gitee.com/uid9622/longhun-cnsh/blob/main/CONTRIBUTING.md
Project-URL: Security, https://gitee.com/uid9622/longhun-cnsh/blob/main/SECURITY.md
Keywords: CNSH,中文编程,chinese-programming,LongHun,龍魂
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Compilers
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: web
Requires-Dist: fastapi; extra == "web"
Requires-Dist: uvicorn; extra == "web"
Dynamic: license-file

> DNA: #龍芯⚡️丙午·丁酉·乙未·亥时·䷏豫-CNSH-RELEASE-v2.1.1-UID9622
> 作者：诸葛鑫（UID9622 · 龍芯北辰） · 许可：工程层 MulanPSL v2 · 思想层 CC BY-NC-SA 4.0 · 字体 SIL OFL 1.1

> ## ⚠️ 此包已停止维护，请迁移：`pip install cnsh-v2`
>
> **`cnsh-v2` 是完整的中文 → C 编译器**（严格 C99 · 12 个子命令 · 支持 VS Code）。
> 本包描述的功能已过时，**子命令接口已全部变更**。
>
> ```bash
> pip uninstall cnsh
> pip install cnsh-v2
> ```

# CNSH · 中文原生脚本语言（Chinese Native Script for Harmony）

[![版本](https://img.shields.io/badge/版本-2.2.1-green)](CHANGELOG.md)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
[![许可](https://img.shields.io/badge/许可-MulanPSL--2.0-blue)](LICENSE)
[![依赖](https://img.shields.io/badge/运行时依赖-0-brightgreen)](pyproject.toml)
[![Gitee star](https://gitee.com/uid9622/longhun-cnsh/badge/star.svg?theme=dark)](https://gitee.com/uid9622/longhun-cnsh/stargazers)
[![Gitee fork](https://gitee.com/uid9622/longhun-cnsh/badge/fork.svg?theme=dark)](https://gitee.com/uid9622/longhun-cnsh/members)

用中文写程序。`你好，龍魂世界！` 不是口号，是 `cnsh run examples/hello.cnsh` 的真实输出。

**零运行时依赖** · **四种目标语言已验证** · **内置国密 SM4 与 GnuPG** · **附赠龍魂字体**

> 🏠 **仓库关系**：本仓 = CNSH **对外发布仓**（`pip install cnsh` 的源头，含 `cnshc` 转 C 转译器）；
> 开发主仓 = [longhun-system](https://gitee.com/uid9622_admin/longhun-system-core)
> （治理框架 + 工具链源码，转译器开发版在 `packaging/cnsh-v2/`）。两边双向链接，别找错门。

---

## 目录

| | | |
|:---|:---|:---|
| [30 秒上手](#30-秒上手) | [能做什么](#能做什么) | [怎么调用](#怎么调用) |
| [工作流](#工作流) | [项目结构](#项目结构) | [多目标编译](#多目标编译--实测状态) |
| [龍魂字体](#龍魂字体-longhunfont) | [编辑器支持](#编辑器支持) | [开发环境](#开发环境) |
| [转 C 转译器](#cnsh--c-通用转译器v220-新增) | | |
| [自动化](#自动化) | [语法定义](#语法定义) | [常见问题](#常见问题) |
| [文档地图](#文档地图) | [常见问题](#常见问题) | [Roadmap](#roadmap) |
| [许可](#许可三层各归各) | [贡献](#贡献) | [支持项目](#支持这个项目纯自愿--零黑箱) |

---

## 30 秒上手

```bash
# 方式一：pip（推荐）
pip install cnsh
cnsh run examples/hello.cnsh

# 方式二：从 Gitee 源码
git clone https://gitee.com/uid9622/longhun-cnsh.git
cd longhun-cnsh          # ← 注意：目录名是 longhun-cnsh，不是 cnsh
pip install .
cnsh run examples/hello.cnsh
```

> **pip 装完想立刻试**：16 个示例随包装在 `<前缀>/share/cnsh/examples/`
>（venv 里就是 `.venv/share/cnsh/examples/`，`--user` 装在 `~/Library/Python/3.x/share/cnsh/examples/`）。
> 2026-09-20 封装实测：干净 venv 里 wheel / sdist 两种装法都是 **16/16 跑通**
> （产物 sha256 见 [docs/SHA256SUMS-v2.1.1.txt](docs/SHA256SUMS-v2.1.1.txt)）。
>
> ⚠️ **两个 pip 怪癖，先知道省得踩**（2026-09-20 实机抓到）：
> 1. **重装同版本要加 `--force-reinstall`** —— pip 看到「同版本已装」会**整个跳过安装且返回成功**；
>    连「在源码仓里先 `python -m build` 再 `pip install dist/xxx.whl`」都会触发
>    （构建留下的 `*.egg-info` 被 pip 当成"已安装"）。装本地 wheel 时换个干净目录跑 pip，
>    或加 `--force-reinstall`。
> 2. `pip show 查无此包` 但 `pip install 说已装` —— 同一件事的两个侧面，别怀疑自己。

**预期输出**：

```
你好，龍魂世界！
```

> **不想装也能看**：`examples/` 下有 16 个 `.cnsh`，直接用文本编辑器打开就能读 —— 语法是中文的，不用学。
>
> ✅ **16 个示例全部能跑通**（2026-09-19 实测 `make example` 16/16）。
> 曾有 3 个跑不过（`async_enum_dataclass` / `class_decorator_generator` / `braket_persona`），
> 已全部修好 —— 过程留档见 [grammar/README.md §四](grammar/README.md)。

---

## 能做什么

| 能力 | 说明 | 入口 |
|:---|:---|:---|
| **中文编程** | 关键字、标识符、字符串全支持中文 | `cnsh run 文件.cnsh` |
| **解释执行** | 词法 → 语法 → 类型检查 → 求值，全链自研 | `cnsh_v21/interpreter.py` |
| **多目标编译** | 一份 `.cnsh` 编译成 Python / JS / Rust / C | `cnsh compile x.cnsh --target rust` |
| **类型检查** | 静态类型，不靠运行时才发现错 | `cnsh_v21/typechecker.py` |
| **编辑器支持** | 语言服务（补全 / 跳转 / 诊断） | `cnsh lsp` |
| **交互式** | REPL，边写边试 | `cnsh_v21/repl.py` |
| **项目脚手架** | 一条命令生成项目骨架 | `cnsh init 我的项目` |
| **内置密码学** | 国密 SM4 + GnuPG，**零外部依赖** | `cnsh_v21/crypto.py` |
| **中文编辑器字体** | 龍魂字体，含彩色字形版 | `fonts/` |

**内置函数**（标准库，`cnsh_v21/stdlib.py`）：`打印` · `输入` · `长度` · `类型` · `范围`

---

## 怎么调用

安装后得到 `cnsh` 命令，六个子命令：

| 命令 | 作用 | 例子 |
|:---|:---|:---|
| `cnsh run <文件.cnsh>` | 解释执行 | `cnsh run examples/fib.cnsh` |
| `cnsh compile <文件> --target <语言>` | 编译成其他语言 | `cnsh compile fib.cnsh --target python -o fib.py` |
| `cnsh test` | 跑测试 | `cnsh test` |
| `cnsh init <项目名>` | 新建项目骨架 | `cnsh init 我的项目` |
| `cnsh publish` | 打包项目 | `cnsh publish` |
| `cnsh lsp` | 起编辑器语言服务 | `cnsh lsp` |

也可以不当命令用，当 Python 库调：

```python
from cnsh_v21 import toolchain   # 工具链入口
```

---

## 工作流

一份 `.cnsh` 从源码到产物，走的是这条路：

```mermaid
flowchart LR
    A[".cnsh 源文件"] --> B["词法分析<br/>lexer.py"]
    B --> C["语法分析<br/>parser.py"]
    C --> D["类型检查<br/>typechecker.py"]
    D --> E["优化<br/>optimizer.py"]
    E --> F{"怎么用？"}
    F -->|run| G["解释执行<br/>interpreter.py"]
    F -->|compile| H["多目标代码生成"]
    H --> H1["Python"]
    H --> H2["JavaScript"]
    H --> H3["Rust"]
    H --> H4["C"]
    G --> I["输出结果"]
    H1 --> J["产物文件"]
    H2 --> J
    H3 --> J
    H4 --> J

    style A fill:#e1f5fe
    style I fill:#c8e6c9
    style J fill:#c8e6c9
    style H1 fill:#fff9c4
    style H2 fill:#fff9c4
    style H3 fill:#fff9c4
    style H4 fill:#fff9c4
```

**每个阶段都是独立的可测模块**（46 个 `.py` · 21092 行）—— 想只看词法？`cnsh_v21/lexer.py` 单独就能跑。

---

## 项目结构

```
longhun-cnsh/
├── cnsh_v21/                  编译器与运行时（46 个模块 · 21092 行）
│   ├── lexer.py               词法分析 —— 中文标识符支持在这
│   ├── parser.py              语法分析（1517 行 · 递归下降）
│   ├── ast_nodes.py           抽象语法树（578 行）
│   ├── tokens.py              词法单元定义（524 行）
│   ├── typechecker.py         类型检查（564 行）
│   ├── optimizer.py           优化器（354 行）
│   ├── interpreter.py         解释执行（3718 行）
│   ├── compiler_py.py         → Python   ✅ 已验证
│   ├── compiler_js.py         → JavaScript ✅ 已验证
│   ├── compiler_rust.py       → Rust     ✅ 已验证
│   ├── compiler_c.py          → C        ✅ 已验证
│   ├── compiler_cpp.py        → C++      🟡 桩 · 待 v3.0
│   ├── compiler_objc.py       → Obj-C    🟡 桩 · 待 v3.0
│   ├── compiler_swift.py      → Swift    🟡 桩 · 待 v3.0
│   ├── lsp_server.py          编辑器语言服务（1098 行）
│   ├── stdlib.py              标准库（279 行）
│   ├── crypto.py              密码学接口（155 行）
│   ├── repl.py                交互式解释器
│   ├── project.py             项目脚手架
│   ├── cli.py                 命令行入口
│   ├── toolchain.py           工具链统一入口
│   ├── errors.py              错误定义
│   └── _vendor/               内置依赖（不外拉）
│       ├── gnupg.py           GnuPG 实现（2335 行）
│       └── sm4/               国密 SM4
├── cnsh_v2c/                  CNSH→C 通用转译器（v2.2.0 新增 · 严格 C99 · cnshc 命令）
│   └── stdlib/                转译器标准库声明（字符串/数学/文件/时间/输入/内存 · 随 wheel）
├── docs/                      规范文档（思想层 · CC BY-NC-SA 4.0）
│   ├── LH-CNSH-LANGUAGE-SPEC-v4.0.md    最新融合规范
│   └── spec/                  完整规范 v2.0.0（16 章 + 附录 + BNF）
├── examples/                  16 个可运行示例（全部能跑 · make example 实测）
├── fonts/                     龍魂字体（SIL OFL 1.1）
├── grammar/                   ★ 形式化语法（cnsh.lark · Lark 格式）
│   ├── cnsh.lark              191 个关键字 + 表达式优先级 + 语句结构
│   └── README.md              逐条实测证据 + 常见误记校正
├── editors/vscode/            ★ VS Code 扩展（语法高亮 · **LSP 客户端** · 全角标点标红）
├── scripts/                   自检脚本（关键字覆盖率 / 语义引用校验 / 引用完整性）
├── tests/                     测试（test_all / test_lsp / test_semantic_drawer / test_grammar / test_toolchain）
├── assets/                    捐赠二维码
├── .workflow/ci.yml           Gitee Go 流水线
├── .github/workflows/ci.yml   GitHub Actions
├── Makefile                   开发命令（make help 看全部）
└── pyproject.toml             打包配置（零运行时依赖）
```

---

## 多目标编译 · 实测状态（2026-09-18 实机验证）

| 目标语言 | 状态 |
|:---|:---:|
| Python | ✅ 已验证 |
| JavaScript | ✅ 已验证 |
| Rust | ✅ 已验证 |
| C | ✅ 已验证 |
| C++ / Objective-C / Swift | 🟡 规划中（v3.0 交付） |

> ⚠️ **如实标注**：后三个目前是 **33~35 行的桩**（`compiler_cpp.py` / `compiler_objc.py` / `compiler_swift.py`），
> 接口占位但未实现。**不把它们标成"支持"** —— 标了就是骗人。

---

## CNSH → C 通用转译器（v2.2.0 新增）

**一句话**：`cnshc` 把 `.cnsh` 转成**严格 C99**，再交给本机 cc/gcc/clang 产出**原生可执行文件** ——
规范先行（EBNF）、完整类型系统、DNA 追溯、三色审计、数组边界检查，全部内置。

```bash
cnshc build examples/v2c/演示_主程序.cnsh && ./examples/v2c/演示_主程序
```

**真实输出**（2026-09-21 实机，macOS + Apple Clang）：

```
状态: ok
DNA: #龍芯⚡️2026-09-21-演示_主程序-2.0-8c7de0d0
C 文件: examples/v2c/演示_主程序.c
可执行: examples/演示_主程序
45          ← 对于循环求和
3           ← 当循环计数
和翻倍大于八十  ← 如果否则 + 函数调用
情形四命中     ← 选择语句
龍魂·CNSH转C·v2.0  ← 字符串拼接（导入 "stdlib/字符串.cnsh"）
```

**八层结构**（每层都有对应文档，见 [docs/v2c/](docs/v2c/)）：

| 层 | 内容 | 入口 |
|:---|:---|:---|
| 规范 | EBNF 语法 + 类型系统 + 作用域规则 + UB 清单 + ABI 约定 | `docs/v2c/SPEC.md` 等八份 |
| 前端 | 词法器 / 递归下降解析器 / 符号表 / 语义检查 | `cnsh_v2c/lexer.py` ~ `sema.py` |
| 中端 | DNA 注入 / 三色审计 / 模块解析 / 常量折叠 | `cnsh_v2c/dna.py` 等 |
| 后端 | C99 代码生成（`主函数`→main · 按类型打印 · 边界检查） | `cnsh_v2c/codegen_c.py` |
| 标准库 | 字符串 / 数学 / 文件 / 时间 / 输入 / 内存（声明随 wheel 走） | `cnsh_v2c/stdlib/*.cnsh` |
| 工具链 | `cnshc translate/build/audit/dna/fmt/version` + 格式化器 + LSP 骨架 | `cnsh_v2c/cli.py` |
| 测试 | 一致性 20 例（JSON）+ 黄金输出 + 缺陷回归 | `tests/v2c/` |
| 版本 | 语义化版本 + 废弃流程 | `docs/v2c/VERSIONING.md` |

**与解释器后端 `compiler_c.py` 的区别**：`cnsh_v21/compiler_c.py` 是解释器体系的
**多目标后端之一**（一份源码出四种语言，求覆盖广度）；`cnsh_v2c` 是**只做 C 的独立转译器**，
求深度 —— 完整类型推导、未初始化拦截、🔴 红线阻断编译、越界确定 panic。
二者共存，互不影响。

> ⚠️ **如实标注**：指针下标暂不做边界检查（`sizeof` 求不出指针真实长度，
> 假检查比不检查更危险）；LSP 只有语法诊断骨架。边界清单见
> [docs/v2c/UNDEFINED_BEHAVIOR.md](docs/v2c/UNDEFINED_BEHAVIOR.md) 与
> [docs/v2c/ROADMAP.md](docs/v2c/ROADMAP.md)。

---

## 龍魂字体 LonghunFont

`fonts/` 目录开箱即用。**v2.1.2 起字体也随 wheel 走** —— `pip install cnsh` 后直接位于
`<前缀>/share/cnsh/fonts/`（venv 里就是 `.venv/share/cnsh/fonts/`），不必 clone 仓库：

| 文件 | 用途 |
|:---|:---|
| `LonghunFont-Regular.otf` / `.ttf` | 桌面安装（macOS 双击 / Windows 右键安装 / Linux 放 `~/.fonts` 后 `fc-cache`） |
| `LonghunFont-Regular.woff2` | 网页 `@font-face` |
| `LonghunFont-WuwuColor.otf` | 彩色字形版 |
| `LonghunFont.css` | 网页直接引入 |

网页用法：

```css
@font-face {
  font-family: 'LonghunFont';
  src: url('fonts/LonghunFont-Regular.woff2') format('woff2');
}
body { font-family: 'LonghunFont', sans-serif; }
```

详细安装说明见 [fonts/README.md](fonts/README.md) · 字体许可 **SIL OFL 1.1**（`fonts/OFL.txt`）。

---

## 编辑器支持

### VS Code（已可用 · 本地安装）

```
editors/vscode/          ← 扩展本体
```

| 能力 | 说明 |
|:---|:---|
| **语法高亮** | **191 个关键字全着色**，分 6 类 |
| **括号配对** | `{}` `[]` `()` `""` 自动配对 |
| **注释切换** | `Ctrl+/` → `#` · `Shift+Alt+A` → `/* */` |
| **自动缩进** | `{` 后回车自动缩进 + 补 `}` |
| **中文整词选中** | 双击 `变量` 选中**整个词**（不是只选一个字） |
| 🔴 **全角标点标红** | 中文标点（`，。；「」`）**直接标红** —— 不用等跑起来才报错 |

**安装**：

```bash
# 软链（开发时用，改完即时生效）
ln -s "$(pwd)/editors/vscode" ~/.vscode/extensions/cnsh-local

# 或打包安装
npx @vscode/vsce package --no-dependencies && code --install-extension cnsh-*.vsix
```

**⇒ 龍魂专属关键字单列一类**（`三色审计` `DNA追溯` `量子纠缠` `五行` `八卦` `熔断` `红线词` `龍盾`…）
—— 那是**这套语言区别于所有其它语言的地方**，值得单独一种颜色。

**高亮的"全角标点标红"是本扩展最实用的功能**：全角 `，` 和半角 `,` 屏幕上几乎看不出区别，
**但会让解释器报 `无法识别的字符`**。标红让它跑之前就被发现。

详情见 [editors/vscode/README.md](editors/vscode/README.md)。

---

## 通心译语义抽屉

**语义库不是外挂词典 —— 它是语言的一部分。**

```
通心译(引擎) → 语义库总账(路由表) → 语义抽屉 D01~D08(35 个词元)
```

```cnsh
模块 语义示例 ⚖️100 {
    函数 查词元() -> 文本 {
        变量 命令 = @D03.铸码
        输出(命令.en)    # dna generate
        输出(命令.gua)   # ䷱鼎
        输出(命令.note)  # 调用DNA生成器
        返回 命令.cnsh
    }
    函数 展开抽屉() {
        变量 文化 = @D07.*          # 整抽屉展开 ⇒ 列表
        对于 词 在 文化 {
            输出(词.gua + "  " + 词.term + "  →  " + 词.en)
        }
    }
}
```

**八个抽屉**：D01 系统核 · D02 网络云 · D03 AI调度 · D04 协议法典 · D05 数据主权 ·
D06 民生审计 · D07 文化映射 · D08 军事指挥
（各自带默认人格：架构师 / 助手 / 审计师 / 哲人）

**词元七字段**：`term` `alias` `en` `cnsh` `gua` `status` `note`

**引用语法**：

| 写法 | 求值为 |
|:---|:---|
| `@D03.铸码` | 映射（单条词元信息） |
| `@D07.*` | 列表（整抽屉展开） |
| `@D99.瞎写` | 🔴 报错（**语法合法，语义不存在**） |

⚠️ **求值 ≠ 执行。** 看 `@D01.冻结` 的 `en` 是 `"rm (禁用,改冻结)"` ——
那是 P0 明令禁止的删除。**语义库是词典，不是执行器。**

**五级匹配**（与主仓 `lh_tongxinyi_resolver.py` 评分一致）：
显式引用 1.0 → 精确词元 0.95 → 别名 0.85 → 模糊 0.6 → 抽屉路由 0.4

```bash
python3 -m cnsh_v21 run examples/semantic_ref.cnsh   # 真跑一遍
python3 scripts/check_semantic_refs.py               # 校验所有 @ 引用
```

**⇒ 语义层能抓住语法层永远看不见的错**：`@D03.铸码` 和 `@D99.瞎写`
的**语法完全一样**，只有对着语义库才知道哪个是错的。这条检查同时挂在
**LSP 实时诊断**和 **CI** 上。

---

## 技能抽屉（55 个技能映射域）

**和语义抽屉是两套数据** —— 但共用 `@` 语法：

| | 语义抽屉 | 技能抽屉 |
|:---|:---|:---|
| 引用 | `@D03.铸码` | **`@S001.身份验证`** |
| 是什么 | **词典**（中文词元 → 命令） | **能力域映射**（域 → 技能包） |
| 数量 | 8 个 / 35 词元 | **55 个**（P0 16 · P1 20 · P2 19） |
| 字段 | `term/alias/en/cnsh/gua/status/note` | `drawer_id/name/trigger_word/layer/priority/capacity_kb/test_coverage/mapped_skill_ids` |
| 数据源 | `15_LABS/.../tongxinyi-semantic/` | `L5_.../control-panel/tongxinyi_drawers.json` |

**🔴 为什么前缀是 `S` 不是 `D`**：技能抽屉原始 id 是 **`D-001`**，而语义抽屉是 **`D01`**
—— **同一个 `D` 前缀两义**，用户看 `@D001.x` 分不清查的是词元还是技能。
⇒ 映射成 `S001`（**S = Skill**），位数也不同（三位 vs 两位），扫一眼就能分。

```cnsh
变量 域 = @S001.身份验证
输出(域.priority)          # P0
输出(域.trigger_word)      # auth/verify
输出(域.mapped_skill_ids)  # ['longhun-governance']
变量 技能 = @S001.*         # 展开该域映射的技能
```

**⚠️ 6 个抽屉名含空格**（`DNA 链验证` · `CPU 监控` · `Notion 同步` · `Obsidian 同步` ·
`GitHub 同步` · `API 文档`）⇒ **引用写去空格版**：`@S004.DNA链验证`
（lexer 的正则不收空格；写错会被诊断当场抓住并提示正确写法）。

**⇒ 技能抽屉的诊断多查一层**：**映射的技能是否真存在**。
那才是映射表最容易烂的地方 —— 实测就抓到一个：`D-011 技能执行` 指向的
`control-panel` **在技能库里不存在**（`skill_drawer.selfcheck()` 会报）。

```bash
python3 -m cnsh_v21 run examples/skill_ref.cnsh   # 真跑一遍
python3 -c "from cnsh_v21.skill_drawer import get_library; print(get_library().selfcheck())"
```

---

## 护栏四件套：熔断 · 回滚 · 三色审计 · 技能执行

**这四个关键字以前"只在语法里，没有实现"** —— 在 `tokens.py`、`parser.py`、
`ast_nodes.py` 里全都有，但 `interpreter.py` **一个都没实现**。
⇒ 能解析，一跑就报 `未实现的语句类型`。**现在接上了。**

```cnsh
模块 护栏 ⚖️100 {
    函数 示范() {
        变量 计数 = 1
        生成回滚点("改动前")        # ⚠️ 写在变量声明**之后**
        变量 计数 = 99
        回滚("改动前")               # ⇒ 计数 回到 1

        尝试 {
            熔断("主动刹车")          # ⇒ 抛 CNSHFuseError，中止
        } 捕获 错误 {
            输出(错误)                # ⇒ 在这里被接住
        }

        变量 记录 = 技能执行(@S001.身份验证)
        # 未注册 ⇒ 状态="未注册"，**不假装成功**
        注册技能("longhun-governance", 长度)
        技能执行(@S001.身份验证)      # ⇒ 状态="已执行"
    }
}
```

**四个关键设计**：

| 设计 | 为什么 |
|:---|:---|
| **熔断默认向上传播** | 要接住必须显式 `尝试 {...} 捕获 错误 {...}`。熔断是**必须被看见**的事件，默认吞掉才危险 |
| **技能执行先建回滚点** | 出事之前先把退路留好。失败 ⇒ **自动回滚** + 审计记「已熔断」 + 抛 `CNSHFuseError` |
| **未注册就说未注册** | 静默成功比报错危险得多。`技能执行` 返回 `状态` / `已执行` / `未注册` 三个字段，**一眼看得出真跑了没有** |
| **回滚不碰函数/模块** | 函数、模块不是"状态"。回滚它们不是回滚，是**删代码** |

**`技能执行` 的完整语义**：

```
技能执行(@Sxxx.yyy [, 参数])
  ① 解析抽屉 → ② **先建回滚点** → ③ 审计记「审计中」
  ④ 查技能是否注册
       · 已注册 ⇒ 真调用（`注册技能(id, 函数)` 登记的实现体）
       · 未注册 ⇒ 状态="未注册"，列出该抽屉映射了哪些技能
  ⑤ 成功 ⇒ 审计记「已审计」
  ⑥ 抛错 ⇒ **回滚 + 审计记「已熔断」+ 抛 CNSHFuseError**
```

⚠️ **它不"执行"什么魔法** —— 映射表索引的 21 个技能里，发布仓**内置了 18 个实现**
（`cnsh_v21/skills.py` 的 `BUILTIN_SKILL_TABLE`：**12 个只读开箱即用**（审计/监控/DNA/NLP/跨平台/性能探针等）
· **2 个可写**需显式注册 · **4 个云侧是可选依赖**，没装会明说在哪找、怎么装）；
其余实现散在主仓各层。
所以 `技能执行` 给的是**带护栏的执行框架**：登记、审计、回滚、熔断全都做了，
**内置的拿来就用，其余由你用 `注册技能` 接进来**。

```bash
python3 -m cnsh_v21 run examples/guardrails.cnsh    # 四件套全演示
```

---

## 执行白名单 —— 技能不是想调就能调

**默认严格**：白名单外的技能，`技能执行` **直接熔断**。

**⇒ 为什么不是"静默跳过"**：静默跳过 = **脚本以为执行了、其实没有** ——
那是最危险的失败方式。**宁可报错，不可假装。**

```cnsh
技能执行(@S001.身份验证)          # ⇒ 🔴 熔断（白名单外）
许可技能("longhun-governance")     # ⇒ 进白名单（只登记，不接实现）
技能执行(@S001.身份验证)          # ⇒ 状态"未注册"（已许可但没注入实现）
注册技能("longhun-governance", 函数)  # ⇒ 连实现一起给
技能执行(@S001.身份验证)          # ⇒ 状态"已执行"
```

**三条设计**：

| 设计 | 为什么 |
|:---|:---|
| **未许可 ⇒ 熔断**（不是跳过） | 静默跳过是最危险的失败方式 |
| **`只读` 默认真** | 要一个能改系统的技能，必须显式写 `注册技能("id", 函数, 假)` —— **让"能写"必须被写出来** |
| **记录带 `可写技能` 字段** | 动过系统的那几个，审计里**一眼看得出** |

**模式**：`技能模式("严格")`（默认）· `技能模式("宽松")`（白名单外返回记录、程序继续）

**开箱就有三个内置只读技能**（用发布仓里**真有的**能力，不是空壳）：

| 技能 | 干什么 |
|:---|:---|
| `longhun-archive` | 查语义抽屉 / 技能抽屉（纯查询，传关键词还能查词元） |
| `longhun-audit` | 查审计流水（只追加不改） |
| `longhun-review` | 查语义库/技能库自检 + 护栏状态 |

```bash
python3 -m cnsh_v21 run examples/skill_whitelist.cnsh   # 白名单全流程演示
```

⚠️ **`技能执行` 返回的是「执行记录」，不是技能返回值** —— 技能真正返回的在 `记录.结果` 里。
**一个抽屉常映射多个技能**（`D-012 执行日志` → audit + review），
多技能时 `结果` 是 `{技能id: 输出}`，**一个都不丢**。

---

## 观察期：审计落盘 + 周报

**"让它在只读状态下跑一段时间，看有没有异常调用模式"** —— 这句话的前提是
**审计得先能落盘**（原来只在内存，进程一退就没了）。

### 落盘（字段对齐主仓 `04_AUDIT/*.jsonl`）

```json
{"timestamp": "2026-09-19T11:54:50.919319",
 "dna":       "#龍芯⚡️2026-09-19-115450-CNSH-GUARDRAIL-9622-76AA4764",
 "operation": "技能执行 @S001.身份验证",
 "status":    "已审计",
 "tricolor":  "🟢",
 "source":    "prod"}
```

**三色语义出处**（**不自己发明**）：`12_DOCS/契约矩阵/龍魂文档标准模板_v1.0.md:129`
> 审计色：#三色审计 **#绿色放行 / #黄色待审 / #红色阻断**

完整规范（**字段必选/可选 · 样本量说明 · 阈值判据**）见 [docs/审计格式规范.md](docs/审计格式规范.md)。

### 三条纪律

| 纪律 | 为什么 |
|:---|:---|
| **① 只统计 `source=prod`** | 测试造的"白名单外尝试"混进正式流水 ⇒ **一周后没人分得清真假**，观察期就白跑了 |
| **② 判据用速率/比例，不用绝对次数** | 同一个"3 次"，低频脚本里是严重、高频服务里是噪声。**且必须带窗口内样本下限**，否则"1 条里 1 条红 = 100%"天天误报 |
| **③ 审计健康要一起报** | 磁盘满/只读挂载 ⇒ 审计静默不落 ⇒ **你以为有留痕、实际没留**。数据不完整时，上面所有指标都是假的 |

### 健康检查（**这条是"能否信任数据"的开关**）

启动探一次可写性 · 每条写失败计数 · **连续 3 次失败 ⇒ 打 stderr + 切 `/tmp` fallback**：

```
⚠️ CNSH 审计**主位置不可写**（...）—— 连续 3 次写失败
   ⇒ 已切到备用位置：/tmp/cnsh_audit_fallback/...
   ⇒ **你的审计在留痕，但不在你以为的地方。**
```

**⇒ 落盘失败不拖垮程序（旁路），但绝不让它静默。**

### 用法

```bash
# 跑东西（审计自动落盘）
python3 -m cnsh_v21 run examples/skill_whitelist.cnsh

# 测试/演示请标来源，写到独立文件
CNSH_AUDIT_SOURCE=test python3 -m cnsh_v21 run examples/xxx.cnsh

# 看报告
python3 scripts/audit_report.py            # 单次分析
python3 scripts/weekly_report.py --days 7  # 观察期周报（含逐日三色趋势）
python3 scripts/weekly_report.py --md report.md

# 指到主仓审计目录
CNSH_AUDIT_DIR=/path/to/04_AUDIT python3 scripts/weekly_report.py
```

### ⚠️ 措辞准确性（不接受含糊）

**准确说法**：**所有写操作都经过审计 + 熔断，不存在绕过审计的写路径。**

"白名单外尝试被抓到"说明**路径可达、只是被拦并留痕** ——
这和"没有写权限"是两件事。**安全态势要说准，否则会误判。**

### 其它编辑器

| 编辑器 | 状态 |
|:---|:---|
| VS Code | ✅ 词法高亮已可用（本仓）· 🟡 LSP 待接（`cnsh_v21/lsp_server.py` 已存在） |
| Vim / Neovim | 🟡 待做 |
| JetBrains 全家桶 | 🟡 待做 |

---

## 开发环境

### 一次性配好

```bash
git clone https://gitee.com/uid9622/longhun-cnsh.git
cd longhun-cnsh

python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
make dev        # 装依赖 + 装 pre-commit 钩子
```

**跑起来本身不需要任何依赖** —— `pyproject.toml` 里 `dependencies = []` 是刻意的。
`requirements-dev.txt` 装的都是**开发工具**（pytest / ruff / mypy / pre-commit / build / twine）。

### 常用命令

```bash
make            # 看全部命令
make test       # 跑测试
make check      # 提交前全套（格式 + 类型 + 测试）← CI 跑的就是这个
make example    # 跑全部 16 个 .cnsh 示例（验证示例真能跑）
make cov        # 测试 + 覆盖率报告
make build      # 构建 wheel + sdist
make clean      # 清构建产物

make new-example NAME=我的例子    # 新建示例骨架
```

### 开发环境要求

| 项 | 要求 | 说明 |
|:---|:---|:---|
| Python | **≥ 3.10** | 3.10 ~ 3.13 都会在 CI 里跑 |
| 操作系统 | macOS / Linux / Windows | CI 三个平台都覆盖 |
| 编辑器 | 任意 | `.editorconfig` 自动统一缩进/换行（4 空格 · LF · UTF-8） |
| Git 钩子 | `pre-commit` | `make dev` 自动装 · 提交时自动查格式/语法/包体卫生 |

### 自动化替你盯的事

装完 `pre-commit` 后，**每次提交前自动跑**（`make dev` 已装好）：

| 检查 | 拦什么 |
|:---|:---|
| `ruff format` / `ruff check` | 格式不统一、明显 bug |
| `mypy` | 类型问题（暂不阻塞，渐进补齐） |
| `trailing-whitespace` / `end-of-file-fixer` | 行尾空格、缺末行换行 |
| `check-yaml` / `check-toml` / `check-json` | 配置文件语法错误 |
| `debug-statements` | 漏删的 `breakpoint()` / `pdb` |
| **CNSH 示例语法自检** | **`examples/*.cnsh` 跑不过**（上了 CI 才发现就晚了） |
| **日志不得被 git 跟踪** | `.log` 是本地产物，不该进版本历史 |
| **docs/ 无 AI 生成内容** | 违反思想层 "禁止 AI 训练" 精神的内容 |

---

## 自动化

三套流水线，各管一段：

```mermaid
flowchart TB
    subgraph local["🖥️ 本地 · pre-commit"]
        L1["改代码"] --> L2["git commit"]
        L2 --> L3{"钩子检查"}
        L3 -->|不过| L1
        L3 -->|过了| L4["提交成功"]
    end

    subgraph gitee["🇨🇳 Gitee Go（国内主力）"]
        G1["push / PR"] --> G2["① 单元测试<br/>Py 3.10 + 3.12"]
        G2 --> G3["② 示例可执行性"]
        G3 --> G4["③ 包体卫生"]
        G4 --> G5["④ 元数据自检"]
    end

    subgraph gh["🌍 GitHub Actions（镜像）"]
        H1["push / tag"] --> H2["测试矩阵<br/>3.10~3.13 × 3 平台"]
        H2 --> H3["静态检查"]
        H3 --> H4["打包 + twine check"]
        H4 --> H5{"是 tag v* 吗？"}
        H5 -->|是| H6["自动建 Release"]
    end

    subgraph pub["📦 发布"]
        P1["make release"] --> P2["构建 wheel + sdist"]
        P2 --> P3["twine upload → PyPI"]
        P3 --> P4["Gitee 打 tag + 建 Release"]
    end

    L4 --> G1
    L4 --> H1

    style L3 fill:#fff9c4
    style H5 fill:#fff9c4
    style P4 fill:#c8e6c9
```

**为什么用 `make check` 而不是记一堆命令**：CI 跑的就是它。**本地过了，CI 基本也过** —— 不用等 5 分钟才知道少了个空格。

| 流水线 | 文件 | 说明 |
|:---|:---|:---|
| Gitee Go | `.workflow/ci.yml` | ⚠️ 目录是 `.workflow`（**不带 s**）· 需在 Gitee 控制台开通 |
| GitHub Actions | `.github/workflows/ci.yml` | 多平台 × 多版本矩阵 · tag 自动建 Release |
| 提交前 | `.pre-commit-config.yaml` | 装了钩子才生效（`make dev` 会装） |

---

## 语法定义

**机器可读的语法**在 [`grammar/cnsh.lark`](grammar/cnsh.lark)（[Lark](https://github.com/lark-parser/lark) 格式）。

```bash
# 装依赖（国内走清华镜像）
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple lark pytest

# 用语法解析真实代码
python -m pytest tests/test_grammar.py -v
```

**覆盖**：**191 个关键字** · 表达式优先级（13 层）· 语句结构 · 类型系统 · 中文标识符。

**这是个"语法也能被验证"的项目** —— `tests/test_grammar.py` 会：
1. 用 `.lark` 解析 `examples/` 里**全部 16 个示例**（语法层）
2. 用 **CNSH 自己的解释器真跑**（实现层）—— **两层分开验，因为"能解析"≠"能用"**
3. `RUNS_BAD` / `LARK_BEHIND` 回归名单**当前为空**（曾有的 3 个问题示例已全部修好）——
   谁把示例改坏了，strict xfail 会当场红，**不会悄悄通过**

**逐条依据 & 常见误记校正**见 [grammar/README.md](grammar/README.md) —— 那份文件里还有：
- **191 个关键字里的"龍魂专属"词汇**（`三色审计` `DNA追溯` `量子纠缠` `五行` `八卦`…）
- **两条"照抄必踩"的坑**（lark 不支持中文规则名 · 不认字符串差集）
- **我自己犯过的错**（读 KEYWORDS 只读到一半，误判 `打印`/`小数`/`文本` 不存在）

---

## 文档地图

- [docs/SPEC-v4.0 最新融合规范](docs/LH-CNSH-LANGUAGE-SPEC-v4.0.md)
- [docs/spec/](docs/spec/) — 完整规范 v2.0.0（入门 0-3 章 / 参考 4-8 章 / 审计 9-12 章 / Shell 13-16 章 / 附录 + BNF）
- [examples/](examples/) — 16 个 `.cnsh` 示例（全部能跑）

| 示例 | 演示什么 |
|:---|:---|
| `hello.cnsh` | 最小可运行 |
| `fib.cnsh` | 递归函数 |
| `types.cnsh` | 类型系统 |
| `async_enum_dataclass.cnsh` | 异步 / 枚举 / 数据类 |
| `class_decorator_generator.cnsh` | 类 / 装饰器 / 生成器 |
| `crypto.cnsh` | 内置密码学（SM4 / GPG） |
| `ffi.cnsh` | 外部函数接口 |
| `file_io.cnsh` | 文件读写 |
| `audit.cnsh` | 审计日志 |
| `braket_persona.cnsh` | 量子风格语法 |

> ⚠️ **规范版本号 vs 发行版本号不是一套**：`SPEC-v4.0` 是**规范文档**自己的版本，
> 本项目**发行**版本是 `v2.1.x`。规范迭代快于实现，这是有意为之。

---

## 常见问题

<details>
<summary><b>为什么叫 "CNSH"？</b></summary>

**C**hinese **N**ative **S**cript for **H**armony —— 中文原生脚本语言。

"原生"指的是：不是"支持中文"（很多语言都能写中文变量名），而是**关键字、标准库、错误信息本身就用中文**。

</details>

<details>
<summary><b>能用中文变量名吗？中文编程有什么意义？</b></summary>

能，而且这是设计目标。意义在于：**把编程的入门门槛降到"认字"**。
中文母语者不必先在脑子里做一次"概念 → 英文单词"的翻译。

**不等于**"英文编程没意义" —— 两件事不冲突。

</details>

<details>
<summary><b>CNSH 和易语言、木兰等中文编程语言有什么区别？</b></summary>

| | CNSH |
|:---|:---|
| 零运行时依赖 | ✅ `dependencies = []` |
| 多目标编译 | ✅ 一份源码 → Python/JS/Rust/C |
| 内置国密 | ✅ SM4 |
| 编辑器支持 | ✅ LSP |
| 许可 | 三层分离（见下） |

**最实际的区别**：`pip install cnsh` 就能用，不用装别的。

</details>

<details>
<summary><b>为什么代码是开源（MulanPSL）但文档"禁止 AI 训练"？</b></summary>

**这两条不矛盾，因为管的是不同的东西**：

| 层 | 内容 | 许可 | 能拿去训 AI 吗 |
|:---|:---|:---|:---:|
| 工程层 | `cnsh_v21/` 代码 | MulanPSL v2 | ✅ **可以** |
| 思想层 | `docs/` 文档 | CC BY-NC-SA 4.0 | ❌ **不可以** |
| 字体 | `fonts/` | SIL OFL 1.1 | — |

**代码随便用（含训练）**；**文档里的思想体系不许拿去喂模型**。
不认同这个边界的话，**请别用这个项目** —— 这是主权声明，不是可谈判项。

</details>

<details>
<summary><b>运行 .cnsh 文件安全吗？</b></summary>

**和你运行别人的 `.py` 一样危险 —— 没有沙箱。**

```bash
cnsh run 别人给的文件.cnsh     # ⚠️ 会真的执行
```

**别跑来路不明的 `.cnsh`。** 详见 [SECURITY.md](SECURITY.md)。

</details>

<details>
<summary><b>遇到 bug / 想提功能怎么办？</b></summary>

到 [Issues](https://gitee.com/uid9622/longhun-cnsh/issues) 提，仓库有现成模板。
报 bug 请带上 `cnsh --version`、`python3 --version` 和完整报错 —— 缺了很难复现。

想改代码看 [CONTRIBUTING.md](CONTRIBUTING.md)。

</details>

<details>
<summary><b>字体能商用吗？</b></summary>

**能。** SIL OFL 1.1 允许自由使用、修改、再分发（含商用），**唯一限制是不能单独售卖字体文件本身**。

</details>

---

## Roadmap

```mermaid
flowchart LR
    V21["v2.1.x<br/>✅ 当前<br/>四目标编译"] --> V22["v2.2<br/>🟡 包体清理<br/>PGP 签名"]
    V22 --> V30["v3.0<br/>🟡 C++/Obj-C/Swift<br/>产地证明"]
    V30 --> V4["v4.x<br/>⚪ 待定"]

    style V21 fill:#c8e6c9
    style V22 fill:#fff9c4
    style V30 fill:#ffe0b2
    style V4 fill:#f5f5f5
```

| 版本 | 计划 |
|:---|:---|
| **v2.1.x** | ✅ 当前 —— 四目标编译、龍魂字体、编辑器支持 |
| **v2.2** | 发布件 PGP 签名 · 完善类型注解（mypy 转阻塞） |
| **v3.0** | C++ / Objective-C / Swift 编译器实现 · PyPI 产地证明 |
| **v4.x** | 待定 |

**详细变更见 [CHANGELOG.md](CHANGELOG.md)。**

---

## 许可（三层，各归各）

| 层 | 内容 | 许可 | 链接 |
|:---|:---|:---|:---|
| **工程层** | `cnsh_v21/` · `tests/` | **MulanPSL v2** | [LICENSE](LICENSE) |
| **思想层** | `docs/` · 规范 · 示例 | **CC BY-NC-SA 4.0**（禁止 AI 训练 · 引用须署名） | [ATTRIBUTION.md](ATTRIBUTION.md) |
| **字体** | `fonts/` | **SIL OFL 1.1** | [fonts/OFL.txt](fonts/OFL.txt) |

**机器可读的许可标注**见 [REUSE.toml](REUSE.toml)（符合 [REUSE 规范](https://reuse.software/)）——
合规扫描工具能逐目录判对，不会把三层当成一层。

---

## 贡献

**欢迎**：报 bug · 提想法 · 改代码 · 加示例 · 修文档。

**先读** [CONTRIBUTING.md](CONTRIBUTING.md) —— 尤其**许可边界那一节**（改的东西落在哪层，适用哪个许可）。

```bash
# 最短路径
fork → clone → make dev → 改 → make check → 提 PR
```

**报 bug**：[Issues](https://gitee.com/uid9622/longhun-cnsh/issues)（有模板）
**报漏洞**：走私密渠道，**别开公开 Issue** —— 见 [SECURITY.md](SECURITY.md)

---

## 支持这个项目（纯自愿 · 零黑箱）

觉得有用，可以请作者喝杯咖啡：

| SOL | Tron |
|:---:|:---:|
| ![SOL](assets/donate-solana.png) | ![Tron](assets/donate.png) |

**不给钱也完全能用** —— 全功能开源，没有任何付费墙、没有"专业版"、没有功能阉割。

---

*发行版本 v2.1.1 · 源自龍魂系统主仓（longhun-system）· GPG 签名链与完整审计轨迹在主仓保留*
