@thinkingai/ae-cli 6.1.27 → 6.1.29

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/execution-contract.mjs

@@ -0,0 +1,173 @@
+// Structural facts only. Business meanings and asset routes remain Agent-authored.
+const obj = value => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const list = value => Array.isArray(value) ? value : [];
+const valueOf = value => {
+  if (typeof value !== 'string') return value;
+  try { return JSON.parse(value); } catch { return value; }
+};
+const present = value => value !== undefined && value !== null && value !== '';
+const pick = (source, keys) => Object.fromEntries(keys.filter(key => present(source[key])).map(key => [key, source[key]]));
+const displayKeys = new Set(['display_name', 'eventNameDisplay', 'eventDesc', 'analysisDesc', 'quotaDesc', 'columnDesc', 'eventUuid', 'uuid']);
+
+export function semanticValue(value) {
+  if (Array.isArray(value)) return value.map(semanticValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).filter(key => !displayKeys.has(key)).sort()
+    .map(key => [key, semanticValue(value[key])]));
+}
+
+export function semanticTime(value) {
+  const time = { ...obj(value) };
+  if (present(time.recentDay ?? time.recent_day)) {
+    for (const key of ['startTime', 'endTime', 'start_time', 'end_time']) delete time[key];
+  }
+  return time;
+}
+
+export function logicalRelation(value) {
+  const relation = String(value ?? '').toLowerCase();
+  return ({ '1': 'AND', '0': 'OR', and: 'AND', or: 'OR' })[relation] || `UNKNOWN(${relation || 'unspecified'})`;
+}
+
+export function conditionTree(value, relation) {
+  if (Array.isArray(value)) return { relation: logicalRelation(relation), items: value.map(item => conditionTree(item)) };
+  const source = obj(value);
+  const nested = source.filts ?? source.items ?? source.filters;
+  if (nested != null) {
+    if (!Array.isArray(nested)) return { unknown: true, raw: source };
+    return { relation: logicalRelation(source.relation ?? source.junctionKind ?? relation), items: nested.map(item => conditionTree(item)) };
+  }
+  if (!Object.keys(source).length) return { unknown: true };
+  return { predicate: source };
+}
+
+export function renderConditionTree(value, leaf) {
+  if (value.predicate) return leaf(value.predicate);
+  if (value.unknown) return 'Unknown predicate; verify the source definition';
+  if (!value.items.length) return 'No conditions in this scope';
+  if (value.items.length === 1) return renderConditionTree(value.items[0], leaf);
+  return `(${value.items.map(item => renderConditionTree(item, leaf)).join(` ${value.relation} `)})`;
+}
+
+export function metricContract(item) {
+  const formula = obj(item.formula_definition ?? item.formula);
+  return {
+    ...pick(item, ['event_name', 'aggregation_code', 'measure_key', 'formula_expression', 'entity_grain', 'aggregation_parameters', 'time_scope']),
+    filters: item.filters == null ? null : conditionTree(item.filters, item.relation),
+    operand_filters: list(item.custom_filters).map(filter => ({ index: filter.index, tree: conditionTree(filter, filter.relation) })),
+    operands: list(formula.formulationDeps).map((dependency, index) => ({ index,
+      ...pick(obj(dependency), ['event', 'quota', 'property', 'date', 'timeRange', 'time_scope', 'quotaTimeRange']),
+    })),
+    operand_time_ranges: item.quota_time_ranges ?? item.quotaTimeRanges ?? null,
+  };
+}
+
+export const modelConfigKeys = [
+  'windowsGapValue', 'windowsGapUnit', 'percentConfig', 'userCrowds', 'retentionType',
+  'rtnRateOrNum', 'statType', 'retentionCollectSet', 'relationProps', 'relationPropSplit',
+  'unitNum', 'eventModel', 'taIdMeasureVo',
+];
+const timeKeys = ['recentDay', 'startTime', 'endTime', 'startToNow', 'startToYesterday',
+  'timeParticleSize', 'firstDayOfWeek', 'zoneOffset', 'timezone', 'completeIncompletePeriod', 'hideIncompleteData'];
+const interpretedViewKeys = new Set([...timeKeys, ...modelConfigKeys, 'filts', 'groupBy', 'group_by',
+  'relation', 'sqlViewParams', 'graphShape', 'projectId', 'displayQuotas', 'displayGroups']);
+
+export function reportContract(report, context = report.calculation_context || {}) {
+  const view = obj(valueOf(context.event_view));
+  const savedParameters = context.saved_parameters ?? view.sqlViewParams ?? null;
+  const parameters = list(context.sql_params ?? context.parameters).map(parameter => ({ ...parameter,
+    name: parameter.name ?? parameter.paramName,
+  }));
+  return {
+    model: report.report_model,
+    groups: context.group_by ?? view.groupBy ?? view.group_by ?? [],
+    time: semanticTime({ ...pick(view, timeKeys), ...obj(context.time_scope) }),
+    filters: conditionTree(context.filters ?? view.filts ?? [], context.relation ?? view.relation),
+    metrics: list(report.metric_occurrences).map(metricContract),
+    model_config: { ...pick(view, modelConfigKeys), ...obj(context.model_config) },
+    unparsed_model_config: Object.fromEntries(Object.entries(view).filter(([key]) => !interpretedViewKeys.has(key))),
+    model_events: list(valueOf(context.source_events)).map(event => pick(obj(event), ['eventName', 'type', 'filts', 'relation', 'analysis', 'analysisParams', 'quota', 'quotaEntities'])),
+    parameters,
+    saved_parameters: Array.isArray(savedParameters) ? savedParameters.map(parameter => Object.keys(obj(parameter)).length ? semanticTime(parameter) : parameter) : savedParameters,
+    sql_projections: report.definition_kind === 'SQL' ? list(obj(context.sql_semantic_facts).final_select?.fields) : [],
+  };
+}
+
+export function reportSignature(report, context = report.calculation_context || {}, includeSavedSettings = true) {
+  const contract = reportContract(report, context);
+  contract.time = semanticTime(contract.time);
+  if (!includeSavedSettings) contract.unparsed_model_config = {};
+  if (report.definition_kind === 'SQL') {
+    const definitions = contract.parameters.map(parameter => pick(parameter, ['name', 'paramType', 'type', 'options', 'selectorItems', 'required', 'useTimezone', 'use_timezone']));
+    return JSON.stringify(semanticValue({ sql: String(context.sql || '').replace(/\r\n?/g, '\n').trim(),
+      parameters: definitions, ...(includeSavedSettings ? { saved_parameters: contract.saved_parameters, time: contract.time } : {}) }));
+  }
+  return JSON.stringify(semanticValue(contract));
+}
+
+export function enrichMetricEvidence(metrics, context) {
+  const source = list(valueOf(context.source_events));
+  return metrics.map((metric, index) => {
+    const raw = obj(source[index]);
+    if (source.length !== metrics.length || raw.eventName !== metric.event_name || String(raw.analysis ?? '') !== String(metric.aggregation_code ?? '')) return metric;
+    return { ...metric,
+      ...(raw.analysisParams != null ? { aggregation_parameters: raw.analysisParams } : {}),
+      ...(raw.quotaEntities != null ? { entity_grain: raw.quotaEntities } : {}),
+      ...(raw.quotaTimeRanges != null ? { quota_time_ranges: raw.quotaTimeRanges } : {}),
+    };
+  });
+}
+
+const inline = value => `\`${JSON.stringify(value).replaceAll('`', '\\`').replaceAll('\n', ' ')}\``;
+
+export function renderExecutionContract(contract) {
+  const rows = [
+    '- These are saved definition settings. Execution overrides and inherited dashboard settings require live verification.',
+    '- Saved result grouping is listed below. SQL output grain and inherited settings require the asset explanation; referenced metadata is not a saved group.',
+    ...contract.groups.map((group, index) => `- Group ${index + 1}: ${inline(group)}`),
+    `- Saved population filter structure: ${inline(contract.filters)}`,
+    `- Saved time settings: ${Object.keys(contract.time).length ? inline(contract.time) : 'unknown; verify the current definition'}`,
+    '- State timing: a historical behavior window does not establish historical values for user or dimension tables. Source refresh times and historical reconstruction require source evidence.',
+    '- Empty/missing rows, null, empty arrays, false and zero are distinct. Do not fill missing rows with zero without coverage evidence.',
+  ];
+  if (contract.groups.some(group => /array/i.test(JSON.stringify(group)))) rows.push('- Array grouping can expand an entity into several rows. Distinct counts, ratios and percentiles are not additive across those rows.');
+  if (Object.keys(contract.model_config).length) rows.push(`- Model-specific settings: ${inline(contract.model_config)}`);
+  if (Object.keys(contract.unparsed_model_config).length) rows.push(`- Uninterpreted saved configuration; semantic support is unknown: ${inline(contract.unparsed_model_config)}`);
+  if ((contract.model_config.windowsGapValue != null || list(contract.model_config.userCrowds).length) && contract.model_events.length) rows.push(`- Model event roles and measures: ${inline(contract.model_events)}`);
+  if (contract.parameters.length) rows.push(`- Parameter definitions: ${inline(contract.parameters)}`);
+  if (contract.saved_parameters != null) rows.push(`- Saved parameter choices (separate from definitions and call-time overrides): ${inline(contract.saved_parameters)}`);
+  if (contract.sql_projections.length) {
+    const projections = contract.sql_projections.filter(field => !/\$\{/.test(field.expression || ''));
+    rows.push(`- SQL outer projection evidence: ${inline(projections)}`);
+    rows.push('- SQL lineage completeness: unknown for nested scopes, CTEs, wildcard fields and dynamic expressions. Output names alone do not prove source meanings; verify unresolved columns.');
+  }
+  for (const [index, metric] of contract.metrics.entries()) {
+    if (metric.operands.length || metric.operand_filters.length || metric.aggregation_parameters != null || metric.entity_grain != null) {
+      rows.push(`- Measure ${index + 1} calculation scopes: ${inline(metric)}`);
+    }
+  }
+  return `\n\n## Execution contract\n\n${rows.join('\n')}\n`;
+}
+
+export function validateSqlExplanations(summary, sql) {
+  const normalize = value => String(value).replace(/\s+/g, ' ').trim();
+  for (const key of ['calculation_rules', 'time_semantics', 'coverage_gaps']) {
+    if (summary[key] == null) continue;
+    if (!Array.isArray(summary[key])) throw new Error(`${key} must be an array.`);
+    for (const item of summary[key]) {
+      if (!item?.meaning || !item?.evidence || !normalize(sql).includes(normalize(item.evidence))) {
+        throw new Error(`${key} requires a meaning and exact SQL evidence from the current definition.`);
+      }
+    }
+  }
+  for (const field of list(summary.output_fields)) {
+    if (field.evidence != null && !normalize(sql).includes(normalize(field.evidence))) {
+      throw new Error('Output field lineage evidence must occur in the current SQL.');
+    }
+  }
+}
+
+export function renderSqlExplanations(summary) {
+  return ['calculation_rules', 'time_semantics', 'coverage_gaps'].flatMap(key => list(summary?.[key])
+    .map(item => `- ${key}: ${item.meaning} (evidence: ${inline(item.evidence)})`)).join('\n');
+}

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/generate-build-ir.mjs

@@ -3,6 +3,9 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { conditionTree, renderConditionTree, reportContract, reportSignature,
+  semanticValue, enrichMetricEvidence, renderExecutionContract, validateSqlExplanations,
+  renderSqlExplanations } from './execution-contract.mjs';
 
 const args = parseArgs(process.argv.slice(2));
 const packageRoot = path.resolve(requiredArg(args, 'asset-package'));
@@ -99,13 +102,19 @@ const sqlReportSemanticsById = new Map(array(domainPlan.sql_report_semantics)
   .map((value) => object(value))
   .map((value) => [text(value.report_id), value])
   .filter(([id]) => id));
+for (const report of reports) {
+  report.calculation_context = calculationContextForKb(report);
+  report.metric_occurrences = enrichMetricEvidence(array(report.metric_occurrences), report.calculation_context);
+}
 const semanticConflicts = detectSemanticConflicts();
 const reportConflicts = semanticConflicts.reportConflicts;
+const reportSettingVariants = semanticConflicts.executionVariants;
 const metadataSemanticConflicts = semanticConflicts.metadataConflicts;
 const metadataMissingTitles = metadata.filter((item) => !text(item.title));
 const reportsInBusinessDomains = reports.filter((report) => domainsForReport(report).length);
 const reportsInTechnicalAppendices = reports.filter((report) => appendicesForReport(report).length);
 const warnings = [
+  ...[...reportSettingVariants.keys()].map(id => `Report ${id} has matching calculation evidence but different saved or uninterpreted settings; verify explicit overrides before reuse.`),
   ...(text(descriptor.asset_scope ?? manifest.asset_scope) !== 'governed'
     ? [`The package scope is ${text(descriptor.asset_scope ?? manifest.asset_scope) || 'unknown'}; unauthenticated assets may be present.`]
     : []),
@@ -533,6 +542,9 @@ function validateSqlSemanticPlan(plan) {
     const summary = object(summaryValue);
     const reportId = text(summary.report_id);
     if (!sqlReportsById.has(reportId)) continue;
+    try {
+      validateSqlExplanations(summary, sqlTextFromCalculationContext(calculationContextForKb(sqlReportsById.get(reportId))));
+    } catch (error) { fail(`SQL report ${reportId}: ${error.message}`); }
     if (text(summary.definition_state) !== 'valid') continue;
     const issues = sqlSemanticQualityIssues(summary);
     if (issues.length) {
@@ -1036,13 +1048,29 @@ function renderDashboardAgentUsageSummary(dashboard, reportRows, notes, domain,
 }
 
 function renderReportAgentUsageSummary(report, metadataRefs, calculationContext, sqlSummary) {
+  const explanation = renderSqlExplanations(sqlSummary);
+  const coverage = text(report.definition_kind) === 'SQL' && !array(sqlSummary?.calculation_rules).length
+    ? '\n\n- Calculation coverage: unknown for this legacy summary. Verify the current SQL for operand filters, denominator, units, rounding, time baselines and excluded rows before execution.' : '';
+  return renderReportAuthoredSummary(report, metadataRefs, calculationContext, sqlSummary)
+    + (explanation ? `\n\n### Calculation evidence\n\n${explanation}` : '')
+    + coverage
+    + renderExecutionContract(reportContract(report, calculationContext))
+    + (reportSettingVariants.has(text(report.resource_key)) ? '\n- Saved-setting variant: matching calculation evidence does not establish identical defaults. Verify or explicitly override the required settings before reuse.\n' : '');
+}
+
+function renderReportAuthoredSummary(report, metadataRefs, calculationContext, sqlSummary) {
   const isSql = text(report.definition_kind) === 'SQL';
   if (isSql) return renderSqlReportAgentUsageSummary(report, sqlSummary);
+  const modelConfig = reportContract(report, calculationContext).model_config;
+  if (array(modelConfig.userCrowds).length || modelConfig.windowsGapValue != null) {
+    const model = array(modelConfig.userCrowds).length ? 'Saved population analysis' : 'Saved interval analysis';
+    return `- Model: ${model}.\n- Purpose: ${text(report.description || report.summary) || 'Verify the business question against the saved model settings below.'}\n- Result semantics: use the complete population conditions or ordered event roles, window and selected statistics in the execution contract.\n- Missing configuration, entity scope and historical state remain unknown; do not infer ordinary event metrics from model endpoints.`;
+  }
   const purpose = usefulSemanticText(sqlSummary?.business_purpose) || reportPurpose(report);
   const questions = usefulSemanticList(sqlSummary?.applicable_questions)
     ? array(sqlSummary.applicable_questions).map(renderPlainSemanticItem)
     : reportApplicableQuestions(report);
-  const metrics = topDomainFacts(array(report.metric_occurrences).map(occurrenceSentence), 12);
+  const metrics = array(report.metric_occurrences).map(occurrenceSentence);
   const parameters = reportParameterSummaryItems(calculationContext);
   const dimensions = reportDimensionSummaryItems(report, sqlSummary, calculationContext, metadataRefs);
   const filters = reportFilterSummaryItems(report, calculationContext);
@@ -1083,18 +1111,29 @@ function renderSqlReportAgentUsageSummary(report, summary) {
 }
 
 function renderSqlSemanticItem(value, summary) {
+  const item = object(value);
+  if (Object.keys(item).length && item.required == null && item.default_value == null && !Array.isArray(item.options)) {
+    return [text(item.name) ? `\`${text(item.name)}\`` : '', sanitizeVisibleSqlSemanticText(item.meaning)].filter(Boolean).join('：')
+      + (item.evidence ? ` [source: ${jsonInline(item.evidence)}]` : '')
+      + (item.identity_state === 'unknown' ? ' [output identity unverified; match the current SQL projection before use]' : '');
+  }
   return replaceSqlParameterMentions(renderSemanticItem(value), summary);
 }
 
 function renderSqlInputParameterItem(value) {
-  return sanitizeVisibleSqlSemanticText(renderSemanticItem(value));
+  if (!value || typeof value !== 'object') return sanitizeVisibleSqlSemanticText(value);
+  return renderSemanticItem({ ...value, meaning: sanitizeVisibleSqlSemanticText(value.meaning) });
 }
 
 function replaceSqlParameterMentions(value, summary) {
-  let result = sanitizeVisibleSqlSemanticText(value);
+  let result = text(value);
   for (const [name, meaning] of sqlParameterMeaningEntries(summary)) {
-    const pattern = new RegExp(`(?<![A-Za-z0-9_#$])${escapeRegExp(name)}(?![A-Za-z0-9_#$]|\\s*\\()`, 'giu');
+    const pattern = new RegExp(`\\$\\{(?:[A-Za-z]+:)?${escapeRegExp(name)}\\}`, 'gu');
     result = result.replace(pattern, meaning);
+    if (/^(?:selector|variable|text|number|date)\d+$/i.test(name)) {
+      const generatedReference = new RegExp(`(?<![A-Za-z0-9_#$\x60])${escapeRegExp(name)}(?![A-Za-z0-9_#$\x60])`, 'gu');
+      result = result.replace(generatedReference, meaning);
+    }
   }
   return sanitizeVisibleSqlSemanticText(result)
     .replace(/\bLIMIT\s+([^，；。]+?)限制/g, '按$1限制')
@@ -1135,11 +1174,6 @@ function genericSqlParameterMeaning(name) {
   return normalized;
 }
 
-function isGeneratedSqlParameterName(name) {
-  return /^(?:selector|variable|text|number|partdate)\d*$/i.test(text(name))
-    || /^date\d+$/i.test(text(name));
-}
-
 function escapeRegExp(value) {
   return text(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -1161,7 +1195,7 @@ function renderPlainSemanticItem(value) {
   if (item.default_value != null && text(item.default_value)) extras.push(`default=${text(item.default_value)}`);
   const expressionKind = text(item.expression_kind);
   if (expressionKind) extras.push(expressionKind);
-  if (isInputParameterSemanticItem(item) && meaning && name && !isGeneratedSqlParameterName(name)) {
+  if (isInputParameterSemanticItem(item) && meaning && name) {
     return [`${meaning}（\`${name}\`）`, extras.join('，')].filter(Boolean).join('：');
   }
   if (isInputParameterSemanticItem(item) && meaning) {
@@ -1190,6 +1224,12 @@ function reportDimensionSummaryItems(report, summary = null, calculationContext
   const context = calculationContext || calculationContextForKb(report);
   const facts = object(context.sql_semantic_facts);
   const refs = metadataRefs || metadataRefsForReport(report);
+  if (text(report.definition_kind) !== 'SQL') {
+    return reportContract(report, context).groups.map(group => {
+      const row = object(group);
+      return namedCodeFact(row.columnDesc || row.columnName || text(group), row.columnName || text(group));
+    });
+  }
   const candidates = [
     ...array(summary?.output_fields)
       .filter((item) => text(object(item).semantic_role) === 'dimension')
@@ -1207,14 +1247,18 @@ function reportDimensionSummaryItems(report, summary = null, calculationContext
 function reportParameterSummaryItems(calculationContext) {
   const context = object(calculationContext);
   return [
+    ...(Object.keys(object(context.time_scope)).length ? [`Saved time settings: ${JSON.stringify(context.time_scope)}`] : []),
     ...array(context.sql_params).map((item) => renderPlainSemanticItem({ name: object(item).name || object(item).paramName, meaning: object(item).displayName || object(item).placeholder })),
   ].filter(Boolean).slice(0, 12);
 }
 
 function reportFilterSummaryItems(report, calculationContext) {
   const items = [
-    ...array(report.metric_occurrences).flatMap((item) => filterSummaryLines(item.filters ?? item.custom_filters)),
-    ...array(object(calculationContext).filters).flatMap((item) => filterSummaryLines(item)),
+    ...array(report.metric_occurrences).flatMap((item) => [
+      ...filterSummaryLines(item.filters, item.relation),
+      ...array(item.custom_filters).flatMap((filter) => filterSummaryLines(filter).map(line => `Operand ${filter.index}: ${line}`)),
+    ]),
+    ...filterSummaryLines(object(calculationContext).filters, object(calculationContext).relation),
     ...array(object(calculationContext).event_view?.filts).flatMap((item) => filterSummaryLines(item)),
     ...array(object(calculationContext).visual_view?.filters).flatMap((item) => filterSummaryLines(item)),
     ...array(object(calculationContext).key_predicate_fragments).map(compactSqlFragment),
@@ -1224,7 +1268,17 @@ function reportFilterSummaryItems(report, calculationContext) {
 
 function completeSqlAgentSummary(report, planSummary, facts) {
   const base = object(planSummary);
-  if (Object.keys(base).length) return { summary_source: 'semantic_plan', ...base };
+  if (Object.keys(base).length) {
+    const names = new Set(array(object(facts.final_select).fields).map(field => {
+      if (field.name) return field.name;
+      const expression = text(field.expression);
+      return /^(?:[A-Za-z_][\w$#@.]*|"[^"]+")$/.test(expression) ? unquoteIdentifier(expression) : null;
+    }).filter(Boolean));
+    return { summary_source: 'semantic_plan', ...base,
+      output_fields: array(base.output_fields).map(field => typeof field === 'object' && !names.has(field.name)
+        ? { ...field, identity_state: 'unknown' } : field),
+    };
+  }
   return null;
 }
 
@@ -1380,7 +1434,7 @@ function renderSemanticItem(value) {
     .filter(([key]) => !['name', 'field', 'key', 'column', 'title', 'meaning', 'description', 'remark', 'purpose'].includes(key))
     .map(([key, itemValue]) => `${key}=${inlineSemanticValue(itemValue)}`)
     .join(', ');
-  if (isInputParameterSemanticItem(item) && meaning && name && !isGeneratedSqlParameterName(name)) {
+  if (isInputParameterSemanticItem(item) && meaning && name) {
     return [`${meaning}（\`${name}\`）`, details].filter(Boolean).join('：') || jsonInline(item);
   }
   if (isInputParameterSemanticItem(item) && meaning) {
@@ -1391,12 +1445,9 @@ function renderSemanticItem(value) {
 
 function isInputParameterSemanticItem(item) {
   const row = object(item);
-  const name = text(row.name ?? row.field ?? row.key ?? row.column ?? row.title);
-  const meaning = text(row.meaning ?? row.description ?? row.remark ?? row.purpose);
   return row.required != null
     || row.default_value != null
-    || Array.isArray(row.options)
-    || (Boolean(meaning) && /^(?:selector|variable|date|partdate|text|number)\d*$/i.test(name));
+    || Array.isArray(row.options);
 }
 
 function inlineSemanticValue(value) {
@@ -1434,6 +1485,11 @@ function reportDetailCalculationContext(report) {
   if (Object.keys(eventView).length) result.event_view = eventView;
   const events = jsonObject(rawDefinition.events);
   if (array(events.sqlVoParams).length) result.sql_params = events.sqlVoParams;
+  if (rawDefinition.events != null) {
+    try { result.source_events = typeof rawDefinition.events === 'string' ? JSON.parse(rawDefinition.events) : rawDefinition.events; }
+    catch { result.source_events = null; }
+  }
+  if (eventView.sqlViewParams != null) result.saved_parameters = eventView.sqlViewParams;
   return result;
 }
 
@@ -1857,6 +1913,9 @@ function metadataDefinitionLines(item) {
   if (text(definition.entity_mapping_scope)) lines.push(`实体映射范围: ${text(definition.entity_mapping_scope)}`);
   const sourceVersion = text(object(item.raw).sourceVersion ?? object(item.raw).source_version);
   if (sourceVersion) lines.push(`来源版本: ${sourceVersion}`);
+  for (const key of ['rule', 'rules', 'expression', 'dependent_events', 'dependent_properties']) {
+    if (definition[key] != null) lines.push(`Rule evidence (${key}): ${jsonInline(definition[key])}`);
+  }
   return lines;
 }
 
@@ -2020,11 +2079,17 @@ function eventBasisLabel(value) {
 
 function detectSemanticConflicts() {
   const reportConflicts = new Map();
+  const executionVariants = new Map();
   const metadataConflicts = new Map();
   for (const [key, values] of groupBySemanticKey(reports, reportSemanticKey)) {
     if (values.length < 2) continue;
-    const signatures = new Set(values.map(reportSemanticSignature));
-    if (signatures.size <= 1) continue;
+    const signatures = new Set(values.map(report => reportSignature(report, report.calculation_context, false)));
+    if (signatures.size <= 1) {
+      if (new Set(values.map(reportSemanticSignature)).size > 1) {
+        for (const report of values) executionVariants.set(text(report.resource_key), true);
+      }
+      continue;
+    }
     const summary = semanticConflictSummary('报表', key, values, (row) => reportSemanticSignatureLabel(row));
     for (const report of values) appendConflict(reportConflicts, text(report.resource_key), summary);
   }
@@ -2036,7 +2101,7 @@ function detectSemanticConflicts() {
     const summary = semanticConflictSummary('元数据', key, values, (row) => metadataSemanticSignatureLabel(row));
     for (const item of values) appendConflict(metadataConflicts, text(item.evidence_id), summary);
   }
-  return { reportConflicts, metadataConflicts };
+  return { reportConflicts, metadataConflicts, executionVariants };
 }
 
 function groupBySemanticKey(values, keyFn) {
@@ -2105,25 +2170,7 @@ function normalizeSemanticIntent(value) {
 }
 
 function reportSemanticSignature(report) {
-  if (text(report.definition_kind) === 'SQL') {
-    return JSON.stringify({ kind: 'SQL', sql: normalizeSql(text(object(report.calculation_context).sql)) });
-  }
-  return JSON.stringify({
-    kind: text(report.definition_kind) || text(report.report_model),
-    metrics: array(report.metric_occurrences).map(metricSemanticSignature).sort(),
-    filters: filterSummaryLines(object(report.calculation_context).filters).sort(),
-    groups: array(object(report.calculation_context).group_by).map(groupLabel).sort(),
-  });
-}
-
-function metricSemanticSignature(item) {
-  return JSON.stringify({
-    event_name: text(item.event_name),
-    aggregation_code: text(item.aggregation_code),
-    measure_key: text(item.measure_key),
-    formula_expression: text(item.formula_expression),
-    filters: filterSummaryLines(item.filters ?? item.custom_filters).sort(),
-  });
+  return reportSignature(report);
 }
 
 function reportSemanticSignatureLabel(report) {
@@ -2146,6 +2193,7 @@ function metadataSemanticSignature(item) {
     select_type: text(definition.select_type),
     source_type: text(definition.source_type),
     tag_type: text(definition.tag_type || definition.tag_sub_type),
+    rules: semanticValue(Object.fromEntries(['rule', 'rules', 'expression', 'dependent_events', 'dependent_properties'].filter(key => definition[key] != null).map(key => [key, definition[key]]))),
   });
 }
 
@@ -2173,7 +2221,10 @@ function collectFilterValues(value) {
 function renderOccurrence(item, index) {
   const expression = formulaExpression(item);
   const formulaSummary = formulaDefinitionSummary(item);
-  const filterSummary = filterSummaryLines(item.filters || item.custom_filters);
+  const filterSummary = [
+    ...filterSummaryLines(item.filters, item.relation),
+    ...array(item.custom_filters).flatMap(filter => filterSummaryLines(filter).map(line => `Operand ${filter.index}: ${line}`)),
+  ];
   const event = metricEventLabel(item) || 'unknown';
   return `### ${index + 1}. ${heading(occurrenceLabel(item) || `Metric ${index + 1}`)}
 
@@ -2219,15 +2270,17 @@ function formulaDefinition(item) {
 }
 
 function formulaDependencies(item) {
-  return array(formulaDefinition(item).formulationDeps).map((dependency) => {
+  return array(formulaDefinition(item).formulationDeps).map((dependency, index) => {
     const event = object(object(dependency).event);
     const quota = object(object(dependency).quota);
     const eventName = text(event.eventDesc || event.eventName) || '未知事件';
     const aggregation = text(quota.quotaDesc || quota.quotaName) || '资产包未暴露聚合方式';
-    const filters = array(object(event.filter).filts)
-      .map((filter) => text(object(filter).columnDesc || object(filter).quotDesc || object(filter).prop))
-      .filter(Boolean);
-    return `“${eventName}”的“${aggregation}”${filters.length ? `（过滤：${filters.join('、')}）` : ''}`;
+    const filters = [
+      ...filterSummaryLines(event.filter),
+      ...array(item.custom_filters).filter(filter => Number(filter.index) === index).flatMap(filter => filterSummaryLines(filter)),
+    ];
+    const time = object(dependency).date ?? array(item.quota_time_ranges)[index];
+    return `“${eventName}”的“${aggregation}”${filters.length ? `（过滤：${filters.join('、')}）` : ''}${time != null ? ` [operand ${index}, time=${JSON.stringify(time)}]` : ''}`;
   });
 }
 
@@ -2249,6 +2302,10 @@ function formulaDefinitionSummary(item) {
 }
 
 function aggregationLabel(item) {
+  const entity = array(item.entity_grain).map(row => object(row.taIdMeasure ?? row.ta_id_measure ?? row)).find(row => row.custom === true || text(row.entityType ?? row.entity_type).toUpperCase() === 'CUSTOM');
+  if (text(item.aggregation_code) === 'A101' && entity) {
+    return `Distinct entities (${text(entity.columnName ?? entity.column_name) || 'verify entity key'})`;
+  }
   const name = text(item.aggregation_name);
   const code = text(item.aggregation_code);
   const codeLabel = aggregationCodeLabel(code);
@@ -2312,31 +2369,19 @@ function isAggregationCode(value) {
   return /^A\d{3}(?:_\d+)?$/.test(text(value));
 }
 
-function filterSummaryLines(value) {
-  const conditions = collectFilterConditions(value);
-  return [...new Set(conditions.map(filterConditionSentence).filter(Boolean))];
-}
-
-function collectFilterConditions(value) {
-  if (Array.isArray(value)) return value.flatMap(collectFilterConditions);
-  if (!value || typeof value !== 'object') return [];
-  const source = object(value);
-  const nested = Object.entries(source)
-    .filter(([key]) => !['ftv', 'columnDesc', 'columnName', 'quotDesc', 'prop', 'calcuSymbol', 'calcu_symbol', 'relation', 'junctionKind', 'junction_kind'].includes(key))
-    .flatMap(([, item]) => collectFilterConditions(item));
-  const hasConditionIdentity = ['columnDesc', 'columnName', 'quotDesc', 'prop', 'propertyName', 'tagName'].some((key) => text(source[key]))
-    || array(source.ftv).some((item) => text(item));
-  return hasConditionIdentity ? [source, ...nested] : nested;
+function filterSummaryLines(value, relation) {
+  if (value == null || (Array.isArray(value) && !value.length) || (!Array.isArray(value) && !Object.keys(object(value)).length)) return [];
+  return [renderConditionTree(conditionTree(value, relation), filterConditionSentence)];
 }
 
 function filterConditionSentence(condition) {
   const field = text(condition.columnDesc || condition.quotDesc || condition.columnName || condition.prop || condition.propertyName || condition.tagName) || '未命名字段';
-  const values = array(condition.ftv).map(text).filter(Boolean);
+  const values = array(condition.ftv).map(value => typeof value === 'string' ? `“${value}”` : JSON.stringify(value));
   const code = text(condition.calcuSymbol ?? condition.calcu_symbol);
   const operator = filterOperatorLabel(code);
   const relation = text(condition.relation || condition.junctionKind || condition.junction_kind);
   const needsValue = filterOperatorNeedsValue(code);
-  const valueText = values.length ? values.map((value) => `“${value}”`).join('、') : needsValue ? '未给出固定值' : '';
+  const valueText = values.length ? values.join('、') : needsValue ? '未给出固定值' : '';
   const valuePart = valueText ? ` ${valueText}` : '';
   const relationText = relation ? `（关系：${relation}）` : '';
   return `${field} ${operator}${valuePart}${relationText}`;
@@ -2381,6 +2426,7 @@ function filterOperatorNeedsValue(value) {
 }
 
 function occurrenceLabel(item) { return readableMetricText(item.display_name || item.event_title || item.event_name); }
+function groupLabel(group) { return text(object(group).columnDesc || object(group).columnName || group); }
 
 function metricEventLabel(item) {
   const title = readableMetricText(item.event_title);
@@ -2411,7 +2457,6 @@ function readableMetricText(value) {
     .replace(/^、|、$/g, '')
     .trim();
 }
-function groupLabel(group) { return text(object(group).columnDesc || object(group).columnName || group); }
 
 function renderSemanticConflictList() {
   const reportLines = [...reportConflicts.entries()]

package/skills/ae-automation/SKILL.md

@@ -7,9 +7,9 @@ description: "Manage AE Agent and Agent team automations with ae-cli: create and
 
 See [command risks](references/command_index.md). Read [the command contract](references/cli.md) before writing or executing an automation. Use `ae-cli automation --help` and leaf help to discover flags.
 
-1. Resolve the host and space. A local user signs in with `ae-cli auth login`; a sandbox uses its injected credentials. Pass `--agent-space-id` when the user identifies a space. Without a space, the server uses a bound sandbox space or the personal default. Show the resolved space when it matters.
+1. Resolve the host and space. A local user signs in with `ae-cli auth login`; a sandbox uses the current conversation user's injected CLI token, never a shared sandbox's user binding. Pass `--agent-space-id` when the user identifies a space. Without an explicit space, the CLI inherits the current AgentSpace from its runtime context, working directory or verified current conversation; only a local invocation without space context uses the personal default. Show the resolved space when it matters.
 2. Discover the automation with `automation list` and inspect `automation get`. Use the returned IDs; names are not unique.
-3. For creation, select an Agent or team through the corresponding discovery commands. Match configuration to the target type. Preview writes with `--dry-run` when useful; the CLI shows a redacted request and asks the server to validate authentication, space, permissions, target state, fields, and idempotency without applying the operation.
+3. For creation, select an Agent or team through the corresponding discovery commands. Match configuration to the target type. Use `--weekdays` or `--days-of-month` JSON arrays for multiple days with one time; skip dates absent in a month. For the actual last day of every month use `--days-of-month '["L"]'`, or combine it with dates, e.g. `'[1,15,"L"]'`; overlapping selections execute only once. Both Agent and Agent Team accept result notifications. Confirm the complete configuration before creation; save only the recurring task instructions as `--message`, never the automation-creation guide. Preview writes with `--dry-run` when useful; the CLI shows a redacted request and asks the server to validate authentication, space, permissions, target state, fields, and idempotency without applying the operation.
 4. Execute the requested operation. Deleting an automation or stopping an execution requires confirmation; use `--yes` only when the user already authorized that action. In a non-interactive shell, these operations fail immediately unless global `--yes` is present.
 5. Read the returned run ID, then `automation runs result`. Report acceptance separately from completion. Use `--wait` only when the user needs the final outcome now.
 

package/skills/ae-automation/references/cli.md

@@ -17,7 +17,7 @@ Exit condition: equivalent gateway capabilities preserve permissions, idempotenc
 - `ae-cli automation enable|disable --id ID`
 - `ae-cli automation delete --id ID --yes`
 
-Scheduled creation needs `--schedule-kind` or `--cron-expression`. Frequencies: hourly with `--minute 0..59`; daily with `--time HH:mm`; weekly also `--weekday 0..6`; monthly also `--day-of-month 1..28`. Times use the server timezone. Manual creation does not require a schedule. `--trigger-immediately` executes after creation; `--wait` then waits for that execution. Creation and immediate execution have separate results: do not create another automation if only its execution failed.
+Scheduled creation needs `--schedule-kind` or `--cron-expression`. Frequencies: hourly with `--minute 0..59`; daily with `--time HH:mm`; weekly also `--weekdays '[1,3,5]'` (0=Sunday through 6=Saturday); monthly also `--days-of-month '[1,15,31]'` (integers 1–31 and `"L"` for the actual last day of the month). Existing single-day flags `--weekday 0..6` and `--day-of-month 1..31` remain supported; do not combine a single-day flag with its plural array. Arrays must be non-empty; duplicates are removed and dates sorted. Dates absent in the current month are skipped, never shifted into the next month. `"L"` follows the actual month end in the server timezone (including leap years). It can be selected alone or with numeric dates; overlapping selections at the same time run only once. Any minute 00–59 is valid in `--time`. Times use the server timezone. Manual creation does not require a schedule. `--trigger-immediately` executes after creation; `--wait` then waits for that execution. Creation and immediate execution have separate results: do not create another automation if only its execution failed.
 
 On update, omitted fields retain their values. `--model null`, `--scope null`, destination IDs set to `null`, and `--save-to-knowledge-base-id null` clear nullable fields. `--channels '[]'` clears notifications; `--clear-message` clears instructions; `--reuse-conversation false` disables reuse. An automation's target is immutable on update. Team fields are rejected for Agent targets and vice versa.
 
@@ -51,3 +51,20 @@ Without `--wait`, success means accepted. With `--wait`, output includes complet
 ## Compatibility
 
 The retired Agent-domain automation commands are unavailable. Use the `automation` domain for the complete lifecycle, including teams.
+
+## Shared result notifications and identity
+
+Agent and Agent Team both accept `--channels '["feishu","slack"]'`, `--feishu-chat-id`, `--lark-chat-id` and `--slack-channel-id`. Supported channels: `feishu`, `lark`, `slack`, `discord`, `dingtalk`, `wecom`, `mattermost`, `google_chat`, `zoom_chat`, `whatsapp`. Availability and destination permissions are validated by the server. Omitted update fields keep the existing values; `--channels '[]'` disables external delivery, and a receiver value of `null` clears that override. Results remain available in the application.
+
+Automation requests use the current user's `cli-token`, including in a shared sandbox. They do not infer an owner from `SandboxUser` or fall back to a different member. `--agent-space-id` takes precedence over `TE_AGENT_CURRENT_AGENT_SPACE_ID` or the current AgentSpace working directory. When the shell has changed directories, `TE_AGENT_CONVERSATION_ID` resolves the space through the existing authenticated workspace target API; a resolution failure never falls back to the personal space. Membership and write permissions are enforced by the server.
+
+For conversational creation, keep the supplied prompt editable until the user sends it. Resolve missing or ambiguous targets, summarize the configuration and obtain confirmation before creating. Agent runs inherit its model unless explicitly overridden; Agent Team retains its own configuration. Omit `--trigger-immediately` unless the user requests an immediate run.
+
+## Multi-date examples
+
+```bash
+ae-cli automation create --target-type agent --agent-id ID --name "Weekly report" --message "Summarize the latest metrics" --schedule-kind weekly --weekdays '[1,3,5]' --time 09:17
+ae-cli automation update --id ID --target-type team --schedule-kind monthly --days-of-month '[1,15,"L"]' --time 18:59
+```
+
+Each schedule has one execution time. Select `[1,2,3,4,5]` for Monday–Friday or `[0,6]` for weekends; these are weekdays, not a regional holiday calendar. Five-field cron accepts equivalent comma-separated weekday or month-day lists, such as `17 9 * * 1,3,5` and `59 18 1,15,L * *`. `L` is supported only in the month-day field. Ranges, steps and multiple execution times are not supported. `get` returns the saved `cronExpression` and notification configuration. On a scheduled active task, `nextRunAt`, `scheduleTimeZone` and `serverUtcOffset` describe the server's next execution.