@thinkingai/ae-cli 6.1.27 → 6.1.28

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.

package/skills/ae-capability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ae-capability
-version: 1.3.7
+version: 1.3.15
 description: "AE capability gateway discovery and generic invocation with ae-cli. Use when the user needs to list or search available capabilities, inspect an unknown capability schema/risk/auth contract, optionally validate complex input or dry-run before execute, or invoke a long-tail capability that has no curated ae-cli command. Always discover and inspect before composing input; never guess capability IDs or input fields. Prefer on-demand validate OR dry-run — do not stack both by default."
 ---
 
@@ -86,9 +86,13 @@ After running a gateway command, if you are asked whether intent telemetry was s
 
 Fallbacks, in priority order: `.ta/cli-agent-context.json` / `.ae/cli-agent-context.json` > `--agent-context` for isolated no-write environments or local debugging > legacy `TA_CLI_*` variables > runtime environment auto-detection.
 
-### Analysis query feedback
+### Analysis outcome assessment and supplementary feedback
 
-Analysis feedback trigger: only after a completed analysis data query and the final business analysis answer, ask once in the user's language whether the analysis met expectations. Do not ask after individual CLI calls, intermediate steps, discovery, metadata inspection, asset governance/writes, configuration, help, unrelated questions, query submission, running exports or failed queries. No explicit feedback means no submission or new feedback event. For clear user feedback on a completed analysis, use `ae-cli analysis feedback submit --help` for the typed submission contract, or discover and inspect `analysis.feedback.submit`. Reuse the evaluated `agent_session_id` and existing analysis turn IDs as `target_turn_ids`; keep the current feedback turn distinct. Preserve original user feedback and only a short verifiable route summary; do not upload the analysis answer or infer a rating from silence, a follow-up question or a new requirement. Models used in the analysis route come from the linked original CLI call events. Feedback collection must not block subsequent business work.
+Scenario collection is project opt-in. Before preparing or uploading a scenario sample, read `ae-cli project info get --project-id <source_project_id>` for the current host, authenticated account, and source analysis project. Only `data.analysis_scenario_collection_enabled === true` permits collection. Recheck for each new scenario and before appending feedback or a revision; do not reuse a previous grant or the company configuration's 24-hour cache. A missing field (including older services), false, unreadable configuration, or unknown project means skip collection and answer normally. Never enable the project switch, choose a different project, or invent a project ID to make collection succeed. The curated collect/append commands also check immediately before submission, and the service is authoritative if the switch changes. This controls only scenario samples; existing invocation and intent logs stay unchanged. `accepted=false, skipped=true` is a normal skip, not a failed analysis or successful upload. Do not retry, backfill, or fall back to `analysis feedback submit` to bypass this switch.
+
+Collect one sample for the whole user scenario, not one per CLI call. After forming the final answer, use `ae-cli analysis scenario collect` as specified in the `ae-cli analysis scenario collect --help` and `append --help` contracts, then deliver that exact answer text. Capture the original question/confirmed clarifications, actual final answer and the ordered query path (existing capability/call IDs and optional short purpose; prefer only meta.invocation_id, never confuse a business request_id with gateway client_request_id), never query result rows or error payloads; do not score correctness or generate a separate self-evaluation. The question_id is the original scenario's first user turn ID, stable across clarification, retries, multiple queries and corrections. Store/reuse the IDs returned by collection in conversation context. On later user objections, scope corrections or reported omissions targeting that answer, append the user's original text with `ae-cli analysis scenario append --entry-type user_feedback` and the original question_id/target_answer_id; do not decide whether the user is right. An ambiguous request for an explanation may be preserved as user text when clearly linked; do not invent a link. A normal follow-up or changed requirement is not automatically negative feedback. After a substantive follow-up answer to the same scenario (recheck, explanation, correction or scope clarification), append answer_revision with that exact answer/query path and a new answer_id, even when the conclusion stays the same; keep earlier answers. If the triggering user request was not already captured as user_feedback, include its exact text using --user-message on answer_revision so later scope changes are not lost. Do not duplicate feedback text in user_message. Acknowledgments such as thanks alone need no entry. A genuinely separate question gets a new question_id. Do not create another initial sample for an existing scenario. A separate evaluation task reads these samples later and can join existing call telemetry for parameters/status/timing. Path-only evidence cannot prove numeric answer correctness; unresolved correctness stays unknown. Only attempted analysis data queries qualify; metadata, discovery, help and asset writes alone do not. No routine satisfaction question. Collection failure must not block the answer or subsequent business work, trigger login or automatic retries, or be claimed as successful ingestion. For external Agents this is a Skill collection step, not a guaranteed post-answer hook; it has one collection tool call but no additional evaluation task on the answering path.
+
+User feedback is evidence, not a correctness label. Preserve exact user words and their target answer even if you disagree. Do not routinely ask for a satisfaction rating. The existing `analysis feedback submit` contract remains available for explicit standalone user ratings without a collected scenario; when a scenario exists, use its append command instead of submitting duplicate feedback. No explicit feedback means no submission or new feedback event for `cli_analysis_feedback`. Do not upload the analysis answer through that legacy feedback command. All collection excludes credentials, full transcripts and private reasoning.
 
 ### On-demand pre-check (pick one)
 

package/skills/ae-evaluation/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: ae-evaluation
+version: 2.4.5
+description: "Operate the Agent Evaluation (agent-test) platform through ae-cli: manage evaluation assets, configure and run Agent or preset-output evaluations, and analyze results. Use for platform evaluation tasks and their model, credential, integration, or schedule setup."
+---
+
+# ae-evaluation
+
+Use `ae-cli evaluation +<command> [options]` for existing operations and the resource commands below for new capabilities. All 121 commands target the Agent Evaluation platform.
+AE Agent resource management belongs to `ae-agent`; this skill manages evaluation assets and agents under test.
+
+## Read only the relevant reference
+
+Before executing a command, read the reference for the operation. Do not load all references.
+References contain command inputs, JSON contracts, and task-specific workflows; use command `--help` for additional flags.
+
+| Task | Reference |
+|---|---|
+| Create/import datasets, manage fields and cases, publish versions | [datasets.md](references/datasets.md) |
+| Configure LLM judges/templates, publish evaluator versions, calibrate or optimize prompts | [evaluators.md](references/evaluators.md) |
+| Create/configure/start/retry/cancel runs, inspect results/traces, export results | [runs.md](references/runs.md) |
+| Configure/test models and agents, manage credentials | [connections.md](references/connections.md) |
+| Change resource visibility or administer project members | [access-and-members.md](references/access-and-members.md) |
+| Download imported/exported files to disk | [files.md](references/files.md) |
+| Create/update/delete recurring evaluation schedules | [schedules.md](references/schedules.md) |
+| Connect/import AI Monitor data, configure TE reporting, discover TE Claude catalog | [integrations.md](references/integrations.md) |
+
+## Endpoint and authentication
+
+- In both personal terminals and AE sandboxes, evaluation commands default to the current AE Host and call `<current-host>/agenteval/api/v1/...` (an optional trailing `/agent` is removed from the host). Use `--host` to select another AE Host. Evaluation requests use the HTTP or HTTPS scheme configured for that AE Host, consistent with other AE commands. Legacy `--endpoint` and `AE_EVAL_BASE_URL` values may only match the current AE Host; other values fail before credentials are sent. Remove these settings and use `--host` to select a host.
+- Session exchange and evaluation requests reject redirects; session exchange has a 30-second timeout.
+- Path resource IDs must contain only letters, digits, hyphens, or underscores; separators and URL escape syntax are rejected locally.
+- Use the online platform. Do not suggest localhost/loopback endpoints or obtain tokens from a local `agent-test/.env`.
+- Authentication uses `AE_EVAL_ACCESS_TOKEN` when explicitly set; it is sent only as `Authorization: Bearer` and must never appear in command arguments or output.
+- In an AE sandbox, when `AE_EVAL_ACCESS_TOKEN` is unset, ae-cli automatically exchanges the sandbox-provisioned `cli-token` through te-claude for a short-lived evaluation session. The CLI token is never sent to Agent Evaluation. If the token can access multiple TE projects, set `AE_EVAL_TE_PROJECT_ID` to the authorized TE project id.
+- Outside a sandbox, obtain a session token through the platform web console (`sessionStorage.getItem('agent.evaluation.session-token')`) or `POST /agenteval/api/v1/auth/session`. An unset token produces `EVAL_ACCESS_TOKEN_MISSING`.
+- Successful commands return JSON by default; use the actual error envelope to diagnose failures.
+
+## IDs, versions, and mutations
+
+- Discover real IDs with list/get commands. UUIDs are version-7 strings; never guess IDs, JSON payload shapes, frequency fields, or `lock_version` values.
+- Published dataset, evaluator, and evaluation-task versions are immutable and separate from drafts. Runs and schedules pin versions; existing published versions cannot be overwritten. Publishing unchanged assets returns `ASSET_VERSION_NO_CHANGES`.
+- Read operations can run once inputs are known. Writes require user intent; high-risk operations retain confirmation unless the user authorizes bypassing it with `--yes`.
+- Credential enabling/disabling, run cancellations, deletes, ownership transfers, template disabling, access-scope changes, and member admission/permission changes are high-risk writes. Check command help for risk and role requirements; references identify ADMIN-only operations.
+- Before each mutation requiring `--lock-version`, read the current resource. Every successful mutation increments its version; re-read before the next mutation.
+- Use the corresponding get command for runs, datasets, evaluators, models, agents, credentials, dataset cases, TE report config, and AI Monitor connection. Schedules use `+list_schedules`; calibration cases use `+list_calibration_cases`.
+- Field mutations use the dataset version; case mutations use the case version. First creation of TE report config or AI Monitor connection omits `--lock-version`; updates require the current value, including 0.
+- Async dataset imports, evaluation-set imports, and result exports require a fresh unique `--idempotency-key` per attempt. Poll the relevant status until completion; resource creation alone does not establish readiness.
+- Prefer `--dry-run` before broad/destructive writes whose targets have not been validated. It previews the request without executing it.
+- Evaluation errors redact the submitted credential values and session tokens; server-provided error messages and hints are not persisted in CLI logs. Stable business error codes are preserved unchanged; non-sensitive diagnostics remain available in the JSON error envelope.
+- Case data is redacted from command logs for both single-case and batch writes. Sensitive JSON parse failures report the flag and syntax guidance without echoing the input.
+- Credential secrets are write-only. Never echo secrets, session claims, or sensitive trace evidence; use redacted dry-run output.
+
+## Evaluation lifecycle
+
+1. Select a published dataset version with `+list_dataset_versions`.
+2. Choose `LIVE_AGENT` (default) to call an Agent/model, or `PRESET_RESULT` to score outputs stored in the dataset. PRESET_RESULT must omit agent/model config IDs. `IMPORTED_OUTPUT` is legacy data only; never recommend it.
+3. Create a draft run, bind at least one ACTIVE evaluator (prefer pinned published versions), and configure complete field mapping plus result filter fields. An explicit empty result filter is required when no fields are selected.
+4. Prefer `+validate_run` before starting. It runs the start preflight without a body or lock version. Read the latest run, then `+start_run` with its current lock version.
+5. Inspect overview/distribution, drill into cases, and use the run reference for retry, trace, and export semantics.
+
+Read [runs.md](references/runs.md) for the executable sequence and mapping examples. Setup of datasets, evaluators, or connections needs only the matching reference above.
+
+## Transport transition
+
+The existing platform contract exposes REST operations rather than evaluation
+capabilities registered in this repository. New commands retain that transport
+for typed input, permission confirmation, and file handling. They are Transitional;
+see the matching references for migration records. Check deployment Gateway
+coverage before extending these commands; prefer existing equivalent capabilities.
+
+Transition status: transitional
+Owning module: Agent Evaluation (agent-test)
+Current transport: authenticated REST /agenteval/api/v1
+Gateway target: TBD (evaluation capability registration)
+Review after: 2027-01-21
+Exit condition: once equivalent evaluation capabilities are available, migrate
+selected typed/file commands to L2 or replace simple wrappers with L3; retain
+existing + commands only where compatibility or orchestration justifies them.
+
+This record also applies to the locale and process-evidence updates in the
+existing evaluator/run references. It is a migration plan, not a claim that a
+particular deployed Gateway has been inspected.

package/skills/ae-evaluation/references/access-and-members.md

@@ -0,0 +1,55 @@
+# Resource visibility and project members
+
+Read [SKILL.md](../SKILL.md) for authentication and mutation rules. These commands
+require administrator privileges (`root` or `agent_admin`). Permission changes
+are high-risk writes; retain confirmation unless the user authorizes `--yes`.
+
+## Resource visibility
+
+```bash
+ae-cli evaluation dataset access-scope --id <dataset-uuid> --access-scope COMPANY --lock-version <n>
+ae-cli evaluation evaluator access-scope --id <evaluator-uuid> --access-scope COMPANY --lock-version <n>
+ae-cli evaluation model-config access-scope --id <model-config-uuid> --access-scope PERSONAL --lock-version <n>
+ae-cli evaluation agent access-scope --id <agent-uuid> --access-scope PERSONAL --lock-version <n>
+```
+
+Read the current resource with its `+get_*` command before changing it. Each
+successful mutation increments `lock_version`. PERSONAL and COMPANY are mutable;
+SYSTEM resources are read-only. COMPANY sharing stays within the authenticated
+project/tenant. Shared assets cannot depend on personal configurations or
+credentials (`ACCESS_SCOPE_DEPENDENCY_PRIVATE`); inspect dependencies rather
+than silently broadening their visibility. Ordinary model/Agent creation produces
+personal resources and is not restricted to administrators by its create route.
+Credential operations and administrative routes remain administrator-only.
+
+## Project membership
+
+```bash
+ae-cli evaluation +list_project_members
+ae-cli evaluation project-member list-candidates
+ae-cli evaluation project-member batch-add --members-json '[{"external_id":"<te-id>","display_name":"<name>"}]'
+ae-cli evaluation project-member change-role --id <user-uuid> --role agent_admin
+ae-cli evaluation project-member set-status --id <user-uuid> --status DISABLED
+ae-cli evaluation project-member remove --id <user-uuid>
+```
+
+Discover candidates rather than guessing IDs. Admission takes TE `external_id`;
+role/status/removal take the project member's `user_id` UUID from
+`+list_project_members`. Batch admission returns added/skipped counts and skips
+existing members. These routes do not accept `lock_version`.
+
+Roles are `root`, `agent_admin`, and `member`; change-role accepts only
+`agent_admin|member`. Root members are protected. `set-status` accepts
+`ACTIVE|DISABLED` and affects login across all projects in the tenant. `remove`
+revokes only the current project's membership, including subsequent TE login
+and refresh, until explicitly re-added. Never describe disabling a login as
+merely removing it from one project.
+
+Transition status: transitional
+Owning module: Agent Evaluation accessscope and membership
+Current transport: authenticated REST /agenteval/api/v1
+Gateway target: TBD (evaluation access-scope and member administration)
+Review after: 2027-01-21
+Exit condition: when equivalent capabilities exist, migrate typed permission
+commands to L2 where confirmation and typed validation add value; use L3 for
+simple discovery operations and remove duplicate Transitional routes.