udpate latest codes

Author: Your Name

docs/Agents.md

@@ -106,19 +106,30 @@ spark git update -p ~/workspace -p ~/projects
 详细文档: [docs/usage/update.md](docs/usage/update.md)
 
 #### `spark git submodule`
-将当前目录下的 Git 仓库添加为子模块，无需重新克隆。
+将本地 Git 仓库添加为子模块，或将远程仓库克隆为子模块。
 
+**本地模式**：
 ```bash
 spark git submodule add                    # 添加当前目录下的仓库
 spark git submodule add -p /path/to/repos  # 添加指定目录下的仓库
+spark git submodule add ./spark-cli        # 将指定目录作为子模块添加
 ```
 
 | 选项 | 说明 |
 |------|------|
 | `-n, --name` | 子模块路径名称 (默认: 仓库名) |
 
+**智能检测行为**：
+
+| 场景 | 输出 |
+|------|------|
+| 目标已是 submodule（160000） | `Skipping <name>: already as submodule` |
+| 目标与父仓库 URL 相同（worktree） | `Skipping <name>: already as submodule` |
+| 目录存在但不是 submodule | `Skipping <name>: directory already exists (use 'git submodule add' manually)` |
+| 正常添加 | `Adding submodule: <name> (<url>)` |
+
 #### `spark git sync`
-同步当前仓库中所有子模块到最新版本。
+同步当前仓库中所有子模块到最新版本。包含 `git submodule update --init`，确保缺失的子模块也会被 clone。
 
 ```bash
 spark git sync ./my-repo

docs/spec/git.md

@@ -68,6 +68,15 @@ spark git submodule add [-p <path>]
 
 无参数。
 
+**智能检测行为**：
+
+| 场景 | 输出 |
+|------|------|
+| 目标已是 submodule（160000） | `Skipping <name>: already as submodule` |
+| 目标与父仓库 URL 相同（worktree） | `Skipping <name>: already as submodule` |
+| 目录存在但不是 submodule | `Skipping <name>: directory already exists (use 'git submodule add' manually)` |
+| 正常添加 | `Adding submodule: <name> (<url>)` |
+
 ### 远程模式
 
 ```
@@ -95,6 +104,11 @@ spark git sync [repo-path]
 |------|------|--------|------|------|
 | `repo-path` | string | `.` | 否 | 仓库路径 |
 
+**流程**：
+1. `git fetch --all` — 获取所有远程最新代码
+2. `git submodule update --init` — 初始化缺失的子模块（从 `.gitmodules` 中读取）
+3. `git submodule update --remote --merge` — 更新所有子模块到最新版本并合并
+
 ---
 
 ## spark git gitcode

docs/usage/git.md

@@ -44,13 +44,22 @@ spark git update -p ~/ws -p ~/projects        # 多个目录
 
 | 标志 | 简写 | 默认值 | 说明 |
 |------|------|--------|------|
-
+| `-p, --path` | | `.` | 包含 Git 仓库的目录路径 |
 
 ```bash
 spark git submodule add ./repos                       # 将本地文件夹中所有 GitHub 仓库添加为 submodule
-spark git submodule add https://github.com/user/repo  # 添加远程仓库
+spark git submodule add ./spark-cli                  # 将指定目录作为子模块添加
 ```
 
+**智能检测行为**：
+
+| 场景 | 输出 |
+|------|------|
+| 目标已是 submodule（160000） | `Skipping <name>: already as submodule` |
+| 目标与父仓库 URL 相同（worktree） | `Skipping <name>: already as submodule` |
+| 目录存在但不是 submodule | `Skipping <name>: directory already exists (use 'git submodule add' manually)` |
+| 正常添加 | `Adding submodule: <name> (<url>)` |
+
 ### 模式 2：添加远程仓库为子模块
 
 克隆远程 Git 仓库并将其添加为子模块。
@@ -83,6 +92,13 @@ spark git submodule add user/repo
 spark git sync ./my-repo                       # 同步指定仓库
 ```
 
+**流程**：
+1. `git fetch --all` — 获取所有远程最新代码
+2. `git submodule update --init` — 初始化缺失的子模块（从 `.gitmodules` 中读取）
+3. `git submodule update --remote --merge` — 更新所有子模块到最新版本并合并
+
+**注意**：`--init` 确保即使子模块目录在本地缺失，也会从远程 clone 下来。
+
 ---
 
 ## spark git gitcode