{"_id":"@elegant_white/persistent-terminal-mcp","name":"@elegant_white/persistent-terminal-mcp","dist-tags":{"latest":"1.0.9"},"versions":{"1.0.9":{"name":"@elegant_white/persistent-terminal-mcp","version":"1.0.9","description":"MCP server for managing persistent terminal sessions using node-pty","main":"dist/index.js","types":"dist/index.d.ts","bin":{"persistent-terminal-mcp":"dist/index.js","persistent-terminal-mcp-rest":"dist/rest-server.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./rest-server":{"types":"./dist/rest-server.d.ts","import":"./dist/rest-server.js"},"./rest-api":{"types":"./dist/rest-api.d.ts","import":"./dist/rest-api.js"},"./mcp-server":{"types":"./dist/mcp-server.d.ts","import":"./dist/mcp-server.js"},"./terminal-manager":{"types":"./dist/terminal-manager.d.ts","import":"./dist/terminal-manager.js"},"./web-ui-manager":{"types":"./dist/web-ui-manager.d.ts","import":"./dist/web-ui-manager.js"},"./web-ui-server":{"types":"./dist/web-ui-server.d.ts","import":"./dist/web-ui-server.js"},"./types":{"types":"./dist/types.d.ts","import":"./dist/types.js"},"./package.json":"./package.json"},"type":"module","scripts":{"build":"tsc","dev":"tsx src/index.ts","dev:rest":"tsx src/rest-server.ts","start":"node dist/index.js","start:rest":"node dist/rest-server.js","test":"jest","test:unit":"jest","test:integration":"npm run test:integration:stdio && npm run test:integration:cursor && npm run test:integration:terminal && npm run test:integration:raw-tail","test:integration:stdio":"node tests/integration/test-mcp-stdio.mjs","test:integration:cursor":"node tests/integration/test-cursor-scenario.mjs","test:integration:terminal":"node tests/integration/test-terminal-fixes.mjs","test:integration:raw-tail":"node tests/integration/test-read-terminal-raw-tail.mjs","test:all":"npm run test:unit && npm run test:integration","clean":"rm -rf dist","prepare":"npm run build","example:basic":"tsx src/examples/basic-usage.ts","example:rest":"tsx src/examples/rest-api-demo.ts","example:interactive":"tsx src/examples/interactive-demo.ts","example:smart":"tsx src/examples/smart-reading-demo.ts","example:spinner":"tsx src/examples/test-spinner-compaction.ts","example:webui":"tsx src/examples/test-web-ui.ts","test:tools":"tsx src/examples/test-all-tools.ts","test:fixes":"tsx src/examples/test-fixes.ts","test:spinner":"jest spinner-detection.test.ts","test:webui":"tsx src/examples/test-web-ui.ts","lint":"echo 'Linting not configured yet'","format":"echo 'Formatting not configured yet'"},"keywords":["mcp","terminal","pty","persistent","session","node-pty"],"author":{"name":"Persistent Terminal Contributors"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/sanshao85/persistent-terminal-mcp.git"},"bugs":{"url":"https://github.com/sanshao85/persistent-terminal-mcp/issues"},"homepage":"https://github.com/sanshao85/persistent-terminal-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","cors":"^2.8.5","express":"^4.18.2","node-pty":"1.0.0","uuid":"^9.0.1","ws":"^8.18.3","zod":"^3.22.4"},"devDependencies":{"@types/cors":"^2.8.17","@types/express":"^4.17.21","@types/jest":"^29.0.0","@types/node":"^20.0.0","@types/uuid":"^9.0.7","@types/ws":"^8.18.1","jest":"^29.0.0","ts-jest":"^29.0.0","tsx":"^4.0.0","typescript":"^5.9.3"},"engines":{"node":">=18.0.0"},"sideEffects":false,"publishConfig":{"access":"public"},"_id":"@elegant_white/persistent-terminal-mcp@1.0.9","_nodeVersion":"24.19.0","_npmVersion":"11.11.1","dist":{"integrity":"sha512-8eDM5ZZ+vR1o+ACs+fxX/CRYb17nDl7PmjbSpSLu8eS7rhb1oRgkuvQZU8BrJmX+LZ8RywywkKhYXTOVClb8mw==","shasum":"4911bf57c5c1474cca69da0ae344460d8af532c4","tarball":"https://registry.npmjs.org/@elegant_white/persistent-terminal-mcp/-/persistent-terminal-mcp-1.0.9.tgz","fileCount":91,"unpackedSize":524894,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG8UVojvrPnGmD0wFwy6v+83TFmtc6mwCDX4dng8P6RwAiEAod3zM862H+QZjmjKY44uY/C0CBkSMZTXOEfUq7c8+20="}]},"_npmUser":{"name":"elegant_white","email":"1412998603@qq.com"},"directories":{},"maintainers":[{"name":"elegant_white","email":"1412998603@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/persistent-terminal-mcp_1.0.9_1788827392966_0.9990406484436161"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-08T00:29:52.813Z","1.0.9":"2026-09-08T00:29:53.120Z","modified":"2026-09-08T00:29:53.299Z"},"maintainers":[{"name":"elegant_white","email":"1412998603@qq.com"}],"description":"MCP server for managing persistent terminal sessions using node-pty","homepage":"https://github.com/sanshao85/persistent-terminal-mcp#readme","keywords":["mcp","terminal","pty","persistent","session","node-pty"],"repository":{"type":"git","url":"git+https://github.com/sanshao85/persistent-terminal-mcp.git"},"author":{"name":"Persistent Terminal Contributors"},"bugs":{"url":"https://github.com/sanshao85/persistent-terminal-mcp/issues"},"license":"MIT","readme":"# Persistent Terminal MCP Server\r\n\r\n[English](README.en.md)\r\n\r\n一个功能强大的 Model Context Protocol (MCP) 服务器，基于 TypeScript 和 [`node-pty`](https://github.com/microsoft/node-pty) 实现持久化终端会话管理。即使客户端断开连接，终端命令也会继续运行，特别适合 Claude、Cursor、Cline 等 AI 助手执行长时间任务。\r\n油管视频地址：https://youtu.be/nfLi1IZxhJs\r\nb站视频地址：https://www.bilibili.com/video/BV14ksPzqEbM/\r\n\r\nWindows 配置mcp 视频教程地址：https://youtu.be/WYEKwTQCAnc\r\n\r\n## ✨ 核心特性\r\n\r\n### 🔥 持久化终端会话\r\n- **长期运行**：创建、复用、管理长期运行的 Shell 会话\r\n- **断线续传**：客户端断开后终端继续运行，重连后可继续操作\r\n- **多会话管理**：同时管理多个独立的终端会话\r\n- **自动清理**：超时会话自动清理，避免资源泄漏\r\n\r\n### 🧠 智能输出管理\r\n- **循环缓冲区**：可配置大小（默认 10,000 行），自动管理内存\r\n- **多种读取模式**：\r\n  - `full`：完整输出\r\n  - `head`：只读取开头 N 行\r\n  - `tail`：只读取末尾 N 行\r\n  - `head-tail`：同时读取开头和末尾\r\n- **增量读取**：使用 `since` 参数只读取新增内容\r\n- **Token 估算**：自动估算输出的 token 数量，方便 AI 控制上下文\r\n\r\n### 🎨 Spinner 动画压缩\r\n- **自动检测**：识别常见的进度动画字符（⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏, ◐◓◑◒ 等）\r\n- **智能节流**：减少 `npm install`、`yarn`、`pnpm` 等命令的噪音输出\r\n- **保留关键信息**：压缩动画的同时保留真实日志\r\n- **灵活配置**：可通过环境变量或参数控制开关\r\n\r\n### 🌐 Web 可视化管理界面\r\n- **实时终端**：基于 xterm.js 的终端渲染，支持完整 ANSI 颜色\r\n- **WebSocket 推送**：终端输出实时显示，无需刷新\r\n- **交互操作**：直接在浏览器中发送命令、查看输出\r\n- **多实例支持**：自动端口分配，支持多个 AI 客户端同时使用\r\n- **VS Code 风格**：暗色主题，简洁美观的界面设计\r\n\r\n### 🤖 Codex 自动修复 Bug\r\n- **完全自动化**：集成 OpenAI Codex CLI，自动修复代码 Bug\r\n- **文档驱动**：AI 描述保存为 MD 文档，Codex 读取并修复\r\n- **详细报告**：生成完整的修复报告，包含修改前后对比\r\n- **智能等待**：自动检测 Codex 执行完成，默认超时 10 分钟\r\n- **历史记录**：所有 Bug 描述和修复报告永久保存在 docs/ 目录\r\n\r\n### 🔌 多种集成方式\r\n- **MCP 协议**：原生支持 Claude Desktop、Claude Code、Cursor、Cline 等客户端\r\n- **REST API**：提供 HTTP 接口，方便非 MCP 场景集成\r\n- **严格兼容**：完全符合 MCP stdio 协议规范，stdout 纯净无污染\r\n\r\n### 🛡️ 稳定性保障\r\n- **输出稳定检测**：`wait_for_output` 工具确保获取完整输出\r\n- **交互式应用支持**：完美支持 vim、npm create 等交互式程序\r\n- **ANSI 转义序列**：正确处理终端控制字符\r\n- **错误恢复**：自动重连、异常处理机制\r\n\r\n## 🚀 安装方式\r\n\r\n### ✅ 快速运行（推荐）\r\n无需安装，直接使用 `npx` 启动：\r\n```bash\r\nnpx persistent-terminal-mcp\r\n```\r\n\r\nREST 版本同样支持：\r\n```bash\r\nnpx persistent-terminal-mcp-rest\r\n```\r\n\r\n### 📦 引入到现有项目\r\n```bash\r\nnpm install persistent-terminal-mcp\r\n```\r\n\r\n安装后即可在代码中引用所有核心类与类型：\r\n```ts\r\nimport { PersistentTerminalMcpServer } from 'persistent-terminal-mcp';\r\n```\r\n\r\n### 🌐 全局安装（可选）\r\n```bash\r\nnpm install --global persistent-terminal-mcp\r\npersistent-terminal-mcp\r\n```\r\n\r\n## 🧪 本地开发\r\n适合想要修改源码或深入调试的场景：\r\n```bash\r\nnpm install          # 安装依赖\r\nnpm run build        # 编译 TypeScript → dist/\r\nnpm start            # 通过 stdio 启动 MCP 服务器\r\n```\r\n\r\n开发阶段也可直接运行 TypeScript 源码：\r\n```bash\r\nnpm run dev          # MCP 服务器 (tsx)\r\nnpm run dev:rest     # REST 服务器 (tsx)\r\n```\r\n\r\n### 🐞 调试模式\r\n启用调试日志（输出到 stderr，不会干扰 MCP 通信）：\r\n```bash\r\nMCP_DEBUG=true persistent-terminal-mcp\r\n```\r\n\r\n### 📚 示例脚本\r\n```bash\r\nnpm run example:basic        # 基础操作：创建 → 写入 → 读取 → 终止\r\nnpm run example:smart        # 智能读取：head/tail/head-tail 模式演示\r\nnpm run example:spinner      # Spinner 压缩功能演示\r\nnpm run example:webui        # Web UI 功能演示\r\nnpm run test:tools           # 全量验证所有 MCP 工具\r\nnpm run test:fixes           # 关键修复的回归测试\r\n```\r\n\r\n## ⚙️ MCP 客户端配置\r\n\r\n### Claude Desktop\r\n\r\n#### macOS / Linux\r\n\r\n**配置文件位置**: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n\r\n在配置文件中添加以下内容：\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"persistent-terminal\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"persistent-terminal-mcp\"],\r\n      \"env\": {\r\n        \"MAX_BUFFER_SIZE\": \"10000\",\r\n        \"SESSION_TIMEOUT\": \"86400000\",\r\n        \"COMPACT_ANIMATIONS\": \"true\",\r\n        \"ANIMATION_THROTTLE_MS\": \"100\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**说明**：\r\n- `-y` 参数会自动确认 npx 的下载提示\r\n- 若已全局安装（`npm install -g persistent-terminal-mcp`），可将 `command` 改为 `\"persistent-terminal-mcp\"` 并移除 `args` 中的 `-y`\r\n\r\n#### Windows\r\n\r\n**配置文件位置**: `%APPDATA%\\Claude\\claude_desktop_config.json`\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"persistent-terminal\": {\r\n      \"command\": \"cmd\",\r\n      \"args\": [\"/c\", \"npx\", \"-y\", \"persistent-terminal-mcp\"],\r\n      \"env\": {\r\n        \"MAX_BUFFER_SIZE\": \"10000\",\r\n        \"SESSION_TIMEOUT\": \"86400000\",\r\n        \"COMPACT_ANIMATIONS\": \"true\",\r\n        \"ANIMATION_THROTTLE_MS\": \"100\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**说明**：\r\n- Windows 需要通过 `cmd /c` 来调用 `npx`\r\n- 若已全局安装，可将 `args` 改为 `[\"/c\", \"persistent-terminal-mcp\"]`\r\n\r\n---\r\n\r\n### Claude Code\r\n\r\n#### macOS / Linux\r\n\r\n使用命令行快速添加：\r\n\r\n```bash\r\nclaude mcp add persistent-terminal \\\r\n  --env MAX_BUFFER_SIZE=10000 \\\r\n  --env SESSION_TIMEOUT=86400000 \\\r\n  --env COMPACT_ANIMATIONS=true \\\r\n  --env ANIMATION_THROTTLE_MS=100 \\\r\n  -- npx -y persistent-terminal-mcp\r\n```\r\n\r\n**或者**编辑配置文件 `~/.claude.json`：\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"persistent-terminal\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"persistent-terminal-mcp\"],\r\n      \"env\": {\r\n        \"MAX_BUFFER_SIZE\": \"10000\",\r\n        \"SESSION_TIMEOUT\": \"86400000\",\r\n        \"COMPACT_ANIMATIONS\": \"true\",\r\n        \"ANIMATION_THROTTLE_MS\": \"100\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n#### Windows\r\n\r\n> # ⚠️ **Windows 用户请注意**\r\n>\r\n> ## **Claude Code** 在 Windows 下 `claude mcp add` 命令存在参数解析问题\r\n>\r\n> ### **🚫 不推荐使用命令行方式**\r\n>\r\n> 请参考专门的配置文档：\r\n> ### 📖 [《Windows 下配置 persistent-terminal MCP》](docs/clients/claude-code-windows.md)\r\n>\r\n> 该文档提供了两种推荐方案：\r\n> - ✅ **项目级配置**（推荐）：在项目根目录创建 `.mcp.json` 文件\r\n> - ✅ **全局配置**：使用 Python 脚本修改 `~/.claude.json`\r\n\r\n---\r\n\r\n### Cursor / Cline\r\n\r\n配置方式与 Claude Desktop 类似，请参考各客户端的 MCP 配置文档。\r\n\r\n### Codex\r\n\r\n#### macOS / Linux\r\n\r\n在 .codex/config.toml 文件中添加以下配置：\r\n\r\n```toml\r\n# MCP Server Configuration (TOML Format)\r\n# 用于配置 persistent-terminal MCP 服务器\r\n\r\n[mcp_servers.persistent-terminal]\r\ncommand = \"npx\"\r\nargs = [\"-y\", \"persistent-terminal-mcp@1.0.9\"]\r\nenabled = true\r\nstartup_timeout_sec = 30\r\ntool_timeout_sec = 60\r\n\r\n[mcp_servers.persistent-terminal.env]\r\nMAX_BUFFER_SIZE = \"10000\"\r\nSESSION_TIMEOUT = \"86400000\"\r\nCOMPACT_ANIMATIONS = \"true\"\r\nANIMATION_THROTTLE_MS = \"100\"\r\nREAD_TERMINAL_MAX_CHARS = \"12000\"\r\n```\r\n\r\n#### Windows\r\n\r\n在 .codex/config.toml 文件中添加以下配置：\r\n\r\n```toml\r\n# MCP Server Configuration (TOML Format)\r\n# 用于配置 persistent-terminal MCP 服务器\r\n\r\n[mcp_servers.persistent-terminal]\r\ncommand = \"cmd\"\r\nargs = [\"/c\", \"npx\", \"-y\", \"persistent-terminal-mcp@1.0.9\"]\r\nenabled = true\r\nstartup_timeout_sec = 30\r\ntool_timeout_sec = 60\r\n\r\n[mcp_servers.persistent-terminal.env]\r\nMAX_BUFFER_SIZE = \"10000\"\r\nSESSION_TIMEOUT = \"86400000\"\r\nCOMPACT_ANIMATIONS = \"true\"\r\nANIMATION_THROTTLE_MS = \"100\"\r\nREAD_TERMINAL_MAX_CHARS = \"12000\"\r\n```\r\n\r\n**说明**：\r\n- `persistent-terminal-mcp` 是 **STDIO** 类型 MCP server（不是 HTTP/SSE）。\r\n- Windows 需要通过 `cmd /c` 调用 `npx`。\r\n- 若出现 “initialize response / connection closed”，通常是启动超时或旧版本导致，优先确认使用 `@1.0.9`，并适当增大 `startup_timeout_sec`。\r\n\r\n---\r\n\r\n### 环境变量说明\r\n| 变量 | 说明 | 默认值 |\r\n|------|------|--------|\r\n| `MAX_BUFFER_SIZE` | 缓冲区最大行数 | 10000 |\r\n| `SESSION_TIMEOUT` | 会话超时时间（毫秒） | 86400000 (24小时) |\r\n| `COMPACT_ANIMATIONS` | 是否启用 Spinner 压缩 | true |\r\n| `ANIMATION_THROTTLE_MS` | 动画节流时间（毫秒） | 100 |\r\n| `READ_TERMINAL_MAX_CHARS` | read_terminal 单次最大返回字符数 | 12000 |\r\n| `MCP_DEBUG` | 是否启用调试日志 | false |\r\n\r\n## 🧱 TypeScript 程序化使用\r\n\r\n```ts\r\nimport {\r\n  PersistentTerminalMcpServer,\r\n  TerminalManager,\r\n  RestApiServer\r\n} from 'persistent-terminal-mcp';\r\n\r\nconst manager = new TerminalManager();\r\nconst rest = new RestApiServer(manager);\r\nawait rest.start(3001);\r\n\r\nconst mcpServer = new PersistentTerminalMcpServer();\r\nconst server = mcpServer.getServer();\r\nawait server.connect(/* 自定义 transport */);\r\n```\r\n\r\n所有核心类和类型在包的根入口即可获取，详情可参考 `src/index.ts`。\r\n\r\n## 🛠️ MCP 工具一览\r\n\r\n| 工具 | 作用 | 主要参数 |\r\n|------|------|----------|\r\n| `create_terminal` | 创建持久终端会话 | `shell`, `cwd`, `env`, `cols`, `rows` |\r\n| `create_terminal_basic` | 精简版创建入口 | `shell`, `cwd` |\r\n| `write_terminal` | 向终端写入命令 | `terminalId`, `input`, `appendNewline`, `sendEnter` |\r\n| `read_terminal` | 读取缓冲输出 | `terminalId`, `mode`, `since`, `stripSpinner`, `raw`, `cleanAnsi`, `maxChars` |\r\n| `wait_for_output` | 等待输出稳定 | `terminalId`, `timeout`, `stableTime` |\r\n| `get_terminal_stats` | 查看统计信息 | `terminalId` |\r\n| `list_terminals` | 列出所有活跃终端 | 无 |\r\n| `kill_terminal` | 终止会话 | `terminalId`, `signal` |\r\n| `open_terminal_ui` | 打开 Web 管理界面 | `port`, `autoOpen` |\r\n| `fix_bug_with_codex` 🆕 | 使用 Codex 自动修复 Bug | `description`, `cwd`, `timeout` |\r\n\r\n### 工具详细说明\r\n\r\n#### `create_terminal` - 创建终端\r\n创建一个新的持久化终端会话。\r\n\r\n**参数**：\r\n- `shell` (可选): Shell 类型，如 `/bin/bash`、`/bin/zsh`\r\n- `cwd` (可选): 工作目录\r\n- `env` (可选): 环境变量对象\r\n- `cols` (可选): 终端列数，默认 80\r\n- `rows` (可选): 终端行数，默认 24\r\n\r\n**返回**：\r\n- `terminalId`: 终端 ID\r\n- `status`: 状态\r\n- `pid`: 进程 ID\r\n- `shell`: Shell 类型\r\n- `cwd`: 工作目录\r\n\r\n#### `write_terminal` - 写入命令\r\n向终端发送命令或输入。\r\n\r\n**参数**：\r\n- `terminalId`: 终端 ID\r\n- `input`: 要发送的内容\r\n- `appendNewline` (可选): 是否自动添加换行符，默认 true\r\n- `sendEnter` (可选): 强制发送一次回车（CR），适合交互式程序“只按回车继续”场景\r\n\r\n**提示**：\r\n- 默认会自动添加换行符执行命令；即使 `input` 为空，也会默认发送一次回车，避免交互式会话卡在“等待回车”。\r\n- 如需发送原始控制字符（如方向键），请设置 `appendNewline: false`。\r\n- 如需显式“只发回车”，建议：`input: \"\", sendEnter: true`。\r\n\r\n#### `read_terminal` - 读取输出\r\n读取终端的缓冲输出，支持多种智能截断模式。\r\n\r\n**参数**：\r\n- `terminalId`: 终端 ID\r\n- `mode` (可选): 读取模式\r\n  - `full`: 完整输出（默认）\r\n  - `head`: 只读取开头\r\n  - `tail`: 只读取末尾\r\n  - `head-tail`: 同时读取开头和末尾\r\n- `since` (可选): 从第 N 行开始读取（增量读取）\r\n- `maxLines` (可选): 最大行数，默认 1000\r\n- `headLines` (可选): head 模式的行数，默认 50\r\n- `tailLines` (可选): tail 模式的行数，默认 50\r\n- `stripSpinner` (可选): 是否压缩 Spinner 动画\r\n- `raw` (可选): 是否读取原始 PTY 输出流（适合 Codex/vim 等 TUI，避免历史回放丢失）\r\n- `cleanAnsi` (可选): 当 `raw=true` 时，是否清理 ANSI 控制序列并折叠重复刷屏，默认 true\r\n- `maxChars` (可选): 单次返回的最大字符数（默认 12000，超出会自动截断并给出提示）\r\n\r\n**Claude / Codex 场景建议**：\r\n- 优先使用：`mode: \"tail\"`, `tailLines: 120`, `raw: true`, `cleanAnsi: true`, `maxChars: 8000`\r\n- 避免直接 `mode: \"full\" + raw: true`，否则容易把大段 TUI 刷屏控制流塞进上下文。\r\n- 说明：从 `1.0.8` 开始，`raw=true` 下也会严格应用 `mode=head/tail/head-tail`，便于稳定读取“最后 N 行”。\r\n- 如果用户要求“最后 10 行”，优先：`mode: \"tail\"`, `tailLines: 10`, `raw: true`, `cleanAnsi: true`；若仍不完整，再用 `head-tail` 补读。\r\n\r\n**Codex 聊天发送建议**：\r\n- 先发送文本消息；若仍显示等待提交（Running 持续、无新回复），补发一次回车：`input: \"\", sendEnter: true`。\r\n\r\n**返回**：\r\n- `output`: 输出内容\r\n- `totalLines`: 总行数\r\n- `lineRange`: 实际返回的行范围\r\n- `estimatedTokens`: 估算的 token 数量\r\n- `truncated`: 是否被截断\r\n- `spinnerCompacted`: 是否进行了 Spinner 压缩\r\n\r\n#### `wait_for_output` - 等待输出稳定\r\n等待终端输出稳定后再读取，确保获取完整输出。\r\n\r\n**参数**：\r\n- `terminalId`: 终端 ID\r\n- `timeout` (可选): 最大等待时间（毫秒），默认 5000\r\n- `stableTime` (可选): 稳定时间（毫秒），默认 500\r\n\r\n**使用场景**：\r\n- 执行命令后确保获取完整输出\r\n- 等待交互式应用启动完成\r\n\r\n#### `fix_bug_with_codex` 🆕 - 自动修复 Bug\r\n使用 OpenAI Codex CLI 自动分析和修复代码中的 Bug。\r\n\r\n**参数**：\r\n- `description` (必需): 详细的 Bug 描述，必须包含：\r\n  - 问题症状（具体的错误行为）\r\n  - 期望行为（应该如何工作）\r\n  - 问题位置（文件路径、行号、函数名）\r\n  - 相关代码（有问题的代码片段）\r\n  - 根本原因（为什么会出现这个问题）\r\n  - 修复建议（如何修复）\r\n  - 影响范围（还会影响什么）\r\n  - 相关文件（所有相关的文件路径）\r\n  - 测试用例（如何验证修复是否有效）\r\n  - 上下文信息（有助于理解问题的背景）\r\n- `cwd` (可选): 工作目录，默认为当前目录\r\n- `timeout` (可选): 超时时间（毫秒），默认 600000（10 分钟）\r\n\r\n**返回**：\r\n- `terminalId`: 执行 Codex 的终端 ID\r\n- `reportPath`: 修复报告路径\r\n- `reportExists`: 报告是否存在\r\n- `workingDir`: 工作目录\r\n- `executionTime`: 执行时间（秒）\r\n- `timedOut`: 是否超时\r\n- `output`: 终端输出\r\n- `reportPreview`: 报告预览\r\n\r\n**工作流程**：\r\n1. AI 提供详细的 Bug 描述\r\n2. 工具将描述保存到 `docs/codex-bug-description-TIMESTAMP.md`\r\n3. Codex 读取文档并分析问题\r\n4. Codex 修复 Bug 并生成报告 `docs/codex-fix-TIMESTAMP.md`\r\n5. AI 读取报告并总结给用户\r\n\r\n**重要提示**：\r\n- ⚠️ 此工具具有完全系统访问权限（`danger-full-access`）\r\n- ⚠️ Codex 可以修改任何文件，建议在 Git 仓库中使用\r\n- ✅ 只使用英文描述（避免 UTF-8 编码问题）\r\n- ✅ 描述越详细，修复质量越高\r\n\r\n**示例**：\r\n```javascript\r\nfix_bug_with_codex({\r\n  description: `Username validation bug in auth.js file.\r\n\r\nPROBLEM:\r\n- File: src/auth/login.ts, line 45\r\n- Code: const usernameRegex = /^[a-zA-Z0-9]{3,20}$/\r\n- Symptom: Username 'user_name' is rejected with 'Invalid username' error\r\n- Expected: Should accept usernames with underscores and hyphens\r\n\r\nROOT CAUSE:\r\n- Regex [a-zA-Z0-9] only allows letters and numbers\r\n- Missing support for underscore and hyphen characters\r\n\r\nSUGGESTED FIX:\r\n- Change regex to: /^[a-zA-Z0-9_-]{3,20}$/\r\n\r\nVERIFICATION:\r\n- Run: npm test\r\n- Expected: all tests pass`,\r\n  cwd: '/path/to/project',\r\n  timeout: 600000\r\n})\r\n```\r\n\r\n**详细文档**：\r\n- [Codex Bug Fix Tool 功能文档](docs/features/CODEX_BUG_FIX_TOOL.md)\r\n- [Codex Bug Fix Tool 测试报告](docs/features/CODEX_BUG_FIX_TEST_REPORT.md)\r\n\r\n> **💡 提示**：Codex CLI 需要 OpenAI API 访问权限。如果你在国内或遇到访问问题，可以考虑使用 [Codex CLI 镜像服务](https://www.codex-cli.top)（¥99/月，每日 $90 额度），让 AI 编程更流畅。\r\n\r\n#### `open_terminal_ui` - 打开 Web 管理界面\r\n启动一个基于浏览器的可视化终端管理界面。\r\n\r\n**参数**：\r\n- `port` (可选): 端口号，默认从 3002 开始自动查找\r\n- `autoOpen` (可选): 是否自动打开浏览器，默认 true\r\n\r\n**返回**：\r\n- `url`: Web UI 地址\r\n- `port`: 实际使用的端口\r\n- `mode`: 启动模式（new/existing）\r\n- `autoOpened`: 是否自动打开了浏览器\r\n\r\n#### `fix_bug_with_codex` 🆕 - 使用 Codex 自动修复 Bug\r\n调用 OpenAI Codex CLI 自动分析和修复代码中的 bug，并生成详细的修复报告。\r\n\r\n**⚠️ 重要提示**：\r\n- 此工具使用 **完全权限模式**（`--sandbox danger-full-access --ask-for-approval never`）\r\n- Codex 可以完全控制代码库，请谨慎使用\r\n- 建议在使用前备份代码或使用版本控制\r\n\r\n**参数**：\r\n- `description` (必填): **详细的** bug 描述，必须包含：\r\n  - 问题现象（具体的错误表现）\r\n  - 预期行为（应该如何工作）\r\n  - 问题位置（文件路径、行号）\r\n  - 相关代码片段\r\n  - 根本原因（如果知道）\r\n  - 修复建议（如果有）\r\n  - 影响范围（可能影响的功能）\r\n  - 相关文件（所有相关文件路径）\r\n  - 测试用例（如何验证修复）\r\n  - 上下文信息（背景资料）\r\n- `cwd` (可选): 工作目录，默认当前目录\r\n- `timeout` (可选): 超时时间（毫秒），默认 600000（10分钟）\r\n\r\n**返回**：\r\n- `terminalId`: 执行 Codex 的终端 ID\r\n- `reportPath`: 修复报告的路径（`docs/codex-fix-TIMESTAMP.md`）\r\n- `reportExists`: 报告是否成功生成\r\n- `executionTime`: 执行时间\r\n- `output`: Codex 的终端输出\r\n\r\n**工作流程**：\r\n1. AI 助手收集详细的 bug 信息\r\n2. 调用此工具，传入详细描述\r\n3. Codex 分析问题并修复代码\r\n4. Codex 在 `docs/` 目录生成详细报告\r\n5. AI 助手读取报告并向用户汇报\r\n\r\n**报告内容**：\r\n- 问题描述\r\n- 修改的文件列表\r\n- 每个文件的具体修改（修改前/修改后对比）\r\n- 修改原因说明\r\n- 测试建议\r\n- 注意事项\r\n\r\n**使用示例**：\r\n```\r\n用户：登录功能有 bug，用户名验证总是失败\r\n\r\nAI 助手：\r\n1. [查看相关文件，理解问题]\r\n2. [调用 fix_bug_with_codex]\r\n   {\r\n     \"description\": \"登录功能用户名验证存在 bug，具体表现：\r\n     1. 问题现象：用户输入 'user_name' 时被拒绝\r\n     2. 预期行为：应该接受包含下划线的用户名\r\n     3. 问题位置：src/auth/login.ts 第 45 行\r\n     4. 相关代码：const usernameRegex = /^[a-zA-Z0-9]{3,20}$/\r\n     5. 根本原因：正则表达式不允许下划线\r\n     ...\"\r\n   }\r\n3. [等待 Codex 完成]\r\n4. [读取报告] view(\"docs/codex-fix-2025-10-18T00-35-12.md\")\r\n5. [向用户汇报修复结果]\r\n```\r\n\r\n**前置要求**：\r\n- 已安装 Codex CLI：`npm install -g @openai/codex-cli`\r\n- 已配置 Codex 认证\r\n- 项目中存在 `docs/` 目录\r\n\r\n**最佳实践**：\r\n- 提供尽可能详细的 bug 描述（描述越详细，修复质量越高）\r\n- 在调用前先查看相关文件，理解问题\r\n- 修复后务必运行测试验证\r\n- 查看生成的报告了解具体修改\r\n- 使用版本控制，便于回滚\r\n\r\n## 🌐 Web 管理界面\r\n\r\n### 功能特性\r\n- 📊 **终端列表**：查看所有终端的状态、PID、Shell、工作目录等信息\r\n- 🖥️ **实时终端**：使用 xterm.js 渲染终端输出，支持 ANSI 颜色\r\n- ⚡ **实时更新**：WebSocket 推送，终端输出实时显示\r\n- ⌨️ **交互操作**：直接在浏览器中发送命令\r\n- 🧾 **历史保真**：终端详情页历史加载默认使用原始 PTY 回放，改善 Codex 对话历史缺失\r\n- 🎨 **VS Code 风格**：暗色主题，简洁美观\r\n- 🔄 **自动端口**：支持多实例，自动避免端口冲突\r\n\r\n### 快速使用\r\n在 Claude 或其他 MCP 客户端中说：\r\n```\r\n请打开终端管理界面\r\n```\r\n\r\n或者直接运行测试脚本：\r\n```bash\r\nnpm run test:webui\r\n```\r\n\r\n详细使用说明见 [Web UI 使用指南](docs/guides/WEB_UI_USAGE.md)。\r\n\r\n## 🔌 REST API（可选）\r\n\r\n如果需要 HTTP 接口，可启动 REST 版本：\r\n```bash\r\nnpx persistent-terminal-mcp-rest\r\n```\r\n\r\n服务器默认监听 `3001` 端口（可配置），端点与 MCP 工具一一对应：\r\n\r\n| 端点 | 方法 | 说明 |\r\n|------|------|------|\r\n| `/api/terminals` | POST | 创建终端 |\r\n| `/api/terminals` | GET | 列出所有终端 |\r\n| `/api/terminals/:id` | GET | 获取终端详情 |\r\n| `/api/terminals/:id` | DELETE | 终止终端 |\r\n| `/api/terminals/:id/input` | POST | 发送命令 |\r\n| `/api/terminals/:id/output` | GET | 读取输出 |\r\n| `/api/terminals/:id/stats` | GET | 获取统计信息 |\r\n\r\n## 📁 项目结构\r\n\r\n```\r\npersistent-terminal-mcp/\r\n├── src/                    # TypeScript 源码\r\n│   ├── index.ts           # MCP 服务器入口\r\n│   ├── mcp-server.ts      # MCP 服务器实现\r\n│   ├── terminal-manager.ts # 终端管理器\r\n│   ├── output-buffer.ts   # 输出缓冲区\r\n│   ├── web-ui-manager.ts  # Web UI 管理器\r\n│   ├── web-ui-server.ts   # Web UI 服务器\r\n│   ├── rest-server.ts     # REST API 服务器\r\n│   ├── types.ts           # 类型定义\r\n│   ├── __tests__/         # 单元测试\r\n│   └── examples/          # 示例脚本\r\n├── dist/                   # 编译后的 JavaScript\r\n├── public/                 # Web UI 静态文件\r\n├── docs/                   # 文档\r\n│   ├── guides/            # 使用指南\r\n│   ├── reference/         # 技术参考\r\n│   ├── clients/           # 客户端配置\r\n│   └── zh/                # 中文文档\r\n├── tests/                  # 测试套件\r\n│   └── integration/       # 集成测试\r\n└── scripts/                # 辅助脚本\r\n```\r\n\r\n## 📚 文档导航\r\n\r\n### 快速访问\r\n- 📖 [完整文档索引](docs/README.md)\r\n- 🚨 [修复文档索引](docs/reference/fixes/README.md)\r\n- 🧪 [集成测试说明](tests/integration/README.md)\r\n- 🌐 [Web UI 使用指南](docs/guides/WEB_UI_USAGE.md)\r\n\r\n### 按分类\r\n- **使用指南**：[使用说明](docs/guides/usage.md) | [故障排查](docs/guides/troubleshooting.md) | [MCP 配置](docs/guides/mcp-config.md)\r\n- **技术参考**：[技术细节](docs/reference/technical-details.md) | [工具总结](docs/reference/tools-summary.md)\r\n- **修复文档**：[Stdio 修复](docs/reference/fixes/STDIO_FIX.md) | [Cursor 修复](docs/reference/fixes/CURSOR_FIX_SUMMARY.md) | [终端修复](docs/reference/fixes/TERMINAL_FIXES.md)\r\n- **客户端配置**：[Claude Desktop/Code](docs/clients/claude-code-setup.md)\r\n\r\n## 🔍 重要说明\r\n\r\n### Stdio 纯净性\r\n本 MCP 服务器严格遵循 MCP 协议，确保 stdout 只包含 JSON-RPC 消息，所有日志输出到 stderr。这保证了与 Cursor 等严格客户端的完全兼容。详见 [Stdio 修复文档](docs/reference/fixes/STDIO_FIX.md)。\r\n\r\n### Cursor 兼容性\r\n完全兼容 Cursor 及其他要求严格 JSON-RPC 通信的 MCP 客户端。快速设置见 [快速修复指南](docs/reference/fixes/QUICK_FIX_GUIDE.md)。\r\n\r\n### 终端交互\r\n支持交互式应用（vim、npm create 等），正确处理 ANSI 转义序列。详见 [终端修复文档](docs/reference/fixes/TERMINAL_FIXES.md)。\r\n\r\n### 输出稳定性\r\n使用 `wait_for_output` 工具确保命令执行后获取完整输出，避免读取不完整的数据。\r\n\r\n## 🧪 测试\r\n\r\n### 运行测试\r\n```bash\r\nnpm test                     # 运行所有单元测试\r\nnpm run test:integration     # 运行所有集成测试\r\nnpm run test:all            # 运行所有测试\r\n```\r\n\r\n### 集成测试\r\n```bash\r\nnpm run test:integration:stdio      # Stdio 纯净性测试\r\nnpm run test:integration:cursor     # Cursor 场景测试\r\nnpm run test:integration:terminal   # 终端功能测试\r\n```\r\n\r\n## 🤝 贡献指南\r\n\r\n欢迎提 Issue 或 PR！详细流程与代码规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。\r\n\r\n### 贡献方式\r\n1. Fork 本仓库\r\n2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)\r\n3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)\r\n4. 推送到分支 (`git push origin feature/AmazingFeature`)\r\n5. 开启 Pull Request\r\n\r\n## 📄 开源许可\r\n\r\n本项目以 [MIT 许可证](LICENSE) 发布。\r\n\r\n## 🙏 致谢\r\n\r\n- [node-pty](https://github.com/microsoft/node-pty) - 强大的 PTY 库\r\n- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 协议规范\r\n- [xterm.js](https://xtermjs.org/) - 优秀的终端模拟器\r\n\r\n## 📞 支持\r\n\r\n- 📖 查看 [文档](docs/README.md)\r\n- 🐛 提交 [Issue](https://github.com/yourusername/node-pty/issues)\r\n- 💬 参与 [讨论](https://github.com/yourusername/node-pty/discussions)\r\n\r\n---\r\n\r\n**最后更新**: 2025-10-08\r\n**版本**: 1.0.1\r\n","readmeFilename":"README.md","_rev":"1-e209a701f8a4f2208ac271bed2a6abda"}