From cf6dc208efdd188ab37d42cf95ed6ca2b3d60ebb Mon Sep 17 00:00:00 2001
From: "man.zhong" <man.zhong@afe-solutions.com>
Date: Mon, 16 Mar 2026 16:05:34 +0800
Subject: [PATCH] chore(g3fo-db-ops): sync SKILL.md and db_ops implementation
 from project

Made-with: Cursor
---
 skills/g3fo-db-ops/SKILL.md          | 17 +++++++++++++----
 skills/g3fo-db-ops/scripts/db_ops.py | 17 ++++++++++++++++-
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/skills/g3fo-db-ops/SKILL.md b/skills/g3fo-db-ops/SKILL.md
index cc69f24..f808d83 100644
--- a/skills/g3fo-db-ops/SKILL.md
+++ b/skills/g3fo-db-ops/SKILL.md
@@ -13,11 +13,20 @@ Guide for performing database operations in the G3FO project, including automate
 
 **本技能不再使用 MCP MySQL**，改用 Python 程序 `scripts/db_ops.py` 执行所有数据库操作。
 
-### 安装依赖
+### 安装依赖与运行前提
 
-```bash
-pip install -r .claude/skills/g3fo-db-ops/scripts/requirements.txt
-```
+> **重要：本技能依赖本机可用的 Python 解释器。若未安装 Python 或 `python` 不在 PATH 中，在 Cursor 的 Shell 里直接执行脚本会出现 Windows `Exit code: 9009`（命令未找到）错误。**
+
+1. 在本机安装 Python（3.8+），并确认命令行中可以直接运行：
+   ```bash
+   python --version
+   ```
+   如命令无效，请将 Python 安装目录加入系统 PATH，或使用 `py` / `python3` 等本机实际命令名。
+
+2. 安装依赖：
+   ```bash
+   pip install -r .claude/skills/g3fo-db-ops/scripts/requirements.txt
+   ```
 
 ### 默认连接配置
 
diff --git a/skills/g3fo-db-ops/scripts/db_ops.py b/skills/g3fo-db-ops/scripts/db_ops.py
index 31fffe9..ea43ae3 100644
--- a/skills/g3fo-db-ops/scripts/db_ops.py
+++ b/skills/g3fo-db-ops/scripts/db_ops.py
@@ -19,6 +19,8 @@ import json
 import os
 import sys
 from typing import Any, Optional
+from datetime import date, datetime, time
+from decimal import Decimal
 
 try:
     import mysql.connector
@@ -88,6 +90,16 @@ def get_connection(config: dict):
     )
 
 
+def _normalize_value(value: Any) -> Any:
+    """将 MySQL 返回的值转换为可 JSON 序列化的类型。"""
+    if isinstance(value, (datetime, date, time)):
+        return value.isoformat()
+    if isinstance(value, Decimal):
+        # 大多数场景下用 float 即可，避免 JSON 不支持 Decimal
+        return float(value)
+    return value
+
+
 def cmd_query(args: argparse.Namespace, config: dict) -> dict:
     """执行 SELECT 查询。"""
     conn = get_connection(config)
@@ -96,7 +108,10 @@ def cmd_query(args: argparse.Namespace, config: dict) -> dict:
         cursor.execute(args.sql, args.params or [])
         rows = cursor.fetchall()
         cursor.close()
-        return {"success": True, "data": rows, "rowCount": len(rows)}
+        normalized_rows = [
+            {k: _normalize_value(v) for k, v in row.items()} for row in rows
+        ]
+        return {"success": True, "data": normalized_rows, "rowCount": len(normalized_rows)}
     except MySQLError as e:
         return {"success": False, "error": str(e)}
     finally: