@bangdao-ai/zentao-mcp 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bangdao-ai/zentao-mcp",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "禅道项目管理AI中枢 v2.0 — 35+MCP工具覆盖需求·任务·Bug·用例·发布·我的地盘全生命周期，原生API模式，Bug智能分类引擎+CSV批量用例导入+截图上传，一句话驱动禅道",
   "main": "index.js",
   "bin": {

package/src/core/zentao_nexus.py

@@ -36,7 +36,7 @@ def _safe_path(path: str, must_exist: bool = False) -> str:
     """
     _init_allowed_dirs()
     real = os.path.realpath(os.path.expanduser(path))
-    if not any(real.startswith(d) for d in _ALLOWED_WORK_DIRS):
+    if not any(real == d or real.startswith(d + os.sep) for d in _ALLOWED_WORK_DIRS):
         _security_logger.warning("路径安全拒绝: %s (resolved: %s)", path, real)
         raise ValueError(f"路径不在允许的工作目录内: {path}")
     if must_exist and not os.path.exists(real):
@@ -1071,14 +1071,21 @@ class ZenTaoNexus:
         if not gateway_payload.get("mold"):
             gateway_payload["mold"] = "20"
         result = self.client.task_create_by_gateway(gateway_payload)
-        if result.get("status") == 1 and result.get("taskID"):
+        if result.get("status") == 1:
+            tid = result.get("taskID")
+            if not tid and task_name:
+                tid = self._find_recent_task_id_by_name(task_name)
+            if tid:
+                result["taskID"] = tid
             result["projectID"] = str(project_id)
             result["create_channel"] = "gateway"
+            if not tid:
+                result["warning"] = "任务已通过网关创建成功，但无法获取 taskID"
             return result
 
         gateway_error = result
 
-        # 2) 网关失败时回退到原生 task.create（仍要求必须拿到 taskID）
+        # 2) 网关失败时回退到原生 task.create
         native_result = self.client.task_create(project_id, task_data)
         if native_result.get("status") == 1:
             data = native_result.get("data", {})
@@ -1087,25 +1094,18 @@ class ZenTaoNexus:
                 tid = self._find_recent_task_id_by_name(task_name)
             if tid:
                 native_result["taskID"] = tid
-                native_result["projectID"] = str(project_id)
-                native_result["create_channel"] = "native"
-                return native_result
-            result = {
-                "status": 0,
-                "message": "fail",
-                "info": "任务创建返回 success 但无 taskID，判定为未实际创建",
-                "data": data,
-                "projectID": str(project_id),
-                "gateway_error": gateway_error,
-            }
-        else:
-            result = dict(native_result) if isinstance(native_result, dict) else {
-                "status": 0, "message": "fail", "info": str(native_result), "data": {}
-            }
-            result["gateway_error"] = gateway_error
+            native_result["projectID"] = str(project_id)
+            native_result["create_channel"] = "native"
+            if not tid:
+                native_result["warning"] = "任务已通过原生接口创建成功，但无法获取 taskID"
+            return native_result
+
+        result = dict(native_result) if isinstance(native_result, dict) else {
+            "status": 0, "message": "fail", "info": str(native_result), "data": {}
+        }
+        result["gateway_error"] = gateway_error
 
         if str(project_id) == "0":
-            # 便于排查：当无法自动选出项目时返回候选项
             candidates = self.get_product_projects(product_id)
             if candidates.get("status") == 1:
                 result["project_candidates"] = candidates.get("data", {}).get("projects", [])
@@ -1333,20 +1333,29 @@ class ZenTaoNexus:
                 case_id = self._find_recent_case_id_by_name(case_title)
             if case_id:
                 result["caseID"] = case_id
-                return result
+            result["create_channel"] = "native"
+            if not case_id:
+                result["warning"] = "用例已通过原生接口创建成功，但无法获取 caseID"
+            return result
 
-        # 原生成功但无法拿到 caseID 时，回退网关创建，确保后续流程可追踪 caseID。
+        # 原生创建失败时，回退到网关创建
         gateway_payload = dict(case_data)
         gateway_result = self.client.testcase_create_by_gateway(gateway_payload)
-        if gateway_result.get("status") == 1 and gateway_result.get("caseID"):
+        if gateway_result.get("status") == 1:
             gateway_result["create_channel"] = "gateway"
+            if not gateway_result.get("caseID") and case_title:
+                cid = self._find_recent_case_id_by_name(case_title)
+                if cid:
+                    gateway_result["caseID"] = cid
+            if not gateway_result.get("caseID"):
+                gateway_result["warning"] = "用例已通过网关创建成功，但无法获取 caseID"
             return gateway_result
 
-        return result if result.get("status") != 1 else {
+        return {
             "status": 0,
             "message": "fail",
-            "info": "用例创建返回 success 但无 caseID，且网关回退失败",
-            "data": result.get("data", {}),
+            "info": "原生和网关均创建失败",
+            "native_error": result,
             "gateway_error": gateway_result,
         }
 
@@ -1518,9 +1527,20 @@ class ZenTaoNexus:
     }
 
     def export_bug_detail(self, bug_id, output_dir=None) -> Dict:
-        """导出 Bug 详情到本地文件夹：{bug_id}_bug/{bug_id}_bug.md + 附件 + 图片 + 备注"""
+        """
+        导出 Bug 完整详情到本地文件夹，结构：
+          bug_{bug_id}/
+          ├── bug_{bug_id}.md          # 完整 Markdown 文档
+          ├── images/                   # 描述 + 备注中的图片
+          │   ├── step_1.png
+          │   └── comment_1.png
+          └── attachments/              # Bug 附件
+              ├── 需求文档.pdf
+              └── 截图.png
+        """
         if output_dir:
             output_dir = _safe_path(output_dir)
+
         detail = self.client.bug_view_full(bug_id)
         if detail.get("status") != 1:
             return detail
@@ -1530,7 +1550,6 @@ class ZenTaoNexus:
         users = detail.get("users", {})
 
         def _name(field, mapping=None):
-            """取友好名称：优先 xxxName 字段，否则用映射表，最后用原始值"""
             name_val = bug.get(f"{field}Name")
             raw = str(bug.get(field, '') or '')
             if name_val and name_val != 'None':
@@ -1538,55 +1557,133 @@ class ZenTaoNexus:
             if mapping and raw in mapping:
                 return mapping[raw]
             return raw
-        folder_name = f"{bug_id}_bug"
+
+        # ── 创建目录结构 ──
+        folder_name = f"bug_{bug_id}"
         base_dir = os.path.join(output_dir, folder_name) if output_dir else folder_name
-        os.makedirs(base_dir, exist_ok=True)
+        images_dir = os.path.join(base_dir, "images")
+        attach_dir = os.path.join(base_dir, "attachments")
+        os.makedirs(images_dir, exist_ok=True)
+        os.makedirs(attach_dir, exist_ok=True)
 
         downloaded_files = []
         downloaded_images = []
 
-        # 下载附件（files 可能是 dict{id: info} 或 list[info]）
-        raw_files = bug.get("files", {})
-        file_list = list(raw_files.values()) if isinstance(raw_files, dict) else raw_files
-        for file_info in file_list:
-            if isinstance(file_info, str):
+        img_pattern = re.compile(
+            r'<img\s+[^>]*src=["\']([^"\']+)["\'][^>]*/?>',
+            re.IGNORECASE,
+        )
+
+        def _guess_ext(url: str, fallback: str = ".png") -> str:
+            for pat in (r't=(png|jpe?g|gif|bmp|webp)',
+                        r'\.(png|jpe?g|gif|bmp|webp)(?:[?#]|$)'):
+                m = re.search(pat, url, re.IGNORECASE)
+                if m:
+                    e = m.group(1).lower()
+                    return f".{'jpg' if e == 'jpeg' else e}"
+            return fallback
+
+        def _download_image(url: str, name: str, category: str) -> bool:
+            save_path = os.path.join(images_dir, name)
+            r = self.client.file_download(url, save_path)
+            ok = r.get("status") == 1
+            downloaded_images.append({
+                "name": name, "type": category,
+                "success": ok, "size": r.get("size", 0),
+            })
+            return ok
+
+        # ── 1. 下载附件 ──
+        raw_files = bug.get("files") or {}
+        file_list = (list(raw_files.values()) if isinstance(raw_files, dict)
+                     else raw_files if isinstance(raw_files, list) else [])
+        for fi in file_list:
+            if not isinstance(fi, dict):
                 continue
-            title = file_info.get("title", "unknown")
-            secret_id = file_info.get("secretID", "")
-            url = file_info.get("downloadUrl", "")
-            if not url and secret_id:
-                url = (f"{self.client.base_url}/zentaopms/www/index.php"
-                       f"?m=file&f=download&t=json&fileID={secret_id}")
+            title = fi.get("title", "unknown")
+            url = fi.get("downloadUrl", "")
+            if not url:
+                ident = fi.get("secretID") or fi.get("id") or ""
+                if ident:
+                    url = (f"{self.client.base_url}/zentaopms/www/index.php"
+                           f"?m=file&f=download&t=json&fileID={ident}")
             if not url:
+                downloaded_files.append({
+                    "name": title, "saved": "", "success": False,
+                    "size": 0, "reason": "no_download_url",
+                })
                 continue
             safe_name = re.sub(r'[<>:"/\\|?*]', '_', title)
-            save_path = os.path.join(base_dir, safe_name)
+            save_path = os.path.join(attach_dir, safe_name)
             r = self.client.file_download(url, save_path)
             downloaded_files.append({
-                "name": title, "saved": safe_name,
+                "name": title, "saved": f"attachments/{safe_name}",
                 "success": r.get("status") == 1,
                 "size": r.get("size", 0),
             })
 
-        # 从 steps HTML 提取并下载图片，替换为本地路径
-        steps_html = bug.get("steps", "").replace("&amp;", "&")
-        img_pattern = re.compile(r'<img\s+[^>]*src="([^"]+)"[^>]*/?>',  re.IGNORECASE)
-        img_index = 0
+        # ── 2. 下载描述（steps）中的图片 ──
+        steps_html = (bug.get("steps") or "").replace("&amp;", "&")
+        step_img_idx = 0
         for match in img_pattern.finditer(steps_html):
             img_url = match.group(1)
-            ext = ".png"
-            ext_match = re.search(r't=(png|jpg|jpeg|gif|bmp|webp)', img_url, re.IGNORECASE)
-            if ext_match:
-                ext = f".{ext_match.group(1).lower()}"
-            img_index += 1
-            img_name = f"step_img_{img_index}{ext}"
-            save_path = os.path.join(base_dir, img_name)
-            r = self.client.file_download(img_url, save_path)
-            if r.get("status") == 1:
-                steps_html = steps_html.replace(img_url, f"./{img_name}")
-                downloaded_images.append(img_name)
-
-        # 生成 Markdown
+            if img_url.startswith("data:"):
+                continue
+            step_img_idx += 1
+            ext = _guess_ext(img_url)
+            img_name = f"step_{step_img_idx}{ext}"
+            if _download_image(img_url, img_name, "step"):
+                steps_html = steps_html.replace(img_url, f"./images/{img_name}")
+
+        # ── 3. 处理备注 & 下载备注中的图片 ──
+        _ACTION_MAP = {
+            "opened": "创建", "edited": "编辑", "commented": "备注",
+            "resolved": "解决", "closed": "关闭", "activated": "激活",
+            "confirmed": "确认", "assigned": "指派", "bugconfirmed": "确认",
+        }
+        action_list = (list(actions.values()) if isinstance(actions, dict)
+                       else actions if isinstance(actions, list) else [])
+
+        comment_img_idx = 0
+        comments_data = []
+
+        for act in action_list:
+            if not isinstance(act, dict):
+                continue
+            action_type = act.get("action", "")
+            actor_id = act.get("actor", "")
+            actor_name = users.get(actor_id, actor_id) if users else actor_id
+            date = act.get("date", "")
+            comment_html = (act.get("comment") or "").strip()
+            processed_comment = ""
+
+            if comment_html:
+                comment_html = comment_html.replace("&amp;", "&").replace("&nbsp;", " ")
+                for img_match in img_pattern.finditer(comment_html):
+                    c_url = img_match.group(1)
+                    if c_url.startswith("data:"):
+                        continue
+                    if not c_url.startswith("http"):
+                        c_url = f"{self.client.base_url}{c_url}"
+                    comment_img_idx += 1
+                    ext = _guess_ext(c_url)
+                    c_img_name = f"comment_{comment_img_idx}{ext}"
+                    if _download_image(c_url, c_img_name, "comment"):
+                        comment_html = comment_html.replace(
+                            img_match.group(0),
+                            f'<img src="./images/{c_img_name}" alt="" />')
+                processed_comment = self._html_to_markdown(comment_html)
+
+            comments_data.append({
+                "date": date,
+                "actor": actor_name,
+                "action": action_type,
+                "action_label": _ACTION_MAP.get(action_type, action_type),
+                "comment": processed_comment,
+                "history": act.get("history") or act.get("histories") or [],
+            })
+
+        # ── 4. 生成完整 Markdown ──
         md_lines = [
             f"# Bug #{bug_id}: {bug.get('title', '')}",
             "",
@@ -1596,6 +1693,7 @@ class ZenTaoNexus:
             "|------|------|",
             f"| ID | {bug_id} |",
             f"| 产品 | {_name('product')} |",
+            f"| 模块 | {_name('module')} |",
             f"| 状态 | {_name('status', self._STATUS_MAP)} |",
             f"| 严重程度 | {_name('severity', self._SEVERITY_MAP)} |",
             f"| 优先级 | P{bug.get('pri', '')} |",
@@ -1603,130 +1701,125 @@ class ZenTaoNexus:
             f"| 指派给 | {_name('assignedTo')} |",
             f"| 创建人 | {_name('openedBy')} |",
             f"| 创建时间 | {bug.get('openedDate', '')} |",
-            f"| 截止日期 | {bug.get('deadline', '')} |",
             f"| 解决人 | {_name('resolvedBy') or '-'} |",
+            f"| 解决时间 | {bug.get('resolvedDate', '') or '-'} |",
             f"| 解决方案 | {_name('resolution', self._RESOLUTION_MAP) or '-'} |",
-            f"| 关键词 | {bug.get('keywords', '')} |",
+            f"| 关闭人 | {_name('closedBy') or '-'} |",
+            f"| 关闭时间 | {bug.get('closedDate', '') or '-'} |",
+            f"| 截止日期 | {bug.get('deadline', '') or '-'} |",
+            f"| 关键词 | {bug.get('keywords', '') or '-'} |",
+            f"| 关联需求 | {bug.get('story', '') or '-'} |",
+            f"| 关联任务 | {bug.get('task', '') or '-'} |",
             "",
             "## 复现步骤",
             "",
+            self._html_to_markdown(steps_html),
+            "",
         ]
 
-        steps_md = self._html_to_markdown(steps_html)
-        md_lines.append(steps_md)
-        md_lines.append("")
-
+        # ── 附件列表 ──
         if downloaded_files:
             md_lines.append("## 附件")
             md_lines.append("")
             for f in downloaded_files:
+                path_ref = f"./{f['saved']}" if f["saved"] else ""
                 if f["success"]:
                     is_img = any(f["saved"].lower().endswith(e)
-                                for e in ('.png','.jpg','.jpeg','.gif','.bmp','.webp'))
+                                for e in ('.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp'))
                     if is_img:
-                        md_lines.append(f"![{f['name']}](./{f['saved']})")
+                        md_lines.append(f"![{f['name']}]({path_ref})")
                     else:
-                        md_lines.append(f"- [{f['name']}](./{f['saved']})")
+                        size_kb = round(f["size"] / 1024, 1) if f["size"] else 0
+                        md_lines.append(f"- [{f['name']}]({path_ref}) ({size_kb} KB)")
                 else:
-                    md_lines.append(f"- {f['name']}（下载失败）")
+                    md_lines.append(f"- {f['name']}（下载失败: {f.get('reason', 'unknown')}）")
             md_lines.append("")
 
-        # 备注/操作历史
-        _ACTION_MAP = {
-            "opened": "创建", "edited": "编辑", "commented": "备注",
-            "resolved": "解决", "closed": "关闭", "activated": "激活",
-            "confirmed": "确认", "assigned": "指派", "bugconfirmed": "确认",
-        }
-        action_list = list(actions.values()) if isinstance(actions, dict) else actions
-        has_comments = any(
-            a.get("comment", "").strip() for a in action_list if isinstance(a, dict)
-        )
-        if action_list:
-            md_lines.append("## 操作历史")
+        # ── 操作历史 & 备注 ──
+        if comments_data:
+            md_lines.append("## 操作历史 & 备注")
             md_lines.append("")
-            comment_img_idx = 0
-            for act in action_list:
-                if not isinstance(act, dict):
-                    continue
-                action_type = act.get("action", "")
-                action_label = _ACTION_MAP.get(action_type, action_type)
-                actor_id = act.get("actor", "")
-                actor_name = users.get(actor_id, actor_id) if users else actor_id
-                date = act.get("date", "")
-                comment_html = (act.get("comment") or "").strip()
-
-                md_lines.append(f"### {date} — {actor_name} [{action_label}]")
+            for c in comments_data:
+                md_lines.append(f"### {c['date']} — {c['actor']} [{c['action_label']}]")
                 md_lines.append("")
-
-                if comment_html:
-                    comment_html = comment_html.replace("&amp;", "&").replace("&nbsp;", " ")
-                    for img_match in img_pattern.finditer(comment_html):
-                        img_url = img_match.group(1)
-                        if not img_url.startswith('http'):
-                            img_url = f"{self.client.base_url}{img_url}"
-                        ext = ".png"
-                        ext_m = re.search(r't=(png|jpg|jpeg|gif|bmp|webp)', img_url, re.IGNORECASE)
-                        if ext_m:
-                            ext = f".{ext_m.group(1).lower()}"
-                        comment_img_idx += 1
-                        c_img_name = f"comment_img_{comment_img_idx}{ext}"
-                        c_save = os.path.join(base_dir, c_img_name)
-                        r = self.client.file_download(img_url, c_save)
-                        if r.get("status") == 1:
-                            comment_html = comment_html.replace(
-                                img_match.group(0),
-                                f'<img src="./{c_img_name}" alt="" />')
-                            downloaded_images.append(c_img_name)
-
-                    comment_md = self._html_to_markdown(comment_html)
-                    md_lines.append(comment_md)
+                if c["comment"]:
+                    md_lines.append(c["comment"])
                     md_lines.append("")
-
-                history = act.get("history", [])
-                if history:
+                history = c["history"]
+                if isinstance(history, list):
                     for h in history:
+                        if not isinstance(h, dict):
+                            continue
                         field = h.get("field", "")
-                        old_val = h.get("old", "")
-                        new_val = h.get("new", "")
+                        old_val = str(h.get("old", ""))
+                        new_val = str(h.get("new", ""))
                         if old_val or new_val:
-                            old_short = (old_val[:80] + '...') if len(old_val) > 80 else old_val
-                            new_short = (new_val[:80] + '...') if len(new_val) > 80 else new_val
-                            md_lines.append(f"- **{field}**: `{old_short}` → `{new_short}`")
-                    md_lines.append("")
+                            old_s = (old_val[:100] + '…') if len(old_val) > 100 else old_val
+                            new_s = (new_val[:100] + '…') if len(new_val) > 100 else new_val
+                            md_lines.append(f"- **{field}**: `{old_s}` → `{new_s}`")
+                    if history:
+                        md_lines.append("")
 
         md_content = "\n".join(md_lines)
-        md_path = os.path.join(base_dir, f"{bug_id}_bug.md")
+        md_path = os.path.join(base_dir, f"bug_{bug_id}.md")
         with open(md_path, 'w', encoding='utf-8') as fw:
             fw.write(md_content)
 
+        abs_folder = os.path.abspath(base_dir)
+        abs_md = os.path.abspath(md_path)
+
         return {
             "status": 1,
             "message": "success",
-            "bug": bug,
+            "data": {
+                "bug": bug,
+                "comments": comments_data,
+                "users": users,
+            },
             "export": {
-                "folder": os.path.abspath(base_dir),
-                "markdown": os.path.abspath(md_path),
+                "folder": abs_folder,
+                "markdown": abs_md,
                 "attachments": downloaded_files,
-                "step_images": downloaded_images,
-            }
+                "images": downloaded_images,
+                "summary": {
+                    "total_attachments": len(downloaded_files),
+                    "downloaded_attachments": sum(1 for f in downloaded_files if f["success"]),
+                    "total_images": len(downloaded_images),
+                    "downloaded_images": sum(1 for i in downloaded_images if i["success"]),
+                    "total_comments": sum(1 for c in comments_data if c["comment"]),
+                },
+            },
         }
 
     @staticmethod
     def _html_to_markdown(html: str) -> str:
-        """简易 HTML→Markdown：处理 p、strong、img、br 标签"""
+        """HTML → Markdown 转换"""
         if not html:
             return ""
         text = html
-        text = re.sub(r'<img\s+[^>]*src="([^"]+)"[^>]*alt="([^"]*)"[^>]*/?>',
+        text = re.sub(r'<img\s+[^>]*src=["\']([^"\']+)["\'][^>]*alt=["\']([^"\']*)["\'][^>]*/?>',
                        r'![\2](\1)', text)
-        text = re.sub(r'<img\s+[^>]*src="([^"]+)"[^>]*/?>',
+        text = re.sub(r'<img\s+[^>]*src=["\']([^"\']+)["\'][^>]*/?>',
                        r'![](\1)', text)
+        for i in range(6, 0, -1):
+            text = re.sub(rf'<h{i}[^>]*>(.*?)</h{i}>', r'\n' + '#' * i + r' \1\n', text, flags=re.DOTALL)
+        text = re.sub(r'<a\s+[^>]*href=["\']([^"\']+)["\'][^>]*>(.*?)</a>', r'[\2](\1)', text, flags=re.DOTALL)
         text = re.sub(r'<strong>(.*?)</strong>', r'**\1**', text)
         text = re.sub(r'<b>(.*?)</b>', r'**\1**', text)
         text = re.sub(r'<em>(.*?)</em>', r'*\1*', text)
+        text = re.sub(r'<code>(.*?)</code>', r'`\1`', text)
+        text = re.sub(r'<pre[^>]*>(.*?)</pre>', r'\n```\n\1\n```\n', text, flags=re.DOTALL)
+        text = re.sub(r'<li[^>]*>(.*?)</li>', r'- \1\n', text, flags=re.DOTALL)
+        text = re.sub(r'</?[ou]l[^>]*>', '\n', text)
         text = re.sub(r'<br\s*/?>', '\n', text)
-        text = re.sub(r'<p>(.*?)</p>', r'\1\n', text, flags=re.DOTALL)
+        text = re.sub(r'<p[^>]*>(.*?)</p>', r'\1\n', text, flags=re.DOTALL)
+        text = re.sub(r'<hr\s*/?>', '\n---\n', text)
+        text = re.sub(r'</?(?:div|span|table|thead|tbody|tr|td|th|blockquote)[^>]*>', '\n', text)
         text = re.sub(r'<[^>]+>', '', text)
+        text = re.sub(r'&lt;', '<', text)
+        text = re.sub(r'&gt;', '>', text)
+        text = re.sub(r'&quot;', '"', text)
+        text = re.sub(r'&nbsp;', ' ', text)
         text = re.sub(r'\n{3,}', '\n\n', text)
         return text.strip()
 

package/src/mcp/server.py

@@ -93,12 +93,12 @@ class ZenTaoMCPServer:
             ),
             Tool(
                 name="get_bug_detail",
-                description="获取Bug详情并自动导出到本地文件夹（含Markdown文档、附件、步骤截图）",
+                description="获取Bug完整详情并导出到 bug_{id}/ 文件夹（含Markdown、描述图片、附件、备注图片，完整返回bug数据+备注+下载清单）",
                 inputSchema={
                     "type": "object",
                     "properties": {
                         "bug_id": {"type": "string", "description": "Bug ID"},
-                        "output_dir": {"type": "string", "description": "导出目录（可选，默认当前目录）"},
+                        "output_dir": {"type": "string", "description": "导出根目录（可选，默认当前目录，实际文件存于 bug_{id}/ 子目录）"},
                     },
                     "required": ["bug_id"],
                 }

package/src/mcp_server.py

@@ -88,12 +88,12 @@ class ZenTaoMCPServer:
             ),
             Tool(
                 name="get_bug_detail",
-                description="获取Bug详情并自动导出到本地文件夹（含Markdown文档、附件、步骤截图）",
+                description="获取Bug完整详情并导出到 bug_{id}/ 文件夹（含Markdown、描述图片、附件、备注图片，完整返回bug数据+备注+下载清单）",
                 inputSchema={
                     "type": "object",
                     "properties": {
                         "bug_id": {"type": "string", "description": "Bug ID"},
-                        "output_dir": {"type": "string", "description": "导出目录（可选，默认当前目录）"},
+                        "output_dir": {"type": "string", "description": "导出根目录（可选，默认当前目录，实际文件存于 bug_{id}/ 子目录）"},
                     },
                     "required": ["bug_id"],
                 }

package/src/zentao_nexus.py

@@ -1346,7 +1346,17 @@ class ZenTaoNexus:
     }
 
     def export_bug_detail(self, bug_id, output_dir=None) -> Dict:
-        """导出 Bug 详情到本地文件夹：{bug_id}_bug/{bug_id}_bug.md + 附件 + 图片 + 备注"""
+        """
+        导出 Bug 完整详情到本地文件夹，结构：
+          bug_{bug_id}/
+          ├── bug_{bug_id}.md          # 完整 Markdown 文档
+          ├── images/                   # 描述 + 备注中的图片
+          │   ├── step_1.png
+          │   └── comment_1.png
+          └── attachments/              # Bug 附件
+              ├── 需求文档.pdf
+              └── 截图.png
+        """
         detail = self.client.bug_view_full(bug_id)
         if detail.get("status") != 1:
             return detail
@@ -1356,7 +1366,6 @@ class ZenTaoNexus:
         users = detail.get("users", {})
 
         def _name(field, mapping=None):
-            """取友好名称：优先 xxxName 字段，否则用映射表，最后用原始值"""
             name_val = bug.get(f"{field}Name")
             raw = str(bug.get(field, '') or '')
             if name_val and name_val != 'None':
@@ -1364,55 +1373,133 @@ class ZenTaoNexus:
             if mapping and raw in mapping:
                 return mapping[raw]
             return raw
-        folder_name = f"{bug_id}_bug"
+
+        # ── 创建目录结构 ──
+        folder_name = f"bug_{bug_id}"
         base_dir = os.path.join(output_dir, folder_name) if output_dir else folder_name
-        os.makedirs(base_dir, exist_ok=True)
+        images_dir = os.path.join(base_dir, "images")
+        attach_dir = os.path.join(base_dir, "attachments")
+        os.makedirs(images_dir, exist_ok=True)
+        os.makedirs(attach_dir, exist_ok=True)
 
         downloaded_files = []
         downloaded_images = []
 
-        # 下载附件（files 可能是 dict{id: info} 或 list[info]）
-        raw_files = bug.get("files", {})
-        file_list = list(raw_files.values()) if isinstance(raw_files, dict) else raw_files
-        for file_info in file_list:
-            if isinstance(file_info, str):
+        img_pattern = re.compile(
+            r'<img\s+[^>]*src=["\']([^"\']+)["\'][^>]*/?>',
+            re.IGNORECASE,
+        )
+
+        def _guess_ext(url: str, fallback: str = ".png") -> str:
+            for pat in (r't=(png|jpe?g|gif|bmp|webp)',
+                        r'\.(png|jpe?g|gif|bmp|webp)(?:[?#]|$)'):
+                m = re.search(pat, url, re.IGNORECASE)
+                if m:
+                    e = m.group(1).lower()
+                    return f".{'jpg' if e == 'jpeg' else e}"
+            return fallback
+
+        def _download_image(url: str, name: str, category: str) -> bool:
+            save_path = os.path.join(images_dir, name)
+            r = self.client.file_download(url, save_path)
+            ok = r.get("status") == 1
+            downloaded_images.append({
+                "name": name, "type": category,
+                "success": ok, "size": r.get("size", 0),
+            })
+            return ok
+
+        # ── 1. 下载附件 ──
+        raw_files = bug.get("files") or {}
+        file_list = (list(raw_files.values()) if isinstance(raw_files, dict)
+                     else raw_files if isinstance(raw_files, list) else [])
+        for fi in file_list:
+            if not isinstance(fi, dict):
                 continue
-            title = file_info.get("title", "unknown")
-            secret_id = file_info.get("secretID", "")
-            url = file_info.get("downloadUrl", "")
-            if not url and secret_id:
-                url = (f"{self.client.base_url}/zentaopms/www/index.php"
-                       f"?m=file&f=download&t=json&fileID={secret_id}")
+            title = fi.get("title", "unknown")
+            url = fi.get("downloadUrl", "")
             if not url:
+                ident = fi.get("secretID") or fi.get("id") or ""
+                if ident:
+                    url = (f"{self.client.base_url}/zentaopms/www/index.php"
+                           f"?m=file&f=download&t=json&fileID={ident}")
+            if not url:
+                downloaded_files.append({
+                    "name": title, "saved": "", "success": False,
+                    "size": 0, "reason": "no_download_url",
+                })
                 continue
             safe_name = re.sub(r'[<>:"/\\|?*]', '_', title)
-            save_path = os.path.join(base_dir, safe_name)
+            save_path = os.path.join(attach_dir, safe_name)
             r = self.client.file_download(url, save_path)
             downloaded_files.append({
-                "name": title, "saved": safe_name,
+                "name": title, "saved": f"attachments/{safe_name}",
                 "success": r.get("status") == 1,
                 "size": r.get("size", 0),
             })
 
-        # 从 steps HTML 提取并下载图片，替换为本地路径
-        steps_html = bug.get("steps", "").replace("&amp;", "&")
-        img_pattern = re.compile(r'<img\s+[^>]*src="([^"]+)"[^>]*/?>',  re.IGNORECASE)
-        img_index = 0
+        # ── 2. 下载描述（steps）中的图片 ──
+        steps_html = (bug.get("steps") or "").replace("&amp;", "&")
+        step_img_idx = 0
         for match in img_pattern.finditer(steps_html):
             img_url = match.group(1)
-            ext = ".png"
-            ext_match = re.search(r't=(png|jpg|jpeg|gif|bmp|webp)', img_url, re.IGNORECASE)
-            if ext_match:
-                ext = f".{ext_match.group(1).lower()}"
-            img_index += 1
-            img_name = f"step_img_{img_index}{ext}"
-            save_path = os.path.join(base_dir, img_name)
-            r = self.client.file_download(img_url, save_path)
-            if r.get("status") == 1:
-                steps_html = steps_html.replace(img_url, f"./{img_name}")
-                downloaded_images.append(img_name)
-
-        # 生成 Markdown
+            if img_url.startswith("data:"):
+                continue
+            step_img_idx += 1
+            ext = _guess_ext(img_url)
+            img_name = f"step_{step_img_idx}{ext}"
+            if _download_image(img_url, img_name, "step"):
+                steps_html = steps_html.replace(img_url, f"./images/{img_name}")
+
+        # ── 3. 处理备注 & 下载备注中的图片 ──
+        _ACTION_MAP = {
+            "opened": "创建", "edited": "编辑", "commented": "备注",
+            "resolved": "解决", "closed": "关闭", "activated": "激活",
+            "confirmed": "确认", "assigned": "指派", "bugconfirmed": "确认",
+        }
+        action_list = (list(actions.values()) if isinstance(actions, dict)
+                       else actions if isinstance(actions, list) else [])
+
+        comment_img_idx = 0
+        comments_data = []
+
+        for act in action_list:
+            if not isinstance(act, dict):
+                continue
+            action_type = act.get("action", "")
+            actor_id = act.get("actor", "")
+            actor_name = users.get(actor_id, actor_id) if users else actor_id
+            date = act.get("date", "")
+            comment_html = (act.get("comment") or "").strip()
+            processed_comment = ""
+
+            if comment_html:
+                comment_html = comment_html.replace("&amp;", "&").replace("&nbsp;", " ")
+                for img_match in img_pattern.finditer(comment_html):
+                    c_url = img_match.group(1)
+                    if c_url.startswith("data:"):
+                        continue
+                    if not c_url.startswith("http"):
+                        c_url = f"{self.client.base_url}{c_url}"
+                    comment_img_idx += 1
+                    ext = _guess_ext(c_url)
+                    c_img_name = f"comment_{comment_img_idx}{ext}"
+                    if _download_image(c_url, c_img_name, "comment"):
+                        comment_html = comment_html.replace(
+                            img_match.group(0),
+                            f'<img src="./images/{c_img_name}" alt="" />')
+                processed_comment = self._html_to_markdown(comment_html)
+
+            comments_data.append({
+                "date": date,
+                "actor": actor_name,
+                "action": action_type,
+                "action_label": _ACTION_MAP.get(action_type, action_type),
+                "comment": processed_comment,
+                "history": act.get("history") or act.get("histories") or [],
+            })
+
+        # ── 4. 生成完整 Markdown ──
         md_lines = [
             f"# Bug #{bug_id}: {bug.get('title', '')}",
             "",
@@ -1422,6 +1509,7 @@ class ZenTaoNexus:
             "|------|------|",
             f"| ID | {bug_id} |",
             f"| 产品 | {_name('product')} |",
+            f"| 模块 | {_name('module')} |",
             f"| 状态 | {_name('status', self._STATUS_MAP)} |",
             f"| 严重程度 | {_name('severity', self._SEVERITY_MAP)} |",
             f"| 优先级 | P{bug.get('pri', '')} |",
@@ -1429,130 +1517,125 @@ class ZenTaoNexus:
             f"| 指派给 | {_name('assignedTo')} |",
             f"| 创建人 | {_name('openedBy')} |",
             f"| 创建时间 | {bug.get('openedDate', '')} |",
-            f"| 截止日期 | {bug.get('deadline', '')} |",
             f"| 解决人 | {_name('resolvedBy') or '-'} |",
+            f"| 解决时间 | {bug.get('resolvedDate', '') or '-'} |",
             f"| 解决方案 | {_name('resolution', self._RESOLUTION_MAP) or '-'} |",
-            f"| 关键词 | {bug.get('keywords', '')} |",
+            f"| 关闭人 | {_name('closedBy') or '-'} |",
+            f"| 关闭时间 | {bug.get('closedDate', '') or '-'} |",
+            f"| 截止日期 | {bug.get('deadline', '') or '-'} |",
+            f"| 关键词 | {bug.get('keywords', '') or '-'} |",
+            f"| 关联需求 | {bug.get('story', '') or '-'} |",
+            f"| 关联任务 | {bug.get('task', '') or '-'} |",
             "",
             "## 复现步骤",
             "",
+            self._html_to_markdown(steps_html),
+            "",
         ]
 
-        steps_md = self._html_to_markdown(steps_html)
-        md_lines.append(steps_md)
-        md_lines.append("")
-
+        # ── 附件列表 ──
         if downloaded_files:
             md_lines.append("## 附件")
             md_lines.append("")
             for f in downloaded_files:
+                path_ref = f"./{f['saved']}" if f["saved"] else ""
                 if f["success"]:
                     is_img = any(f["saved"].lower().endswith(e)
-                                for e in ('.png','.jpg','.jpeg','.gif','.bmp','.webp'))
+                                for e in ('.png', '.jpg', '.jpeg', '.gif', '.bmp', '.webp'))
                     if is_img:
-                        md_lines.append(f"![{f['name']}](./{f['saved']})")
+                        md_lines.append(f"![{f['name']}]({path_ref})")
                     else:
-                        md_lines.append(f"- [{f['name']}](./{f['saved']})")
+                        size_kb = round(f["size"] / 1024, 1) if f["size"] else 0
+                        md_lines.append(f"- [{f['name']}]({path_ref}) ({size_kb} KB)")
                 else:
-                    md_lines.append(f"- {f['name']}（下载失败）")
+                    md_lines.append(f"- {f['name']}（下载失败: {f.get('reason', 'unknown')}）")
             md_lines.append("")
 
-        # 备注/操作历史
-        _ACTION_MAP = {
-            "opened": "创建", "edited": "编辑", "commented": "备注",
-            "resolved": "解决", "closed": "关闭", "activated": "激活",
-            "confirmed": "确认", "assigned": "指派", "bugconfirmed": "确认",
-        }
-        action_list = list(actions.values()) if isinstance(actions, dict) else actions
-        has_comments = any(
-            a.get("comment", "").strip() for a in action_list if isinstance(a, dict)
-        )
-        if action_list:
-            md_lines.append("## 操作历史")
+        # ── 操作历史 & 备注 ──
+        if comments_data:
+            md_lines.append("## 操作历史 & 备注")
             md_lines.append("")
-            comment_img_idx = 0
-            for act in action_list:
-                if not isinstance(act, dict):
-                    continue
-                action_type = act.get("action", "")
-                action_label = _ACTION_MAP.get(action_type, action_type)
-                actor_id = act.get("actor", "")
-                actor_name = users.get(actor_id, actor_id) if users else actor_id
-                date = act.get("date", "")
-                comment_html = (act.get("comment") or "").strip()
-
-                md_lines.append(f"### {date} — {actor_name} [{action_label}]")
+            for c in comments_data:
+                md_lines.append(f"### {c['date']} — {c['actor']} [{c['action_label']}]")
                 md_lines.append("")
-
-                if comment_html:
-                    comment_html = comment_html.replace("&amp;", "&").replace("&nbsp;", " ")
-                    for img_match in img_pattern.finditer(comment_html):
-                        img_url = img_match.group(1)
-                        if not img_url.startswith('http'):
-                            img_url = f"{self.client.base_url}{img_url}"
-                        ext = ".png"
-                        ext_m = re.search(r't=(png|jpg|jpeg|gif|bmp|webp)', img_url, re.IGNORECASE)
-                        if ext_m:
-                            ext = f".{ext_m.group(1).lower()}"
-                        comment_img_idx += 1
-                        c_img_name = f"comment_img_{comment_img_idx}{ext}"
-                        c_save = os.path.join(base_dir, c_img_name)
-                        r = self.client.file_download(img_url, c_save)
-                        if r.get("status") == 1:
-                            comment_html = comment_html.replace(
-                                img_match.group(0),
-                                f'<img src="./{c_img_name}" alt="" />')
-                            downloaded_images.append(c_img_name)
-
-                    comment_md = self._html_to_markdown(comment_html)
-                    md_lines.append(comment_md)
+                if c["comment"]:
+                    md_lines.append(c["comment"])
                     md_lines.append("")
-
-                history = act.get("history", [])
-                if history:
+                history = c["history"]
+                if isinstance(history, list):
                     for h in history:
+                        if not isinstance(h, dict):
+                            continue
                         field = h.get("field", "")
-                        old_val = h.get("old", "")
-                        new_val = h.get("new", "")
+                        old_val = str(h.get("old", ""))
+                        new_val = str(h.get("new", ""))
                         if old_val or new_val:
-                            old_short = (old_val[:80] + '...') if len(old_val) > 80 else old_val
-                            new_short = (new_val[:80] + '...') if len(new_val) > 80 else new_val
-                            md_lines.append(f"- **{field}**: `{old_short}` → `{new_short}`")
-                    md_lines.append("")
+                            old_s = (old_val[:100] + '…') if len(old_val) > 100 else old_val
+                            new_s = (new_val[:100] + '…') if len(new_val) > 100 else new_val
+                            md_lines.append(f"- **{field}**: `{old_s}` → `{new_s}`")
+                    if history:
+                        md_lines.append("")
 
         md_content = "\n".join(md_lines)
-        md_path = os.path.join(base_dir, f"{bug_id}_bug.md")
+        md_path = os.path.join(base_dir, f"bug_{bug_id}.md")
         with open(md_path, 'w', encoding='utf-8') as fw:
             fw.write(md_content)
 
+        abs_folder = os.path.abspath(base_dir)
+        abs_md = os.path.abspath(md_path)
+
         return {
             "status": 1,
             "message": "success",
-            "bug": bug,
+            "data": {
+                "bug": bug,
+                "comments": comments_data,
+                "users": users,
+            },
             "export": {
-                "folder": os.path.abspath(base_dir),
-                "markdown": os.path.abspath(md_path),
+                "folder": abs_folder,
+                "markdown": abs_md,
                 "attachments": downloaded_files,
-                "step_images": downloaded_images,
-            }
+                "images": downloaded_images,
+                "summary": {
+                    "total_attachments": len(downloaded_files),
+                    "downloaded_attachments": sum(1 for f in downloaded_files if f["success"]),
+                    "total_images": len(downloaded_images),
+                    "downloaded_images": sum(1 for i in downloaded_images if i["success"]),
+                    "total_comments": sum(1 for c in comments_data if c["comment"]),
+                },
+            },
         }
 
     @staticmethod
     def _html_to_markdown(html: str) -> str:
-        """简易 HTML→Markdown：处理 p、strong、img、br 标签"""
+        """HTML → Markdown 转换"""
         if not html:
             return ""
         text = html
-        text = re.sub(r'<img\s+[^>]*src="([^"]+)"[^>]*alt="([^"]*)"[^>]*/?>',
+        text = re.sub(r'<img\s+[^>]*src=["\']([^"\']+)["\'][^>]*alt=["\']([^"\']*)["\'][^>]*/?>',
                        r'![\2](\1)', text)
-        text = re.sub(r'<img\s+[^>]*src="([^"]+)"[^>]*/?>',
+        text = re.sub(r'<img\s+[^>]*src=["\']([^"\']+)["\'][^>]*/?>',
                        r'![](\1)', text)
+        for i in range(6, 0, -1):
+            text = re.sub(rf'<h{i}[^>]*>(.*?)</h{i}>', r'\n' + '#' * i + r' \1\n', text, flags=re.DOTALL)
+        text = re.sub(r'<a\s+[^>]*href=["\']([^"\']+)["\'][^>]*>(.*?)</a>', r'[\2](\1)', text, flags=re.DOTALL)
         text = re.sub(r'<strong>(.*?)</strong>', r'**\1**', text)
         text = re.sub(r'<b>(.*?)</b>', r'**\1**', text)
         text = re.sub(r'<em>(.*?)</em>', r'*\1*', text)
+        text = re.sub(r'<code>(.*?)</code>', r'`\1`', text)
+        text = re.sub(r'<pre[^>]*>(.*?)</pre>', r'\n```\n\1\n```\n', text, flags=re.DOTALL)
+        text = re.sub(r'<li[^>]*>(.*?)</li>', r'- \1\n', text, flags=re.DOTALL)
+        text = re.sub(r'</?[ou]l[^>]*>', '\n', text)
         text = re.sub(r'<br\s*/?>', '\n', text)
-        text = re.sub(r'<p>(.*?)</p>', r'\1\n', text, flags=re.DOTALL)
+        text = re.sub(r'<p[^>]*>(.*?)</p>', r'\1\n', text, flags=re.DOTALL)
+        text = re.sub(r'<hr\s*/?>', '\n---\n', text)
+        text = re.sub(r'</?(?:div|span|table|thead|tbody|tr|td|th|blockquote)[^>]*>', '\n', text)
         text = re.sub(r'<[^>]+>', '', text)
+        text = re.sub(r'&lt;', '<', text)
+        text = re.sub(r'&gt;', '>', text)
+        text = re.sub(r'&quot;', '"', text)
+        text = re.sub(r'&nbsp;', ' ', text)
         text = re.sub(r'\n{3,}', '\n\n', text)
         return text.strip()