CommerceLens Public v0.1 技能

将此技能视为受治理的业务编排边界，用于约束的商务和电商结构化数据分析。

技能可以决定询问什么。但它绝不能决定什么是真的。

工作流程

将用户问题解读为结构化的 Public v0.1 意图。
验证意图是否在批准的提问、指标、来源、期间、范围、分组和声明边界内。
当期间、来源选择或映射授权存在实质性歧义时，请求澄清。
构建现有的受治理 AnalysisRequest。
通过 CommerceLens 应用服务调用 run_analysis(...)。
仅从确切的 AnalysisResult 引用和持久化内核授权绑定 ClaimCandidate 授权。
对每个重要的支持的公共声明调用 evaluate_claim(...)。
仅呈现公共响应投影。

支持的 Public v0.1 提问

支持的指标确切为：

revenue
orders
aov
revenue_change

支持的分析类型确切为：

单个受治理期间的收入；
单个受治理期间的订单数；
单个受治理期间的平均订单价值；以及
两个明确受治理的可比期间之间的收入变化。

分组为 NONE。

头条来源工作流为 CSV 和 XLSX。SQLite 在内核中可能仍然可用，但并非头条 Public v0.1 工作流。

结构化意图职责

宿主解释自然语言并将结构化意图传递给集成层。集成层验证已解释的意图是否安全关闭。

不要实现或依赖 Python 自然语言解析器、关键词匹配器、泛型 SQL 生成器、任意 Python 执行或 LLM 生成的分析授权。

意图只能携带最小的瞬态概念，例如问题类别、指标 ID、显式受治理期间、范围、分组、来源选择、映射选择和声明意图。

意图不得携带指标公式、计算值、证据引用、指纹、ValidatedResult 引用或 ClaimDecision 权限。

自然语言映射

自然语言解释属于 Agent。确定性运行器仅接受已解释的结构化参数。

按如下方式映射受支持的用户请求：

"Q4 2026 的收入/订单/AOV 是多少？" 映射到 question-class=single_period_metric，metric=revenue|orders|aov，result-period-role=comparison，以及明确的受治理基准/比较期间。
"收入从 Q3 2026 到 Q4 2026 如何变化？" 映射到 question-class=revenue_change，metric=revenue_change，明确的受治理基准/比较期间，以及一个描述性声明意图。
"为什么收入从 Q3 2026 到 Q4 2026 下降了？" 映射到 question-class=diagnostic_revenue_drop，metric=revenue_change，明确的受治理基准/比较期间，一个描述性声明意图，以及一个诊断性声明意图。仅当 CommerceLens 授权允许时，才能显示描述性的收入变化。根据 Public v0.1，必须拒绝诊断性解释。

如果用户未提供源文件、源类型、所需的选定 XLSX 工作表或明确的受治理期间，请要求澄清。不得近似处理不支持的请求。

模式映射用户体验

在源文件可用后，在运行实质性分析之前检查源标头。

如果所请求的支持分析所需的所有规范字段都作为确切的规范列名可用，则继续执行，无需要求映射确认。精确的恒等映射已在 CommerceLens 规范合同下明确。

如果确切的规范字段缺失但语义兼容的源标头看似可用，则提出一个源到规范的映射，并要求用户确认或更正。该提议不是授权。在用户明确确认或提供映射之前，不得运行实质性分析。

用户可以确认所有提议的映射、更正一个或多个映射、拒绝映射或提供缺失的映射。如果仍然存在歧义，请提出有针对性的澄清，例如哪个源列代表 line_revenue。不要从沉默中推断确认。

确认后，将结构化的源到规范映射交给运行器，其中源标头作为键，规范字段作为值。运行器将其转换为现有的 CanonicalMapping 合同，并且 CommerceLens 的确定性授权仍然会在分析前使用 validate_mapping(...) 对其进行验证。

当所需的映射授权未解决、被拒绝、存在歧义或未被确定性验证通过时，安全关闭。切勿回退到 LLM 计算、静默重命名、猜测映射或泛型 DataFrame 分析。

确定性运行器

使用 skills/commerce-lens/scripts/run_public_analysis.py 作为首次运行的命令界面。它将结构化参数转换为：

PublicAnalysisIntent
PublicSourceSelection
run_public_analysis(...)

当未提供时，运行器会自动创建临时 ArtifactStore 和 MetadataStore 位置。这些是实现细节；用户无需构造它们。

示例：

python3.11 skills/commerce-lens/scripts/run_public_analysis.py \
  --source examples/public_v0_1/orders.csv \
  --source-type csv \
  --question-class revenue_change \
  --metric revenue_change \
  --baseline-label "Q3 2026" \
  --baseline-start 2026-07-01 \
  --baseline-end 2026-09-30 \
  --comparison-label "Q4 2026" \
  --comparison-start 2026-10-01 \
  --comparison-end 2026-12-31 \
  --original-question "收入从 Q3 2026 到 Q4 2026 如何变化？"

已确认的非规范映射示例：

python3.11 skills/commerce-lens/scripts/run_public_analysis.py \
  --source path/to/orders.csv \
  --source-type csv \
  --question-class revenue_change \
  --metric revenue_change \
  --baseline-label "Q3 2026" \
  --baseline-start 2026-07-01 \
  --baseline-end 2026-09-30 \
  --comparison-label "Q4 2026" \
  --comparison-start 2026-10-01 \
  --comparison-end 2026-12-31 \
  --mapping-json '{"Order ID":"order_id","Order Line ID":"order_line_id","Order Date":"order_date","Product ID":"product_id","Quantity":"quantity","Revenue":"line_revenue","Currency":"currency","Order Status":"eligibility_status"}'

首次使用时，请验证 Python >= 3.11。如果无法导入 CommerceLens，请创建一个隔离环境，安装本地包，并从该环境调用运行器：

python3.11 -m venv .venv-commerce-lens-skill
.venv-commerce-lens-skill/bin/python -m pip install --upgrade pip
.venv-commerce-lens-skill/bin/python -m pip install -e "."
.venv-commerce-lens-skill/bin/python skills/commerce-lens/scripts/run_public_analysis.py ...

不要隐藏引导失败。如果无法安装 Python >= 3.11 或包依赖项，请报告安装/运行时失败。切勿让 LLM 自行计算实质性指标来作为回应。

证据和声明授权

未经确定性 CommerceLens 引擎的可追溯证据，不得呈现任何实质性声明。

实质性指标值必须来自确定性运行器。技能不得计算收入、订单数、AOV、收入变化或任何衍生值。

诊断性、因果性、预测性和规范性声明在 Public v0.1 下保持安全关闭。不得近似处理不支持的请求。

对于诸如 "为什么收入从 Q3 2026 到 Q4 2026 下降了？" 之类的问题，请将受支持的描述性收入变化主张与不受支持的诊断性主张分开。描述性部分可以通过 run_analysis(...) 和 evaluate_claim(...) 进行。诊断性部分必须仅作为不支持的声明意图提交，并且如果 ClaimDecision 不可接受，则应呈现为被拒绝。

在适用的情况下，使用此精确的有界拒绝：

没有足够的证据来得出结论，说明收入为何下降。

不要列出推测性原因。

响应渲染

仅在权威的 ClaimDecision 允许的情况下，才渲染受支持的实质性声明。

保持指标状态、声明状态和公共支持处置清晰区分。订单数为零时的 AOV 是 MetricState UNDEFINED，值为 None，undefined_reason 为 orders_equals_zero；这不是数值零。

公共响应可以包括受支持的声明/答案、证据摘要、指标状态、声明状态、限制、不支持结论、额外证据需求、需要澄清以及被阻止/证据不足。

不要在响应中创建新的指标值、公式、证据、验证结果、发现、替代解释或建议。

CommerceLens 商业分析技能