aukeys-opscli 0.0.22__tar.gz → 0.0.23__tar.gz

{aukeys_opscli-0.0.22 → aukeys_opscli-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aukeys-opscli
-Version: 0.0.22
+Version: 0.0.23
 Summary: Aukeys 运营 CLI 工具集
 Requires-Python: >=3.10
 Requires-Dist: cryptography>=38

aukeys_opscli-0.0.23/docs/change-log-pending.md

@@ -0,0 +1,76 @@
+# 待归档变更记录
+
+## 2026-04-27 opscli - 新增 chart_analyze_mcp.py
+
+**变更原因**：为 ops-dataset-query Skill 新增 MCP 无状态模式的图表异常检测脚本，原 `chart_analyze.py` 依赖 `opscli` CLI（subprocess），无法在纯 MCP 环境中使用。
+
+**改动点**：
+- 新增 `opscli/skills/templates/ops-dataset-query/scripts/chart_analyze_mcp.py`
+- 移除所有 `subprocess` 调用 `opscli` 的逻辑
+- 数据获取改为纯文件输入（`--input` / `--dc-input`），由 MCP Agent 预先通过 `query_chart` / `query_build_and_run` Tool 获取后传入
+- 移除自动 `upgrade` 兜底，改为返回错误并提示调用 MCP `skills_upgrade`
+- 文件头部添加详细 MCP 调用指南注释（含前置 session 检查、Tool 调用示例、dataComparison 用法）
+- 核心异常检测逻辑（5 类规则）与 `chart_analyze.py` 完全一致
+
+**验证结果**：`python -m py_compile` 语法检查通过
+
+**影响范围**：不影响现有 `chart_analyze.py`，为 MCP 环境提供独立入口
+
+**回滚方式**：删除 `chart_analyze_mcp.py` 即可
+
+---
+
+## 2026-04-27 opscli - 新增 chart_map_mcp.py / excel_export_mcp.py / query_mcp.py / updater_mcp.py
+
+**变更原因**：为 ops-dataset-query Skill 的 4 个核心脚本创建 MCP 无状态模式版本，原脚本均依赖 opscli CLI（subprocess 或直接导入内部模块），无法在纯 MCP 环境中使用。
+
+### chart_map_mcp.py
+- 新增 `opscli/skills/templates/ops-dataset-query/scripts/chart_map_mcp.py`
+- 移除 `subprocess` 调用 `opscli query chart`（原 `--uuid`/`--run` 参数）
+- 移除 `_try_upgrade()` 自动升级逻辑，映射失败时提示调用 MCP `skills_upgrade`
+- 数据入口改为纯 `--input` 文件（由 MCP `query_chart` 获取后保存）
+- 保留核心映射函数：`discover_data_dir`、`load_local_index`、`map_chart_queries`、`map_query_results`
+
+### excel_export_mcp.py
+- 新增 `opscli/skills/templates/ops-dataset-query/scripts/excel_export_mcp.py`
+- 不再从 `chart_analyze.py` 导入 CLI 函数（`_check_mapping_hit`、`_try_upgrade`、`load_chart_data`）
+- 自行实现文件版 `load_chart_data()` 和 `_check_mapping_hit()`
+- 移除 `--uuid` 和 `--no-auto-upgrade` 参数
+- 保留 Excel 导出核心逻辑：样式、行列类型判断、百分比列识别、列宽自适应
+
+### query_mcp.py
+- 新增 `opscli/skills/templates/ops-dataset-query/scripts/query_mcp.py`
+- 原 `query.py` 为纯 opscli 转发脚本（`subprocess` 调用 CLI），MCP 模式下无直接价值
+- 改造为**本地 Payload 构造器**：使用本地 CSV 索引实现字段别名解析（`global_alias > field_name > verbose_name`），构造标准 query payload JSON
+- 支持 `build` 子命令（dimensions/metrics/where/order_by/limit/offset/data_comparison）和 `metadata` 子命令
+- 输出 payload JSON 文件，供 MCP `query_run` Tool 使用
+- 实现字段歧义自动消歧（`_pick_primary_field`，优先选取原始字段）
+
+### updater_mcp.py
+- 新增 `opscli/skills/templates/ops-dataset-query/scripts/updater_mcp.py`
+- 移除对 `opscli.skills.models.SkillRecord` 和 `opscli.skills.updater.SkillsUpdater` 的依赖
+- 改为仅检查本地 `VERSION.json` 和数据文件（`datasets.csv`、`dataset_fields.csv`、`query_metadata.json`）完整性的轻量脚本
+- 更新操作提示通过 MCP `skills_upgrade` Tool 执行
+
+**验证结果**：`python -m py_compile` 语法检查全部通过（4/4）
+
+**影响范围**：不影响现有 CLI 版本脚本，为 MCP 环境提供独立入口
+
+**回滚方式**：删除 4 个 `*_mcp.py` 文件即可
+
+---
+
+## 2026-04-27 opscli - 更新 SKILL_MCP.md 文档
+
+**变更原因**：将新增的 5 个 MCP 版本脚本（`query_mcp.py`、`chart_map_mcp.py`、`chart_analyze_mcp.py`、`excel_export_mcp.py`、`updater_mcp.py`）的调用方式及用法补充到 SKILL_MCP.md 中，方便 MCP Agent 查阅。
+
+**改动点**：
+- 在 `opscli/skills/templates/ops-dataset-query/SKILL_MCP.md` 的"辅助脚本"章节中新增"MCP 环境辅助脚本"小节
+- 每个脚本包含：功能说明、用法示例、输入来源（对应哪个 MCP Tool）、输出格式
+- `query_mcp.py` 单独说明与 `query_run` Tool 的配合使用流程
+- `chart_analyze_mcp.py` 包含 5 类异常检测规则速查表
+- `excel_export_mcp.py` 包含格式规范说明
+
+**影响范围**：仅文档更新，不影响代码
+
+**回滚方式**：回退 SKILL_MCP.md 修改即可

{aukeys_opscli-0.0.22 → aukeys_opscli-0.0.23}/opscli/query/services/manager.py

@@ -447,13 +447,25 @@ class QueryManager:
         raise InvalidPayloadError(f"无效的 --dimension 定义: {raw}")
 
     def _parse_metric_spec(self, raw: str) -> _FieldSpec:
-        """解析指标定义：field_name:aggregation[:alias]。"""
+        """解析指标定义：field_name[:aggregation[:alias]]。
+
+        支持三种格式：
+        - field_name                    公式字段（has_formula_config=1），由 _resolve_metric_expr 自动使用 summary_expression
+        - field_name:aggregation        普通聚合字段
+        - field_name:aggregation:alias  普通聚合字段 + 自定义别名
+        - field_name::alias             公式字段 + 自定义别名（aggregation 留空）
+        """
         parts = [item.strip() for item in raw.split(":")]
+        # 仅有字段名：公式字段，aggregation=None 由 _resolve_metric_expr 处理
+        if len(parts) == 1 and parts[0]:
+            return _FieldSpec(field_name=parts[0], aggregation=None, alias=None)
         if len(parts) == 2 and parts[0] and parts[1]:
             return _FieldSpec(field_name=parts[0], aggregation=parts[1].upper(), alias=None)
-        if len(parts) == 3 and parts[0] and parts[1] and parts[2]:
-            return _FieldSpec(field_name=parts[0], aggregation=parts[1].upper(), alias=parts[2])
-        raise InvalidPayloadError(f"无效的 --metric 定义: {raw}")
+        if len(parts) == 3 and parts[0] and parts[2]:
+            # 第二段为空时表示公式字段 + 自定义别名（如 gross_profit_percent::gpp）
+            agg = parts[1].upper() if parts[1] else None
+            return _FieldSpec(field_name=parts[0], aggregation=agg, alias=parts[2])
+        raise InvalidPayloadError(f"无效的 --metric 定义: {raw}，格式: field_name[:aggregation[:alias]]")
 
     def _build_order_by(self, items: list[str], *, alias_map: dict[str, str] | None = None) -> list[dict]:
         """解析排序定义：expr[:asc|desc]，自动映射到 select 输出别名。"""
@@ -511,8 +523,25 @@ class QueryManager:
             raise InvalidPayloadError("where 必须是 JSON 对象")
         return payload
 
+    # 操作符标准化映射：将 Python/SQL 风格符号转换为服务端语义操作符
+    _WHERE_OP_MAP: dict[str, str] = {
+        ">=": "gte",
+        "<=": "lte",
+        ">": "gt",
+        "<": "lt",
+        "=": "eq",
+        "==": "eq",
+        "!=": "neq",
+        "<>": "neq",
+    }
+
     def _parse_where_condition(self, raw: str, *, dataset_alias: str) -> dict:
-        """解析 where 简写条件：field|operator|value_json。"""
+        """解析 where 简写条件：field|operator|value_json。
+
+        操作符支持两种写法：
+        - 语义操作符（服务端原生）：between, eq, neq, gt, gte, lt, lte, in
+        - 符号操作符（自动转换）：>=, <=, >, <, =, ==, !=, <>
+        """
         parts = raw.split("|", 2)
         if len(parts) != 3:
             raise InvalidPayloadError(f"无效的 --where 定义: {raw}")
@@ -521,6 +550,9 @@ class QueryManager:
         if not field or not operator or not value_raw:
             raise InvalidPayloadError(f"无效的 --where 定义: {raw}")
 
+        # 将符号操作符标准化为服务端语义操作符
+        operator = self._WHERE_OP_MAP.get(operator, operator)
+
         expr = field if "." in field else f"{dataset_alias}.{field}"
         try:
             value = json.loads(value_raw)

{aukeys_opscli-0.0.22 → aukeys_opscli-0.0.23}/opscli/skills/templates/ops-dataset-query/SKILL_MCP.md

@@ -182,6 +182,204 @@ print(format_pct(pct))                 # +23.46%
 
 ---
 
+### MCP 环境辅助脚本（无状态模式，不依赖 opscli）
+
+以下脚本位于 `scripts/` 目录，**专为 MCP 无状态模式设计**，零 opscli 依赖，仅通过文件输入/输出与 MCP Tool 配合。
+
+#### `query_mcp.py` — 本地 Payload 构造器
+
+使用本地 CSV 索引将简化参数转换为标准 query payload JSON 文件，供 `query_run` 使用。
+
+**特点**：
+- 字段别名解析（`global_alias > field_name > verbose_name`）
+- 字段歧义自动消歧（优先选取原始字段）
+- 支持 `data_comparison` 自动构造 `dataComparison` 对象
+
+**子命令**：
+
+```bash
+# build：构造 payload 并写入 JSON 文件
+python scripts/query_mcp.py build \
+  --dataset sales_order_d \
+  --dimension date_id \
+  --metric "order_cost:sum:total_cost" \
+  --where "date_id|>=|\"2024-01-01\"" \
+  --order-by "total_cost:desc" \
+  --output /tmp/query.json
+
+# 附带 dataComparison 环比
+python scripts/query_mcp.py build \
+  --dataset sales_order_d \
+  --dimension dept_name \
+  --metric "price:sum:total_price" \
+  --where "date_id|>=|\"2026-04-01\"" \
+  --data-comparison "date_id,2026-03-01,2026-03-22" \
+  --output /tmp/query.json
+
+# metadata：查看本地数据集 metadata（无需认证）
+python scripts/query_mcp.py metadata --dataset sales_order_d --pretty
+```
+
+**输出**（`build` 成功时）：
+```json
+{
+  "success": true,
+  "data": {
+    "output": "/tmp/query.json",
+    "payload": {
+      "tableId": 1,
+      "query": {
+        "select": [...],
+        "groupBy": [...],
+        "where": {...},
+        "orderBy": [...],
+        "limit": 20,
+        "offset": 0
+      }
+    }
+  }
+}
+```
+
+**配合 MCP Tool 使用**：
+```python
+# 1. 先用 query_mcp.py 构造 payload JSON（无需认证）
+# 2. 再通过 query_run 执行查询（需要认证）
+query_run(
+    payload_path="/tmp/query.json",
+    session_id="860b0636485b5188a2b9b4ed5210e736"
+)
+```
+
+---
+
+#### `chart_map_mcp.py` — chart 字段映射
+
+将 MCP `query_chart` 返回的 chart 结果中的 `global_alias` 映射为可读的 `verbose_name` / `field_name`。
+
+**用法**：
+```bash
+# 仅映射查询结构
+python scripts/chart_map_mcp.py --input /tmp/chart_result.json --pretty
+
+# 映射查询结构 + 结果行数据列名
+python scripts/chart_map_mcp.py --input /tmp/chart_result.json --map-results --pretty
+
+# 映射为 field_name
+python scripts/chart_map_mcp.py --input /tmp/chart_result.json --map-to field_name --pretty
+```
+
+**输入来源**：先通过 MCP `query_chart` 获取并保存为 JSON：
+```python
+query_chart(
+    chart_uuid="4NQ5f66sU9",
+    run=True,
+    session_id="860b0636485b5188a2b9b4ed5210e736"
+)
+# → 保存到 /tmp/chart_result.json
+```
+
+**输出**：每条 query 添加 `_mapping` 字段，包含 `dataset_alias`、`dataset_info`、`field_mappings`（含 `alias`、`expr`、`mapped_name`、`field_info`）。
+
+---
+
+#### `chart_analyze_mcp.py` — 图表异常检测
+
+对 chart 查询结果执行 5 类异常规则检测，输出结构化 JSON 报告。
+
+**用法**：
+```bash
+# 仅分析当期数据
+python scripts/chart_analyze_mcp.py --input /tmp/chart_result.json --pretty
+
+# 附带 dataComparison 环比数据（增强趋势检测）
+python scripts/chart_analyze_mcp.py \
+  --input /tmp/chart_result.json \
+  --dc-input /tmp/dc_result.json \
+  --pretty
+```
+
+**输入来源**：
+- `--input`：MCP `query_chart(chart_uuid="...", run=True)` 结果
+- `--dc-input`：MCP `query_build_and_run(..., data_comparison="...")` 结果
+
+**检测规则**：
+| 规则 | 触发条件 |
+|------|---------|
+| `negative_margin` | 毛利率 < 0 |
+| `profit_drop` | 毛利环比下降 > 30% |
+| `revenue_cliff` | 原价金额环比下降 > 20% |
+| `ad_roi_decline` | 广告费上升 + 毛利下降 |
+| `zero_orders` | 当期订单量归零（对比期 > 0） |
+
+**输出**：包含 `summary`（汇总统计）、`anomalies`（异常列表，按 severity 排序）、`findings`（人类可读关键发现）。
+
+---
+
+#### `excel_export_mcp.py` — 图表数据 Excel 导出
+
+从 chart 查询结果中提取明细、小计、总计数据，按透视表格式写入 Excel。
+
+**前置依赖**：`pip install openpyxl`
+
+**用法**：
+```bash
+python scripts/excel_export_mcp.py \
+  --input /tmp/chart_result.json \
+  --output /tmp/output.xlsx \
+  --sheet-name 销售数据
+```
+
+**格式规范**：
+- 表头：蓝色背景（4472C4）白色粗体字，冻结首行
+- 明细行：数值列千分位格式，百分比列 0.00% 格式
+- 小计行：灰色背景（D9E2F3），粗体字
+- 总计行：深蓝背景白色粗体字
+- 负值：红色字体（FF0000）
+- 列宽：自适应（最大 50 字符）
+
+**输出**：
+```json
+{
+  "success": true,
+  "output": "/tmp/output.xlsx",
+  "rows": 150,
+  "columns": ["日期", "部门", "销售额", "订单量"]
+}
+```
+
+---
+
+#### `updater_mcp.py` — 本地状态检查
+
+检查本地数据文件完整性，更新操作需通过 MCP `skills_upgrade` 执行。
+
+**用法**：
+```bash
+python scripts/updater_mcp.py --check --pretty
+```
+
+**输出**：
+```json
+{
+  "success": true,
+  "data": {
+    "data_dir": "/Users/mask/.config/opencode/skills/ops-dataset-query/data",
+    "version": "v1.2.3",
+    "healthy": true,
+    "files": {
+      "VERSION.json": {"exists": true, "version": "v1.2.3"},
+      "datasets.csv": {"exists": true, "size": 12345},
+      "dataset_fields.csv": {"exists": true, "size": 67890},
+      "query_metadata.json": {"exists": true, "size": 4567}
+    }
+  },
+  "mcp_hint": "如需更新，调用 skills_upgrade(name='ops-dataset-query')"
+}
+```
+
+---
+
 ## MCP Tool 调用参考
 
 ### `query_metadata`