update docs

Author: qdriven

AGENTS.md

@@ -12,6 +12,9 @@
 4. **Git 用户配置** - 配置仓库的 Git 用户信息
 5. **任务管理** - 任务分发、同步和 GitHub 仓库创建
 6. **Gitcode 远程管理** - 为仓库添加 Gitcode 远程地址
+7. **系统工具** - DNS 缓存刷新、包管理器镜像源切换、项目目录清理
+8. **文档管理** - 初始化文档结构和 docmd 站点配置
+9. **进程诊断** - 检查进程或端口为何在运行（witr）
 
 ## 技术栈
 
@@ -94,6 +97,7 @@ spark git url          # 获取仓库 URL
 spark git init         # 初始化仓库并创建 GitHub 远程
 spark git batch-clone  # 克隆用户/组织所有仓库
 spark git issues       # 从 Markdown 文档/任务创建 GitHub Issue
+spark git push-all     # 提交并推送所有仓库的更改
 ```
 
 #### `spark git update`
@@ -251,6 +255,18 @@ spark git update-org-status variableway --skip-push        # 跳过 git push
 - 只更新指定的 section，保留其他所有内容不变
 - 自动克隆、修改、提交并推送更改
 
+#### `spark git push-all`
+扫描指定目录中的所有 Git 仓库，自动提交并推送所有更改。
+
+```bash
+spark git push-all                           # 推送所有更改
+spark git push-all -p ~/workspace            # 指定目录
+```
+
+- 跳过非 GitHub 仓库和无更改的仓库
+- 自动 `git add -A` → `git commit` → `git push`
+- 遇到冲突时提示并继续处理下一个仓库
+
 ### 脚本管理
 
 #### `spark script`
@@ -364,6 +380,88 @@ tasks/
 
 详细文档: [docs/usage/task.md](docs/usage/task.md)
 
+### 系统工具
+
+#### `spark magic`
+系统实用工具命令组。
+
+```bash
+spark magic flush-dns              # 刷新 DNS 缓存
+spark magic clean                  # 清理 node_modules 和 .venv
+spark magic pip list               # 列出 pip 镜像源
+spark magic pip use tsinghua       # 切换 pip 镜像源
+spark magic pip current            # 查看当前 pip 源
+spark magic go list                # 列出 Go module proxy
+spark magic go use goproxy         # 切换 Go proxy
+spark magic go current             # 查看当前 Go proxy
+spark magic node list              # 列出 npm registry
+spark magic node use taobao        # 切换 npm registry
+spark magic node current           # 查看当前 npm registry
+```
+
+#### `spark magic flush-dns`
+刷新系统 DNS 缓存，支持 macOS、Windows、Linux。
+
+#### `spark magic clean`
+递归清理项目目录中的 `node_modules` 和 `.venv`。
+
+```bash
+spark magic clean                  # 清理两者
+spark magic clean -m node          # 只清理 node_modules
+spark magic clean -m python        # 只清理 .venv
+```
+
+| 选项 | 说明 |
+|------|------|
+| `-m, --mode` | 清理模式：`node`、`python`（默认两者） |
+
+### 文档管理
+
+#### `spark docs`
+文档管理命令组。
+
+```bash
+spark docs init                    # 创建文档目录结构
+spark docs site                    # 初始化 docmd 站点配置
+```
+
+#### `spark docs init`
+创建标准文档目录结构（`analysis/`、`features/`、`index.md`、`quick-start/`、`README.md`、`spec/`、`tips/`、`usage/`）。
+
+#### `spark docs site`
+初始化 docmd 文档站点配置，自动从 git remote 检测项目名称和 GitHub Pages URL，生成 `docmd.config.js`。
+
+### 进程诊断
+
+#### `spark witr`
+进程诊断工具（Why Is This Running），检查进程或端口为何在运行。
+
+```bash
+spark witr nginx                   # 按名称检查进程
+spark witr --pid 1234              # 按 PID 检查
+spark witr --port 8080             # 按端口查找进程
+spark witr --file /path/to/lock    # 查找占用文件的进程
+spark witr --container redis       # 检查容器
+spark witr nginx --tree            # 显示进程树
+spark witr nginx --env             # 显示环境变量
+spark witr nginx --json            # JSON 输出
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--pid` | 按 PID 查找（可多次使用） |
+| `--port` / `-o` | 按端口查找（可多次使用） |
+| `--file` / `-f` | 按文件查找（可多次使用） |
+| `--container` / `-c` | 按容器查找（可多次使用） |
+| `--tree` / `-t` | 显示进程祖先树 |
+| `--env` | 显示环境变量 |
+| `--json` | JSON 格式输出 |
+| `--short` / `-s` | 简短输出 |
+| `--warnings` | 仅显示警告 |
+| `--verbose` | 扩展信息 |
+| `--exact` / `-x` | 精确匹配 |
+| `--no-color` | 禁用颜色 |
+
 ## Spark Skills
 
 个人 Skill 集合仓库，用于增强 spark-cli 的功能。

docs/README.md

@@ -79,6 +79,7 @@ go test ./internal/git/... -v -run TestFunctionName
 | `spark git batch-clone <account> [--ssh] [--include] [--exclude] [-o <dir>]` | Clone all repos from GitHub org/user |
 | `spark git update-org-status <org> [--dry-run] [--update-dot-github] [--section <name>]` | Update org README with repo list |
 | `spark git issues [-r <owner/repo>] (-d <dir> \| -f <file>) [--dry-run] [-l <labels>]` | Create GitHub issues from markdown docs/tasks |
+| `spark git push-all [-p <path>]` | Commit and push all changes in repositories |
 
 ---
 
@@ -103,6 +104,7 @@ Flags: `--task-dir`, `--owner`, `--work-dir`, `--tui`
 | Command | Description |
 |---------|-------------|
 | `spark magic flush-dns` | Flush DNS cache (macOS/Windows/Linux) |
+| `spark magic clean [-m node\|python]` | Clean node_modules and .venv directories |
 
 #### Mirror Switching (list / use / current)
 
@@ -123,6 +125,20 @@ Flags: `--task-dir`, `--owner`, `--work-dir`, `--tui`
 
 Scripts sourced from `~/.spark.yaml` (`spark.scripts`) and `scripts/` directory.
 
+---
+
+### spark witr — Process Inspector
+
+| Command | Description |
+|---------|-------------|
+| `spark witr [process name...]` | Inspect why a process or port is running |
+| `spark witr --pid <pid>` | Look up by PID |
+| `spark witr --port <port>` | Find process by port |
+| `spark witr --file <path>` | Find process holding file open |
+| `spark witr --container <name>` | Inspect container |
+
+Flags: `--tree`, `--env`, `--json`, `--short`, `--warnings`, `--verbose`, `--exact`, `--no-color`
+
 ## Configuration
 
 Config file: `~/.spark.yaml`

docs/features/git.md

@@ -101,6 +101,17 @@ spark git issues -f tasks/issues/task-bug-fix.md -r variableway/spark-cli
 spark git issues -f tasks/issues/task-bug-fix.md --dry-run
 ```
 
+### 批量推送更改
+
+扫描所有 GitHub 仓库，自动提交并推送未提交的更改。
+
+```bash
+spark git push-all -p ~/workspace
+```
+
+- 跳过非 GitHub 仓库和无更改的仓库
+- 遇到错误继续处理下一个仓库
+
 ## 使用参数
 
 | 参数 | 说明 |

docs/features/magic.md

@@ -74,6 +74,16 @@ spark magic node current    # 查看当前 registry
 | `huawei` | 华为云 |
 | `ustc` | 中国科技大学 |
 
+### 项目目录清理
+
+递归清理 `node_modules` 和 `.venv` 目录，释放磁盘空间。
+
+```bash
+spark magic clean           # 清理两者
+spark magic clean -m node   # 只清理 node_modules
+spark magic clean -m python # 只清理 .venv
+```
+
 ## 使用参数
 
 三个镜像切换命令（pip/go/node）共享相同的子命令结构：

docs/index.md

@@ -84,6 +84,7 @@ go test ./internal/git/... -v -run TestFunctionName
 | `spark git batch-clone <account> [--ssh] [--include] [--exclude] [-o <dir>]` | Clone all repos from GitHub org/user |
 | `spark git update-org-status <org> [--dry-run] [--update-dot-github] [--section <name>]` | Update org README with repo list |
 | `spark git issues [-r <owner/repo>] (-d <dir> \| -f <file>) [--dry-run] [-l <labels>]` | Create GitHub issues from markdown docs/tasks |
+| `spark git push-all [-p <path>]` | Commit and push all changes in repositories |
 
 ---
 
@@ -108,6 +109,7 @@ Flags: `--task-dir`, `--owner`, `--work-dir`, `--tui`
 | Command | Description |
 |---------|-------------|
 | `spark magic flush-dns` | Flush DNS cache (macOS/Windows/Linux) |
+| `spark magic clean [-m node\|python]` | Clean node_modules and .venv directories |
 
 #### Mirror Switching (list / use / current)
 
@@ -128,6 +130,20 @@ Flags: `--task-dir`, `--owner`, `--work-dir`, `--tui`
 
 Scripts sourced from `~/.spark.yaml` (`spark.scripts`) and `scripts/` directory.
 
+---
+
+### spark witr — Process Inspector
+
+| Command | Description |
+|---------|-------------|
+| `spark witr [process name...]` | Inspect why a process or port is running |
+| `spark witr --pid <pid>` | Look up by PID |
+| `spark witr --port <port>` | Find process by port |
+| `spark witr --file <path>` | Find process holding file open |
+| `spark witr --container <name>` | Inspect container |
+
+Flags: `--tree`, `--env`, `--json`, `--short`, `--warnings`, `--verbose`, `--exact`, `--no-color`
+
 ## Configuration
 
 Config file: `~/.spark.yaml`

docs/quick-start/getting-started.md

@@ -32,6 +32,7 @@ spark git update -p ~/workspace               # 更新所有仓库
 spark git init --owner variableway            # 初始化仓库并创建 GitHub 远程
 spark git submodule add -p /path/to/repos          # 添加仓库为子模块
 spark git batch-clone variableway -o ./repos  # 克隆组织仓库
+spark git push-all -p ~/workspace             # 推送所有仓库的更改
 ```
 
 ### 镜像源切换
@@ -40,6 +41,7 @@ spark git batch-clone variableway -o ./repos  # 克隆组织仓库
 spark magic pip use tsinghua                  # Python → 清华源
 spark magic go use goproxy                    # Go → goproxy.cn
 spark magic node use taobao                   # Node → 淘宝源
+spark magic clean                             # 清理 node_modules 和 .venv
 ```
 
 ### 任务管理
@@ -59,6 +61,14 @@ spark docs site                               # 初始化 docmd 站点
 docmd dev                                     # 本地预览文档
 ```
 
+### 进程诊断
+
+```bash
+spark witr nginx                              # 检查 nginx 进程
+spark witr --port 8080                        # 查找占用 8080 端口的进程
+spark witr --pid 1234                         # 按 PID 检查进程
+```
+
 ## 下一步
 
 - [完整使用指南](../usage/usage.md)

docs/spec/git.md

@@ -258,3 +258,25 @@ spark git update-org-status <org-name-or-url> [--dry-run] [--update-dot-github]
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `org-name-or-url` | string | 是 | 组织名或 URL |
+
+---
+
+## spark git push-all
+
+扫描目录中的所有 Git 仓库，自动提交并推送所有更改。
+
+```
+spark git push-all [-p <path>]
+```
+
+| 标志 | 类型 | 默认值 | 必填 | 说明 |
+|------|------|--------|------|------|
+| `-p, --path` | stringSlice | `["."]` | 否 | 包含 Git 仓库的目录路径 |
+
+无参数。
+
+**行为**：
+- 跳过非 GitHub 仓库
+- 跳过无更改的仓库
+- 自动 `git add -A` → `git commit` → `git push`
+- 遇到错误打印提示并继续下一个仓库

docs/spec/magic.md

@@ -141,3 +141,24 @@ spark magic node current
 ```
 
 无标志，无参数。
+
+---
+
+## spark magic clean
+
+递归清理项目目录中的 `node_modules` 和 `.venv`。
+
+```
+spark magic clean [-m <mode>]
+```
+
+| 标志 | 类型 | 默认值 | 必填 | 说明 |
+|------|------|--------|------|------|
+| `-m, --mode` | string | `""` | 否 | 清理模式：`node`、`python`（默认两者） |
+
+无参数。
+
+**行为**：
+- 扫描 `--path` 指定的目录（默认当前目录）
+- 自动跳过 `.git` 目录
+- 列出所有被清理的目录

docs/usage/git.md

@@ -19,6 +19,7 @@ spark git url [repo-path]                     # 查看远程 URL
 spark git batch-clone <account> [-o <dir>]    # 克隆用户/组织所有仓库
 spark git update-org-status <org> [--dry-run] # 更新组织 README
 spark git issues [-r <owner/repo>] (-d <dir> | -f <file>) # 从文档/任务创建 Issue
+spark git push-all                            # 提交并推送所有仓库的更改
 ```
 
 ---
@@ -69,7 +70,7 @@ spark git submodule add ./spark-cli                  # 将指定目录作为子
 
 | 标志 | 简写 | 默认值 | 说明 |
 |------|------|--------|------|
-| `-n, --name` | string | repo 名 | 否 | 子模块路径名称（远程模式） |
+| `-n, --name` | string | repo 名 | 子模块路径名称（远程模式） |
 
 ```bash
 # 添加远程仓库（使用默认路径名）
@@ -315,6 +316,27 @@ spark git issues -f tasks/issues/task-bug-fix.md -r variableway/spark-cli
 spark git issues -f tasks/issues/task-bug-fix.md --dry-run
 ```
 
+## spark git push-all
+
+扫描指定目录中的所有 Git 仓库，自动提交并推送所有更改。
+
+| 标志 | 默认值 | 说明 |
+|------|--------|------|
+| `-p, --path` | `.` | 包含 Git 仓库的目录路径（可多次指定） |
+
+```bash
+spark git push-all                            # 推送所有仓库的更改
+spark git push-all -p ~/workspace             # 指定目录
+```
+
+**行为**：
+- 跳过非 GitHub 仓库
+- 跳过无更改的仓库
+- 自动 `git add -A` → `git commit` → `git push`
+- 遇到冲突时提示并继续处理下一个仓库
+
+---
+
 ## 相关命令
 
 - [任务管理](./task.md)

docs/usage/magic.md

@@ -6,6 +6,7 @@
 
 ```bash
 spark magic flush-dns                         # 刷新 DNS 缓存
+spark magic clean [-m node|python]            # 清理 node_modules 和 .venv
 
 # 镜像源切换（pip / go / node 通用子命令）
 spark magic <pip|go|node> list                # 列出可用镜像
@@ -30,6 +31,27 @@ spark magic flush-dns
 
 ---
 
+## spark magic clean
+
+递归清理项目目录中的 `node_modules` 和 `.venv` 目录。
+
+```bash
+spark magic clean                             # 清理两者
+spark magic clean -m node                     # 只清理 node_modules
+spark magic clean -m python                   # 只清理 .venv
+```
+
+| 标志 | 简写 | 默认值 | 说明 |
+|------|------|--------|------|
+| `-m, --mode` | | | 清理模式：`node`、`python`（默认两者） |
+
+**行为**：
+- 扫描 `--path` 指定的目录（默认当前目录）
+- 自动跳过 `.git` 目录
+- 列出所有被清理的目录
+
+---
+
 ## spark magic pip
 
 管理 Python pip 镜像源。