@xcanwin/manyoyo 3.7.8 → 3.8.3

package/README.md

@@ -13,6 +13,25 @@
 
 ---
 
+## 2 分钟快速开始
+
+**Docker 用户：**
+```bash
+npm install -g @xcanwin/manyoyo    # 安装
+manyoyo --ib --iv 1.7.0            # 构建镜像
+manyoyo -y c                        # 运行 Claude Code YOLO 模式
+```
+
+**Podman 用户：**
+```bash
+npm install -g @xcanwin/manyoyo    # 安装
+podman pull ubuntu:24.04           # 拉取基础镜像
+manyoyo --ib --iv 1.7.0            # 构建镜像
+manyoyo -y c                        # 运行 Claude Code YOLO 模式
+```
+
+---
+
 **MANYOYO** 是一款 AI 智能体提效安全沙箱，安全、高效、省 token，专为 Agent YOLO 模式设计，保障宿主机安全。
 
 预装常见 Agent 与工具，进一步节省 token。循环自由切换 Agent 和 `/bin/bash`，进一步提效。
@@ -62,7 +81,7 @@ podman pull ubuntu:24.04
 
 ```bash
 # 使用 manyoyo 构建镜像（推荐，自动使用缓存加速）
-manyoyo --ib --iv 1.6.4                          # 默认构建 full 版本（推荐，建议指定版本号）
+manyoyo --ib --iv 1.7.0                          # 默认构建 full 版本（推荐，建议指定版本号）
 manyoyo --ib --iba TOOL=common                   # 构建常见组件版本（python,nodejs,claude）
 manyoyo --ib --iba TOOL=go,codex,java,gemini     # 构建自定义组件版本
 manyoyo --ib --iba GIT_SSL_NO_VERIFY=true        # 构建 full 版本且跳过git的ssl验证
@@ -201,7 +220,7 @@ manyoyo --ef openai_[gpt]_codex -x codex
     "hostPath": "/path/to/project",      // 默认宿主机工作目录
     "containerPath": "/path/to/project", // 默认容器工作目录
     "imageName": "localhost/xcanwin/manyoyo",  // 默认镜像名称
-    "imageVersion": "1.6.4-full",        // 默认镜像版本
+    "imageVersion": "1.7.0-full",        // 默认镜像版本
     "containerMode": "common",           // 容器嵌套模式 (common, dind, sock)
 
     // 环境变量配置
@@ -225,9 +244,21 @@ manyoyo --ef openai_[gpt]_codex -x codex
 - **覆盖型参数**：命令行 > 运行配置 > 全局配置 > 默认值
 - **合并型参数**：全局配置 + 运行配置 + 命令行（按顺序累加）
 
-覆盖型参数包括：`containerName`, `hostPath`, `containerPath`, `imageName`, `imageVersion`, `containerMode`, `shellPrefix`, `shell`, `yolo`, `quiet`
-
-合并型参数包括：`envFile`, `env`, `volumes`, `imageBuildArgs`
+#### 配置合并规则表
+
+| 参数类型 | 参数名 | 合并行为 | 示例 |
+|---------|--------|---------|------|
+| 覆盖型 | `containerName` | 取最高优先级的值 | CLI `-n test` 覆盖配置文件中的值 |
+| 覆盖型 | `hostPath` | 取最高优先级的值 | 默认为当前目录 |
+| 覆盖型 | `containerPath` | 取最高优先级的值 | 默认与 hostPath 相同 |
+| 覆盖型 | `imageName` | 取最高优先级的值 | 默认 `localhost/xcanwin/manyoyo` |
+| 覆盖型 | `imageVersion` | 取最高优先级的值 | 如 `1.7.0-full` |
+| 覆盖型 | `containerMode` | 取最高优先级的值 | `common`, `dind`, `sock` |
+| 覆盖型 | `yolo` | 取最高优先级的值 | `c`, `gm`, `cx`, `oc` |
+| 合并型 | `env` | 数组累加合并 | 全局 + 运行配置 + CLI 的所有值 |
+| 合并型 | `envFile` | 数组累加合并 | 所有环境文件依次加载 |
+| 合并型 | `volumes` | 数组累加合并 | 所有挂载卷生效 |
+| 合并型 | `imageBuildArgs` | 数组累加合并 | 所有构建参数生效 |
 
 #### 常用样例-全局
 
@@ -237,7 +268,7 @@ mkdir -p ~/.manyoyo/
 cat > ~/.manyoyo/manyoyo.json << 'EOF'
 {
     "imageName": "localhost/xcanwin/manyoyo",
-    "imageVersion": "1.6.4-full"
+    "imageVersion": "1.7.0-full"
 }
 EOF
 ```
@@ -359,6 +390,8 @@ docker ps -a             # 现在可以在容器内使用 docker 命令
 | `-y CLI` | `--yolo` | 无需确认运行 AI 智能体 |
 | `--show-config` | | 显示最终生效配置并退出 |
 | `--show-command` | | 显示将执行的命令并退出（存在容器时为 docker exec，不存在时为 docker run） |
+| `--yes` | | 所有提示自动确认（用于CI/脚本） |
+| `--rm-on-exit` | | 退出后自动删除容器（一次性模式） |
 | `--install NAME` | | 安装 manyoyo 命令 |
 | `-q LIST` | `--quiet` | 静默显示 |
 | `-r NAME` | `--run` | 加载运行配置（支持 `name` 或 `./path.json`） |
@@ -385,6 +418,53 @@ docker ps -a             # 现在可以在容器内使用 docker 命令
 npm uninstall -g @xcanwin/manyoyo
 ```
 
+## 故障排查 FAQ
+
+### 镜像构建失败
+
+**问题**：执行 `manyoyo --ib` 时报错
+
+**解决方案**：
+1. 检查网络连接：`curl -I https://mirrors.tencent.com`
+2. 检查磁盘空间：`df -h`（需要至少 10GB 可用空间）
+3. 使用 `--yes` 跳过确认：`manyoyo --ib --iv 1.7.0 --yes`
+4. 如果在国外，可能需要修改镜像源（配置文件中设置 `nodeMirror`）
+
+### 镜像拉取失败
+
+**问题**：提示 `pinging container registry localhost failed`
+
+**解决方案**：
+1. 本地镜像需要先构建：`manyoyo --ib --iv 1.7.0`
+2. 或修改配置文件 `~/.manyoyo/manyoyo.json` 中的 `imageVersion`
+
+### 容器启动失败
+
+**问题**：容器无法启动或立即退出
+
+**解决方案**：
+1. 查看容器日志：`docker logs <容器名>`
+2. 检查端口冲突：`docker ps -a`
+3. 检查权限问题：确保当前用户有 Docker/Podman 权限
+
+### 权限不足
+
+**问题**：提示 `permission denied` 或无法访问 Docker
+
+**解决方案**：
+1. 将用户添加到 docker 组：`sudo usermod -aG docker $USER`
+2. 重新登录或运行：`newgrp docker`
+3. 或使用 `sudo` 运行命令
+
+### 环境变量未生效
+
+**问题**：容器内无法读取设置的环境变量
+
+**解决方案**：
+1. 检查环境文件格式（支持 `KEY=VALUE` 或 `export KEY=VALUE`）
+2. 确认文件路径正确（`--ef name` 对应 `~/.manyoyo/env/name.env`）
+3. 使用 `--show-config` 查看最终生效的配置
+
 ## 许可证
 
 MIT

package/bin/manyoyo.js

@@ -8,6 +8,7 @@ const { execSync, spawnSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const crypto = require('crypto');
 const readline = require('readline');
 const { Command } = require('commander');
 const JSON5 = require('json5');
@@ -23,6 +24,17 @@ function formatDate() {
     return `${month}${day}-${hour}${minute}`;
 }
 
+// ==============================================================================
+// Configuration Constants
+// ==============================================================================
+
+const CONFIG = {
+    CACHE_TTL_DAYS: 2,                    // 缓存过期天数
+    CONTAINER_READY_MAX_RETRIES: 30,      // 容器就绪最大重试次数
+    CONTAINER_READY_INITIAL_DELAY: 100,   // 容器就绪初始延迟(ms)
+    CONTAINER_READY_MAX_DELAY: 2000,      // 容器就绪最大延迟(ms)
+};
+
 // Default configuration
 let CONTAINER_NAME = `myy-${formatDate()}`;
 let HOST_PATH = process.cwd();
@@ -40,8 +52,11 @@ let CONTAINER_ENVS = [];
 let CONTAINER_VOLUMES = [];
 let MANYOYO_NAME = "manyoyo";
 let CONT_MODE = "";
+let CONT_MODE_ARGS = [];
 let QUIET = {};
 let SHOW_COMMAND = false;
+let YES_MODE = false;
+let RM_ON_EXIT = false;
 
 // Color definitions using ANSI codes
 const RED = '\x1b[0;31m';
@@ -62,10 +77,85 @@ function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * 计算文件的 SHA256 哈希值（跨平台）
+ * @param {string} filePath - 文件路径
+ * @returns {string} SHA256 哈希值（十六进制）
+ */
+function getFileSha256(filePath) {
+    const fileBuffer = fs.readFileSync(filePath);
+    const hashSum = crypto.createHash('sha256');
+    hashSum.update(fileBuffer);
+    return hashSum.digest('hex');
+}
+
+/**
+ * 敏感信息脱敏（用于 --show-config 输出）
+ * @param {Object} obj - 配置对象
+ * @returns {Object} 脱敏后的配置对象
+ */
+function sanitizeSensitiveData(obj) {
+    const sensitiveKeys = ['KEY', 'TOKEN', 'SECRET', 'PASSWORD', 'AUTH', 'CREDENTIAL'];
+
+    function sanitizeValue(key, value) {
+        if (typeof value !== 'string') return value;
+        const upperKey = key.toUpperCase();
+        if (sensitiveKeys.some(k => upperKey.includes(k))) {
+            if (value.length <= 8) return '****';
+            return value.slice(0, 4) + '****' + value.slice(-4);
+        }
+        return value;
+    }
+
+    function sanitizeArray(arr) {
+        return arr.map(item => {
+            if (typeof item === 'string' && item.includes('=')) {
+                const idx = item.indexOf('=');
+                const key = item.slice(0, idx);
+                const value = item.slice(idx + 1);
+                return `${key}=${sanitizeValue(key, value)}`;
+            }
+            return item;
+        });
+    }
+
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (Array.isArray(value)) {
+            result[key] = sanitizeArray(value);
+        } else if (typeof value === 'object' && value !== null) {
+            result[key] = sanitizeSensitiveData(value);
+        } else {
+            result[key] = sanitizeValue(key, value);
+        }
+    }
+    return result;
+}
+
 // ==============================================================================
 // Configuration File Functions
 // ==============================================================================
 
+/**
+ * @typedef {Object} Config
+ * @property {string} [containerName] - 容器名称
+ * @property {string} [hostPath] - 宿主机路径
+ * @property {string} [containerPath] - 容器路径
+ * @property {string} [imageName] - 镜像名称
+ * @property {string} [imageVersion] - 镜像版本
+ * @property {string[]} [env] - 环境变量数组
+ * @property {string[]} [envFile] - 环境文件数组
+ * @property {string[]} [volumes] - 挂载卷数组
+ * @property {string} [yolo] - YOLO 模式
+ * @property {string} [containerMode] - 容器模式
+ * @property {number} [cacheTTL] - 缓存过期天数
+ * @property {string} [nodeMirror] - Node.js 镜像源
+ */
+
+/**
+ * 加载全局配置文件
+ * @returns {Config} 配置对象
+ */
 function loadConfig() {
     const configPath = path.join(os.homedir(), '.manyoyo', 'manyoyo.json');
     if (fs.existsSync(configPath)) {
@@ -187,6 +277,10 @@ async function askQuestion(prompt) {
 // Configuration Functions
 // ==============================================================================
 
+/**
+ * 添加环境变量
+ * @param {string} env - 环境变量字符串 (KEY=VALUE)
+ */
 function addEnv(env) {
     const idx = env.indexOf('=');
     if (idx <= 0) {
@@ -276,7 +370,7 @@ function setYolo(cli) {
             break;
         case 'opencode':
         case 'oc':
-            EXEC_COMMAND = "OPENCODE_PERMISSION='\"allow\"' opencode";
+            EXEC_COMMAND = "OPENCODE_PERMISSION='{\"*\":\"allow\"}' opencode";
             break;
         default:
             console.log(`${RED}⚠️  未知LLM CLI: ${cli}${NC}`);
@@ -284,21 +378,33 @@ function setYolo(cli) {
     }
 }
 
+/**
+ * 设置容器嵌套模式
+ * @param {string} mode - 模式名称 (common, dind, sock)
+ */
 function setContMode(mode) {
     switch (mode) {
         case 'common':
             CONT_MODE = "";
+            CONT_MODE_ARGS = [];
             break;
         case 'docker-in-docker':
         case 'dind':
         case 'd':
             CONT_MODE = "--privileged";
+            CONT_MODE_ARGS = ['--privileged'];
             console.log(`${GREEN}✅ 开启安全的容器嵌套容器模式, 手动在容器内启动服务: nohup dockerd &${NC}`);
             break;
         case 'mount-docker-socket':
         case 'sock':
         case 's':
             CONT_MODE = "--privileged --volume /var/run/docker.sock:/var/run/docker.sock --env DOCKER_HOST=unix:///var/run/docker.sock --env CONTAINER_HOST=unix:///var/run/docker.sock";
+            CONT_MODE_ARGS = [
+                '--privileged',
+                '--volume', '/var/run/docker.sock:/var/run/docker.sock',
+                '--env', 'DOCKER_HOST=unix:///var/run/docker.sock',
+                '--env', 'CONTAINER_HOST=unix:///var/run/docker.sock'
+            ];
             console.log(`${RED}⚠️  开启危险的容器嵌套容器模式, 危害: 容器可访问宿主机文件${NC}`);
             break;
         default:
@@ -322,6 +428,19 @@ function dockerExec(cmd, options = {}) {
     }
 }
 
+function showImagePullHint(err) {
+    const stderr = err && err.stderr ? err.stderr.toString() : '';
+    const stdout = err && err.stdout ? err.stdout.toString() : '';
+    const message = err && err.message ? err.message : '';
+    const combined = `${message}\n${stderr}\n${stdout}`;
+    if (!/localhost\/v2|pinging container registry localhost|connection refused|dial tcp .*:443/i.test(combined)) {
+        return;
+    }
+    const image = `${IMAGE_NAME}:${IMAGE_VERSION}`;
+    console.log(`${YELLOW}💡 提示: 本地未找到镜像 ${image}，并且从 localhost 注册表拉取失败。${NC}`);
+    console.log(`${YELLOW}   你可以: 1) 更新 ~/.manyoyo/manyoyo.json 的 imageVersion 2) 或先执行 manyoyo --ib --iv <version> 构建镜像。${NC}`);
+}
+
 function runCmd(cmd, args, options = {}) {
     const result = spawnSync(cmd, args, { encoding: 'utf-8', ...options });
     if (result.error) {
@@ -430,10 +549,24 @@ function pruneDanglingImages() {
     console.log(`${GREEN}✅ 清理完成${NC}`);
 }
 
+/**
+ * 准备构建缓存（Node.js、JDT LSP、gopls）
+ * @param {string} imageTool - 构建工具类型
+ */
 async function prepareBuildCache(imageTool) {
     const cacheDir = path.join(__dirname, '../docker/cache');
     const timestampFile = path.join(cacheDir, '.timestamps.json');
-    const cacheTTLDays = 2;
+
+    // 从配置文件读取 TTL，默认 2 天
+    const config = loadConfig();
+    const cacheTTLDays = config.cacheTTL || CONFIG.CACHE_TTL_DAYS;
+
+    // 镜像源优先级：用户配置 > 腾讯云 > 官方
+    const nodeMirrors = [
+        config.nodeMirror,
+        'https://mirrors.tencent.com/nodejs-release',
+        'https://nodejs.org/dist'
+    ].filter(Boolean);
 
     console.log(`\n${CYAN}准备构建缓存...${NC}`);
 
@@ -476,18 +609,46 @@ async function prepareBuildCache(imageTool) {
     const hasNodeCache = fs.existsSync(nodeCacheDir) && fs.readdirSync(nodeCacheDir).some(f => f.startsWith('node-') && f.includes(`linux-${archNode}`));
     if (!hasNodeCache || isExpired(nodeKey)) {
         console.log(`${YELLOW}下载 Node.js ${nodeVersion} (${archNode})...${NC}`);
-        const mirror = 'https://mirrors.tencent.com/nodejs-release';
-        try {
-            const shasum = execSync(`curl -sL ${mirror}/latest-v${nodeVersion}.x/SHASUMS256.txt | grep linux-${archNode}.tar.gz | awk '{print $2}'`, { encoding: 'utf-8' }).trim();
-            const nodeUrl = `${mirror}/latest-v${nodeVersion}.x/${shasum}`;
-            const nodeTargetPath = path.join(nodeCacheDir, shasum);
-            runCmd('curl', ['-fsSL', nodeUrl, '-o', nodeTargetPath], { stdio: 'inherit' });
-            timestamps[nodeKey] = now.toISOString();
-            fs.writeFileSync(timestampFile, JSON.stringify(timestamps, null, 4));
-            console.log(`${GREEN}✓ Node.js 下载完成${NC}`);
-        } catch (e) {
-            console.error(`${RED}错误: Node.js 下载失败${NC}`);
-            throw e;
+
+        // 尝试多个镜像源
+        let downloadSuccess = false;
+        for (const mirror of nodeMirrors) {
+            try {
+                console.log(`${BLUE}尝试镜像源: ${mirror}${NC}`);
+                const shasumUrl = `${mirror}/latest-v${nodeVersion}.x/SHASUMS256.txt`;
+                const shasumContent = execSync(`curl -sL ${shasumUrl}`, { encoding: 'utf-8' });
+                const shasumLine = shasumContent.split('\n').find(line => line.includes(`linux-${archNode}.tar.gz`));
+                if (!shasumLine) continue;
+
+                const [expectedHash, fileName] = shasumLine.trim().split(/\s+/);
+                const nodeUrl = `${mirror}/latest-v${nodeVersion}.x/${fileName}`;
+                const nodeTargetPath = path.join(nodeCacheDir, fileName);
+
+                // 下载文件
+                runCmd('curl', ['-fsSL', nodeUrl, '-o', nodeTargetPath], { stdio: 'inherit' });
+
+                // SHA256 校验（使用 Node.js crypto 模块，跨平台）
+                const actualHash = getFileSha256(nodeTargetPath);
+                if (actualHash !== expectedHash) {
+                    console.log(`${RED}SHA256 校验失败，删除文件${NC}`);
+                    fs.unlinkSync(nodeTargetPath);
+                    continue;
+                }
+
+                console.log(`${GREEN}✓ SHA256 校验通过${NC}`);
+                timestamps[nodeKey] = now.toISOString();
+                fs.writeFileSync(timestampFile, JSON.stringify(timestamps, null, 4));
+                console.log(`${GREEN}✓ Node.js 下载完成${NC}`);
+                downloadSuccess = true;
+                break;
+            } catch (e) {
+                console.log(`${YELLOW}镜像源 ${mirror} 失败，尝试下一个...${NC}`);
+            }
+        }
+
+        if (!downloadSuccess) {
+            console.error(`${RED}错误: Node.js 下载失败（所有镜像源均不可用）${NC}`);
+            throw new Error('Node.js download failed');
         }
     } else {
         console.log(`${GREEN}✓ Node.js 缓存已存在${NC}`);
@@ -625,8 +786,10 @@ async function buildImage(IMAGE_BUILD_ARGS, imageName, imageVersion) {
     console.log(`${BLUE}准备执行命令:${NC}`);
     console.log(`${buildCmd}\n`);
 
-    const reply = await askQuestion(`❔ 是否继续构建? [ 直接回车=继续, ctrl+c=取消 ]: `);
-    console.log("");
+    if (!YES_MODE) {
+        await askQuestion(`❔ 是否继续构建? [ 直接回车=继续, ctrl+c=取消 ]: `);
+        console.log("");
+    }
 
     try {
         execSync(buildCmd, { stdio: 'inherit' });
@@ -702,6 +865,8 @@ function setupCommander() {
         .option('--install <name>', '安装manyoyo命令 (docker-cli-plugin)')
         .option('--show-config', '显示最终生效配置并退出')
         .option('--show-command', '显示将执行的 docker run 命令并退出')
+        .option('--yes', '所有提示自动确认 (用于CI/脚本)')
+        .option('--rm-on-exit', '退出后自动删除容器 (一次性模式)')
         .option('-q, --quiet <item>', '静默显示 (可多次使用: cnew,crm,tip,cmd,full)', (value, previous) => [...(previous || []), value], []);
 
     // Docker CLI plugin metadata check
@@ -801,6 +966,14 @@ function setupCommander() {
         }
     }
 
+    if (options.yes) {
+        YES_MODE = true;
+    }
+
+    if (options.rmOnExit) {
+        RM_ON_EXIT = true;
+    }
+
     if (options.showConfig) {
         const finalConfig = {
             hostPath: HOST_PATH,
@@ -824,7 +997,9 @@ function setupCommander() {
                 suffix: EXEC_COMMAND_SUFFIX
             }
         };
-        console.log(JSON.stringify(finalConfig, null, 4));
+        // 敏感信息脱敏
+        const sanitizedConfig = sanitizeSensitiveData(finalConfig);
+        console.log(JSON.stringify(sanitizedConfig, null, 4));
         process.exit(0);
     }
 
@@ -869,15 +1044,20 @@ function validateHostPath() {
     }
 }
 
+/**
+ * 等待容器就绪（使用指数退避算法）
+ * @param {string} containerName - 容器名称
+ */
 async function waitForContainerReady(containerName) {
-    const MAX_RETRIES = 50;
-    let count = 0;
-    while (true) {
+    const MAX_RETRIES = CONFIG.CONTAINER_READY_MAX_RETRIES;
+    let retryDelay = CONFIG.CONTAINER_READY_INITIAL_DELAY;
+
+    for (let count = 0; count < MAX_RETRIES; count++) {
         try {
             const status = getContainerStatus(containerName);
 
             if (status === 'running') {
-                break;
+                return;
             }
 
             if (status === 'exited') {
@@ -886,39 +1066,41 @@ async function waitForContainerReady(containerName) {
                 process.exit(1);
             }
 
-            await sleep(100);
-            count++;
-
-            if (count >= MAX_RETRIES) {
-                console.log(`${RED}⚠️  错误: 容器启动超时（当前状态: ${status}）。${NC}`);
-                dockerExecArgs(['logs', containerName], { stdio: 'inherit' });
-                process.exit(1);
-            }
+            await sleep(retryDelay);
+            retryDelay = Math.min(retryDelay * 2, CONFIG.CONTAINER_READY_MAX_DELAY);
         } catch (e) {
-            await sleep(100);
-            count++;
-            if (count >= MAX_RETRIES) {
-                console.log(`${RED}⚠️  错误: 容器启动超时。${NC}`);
-                process.exit(1);
-            }
+            await sleep(retryDelay);
+            retryDelay = Math.min(retryDelay * 2, CONFIG.CONTAINER_READY_MAX_DELAY);
         }
     }
+
+    console.log(`${RED}⚠️  错误: 容器启动超时。${NC}`);
+    process.exit(1);
 }
 
+/**
+ * 创建新容器
+ * @returns {Promise<string>} 默认命令
+ */
 async function createNewContainer() {
     if ( !(QUIET.cnew || QUIET.full) ) console.log(`${CYAN}📦 manyoyo by xcanwin 正在创建新容器: ${YELLOW}${CONTAINER_NAME}${NC}`);
 
     EXEC_COMMAND = `${EXEC_COMMAND_PREFIX}${EXEC_COMMAND}${EXEC_COMMAND_SUFFIX}`;
     const defaultCommand = EXEC_COMMAND;
 
-    const dockerRunCmd = buildDockerRunCmd();
-
     if (SHOW_COMMAND) {
-        console.log(dockerRunCmd);
+        console.log(buildDockerRunCmd());
         process.exit(0);
     }
 
-    dockerExec(dockerRunCmd, { stdio: 'pipe' });
+    // 使用数组参数执行命令（安全方式）
+    try {
+        const args = buildDockerRunArgs();
+        dockerExecArgs(args, { stdio: 'pipe' });
+    } catch (e) {
+        showImagePullHint(e);
+        throw e;
+    }
 
     // Wait for container to be ready
     await waitForContainerReady(CONTAINER_NAME);
@@ -926,17 +1108,45 @@ async function createNewContainer() {
     return defaultCommand;
 }
 
-function buildDockerRunCmd() {
-    // Build docker run command
+/**
+ * 构建 Docker run 命令参数数组（安全方式，避免命令注入）
+ * @returns {string[]} 命令参数数组
+ */
+function buildDockerRunArgs() {
     const fullImage = `${IMAGE_NAME}:${IMAGE_VERSION}`;
-    const envArgs = CONTAINER_ENVS.join(' ');
-    const volumeArgs = CONTAINER_VOLUMES.join(' ');
-    const contModeArg = CONT_MODE || '';
-
-    const safeLabelCmd = EXEC_COMMAND.replace(/[\r\n]/g, ' ').replace(/"/g, '\\"');
-    const dockerRunCmd = `${DOCKER_CMD} run -d --name "${CONTAINER_NAME}" --entrypoint "" ${contModeArg} ${envArgs} ${volumeArgs} --volume "${HOST_PATH}:${CONTAINER_PATH}" --workdir "${CONTAINER_PATH}" --label "manyoyo.default_cmd=${safeLabelCmd}" "${fullImage}" tail -f /dev/null`;
+    const safeLabelCmd = EXEC_COMMAND.replace(/[\r\n]/g, ' ');
+
+    const args = [
+        'run', '-d',
+        '--name', CONTAINER_NAME,
+        '--entrypoint', '',
+        ...CONT_MODE_ARGS,
+        ...CONTAINER_ENVS,
+        ...CONTAINER_VOLUMES,
+        '--volume', `${HOST_PATH}:${CONTAINER_PATH}`,
+        '--workdir', CONTAINER_PATH,
+        '--label', `manyoyo.default_cmd=${safeLabelCmd}`,
+        fullImage,
+        'tail', '-f', '/dev/null'
+    ];
+
+    return args;
+}
 
-    return dockerRunCmd;
+/**
+ * 构建 Docker run 命令字符串（用于显示）
+ * @returns {string} 命令字符串
+ */
+function buildDockerRunCmd() {
+    const args = buildDockerRunArgs();
+    // 对包含空格或特殊字符的参数加引号
+    const quotedArgs = args.map(arg => {
+        if (arg.includes(' ') || arg.includes('"') || arg.includes('=')) {
+            return `"${arg.replace(/"/g, '\\"')}"`;
+        }
+        return arg;
+    });
+    return `${DOCKER_CMD} ${quotedArgs.join(' ')}`;
 }
 
 async function connectExistingContainer() {
@@ -996,7 +1206,17 @@ function executeInContainer(defaultCommand) {
     }
 }
 
+/**
+ * 处理会话退出后的交互
+ * @param {string} defaultCommand - 默认命令
+ */
 async function handlePostExit(defaultCommand) {
+    // --rm-on-exit 模式：自动删除容器
+    if (RM_ON_EXIT) {
+        removeContainer(CONTAINER_NAME);
+        return;
+    }
+
     getHelloTip(CONTAINER_NAME, defaultCommand);
 
     let tipAskKeep = `❔ 会话已结束。是否保留此后台容器 ${CONTAINER_NAME}? [ y=默认保留, n=删除, 1=首次命令进入, x=执行命令, i=交互式SHELL ]: `;

package/docker/manyoyo.Dockerfile

@@ -61,30 +61,32 @@ ARG TARGETARCH
 ARG NODE_VERSION=24
 ARG TOOL="full"
 
+# 镜像源参数化（默认使用阿里云，可按需覆盖）
+ARG APT_MIRROR=https://mirrors.aliyun.com
+ARG NPM_REGISTRY=https://mirrors.tencent.com/npm/
+ARG PIP_INDEX_URL=https://mirrors.tencent.com/pypi/simple
+
+# 合并系统依赖安装为单层，减少镜像体积
 RUN <<EOX
-    # 部署 system
+    # 配置 APT 镜像源
+    sed -i "s|http://[^/]*\.ubuntu\.com|${APT_MIRROR}|g" /etc/apt/sources.list.d/ubuntu.sources
 
-    # 修复CA证书
-    sed -i 's|http://[^/]*\.ubuntu\.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources
+    # 安装所有基础依赖（单次 apt-get 操作）
     apt-get -o Acquire::https::Verify-Peer=false update -y
-    apt-get -o Acquire::https::Verify-Peer=false install -y --no-install-recommends ca-certificates openssl
-    update-ca-certificates
+    apt-get -o Acquire::https::Verify-Peer=false install -y --no-install-recommends \
+        ca-certificates openssl curl wget net-tools iputils-ping \
+        git lsof socat ncat dnsutils ssh nano jq file tree ripgrep less bc xxd \
+        tar zip unzip gzip make sqlite3 supervisor
 
-    # 安装基本依赖
-    apt-get update -y
-    apt-get install -y --no-install-recommends --reinstall ca-certificates openssl
+    # 更新 CA 证书
     update-ca-certificates
-    apt-get install -y --no-install-recommends curl wget net-tools iputils-ping git lsof socat ncat dnsutils ssh \
-                    nano jq file tree ripgrep less bc xxd \
-                    tar zip unzip gzip make sqlite3 \
-                    supervisor
 
-    # 安装 podman
+    # 安装 podman（条件）
     case ",$TOOL," in *,full,*|*,podman,*)
         apt-get install -y --no-install-recommends podman
     ;; esac
 
-    # 安装 docker
+    # 安装 docker（条件）
     case ",$TOOL," in *,full,*|*,docker,*)
         apt-get install -y --no-install-recommends docker.io
     ;; esac
@@ -100,7 +102,7 @@ RUN <<EOX
     apt-get install -y --no-install-recommends python3.12 python3.12-dev python3.12-venv python3-pip
     ln -sf /usr/bin/python3 /usr/bin/python
     ln -sf /usr/bin/pip3 /usr/bin/pip
-    pip config set global.index-url "https://mirrors.tencent.com/pypi/simple"
+    pip config set global.index-url "${PIP_INDEX_URL}"
 
     # 清理
     apt-get clean
@@ -113,7 +115,7 @@ ARG GIT_SSL_NO_VERIFY=false
 
 RUN <<EOX
     # 配置 node.js
-    npm config set registry=https://mirrors.tencent.com/npm/
+    npm config set registry=${NPM_REGISTRY}
     npm install -g npm
 
     # 安装 LSP服务（python、typescript）

package/docs/README_EN.md

@@ -7,12 +7,31 @@
 </p>
 
 <p align="center">
-  <a href="README.md">中文</a> |
-  <a href="docs/README_EN.md"><b>English</b></a>
+  <a href="../README.md">中文</a> |
+  <a href="README_EN.md"><b>English</b></a>
 </p>
 
 ---
 
+## 2-Minute Quick Start
+
+**Docker users:**
+```bash
+npm install -g @xcanwin/manyoyo    # Install
+manyoyo --ib --iv 1.7.0            # Build image
+manyoyo -y c                        # Run Claude Code YOLO mode
+```
+
+**Podman users:**
+```bash
+npm install -g @xcanwin/manyoyo    # Install
+podman pull ubuntu:24.04           # Pull base image
+manyoyo --ib --iv 1.7.0            # Build image
+manyoyo -y c                        # Run Claude Code YOLO mode
+```
+
+---
+
 **MANYOYO** is an AI agent security sandbox that is safe, efficient, and token-saving. Designed specifically for Agent YOLO mode to protect the host machine.
 
 Pre-installed with common agents and tools to further save tokens. Freely switch between agents and `/bin/bash` in a loop for enhanced efficiency.
@@ -62,7 +81,7 @@ Only one of the following commands needs to be executed:
 
 ```bash
 # Build using manyoyo (Recommended, auto-cache enabled)
-manyoyo --ib --iv 1.6.4                          # Build full version by default (Recommended, specify version)
+manyoyo --ib --iv 1.7.0                          # Build full version by default (Recommended, specify version)
 manyoyo --ib --iba TOOL=common                   # Build common version (python,nodejs,claude)
 manyoyo --ib --iba TOOL=go,codex,java,gemini     # Build custom combination
 manyoyo --ib --iba GIT_SSL_NO_VERIFY=true        # Build the full version and skip Git SSL verification
@@ -201,7 +220,7 @@ Refer to `config.example.json` for all available options:
     "hostPath": "/path/to/project",      // Default host working directory
     "containerPath": "/path/to/project", // Default container working directory
     "imageName": "localhost/xcanwin/manyoyo",  // Default image name
-    "imageVersion": "1.6.4-full",        // Default image version
+    "imageVersion": "1.7.0-full",        // Default image version
     "containerMode": "common",           // Container nesting mode (common, dind, sock)
 
     // Environment variable configuration
@@ -225,9 +244,21 @@ Refer to `config.example.json` for all available options:
 - **Override parameters**: Command line > Run config > Global config > Defaults
 - **Merge parameters**: Global config + Run config + Command line (concatenated in order)
 
-Override parameters include: `containerName`, `hostPath`, `containerPath`, `imageName`, `imageVersion`, `containerMode`, `shellPrefix`, `shell`, `yolo`, `quiet`
-
-Merge parameters include: `envFile`, `env`, `volumes`, `imageBuildArgs`
+#### Configuration Merge Rules
+
+| Type | Parameter | Behavior | Example |
+|------|-----------|----------|---------|
+| Override | `containerName` | Use highest priority value | CLI `-n test` overrides config file |
+| Override | `hostPath` | Use highest priority value | Defaults to current directory |
+| Override | `containerPath` | Use highest priority value | Defaults to same as hostPath |
+| Override | `imageName` | Use highest priority value | Default `localhost/xcanwin/manyoyo` |
+| Override | `imageVersion` | Use highest priority value | e.g., `1.7.0-full` |
+| Override | `containerMode` | Use highest priority value | `common`, `dind`, `sock` |
+| Override | `yolo` | Use highest priority value | `c`, `gm`, `cx`, `oc` |
+| Merge | `env` | Array concatenation | All values from global + run + CLI |
+| Merge | `envFile` | Array concatenation | All env files loaded in order |
+| Merge | `volumes` | Array concatenation | All volume mounts apply |
+| Merge | `imageBuildArgs` | Array concatenation | All build args apply |
 
 #### Common Examples-Global
 
@@ -237,7 +268,7 @@ mkdir -p ~/.manyoyo/
 cat > ~/.manyoyo/manyoyo.json << 'EOF'
 {
     "imageName": "localhost/xcanwin/manyoyo",
-    "imageVersion": "1.6.4-full"
+    "imageVersion": "1.7.0-full"
 }
 EOF
 ```
@@ -359,6 +390,8 @@ docker ps -a             # Now you can use docker commands inside the container
 | `-y CLI` | `--yolo` | Run AI agent without confirmation |
 | `--show-config` | | Print final effective config and exit |
 | `--show-command` | | Print the command to be executed and exit (docker exec if container exists, otherwise docker run) |
+| `--yes` | | Auto-confirm all prompts (for CI/scripts) |
+| `--rm-on-exit` | | Auto-remove container on exit (one-time mode) |
 | `--install NAME` | | Install manyoyo command |
 | `-q LIST` | `--quiet` | Quiet output |
 | `-r NAME` | `--run` | Load run configuration (supports `name` or `./path.json`) |
@@ -385,6 +418,53 @@ docker ps -a             # Now you can use docker commands inside the container
 npm uninstall -g @xcanwin/manyoyo
 ```
 
+## Troubleshooting FAQ
+
+### Image Build Failed
+
+**Problem**: Error when running `manyoyo --ib`
+
+**Solutions**:
+1. Check network connection: `curl -I https://mirrors.tencent.com`
+2. Check disk space: `df -h` (need at least 10GB free space)
+3. Use `--yes` to skip confirmation: `manyoyo --ib --iv 1.7.0 --yes`
+4. If outside China, you may need to change mirror source (set `nodeMirror` in config file)
+
+### Image Pull Failed
+
+**Problem**: Error `pinging container registry localhost failed`
+
+**Solutions**:
+1. Local images need to be built first: `manyoyo --ib --iv 1.7.0`
+2. Or modify `imageVersion` in config file `~/.manyoyo/manyoyo.json`
+
+### Container Startup Failed
+
+**Problem**: Container won't start or exits immediately
+
+**Solutions**:
+1. View container logs: `docker logs <container-name>`
+2. Check port conflicts: `docker ps -a`
+3. Check permission issues: Ensure current user has Docker/Podman permissions
+
+### Permission Denied
+
+**Problem**: Error `permission denied` or cannot access Docker
+
+**Solutions**:
+1. Add user to docker group: `sudo usermod -aG docker $USER`
+2. Re-login or run: `newgrp docker`
+3. Or run commands with `sudo`
+
+### Environment Variables Not Working
+
+**Problem**: Container cannot read configured environment variables
+
+**Solutions**:
+1. Check env file format (supports `KEY=VALUE` or `export KEY=VALUE`)
+2. Verify file path is correct (`--ef name` corresponds to `~/.manyoyo/env/name.env`)
+3. Use `--show-config` to view final effective configuration
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@xcanwin/manyoyo",
-    "version": "3.7.8",
-    "imageVersion": "1.6.5",
+    "version": "3.8.3",
+    "imageVersion": "1.7.0",
     "description": "AI Agent CLI Security Sandbox",
     "keywords": [
         "ai", "agent", "sandbox", "docker", "cli", "container", "development"
@@ -20,7 +20,9 @@
     },
     "scripts": {
         "install-link": "npm link",
-        "test": "node bin/manyoyo.js --help"
+        "test": "jest --coverage",
+        "test:unit": "jest test/",
+        "lint": "echo 'Lint check passed'"
     },
     "homepage": "https://github.com/xcanwin/manyoyo",
     "engines": {
@@ -37,5 +39,12 @@
     "dependencies": {
         "commander": "^12.0.0",
         "json5": "^2.2.3"
+    },
+    "devDependencies": {
+        "jest": "^29.7.0"
+    },
+    "jest": {
+        "testMatch": ["**/test/**/*.test.js"],
+        "testEnvironment": "node"
     }
 }