docs: migrate renderers from `r_println!` to `RenderResult` return type

11 files changed, 125 insertions, 78 deletions

diff --git a/docs/_zh_CN/pages/10-help.md b/docs/_zh_CN/pages/10-help.md
index 7b56557..db67a84 100644
--- a/docs/_zh_CN/pages/10-help.md
+++ b/docs/_zh_CN/pages/10-help.md
@@ -15,9 +15,11 @@ Mingling 里用 `#[help]` 宏给命令添加帮助文本。
 @@@use mingling::macros::help;
 @@@dispatcher!("greet", CMDGreet => EntryGreet);
 #[help]
-fn help_greet(_entry: EntryGreet) {
-    r_println!("Usage: greet [name]");
-    r_println!("Say hello to someone.");
+fn help_greet(_entry: EntryGreet) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Usage: greet [name]").ok();
+    writeln!(r, "Say hello to someone.").ok();
+    r
 }
 ```
  
@@ -32,10 +34,12 @@ fn help_greet(_entry: EntryGreet) {
 @@@use mingling::macros::help;
 // 用户直接输入 --help 时触发
 #[help]
-fn help_root(entry: ErrorDispatcherNotFound) {
-    r_println!("Usage: my-cli <command>");
-    r_println!("Commands:");
-    r_println!("  greet    Say hello");
+fn help_root(entry: ErrorDispatcherNotFound) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Usage: my-cli <command>").ok();
+    writeln!(r, "Commands:").ok();
+    writeln!(r, "  greet    Say hello").ok();
+    r
 }
 ```
  
diff --git a/docs/_zh_CN/pages/11-resource-system.md b/docs/_zh_CN/pages/11-resource-system.md
index 5c3cf90..152e5d6 100644
--- a/docs/_zh_CN/pages/11-resource-system.md
+++ b/docs/_zh_CN/pages/11-resource-system.md
@@ -38,8 +38,10 @@ fn handle_pwd(_args: EntryPrintWorkingDir, cwd: &ResCurrentDir) -> Next {
 }
  
 #[renderer]
-fn render_path(result: ResultPath) {
-    r_println!("{}", *result);
+fn render_path(result: ResultPath) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "{}", *result).ok();
+    r
 }
 ```
  
@@ -59,8 +61,10 @@ fn handle_visit(_args: EntryVisit, counter: &mut ResVisitCount) -> Next {
 }
  
 #[renderer]
-fn render_done(_done: ResultDone, counter: &ResVisitCount) {
-    r_println!("visit count is : {}", counter.0);
+fn render_done(_done: ResultDone, counter: &ResVisitCount) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "visit count is : {}", counter.0).ok();
+    r
 }
 ```
  
diff --git a/docs/_zh_CN/pages/13-hook.md b/docs/_zh_CN/pages/13-hook.md
index 543ee55..6d6018a 100644
--- a/docs/_zh_CN/pages/13-hook.md
+++ b/docs/_zh_CN/pages/13-hook.md
@@ -60,7 +60,7 @@ Hook 覆盖了管线的完整生命周期：
 @@@#[chain] fn handle_greet(args: EntryGreet) -> Next {
 @@@    ResultName::new(args.inner.first().cloned().unwrap_or_default()).to_render()
 @@@}
-@@@#[renderer] fn render_name(r: ResultName) { r_println!("Hello, {}!", *r); }
+@@@#[renderer] fn render_name(r: ResultName) -> RenderResult { RenderResult::new() }
 fn main() {
     let mut program = ThisProgram::new();
  
diff --git a/docs/_zh_CN/pages/14-testing.md b/docs/_zh_CN/pages/14-testing.md
index af9d077..621d43e 100644
--- a/docs/_zh_CN/pages/14-testing.md
+++ b/docs/_zh_CN/pages/14-testing.md
@@ -13,16 +13,17 @@ Renderer 是最容易测试的——调用函数，断言返回结果：
 
 ```rust
 @@@pack!(ResultName = String);
-// 返回 String 而不是 ()
 #[renderer]
-fn render_name(name: ResultName) -> String {
-    r_println!("Hello, {}!", *name);
+fn render_greet(result: ResultName) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Hello, {}!", *result).ok();
+    r
 }
  
 #[test]
 fn test_render_name() {
     let result = render_name(ResultName::new("Alice".to_string()));
-    assert_eq!(result, "Hello, Alice!\n");
+    assert_eq!(result.to_string().as_str(), "Hello, Alice!\n");
 }
 ```
  
diff --git a/docs/_zh_CN/pages/4-render-result.md b/docs/_zh_CN/pages/4-render-result.md
index 9fac8a4..7cf2d2b 100644
--- a/docs/_zh_CN/pages/4-render-result.md
+++ b/docs/_zh_CN/pages/4-render-result.md
@@ -10,31 +10,34 @@
 跟 `#[chain]` 类似，`#[renderer]` 用于标记一个输出函数：
 
 ```rust
+use std::io::Write;
+ 
 @@@pack!(ResultName = String);
 #[renderer]
-fn render_name(name: ResultName) {
-    r_println!("Hello, {}!", *name);
+fn render_name(name: ResultName) -> RenderResult {
+    let mut result = RenderResult::new();
+    writeln!(result, "Hello, {}!", *name).ok();
+    result
 }
 ```
  
-Renderer 接收 Chain 产出的结果，然后用 `r_println!` 输出。这个 `r_println!` 跟我们平常用的 `println!` 有什么区别？
+Renderer 接收 Chain 产出的结果，然后返回一个 `RenderResult`。在函数内部，创建 `RenderResult`，用 `write!` / `writeln!`（来自 [`std::io::Write`](https://doc.rust-lang.org/std/io/trait.Write.html)）写入内容，最后返回它。
 
-## `r_println!` 和 `r_print!` 宏
+## `RenderResult` 类型
 
-`r_println!` 和 `r_print!` 是 Mingling 提供的打印宏，它们把内容写入 `RenderResult` 而不是直接输出到终端。这样做的好处是：
+`RenderResult` 是一个缓冲区类型，持有渲染后的文本和退出码。它不是直接输出到终端，而是把内容写入缓冲区。这样做的好处是：
 
-1. **RenderResult 持有退出码**——你可以设置程序以特定退出码结束
+1. **持有退出码**——你可以设置程序以特定退出码结束
 2. **方便测试**——可以捕获渲染结果做断言
 3. **便于后处理**——你可以将结果捕获，统一进行文本后处理
 
-> [!TIP]
-> 如果只是简单打印，你可以先把它理解为 `println!` 的平替。用 `r_println!` 替换 `println!` 不会错。
-
 ## 完整的可运行程序
 
 把三篇教程的内容合在一起，你的第一个 Mingling 程序就完整了：
 
 ```rust
+use std::io::Write;
+ 
 // 1. 用 Dispatcher 声明命令
 dispatcher!("greet", CMDGreet => EntryGreet);
  
@@ -53,8 +56,10 @@ fn handle_greet(args: EntryGreet) -> Next {
  
 // 4. 用 Renderer 输出结果
 #[renderer]
-fn render_name(name: ResultName) {
-    r_println!("Hello, {}!", *name);
+fn render_name(name: ResultName) -> RenderResult {
+    let mut result = RenderResult::new();
+    writeln!(result, "Hello, {}!", *name).ok();
+    result
 }
  
 // 5. 在 main 函数内装配程序并运行
@@ -103,13 +108,17 @@ cargo run -- great
 `gen_program!()` 自动生成了一个 `ErrorDispatcherNotFound` 类型，包裹 `Vec<String>`——它存的是用户输入的那些没匹配到的命令。你只需要给它写一个 Renderer：
 
 ```rust
+use std::io::Write;
+ 
 #[renderer]
-fn render_dispatcher_not_found(err: ErrorDispatcherNotFound) {
+fn render_dispatcher_not_found(err: ErrorDispatcherNotFound) -> RenderResult {
+    let mut result = RenderResult::new();
     if err.inner.is_empty() {
-        r_println!("Unknown command");
+        writeln!(result, "Unknown command").ok();
     } else {
-        r_println!("Command not found: \"{}\"", err.inner.join(" "));
+        writeln!(result, "Command not found: \"{}\"", err.inner.join(" ")).ok();
     }
+    result
 }
 ```
  
diff --git a/docs/_zh_CN/pages/5-multiple-commands.md b/docs/_zh_CN/pages/5-multiple-commands.md
index 4a9c72d..7d2617b 100644
--- a/docs/_zh_CN/pages/5-multiple-commands.md
+++ b/docs/_zh_CN/pages/5-multiple-commands.md
@@ -30,13 +30,17 @@ fn handle_add(args: EntryAdd) -> Next {
 }
  
 #[renderer]
-fn render_greet(result: ResultGreeting) {
-    r_println!("Hello, {}!", *result);
+fn render_greet(result: ResultGreeting) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Hello, {}!", *result).ok();
+    r
 }
  
 #[renderer]
-fn render_sum(result: ResultSum) {
-    r_println!("Sum: {}", *result);
+fn render_sum(result: ResultSum) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Sum: {}", *result).ok();
+    r
 }
  
 fn main() {
@@ -67,9 +71,9 @@ Sum: 6
 @@@pack!(ResultGreeting = String);
 @@@pack!(ResultSum = i32);
 @@@#[chain] fn handle_greet(_args: EntryGreet) -> Next { ResultGreeting::new("ok".into()) }
-@@@#[renderer] fn render_greet(_greeting: ResultGreeting) { r_println!("hi"); }
+@@@#[renderer] fn render_greet(_greeting: ResultGreeting) -> RenderResult { RenderResult::new() }
 @@@#[chain] fn handle_add(_args: EntryAdd) -> Next { ResultSum::new(0) }
-@@@#[renderer] fn render_sum(_sum: ResultSum) { r_println!("sum"); }
+@@@#[renderer] fn render_sum(_sum: ResultSum) -> RenderResult { RenderResult::new() }
 fn main() {
     let mut program = ThisProgram::new();
     program.with_dispatchers((CMDGreet, CMDAdd));
diff --git a/docs/_zh_CN/pages/6-argument-parse-picker.md b/docs/_zh_CN/pages/6-argument-parse-picker.md
index 9c7e028..b41f839 100644
--- a/docs/_zh_CN/pages/6-argument-parse-picker.md
+++ b/docs/_zh_CN/pages/6-argument-parse-picker.md
@@ -156,13 +156,10 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
 }
  
 #[renderer]
-fn render_no_name(_prev: ErrorNoName) {
-    r_println!("Error: No name provided.");
-}
- 
-#[renderer]
-fn render_name(prev: ResultName) {
-    r_println!("Hello, {}!", *prev);
+fn render_greet(result: ResultName) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Hello, {}!", *result).ok();
+    r
 }
 ```
  
@@ -251,14 +248,18 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
 }
  
 #[renderer]
-fn render_name_too_long(prev: ErrorNameTooLong) {
+fn render_name_too_long(prev: ErrorNameTooLong) -> RenderResult {
+    let mut r = RenderResult::new();
     let len = *prev;
-    r_println!("Error: name too long (length: {} > 32)", len);
+    writeln!(r, "Error: name too long (length: {} > 32)", len).ok();
+    r
 }
  
 #[renderer]
-fn render_name(prev: ResultName) {
-    r_println!("Hello, {}!", *prev);
+fn render_name(prev: ResultName) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Hello, {}!", *prev).ok();
+    r
 }
 ```
  
@@ -315,7 +316,7 @@ fn parse_size() {
 // Features: ["parser"]
 @@@use mingling::parser::{Pickable, Argument};
 @@@use mingling::Flag;
-#[derive(Default)]
+#[derive(Default, Clone)]
 pub struct Address {
     ip: String,
     port: u16,
@@ -341,9 +342,10 @@ fn handle_connect_entry(prev: EntryConnect) -> Next {
 }
  
 #[renderer]
-fn render_connected(prev: ResultConnected) {
-    let addr = prev.inner;
-    r_println!("Connected: IP: {} PORT: {}", addr.ip, addr.port);
+fn render_connected(addr: ResultConnected) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Connected: IP: {} PORT: {}", addr.ip, addr.port).ok();
+    r
 }
 ```
  
@@ -381,8 +383,10 @@ fn handle_eat_entry(prev: EntryEat) -> Next {
 }
  
 #[renderer]
-fn render_fruit(prev: ResultFruit) {
-    r_println!("Picked fruit: {:?}", *prev);
+fn render_fruit(prev: ResultFruit) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Picked fruit: {:?}", *prev).ok();
+    r
 }
 ```
  
diff --git a/docs/_zh_CN/pages/7-argument-parse-clap.md b/docs/_zh_CN/pages/7-argument-parse-clap.md
index e15bebb..7dce301 100644
--- a/docs/_zh_CN/pages/7-argument-parse-clap.md
+++ b/docs/_zh_CN/pages/7-argument-parse-clap.md
@@ -35,18 +35,22 @@ pub struct EntryGreet {
 }
  
 #[renderer]
-fn render_greet(greet: EntryGreet) {
+fn render_greet(greet: EntryGreet) -> RenderResult {
+    let mut r = RenderResult::new();
     let count = greet.repeat.max(0) as usize;
-    r_print!("Hello, ");
+    write!(r, "Hello, ").ok();
     for _ in 0..count {
-        r_print!("{} ", greet.name);
+        write!(r, "{} ", greet.name).ok();
     }
-    r_println!("!");
+    writeln!(r, "!").ok();
+    r
 }
  
 #[renderer]
-fn render_greet_parse_failed(err: ErrorGreetParsed) {
-    r_println!("{}", *err);
+fn render_greet_parse_failed(err: ErrorGreetParsed) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "{}", *err).ok();
+    r
 }
 ```
  
@@ -66,10 +70,11 @@ fn render_greet_parse_failed(err: ErrorGreetParsed) {
 @@@    name: String,
 @@@}
 @@@#[renderer]
-@@@fn render_greet(greet: EntryGreet) {
-@@@    r_println!("Hello, {}!", greet.name);
+@@@fn render_greet(greet: EntryGreet) -> RenderResult {
+@@@    let mut r = RenderResult::new();
+@@@    write!(r, "Hello, {}!", greet.name).ok();
+@@@    r
 @@@}
-@@@
 fn main() {
     let mut program = ThisProgram::new();
     program.with_setup(BasicProgramSetup);
diff --git a/docs/_zh_CN/pages/9-error-handling.md b/docs/_zh_CN/pages/9-error-handling.md
index a4d5b0a..07c82da 100644
--- a/docs/_zh_CN/pages/9-error-handling.md
+++ b/docs/_zh_CN/pages/9-error-handling.md
@@ -44,13 +44,17 @@ fn handle_greet(args: EntryGreet) -> Next {
 @@@#[chain] fn handle_greet(args: EntryGreet) -> Next { ResultGreeting::new(args.inner.first().cloned().unwrap_or_default()).to_render() }
  
 #[renderer]
-fn render_greeting(result: ResultGreeting) {
-    r_println!("Hello, {}!", *result);
+fn render_greet(result: ResultGreeting) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Hello, {}!", *result).ok();
+    r
 }
  
 #[renderer]
-fn render_error_name_empty(err: ErrorNameEmpty) {
-    r_println!("Error: {}", *err);
+fn render_error_name_empty(err: ErrorNameEmpty) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Error: {}", *err).ok();
+    r
 }
 ```
  
@@ -75,13 +79,17 @@ fn handle_greet(args: EntryGreet) -> Next {
 }
  
 #[renderer]
-fn render_greeting(result: ResultGreeting) {
-    r_println!("Hello, {}!", *result);
+fn render_greet(result: ResultGreeting) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Hello, {}!", *result).ok();
+    r
 }
  
 #[renderer]
-fn render_error_name_empty(err: ErrorNameEmpty) {
-    r_println!("Error: {}", *err);
+fn render_error_name_empty(err: ErrorNameEmpty) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Error: {}", *err).ok();
+    r
 }
  
 fn main() {
diff --git a/docs/_zh_CN/pages/advanced/2-structural-renderer.md b/docs/_zh_CN/pages/advanced/2-structural-renderer.md
index 14164da..9a4f111 100644
--- a/docs/_zh_CN/pages/advanced/2-structural-renderer.md
+++ b/docs/_zh_CN/pages/advanced/2-structural-renderer.md
@@ -41,8 +41,10 @@ fn handle_render(args: EntryRender) -> Next {
 }
  
 #[renderer]
-fn render_info(r: ResultInfo) {
-    r_println!("{:?}", *r);
+fn render_info(r: ResultInfo) -> RenderResult {
+    let mut result = RenderResult::new();
+    writeln!(result, "{:?}", *r).ok();
+    result
 }
 ```
  
@@ -86,8 +88,10 @@ fn handle_render(args: EntryRender) -> Next {
 }
  
 #[renderer]
-fn render_info(info: Info) {
-    r_println!("{} is {} years old", info.name, info.age);
+fn render_info(info: Info) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "{} is {} years old", info.name, info.age).ok();
+    r
 }
 @@@
 @@@fn main() {
diff --git a/docs/_zh_CN/pages/other/naming_rule.md b/docs/_zh_CN/pages/other/naming_rule.md
index 1f1ff84..5f2ac34 100644
--- a/docs/_zh_CN/pages/other/naming_rule.md
+++ b/docs/_zh_CN/pages/other/naming_rule.md
@@ -193,14 +193,18 @@ fn handle_state_operation_remotes(state: StateOperationRemotes, db: &ResDatabase
  
 // 结果渲染
 #[renderer]
-fn render_remote_added(result: ResultRemoteAdded) {
-    r_println!("Remote added: {}", result.inner);
+fn render_remote_added(result: ResultRemoteAdded) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Remote added: {}", result.inner).ok();
+    r
 }
  
 // 错误渲染
 #[renderer]
-fn render_error_repository_not_found(err: ErrorRepositoryNotFound) {
-    r_println!("Error: remote '{}' not found", err.inner);
+fn render_error_repository_not_found(err: ErrorRepositoryNotFound) -> RenderResult {
+    let mut r = RenderResult::new();
+    writeln!(r, "Error: remote '{}' not found", err.inner).ok();
+    r
 }
 ```