ae-analysis

ae-analysis

这是用于分析意图和命令执行的单一入口技能。

能力约定

• 职责：分析查询和资产、元数据发现、受众定义、本地输入文件上传，以及下文所述的治理／项目／跟踪工作流。
• 输入：已验证的项目上下文，以及所请求的度量指标、时间范围、筛选条件或特定操作所需的资源；上传还需要本地文件和已发现的用途。
• 输出：带有范围说明的查询证据、已验证的元数据、操作／资源标识符、已上传输入文件的标识符，或适用时的异步运行／制品状态。查询行不会自动成为已持久化的受众。
• 边界：参与度操作，以及元数据数据表写入／维度绑定不属于此技能的工作流；若还有其他工作需要完成，请查找所需能力。
• 完成条件：已验证所请求的分析侧结果，或已识别待处理／受阻的工作。在处理完之前，用户请求中的其他部分仍应保持未完成状态。

跨技能协作

当剩余工作超出此技能范围，或必要的前置条件需要其他能力时，请遵循协作协议。根据能力从本次运行可用的技能中进行选择，保留已验证的上下文，并继续处理剩余任务。如果已加载此协议，请重复使用。

Agent 上下文遥测

硬性规则：在此技能中运行由网关支持的 ae-cli 命令之前，必须在工作目录根目录的 .ae/cli-agent-context.json 中维护当前 Agent 上下文，除非用户明确要求不发送意图遥测。保持业务命令简洁；默认不要追加 --agent-context <base64url-json>。仅依靠运行时自动检测只是部分回退方案，不足以满足用户意图遥测的要求。

上下文文件必须使用 intent_source: "agent_context_file"，并包含简洁的任务级 user_intent、当前 session_goal、稳定的 agent_session_id、当前 agent_turn_id（如果可用）、intent_relation 和 intent_revision。只要能确认当前模型，就应包含 agent_model。session_initial_intent、user_intent 和 session_goal 应使用用户的原始语言；例如，中文用户请求应使用中文内容。省略未知的父级轮次字段，不要猜测；但不要省略整个上下文载荷。意图摘要应尽量简洁，避免使用冗长的原始对话记录。开始由 CLI 支持的任务，或用户的 CLI 用途发生变化时，请更新此文件。用途和模型保持不变时，可重复使用该文件。

Agent 必须主动获取当前模型标识符，并在上下文文件中将其明确写入 agent_model。应使用可信的运行时上下文或针对当前会话和轮次的有限元数据；例如 Codex 当前会话中的 turn_context.model。不要仅依赖模型环境变量是否存在。绝不能根据 Agent／产品名称、配置的默认值或其他会话推断模型。此要求适用于每个 Agent 客户端。即使 CLI 用途不变，只要模型发生变化，也必须更新此文件。

如果无法确认模型，请省略 agent_model，设置 context_capture_status: "partial"，然后继续；不要因此阻塞或延迟业务命令，也不要仅为遥测而询问用户模型信息。确认模型后，写入模型并移除过时的部分状态标记，以便 CLI 根据其余字段计算采集状态。

分析工作流

对于数据查询：

1. 获取当前项目以及所需的指标、时间窗口、分组和筛选条件。在选择知识库或分析路径之前，先应用项目语义知识与发现门控。复用已知资产和定义；使用元数据解析发现未知业务指标，然后选择所需的已保存报表或临时查询命令／模型参考。
2. 对任何新的业务映射进行一次确认，填写必需参数，并执行适用的已保存报表或完整的临时查询定义。在依赖查询中复用已确认的含义。如果确认工具无法获取回复，请以文本形式提供相同选项并等待回复。
3. 根据编译器报告的路径修正错误。新证据或用户更正会改变已完成的选择；保留其他已验证的输入。
4. 直接使用返回结果。仅在用户要求文件或必要的本地处理需要时保存原始 JSON；遵循结果处理。保留 stderr 和 CLI 退出状态。
5. 仅计算请求所需的缺失值，并在一次本地调用中一并完成。复用已完成的结果；当所需数据可用时作答，否则说明具体错误或缺失输入。
6. 仅在完成分析数据查询并给出最终业务分析答案后，才用用户的语言询问一次分析是否符合预期：满意、部分满意、不满意或无法判断。不要在单次 CLI 调用、处理中间步骤、发现、元数据检查、资产治理／写入、配置、帮助、无关问题、提交查询、运行导出或查询失败后询问。未明确提供反馈时，不得提交或创建新的反馈事件。对于已完成分析的明确评价，请使用分析查询反馈；保留被评价的会话和轮次 ID、用户的原始反馈以及简短且可验证的路径摘要。不要上传分析答案，也不要从沉默、后续问题或新要求中推断评分。反馈收集不得阻碍后续业务工作。

先确定路径，再阅读

1. 在打开任何参考文档前，先将请求归类到命令族。
   • CLI Agent 资产认证与指标推荐审核：包括推荐项目资产进行认证、审核资产认证候选项、审核项目资产治理建议、审核推荐指标，或明确要求自动审核／自动认证推荐资产的请求。打开 references/governance_recommendation_export.md，并使用 analysis-meta governance-recommendation export|submit|auto-review|decisions。提交到审核页面时，打开 references/agent_review_submit_to_page.md，并使用 analysis-meta agent-review submit-to-page|list|detail|records|review|retry。预先检查时不要加载项目语义、项目知识库或个人语义偏好。
   • 项目语义知识库构建／更新／刷新／同步：打开 references/project_semantic_knowledge_wiki.md，并使用 project-semantic asset-package export、本地语义规划和本地 Wiki 渲染。默认采用 CLI 语义预编译为 Markdown 源文件、上传源文件 ZIP、初始化／复用正式预设，以及编译知识库。正常刷新时，不要重新生成 Schema，也不要对未更改的预设进行 AI 验证。日常刷新时更新已更改的源文件并使用增量编译；导航分类体系版本发生变化时，必须执行源树打包工具报告的完整迁移重建。绝不可改用只读快照导入。遇到公司权限拒绝时停止。这是 ae-analysis 内的命令参考工作流，不是独立的项目语义 Skill。
   • 已知命令族：只打开其专用参考文档。例如，留存请求直接使用 references/adhoc_run.md、通用的 references/ai_models.md 和 references/ai_models/retention.md。
   • 未知命令族：使用 rg 或同类文本搜索工具搜索 references/command_index.md，并只保留匹配的行。command_index.md 是仅供搜索的备用文档；绝不要读取整个文件或打印完整文件内容。
2. 编写命令前，先阅读所选命令的专用参考文档：
   • event list -> references/event_list.md
   • 可读的已保存报告／仪表板发现 -> analysis asset search 和 references/asset_search.md；包括共享只读资产。
   • analysis dashboard list -> references/dashboard_list.md
   • 已保存事件报告的图表／结果表布局 -> references/report_get.md 和匹配的 report_create.md 或 report_update.md。特定分析看板上的表格卡片 -> dashboard-report get/update 和 references/dashboard_report_get.md / references/dashboard_report_update.md；卡片显示设置与其源报告定义是分开的。
   • 事件组合图表或按指标设置柱形图／折线图及主／次坐标轴 -> 还要阅读 references/event_report_presentation.md。系列配置作用于源报告，并可能影响该报告的其他趋势卡片；更新卡片显示设置无法创建本地系列覆盖。
   • personal-semantic-preference list -> references/personal_semantic_preference_list.md
   • 资产中心跨源配置（资产中心 / 跨源资产配置 / Excel 配置表导入）：L3 发现使用 capability search "cross_source_config" --domain metadata --project-id <id>；阅读 references/cross_source_config.md，了解工作簿上传与验证。没有专用业务命令。
   • 网关文件名中的连字符须替换为下划线。
3. 对于面向 AI 的定义，阅读简短的通用文档 references/ai_models.md，以及每个所选模型对应的 references/ai_models/<model_type>.md。批量阅读这些文档；直接使用模型路径，无需搜索标题或计算行号。
4. 对于集群／标签的 --definition-request，还要阅读匹配的 references/user_cluster_models.md 或 references/user_tag_models.md。共享基础组件见 references/audience_models.md。
   • 对于标签定期刷新，阅读 references/user_tag_create.md 或 references/user_tag_update.md；这些文档涵盖启用开关、频率／时间计划、cron 替代方案及时区行为。
5. 对于查询数据，结合所选命令和模型文件，阅读简短的 references/analysis_data_retrieval.md。只有在需要这些操作时，该文档才会链接到导出和后续操作的详细说明。
6. 对于未知的面向 AI 的元数据，或编译失败信息中包含 slot_kind、allowed_resource_types、search_targets 和 next_action 时，阅读并遵循 references/metadata_resolution.md。
7. 对于不熟悉的聚合、群组或归因规则，查阅 references/analysis_interpretation.md 中对应的章节。 选定一个命令系列及其专用参考资料后，路由即完成。生成的命令索引是完整的，除匹配的搜索结果行外，必须避免将其纳入模型上下文。此文件仅包含路由和工作流规则；不要在此重复手动维护的命令清单。

仅在编辑或管理工作流开始前，使用 analysis report list 和 analysis dashboard list 查询可管理资产目录。这些命令不包含只读共享资产。要查看、查找或选择已保存的报告或仪表板，优先使用 analysis asset search，以确保仍可发现可读资产。

已保存报告的写入遵循分析页面的产品边界：analysis report create/update 最多接受一个复合筛选器层级，且该分组的 items 中每一项都必须是叶子筛选器。不要扁平化 analysis report get 返回的更深层树结构；应改用仅更新元数据的操作，或获取明确兼容页面的替代定义。即席分析仍支持特定模型的递归筛选器。

边界与优先级

此技能适用于以下 CLI 服务：

• analysis：报告、仪表板、BI 面板、即席分析、下钻、详细数据、警报、集群、标签，以及异步运行和产物。
• analysis-meta：网关元数据资产、事件、属性、虚拟元数据、指标、数据表、交换规则和超级元数据。跨来源资产配置则使用元数据 L3 目录。
• analysis-governance：网关资产治理操作，包括受治理资产列表／导出、血缘、依赖关系、影响、查询历史、规则架构／列表／创建／更新／删除、批量资产操作和操作记录。资产治理工作流使用此服务，不要用它执行元数据事件／属性／指标的 CRUD 操作。
• tracking：网关跟踪计划、检查、摄取、实时数据和事件黑名单操作。
• personal-semantic-preference：当前用户的项目级个人语义偏好。在消解含糊的业务表述、选择资产或处理用户反复提及的偏好之前，将其用作 Agent 上下文。
• project-semantic：针对明确的项目知识库构建或刷新任务导出资产包。旧版受治理项目语义生命周期已无法通过 CLI 使用。

对于此处未涵盖的命令系列，请使用协作协议来发现匹配的可用能力，而不要假定某个特定的 Skill 名称。

此技能只能通过 ae-cli 执行。如果命令缺失、不受支持、尚未实现，或已确认存在能力缺口，请报告该缺口；不要切换到直接执行 MCP。验证错误或 need_clarification 表示需要针对具体输入进行修正。诸如 fetch failed 的传输失败意味着结果不可用：报告错误以及已获取的任何结果，然后停止依赖该结果的请求。环境恢复后再继续；不要开始路由探测、休眠或后台网络轮询。传输失败并不能证明能力缺失或数据为空。

对于标签和受众群组，使用原生的 analysis user-tag ... 和 analysis user-cluster ... 网关命令。 对于 CLI Agent 的资产认证和指标推荐审核，请路由到 analysis-meta governance-recommendation export|submit|auto-review|decisions。Common 会返回确定性证据包；Agent 负责按照 references/governance_recommendation_export.md 固定展示给人工审核的内容，包括按业务领域分组、纯文本状态标签，以及风险／冲突说明。只有在用户明确要求自动审核或自动认证时，才调用 auto-review；单纯的推荐请求，以及“推荐并提交到页面”的请求，都不得检查自动认证项目配置或自动认证资产。未显式指定 --limit 时调用 auto-review，CLI 会验证自动认证和项目语义开关，并按需以只读方式探测前 20／50／100 条待处理推荐材料；随后 CLI Agent 根据最终材料构建一组自动认证决策，并提交这些决策以供执行／审计。语义重复检测由 CLI Agent 负责，而非 Common 的历史推荐状态；跳过重复项时，必须指出具体的冲突资产目标。auto-review 结果还会为自动审核后仍未认证的资产返回 manual_review_handoff；如果用户之后要求将这些剩余项提交到页面，请根据 manual_review_handoff.page_review_items 构建 agent-review submit-to-page，以保留仪表板／报告的父级上下文；仅将 manual_review_handoff.items 视为人工认证工作项，并在每项摘要中列出自动认证未通过的原因。不得将项目语义、项目知识库或个人语义偏好命令用作此工作流的前置上下文。不得使用 asset-authentication list|export|update 等管理命令或指标 CRUD 命令来合成推荐。不得绕过精选命令，通过 ae-cli capability inspect|validate|dry-run|run 操作 governance.asset_authentication.dashboard_package、metadata.metric.recommended_scan 或 metadata.metric.recommended_create。

在进行耗时的 Agent 分析之前，先使用 governance-recommendation export 开始推荐，以便 Common 能以原子方式将项目标记为运行中。同一 Agent 轮次中后续的导出可以扩大候选池。如果 Common 返回 RECOMMENDATION_RUNNING，则停止本次尝试，并告知用户已有推荐正在进行；不得切换到另一个 Agent 上下文重试，也不得绕过该标记。成功提交到页面或完成自动审核后会释放该标记；仅生成推荐或 Agent 运行失败时，则依赖固定的过期机制。无需单独调用开始或完成 CLI 命令。

展示推荐后，Agent 可以询问是否要将其提交到审核页面。用户选择提交，仅授权执行 analysis-meta agent-review submit-to-page，不代表授权批准、认证、检查配置或调用 governance-recommendation auto-review。如果用户拒绝，则不得写入，也不得反复建议提交。已有的明确提交授权仍然有效，无需再次询问。预先获授权的无人值守任务只能提交审核提案；绝不能自动调用 agent-review review|retry、旧版 governance-recommendation submit、governance-recommendation auto-review，也不能直接修改认证／指标。使用 agent-review list|detail|records 和任务持久化的提案指纹来复用之前的批次。对于未变化的提案、待审核项、已完成项或用户先前拒绝的建议，不得重新提交或重复发送通知。仅有新的运行 ID 并不构成新证据。仅报告一次返回的 review_url；在有实质变化或需要用户采取行动之前，不再发送消息。稳定的请求键和数据包规则请参阅 references/agent_review_submit_to_page.md。 报告审核详情必须说明计算逻辑和统计指标，而不能只说明业务目的。遵循 resolve/export -> material-package 完整性检查 -> 仅针对缺口执行 analysis-meta agent-review evidence 或 analysis report get -> 分块 AI 说明 -> 独立预检 -> 经授权后 submit-to-page -> 详情回读。LOCAL_ONLY 在本地预检结果处停止。预期 governance-recommendation export 会在 review_material_package.candidate_assets 中包含报告的 evidence_snapshot.analysis 和 target_revision；如果这些字段已存在，不要要求客户对每份报告都运行 analysis report get。仅当报告条目缺少当前分析、需要验证生成的草稿，或材料包明确标记定义缺口时，才获取 agent-review evidence。请阅读 references/agent_review_evidence.md，了解稳定分析字段及其限制。根据适用情况，在 item.ai_summary.analysis_explanation 中填写有证据支持的指标、维度、计算、筛选条件、time_scope 和 query_columns；分别解读每个受支持的 SQL 投影列。仅引用以 evidence_snapshot.analysis 为根的实际事实支持型响应路径；source_path 是来源信息，不能自动替代 evidence_refs。将服务端事实与 AI 解读分别保留，并明确指出证据为 null、缺失、动态或未解析的情况。对于 DYNAMIC SQL，将对受支持的 sql.raw/normalized_definition.params 的讨论标注为对原始文本的解读，绝不要臆造 select_columns 或运行时替换值。Common create 会存储提交的数据包；它不会替 Agent 补充缺失的计算说明。调用 submit-to-page 前，检查必需的 evidence_snapshot.analysis，以及 analysis_explanation.calculations / analysis_explanation.measures 中可解析的引用；缺少必需结构仍属于错误。审核者可读性和解读缺陷应遵循有范围限制的质量修正／警告流程。提交后，在详情中验证已存储的快照和引用。绝不要猜测 SQL、别名、列、公式、时间范围、时区或执行是否成功。定义检查、证据读取、验证和提交都不能证明查询结果、审批或认证。

item.ai_summary.summary 是简洁的条目建议理由，包含其证据依据和主要风险，并显示在主列表中。batch.ai_summary.summary 是批次概述，不能替代条目理由。详细的事实说明只能放在 item.ai_summary.analysis_explanation 中。不要在展示字段中重复理由或详细分析；将 presentation_snapshot.analysisByItem 保持为 {}。不要根据未知值臆造理由；应明确说明证据缺失或风险不确定，而不是将其视为零或不存在。

脚本可以构建传输文件、保留 ID、复制证据、规范化链接，并运行确定性的完整性检查。脚本不得通过填充可复用的句子模板来撰写页面可见的 ai_summary.summary、analysis_explanation.*.statement、限制、待解决问题或审批理由。这些字段必须由 Agent 根据当前资源／报告证据撰写解读；如果许多已提交条目的叙述模式相同，只是资源名称或数字有所变化，则应标记为质量失败，并遵循 references/agent_review_preflight.md 中有范围限制的修正／警告流程。 面向页面的审核文案是给人工资产审核人员看的，而非给实现人员看的。在 item.ai_summary.summary、可见陈述和待确认问题中，使用通俗的业务中文说明资产的用途、计算方式、重要的筛选条件和日期范围，以及审核人员需要确认的事项。适当使用当前资产定义中的事件名称和属性名称，帮助审核人员核实计算定义。不要暴露内部证据、解析器术语、临时 SQL 别名或运行时参数名称，例如 SAVED_REPORT_ONLY、DYNAMIC、REPORT、T1、a0、a1、Variable2、selector3、PartDate date1、source_path、evidence_snapshot；也不要暴露原始 JSON、原始 SQL、哈希／修订详情、看板覆盖警告、“未保存时区”备注，或有关查询执行的说法，除非用户明确要求调试证据。展示前应转换内部值，例如将 T1／day 转换为“按天”，将动态 SQL 的注意事项转为业务确认事项，例如“确认参数含义、默认日期范围和是否包含测试数据”。

如需在真实审核页面提交，请从 analysis-meta governance-recommendation export --limit 20 开始。这是初始候选池，并非必须提交的数量。按照 references/governance_recommendation_export.md 中的拒绝项过滤和有限扩展流程操作：隐藏每个定义相同且已被拒绝的看板的整个展示分支；仅在其他保留的看板下保留共享资产；将已完成／已认证、已延期或正在处理的资产过滤为待处理工作；候选池不足时，按 20、50、100 的顺序扩展，然后停止。扩展是为了覆盖业务领域，而不是无限增加工作量：对于定期每日批次，待审核资产目标约为 20-50 项，上限约为 80 项；在添加背景信息前，应平衡覆盖约 3-6 个可见领域，并为各领域设置配额。以最新一次成功导出作为起草依据，并报告实际审核范围以及留待后续批次处理的超量部分。不要将符合条件的覆盖范围压缩成少数几个代表性主题，也不要只提交第一组工作，除非用户要求提供样例或诊断批次。业务主题用于组织保留的看板集合，不能取代其覆盖范围。对于定期的推荐任务，只提交仍包含待审核资产的业务领域；已认证资产仅作为这些可见领域下的背景信息，不应作为独立工作项。不要为隐藏领域或纯背景认证信息撰写冗长的 Agent 摘要。

对于看板推荐，保留 Common 中的可选位置信息：当看板候选项或源看板包含 space_id 或 space_name 时，将这些字段复制到已提交看板项的 evidence_snapshot.definition.config 中，以便审核页面显示“所属空间”。并非每个看板都属于某个空间；缺少空间字段是有效情况，不得臆造或强制要求这些字段，也不得据此过滤掉其他方面符合条件的看板。

presentation_snapshot.topics 必须是业务领域，而不是看板容器；业务领域不等同于看板。不得仅仅因为导出返回了 20 个工作单元，就为每个热门看板创建一个主题。首先根据看板名称、子报表名称、报表定义、引用的事件／属性、指标、文件夹背景和撰写的备注，按业务流程对选定的看板进行归类。如果多个看板描述同一业务领域，应将其归入同一个主题，并将每个看板保留为该主题下的根项目。只有在业务流程或审核决策存在实质差异时才拆分主题。预期层级为 业务域 -> 看板 -> 报表 -> 元数据；主题数量可以少于选定看板数量，而 topic_count == selected_dashboard_count 的结果必须有真正不同的业务含义作为依据，不能依据源数组顺序来决定。 审核页面时，请在 presentation_snapshot.relations 中保留原型层级：源看板条目是其子报表条目的父项，关系类型为 type:"contains"；报表条目是其实际引用的元数据条目的父项，例如事件、事件属性、用户属性和指标资源，关系类型为 type:"uses"。主题 items 可以列出相同的稳定 client_item_id，但页面必须能够根据 relations 渲染看板 -> 报表 -> 元数据。只有在所选资源确实没有已知的父子关系证据时，relations: [] 的扁平数据包才有效。

完整的 evidence_hash 包含采集时间，因此不同预览之间可能会发生变化，即使业务内容并未变化；请使用 target_revision 检查已保存定义的版本，并单独比较实质性事实。不要使用完整快照哈希触发跨扫描重新提交。Create 会存储提交的快照，不会恢复省略的字段；请针对最终分发的材料详细核验引用和重要事实。

如果意外探测已弃用的拆分推荐命令或能力并返回错误，只将其视为路由纠正。不要将拆分推荐命令或能力中的数据用作推荐答案的业务来源；请通过 analysis-meta governance-recommendation export 重新运行当前工作流。

对于审核页面起草、材料检查或仅本地演练，请阅读 references/agent_review_preflight.md 和 references/agent_review_priorities_comparisons.md。完成条目说明后，生成有证据支持的审核优先级，并跨创作分块/主题比较相关定义；将 recommendation、分类后的 comparisons 和 comparison_review 存入条目的 AI 摘要中。审核优先级不是认证决定，相似性本身也不构成冲突。使用独立的新上下文审核者，将所有证据（包括 signals）与已保存来源进行比较，并审核条目特定的含义、优先级和成对定义。作者对具体问题的修正次数最多为 3 次，适用于整个数据包，且每次修正后都必须独立复审。如果质量仍不达标，已获授权的提交仍应继续，并明确警告尚未解决的质量问题；绝不可声称 PASS，也不可重置修正次数上限。请披露无法进行审核或覆盖不完整的情况。仅本地处理的意图始终禁止提交。质量评估由 Agent 负责，不属于 Common；结构验证、授权和传输错误仍须强制执行。

全局 AE CLI 规则

命令形式：

ae-cli analysis <resource> <action> [options]
ae-cli analysis-meta <resource> <action> [options]
ae-cli analysis-governance <resource> <action> [options]
ae-cli tracking <resource> <action> [options]
ae-cli capability search|inspect|validate|dry-run|run [options]

• 网关命令使用 kebab-case 标志，例如 --project-id；CLI 会发送 snake_case JSON。
• 网关命令前必须先按「Agent Context Telemetry」部分所述更新 .ae/cli-agent-context.json。隐藏选项 --agent-context <base64url-json> 仅用于无法写入的隔离环境或本地调试，是此技能的备用方案，并非首选路径。
• JSON 值必须是 JSON 字符串字面量。
• 全局标志包括 --host、--format json|table、--jq、--validate、--dry-run 和 --yes。仅在解决具体的复杂输入问题时使用 --validate；对于高风险写入或明确要求预览的情况，使用 --dry-run。这些模式不能同时使用。
• 对于参数完整的读取或普通写入，直接执行。不要惯常地依次进行检查、验证、试运行和执行。仅当具体的架构不匹配问题需要时，检查所选模型契约一次；在对话范围未变的情况下，复用已检查的契约。这是复用本地证据，并不表示 CLI 会缓存契约。
• JSON 是默认的机器可读输出。发生失败时，保留结构化错误和非零退出状态。
• CREDENTIAL_STORE_UNREADABLE（error.type: config）表示本地凭证读取或解密失败。保留文件，并在原始 OS 用户／运行时环境中重试，同时确保可访问机器标识；不要自动登录、替换令牌或登出。这并不能证明服务端令牌已过期。
• 切勿臆造命令名称、标志、载荷字段、项目、资源 ID、资产名称、规范事件／属性标识符、指标公式或日期。用户提供的业务措辞可以作为尚未解析的编译器输入；这并不表示已知规范绑定。
• 中文时间表达必须按固定语义映射：最近 7 天／近 7 天 -> mode=recent -> QP recentDay=0-7，含今天；过去 7 天／前 7 天 -> mode=previous -> QP recentDay=1-7，不含今天。用户明确说明是否包含今天时，以该说明为准。完整映射见 references/ai_models.md。

CAPABILITY_NOT_FOUND 表示当前主机未公开该网关功能；更改参数无法解决问题。权限错误会中止任何依赖此操作的链路。检查异步运行时出现 404，表示路由／部署失败；不要无限轮询同一个 ID。

按状态解读网关信封：

• ok: true 且数据为空表示成功，即没有匹配数据。切勿将空的报告／仪表板结果标记为查询失败。
• ok: true 且 meta.partial: true 表示部分成功。使用成功的数据，并明确报告 meta.failures；不要判定整个批次失败，也不要隐藏失败项。
• ok: false 表示失败。若存在，保留 error.code、error.message 以及 meta.request_id、meta.invocation_id、meta.stage 和 meta.failures。
• OUTPUT_PROJECTION_FAILED 表示命令完成后的本地输出失败：stdout 会在 data 中保留原始业务载荷，并保留原始 meta，但退出状态仍为非零。根据返回的信封修复投影，不要重新提交远程命令。
• 不要重试未作更改的失败命令，也不要猜测其他载荷格式。仅在应用具体的验证／澄清建议或修正已确认的瞬时问题后才重试。

失败证据：

• 当信封中显示 ok: false 时，进程退出代码为 0 并不代表业务成功。优先直接调用 CLI；如果必须使用 shell 管道，请通过 set -o pipefail 保留 CLI 的退出状态，并保留完整错误信封，不要截断。
• TE_TOOL_POLICY_DENIED 表示运行时授权阶段。请报告其确切原因；这并不能证明后端架构检查已通过，也不表示用户需要重新登录。不要绕过策略，也不要通过更改业务范围来重试。
• INVALID_ANALYSIS_DEFINITION / INVALID_CAPABILITY_INPUT 表示输入错误。请在允许的重试次数内一并更正所有相关字段。只有在同一主机上针对同一份完整定义收到明确的验证成功响应后，才能说“验证通过”。
• QUERY_FAILED 表明查询失败；它并不能确定数据库或引擎的根本原因。请保留返回的错误和关联 ID，将不可用的值保留为未知（而非 0），并在用户要求不再重试时停止。区分观察到的错误与未经验证的假设。

对于每条支持 --request-id 的网关命令，如果调用方未提供 ID，ae-cli 会生成 request_id，并在分发前将其打印到 stderr。请将该 ID 与最终信封和诊断信息一并保留。仅当需要由调用方提供关联 ID 时，才传入显式的 --request-id cli_<32 lowercase hex>。

执行不变量

• 仅探测一次第一页。在开始分页循环前，验证 ok、文档规定的数据形状以及生效的 limit。
• 对分页目录结果，仅当 has_more 为 true 时，才使用返回的 next_offset 继续。绝不计算推测的偏移量、重复当前页，或在 has_more 变为 false 前宣告列表完整。
• 跟踪每次调用的规范化命令、输入和已公布的 request_id。调用仍在执行时，绝不重新提交相同调用；应等待当前进程，或在异步执行时检查其返回的 run_id。
• 当主机、身份、项目、定义、生效范围和完整性均匹配时，复用已完成的数据、已验证的元数据、已选资源和已下载文件。仅查询已确认缺失的依赖项；将兼容的指标合并处理，不要在查找中添加无关分析。
• 仅重试 meta.failures 中列出的项目，且仅当其 retryable 值和 next_action 允许时才重试。绝不重试同一批次中已成功或结果为空的项目。

强制路由

产品术语门槛

• 中文产品术语 看板 指基于已保存报表的分析看板。请将其路由到 ae-cli analysis dashboard ... 和 analysis.dashboard.* 下的能力 ID。
• 中文产品术语 仪表盘 和 BI 仪表盘 指包含工作表、图表和页面的 BI 仪表盘。请将其路由到 ae-cli analysis bi-panel ... 和 analysis.bi_panel.* 下的能力 ID。
• 这些资源不能互换。绝不要用分析看板替代 BI 仪表盘，也不要用 BI 仪表盘替代分析看板。
• 在此产品中，单独使用的英文单词 dashboard 含义不明确。执行写入操作前，请询问用户指的是分析看板（看板）还是 BI 仪表盘（仪表盘），除非上下文已明确指出产品资源。
• 如果所请求的 BI-panel 能力不可用或未获授权，请报告此限制。不要改为创建分析看板。

项目门槛

使用 Agent 主机在当前轮次提供的项目 ID。如果未提供项目，请使用 project info list 解析用户的 ID 或名称。仅当返回的候选项确实存在歧义时才询问。用户的新选择将替换后续命令使用的先前项目。

项目语义知识

当用户明确要求构建、更新、刷新、重建或同步项目语义知识库时，打开 references/project_semantic_knowledge_wiki.md。该命令参考工作流从 ae-cli project-semantic asset-package export 开始，然后上传／编译知识库来源。已退役的受治理项目语义候选项与发布生命周期，不属于此知识库构建路径，也不属于 CLI Agent 资产认证与指标推荐审核流程。

项目语义知识与发现

不要调用项目语义目录、条目、候选项、发布或发布上线命令。受治理的项目语义生命周期已从 CLI 中退役；当前用户语义请使用 personal-semantic-preference，项目知识请使用知识库工作流。

对于可能需要资产或指标定义的项目范围请求，应在查找任何分析资产、报告或指标之前确定路径。若用户明确指定了知识库，直接使用该知识库；若用户排除知识库，则跳过此检查。否则，在本次对话中，每个主机和已认证账户调用一次 ae-cli config show；当该范围发生变化，或答案已超过 24 小时时，重新检查。该命令使用 CLI 的每日公司配置缓存；不要为每个问题强制远程刷新。

如果 data.routing.knowledge_base 为 auto，请考虑项目知识库是否能回答问题或提供所需的资产定义。如果可以，先使用 ae-kb-discovery，优先选择精确的项目绑定，并通过 ae-kb 阅读匹配页面。对于数据问题，请验证所选资产的语义覆盖范围，并运行适用的分析命令。如果页面只提供相关定义、限制或部分覆盖范围，请保留这些证据，并通过知识库分析工作流继续常规资产或指标发现，以满足缺失的要求。如果未找到相关知识库页面，则继续常规发现。如果路由值为 explicit，或 data.source 为 unavailable，则使用常规分析路径，不进行隐式知识库发现。知识库候选项未命中相关页面，并不能作为使用其资产的依据。

个人语义偏好

当请求涉及个人业务措辞、资产偏好、明确的个性化设置，或项目范围内记忆／保存可复用分析工作流的请求时，在每个主机、已认证用户、项目和对话范围内调用一次 ae-cli personal-semantic-preference list --project-id <project_id>；在该范围内重复使用结果。使用 Agent 主机提供的当前项目。如果采用某个条目，请阅读 references/personal_semantic_preference_list.md，并使用 --title <title_from_list> --mark-used 获取该条目。在记录长期用户偏好之前，也请阅读同一参考文档；一次性分析确认属于任务上下文。 此规则不适用于通过 analysis-meta governance-recommendation export|submit|auto-review|decisions 进行的 CLI Agent 资产认证与指标推荐审核；该工作流不得将加载个人语义偏好作为前置上下文。

个人语义提供当前用户的默认设置、释义修正、资产选择和输出偏好。执行前，请根据已保存的定义验证所选资产或计算；个人偏好不能替代资产的当前定义。

个人偏好捕获触发条件由 Agent 负责。请根据含义选择 context_type：

• preference：持久的解读或输出偏好，不与任何确切资源绑定。
• asset_context：与一个或多个确切项目资源绑定的持久用户措辞或意图。发送完整且有序的 resource_refs 数组；每个条目都包含 resource_type、字符串形式的 resource_key 和 display_name。
• experience：可复用且已确认的项目工作方法或分析工作流，不与任何确切资源绑定。
• background：稳定的个人背景信息，不与任何确切资源绑定。

任何对具体资源的稳定选择（包括事件选择场景）都必须使用 asset_context；不要只在文字说明中记录资源 ID。执行项目任务期间，收集持久的当前用户偏好、稳定的解读修正、可复用的资源选择、反复出现的输出偏好、可复用的项目分析工作流，以及尚未成为已批准项目语义的当前用户工作定义。若用户在项目范围内说“记住上述工作流”“将此流程保存到此项目”“以后按这个流程”或类似的话，应在此处将其记录为 context_type=experience，而不是使用 ae-cli memory。即使工作定义也会使其他项目用户受益，它仍可存入个人记录。只能将其作为当前用户的偏好存储；绝不能将其描述为已批准的项目权威定义，也不能将与资源绑定的定义复制到其内容中。不要将未来的治理或生命周期说明加入存储内容。不要将临时任务详情、一次性分析结果、公司知识、独立元数据事实、报告或仪表板保存为个人偏好。

通过上述证据门槛的明确稳定陈述、修正或确认，无需再次征求“保存”确认，即可授权执行 personal-semantic-preference add 或 update。先与已加载的目录进行比较；如果有一条现有偏好匹配，则使用 --mark-used 获取该偏好，更新这条现有偏好，避免创建重复项。否则，添加新偏好。明确要求不要保留信息时，始终以此为准。删除属于高风险操作，必须获得用户的明确确认。

个人记录和项目推荐相互独立。当满足证据门槛时，先保存或更新个人语义。如果同一内容看起来也适合作为正式的项目范围定义，则完成当前任务后，再询问用户是否希望将其推荐为项目语义候选项。不要把项目推荐设为个人记录的前提；未经用户选择，不要提交候选项；绝不要代表普通用户批准或发布。

成功添加、更新或删除后，在本地将响应合并到对话缓存的目录中。不要仅为了确认写入而再次调用 list。

后续若已发布的项目语义与个人语义相符，应将项目语义视为正式定义，并允许个人记录通过受支持的生命周期机制变为冗余、过期或合并。若二者冲突，应以项目语义为正式定义，说明冲突，并保留个人记录，除非用户明确更改或删除它们。这些属于使用和生命周期规则；不要将其附加到存储的个人语义内容中。

过时或过期的偏好会由列表筛选和后端维护自动隐藏。不要为此寻找或编造单独的命令。

元数据发现

直接复用已知定义和规范元数据。对于未知的业务指标，请遵循 references/metadata_resolution.md：搜索相关的已保存指标/报告，阅读其定义，并仅发现缺失的事件或属性。对于编译器错误，allowed_resource_types 是权威依据。验证已有明确或已确认含义的字段、类型和筛选条件，属于补全证据，而不是做出新的业务选择。即使只有一个合适的候选项，也要确认一次所选的业务映射；复用任务中已确认的映射。

已保存的业务资产或临时分析

如果某项精确资产或定义来自知识库页面，请先阅读并遵循 ../ae-kb/references/analysis-workflow.md。检查实时定义，并优先尝试精确且语义适用的已保存资产。如果检查发现不匹配、缺少字段或覆盖不完整，则无需强行执行数据查询，继续针对原始请求进行常规发现。保留有用的知识库证据，仅解析缺失的元数据，并遵循工作流中授权的回退和披露规则。知识库的限制本身不代表任务已完成。

使用支持所请求覆盖项的合适已保存报告。对于自定义组合，请在临时模型中复用适用的定义。读取 references/analysis_gateway_assets.md，了解已保存的筛选条件、仪表板上下文和资产选择。构建临时定义时，请加载模型参考资料。

保留已确认的意图

在最终查询前，解析所请求的指标、筛选条件、分组、比较时间窗口、时区和群组资格。将用户的更正带入实际定义，包括所有依赖查询；仅在推理中注意到旧日期或指标不匹配，并不能修正提交的输入。按照元数据工作流所述，将实际的确认回复纳入这些选择。

当调用方提供现有定义快照时，使用所选命令的可选 --intent-snapshot 契约检查本地 JSON 是否一致。

结果数据与元数据

• 指标值、趋势、比较或异常 -> 根据上述决策选择已保存报告/仪表板或临时分析。
• 指标定义搜索/创建/更新 -> 元数据命令。
• 事件/实体行 -> event-detail run|export 或 entity-detail run|export。
• 查询结果中的事件/实体 -> 传入原始 --project-id，遵循返回的同步 query_context_id 和精简来源操作摘要，然后调用 analysis query-context get 获取完整坐标选项；切勿重建原始 QP，也不要将导出行用作坐标。
• 集群/标签定义 -> 匹配的网关集群/标签命令及匹配的模型参考资料。
• 标签/集群候选值，包括表述为“最新版本”或“最新结果”的请求 -> 解析确切资产，然后使用 analysis filter-value list，并设置 cluster_date_policy=LATEST。这表示最新计算的数据快照，绝不表示定义或配置版本；不要臆造版本列表、版本 ID、草稿状态或发布状态。
• 告警/配置/跟踪计划请求 -> 使用索引中对应的专用网关命令参考。

运行、导出和后续操作

对于范围有限的内联结果，使用 run；对于完整结果或超出限制的结果，使用 export --output <file>。导出或恢复中断的导出时，请阅读导出处理。如果请求需要返回的查询上下文所提供的后续操作，请阅读 references/analysis_drilldown_contract.md。

写入和破坏性操作

仅在用户明确提出意图时写入。必要时，使用 --validate 修正具体的复杂输入问题。对于高风险写入或用户明确要求预览时，使用 --dry-run；不要叠加使用这些模式。执行 read 和普通 write 命令时不要使用 --yes。对于 high-risk-write，先进行 dry-run，总结目标和影响，等待用户明确确认，然后才使用 --yes 执行未更改的命令。

项目空间和文件夹的创建、删除、共享属于 L3 能力，而不是精选的 analysis 命令。阅读对应的命令参考，然后使用 ae-cli capability inspect|dry-run|run；通过 capability search|inspect|run 和 references/analysis_gateway_assets.md 查找 *.members。对于 risk=high-risk-write，先进行 dry-run，总结影响，并仅在之后得到用户明确确认后使用 --yes 执行。

成功创建或更新后，如果存在资源 ID 和受支持的资源类型，请调用 analysis-meta asset url-get 并返回链接。若因缺少资源 ID 而跳过链接生成，或链接生成失败，请明确说明。

输出要求

• 返回用户要求的结果，并包含其指标、时间窗口、维度／筛选范围和单位。
• 复用已返回或已计算的值；仅在请求需要时才计算额外值。
• 对于已保存仪表板的答案，使用非空的 location.folder_name、dashboard_name、remark 和 notes[].note_title/description 来确定业务范围。将文件夹名称和备注标记为作者提供的上下文，并与查询中观察到的证据分开呈现。
• 说明任何影响请求的部分数据、权限或能力限制。

对于 CLI Agent 资产认证和指标推荐审核，最终答案必须使用 references/governance_recommendation_export.md 中的固定审批展示格式：

• 顶层分组为 业务主题域；不要使用 资产认证建议 和 推荐指标 等独立的顶层分组。
• 保留源看板作为核心证据包。根据看板语义、其子报表名称、事件／属性／指标语义以及共享的业务流程来确定 业务主题域。如果原始源标题、测试标签、优先级标签、资产类型标签或后端 topic_seed 字符串只是工作流标签，就不要将其用作最终分组名称。
• work_units 是证据容器，不是展示分组。单个看板／工作单元中的子报表若涉及不同业务流程，可拆分到多个业务域；多个看板／工作单元中的证据若业务含义一致，也可合并到一个业务域。
• 将每条以报表为中心的证据链放在一起：报表行、元数据行以及该报表引出的指标候选项，都归入同一个 业务主题域。不要将报表元数据拆分到单独的通用元数据分组，也不要仅因多个子报表属于同一个源看板，就合并彼此无关的子报表业务域。
• 当一个源看板包含针对不同业务问题的子报表时，应针对每个子报表的业务问题创建一个 业务主题域。不要仅因它们共用一个看板，就将不同的报表域合并成宽泛的 A 与 B 运营、综合运营 或 核心语义 分组。该看板可作为共享的关联源证据，出现在每个相关域中。
• 源看板和报表是证据容器，也可能是资产行，但不是独立的顶层业务域。不要仅为了安置源看板而创建 看板上下文、综合验收看板上下文、推荐上下文 或 待审批资产 等通用分组。应根据源看板的子报表、事件、属性、指标和定义所体现的业务域，将源看板关联到相应业务域；如果一个看板支持多个域，应在每个相关域中将其复用为关联源证据，而不是以看板标题作为域名。
• 每个 业务主题域 都必须在同一张审核表中包含资产认证行和指标候选行。
• 在域详情表中，类型 列表示对象类别（资产 或 指标）。诸如 [已认证]、[未认证]、[认证资产候选] 和 [推荐指标候选] 等审核标签，应放在 状态 或 审批关注点 列中，不要将其作为 类型 的值。
• 默认的推荐导出包含已完成／已认证的上下文。在每个 业务主题域 中，如果同时存在 [已认证] 和 [未认证] 资产行，应将它们放在同一张审核表中。如果只出现一种状态，应说明这反映的是当前返回的证据范围，而非 Agent 侧仅筛选待处理项，也不代表整个项目的认证覆盖情况。
• 在主审核表中，如果有 markdown_link 或 raw_url，资产名称应显示为可点击的 Markdown 链接。不要将原始资产 ID 作为主要对象文本；应将项目标识和哈希值保留在上下文中，供提交或调试使用。
• 在 来源证据 列中，资产行优先使用各自的 source_evidence[].markdown_link／raw_url；指标行优先使用 source_report.markdown_link／raw_url。仅当该行没有直接的 source_evidence 时，才回退使用工作单元的 source_dashboard 或 source_reports 链接。如果 JSON 提供了来源证据链接，不要删除这些链接，也不要将带链接的来源替换为 相关报表、热门看板、来源看板、同名看板、同名报表、<业务>相关报表 或不带链接的报表名称等通用文本。如果资产行本身就是源看板或源报表，应复用该行自身的链接作为来源证据。如果一行有多个关联来源链接，应显示最直接的来源链接，或以精简的逗号分隔列表显示来源链接。
• 展示数据中已有的决策信号，尤其是热度、用户数和影响程度。不要编造缺失的值。
• 仅使用纯文本审核标签：[已认证]、[未认证]、[已有指标资产]、[推荐指标候选]、[认证资产候选]、[风险/冲突]。Agent 的回答中不要使用 HTML、字体标签、颜色名称或依赖颜色的表述。
• 如果 conflict_risks、previous_decision、action_state、actionable 或 authentication_status 表明存在语义冲突、身份冲突、先前已拒绝／跳过、不可执行状态或审批阻塞项，则必须说明风险／冲突。
• 最终回答中不要显示原始 JSON。