@thinkingai/ae-cli 6.1.24 → 6.1.25

package/skills/ae-analysis/references/user_tag_get.md

@@ -4,7 +4,7 @@ Get exact user tag details after discovery.
 
 Do not use it for fuzzy discovery, member data, or history statistics. Output contains saved tag metadata/definition for the requested names.
 
-After `user-tag create` or an update containing `--definition-request`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a definition update, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly.
+After `user-tag create` or an update reporting `computation.triggered_automatically=true`, use this command to observe the automatically started computation; do not trigger `user-tag refresh`. For create, wait until `progress=100` and `refresh_time` is present. For a changed definition, record the previous `refresh_time` first and wait until `progress=100` and `refresh_time` advances. Until then, `users_num` and member queries may still reflect the previous successful computation; treat that as stale data, not as evidence that the new definition was compiled or calculated incorrectly. An identical definition is not recomputed; when update returns `not_triggered` and `next_action=none`, do not wait for a new refresh timestamp.
 
 The raw backend value is returned under `result`. The response also provides aggregate and per-tag `computation`, `result_freshness`, and `next_action`. `poll_get` includes an exact capability/input pair; `none` means the latest result is usable. `potentially_stale` with `is_stale=null` means `refresh_time` predates `update_time`, but the update may have changed metadata only; inspect the latest update instead of refreshing automatically.
 

package/skills/ae-analysis/references/user_tag_models.md

@@ -24,7 +24,9 @@ Top-level `type` is exactly one of `condition`, `metric`, `first_last`, or `sql`
 
 ## Metric tag
 
-Required: `event`, `aggregation`. `property`, `percentile`, `time_range`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property.
+Required: `event`, `aggregation`, and `time_range`. `property`, `percentile`, and `filters` are optional. Filters support only event properties and user properties. A string `field` is an event property; use `{name,type:"user_property"}` for a user property. Use the semantic time mappings in [`audience_models.md`](audience_models.md); never omit `time_range` from a metric tag.
+
+Supported aggregations are `count`, `active_days`, `sum`, `avg`, `max`, `min`, `median`, and `percentile`. `median` is a dedicated aggregation for a numeric event `property`; do not represent it as `percentile=50`.
 
 Use `aggregation=percentile` with a numeric event `property` and pass `percentile`. Supported percentile values match the page controls: `5`, `10`, `20`, `25`, `30`, `40`, `60`, `70`, `75`, `80`, `90`, `95`, and `99`. The `percentile` field is required for percentile aggregation and is rejected for every other aggregation.
 
@@ -32,10 +34,16 @@ Use `aggregation=percentile` with a numeric event `property` and pass `percentil
 {"type":"metric","metric":{"event":"pay","aggregation":"sum","property":"amount","time_range":{"mode":"previous","unit":"day","value":30},"filters":{"relation":"and","items":[{"field":"channel","operator":"eq","values":["app"]},{"field":{"name":"country","type":"user_property"},"operator":"eq","values":["US"]}]}}}
 ```
 
+Median example:
+
+```json
+{"type":"metric","metric":{"event":"pay","aggregation":"median","property":"amount","time_range":{"mode":"previous","unit":"day","value":30}}}
+```
+
 Percentile example:
 
 ```json
-{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90}}
+{"type":"metric","metric":{"event":"pay","aggregation":"percentile","property":"amount","percentile":90,"time_range":{"mode":"previous","unit":"day","value":30}}}
 ```
 
 ## First/last tag
@@ -61,8 +69,16 @@ From a fixed date through today:
 SQL tags support only `${PartDate:name}` dynamic placeholders. Every placeholder requires one `params` item with `type=part_date` and either `recent_day` or `start_time` plus `end_time`. `Text`, `Number`, `Variable`, `Time`, and `Selector` parameters are valid for general SQL analysis but are not valid for SQL tags.
 For `recent_day`, `0-7` means 最近7天 and includes today; `1-7` means 过去7天 and excludes today.
 
+`${base_date}` is a separate built-in computation-date macro, not a user-configurable dynamic placeholder. SQL tags may use `${base_date}`, a formatted value such as `${base_date:yyyy-MM-dd}`, or a server-supported offset such as `${base_date:yyyy-MM-dd-1*day}`. Keep the macro in `sql` and do not add it to `params`; it is expanded when the tag is calculated. Expansion produces plain text, so quote the macro when the SQL expression expects a string or date literal:
+
+```json
+{"type":"sql","sql":"SELECT \"#user_id\", 'payer' AS tag_value FROM hive.ta.v_event_1 WHERE \"$part_date\"='${base_date:yyyy-MM-dd}' AND \"$part_event\"='pay'"}
+```
+
 Before writing a SQL tag, use `analysis sql-table list --project-id <project_id> --usage tag_cluster`, then call `analysis sql-table columns --project-id <project_id> --table-ref <table_ref> --usage tag_cluster`. The `tag_cluster` authorized table set is intentionally different from the general analysis SQL table set; do not reuse a table discovered with the default `usage=analysis`.
 
 `#user_id`, `$part_event`, and any other Trino identifier containing `#`, `$`, `@`, spaces, or punctuation must be delimited with double quotes. Single quotes are only for values.
 
 When the SQL reads an event table, it must also filter the quoted `"$part_date"` date-partition column; the backend rejects event-table SQL without that predicate.
+
+For space tables, use the returned `sql_reference` when writing SQL and loading columns. `source_type=gaia` identifies a space table; keep `--usage tag_cluster` for both discovery commands.

package/skills/ae-analysis/references/user_tag_refresh.md

@@ -2,7 +2,7 @@
 
 Explicitly recompute an existing user tag by exact `tag_name` without changing its definition.
 
-Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update containing `--definition-request`; those commands already start computation automatically. Do not use it to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
+Use this only when an unchanged definition must be run again, such as an explicit retry or a recomputation against changed source data. Do not call it after `user-tag create` or an update reporting `computation.triggered_automatically=true`; those commands already start computation. An identical definition update does not trigger computation and does not by itself authorize a separate refresh. Do not use this command to refresh one history snapshot. Output means recomputation was submitted, not completed. Poll `user-tag get` and verify the new computation before using `users_num` or querying members.
 
 The response marks this as an explicit trigger: `computation.triggered_by_command=true`, `computation.triggered_automatically=false`, `computation.status=submitted`, and `result_freshness.is_stale=true`. Follow the returned `next_action`, `next_capability_id`, and `next_input` to poll.
 

package/skills/ae-analysis/references/user_tag_update.md

@@ -2,9 +2,9 @@
 
 Update a user tag. Discover the exact `tag_name` first.
 
-Do not use it for ID-file value replacement or to create a missing tag. Supplying `--definition-request` automatically starts recomputation after the definition is updated; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that the new result is complete. Record the current `refresh_time` before updating, then poll `user-tag get` until `progress=100` and `refresh_time` advances before using `users_num` or querying members.
+Do not use it for ID-file value replacement or to create a missing tag. A changed `--definition-request` automatically starts recomputation; the native service skips recomputation when the normalized definition and timezone are unchanged. Follow the returned `computation.triggered_automatically` and `next_action`; do not call `user-tag refresh` afterward. Updating only `--display-name` or `--remark` does not recompute. A schedule-only update changes periodic refresh without starting immediate recomputation. `--auto-refresh-cron` or `--auto-refresh-schedule` can enable periodic refresh directly, including on a previously disabled tag. A successful update means the definition was saved, not that a triggered computation is complete. When computation was triggered, poll `user-tag get` until `progress=100` and `refresh_time` advances from the value recorded before the update. An unchanged definition returns `not_triggered` and `next_action=none`; do not wait for its refresh timestamp to change.
 
-The response distinguishes both paths. A definition update returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and normally `next_action=poll_get` with an exact capability/input pair. A display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
+The response distinguishes both paths. An update that triggers recomputation returns `computation.triggered_automatically=true`, `result_freshness.is_stale=true`, and `next_action=poll_get` with an exact capability/input pair. An unchanged definition or display-name/remark-only update returns `computation.status=not_triggered`, `result_freshness.status=fresh`, and `next_action=none`.
 
 Flags: `--project-id`, `--tag-name` required. Optional: `--display-name`, `--definition-request`, `--authenticated-only`, `--remark`, `--zone-offset`, `--enable-auto-refresh`, `--auto-refresh-schedule`, `--auto-refresh-cron`. The tag type comes from `definition_request.type` when the definition changes.
 

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

@@ -23,6 +23,7 @@ const projectNameOverride = clean(args['project-name']);
 const force = Boolean(args.force);
 const keepBuildIr = Boolean(args['keep-build-ir']);
 const allowAllVisible = Boolean(args['allow-all-visible']);
+const allowSemanticPlanSnapshotDrift = Boolean(args['allow-semantic-plan-snapshot-drift']);
 
 assertSafePaths(packageRoot, outputRoot, archivePath, uploadSourcesPath);
 
@@ -59,7 +60,9 @@ const snapshotDate = normalizeSnapshotDate(args['snapshot-date'] || descriptor.g
 
 const semanticPlan = readJson(semanticPlanPath);
 if (clean(semanticPlan.schema_version) !== '2.0') fail('Project semantic knowledge Wiki plan schema 2.0 is required.');
-if (clean(semanticPlan.source_snapshot_hash) !== snapshotHash) fail('Semantic plan snapshot hash does not match the asset package.');
+if (clean(semanticPlan.source_snapshot_hash) !== snapshotHash && !allowSemanticPlanSnapshotDrift) {
+  fail('Semantic plan snapshot hash does not match the asset package.');
+}
 if (clean(semanticPlan.generation_method) !== 'agent_semantic_synthesis') {
   fail('Semantic plan generation_method must be agent_semantic_synthesis.');
 }
@@ -84,6 +87,7 @@ for (const domain of domains) for (const id of asArray(domain.dashboard_ids).map
 for (const appendix of appendices) for (const id of asArray(appendix.dashboard_ids).map(clean)) appendixByDashboardId.set(id, appendix);
 
 const planModel = validateSemanticPlan();
+const semanticPlanState = buildSemanticPlanState();
 const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'project-semantic-knowledge-wiki-'));
 const buildIr = path.join(scratch, 'build-ir');
 
@@ -92,6 +96,7 @@ try {
   const generatorArgs = [generator, '--asset-package', packageRoot, '--domain-plan', semanticPlanPath,
     '--output', buildIr, '--project-name', projectName];
   if (allowAllVisible) generatorArgs.push('--allow-all-visible');
+  if (allowSemanticPlanSnapshotDrift) generatorArgs.push('--allow-semantic-plan-snapshot-drift');
   execFileSync(process.execPath, generatorArgs, { stdio: 'pipe' });
 
   const corpus = readJson(path.join(buildIr, 'corpus.json'));
@@ -117,7 +122,7 @@ try {
       const id = clean(domain.domain_id);
       const source = readText(path.join(buildIr, 'domains', fileName('domain', id)));
       const cards = asArray(domain.recall_cards);
-      const cardLinks = cards.map((card) => `- [${escapeLink(card.questions?.[0] || card.intent || card.card_id)}](../recall-cards/${fileName('recall-card', card.card_id)})`).join('\n');
+      const cardLinks = cards.map((card) => `- [${escapeLink(card.intent || card.card_id)}](../recall-cards/${fileName('recall-card', card.card_id)})`).join('\n');
       writeText(path.join(wikiRoot, 'domains', fileName('domain', id)),
         replaceFrontmatter(source, domainFrontmatter(domain))
           + `\n## 场景召回卡\n\n${cardLinks || '- 无'}\n`);
@@ -201,6 +206,7 @@ try {
     writeText(path.join(wikiRoot, 'index.md'), renderWikiIndex(corpus));
     writeText(path.join(wikiRoot, 'log.md'), renderLog(corpus));
     writeText(path.join(staging, 'index.md'), renderSnapshotIndex(corpus));
+    writeText(path.join(staging, 'refresh-state.md'), renderRefreshState(semanticPlanState));
 
     const sourceProjectRefs = sourceProjectReferencesFromPackage();
     const sourceProjectIds = [...new Set(sourceProjectRefs.map((row) => row.source_project_id))].sort((a, b) => a - b);
@@ -215,7 +221,9 @@ try {
       source_project_id_status: sourceProjectRefs.length ? 'detected_in_packaged_definitions' : 'not_exposed',
       project_name: projectName,
       source_snapshot_hash: snapshotHash,
-      semantic_plan_hash: sha256(fs.readFileSync(semanticPlanPath)),
+      semantic_plan_hash: semanticPlanState.plan_hash,
+      semantic_plan_state_schema_version: semanticPlanState.schema_version,
+      semantic_plan_fragment_count: semanticPlanState.fragments.length,
       asset_package_schema_version: '3.0',
       asset_scope: packageAssetScope,
       wiki_schema_version: '1.0',
@@ -265,6 +273,8 @@ function validateSemanticPlan() {
   const cardIds = new Set();
   const excludedByAsset = new Map();
   const preferredByAsset = new Map();
+  const domainIds = new Set(domains.map((domain) => clean(domain.domain_id)).filter(Boolean));
+  const projectBusinessModel = validateProjectBusinessModel(semanticPlan.project_business_model, domainIds);
   for (const domain of domains) {
     const domainId = clean(domain.domain_id);
     const domainDashboardIds = new Set(asArray(domain.dashboard_ids).map(clean));
@@ -272,6 +282,7 @@ function validateSemanticPlan() {
       .some((ref) => domainDashboardIds.has(clean(ref.dashboard_id)))).map((report) => clean(report.resource_key)));
     const domainMetricIds = new Set(reports.filter((report) => domainReportIds.has(clean(report.resource_key)))
       .flatMap((report) => asArray(report.metric_occurrences).map((item) => clean(item.metric_key)).filter(Boolean)));
+    validateDomainJudgmentModel(domain.domain_judgment_model, domainId, domainDashboardIds, domainReportIds, domainMetricIds);
     const recallCards = asArray(domain.recall_cards);
     if (!recallCards.length) fail(`Domain ${domainId || '<unknown>'} must contain at least one recall card.`);
     for (const value of recallCards) {
@@ -334,7 +345,138 @@ function validateSemanticPlan() {
     fail(`Semantic plan is missing SQL semantics for ${missingSql.length} report(s): ${missingSql.join(', ')}`);
   }
 
-  return { cards, excludedByAsset, preferredByAsset, sqlByReportId, missingSqlByReportId: new Set(missingSql) };
+  return {
+    cards,
+    excludedByAsset,
+    preferredByAsset,
+    sqlByReportId,
+    missingSqlByReportId: new Set(missingSql),
+    projectBusinessModel,
+  };
+}
+
+function validateProjectBusinessModel(value, domainIds) {
+  const model = asObject(value);
+  const businessPositioning = clean(model.business_positioning);
+  const audienceRoles = asArray(model.audience_roles).map(clean).filter(Boolean);
+  const businessObjects = asArray(model.business_objects).map((item, index) => {
+    const row = asObject(item);
+    const objectId = clean(row.object_id);
+    const name = clean(row.name);
+    const meaning = clean(row.meaning);
+    if (!/^[a-z0-9][a-z0-9_-]{1,79}$/.test(objectId)) fail(`project_business_model.business_objects[${index}] has invalid object_id.`);
+    if (!name || !meaning) fail(`project_business_model.business_objects[${index}] requires name and meaning.`);
+    const evidenceRefs = normalizePlanAssetRefs(row.evidence_refs, `business object ${objectId}`);
+    if (!evidenceRefs.length) fail(`business object ${objectId} requires evidence_refs.`);
+    return { object_id: objectId, name, meaning, evidence_refs: evidenceRefs };
+  });
+  const objectNames = new Set(businessObjects.map((item) => item.name));
+  const objectRelationships = asArray(model.object_relationships).map((item, index) => {
+    const row = asObject(item);
+    const fromObject = clean(row.from_object);
+    const toObject = clean(row.to_object);
+    const relationship = clean(row.relationship);
+    if (!fromObject || !toObject || !relationship) {
+      fail(`project_business_model.object_relationships[${index}] requires from_object, to_object and relationship.`);
+    }
+    if (!objectNames.has(fromObject) || !objectNames.has(toObject)) {
+      fail(`object relationship ${fromObject || '<empty>'}->${toObject || '<empty>'} must reference declared business object names.`);
+    }
+    const evidenceRefs = normalizePlanAssetRefs(row.evidence_refs, `object relationship ${fromObject}->${toObject}`);
+    if (!evidenceRefs.length) fail(`object relationship ${fromObject}->${toObject} requires evidence_refs.`);
+    return { from_object: fromObject, to_object: toObject, relationship, evidence_refs: evidenceRefs };
+  });
+  const decisionChains = asArray(model.decision_chains).map((item, index) => {
+    const row = asObject(item);
+    const chainId = clean(row.chain_id);
+    const title = clean(row.title);
+    const decisionQuestion = clean(row.decision_question);
+    const signals = asArray(row.signals).map(clean).filter(Boolean);
+    const decisionSteps = asArray(row.decision_steps).map(clean).filter(Boolean);
+    const preferredDomainIds = asArray(row.preferred_domain_ids).map(clean).filter(Boolean);
+    const assetRefs = normalizePlanAssetRefs(row.asset_refs, `decision chain ${chainId || index + 1}`);
+    const boundaries = asArray(row.boundaries).map(clean).filter(Boolean);
+    if (!/^[a-z0-9][a-z0-9_-]{1,79}$/.test(chainId)) fail(`project_business_model.decision_chains[${index}] has invalid chain_id.`);
+    if (!title || !decisionQuestion) fail(`decision chain ${chainId} requires title and decision_question.`);
+    if (signals.length < 2) fail(`decision chain ${chainId} requires at least two signals.`);
+    if (decisionSteps.length < 2) fail(`decision chain ${chainId} requires at least two decision_steps.`);
+    if (!preferredDomainIds.length || preferredDomainIds.some((id) => !domainIds.has(id))) {
+      fail(`decision chain ${chainId} must reference existing preferred_domain_ids.`);
+    }
+    if (!assetRefs.length) fail(`decision chain ${chainId} requires asset_refs.`);
+    if (!boundaries.length) fail(`decision chain ${chainId} requires boundaries.`);
+    return {
+      chain_id: chainId,
+      title,
+      decision_question: decisionQuestion,
+      signals,
+      decision_steps: decisionSteps,
+      preferred_domain_ids: preferredDomainIds,
+      asset_refs: assetRefs,
+      requires_live_execution: Boolean(row.requires_live_execution),
+      boundaries,
+    };
+  });
+  const nonGoals = asArray(model.non_goals).map(clean).filter(Boolean);
+  if (!businessPositioning) fail('project_business_model requires business_positioning.');
+  if (!audienceRoles.length) fail('project_business_model requires audience_roles.');
+  if (!businessObjects.length) fail('project_business_model requires business_objects.');
+  if (!objectRelationships.length) fail('project_business_model requires object_relationships.');
+  if (!decisionChains.length) fail('project_business_model requires decision_chains.');
+  if (!nonGoals.length) fail('project_business_model requires non_goals.');
+  return {
+    business_positioning: businessPositioning,
+    audience_roles: audienceRoles,
+    business_objects: businessObjects,
+    object_relationships: objectRelationships,
+    decision_chains: decisionChains,
+    non_goals: nonGoals,
+  };
+}
+
+function validateDomainJudgmentModel(value, domainId, domainDashboardIds, domainReportIds, domainMetricIds) {
+  const model = asObject(value);
+  const businessStateJudged = clean(model.business_state_judged);
+  const mainObjects = asArray(model.main_objects).map(clean).filter(Boolean);
+  const signals = asArray(model.signals).map(clean).filter(Boolean);
+  const decisionPath = asArray(model.decision_path).map(clean).filter(Boolean);
+  const boundaries = asArray(model.boundaries).map(clean).filter(Boolean);
+  const attachmentLogic = asArray(model.asset_attachment_logic);
+  if (!businessStateJudged) fail(`Domain ${domainId} is missing domain_judgment_model.business_state_judged.`);
+  if (!mainObjects.length) fail(`Domain ${domainId} is missing domain_judgment_model.main_objects.`);
+  if (signals.length < 2) fail(`Domain ${domainId} domain_judgment_model requires at least two signals.`);
+  if (decisionPath.length < 2) fail(`Domain ${domainId} domain_judgment_model requires at least two decision_path steps.`);
+  if (!attachmentLogic.length) fail(`Domain ${domainId} domain_judgment_model requires asset_attachment_logic.`);
+  if (!boundaries.length) fail(`Domain ${domainId} domain_judgment_model requires boundaries.`);
+  for (const [index, item] of attachmentLogic.entries()) {
+    const row = asObject(item);
+    const ref = normalizePlanAssetRef(row.asset_ref, `domain ${domainId} asset_attachment_logic[${index}]`);
+    const role = clean(row.role);
+    const reason = clean(row.reason);
+    if (!['primary_entry', 'supporting_evidence', 'drilldown', 'exclusion'].includes(role)) {
+      fail(`domain ${domainId} asset_attachment_logic[${index}] has invalid role.`);
+    }
+    if (!reason || reason.length < 10) fail(`domain ${domainId} asset_attachment_logic[${index}] requires concrete reason.`);
+    const inDomain = ref.resource_type === 'dashboard' ? domainDashboardIds.has(ref.resource_key)
+      : ref.resource_type === 'report' ? domainReportIds.has(ref.resource_key)
+        : ref.resource_type === 'metric' ? domainMetricIds.has(ref.resource_key) : false;
+    if (!inDomain) fail(`domain ${domainId} asset_attachment_logic references ${ref.resource_type}:${ref.resource_key} outside domain closure.`);
+  }
+}
+
+function normalizePlanAssetRefs(values, label) {
+  return asArray(values).map((value, index) => normalizePlanAssetRef(value, `${label} asset_refs[${index}]`));
+}
+
+function normalizePlanAssetRef(value, label) {
+  const ref = asObject(value);
+  const type = clean(ref.resource_type);
+  const key = clean(ref.resource_key);
+  const exists = type === 'dashboard' ? dashboardById.has(key)
+    : type === 'report' ? reportById.has(key)
+      : type === 'metric' ? metricById.has(key) : false;
+  if (!exists) fail(`${label} references unknown asset ${type || '<type>'}:${key || '<key>'}.`);
+  return { resource_type: type, resource_key: key };
 }
 
 function assertAgentAuthoredRecallCard(card, domainId) {
@@ -436,8 +578,36 @@ function writeMergedAsset(wikiRoot, directory, asset, authority, extra = '') {
   const brief = readText(path.join(buildIr, 'briefs', directory, fileName(directory.slice(0, -1), id)));
   const type = directory === 'dashboards' ? 'project-dashboard' : directory === 'reports' ? 'project-report' : 'project-reusable-metric';
   const title = assetReadableTitle(asset, directory.slice(0, -1));
+  const authorityNotice = renderAssetAuthorityNotice(authority);
+  const mergedExtra = [authorityNotice, extra.trim()].filter(Boolean).join('\n\n');
   writeText(path.join(wikiRoot, directory, assetOutputFileName(directory, id)),
-    ensureReadableHeading(mergePage(source, brief, authorityFrontmatter(type, id, title, authority), extra), title));
+    ensureReadableHeading(mergePage(source, brief, authorityFrontmatter(type, id, title, authority), mergedExtra), title));
+}
+
+function renderAssetAuthorityNotice(authority) {
+  const runtimePolicy = clean(authority.runtime_policy);
+  const definitionState = clean(authority.definition_state);
+  const authorityRole = clean(authority.authority_role);
+  const canonical = clean(authority.canonical_asset_id);
+  const lines = [];
+  if (runtimePolicy === 'block') {
+    lines.push('- 召回限制：该资产不能作为直接回答入口。');
+  } else if (runtimePolicy === 'warn') {
+    lines.push('- 召回限制：该资产只能作为辅助线索，回答时需要说明其依赖或待确认边界。');
+  }
+  if (authorityRole === 'dependency_only') {
+    lines.push('- 权威边界：该资产来自依赖闭包，只能支撑承载看板或业务域，不能单独代表正式业务入口。');
+  }
+  if (definitionState === 'conflict') {
+    lines.push('- 口径状态：存在同名或近义资产口径冲突，应优先回到业务域、召回卡或让用户确认。');
+  } else if (definitionState === 'unknown') {
+    lines.push('- 口径状态：定义证据不足，只能作为待核验线索。');
+  }
+  if (canonical) {
+    lines.push(`- 推荐入口：优先使用 \`${canonical}\`，本页只保留来源和排除理由。`);
+  }
+  if (!lines.length) return '';
+  return `## 召回与权威边界\n\n${lines.join('\n')}`;
 }
 
 function mergePage(source, brief, frontmatter, extra = '') {
@@ -525,7 +695,7 @@ function recallAssetLabel(ref) {
 }
 
 function renderRecallCardIndex(cards) {
-  return `# 场景召回卡\n\n首轮召回先使用这里的业务问题与权威资产路由，不直接宽搜全部资产页。\n\n${cards.map((card) => `- [${escapeLink(card.questions?.[0] || card.intent || card.card_id)}](${fileName('recall-card', card.card_id)})（${clean(card.domain_title)}）`).join('\n')}\n`;
+  return `# 场景召回卡\n\n首轮召回先使用这里的业务问题与权威资产路由，不直接宽搜全部资产页。\n\n${cards.map((card) => `- [${escapeLink(card.intent || card.card_id)}](${fileName('recall-card', card.card_id)})（${clean(card.domain_title)}）`).join('\n')}\n`;
 }
 
 function renderAuthorityIndex(rows) {
@@ -555,16 +725,48 @@ function renderGovernanceIndex(conflicts) {
 }
 
 function renderWikiIndex(corpus) {
-  return `---\ntype: project-semantic-knowledge-wiki-index\nsemantic_project_id: ${semanticProjectId}\nproject_name: ${yaml(projectName)}\nsource_snapshot_hash: ${yaml(snapshotHash)}\n---\n\n# ${projectName} 项目语义知识库 Wiki\n\n## 查询顺序\n\n1. [场景召回卡](recall-cards/index.md)\n2. [业务域](domains/index.md)\n3. [看板](dashboards/index.md)、[报表](reports/index.md)、[可复用指标](metrics/index.md)\n4. [分析元数据](metadata/index.md)\n5. [治理与质量](governance/index.md)\n\n技术、演示、副本和定向诊断资产只在[技术附录](technical-appendices/index.md)中追溯。物理空间在[source containers](source-containers/index.md)中保留，不作为业务域。\n\n${countSummary(corpus)}\n`;
+  return `---\ntype: project-semantic-knowledge-wiki-index\nsemantic_project_id: ${semanticProjectId}\nproject_name: ${yaml(projectName)}\nsource_snapshot_hash: ${yaml(snapshotHash)}\n---\n\n# ${projectName} 项目语义知识库 Wiki\n\n## 查询顺序\n\n1. [项目业务模型](project-overview.md)\n2. [场景召回卡](recall-cards/index.md)\n3. [业务域](domains/index.md)\n4. [看板](dashboards/index.md)、[报表](reports/index.md)、[可复用指标](metrics/index.md)\n5. [分析元数据](metadata/index.md)\n6. [治理与质量](governance/index.md)\n\n技术、演示、副本和定向诊断资产只在[技术附录](technical-appendices/index.md)中追溯。物理空间在[source containers](source-containers/index.md)中保留，不作为业务域。\n\n${countSummary(corpus)}\n`;
 }
 
 function renderSnapshotIndex(corpus) {
   const title = String(projectName).replace(/\r?\n/g, ' ').replace(/^#+\s*/, '');
-  return `# ${title} 项目语义知识库 Wiki\n\n这是可导入知识库源文件体系的项目语义 Wiki，共包含 ${corpus.counts.dashboards} 张看板、${corpus.counts.reports} 张报表和 ${corpus.counts.analysis_metadata} 条分析元数据。\n\n## 查询顺序\n\n1. [场景召回卡](wiki/recall-cards/index.md)\n2. [业务域](wiki/domains/index.md)\n3. [看板](wiki/dashboards/index.md)、[报表](wiki/reports/index.md)、[可复用指标](wiki/metrics/index.md)\n4. [分析元数据](wiki/metadata/index.md)\n5. [治理与质量](wiki/governance/index.md)\n\n技术、演示、副本和定向诊断资产只在[技术附录](wiki/technical-appendices/index.md)中追溯。物理空间在[source containers](wiki/source-containers/index.md)中保留，不作为业务域。\n\n${countSummary(corpus)}\n`;
+  return `# ${title} 项目语义知识库 Wiki\n\n这是可导入知识库源文件体系的项目语义 Wiki，共包含 ${corpus.counts.dashboards} 张看板、${corpus.counts.reports} 张报表和 ${corpus.counts.analysis_metadata} 条分析元数据。\n\n## 查询顺序\n\n1. [项目业务模型](wiki/project-overview.md)\n2. [场景召回卡](wiki/recall-cards/index.md)\n3. [业务域](wiki/domains/index.md)\n4. [看板](wiki/dashboards/index.md)、[报表](wiki/reports/index.md)、[可复用指标](wiki/metrics/index.md)\n5. [分析元数据](wiki/metadata/index.md)\n6. [治理与质量](wiki/governance/index.md)\n\n技术、演示、副本和定向诊断资产只在[技术附录](wiki/technical-appendices/index.md)中追溯。物理空间在[source containers](wiki/source-containers/index.md)中保留，不作为业务域。\n\n${countSummary(corpus)}\n`;
 }
 
 function renderProjectOverview(corpus) {
-  return `# ${projectName} 项目语义知识库概览\n\n- Semantic project ID: ${semanticProjectId}\n- Snapshot hash: \`${snapshotHash}\`\n- Asset scope: ${packageAssetScope}\n- Business domains: ${corpus.counts.business_domains}\n- Dashboards: ${corpus.counts.dashboards}\n- Reports: ${corpus.counts.reports}\n- Reusable metrics: ${corpus.counts.reusable_metrics}\n- Metadata: ${corpus.counts.analysis_metadata}\n\nCommon 资产包是权威来源。本 Wiki 将用途总结和精确证据合并为单一页面，不再发布第二套 raw/briefs 语料。\n`;
+  return `# ${projectName} 项目业务模型\n\n${renderProjectBusinessModel(planModel.projectBusinessModel)}\n\n## 资产与治理范围\n\n- Semantic project ID: ${semanticProjectId}\n- Snapshot hash: \`${snapshotHash}\`\n- Asset scope: ${packageAssetScope}\n- Business domains: ${corpus.counts.business_domains}\n- Dashboards: ${corpus.counts.dashboards}\n- Reports: ${corpus.counts.reports}\n- Reusable metrics: ${corpus.counts.reusable_metrics}\n- Metadata: ${corpus.counts.analysis_metadata}\n\nCommon 资产包是权威来源。本 Wiki 将业务判断模型、用途总结和精确证据合并为单一页面，不再发布第二套 raw/briefs 语料。\n`;
+}
+
+function renderProjectBusinessModel(model) {
+  return `## 项目定位\n\n${clean(model.business_positioning)}\n\n## 使用角色\n\n${asArray(model.audience_roles).map((role) => `- ${clean(role)}`).join('\n')}\n\n## 业务对象\n\n${asArray(model.business_objects).map((item) => {
+    const evidence = asArray(item.evidence_refs).map(renderOverviewAssetRef).join('、');
+    return `- ${clean(item.name)}（\`${clean(item.object_id)}\`）：${appendEvidenceSentence(item.meaning, evidence)}`;
+  }).join('\n')}\n\n## 对象关系\n\n${asArray(model.object_relationships).map((item) => {
+    const evidence = asArray(item.evidence_refs).map(renderOverviewAssetRef).join('、');
+    return `- ${clean(item.from_object)} -> ${clean(item.to_object)}：${appendEvidenceSentence(item.relationship, evidence)}`;
+  }).join('\n')}\n\n## 业务判断链路\n\n${asArray(model.decision_chains).map(renderDecisionChain).join('\n\n')}\n\n## 不承载的内容\n\n${asArray(model.non_goals).map((item) => `- ${clean(item)}`).join('\n')}`;
+}
+
+function appendEvidenceSentence(value, evidence) {
+  const body = clean(value).replace(/[。；;，,\s]+$/u, '');
+  return `${body}${evidence ? `。证据：${evidence}` : ''}`;
+}
+
+function renderDecisionChain(chain) {
+  const domains = asArray(chain.preferred_domain_ids)
+    .map((id) => `[\`${clean(id)}\`](domains/${fileName('domain', id)})`).join('、');
+  const assets = asArray(chain.asset_refs).map(renderOverviewAssetRef).join('、');
+  return `### ${clean(chain.title)}\n\n- 判断问题：${stripClausePunctuation(chain.decision_question)}\n- 判断信号：${joinChineseClauses(chain.signals)}\n- 判断步骤：\n${renderNumberedSteps(chain.decision_steps, '  ')}\n- 业务域：${domains || '未指定'}\n- 关联资产：${assets || '未指定'}\n- 实时执行：${chain.requires_live_execution ? '需要' : '不需要'}\n- 边界：${joinChineseClauses(chain.boundaries)}`;
+}
+
+function renderOverviewAssetRef(ref) {
+  const type = clean(ref.resource_type);
+  const key = clean(ref.resource_key);
+  const label = recallAssetLabel(ref);
+  if (type === 'dashboard') return `[${escapeLink(label)}](dashboards/${dashboardFileNames.get(key) ?? fileName('dashboard', key)})`;
+  if (type === 'report') return `[${escapeLink(label)}](reports/${reportFileNames.get(key) ?? fileName('report', key)})`;
+  if (type === 'metric') return `[${escapeLink(label)}](metrics/${metricFileNames.get(key) ?? fileName('metric', key)})`;
+  return `${type}:${key}`;
 }
 
 function renderLog(corpus) {
@@ -744,6 +946,7 @@ function hideMarkdownFrontmatter(root) {
 function assertSnapshotEntryPoint(root) {
   const content = readText(path.join(root, 'index.md'));
   const requiredLinks = [
+    'wiki/project-overview.md',
     'wiki/recall-cards/index.md', 'wiki/domains/index.md', 'wiki/dashboards/index.md',
     'wiki/reports/index.md', 'wiki/metrics/index.md', 'wiki/metadata/index.md',
     'wiki/governance/index.md', 'wiki/technical-appendices/index.md',
@@ -876,6 +1079,7 @@ function writeFlatUploadSources(sourceRoot, targetRoot, replace) {
       const content = precompiledSource(rewriteLinksForFlatUpload(readText(file), rel, relToFlat));
       const contentHash = syncContentHash(content);
       const identity = uploadSourceIdentity(rel, content);
+      const semanticPlanFragmentRefs = semanticPlanFragmentRefsForSource(identity, rel);
       manifestSources.push({
         display_name: flatName,
         file: flatName,
@@ -888,8 +1092,9 @@ function writeFlatUploadSources(sourceRoot, targetRoot, replace) {
         title: firstHeading(content),
         content_hash: contentHash,
         source_path: rel,
+        semantic_plan_fragment_refs: semanticPlanFragmentRefs,
       });
-      writeText(path.join(staging, flatName), `<!--\nkb_source_namespace: ${uploadSourceNamespace}\nsnapshot_date: ${snapshotDate ?? 'null'}\nsnapshot_hash: ${snapshotHash}\nsource_kind: ${identity.source_kind}\nasset_type: ${identity.asset_type ?? 'null'}\nasset_key: ${identity.asset_key ?? 'null'}\ncontent_hash: ${contentHash}\nsource_path: ${rel}\n-->\n\n${content}`);
+      writeText(path.join(staging, flatName), `<!--\nkb_source_namespace: ${uploadSourceNamespace}\nsnapshot_date: ${snapshotDate ?? 'null'}\nsnapshot_hash: ${snapshotHash}\nsource_kind: ${identity.source_kind}\nasset_type: ${identity.asset_type ?? 'null'}\nasset_key: ${identity.asset_key ?? 'null'}\ncontent_hash: ${contentHash}\nsource_path: ${rel}\nsemantic_plan_fragment_refs: ${semanticPlanFragmentRefs.join(',') || 'null'}\n-->\n\n${content}`);
     }
     const manifest = readJson(path.join(sourceRoot, 'manifest.json'));
     const manifestContent = precompiledSource(`# Package manifest\n\n\`\`\`json\n${JSON.stringify(manifest, null, 2)}\n\`\`\`\n`);
@@ -907,8 +1112,9 @@ function writeFlatUploadSources(sourceRoot, targetRoot, replace) {
       title: 'Package manifest',
       content_hash: manifestHash,
       source_path: 'manifest.json',
+      semantic_plan_fragment_refs: [],
     });
-    writeText(path.join(staging, manifestName), `<!--\nkb_source_namespace: ${uploadSourceNamespace}\nsnapshot_date: ${snapshotDate ?? 'null'}\nsnapshot_hash: ${snapshotHash}\nsource_kind: manifest\nasset_type: null\nasset_key: null\ncontent_hash: ${manifestHash}\nsource_path: manifest.json\n-->\n\n${manifestContent}`);
+    writeText(path.join(staging, manifestName), `<!--\nkb_source_namespace: ${uploadSourceNamespace}\nsnapshot_date: ${snapshotDate ?? 'null'}\nsnapshot_hash: ${snapshotHash}\nsource_kind: manifest\nasset_type: null\nasset_key: null\ncontent_hash: ${manifestHash}\nsource_path: manifest.json\nsemantic_plan_fragment_refs: null\n-->\n\n${manifestContent}`);
     writeJson(path.join(staging, 'kb-upload-manifest.json'), {
       schema_version: '1.0',
       manifest_kind: 'ae_project_semantic_kb_upload_sources',
@@ -917,6 +1123,7 @@ function writeFlatUploadSources(sourceRoot, targetRoot, replace) {
       project_name: projectName,
       snapshot_date: snapshotDate,
       snapshot_hash: snapshotHash,
+      semantic_plan_state: semanticPlanState,
       source_count: manifestSources.length,
       sources: manifestSources.sort((a, b) => a.display_name.localeCompare(b.display_name, 'en')),
     });
@@ -940,6 +1147,7 @@ function flatUploadFileName(rel, namespace) {
 function uploadSourceIdentity(rel, content = '') {
   const normalized = rel.replaceAll('\\', '/');
   if (normalized === 'index.md') return { source_kind: 'index', asset_type: null, asset_key: null, file_stem: 'index' };
+  if (normalized === 'refresh-state.md') return { source_kind: 'refresh-state', asset_type: null, asset_key: null, file_stem: 'refresh-state' };
   if (normalized === 'wiki/index.md') return { source_kind: 'index', asset_type: null, asset_key: null, file_stem: 'wiki-index' };
   const match = normalized.match(/^wiki\/([^/]+)\/(.+)\.md$/);
   if (!match) {
@@ -966,6 +1174,108 @@ function uploadSourceIdentity(rel, content = '') {
   return namedUploadSource(section, stem);
 }
 
+function semanticPlanFragmentRefsForSource(identity, rel) {
+  const refs = new Set();
+  const sourceKind = clean(identity.source_kind);
+  const assetType = clean(identity.asset_type);
+  const assetKey = clean(identity.asset_key);
+  if (sourceKind === 'refresh-state') {
+    for (const fragment of semanticPlanState.fragments) refs.add(fragment.id);
+    return [...refs].sort();
+  }
+  if (rel === 'wiki/project-overview.md') refs.add('project:model');
+  if (sourceKind === 'domain' && assetKey) refs.add(`domain:${assetKey}`);
+  if (sourceKind === 'appendix' && assetKey) refs.add(`appendix:${assetKey}`);
+  if (sourceKind === 'recall-card' && assetKey) refs.add(`recall-card:${assetKey}`);
+  if (assetType === 'dashboard' && assetKey) {
+    const domain = domainByDashboardId.get(assetKey);
+    const appendix = appendixByDashboardId.get(assetKey);
+    if (domain) refs.add(`domain:${clean(domain.domain_id)}`);
+    if (appendix) refs.add(`appendix:${clean(appendix.appendix_id)}`);
+  }
+  if (assetType === 'report' && assetKey) {
+    if (planModel.sqlByReportId.has(assetKey)) refs.add(`report:${assetKey}:sql_semantics`);
+    const report = reportById.get(assetKey);
+    for (const dashboardRef of asArray(report?.dashboard_refs)) {
+      const dashboardId = clean(dashboardRef.dashboard_id);
+      const domain = domainByDashboardId.get(dashboardId);
+      const appendix = appendixByDashboardId.get(dashboardId);
+      if (domain) refs.add(`domain:${clean(domain.domain_id)}`);
+      if (appendix) refs.add(`appendix:${clean(appendix.appendix_id)}`);
+    }
+  }
+  if (sourceKind === 'index' && rel === 'wiki/recall-cards/index.md') {
+    for (const card of planModel.cards) refs.add(`recall-card:${clean(card.card_id)}`);
+  }
+  if (sourceKind === 'index' && rel === 'wiki/domains/index.md') {
+    for (const domain of domains) refs.add(`domain:${clean(domain.domain_id)}`);
+  }
+  return [...refs].filter(Boolean).sort();
+}
+
+function buildSemanticPlanState() {
+  const fragments = [];
+  const add = (id, kind, value, fields = {}) => {
+    const fragmentId = clean(id);
+    if (!fragmentId) return;
+    fragments.push({
+      id: fragmentId,
+      kind,
+      ...fields,
+      hash: sha256(stableJson(value)),
+    });
+  };
+  add('project:model', 'project', semanticPlan.project_business_model ?? null);
+  for (const domain of domains) {
+    const id = clean(domain.domain_id);
+    const { recall_cards: _recallCards, ...domainWithoutCards } = asObject(domain);
+    add(`domain:${id}`, 'domain', domainWithoutCards, { domain_id: id });
+    for (const card of asArray(domain.recall_cards)) {
+      const cardId = clean(card.card_id);
+      add(`recall-card:${cardId}`, 'recall-card', { ...asObject(card), domain_id: id }, { card_id: cardId, domain_id: id });
+    }
+  }
+  for (const appendix of appendices) {
+    const id = clean(appendix.appendix_id);
+    add(`appendix:${id}`, 'appendix', appendix, { appendix_id: id });
+  }
+  for (const [reportId, summary] of [...planModel.sqlByReportId.entries()].sort(([left], [right]) => left.localeCompare(right, 'en'))) {
+    add(`report:${reportId}:sql_semantics`, 'sql-report', summary, { report_id: reportId });
+  }
+  fragments.sort((left, right) => left.id.localeCompare(right.id, 'en'));
+  return {
+    schema_version: '1.0',
+    plan_schema_version: clean(semanticPlan.schema_version),
+    plan_hash: sha256(stableJson(semanticPlan)),
+    fragment_count: fragments.length,
+    fragments,
+  };
+}
+
+function renderRefreshState(state) {
+  const payload = {
+    schema_version: '1.0',
+    semantic_plan: semanticPlan,
+    semantic_plan_state: state,
+  };
+  const encoded = Buffer.from(JSON.stringify(payload, null, 2)).toString('base64url');
+  return `# Refresh State
+
+This managed source stores the reusable semantic plan and incremental-refresh state for generated project semantic sources. It is not business evidence.
+
+<!-- pskb_refresh_state_base64
+${encoded}
+-->
+`;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (!value || typeof value !== 'object') return JSON.stringify(value);
+  const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right, 'en'));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`;
+}
+
 function namedUploadSource(kind, stem, resourceKey = '') {
   const key = stem === 'index' ? null : clean(resourceKey) || stem;
   return {
@@ -1027,11 +1337,26 @@ function asObject(value) { return value && typeof value === 'object' && !Array.i
 function indexBy(values, key) { return new Map(values.map((value) => [clean(value[key]), value])); }
 function readText(file) { return fs.readFileSync(file, 'utf8'); }
 function readJson(file) { return JSON.parse(readText(file)); }
+
+function stripClausePunctuation(value) {
+  return clean(value).replace(/[。；;，,\s]+$/u, '');
+}
+
+function joinChineseClauses(value) {
+  const values = asArray(value).map(stripClausePunctuation).filter(Boolean);
+  return values.join('；') || '无';
+}
+
+function renderNumberedSteps(value, indent = '') {
+  const values = asArray(value).map(stripClausePunctuation).filter(Boolean);
+  if (!values.length) return `${indent}- 无`;
+  return values.map((item, index) => `${indent}${index + 1}. ${item}`).join('\n');
+}
 function writeText(file, value) { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, value.endsWith('\n') ? value : `${value}\n`, 'utf8'); }
 function writeJson(file, value) { writeText(file, JSON.stringify(value, null, 2)); }
 function readIndex(name) { return readText(path.join(packageRoot, 'indexes', `${name}.jsonl`)).split(/\r?\n/).filter(Boolean).map(JSON.parse).filter((row) => row.record_type !== 'header'); }
 function listFiles(root) { return fs.readdirSync(root, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? listFiles(path.join(root, entry.name)) : [path.join(root, entry.name)]); }
-function parseArgs(values) { const out = {}; for (let i = 0; i < values.length; i += 1) { const value = values[i]; if (!value.startsWith('--')) fail(`Unexpected argument: ${value}`); const key = value.slice(2); if (['force', 'keep-build-ir', 'allow-all-visible'].includes(key)) out[key] = true; else out[key] = values[++i]; } return out; }
+function parseArgs(values) { const out = {}; for (let i = 0; i < values.length; i += 1) { const value = values[i]; if (!value.startsWith('--')) fail(`Unexpected argument: ${value}`); const key = value.slice(2); if (['force', 'keep-build-ir', 'allow-all-visible', 'allow-semantic-plan-snapshot-drift'].includes(key)) out[key] = true; else out[key] = values[++i]; } return out; }
 function required(values, key) { const value = clean(values[key]); if (!value) fail(`--${key} is required.`); return value; }
 function normalizeUploadSourceNamespace(value) {
   const namespace = slug(clean(value));

package/skills/ae-analysis/scripts/project-semantic-knowledge-wiki/default-compile-rules.md

@@ -7,6 +7,7 @@ These rules guide Schema generation for project semantic knowledge bases built f
 - Treat `sources/README.md` and category `README.md` files as filing guides. They define where future material belongs; they are not business evidence.
 - CLI-managed asset facts live under `sources/assets/**`. Human project background, business rules, meetings, decisions, corrections, and references live outside `sources/assets/**`; asset refresh must not delete or override those human inputs.
 - Organize generated Wiki pages for knowledge consumption, not by mirroring every source file. Use project overview, business domains, reusable semantics, assets, decisions, and review pages.
+- The project overview must start with the project-level business model: business positioning, audience roles, business objects, object relationships, decision chains, asset roles in those chains, and non-goals. Asset counts, snapshot hashes, source package metadata and build logs belong after that model. Do not reduce the overview to a directory, asset inventory, or build summary.
 - Do not infer business meaning from titles alone. Preserve unknowns, conflicts, source scope, certification state, and provenance when evidence is incomplete.
 - Corrections and decisions override other material only when they state target, content, date, status, and applicable scope.
 
@@ -21,10 +22,14 @@ When linking to an individual asset, use its business title as the visible link
 
 CLI Agent has already performed the main semantic compilation for ALL assets: business meanings, SQL interpretation, calculation definitions, relationships, domains, recall boundaries, and conflict findings. These are editable source documents, not an imported final Wiki snapshot. Reuse their complete prose and calculation facts. Do not repeat project-wide extraction, SQL parsing, semantic planning, or per-field rewriting.
 
-Business-domain pages include an `Agent 使用摘要` for first-hop routing. Preserve it as the concise answer source for "what does this domain solve", "which events/metrics are mainly used", and "which dimensions should the agent drill down by". Do not replace it with a raw report list or regenerate it from every report page unless newer scoped evidence explicitly changes the summary.
+Business-domain pages include a judgment model and an `Agent 使用摘要` for first-hop routing. Preserve them as the concise answer source for "what business state does this domain judge", "which objects/signals/decision path should the Agent follow", "which assets are primary/supporting/drilldown/excluded", "what does this domain solve", "which events/metrics are mainly used", and "which dimensions should the agent drill down by". Do not replace them with a raw report list or regenerate them from every report page unless newer scoped evidence explicitly changes the summary.
+
+Reject or repair any generated Wiki shape where the root, overview, or business-domain pages only list questions, events, metrics, dimensions, reports, dashboards or counts without explaining the business judgment chain that makes those assets useful. Examples in source instructions are illustrative only; never hardcode project-specific business domains, assets, metrics, event names or decision chains into the compiled Wiki.
 
 KB must compile and publish the final Wiki: preserve prepared asset sections, map source references to Wiki links, build concise titled navigation, and integrate project background, meetings, decisions and corrections. Batch independent page writes and link checks. Do not read each source repeatedly or regenerate unchanged pages.
 
-For SQL assets, preserve the complete Agent-authored purpose, parameters, output fields, grain, filters, limits, applicable/non-applicable questions and evidence locator in the report page's single `Agent 使用摘要`. Raw SQL/index JSON stays in the local evidence package; do not attempt to fetch it or infer omitted details. Missing facts remain unknown. Preserve certification, dependency-only status, conflicts and blocked recall; do not dismiss safety states as stale placeholders.
+For SQL assets, preserve the complete Agent-authored purpose, parameters, output fields, grain, filters, limits, applicable/non-applicable questions and evidence locator in the report page's single `Agent 使用摘要`. Raw SQL/index JSON stays in the local evidence package; do not attempt to fetch it or infer omitted details. Missing facts remain unknown. Preserve certification, dependency-only status, conflicts and blocked recall; do not dismiss safety states as stale placeholders. Keep build-process markers out of visible Wiki prose: do not expose `CLI Agent`, `摘要来源`, `semantic_plan`, parser fallback labels, or builder/debug terminology as user-facing business content.
+
+For non-SQL report pages, preserve the `Agent 使用摘要` as a usable business routing summary, not a mechanical parser echo. The purpose and applicable-question bullets must not be identical. Metric, dimension and filter sections should preserve structured evidence when present and use source-confirmation wording for unavailable facts. Do not introduce broad placeholder phrases such as `未识别到稳定下钻维度` or `未发现明确过滤` when a safer "open the source report to confirm" boundary is already present.
 
 During incremental compilation, inspect changed sources and their existing dependent pages. Update affected asset pages, indexes and cross-source conclusions; retain unrelated pages. Remove obsolete current assertions when a source changes or is removed. Integrate human evidence according to explicit scope, status and authority, never recency alone. Scope differences belong separately from same-scope contradictions. Preserve provenance to the actual uploaded source.