Qb64pe MCP Server

QB64PE MCP服务器

 ](https://github.com/grymmjack/qb64pe-mcp-server) ](https://nodejs.org/)    

一个全面的模型上下文协议（MCP）服务器，提供高级QB64PE（QBasic 64 Phoenix Edition）编程辅助。该服务器使AI助手能够搜索QB64PE维基，了解编译器选项，提供调试帮助，验证仅QB64PE的语法，处理跨平台差异， 将QBasic程序移植到QB64PE，以及 通过本机日志记录提供高级自动化调试功能.

✨ 新增：自动刀具发现系统

MCP服务器现在包括 自动刀具发现系统 确保LLM立即了解所有可用工具。在第一次工具调用时，LLM会收到所有52种工具的全面文档，按类别组织，并附有使用指南和工作流程建议。这解决了LLM不知道有什么工具可用的常见问题。

主要特点：

• 🎓 首次交互时自动完成-无需手动发现
• 📚 完整的工具目录，包括描述和模式
• 🏷️ 按10个功能类别组织
• 📖 包括使用指南和工作流程模式
• 🔄 零配置-自动工作

🚀 52个工具和6个提示可用！

此MCP服务器提供 52种综合工具 和 6个智能提示 提供完整的QB64PE开发支持，从安装检测到高级调试和移植协助。

🧠 新：特工情报系统！ -请参阅 HOW_GENTS_LEARN.md 有关AI代理如何通过以下方式自动发现和智能使用QB64PE MCP工具的详细信息：

• 自动工具发现 -首次致电时完成工具目录
• MCP资源 - qb64pe://agent/intelligence-guide 具有上下文识别、决策矩阵和自主工作流
• MCP提示 - analyze-compilation-error 用于自主编译错误修复

______________________________________________________________________

📁 仓库结构

存储库被组织成清晰的功能目录：

qb64pe-mcp-server/
├── src/                          # TypeScript source code
│   ├── index.ts                  # Main MCP server
│   ├── services/                 # Core services (wiki, compiler, syntax, etc.)
│   ├── tools/                    # MCP tool implementations
│   ├── constants/                # Constants and data definitions
│   ├── data/                     # Static data files
│   └── utils/                    # Utility functions
├── build/                        # Compiled JavaScript output
├── tests/                        # Test suite
│   ├── integration/              # Integration tests (test-*.js files)
│   ├── fixtures/                 # Test fixtures
│   │   ├── bas-files/            # .bas test files
│   │   └── porting/              # Porting test files (qbasic/, qb64pe/)
│   ├── services/                 # Service unit tests
│   ├── tools/                    # Tool unit tests
│   ├── utils/                    # Utility unit tests
│   └── constants/                # Test constants
├── docs/                         # Documentation
│   ├── guides/                   # Developer guides
│   │   ├── HOW_AGENTS_LEARN.md
│   │   ├── AGENT_INTELLIGENCE_GUIDE.md
│   │   ├── WORKFLOW_AUTOMATION.md    # 🔄 Auto-compile after edits (MANDATORY)
│   │   ├── QB64PE_DEBUGGING_SYSTEM_USAGE.md
│   │   ├── GRAPHICS_MODE_ECHO_REQUIREMENTS.md
│   │   └── QUICK_REFERENCE.md
│   ├── api/                      # API reference docs
│   │   ├── SERVICE_API_REFERENCE.md
│   │   └── MCP_TOOLS_REFERENCE.md
│   ├── examples/                 # Examples and tutorials
│   │   ├── TOOL_EXAMPLES.md
│   │   └── test-session-problems.md
│   ├── features/                 # Feature documentation
│   │   └── NEW_TOOLS_README.md
│   ├── resources/                # MCP resources
│   ├── tools/                    # Individual tool documentation (52 files)
│   ├── prompts/                  # Prompt documentation (6 files)
│   └── archive/                  # Archived documentation
│       ├── implementation-summaries/
│       └── session-problems/
├── tools/                        # Development and maintenance tools
│   ├── data-generation/          # Data builders (build-*.js, extract-*.js)
│   ├── validation/               # Validators (check-*.js, verify-*.js)
│   ├── code-generation/          # Code generators (update-*.js)
│   ├── generators/               # Template generators (generate-*.js, create-*.js)
│   ├── testing/                  # Test helper scripts
│   └── archive/                  # Archived tools
│       └── debug-scripts/
├── templates/                    # Code templates
│   ├── bas/                      # QB64PE code templates
│   │   └── enhanced-debugging-template.bas
│   └── example-claude-config.json
├── coverage/                     # Test coverage reports (generated)
├── qb64pe-logs/                  # QB64PE execution logs (runtime)
├── qb64pe-screenshots/           # Screenshot captures (runtime)
├── .vscode/                      # VS Code workspace settings
├── jest.config.js                # Jest test configuration
├── tsconfig.json                 # TypeScript configuration
├── package.json                  # Node.js dependencies and scripts
├── CONFIGURATION.md              # MCP server configuration guide
└── README.md                     # This file

______________________________________________________________________

📋 工具快速参考

🚀 Advanced Debugging & Automation (12 tools)

🔄 QBasic to QB64PE Porting (3 tools)

📖 Wiki & Documentation (3 tools)

🛠️ Compiler & Development (4 tools)

✅ Syntax & Compatibility (3 tools)

🔍 Keywords Reference (6 tools)

⚡ Execution Monitoring & Process Management (7 tools)

📷 Screenshot & Graphics Analysis (8 tools)

🔧 Installation & Setup (6 tools)

______________________________________________________________________

🎯 提示快速参考

______________________________________________________________________

🚀 主要特点

🔍 关键发现：$CONSOLE指令策略

' For TEXT-ONLY programs (no graphics):
$CONSOLE:ONLY  ' Console-only mode, enables shell redirection

' For GRAPHICS programs (SCREEN modes, _NEWIMAGE):
$CONSOLE       ' Dual console+graphics, use ECHO functions for output
' ECHO functions handle _DEST management automatically

影响:

• $CONSOLE:ONLY：纯文本程序，最适合stdio重定向
• $CONSOLE +ECHO：图形程序、ECHO功能可实现自动输出捕获
• 两者都使用： program.exe > output.txt 2>&1

📊 现实世界的成功：高级调试系统

=== PROGRAM ANALYSIS ===
Program: ASEPRITE ZLIB Analyzer
Expected: 82944 bytes

=== STEP 1: HEADER VALIDATION ===
INFO: ZLIB header validation completed
CMF: 120, FLG: 156 - Valid header

=== STEP 2: DEFLATE PARSING ===
ERROR: Dynamic Huffman decoder incomplete
Only 51 bytes decoded (0.06% of expected)

=== RESULTS SUMMARY ===
FAILED: Incomplete DEFLATE implementation
Auto-exiting in 10 seconds...

• ✅ 找到根本原因：动态霍夫曼解码器不完整
• ✅ 精确指标：51字节，而预期为82944字节（0.06%）
• ✅ 自动化工作流程：无需人工干预
• ✅ 结构化输出：易于解析LLM分析

🎯 大猩猩。BAS移植成功

• 源：1136行QBasic→ 输出：1119线QB64PE
• 变换：成功应用了13种主要模式
• 关键词：908次成功转换为Pascal Case
• 兼容性：高评级-准备编译
• 自动化：99%以上的自动化，只需要最少的手动审查

______________________________________________________________________

📚 Documentation Structure

\[文件\] 工具文档

每个工具都有全面的文档 docs/tools/:

• 概述：目的和能力
• 参数：输入参数和选项
• 退货：输出格式和示例
• 用例：常见场景和应用
• 例子：实际使用示例
• 相关工具：交叉引用和工作流程

🎯 及时记录

每个提示都有详细的指导 docs/prompts/:

• 概述：目的和功能迅速
• 参数：输入要求和选项
• 生成的响应：预期输出格式
• 例子：示例使用场景
• 相关提示：交叉引用和工作流程

📚 核心文件

综合指南 docs/:

• QB64PE调试增强系统
• QB64PE执行监控
• QB64PE图形报表指南
• Pixel完美绘图指南 - 新 透明度、角平滑、画布状态图案
• LLM使用指南
• 兼容性集成指南
• 关键词集成指南

📑 API和参考文件

中的API详细参考资料 docs/api/:

• 服务API参考
• MCP工具参考

📝 示例和教程

实际示例 docs/examples/:

• 工具示例

🚀 功能文档

中的特定功能文档 docs/features/:

• 新工具README

💡 Example Workflows

🤖 自主编译验证修复循环 ⭐ 新

// The agent autonomously fixes compilation errors without human intervention
async function autonomousPorting(qbasicFile, outputFile) {
  // 1. Port QBasic to QB64PE
  const ported = await portQbasicToQb64pe({
    sourceCode: await readFile(qbasicFile),
    sourceDialect: "qbasic",
  });

  await writeFile(outputFile, ported.convertedCode);

  // 2. Autonomous compilation loop - NO HUMAN INTERVENTION NEEDED
  let iteration = 0;
  while (iteration  output.txt 2>&1`)用于自动化工作流程
- **结构化输出生成** -为系统分析创建有组织的调试部分
- **自动退出机制** -防止自动LLM工作流中的无限等待
- **真实世界证明** -成功诊断出ASEPRITE ZLIB解压缩问题等复杂问题
- **跨平台监控** -Windows、Linux、macOS进程和文件监控命令
- **高级模板生成** -创建具有内置日志记录和错误处理功能的全面调试程序

### 📖 **Wiki集成**

- 搜索QB64PE官方维基(https://qb64phoenix.com/qb64wiki/)
- 使用格式化的示例检索完整的页面内容
- 智能缓存系统，提高性能
- 全面结果的回退搜索机制

### 🛠️ **编译器帮助**

- 完整的QB64PE编译器选项参考（-c、-x、-o、-z、-g、-w）
- 特定于平台的编译指南（Windows、macOS、Linux）
- 优化建议和构建策略
- 跨平台兼容性见解

### 🐛 **增强的调试支持**

- **本地日志集成** -\_LOGINFO、\_LOGERROR、\_LOGWARN、\_LOGTRACE函数
- **结构化调试部分** -系统分析的有组织输出
- **$CONSOLE：仅限管理** -用于shell重定向的正确控制台指令
- **自动退出机制** -基于超时的程序终止以实现自动化
- **资源跟踪** -文件句柄和图形上下文管理
- **错误检测和清理** -全面的错误处理和资源清理
- **模板生成** -具有内置监控功能的高级调试模板
- **输出解析** -程序执行结果的结构化分析

### ✅ **语法验证和兼容性**

- 仅QB64PE语法强制（不包括Visual Basic/QBasic构造）
- 全面的兼容性验证，并提供详细的问题报告
- 多级验证（基本、严格、最佳实践）
- 实时错误检测和建议
- 代码质量评分（0-100）
- 跨平台兼容性检查
- 传统BASIC关键字检测
- 平台特定功能警告
- **变量范围验证** （DIM共享，范围访问问题）
- **动态数组指令检查** （$DYNAMIC用法）
- **SHARED关键字语法验证**
- **可变阴影检测**

### \[设置\] **可变范围界定助手**

- **DIM共享使用验证** -确保变量在过程之间正确共享
- **$DYNAMIC指令检查** -验证动态数组声明
- **范围访问分析** -检测在没有正确SHARED声明的情况下访问的变量
- **可变阴影警告** -识别可能影响全局变量的局部变量
- **最佳实践指南** -推荐适当的变量范围界定技术
- **真实世界的例子** -提供正确和不正确的使用模式

### 🔍 **兼容性知识库**

- 广泛的兼容性问题数据库
- 可搜索的解决方案和变通方法
- 基于模式的代码分析
- 最佳实践指南
- QB64PE特有的调试技术
- 平台兼容性矩阵（Windows/Linux/macOS）

### \[文件\] **关键词参考系统**

- 完整的QB64PE关键词库（800+关键词）
- 智能分类（语句、函数、运算符、元命令、OpenGL、类型、遗留）
- 具有智能建议的实时关键字验证
- 部分关键字的自动补全支持
- 跨关键字定义和示例的全文搜索
- 版本兼容性检查（QBasic vs QB64 vs QB64PE）
- 平台可用性信息
- 语法示例和相关关键字建议

### 📚 **资源和提示**

- 快速访问QB64PE编译器参考
- 常见语法模式和示例
- 带有重点领域的代码审查模板
- 入门指南和教程

📦 Installation

### 先决条件

- Node.js 18或更高版本
- npm或yarn包管理器

### 设置

1. 克隆存储库：

git clone cd qb64pe-mcp-server

2. 安装依赖项：

npm install

3. 构建TypeScript代码：

npm run build

4. 启动MCP服务器：

npm start

服务器将输出： `QB64PE MCP Server started successfully`

## 用法

### 作为MCP服务器

该服务器实现了模型上下文协议，可以与任何兼容MCP的AI助手或应用程序一起使用。

#### Claude桌面配置

将此配置添加到您的Claude Desktop设置中：

{ "mcpServers": { "qb64pe": { "command": "node", "args": ["path/to/qb64pe-mcp-server/build/index.js"], "env": {} } } }

#### 其他MCP客户端的配置

使用标准MCP连接格式：

- **运输**标准： stdio
- **命令**: `node build/index.js`
- **工作目录**：此项目的路径

## 可用工具

### 1. `search_qb64pe_wiki`

在QB64PE wiki上搜索有关函数、语句和概念的信息。

**论据：**

- `query` （string）：搜索词
- `maxResults` （数字，可选）：返回的最大结果数（默认值：5）

**例子：**

{ "query": "_RGB32 color functions", "maxResults": 3 }

### 2. `get_qb64pe_page`

检索特定QB64PE维基页面的完整内容。

**论据：**

- `pageTitle` （string）：维基页面的确切标题

**例子：**

{ "pageTitle": "_RGB32" }

### 3. `get_compiler_options`

获取有关QB64PE编译器选项和使用方法的详细信息。

**论据：**

- `option` （string，可选）：要了解的特定编译器选项
- `platform` （字符串，可选）：目标平台（windows、macos、linux）

**例子：**

{ "option": "-c", "platform": "windows" }

### 4. `validate_qb64pe_syntax`

验证QB64PE代码语法并获得改进建议。

**论据：**

- `code` （string）：要验证的QB64PE代码
- `checkLevel` （字符串，可选）：验证级别（基本、严格、最佳实践）

**例子：**

{ "code": "PRINT \"Hello World\"\\nINPUT \"Your name: \", name$", "checkLevel": "strict" }

### 5. `get_debugging_help`

获取调试QB64PE程序的帮助。

**论据：**

- `issue` （string）：调试问题的描述
- `platform` （字符串，可选）：目标平台

**例子：**

{ "issue": "Program crashes when reading file", "platform": "windows" }

### 6. `validate_qb64pe_compatibility`

检查QB64PE兼容性问题的代码，并提供详细的解决方案。

**论据：**

- `code` （string）：QB64PE代码，用于检查兼容性问题
- `platform` （字符串，可选）：目标平台（windows、macos、linux、全部）

**例子：**

{ "code": "FUNCTION Test(x AS INTEGER) AS INTEGER\\n Test = x * 2\\nEND FUNCTION", "platform": "all" }

### 7. `search_qb64pe_compatibility`

搜索兼容性问题、解决方案和最佳实践。

**论据：**

- `query` （string）：兼容性知识搜索查询
- `category` （字符串，可选）：特定兼容性类别

**类别：**

- `function_return_types`：函数声明问题
- `console_directives`：控制台模式问题
- `multi_statement_lines`：多语句语法问题
- `array_declarations`：数组声明限制
- `missing_functions`：不存在的功能
- `legacy_keywords`：不支持的旧版关键字
- `device_access`：硬件/设备访问问题
- `platform_specific`：平台兼容性
- `best_practices`：编码指南
- `debugging`：调试技术

**例子：**

{ "query": "function return type sigil", "category": "function_return_types" }

### 8. `get_qb64pe_best_practices`

获取QB64PE开发的最佳实践和编码指南。

**论据：**

- `topic` （字符串，可选）：最佳实践的特定主题

**话题：**

- `syntax`：语言语法指南
- `debugging`：调试最佳实践
- `performance`：性能优化
- `cross_platform`：跨平台开发
- `code_organization`：代码结构和组织

**例子：**

{ "topic": "debugging" }

### 9. `lookup_qb64pe_keyword`

获取特定QB64PE关键字的详细信息。

**论据：**

- `keyword` （string）：要查找的QB64PE关键字

**例子：**

{ "keyword": "PRINT" }

### 10. `autocomplete_qb64pe_keywords`

获取QB64PE关键字的自动补全建议。

**论据：**

- `prefix` （string）：要自动完成的部分关键字
- `maxResults` （数字，可选）：建议的最大数量（默认值：10）

**例子：**

{ "prefix": "_MOU", "maxResults": 5 }

### 11. `get_qb64pe_keywords_by_category`

获取特定类别中的所有关键字。

**论据：**

- `category` （string）：要检索的关键字类别

**类别：**

- `statements`：执行操作的QB64PE语句
- `functions`：返回值的QB64PE函数
- `operators`：数学和逻辑运算符
- `metacommands`：以开头的编译器指令$
- `opengl`：OpenGL图形函数和语句
- `types`：数据类型和类型后缀
- `constants`：内置常量和文字
- `legacy`：传统QBasic关键字和兼容性项目

**例子：**

{ "category": "functions" }

### 12. `search_qb64pe_keywords`

按名称、描述或功能搜索QB64PE关键字。

**论据：**

- `query` （string）：关键字搜索查询
- `maxResults` （数字，可选）：最大结果数（默认值：20）

**例子：**

{ "query": "mouse position", "maxResults": 10 }

### 13. `analyze_qb64pe_execution_mode`

分析QB64PE源代码，确定执行特性和监控要求。

**论据：**

- `sourceCode` （string）：QB64PE源代码解析

**返回执行状态和监控指南：**

- 程序类型（图形、控制台、混合）
- LLM的超时建议
- 监控策略
- 屏幕截图和日志记录要求

**例子：**

{ "sourceCode": "SCREEN _NEWIMAGE(800, 600, 32)\\nDO\\n _LIMIT 60\\nLOOP" }

### 14. `get_process_monitoring_commands`

获取用于监视QB64PE进程的跨平台命令。

**论据：**

- `processName` （字符串，可选）：要监视的进程名称（默认值：“qb64pe”）
- `platform` （字符串，可选）：目标平台（windows、linux、macos、current）

**例子：**

{ "processName": "qb64pe", "platform": "windows" }

### 15. `generate_monitoring_template`

生成内置日志记录、屏幕截图和执行监控的QB64PE代码模板。

**论据：**

- `originalCode` （string）：原始QB64PE代码，用于包裹监控

**例子：**

{ "originalCode": "PRINT \"Hello World\"\\nFOR i = 1 TO 5\\n PRINT i\\nNEXT i" }

### 16. `generate_console_formatting_template`

生成具有增强控制台输出格式的QB64PE模板，以更好地进行终端解析。

**论据：** 无

**退货：** 带有颜色编码控制台输出功能的模板代码

### 17. `get_execution_monitoring_guidance`

获取监控QB64PE程序执行的全面指导，包括LLM超时策略。

**论据：** 无

**退货：** 执行监控最佳实践的详细降价指南

### 18. `parse_console_output`

解析QB64PE控制台输出，检测完成信号、输入提示和执行状态。

**论据：**

- `output` （string）：要解析的控制台输出

**例子：**

{ "output": "Processing complete.\\nPress any key to continue..." }

### 19. `get_file_monitoring_commands`

获取用于监视QB64PE日志文件和输出的跨平台命令。

**论据：**

- `logFile` （string）：要监视的日志文件的路径

**例子：**

{ "logFile": "qb64pe-logs/execution_timestamp.log" }

## 可用资源

### 1. `qb64pe://wiki/search`

基于URI访问wiki搜索功能。

### 2. `qb64pe://compiler/reference`

所有QB64PE编译器选项和标志的快速参考。

### 3. `qb64pe://compatibility/`

全面的兼容性文档和问题解决方案。

### 4. `qb64pe://keywords/`

完成QB64PE关键字参考，包括分类和搜索。

### 5. `qb64pe://keywords/category/{category}`

按特定类别（语句、函数、运算符等）过滤的关键字。

### 6. `qb64pe://keywords/detail/{keyword}`

有关特定QB64PE关键字的详细信息。

### 7. `qb64pe://execution/monitoring`

用于监控QB64PE程序执行、进程管理和LLM超时策略的综合指南。

## 可用提示

### 1. `analyze-compilation-error` ⭐ 新

用于分析和修复QB64PE编译错误的自主模板。

**论据：**

- `errorOutput` （string）：包含编译错误的终端输出
- `sourceFile` （string）：QB64PE源文件的路径
- `sourceCode` （字符串，可选）：QB64PE源代码（如果可用）

**为以下内容提供自主指导：**

- 错误模式识别（语法、类型、声明、结构错误）
- 工具决策矩阵映射错误
- 自主修复工作流程（无需用户确认）
- 迭代编译-验证-修复循环（最多5次迭代）
- 基于上下文的建议和修复

**主要特点：** 强调“不要要求用户确认——自主行动！”

### 2. `review-qb64pe-code`

QB64PE代码综合评审模板。

**论据：**

- `code` （string）：待审核的QB64PE代码
- `focusAreas` （字符串，可选）：逗号分隔的焦点区域

**重点领域：**

- `syntax`：语言语法和结构
- `performance`：优化机会
- `best-practices`：代码质量和可维护性
- `cross-platform`：平台兼容性
- `debugging`：调试和故障排除

### 2. `monitor-qb64pe-execution`

用于监控QB64PE程序执行超时策略的模板。

**论据：**

- `sourceCode` （string）：QB64PE源代码解析
- `expectedBehavior` （字符串，可选）：预期的程序行为
- `platform` （字符串，可选）：目标平台（windows、macos、linux）

**为以下方面提供指导：**

- 程序类型分析（图形、控制台、混合）
- LLM的执行超时建议
- 过程监控策略
- 控制台输出解析指南
- 屏幕截图/日志记录建议
- 何时移交给人际互动

## 建筑

### 核心组件

- **MCP 服务器**：主服务器处理工具/资源注册
- **Wiki服务**：QB64PE wiki与缓存集成
- **编译器服务**：编译器选项和平台指南
- **语法服务**：QB64PE语法验证和分析
- **兼容性服务**：兼容性知识和验证
- **关键词服务**：关键词参考和验证
- **执行服务**：程序执行监控和流程管理
- **搜索服务**：跨兼容性内容的语义搜索

### 服务详细信息

#### Wiki服务(`WikiService`)

- 使用MediaWiki API搜索QB64PE wiki
- 提取和格式化页面内容
- 缓存性能结果
- 提供回退搜索机制

#### 编译器服务(`CompilerService`)

- 全面的编译器选项数据库
- 平台特定编译说明
- 调试技术建议
- 跨平台开发指导

#### 语法服务(`QB64PESyntaxService`)

- 多级语法验证
- 仅QB64PE语法强制
- 错误检测和纠正建议
- 代码质量评分系统
- 兼容性问题检测

#### 兼容性服务(`QB64PECompatibilityService`)

- 全面的兼容性验证
- 知识库搜索与检索
- 最佳实践指南
- 平台兼容性检查
- 遗留关键字检测
- 函数返回类型验证

#### 搜索服务(`CompatibilitySearchService`)

- 全文搜索索引
- 基于术语的相关性评分
- 类别和标签过滤
- 语义搜索功能

#### 执行服务(`QB64PEExecutionService`)

- 程序执行类型检测（图形、控制台、混合）
- LLM超时策略建议
- 跨平台过程监控命令
- 控制台输出解析和完成信号检测
- 使用自动生成屏幕截图 `_SAVEIMAGE`
- 增强的日志记录和监控模板生成
- 控制台输出格式，以便更好地解析
- 实时日志文件监控实用程序
- 跨平台的流程终止策略

🛠️ Development

### 建筑

npm run build

### 测试

npm test

### 发展模式

npm run dev

### 代码结构

src/ ├── index.ts # Main MCP server ├── services/ │ ├── wiki-service.ts # QB64PE wiki integration │ ├── compiler-service.ts # Compiler assistance │ ├── syntax-service.ts # Syntax validation │ ├── compatibility-service.ts # Compatibility validation │ ├── keywords-service.ts # Keywords reference and validation │ ├── execution-service.ts # Program execution monitoring │ └── search-service.ts # Search indexing ├── data/ │ ├── compatibility-rules.json # Structured compatibility rules │ └── keywords-data.json # Enhanced keywords database └── types/ # TypeScript type definitions

## 文档

### 🚀 **新的调试和自动化指南**

- [QB64PE调试增强系统](docs/QB64PE_DEBUGGING_ENHANCEMENT_SYSTEM.md) -高级调试系统的完整指南
- [QB64PE测井服务指南](docs/QB64PE_LOGGING_SERVICE_GUIDE.md) -全面的本地日志服务文档
- [日志服务实施摘要](docs/LOGGING_SERVICE_IMPLEMENTATION_SUMMARY.md) -实施总结和成功指标
- [LLM使用指南](docs/LLM_USAGE_GUIDE.md) -LLM如何使用MCP服务器工具和工作流
- [LLM连接示例](docs/LLM_CONNECTION_EXAMPLES.md) -将LLM连接到MCP服务器的配置示例

### 📚 **核心开发指南**

- [执行监控指南](docs/QB64PE_EXECUTION_MONITORING.md) -监控QB64PE程序执行、进程管理和LLM超时策略的综合指南
- [执行监控示例](docs/EXECUTION_MONITORING_EXAMPLES.md) -执行监控功能的实际示例和使用模式
- [兼容性集成指南](docs/COMPATIBILITY_INTEGRATION.md) -兼容性验证系统的详细文档
- [关键词集成指南](docs/KEYWORDS_INTEGRATION.md) -关键词参考系统综合指南
- [可变范围界定规则](docs/VARIABLE_SCOPING_RULES.md) -DIM SHARED、$DYNAMIC和变量作用域的完整指南

### 🌐 **外部资源**

- [QB64PE官方维基](https://qb64phoenix.com/qb64wiki/) -QB64PE官方文件

📝 Examples

### 示例1：搜索图形函数

// Using the search_qb64pe_wiki tool { "query": "_PUTIMAGE graphics drawing", "maxResults": 3 }

### 示例2：验证代码语法

// Using the validate_qb64pe_syntax tool { "code": DIM x AS INTEGER FOR x = 1 TO 10 PRINT "Number: "; x NEXT x, "checkLevel": "best-practices" }

### 示例3：获取调试帮助

// Using the get_debugging_help tool { "issue": "Variables showing wrong values in loop", "platform": "windows" }

### 示例4：检查兼容性问题

// Using the validate_qb64pe_compatibility tool { "code": "FUNCTION Test(x AS INTEGER) AS INTEGER\\n Test = x * 2\\nEND FUNCTION", "platform": "all" }

### 示例5：搜索兼容性知识

// Using the search_qb64pe_compatibility tool { "query": "console directive", "category": "console_directives" }

### 示例6：分析程序执行模式

// Using the analyze_qb64pe_execution_mode tool { "sourceCode": "SCREEN _NEWIMAGE(800, 600, 32)\\nDO\\n WHILE _MOUSEINPUT\\n IF _MOUSEBUTTON(1) THEN CLS\\n WEND\\n _LIMIT 60\\nLOOP" }

// Result indicates graphics program that will wait indefinitely for user input // LLM should timeout after 30-60 seconds and hand over to human

### 示例7：生成监控模板

// Using the generate_monitoring_template tool { "originalCode": "PRINT \"Processing data...\"\\nFOR i = 1 TO 100\\n PRINT \"Item\"; i\\nNEXT i" }

// Returns enhanced code with automatic logging, screenshots, and progress tracking

### 示例8：解析控制台输出

// Using the parse_console_output tool { "output": "Processing complete.\\nPress any key to continue..." }

// Result: {"isWaitingForInput": true, "isCompleted": true, "suggestedAction": "requires_user_input"}

### 示例9：增强代码调试（新增！）

// Using the enhance_qb64pe_code_for_debugging tool { "sourceCode": "PRINT \"Hello\"\\nFOR i = 1 TO 10\\n PRINT i\\nNEXT", "config": { "enableConsole": true, "enableLogging": true, "enableFlowControl": true, "timeoutSeconds": 30, "autoExit": true } }

// Returns enhanced code with console management, logging, auto-exit, and resource tracking

### 示例10：原生日志注入（新增！）

// Using the inject_native_qb64pe_logging tool { "sourceCode": "PRINT \"Processing data\"\\nFOR i = 1 TO 100\\n PRINT i\\nNEXT", "config": { "consoleDirective": "$CONSOLE:ONLY", // Critical for shell redirection! "enableNativeLogging": true, "enableStructuredOutput": true } }

// Returns code with _LOGINFO, _LOGERROR functions and structured sections

### 示例11：高级调试模板（新增！）

// Using the generate_advanced_debugging_template tool { "programName": "Data Analyzer", "analysisSteps": ["Header Validation", "Data Processing", "Results Summary"], "config": { "consoleDirective": "$CONSOLE:ONLY", "enableNativeLogging": true, "autoExitTimeout": 15 } }

// Returns complete debugging program with systematic analysis structure

### 示例12：解析结构化输出（新增！）

// Using the parse_qb64pe_structured_output tool { "output": "=== PROGRAM ANALYSIS ===\\nProgram: Test\\n=== STEP 1: VALIDATION ===\\nINFO: Validation completed\\n=== RESULTS SUMMARY ===\\nSUCCESS: All steps completed" }

// Returns structured analysis with sections, logs, execution status, and completion rate

🤝 Contributing

1. 分叉存储库
1. 创建要素分支： `git checkout -b feature-name`
1. 进行更改并添加测试
1. 构建和测试： `npm run build && npm test`
1. 提交拉取请求

## 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

## 支持

- QB64PE官方网站：https://qb64phoenix.com/
- QB64PE维基：https://qb64phoenix.com/qb64wiki/
- QB64PE论坛：https://qb64phoenix.com/forum/

## 更新日志

### v2.0.1-兼容性规则更正和智能关键字查找（2026年1月21日）

#### 兼容性更正

- **🔧 纠正**：布尔常量验证-\_TRUE和_FALSE是保留字（始终可用）
- **🔧 纠正**：DECLARE语句验证-DECLARE仅适用于C库导入，不适用于子程序/函数
- **📚 更新**：知识库现在正确反映了QB64PE语言事实
- **✅ 改进**：使用正确的布尔值和DECLARE指南更新了最佳实践
- **📖 文档**：已创建.github/reductions/project-conventions.enstructions.md以供将来参考
- **🎯 经验教训**：在操作MCP服务器本身时，始终使用MCP工具进行验证

#### 智能关键词查询系统

- **✨ 新**: `lookup_qb64pe_keyword` 现在包括智能回退搜索
- **🔍 明智的**：未找到关键字时自动推断语义术语
- **📚 自动**：执行相关搜索（例如，TRUE/FALSE→ 搜索“boolean”、“常量”）
- **🌐 维基**：生成用于手动验证的直接wiki搜索URL
- **💡 提示**：提供上下文建议和搜索策略
- **🤖 LLM**：针对自主代理工作流进行了优化

支持的语义类别：

- 布尔值(`true`/`false` → `BOOLEAN`, `CONSTANTS`)
- 图形(`screen`/`pixel`/`draw` → `SCREEN`, `GRAPHICS`, `_DISPLAY`)
- 文件I/O(`file`/`open`/`read` → `OPEN`, `FILE`, `INPUT`, `OUTPUT`)
- 字符串(`string`/`text`/`chr` → `STRING`, `CHR$`, `ASC`)
- 数学(`sin`/`cos`/`sqrt` → `SIN`, `COS`, `SQR`, `ABS`)
- 声音(`sound`/`audio`/`play` → `SOUND`, `PLAY`, `_SNDOPEN`)

基于QB64PE实际行为的关键修正：

- \_TRUE和_FALSE是保留字，始终可用（非用户定义）
- TRUE/FALSE可以由用户定义，但不是内置的
- DECLARE仅适用于DECLARE库（C函数导入）
- QB64PE自动处理所有子/功能转发引用
- 任何QB64PE程序都不需要声明

### v2.0.0-高级调试和自动化版本

- **🚀 重大**：高级调试增强系统，具有全面的代码修复功能
- **🚀 重大**：具有_LOGINFO、\_LOGERROR等功能的原生QB64PE日志记录服务。
- **🔍 关键发现**：$CONSOLE:仅与$CONSOLE兼容外壳重定向
- **新**: `enhance_qb64pe_code_for_debugging` -全面的调试增强功能
- **新**: `inject_native_qb64pe_logging` -使用适当的控制台指令进行本地日志注入
- **新**: `generate_advanced_debugging_template` -高级调试模板
- **新**: `parse_qb64pe_structured_output` -结构化输出分析
- **新**: `generate_output_capture_commands` -跨平台监控命令
- **新**: `get_qb64pe_debugging_best_practices` -调试最佳实践
- **新**: `get_llm_debugging_guide` -LLM特定调试指导
- **增强**：自动化工作流的Shell重定向兼容性
- **增强**：用ASEPRITE ZLIB分析成功案例进行真实世界测试
- **增强**：用于系统分析的结构化调试部分
- **增强**：LLM自动化兼容性的自动退出机制
- **增强**：资源跟踪和清理管理
- **增强**：跨平台输出捕获和监控

### v1.0.0

- 初始版本
- Wiki搜索和页面检索
- 编译器选项参考
- 语法验证系统
- 调试辅助工具
- 跨平台支持指导
- **新**：全面的兼容性验证
- **新**：与搜索的兼容性知识库
- **新**：最佳做法指导制度
- **新**：平台特定兼容性检查
- **新**：传统BASIC关键字检测
- **新**：函数返回类型验证
- **新**：变量作用域验证（DIM SHARED、SHARED语法）
- **新**：动态数组指令检查（$Dynamic）
- **新**：可变可访问性分析
- **新**：可变阴影检测
- **新**：特定范围的调试指导
- **新**：程序执行监控和超时策略
- **新**：跨平台进程监控命令
- **新**：完成信号的控制台输出解析
- **新**：使用_SAVEIMAGE自动生成屏幕截图
- **新**：增强的日志记录和监控模板
- **新**：实时日志文件监控实用程序
- **新**：图形程序的LLM超时建议