MCP Confluence Server

# Confluence 宏处理功能实现计划 ## 阶段一：基础架构（已完成） - [x] 1. 创建 HTML 解析器适配器基础设施 - 创建 HTMLParserAdapter 接口定义，支持 Node.js 和浏览器环境 - 实现 NodeHTMLParserAdapter 使用 jsdom 库进行 HTML 解析 - 实现 BrowserHTMLParserAdapter 使用原生 DOM API - 添加环境检测逻辑，自动选择合适的解析器适配器 - 编写适配器的单元测试，确保在不同环境下正常工作 - _需求: 2.1, 2.2, 2.3_ - [x] 2. 创建宏处理核心类型定义和基础架构 - 创建 `src/types/macro.types.ts` 文件，定义所有宏相关的接口和枚举 - 实现 MacroInfo、MacroParameters、MacroProcessingContext 等核心接口 - 定义 MacroFallbackStrategy、MacroErrorType 等枚举类型 - 扩展 MacroProcessingResult 包含回退策略和统计信息 - 添加递归深度控制和循环引用检测的类型定义 - _需求: 1.1, 2.1, 3.1, 4.1, 5.1, 6.1, 7.1, 8.1_ - [x] 3. 实现基础宏处理器抽象类 - 创建 `src/services/macro-processors/base-macro-processor.ts` 文件 - 实现 BaseMacroProcessor 抽象类，定义宏处理器的通用接口 - 实现 extractMacroParameters 和 generateFallbackContent 等通用方法 - 添加错误处理和日志记录功能 - 实现宏参数的注释化保留功能 - _需求: 6.1, 6.2, 6.3, 7.1, 7.2_ - [x] 4. 创建宏注册器和配置管理系统 - 创建 `src/services/macro-registry.ts` 文件，实现宏处理器注册和查找机制 - 创建 `src/services/macro-config.service.ts` 文件，实现配置加载和管理 - 创建默认配置文件 `.macro-config.json` - 实现配置验证和错误处理逻辑 - 支持黑名单配置和插件式扩展 - _需求: 7.4, 7.5, 8.2, 8.4, 8.5_ ## 阶段二：紧急 Bug 修复（高优先级 - 解决导出只显示"INLINE"问题） - [x] 5. 诊断和修复导出内容丢失问题 - 分析当前导出流程，确定内容丢失的具体环节 - 检查页面内容获取是否正确返回 HTML 内容 - 验证 HTML 到 Markdown 转换过程是否保留内容 - 检查宏处理过程是否正确提取和转换内容 - 添加详细的调试日志记录每个转换步骤 - 确保最终写入文件包含完整内容而不仅仅是"INLINE"字符串 - _需求: 导出bug修复 1.1, 1.2, 1.3, 1.4, 1.5, 3.1, 3.2, 3.3, 3.4_ - [ ] 6. 修复 Markdown 宏的 CDATA 内容提取 - 检查现有 MarkdownMacroProcessor 的 CDATA 提取逻辑 - 修复 extractCDATAContent 方法，确保正确解析包装内容 - 处理 atlassian-macro-output-type 参数的 INLINE/BLOCK 模式 - 验证 INLINE 模式不会导致内容丢失 - 添加内容长度和格式的验证检查 - 测试包含表格和复杂格式的 Markdown 宏处理 - _需求: 导出bug修复 2.1, 2.2, 2.3, 3.1, 3.2, 3.3_ - [ ] 7. 增强导出流程的错误处理和日志记录 - 在导出服务中添加详细的步骤日志记录 - 记录页面内容获取的响应结构和大小 - 记录宏处理前后的内容长度变化 - 记录 HTML 到 Markdown 转换的详细信息 - 添加内容验证检查，确保每步都有实际内容 - 实现错误恢复机制，防止部分失败导致整体失败 - _需求: 导出bug修复 3.1, 3.2, 3.3, 3.4, 5.1, 5.2, 5.3, 5.4, 5.5_ - [ ] 8. 验证和测试导出修复结果 - 使用包含 Markdown 宏的真实页面进行测试 - 验证导出的 Markdown 文件包含完整内容 - 测试不同类型的页面内容（纯文本、HTML、宏混合） - 验证内容统计信息的准确性 - 测试错误场景的处理和恢复 - 确保修复不影响其他导出功能 - _需求: 导出bug修复 4.1, 4.2, 4.3, 4.4, 6.1, 6.2, 6.3, 6.4, 6.5_ ## 阶段三：核心宏处理器扩展（中优先级 - 基于真实页面使用） - [x] 9. 实现专门的 Markdown 宏处理器（已完成基础版本） - 创建 MarkdownMacroProcessor 类继承 BaseMacroProcessor - 实现 CDATA 内容提取逻辑，正确解析包装的内容 - 处理 atlassian-macro-output-type 参数（INLINE/BLOCK） - 添加 Markdown 内容清理和格式化 - 支持内联模式的换行符处理 - _需求: 3.1, 3.2, 3.3_ - [x] 10. 使用真实页面测试和优化 Markdown 宏处理器（已完成基础测试） - 使用页面 ID 104762256 ("数据防篡改签名方案") 作为测试用例 - 验证 INLINE 模式 Markdown 宏的处理效果 - 测试包含表格的复杂 Markdown 内容转换 - 验证 CDATA 内容提取的准确性 - 测试长文档的 Markdown 宏处理性能 - 确保表格格式在转换后保持可读性 - _需求: 3.1, 3.2, 3.3_ - [ ] 11. 增强 Markdown 宏处理器的表格支持 - 改进 Markdown 表格格式的识别和处理 - 优化表格对齐和格式化逻辑 - 处理复杂表格结构（如嵌套内容） - 添加表格格式验证和修复功能 - 支持表格标题和说明的处理 - 测试各种表格样式的转换效果 - _需求: 3.4, 3.5_ - [ ] 12. 优化 INLINE 模式的内容处理 - 改进 INLINE 模式下的换行符处理逻辑 - 优化长内容在内联模式下的显示效果 - 处理 INLINE 模式下的表格显示问题 - 添加内容长度限制和截断功能 - 改进内联模式的可读性 - 测试各种内容类型在内联模式下的效果 - _需求: 3.2, 3.3_ - [ ] 13. 修复宏处理器服务的 DOM 解析问题 - 在 MacroProcessorService 中集成 HTMLParserAdapter - 替换 parseHTML 方法使用适配器，解决 Node.js 环境问题 - 替换 domToHTML 方法使用适配器 - 添加 DOM 解析失败的错误处理和恢复机制 - 实现 HTML 解析错误的自动修复功能 - _需求: 2.1, 2.2, 2.3, 7.1_ - [ ] 14. 创建基于真实页面的集成测试套件 - 创建包含页面 104762256 内容的测试用例 - 建立真实页面内容的回归测试 - 验证 Markdown 宏在不同输出模式下的表现 - 测试包含中文内容的宏处理 - 创建性能基准测试 - 建立内容质量评估标准 - _需求: 1.1, 1.2, 3.1_ ## 阶段四：常用宏处理器 - [ ] 15. 实现代码宏处理器 - 创建 `src/services/macro-processors/code-macro-processor.ts` 文件 - 实现代码宏的识别逻辑，支持各种代码宏格式 - 实现语言类型提取和语法高亮信息保留 - 支持代码标题、行号、折叠等功能的转换 - 将代码宏转换为 markdown 围栏代码块格式 - 在代码块前添加标题注释说明 - _需求: 1.4, 1.5_ - [ ] 16. 实现信息类宏处理器 - 创建 `src/services/macro-processors/info-macro-processor.ts` 文件 - 实现 info、warning、note、error、tip 等信息宏的识别 - 实现不同信息类型到 markdown 引用块的转换 - 为不同类型的信息宏添加相应的图标 - 支持信息宏标题和复杂内容的递归处理 - _需求: 2.4_ - [ ] 17. 实现表格宏处理器 - 创建 `src/services/macro-processors/table-macro-processor.ts` 文件 - 实现简单表格到 markdown 表格的转换逻辑 - 检测复杂表格特性（合并单元格、排序等） - 对复杂表格保留 HTML 格式并添加说明 - 处理表格数据来源和引用链接 - _需求: 3.4, 3.5_ - [ ] 18. 实现图表宏处理器 - 创建 `src/services/macro-processors/chart-macro-processor.ts` 文件 - 实现流程图到 mermaid 格式的转换逻辑 - 实现甘特图到 mermaid 格式的转换 - 处理无法转换的图表，导出为图片链接 - 添加图表功能说明和原始数据链接 - 为复杂图表数据提供附件或链接 - _需求: 4.1, 4.2, 4.3, 4.4, 4.5_ - [ ] 19. 实现页面包含和引用宏处理器 - 创建 `src/services/macro-processors/include-macro-processor.ts` 文件 - 实现页面包含宏的内容获取和嵌入逻辑 - 实现页面引用宏到 markdown 链接的转换 - 添加递归深度限制和循环引用检测 - 处理权限错误和页面不存在的情况 - 支持递归处理被包含页面中的宏 - _需求: 5.1, 5.2, 5.3, 5.4, 5.5_ - [ ] 20. 实现自定义和未知宏处理器 - 创建 `src/services/macro-processors/custom-macro-processor.ts` 文件 - 实现未知宏的识别和基础处理逻辑 - 支持自定义宏的模式匹配和转换 - 实现宏参数的保留和注释化 - 提供多种未知宏的处理策略选项 - 为纯装饰性宏提供忽略或简化处理选项 - _需求: 6.1, 6.2, 6.3, 6.4, 6.5_ ## 阶段五：系统集成和服务 - [ ] 21. 增强错误处理和回退机制 - 创建 MacroErrorRecovery 工具类 - 实现各种回退策略的具体逻辑 - 增强 generateFallbackContent 方法 - 添加错误分类和详细日志记录 - 实现 DOM 解析错误的恢复机制 - 记录回退策略的使用情况和原因 - _需求: 1.3, 6.4, 7.1, 7.2_ - [ ] 22. 创建宏处理服务主类 - 创建 `src/services/features/macro-processor.service.ts` 文件 - 实现 MacroProcessorService 类，整合所有宏处理器 - 实现宏识别、处理和统计功能 - 添加处理超时和错误恢复机制 - 实现宏处理的性能监控和日志记录 - 支持并发处理以提高性能 - _需求: 1.1, 1.2, 7.3, 8.1, 8.3_ - [ ] 23. 修复宏处理器注册和初始化 - 确保所有宏处理器正确注册到 MacroRegistry - 修复宏处理器初始化时的依赖问题 - 添加宏处理器可用性检查 - 优化宏处理器的加载顺序 - 支持动态添加新的宏处理器 - _需求: 8.2, 8.5_ - [ ] 24. 优化宏识别和处理逻辑 - 改进 identifyMacros 方法的宏识别准确性 - 优化 processSingleMacro 的错误处理 - 增强 replaceMacroInDOM 的 DOM 操作安全性 - 添加宏处理超时机制 - 实现宏处理的优先级排序 - _需求: 1.1, 7.1, 8.3_ - [ ] 25. 扩展 ContentConverter 集成宏处理 - 修改 `src/utils/content-converter.ts` 文件 - 在 htmlToMarkdown 方法中集成宏处理流程 - 添加宏处理选项到转换配置中 - 实现宏处理前后的内容验证 - 确保向后兼容性，不影响现有功能 - _需求: 1.1, 1.2, 2.1, 3.1, 4.1, 5.1, 6.1_ - [ ] 26. 更新导出服务集成宏处理功能 - 修改 `src/services/features/export.service.ts` 文件 - 在导出选项中添加宏处理配置参数 - 集成 MacroProcessorService 到导出流程中 - 添加宏处理统计到导出结果中 - 实现宏处理错误的收集和报告 - 确保导出过程不会因宏处理失败而中断 - _需求: 1.1, 1.2, 1.3, 7.1, 7.3_ - [ ] 27. 扩展导出类型定义支持宏处理 - 修改 `src/types/export.types.ts` 文件 - 添加 MacroProcessingOptions 到导出选项中 - 扩展 ExportResult 包含宏处理统计信息 - 添加宏相关的错误类型定义 - 更新导出摘要包含宏处理信息 - _需求: 7.1, 7.2, 7.3_ - [ ] 28. 更新 MCP 工具支持宏处理选项 - 修改 `src/index.ts` 文件中的导出工具定义 - 在 exportPage 工具中添加宏处理相关参数 - 在 exportPageHierarchy 和 batchExportPages 中添加宏处理支持 - 更新工具描述和参数验证逻辑 - 确保 API 向后兼容性 - _需求: 1.1, 2.1, 3.1, 4.1, 5.1, 6.1, 7.1_ - [ ] 29. 添加依赖库和配置 - 在 package.json 中添加 jsdom 依赖 - 配置 TypeScript 类型定义 - 更新构建配置支持新的依赖 - 添加宏处理相关的配置选项 - 确保依赖库的版本兼容性 - _需求: 2.2_ ## 阶段六：测试和质量保证 - [ ] 30. 编写宏处理器单元测试 - 在 `test/unit/macro-processors/` 目录下创建测试文件 - 为每个宏处理器编写单元测试 - 测试各种宏类型的识别和转换准确性 - 测试错误处理和回退策略 - 创建测试用的 HTML 样本和预期输出 - 测试 CDATA 内容提取和参数处理 - _需求: 1.4, 1.5, 2.4, 3.1, 3.2, 3.3, 4.1, 5.1, 6.1_ - [ ] 31. 编写宏处理集成测试 - 创建包含多种宏的测试页面样本 - 测试完整的宏处理流程 - 测试递归包含和循环引用检测 - 测试性能和内存使用情况 - 验证导出结果的正确性和完整性 - 测试并发处理的正确性 - _需求: 5.3, 5.5, 8.1_ - [ ] 32. 验证和调试宏处理功能 - 使用测试页面验证各种宏处理 - 测试各种宏参数组合 - 验证错误处理和回退机制 - 检查性能和内存使用情况 - 测试 HTML 解析器适配器在不同环境下的工作 - 验证日志记录和统计信息的准确性 - _需求: 1.1, 1.2, 1.3, 7.1, 7.3, 8.1_ - [ ] 33. 优化宏处理性能和内存使用 - 实现宏处理结果的缓存机制 - 优化大文档的宏处理性能 - 添加内存使用监控和优化 - 实现宏处理的并发控制 - 添加处理超时和资源限制 - 优化 DOM 操作的性能 - _需求: 8.1, 8.3_ - [ ] 34. 完善错误处理和日志记录 - 实现详细的宏处理错误分类和报告 - 添加调试模式的详细日志输出 - 实现宏处理失败的恢复策略 - 添加宏处理统计和性能指标收集 - 确保错误信息对用户友好且有用 - 记录配置文件加载和验证过程 - _需求: 7.1, 7.2, 7.3, 7.4, 7.5_ - [ ] 35. 创建宏处理配置文档和示例 - 创建宏处理配置的文档说明 - 提供各种宏处理场景的配置示例 - 编写自定义宏处理器的开发指南 - 创建故障排除和调试指南 - 更新项目 README 包含宏处理功能说明 - 提供黑名单配置和插件扩展的示例 - _需求: 7.4, 7.5, 8.4, 8.5_ - [ ] 36. 端到端测试和文档完善 - 使用真实的 Confluence 页面进行端到端测试 - 验证各种宏类型在实际场景中的处理效果 - 完善 API 文档和使用示例 - 创建宏处理功能的演示和教程 - 确保所有功能正常工作并满足需求 - 验证系统在高负载下的稳定性 - _需求: 1.1, 1.2, 1.3, 2.1, 3.1, 4.1, 5.1, 6.1, 7.1, 8.1_