@bangdao-ai/zentao-mcp 2.0.4 → 2.0.6

package/main.py

@@ -14,15 +14,24 @@ from dingtalk_stream import DingTalkStreamClient, Credential, ChatbotMessage
 
 from zenbot.config import JsonFormatter
 from zenbot.dingtalk_handler import ZentaoBotHandler
+from zenbot.logging_utils import struct_log
 
 load_dotenv()
 
-_stderr_handler = logging.StreamHandler(sys.stderr)
-_stderr_handler.setFormatter(JsonFormatter())
+def _setup_structured_logging() -> None:
+    fmt = JsonFormatter()
+    h = logging.StreamHandler(sys.stderr)
+    h.setFormatter(fmt)
+    for name in ("zentaoagent", "zentao_audit", "zentao_security"):
+        lg = logging.getLogger(name)
+        lg.handlers.clear()
+        lg.propagate = False
+        lg.addHandler(h)
+        lg.setLevel(logging.INFO)
 
+
+_setup_structured_logging()
 logger = logging.getLogger("zentaoagent")
-logger.addHandler(_stderr_handler)
-logger.setLevel(logging.INFO)
 
 
 def main():
@@ -36,7 +45,7 @@ def main():
     bot_handler = ZentaoBotHandler()
     client = DingTalkStreamClient(credential, logger)
     client.register_callback_handler(ChatbotMessage.TOPIC, bot_handler)
-    logger.info("ZenBot v2 启动中...")
+    struct_log(logger, logging.INFO, "zenbot_startup", component="main", version="v2")
     client.start_forever()
 
 

package/package.json

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

package/src/core/zentao_nexus.py

@@ -15,6 +15,12 @@ import csv
 import shutil
 import requests
 
+try:
+    from zenbot.logging_utils import struct_log as _struct_log
+except ImportError:
+    def _struct_log(logger, level, event, msg=None, component=None, **ctx):
+        logger.log(level, f"{event} {ctx}")
+
 logger = logging.getLogger("zentaoagent")
 _security_logger = logging.getLogger("zentao_security")
 
@@ -128,7 +134,12 @@ class ZenTaoNativeClient:
             safe_form = {k: (v if k not in ('password',) else '***') for k, v in form_data.items()}
         else:
             safe_form = None
-        logger.info("禅道请求 m=%s&f=%s params=%s form=%s", module, action, safe_params, safe_form)
+        _struct_log(
+            logger, logging.INFO, "zentao_api_request",
+            component="zentao_api",
+            m=module, f=action, url_params=safe_params,
+            form_preview=safe_form,
+        )
 
         if not self.silent:
             self._log_request(url_params, form_data, files)
@@ -149,11 +160,22 @@ class ZenTaoNativeClient:
             resp_summary = json.dumps(result, ensure_ascii=False)
             if len(resp_summary) > 1000:
                 resp_summary = resp_summary[:1000] + f"...(truncated, total {len(resp_summary)} chars)"
-            logger.info("禅道响应 m=%s&f=%s http=%d body=%s", module, action, resp.status_code, resp_summary)
+            st = result.get("status")
+            info = result.get("info") or result.get("message") or ""
+            _struct_log(
+                logger, logging.INFO, "zentao_api_response",
+                component="zentao_api",
+                m=module, f=action, http_status=resp.status_code,
+                api_status=st, info_preview=str(info)[:400],
+                body_truncated=len(resp_summary) > 1000,
+            )
             return result
 
         except requests.exceptions.RequestException as e:
-            logger.error("禅道请求异常 m=%s&f=%s error=%s", module, action, e)
+            _struct_log(
+                logger, logging.ERROR, "zentao_api_transport_error",
+                component="zentao_api", m=module, f=action, error=str(e),
+            )
             return {"status": 0, "message": "fail", "info": f"请求失败: {e}", "data": {}}
 
     def _prepare_form_data(self, form_data: Optional[Dict]) -> Optional[list]:
@@ -792,7 +814,7 @@ class ZenTaoNativeClient:
         优先使用 allneedlist/uploadbyapi（token 认证兼容），
         回退到 file/upload（需要 web session 权限，部分环境 401）。
         """
-        file_path = _safe_path(file_path, must_exist=True)
+        file_path = _safe_path(file_path)
         if not os.path.exists(file_path):
             return {"status": 0, "message": "fail",
                     "info": f"文件不存在: {file_path}", "data": {}}
@@ -1461,7 +1483,7 @@ class ZenTaoNexus:
         return fieldnames, rows, case_type
 
     def create_case_from_csv(self, csv_file_path, case_type=None) -> list:
-        csv_file_path = _safe_path(csv_file_path, must_exist=True)
+        csv_file_path = _safe_path(csv_file_path)
         if not os.path.exists(csv_file_path):
             return [{"status": 0, "message": f"CSV文件不存在: {csv_file_path}"}]
 
@@ -1534,12 +1556,13 @@ class ZenTaoNexus:
         if not batch_cases:
             return [{"status": 0, "message": "CSV 中无有效用例行"}]
 
-        result = self.client.testcase_import_batch(self.product_id, batch_cases)
+        pid = self.resolve_product_id()
+        result = self.client.testcase_import_batch(pid, batch_cases)
         ok = result.get('status') == 1
 
         if ok:
             latest = self.client.testcase_browse(
-                self.product_id, orderBy='id_desc',
+                pid, orderBy='id_desc',
                 recPerPage=str(len(batch_cases) + 5))
             latest_cases = latest.get("data", {}).get("cases", [])
             if isinstance(latest_cases, dict):
@@ -1581,7 +1604,7 @@ class ZenTaoNexus:
         return results
 
     def submit_csv_cases_to_zentao(self, csv_file_path, case_type=None) -> Dict:
-        csv_file_path = _safe_path(csv_file_path, must_exist=True)
+        csv_file_path = _safe_path(csv_file_path)
         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}

package/src/zenbot/bot_service.py

@@ -4,10 +4,11 @@ import json
 import logging
 
 from .config import build_user_context
+from .logging_utils import struct_log
 
 logger = logging.getLogger("zentaoagent")
 audit_logger = logging.getLogger("zentao_audit")
-from .intent_parser import parse_intent, IntentResult
+from .intent_parser import parse_intent, fix_params_on_api_error, IntentResult
 from .session_manager import (
     get_session, create_session, update_session, clear_session, is_cancel_keyword,
     get_last_bug_ids, set_last_action, get_last_action,
@@ -57,7 +58,10 @@ def dispatch(
 ) -> str:
     user_context = build_user_context(staff_id, staff_nick, session_webhook, conversation_id, conversation_type)
     if not user_context:
-        logger.warning("用户未绑定 staff_id=%s nick=%s", staff_id, staff_nick)
+        struct_log(
+            logger, logging.WARNING, "user_unbound",
+            component="bot_service", staff_id=staff_id, staff_nick=staff_nick,
+        )
         return format_unbound_user()
 
     if is_cancel_keyword(content):
@@ -71,7 +75,10 @@ def dispatch(
     pending = _pending_confirms.get(session_key)
     if pending and content.strip().lower() in _CONFIRM_KEYWORDS:
         _pending_confirms.pop(session_key, None)
-        logger.info("二次确认通过 intent=%s session=%s", pending.intent, session_key)
+        struct_log(
+            logger, logging.INFO, "confirm_passed",
+            component="bot_service", intent=pending.intent, session_key=session_key,
+        )
         reply = _execute_handler(pending, user_context)
         set_last_action(session_key, pending.intent, pending.params, reply)
         return reply
@@ -146,12 +153,20 @@ def dispatch(
         _pending_confirms[session_key] = intent_result
         bug_ids = intent_result.params.get("bug_ids") or [intent_result.params.get("bug_id", "")]
         ids_str = ", ".join(f"#{b}" for b in bug_ids if b)
-        logger.info("关闭Bug二次确认 session=%s bug_ids=%s", session_key, ids_str)
+        struct_log(
+            logger, logging.INFO, "bug_close_confirm_prompt",
+            component="bot_service", session_key=session_key, bug_ids_preview=ids_str,
+        )
         return f"你确定要关闭 Bug {ids_str} 吗？回复「确认关闭」继续，或「取消」放弃～"
 
-    logger.info("意图解析 intent=%s confidence=%.2f params=%s missing=%s",
-                intent_result.intent, intent_result.confidence,
-                intent_result.params, intent_result.missing_params)
+    struct_log(
+        logger, logging.INFO, "dispatch_execute",
+        component="bot_service",
+        intent=intent_result.intent,
+        confidence=round(intent_result.confidence, 4),
+        params=intent_result.params,
+        missing_params=intent_result.missing_params,
+    )
     reply = _execute_handler(intent_result, user_context)
     set_last_action(session_key, intent_result.intent, intent_result.params, reply)
     return reply
@@ -166,31 +181,132 @@ _WRITE_INTENTS = frozenset({
 })
 
 
+_MAX_FIELD_RETRIES = 5
+_ERROR_PREFIX = "哎呀，没成功 😥\n\n禅道返回: "
+_ERROR_SUFFIX = "\n\n要不检查一下状态再试试？"
+
+
+def _extract_error_info(reply: str) -> str | None:
+    """从 format_error 的固定格式中提取原始错误信息，非该格式返回 None。"""
+    if not reply.startswith(_ERROR_PREFIX):
+        return None
+    tail = reply[len(_ERROR_PREFIX):]
+    idx = tail.find(_ERROR_SUFFIX)
+    if idx == -1:
+        return None
+    return tail[:idx].strip() or None
+
+
+def _safe_call_handler(handler, user_context, intent_result: IntentResult) -> tuple[str, bool]:
+    """调用 handler，返回 (reply, is_exception)。异常被捕获后 is_exception=True。"""
+    try:
+        result = handler(user_context, intent_result)
+        return result, False
+    except ZentaoPermissionError as e:
+        struct_log(
+            logger, logging.WARNING, "handler_permission_denied",
+            component="bot_service", intent=intent_result.intent,
+            zentao_code=user_context.zentao_code, error=str(e),
+        )
+        return str(e), True
+    except Exception as e:
+        logger.exception("handler 执行异常 intent=%s", intent_result.intent)
+        return format_error(str(e)), True
+
+
 def _execute_handler(intent_result: IntentResult, user_context) -> str:
     if intent_result.intent not in _ALLOWED_INTENTS:
-        logger.warning("LLM返回非法意图 intent=%s user=%s", intent_result.intent, user_context.zentao_code)
+        struct_log(
+            logger, logging.WARNING, "invalid_intent",
+            component="bot_service", intent=intent_result.intent,
+            zentao_code=user_context.zentao_code,
+        )
         return format_unknown()
 
     handler = HANDLERS.get(intent_result.intent)
     if not handler:
-        logger.warning("未知意图 intent=%s", intent_result.intent)
+        struct_log(logger, logging.WARNING, "unknown_intent_handler",
+                   component="bot_service", intent=intent_result.intent)
         return format_unknown()
 
     if intent_result.intent in _WRITE_INTENTS:
-        audit_logger.info("WRITE op=%s user=%s params=%s",
-                          intent_result.intent, user_context.zentao_code,
-                          json.dumps(intent_result.params, ensure_ascii=False))
+        struct_log(
+            audit_logger, logging.INFO, "audit_write",
+            component="audit",
+            op=intent_result.intent,
+            user=user_context.zentao_code,
+            params=intent_result.params,
+        )
 
-    try:
-        result = handler(user_context, intent_result)
-        logger.info("handler 执行完成 intent=%s", intent_result.intent)
-        return result
-    except ZentaoPermissionError as e:
-        logger.warning("权限不足 intent=%s user=%s: %s", intent_result.intent, user_context.zentao_code, e)
-        return str(e)
-    except Exception as e:
-        logger.exception("handler 执行异常 intent=%s", intent_result.intent)
-        return format_error(str(e))
+    reply, raised = _safe_call_handler(handler, user_context, intent_result)
+
+    if not raised and intent_result.intent in _WRITE_INTENTS:
+        for attempt in range(1, _MAX_FIELD_RETRIES + 1):
+            error_info = _extract_error_info(reply)
+            if not error_info:
+                break
+
+            struct_log(
+                logger, logging.INFO, "field_retry_start",
+                component="bot_service",
+                intent=intent_result.intent, attempt=attempt,
+                error_info=error_info,
+                current_params=intent_result.params,
+            )
+
+            fixed_params = fix_params_on_api_error(
+                intent_result.intent, intent_result.params,
+                error_info, user_context, attempt,
+            )
+            if not fixed_params or fixed_params == intent_result.params:
+                struct_log(
+                    logger, logging.INFO, "field_retry_abort",
+                    component="bot_service",
+                    intent=intent_result.intent, attempt=attempt,
+                    reason="no_fix" if not fixed_params else "params_unchanged",
+                )
+                break
+
+            intent_result.params = fixed_params
+
+            struct_log(
+                audit_logger, logging.INFO, "audit_field_retry",
+                component="audit",
+                op=intent_result.intent,
+                user=user_context.zentao_code,
+                attempt=attempt,
+                fixed_params=fixed_params,
+            )
+
+            reply, raised = _safe_call_handler(handler, user_context, intent_result)
+            if raised:
+                struct_log(
+                    logger, logging.WARNING, "field_retry_exception",
+                    component="bot_service",
+                    intent=intent_result.intent, attempt=attempt,
+                )
+                break
+
+        else:
+            struct_log(
+                logger, logging.WARNING, "field_retry_exhausted",
+                component="bot_service",
+                intent=intent_result.intent, max_retries=_MAX_FIELD_RETRIES,
+            )
+
+    if not raised:
+        if _extract_error_info(reply) is None:
+            struct_log(
+                logger, logging.INFO, "handler_ok",
+                component="bot_service", intent=intent_result.intent,
+            )
+        else:
+            struct_log(
+                logger, logging.WARNING, "handler_failed_after_retries",
+                component="bot_service", intent=intent_result.intent,
+            )
+
+    return reply
 
 
 def _inject_image_paths(intent_result: IntentResult, image_paths: list[str] | None) -> None:
@@ -200,7 +316,10 @@ def _inject_image_paths(intent_result: IntentResult, image_paths: list[str] | No
     if intent_result.intent == "bug_upload" and not intent_result.params.get("file_path"):
         intent_result.params["file_path"] = image_paths[0]
         intent_result.missing_params = [p for p in intent_result.missing_params if p != "file_path"]
-        logger.info("自动注入图片路径 file_path=%s", image_paths[0])
+        struct_log(
+            logger, logging.INFO, "inject_image_path",
+            component="bot_service", file_path=image_paths[0],
+        )
 
 
 def _fix_bug_resolve_missing(intent_result: IntentResult) -> None:
@@ -285,7 +404,11 @@ def _handle_general_chat(content: str, image_paths: list[str] | None, user_conte
             soul_content=soul,
         )
         if reply:
-            logger.info("通用问答回复 user=%s reply=%s", user_context.zentao_code, reply[:100])
+            struct_log(
+                logger, logging.INFO, "general_chat_reply",
+                component="bot_service", user=user_context.zentao_code,
+                reply_preview=reply[:200],
+            )
             return reply
     except Exception:
         logger.exception("通用问答异常")

package/src/zenbot/config.py

@@ -3,6 +3,7 @@
 import json
 import logging
 import os
+from datetime import datetime, timezone
 from dataclasses import dataclass
 from pathlib import Path
 
@@ -118,6 +119,15 @@ def resolve_product_id(product_name: str | None, user_code: str | None = None) -
 
 
 class JsonFormatter(logging.Formatter):
+    """单行 JSON：含 ts(UTC ISO8601)、level、logger、msg，可选 event、ctx。"""
+
+    def formatTime(self, record, datefmt=None):
+        return (
+            datetime.fromtimestamp(record.created, tz=timezone.utc)
+            .strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+            + "Z"
+        )
+
     def format(self, record):
         try:
             msg = record.getMessage()
@@ -128,9 +138,14 @@ class JsonFormatter(logging.Formatter):
         log = {
             "ts": self.formatTime(record),
             "level": record.levelname,
-            "module": getattr(record, "module", record.name),
+            "logger": record.name,
+            "module": getattr(record, "module", ""),
             "msg": msg,
         }
+        if hasattr(record, "struct_event") and record.struct_event:
+            log["event"] = record.struct_event
+        if hasattr(record, "struct_ctx") and record.struct_ctx:
+            log["ctx"] = record.struct_ctx
         if record.exc_info and not record.exc_text:
             record.exc_text = self.formatException(record.exc_info)
         if record.exc_text:

package/src/zenbot/dingtalk_handler.py

@@ -8,6 +8,7 @@ from dingtalk_stream.chatbot import ChatbotHandler
 from . import dingtalk_reply
 from .bot_service import dispatch
 from .dingtalk_api import resolve_job_number, download_robot_file
+from .logging_utils import struct_log
 
 logger = logging.getLogger("zentaoagent")
 
@@ -91,7 +92,11 @@ def _download_images(robot_code: str, download_codes: list[str]) -> list[str]:
         if local_path:
             paths.append(local_path)
         else:
-            logger.warning("图片下载失败 download_code=%s...%s", code[:8], code[-4:])
+            struct_log(
+                logger, logging.WARNING, "dingtalk_image_download_fail",
+                component="dingtalk_handler",
+                download_code_prefix=code[:12] if len(code) > 12 else code,
+            )
     return paths
 
 
@@ -116,35 +121,57 @@ class ZentaoBotHandler(ChatbotHandler):
                 _userid_to_jobnumber[userid] = job_number
                 staff_id = job_number
             else:
-                logger.warning("无法解析工号 userid=%s nick=%s", userid, staff_nick)
+                struct_log(
+                    logger, logging.WARNING, "dingtalk_jobnumber_unresolved",
+                    component="dingtalk_handler", userid=userid, staff_nick=staff_nick,
+                )
                 staff_id = userid
 
         robot_code = incoming_message.robot_code or ""
         download_codes = _extract_download_codes(incoming_message)
         image_paths: list[str] = []
         if download_codes:
-            logger.info("检测到图片消息 count=%d robot_code=%s", len(download_codes), robot_code)
+            struct_log(
+                logger, logging.INFO, "dingtalk_inbound_images",
+                component="dingtalk_handler",
+                image_count=len(download_codes), robot_code=robot_code,
+            )
             image_paths = _download_images(robot_code, download_codes)
 
         referenced = _extract_referenced_content(message.data, incoming_message)
         if referenced:
             content = f"【用户引用的消息】\n{referenced}\n\n【用户输入】\n{content}"
-            logger.info("检测到引用/转发消息 ref_len=%d 已合并到 content", len(referenced))
+            struct_log(
+                logger, logging.INFO, "dingtalk_inbound_reference",
+                component="dingtalk_handler", referenced_len=len(referenced),
+            )
 
         if not content.strip() and not image_paths:
-            logger.warning("消息内容为空 msgtype=%s raw_data_keys=%s",
-                           incoming_message.message_type, list(message.data.keys()))
+            struct_log(
+                logger, logging.WARNING, "dingtalk_empty_message",
+                component="dingtalk_handler",
+                msgtype=incoming_message.message_type,
+                raw_data_keys=list(message.data.keys()),
+            )
             reply_text = "没收到内容，试试直接打字发送？"
-            logger.info("回复消息 staff_id=%s reply=%s", staff_id, reply_text[:100])
+            struct_log(
+                logger, logging.INFO, "dingtalk_outbound",
+                component="dingtalk_handler", staff_id=staff_id, reply_preview=reply_text[:200],
+            )
             dingtalk_reply.reply_markdown(session_webhook, "小禅", reply_text)
             return AckMessage.STATUS_OK, "ok"
 
         if not content.strip() and image_paths:
             content = "请帮我看看这张图片"
 
-        logger.info("收到消息 userid=%s staff_id=%s nick=%s msgtype=%s images=%d content=%s",
-                     userid, staff_id, staff_nick,
-                     incoming_message.message_type, len(image_paths), content.strip()[:100])
+        struct_log(
+            logger, logging.INFO, "dingtalk_inbound_text",
+            component="dingtalk_handler",
+            userid=userid, staff_id=staff_id, staff_nick=staff_nick,
+            msgtype=incoming_message.message_type,
+            image_count=len(image_paths),
+            content_preview=content.strip()[:300],
+        )
 
         try:
             reply_text = dispatch(
@@ -157,9 +184,17 @@ class ZentaoBotHandler(ChatbotHandler):
                 image_paths=image_paths,
             )
         except Exception:
-            logger.exception("dispatch 异常")
+            struct_log(
+                logger, logging.ERROR, "dispatch_exception",
+                component="dingtalk_handler", staff_id=staff_id,
+            )
+            logger.exception("dispatch_exception detail")
             reply_text = "处理消息时出错，请稍后再试"
 
-        logger.info("回复消息 staff_id=%s reply=%s", staff_id, reply_text[:100])
+        struct_log(
+            logger, logging.INFO, "dingtalk_outbound",
+            component="dingtalk_handler", staff_id=staff_id,
+            reply_preview=reply_text[:300],
+        )
         dingtalk_reply.reply_markdown(session_webhook, "小禅", reply_text)
         return AckMessage.STATUS_OK, "ok"

package/src/zenbot/intent_parser.py

@@ -8,6 +8,7 @@ from pathlib import Path
 
 from .config import UserContext
 from . import llm_client
+from .logging_utils import struct_log
 
 logger = logging.getLogger("zentaoagent")
 
@@ -273,7 +274,10 @@ def parse_intent(
     try:
         content = llm_client.chat_completion(messages)
         if not content:
-            logger.warning("LLM返回空内容 user_input=%s", user_input)
+            struct_log(
+                logger, logging.WARNING, "intent_llm_empty",
+                component="intent_parser", user_input_preview=user_input[:300],
+            )
             return IntentResult("unknown", 0.0, {}, [], "理解失败，请用更明确的指令")
         data = json.loads(content)
         intent = data.get("intent", "unknown")
@@ -281,12 +285,124 @@ def parse_intent(
         params = data.get("params") or {}
         missing_params = data.get("missing_params") or []
         clarify_question = data.get("clarify_question") or ""
-        logger.info("意图解析结果 user_input=%s intent=%s confidence=%.2f params=%s missing=%s",
-                     user_input, intent, confidence, params, missing_params)
+        struct_log(
+            logger, logging.INFO, "intent_parse_result",
+            component="intent_parser",
+            user_input_preview=user_input[:400],
+            intent=intent, confidence=confidence,
+            params=params, missing_params=missing_params,
+        )
         return IntentResult(intent, confidence, params, missing_params, clarify_question)
     except (json.JSONDecodeError, TypeError) as e:
-        logger.error("LLM返回JSON解析失败 user_input=%s error=%s", user_input, e)
+        struct_log(
+            logger, logging.ERROR, "intent_json_error",
+            component="intent_parser", user_input_preview=user_input[:300], error=str(e),
+        )
         return IntentResult("unknown", 0.0, {}, [], "理解失败，请用更明确的指令")
     except Exception as e:
-        logger.error("意图解析异常 user_input=%s error=%s", user_input, e, exc_info=True)
+        struct_log(
+            logger, logging.ERROR, "intent_parse_exception",
+            component="intent_parser", user_input_preview=user_input[:300], error=str(e),
+        )
+        logger.exception("intent_parse_exception detail")
         return IntentResult("unknown", 0.0, {}, [], "理解失败，请用更明确的指令")
+
+
+# ─────────── API 字段自修复 ───────────
+
+_FIX_PARAMS_SYSTEM = """\
+你是禅道 API 调试专家。handler 调用禅道 API 失败了，你需要根据错误信息判断能否通过修正参数来修复。
+
+## 禅道 API 常见字段格式规则
+- severity: 整数 1-4（1最高），字符串形式如 "1"
+- pri: 整数 1-4（1最高），字符串形式如 "1"
+- openedBuild: 字符串，如 "trunk"
+- resolution: fixed|bydesign|duplicate|notrepro|postponed|willnotfix|reqchange|external|tostory
+- assignedTo: 禅道工号（英文小写），不是中文姓名
+- product: 数字字符串，如 "365"
+- deadline / estStarted: 日期格式 "YYYY-MM-DD"
+- type: bug类型如 codeerror|config|install|security|performance|standard|automation|designdefect|others
+- status 相关字段不能在创建时指定
+- 布尔类字段用 "0" / "1"
+
+## 意图参数定义
+{intent_schema}
+
+## 当前情况
+- 意图: {intent}
+- 当前参数: {params}
+- API 错误信息: {error_info}
+- 已尝试修复次数: {attempt}
+
+## 输出 JSON（严格，不输出其他内容）
+{{"can_fix": true/false, "fixed_params": {{...}}, "fix_description": "一句话说明修了什么"}}
+
+规则：
+- can_fix=true 时，fixed_params 必须包含完整参数（在当前参数基础上做修改）
+- 以下情况 can_fix 必须为 false：权限不足、ID不存在、网络错误、认证失败、服务器内部错误
+- 不要凭空编造 ID（bug_id / product_id / story_id 等）
+- 如果多次尝试后错误不变，can_fix 设为 false
+"""
+
+
+def fix_params_on_api_error(
+    intent: str,
+    params: dict,
+    error_info: str,
+    user_context: UserContext,
+    attempt: int,
+) -> dict | None:
+    """用 LLM 分析 API 错误并尝试修正参数。返回修正后的 params 或 None（无法修复）。"""
+    prompt = _FIX_PARAMS_SYSTEM.format(
+        intent_schema=INTENT_SCHEMA,
+        intent=intent,
+        params=json.dumps(params, ensure_ascii=False),
+        error_info=error_info,
+        attempt=attempt,
+    )
+    messages = [
+        {"role": "system", "content": prompt},
+        {"role": "user", "content": f"请分析错误并给出修复方案（第 {attempt} 次尝试）"},
+    ]
+
+    try:
+        content = llm_client.chat_completion(messages)
+        if not content:
+            struct_log(
+                logger, logging.WARNING, "fix_params_llm_empty",
+                component="intent_parser", intent=intent, attempt=attempt,
+            )
+            return None
+
+        data = json.loads(content)
+        can_fix = data.get("can_fix", False)
+        fix_desc = data.get("fix_description", "")
+
+        struct_log(
+            logger, logging.INFO, "fix_params_result",
+            component="intent_parser",
+            intent=intent, attempt=attempt, can_fix=can_fix,
+            fix_description=fix_desc,
+        )
+
+        if not can_fix:
+            return None
+
+        fixed = data.get("fixed_params")
+        if not isinstance(fixed, dict) or not fixed:
+            return None
+
+        return fixed
+
+    except (json.JSONDecodeError, TypeError) as e:
+        struct_log(
+            logger, logging.ERROR, "fix_params_json_error",
+            component="intent_parser", intent=intent, attempt=attempt, error=str(e),
+        )
+        return None
+    except Exception as e:
+        struct_log(
+            logger, logging.ERROR, "fix_params_exception",
+            component="intent_parser", intent=intent, attempt=attempt, error=str(e),
+        )
+        return None

package/src/zenbot/llm_client.py

@@ -8,6 +8,8 @@ import time
 
 import requests
 
+from .logging_utils import struct_log
+
 logger = logging.getLogger("zentaoagent")
 
 OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://dashscope.aliyuncs.com/compatible-mode/v1")
@@ -42,8 +44,12 @@ def chat_completion(messages: list, max_retries: int = 2) -> str | None:
         "messages": messages,
     }
 
-    logger.info("LLM请求 model=%s messages_count=%d summary=%s",
-                LLM_MODEL, len(messages), _summarize_messages(messages))
+    struct_log(
+        logger, logging.INFO, "llm_request",
+        component="llm_client",
+        model=LLM_MODEL, messages_count=len(messages),
+        messages_summary=_summarize_messages(messages),
+    )
     logger.debug("LLM请求完整messages: %s",
                  json.dumps(messages, ensure_ascii=False, indent=2))
 
@@ -57,17 +63,28 @@ def chat_completion(messages: list, max_retries: int = 2) -> str | None:
             data = resp.json()
             content = data.get("choices", [{}])[0].get("message", {}).get("content")
             usage = data.get("usage", {})
-            logger.info("LLM响应 elapsed=%.2fs tokens_in=%s tokens_out=%s content=%s",
-                        elapsed,
-                        usage.get("prompt_tokens", "?"),
-                        usage.get("completion_tokens", "?"),
-                        content)
+            struct_log(
+                logger, logging.INFO, "llm_response",
+                component="llm_client",
+                model=LLM_MODEL,
+                elapsed_sec=round(elapsed, 3),
+                prompt_tokens=usage.get("prompt_tokens"),
+                completion_tokens=usage.get("completion_tokens"),
+                content_preview=(content or "")[:500],
+            )
             return content
         except (requests.exceptions.Timeout, requests.exceptions.RequestException) as e:
             last_err = e
-            logger.warning("LLM请求失败 attempt=%d/%d error=%s", attempt + 1, max_retries, e)
+            struct_log(
+                logger, logging.WARNING, "llm_retry",
+                component="llm_client",
+                attempt=attempt + 1, max_retries=max_retries, error=str(e),
+            )
             continue
-    logger.error("LLM请求全部失败 max_retries=%d last_error=%s", max_retries, last_err)
+    struct_log(
+        logger, logging.ERROR, "llm_all_failed",
+        component="llm_client", max_retries=max_retries, last_error=str(last_err),
+    )
     raise last_err
 
 
@@ -143,8 +160,12 @@ def general_chat(
         "messages": messages,
     }
 
-    logger.info("通用问答请求 model=%s has_images=%s message=%s",
-                model, has_images, (user_message or "")[:100])
+    struct_log(
+        logger, logging.INFO, "llm_general_chat_request",
+        component="llm_client",
+        model=model, has_images=has_images,
+        message_preview=(user_message or "")[:300],
+    )
 
     try:
         t0 = time.time()
@@ -154,9 +175,19 @@ def general_chat(
         data = resp.json()
         content = data.get("choices", [{}])[0].get("message", {}).get("content")
         usage = data.get("usage", {})
-        logger.info("通用问答响应 elapsed=%.2fs tokens_in=%s tokens_out=%s",
-                    elapsed, usage.get("prompt_tokens", "?"), usage.get("completion_tokens", "?"))
+        struct_log(
+            logger, logging.INFO, "llm_general_chat_response",
+            component="llm_client",
+            model=model,
+            elapsed_sec=round(elapsed, 3),
+            prompt_tokens=usage.get("prompt_tokens"),
+            completion_tokens=usage.get("completion_tokens"),
+        )
         return content
     except Exception as e:
-        logger.error("通用问答请求失败: %s", e, exc_info=True)
+        struct_log(
+            logger, logging.ERROR, "llm_general_chat_failed",
+            component="llm_client", model=model, error=str(e),
+        )
+        logger.exception("llm_general_chat_failed detail")
         return None

package/src/zenbot/logging_utils.py

@@ -0,0 +1,64 @@
+"""结构化日志：与 JsonFormatter 配合，输出可检索的 event + ctx 字段。"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+_MAX_STR = 2000
+_MAX_LIST = 50
+
+
+def _truncate(s: str, max_len: int = _MAX_STR) -> str:
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 3] + "..."
+
+
+def json_safe(value: Any, depth: int = 0) -> Any:
+    """将任意值转为 JSON 可序列化结构，控制深度与体积。"""
+    if depth > 6:
+        return "<max_depth>"
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, str):
+        return _truncate(value)
+    if isinstance(value, bytes):
+        return _truncate(value.decode("utf-8", errors="replace"))
+    if isinstance(value, dict):
+        out = {}
+        for i, (k, v) in enumerate(value.items()):
+            if i >= 80:
+                out["_truncated_keys"] = len(value) - 80
+                break
+            key = str(k) if not isinstance(k, str) else k
+            out[key] = json_safe(v, depth + 1)
+        return out
+    if isinstance(value, (list, tuple, set)):
+        seq = list(value)
+        if len(seq) > _MAX_LIST:
+            return [json_safe(x, depth + 1) for x in seq[:_MAX_LIST]] + [f"...+{len(seq) - _MAX_LIST} items"]
+        return [json_safe(x, depth + 1) for x in seq]
+    return _truncate(str(value))
+
+
+def struct_log(
+    logger: logging.Logger,
+    level: int,
+    event: str,
+    msg: str | None = None,
+    component: str | None = None,
+    **ctx: Any,
+) -> None:
+    """
+    记录一条结构化日志。JsonFormatter 会输出 event、component（若有）、ctx 等字段。
+    """
+    payload = json_safe(ctx) if ctx else {}
+    if component:
+        payload = {"component": component, **payload}
+    logger.log(
+        level,
+        msg or event,
+        extra={"struct_event": event, "struct_ctx": payload},
+    )