Add Chinese tutorial for Step 1 of Mingling framework

3 files changed, 210 insertions, 0 deletions

diff --git a/docs/_zh_CN/_sidebar.md b/docs/_zh_CN/_sidebar.md
index 40968ba..8c854f9 100644
--- a/docs/_zh_CN/_sidebar.md
+++ b/docs/_zh_CN/_sidebar.md
@@ -1 +1,3 @@
 - [Welcome!](README)
+* [介绍](pages/1-intro)
+* [初次上手！](pages/2-step1)
diff --git a/docs/_zh_CN/pages/1-intro.md b/docs/_zh_CN/pages/1-intro.md
new file mode 100644
index 0000000..4e3106c
--- /dev/null
+++ b/docs/_zh_CN/pages/1-intro.md
@@ -0,0 +1,68 @@
+<h1 align="center">介绍</h1>
+<p align="center">
+    <b>Mingling</b> 能做什么？
+</p>
+
+## 前言
+
+  首先，非常感谢您愿意尝试和体验 **Mingling**
+
+  因为这是一个早期框架，所以尚不成熟。
+
+  若您在使用过程中遇到任何问题，欢迎提交 [Issue](https://github.com/catilgrass/mingling/issues)，我们乐意解决。
+
+<div style="display: flex; gap: 16px; padding: 8px; align-items: stretch; max-width: 90%;">
+  <div style="flex-shrink: 0; display: flex; align-items: center;">
+    <a href="https://github.com/catilgrass/mingling" target="_blank">
+      <img src="../res/pixel_icon_core_1024.png" style="height: 120px; object-fit: contain; padding: 8px;" />
+    </a>
+  </div>
+  <div style="display: flex; flex-direction: column; justify-content: flex-start;">
+    <div style="font-weight: bold; font-size: 1.2em; margin-bottom: 8px;">
+      <a href="https://github.com/catilgrass/mingling" target="_blank" style="text-decoration: none; color: inherit;">Mingling - Github</a>
+    </div>
+    <div style="color: #555;">
+        A Rust CLI framework for many subcmds & complex workflows, reduces boilerplate via proc macros, focus on biz logic
+    </div>
+  </div>
+</div>
+
+## Mingling 是什么？
+
+  **Mingling** 是一款 Rust 命令行开发框架，更准确地说，它是一款在调度、执行、渲染等方面提供高度抽象的框架。
+
+  它的核心逻辑是 **"转换"** —— 您输入的命令行参数（`Vec<String>`）会经过一系列的类型转换，最终变成您想要的结果。用一张图来说明：
+
+  <center>
+    <img src="../res/graph/flow.drawio.svg"/>
+  </center>
+
+  **这意味着**，您的执行逻辑和渲染逻辑是完全分离的：所有的状态、数据和结构都是类型，它们都只是转换过程中的一个环节，清晰又灵活。
+
+## 它适合什么样的项目？
+
+  如果您正在开发一个**子命令多、嵌套层次深、横切关注点多**，并且对**执行效率和动态补全**有要求的命令行工具，那么 **Mingling** 会是一个很好的选择。
+
+  这些能力得益于它高度抽象的宏系统，以及几乎全部在编译期完成的构建逻辑，让您在运行时能获得出色的性能。
+
+## Mingling 能做些什么？
+
+  **Mingling** 专注于命令行流程的调度与编排，为您提供以下能力：
+
+  1. **核心调度** — 通过类型转换优雅地编排业务逻辑
+  2. **纯函数设计** — 所有行为都是纯函数，可以直接测试
+  3. **无限嵌套** — 支持无限嵌套的子命令系统，再复杂的结构也能驾驭
+  4. **动态补全** — 为任意子命令插入完全动态的补全逻辑 **\[`comp`\]**
+  5. **帮助文档** — 为任意子命令插入帮助文档，让用户轻松上手
+
+## Mingling 不做些什么？
+
+  **Mingling** 专注于命令行**流程的调度与编排**，因此它不会提供以下功能（您可以自由搭配其他库来实现）：
+
+  1. ❌ 彩色文字、进度条等外观功能
+  2. ❌ 国际化、本地化功能
+  3. ❌ TUI 界面功能
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
diff --git a/docs/_zh_CN/pages/2-step1.md b/docs/_zh_CN/pages/2-step1.md
new file mode 100644
index 0000000..56f4b3c
--- /dev/null
+++ b/docs/_zh_CN/pages/2-step1.md
@@ -0,0 +1,140 @@
+<h1 align="center">初次上手！</h1>
+<p align="center">
+    使用 <b>Mingling</b> 开发简易水果名搜索命令行程序
+</p>
+
+## 前言
+
+在本篇示例中，我将介绍如何使用 **Mingling** 开发基本的命令行程序，它包括：
+
+1. `fruit-mgr list` 命令
+2. `fruit-mgr list --help` 帮助页面
+
+<iframe
+    src="../play/play.html?tur=zh_CN/2-fruit-mgr-expect.md&amp;title=水果管理器预期效果"
+    height="580px">
+</iframe>
+
+## 一、导入依赖
+
+首先，请确保您的项目依赖 **Mingling**
+
+若未导入依赖，您可以在 `Cargo.toml` 添加如下内容：
+
+```toml
+[dependencies.mingling]
+version = "0.1.9"
+features = [""]
+```
+ 
+## 二、编写 `main.rs`，创建基本的项目
+
+在 `src/main.rs` 中，我们将编写程序的入口函数：
+
+<iframe
+    src="../play/play.html?tur=zh_CN/2-writing.md&amp;title=编写入口"
+    height="500px">
+</iframe>
+
+## 三、注册 `list` 子命令
+
+<iframe
+    src="../play/play.html?tur=zh_CN/2-writing1.md&amp;title=注册 List 子命令"
+    height="550px">
+</iframe>
+
+## 四、实现 `EntryList` 行为
+
+<iframe
+    src="../play/play.html?tur=zh_CN/2-writing2.md&amp;title=实现 EntryList 行为"
+    height="860px">
+</iframe>
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>
+
+## 五、渲染 `ResultFruits`
+
+在上一步中，`handle_entry_list` 链接收 `EntryList`，并输出了 `ResultFruits`。
+
+接下来我们就要为 `ResultFruits` 渲染出最终的结果，使整个程序像下图这样排列：
+
+<center>
+    <img src="../res/graph/2-1.drawio.svg"/>
+</center>
+
+让我们开始编写代码吧：
+
+<iframe
+    src="../play/play.html?tur=zh_CN/2-writing3.md&amp;title=渲染 ResultFruits"
+    height="740px">
+</iframe>
+
+### 💡 关于 `r_println!` 宏
+
+`r_println!` 宏并不是对 `println!` 的包装
+
+它是为 `#[renderer]` 宏中 **隐式注入** 的 `&mut RenderResult` 值提供。
+
+在 `r_println!` 调用时，不会立刻向 stdout 输出信息，而是会被累计到 `&mut RenderResult` 中，在程序结束时整体输出。
+
+
+## 六、编译并运行
+
+现在您已经完成了 `list` 命令，现在可以使用 `cargo run` 运行您的程序：
+
+```bash
+cargo run -- list
+```
+ 
+您将会看到如下输出：
+
+```
+Apple
+Banana
+Orange
+```
+ 
+<details>
+<summary>完整代码</summary>
+
+```rust
+use mingling::prelude::*;
+ 
+dispatcher!("list", CMDList => EntryList);
+ 
+fn main() {
+    let mut program = ThisProgram::new();
+    program.with_dispatcher(CMDList);
+    program.exec_and_exit();
+}
+ 
+pack!(ResultFruits = Vec<String>);
+ 
+#[chain]
+fn handle_entry_list(_prev: EntryList) -> Next {
+    let fruits = vec![
+        "Apple".to_string(),
+        "Banana".to_string(),
+        "Orange".to_string(),
+    ];
+    ResultFruits::new(fruits)
+}
+ 
+#[renderer]
+fn render_fruits(result: ResultFruits) {
+    let vec: &Vec<String> = &*result;
+    for fruit in vec {
+        r_println!("{}", fruit)
+    }
+}
+ 
+gen_program!();
+ 
+```
+</details>
+
+<p align="center" style="font-size: 0.85em; color: gray;">
+    Written by @Weicao-CatilGrass
+</p>