feat: XRobot 0.2.0 重大功能升级与架构优化

- 全面重写并补充各主命令脚本，支持递归依赖解析、模块唯一 id、模板参数与多源仓库管理
- README.md 文档全面重写，详细说明各命令用法、参数和数据结构
- xrobot_add_mod：支持 namespace/ModuleName[@Version] 形式添加仓库，支持自动分配/指定实例 id，自动解析并写入构造参数和模板参数
- xrobot_gen_main：支持新 YAML 结构和模板参数，自动主函数代码生成，完善实例命名
- xrobot_init_mod：支持依赖递归拉取、依赖冲突检测、sources.yaml 多源聚合，完善命令行与行为
- xrobot_create_mod：标准化生成 V2 MANIFEST，支持 constructor/template/depends 结构参数，CLI 参数增强
- xrobot_mod_parser：统一解析模块信息，完善 manifest 兼容性与格式化输出
- 全部 Python 工具脚本增加 usage 说明和 CLI 参数帮助，支持独立调用和作为库复用
- 版本号升级至 0.2.0

BREAKING CHANGE: 配置文件格式升级，建议手动迁移 modules.yaml 和 xrobot.yaml 内容以兼容新版数据结构。

Author: Jiu-xiao

README.md

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrobot"
-version = "0.1.6"
+version = "0.2.0"
 description = "A lightweight application framework for robot module management, lifecycle control, and hardware abstraction."
 requires-python = ">=3.8"
 authors = [

pyproject.toml

@@ -1,120 +1,118 @@
 #!/usr/bin/env python3
 """
-xrobot_add_mod.py - 添加模块仓库或追加模块实例配置
+xrobot_add_mod.py - Add a module repository to modules.yaml or append a module instance config.
 
-Usage 示例：
-  # 添加模块仓库（默认写入 Modules/modules.yaml）
-  python xrobot_add_mod.py https://github.com/yourorg/BlinkLED.git --version main
-
-  # 追加模块实例（默认写入 User/xrobot.yaml）
+Usage examples:
+  python xrobot_add_mod.py xrobot-org/BlinkLED@main
   python xrobot_add_mod.py BlinkLED
 """
 
 import argparse
 import yaml
 from pathlib import Path
-from urllib.parse import urlparse
-from collections import OrderedDict
 
+# Default config file paths
 DEFAULT_REPO_CONFIG = Path("Modules/modules.yaml")
 DEFAULT_INSTANCE_CONFIG = Path("User/xrobot.yaml")
 MODULES_DIR = Path("Modules")
 
-def is_repo_url(s: str) -> bool:
-    return s.startswith("http://") or s.startswith("https://")
-
-def extract_name_from_repo(repo: str) -> str:
-    return Path(urlparse(repo).path).stem
-
-def load_yaml(path: Path) -> dict:
-    return yaml.safe_load(path.read_text(encoding="utf-8")) if path.exists() else {}
-
-def save_yaml(path: Path, data: dict):
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(yaml.dump(data, sort_keys=False, allow_unicode=True), encoding="utf-8")
-
-def parse_manifest_from_header(header_path: Path) -> dict:
-    content = header_path.read_text(encoding="utf-8")
-    lines = content.splitlines()
-    block = []
-    inside = False
-
-    for line in lines:
-        stripped = line.strip()
-        if stripped == "/* === MODULE MANIFEST ===":
-            inside = True
-            continue
-        if stripped == "=== END MANIFEST === */":
-            break
-        if inside:
-            block.append(line.replace("/*", "  ").replace("*/", "  ").rstrip())
-
-    try:
-        return yaml.safe_load("\n".join(block)) or {}
-    except yaml.YAMLError as e:
-        print(f"[ERROR] Failed to parse manifest: {e}")
-        return {}
-
-def append_module_instance(module_name: str, config_path: Path):
-    header_path = MODULES_DIR / module_name / f"{module_name}.hpp"
-    if not header_path.exists():
-        print(f"[ERROR] Module header not found: {header_path}")
+# Import utility functions from local module
+from xrobot.ModuleParser import load_single_module, parse_constructor_args
+
+def is_repo_id(s: str) -> bool:
+    """
+    Determine if string is a repo ID (e.g., 'namespace/ModuleName' or 'namespace/ModuleName@version').
+    """
+    return "/" in s
+
+def get_next_instance_id(modules: list, base_name: str) -> str:
+    """
+    Return a unique instance id for the given module name, such as 'BlinkLED_0', 'BlinkLED_1', etc.
+    """
+    existing = [m.get("id", "") for m in modules if m.get("name") == base_name]
+    nums = []
+    for eid in existing:
+        if eid and eid.startswith(base_name + "_"):
+            try:
+                nums.append(int(eid[len(base_name) + 1:]))
+            except Exception:
+                pass
+    next_num = (max(nums) + 1) if nums else 0
+    return f"{base_name}_{next_num}"
+
+def append_module_instance(module_name: str, config_path: Path, instance_id: str = None):
+    """
+    Append a module instance (with id and constructor args) to the user config YAML.
+    """
+    mod_dir = MODULES_DIR / module_name
+    manifest = load_single_module(mod_dir)
+    if not manifest:
+        print(f"[ERROR] Module manifest not found in: {mod_dir}")
         return
 
-    manifest = parse_manifest_from_header(header_path)
-    args = manifest.get("constructor_args", {})
-    args_ordered = OrderedDict()
-    if isinstance(args, dict):
-        args_ordered.update(args)
-    elif isinstance(args, list):
-        for item in args:
-            if isinstance(item, dict):
-                args_ordered.update(item)
-
-    data = load_yaml(config_path)
+    # Parse constructor and template args in order
+    args_ordered = parse_constructor_args(manifest.constructor_args)
+    template_args_ordered = parse_constructor_args(manifest.template_args)
+
+    # Load or create config file
+    if config_path.exists():
+        data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    else:
+        data = {}
     if "modules" not in data or not isinstance(data["modules"], list):
         data["modules"] = []
 
-    data["modules"].append({
+    # Auto-generate unique instance id if not given
+    inst_id = instance_id or get_next_instance_id(data["modules"], module_name)
+
+    mod_entry = {
+        "id": inst_id,
         "name": module_name,
         "constructor_args": dict(args_ordered)
-    })
-
-    save_yaml(config_path, data)
-    print(f"[SUCCESS] Appended module instance '{module_name}' to {config_path}")
-
-def add_repo_entry(repo: str, version: str, config_path: Path):
-    name = extract_name_from_repo(repo)
-    data = load_yaml(config_path)
-    modules = data.get("modules", [])
+    }
+    if template_args_ordered:
+        mod_entry["template_args"] = dict(template_args_ordered)
+
+    data["modules"].append(mod_entry)
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(yaml.dump(data, sort_keys=False, allow_unicode=True), encoding="utf-8")
+    print(f"[SUCCESS] Appended module instance '{module_name}' as id '{inst_id}' to {config_path}")
+
+def add_repo_entry(repo_id: str, config_path: Path):
+    """
+    Add a new repo module (as a plain string, e.g., 'namespace/ModuleName[@version]') to modules.yaml.
+    """
+    if config_path.exists():
+        data = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    else:
+        data = {}
+    if "modules" not in data or not isinstance(data["modules"], list):
+        data["modules"] = []
 
-    if any(m.get("name") == name for m in modules):
-        print(f"[WARN] Module '{name}' already exists in {config_path}. Skipping.")
+    if repo_id in data["modules"]:
+        print(f"[WARN] Module '{repo_id}' already exists in {config_path}. Skipping.")
         return
 
-    entry = {"name": name, "repo": repo}
-    if version:
-        entry["version"] = version
-    modules.append(entry)
-
-    save_yaml(config_path, {"modules": modules})
-    print(f"[SUCCESS] Added repo module '{name}' to {config_path}")
+    data["modules"].append(repo_id)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(yaml.dump(data, sort_keys=False, allow_unicode=True), encoding="utf-8")
+    print(f"[SUCCESS] Added repo module '{repo_id}' to {config_path}")
 
 def main():
-    parser = argparse.ArgumentParser(description="Add module repo or instance config to YAML")
-    parser.add_argument("target", help="Repo URL or local module name")
-    parser.add_argument("--version", "-v", help="Branch or tag (repo only)")
-    parser.add_argument("--config", "-c", help="YAML file path to write (auto default)")
+    parser = argparse.ArgumentParser(description="Add a module repo or instance config to a YAML file")
+    parser.add_argument("target", help="namespace/ModuleName[@version] or local module name")
+    parser.add_argument("--config", "-c", help="Path to YAML config file (optional, auto default)")
+    parser.add_argument("--instance-id", help="Optional: manually set the module instance id")
 
     args = parser.parse_args()
 
-    # 判断类型并选择默认 config 路径
-    if is_repo_url(args.target):
+    if is_repo_id(args.target):
         config_path = Path(args.config) if args.config else DEFAULT_REPO_CONFIG
-        add_repo_entry(args.target, args.version, config_path)
+        add_repo_entry(args.target, config_path)
     else:
         config_path = Path(args.config) if args.config else DEFAULT_INSTANCE_CONFIG
-        append_module_instance(args.target, config_path)
+        append_module_instance(args.target, config_path, args.instance_id)
 
 if __name__ == "__main__":
     main()