From d9b08339665d217d4c3c01e91523a903e9f640fc Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Sun, 15 Mar 2026 01:20:24 +0800
Subject: Add completion script documentation to command READMEs

---
 src/cmds/README.md       | 42 +++++++++++++++++++++++++++++++++++++++++-
 src/cmds/README_zh_CN.md | 42 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 2 deletions(-)

diff --git a/src/cmds/README.md b/src/cmds/README.md
index 491163f..6e4b9f8 100644
--- a/src/cmds/README.md
+++ b/src/cmds/README.md
@@ -9,6 +9,7 @@ src/cmds/
 ├── arg/          # CLI arg definitions
 ├── cmd/          # Command impl
 ├── collect/      # Resource collection
+├── comp/         # Command completion scripts
 ├── converter/    # Data converters
 ├── in/           # Input data structs
 ├── out/          # Output data structs
@@ -84,6 +85,35 @@ pub struct JVSumOutput {
 }
 ```
 
+### 5. Completion Script
+- Implements command auto-completion
+- Naming: Same as command name
+- Location: `src/cmds/comp/{command_name}.rs`
+- Function signature must be `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>`
+
+Example: helpdoc command completion script
+```rust
+// src/cmds/comp/helpdoc.rs
+use crate::systems::{comp::context::CompletionContext, helpdoc};
+
+pub fn comp(ctx: CompletionContext) -> Option<Vec<String>> {
+    if ctx.previous_word == "helpdoc" {
+        return Some(
+            helpdoc::get_helpdoc_list()
+                .iter()
+                .map(|s| s.to_string())
+                .collect(),
+        );
+    }
+    None
+}
+```
+
+**Completion Script Return Value Explanation:**
+- Return `None`: System will suggest file list
+- Return `Some(Vec::new())`: No suggestions
+- Return `Some(vec!["suggestion1", "suggestion2"])`: Suggest specific content
+
 ## Command Execution Phases
 
 ### 1. prepare phase
@@ -198,7 +228,11 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError
    - Create renderer file in `renderer/` dir
    - Use `#[result_renderer]` macro
 
-5. **Test Command**
+5. **Implement Completion Script (Optional)**
+   - Create completion script file in `comp/` dir
+   - Implement `comp` function with signature `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>`
+
+6. **Test Command**
    - Use `cargo build` to check compile errors
    - Run cmd to test functionality
 
@@ -241,6 +275,11 @@ Use `log` for debugging during cmd dev:
    - Output struct should have enough info for renderer
    - Consider needs of different output formats
 
+5. **Completion Scripts**
+   - Provide intelligent completion suggestions for common parameters
+   - Generate completion options dynamically based on context
+   - Use return values appropriately to control completion behavior
+
 ## Example Commands
 
 Check existing cmd impls for inspiration:
@@ -264,3 +303,4 @@ Check existing cmd impls for inspiration:
    .\scripts\dev\dev_deploy.ps1
 
    jvn sum 1 2
+   ```
diff --git a/src/cmds/README_zh_CN.md b/src/cmds/README_zh_CN.md
index 42823a8..312d1c3 100644
--- a/src/cmds/README_zh_CN.md
+++ b/src/cmds/README_zh_CN.md
@@ -9,6 +9,7 @@ src/cmds/
 ├── arg/          # 命令行参数定义
 ├── cmd/          # 命令实现
 ├── collect/      # 资源收集信息
+├── comp/         # 命令补全脚本
 ├── converter/    # 数据转换器
 ├── in/           # 输入数据结构
 ├── out/          # 输出数据结构
@@ -84,6 +85,35 @@ pub struct JVSumOutput {
 }
 ```
 
+### 5. 补全脚本
+- 实现命令的自动补全功能
+- 命名规范：与命令同名
+- 位置：`src/cmds/comp/{command_name}.rs`
+- 函数签名必须为 `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>`
+
+示例：helpdoc 命令的补全脚本
+```rust
+// src/cmds/comp/helpdoc.rs
+use crate::systems::{comp::context::CompletionContext, helpdoc};
+
+pub fn comp(ctx: CompletionContext) -> Option<Vec<String>> {
+    if ctx.previous_word == "helpdoc" {
+        return Some(
+            helpdoc::get_helpdoc_list()
+                .iter()
+                .map(|s| s.to_string())
+                .collect(),
+        );
+    }
+    None
+}
+```
+
+**补全脚本返回值说明：**
+- 返回 `None`：系统会建议文件列表
+- 返回 `Some(Vec::new())`：不进行任何建议
+- 返回 `Some(vec!["suggestion1", "suggestion2"])`：建议具体内容
+
 ## 命令执行阶段
 
 ### 1. prepare 阶段
@@ -198,7 +228,11 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError
    - 在 `renderer/` 目录创建渲染器文件
    - 使用 `#[result_renderer]` 宏
 
-5. **测试命令**
+5. **实现补全脚本 (可选)**
+   - 在 `comp/` 目录创建补全脚本文件
+   - 实现 `comp` 函数，签名必须为 `pub fn comp(ctx: CompletionContext) -> Option<Vec<String>>`
+
+6. **测试命令**
    - 使用 `cargo build` 检查编译错误
    - 运行命令测试功能
 
@@ -241,6 +275,11 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError
    - 输出结构应包含足够的信息供渲染器使用
    - 考虑不同输出格式的需求
 
+5. **补全脚本**
+   - 为常用参数提供智能补全建议
+   - 根据上下文动态生成补全选项
+   - 合理使用返回值控制补全行为
+
 ## 示例命令参考
 
 查看现有命令实现以获取更多灵感：
@@ -264,3 +303,4 @@ pub async fn render(data: &JVSumOutput) -> Result<JVRenderResult, CmdRenderError
    .\scripts\dev\dev_deploy.ps1
    
    jvn sum 1 2
+   ```
-- 
cgit