chore: initialize qiming workspace repository

qimingclaw/crates/agent-electron-client/docs/sandbox/TROUBLESHOOTING.md

@@ -0,0 +1,451 @@
+# 沙箱故障排查指南
+
+> **版本**: 1.0.0  
+> **更新**: 2026-03-22
+
+---
+
+## 1. Docker 相关问题
+
+### 1.1 Docker 不可用
+
+**症状：** `SandboxError: SANDBOX_UNAVAILABLE`
+
+**排查步骤：**
+
+```bash
+# 1. 检查 Docker 是否安装
+docker --version
+
+# 2. 检查 Docker 服务状态
+# macOS
+docker status
+# Linux
+sudo systemctl status docker
+
+# 3. 检查 Docker 权限
+docker ps
+```
+
+**解决方案：**
+
+| 平台 | 命令 |
+|------|------|
+| macOS | 安装 Docker Desktop 并启动 |
+| Linux | `sudo systemctl start docker` |
+| Windows | 安装 Docker Desktop 并启用 WSL2 |
+
+---
+
+### 1.2 容器启动失败
+
+**症状：** `SandboxError: WORKSPACE_EXISTS` 或容器无法创建
+
+**排查步骤：**
+
+```bash
+# 1. 检查容器列表
+docker ps -a
+
+# 2. 检查 Docker 日志
+docker logs <container-id>
+
+# 3. 检查磁盘空间
+docker system df
+```
+
+**解决方案：**
+
+```bash
+# 清理未使用的容器和镜像
+docker system prune -a
+
+# 增加 Docker 磁盘配额（Docker Desktop -> Settings -> Disk）
+```
+
+---
+
+### 1.3 容器内命令执行失败
+
+**症状：** `SandboxError: EXECUTION_FAILED`
+
+**排查步骤：**
+
+```bash
+# 1. 检查容器是否运行
+docker ps | grep <container-id>
+
+# 2. 进入容器调试
+docker exec -it <container-id> /bin/sh
+
+# 3. 检查容器资源
+docker stats <container-id>
+```
+
+---
+
+## 2. Windows WSL 相关问题
+
+### 2.1 WSL 未安装
+
+**症状：** `SandboxError: SANDBOX_UNAVAILABLE` (Windows)
+
+**排查步骤：**
+
+```powershell
+# 检查 WSL 状态
+wsl --status
+
+# 列出已安装的发行版
+wsl --list --verbose
+```
+
+**解决方案：**
+
+```powershell
+# 安装 WSL
+wsl --install -d Ubuntu-22.04
+
+# 重启后检查
+wsl --set-default Ubuntu-22.04
+```
+
+---
+
+### 2.2 WSL 发行版启动失败
+
+**症状：** `SandboxError: WORKSPACE_EXISTS`
+
+**排查步骤：**
+
+```powershell
+# 关闭所有 WSL 实例
+wsl --shutdown
+
+# 检查发行版状态
+wsl --list --verbose
+```
+
+---
+
+## 3. Linux Firejail 相关问题
+
+### 3.1 Firejail 未安装
+
+**症状：** `SandboxError: SANDBOX_UNAVAILABLE` (Linux)
+
+**排查步骤：**
+
+```bash
+# 检查 Firejail
+firejail --version
+
+# 安装 Firejail
+# Ubuntu/Debian
+sudo apt install firejail
+
+# Fedora
+sudo dnf install firejail
+```
+
+---
+
+### 3.2 Firejail 配置文件错误
+
+**症状：** `SandboxError: EXECUTION_FAILED`
+
+**排查步骤：**
+
+```bash
+# 检查 profile 语法
+firejail --debug-profile=/path/to/profile 2>&1
+
+# 测试 profile
+firejail --profile=/path/to/profile /bin/ls
+```
+
+---
+
+## 4. 权限相关问题
+
+### 4.1 权限被拒绝
+
+**症状：** `SandboxError: PERMISSION_DENIED`
+
+**排查步骤：**
+
+```bash
+# 检查工作区目录权限
+ls -la ~/.qimingclaw/workspaces/
+
+# 检查用户组
+groups $USER
+```
+
+**解决方案：**
+
+```bash
+# 修复目录权限
+chmod -R 755 ~/.qimingclaw/workspaces/
+
+# 将用户加入 docker 组
+sudo usermod -aG docker $USER
+```
+
+---
+
+### 4.2 权限请求无响应
+
+**症状：** 命令挂起等待权限确认
+
+**排查步骤：**
+
+```bash
+# 检查待处理的权限请求
+# 在渲染进程中查看 PendingPermissions 状态
+```
+
+**解决方案：**
+
+- 检查用户是否看到了权限确认弹窗
+- 增加权限请求超时时间
+- 设置自动批准常见操作
+
+---
+
+## 5. 工作区问题
+
+### 5.1 工作区创建失败
+
+**症状：** `SandboxError: WORKSPACE_EXISTS`
+
+**排查步骤：**
+
+```bash
+# 检查工作区目录
+ls -la ~/.qimingclaw/workspaces/
+
+# 检查是否有残留进程
+ps aux | grep qimingclaw
+```
+
+**解决方案：**
+
+```bash
+# 删除残留目录
+rm -rf ~/.qimingclaw/workspaces/<session-id>
+
+# 重启应用
+```
+
+---
+
+### 5.2 工作区磁盘空间不足
+
+**症状：** `SandboxError: EXECUTION_FAILED` (disk full)
+
+**排查步骤：**
+
+```bash
+# 检查磁盘空间
+df -h ~/.qimingclaw/
+
+# 检查工作区大小
+du -sh ~/.qimingclaw/workspaces/*
+```
+
+**解决方案：**
+
+```bash
+# 清理临时文件
+rm -rf ~/.qimingclaw/workspaces/*/tmp/*
+
+# 增加磁盘限额配置
+# 在 sandbox.json 中设置 maxDiskUsage
+```
+
+---
+
+### 5.3 工作区清理失败
+
+**症状：** 退出应用后工作区仍然存在
+
+**排查步骤：**
+
+```bash
+# 检查保留策略配置
+cat ~/.qimingclaw/workspaces/<session-id>/sandbox.json
+
+# 检查是否有进程占用
+lsof +D ~/.qimingclaw/workspaces/<session-id>
+```
+
+---
+
+## 6. 性能问题
+
+### 6.1 沙箱启动慢
+
+**症状：** 首次创建沙箱需要很长时间
+
+**原因：** Docker 镜像下载、WSL 初始化等
+
+**解决方案：**
+
+```bash
+# 预热：提前拉取镜像
+docker pull node:20-slim
+
+# WSL 预初始化
+wsl -d Ubuntu-22.04
+```
+
+---
+
+### 6.2 命令执行超时
+
+**症状：** `SandboxError: EXECUTION_TIMEOUT`
+
+**排查步骤：**
+
+```bash
+# 检查命令复杂度
+# 增加超时时间
+```
+
+**解决方案：**
+
+```typescript
+// 增加默认超时
+const executeOptions: ExecuteOptions = {
+  timeout: 600000, // 10 分钟
+};
+```
+
+---
+
+## 7. 网络问题
+
+### 7.1 沙箱内无法访问网络
+
+**症状：** `npm install` 失败
+
+**排查步骤：**
+
+```bash
+# 检查 Docker 网络
+docker network ls
+
+# 测试网络连通性
+docker exec <container-id> ping 8.8.8.8
+```
+
+**解决方案：**
+
+```typescript
+// 在配置中启用网络
+const config: SandboxConfig = {
+  networkEnabled: true,
+};
+```
+
+---
+
+## 8. 跨平台路径问题
+
+### 8.1 Windows 路径错误
+
+**症状：** 文件找不到
+
+**排查步骤：**
+
+```bash
+# 检查路径格式
+echo $PATH
+```
+
+**解决方案：**
+
+```typescript
+// 使用 path 模块
+import path from 'path';
+
+const sandboxPath = path.join(workspacePath, 'projects');
+// 避免手动拼接字符串
+```
+
+---
+
+## 9. 日志获取
+
+### 9.1 主进程日志
+
+```bash
+# 查看主进程日志
+tail -f ~/.qimingclaw/logs/main.$(date +%Y-%m-%d).log
+```
+
+### 9.2 Docker 容器日志
+
+```bash
+# 查看容器日志
+docker logs <container-id>
+
+# 实时跟踪
+docker logs -f <container-id>
+```
+
+---
+
+## 10. 常见错误代码
+
+| 错误代码 | 说明 | 解决方案 |
+|---------|------|---------|
+| `SANDBOX_UNAVAILABLE` | 沙箱不可用 | 检查 Docker/WSL/Firejail 安装 |
+| `WORKSPACE_NOT_FOUND` | 工作区不存在 | 创建工作区或检查 ID |
+| `WORKSPACE_EXISTS` | 工作区已存在 | 销毁现有工作区 |
+| `PERMISSION_DENIED` | 权限不足 | 检查权限配置或用户确认 |
+| `EXECUTION_FAILED` | 执行失败 | 查看详细日志 |
+| `EXECUTION_TIMEOUT` | 执行超时 | 增加超时或优化命令 |
+| `FILE_NOT_FOUND` | 文件不存在 | 检查路径 |
+| `FILE_WRITE_FAILED` | 文件写入失败 | 检查磁盘空间和权限 |
+| `CLEANUP_FAILED` | 清理失败 | 手动清理或检查进程 |
+| `CONFIG_INVALID` | 配置无效 | 检查配置参数 |
+
+---
+
+## 11. 获取帮助
+
+### 11.1 收集诊断信息
+
+```bash
+# 1. 系统信息
+uname -a
+
+# 2. Docker 信息
+docker version
+docker info
+
+# 3. 应用日志
+tar -czf diagnostics.tar.gz ~/.qimingclaw/logs/
+
+# 4. 配置文件
+cat ~/.qimingclaw/config.json
+```
+
+### 11.2 报告问题
+
+报告问题时请包含：
+- 操作系统版本
+- Docker/WSL/Firejail 版本
+- 错误日志
+- 复现步骤
+- 预期行为
+
+---
+
+## 12. 变更记录
+
+| 日期 | 版本 | 变更 |
+|------|------|------|
+| 2026-03-22 | 1.0.0 | 初始版本 |