chore: initialize qiming workspace repository

qimingclaw/docs/WINDOWS_CMD_WINDOW_VERIFICATION_REPORT.md

@@ -0,0 +1,365 @@
+# qiming-agent_diff Windows CMD 窗口问题验证报告
+
+## 测试环境
+- **版本**: qiming-agent_diff (tag: win-v0.1.2, v0.1.26)
+- **mcp-proxy 版本**: 0.1.37 → 0.1.39
+- **测试日志**: `/Users/apple/Downloads/qiming-agent.log.2026-02-12`
+
+## 测试结果 ❌
+
+### 问题 1: CMD 窗口仍然弹出
+**预期**: 所有服务启动时不弹出 CMD 窗口  
+**实际**: CMD 窗口仍然弹出  
+**状态**: ❌ **未解决**
+
+### 问题 2: mcp-proxy 启动失败
+**预期**: mcp-proxy 正常启动并通过健康检查  
+**实际**: 健康检查超时（15秒后仍未就绪）  
+**状态**: ❌ **未解决**
+
+### 问题 3: Node.js 重复安装
+**预期**: 检测到已安装的 Node.js，直接使用  
+**实际**: 重复尝试安装 10 次后才使用自动安装  
+**状态**: ❌ **未解决**
+
+---
+
+## 代码验证
+
+### qiming-agent_diff 中的实现 ✅ 代码正确
+
+**文件**: `crates/qiming-agent-core/src/service/mod.rs`
+
+```rust
+// Windows 下正确使用了 CreationFlags + JobObject
+#[cfg(target_os = "windows")]
+let child = cmd
+    .wrap(process_wrap::tokio::KillOnDrop)
+    .wrap(CreationFlags(CREATE_NO_WINDOW | DETACHED_PROCESS))  // ✅ 正确
+    .wrap(JobObject)                                            // ✅ 正确
+    .spawn()?;
+```
+
+**应用位置**:
+1. ✅ `run_command_with_timeout()` - 通用命令执行
+2. ✅ `file_server_start()` - 文件服务器启动
+3. ✅ `lanproxy_start()` - LAN 代理启动
+4. ✅ `mcp_proxy_start()` - MCP 代理启动
+
+**Cargo.toml 特性**:
+```toml
+process-wrap = { version = "9", features = ["tokio1", "process-group", "job-object"] }
+```
+✅ 已正确添加 `job-object` 特性
+
+---
+
+## 为什么代码正确但仍然弹出窗口？
+
+### 可能原因 1: `.cmd` 批处理文件本身的问题 ⭐ 最可能
+
+**分析**:
+
+Windows 上的 npm 全局包会生成 `.cmd` 包装文件：
+```
+C:\Users\MECHREVO\.local\bin\
+├── mcp-proxy.cmd        ← 批处理文件
+├── qiming-file-server.cmd
+└── ...
+```
+
+**问题**: 即使父进程设置了 `CREATE_NO_WINDOW`，`.cmd` 文件启动时仍然会：
+1. 启动 `cmd.exe` 解释器
+2. `cmd.exe` 可能会**忽略**父进程的窗口标志
+3. `.cmd` 内部再启动 Node.js 进程
+
+**层级关系**:
+```
+qiming-agent.exe (设置 CREATE_NO_WINDOW)
+  └─ cmd.exe (解释 .cmd 文件) ← 可能弹窗！
+      └─ node.exe (实际的服务)
+```
+
+**验证方法**:
+
+1. 直接运行 `.cmd` 文件看是否弹窗：
+```powershell
+# 测试 1: 直接运行
+C:\Users\MECHREVO\.local\bin\mcp-proxy.cmd
+
+# 测试 2: 通过 Rust 程序运行（设置 CREATE_NO_WINDOW）
+# 如果仍然弹窗，说明问题在 .cmd 文件本身
+```
+
+2. 查看 `.cmd` 文件内容：
+```powershell
+type C:\Users\MECHREVO\.local\bin\mcp-proxy.cmd
+```
+
+---
+
+### 可能原因 2: process-wrap 的 JobObject 实现问题
+
+**分析**:
+
+`process-wrap` 的 `JobObject` 可能没有正确传递 `CREATE_NO_WINDOW` 标志给子进程。
+
+**验证代码**:
+```rust
+// 当前实现
+.wrap(CreationFlags(CREATE_NO_WINDOW | DETACHED_PROCESS))
+.wrap(JobObject)
+
+// 可能的问题：JobObject 重新创建了进程，覆盖了 CreationFlags？
+```
+
+**解决方案**: 检查 process-wrap 的源码，确认 JobObject 是否保留了 CreationFlags。
+
+---
+
+### 可能原因 3: Windows 版本或系统设置
+
+某些 Windows 版本或系统设置可能忽略 `CREATE_NO_WINDOW` 标志。
+
+**验证**:
+```powershell
+# 检查 Windows 版本
+systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
+
+# 检查是否有组策略限制
+gpedit.msc
+```
+
+---
+
+## 解决方案建议
+
+### 方案 A: 绕过 `.cmd` 文件，直接调用 Node.js ⭐ 推荐
+
+**原理**: 不使用 `.cmd` 包装文件，直接调用 node.exe
+
+**实现**:
+
+```rust
+// 修改前
+let bin_path = "C:\\Users\\...\\mcp-proxy.cmd";
+let mut cmd = CommandWrap::with_new(&bin_path, |cmd| {
+    // ...
+});
+
+// 修改后
+let node_exe = "C:\\Users\\...\\node.exe";
+let mcp_proxy_js = "C:\\Users\\...\\node_modules\\mcp-stdio-proxy\\dist\\index.js";
+
+let mut cmd = CommandWrap::with_new(node_exe, |cmd| {
+    cmd.arg(mcp_proxy_js)  // 直接调用 JS 文件
+       .env("PATH", ...)
+       // ...
+});
+
+#[cfg(windows)]
+let child = cmd
+    .wrap(CreationFlags(CREATE_NO_WINDOW | DETACHED_PROCESS))
+    .wrap(JobObject)
+    .spawn()?;
+```
+
+**优点**:
+- ✅ 完全绕过 `.cmd` 文件
+- ✅ 更可控的进程启动
+- ✅ 更清晰的参数传递
+
+**缺点**:
+- ⚠️ 需要找到 `.cmd` 对应的 `.js` 文件路径
+- ⚠️ 需要处理 npm 包的路径解析
+
+---
+
+### 方案 B: 使用 `conhost.exe` 隐藏控制台
+
+**原理**: 使用 Windows 的 `conhost.exe` 工具隐藏控制台窗口
+
+**实现**:
+
+```rust
+#[cfg(windows)]
+fn run_hidden(cmd_path: &str, args: &[&str]) -> Result<Child> {
+    use std::process::{Command, Stdio};
+    use std::os::windows::process::CommandExt;
+    
+    // 方法 1: 使用 CREATE_NO_WINDOW + STARTUPINFOEXW
+    const CREATE_NO_WINDOW: u32 = 0x08000000;
+    const DETACHED_PROCESS: u32 = 0x00000008;
+    
+    let mut cmd = Command::new(cmd_path);
+    cmd.args(args);
+    cmd.creation_flags(CREATE_NO_WINDOW | DETACHED_PROCESS);
+    cmd.stdout(Stdio::null());
+    cmd.stderr(Stdio::null());
+    
+    // 方法 2: 使用 wscript 启动（更隐蔽）
+    // let mut cmd = Command::new("wscript.exe");
+    // cmd.arg("//B")  // Batch mode (no UI)
+    //    .arg("//NoLogo")
+    //    .arg(vbs_script_path);  // 需要生成 VBS 脚本
+    
+    cmd.spawn()
+}
+```
+
+---
+
+### 方案 C: 打包成 Windows 服务或使用隐藏启动器
+
+**原理**: 将服务打包成 Windows 服务或使用专门的隐藏启动器
+
+**实现**:
+
+1. **Windows 服务**:
+```rust
+// 使用 windows-service crate
+// 将 qiming-agent 注册为 Windows 服务
+```
+
+2. **隐藏启动器**:
+```rust
+// 创建一个小的 C++ 启动器
+// 使用 ShellExecuteEx + SW_HIDE
+```
+
+---
+
+## 调试步骤
+
+### 1. 验证 `.cmd` 文件是否是根本原因
+
+```powershell
+# 查看 mcp-proxy.cmd 内容
+type C:\Users\MECHREVO\.local\bin\mcp-proxy.cmd
+
+# 尝试直接运行 node.exe（而不是 .cmd）
+C:\Users\MECHREVO\.local\bin\node.exe C:\Users\MECHREVO\.local\bin\node_modules\mcp-stdio-proxy\dist\index.js --help
+```
+
+### 2. 使用 Process Explorer 查看进程树
+
+下载 Process Explorer: https://learn.microsoft.com/en-us/sysinternals/downloads/process-explorer
+
+启动 qiming-agent 后，查看进程树：
+```
+qiming-agent.exe
+  └─ cmd.exe  ← 如果看到这个，说明 .cmd 文件启动了 cmd.exe
+      └─ conhost.exe  ← 控制台宿主
+          └─ node.exe
+```
+
+### 3. 添加详细日志
+
+修改 `service/mod.rs`，添加日志：
+
+```rust
+#[cfg(windows)]
+{
+    tracing::info!("Windows: 设置 CREATE_NO_WINDOW | DETACHED_PROCESS");
+    tracing::info!("命令路径: {}", bin_path);
+    tracing::info!("是否是 .cmd 文件: {}", bin_path.ends_with(".cmd"));
+}
+```
+
+---
+
+## 测试 mcp-proxy v0.1.39 的改进
+
+根据 mcp-proxy 的更新日志，v0.1.39 添加了：
+
+1. ✅ 环境变量日志配置支持
+2. ✅ 增强的启动日志
+3. ✅ stderr 输出关键信息
+
+**验证**:
+
+```powershell
+# 设置日志目录
+$env:MCP_PROXY_LOG_DIR = "C:\Users\MECHREVO\AppData\Roaming\qiming-agent\logs\mcp-proxy"
+$env:MCP_PROXY_LOG_LEVEL = "debug"
+$env:MCP_PROXY_PORT = "18099"
+
+# 手动启动 mcp-proxy
+C:\Users\MECHREVO\.local\bin\mcp-proxy.cmd
+
+# 查看日志
+type C:\Users\MECHREVO\AppData\Roaming\qiming-agent\logs\mcp-proxy\log.2026-02-12
+```
+
+---
+
+## Node.js 检测问题修复
+
+日志显示的问题：
+```
+[resolve_node_bin] npm -> fallback to PATH  # 10 次失败
+[NodeInstall] 开始自动安装 Node.js...      # 最终触发安装
+```
+
+**根本原因**: `resolve_node_bin` 没有真正验证 npm 命令是否可用
+
+**修复方案** (已在 mcp-proxy 仓库的分析文档中提供):
+
+```rust
+async fn is_nodejs_available() -> bool {
+    tokio::process::Command::new("node")
+        .arg("--version")
+        .status()
+        .await
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+async fn ensure_npm_package(package_name: &str) -> Result<()> {
+    // 1. 先检查 Node.js 是否可用
+    if !is_nodejs_available().await {
+        install_nodejs().await?;
+    }
+    
+    // 2. 检查包是否已安装
+    if is_npm_package_installed(package_name).await? {
+        return Ok(());
+    }
+    
+    // 3. 安装包（带重试限制）
+    // ...
+}
+```
+
+---
+
+## 总结
+
+### ✅ qiming-agent_diff 代码是正确的
+
+代码层面的修改是正确的：
+- ✅ 使用了 `CreationFlags(CREATE_NO_WINDOW | DETACHED_PROCESS)`
+- ✅ 使用了 `JobObject` 管理进程
+- ✅ 添加了 `process-group` 和 `job-object` 特性
+
+### ❌ 但仍然弹出 CMD 窗口
+
+**最可能的原因**: `.cmd` 批处理文件本身启动了 `cmd.exe`，导致窗口弹出
+
+**推荐的解决方案**:
+1. ⭐ **方案 A**: 绕过 `.cmd` 文件，直接调用 `node.exe`
+2. 🔧 **方案 B**: 验证 process-wrap 的 JobObject 实现
+3. 📊 **调试**: 使用 Process Explorer 查看进程树
+
+### 📋 下一步行动
+
+1. **立即**: 查看 `.cmd` 文件内容，确认是否是根本原因
+2. **验证**: 尝试直接调用 `node.exe` 而不是 `.cmd`
+3. **测试**: 使用 Process Explorer 查看进程树
+4. **应用**: 如果方案 A 有效，修改 qiming-agent 代码
+
+### 📝 相关文档
+
+- mcp-proxy LOG_CONFIGURATION.md - 日志配置指南
+- QIMING_AGENT_WINDOWS_CMD_FIX.md - CMD 窗口修复方案
+- MCP_PROXY_STARTUP_FAILURE_ANALYSIS.md - 启动失败分析