Persistent Terminal MCP Server

# 如何使用这些提示词让 AI 开发项目 ## 📁 提示词文件说明 我已经为你创建了 3 个文档： ### 1. **docs/meta/project-prompt.md** ⭐ 主提示词 **用途：** 这是最重要的文档，包含完整的项目需求 **内容：** - 项目概述 - 核心需求（5 大功能） - REST API 设计（7 个端点） - 技术栈要求 - 项目结构 - 环境变量配置 - 错误处理 - 测试要求 - 部署要求 - 使用示例 ### 2. **docs/reference/technical-details.md** 🔧 技术细节 **用途：** 补充技术实现细节 **内容：** - node-pty 使用示例 - 循环缓冲区实现 - 智能截断实现 - Express 路由和控制器 - 错误处理中间件 - 会话超时清理 - 完整的代码示例 ### 3. **如何使用提示词.md** 📖 使用指南 **用途：** 告诉你如何使用这些文档（就是本文档） --- ## 🎯 推荐使用方式 ### 方式 1: 一次性发送（推荐）⭐ **适用于：** Claude、GPT-4、Gemini 等支持长上下文的 AI **步骤：** 1. 打开 AI 对话界面 2. 复制并发送以下内容： ``` 我需要你帮我开发一个项目。请仔细阅读以下两份文档： 【文档 1：项目需求】 [粘贴 docs/meta/project-prompt.md 的完整内容] 【文档 2：技术细节】 [粘贴 docs/reference/technical-details.md 的完整内容] 请确认你理解了所有需求，然后开始创建项目。 ``` **优点：** - AI 能看到完整的上下文 - 减少来回沟通 - 实现更准确 --- ### 方式 2: 分步发送 **适用于：** 上下文窗口较小的 AI，或者你想逐步验证 **步骤：** **第 1 步：发送主需求** ``` 我需要你帮我开发一个持久终端管理系统。请先阅读这份需求文档： [粘贴 docs/meta/project-prompt.md 的完整内容] 请确认你理解了需求，并告诉我你的实现计划。 ``` **第 2 步：等待 AI 回复并确认理解** **第 3 步：发送技术细节** ``` 很好！现在请阅读这份技术实现细节文档，它包含了关键代码示例： [粘贴 docs/reference/technical-details.md 的完整内容] 现在请开始创建项目。 ``` --- ### 方式 3: 使用文件上传（如果支持） **适用于：** Claude Desktop、ChatGPT Plus、Cursor 等支持文件上传的工具 **步骤：** 1. 上传 `docs/meta/project-prompt.md` 2. 上传 `docs/reference/technical-details.md` 3. 发送消息： ``` 我上传了两份文档，请阅读它们并帮我创建这个项目。 第一份是项目需求，第二份是技术实现细节。 请严格按照文档要求实现所有功能。 ``` --- ## 💬 推荐的对话流程 ### 初始消息 ``` 你好！我需要你帮我开发一个持久终端管理系统的后端 API。 这个系统的主要目的是让 AI 助手能够执行长时间运行的命令（如 npm start）而不会被阻塞。 我已经准备了详细的需求文档和技术实现细节。请仔细阅读以下内容： 【项目需求文档】 [粘贴 docs/meta/project-prompt.md] 【技术实现细节】 [粘贴 docs/reference/technical-details.md] 请确认你理解了所有需求，然后开始创建项目。 ``` --- ### AI 确认后，你可以说： ``` 很好！请开始创建项目。 请按照以下顺序进行： 1. 创建项目结构和 package.json 2. 实现核心的 TerminalManager 和 OutputBuffer 3. 实现 Express 服务器和路由 4. 实现所有 API 端点 5. 添加错误处理和日志 6. 创建测试文件 7. 编写 README.md 每完成一个主要部分，请告诉我，我会确认后再继续下一步。 ``` --- ## ✅ 验证 AI 是否理解 在 AI 开始编码前，你可以问： ``` 在开始之前，请回答以下问题确认你理解了需求： 1. 用户发送 "pwd" 命令时，系统应该如何处理？ 2. 当终端被 kill 后，需要清理哪些资源？ 3. 输出缓冲区的 head-tail 模式是什么意思？ 4. API 应该监听哪个端口？ 5. 会话超时时间是多少？ ``` **正确答案：** 1. 自动添加 `\n` 使其变成 `"pwd\n"` 并执行 2. 需要从 ptyProcesses、outputBuffers、sessions 三个 Map 中删除 3. 显示开头 N 行 + 结尾 N 行，中间省略 4. 3001（可配置） 5. 24 小时 / 86400000 毫秒（可配置） --- ## 🎯 不同 AI 的使用建议 ### Claude (Anthropic) - ✅ 支持长上下文，可以一次性发送所有文档 - ✅ 理解能力强，通常能准确实现需求 - 💡 建议：直接使用方式 1 ### ChatGPT (OpenAI) - ✅ GPT-4 支持长上下文 - ⚠️ GPT-3.5 上下文较短，建议分步发送 - 💡 建议：GPT-4 用方式 1，GPT-3.5 用方式 2 ### Cursor / Windsurf - ✅ 支持文件上传 - ✅ 可以直接在项目中工作 - 💡 建议：使用方式 3，上传文档文件 ### Codex CLI - ⚠️ 上下文可能有限 - 💡 建议：使用方式 2，分步发送 ### Gemini (Google) - ✅ 支持超长上下文 - 💡 建议：使用方式 1 --- ## 📋 检查清单 在 AI 完成项目后，检查以下内容： ### 功能检查 - [ ] 可以创建终端会话 - [ ] 发送 `"pwd"` 会自动执行（不需要 `\n`） - [ ] 可以读取终端输出 - [ ] 支持增量读取（since 参数） - [ ] 支持智能截断（head-tail 模式） - [ ] 可以获取统计信息 - [ ] 可以列出所有终端 - [ ] kill 后终端从列表中消失 - [ ] 会话超时自动清理 ### 代码质量检查 - [ ] 使用 TypeScript - [ ] 有完整的类型定义 - [ ] 有错误处理 - [ ] 有日志记录 - [ ] 代码结构清晰 ### 文档检查 - [ ] 有 README.md - [ ] 有 API 文档 - [ ] 有使用示例 - [ ] 有部署说明 ### 测试检查 - [ ] 有测试文件 - [ ] 测试覆盖主要功能 - [ ] 测试可以运行 --- ## 🐛 常见问题 ### Q1: AI 创建的代码命令不会自动执行怎么办？ **回复：** ``` 我发现命令不会自动执行。请检查 writeToTerminal 方法， 确保实现了自动添加换行符的逻辑： const inputToWrite = input.endsWith('\n') || input.endsWith('\r') ? input : input + '\n'; ptyProcess.write(inputToWrite); ``` --- ### Q2: AI 创建的代码 kill 后终端仍在列表中怎么办？ **回复：** ``` 我发现 kill 终端后它仍然在列表中。请检查 killTerminal 方法， 确保在 kill 后删除了所有资源： this.ptyProcesses.delete(terminalId); this.outputBuffers.delete(terminalId); this.sessions.delete(terminalId); ``` --- ### Q3: AI 没有实现某个功能怎么办？ **回复：** ``` 我注意到你没有实现 [具体功能]。 根据需求文档的第 [X] 部分，这个功能应该： [描述具体需求] 请添加这个功能。 ``` --- ### Q4: AI 的实现和需求不一致怎么办？ **回复：** ``` 你的实现和需求文档不一致。 需求文档说：[引用原文] 你的实现是：[描述实际实现] 请按照需求文档修改。 ``` --- ## 💡 提示 ### 让 AI 更好理解的技巧 1. **强调关键点** ``` 特别注意以下两点： 1. 命令必须自动添加换行符 2. kill 后必须完全清理资源 ``` 2. **提供示例** ``` 例如，用户发送 "pwd" 时，系统应该自动转换为 "pwd\n" 并执行。 ``` 3. **分步验证** ``` 请先实现核心的 TerminalManager，完成后我会测试， 然后再继续实现 API 层。 ``` --- ## 🎉 成功标准 当 AI 完成项目后，你应该能够： 1. **启动服务器** ```bash npm install npm run dev ``` 2. **创建终端** ```bash curl -X POST http://localhost:3001/api/terminals \ -H "Content-Type: application/json" \ -d '{"cwd": "/tmp"}' ``` 3. **发送命令（不需要 \n）** ```bash curl -X POST http://localhost:3001/api/terminals/[ID]/input \ -H "Content-Type: application/json" \ -d '{"input": "pwd"}' ``` 4. **读取输出** ```bash curl http://localhost:3001/api/terminals/[ID]/output ``` 5. **看到正确的输出** ```json { "success": true, "data": { "output": "/tmp\n", ... } } ``` --- ## 📞 需要帮助？ 如果 AI 创建的项目有问题，你可以： 1. 把错误信息发给 AI，让它修复 2. 引用需求文档的具体部分，指出问题 3. 提供具体的测试用例，让 AI 验证 --- **祝你顺利！这个项目应该比 MCP 方案更可靠、更容易使用。** 🚀