# Windows Sandbox 项目固化改造实施方案

## 项目概述
将现有的 Windows Sandbox 自动化注册项目从"每次重新安装所有依赖"模式改造为"固化依赖 + 快速启动"模式，实现类似 Sandboxie Plus 的功能，大幅提升启动速度和用户体验。

## 核心改造理念
- **固化 Python 环境**：使用便携版 Python，一次安装，永久使用
- **保持 Kiro.exe 每次重新安装**：确保隐私保护和指纹随机化
- **利用 Windows Sandbox MappedFolders**：实现只读映射固化
- **优化启动流程**：从 2-3 分钟缩短到 10-30 秒

---

## 实施计划

### 阶段一：环境准备与固化包创建
- [✓] **1.1** ~~创建便携版 Python 预安装脚本~~ → **集成到 start_sandbox.ps1 中**
- [✓] **1.2** 在 start_sandbox.ps1 中添加固化检查逻辑
- [✓] **1.3** 在 start_sandbox.ps1 中添加便携版 Python 下载和配置逻辑
- [✓] **1.4** 在 start_sandbox.ps1 中添加依赖库安装逻辑 (pywinauto, selenium, psutil, requests)
- [ ] **1.5** 测试集成化固化流程的完整性

### 阶段二：Windows Sandbox 配置文件重构
- [ ] **2.1** 更新 `.wsb` 配置文件 (`sandbox_config.wsb`)
- [ ] **2.2** 配置 MappedFolders 映射关系
  - [ ] Python 环境只读映射 (`python_env` → `C:\python_env`)
  - [ ] 资源文件只读映射 (`sandbox_files` → `C:\assets`)
  - [ ] 共享目录读写映射 (`shared` → `C:\shared`)
- [ ] **2.3** 配置自动启动命令 (LogonCommand)
- [ ] **2.4** 测试 `.wsb` 文件有效性

### 阶段三：安装脚本重构
- [ ] **3.1** 备份原始 `install.ps1` 为 `install_original.ps1`
- [ ] **3.2** 重写 `install.ps1` 为固化版本
  - [ ] 添加固化 Python 检测逻辑
  - [ ] 保留 Kiro.exe 每次重新安装逻辑
  - [ ] 优化环境变量设置
  - [ ] 改进错误处理和日志记录
- [ ] **3.3** 创建指纹生成优化脚本
- [ ] **3.4** 测试新版安装脚本功能

### 阶段四：启动脚本优化
- [ ] **4.1** 创建一键启动脚本 (`run_kiro_optimized.bat`)
- [ ] **4.2** 添加启动前检查逻辑
- [ ] **4.3** 集成日志记录功能
- [ ] **4.4** 创建故障恢复机制

### 阶段五：项目结构重组
- [ ] **5.1** 创建新的目录结构
  - [ ] `python_env/` - 固化的 Python 环境
  - [ ] `shared/` - 沙盒与主机共享目录
  - [ ] `backup/` - 原版本备份
- [ ] **5.2** 迁移现有脚本到新结构
- [ ] **5.3** 更新所有路径引用
- [ ] **5.4** 清理冗余文件

### 阶段六：测试与验证
- [ ] **6.1** 单元测试：固化 Python 环境
- [ ] **6.2** 集成测试：完整启动流程
- [ ] **6.3** 性能测试：启动时间对比
- [ ] **6.4** 功能测试：Kiro 自动化流程
- [ ] **6.5** 兼容性测试：不同 Windows 版本

### 阶段七：文档更新与优化
- [ ] **7.1** 更新 README.md 文档
- [ ] **7.2** 创建使用指南 (`USAGE_GUIDE.md`)
- [ ] **7.3** 编写故障排除文档 (`TROUBLESHOOTING.md`)
- [ ] **7.4** 更新项目架构图

### 阶段八：性能优化与增强功能
- [ ] **8.1** 进一步精简便携版 Python (目标 < 30MB)
- [ ] **8.2** 添加启动进度显示
- [ ] **8.3** 实现配置文件热重载
- [ ] **8.4** 添加自动更新检查机制

---

## 技术实现细节

### 核心技术栈
- **Windows Sandbox**: VM 级隔离环境
- **Python 便携版**: 零依赖、免安装的 Python 环境
- **PowerShell**: 自动化脚本和系统配置
- **MappedFolders**: 主机与沙盒的文件映射机制

### 关键设计决策
1. **Python 固化策略**: 使用便携版而非安装版，避免注册表污染
2. **Kiro.exe 策略**: 保持每次重新安装，确保隐私和指纹随机化
3. **映射策略**: 只读映射固化资源，读写映射临时数据
4. **启动策略**: 检测 → 设置 → 执行的三阶段启动流程

### 预期性能提升
- **启动时间**: 从 2-3 分钟缩短到 10-30 秒 (提升 80-90%)
- **资源占用**: 减少重复下载，节省带宽和存储
- **用户体验**: 一键启动，无需等待依赖安装

---

## 风险评估与应对

### 潜在风险
1. **兼容性风险**: 便携版 Python 可能与某些库不兼容
2. **路径依赖风险**: 硬编码路径可能导致迁移问题
3. **权限风险**: MappedFolders 可能需要特定权限设置

### 应对措施
1. **充分测试**: 在多个环境中验证兼容性
2. **路径参数化**: 使用配置文件管理所有路径
3. **权限检查**: 添加启动前权限验证逻辑

---

## 成功标准

### 功能标准
- [ ] 固化 Python 环境正常工作
- [ ] Kiro 自动化流程无异常
- [ ] 所有原有功能保持完整

### 性能标准
- [ ] 启动时间 < 30 秒
- [ ] 固化包大小 < 50MB
- [ ] 内存占用无显著增加

### 用户体验标准
- [ ] 一键启动成功率 > 95%
- [ ] 错误信息清晰易懂
- [ ] 故障恢复机制有效

---

## 项目时间线

| 阶段 | 预计时间 | 关键里程碑 |
|------|----------|------------|
| 阶段一 | 1-2 小时 | 固化包创建完成 |
| 阶段二 | 30 分钟 | .wsb 配置完成 |
| 阶段三 | 1-2 小时 | 安装脚本重构完成 |
| 阶段四 | 30 分钟 | 启动脚本优化完成 |
| 阶段五 | 1 小时 | 项目结构重组完成 |
| 阶段六 | 2-3 小时 | 全面测试完成 |
| 阶段七 | 1 小时 | 文档更新完成 |
| 阶段八 | 1-2 小时 | 性能优化完成 |

**总预计时间**: 8-12 小时

---

## 备注

- 每完成一个任务项，在对应的 `[ ]` 中打勾 `[✓]`
- 遇到问题时，在对应任务项下添加问题描述和解决方案
- 重要的配置更改需要在 Git 中提交并添加详细的 commit 信息
- 保持原有功能的向后兼容性，确保可以随时回滚到原版本

---

*最后更新: 2025-11-02*
*创建者: Claude Code*