Persistent Terminal MCP Server

# 测试反馈总结与修复报告 ## 📊 测试报告概览 ### Claude Code 测试报告 **测试者：** Claude Code AI **测试日期：** 2025-10-03 **发现问题：** 2 个 | 问题 | 严重程度 | 状态 | | ------------------- | -------- | --------- | | 命令不会自动执行 | 🔴 严重 | ✅ 已修复 | | kill 后终端仍在列表 | 🟡 中等 | ✅ 已修复 | ### Codex CLI 测试报告 **测试者：** Codex CLI AI **测试日期：** 2025-10-03 **发现问题：** 1 个 | 问题 | 严重程度 | 状态 | | --------------------------- | -------- | ----------- | | 找不到 create_terminal 工具 | 🟡 中等 | ⚠️ 配置问题 | --- ## 🔧 修复详情 ### 修复 1: 命令自动执行 #### 问题描述 Claude Code 报告：发送到终端的命令只是显示在终端中，但不会被执行。 #### 根本原因 ```typescript // 旧代码 ptyProcess.write(input); // 直接写入，没有换行符 ``` 用户发送 `"pwd"` 时，终端只是显示 `pwd` 但不执行，因为缺少换行符。 #### 修复方案 ```typescript // 新代码 const inputToWrite = input.endsWith("\n") || input.endsWith("\r") ? input : input + "\n"; ptyProcess.write(inputToWrite); ``` #### 用户体验改进 **之前：** ```json { "name": "write_terminal", "arguments": { "terminalId": "xxx", "input": "npm start\n" // 必须手动添加 \n } } ``` **现在：** ```json { "name": "write_terminal", "arguments": { "terminalId": "xxx", "input": "npm start" // 自动添加 \n } } ``` #### 测试结果 ``` ✅ 测试 1.1: 发送 "pwd" (不带换行符) - 命令自动执行 ✅ 测试 1.2: 发送 "echo test\n" (带换行符) - 正常工作 ✅ 测试 1.3: 连续发送多个命令 - 所有命令都执行 ``` --- ### 修复 2: 终端清理 #### 问题描述 Claude Code 报告：kill_terminal 执行后，终端状态显示为 "terminated"，但在 list_terminals 中该终端仍然显示。 #### 根本原因 ```typescript // 旧代码 ptyProcess.kill(signal); session.status = "terminated"; // 只修改状态 // 没有从 Map 中删除 ``` #### 修复方案 ```typescript // 新代码 ptyProcess.kill(signal); session.status = "terminated"; this.emit("terminalKilled", terminalId, signal); // 清理资源 this.ptyProcesses.delete(terminalId); this.outputBuffers.delete(terminalId); this.sessions.delete(terminalId); ``` #### 测试结果 ``` 📋 Kill 前: 2 个终端 🔪 Kill 第 1 个终端 📋 Kill 后: 1 个终端 ✅ 测试通过: 被 kill 的终端已从列表中移除 ``` --- ### Codex CLI 问题分析 #### 问题描述 Codex CLI 报告：所有操作都返回 "Terminal 1 not found"，找不到 create_terminal 工具。 #### 分析结果 这不是代码问题，而是 **MCP 配置问题**。 #### 可能原因 1. **MCP 服务器未正确配置** - Codex CLI 的配置文件中没有添加 persistent-terminal - 配置文件路径不正确 2. **工具名称不匹配** - Codex CLI 可能使用不同的工具命名规则 - 例如：`persistent-terminal__create_terminal` vs `create_terminal` 3. **使用了硬编码的 terminalId** - 测试中使用了 `terminalId: "1"` - 但应该先调用 `create_terminal` 获取实际的 ID #### 解决方案 **步骤 1: 检查配置** ```bash # 查找 Codex CLI 配置文件 find ~ -name "*codex*config*" 2>/dev/null ``` **步骤 2: 添加 MCP 配置** ```json { "mcpServers": { "persistent-terminal": { "command": "node", "args": ["/Users/admin/Desktop/node-pty/dist/index.js"], "env": { "MAX_BUFFER_SIZE": "10000", "SESSION_TIMEOUT": "86400000" } } } } ``` **步骤 3: 正确使用流程** ```javascript // 1. 先创建终端 const result = await create_terminal({ cwd: "/path" }); const terminalId = result.terminalId; // 获取实际 ID // 2. 使用实际 ID 进行操作 await write_terminal({ terminalId, input: "pwd" }); await read_terminal({ terminalId }); ``` --- ## 📁 创建的文档 ### 1. docs/reference/bug-fixes.md **内容：** 详细的技术修复报告 - 问题分析 - 修复方案 - 代码对比 - 测试结果 - 性能影响 - 部署步骤 ### 2. docs/reference/test-response.md **内容：** 给 AI 测试团队的回复 - 问题确认 - 修复说明 - 使用指南 - 重新测试步骤 - 配置检查 ### 3. CHANGELOG.md **内容：** 版本变更日志 - 1.0.1 版本的修复内容 - 1.0.0 版本的初始功能 - 升级指南 - 未来计划 ### 4. 测试反馈总结.md (本文档) **内容：** 测试反馈的中文总结 ### 5. src/examples/test-fixes.ts **内容：** 自动化测试脚本 - 测试命令自动执行 - 测试终端清理 - 完整的测试流程 --- ## 🚀 部署步骤 ### 1. 重新构建 ```bash cd /Users/admin/Desktop/node-pty npm run build ``` ### 2. 运行测试验证 ```bash npm run test:fixes ``` 应该看到： ``` ✅ 测试 1.1 通过: 命令自动执行了！ ✅ 测试 1.2 通过: 带换行符的命令也正常工作！ ✅ 测试 1.3 通过: 所有命令都执行了！ ✅ 测试 2 通过: 被 kill 的终端已从列表中移除！ ✅ 清理成功: 所有终端都已移除 🎉 所有测试完成！ ``` ### 3. 更新 Claude Code 配置 配置文件位置：`~/.claude.json` 确保配置正确： ```json { "mcpServers": { "persistent-terminal": { "type": "stdio", "command": "node", "args": ["/Users/admin/Desktop/node-pty/dist/index.js"], "env": { "MAX_BUFFER_SIZE": "10000", "SESSION_TIMEOUT": "86400000" } } } } ``` ### 4. 重启 Claude Code ```bash # 完全退出 Claude Code # 重新启动 claude ``` ### 5. 验证修复 ```bash # 在 Claude Code 中 /mcp # 应该看到 ✔ Found 1 MCP server • persistent-terminal: connected ``` --- ## 📊 修复前后对比 ### 命令执行 | 场景 | 修复前 | 修复后 | | ------------ | ---------------- | ----------------- | | 发送 "pwd" | ❌ 不执行 | ✅ 自动执行 | | 发送 "pwd\n" | ✅ 执行 | ✅ 执行（不重复） | | 用户体验 | 😞 需要记住加 \n | 😊 自然使用 | ### 终端清理 | 操作 | 修复前 | 修复后 | | -------------- | ----------------- | -------------- | | kill 终端 | 状态变 terminated | 完全移除 | | list_terminals | 显示已终止的终端 | 只显示活跃终端 | | 内存使用 | 逐渐增加（泄漏） | 正常释放 | --- ## 🎯 给 AI 的建议 ### Claude Code **测试通过后，你可以这样使用：** ``` 请创建一个终端，然后执行以下命令： 1. pwd 2. npm install 3. npm start 注意：不需要手动添加换行符，系统会自动处理。 ``` ### Codex CLI **配置检查清单：** 1. ✅ 确认 MCP 配置文件存在 2. ✅ 确认 persistent-terminal 已添加到配置 3. ✅ 确认路径是绝对路径 4. ✅ 重启 Codex CLI 5. ✅ 验证工具列表中有 6 个工具 6. ✅ 先调用 create_terminal 获取 ID 7. ✅ 使用实际 ID 进行后续操作 --- ## 📞 后续支持 ### 如果 Claude Code 仍有问题 请提供： 1. `/mcp` 命令的输出 2. 具体的错误信息 3. 你发送的命令内容 ### 如果 Codex CLI 仍有问题 请提供： 1. 配置文件的完整内容 2. "列出所有 MCP 工具" 的结果 3. 具体的调用代码和错误信息 --- ## ✅ 总结 ### 修复状态 - ✅ **命令自动执行** - 已修复并测试通过 - ✅ **终端清理** - 已修复并测试通过 - ⚠️ **Codex CLI 配置** - 需要用户检查配置 ### 版本更新 - **旧版本：** 1.0.0 - **新版本：** 1.0.1 - **发布日期：** 2025-10-03 ### 向后兼容性 ✅ **完全向后兼容** - 所有现有代码无需修改即可工作 ### 下一步 1. 重新构建项目 2. 重启 Claude Code / Codex CLI 3. 运行测试验证 4. 享受改进的用户体验！ --- **感谢 Claude Code 和 Codex CLI 团队的详细测试！你们的反馈帮助我们发现并修复了关键问题。** 🙏 **项目现在更加稳定和易用！** 🎉