@thinkingai/ae-cli 6.1.25 → 6.1.27

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

@@ -71,9 +71,12 @@ const dashboards = readIndex('dashboard-catalog');
 const reports = readIndex('report-catalog');
 const metrics = readIndex('metric-catalog');
 const containers = readIndex('asset-containers');
+const adoptedPersonalSemantics = readPackageJsonl('sources/adopted-personal-semantics.jsonl');
+const eventGroups = readOptionalIndex('event-groups');
 const dashboardById = indexBy(dashboards, 'resource_key');
 const reportById = indexBy(reports, 'resource_key');
 const metricById = indexBy(metrics, 'resource_key');
+const adoptedPersonalBySourceId = indexBy(adoptedPersonalSemantics, 'source_id');
 const dashboardFileNames = titleFirstAssetFileMap(dashboards, 'dashboard');
 const reportFileNames = titleFirstAssetFileMap(reports, 'report');
 const metricFileNames = titleFirstAssetFileMap(metrics, 'metric');
@@ -81,6 +84,7 @@ const titleFirstAssetPathMap = titleFirstAssetPathRewrites();
 const containerById = indexBy(containers, 'container_key');
 const domains = asArray(semanticPlan.domains);
 const appendices = asArray(semanticPlan.appendices);
+const personalSemanticIntegrations = asArray(semanticPlan.personal_semantic_integrations);
 const domainByDashboardId = new Map();
 const appendixByDashboardId = new Map();
 for (const domain of domains) for (const id of asArray(domain.dashboard_ids).map(clean)) domainByDashboardId.set(id, domain);
@@ -110,8 +114,11 @@ try {
     const wikiRoot = path.join(staging, 'wiki');
     for (const directory of [
       'domains', 'technical-appendices', 'source-containers', 'dashboards', 'reports', 'metrics',
-      'metadata', 'recall-cards', 'governance',
+      'metadata', 'recall-cards', 'personal-semantics', 'governance', 'common', 'event-map', 'asset-index',
     ]) fs.mkdirSync(path.join(wikiRoot, directory), { recursive: true });
+    for (const type of ['background', 'preference', 'experience', 'asset-context']) {
+      fs.mkdirSync(path.join(wikiRoot, 'personal-semantics', type), { recursive: true });
+    }
 
     for (const metadataType of fs.readdirSync(path.join(buildIr, 'metadata'), { withFileTypes: true })
       .filter((entry) => entry.isDirectory()).map((entry) => entry.name)) {
@@ -125,7 +132,8 @@ try {
       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`);
+          + `\n## 场景召回卡\n\n${cardLinks || '- 无'}\n`
+          + renderTargetedKnowledge('domain', id, '../personal-semantics/'));
     }
 
     for (const appendix of appendices) {
@@ -185,7 +193,7 @@ try {
     }
 
     copyIndex(path.join(buildIr, 'dashboards', 'index.md'), path.join(wikiRoot, 'dashboards', 'index.md'));
-    copyIndex(path.join(buildIr, 'reports', 'index.md'), path.join(wikiRoot, 'reports', 'index.md'));
+    writeText(path.join(wikiRoot, 'reports', 'index.md'), renderReportIndex());
     copyIndex(path.join(buildIr, 'metrics', 'index.md'), path.join(wikiRoot, 'metrics', 'index.md'));
     copyIndex(path.join(buildIr, 'metadata', 'index.md'), path.join(wikiRoot, 'metadata', 'index.md'));
 
@@ -194,12 +202,29 @@ try {
     }
     writeText(path.join(wikiRoot, 'recall-cards', 'index.md'), renderRecallCardIndex(planModel.cards));
 
+    writeText(path.join(wikiRoot, 'common', 'index.md'), renderCommonIndex());
+    writeText(path.join(wikiRoot, 'asset-index', 'index.md'), renderAssetIndex());
+    writeEventMap(wikiRoot, buildIr);
+
+    for (const integration of planModel.personalSemanticIntegrations) {
+      const contextPath = personalSemanticContextPath(integration.context_type);
+      writeText(path.join(wikiRoot, 'personal-semantics', contextPath,
+        fileName('personal-semantic', integration.integration_id)), renderPersonalSemanticIntegration(integration));
+    }
+    writeText(path.join(wikiRoot, 'personal-semantics', 'index.md'),
+      renderPersonalSemanticIndex(planModel.personalSemanticIntegrations));
+    for (const type of ['background', 'preference', 'experience', 'asset_context']) {
+      writeText(path.join(wikiRoot, 'personal-semantics', personalSemanticContextPath(type), 'index.md'),
+        renderPersonalSemanticTypeIndex(type, planModel.personalSemanticIntegrations));
+    }
+
     const coverage = readText(path.join(buildIr, 'indexes', 'coverage.md'))
       .replaceAll('../appendices/', '../technical-appendices/')
       .replaceAll('../briefs/reports/', '../reports/')
       .replaceAll('../briefs/metadata/', '../metadata/');
     writeText(path.join(wikiRoot, 'governance', 'coverage.md'), coverage);
     writeText(path.join(wikiRoot, 'governance', 'authority-index.md'), renderAuthorityIndex(authorityRows));
+    writeText(path.join(wikiRoot, 'governance', 'knowledge-adoption.md'), renderKnowledgeAdoptionIndex());
     writeText(path.join(wikiRoot, 'governance', 'index.md'), renderGovernanceIndex(conflictReportIds.size));
     writeText(path.join(wikiRoot, 'governance', 'source-project-boundary.md'), renderSourceProjectBoundary(sourceProjectReferencesFromPackage()));
     writeText(path.join(wikiRoot, 'project-overview.md'), renderProjectOverview(corpus));
@@ -226,9 +251,13 @@ try {
       semantic_plan_fragment_count: semanticPlanState.fragments.length,
       asset_package_schema_version: '3.0',
       asset_scope: packageAssetScope,
-      wiki_schema_version: '1.0',
+      wiki_schema_version: '2.0',
+      navigation_taxonomy_version: '2.1',
       generated_at: descriptor.generated_at ?? packageManifest.generated_at ?? null,
-      counts: { ...corpus.counts, recall_cards: planModel.cards.length, blocked_assets: blockedCount, unknown_sql_reports: unknownSqlCount },
+      counts: { ...corpus.counts, recall_cards: planModel.cards.length,
+        adopted_personal_semantics: adoptedPersonalSemantics.length,
+        personal_semantic_integrations: planModel.personalSemanticIntegrations.length,
+        blocked_assets: blockedCount, unknown_sql_reports: unknownSqlCount },
       quality_warnings: [...asArray(corpus.warnings),
         ...(sourceProjectRefs.filter((row) => Number(row.source_project_id) !== semanticProjectId).length
           ? [`${sourceProjectRefs.filter((row) => Number(row.source_project_id) !== semanticProjectId).length} packaged asset reference(s) mention another project: ${sourceProjectRefs.filter((row) => Number(row.source_project_id) !== semanticProjectId).slice(0, 5).map((row) => `${row.resource_type}:${row.resource_key}->${row.source_project_id}`).join(', ')}`] : []),
@@ -304,6 +333,25 @@ function validateSemanticPlan() {
         if (!inDomain) fail(`Recall card ${cardId} references ${type}:${key} outside domain ${domainId}.`);
         if (preferred.includes(ref)) addMulti(preferredByAsset, `${type}:${key}`, cardId);
       }
+      const routing = asObject(card.routing);
+      if (card.routing != null) {
+        for (const field of ['applicable_when', 'answer_grain', 'stop_when', 'fallback_when_unavailable', 'evidence_boundary']) {
+          if (!clean(routing[field])) fail(`Recall card ${cardId} routing requires ${field}.`);
+        }
+        if (!asArray(routing.branches).length) fail(`Recall card ${cardId} routing requires branches.`);
+        for (const branch of asArray(routing.branches)) {
+          if (!clean(branch.when) || !asArray(branch.asset_refs).length) {
+            fail(`Recall card ${cardId} routing branch requires when and asset_refs.`);
+          }
+          for (const ref of asArray(branch.asset_refs)) {
+            validateAssetRef(ref, cardId);
+            if (![...preferred, ...asArray(card.fallback_asset_refs)].some((allowed) =>
+              clean(allowed.resource_type) === clean(ref.resource_type) && clean(allowed.resource_key) === clean(ref.resource_key))) {
+              fail(`Recall card ${cardId} routing branch references an asset outside preferred/fallback refs.`);
+            }
+          }
+        }
+      }
       for (const ref of asArray(card.excluded_asset_refs)) {
         validateAssetRef(ref, cardId);
         if (!clean(ref.reason)) fail(`Recall card ${cardId} excluded asset ${clean(ref.resource_key)} is missing a reason.`);
@@ -344,9 +392,11 @@ function validateSemanticPlan() {
   if (missingSql.length && !allowAllVisible) {
     fail(`Semantic plan is missing SQL semantics for ${missingSql.length} report(s): ${missingSql.join(', ')}`);
   }
+  const personalIntegrations = validatePersonalSemanticIntegrations(domainIds, cardIds);
 
   return {
     cards,
+    personalSemanticIntegrations: personalIntegrations,
     excludedByAsset,
     preferredByAsset,
     sqlByReportId,
@@ -355,6 +405,73 @@ function validateSemanticPlan() {
   };
 }
 
+function validatePersonalSemanticIntegrations(domainIds, cardIds) {
+  const integrationIds = new Set();
+  const referencedSourceIds = new Set();
+  const integrations = [];
+  for (const [index, value] of personalSemanticIntegrations.entries()) {
+    const row = asObject(value);
+    const integrationId = clean(row.integration_id);
+    if (!/^[a-z0-9][a-z0-9_-]{1,79}$/.test(integrationId) || integrationIds.has(integrationId)) {
+      fail(`Invalid or duplicate personal semantic integration ID: ${integrationId || `<index ${index}>`}.`);
+    }
+    integrationIds.add(integrationId);
+    const contextType = normalizePersonalSemanticContextType(row.context_type);
+    const sourceIds = asArray(row.source_ids).map(clean).filter(Boolean);
+    if (!sourceIds.length) fail(`Personal semantic integration ${integrationId} requires source_ids.`);
+    for (const sourceId of sourceIds) {
+      const source = adoptedPersonalBySourceId.get(sourceId);
+      if (!source) fail(`Personal semantic integration ${integrationId} references unknown source ${sourceId}.`);
+      if (normalizePersonalSemanticContextType(source.context_type) !== contextType) {
+        fail(`Personal semantic integration ${integrationId} mixes context_type ${contextType} with source ${sourceId}:${source.context_type}.`);
+      }
+      referencedSourceIds.add(sourceId);
+    }
+    const title = clean(row.title);
+    const projectUsage = clean(row.project_usage);
+    const boundaries = asArray(row.boundaries).map(clean).filter(Boolean);
+    const conflictPolicy = clean(row.conflict_policy);
+    if (!title || !projectUsage) fail(`Personal semantic integration ${integrationId} requires title and project_usage.`);
+    if (!['compatible', 'scoped', 'blocked'].includes(conflictPolicy)) {
+      fail(`Personal semantic integration ${integrationId} has invalid conflict_policy.`);
+    }
+    if (!boundaries.length) fail(`Personal semantic integration ${integrationId} requires boundaries.`);
+    const target = validatePersonalSemanticIntegrationTarget(row.integration_target, integrationId, domainIds, cardIds);
+    integrations.push({ ...row, integration_id: integrationId, context_type: contextType,
+      source_ids: sourceIds, title, project_usage: projectUsage, boundaries, conflict_policy: conflictPolicy,
+      integration_target: target });
+  }
+  const missing = adoptedPersonalSemantics
+    .map((source) => clean(source.source_id))
+    .filter((sourceId) => sourceId && !referencedSourceIds.has(sourceId));
+  if (missing.length) {
+    fail(`Semantic plan is missing adopted personal semantic source(s): ${missing.join(', ')}`);
+  }
+  return integrations;
+}
+
+function validatePersonalSemanticIntegrationTarget(value, integrationId, domainIds, cardIds) {
+  const target = asObject(value);
+  const type = clean(target.target_type);
+  const id = clean(target.target_id);
+  if (!['project', 'domain', 'asset', 'recall_card'].includes(type)) {
+    fail(`Personal semantic integration ${integrationId} has invalid integration_target.target_type.`);
+  }
+  if (type === 'project') return { target_type: type, target_id: id || 'project' };
+  if (!id) fail(`Personal semantic integration ${integrationId} target ${type} requires target_id.`);
+  if (type === 'domain' && !domainIds.has(id)) fail(`Personal semantic integration ${integrationId} references unknown domain ${id}.`);
+  if (type === 'recall_card' && !cardIds.has(id)) fail(`Personal semantic integration ${integrationId} references unknown recall card ${id}.`);
+  if (type === 'asset') {
+    const [assetType, assetKey] = id.includes(':') ? id.split(/:(.*)/s).filter(Boolean) : ['', id];
+    const exists = assetType === 'dashboard' ? dashboardById.has(assetKey)
+      : assetType === 'report' ? reportById.has(assetKey)
+        : assetType === 'metric' ? metricById.has(assetKey)
+          : dashboardById.has(assetKey) || reportById.has(assetKey) || metricById.has(assetKey);
+    if (!exists) fail(`Personal semantic integration ${integrationId} references unknown asset target ${id}.`);
+  }
+  return { target_type: type, target_id: id };
+}
+
 function validateProjectBusinessModel(value, domainIds) {
   const model = asObject(value);
   const businessPositioning = clean(model.business_positioning);
@@ -579,7 +696,7 @@ function writeMergedAsset(wikiRoot, directory, asset, authority, extra = '') {
   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');
+  const mergedExtra = [authorityNotice, extra.trim(), renderTargetedKnowledge('asset', `${directory.slice(0, -1)}:${id}`, '../personal-semantics/')].filter(Boolean).join('\n\n');
   writeText(path.join(wikiRoot, directory, assetOutputFileName(directory, id)),
     ensureReadableHeading(mergePage(source, brief, authorityFrontmatter(type, id, title, authority), mergedExtra), title));
 }
@@ -635,6 +752,12 @@ ${asArray(values).map((ref) => {
     const linkPath = assetPath(clean(ref.resource_type), clean(ref.resource_key));
     return `- [${escapeLink(recallAssetLabel(ref))}](${linkPath})：${clean(ref.reason)}`;
   }).join('\n') || '- 无'}`;
+  const routing = asObject(card.routing);
+  const branches = asArray(routing.branches).map((branch) => {
+    const item = asObject(branch);
+    const targets = asArray(item.asset_refs).map(recallAssetLabel).join('、') || '回到业务域核对资产';
+    return `- 当${clean(item.when)}：使用 ${targets}。${clean(item.reason)}`;
+  });
   return `---
 type: project-semantic-recall-card
 card_id: ${yaml(card.card_id)}
@@ -662,12 +785,15 @@ ${alternateQuestions.map((value) => `- ${value}`).join('\n') || '- 同页面标
 
 ${clean(card.intent)}
 
-## Agent 执行顺序
+## 条件路由与停止
 
-1. 先进入首选资产确认业务范围、指标和维度。
-2. 首选资产不足以回答时，再使用备选资产补充证据。
-3. 排除资产只用于解释为什么不采用，不能作为当前问题的主要答案来源。
-4. 需要当前数值、客户名单、趋势或明细时，必须实时执行报表/查询。
+- 适用条件：${clean(routing.applicable_when) || clean(card.intent)}
+- 答案对象与粒度：${clean(routing.answer_grain) || '先按用户问法确认对象、统计粒度与时间范围。'}
+- 必要参数：${asArray(routing.required_parameters).map(clean).filter(Boolean).join('、') || '按首选资产的输入定义核对。'}
+${branches.join('\n') || `- 问法和资产定义匹配时使用首选资产；不匹配时先回到业务域确认对象与口径，再考虑备选资产。`}
+- 停止条件：${clean(routing.stop_when) || '取得对象、粒度、范围、时间和权威状态均匹配的最小证据后停止扩搜。'}
+- 无匹配或不可用时：${clean(routing.fallback_when_unavailable) || '回到业务域按对象、粒度、过滤和时间筛选域内资产；仍不匹配则说明缺口。'}
+- 执行边界：${clean(routing.evidence_boundary) || '排除资产不能作为当前答案；当前数值、客户名单、趋势或明细必须实时执行。'}
 
 ${refs(card.preferred_asset_refs, '首选资产')}
 
@@ -679,6 +805,7 @@ ${refs(card.excluded_asset_refs, '排除资产')}
 
 - 是否需要执行实时数据：${Boolean(card.requires_live_execution)}
 - 原因：${clean(card.live_execution_reason) || '未说明'}
+${renderTargetedKnowledge('recall_card', clean(card.card_id), '../personal-semantics/')}
 `;
 }
 
@@ -695,11 +822,140 @@ function recallAssetLabel(ref) {
 }
 
 function renderRecallCardIndex(cards) {
-  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`;
+  return `# 场景召回卡\n\n先按问法、对象、粒度和参数选择匹配的卡；卡内按条件分支找到最小证据并在满足停止条件后停止。无匹配卡时，回到[业务领域](../domains/index.md)，按对象、粒度、过滤和时间筛选域内资产；仍无可用资产时说明具体缺口。\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 renderReportIndex() {
+  const assigned = new Set();
+  const sections = domains.map((domain) => {
+    const dashboardIds = new Set(asArray(domain.dashboard_ids).map(clean));
+    const matching = reports.filter((report) => asArray(report.dashboard_refs)
+      .some((ref) => dashboardIds.has(clean(ref.dashboard_id))))
+      .sort((a, b) => clean(a.resource_key).localeCompare(clean(b.resource_key), 'en'));
+    for (const report of matching) assigned.add(clean(report.resource_key));
+    const questions = asArray(domain.primary_questions).map(clean).filter(Boolean);
+    const cards = asArray(domain.recall_cards)
+      .map((card) => `- 问题入口：[${escapeLink(clean(card.questions?.[0]) || clean(card.intent))}](../recall-cards/${fileName('recall-card', card.card_id)})`);
+    return `## ${clean(domain.title)}\n\n- 业务问题：${questions.join('；') || clean(domain.summary)}\n- [领域判断](../domains/${fileName('domain', domain.domain_id)})\n${cards.join('\n')}\n${matching.map((report) => `- [${escapeLink(assetReadableTitle(report, 'report'))}](${reportFileNames.get(clean(report.resource_key))})（report:${clean(report.resource_key)}）`).join('\n') || '- 本快照无该域报表，按领域页核对其他资产。'}\n`;
+  });
+  const unassigned = reports.filter((report) => !assigned.has(clean(report.resource_key)))
+    .sort((a, b) => clean(a.resource_key).localeCompare(clean(b.resource_key), 'en'));
+  return `# 报表\n\n先按业务问题选择领域或场景，再核对报表的对象、粒度、过滤和时间。点名报表时可直接进入报表页；未归属报表不自动视为业务入口。\n\n${sections.join('\n')}\n## 其他与未归属报表\n\n${unassigned.map((report) => `- [${escapeLink(assetReadableTitle(report, 'report'))}](${reportFileNames.get(clean(report.resource_key))})（report:${clean(report.resource_key)}）`).join('\n') || '- 无'}\n`;
+}
+
+function renderPersonalSemanticIntegration(integration) {
+  const sourceRows = integration.source_ids.map((sourceId) => adoptedPersonalBySourceId.get(sourceId)).filter(Boolean);
+  const provenanceRows = sourceRows.map((source) => {
+    const payload = asObject(source.payload);
+    return `| \`${clean(source.source_id)}\` | ${escapeTable(personalSemanticOwnerName(payload))} | ${escapeTable(formatPersonalSemanticTime(payload.updated_at ?? source.updated_at))} | ${escapeTable(payload.heat_count)} |`;
+  }).join('\n');
+  const sourceSummaries = sourceRows.map((source) => {
+    const payload = asObject(source.payload);
+    return `### ${clean(payload.title) || clean(source.source_id)}\n\n- Source ID: \`${clean(source.source_id)}\`\n- 来源人：${personalSemanticOwnerName(payload)}\n- 更新时间：${formatPersonalSemanticTime(payload.updated_at ?? source.updated_at)}\n- 热度：${clean(payload.heat_count) || '0'}\n- 摘要：${clean(payload.summary) || 'unknown'}\n- 内容：${clean(payload.content) || 'unknown'}\n- 关键词：${asArray(payload.keywords).map(clean).filter(Boolean).join('、') || '无'}\n- 资源引用：${renderPersonalSemanticResourceRefs(payload.resource_refs)}\n`;
+  }).join('\n');
+  return `---\ntype: project-semantic-personal-integration\nsemantic_project_id: ${semanticProjectId}\nintegration_id: ${yaml(integration.integration_id)}\ncontext_type: ${yaml(integration.context_type)}\nsource_snapshot_hash: ${yaml(snapshotHash)}\ntarget_type: ${yaml(integration.integration_target.target_type)}\ntarget_id: ${yaml(integration.integration_target.target_id)}\nconflict_policy: ${yaml(integration.conflict_policy)}\n---\n\n# ${clean(integration.title)}\n\n## Agent 使用摘要\n\n- 类型：${personalSemanticContextLabel(integration.context_type)}\n- 项目用法：${clean(integration.project_usage)}\n- 作用目标：${renderPersonalSemanticTarget(integration.integration_target)}\n- 冲突策略：${clean(integration.conflict_policy)}\n- 边界：${joinChineseClauses(integration.boundaries)}\n\n## 来源\n\n| Source ID | 来源人 | 更新时间 | 热度 |\n| --- | --- | --- | ---: |\n${provenanceRows || '| - | - | - | - |'}\n\n## 原始个人语义摘要\n\n${sourceSummaries || '无'}\n`;
+}
+
+function personalSemanticOwnerName(payload) {
+  return clean(payload.owner_name) || clean(payload.owner_display_name) || '未知用户';
+}
+
+function renderPersonalSemanticIndex(integrations) {
+  const rows = integrations
+    .slice()
+    .sort((left, right) => `${left.context_type}:${left.integration_id}`.localeCompare(`${right.context_type}:${right.integration_id}`, 'en'));
+  return `# 知识采纳记录\n\n已采纳的补充知识按目标写入项目、业务领域、场景或资产页；这里保留来源和适用边界以便追溯。\n\n- [背景](background/index.md)\n- [偏好](preference/index.md)\n- [经验](experience/index.md)\n- [资产上下文](asset-context/index.md)\n\n## 采纳项\n\n${rows.map((row) => `- [${escapeLink(row.title)}](${personalSemanticContextPath(row.context_type)}/${fileName('personal-semantic', row.integration_id)})：${personalSemanticContextLabel(row.context_type)}，${clean(row.project_usage)}`).join('\n') || '- 无已采纳补充知识。'}\n`;
+}
+
+function renderTargetedKnowledge(type, id, relativeRoot) {
+  const rows = planModel.personalSemanticIntegrations.filter((integration) => {
+    const target = integration.integration_target;
+    if (target.target_type !== type) return false;
+    if (type !== 'asset') return target.target_id === id;
+    return target.target_id === id || target.target_id === id.split(':')[1];
+  });
+  if (!rows.length) return '';
+  return `\n## 项目补充知识\n\n${rows.map((row) => `- [${escapeLink(row.title)}](${relativeRoot}${personalSemanticContextPath(row.context_type)}/${fileName('personal-semantic', row.integration_id)})：${clean(row.project_usage)}；适用边界：${joinChineseClauses(row.boundaries)}`).join('\n')}\n`;
+}
+
+function renderKnowledgeAdoptionIndex() {
+  return `# 知识采纳记录\n\n[查看已采纳补充知识及来源](../personal-semantics/index.md)。内容按适用目标进入项目、领域、场景和资产页；个人偏好只在声明的范围内生效。\n`;
+}
+
+function renderCommonIndex() {
+  const model = planModel.projectBusinessModel;
+  const objects = asArray(model.business_objects).map((row) => `- **${clean(row.name)}**：${clean(row.meaning)}`).join('\n');
+  const relationships = asArray(model.object_relationships).map((row) => `- ${clean(row.from_object)} → ${clean(row.to_object)}：${clean(row.relationship)}`).join('\n');
+  const supplements = planModel.personalSemanticIntegrations.filter((row) => row.integration_target.target_type === 'project')
+    .map((row) => `- [${escapeLink(row.title)}](../personal-semantics/${personalSemanticContextPath(row.context_type)}/${fileName('personal-semantic', row.integration_id)})：${clean(row.project_usage)}；适用边界：${joinChineseClauses(row.boundaries)}`).join('\n');
+  return `# 项目共识\n\n这里收录跨业务领域适用的项目对象、关系与已采纳补充知识。领域特有的判断方法保留在对应领域页。\n\n## 共同业务对象\n\n${objects || '- 无。'}\n\n## 对象关系\n\n${relationships || '- 无。'}\n\n## 跨领域补充知识\n\n${supplements || '- 暂无。'}\n\n[查看完整项目判断链路](../project-overview.md#业务判断链路)。\n`;
+}
+
+function renderAssetIndex() {
+  return `# 事件与资产目录\n\n事件公共分组帮助按产品模块找到事件；分组名称本身不定义业务领域或认证状态。业务含义以领域判断和事件定义为准。\n\n- [事件地图](../event-map/index.md)\n- [看板](../dashboards/index.md)\n- [报表](../reports/index.md)\n- [可复用指标](../metrics/index.md)\n- [分析元数据](../metadata/index.md)\n`;
+}
+
+function writeEventMap(wikiRoot, buildIrRoot) {
+  const eventPages = new Map();
+  const eventsDir = path.join(buildIrRoot, 'metadata', 'events');
+  if (fs.existsSync(eventsDir)) for (const name of fs.readdirSync(eventsDir).filter((item) => item.endsWith('.md'))) {
+    const content = readText(path.join(eventsDir, name));
+    const key = frontmatterValue(content, 'resource_key');
+    if (key) eventPages.set(key, name);
+  }
+  const groups = eventGroups.filter((group) => clean(group.catalog_scope) === 'project_public');
+  const seen = new Set();
+  const links = [];
+  for (const group of groups) {
+    const name = clean(group.group_name);
+    if (!name || seen.has(name)) fail(`Duplicate or empty public event group: ${name || '<empty>'}.`);
+    seen.add(name);
+    const members = asArray(group.events).filter((event) => eventPages.has(clean(event.event_name)));
+    if (!members.length) continue;
+    const file = fileName('event-group', `group-${name}-${sha256(name).slice(0, 8)}`);
+    links.push(`- [${escapeLink(name)}](${file})（${members.length} 个已导出事件）`);
+    writeText(path.join(wikiRoot, 'event-map', file), `# ${name}\n\n来源：项目公共事件目录。此分组仅用于查找事件，不自动定义业务领域或事件认证状态。\n\n${members.map((event) => `- [${escapeLink(clean(event.event_title) || clean(event.event_name))}（\`${clean(event.event_name)}\`）](../metadata/events/${eventPages.get(clean(event.event_name))})`).join('\n')}\n`);
+  }
+  writeText(path.join(wikiRoot, 'event-map', 'index.md'), `# 事件地图\n\n按项目公共事件分组查找已纳入资产包的事件。未纳入当前资产范围的事件不会在这里出现；事件分组不等于业务领域。\n\n${links.join('\n') || '- 当前资产范围内没有可展示的公共事件分组。'}\n\n[按元数据类型查找事件](../metadata/index.md)。\n`);
+}
+
+function renderPersonalSemanticTypeIndex(type, integrations) {
+  const normalized = normalizePersonalSemanticContextType(type);
+  const rows = integrations.filter((row) => normalizePersonalSemanticContextType(row.context_type) === normalized)
+    .sort((left, right) => left.integration_id.localeCompare(right.integration_id, 'en'));
+  return `# ${personalSemanticContextLabel(normalized)}\n\n${personalSemanticContextUsage(normalized)}\n\n${rows.map((row) => `- [${escapeLink(row.title)}](${fileName('personal-semantic', row.integration_id)})：${clean(row.project_usage)}`).join('\n') || '- 暂无。'}\n`;
+}
+
+function renderPersonalSemanticTarget(target) {
+  const type = clean(target.target_type);
+  const id = clean(target.target_id);
+  if (type === 'domain') return `业务域 \`${id}\``;
+  if (type === 'recall_card') return `召回卡 \`${id}\``;
+  if (type === 'asset') return `资产 \`${id}\``;
+  return '项目整体';
+}
+
+function renderPersonalSemanticResourceRefs(value) {
+  const refs = asArray(value).map(asObject).map((ref) => {
+    const type = clean(ref.resource_type);
+    const key = clean(ref.resource_key);
+    return type && key ? `${type}:${key}` : clean(ref);
+  }).filter(Boolean);
+  return refs.join('、') || '无';
+}
+
+function formatPersonalSemanticTime(value) {
+  const text = clean(value);
+  if (!text) return 'unknown';
+  if (/^\d{12,}$/.test(text)) {
+    const date = new Date(Number(text));
+    if (!Number.isNaN(date.getTime())) return date.toISOString().replace('T', ' ').replace('.000Z', ' UTC');
+  }
+  return text;
 }
 
 function renderAuthorityIndex(rows) {
-  return `# 资产权威状态\n\n## Agent 判定规则\n\n- \`runtime_policy=allow\`：可以作为主要答案依据，但当前数值仍需实时执行。\n- \`runtime_policy=warn\`：只能作为依赖或辅助线索，回答时需要说明它不是独立召回入口。\n- \`runtime_policy=block\`：不能直接回答，必须回到 canonical 资产、业务域或等待资产作者确认。\n- \`authority_role=dependency_only\`：只在报表/指标引用时使用，不能单独作为业务入口。\n- \`definition_state=conflict\` 或 \`unknown\`：不要断言精确口径，只能描述已知证据和待确认点。\n\n| 类型 | 资产 | Authority role | Certification | Definition | Runtime | Standalone recall | Canonical |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n${rows.sort((a, b) => `${a.resource_type}:${a.resource_key}`.localeCompare(`${b.resource_type}:${b.resource_key}`, 'en')).map((row) => `| ${row.resource_type} | \`${row.resource_key}\` ${escapeTable(row.title)} | ${row.authority_role} | ${row.certification_state} | ${row.definition_state} | ${row.runtime_policy} | ${row.standalone_recall} | ${row.canonical_asset_id ?? '-'} |`).join('\n')}\n`;
+  return `# 资产权威状态\n\n## Agent 判定规则\n\n- \`runtime_policy=allow\`：可以作为主要答案依据，但当前数值仍需实时执行。\n- \`runtime_policy=warn\`：只能作为依赖或辅助线索，回答时需要说明它不是独立召回入口。\n- \`runtime_policy=block\`：不能直接回答，必须回到 canonical 资产、业务域或等待资产作者确认。\n- \`authority_role=dependency_only\`：定义、依赖关系或冲突解释可以引用已知元数据；不能单独据此断言业务状态或当前数值。平台禁止直接检索时回到授权引用资产。\n- \`definition_state=conflict\` 或 \`unknown\`：不要断言精确口径，只能描述已知证据和待确认点。\n\n| 类型 | 资产 | Authority role | Certification | Definition | Runtime | Standalone recall | Canonical |\n| --- | --- | --- | --- | --- | --- | --- | --- |\n${rows.sort((a, b) => `${a.resource_type}:${a.resource_key}`.localeCompare(`${b.resource_type}:${b.resource_key}`, 'en')).map((row) => `| ${row.resource_type} | \`${row.resource_key}\` ${escapeTable(row.title)} | ${row.authority_role} | ${row.certification_state} | ${row.definition_state} | ${row.runtime_policy} | ${row.standalone_recall} | ${row.canonical_asset_id ?? '-'} |`).join('\n')}\n`;
 }
 
 function renderSourceProjectBoundary(rows) {
@@ -721,20 +977,20 @@ ${external.map((row) => `| ${row.resource_type}:${row.resource_key} ${escapeTabl
 }
 
 function renderGovernanceIndex(conflicts) {
-  return `# 治理与质量\n\n- [资产权威状态](authority-index.md)\n- [覆盖、物理来源与未归属资产](coverage.md)\n- [项目来源边界](source-project-boundary.md)\n\n## Agent 使用方式\n\n- 回答前先看资产页 frontmatter 的 \`runtime_policy\`、\`definition_state\` 和 \`authority_role\`。\n- \`runtime_policy=block\` 的资产不能直接回答；如果存在 canonical 资产，优先跳转到 canonical。\n- \`dependency_only\` 元数据只解释报表/指标依赖，不单独发起召回。\n- 语义冲突表示多个资产表达同一业务含义但口径不同，不能只凭名称选择资产；优先使用业务域、召回卡或用户确认。\n- 项目来源边界用于识别资产包里引用了其他项目 ID 的字段；跨项目引用只能作为来源线索，不代表当前项目事实。\n\n当前检测到 ${conflicts} 张语义冲突报表。\n`;
+  return `# 治理与来源\n\n- [知识采纳记录](knowledge-adoption.md)\n- [资产权威状态](authority-index.md)\n- [覆盖、物理来源与未归属资产](coverage.md)\n- [项目来源边界](source-project-boundary.md)\n\n## Agent 使用方式\n\n- 回答前先看资产页 frontmatter 的 \`runtime_policy\`、\`definition_state\` 和 \`authority_role\`。\n- \`runtime_policy=block\` 的资产不能直接回答；如果存在 canonical 资产，优先跳转到 canonical。\n- \`dependency_only\` 元数据可用于有证据的定义、依赖和冲突解释；不能据此单独回答业务状态或当前数值。\n- 语义冲突表示多个资产表达同一业务含义但口径不同，不能只凭名称选择资产；优先使用业务域、召回卡或用户确认。\n- 项目来源边界用于识别资产包里引用了其他项目 ID 的字段；跨项目引用只能作为来源线索，不代表当前项目事实。\n\n当前检测到 ${conflicts} 张语义冲突报表。\n`;
 }
 
 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. [项目业务模型](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`;
+  return `---\ntype: project-semantic-knowledge-wiki-index\nsemantic_project_id: ${semanticProjectId}\nproject_name: ${yaml(projectName)}\nsource_snapshot_hash: ${yaml(snapshotHash)}\nnavigation_taxonomy_version: "2.1"\n---\n\n# ${projectName} 项目语义知识库 Wiki\n\n## 问题意图路由\n\n- 业务判断或当前数值：先选[业务领域](domains/index.md)及其[场景召回卡](recall-cards/index.md)，按对象、粒度、参数选择分支并实时执行。\n- 点名资产、字段定义或依赖关系：从[事件与资产目录](asset-index/index.md)定位资产，再核对[治理与来源](governance/index.md)；依赖元数据可解释定义与关系，但不能单独证明业务状态。\n- 产品机制或共同背景：先读[项目共识](common/index.md)，再进入相关业务域。\n- 无匹配场景卡：进入相关业务域，按对象、粒度、过滤和时间筛选域内资产；仍无合适资产就说明缺口，不编造答案。\n- 已取得对象、粒度、时间、范围和权威性匹配的最小证据后停止扩搜；需要当前值时按权限执行。\n\n## 知识导航\n\n1. [项目总览](project-overview.md)：项目定位、对象关系和判断链路。\n2. [项目共识](common/index.md)：跨领域适用的知识。\n3. [业务领域](domains/index.md)：按业务问题进入判断路径和证据。\n4. [事件与资产目录](asset-index/index.md)：按事件公共分组或资产类型查找。\n5. [治理与来源](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/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`;
+  return `# ${title} 项目语义知识库 Wiki\n\n## 问题意图路由\n\n- 业务判断或当前数值：先选[业务领域](wiki/domains/index.md)和匹配的[场景召回卡](wiki/recall-cards/index.md)，按对象、粒度和参数选择分支。\n- 点名资产、字段定义或依赖关系：从[事件与资产目录](wiki/asset-index/index.md)定位，再核对[治理与来源](wiki/governance/index.md)。\n- 产品机制或共同背景：先读[项目共识](wiki/common/index.md)。\n- 无匹配场景卡：回到相关业务域，按对象、粒度、过滤和时间筛选；仍无合适资产则说明缺口。\n- 证据已经匹配对象、粒度、范围、时间和权威状态时停止扩搜；当前数值需要授权实时执行。\n\n## 知识导航\n\n1. [项目总览](wiki/project-overview.md)\n2. [项目共识](wiki/common/index.md)\n3. [业务领域](wiki/domains/index.md)\n4. [事件与资产目录](wiki/asset-index/index.md)\n5. [治理与来源](wiki/governance/index.md)\n\n${countSummary(corpus)}\n`;
 }
 
 function renderProjectOverview(corpus) {
-  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`;
+  return `# ${projectName} 项目总览\n\n${renderProjectBusinessModel(planModel.projectBusinessModel)}${renderTargetedKnowledge('project', 'project', 'personal-semantics/')}\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) {
@@ -774,7 +1030,7 @@ function renderLog(corpus) {
 }
 
 function countSummary(corpus) {
-  return `## 数量\n\n| 资产 | 数量 |\n| --- | ---: |\n| 业务域 | ${corpus.counts.business_domains} |\n| 技术附录 | ${corpus.counts.technical_appendices} |\n| 看板 | ${corpus.counts.dashboards} |\n| 报表 | ${corpus.counts.reports} |\n| 可复用指标 | ${corpus.counts.reusable_metrics} |\n| 分析元数据 | ${corpus.counts.analysis_metadata} |\n| 场景召回卡 | ${planModel.cards.length} |`;
+  return `## 数量\n\n| 内容 | 数量 |\n| --- | ---: |\n| 业务领域 | ${corpus.counts.business_domains} |\n| 公共事件分组 | ${eventGroups.length} |\n| 看板 | ${corpus.counts.dashboards} |\n| 报表 | ${corpus.counts.reports} |\n| 可复用指标 | ${corpus.counts.reusable_metrics} |\n| 分析元数据 | ${corpus.counts.analysis_metadata} |\n| 场景召回卡 | ${planModel.cards.length} |\n| 已采纳补充知识 | ${planModel.personalSemanticIntegrations.length} |`;
 }
 
 function authorityFrontmatter(type, resourceKey, title, authority) {
@@ -801,6 +1057,35 @@ function assetPath(type, key) {
   fail(`Unsupported recall-card asset type ${type}.`);
 }
 
+function normalizePersonalSemanticContextType(value) {
+  const type = clean(value).toLowerCase().replace('-', '_');
+  if (!['background', 'preference', 'experience', 'asset_context'].includes(type)) {
+    fail(`Invalid adopted personal semantic context_type: ${clean(value) || '<empty>'}.`);
+  }
+  return type;
+}
+
+function personalSemanticContextPath(value) {
+  const type = normalizePersonalSemanticContextType(value);
+  return type === 'asset_context' ? 'asset-context' : type;
+}
+
+function personalSemanticContextLabel(value) {
+  const type = normalizePersonalSemanticContextType(value);
+  if (type === 'background') return '项目背景';
+  if (type === 'preference') return '偏好';
+  if (type === 'experience') return '经验';
+  return '资产上下文';
+}
+
+function personalSemanticContextUsage(value) {
+  const type = normalizePersonalSemanticContextType(value);
+  if (type === 'background') return '用于补充项目、业务域和对象关系的背景信息。';
+  if (type === 'preference') return '用于补充项目内的回答偏好、入口选择和路由方式。';
+  if (type === 'experience') return '用于补充已经验证过的分析路径、风险提示和经验规则。';
+  return '用于补充具体资产的使用语境；引用资产不存在时不能作为当前资产事实。';
+}
+
 function assetOutputFileName(directory, key) {
   if (directory === 'dashboards') return dashboardFileNames.get(key) ?? fileName('dashboard', key);
   if (directory === 'reports') return reportFileNames.get(key) ?? fileName('report', key);
@@ -947,10 +1232,8 @@ 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',
-    'wiki/source-containers/index.md',
+    'wiki/common/index.md', 'wiki/domains/index.md', 'wiki/asset-index/index.md',
+    'wiki/governance/index.md',
   ];
   const missing = requiredLinks.filter((target) => !content.includes(`(${target})`));
   if (missing.length) fail(`Snapshot root index is missing required navigation: ${missing.join(', ')}.`);
@@ -1118,6 +1401,7 @@ function writeFlatUploadSources(sourceRoot, targetRoot, replace) {
     writeJson(path.join(staging, 'kb-upload-manifest.json'), {
       schema_version: '1.0',
       manifest_kind: 'ae_project_semantic_kb_upload_sources',
+      navigation_taxonomy_version: '2.1',
       namespace: uploadSourceNamespace,
       semantic_project_id: semanticProjectId,
       project_name: projectName,
@@ -1162,6 +1446,17 @@ function uploadSourceIdentity(rel, content = '') {
   if (section === 'metrics') return namedUploadSource('metric', stem, frontmatterValue(content, 'resource_key'));
   if (section === 'domains') return namedUploadSource('domain', stem);
   if (section === 'recall-cards') return namedUploadSource('recall-card', stem);
+  if (section === 'personal-semantics') {
+    if (rest.endsWith('/index') || rest === 'index') {
+      return {
+        source_kind: 'personal-semantic',
+        asset_type: null,
+        asset_key: null,
+        file_stem: `personal-semantic-${stem}`,
+      };
+    }
+    return namedUploadSource('personal-semantic', stem, frontmatterValue(content, 'integration_id'));
+  }
   if (section === 'technical-appendices') return namedUploadSource('appendix', stem);
   if (section === 'source-containers') return namedUploadSource('source-container', stem);
   if (section === 'governance') return namedUploadSource('governance', stem);
@@ -1187,6 +1482,9 @@ function semanticPlanFragmentRefsForSource(identity, rel) {
   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 (sourceKind === 'personal-semantic' && assetKey) {
+    refs.add(`personal-semantic-integration:${assetKey}`);
+  }
   if (assetType === 'dashboard' && assetKey) {
     const domain = domainByDashboardId.get(assetKey);
     const appendix = appendixByDashboardId.get(assetKey);
@@ -1210,6 +1508,9 @@ function semanticPlanFragmentRefsForSource(identity, rel) {
   if (sourceKind === 'index' && rel === 'wiki/domains/index.md') {
     for (const domain of domains) refs.add(`domain:${clean(domain.domain_id)}`);
   }
+  if (sourceKind === 'personal-semantic' && /\/index\.md$/.test(rel)) {
+    for (const integration of planModel.personalSemanticIntegrations) refs.add(`personal-semantic-integration:${clean(integration.integration_id)}`);
+  }
   return [...refs].filter(Boolean).sort();
 }
 
@@ -1242,6 +1543,14 @@ function buildSemanticPlanState() {
   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 });
   }
+  for (const integration of planModel.personalSemanticIntegrations) {
+    const id = clean(integration.integration_id);
+    add(`personal-semantic-integration:${id}`, 'personal-semantic-integration', integration, {
+      integration_id: id,
+      context_type: clean(integration.context_type),
+      source_ids: integration.source_ids,
+    });
+  }
   fragments.sort((left, right) => left.id.localeCompare(right.id, 'en'));
   return {
     schema_version: '1.0',
@@ -1355,6 +1664,12 @@ function renderNumberedSteps(value, indent = '') {
 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 readOptionalIndex(name) { return fs.existsSync(path.join(packageRoot, 'indexes', `${name}.jsonl`)) ? readIndex(name) : []; }
+function readPackageJsonl(rel) {
+  const file = path.join(packageRoot, rel);
+  if (!fs.existsSync(file)) return [];
+  return readText(file).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', '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; }

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

@@ -1,13 +1,29 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
+import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 
-const scoped = new Set(['+new', '+add', '+list-sources', '+schema', '+compile', '+status', '+import']);
+const scoped = new Set(['+new', '+add', '+list-sources', '+schema', '+compile', '+status', '+import', '+schema-download', '+schema-import', '+schema-import-list']);
 const requestScoped = new Set(['+import-status']);
 const directory = new Set(['+source-ls', '+source-read', '+source-put', '+source-rm']);
 const value = (args, key) => args[args.indexOf(key) + 1];
 
+export function invokeCompanyKbCli(flags, { spawn = spawnSync, localCli = path.resolve(import.meta.dirname, '../../../../bin/ae-cli.js') } = {}) {
+  // Packaged/project scripts use their matching CLI; standalone installed Skills retain PATH lookup.
+  const bundled = fs.existsSync(localCli);
+  const child = spawn(bundled ? process.execPath : 'ae-cli', bundled ? [localCli, ...flags] : flags,
+    { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] });
+  if (child.stderr) process.stderr.write(child.stderr);
+  if (child.error) throw child.error;
+  if (child.status === 0) return JSON.parse(child.stdout);
+  // CLI failures are JSON on stderr, possibly surrounded by compatibility/progress messages.
+  const start = child.stderr.indexOf('{\n  "ok": false,');
+  const end = start < 0 ? -1 : child.stderr.indexOf('\n}', start);
+  if (end >= 0) return JSON.parse(child.stderr.slice(start, end + 2));
+  throw new Error(child.stderr || child.stdout || 'CLI process failed.');
+}
+
 // Project semantic KB operations must never fall back to a personal KB.
 export async function runCompanyKb(command, args, invoke) {
   if (args.some((arg) => arg === '--custom-instructions' || arg.startsWith('--custom-instructions='))) {
@@ -24,7 +40,9 @@ export async function runCompanyKb(command, args, invoke) {
   const call = async (cmd, flags) => {
     const result = await invoke(['kb', cmd, ...flags]);
     if (!result || result.ok !== true) {
-      throw new Error(`Company KB operation failed; stop without personal fallback: ${JSON.stringify(result?.error ?? result)}`);
+      const error = new Error(`Company KB operation failed; stop without personal fallback: ${JSON.stringify(result?.error ?? result)}`);
+      error.code = result?.error?.code;
+      throw error;
     }
     return result;
   };
@@ -98,12 +116,7 @@ function expandCustomInstructionsFile(args) {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   try {
     const [command, ...args] = process.argv.slice(2);
-    const result = await runCompanyKb(command, args, (flags) => {
-      const child = spawnSync('ae-cli', flags, { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] });
-      if (child.stderr) process.stderr.write(child.stderr);
-      if (child.error || child.status !== 0) throw new Error(child.error?.message || child.stderr || child.stdout || 'CLI failed.');
-      return JSON.parse(child.stdout);
-    });
+    const result = await runCompanyKb(command, args, invokeCompanyKbCli);
     console.log(JSON.stringify(result, null, 2));
   } catch (error) {
     console.error(error.message);