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

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

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

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

@@ -1,41 +1,5 @@
 # 待归档变更记录
 
-## 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 环境中使用。
@@ -248,36 +212,3 @@
 - 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.26 → aukeys_opscli-0.0.29}/opscli/query/services/manager.py

@@ -428,9 +428,7 @@ class QueryManager:
         md_lines.append("4. Skill 开发时，优先使用本文中的 `origin_name` 构造过滤条件，使用 `global_alias` / `query_alias` 对齐结果列名。")
         md_lines.append("")
 
-        md_lines.append("## 二、关键术语与命名约定")
-        md_lines.append("")
-        md_lines.append("### 2.1 术语说明")
+        md_lines.append("## 二、关键术语")
         md_lines.append("")
         md_lines.append("| 术语 | 含义 | 典型用途 |")
         md_lines.append("|------|------|----------|")
@@ -440,18 +438,6 @@ class QueryManager:
         md_lines.append("| `global_alias` | 字段统一全局别名 | 与图表配置、查询结果做稳定映射 |")
         md_lines.append("| `field_type` | `dimension` 或 `metric` | 决定字段角色与用法 |")
         md_lines.append("")
-        md_lines.append("### 2.2 字段命名约定")
-        md_lines.append("")
-        md_lines.append("| 别名类型 | 格式规律 | 生成方式 | 使用场景 |")
-        md_lines.append("|----------|----------|----------|----------|")
-        md_lines.append("| `query_alias` | `f_[16位16进制]`，如 `f_9064850a20e4d581` | 系统自动生成，**禁止手写** | `select.alias`、`groupBy`、`orderBy` 中引用字段 |")
-        md_lines.append("| `global_alias` | `f_[20位字母数字]`，如 `f_WfKn5Dex0mqGINtDlWx` | 系统自动生成，跨 Query 保持稳定 | 字段身份识别，与图表配置做稳定映射 |")
-        md_lines.append("| `origin_name` | `{dataset_alias}.{column_name}` | 由数据集别名 + 列名拼接 | `where.field`、`dataComparison.field` 的值 |")
-        md_lines.append("| `expr`（select） | 通常等于 `origin_name`；公式字段时为完整 SQL 表达式 | 来自图表配置 | `select.expr`，直接传入查询服务 |")
-        md_lines.append("")
-        md_lines.append("> **边界场景**：当字段的 `expr` 与 `origin_name` 不同时（即公式字段），构造 select 时必须使用 `expr` 原值，")
-        md_lines.append("> 且不得再传 `aggregation`（公式内已内置聚合逻辑）。")
-        md_lines.append("")
 
         md_lines.append("## 三、图表总览")
         md_lines.append("")
@@ -596,10 +582,8 @@ class QueryManager:
 
         md_lines.append("## 七、Query 逐条拆解")
         md_lines.append("")
-        # 建立 dataset 索引，便于为每个 query 快速找到对应的 fields 和 filterable_fields
+        # 建立 dataset 索引，便于为每个 query 快速找到对应的 fields
         dataset_field_index: dict[tuple[str, int | None, str], list[dict]] = {}
-        # dataset_filterable_index: key → frozenset of column_names，用于 7.3 节去重判断
-        dataset_filterable_index: dict[tuple[str, int | None, str], frozenset[str]] = {}
         for ds in datasets:
             if not isinstance(ds, dict):
                 continue
@@ -609,12 +593,6 @@ class QueryManager:
                 str(ds.get("dataSource") or ""),
             )
             dataset_field_index[key] = ds.get("fields") or []
-            # 将数据集级可过滤字段的 column_name 集合存入索引，供后续去重比对
-            dataset_filterable_index[key] = frozenset(
-                str(f.get("column_name") or "")
-                for f in (ds.get("filterable_fields") or [])
-                if isinstance(f, dict) and f.get("column_name")
-            )
 
         for idx, item in enumerate(chart_items, 1):
             query = item.get("query", {}) or {}
@@ -641,34 +619,14 @@ class QueryManager:
             md_lines.append("#### 7.1 输出字段映射")
             md_lines.append("")
             if select_field_mappings:
-                # 表 A：字段语义（AI 读取，4列）
-                md_lines.append("**表A — 字段语义**（用于理解字段业务含义）")
-                md_lines.append("")
-                md_lines.append("| verbose_name | field_type | aggregation | field_name |")
-                md_lines.append("|--------------|------------|-------------|------------|")
-                for mapping in select_field_mappings:
-                    md_lines.append(
-                        f"| {mapping.get('verbose_name') or '-'} | `{mapping.get('field_type') or '-'}` | "
-                        f"`{mapping.get('aggregation') or '-'}` | `{mapping.get('field_name') or '-'}` |"
-                    )
-                md_lines.append("")
-                # 表 B：字段引用（AI 构造查询，4列）
-                # expr 通常等于 origin_name，仅公式字段时不同；
-                # 当 expr != origin_name 时在 select.expr 中必须使用 expr 原值
-                md_lines.append("**表B — 字段引用**（用于构造 select / groupBy / where）")
-                md_lines.append("")
-                md_lines.append("| field_name | query_alias | origin_name | global_alias |")
-                md_lines.append("|------------|-------------|-------------|--------------|")
+                md_lines.append("| query_alias | aggregation | verbose_name | field_type | field_name | origin_name | global_alias | expr |")
+                md_lines.append("|-------------|-------------|--------------|------------|------------|-------------|--------------|------|")
                 for mapping in select_field_mappings:
-                    expr = mapping.get("query_expr") or ""
-                    origin = mapping.get("origin_name") or ""
-                    # 当 expr 与 origin_name 不同（公式字段）时标注差异
-                    origin_cell = f"`{origin}`" if origin else "-"
-                    if expr and expr != origin:
-                        origin_cell = f"`{origin}` ⚠️ expr=`{expr}`"
                     md_lines.append(
-                        f"| `{mapping.get('field_name') or '-'}` | `{mapping.get('query_alias') or '-'}` | "
-                        f"{origin_cell} | `{mapping.get('global_alias') or '-'}` |"
+                        f"| `{mapping.get('query_alias') or '-'}` | `{mapping.get('aggregation') or '-'}` | "
+                        f"{mapping.get('verbose_name') or '-'} | `{mapping.get('field_type') or '-'}` | "
+                        f"`{mapping.get('field_name') or '-'}` | `{mapping.get('origin_name') or '-'}` | "
+                        f"`{mapping.get('global_alias') or '-'}` | `{mapping.get('query_expr') or '-'}` |"
                     )
             else:
                 md_lines.append("当前 Query 未返回可解析的输出字段映射。")
@@ -694,28 +652,14 @@ class QueryManager:
             md_lines.append("")
             filterable = item.get("filterable_fields", []) or []
             if filterable:
-                # 比较当前 Query 的过滤字段集合与数据集级别（第五章 §5.2）是否完全相同
-                # 若相同则只引用，避免重复渲染浪费 token
-                ds_key = (dataset_alias, table_id, data_source)
-                ds_filterable_set = dataset_filterable_index.get(ds_key, frozenset())
-                query_filterable_set = frozenset(
-                    str(f.get("column_name") or "")
-                    for f in filterable
-                    if isinstance(f, dict) and f.get("column_name")
-                )
-                if query_filterable_set == ds_filterable_set and ds_filterable_set:
-                    # 与数据集级可过滤字段完全相同，直接引用第五章，不重复渲染
-                    md_lines.append(f"> 可过滤字段与数据集 `{dataset_alias}` 完全相同，见第五章 §5.2，共 {len(filterable)} 个字段。")
-                else:
-                    # 与数据集级不同（或无法比对），完整渲染本 Query 的过滤字段
-                    md_lines.append("| column_name | verbose_name | source_column_name | 建议 field 写法 |")
-                    md_lines.append("|-------------|--------------|--------------------|-----------------|")
-                    for field in filterable:
-                        column_name = field.get("column_name") or "-"
-                        verbose_name = field.get("verbose_name") or "-"
-                        source_name = field.get("source_column_name") or "-"
-                        suggested = f"{dataset_alias}.{column_name}" if dataset_alias and column_name != "-" else "-"
-                        md_lines.append(f"| `{column_name}` | {verbose_name} | `{source_name}` | `{suggested}` |")
+                md_lines.append("| column_name | verbose_name | source_column_name | 建议 field 写法 |")
+                md_lines.append("|-------------|--------------|--------------------|-----------------|")
+                for field in filterable:
+                    column_name = field.get("column_name") or "-"
+                    verbose_name = field.get("verbose_name") or "-"
+                    source_name = field.get("source_column_name") or "-"
+                    suggested = f"{dataset_alias}.{column_name}" if dataset_alias and column_name != "-" else "-"
+                    md_lines.append(f"| `{column_name}` | {verbose_name} | `{source_name}` | `{suggested}` |")
             else:
                 md_lines.append("当前数据集没有返回 `filterable_fields` 配置。")
             md_lines.append("")

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.29}/opscli/skills/commands/cli.py

@@ -60,10 +60,8 @@ def _tui_select_skills(manager: SkillsManager) -> list[str]:
     if not templates:
         raise ValueError("未找到任何内置 Skill 模板")
 
-    # 根据总数动态计算序号列宽，避免两位数以上被截断
-    idx_width = max(3, len(str(len(templates))) + 2)
     table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 1))
-    table.add_column("#", style="bold yellow", width=idx_width)
+    table.add_column("#", style="bold yellow", width=3)
     table.add_column("名称", style="green", min_width=20)
     table.add_column("版本", style="dim", width=8)
     table.add_column("说明")
@@ -93,9 +91,8 @@ def _tui_select_targets(manager: SkillsManager) -> list[tuple[str, Path]] | None
     if not targets:
         return None
 
-    idx_width = max(3, len(str(len(targets))) + 2)
     table = Table(show_header=True, header_style="bold cyan", box=None, padding=(0, 1))
-    table.add_column("#", style="bold yellow", width=idx_width)
+    table.add_column("#", style="bold yellow", width=3)
     table.add_column("工具", style="green", min_width=14)
     table.add_column("安装路径", style="dim")
     for idx, (runtime, path) in enumerate(targets, start=1):

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.29}/opscli/version.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 from importlib.metadata import PackageNotFoundError, version
 
 PACKAGE_NAME = "aukeys-opscli"
-FALLBACK_VERSION = "0.0.23-dev"
+FALLBACK_VERSION = "0.0.29-dev"
 
 
 def get_version() -> str:

aukeys_opscli-0.0.29/publish.sh

@@ -0,0 +1,272 @@
+#!/usr/bin/env bash
+# 一键升级版本号 + 构建分发包 + 上传
+# 用法：
+#   ./publish.sh patch
+#   ./publish.sh minor
+#   ./publish.sh major
+#   ./publish.sh           # 默认 patch
+#
+# 可选环境变量：
+#   AUTO_CONFIRM=1       跳过确认提示
+#   DRY_RUN=1            执行构建和校验，但不上传，并在结束后回滚版本号
+#   USE_CIBUILDWHEEL=0   强制跳过 cibuildwheel
+#   USE_CIBUILDWHEEL=1   允许在需要平台轮子时使用 cibuildwheel（默认）
+#   ENABLE_CYTHON=1      额外执行 in-place cythonize（默认关闭）
+#   PRIVATE_PYPI_URL=... 上传到私有仓库
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT_DIR"
+
+PYPROJECT="$ROOT_DIR/pyproject.toml"
+BUMP_TYPE="${1:-patch}"
+AUTO_CONFIRM="${AUTO_CONFIRM:-0}"
+DRY_RUN="${DRY_RUN:-0}"
+USE_CIBUILDWHEEL="${USE_CIBUILDWHEEL:-1}"
+ENABLE_CYTHON="${ENABLE_CYTHON:-0}"
+PRIVATE_PYPI_URL="${PRIVATE_PYPI_URL:-}"
+
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'
+BLUE='\033[0;34m'; BOLD='\033[1m'; RESET='\033[0m'
+
+info()    { echo -e "${BLUE}[INFO]${RESET} $*"; }
+success() { echo -e "${GREEN}[OK]${RESET}  $*"; }
+warn()    { echo -e "${YELLOW}[WARN]${RESET} $*"; }
+error()   { echo -e "${RED}[ERROR]${RESET} $*"; exit 1; }
+
+[[ "$BUMP_TYPE" =~ ^(patch|minor|major)$ ]] \
+    || error "参数必须是 patch / minor / major，当前：$BUMP_TYPE"
+
+detect_package_dir() {
+    local package_dir
+
+    package_dir="$(
+        awk '
+            /^\[tool\.hatch\.build\.targets\.wheel\]$/ { in_section = 1; next }
+            /^\[/ { if (in_section) exit; in_section = 0 }
+            in_section && /^packages = \[/ {
+                line = $0
+                sub(/^packages = \["/, "", line)
+                sub(/".*$/, "", line)
+                print line
+                exit
+            }
+        ' "$PYPROJECT"
+    )"
+    if [[ -n "$package_dir" && -d "$ROOT_DIR/$package_dir" ]]; then
+        printf '%s\n' "$package_dir"
+        return 0
+    fi
+
+    package_dir="$(find "$ROOT_DIR" -mindepth 2 -maxdepth 2 -type f -name "__init__.py" \
+        ! -path '*/tests/*' ! -path '*/.*/*' \
+        -exec dirname {} \; | head -n1)"
+    if [[ -n "$package_dir" ]]; then
+        basename "$package_dir"
+        return 0
+    fi
+
+    return 1
+}
+
+ensure_python_pip() {
+    if python3 -m pip --version >/dev/null 2>&1; then
+        return 0
+    fi
+
+    warn "当前 python3 缺少 pip，尝试使用 ensurepip 修复..."
+    python3 -m ensurepip --upgrade >/dev/null 2>&1 \
+        || error "当前 python3 不包含 pip/ensurepip，请切换到带 pip 的解释器后重试"
+    python3 -m pip --version >/dev/null 2>&1 \
+        || error "pip 修复失败，请检查当前 python3 环境"
+}
+
+is_pure_python_wheel() {
+    local wheel_path="$1"
+    [[ "$wheel_path" == *"-none-any.whl" ]]
+}
+
+CURRENT_VERSION="$(grep -m1 '^version = ' "$PYPROJECT" | sed 's/version = "\(.*\)"/\1/')"
+[[ -n "$CURRENT_VERSION" ]] || error "无法从 $PYPROJECT 读取 version 字段"
+IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT_VERSION"
+
+case "$BUMP_TYPE" in
+    patch) PATCH=$((PATCH + 1)) ;;
+    minor) MINOR=$((MINOR + 1)); PATCH=0 ;;
+    major) MAJOR=$((MAJOR + 1)); MINOR=0; PATCH=0 ;;
+esac
+NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}"
+NEW_FALLBACK_VERSION="${NEW_VERSION}-dev"
+
+PACKAGE_DIR="$(detect_package_dir)" || error "无法自动探测包目录，请检查 $PYPROJECT 的 wheel packages 配置"
+VERSION_FILE="$ROOT_DIR/$PACKAGE_DIR/version.py"
+
+PYPROJECT_BAK="$(mktemp)"
+VERSION_FILE_BAK=""
+ROLLBACK_REQUIRED=0
+
+cleanup_backups() {
+    rm -f "$PYPROJECT_BAK"
+    if [[ -n "$VERSION_FILE_BAK" ]]; then
+        rm -f "$VERSION_FILE_BAK"
+    fi
+}
+
+rollback_versions() {
+    if [[ "$ROLLBACK_REQUIRED" != "1" ]]; then
+        return
+    fi
+
+    cp "$PYPROJECT_BAK" "$PYPROJECT"
+    if [[ -n "$VERSION_FILE_BAK" && -f "$VERSION_FILE" ]]; then
+        cp "$VERSION_FILE_BAK" "$VERSION_FILE"
+    fi
+    warn "已回滚版本文件到发布前状态"
+}
+
+trap 'status=$?; if [[ $status -ne 0 ]]; then rollback_versions; fi; cleanup_backups' EXIT
+
+echo -e "\n${BOLD}======================================${RESET}"
+echo -e "${BOLD} 发布脚本（稳健版）${RESET}"
+echo -e "${BOLD}======================================${RESET}"
+echo -e "  包目录    ：${BLUE}${PACKAGE_DIR}${RESET}"
+echo -e "  当前版本：${YELLOW}${CURRENT_VERSION}${RESET}"
+echo -e "  新版本  ：${GREEN}${NEW_VERSION}${RESET}  (${BUMP_TYPE})"
+echo -e "  Dry Run ：${YELLOW}${DRY_RUN}${RESET}"
+echo -e "${BOLD}======================================${RESET}\n"
+
+if [[ "$AUTO_CONFIRM" != "1" ]]; then
+    read -rp "确认发布？[y/N] " CONFIRM
+    [[ "$CONFIRM" =~ ^[Yy]$ ]] || { warn "已取消"; exit 0; }
+fi
+
+info "Step 1/10 检查依赖工具..."
+command -v python3 &>/dev/null || error "未找到 python3"
+ensure_python_pip
+python3 -c "import build" 2>/dev/null || { warn "正在安装 build..."; python3 -m pip install build -q; }
+python3 -c "import twine" 2>/dev/null || { warn "正在安装 twine..."; python3 -m pip install twine -q; }
+if [[ "$ENABLE_CYTHON" == "1" ]]; then
+    python3 -c "import Cython" 2>/dev/null || { warn "正在安装 Cython..."; python3 -m pip install cython -q; }
+fi
+success "工具检查通过"
+
+info "Step 2/10 校验项目结构..."
+[[ -d "$ROOT_DIR/$PACKAGE_DIR" ]] || error "包目录不存在：$ROOT_DIR/$PACKAGE_DIR"
+if [[ -f "$VERSION_FILE" ]]; then
+    grep -q '^FALLBACK_VERSION = "' "$VERSION_FILE" \
+        || error "未在 $VERSION_FILE 找到 FALLBACK_VERSION，无法同步开发态版本"
+else
+    warn "未找到 $VERSION_FILE，发布时将只更新 pyproject.toml"
+fi
+success "项目结构校验通过"
+
+info "Step 3/10 更新版本号 → ${NEW_VERSION}..."
+cp "$PYPROJECT" "$PYPROJECT_BAK"
+if [[ -f "$VERSION_FILE" ]]; then
+    VERSION_FILE_BAK="$(mktemp)"
+    cp "$VERSION_FILE" "$VERSION_FILE_BAK"
+fi
+ROLLBACK_REQUIRED=1
+
+sed -i.bak "s/^version = \"${CURRENT_VERSION}\"/version = \"${NEW_VERSION}\"/" "$PYPROJECT"
+rm -f "${PYPROJECT}.bak"
+
+if [[ -f "$VERSION_FILE" ]]; then
+    sed -i.bak "s/^FALLBACK_VERSION = \".*\"/FALLBACK_VERSION = \"${NEW_FALLBACK_VERSION}\"/" "$VERSION_FILE"
+    rm -f "${VERSION_FILE}.bak"
+fi
+success "版本号已更新"
+
+info "Step 4/10 清理旧构建产物..."
+rm -rf dist/ build/ *.egg-info/
+success "清理完成"
+
+info "Step 5/10 处理可选 Cython 编译..."
+if [[ "$ENABLE_CYTHON" == "1" ]]; then
+    mapfile -t pyfiles < <(find "$ROOT_DIR/$PACKAGE_DIR" -type f -name "*.py" ! -name "__init__.py" | sort)
+    if [[ "${#pyfiles[@]}" -eq 0 ]]; then
+        warn "未找到可编译的 Python 源文件，跳过 Cython"
+    else
+        for pyfile in "${pyfiles[@]}"; do
+            info "  编译 ${pyfile#$ROOT_DIR/}"
+            cythonize -3 -i "$pyfile"
+        done
+        success "Cython 编译完成"
+    fi
+else
+    warn "默认跳过 Cython。当前项目使用 hatchling，in-place cythonize 不会自动变成可靠的发布产物。"
+fi
+
+info "Step 6/10 构建分发包..."
+info "  构建 sdist..."
+python3 -m build --sdist --outdir dist
+
+info "  预构建 wheel，用于判断是否为纯 Python 包..."
+python3 -m build --wheel --outdir dist
+
+shopt -s nullglob
+probe_wheels=(dist/*.whl)
+shopt -u nullglob
+[[ "${#probe_wheels[@]}" -gt 0 ]] || error "预构建 wheel 失败，dist/ 中未发现 wheel 产物"
+PROBE_WHEEL="${probe_wheels[0]}"
+
+if is_pure_python_wheel "$PROBE_WHEEL"; then
+    warn "检测到纯 Python wheel：$(basename "$PROBE_WHEEL")"
+    warn "纯 Python 包不需要 cibuildwheel，保留当前 wheel 作为发布产物"
+elif [[ "$USE_CIBUILDWHEEL" == "1" ]]; then
+    info "  检测到平台相关 wheel，切换到 cibuildwheel 生成多 Python 版本产物..."
+    python3 -c "import cibuildwheel" 2>/dev/null || { warn "正在安装 cibuildwheel..."; python3 -m pip install cibuildwheel -q; }
+    rm -f dist/*.whl
+    cibuildwheel --output-dir dist
+else
+    warn "检测到平台相关 wheel，但 USE_CIBUILDWHEEL=0；将仅发布当前解释器构建的 wheel"
+fi
+success "构建完成"
+
+info "Step 7/10 校验包（twine check）..."
+shopt -s nullglob
+artifacts=(dist/*)
+shopt -u nullglob
+[[ "${#artifacts[@]}" -gt 0 ]] || error "dist/ 目录为空，未生成任何构建产物"
+twine check "${artifacts[@]}"
+success "校验通过"
+printf '%s\n' "${artifacts[@]##$ROOT_DIR/}" | sed 's/^/    /'
+
+info "Step 8/10 上传包..."
+if [[ "$DRY_RUN" == "1" ]]; then
+    warn "DRY_RUN=1，跳过上传"
+elif [[ -n "$PRIVATE_PYPI_URL" ]]; then
+    twine upload --repository-url "$PRIVATE_PYPI_URL" "${artifacts[@]}"
+else
+    twine upload "${artifacts[@]}"
+fi
+success "上传步骤完成"
+
+info "Step 9/10 清理临时编译文件..."
+if [[ "$ENABLE_CYTHON" == "1" ]]; then
+    find "$ROOT_DIR/$PACKAGE_DIR" -type f \( -name "*.c" -o -name "*.so" -o -name "*.pyd" \) -delete
+    success "临时编译文件清理完成"
+else
+    warn "未启用 Cython，无需清理临时编译文件"
+fi
+
+if [[ "$DRY_RUN" == "1" ]]; then
+    rollback_versions
+    ROLLBACK_REQUIRED=0
+fi
+
+if [[ "$DRY_RUN" != "1" ]]; then
+    ROLLBACK_REQUIRED=0
+fi
+
+echo ""
+info "Step 10/10 完成提示："
+echo "    pip install aukeys-opscli==${NEW_VERSION}"
+echo "    opscli --version"
+echo ""
+if [[ "$DRY_RUN" == "1" ]]; then
+    success "Dry run 完成，版本文件已回滚，可直接检查 dist/ 产物"
+else
+    success "全部完成 aukeys-opscli v${NEW_VERSION} 已发布"
+fi

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.29}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aukeys-opscli"
-version = "0.0.26"
+version = "0.0.29"
 description = "Aukeys 运营 CLI 工具集"
 readme = "README.md"
 requires-python = ">=3.10"

{aukeys_opscli-0.0.26 → aukeys_opscli-0.0.29}/tests/query/test_manager.py

@@ -734,15 +734,9 @@ def test_generate_chart_doc_uses_server_field_mappings(monkeypatch):
     assert "| 订单量 | `metric` | `order_qty` | `ds_sales.order_qty` | `ga_order_qty` | `f_order_qty` | `SUM` | `select` |" in markdown
     assert "## 七、Query 逐条拆解" in markdown
     assert "#### 7.1 输出字段映射" in markdown
-    # 7.1 拆分为两张 4 列表：表A（语义）和表B（引用）
-    assert "**表A — 字段语义**" in markdown
-    assert "| 订单量 | `metric` | `SUM` | `order_qty` |" in markdown
-    assert "**表B — 字段引用**" in markdown
-    assert "| `order_qty` | `f_order_qty` | `ds_sales.order_qty` | `ga_order_qty` |" in markdown
-    # 7.2 条件字段映射格式不变
+    assert "| `f_order_qty` | `SUM` | 订单量 | `metric` | `order_qty` | `ds_sales.order_qty` | `ga_order_qty` | `ds_sales.order_qty` |" in markdown
     assert "| `where` | `ds_sales.date_id` | 日期 | `dimension` | `date_id` | `ds_sales.date_id` | `ga_date_id` |" in markdown
-    # 7.3 可过滤字段与数据集相同时改为引用第五章，不重复渲染完整表格
-    assert "可过滤字段与数据集 `ds_sales` 完全相同，见第五章 §5.2，共 1 个字段。" in markdown
+    assert "| `date_id` | 日期 | `date_id` | `ds_sales.date_id` |" in markdown
 
 
 def test_generate_chart_doc_falls_back_when_field_mappings_missing(monkeypatch):
@@ -779,10 +773,5 @@ def test_generate_chart_doc_falls_back_when_field_mappings_missing(monkeypatch):
     markdown = result["markdown"]
 
     assert "当前数据集没有返回 `filterable_fields` 配置。" in markdown
-    # 7.1 fallback 也使用新双表格式：表A 语义列，表B 引用列
-    assert "**表A — 字段语义**" in markdown
-    assert "| - | `-` | `-` | `channel_name` |" in markdown
-    assert "**表B — 字段引用**" in markdown
-    assert "| `channel_name` | `f_channel` | `ds_sales.channel_name` | `f_channel` |" in markdown
-    # 7.2 条件字段映射：fallback 时 field_name 从 origin_name 末段提取（date_id），不为 -
-    assert "| `where` | `ds_sales.date_id` | - | `-` | `date_id` | `ds_sales.date_id` | `-` |" in markdown
+    assert "| `f_channel` | `-` | - | `-` | `-` | `-` | `f_channel` | `ds_sales.channel_name` |" in markdown
+    assert "| `where` | `ds_sales.date_id` | - | `-` | `-` | `ds_sales.date_id` | `-` |" in markdown