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

{aukeys_opscli-0.0.24 → aukeys_opscli-0.0.26}/CLAUDE.md

@@ -432,6 +432,85 @@ with self._thread_lock:
 - ❌ 公开方法缺少 docstring
 - ❌ 复杂逻辑只靠变量名自说明，不加任何注释
 
+### 【铁律18】代码修改后必须更新变更记录文件
+
+每次通过 Edit/Write 工具修改代码文件后，**必须立即**将改动记录追加到 `/Users/mask/python3/opscli/docs/change-log-pending.md`。
+
+**格式要求**：
+
+```markdown
+## YYYY-MM-DD 模块名 - 简短标题
+
+**变更原因**：为什么要改（1-2 句话）
+**改动点**：改了哪些文件/模块，具体改了什么
+**验证结果**：如何验证（测试命令/脚本运行结果）
+**影响范围**：哪些功能受影响
+**回滚方式**：如何回滚
+---
+```
+
+**禁止行为**：
+- ❌ 修改代码后不写变更记录
+- ❌ 只写"改了什么"不写"为什么"
+- ❌ 变更记录缺少验证结果或回滚方式
+
+### 【铁律19】编码前先思考，不假设、不掩盖困惑
+
+在动手写代码之前，必须先完成以下检查：
+
+- **显式声明假设**：对任何不确定的假设必须明确写出。如果不确定，先问用户
+- **多方案时要列出**：如果存在多种理解或实现方式，必须全部列出让用户选择，禁止静默取一种
+- **更简方案优先**：如果存在更简单的方案，必须主动提出。有理有据地反驳不合理的需求
+- **有疑问就停下**：如果某个需求不清楚或令人困惑，立即停下来命名困惑点并提问，禁止猜测
+
+**权衡**：这条铁律偏向谨慎而非速度。对于真正零歧义的小任务，可以适当简化。
+
+### 【铁律20】极简优先，只写解决问题所需的最少代码
+
+- **禁止超范围功能**：不实现用户没有要求的功能
+- **禁止单次抽象**：如果代码只使用一次，不做抽象
+- **禁止未请求的灵活性和可配置性**：不加用户没要求的参数、配置项或钩子
+- **禁止不可能场景的错误处理**：不为逻辑上不可能发生的场景写防御代码
+- **200 行能写 50 行的必须重写**：如果代码膨胀，问自己"资深工程师会认为这段代码过度复杂吗？"如果会，精简
+
+### 【铁律21】精确变更，只改必须改的
+
+编辑现有代码时：
+
+- **不美化邻里代码**：不改adjacent代码的注释、格式或风格
+- **不改不坏的东西**：不重构正常运行的代码
+- **匹配现有风格**：即使自己会用不同风格，也必须匹配已有代码风格
+- **发现无关死代码只报告不删除**：如果注意到无关的死代码，在注释中提及或口头上报告，不主动删除
+
+当你的修改产生了孤立代码：
+
+- **必须清理自己制造的孤儿**：删除因你的修改而变为未使用的 import、变量、函数
+- **不删预存的死代码**：除非用户明确要求
+
+**判断标准**：每一行改动都必须能追溯到用户的明确请求。
+
+### 【铁律22】目标导向执行，定义成功标准并验证闭环
+
+将所有任务转化为可验证的目标：
+
+- "添加验证" → "为无效输入写测试，然后让测试通过"
+- "修复 Bug" → "写一个能复现该 Bug 的测试，然后让测试通过"
+- "重构 X" → "确保重构前后测试都通过"
+
+多步骤任务必须先声明简要计划：
+
+```
+1. [步骤] → 验证: [检查方式]
+2. [步骤] → 验证: [检查方式]
+3. [步骤] → 验证: [检查方式]
+```
+
+**强的验收标准**让你可以独立闭环。**弱的标准**（如"让它能跑"）则需要反复确认。
+
+---
+
+> **这些铁律有效的标志**：diff 中不必要的减少、因过度复杂导致的重写减少、澄清问题在实现之前而非犯错之后。
+
 ---
 
 ## 开发流程

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aukeys-opscli
-Version: 0.0.24
+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.24 → 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.24 → 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.26/docs/change-log-pending.md

@@ -0,0 +1,283 @@
+# 待归档变更记录
+
+## 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 环境中使用。
+
+**改动点**：
+- 新增 `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 修改即可
+
+---
+
+## 2026-04-27 opscli - 新增 ops-skills/SKILL_MCP.md
+
+**变更原因**：`ops-skills` 虽然不需要 `*_mcp.py` 脚本（核心功能本身就是 MCP Tool），但缺少 MCP 模式下的使用文档，导致 MCP Agent 无法了解 `skills_list`、`skills_install`、`skills_status`、`skills_upgrade` 四个 Tool 的参数格式和返回结构。
+
+**改动点**：
+- 新增 `opscli/skills/templates/ops-skills/SKILL_MCP.md`
+- 包含完整的 4 个 MCP Tool 参数表：
+  - `skills_list`：本地扫描，无需认证
+  - `skills_status`：含远端版本对比
+  - `skills_install`：纯本地模板安装
+  - `skills_upgrade`：仅支持 `ops-dataset-query` 远端升级
+- 提供典型工作流（全新环境初始化、日常版本维护、指定路径安装、强制重置）
+- 明确认证说明：`skills_list`/`skills_install` 纯本地操作无需认证；`skills_status`/`skills_upgrade` 远端调用由服务器端内部处理
+
+**影响范围**：仅文档新增，不影响代码
+
+**回滚方式**：删除 SKILL_MCP.md 即可
+
+---
+
+## 2026-04-27 opscli - 新增 MCP 工具使用手册
+
+**变更原因**：CLI 命令用例手册 (`opscli命令用例手册.md`) 无法直接指导 MCP 环境下的 Tool 调用，需要一份对应的 MCP Tool 使用手册，覆盖全部 4 个模块（auth / amazon / query / skills）共 24+ 个 Tool 的参数、返回结构和示例。
+
+**改动点**：
+- 新增 `docs/guide/MCP工具使用手册.md`
+- 结构与 CLI 手册一一对应，但使用 Python 函数调用风格展示参数
+- 每个 Tool 包含：参数表、返回示例、调用示例
+- 包含认证状态速查表（哪些 Tool 需要认证、认证方式）
+- 包含 CLI → MCP Tool 的映射对照表（快速索引）
+- 覆盖 CLI 手册中所有 8 个常见组合用例的 MCP 版本
+
+**影响范围**：仅文档新增，不影响代码
+
+**回滚方式**：删除 `docs/guide/MCP工具使用手册.md` 即可
+
+---
+
+## 2026-04-29 opscli/skills - Skills 深度审查修复（16 项）
+
+**变更原因**：对已开发完成的 9 个 Skills 进行全面深度审查，发现 7 项必须修复问题 + 6 项建议修复 + 3 项可选优化，逐一修复确保代码质量和安全性。
+
+**改动点**：
+
+### 🔴 必须修复（7 项）
+1. **permission 格式错误**：5 个 reference 文件中 `"permission": ["{permission}"]` 改为 `"permission": "{permission}"`（字符串而非数组）
+   - `ops-competitive-intelligence-analyst/reference/dataset_fields_mapping.md`
+   - `ops-refund-priority-matrix/reference/dataset_fields_mapping.md`
+   - `ops-perspective-builder/reference/dataset_fields_mapping.md`
+   - `ops-profit-structure-analyzer/reference/dataset_fields_mapping.md`
+   - `ops-cross-border-product-selector/reference/dataset_fields_mapping.md`
+2. **透视模板缺失**：`build_perspective_config.py` 补充 4 个缺失模板（`ad_type_comparison`、`device_traffic`、`promotion_effectiveness`、`inventory_structure`）及对应触发词
+3. **四行动策略硬编码**：`competitive_analysis.py` 的 `analyze_four_actions()` 将硬编码的保温杯建议改为基于品类数据和定位分析动态生成
+4. **毛利润可能为负**：`analyze_cost_structure.py` 的 `gross_profit = 1.0 - total_cost` 改为 `max(0.0, min(1.0, 1.0 - total_cost))`
+5. **重复 import**：`calculate_roas_acos.py` 删除 `if __name__` 块中重复的 `from typing import Optional`
+6. **预估成本硬编码**：`product_selector.py` 的 `price * 0.35` 改为可配置参数 `DEFAULT_COST_RATIO` + 支持 `item.estimated_cost` 和 `internal_capability.cost_ratio`
+
+### 🟡 建议修复（6 项）
+7. **字段映射声明**：`ops-asin-health-diagnoser/SKILL.md` 阈值表添加 `sell_qty_days → inventory_days` 字段映射说明
+8. **参数类型标注错误**：`product_selector.py` 的 `classify_quadrant` 参数 `sentiment_score` 从 `Optional[str]` 改为 `Optional[float]`
+9. **硬编码日期**：`generate_replenishment_plan.py` 新增 `reference_date` 参数，默认 `datetime.now()`，支持测试和回测
+10. **description 混合语言**：`ops-profit-structure-analyzer` 和 `ops-refund-priority-matrix` 的 frontmatter description 改为纯英文
+11. **错误输出方向**：`calculate_health_score.py` 错误信息同时输出到 stdout 和 stderr
+12. **SKILL.md 标题风格**：统一 3 个标题为 `# 英文标题` + 中文副标题格式
+
+### 新增铁律
+13. **CLAUDE.md 新增【铁律18】**：代码修改后必须更新变更记录文件 `docs/change-log-pending.md`
+
+**验证结果**：所有 14 个脚本通过 `echo '{}' | python script.py` 基础测试，关键脚本（health_score、cost_structure、roas_acos、perspective_builder、competitive_analysis、product_selector）通过正常数据测试
+
+**影响范围**：仅影响 Skills 模板的脚本和文档，不影响 opscli 核心功能（auth/query/mcp）
+
+**回滚方式**：`git checkout -- opscli/skills/templates/ CLAUDE.md docs/change-log-pending.md`
+
+---
+
+## 2026-04-29 CLAUDE.md - 整合 Andrej Karpathy 编码行为准则为铁律19-22
+
+**变更原因**：将 https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md 中 4 条编码行为准则翻译为中文，以【铁律19~22】形式追加到项目 CLAUDE.md 的铁律章节，与项目现有铁律风格保持一致。
+
+**改动点**：
+- CLAUDE.md 新增 4 条铁律：
+  - 【铁律19】编码前先思考，不假设、不掩盖困惑（原文：Think Before Coding）
+  - 【铁律20】极简优先，只写解决问题所需的最少代码（原文：Simplicity First）
+  - 【铁律21】精确变更，只改必须改的（原文：Surgical Changes）
+  - 【铁律22】目标导向执行，定义成功标准并验证闭环（原文：Goal-Driven Execution）
+- 原则：忠于原文核心精神，中文表达贴合项目铁律风格（禁止行为列表 + 判断标准）
+
+**验证结果**：4 条铁律内容对照原文无遗漏，中文表达通顺
+
+**影响范围**：仅影响 CLAUDE.md 文档，不影响代码
+
+**回滚方式**：删除 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.24 → 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.24 → 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,
 ]