aukeys-opscli 0.0.28__tar.gz → 0.0.30__tar.gz

{aukeys_opscli-0.0.28 → aukeys_opscli-0.0.30}/PKG-INFO

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

{aukeys_opscli-0.0.28 → aukeys_opscli-0.0.30}/docs/guide/MCP/345/267/245/345/205/267/344/275/277/347/224/250/346/211/213/345/206/214.md

@@ -36,7 +36,8 @@ opscli MCP Tools
 │   ├── query_build
 │   ├── query_run
 │   ├── query_build_and_run
-│   └── query_chart
+│   ├── query_chart
+│   └── query_chart_doc
 └── skills
     ├── skills_list
     ├── skills_install
@@ -844,6 +845,61 @@ query_chart(
 
 ---
 
+### 5.6 `query_chart_doc`
+
+通过 `chart_uuid` 生成图表 API 调用 Markdown 文档，包含查询结构、字段映射、过滤规则与样例。**需要认证**。
+
+文档包含七大章节：使用方式、关键术语、图表概览、API 调用流程、字段明细表、过滤规则、查询拆解与样例。适合 Skill / AI Agent 直接消费。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chart_uuid` | string | 是 | 图表唯一标识 |
+| `output_path` | string | 否 | 将 Markdown 写入指定文件路径 |
+| `session_id` | string | 否 | OAuth 授权后的 Session ID（为空则自动加载本地保存的） |
+| `jwt` | string | 否 | 已有 JWT（为空则自动加载本地缓存的） |
+
+**返回**
+
+```json
+{
+  "success": true,
+  "data": {
+    "chart_uuid": "jSNuhm54uY",
+    "markdown": "# 图表查询 API 开发文档\n...",
+    "query_count": 3,
+    "dataset_aliases": ["sales_order_d"],
+    "dataset_count": 1,
+    "output_path": "/tmp/chart_api_doc.md"
+  },
+  "error": null
+}
+```
+
+**示例**
+
+生成文档（Markdown 在返回数据中）：
+
+```python
+query_chart_doc(
+    chart_uuid="jSNuhm54uY",
+    session_id="860b0636485b5188a2b9b4ed5210e736"
+)
+```
+
+生成文档并写入本地文件：
+
+```python
+query_chart_doc(
+    chart_uuid="jSNuhm54uY",
+    output_path="/tmp/chart_api_doc.md",
+    session_id="860b0636485b5188a2b9b4ed5210e736"
+)
+```
+
+---
+
 ## 6. Skill 模块 `skills_*`
 
 用于扫描已安装 Skill、安装内置模板、查看状态、升级远端版本。
@@ -1055,6 +1111,7 @@ result = query_chart(
 | `query_build_and_run` | **是** | 可传 session_id / jwt |
 | `query_chart`（run=False） | 否 | - |
 | `query_chart`（run=True） | **是** | 可传 session_id / jwt |
+| `query_chart_doc` | **是** | 可传 session_id / jwt |
 | `skills_list` | 否 | - |
 | `skills_install` | 否 | - |
 | `skills_status` | 服务端自动 | 涉及远端 API |
@@ -1088,6 +1145,7 @@ result = query_chart(
 | 查询 | `query_run` | `opscli query run` |
 | 查询 | `query_build_and_run` | `opscli query build --run` |
 | 查询 | `query_chart` | `opscli query chart` |
+| 查询 | `query_chart_doc` | `opscli query chart-doc` |
 | Skills | `skills_list` | `opscli skills list` |
 | Skills | `skills_install` | `opscli skills install` |
 | Skills | `skills_status` | `opscli skills status` |

aukeys_opscli-0.0.30/opscli/skills/templates/ops-dataset-query/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store

{aukeys_opscli-0.0.28 → aukeys_opscli-0.0.30}/opscli/skills/templates/ops-dataset-query/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ops-dataset-query
 description: 根据当前环境自动选择 CLI 或 MCP 方式查询本地数据集索引并执行数据查询
-version: v0.0.5
+version: see data/VERSION.json
 ---
 
 # ops-dataset-query

{aukeys_opscli-0.0.28 → aukeys_opscli-0.0.30}/opscli/skills/templates/ops-dataset-query/references/cli.md

@@ -1,7 +1,6 @@
 ---
 name: ops-dataset-query
-description: 使用本地缓存的数据集与字段索引辅助检索和查询
-version: v0.0.3
+description: 使用本地缓存的数据集与字段索引辅助检索和查询（CLI 模式）
 ---
 
 # ops-dataset-query
@@ -885,228 +884,16 @@ opscli skills upgrade ops-dataset-query --force
 
 ## 高级查询说明
 
-详细规则见 `references/data-query-service-dev-guide.md`，核心章节：
-
-| 场景 | 参考章节 |
-|------|---------|
-| innerWhere、子查询数据集 | 第三章 数据集类型详解 |
-| WHERE 操作符、嵌套条件、translate | 第五章 WHERE 条件构建指南 |
-| dataComparison 数据对比 | 第六章 |
-| 多次查询（交叉表/透视表/堆叠图） | 第七章 |
-| SELECT 字段、聚合函数、高级计算(MOY/ACC/PPT) | 第八章 |
-| 权限占位符 | 第四章 |
-| 分页与排序 | 第九章 |
+> 完整的数据对比与高级计算参考（dataComparison / MOY / ACC / PPT / 决策流程 / payload 结构）
+> 请参见 **`references/query-patterns.md`**。
 
 **使用建议**：
 - 普通聚合优先使用 `opscli query build`
-- 涉及上述高级场景时，先阅读引用文档，再手写 payload + `opscli query run`
-
----
-
-## 数据对比与高级计算
-
-### 方案选择决策流程
-
-```
-用户需要比较两个时间段的数据？
-├── YES → 需要按时间粒度（日/月）分组展示趋势？
-│         ├── YES → 使用 MOY 高级计算（comparison 写在 select 字段内）
-│         └── NO  → 需要当期 vs 对比期汇总对比？
-│                   ├── YES → 使用 dataComparison（服务端一次 SQL，推荐首选）
-│                   └── NO  → 普通聚合 opscli query build
-└── NO  → 普通聚合 opscli query build
-```
-
----
-
-### dataComparison 数据对比
-
-> 服务端将当期和对比期合并为**一次 SQL**（条件聚合），每个度量字段自动裂变为 4 个字段。
-
-**字段裂变规则**（以别名 `total_price` 为例）：
-
-| 裂变字段 | 含义 |
-|---------|------|
-| `total_price` | 当期值 |
-| `last_total_price` | 对比期值 |
-| `diff_total_price` | 绝对差值（当期 - 对比期） |
-| `pct_total_price` | 变化率（差值 / ABS(对比期)），上期为 0 时返回 null |
-
-**payload 结构**（`opscli query run --payload`）：
-
-```json
-{
-  "tableId": 1104,
-  "query": {
-    "select": [
-      {"expr": "ds_xxx.dept_name", "alias": "dept_name"},
-      {"expr": "ds_xxx.price", "alias": "total_price", "aggregation": "SUM"},
-      {"expr": "ds_xxx.order_qty", "alias": "total_qty", "aggregation": "SUM"}
-    ],
-    "groupBy": ["dept_name"],
-    "where": {
-      "operator": "AND",
-      "conditions": [
-        {"field": "ds_xxx.date_id", "operator": "gte", "value": "2026-04-01"},
-        {"field": "ds_xxx.date_id", "operator": "lte", "value": "2026-04-22"}
-      ]
-    },
-    "orderBy": [{"expr": "total_price", "desc": true}],
-    "limit": 50,
-    "offset": 0
-  },
-  "dataComparison": {
-    "switch": true,
-    "field": "ds_xxx.date_id",
-    "startDate": "2026-03-01",
-    "endDate": "2026-03-22"
-  }
-}
-```
-
-
-**适用场景**：当期（如本月 1-22 日） vs 对比期（如上月同期 1-22 日）的汇总数据对比，**同期天数对等**，适合月度/季度环比汇总看板。
-
----
-
-### MOY 同环比（高级计算）
-
-> 服务端通过窗口函数 `LAG()` 计算，**`comparison` 字段写在 `select` 内部**，opscli 可正常透传。
-
-**前提条件**：`groupBy` 中**必须同时包含日期维度和其他业务维度**。
-
-**type 枚举速查**：
-
-| 类型 | `type` 值 | groupBy 日期格式 |
-|------|-----------|----------------|
-| 月环比 | `MOM_MONTH` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m')` |
-| 日环比 | `MOM_DAY` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m-%d')` |
-| 周环比 | `MOM_WEEK` | `DATE_FORMAT(ds_xxx.date_id, '%x-%v')` |
-| 月同比 | `YOY_MONTH` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m-%d')` |
-| 年同比 | `YOY_YEAR` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m-%d')` |
-
-**`cacl_type` 字段语义**（重要，容易误解）：
-
-| `cacl_type` | 字段值含义 | 说明 |
-|-------------|-----------|------|
-| `ORIGINAL` | **上期值（LAG）** | 不是当期原始值！是前一期的聚合结果 |
-| `COMPARE` | 当期 − 上期 | 正数=增长，负数=下滑 |
-| `PERCENT` | (当期 − 上期) / ABS(上期) | 环比变化率，上期为 0 时返回 null |
-
-> 💡 当期实际值 = `ORIGINAL 字段值` + `COMPARE 字段值`
-
-**完整 payload 示例（月环比，按部门）**：
-
-```json
-{
-  "tableId": 1104,
-  "query": {
-    "select": [
-      {"expr": "ds_xxx.dept_name", "alias": "dept_name"},
-      {"expr": "DATE_FORMAT(ds_xxx.date_id, '%Y-%m')", "alias": "month"},
-      {
-        "expr": "ds_xxx.price",
-        "alias": "price_prev",
-        "comparison": "MOY",
-        "params": {
-          "date": "DATE_FORMAT(ds_xxx.date_id, '%Y-%m')",
-          "dim": ["dept_name"],
-          "type": "MOM_MONTH",
-          "cacl_type": "ORIGINAL",
-          "aggregation": "SUM"
-        }
-      },
-      {
-        "expr": "ds_xxx.price",
-        "alias": "price_diff",
-        "comparison": "MOY",
-        "params": {
-          "date": "DATE_FORMAT(ds_xxx.date_id, '%Y-%m')",
-          "dim": ["dept_name"],
-          "type": "MOM_MONTH",
-          "cacl_type": "COMPARE",
-          "aggregation": "SUM"
-        }
-      },
-      {
-        "expr": "ds_xxx.price",
-        "alias": "price_pct",
-        "comparison": "MOY",
-        "params": {
-          "date": "DATE_FORMAT(ds_xxx.date_id, '%Y-%m')",
-          "dim": ["dept_name"],
-          "type": "MOM_MONTH",
-          "cacl_type": "PERCENT",
-          "aggregation": "SUM"
-        }
-      }
-    ],
-    "groupBy": ["dept_name", "month"],
-    "where": {
-      "operator": "AND",
-      "conditions": [
-        {"field": "ds_xxx.date_id", "operator": "gte", "value": "2026-03-01"},
-        {"field": "ds_xxx.date_id", "operator": "lte", "value": "2026-04-22"}
-      ]
-    },
-    "orderBy": [
-      {"expr": "month", "desc": true},
-      {"expr": "price_diff", "desc": true}
-    ],
-    "limit": 100,
-    "offset": 0
-  }
-}
-```
-
-**结果读取说明**：
-- 当月行（如 `2026-04`）：`price_prev` = 上月值，`price_diff` = 本月增减，`price_pct` = 环比率
-- 上月行（如 `2026-03`）：`price_prev` = 上上月值，其他同理
-- WHERE 范围需覆盖**当期 + 对比期**（至少两个完整粒度），否则最早一期 `price_prev` 为 NULL
-
-**适用场景**：按月/日/周分组的趋势图、时序对比；注意 MOY 用整个历史周期做 LAG，与 `dataComparison` 的同期对比不同，**月中查询时本月 vs 上月完整月存在天数不等的偏差**。
-
----
-
-### ACC 累加计算
-
-> 按时间序列滚动累计（Running Total），适合 YTD 累计销售额等场景。
-
-```json
-{
-  "expr": "ds_xxx.price",
-  "alias": "price_acc",
-  "comparison": "ACC",
-  "params": {
-    "dim": [],
-    "aggregation": "SUM"
-  }
-}
-```
-
-> `dim` 当前固定传空数组 `[]`，暂不支持分组累加。
-
----
-
-### PPT 占比计算
-
-> 当前维度指标值 ÷ 全局总量，适合各部门销售额占比等场景。
-
-```json
-{
-  "expr": "ds_xxx.price",
-  "alias": "price_ppt",
-  "comparison": "PPT",
-  "params": {
-    "dim": [],
-    "aggregation": "SUM"
-  }
-}
-```
+- 涉及高级场景时，先阅读 `references/query-patterns.md` 和 `references/data-query-service-dev-guide.md`，再手写 payload + `opscli query run`
 
 ---
 
-### 降级方案：多次查询客户端合并
+### 降级方案：多次查询客户端合并（CLI 示例）
 
 > **仅在 dataComparison 和 MOY 均无法满足需求时使用**（如工具限制、跨数据集对比）。
 

{aukeys_opscli-0.0.28 → aukeys_opscli-0.0.30}/opscli/skills/templates/ops-dataset-query/references/mcp.md

@@ -1,6 +1,5 @@
 ---
 name: ops-dataset-query
-mcp-version: v1.0.1
 description: 使用 MCP Tool 查询本地缓存的数据集与字段索引，执行数据查询（无状态模式）
 ---
 
@@ -656,32 +655,15 @@ auth_token_refresh(system="ops", session_id="860b0636485b5188a2b9b4ed5210e736")
 
 ## 数据对比与高级计算
 
-### 方案选择决策流程
+> 完整的数据对比与高级计算参考（dataComparison / MOY / ACC / PPT / 决策流程 / payload 结构）
+> 请参见 **`references/query-patterns.md`**。
 
-```
-用户需要比较两个时间段的数据？
-├── YES → 需要按时间粒度（日/月）分组展示趋势？
-│         ├── YES → 使用 MOY 高级计算（comparison 写在 select 字段内）
-│         └── NO  → 需要当期 vs 对比期汇总对比？
-│                   ├── YES → 使用 dataComparison（服务端一次 SQL，推荐首选）
-│                   └── NO  → 普通聚合 query_build_and_run
-└── NO  → 普通聚合 query_build_and_run
-```
-
-### dataComparison 数据对比
-
-> 服务端将当期和对比期合并为**一次 SQL**（条件聚合），每个度量字段自动裂变为 4 个字段。
-
-**字段裂变规则**（以别名 `total_price` 为例）：
+**使用建议**：
+- 普通聚合优先使用 `query_build_and_run`
+- 涉及高级场景时，先阅读 `references/query-patterns.md` 和 `references/data-query-service-dev-guide.md`，再手写 payload + `query_run`
 
-| 裂变字段 | 含义 |
-|---------|------|
-| `total_price` | 当期值 |
-| `last_total_price` | 对比期值 |
-| `diff_total_price` | 绝对差值（当期 - 对比期） |
-| `pct_total_price` | 变化率（差值 / ABS(对比期)），上期为 0 时返回 null |
+### dataComparison MCP 调用示例
 
-**调用示例**：
 ```python
 query_build_and_run(
     table_id=1104,
@@ -693,53 +675,7 @@ query_build_and_run(
 )
 ```
 
-**适用场景**：当期（如本月 1-22 日） vs 对比期（如上月同期 1-22 日）的汇总数据对比，**同期天数对等**。
-
----
-
-### MOY 同环比（高级计算）
-
-> 服务端通过窗口函数 `LAG()` 计算，**`comparison` 字段写在 `select` 内部**。
-
-**前提条件**：`groupBy` 中**必须同时包含日期维度和其他业务维度**。
-
-**type 枚举速查**：
-
-| 类型 | `type` 值 | groupBy 日期格式 |
-|------|-----------|----------------|
-| 月环比 | `MOM_MONTH` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m')` |
-| 日环比 | `MOM_DAY` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m-%d')` |
-| 周环比 | `MOM_WEEK` | `DATE_FORMAT(ds_xxx.date_id, '%x-%v')` |
-| 月同比 | `YOY_MONTH` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m-%d')` |
-| 年同比 | `YOY_YEAR` | `DATE_FORMAT(ds_xxx.date_id, '%Y-%m-%d')` |
-
-**`cacl_type` 字段语义**：
-
-| `cacl_type` | 字段值含义 | 说明 |
-|-------------|-----------|------|
-| `ORIGINAL` | **上期值（LAG）** | 不是当期原始值！是前一期的聚合结果 |
-| `COMPARE` | 当期 − 上期 | 正数=增长，负数=下滑 |
-| `PERCENT` | (当期 − 上期) / ABS(上期) | 环比变化率，上期为 0 时返回 null |
-
-> 💡 当期实际值 = `ORIGINAL 字段值` + `COMPARE 字段值`
-
-**适用场景**：按月/日/周分组的趋势图、时序对比。注意 MOY 用整个历史周期做 LAG，与 `dataComparison` 的同期对比不同。
-
----
-
-### ACC 累加计算
-
-> 按时间序列滚动累计（Running Total），适合 YTD 累计销售额等场景。
-
----
-
-### PPT 占比计算
-
-> 当前维度指标值 ÷ 全局总量，适合各部门销售额占比等场景。
-
----
-
-### 降级方案：多次查询客户端合并
+### 降级方案：多次查询客户端合并（MCP 示例）
 
 > **仅在 dataComparison 和 MOY 均无法满足需求时使用**。
 
@@ -924,18 +860,8 @@ skills_upgrade(name="ops-dataset-query", skills_dir="/Users/mask/.config/opencod
 
 ## 高级查询说明
 
-详细规则见 `references/data-query-service-dev-guide.md`，核心章节：
-
-| 场景 | 参考章节 |
-|------|---------|
-| innerWhere、子查询数据集 | 第三章 数据集类型详解 |
-| WHERE 操作符、嵌套条件、translate | 第五章 WHERE 条件构建指南 |
-| dataComparison 数据对比 | 第六章 |
-| 多次查询（交叉表/透视表/堆叠图） | 第七章 |
-| SELECT 字段、聚合函数、高级计算(MOY/ACC/PPT) | 第八章 |
-| 权限占位符 | 第四章 |
-| 分页与排序 | 第九章 |
+> 完整的高级查询章节索引和数据对比参考请参见 **`references/query-patterns.md`**。
 
 **使用建议**：
 - 普通聚合优先使用 `query_build_and_run`
-- 涉及上述高级场景时，先阅读引用文档，再手写 payload + `query_run`
+- 涉及高级场景时，先阅读 `references/query-patterns.md` 和 `references/data-query-service-dev-guide.md`，再手写 payload + `query_run`