feat: add module management and installation capabilities

- Implemented a new module manager to handle module definitions and installations.
- Added built-in module definitions for NapCat and an example adapter.
- Introduced a resolver for download mirrors with fallback mechanisms.
- Enhanced the exec runner to support environment variables during command execution.
- Added prerequisite checks in the installation script to ensure required tools are available.
- Implemented retry logic for git operations with configurable backoff.
- Created tests for module installation, mirror resolution, and command execution.
- Improved logging for better visibility during module installation and execution.

Author: Sisyphus-Junior

README.md

@@ -1,7 +1,10 @@
 # MaiBot Bootstrap（单实例 CLI + TUI）
 
 本项目提供 MaiBot 的一键安装入口与跨平台命令行管理能力。
-采用 Git 风格 workspace：在项目目录执行 `maibot init` 创建 `.maibot/`，后续在该目录（或其子目录）运行命令即可。
+采用 Git 风格 workspace：在项目目录执行 `maibot init` 后，目录约定如下：
+- `.maibot/`：仅存放 maibot 命令行工具的配置/状态/日志数据
+- `modules/`：存放附属模块（如 napcat、适配器）
+- `MaiBot/`：存放本体文件
 
 ## 快速安装
 
@@ -11,6 +14,8 @@
 curl -fsSL https://raw.githubusercontent.com/Mai-with-u/maibot-bootstrap/main/scripts/install.sh | bash
 ```
 
+安装脚本会预检 `git` 与 `uv`；若缺失会先征求确认，确认后尝试自动安装。
+
 安装后可用：
 
 ```bash
@@ -30,8 +35,13 @@ maibot update
 maibot stop
 maibot workspace ls .
 maibot -C ../other-workspace status
+maibot modules list
+maibot modules install napcat
 ```
 
+内置 `napcat` 模块会执行系统依赖安装、LinuxQQ 安装、launcher 编译等步骤。
+这些步骤可能触发 sudo 认证，建议在 TTY 环境执行（例如直接在终端或 TUI 中运行）。
+
 服务管理：
 
 ```bash
@@ -42,10 +52,12 @@ maibot service stop
 maibot service uninstall
 ```
 
+说明：service 按 workspace 路径生成唯一服务名；可用 `maibot -C <path> service ...` 管理其他 workspace 的服务。
+
 自更新与清理：
 
 ```bash
-maibot self-update
+maibot upgrade
 maibot cleanup --test-artifacts
 maibot run echo devtool
 ```
@@ -54,8 +66,27 @@ maibot run echo devtool
 
 全局配置文件默认位于 `~/.maibot/maibot.conf`，为 JSON 格式。
 workspace 运行数据位于工作区目录下的 `.maibot/`（通过 `maibot init` 创建）。
+附属模块安装到工作区根目录的 `modules/`，本体目录使用 `MaiBot/`。
 支持环境变量覆盖（`MAIBOT_` 前缀）。
 
+`modules` 支持两种来源：
+- 内置模块列表（写死在代码中）
+- 远程 `catalog_urls`（HTTP JSON）
+
+git 与 modules 共用顶层 `mirrors` 镜像池配置。
+
+远程 catalog JSON 可为以下两种格式之一：
+
+```json
+{"modules":[{"name":"napcat","description":"...","install":[{"name":"step","command":"bash","args":["-lc","..."]}]}]}
+```
+
+或
+
+```json
+[{"name":"napcat","description":"...","install":[{"name":"step","command":"bash","args":["-lc","..."]}]}]
+```
+
 核心字段示例：
 
 ```json
@@ -77,6 +108,36 @@ workspace 运行数据位于工作区目录下的 `.maibot/`（通过 `maibot in
   "updater": {
     "require_signature": false,
     "minisign_public_key": ""
+  },
+  "mirrors": {
+    "urls": [
+      "https://ghfast.top",
+      "https://gh.wuliya.xin",
+      "https://gh-proxy.com",
+      "https://github.moeyy.xyz"
+    ],
+    "probe_url": "https://raw.githubusercontent.com/Mai-with-u/plugin-repo/refs/heads/main/plugins.json",
+    "probe_seconds": 8
+  },
+  "git": {
+    "mirrors": [
+      {
+        "name": "fastgit",
+        "base_url": "https://hub.fastgit.org",
+        "enabled": false
+      }
+    ],
+    "mirror_first": true,
+    "retry_per_source": 2,
+    "retry_backoff_seconds": 1,
+    "command_timeout_seconds": 120
+  },
+  "modules": {
+    "catalog_urls": [],
+    "catalog_timeout_seconds": 5,
+    "install_retries": 2,
+    "install_backoff_seconds": 1,
+    "prefer_catalog_source": false
   }
 }
 ```

internal/app/app.go

@@ -10,6 +10,7 @@ import (
 	"github.com/spf13/cobra"
 	"maibot/internal/config"
 	"maibot/internal/logging"
+	"maibot/internal/modules"
 	"maibot/internal/version"
 )
 
@@ -25,6 +26,7 @@ type App struct {
 	instanceLog *logging.Logger
 	updateLog   *logging.Logger
 	cleanupLog  *logging.Logger
+	modulesLog  *logging.Logger
 }
 
 func New() (*App, error) {
@@ -47,6 +49,7 @@ func New() (*App, error) {
 		instanceLog: rootLog.Module("instance"),
 		updateLog:   rootLog.Module("update"),
 		cleanupLog:  rootLog.Module("cleanup"),
+		modulesLog:  rootLog.Module("modules"),
 	}, nil
 }
 
@@ -148,7 +151,7 @@ func (a *App) newRootCommand() *cobra.Command {
 		return nil
 	}})
 
-	root.AddCommand(&cobra.Command{Use: "self-update", Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error {
+	root.AddCommand(&cobra.Command{Use: "upgrade", Aliases: []string{"self-update"}, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error {
 		if err := a.selfUpdate(); err != nil {
 			return err
 		}
@@ -213,6 +216,34 @@ func (a *App) newRootCommand() *cobra.Command {
 	workspaceCmd.AddCommand(workspaceList)
 	root.AddCommand(workspaceCmd)
 
+	modulesCmd := &cobra.Command{Use: "modules", Short: "Manage installable modules"}
+	modulesInstall := &cobra.Command{Use: "install <module>", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error {
+		mgr := modules.New(a.cfg.Modules, a.cfg.Mirrors, a.modulesLog, nil)
+		report, err := mgr.Install(cmd.Context(), args[0])
+		if err != nil {
+			return err
+		}
+		a.modulesLog.Okf("module install completed module=%s source=%s attempts=%d", report.Module, report.Source, len(report.Attempts))
+		return nil
+	}}
+	modulesList := &cobra.Command{Use: "list", Aliases: []string{"ls"}, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error {
+		mgr := modules.New(a.cfg.Modules, a.cfg.Mirrors, a.modulesLog, nil)
+		defs, err := mgr.List(cmd.Context())
+		if err != nil {
+			return err
+		}
+		for _, def := range defs {
+			desc := strings.TrimSpace(def.Description)
+			if desc == "" {
+				desc = "(no description)"
+			}
+			fmt.Printf("%s\t%s\n", def.Name, desc)
+		}
+		return nil
+	}}
+	modulesCmd.AddCommand(modulesInstall, modulesList)
+	root.AddCommand(modulesCmd)
+
 	root.AddCommand(&cobra.Command{Use: instanceProc, Hidden: true, RunE: func(cmd *cobra.Command, args []string) error {
 		id := workspaceID
 		displayName := defaultName
@@ -243,7 +274,9 @@ func (a *App) printHelp() {
 	fmt.Println("  maibot workspace ls [paths...]   Discover workspaces under paths")
 	fmt.Println("  maibot logs [--tail N]     Show workspace logs")
 	fmt.Println("  maibot update              Update workspace")
-	fmt.Println("  maibot self-update         Update maibot command")
+	fmt.Println("  maibot upgrade             Upgrade maibot command")
+	fmt.Println("  maibot modules install <name>  Install module by catalog name")
+	fmt.Println("  maibot modules list        List configured/catalog modules")
 	fmt.Println("  maibot service <action>    Manage workspace service")
 	fmt.Println("  maibot run <cmd...>        Run developer command")
 	fmt.Println("  maibot cleanup --test-artifacts  Clean local test artifacts")

internal/app/i18n/en.json

@@ -9,6 +9,7 @@
   "input_hint": "Press Enter to continue, Esc to cancel.",
   "menu.instances": "workspace",
   "menu.services": "services",
+  "menu.modules": "modules",
   "action.install": "initialize workspace",
   "action.start": "start workspace",
   "action.stop": "stop workspace",
@@ -17,18 +18,21 @@
   "action.logs": "workspace logs",
   "action.list": "list instances (deprecated)",
   "action.update": "update workspace",
-  "action.self_update": "self-update",
+  "action.self_update": "upgrade",
   "action.service_install": "service install",
   "action.service_start": "service start",
   "action.service_stop": "service stop",
   "action.service_status": "service status",
   "action.service_uninstall": "service uninstall",
+  "action.modules_list": "modules list",
+  "action.modules_install": "modules install",
   "action.cleanup": "cleanup --test-artifacts",
   "action.version": "version",
   "action.help": "help",
   "action.quit": "quit",
   "action.back": "back",
   "field.instance_name": "Instance name (deprecated)",
   "field.tail_lines": "Tail lines",
+  "field.module_name": "Module name",
   "field.cleanup_names": "Instance names (deprecated)"
 }

internal/app/i18n/zh-CN.json

@@ -9,6 +9,7 @@
   "input_hint": "回车继续，Esc 取消。",
   "menu.instances": "工作区",
   "menu.services": "服务管理",
+  "menu.modules": "模块管理",
   "action.install": "初始化工作区",
   "action.start": "启动工作区",
   "action.stop": "停止工作区",
@@ -17,18 +18,21 @@
   "action.logs": "查看工作区日志",
   "action.list": "列出实例（已弃用）",
   "action.update": "更新工作区",
-  "action.self_update": "更新 maibot 本体",
+  "action.self_update": "升级 maibot 本体",
   "action.service_install": "安装服务",
   "action.service_start": "启动服务",
   "action.service_stop": "停止服务",
   "action.service_status": "查看服务状态",
   "action.service_uninstall": "卸载服务",
+  "action.modules_list": "列出模块",
+  "action.modules_install": "安装模块",
   "action.cleanup": "清理测试产物",
   "action.version": "版本",
   "action.help": "帮助",
   "action.quit": "退出",
   "action.back": "返回",
   "field.instance_name": "实例名称（已弃用）",
   "field.tail_lines": "日志行数",
+  "field.module_name": "模块名",
   "field.cleanup_names": "实例名称（已弃用）"
 }

internal/app/service.go

@@ -5,6 +5,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"time"
 
 	kservice "github.com/kardianos/service"
@@ -63,11 +64,11 @@ func (a *App) serviceAction(action, _ string) error {
 		args:       []string{instanceProc, workspaceID, defaultName},
 		workdir:    workdir,
 	}
-	serviceName := "maibot-workspace"
+	serviceName := workspaceServiceName(workdir)
 	svc, err := kservice.New(prg, &kservice.Config{
 		Name:             serviceName,
 		DisplayName:      "MaiBot Workspace",
-		Description:      "MaiBot single workspace service",
+		Description:      "MaiBot workspace service " + serviceName,
 		Arguments:        prg.args,
 		WorkingDirectory: workdir,
 	})
@@ -104,3 +105,37 @@ func (a *App) serviceAction(action, _ string) error {
 	a.instanceLog.Infof("service action %s completed", action)
 	return nil
 }
+
+func workspaceServiceName(workdir string) string {
+	workspaceRoot := filepath.Dir(workdir)
+	base := sanitizeServiceToken(filepath.Base(workspaceRoot))
+	hash := sha256Hex([]byte(workspaceRoot))
+	if len(hash) > 8 {
+		hash = hash[:8]
+	}
+	name := fmt.Sprintf("maibot-%s-%s", base, hash)
+	if len(name) > 80 {
+		name = name[:80]
+	}
+	return name
+}
+
+func sanitizeServiceToken(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return "workspace"
+	}
+	var b strings.Builder
+	for _, r := range raw {
+		if (r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') || (r >= '0' && r <= '9') || r == '-' || r == '_' {
+			b.WriteRune(r)
+		} else {
+			b.WriteRune('-')
+		}
+	}
+	out := strings.Trim(b.String(), "-")
+	if out == "" {
+		return "workspace"
+	}
+	return out
+}

internal/app/tui.go

@@ -41,6 +41,7 @@ type tuiModel struct {
 	rootMenu      []tuiAction
 	instanceMenu  []tuiAction
 	serviceMenu   []tuiAction
+	modulesMenu   []tuiAction
 	cursor        int
 	mode          tuiMode
 	activeAction  int
@@ -84,10 +85,19 @@ func newTUIModel(i18n *tuiI18n) tuiModel {
 		{id: "back", labelKey: "action.back", build: func(_ []string) []string { return nil }},
 	}
 
+	modulesMenu := []tuiAction{
+		{id: "modules-list", labelKey: "action.modules_list", build: func(_ []string) []string { return []string{"modules", "list"} }},
+		{id: "modules-install", labelKey: "action.modules_install", fields: []tuiField{{labelKey: "field.module_name", def: "napcat"}}, build: func(v []string) []string {
+			return []string{"modules", "install", nonEmpty(v[0], "napcat")}
+		}},
+		{id: "back", labelKey: "action.back", build: func(_ []string) []string { return nil }},
+	}
+
 	rootMenu := []tuiAction{
 		{id: "instances", labelKey: "menu.instances", build: func(_ []string) []string { return nil }},
 		{id: "services", labelKey: "menu.services", build: func(_ []string) []string { return nil }},
-		{id: "self-update", labelKey: "action.self_update", build: func(_ []string) []string { return []string{"self-update"} }},
+		{id: "modules", labelKey: "menu.modules", build: func(_ []string) []string { return nil }},
+		{id: "self-update", labelKey: "action.self_update", build: func(_ []string) []string { return []string{"upgrade"} }},
 		{id: "version", labelKey: "action.version", build: func(_ []string) []string { return []string{"version"} }},
 		{id: "help", labelKey: "action.help", build: func(_ []string) []string { return []string{"help"} }},
 		{id: "quit", labelKey: "action.quit", quit: true, build: func(_ []string) []string { return nil }},
@@ -100,6 +110,7 @@ func newTUIModel(i18n *tuiI18n) tuiModel {
 		rootMenu:     rootMenu,
 		instanceMenu: instanceMenu,
 		serviceMenu:  serviceMenu,
+		modulesMenu:  modulesMenu,
 		mode:         tuiModeMenu,
 		activeAction: -1,
 	}
@@ -154,6 +165,9 @@ func (m tuiModel) updateMenu(msg tea.KeyMsg) (tea.Model, tea.Cmd) {
 		if action.id == "services" {
 			return m.pushMenu(m.serviceMenu), nil
 		}
+		if action.id == "modules" {
+			return m.pushMenu(m.modulesMenu), nil
+		}
 		if action.id == "back" {
 			return m.popMenu(), nil
 		}

internal/app/workspace.go

@@ -128,9 +128,16 @@ func (a *App) installInstance(name string) error {
 	if err != nil {
 		return err
 	}
+	workspaceRoot := filepath.Dir(dir)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return err
 	}
+	if err := os.MkdirAll(filepath.Join(workspaceRoot, "modules"), 0o755); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Join(workspaceRoot, "MaiBot"), 0o755); err != nil {
+		return err
+	}
 
 	now := time.Now().UTC()
 	workspaceName := sanitizeWorkspaceName(name)