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

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

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

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.27}/opscli/skills/templates/ops-advertising-efficiency-optimizer/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ops-advertising-efficiency-optimizer
 description: 跨广告系列、广告组和广告类型 (SP/SD/SB/SBV) 维度分析广告效率。识别高 ACOS 问题并生成字级、活动级和时间段优化建议。支持 CLI 模式和 MCP 模式。在评估广告效率、优化广告预算、比较广告类型效果或诊断广告浪费时使用。
-version: v0.1.0
+version: v0.1.1
 ---
 
 # 广告效率优化器
@@ -22,48 +22,27 @@ version: v0.1.0
 
 ## 运行模式判断
 
-进入本 Skill 后，先判断当前环境使用哪种模式。
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
 
 优先级如下：
 
 1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
-2. 否则先检测是否安装了 `aukeys-opscli` Python 发行包
-3. 再检测 `opscli` 命令是否可执行
-4. 如果以上检测通过，读取 `references/cli.md`
-5. 如果任一检测失败，读取 `references/mcp.md`
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli query ...` 不可用、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、查询工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
 
-推荐检测脚本：
+建议提问方式：
 
-```bash
-python - <<'PY'
-from importlib import metadata
-import shutil
-import subprocess
-
-dist_ok = False
-opscli_ok = False
-
-try:
-    metadata.version("aukeys-opscli")
-    dist_ok = True
-except metadata.PackageNotFoundError:
-    pass
-
-opscli_ok = shutil.which("opscli") is not None
-if opscli_ok:
-    opscli_ok = subprocess.run(
-        ["opscli", "query", "--help"],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-    ).returncode == 0
-
-print({
-    "dist_ok": dist_ok,
-    "opscli_ok": opscli_ok,
-    "mode": "cli" if dist_ok and opscli_ok else "mcp",
-})
-PY
-```
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
 
 ---
 
@@ -229,4 +208,4 @@ auth_is_authenticated(session_id="新session_id")
 3. 对于新营销活动（< 14 天），使用宽松的阈值
 4. 在评估品牌活动时考虑有机销售提升
 5. 使用 `opscli query build`（CLI）或 `query_build_and_run`（MCP）构造 payload，而不是手写 SQL
-6. 查询前必须先完成认证门禁检查
+6. 查询前必须先完成认证门禁检查

aukeys_opscli-0.0.27/opscli/skills/templates/ops-amazon/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ops-amazon
+description: 根据当前环境自动选择 CLI 或 MCP 方式抓取 Amazon 商品页和搜索结果样本
+version: v0.1.5
+---
+
+# ops-amazon
+
+用于抓取 Amazon 商品页快照、搜索结果页样本，以及面向 ops API 和数据表设计的标准化样本数据。
+
+---
+
+## 何时使用本 Skill
+
+- 需要抓取某个 Amazon 商品的价格、评分、评论数、配送位置
+- 需要抓取关键词搜索结果做竞品样本分析
+- 需要输出未来提交给 ops API 的标准 payload
+- 需要拿真实样本给后端做字段设计、表结构设计、接口设计
+- 需要查看某个商品的本地历史抓取记录
+
+---
+
+## 运行模式判断
+
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
+
+优先级如下：
+
+1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli amazon ...` 不可用、Amazon 扩展未安装、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、Amazon 工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
+
+建议提问方式：
+
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
+
+---
+
+## 阅读入口
+
+- CLI 模式：继续阅读 `references/cli.md`
+- MCP 模式：继续阅读 `references/mcp.md`
+
+---
+
+## 使用原则
+
+- 抓取动作必须统一走选定模式下的正式入口，不要在 Skill 内直接调用 Amazon HTTP 接口
+- 认证检查仍然是强制门禁，具体门禁流程以对应 reference 文档为准
+- 若目标是后端设计，优先使用商品页快照、payload、搜索结果、schema 四类能力取样
+- 搜索结果页的 `review_count_value` 视为近似值；商品页抓取结果更适合作为精确快照值

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.27}/opscli/skills/templates/ops-asin-health-diagnoser/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ops-asin-health-diagnoser
 description: 通过使用内部运营数据计算 gross_profit_percent、convert_percent、ads_acos、refund_percent、inventory_turnaround_days 和星级的综合分数来诊断 Amazon ASIN 运行状况。支持 CLI 模式和 MCP 模式。在评估产品性能、识别表现不佳的 ASIN、确定运营干预的优先顺序或准备每周审核报告时使用。
-version: v0.1.0
+version: v0.1.1
 ---
 
 # ASIN 健康诊断器
@@ -22,48 +22,27 @@ version: v0.1.0
 
 ## 运行模式判断
 
-进入本 Skill 后，先判断当前环境使用哪种模式。
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
 
 优先级如下：
 
 1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
-2. 否则先检测是否安装了 `aukeys-opscli` Python 发行包
-3. 再检测 `opscli` 命令是否可执行
-4. 如果以上检测通过，读取 `references/cli.md`
-5. 如果任一检测失败，读取 `references/mcp.md`
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli query ...` 不可用、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、查询工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
 
-推荐检测脚本：
+建议提问方式：
 
-```bash
-python - <<'PY'
-from importlib import metadata
-import shutil
-import subprocess
-
-dist_ok = False
-opscli_ok = False
-
-try:
-    metadata.version("aukeys-opscli")
-    dist_ok = True
-except metadata.PackageNotFoundError:
-    pass
-
-opscli_ok = shutil.which("opscli") is not None
-if opscli_ok:
-    opscli_ok = subprocess.run(
-        ["opscli", "query", "--help"],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-    ).returncode == 0
-
-print({
-    "dist_ok": dist_ok,
-    "opscli_ok": opscli_ok,
-    "mode": "cli" if dist_ok and opscli_ok else "mcp",
-})
-PY
-```
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
 
 ---
 
@@ -228,4 +207,4 @@ auth_is_authenticated(session_id="新session_id")
 3. 对于新产品（< 30 天），使用宽松的阈值
 4. 标记具有多个关键指标的任何 ASIN，以便立即引起注意
 5. 使用 `opscli query build`（CLI）或 `query_build_and_run`（MCP）构造 payload，而不是手写 SQL
-6. 查询前必须先完成认证门禁检查
+6. 查询前必须先完成认证门禁检查

aukeys_opscli-0.0.27/opscli/skills/templates/ops-auth/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: ops-auth
+description: 根据当前环境自动选择 CLI 或 MCP 方式处理 Aukeys 内部系统认证与 Token 管理
+version: v1.0.2
+---
+
+# ops-auth
+
+用于管理 Aukeys 内部系统的 OAuth2 登录授权、JWT Token、系统列表和认证诊断。
+
+---
+
+## 何时使用本 Skill
+
+- 需要通过 Device Flow 完成首次登录授权
+- 需要获取、校验、刷新各系统的 JWT
+- 遇到 401、未登录、Token 过期等认证报错
+- 需要查看、添加、同步、移除已注册系统
+- 需要在脚本或其他 Skill 前置环节确认认证状态
+
+---
+
+## 运行模式判断
+
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
+
+优先级如下：
+
+1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli auth ...` 不可用、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、认证工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
+
+建议提问方式：
+
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
+
+---
+
+## 阅读入口
+
+- CLI 模式：继续阅读 `references/cli.md`
+- MCP 模式：继续阅读 `references/mcp.md`
+
+---
+
+## 使用原则
+
+- 认证动作必须统一走选定模式下的正式入口，不要绕过 Skill 直接拼接鉴权请求
+- `ops-auth` 是 `ops-amazon`、`ops-dataset-query` 等 Skill 的前置依赖，出现认证异常时应优先回到本 Skill
+- 认证检查、Token 刷新、系统同步和诊断流程都以对应 reference 文档为准

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.27}/opscli/skills/templates/ops-competitive-intelligence-analyst/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ops-competitive-intelligence-analyst
 description: 融合内部品类销售集中度、爬虫竞品数据、品牌搜索分析，应用波特五力 + 定位图 + 四行动框架，输出品类级竞争情报看板与策略建议。支持 CLI 模式和 MCP 模式。
-version: v0.1.0
+version: v0.1.1
 ---
 
 # 竞争情报分析师
@@ -22,48 +22,27 @@ version: v0.1.0
 
 ## 运行模式判断
 
-进入本 Skill 后，先判断当前环境使用哪种模式。
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
 
 优先级如下：
 
 1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
-2. 否则先检测是否安装了 `aukeys-opscli` Python 发行包
-3. 再检测 `opscli` 命令是否可执行
-4. 如果以上检测通过，读取 `references/cli.md`
-5. 如果任一检测失败，读取 `references/mcp.md`
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli query ...` 不可用、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、查询工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
 
-推荐检测脚本：
+建议提问方式：
 
-```bash
-python - <<'PY'
-from importlib import metadata
-import shutil
-import subprocess
-
-dist_ok = False
-opscli_ok = False
-
-try:
-    metadata.version("aukeys-opscli")
-    dist_ok = True
-except metadata.PackageNotFoundError:
-    pass
-
-opscli_ok = shutil.which("opscli") is not None
-if opscli_ok:
-    opscli_ok = subprocess.run(
-        ["opscli", "query", "--help"],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-    ).returncode == 0
-
-print({
-    "dist_ok": dist_ok,
-    "opscli_ok": opscli_ok,
-    "mode": "cli" if dist_ok and opscli_ok else "mcp",
-})
-PY
-```
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
 
 ---
 

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.27}/opscli/skills/templates/ops-cross-border-product-selector/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ops-cross-border-product-selector
 description: 整合内部销售数据、爬虫 Listing 数据、库存周转数据，应用 BSR 健康度筛选 + 四象限分类 + 众筹信号挖掘，构建数据驱动的新品开发决策系统。支持 CLI 模式和 MCP 模式。
-version: v0.1.0
+version: v0.1.1
 ---
 
 # 跨境选品决策助手
@@ -21,48 +21,27 @@ version: v0.1.0
 
 ## 运行模式判断
 
-进入本 Skill 后，先判断当前环境使用哪种模式。
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
 
 优先级如下：
 
 1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
-2. 否则先检测是否安装了 `aukeys-opscli` Python 发行包
-3. 再检测 `opscli` 命令是否可执行
-4. 如果以上检测通过，读取 `references/cli.md`
-5. 如果任一检测失败，读取 `references/mcp.md`
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli query ...` 不可用、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、查询工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
 
-推荐检测脚本：
+建议提问方式：
 
-```bash
-python - <<'PY'
-from importlib import metadata
-import shutil
-import subprocess
-
-dist_ok = False
-opscli_ok = False
-
-try:
-    metadata.version("aukeys-opscli")
-    dist_ok = True
-except metadata.PackageNotFoundError:
-    pass
-
-opscli_ok = shutil.which("opscli") is not None
-if opscli_ok:
-    opscli_ok = subprocess.run(
-        ["opscli", "query", "--help"],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-    ).returncode == 0
-
-print({
-    "dist_ok": dist_ok,
-    "opscli_ok": opscli_ok,
-    "mode": "cli" if dist_ok and opscli_ok else "mcp",
-})
-PY
-```
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
 
 ---
 

aukeys_opscli-0.0.27/opscli/skills/templates/ops-dataset-query/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: ops-dataset-query
+description: 根据当前环境自动选择 CLI 或 MCP 方式查询本地数据集索引并执行数据查询
+version: v0.0.5
+---
+
+# ops-dataset-query
+
+用于检索本地缓存的数据集、字段和查询元数据，并通过正式查询入口执行数据查询、图表查询和数据更新。
+
+---
+
+## 何时使用本 Skill
+
+- 需要搜索可用数据集、维度、指标和字段别名
+- 需要构造常见聚合查询或高级 payload
+- 需要执行 `dataComparison`、`MOY`、`ACC`、`PPT` 等复杂查询
+- 需要通过图表 ID 或 chart UUID 直接获取查询结构
+- 需要刷新本地缓存的数据集索引和查询元数据
+
+---
+
+## 运行模式判断
+
+进入本 Skill 后，不要为模式判断额外运行检测脚本，直接按下面规则判断。
+
+优先级如下：
+
+1. 如果用户明确要求使用 CLI 或 MCP，直接遵循用户指定
+2. 如果当前就在 `opscli` 项目、本地终端可直接执行正式命令，默认使用 CLI，并读取 `references/cli.md`
+3. 如果当前任务本身就是基于 MCP Tool 协作，或明显无法直接走本地 CLI，再读取 `references/mcp.md`
+4. 如果一开始按 CLI 执行首个正式命令就失败（例如 `opscli query ...` 不可用、当前宿主不适合跑本地命令），直接切换到 MCP 版本，并读取 `references/mcp.md`
+5. 如果 MCP 版本也不可用（例如当前没有可用 MCP 服务、查询工具未注册、调用宿主不支持 MCP），再回退为帮助用户安装 `aukeys-opscli`
+
+建议提问方式：
+
+- `当前 CLI 与 MCP 入口都不可用。你希望我先帮你安装 aukeys-opscli，再继续处理吗？`
+
+简化原则：
+
+- 默认优先 CLI，因为它是 `opscli` 模块的正式入口，最贴近真实交付路径
+- 不单独检查发行包、命令路径、子命令 help；用“首次正式调用是否可执行”作为唯一验证
+- 一旦 CLI 和 MCP 都可行，优先保持单一路径，不要来回切换
+- CLI 首次正式调用失败后，直接切到 MCP，不额外询问
+- 只有在 MCP 版本也不可用时，才回退为帮助用户安装 `aukeys-opscli`
+
+---
+
+## 阅读入口
+
+- CLI 模式：继续阅读 `references/cli.md`
+- MCP 模式：继续阅读 `references/mcp.md`
+- 无论哪种模式，遇到复杂查询都必须同步参考 `references/data-query-service-dev-guide.md`
+
+---
+
+## 使用原则
+
+- 所有远端查询动作必须统一走选定模式下的正式查询入口，禁止直接调用后端 HTTP 接口
+- 认证检查仍然是强制门禁，具体流程以对应 reference 文档为准
+- 查询前优先检查目标 `dataset_alias`、`field_name`、`global_alias`、`verbose_name` 是否存在于本地索引或 metadata；不要先猜字段再直接构造 payload
+- 如果字段或数据集不存在，优先执行当前模式下的 Skill 升级，再重新检查一次
+- CLI 模式使用 `opscli skills upgrade ops-dataset-query`；MCP 模式使用 `skills_upgrade(name="ops-dataset-query")`
+- 升级后若字段仍不存在，应明确告知用户当前本地索引和 metadata 中没有该字段，不要伪造字段名继续查询
+- 字段搜索、payload 构造、图表查询、数据更新都以对应模式文档和 `references/data-query-service-dev-guide.md` 为准
+- 涉及环比、同比、趋势对比时，优先使用服务端能力，不要默认降级为多次查询后本地拼接
+- 处理 chart 查询时，优先采用服务端返回的 `datasets + queries` 双层结构：`datasets` 负责公共字段语义，`queries` 负责执行结构；本地 CSV 仅作字段映射兜底

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

@@ -1,7 +1,7 @@
 ---
 name: ops-dataset-query
 description: 使用本地缓存的数据集与字段索引辅助检索和查询
-version: v0.0.2
+version: v0.0.3
 ---
 
 # ops-dataset-query
@@ -50,13 +50,51 @@ opscli auth token status
 
 - 本 Skill 只负责本地字段搜索、缓存读取和辅助构造查询参数
 - 所有远端查询动作必须通过 `opscli query` 执行，**禁止直接调用后端 HTTP 接口**
-- 本地数据过期时，先执行 `opscli skills upgrade ops-dataset-query` 再重试查询
+- 本地数据过期或字段不存在时，先执行 `opscli skills upgrade ops-dataset-query` 再重试查询
 - 字段搜索结果已按相关性排序（精确匹配 > 子串匹配 > 关键词匹配）
 - `opscli query build` 适合常见聚合查询（select / groupBy / where / having / orderBy / limit / offset / dryRun）
 - `opscli query run` 适合透传完整高级 payload（`innerWhere`、`joins`、`dataComparison`、`translate` 等复杂场景）
 - `opscli query chart` 适合通过图表 ID 直接获取查询结构并执行，支持多 query 自动合并
 - 所有查询工作流都必须以前置的 `ops-auth` 登录检测作为起点
 
+---
+
+## 【强制】字段存在性检查
+
+> 在 CLI 模式下，构造任何 query 参数前，必须先确认目标数据集和字段真实存在；字段不存在时，优先升级本地 Skill 数据，再重新检查。
+
+标准顺序：
+
+1. 先确认目标 `dataset_alias` 是否存在于 `data/datasets.csv`
+2. 再确认目标字段是否存在于 `data/dataset_fields.csv`
+3. 如需进一步确认公式字段、聚合方式、表达式结构，再执行 `opscli query metadata --dataset <dataset_alias> --pretty`
+4. 如果数据集或字段不存在，立即执行 `opscli skills upgrade ops-dataset-query`
+5. 升级后重新执行字段检查
+6. 若升级后仍不存在，明确告知用户当前本地索引和 metadata 中没有该字段，不要猜字段名继续查
+
+推荐检查方式：
+
+```bash
+# 1. 先确认数据集
+python scripts/search.py sales_order_d -n 20
+
+# 2. 在指定数据集内确认字段
+python scripts/search.py order_cost --dataset sales_order_d -n 20
+
+# 3. 再看完整 metadata
+opscli query metadata --dataset sales_order_d --pretty
+
+# 4. 字段不存在时先升级
+opscli skills upgrade ops-dataset-query
+```
+
+判断原则：
+
+- `dataset_fields.csv` 里找不到目标字段时，不要直接写 payload
+- 优先接受这几类命中：`field_name`、`global_alias`、`verbose_name`
+- 公式字段必须额外看 metadata，不能只看 CSV 名称就推断表达式
+- `query_metadata` 与本地 CSV 同时都缺失时，才可判定当前 Skill 数据未覆盖或字段确实不可用
+
 ### 【强制】比较类查询优先级规则
 
 > 涉及环比、同比、趋势对比等场景时，**必须按以下优先级选择方案，禁止跳过高优先级直接多次调用 CLI 后在客户端合并结果**。

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

@@ -1,6 +1,6 @@
 ---
 name: ops-dataset-query
-mcp-version: v1.0.0
+mcp-version: v1.0.1
 description: 使用 MCP Tool 查询本地缓存的数据集与字段索引，执行数据查询（无状态模式）
 ---
 
@@ -79,13 +79,52 @@ auth_is_authenticated(session_id="新session_id")
 
 - 本 Skill 只负责本地字段搜索、缓存读取和辅助构造查询参数
 - 所有远端查询动作必须通过 MCP Tool 执行，**禁止直接调用后端 HTTP 接口**
-- 本地数据过期时，先执行 `skills_upgrade(name="ops-dataset-query")` 再重试查询
+- 本地数据过期或字段不存在时，先执行 `skills_upgrade(name="ops-dataset-query")` 再重试查询
 - 字段搜索结果已按相关性排序（精确匹配 > 子串匹配 > 关键词匹配）
 - `query_build` 适合常见聚合查询（select / groupBy / where / having / orderBy / limit / offset / dryRun）
 - `query_run` 适合透传完整高级 payload（`innerWhere`、`joins`、`dataComparison`、`translate` 等复杂场景）
 - `query_chart` 适合通过图表 UUID 直接获取图表结构或执行图表查询，无需手动构造 payload
 - 所有查询工作流都必须以前置的 `session_id` 有效性检测作为起点
 
+---
+
+## 【强制】字段存在性检查
+
+> 在 MCP 模式下，构造任何 query 参数前，必须先确认目标数据集和字段真实存在；字段不存在时，优先升级本地 Skill 数据，再重新检查。
+
+标准顺序：
+
+1. 先用本地索引或知识工具确认目标 `dataset_alias`
+2. 再确认目标字段是否存在于本地字段索引
+3. 如需进一步确认公式字段、聚合方式、表达式结构，再调用 `query_metadata(dataset=...)`
+4. 如果数据集或字段不存在，立即执行 `skills_upgrade(name="ops-dataset-query")`
+5. 升级后重新执行字段检查
+6. 若升级后仍不存在，明确告知用户当前本地索引和 metadata 中没有该字段，不要猜字段名继续查
+
+推荐检查方式：
+
+```python
+# 1. 先确认数据集或字段是否存在
+search(query="sales_order_d")
+search(query="order_cost")
+
+# 2. 读取详细字段信息
+fetch(id="field:sales_order_d.order_cost")
+
+# 3. 再看完整 metadata
+query_metadata(dataset="sales_order_d")
+
+# 4. 字段不存在时先升级
+skills_upgrade(name="ops-dataset-query")
+```
+
+判断原则：
+
+- `search` / `fetch` / 本地脚本结果里都找不到目标字段时，不要直接构造 payload
+- 优先接受这几类命中：`field_name`、`global_alias`、`verbose_name`
+- 公式字段必须额外看 `query_metadata`，不能只看索引名称就推断表达式
+- `query_metadata` 与本地索引同时都缺失时，才可判定当前 Skill 数据未覆盖或字段确实不可用
+
 ### 【强制】比较类查询优先级规则
 
 > 涉及环比、同比、趋势对比等场景时，**必须按以下优先级选择方案，禁止跳过高优先级直接多次调用 Tool 后在客户端合并结果**。