aukeys-opscli 0.0.25__tar.gz → 0.0.26__tar.gz

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aukeys-opscli
-Version: 0.0.25
+Version: 0.0.26
 Summary: Aukeys 运营 CLI 工具集
 Requires-Python: >=3.10
 Requires-Dist: cryptography>=38
@@ -827,6 +827,42 @@ opscli query chart --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --run --dry-run -
 
 > 每个 query 独立执行，失败不影响其他 query；合并结果中每行附加 `_query_index` 标识来源。
 
+### `opscli query chart-doc` - 通过 chart_uuid 生成图表 API 调用 Markdown 文档
+
+```bash
+# 生成图表 API 调用文档
+opscli query chart-doc --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --pretty
+
+# 将 Markdown 文档写入指定文件
+opscli query chart-doc --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --output chart-doc.md --pretty
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--uuid` | 是 | 图表 UUID（chart_uuid） |
+| `--output` | 否 | 将 Markdown 文档写入指定文件路径 |
+| `--pretty` | 否 | 格式化 JSON 输出 |
+
+**返回结构**：
+
+```json
+{
+  "success": true,
+  "command": "query chart-doc",
+  "data": {
+    "chart_uuid": "32f660fd-f62a-45c4-a443-e21f2edb0779",
+    "markdown": "# 图表查询 API 开发文档\n...",
+    "query_count": 3,
+    "dataset_aliases": ["sales_order_d"],
+    "dataset_count": 1,
+    "output_path": "/path/to/chart-doc.md"
+  },
+  "error": null
+}
+```
+
+> 生成的 Markdown 文档包含七大章节：使用方式、关键术语、图表概览、API 调用流程、字段明细表、过滤规则、查询拆解与样例。
+
 ## Skills 使用
 
 ### `opscli skills list`

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/README.md

@@ -809,6 +809,42 @@ opscli query chart --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --run --dry-run -
 
 > 每个 query 独立执行，失败不影响其他 query；合并结果中每行附加 `_query_index` 标识来源。
 
+### `opscli query chart-doc` - 通过 chart_uuid 生成图表 API 调用 Markdown 文档
+
+```bash
+# 生成图表 API 调用文档
+opscli query chart-doc --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --pretty
+
+# 将 Markdown 文档写入指定文件
+opscli query chart-doc --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --output chart-doc.md --pretty
+```
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `--uuid` | 是 | 图表 UUID（chart_uuid） |
+| `--output` | 否 | 将 Markdown 文档写入指定文件路径 |
+| `--pretty` | 否 | 格式化 JSON 输出 |
+
+**返回结构**：
+
+```json
+{
+  "success": true,
+  "command": "query chart-doc",
+  "data": {
+    "chart_uuid": "32f660fd-f62a-45c4-a443-e21f2edb0779",
+    "markdown": "# 图表查询 API 开发文档\n...",
+    "query_count": 3,
+    "dataset_aliases": ["sales_order_d"],
+    "dataset_count": 1,
+    "output_path": "/path/to/chart-doc.md"
+  },
+  "error": null
+}
+```
+
+> 生成的 Markdown 文档包含七大章节：使用方式、关键术语、图表概览、API 调用流程、字段明细表、过滤规则、查询拆解与样例。
+
 ## Skills 使用
 
 ### `opscli skills list`

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/README_MCP.md

@@ -315,6 +315,53 @@ query_build_and_run(
 
 ---
 
+#### `query_chart_doc`
+
+通过 chart_uuid 生成图表 API 调用 Markdown 文档，包含查询结构、字段映射、过滤规则与样例。**需要认证**。
+
+文档包含七大章节：使用方式、关键术语、图表概览、API 调用流程、字段明细表、过滤规则、查询拆解与样例。适合 Skill / AI Agent 直接消费。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chart_uuid` | string | 是 | 图表唯一标识 |
+| `output_path` | string | 否 | 将 Markdown 写入指定文件路径 |
+| `session_id` | string | **是** | 用户授权后获得的 session_id |
+| `jwt` | string | 否 | JWT，不传则自动用 session_id 换取 |
+
+**返回示例：**
+```json
+{
+  "success": true,
+  "data": {
+    "chart_uuid": "32f660fd-f62a-45c4-a443-e21f2edb0779",
+    "markdown": "# 图表查询 API 开发文档\n...",
+    "query_count": 3,
+    "dataset_aliases": ["sales_order_d"],
+    "dataset_count": 1,
+    "output_path": "/path/to/chart-doc.md"
+  },
+  "error": null
+}
+```
+
+**典型用法：**
+```python
+# 生成图表文档（Markdown 在返回数据中）
+query_chart_doc(
+  chart_uuid="32f660fd-f62a-45c4-a443-e21f2edb0779",
+  session_id="860b0636485b5188a2b9b4ed5210e736",
+)
+
+# 生成文档并写入本地文件
+query_chart_doc(
+  chart_uuid="32f660fd-f62a-45c4-a443-e21f2edb0779",
+  output_path="/tmp/chart-doc.md",
+  session_id="860b0636485b5188a2b9b4ed5210e736",
+)
+```
+
+---
+
 ### 认证（auth_*）
 
 #### `auth_login_start`

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/docs/change-log-pending.md

@@ -1,5 +1,41 @@
 # 待归档变更记录
 
+## 2026-04-29 opscli - 实现 Skill 委托模式，防止 AI 猜测字段名
+
+**变更原因**：测试调用记录显示，AI 在执行数据集查询时经常直接猜测字段名（如 `ds_pdTYjvLRCadv.asin`），导致 `INVALID_PAYLOAD` 错误。需要显式声明业务逻辑层 Skill 应将数据查询工作委托给 `ops-dataset-query` Skill，由其负责字段发现、metadata 验证和 payload 构造。
+
+**改动点**：
+- 为 9 个数据查询类 Skill 的 `SKILL.md` 添加"## 技能委托声明"部分
+  - ops-asin-health-diagnoser（之前已完成）
+  - ops-competitive-intelligence-analyst
+  - ops-cross-border-product-selector
+  - ops-advertising-efficiency-optimizer
+  - ops-inventory-health-monitor
+  - ops-product-attribute-analyzer
+  - ops-perspective-builder
+  - ops-profit-structure-analyzer
+  - ops-refund-priority-matrix
+- 每个委托声明包含：
+  - 责任边界表（数据查询层 → ops-dataset-query，业务逻辑层 → 当前 Skill）
+  - 委托触发规则表（5 场景，标注 ✅ 必须委托 / ❌ 可直接执行）
+  - 委托调用方式示例（→ 调用 / ← 返回）
+  - 反例警告（禁止直接猜测字段名）
+- 插入位置统一为"阅读入口"和"使用原则"之间
+
+**验证结果**：
+- `grep -l "## 技能委托声明" opscli/skills/templates/ops-*/SKILL.md | wc -l` 返回 9
+- 所有 9 个数据查询类 Skill 已包含完整委托声明
+
+**影响范围**：
+- AI Agent 在调用这些 Skill 时，会优先切换到 ops-dataset-query 进行字段发现
+- 减少 INVALID_PAYLOAD 错误，避免额外的往返修复
+- 不影响 CLI 模式用户直接使用 opscli query 命令
+
+**回滚方式**：
+- 删除各 SKILL.md 中"## 技能委托声明"部分（从 `---` 到下一个 `---`）
+
+---
+
 ## 2026-04-27 opscli - 新增 chart_analyze_mcp.py
 
 **变更原因**：为 ops-dataset-query Skill 新增 MCP 无状态模式的图表异常检测脚本，原 `chart_analyze.py` 依赖 `opscli` CLI（subprocess），无法在纯 MCP 环境中使用。
@@ -172,3 +208,76 @@
 **回滚方式**：删除 CLAUDE.md 中【铁律19】至【铁律22】段落
 
 ---
+
+## 2026-04-29 auto-scheduler + opscli - 图表查询接口增加过滤字段及新增 chart-doc 指令
+
+**变更原因**：
+1. 服务端 `latest-request-data` 接口需要返回当前图表数据集支持的过滤条件字段，供 opscli 侧了解可用 WHERE 条件
+2. opscli 侧需要在图表查询结果中透传过滤字段信息
+3. 新增 `opscli query chart-doc` 指令，支持通过 chart_uuid 自动生成完整 API 调用 Markdown 文档
+
+**改动点**：
+
+### 服务端（auto-scheduler）
+- 修改 `vendor/aukey/data-metrics/src/Http/Controllers/CliQueryApiController.php`
+  - 引入 `Aukey\DataMetrics\Models\SelectColumnRelation`
+  - `latestRequestData` 方法新增逻辑：通过 `query.from.alias` → `dm_tables.dataset_alias` → `dm_select_column_relations.dataset_alias` 查询启用的过滤字段
+  - 返回结构扩展：每个 query item 新增 `filterable_fields` 字段（含 `column_name`、`verbose_name`、`source_column_name`）
+  - 按 `dataset_alias` 缓存避免重复查询
+
+### opscli 侧
+- 修改 `opscli/query/services/manager.py`
+  - `run_chart_queries` 方法透传 `filterable_fields` 和 `query_structure` 到每个 query 结果中
+  - 新增 `generate_chart_doc(chart_uuid)` 方法：生成完整 Markdown 文档，含数据集概览、过滤字段表、查询结构说明、API 调用顺序、Payload 示例、WHERE 条件构建指南
+  - 示例中敏感字段（`table`/`permission`）使用占位符，不返回 `userEmail`
+- 修改 `opscli/query/commands/cli.py`
+  - 新增 `chart-doc` 子命令：`opscli query chart-doc --uuid <chart_uuid> [--output <file>] [--pretty]`
+  - 支持将 Markdown 文档直接写入文件
+
+**验证结果**：
+- `python -m py_compile opscli/query/services/manager.py opscli/query/commands/cli.py` 语法检查通过
+- 服务端 PHP 文件未引入语法错误（新增 import + 扩展已有循环逻辑）
+
+**影响范围**：
+- 服务端 `latest-request-data` 接口返回结构向后兼容扩展（新增字段）
+- opscli `query chart` 和 `query chart-run` 返回的每个 query 中新增 `filterable_fields` 和 `query_structure`
+- 新增 `query chart-doc` 命令，不影响现有命令
+
+**回滚方式**：
+- 服务端：回退 `CliQueryApiController.php` 的 `latestRequestData` 方法修改
+- opscli：回退 `manager.py` 中 `run_chart_queries` 和 `generate_chart_doc`，回退 `cli.py` 中 `chart_doc` 命令
+
+---
+
+## 2026-04-29 query - 优化 chart-doc 生成文档结构
+
+**变更原因**：生成的文档存在三个缺陷：可过滤字段在多 Query 时重复渲染浪费 token；7.1 字段映射表列数达 8 列宽表 AI 不友好；缺少字段命名约定说明导致 AI 无法处理边界场景
+**改动点**：
+1. `opscli/query/services/manager.py - generate_chart_doc`：
+   - §2 新增"字段命名约定"小节（§2.2），说明 query_alias / global_alias / origin_name / expr 的格式规律、生成方式和使用场景，及公式字段边界说明
+   - §7.1 输出字段映射由 1 张 8 列宽表拆分为 2 张 4 列表（表A字段语义 + 表B字段引用），以 field_name 作连接键，expr 列去掉并在表B注释中说明
+   - §7.3 可过滤字段新增去重逻辑：对比当前 Query 与所属数据集（§5.2）的 filterable_fields 集合，完全相同时只输出一行引用语句，不同才完整渲染
+2. `tests/query/test_manager.py`：更新两个受影响的测试断言匹配新双表格式和去重引用格式
+**验证结果**：pytest tests/query/ 39 passed
+**影响范围**：opscli query chart-doc 命令输出的 Markdown 文档结构；不影响 API 调用逻辑
+**回滚方式**：git revert 此次改动，恢复 manager.py 和 test_manager.py 对应段落
+---
+
+## 2026-04-29 skills/templates - 精简所有 Skill 的 references 文档
+
+**变更原因**：`data-query-service-dev-guide.md`（1173行）在 9 个业务 Skill 中存在完全相同的 10 份副本，占每个 Skill 文档总量的 60-75%；其中大量章节（多次查询、MOY/ACC/PPT、缓存、PHP 伪代码）对 Skill 执行无用，造成 AI 上下文浪费和维护困难
+
+**改动点**：
+1. 新建 `query-essential-guide.md`（149行）：从完整 dev-guide 中提取 Skill 真正需要的内容（WHERE 操作符、SELECT 格式、日期规范、dataComparison、错误码），复制到 9 个业务 Skill 的 references/
+2. 删除 9 个业务 Skill 中的 `data-query-service-dev-guide.md`，保留 `ops-dataset-query/references/` 中的唯一完整版
+3. 精简 `ops-asin-health-diagnoser/references/dataset_fields_mapping.md`（134行→65行）：去掉静态 payload 模板，保留数据集索引 + 核心字段业务语义 + chart-doc 使用指引
+4. 更新 9 个 Skill 的 `SKILL.md`、`references/cli.md`、`references/mcp.md` 中的文件名引用（data-query-service-dev-guide → query-essential-guide）
+
+**验证结果**：
+- dev-guide 残留检查通过（9 个业务 Skill 均已删除）
+- query-essential-guide 分布：9 个 Skill 均已到位
+- 各 Skill 文档总行数：平均从 ~1800 行降至 ~737 行，减少约 59%
+
+**影响范围**：所有业务类 Skill 的 references 目录结构；ops-dataset-query 不受影响
+**回滚方式**：从 ops-dataset-query/references/data-query-service-dev-guide.md 重新 cp 到各 Skill，删除 query-essential-guide.md，恢复文件名引用
+---

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/docs/guide/opscli/345/221/275/344/273/244/347/224/250/344/276/213/346/211/213/345/206/214.md

@@ -39,7 +39,8 @@ opscli
 │   ├── metadata
 │   ├── run
 │   ├── build
-│   └── chart
+│   ├── chart
+│   └── chart-doc
 └── skills
     ├── list
     ├── install
@@ -632,6 +633,66 @@ opscli query chart --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --run --dry-run -
 
 ---
 
+---
+
+### 6.5 `opscli query chart-doc`
+
+通过 `chart_uuid` 生成图表 API 调用 Markdown 文档，包含查询结构、字段映射、过滤规则与样例。
+
+**用法**
+
+```bash
+opscli query chart-doc --uuid <chart_uuid> [--output <file>] [--pretty]
+```
+
+**参数**
+
+| 参数 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `--uuid` | 是 | - | 图表 UUID（chart_uuid） |
+| `--output` | 否 | - | 将 Markdown 文档写入指定文件路径 |
+| `--pretty` | 否 | `false` | 美化 JSON 输出 |
+
+**说明**
+
+- 该命令通过 `chart_uuid` 获取图表的查询结构，自动生成一份完整 Markdown 文档。
+- 生成的文档包含七大章节：使用方式、关键术语、图表概览、API 调用流程、字段明细表、过滤规则、查询拆解与样例。
+- 使用 `--output` 可将 Markdown 内容直接写入文件，方便保存和分发。
+
+**示例**
+
+生成文档并在终端查看：
+
+```bash
+opscli query chart-doc --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --pretty
+```
+
+将文档写入文件：
+
+```bash
+opscli query chart-doc --uuid 32f660fd-f62a-45c4-a443-e21f2edb0779 --output chart-doc.md --pretty
+```
+
+**返回结构**
+
+```json
+{
+  "success": true,
+  "command": "query chart-doc",
+  "data": {
+    "chart_uuid": "32f660fd-f62a-45c4-a443-e21f2edb0779",
+    "markdown": "# 图表查询 API 开发文档\n...",
+    "query_count": 3,
+    "dataset_aliases": ["sales_order_d"],
+    "dataset_count": 1,
+    "output_path": "/path/to/chart-doc.md"
+  },
+  "error": null
+}
+```
+
+---
+
 ### 6.3 `opscli query build`
 
 基于简化参数构造标准 query payload；也可以直接执行。
@@ -948,5 +1009,5 @@ opscli skills upgrade ops-dataset-query --pretty
 | Token | `opscli auth token status`、`get`、`check`、`refresh` |
 | 系统管理 | `opscli auth system list`、`sync`、`add`、`remove` |
 | Amazon | `opscli amazon scrape`、`payload`、`search`、`schema`、`history` |
-| 查询 | `opscli query metadata`、`run`、`build`、`chart` |
+| 查询 | `opscli query metadata`、`run`、`build`、`chart`、`chart-doc` |
 | Skills | `opscli skills list`、`install`、`status`、`upgrade` |

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/opscli/mcp/tools/query.py

@@ -6,6 +6,7 @@
 - query_run             — 读取本地 payload 文件并执行查询
 - query_build_and_run   — 构造 payload 并立即执行，一步返回结果
 - query_chart           — 通过 chart_uuid 获取/执行图表查询
+- query_chart_doc       — 通过 chart_uuid 生成图表 API 调用 Markdown 文档
 
 所有工具函数定义在模块级，可直接导入调用（测试友好）。
 调用 register(mcp) 将以上工具批量注册到指定 MCP 实例。
@@ -218,8 +219,47 @@ async def query_chart(
             return _ok(result)
         else:
             # 仅获取图表查询结构，不执行
-            chart_items = manager.fetch_chart_queries(chart_uuid)
-            return _ok({"chart_uuid": chart_uuid, "queries": chart_items})
+            chart_bundle = manager.fetch_chart_bundle(chart_uuid)
+            return _ok(chart_bundle)
+    except Exception as exc:
+        return _err(exc)
+
+
+async def query_chart_doc(
+    chart_uuid: str,
+    output_path: str | None = None,
+    session_id: str | None = None,
+    jwt: str | None = None,
+) -> dict:
+    """通过 chart_uuid 生成图表 API 调用 Markdown 文档，包含查询结构、字段映射、过滤规则与样例。
+
+    生成的文档包含七大章节：使用方式、关键术语、图表概览、API 调用流程、
+    字段明细表、过滤规则、查询拆解与样例。适合 Skill / AI Agent 消费。
+
+    如果未提供 session_id / jwt，会自动尝试从本地加载已保存的凭据。
+
+    Args:
+        chart_uuid:  图表唯一标识
+        output_path: 可选，将 Markdown 写入指定文件路径
+        session_id:  可选，OAuth 授权后的 Session ID（为空则自动加载本地保存的）
+        jwt:         可选，已有 JWT（为空则自动加载本地缓存的）
+    """
+    from opscli.mcp.tools.helpers import _get_auth_pair
+
+    sid, jw = _get_auth_pair("ops", session_id, jwt)
+    if not sid:
+        return _err(ValueError("无 session_id：请完成授权登录，或传入有效的 session_id"))
+    manager = _query_manager(jwt=jw, session_id=sid)
+    try:
+        result = manager.generate_chart_doc(chart_uuid=chart_uuid)
+        if output_path:
+            from pathlib import Path
+
+            p = Path(output_path).expanduser()
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_text(result["markdown"], encoding="utf-8")
+            result["output_path"] = str(p)
+        return _ok(result)
     except Exception as exc:
         return _err(exc)
 
@@ -231,6 +271,7 @@ _ALL_TOOLS = [
     query_run,
     query_build_and_run,
     query_chart,
+    query_chart_doc,
 ]
 
 

{aukeys_opscli-0.0.25 → aukeys_opscli-0.0.26}/opscli/query/commands/cli.py

@@ -102,14 +102,11 @@ def chart(
                 "error": None,
             }
         else:
-            chart_items = manager.fetch_chart_queries(uuid)
+            chart_bundle = manager.fetch_chart_bundle(uuid)
             payload = {
                 "success": True,
                 "command": "query chart",
-                "data": {
-                    "chart_uuid": uuid,
-                    "queries": chart_items,
-                },
+                "data": chart_bundle,
                 "error": None,
             }
     except Exception as exc:
@@ -119,6 +116,38 @@ def chart(
     _emit(payload, pretty)
 
 
+@app.command("chart-doc")
+def chart_doc(
+    uuid: str = typer.Option(..., "--uuid", help="图表 UUID（chart_uuid）"),
+    output: str | None = typer.Option(None, "--output", help="将 Markdown 文档写入指定文件路径"),
+    pretty: bool = typer.Option(False, "--pretty", help="格式化输出 JSON 包装体"),
+):
+    """通过 chart_uuid 生成图表 API 调用 Markdown 文档。"""
+    manager = QueryManager()
+    try:
+        result = manager.generate_chart_doc(chart_uuid=uuid)
+
+        # 如果指定了输出文件，将 Markdown 写入文件
+        if output:
+            from pathlib import Path
+            output_path = Path(output).expanduser()
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(result["markdown"], encoding="utf-8")
+            result["output_path"] = str(output_path)
+
+        payload = {
+            "success": True,
+            "command": "query chart-doc",
+            "data": result,
+            "error": None,
+        }
+    except Exception as exc:
+        _emit(_error_payload("query chart-doc", exc), pretty)
+        raise typer.Exit(1)
+
+    _emit(payload, pretty)
+
+
 @app.command("build")
 def build(
     dataset: str | None = typer.Option(None, "--dataset", help="dataset_alias"),