MCP Confluence Server

# Confluence 宏处理功能需求文档 ## 介绍 此功能为 Confluence 页面导出 markdown 时增加完整的宏处理支持，同时修复当前导出功能中的关键 bug。当前系统存在两个主要问题：1) 导出的 Markdown 文件只包含元数据和"INLINE"字符串，而没有实际的页面内容；2) 宏处理器在 Node.js 环境中尝试使用浏览器特定的 DOM API 导致处理失败。本需求文档涵盖了修复这些紧急问题以及实现完整宏处理功能的所有需求。 ## 需求 ### 需求 1 - 紧急 Bug 修复 **用户故事：** 作为开发者，我希望导出的 Markdown 文件包含完整的页面内容，而不仅仅是元数据和"INLINE"字符串，以便我可以正常使用导出的文档。 #### 验收标准 1. WHEN 导出页面时 THEN 系统应正确获取页面的 HTML 内容而不是空内容 2. WHEN 页面内容包含 Confluence 宏时 THEN 系统应正确处理和转换宏内容而不是丢失内容 3. WHEN 转换 HTML 到 Markdown 时 THEN 系统应保留所有文本内容和格式 4. WHEN 生成最终文件时 THEN 系统应包含完整的页面内容而不仅仅是"INLINE"字符串 5. WHEN 页面内容为空时 THEN 系统应记录警告并说明原因 ### 需求 2 - 宏处理功能 **用户故事：** 作为开发者，我希望能够成功导出包含宏的 Confluence 页面，以便获得完整的页面内容。 #### 验收标准 1. WHEN 导出包含 Markdown 宏的页面 THEN 系统应该能够正确处理宏内容并生成 Markdown 文件 2. WHEN 启用宏处理选项 THEN 导出过程不应该失败 3. WHEN 宏处理失败 THEN 系统应该提供清晰的错误信息和回退机制 4. WHEN 页面包含代码宏时 THEN 系统应识别代码宏的语言类型并转换为 markdown 围栏代码块格式 5. WHEN 代码宏包含标题时 THEN 系统应在代码块前添加注释说明 ### 需求 3 - 环境兼容性 **用户故事：** 作为系统管理员，我希望宏处理器能够在 Node.js 环境中正常工作，而不依赖浏览器特定的 API。 #### 验收标准 1. WHEN 宏处理器初始化 THEN 不应该依赖浏览器的 DOMParser 和 XMLSerializer 2. WHEN 在 Node.js 环境中运行 THEN 应该使用适当的 HTML 解析库（如 jsdom 或 cheerio） 3. WHEN HTML 解析失败 THEN 应该有适当的错误处理和回退机制 4. WHEN 遇到信息类宏（info、warning、note等）THEN 应转换为带有相应图标的引用块 ### 需求 4 - Markdown 宏处理 **用户故事：** 作为用户，我希望 Markdown 宏和各种内容宏能够被正确解析和转换，以便在导出的文件中看到实际内容。 #### 验收标准 1. WHEN 页面包含 Markdown 宏 THEN 宏内容应该被提取并转换为纯 Markdown 2. WHEN Markdown 宏有 CDATA 包装 THEN 应该正确解析 CDATA 内容 3. WHEN 宏参数为 "INLINE" THEN 应该将内容内联到页面中 4. WHEN 遇到简单表格宏时 THEN 系统应转换为标准的 markdown 表格 5. WHEN 表格包含合并单元格时 THEN 系统应使用 HTML 表格标签保持布局 ### 需求 5 - 图表宏处理 **用户故事：** 作为项目经理，我希望图表宏（如流程图、甘特图等）能转换为 mermaid 格式或保留为图片链接，以便在 markdown 中仍能查看图表内容。 #### 验收标准 1. WHEN 遇到流程图宏时 THEN 系统应尝试转换为 mermaid 流程图语法 2. WHEN 遇到甘特图宏时 THEN 系统应转换为 mermaid 甘特图格式 3. WHEN 图表无法转换时 THEN 系统应导出为图片并在 markdown 中插入图片链接 4. WHEN 图表包含交互功能时 THEN 系统应在转换后添加功能说明注释 5. WHEN 图表数据复杂时 THEN 系统应提供原始数据的链接或附件 ### 需求 6 - 页面引用和包含宏 **用户故事：** 作为文档管理员，我希望页面引用和包含宏能正确处理，以便导出的文档保持完整的内容结构和引用关系。 #### 验收标准 1. WHEN 遇到页面包含宏时 THEN 系统应获取被包含页面的内容并嵌入当前文档 2. WHEN 遇到页面引用宏时 THEN 系统应转换为 markdown 链接格式 3. WHEN 包含的页面也包含宏时 THEN 系统应递归处理所有宏 4. WHEN 被引用页面不存在或无权限访问时 THEN 系统应添加错误说明并保留原始引用 5. WHEN 包含层级过深时 THEN 系统应限制递归深度并添加警告 ### 需求 7 - 自定义和未知宏处理 **用户故事：** 作为用户，我希望系统能处理自定义宏和第三方插件宏，以便即使是特殊的宏也能得到合理的处理。 #### 验收标准 1. WHEN 遇到未知宏时 THEN 系统应保留宏的原始 HTML 结构 2. WHEN 自定义宏包含可识别模式时 THEN 系统应尝试进行基础转换 3. WHEN 宏包含参数时 THEN 系统应将参数信息作为注释保留 4. WHEN 宏渲染失败时 THEN 系统应记录错误并提供替代显示方案 5. WHEN 宏是纯装饰性的时 THEN 系统应提供选项来忽略或简化处理 ### 需求 8 - 错误处理和日志记录 **用户故事：** 作为开发者，我希望宏处理器有良好的错误处理和日志记录，以便调试和监控。 #### 验收标准 1. WHEN 宏处理失败 THEN 应该记录详细的错误日志 2. WHEN 使用回退策略 THEN 应该记录使用的策略和原因 3. WHEN 宏处理成功 THEN 应该记录处理统计信息 4. WHEN 系统启动时 THEN 应加载宏处理配置文件 5. WHEN 配置文件格式错误时 THEN 系统应使用默认配置并记录警告 ### 需求 9 - 性能和可扩展性 **用户故事：** 作为系统架构师，我希望宏处理器具有良好的性能和可扩展性。 #### 验收标准 1. WHEN 处理大量宏 THEN 系统应该支持并发处理以提高性能 2. WHEN 添加新的宏类型 THEN 应该能够轻松扩展宏处理器 3. WHEN 宏处理超时 THEN 应该有适当的超时处理机制 4. WHEN 需要禁用某些宏处理时 THEN 系统应支持黑名单配置 5. WHEN 需要添加新的宏处理器时 THEN 系统应支持插件式扩展