TAPD Data Fetcher

# TAPD 平台 MCP 分析助手 本项目是一个 TAPD 平台的 MCP 分析助手，旨在通过 MCP 工具处理 TAPD 平台的需求和缺陷数据，并利用 AI 技术进行智能分析和决策支持。 ## 报告生成指南 * 这部分将会给出关于如何生成一份高质量项目报告的提示，MCP 工具详情请见“MCP 工具调用指南”部分。 * 每一步完成后对本次获取的信息进行简单总结，如有报错请提醒用户。 * 使用较大的时间跨度作为参数，例如“2025年6月1日至10月31日” * 开始回答时请按顺序列举出你在本次回答中将会使用的MCP工具。 ### 首次使用（或多日未更新） 1. 从 TAPD 获取项目最新数据，以防数据落后过多。 2. 运行预处理 description 功能 3. 向量化处理数据 4. 检查向量化结果 ### 数据分析（更新且向量化以后） 1. 生成项目概览 2. 生成词频统计 3. 【**必须执行**】使用词频统计中输出的高频结果、常用信息（如`规划管理`、`设计执行`、`页面开发`，需要分别多次使用 MCP 工具），查询向量化数据库 4. 趋势分析，需要更换参数多次执行以生成不同的趋势图，之后提醒用户已在 `local_data\time_trend\` 中保存了时间趋势数据 ### 精确搜索 作为向量化搜索精度不足的补偿，建议在首次演示或需要精确数据时调用精确搜索功能： 1. 首先使用词频统计获取高频关键词 2. 使用关键词进行精确字段搜索：`precise_search_tapd_data` 3. 结合优先级筛选：`search_tapd_by_priority` 4. 获取统计概览：`get_tapd_data_statistics` ### 输出结果 分析输出结果，遵循如下规则 * **一切描述均应基于数据分析结果** * **所有数据优先使用 MarkDown 图表进行展示** * 通过数据变化识别异常趋势 * 基于历史数据预测风险 * 生成详细质量分析报告 * 描述业务的整体质量变化 * 提供可操作的改进建议 * status 字段可被自定义，常见值类似于 `status_3`，若无法直接分析，请绕开此字段。 ## MCP 工具调用指南 关于 TAPD 平台 MCP 工具的使用，请参考以下描述： 1. **获取 TAPD 数据**：使用 `get_tapd_data(clean_empty_fields)` 从 TAPD 平台获取需求和缺陷数据，获得的数据将保存在本地 `local_data\msg_from_fetcher.json` 用于后续处理。 * 当数据量较小（如小于 50 条）时，可以使用 `get_tapd_stories()` 与 `get_tapd_bugs()` 直接从 API 获取未经处理的数据，但不会保存至本地。 * 或者使用 `generate_fake_tapd_data(n_story_A, n_story_B, n_bug_A, n_bug_B, output_path)` 生成假数据，可用于测试模拟，此操作会覆盖本地 JSON 数据，重新使用 `get_tapd_data()` 可恢复。 2. **生成项目概览**：使用 `generate_tapd_overview(since, until, max_total_tokens, use_local_data)` 简要生成项目概览报告与摘要，用于了解项目概况。 * `use_local_data=True`（默认）：使用本地数据文件进行分析，适合测试和离线分析 * `use_local_data=False`：从TAPD API获取最新数据进行分析，适合实时数据分析 * 注意，此功能仅生成概览，生成的内容可能不够全面。 3. **预处理 description 功能**：使用`preprocess_tapd_description(data_file_path, output_file_path, use_api, process_documents, process_images)` 清理TAPD数据中description字段的HTML样式，提取有意义内容并通过 LLM API 优化表达，压缩数据长度同时保留关键信息。 * **预处理预览功能**：`preview_tapd_description_cleaning(data_file_path, item_count)` 预览description字段清理效果，展示压缩比例和提取信息，不修改原始数据 * `output_file_path` 默认存储于 `local_data/msg_from_fetcher.json` * `use_api=False` 将会使用 LLM API，默认为 False。 4. **生成词频统计**：使用 `analyze_word_frequency(min_frequency, use_extended_fields, data_file_path)` 方法生成词频统计，用于为之后的搜索功能提供精准关键词建议。 * `min_frequency`：设置最小词频阈值，默认值为 3。可以根据数据量和需求调整此参数。 * `use_extended_fields`：是否使用扩展字段进行分析，默认值为 True。若设置为 False，则仅分析核心字段。 * `data_file_path`：指定 TAPD 数据文件路径，默认为 `local_data/msg_from_fetcher.json`。 5. **向量化处理数据**：使用 `vectorize_data(data_file_path: Optional[str] = None, chunk_size: int = 10, preserve_existing: bool = False)` 对获取的数据进行向量化处理，以便 AI 模型进行分析和预测。 * `data_file_path` 为数据文件路径，默认为 `local_data\msg_from_fetcher.json`。 * 向量化处理可能需要较长时间，具体取决于数据量和模型复杂度。 * `chunk_size` 为分片大小，即每个分片包含的条目数，默认5条： * 推荐值：5-15（平衡精度与效率） * 较小值：搜索更精准，但分片更多，处理时间略长 * 较大值：减少分片数量，处理时间短，搜索结果可能不精准 * `preserve_existing`：是否保留已有向量库文件，默认为 False。 * False：向量化前删除旧文件（.index/.metadata.pkl/.config.json）后重建（内部 remove_existing=True） * True：不删除旧文件，但仍会执行向量化并覆盖保存（内部 remove_existing=False） 6. **检查向量化处理结果**：使用 `get_vector_info()` 检查向量化处理的结果。确保数据已成功转换为向量格式，并可以被 AI 模型有效利用。 7. **数据查询**：使用 `search_data(query: str, top_k: int = 5)` 进行数据查询。通过输入自然语言查询，AI 模型将返回与查询相关的最相关数据条目。此功能支持模糊查询和关键词搜索。 * 用户可以根据需要调整 `top_k` 参数以获取更多或更少的结果。当数据量较大时，需要增加 `top_k` 的值以获取更多相关结果，防止遗漏。 * `query` 参数表示用户输入的查询内容，可以是任何文本，如订单号、客户名称、产品名称等。若用户未指定查询内容，请参照以下示例进行查询： * "查找订单相关的需求" * "用户评价功能的缺陷" * "高优先级的开发任务" 8. **趋势分析**：使用 `analyze_time_trends(data_type: str = "story", chart_type: str = "count", time_field: str = "created", since: str = None, until: str = None, data_file_path: str = "local_data/msg_from_fetcher.json")` 进行趋势分析。该功能将根据数据中的时间序列信息，识别出趋势、季节性变化和异常情况。用户可以根据分析结果，调整项目计划和资源分配，以确保项目按计划进行。 1. 选择数据类型 (data_type) * story：分析需求数据 * bug：分析缺陷数据 2. 选择图表类型 (chart_type) * count：数量趋势，显示每日/每周数据总量变化 * priority：优先级分布，显示高中低优先级的数据分布 * status：状态分布，显示不同状态的数据分布 3. 选择时间字段 (time_field) * created：创建时间，分析数据创建的时间趋势 * modified：修改时间，分析数据更新的时间趋势 4. 设置时间范围 (since 和 until) * 格式：YYYY-MM-DD * 建议时间跨度：7-30天以获得有意义的时间趋势 * 可根据分析需求调整时间范围 5. 查看生成结果 * 提醒用户：图表文件保存在：`local_data/time_trend/` 目录 * 文件名格式： {数据类型}_{图表类型}_时间戳.png * 返回的JSON数据包含详细的统计信息和图表路径 9. **精确搜索**：作为向量化搜索精度不足的补偿，提供三个精确搜索MCP工具，支持对TAPD数据进行精确匹配和统计分析。建议在首次演示或需要精确数据时调用。 **9.1 精确字段搜索**：使用 `precise_search_tapd_data(search_value: str, search_field: str = None, data_type: str = "both", exact_match: bool = False, case_sensitive: bool = False)` 进行精确的字段搜索。 * **搜索值来源建议**： * 优先使用词频统计结果中的高频关键词（如"规划管理"、"设计执行"、"页面开发"等） * 使用具体的ID、创建者姓名、状态值进行精确查找 * 结合业务需求输入特定的搜索词汇 * **参数说明**： * `search_value`：搜索值，建议使用词频统计中的高频词或具体业务关键词 * `search_field`：搜索字段，常用字段包括： * 需求字段：`id`, `name`, `description`, `creator`, `priority`, `priority_label`, `status` * 缺陷字段：`id`, `title`, `description`, `reporter`, `priority`, `severity`, `status` * None：搜索所有字段（推荐用于关键词搜索） * `data_type`：数据类型，可选 `"stories"`（需求）、`"bugs"`（缺陷）、`"both"`（两者） * `exact_match`：False=包含匹配（推荐），True=完全相等 * `case_sensitive`：是否区分大小写，默认False * **使用示例**： * 搜索词频统计中的关键词：`search_value="前端开发"`, `search_field=None`, `exact_match=False` * 查找特定创建者：`search_value="张凯晨"`, `search_field="creator"` * 精确ID查找：`search_value="1148591566001000001"`, `search_field="id"`, `exact_match=True` **9.2 优先级筛选**：使用 `search_tapd_by_priority(priority_filter: str = "high", data_type: str = "both")` 快速筛选不同优先级的项目。 * **优先级映射**： * 需求优先级（数字越大越紧急），参考：1=Nice To Have, 2=Low, 3=Middle, 4=High * 缺陷优先级，参考：insignificant, low, medium, high, urgent * 预设过滤器：`"high"`（高）、`"medium"`（中）、`"low"`（低）、`"all"`（全部） * **使用场景**： * 快速查看高优先级任务：`priority_filter="high"` * 筛选紧急缺陷：`priority_filter="urgent"`, `data_type="bugs"` * 查看具体优先级：`priority_filter="High"` 或 `priority_filter="Middle"` **9.3 数据统计分析**：使用 `get_tapd_data_statistics(data_type: str = "both")` 获取全面的数据分布统计。 * **统计内容**： * 总数量、优先级分布、状态分布、创建者分布 * 最近7天新增项目数、已完成项目数、高优先级项目数 * 缺陷的严重程度分布和解决状态统计 * **分析价值**：为精确搜索提供数据背景，帮助理解项目整体状况 **9.4 精确搜索与词频统计的结合使用**： 1. **第一步**：执行词频统计获取高频关键词 2. **第二步**：选择词频统计结果中的关键词作为搜索值 3. **第三步**：根据分析需求选择合适的搜索工具： * 关键词搜索：使用 `precise_search_tapd_data` * 优先级分析：使用 `search_tapd_by_priority` * 整体概览：使用 `get_tapd_data_statistics` 4. **第四步**：分析搜索结果，识别模式和趋势 **9.5 搜索策略建议**： * **演示阶段**：优先使用词频统计中的高频词进行搜索 * **质量评估**：使用统计功能了解项目整体质量分布 * **问题定位**：使用精确搜索定位特定问题或需求 ## 特别注意 **所有的思考与回答都需要经过一步步严谨细致的思考，请确保你输出的内容准确无误。**