@bangdao-ai/zentao-mcp 1.0.0

package/README.md

@@ -0,0 +1,155 @@
+# 禅道 MCP 工具
+
+这是一个基于 Python 的 MCP（Model Context Protocol）工具，用于连接禅道Bug管理系统。支持通过 npm/npx 直接使用。
+
+## 功能特性
+
+- ✅ 创建Bug（支持截图上传）
+- ✅ 创建测试用例
+- ✅ 批量从CSV文件创建测试用例
+- ✅ 上传图片到Bug附件
+- ✅ 支持配置文件（支持JSON注释）
+- ✅ 自动格式化步骤为HTML
+
+## 安装
+
+通过 npm/npx 使用（推荐）：
+
+```bash
+npx -y @bangdao-ai/zentao-mcp@latest
+```
+
+## 配置
+
+### 在 Cursor 中配置
+
+在 Cursor 的 MCP 配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@bangdao-ai/zentao-mcp@latest"
+      ],
+      "env": {
+        "ZENTAO_PRODUCT_ID": "365",
+        "ZENTAO_OPENED_BY": "69610",
+        "ZENTAO_KEYWORDS": "AI",
+        "ZENTAO_TITLE_PREFIX": ""
+      }
+    }
+  }
+}
+```
+
+**配置说明**：
+- `ZENTAO_PRODUCT_ID`（必需）：产品ID
+- `ZENTAO_OPENED_BY`（必需）：创建人和指派人ID（同一个人）
+- `ZENTAO_KEYWORDS`（可选）：关键词，默认为空
+- `ZENTAO_TITLE_PREFIX`（可选）：标题前缀，默认为空
+
+### 兜底配置（可选）
+
+如果未在环境变量中配置，可以使用配置文件 `bug_config.json`（参考 `bug_config.example.json`）。配置文件路径可通过环境变量 `ZENTAO_CONFIG_PATH` 指定。
+
+## MCP 工具
+
+### 1. create_bug
+
+创建Bug到禅道系统。
+
+**参数**：
+- `title` (必需): Bug标题
+- `steps` (必需): 重现步骤（支持换行，会自动转换为HTML格式）
+- `product_id` (可选): 产品ID
+- `opened_by` (可选): 创建人和指派人
+- `screenshot_path` (可选): 截图文件路径
+- `severity` (可选): 严重程度（默认3）
+- `pri` (可选): 优先级（默认3）
+- `type` (可选): Bug类型（默认codeissue）
+- `environment` (可选): 环境（默认测试环境）
+- `story` (可选): 相关需求id
+- `task` (可选): 相关任务id
+- `mailto` (可选): 抄送人账号
+- `keywords` (可选): 关键词
+
+### 2. upload_image_to_bug
+
+上传图片到指定Bug的附件。
+
+**参数**：
+- `bug_id` (必需): Bug ID
+- `image_path` (必需): 图片文件路径
+- `custom_filename` (可选): 自定义文件名
+
+### 3. create_case
+
+创建测试用例到禅道系统。
+
+**参数**：
+- `product` (必需): 产品ID
+- `type` (必需): 用例类型（interface 或 feature）
+- `title` (必需): 用例名称
+- `opened_by` (必需): 创建人
+- `module` (可选): 模块ID（默认0）
+- `stage` (可选): 阶段（默认intergrate）
+- `precondition` (可选): 前置条件
+- `keywords` (可选): 关键词
+- `steps` (可选): 测试步骤数组
+- `expects` (可选): 预期结果数组
+
+### 4. create_cases_from_csv
+
+从CSV文件批量创建测试用例。
+
+**参数**：
+- `csv_file_path` (必需): CSV文件路径
+- `case_type` (可选): 用例类型（interface、feature、接口测试、功能测试，会自动识别）
+- `product_id` (可选): 产品ID
+- `opened_by` (可选): 创建人
+- `keywords` (可选): 关键词
+
+**CSV格式**：
+- 接口测试用例需要包含：`用例名称`、`接口地址`、`请求方法`、`请求体`、`断言`、`预期结果`
+- 功能测试用例需要包含：`用例名称`、`预期结果`
+
+### 5. submit_csv_cases_to_zentao
+
+将CSV文件中的所有测试用例提交到禅道（会自动备份原文件）。
+
+**参数**：
+- `csv_file_path` (必需): CSV文件路径
+- `case_type` (可选): 用例类型（interface、feature、接口测试、功能测试，会自动识别）
+- `product_id` (可选): 产品ID
+- `opened_by` (可选): 创建人
+- `keywords` (可选): 关键词
+
+### 6. get_config
+
+获取当前配置信息。
+
+## 项目结构
+
+```
+禅道mcp/
+├── index.js                    # npm 入口文件
+├── package.json                # npm 包配置
+├── src/
+│   ├── mcp_server.py          # MCP服务器主文件
+│   └── zentao_nexus.py         # 禅道工具类
+├── requirements.txt            # Python 依赖
+├── README.md                   # 项目说明
+├── PUBLISH.md                  # 发布指南
+└── bug_config.example.json     # 兜底配置示例
+```
+
+## 发布
+
+参考 [PUBLISH.md](PUBLISH.md) 了解如何发布到 npm。
+
+## 许可证
+
+MIT

package/bug_config.example.json

@@ -0,0 +1,7 @@
+{
+  "product_id": "365",
+  "opened_by": "69610",
+  "keywords": "AI",
+  "title_prefix": ""
+}
+

package/index.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * 禅道 MCP 服务器入口
+ * 通过 npm/npx 调用 Python MCP 服务器
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// 获取 Python 可执行文件路径
+function findPython() {
+  const pythonCommands = ['python3', 'python'];
+  
+  for (const cmd of pythonCommands) {
+    try {
+      const result = require('child_process').execSync(`which ${cmd}`, { encoding: 'utf-8' }).trim();
+      if (result) {
+        return result;
+      }
+    } catch (e) {
+      // 继续尝试下一个
+    }
+  }
+  
+  throw new Error('未找到 Python 3，请确保已安装 Python 3.8+');
+}
+
+// 获取脚本路径
+function getScriptPath() {
+  // 获取当前包的目录
+  const packageDir = __dirname;
+  const scriptPath = path.join(packageDir, 'src', 'mcp_server.py');
+  
+  if (!fs.existsSync(scriptPath)) {
+    // 尝试相对路径（开发环境）
+    const devPath = path.join(packageDir, '..', 'src', 'mcp_server.py');
+    if (fs.existsSync(devPath)) {
+      return devPath;
+    }
+    throw new Error(`找不到 MCP 服务器脚本: ${scriptPath}`);
+  }
+  
+  return scriptPath;
+}
+
+// 检查 Python 依赖
+function checkPythonDependencies() {
+  const requirementsPath = path.join(__dirname, 'requirements.txt');
+  
+  if (fs.existsSync(requirementsPath)) {
+    // 可以在这里添加依赖检查逻辑
+    // 例如：尝试导入模块，如果失败则提示用户安装
+  }
+}
+
+// 主函数
+function main() {
+  try {
+    const python = findPython();
+    const scriptPath = getScriptPath();
+    
+    // 检查 Python 依赖（可选）
+    checkPythonDependencies();
+    
+    // 启动 Python MCP 服务器
+    // 注意：MCP 服务器通过 stdio 通信，不会输出到控制台
+    // 这是正常行为，服务器会等待 MCP 协议消息
+    const child = spawn(python, [scriptPath], {
+      stdio: 'inherit',
+      env: process.env
+    });
+    
+    // 处理退出
+    child.on('exit', (code) => {
+      if (code !== 0 && code !== null) {
+        // 非正常退出，可能有问题
+        process.exit(code);
+      } else {
+        process.exit(0);
+      }
+    });
+    
+    // 处理错误
+    child.on('error', (err) => {
+      console.error('启动 MCP 服务器失败:', err.message);
+      console.error('请确保：');
+      console.error('1. Python 3.8+ 已安装');
+      console.error('2. 已安装依赖: pip install -r requirements.txt');
+      console.error('3. 脚本路径正确:', scriptPath);
+      process.exit(1);
+    });
+    
+    // 处理信号
+    process.on('SIGINT', () => {
+      if (child && !child.killed) {
+        child.kill('SIGINT');
+      }
+      process.exit(0);
+    });
+    
+    process.on('SIGTERM', () => {
+      if (child && !child.killed) {
+        child.kill('SIGTERM');
+      }
+      process.exit(0);
+    });
+    
+  } catch (error) {
+    console.error('错误:', error.message);
+    console.error('\n故障排查：');
+    console.error('1. 检查 Python 是否安装: python3 --version');
+    console.error('2. 检查脚本是否存在: ls -la src/mcp_server.py');
+    console.error('3. 检查依赖是否安装: pip3 list | grep mcp');
+    process.exit(1);
+  }
+}
+
+// 如果直接运行此文件
+if (require.main === module) {
+  main();
+}
+
+module.exports = { main };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@bangdao-ai/zentao-mcp",
+  "version": "1.0.0",
+  "description": "禅道Bug管理系统MCP工具",
+  "main": "index.js",
+  "bin": {
+    "zentao-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "zentao",
+    "bug-management",
+    "禅道"
+  ],
+  "author": "bangdao-ai",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "src/",
+    "requirements.txt",
+    "bug_config.example.json",
+    "README.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bangdao-ai/zentao-mcp.git"
+  }
+}

package/requirements.txt

@@ -0,0 +1,6 @@
+mcp>=0.9.0
+requests>=2.31.0
+python-dotenv>=1.0.0
+fastapi>=0.104.0
+uvicorn[standard]>=0.24.0
+

package/src/mcp_server.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+禅道 MCP 服务器
+基于 Python 的 MCP（Model Context Protocol）服务器实现
+"""
+
+import asyncio
+import json
+import os
+import sys
+from typing import Any, Dict, Optional
+
+from dotenv import load_dotenv
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+from zentao_nexus import ZenTaoNexus
+
+# 加载 .env 文件
+load_dotenv()
+
+
+class ZenTaoMCPServer:
+    """禅道 MCP 服务器"""
+    
+    def __init__(self):
+        self.server = Server("zentao-mcp-server")
+        self.nexus: Optional[ZenTaoNexus] = None
+        self.setup_handlers()
+    
+    def setup_handlers(self):
+        """设置请求处理器"""
+        
+        @self.server.list_tools()
+        async def list_tools() -> list[Tool]:
+            """列出可用工具"""
+            return [
+                Tool(
+                    name="create_bug",
+                    description="创建Bug到禅道系统。支持上传截图。",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "title": {"type": "string", "description": "Bug标题"},
+                            "steps": {"type": "string", "description": "重现步骤（支持换行，会自动转换为HTML格式）"},
+                            "product_id": {"type": "string", "description": "产品ID（可选，默认使用配置文件中的值）"},
+                            "opened_by": {"type": "string", "description": "创建人和指派人（可选，默认使用配置文件中的值）"},
+                            "screenshot_path": {"type": "string", "description": "截图文件路径（可选）"},
+                            "severity": {"type": "string", "description": "严重程度（可选，默认3）"},
+                            "pri": {"type": "string", "description": "优先级（可选，默认3）"},
+                            "type": {"type": "string", "description": "Bug类型（可选，默认codeissue）"},
+                            "environment": {"type": "string", "description": "环境（可选，默认测试环境）"},
+                            "story": {"type": "string", "description": "相关需求id（可选）"},
+                            "task": {"type": "string", "description": "相关任务id（可选）"},
+                            "mailto": {"type": "string", "description": "抄送人账号（可选）"},
+                            "keywords": {"type": "string", "description": "关键词（可选）"}
+                        },
+                        "required": ["title", "steps"]
+                    }
+                ),
+                Tool(
+                    name="upload_image_to_bug",
+                    description="上传图片到指定Bug的附件",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "bug_id": {"type": "string", "description": "Bug ID"},
+                            "image_path": {"type": "string", "description": "图片文件路径"},
+                            "custom_filename": {"type": "string", "description": "自定义文件名（可选）"}
+                        },
+                        "required": ["bug_id", "image_path"]
+                    }
+                ),
+                Tool(
+                    name="create_case",
+                    description="创建测试用例到禅道系统",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "product": {"type": "string", "description": "产品ID"},
+                            "type": {"type": "string", "description": "用例类型（interface或feature）", "enum": ["interface", "feature"]},
+                            "title": {"type": "string", "description": "用例名称"},
+                            "module": {"type": "string", "description": "模块ID（默认0）"},
+                            "stage": {"type": "string", "description": "阶段（默认intergrate）"},
+                            "precondition": {"type": "string", "description": "前置条件"},
+                            "keywords": {"type": "string", "description": "关键词"},
+                            "opened_by": {"type": "string", "description": "创建人"},
+                            "steps": {"type": "array", "description": "测试步骤数组", "items": {"type": "string"}},
+                            "expects": {"type": "array", "description": "预期结果数组", "items": {"type": "string"}}
+                        },
+                        "required": ["product", "type", "title", "opened_by"]
+                    }
+                ),
+                Tool(
+                    name="create_cases_from_csv",
+                    description="从CSV文件批量创建测试用例",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "csv_file_path": {"type": "string", "description": "CSV文件路径"},
+                            "case_type": {"type": "string", "description": "用例类型（interface、feature、接口测试、功能测试，可选，会自动识别）"},
+                            "product_id": {"type": "string", "description": "产品ID（可选，默认使用配置文件中的值）"},
+                            "opened_by": {"type": "string", "description": "创建人（可选，默认使用配置文件中的值）"},
+                            "keywords": {"type": "string", "description": "关键词（可选，默认使用配置文件中的值）"}
+                        },
+                        "required": ["csv_file_path"]
+                    }
+                ),
+                Tool(
+                    name="submit_csv_cases_to_zentao",
+                    description="将CSV文件中的所有测试用例提交到禅道（会自动备份原文件）",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "csv_file_path": {"type": "string", "description": "CSV文件路径"},
+                            "case_type": {"type": "string", "description": "用例类型（interface、feature、接口测试、功能测试，可选，会自动识别）"},
+                            "product_id": {"type": "string", "description": "产品ID（可选，默认使用配置文件中的值）"},
+                            "opened_by": {"type": "string", "description": "创建人（可选，默认使用配置文件中的值）"},
+                            "keywords": {"type": "string", "description": "关键词（可选，默认使用配置文件中的值）"}
+                        },
+                        "required": ["csv_file_path"]
+                    }
+                ),
+                Tool(
+                    name="get_config",
+                    description="获取当前配置信息",
+                    inputSchema={"type": "object", "properties": {}}
+                )
+            ]
+        
+        @self.server.call_tool()
+        async def call_tool(name: str, arguments: Dict[str, Any]) -> list[TextContent]:
+            """处理工具调用"""
+            try:
+                # 延迟初始化 nexus（只在第一次使用时初始化）
+                if self.nexus is None:
+                    # 优先使用环境变量配置（Cursor MCP 配置）
+                    config_path = os.getenv("ZENTAO_CONFIG_PATH")
+                    
+                    # 如果通过环境变量直接配置了产品ID和创建人，则创建临时配置文件
+                    product_id = os.getenv("ZENTAO_PRODUCT_ID")
+                    opened_by = os.getenv("ZENTAO_OPENED_BY")
+                    
+                    if product_id and opened_by and not config_path:
+                        # 使用环境变量配置，创建临时配置
+                        import tempfile
+                        temp_config = {
+                            "product_id": product_id,
+                            "opened_by": opened_by,
+                            "keywords": os.getenv("ZENTAO_KEYWORDS", ""),
+                            "title_prefix": os.getenv("ZENTAO_TITLE_PREFIX", "")
+                        }
+                        temp_file = tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False)
+                        json.dump(temp_config, temp_file, ensure_ascii=False)
+                        temp_file.close()
+                        config_path = temp_file.name
+                    
+                    self.nexus = ZenTaoNexus(config_path)
+                
+                if name == "create_bug":
+                    title = arguments["title"]
+                    steps = arguments["steps"]
+                    product_id = arguments.get("product_id")
+                    opened_by = arguments.get("opened_by")
+                    screenshot_path = arguments.get("screenshot_path")
+                    
+                    # 提取其他可选参数
+                    kwargs = {}
+                    for key in ["severity", "pri", "type", "environment", "story", "task", "mailto", "keywords"]:
+                        if key in arguments:
+                            kwargs[key] = arguments[key]
+                    
+                    result = self.nexus.create_bug(
+                        title, steps, product_id, opened_by, screenshot_path, **kwargs
+                    )
+                    
+                    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
+                
+                elif name == "upload_image_to_bug":
+                    bug_id = arguments["bug_id"]
+                    image_path = arguments["image_path"]
+                    custom_filename = arguments.get("custom_filename")
+                    
+                    if not os.path.exists(image_path):
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({
+                                "status": -1,
+                                "message": f"图片文件不存在: {image_path}"
+                            }, ensure_ascii=False, indent=2)
+                        )]
+                    
+                    result = self.nexus.upload_image_to_bug(bug_id, image_path, custom_filename)
+                    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
+                
+                elif name == "create_case":
+                    product = arguments["product"]
+                    case_type = arguments["type"]
+                    title = arguments["title"]
+                    opened_by = arguments["opened_by"]
+                    module = arguments.get("module", "0")
+                    stage = arguments.get("stage", "intergrate")
+                    precondition = arguments.get("precondition", "")
+                    keywords = arguments.get("keywords", "")
+                    steps = arguments.get("steps", [])
+                    expects = arguments.get("expects", [])
+                    
+                    case_data = {
+                        "product": product,
+                        "type": case_type,
+                        "title": title,
+                        "module": module,
+                        "stage": stage,
+                        "precondition": precondition,
+                        "keywords": keywords,
+                        "openedBy": opened_by
+                    }
+                    
+                    # 添加步骤和预期结果
+                    for i, step in enumerate(steps, 1):
+                        case_data[f"steps[{i}]"] = step
+                    
+                    for i, expect in enumerate(expects, 1):
+                        case_data[f"expects[{i}]"] = expect
+                    
+                    result = self.nexus.client.create_case_by_api(case_data)
+                    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
+                
+                elif name == "create_cases_from_csv":
+                    csv_file_path = arguments["csv_file_path"]
+                    case_type = arguments.get("case_type")
+                    product_id = arguments.get("product_id")
+                    opened_by = arguments.get("opened_by")
+                    keywords = arguments.get("keywords")
+                    
+                    if not os.path.exists(csv_file_path):
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({
+                                "status": -1,
+                                "message": f"CSV文件不存在: {csv_file_path}"
+                            }, ensure_ascii=False, indent=2)
+                        )]
+                    
+                    # 如果提供了参数，需要临时修改配置
+                    original_product_id = self.nexus.product_id
+                    original_opened_by = self.nexus.opened_by
+                    original_keywords = self.nexus.keywords
+                    
+                    if product_id:
+                        self.nexus.product_id = product_id
+                    if opened_by:
+                        self.nexus.opened_by = opened_by
+                    if keywords:
+                        self.nexus.keywords = keywords
+                    
+                    try:
+                        results = self.nexus.create_case_from_csv(csv_file_path, case_type)
+                    finally:
+                        # 恢复原始配置
+                        self.nexus.product_id = original_product_id
+                        self.nexus.opened_by = original_opened_by
+                        self.nexus.keywords = original_keywords
+                    
+                    return [TextContent(type="text", text=json.dumps(results, ensure_ascii=False, indent=2))]
+                
+                elif name == "submit_csv_cases_to_zentao":
+                    csv_file_path = arguments["csv_file_path"]
+                    case_type = arguments.get("case_type")
+                    product_id = arguments.get("product_id")
+                    opened_by = arguments.get("opened_by")
+                    keywords = arguments.get("keywords")
+                    
+                    if not os.path.exists(csv_file_path):
+                        return [TextContent(
+                            type="text",
+                            text=json.dumps({
+                                "status": "error",
+                                "message": f"CSV文件不存在: {csv_file_path}",
+                                "total_cases": 0,
+                                "success_count": 0,
+                                "failed_count": 0,
+                                "success_rate": 0.0
+                            }, ensure_ascii=False, indent=2)
+                        )]
+                    
+                    # 如果提供了参数，需要临时修改配置
+                    original_product_id = self.nexus.product_id
+                    original_opened_by = self.nexus.opened_by
+                    original_keywords = self.nexus.keywords
+                    
+                    if product_id:
+                        self.nexus.product_id = product_id
+                    if opened_by:
+                        self.nexus.opened_by = opened_by
+                    if keywords:
+                        self.nexus.keywords = keywords
+                    
+                    try:
+                        result = self.nexus.submit_csv_cases_to_zentao(csv_file_path, case_type)
+                    finally:
+                        # 恢复原始配置
+                        self.nexus.product_id = original_product_id
+                        self.nexus.opened_by = original_opened_by
+                        self.nexus.keywords = original_keywords
+                    
+                    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
+                
+                elif name == "get_config":
+                    config = self.nexus.get_config()
+                    return [TextContent(type="text", text=json.dumps(config, ensure_ascii=False, indent=2))]
+                
+                else:
+                    raise ValueError(f"未知的工具: {name}")
+            
+            except Exception as e:
+                error_result = {
+                    "status": -1,
+                    "message": str(e),
+                    "error": str(e)
+                }
+                import traceback
+                error_result["traceback"] = traceback.format_exc()
+                return [TextContent(type="text", text=json.dumps(error_result, ensure_ascii=False, indent=2))]
+    
+    async def run(self):
+        """运行服务器"""
+        async with stdio_server() as (read_stream, write_stream):
+            await self.server.run(
+                read_stream,
+                write_stream,
+                self.server.create_initialization_options()
+            )
+
+
+async def main():
+    """主函数"""
+    server = ZenTaoMCPServer()
+    await server.run()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/src/zentao_nexus.py

@@ -0,0 +1,673 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+ZenTao Nexus - 禅道Bug管理系统连接工具类
+支持创建Bug、上传截图、批量创建测试用例等功能
+配置通过JSON文件管理，只需配置 product_id、opened_by 和 keywords
+"""
+
+import json
+import os
+import hashlib
+import time
+import requests
+import csv
+import shutil
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+# ==================== 配置加载 ====================
+
+class ConfigLoader:
+    """配置加载器类"""
+    
+    def __init__(self, config_path: Optional[str] = None):
+        """
+        初始化配置加载器
+        
+        Args:
+            config_path: 配置文件路径，如果为None则使用默认路径
+        """
+        self.config_path = config_path
+        self.config: Dict[str, Any] = {}
+        
+        # 如果提供了配置文件路径，加载配置文件
+        if config_path and os.path.exists(config_path):
+            if isinstance(config_path, Path):
+                config_path = str(config_path.resolve())
+            elif not os.path.isabs(config_path):
+                config_path = str(Path(config_path).resolve())
+            self.config_path = config_path
+            self.load_config()
+        elif config_path is None:
+            # 尝试使用默认路径
+            current_dir = os.path.dirname(os.path.abspath(__file__))
+            project_root = Path(current_dir).parent.parent.parent.parent
+            default_config_path = project_root / "testing" / "bug_config.json"
+            
+            if default_config_path.exists():
+                self.config_path = str(default_config_path.resolve())
+                self.load_config()
+            else:
+                # 如果没有配置文件，使用空配置（将依赖环境变量）
+                self.config = {}
+    
+    def load_config(self) -> None:
+        """加载配置文件（支持JSON注释）"""
+        if not self.config_path or not os.path.exists(self.config_path):
+            # 如果配置文件不存在，使用空配置（将依赖环境变量）
+            self.config = {}
+            return
+        
+        try:
+            with open(self.config_path, 'r', encoding='utf-8') as f:
+                content = f.read()
+            
+            # 移除JSON注释（支持 // 和 /* */ 两种格式）
+            # 移除单行注释 //
+            content = re.sub(r'//.*?$', '', content, flags=re.MULTILINE)
+            # 移除多行注释 /* */
+            content = re.sub(r'/\*.*?\*/', '', content, flags=re.DOTALL)
+            
+            self.config = json.loads(content)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"配置文件JSON格式错误: {str(e)}")
+        except Exception as e:
+            raise RuntimeError(f"加载配置文件失败: {str(e)}")
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """获取配置值"""
+        return self.config.get(key, default)
+    
+    def validate(self) -> bool:
+        """验证配置文件的完整性（如果配置文件存在）"""
+        # 如果配置文件不存在或为空，则依赖环境变量，不强制验证
+        if not self.config_path or not os.path.exists(self.config_path):
+            return True
+        
+        # 如果配置文件存在，则验证必需字段
+        required_keys = ["product_id", "opened_by"]
+        for key in required_keys:
+            if key not in self.config:
+                return False
+        return True
+
+
+# ==================== API客户端 ====================
+
+class ZenTaoAPIClient:
+    """禅道API客户端"""
+    
+    # 写死的配置
+    BASE_URL = "https://zentao.bangdao-tech.com"
+    ACCOUNT = "KUBETEST"
+    SECRET_KEY = "aa287b7b5a4ef5d051f82fb1825ca1ac"
+    CASE_SECRET_KEY = "db1d522a190f1135c6e7c324bd337fda"
+    CASE_ACCOUNT = "AUTOTEST"
+    
+    def __init__(self, silent=True):
+        """
+        初始化禅道API客户端
+        
+        Args:
+            silent (bool): 是否静默模式，不输出调试信息
+        """
+        self.base_url = self.BASE_URL
+        self.account = self.ACCOUNT
+        self.secret_key = self.SECRET_KEY
+        self.case_secret_key = self.CASE_SECRET_KEY
+        self.silent = silent
+    
+    def generate_bdtoken(self, timestamp):
+        """生成BDTOKEN（用于BUG创建）"""
+        token_string = f"accountfmtamp{timestamp}{self.secret_key}"
+        md5_hash = hashlib.md5()
+        md5_hash.update(token_string.encode('utf-8'))
+        return md5_hash.hexdigest()
+    
+    def generate_case_bdtoken(self, timestamp):
+        """生成用例创建用的BDTOKEN"""
+        token_string = f"accountfmtamp{timestamp}{self.case_secret_key}"
+        md5_hash = hashlib.md5()
+        md5_hash.update(token_string.encode('utf-8'))
+        return md5_hash.hexdigest()
+    
+    def create_bug_by_api(self, bug_data, use_form_data=True):
+        """通过API创建bug"""
+        current_timestamp = int(time.time())
+        bdtoken = self.generate_bdtoken(current_timestamp)
+        
+        url = f"{self.base_url}/zentaopms/www/index.php"
+        params = {
+            'm': 'allneedlist',
+            'f': 'createbugbyapi',
+            'account': self.account,
+            'tamp': current_timestamp
+        }
+        
+        headers = {
+            'BDTOKEN': bdtoken,
+            'User-Agent': 'Python-ZenTao-Client/1.0'
+        }
+        
+        try:
+            if use_form_data:
+                response = requests.post(url, params=params, headers=headers, data=bug_data, timeout=30)
+            else:
+                headers['Content-Type'] = 'application/json'
+                response = requests.post(url, params=params, headers=headers, json=bug_data, timeout=30)
+            
+            try:
+                return response.json()
+            except json.JSONDecodeError:
+                return {
+                    "status": -1,
+                    "message": "响应不是有效的JSON格式",
+                    "raw_response": response.text
+                }
+        except requests.exceptions.RequestException as e:
+            return {
+                "status": -1,
+                "message": f"请求失败: {str(e)}"
+            }
+    
+    def create_case_by_api(self, case_data, use_form_data=True):
+        """通过API创建测试用例"""
+        current_timestamp = int(time.time())
+        bdtoken = self.generate_case_bdtoken(current_timestamp)
+        
+        url = f"{self.base_url}/zentaopms/www/index.php"
+        params = {
+            'm': 'allneedlist',
+            'f': 'createcasebyapi',
+            'account': self.CASE_ACCOUNT,
+            'tamp': current_timestamp
+        }
+        
+        headers = {
+            'BDTOKEN': bdtoken,
+            'User-Agent': 'Python-ZenTao-Client/1.0'
+        }
+        
+        try:
+            if use_form_data:
+                response = requests.post(url, params=params, headers=headers, data=case_data, timeout=30)
+            else:
+                headers['Content-Type'] = 'application/json'
+                response = requests.post(url, params=params, headers=headers, json=case_data, timeout=30)
+            
+            try:
+                return response.json()
+            except json.JSONDecodeError:
+                return {
+                    "status": -1,
+                    "message": "响应不是有效的JSON格式",
+                    "raw_response": response.text
+                }
+        except requests.exceptions.RequestException as e:
+            return {
+                "status": -1,
+                "message": f"请求失败: {str(e)}"
+            }
+    
+    def upload_image_to_bug(self, bug_id, image_path, custom_filename=None):
+        """上传图片到BUG附件"""
+        if not os.path.exists(image_path):
+            return {
+                "status": -1,
+                "message": f"图片文件不存在: {image_path}"
+            }
+        
+        current_timestamp = int(datetime.now().timestamp())
+        url = f"{self.base_url}/zentaopms/www/index.php"
+        params = {
+            'm': 'allneedlist',
+            'f': 'uploadbyapi',
+            'account': self.CASE_ACCOUNT,
+            'tamp': current_timestamp
+        }
+        
+        token_string = f"accountfmtamp{current_timestamp}{self.case_secret_key}"
+        md5_hash = hashlib.md5()
+        md5_hash.update(token_string.encode('utf-8'))
+        bdtoken = md5_hash.hexdigest()
+        
+        headers = {
+            'BDTOKEN': bdtoken,
+            'User-Agent': 'Python-ZenTao-Client/1.0'
+        }
+        
+        filename = custom_filename or os.path.basename(image_path)
+        
+        try:
+            with open(image_path, 'rb') as f:
+                files = {
+                    'files[]': (filename, f, 'application/octet-stream')
+                }
+                data = {'id': bug_id}
+                response = requests.post(url, params=params, headers=headers, files=files, data=data, timeout=30)
+                
+                try:
+                    return response.json()
+                except json.JSONDecodeError:
+                    return {
+                        "status": -1,
+                        "message": "响应不是有效的JSON格式",
+                        "raw_response": response.text
+                    }
+        except requests.exceptions.RequestException as e:
+            return {
+                "status": -1,
+                "message": f"请求失败: {str(e)}"
+            }
+        except Exception as e:
+            return {
+                "status": -1,
+                "message": f"文件处理失败: {str(e)}"
+            }
+    
+    def create_case_from_csv(self, csv_file_path, case_type=None, product_id="365", opened_by="69610", keywords="AI"):
+        """从CSV文件批量创建测试用例"""
+        if not os.path.exists(csv_file_path):
+            return [{"status": -1, "message": f"CSV文件不存在: {csv_file_path}"}]
+        
+        current_time = datetime.now()
+        time_str = current_time.strftime("%H:%M:%S")
+        results = []
+        updated_rows = []
+        
+        try:
+            with open(csv_file_path, 'r', encoding='utf-8') as f:
+                reader = csv.DictReader(f)
+                fieldnames = reader.fieldnames
+                
+                if case_type is None:
+                    if '接口地址' in fieldnames and '请求方法' in fieldnames:
+                        case_type = "interface"
+                    else:
+                        case_type = "feature"
+                else:
+                    if case_type == "接口测试":
+                        case_type = "interface"
+                    elif case_type == "功能测试":
+                        case_type = "feature"
+                
+                for row in reader:
+                    if not row.get('用例名称'):
+                        row['用例ID'] = ''
+                        updated_rows.append(row)
+                        continue
+                    
+                    if case_type == "interface":
+                        interface_url = row.get('接口地址', '')
+                        request_method = row.get('请求方法', 'POST')
+                        request_body = row.get('请求体', '')
+                        assertion = row.get('断言', '')
+                        expected_result = row.get('预期结果', '')
+                        
+                        steps = [
+                            "准备测试数据",
+                            f"发送请求体：{request_body}",
+                            f"调用接口 {interface_url}",
+                            "验证响应结果"
+                        ]
+                        
+                        expects = [
+                            "测试数据准备完成",
+                            f"请求体格式正确：{request_body}",
+                            f"接口调用成功，方法：{request_method}",
+                            f"断言验证：{assertion}\\n预期结果：{expected_result}"
+                        ]
+                        
+                        case_data = {
+                            "product": product_id,
+                            "type": "interface",
+                            "title": row['用例名称'],
+                            "module": "0",
+                            "stage": "intergrate",
+                            "precondition": f"前置条件：\\n1. 系统已启动\\n2. 接口服务正常运行\\n3. 接口地址：{interface_url}\\n4. 请求方法：{request_method}",
+                            "keywords": f"{keywords} {time_str}",
+                            "openedBy": opened_by
+                        }
+                        
+                        for i, step in enumerate(steps, 1):
+                            case_data[f"steps[{i}]"] = step
+                        
+                        for i, expect in enumerate(expects, 1):
+                            case_data[f"expects[{i}]"] = expect
+                    else:
+                        steps = [
+                            "打开系统页面",
+                            "执行相关操作",
+                            "验证功能结果"
+                        ]
+                        
+                        expects = [
+                            "系统页面正常打开",
+                            "操作执行成功",
+                            row.get('预期结果', '功能符合预期')
+                        ]
+                        
+                        case_data = {
+                            "product": product_id,
+                            "type": "feature",
+                            "title": row['用例名称'],
+                            "module": "0",
+                            "stage": "intergrate",
+                            "precondition": f"前置条件：\\n1. 系统已启动\\n2. 用户已登录",
+                            "keywords": f"{keywords} {time_str}",
+                            "openedBy": opened_by
+                        }
+                        
+                        for i, step in enumerate(steps, 1):
+                            case_data[f"steps[{i}]"] = step
+                        
+                        for i, expect in enumerate(expects, 1):
+                            case_data[f"expects[{i}]"] = expect
+                    
+                    result = self.create_case_by_api(case_data)
+                    result['case_name'] = row['用例名称']
+                    results.append(result)
+                    
+                    if result.get('status') == 'success':
+                        row['用例ID'] = result.get('info', '')
+                    else:
+                        row['用例ID'] = f"创建失败: {result.get('message', '未知错误')}"
+                    
+                    updated_rows.append(row)
+            
+            if '用例ID' not in fieldnames:
+                fieldnames.append('用例ID')
+            
+            with open(csv_file_path, 'w', encoding='utf-8', newline='') as f:
+                writer = csv.DictWriter(f, fieldnames=fieldnames)
+                writer.writeheader()
+                writer.writerows(updated_rows)
+        
+        except Exception as e:
+            results.append({"status": -1, "message": f"处理CSV文件失败: {str(e)}"})
+        
+        return results
+    
+    def submit_csv_cases_to_zentao(self, csv_file_path, case_type=None, product_id="365", opened_by="69610", keywords="AI"):
+        """将CSV文件中的所有测试用例提交到禅道"""
+        if not os.path.exists(csv_file_path):
+            return {
+                "status": "error",
+                "message": f"CSV文件不存在: {csv_file_path}",
+                "total_cases": 0,
+                "success_count": 0,
+                "failed_count": 0,
+                "success_rate": 0.0
+            }
+        
+        backup_file = csv_file_path + ".backup_submit"
+        shutil.copy2(csv_file_path, backup_file)
+        
+        total_cases = 0
+        with open(csv_file_path, 'r', encoding='utf-8') as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                if row.get('用例名称'):
+                    total_cases += 1
+        
+        results = self.create_case_from_csv(csv_file_path, case_type, product_id, opened_by, keywords)
+        
+        success_count = 0
+        failed_count = 0
+        
+        for result in results:
+            if result.get('status') == 'success':
+                success_count += 1
+            else:
+                failed_count += 1
+        
+        success_rate = (success_count / len(results) * 100) if results else 0.0
+        
+        return {
+            "status": "success",
+            "message": "CSV文件测试用例提交完成",
+            "total_cases": len(results),
+            "success_count": success_count,
+            "failed_count": failed_count,
+            "success_rate": success_rate,
+            "backup_file": backup_file
+        }
+
+
+# ==================== 工具类 ====================
+
+class ZenTaoNexus:
+    """
+    ZenTao Nexus 工具类
+    
+    用于连接禅道Bug管理系统，支持创建Bug、上传截图等功能。
+    配置通过 config.json 文件管理，只需配置 product_id、opened_by 和 keywords。
+    
+    示例:
+        >>> nexus = ZenTaoNexus()
+        >>> result = nexus.create_bug(
+        ...     title="测试Bug",
+        ...     steps="重现步骤\\n1. 第一步\\n2. 第二步"
+        ... )
+        >>> print(result)
+    """
+    
+    # 写死的默认值
+    OPENED_BUILD = "trunk"
+    ENVIRONMENT = "测试环境"
+    BUG_TYPE = "codeissue"
+    BUG_SOURCE = "codemiss"
+    SEVERITY = "3"
+    PRIORITY = "3"
+    DEADLINE_DAYS = 2
+    LOWER_BUG = "0"
+    REGRESSION = "0"
+    
+    def __init__(self, config_path: str = None):
+        """
+        初始化ZenTao Nexus工具
+        
+        Args:
+            config_path: 配置文件路径，如果为None则使用默认路径（当前目录下的config.json）
+        
+        Raises:
+            ValueError: 配置文件验证失败时抛出
+            FileNotFoundError: 配置文件不存在时抛出
+        """
+        # 加载配置
+        self.config_loader = ConfigLoader(config_path)
+        
+        # 验证配置（如果配置文件存在）
+        if not self.config_loader.validate():
+            # 检查是否可以通过环境变量获取必需配置
+            product_id = os.getenv("ZENTAO_PRODUCT_ID") or os.getenv("PRODUCT_ID")
+            opened_by = os.getenv("ZENTAO_OPENED_BY") or os.getenv("OPENED_BY")
+            
+            if not product_id or not opened_by:
+                raise ValueError("配置文件验证失败，且未找到必需的环境变量 ZENTAO_PRODUCT_ID 和 ZENTAO_OPENED_BY。请检查配置文件格式或设置环境变量。")
+        
+        # 从配置加载（优先使用环境变量，支持 ZENTAO_ 前缀）
+        self.product_id = os.getenv("ZENTAO_PRODUCT_ID") or os.getenv("PRODUCT_ID") or self.config_loader.get("product_id", "365")
+        self.opened_by = os.getenv("ZENTAO_OPENED_BY") or os.getenv("OPENED_BY") or self.config_loader.get("opened_by", "69610")
+        # 关键词处理：如果配置中有 keywords，则使用 "ai," 拼接；如果没有，则使用 "ai"
+        env_keywords = os.getenv("ZENTAO_KEYWORDS") or os.getenv("KEYWORDS")
+        config_keywords = env_keywords or self.config_loader.get("keywords")
+        if config_keywords:
+            self.keywords = f"ai,{config_keywords}"
+        else:
+            self.keywords = "ai"
+        
+        # 标题前缀
+        env_title_prefix = os.getenv("ZENTAO_TITLE_PREFIX") or os.getenv("TITLE_PREFIX")
+        self.title_prefix = env_title_prefix or self.config_loader.get("title_prefix", "")
+        
+        # 创建API客户端
+        self.client = ZenTaoAPIClient(silent=True)
+    
+    def _format_steps_to_html(self, steps):
+        """将steps中的换行转换为HTML格式"""
+        if not steps:
+            return ""
+        
+        lines = steps.strip().split('\n')
+        html_steps = []
+        
+        for line in lines:
+            line = line.strip()
+            if not line:
+                continue
+            
+            if line and line[0].isdigit() and ('.' in line[:3] or '、' in line[:3]):
+                html_steps.append(f"<p>{line}</p>")
+            elif line.startswith('- '):
+                html_steps.append(f"<p>• {line[2:]}</p>")
+            elif '：' in line or ':' in line:
+                html_steps.append(f"<p><strong>{line}</strong></p>")
+            else:
+                html_steps.append(f"<p>{line}</p>")
+        
+        return ''.join(html_steps)
+
+    def create_bug(self, title, steps, product_id=None, opened_by=None, screenshot_path=None, **kwargs):
+        """
+        创建Bug（支持截图上传）
+        
+        Args:
+            title (str): Bug标题
+            steps (str): 重现步骤（支持换行，会自动转换为HTML格式）
+            product_id (str): 产品ID，如果为None则使用配置值
+            opened_by (str): 创建人和指派人，如果为None则使用配置值
+            screenshot_path (str): 截图文件路径，如果提供则会上传到禅道
+            **kwargs: 其他可选参数
+                - severity: 严重程度（默认3）
+                - pri: 优先级（默认3）
+                - type: Bug类型（默认功能缺陷）
+                - environment: 环境（默认测试环境）
+                - story: 相关需求id
+                - task: 相关任务id
+                - mailto: 抄送人账号
+                - keywords: 关键词
+        
+        Returns:
+            dict: 创建结果
+        """
+        product_id = product_id or self.product_id
+        opened_by = opened_by or self.opened_by
+        keywords = kwargs.get("keywords", self.keywords)
+        
+        # 处理标题前缀：如果 title_prefix 不为空字符串，则在标题前面加上【title_prefix】
+        original_title = title
+        if self.title_prefix and self.title_prefix.strip():
+            title = f"【{self.title_prefix}】{title}"
+        
+        html_steps = self._format_steps_to_html(steps)
+        
+        bug_data = {
+            "product": product_id,
+            "openedBuild": kwargs.get("opened_build", self.OPENED_BUILD),
+            "environment": kwargs.get("environment", self.ENVIRONMENT),
+            "title": title,
+            "assignedTo": opened_by,
+            "deadline": (datetime.now() + timedelta(days=self.DEADLINE_DAYS)).strftime("%Y-%m-%d"),
+            "type": kwargs.get("type", self.BUG_TYPE),
+            "source": kwargs.get("source", self.BUG_SOURCE),
+            "lowerBug": kwargs.get("lowerBug", self.LOWER_BUG),
+            "regression": kwargs.get("regression", self.REGRESSION),
+            "severity": kwargs.get("severity", self.SEVERITY),
+            "pri": kwargs.get("pri", self.PRIORITY),
+            "steps": html_steps,
+            "story": kwargs.get("story", "0"),
+            "task": kwargs.get("task", "0"),
+            "mailto": kwargs.get("mailto", ""),
+            "keywords": keywords,
+            "openedBy": opened_by
+        }
+        
+        import contextlib
+        with contextlib.redirect_stderr(open(os.devnull, 'w')):
+            result = self.client.create_bug_by_api(bug_data)
+        
+        if result.get("status") == 1 and result.get("bugID"):
+            bug_id = result.get("bugID")
+            bug_url = f"{self.client.base_url}/zentaopms/www/index.php?m=bug&f=view&bugID={bug_id}"
+            result["bug_url"] = bug_url
+            result["actual_title"] = title  # 返回实际提交的标题（包含前缀）
+            
+            if screenshot_path and os.path.exists(screenshot_path):
+                try:
+                    upload_result = self.client.upload_image_to_bug(bug_id, screenshot_path)
+                    if upload_result.get("status") == 1:
+                        result["screenshot_uploaded"] = True
+                        result["screenshot_message"] = "截图上传成功"
+                    else:
+                        result["screenshot_uploaded"] = False
+                        result["screenshot_message"] = f"截图上传失败: {upload_result.get('message')}"
+                except Exception as e:
+                    result["screenshot_uploaded"] = False
+                    result["screenshot_message"] = f"截图上传异常: {str(e)}"
+            else:
+                result["screenshot_uploaded"] = False
+                result["screenshot_message"] = "未提供截图文件"
+        
+        return result
+    
+    def get_config(self):
+        """获取当前配置信息"""
+        return {
+            "product_id": self.product_id,
+            "opened_by": self.opened_by,
+            "keywords": self.keywords,
+            "title_prefix": self.title_prefix
+        }
+    
+    def upload_image_to_bug(self, bug_id, image_path, custom_filename=None):
+        """上传图片到指定Bug"""
+        return self.client.upload_image_to_bug(bug_id, image_path, custom_filename)
+    
+    def create_case_from_csv(self, csv_file_path, case_type=None):
+        """从CSV文件批量创建测试用例"""
+        return self.client.create_case_from_csv(csv_file_path, case_type, self.product_id, self.opened_by, self.keywords)
+    
+    def submit_csv_cases_to_zentao(self, csv_file_path, case_type=None):
+        """将CSV文件中的所有测试用例提交到禅道"""
+        return self.client.submit_csv_cases_to_zentao(csv_file_path, case_type, self.product_id, self.opened_by, self.keywords)
+
+
+# 便捷函数
+def create_bug(title, steps, product_id=None, opened_by=None, screenshot_path=None, config_path=None, **kwargs):
+    """便捷函数：快速创建Bug"""
+    nexus = ZenTaoNexus(config_path)
+    return nexus.create_bug(title, steps, product_id, opened_by, screenshot_path, **kwargs)
+
+
+if __name__ == "__main__":
+    print("=== ZenTao Nexus 工具类示例 ===\n")
+    
+    try:
+        nexus = ZenTaoNexus()
+        
+        print("当前配置:")
+        config = nexus.get_config()
+        for key, value in config.items():
+            print(f"  {key}: {value}")
+        
+        print("\n✅ ZenTao Nexus 初始化成功！")
+        print("\n使用示例:")
+        print("  from zentao_nexus import ZenTaoNexus")
+        print("  nexus = ZenTaoNexus()")
+        print("  result = nexus.create_bug(")
+        print("      title='测试Bug',")
+        print("      steps='重现步骤\\n1. 第一步'")
+        print("  )")
+        
+    except Exception as e:
+        print(f"❌ 初始化失败: {str(e)}")
+        print("\n请检查:")
+        print("  1. config.json 文件是否存在")
+        print("  2. 配置文件格式是否正确")
+        print("  3. 配置文件中是否包含 product_id、opened_by 和 keywords")
+