daniel-j-lin/commerce-lens

CommerceLens 公開版 v0.1 技能

使用此技能作為針對限定的商業與電子商務結構化數據分析的受控編排邊界。

此技能可以決定要問什麼問題，但不得決定什麼是事實。

工作流程

1. 將使用者問題解讀為結構化的公開版 v0.1 意圖。
2. 驗證該意圖是否在核准的問題、指標、來源、期間、範圍、分組與聲明邊界內。
3. 當期間、來源選擇或映射權威存在重大模糊時，要求澄清。
4. 建構現有的受控 AnalysisRequest。
5. 透過 CommerceLens 應用服務呼叫 run_analysis(...)。
6. 僅從確切的 AnalysisResult 參考與持續存在的核心權威綁定 ClaimCandidate 權威。
7. 對每個具實質支持的公開聲明呼叫 evaluate_claim(...)。
8. 僅渲染公開回應投影。

支援的公開版 v0.1 問題

支援的指標完全如下：

• revenue
• orders
• aov
• revenue_change

支援的分析類別完全如下：

• 單一受控期間的營收；
• 單一受控期間的訂單數；
• 單一受控期間的平均訂單價值；以及
• 兩個明確受控可比較期間之間的營收變化。

分組為 NONE。

標題來源工作流程為 CSV 與 XLSX。SQLite 可能仍可在核心中使用，但不是標題公開版 v0.1 工作流程。

結構化意圖責任

主機端解讀自然語言並將結構化意圖傳遞給整合層。整合層驗證已解讀的意圖，並在驗證失敗時關閉。

請勿實作或依賴 Python 自然語言解析器、關鍵字匹配器、通用 SQL 生成器、任意 Python 執行或 LLM 生成的分析權威。

意圖僅能攜帶最低限度的暫態概念，例如問題類別、指標 ID、明確的受控期間、範圍、分組、來源選擇、映射選擇與聲明意圖。

意圖不得攜帶指標公式、計算值、證據參考、指紋、ValidatedResult 參考或 ClaimDecision 權限。

自然語言映射

自然語言解讀屬於代理的責任。確定性執行器僅接受已解讀的結構化引數。

將支援的使用者請求映射如下：

• "2026 年第四季的營收 / 訂單數 / 平均訂單價值是多少？" 映射到 question-class=single_period_metric、metric=revenue|orders|aov、result-period-role=comparison，以及明確的受控基準 / 比較期間。
• "營收從 2026 年第三季到第四季變化了多少？" 映射到 question-class=revenue_change、metric=revenue_change、明確的受控基準 / 比較期間，以及一個描述性的聲明意圖。
• "為什麼營收從 2026 年第三季到第四季下降了？" 映射到 question-class=diagnostic_revenue_drop、metric=revenue_change、明確的受控基準 / 比較期間、一個描述性的聲明意圖，以及一個診斷性的聲明意圖。描述性的營收變化僅在 CommerceLens 權限允許時才能顯示。診斷性解釋必須在公開版 v0.1 下被拒絕。

如果使用者尚未提供來源檔案、來源類型、所需的 XLSX 工作表或明確的受控期間，請要求澄清。不支援的請求不得近似處理。

Schema 映射使用者體驗

在來源檔案可用後，請在執行實際分析之前檢查來源的標頭。

如果請求的支援分析所需的所有標準欄位都以確切的標準欄位名稱存在，則繼續執行，無需要求映射確認。確切的身份映射已在 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 "How did revenue change from Q3 2026 to 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 確定性引擎證據，不得提出任何實質聲明。

實質指標值必須來自確定性執行器。此技能不得自行計算營收、訂單數、平均訂單價值、營收變化或任何衍生值。

診斷性、因果性、預測性與規範性聲明在公開版 v0.1 下保持關閉且失敗。不得近似處理不支援的請求。

對於諸如「為什麼營收從 2026 年第三季到第四季下降了？」這類問題，請將受支援的描述性營收變化主張與不受支援的診斷性主張分開。描述性部分可以透過 run_analysis(...) 與 evaluate_claim(...) 進行。診斷性部分必須僅作為不受支援的聲明意圖提交，並在 ClaimDecision 不允許時渲染為已拒絕。

在適用情況下使用此確切的有限拒絕訊息：

沒有足夠的證據來得出營收為何下降的結論。

請勿列出推測性原因。

回應渲染

僅在權威的 ClaimDecision 允許時，才渲染受支援的實質聲明。

保持指標狀態、聲明狀態與公開支持處置的區別。訂單數為零的平均訂單價值是 MetricState UNDEFINED、值 None 且 undefined_reason 為 orders_equals_zero；這不是數值零。

公開回應可以包含受支援的聲明 / 答案、證據摘要、指標狀態、聲明狀態、限制、不支援的結論、所需額外證據、需要澄清的內容，以及被阻擋 / 證據不足。

請勿在回應中創建新的指標值、公式、證據、驗證結果、發現、替代解釋或建議。