Merge branch '3.6.x'

CodeCasterX · CodeCasterX · commit 08376baf9913 · 2026-02-17T15:38:02.000+08:00
diff --git a/docker/sandbox/DEVELOPMENT.md b/docker/sandbox/DEVELOPMENT.md
@@ -19,9 +19,9 @@ Claude Code、Codex、OpenCode、Gemini CLI 都在各自的配置目录（`~/.cl
 
 | | 宿主机凭据存储 | 沙箱认证方式 | 首次使用 |
 |---|---|---|---|
-| **Codex** | 文件（`~/.codex/auth.json`） | 自动从宿主机预植入 `auth.json` | 无需登录，直接使用 |
-| **OpenCode** | 文件（`~/.local/share/opencode/auth.json`） | 自动从宿主机预植入 `auth.json` | 无需登录，直接使用 |
-| **Gemini CLI** | 文件（`~/.gemini/oauth_creds.json`） | 自动从宿主机预植入 `oauth_creds.json` + `settings.json` | 无需登录，直接使用 |
+| **Codex** | 文件（`~/.codex/auth.json`） | 实时挂载（live mount）宿主机 `auth.json` | 无需登录，宿主机刷新后自动生效 |
+| **OpenCode** | 文件（`~/.local/share/opencode/auth.json`） | 实时挂载（live mount）宿主机 `auth.json` | 无需登录，宿主机刷新后自动生效 |
+| **Gemini CLI** | 文件（`~/.gemini/oauth_creds.json`） | 实时挂载 `oauth_creds.json` + 预植入 `settings.json` | 无需登录，宿主机刷新后自动生效 |
 | **Claude Code** | macOS Keychain（`Claude Code-credentials`） | 容器内 OAuth 登录，凭据存入 `.credentials.json` | 需在容器内登录一次 |
 
 ### 为什么 Claude Code 不能预植入？
@@ -32,7 +32,11 @@ Claude Code 在 macOS 上将 OAuth token 存储在系统 Keychain 中，宿主
 
 ### Codex / OpenCode / Gemini CLI 为什么可以？
 
-Codex、OpenCode 和 Gemini CLI 始终使用文件存储凭据（分别为 `~/.codex/auth.json`、`~/.local/share/opencode/auth.json` 和 `~/.gemini/oauth_creds.json`），`sandbox create` 时自动将宿主机的凭据文件复制到沙箱配置目录，容器内可直接使用。Gemini CLI 还会额外预植入 `settings.json` 和 `google_accounts.json`，确保容器内的模型选项和用户设置与宿主机一致。
+Codex、OpenCode 和 Gemini CLI 始终使用文件存储凭据（分别为 `~/.codex/auth.json`、`~/.local/share/opencode/auth.json` 和 `~/.gemini/oauth_creds.json`）。这些认证文件通过 Docker bind mount（`hostLiveMounts`）直接从宿主机实时挂载到容器内，宿主机刷新 token 后容器自动生效，无需重建沙箱。
+
+> **为什么使用实时挂载而非复制？** OAuth token 通常有过期时间（如 OpenAI token 有效期约 7 天），一次性复制的 token 过期后需要手动重新同步。实时挂载使宿主机和容器始终共享同一份文件，彻底消除 token 过期问题。
+
+Gemini CLI 还会额外预植入（一次性复制）`settings.json` 和 `google_accounts.json`，确保容器内的模型选项和用户设置与宿主机一致。这些配置文件不含过期 token，无需实时同步。
 
 ## AI 工具注册表
 
@@ -52,9 +56,12 @@ AI 工具的安装与运行配置以 `src/tools.ts` 中的 `AI_TOOLS` 注册表
 | `containerMount` | `string` | 是 | 容器内挂载路径（绝对路径），如 `/home/devuser/.codex` |
 | `versionCmd` | `string` | 是 | 验证安装的命令，通过 `bash -lc` 执行 |
 | `noAuthHint` | `string` | 是 | 未预植入认证时的提示信息 |
-| `hostAuthFile` | `string` | 否 | 宿主机认证文件路径，与 `authFileName` 成对使用 |
+| `hostAuthFile` | `string` | 否 | 宿主机认证文件路径，与 `authFileName` 成对使用（一次性复制） |
 | `authFileName` | `string` | 否 | 沙箱内认证文件名（相对于 `sandboxBase/{branch}/`） |
 | `hostPreSeedFiles` | `Array<{hostPath, sandboxName}>` | 否 | 额外需要预植入的宿主机文件（如设置、账户信息） |
+| `hostPreSeedDirs` | `Array<{hostDir, sandboxSubdir}>` | 否 | 递归复制宿主机目录到沙箱（如插件目录） |
+| `pathRewriteFiles` | `string[]` | 否 | 预植入后需要路径重写的文件（宿主机路径 → 容器路径） |
+| `hostLiveMounts` | `Array<{hostPath, containerSubpath}>` | 否 | 实时挂载宿主机文件到容器（双向同步，用于认证 token） |
 | `postSetupCmds` | `string[]` | 否 | 容器启动后执行的 shell 命令（如创建符号链接） |
 | `envVars` | `Record<string, string>` | 否 | 注入容器的额外环境变量 |
 
@@ -68,15 +75,19 @@ AI 工具的安装与运行配置以 `src/tools.ts` 中的 `AI_TOOLS` 注册表
 
 ```
 1. 创建沙箱配置目录           sandboxBase/{branch}/
-2. 预植入认证文件             hostAuthFile → sandboxBase/{branch}/authFileName
+2. 预植入认证文件（一次性）     hostAuthFile → sandboxBase/{branch}/authFileName
 3. 预植入额外配置文件          hostPreSeedFiles[].hostPath → sandboxBase/{branch}/sandboxName
-4. 挂载配置目录到容器          sandboxBase/{branch}/ → containerMount
-5. 注入环境变量               envVars → docker run -e
-6. 容器启动后执行命令          postSetupCmds → docker exec bash -lc
-7. 验证安装                  versionCmd → docker exec bash -lc
+4. 递归复制宿主机目录          hostPreSeedDirs[].hostDir → sandboxBase/{branch}/sandboxSubdir
+5. 路径重写                  pathRewriteFiles[] 中的宿主机路径 → 容器路径
+6. 挂载配置目录到容器          sandboxBase/{branch}/ → containerMount
+7. 实时挂载认证文件            hostLiveMounts[].hostPath → containerMount/containerSubpath
+8. 注入环境变量               envVars → docker run -e
+9. 容器启动后执行命令          postSetupCmds → docker exec bash -lc
+10. 验证安装                 versionCmd → docker exec bash -lc
 ```
 
-所有预植入操作遵循"仅首次"策略：宿主机文件存在且沙箱中不存在时才复制，不会覆盖已有配置。
+- **一次性操作**（步骤 2–5）遵循"仅首次"策略：宿主机文件存在且沙箱中不存在时才复制，不会覆盖已有配置。
+- **实时挂载**（步骤 7）通过 Docker bind mount 将宿主机文件直接映射到容器内，文件始终保持同步，无需重建沙箱。适用于会过期的认证 token。
 
 ## 添加新工具
 
@@ -93,9 +104,12 @@ AI 工具的安装与运行配置以 `src/tools.ts` 中的 `AI_TOOLS` 注册表
   sandboxBase: path.join(HOME, '.gemini-sandboxes'),
   containerMount: '/home/devuser/.gemini',
   versionCmd: 'gemini --version',
-  hostAuthFile: path.join(HOME, '.gemini', 'oauth_creds.json'),
-  authFileName: 'oauth_creds.json',
   noAuthHint: '首次使用需在容器内运行 gemini 完成认证。',
+  // 认证文件实时挂载（token 会过期，需与宿主机保持同步）
+  hostLiveMounts: [
+    { hostPath: path.join(HOME, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' },
+  ],
+  // 配置文件一次性预植入（不含过期 token，无需实时同步）
   hostPreSeedFiles: [
     { hostPath: path.join(HOME, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
     { hostPath: path.join(HOME, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' },
diff --git a/docker/sandbox/README.md b/docker/sandbox/README.md
@@ -91,16 +91,16 @@ sandbox exec feat-xxx
 ```bash
 # 进入容器后，直接使用
 claude              # Claude Code（首次需容器内 OAuth 登录）
-codex               # OpenAI Codex（自动预植入宿主机凭据）
-opencode            # OpenCode（自动预植入宿主机凭据）
-gemini              # Gemini CLI（自动预植入宿主机凭据）
+codex               # OpenAI Codex（实时同步宿主机凭据）
+opencode            # OpenCode（实时同步宿主机凭据）
+gemini              # Gemini CLI（实时同步宿主机凭据）
 
 # 也可以直接开发
 mvn clean install
 python3 script.py
 ```
 
-> **认证差异**：Codex、OpenCode、Gemini CLI 创建沙箱时会自动从宿主机预植入认证凭据，可直接使用；Claude Code 首次需要在容器内完成一次 OAuth 登录（之后免登录）。详见[认证机制说明](#ai-工具认证机制)。
+> **认证差异**：Codex、OpenCode、Gemini CLI 的认证文件通过实时挂载（live mount）与宿主机双向同步，宿主机刷新 token 后容器自动生效；Claude Code 首次需要在容器内完成一次 OAuth 登录（之后免登录）。详见[认证机制说明](#ai-工具认证机制)。
 
 ## 多容器并发工作流
 
@@ -142,6 +142,188 @@ exit
 docker stop fit-dev-feat-xxx
 ```
 
+## 命令行模式（非交互式）
+
+除了打开 TUI 界面，每个 AI 工具都支持直接在命令行传入 prompt 并获取输出，适合脚本自动化、快速提问和管道组合。每个工具还支持会话管理，可以在命令行实现多轮对话。
+
+### Claude Code
+
+```bash
+# 单次提问（-p = print mode，不打开 TUI）
+claude -p "解释一下这个项目的架构"
+
+# 管道输入
+cat src/main/java/App.java | claude -p "审查这段代码的安全性"
+
+# 指定输出格式（text / json / stream-json）
+claude -p "列出所有 TODO" --output-format json
+
+# 指定模型
+claude -p --model opus "设计一个缓存方案"
+
+# 限制轮次和预算
+claude -p --max-turns 3 --max-budget-usd 1.00 "重构数据库模块"
+
+# 跳过所有权限确认（CI/脚本场景）
+claude -p --dangerously-skip-permissions "运行所有测试并汇报结果"
+
+# ── 多轮对话（会话管理）──
+
+# 预先生成 session ID，从第 1 轮起就使用（推荐）
+SID=$(uuidgen)
+
+# 第 1 轮：指定 session ID 开启对话
+claude -p --session-id "$SID" "分析认证模块的架构"
+
+# 第 2 轮：恢复同一个会话继续对话
+claude -p --resume "$SID" "重构登录函数"
+
+# 第 3 轮：继续同一个会话
+claude -p --resume "$SID" "为重构后的代码补充单元测试"
+
+# 快捷方式：继续当前目录下最近一次对话（无需 session ID）
+claude -p -c "为刚才的修改补充单元测试"
+
+# 从已有会话分叉出新会话（不影响原会话）
+claude -p --resume "$SID" --fork-session "尝试另一种实现方案"
+```
+
+### Codex
+
+```bash
+# 单次提问（exec 子命令 = 非交互模式）
+codex exec "为 User 类生成单元测试"
+
+# 管道输入
+echo "解释这个报错信息" | codex exec -
+
+# JSON 事件流输出
+codex exec --json "列出所有 API 端点"
+
+# 指定模型
+codex exec -m o4-mini "优化这个排序算法"
+
+# 全自动模式（无需确认，可写工作区）
+codex exec --full-auto "给所有 API 路由添加错误处理"
+
+# 将最终结果写入文件
+codex exec -o result.txt "分析项目依赖关系"
+
+# ── 多轮对话（会话管理）──
+# Codex 不支持预指定 thread ID，需从首轮 JSON 输出获取
+
+# 第 1 轮：启动会话，通过 JSON 事件流获取 thread_id
+TID=$(codex exec --json "分析数据库模块" 2>/dev/null \
+  | jq -r 'select(.type=="thread.started") | .thread_id')
+
+# 第 2 轮：通过 thread_id 恢复会话（注意 resume 是 exec 的子命令）
+codex exec resume "$TID" "添加连接池"
+
+# 第 3 轮：继续同一个会话
+codex exec resume "$TID" "补充单元测试"
+
+# 快捷方式：恢复最近一次会话
+codex exec resume --last "继续上次的任务"
+```
+
+### OpenCode
+
+```bash
+# 单次提问（run 子命令 = 非交互模式）
+opencode run "解释 JavaScript 闭包的工作原理"
+
+# 指定模型（格式：provider/model-name）
+opencode run -m anthropic/claude-sonnet-4-20250514 "审查这段代码"
+
+# 指定 Agent
+opencode run --agent plan "分析项目结构并给出改进建议"
+
+# JSON 输出
+opencode run --format json "列出所有 API 端点"
+
+# 附加文件到 prompt
+opencode run --file src/auth.ts "审查这个文件的安全性"
+
+# ── 多轮对话（会话管理）──
+# OpenCode 不支持预指定 session ID，需从首轮 JSON 输出获取
+
+# 第 1 轮：启动会话，通过 JSON 输出获取 sessionID
+SID=$(opencode run --format json "设计认证模块" | jq -r '.sessionID')
+
+# 第 2 轮：通过 session ID 恢复会话
+opencode run -s "$SID" "添加 JWT 校验"
+
+# 第 3 轮：继续同一个会话
+opencode run -s "$SID" "补充单元测试"
+
+# 快捷方式：继续最近一次对话（无需 session ID）
+opencode run -c "为刚才的修改补充单元测试"
+
+# 查看历史会话列表
+opencode session list
+opencode session list -n 10   # 只显示最近 10 个
+
+# 从已有会话分叉
+opencode run -s "$SID" --fork "尝试另一种实现方案"
+```
+
+### Gemini CLI
+
+```bash
+# 单次提问（-p = prompt 模式，不打开 TUI）
+gemini -p "解释一下 Docker 的工作原理"
+
+# 管道输入
+cat src/auth.py | gemini -p "审查这段代码的安全性"
+
+# 指定输出格式（text / json / stream-json）
+gemini -p "列出所有 TODO" --output-format json
+
+# 指定模型
+gemini -p -m gemini-2.5-flash "快速解释这段代码"
+
+# 自动确认所有工具调用
+gemini -p --yolo "运行测试并汇报结果"
+
+# 将项目所有文件纳入上下文
+gemini -p --all-files "分析这个项目的架构"
+
+# ── 多轮对话（会话管理）──
+# Gemini CLI 不支持预指定 session ID，需从首轮 JSON 输出中提取。
+
+# 第 1 轮：启动会话，通过 JSON 输出获取 session_id
+SID=$(gemini --output-format json -p "分析项目的整体架构" | jq -r '.session_id')
+
+# 第 2 轮：通过 session_id 恢复会话
+gemini --resume "$SID" "针对刚才的分析，重构认证模块"
+
+# 第 3 轮：继续同一个会话
+gemini --resume "$SID" "补充单元测试"
+
+# 快捷方式：恢复最近一次会话（--resume 不带参数，仅适合非并发场景）
+gemini --resume "继续上次的对话"
+
+# 查看当前项目所有会话
+gemini --list-sessions
+```
+
+> **注意**：Gemini CLI 的会话按项目（工作目录）隔离，切换目录后 `--list-sessions` 显示的是不同项目的会话。`-s` 是 `--sandbox` 的缩写（安全沙箱），不是会话管理，会话管理使用 `-r` / `--resume`。
+
+### 快速对比
+
+| 功能 | Claude Code | Codex | OpenCode | Gemini CLI |
+|------|------------|-------|----------|------------|
+| 非交互标志 | `-p` | `exec` 子命令 | `run` 子命令 | `-p` |
+| 管道输入 | `cat f \| claude -p` | `echo x \| codex exec -` | `--file` 附加文件 | `cat f \| gemini -p` |
+| JSON 输出 | `--output-format json` | `--json` | `--format json` | `--output-format json` |
+| 指定模型 | `--model opus` | `-m o4-mini` | `-m provider/model` | `-m gemini-2.5-flash` |
+| 跳过确认 | `--dangerously-skip-permissions` | `--full-auto` | — | `--yolo` |
+| 预指定会话 ID | `--session-id <UUID>` | — | — | — |
+| 恢复指定会话 | `--resume <ID>` | `exec resume <ID>` | `-s <ID>` | `--resume <ID>` |
+| 继续最近会话 | `-c` | `exec resume --last` | `-c` | `--resume`（无参数） |
+| 查看会话列表 | — | — | `session list` | `--list-sessions` |
+| 分叉会话 | `--fork-session` | — | `--fork` | — |
+
 ## 沙箱管理
 
 ```bash
@@ -203,7 +385,7 @@ sandbox vm start --cpu 6 --memory 8  # 自定义资源启动
 - 路径简短清晰
 - 不在项目目录内，天然被 `.gitignore` 排除
 
-每个沙箱拥有独立的 AI 工具配置目录（如 `~/.codex-sandboxes/{branch}/`），避免并发冲突和会话污染。Codex、OpenCode、Gemini CLI 创建沙箱时自动从宿主机预植入认证凭据；Claude Code 首次需在容器内 OAuth 登录一次。
+每个沙箱拥有独立的 AI 工具配置目录（如 `~/.codex-sandboxes/{branch}/`），避免并发冲突和会话污染。Codex、OpenCode、Gemini CLI 的认证文件通过实时挂载（live mount）与宿主机双向同步，宿主机刷新 token 后容器自动生效；Claude Code 首次需在容器内 OAuth 登录一次。
 
 > 详细的认证机制说明、注册表字段参考和添加新工具指南请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。
 
diff --git a/docker/sandbox/src/commands/create.ts b/docker/sandbox/src/commands/create.ts
@@ -174,6 +174,13 @@ export async function create(branch: string, base: string | undefined, opts: Cre
         const toolVolumes = resolvedTools.flatMap(({ tool, dir }) =>
           ['-v', `${dir}:${tool.containerMount}`]
         );
+        // Live-mount auth files directly from host (bidirectional sync, always fresh)
+        const liveMountVolumes = resolvedTools.flatMap(({ tool }) =>
+          (tool.hostLiveMounts ?? [])
+            .filter(({ hostPath }) => fs.existsSync(hostPath))
+            .flatMap(({ hostPath, containerSubpath }) =>
+              ['-v', `${hostPath}:${path.join(tool.containerMount, containerSubpath)}`])
+        );
 
         run('docker', [
           'run', '-d',
@@ -185,6 +192,7 @@ export async function create(branch: string, base: string | undefined, opts: Cre
           '-v', `${MAIN_REPO}/.git:${MAIN_REPO}/.git`,
           '-v', `${process.env.HOME}/.ssh:/home/devuser/.ssh:ro`,
           ...toolVolumes,
+          ...liveMountVolumes,
           ...envArgs,
           '-w', '/workspace',
           IMAGE_NAME,
@@ -242,8 +250,12 @@ export async function create(branch: string, base: string | undefined, opts: Cre
 
   // Tool credential hints
   const toolHints = resolvedTools.map(({ tool, dir }) => {
-    const hasAuth = tool.authFileName && fs.existsSync(path.join(dir, tool.authFileName));
-    const hint = hasAuth ? '已从宿主机预植入认证凭据，可直接使用。' : tool.noAuthHint;
+    const hasLiveAuth = (tool.hostLiveMounts ?? []).some(({ hostPath }) => fs.existsSync(hostPath));
+    const hasCopiedAuth = tool.authFileName && fs.existsSync(path.join(dir, tool.authFileName));
+    const hasAuth = hasLiveAuth || hasCopiedAuth;
+    const hint = hasAuth
+      ? (hasLiveAuth ? '已与宿主机认证凭据实时同步，宿主机刷新后容器自动生效。' : '已从宿主机预植入认证凭据，可直接使用。')
+      : tool.noAuthHint;
     return `${pc.cyan(`${tool.name}：`)}\n  ${hint}\n  凭据持久化：${dir}/`;
   }).join('\n\n');
 
diff --git a/docker/sandbox/src/tools.ts b/docker/sandbox/src/tools.ts
@@ -39,6 +39,12 @@ export interface AiTool {
    * Rewrites: HOST_HOME → container home, HOST_PROJECT → /workspace.
    */
   pathRewriteFiles?: string[];
+  /**
+   * Host files to live-mount into container (bidirectional, always in sync with host).
+   * Use for auth tokens that expire and need continuous refresh.
+   * Overlays the sandbox directory mount — file-level bind takes precedence.
+   */
+  hostLiveMounts?: Array<{ hostPath: string; containerSubpath: string }>;
 }
 
 /** Validate descriptor consistency at startup — fail fast on misconfiguration. */
@@ -89,9 +95,10 @@ export const AI_TOOLS: readonly Readonly<AiTool>[] = [
     sandboxBase: path.join(HOME, '.codex-sandboxes'),
     containerMount: '/home/devuser/.codex',
     versionCmd: 'codex --version',
-    hostAuthFile: path.join(HOME, '.codex', 'auth.json'),
-    authFileName: 'auth.json',
     noAuthHint: '首次使用需在容器内运行 codex，按 Esc 选择 Device Code 方式登录。',
+    hostLiveMounts: [
+      { hostPath: path.join(HOME, '.codex', 'auth.json'), containerSubpath: 'auth.json' },
+    ],
     postSetupCmds: [
       'test -d /workspace/.codex/commands && ln -sfn /workspace/.codex/commands /home/devuser/.codex/prompts || true',
     ],
@@ -102,19 +109,21 @@ export const AI_TOOLS: readonly Readonly<AiTool>[] = [
     sandboxBase: path.join(HOME, '.opencode-sandboxes'),
     containerMount: '/home/devuser/.local/share/opencode',
     versionCmd: 'opencode version',
-    hostAuthFile: path.join(HOME, '.local', 'share', 'opencode', 'auth.json'),
-    authFileName: 'auth.json',
     noAuthHint: '首次使用需在容器内配置认证凭据。',
+    hostLiveMounts: [
+      { hostPath: path.join(HOME, '.local', 'share', 'opencode', 'auth.json'), containerSubpath: 'auth.json' },
+    ],
   },
   {
     name: 'Gemini CLI',
     npmPackage: '@google/gemini-cli',
     sandboxBase: path.join(HOME, '.gemini-sandboxes'),
     containerMount: '/home/devuser/.gemini',
     versionCmd: 'gemini --version',
-    hostAuthFile: path.join(HOME, '.gemini', 'oauth_creds.json'),
-    authFileName: 'oauth_creds.json',
     noAuthHint: '首次使用需在容器内运行 gemini 完成认证（支持 Google 登录、API Key、Vertex AI）。',
+    hostLiveMounts: [
+      { hostPath: path.join(HOME, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' },
+    ],
     hostPreSeedFiles: [
       { hostPath: path.join(HOME, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
       { hostPath: path.join(HOME, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' },
