ae-project-semantic

ae-project-semantic

项目语义是受治理的 L2 项目级业务概念、规则、计算约定和默认资产选择方法。它们位于仪表板和报告之上。仪表板、报告、事件、属性和指标是 L1 证据与执行资产；它们本身并不属于项目语义。

仅使用 ae-cli。不要直接写入数据库来处理建议、审批或发布。

边界

• 使用此技能生成或评估项目语义建议。
• 在分析任务中使用 ae-analysis 消费已发布的项目语义。
• 前端可以审查、编辑、批准、驳回和发布候选项；不得生成建议。
• 从受治理的已认证仪表板/报告开始。只有在获得用户明确同意后，才能检查范围更广的项目资产；在证据和置信度中必须保留其较低权威性。事件、属性、指标、背景文档和备注只能提供辅助证据，不能作为 L2 候选主体。

必需工作流

1. 确定项目和主机。
2. 在检查候选项之前，阅读两份建议参考文档：
   • references/recommendation-quality.md，了解受治理的 L2 质量标准；
   • references/query-routing-v5.md，了解当前的查询路由、召回快捷方式和分析手册发现协议。
3. 检查现有的已发布项目语义：

ae-cli project-semantic list --project-id <project_id>

4. 默认导出受治理的已认证项目资产和语义快照上下文：

ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force

当 --host 直接指向本地启动的 Common 服务，而不是已部署的分析网关时，将空网关域限定在该命令范围内，以便请求使用 Common 原生的 /api/cli/v1 路由。不要全局导出此覆盖设置：

AE_CLI_CAPABILITY_GATEWAY_DOMAIN= ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope governed --output <tmp>/project-semantic-assets --force --host http://127.0.0.1:8992

5. 扫描前检查 asset_scope、exported_asset_count、authenticated_asset_count、unauthenticated_asset_count、truncated、工作单元数量和定义族数量。如果 truncated=true，请警告该包已达到兼容性限制。如果受治理的资产包过于稀疏，无法支持有价值的问题框架，请报告实际数量，并询问是否重新导出活跃的协作资产。不要自动扩大范围：

ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope collaborative --output <tmp>/project-semantic-assets --force

如果该资产包仍过于稀疏，请报告其数量，并另行询问是否导出所有有效的项目仪表板/报告及其引用的元数据：

ae-cli project-semantic asset-package export --project-id <project_id> --asset-scope all_visible --output <tmp>/project-semantic-assets --force

governed 表示在最近 90 天内已认证、参与协作且处于活跃状态。collaborative 仅移除认证要求。all_visible 移除认证、协作和近期性筛选条件，但仍会排除已删除、已冻结、已隐藏、离线或其他无效资产。仅项目管理员可以导出；在 all_visible 范围内无需按用户进行可见性筛选。资产认证属于独立的治理写入操作，扫描时绝不能隐式更改。

6. 按以下顺序读取资产包：

   • 若存在，先读取 manifest.json、.asset-package.json、catalog/published.jsonl、catalog/disabled.jsonl、catalog/active-candidates.jsonl 和 catalog/rejected-candidates.jsonl，以构建排除和修订上下文；
   • 将 indexes/work-units.jsonl 作为仪表板优先的调查队列，在保持使用优先级顺序的同时，轮换调查不同的业务主题；
   • 读取 indexes/definition-families.jsonl 和精简的仪表板/报告记录，以比较可复用的定义变体；
   • 读取 indexes/asset-directory.jsonl 和 indexes/governance-coverage.jsonl 以获取辅助证据；
   • 仅对包含候选项或存在冲突的定义族读取 details/normalized/**；只有在规范化定义不足时才读取 details/raw/**。 服务负责确定性解析、关键字段规范化、定义签名、用量排序和目录组装。Agent 负责发现业务主题、解读证据、审查反例和拟定候选内容。显示名称、描述和备注仍是解读证据，但它们绝不会让两个其他方面完全相同的定义变得不同。不要一开始就将所有详细文件加载到上下文中，也不要将业务判断交给项目专用的关键词表或确定性模板生成器。

7. 将提议的行为与已发布、已禁用、活跃候选和已拒绝目录进行比较。禁用语义属于抑制上下文：不要通过推荐生成来使用、重建或更新它们。项目管理员之后可以明确启用它们。仅在确有新语义时生成 CREATE；当活跃语义需要实质性修订时生成 UPDATE；如果程序包已涵盖该语义，则不生成候选项。没有新增候选项也是有效且成功的推荐结果。

8. 根据确切导出的程序包验证 Agent 编写的文件。此命令仅检查确定性契约规则，例如必填字段、支持的枚举值、目录冲突、重复指纹和可解析的证据引用。passed=true 并不代表语义质量已获认可：

ae-cli project-semantic candidate validate --asset-package <tmp>/project-semantic-assets --submit-file <tmp>/project-semantic-candidates.json

9. 针对未经改动的候选文件及其引用的证据，单独执行一次 Agent 质量审查。应用 Hard Quality Bar 和 references/recommendation-quality.md；不要依赖生成阶段为其自身措辞背书。对于每个候选项，记录 PASS、REVISE 或 INSUFFICIENT_EVIDENCE，并附上具体发现和证据引用。进行修订，并重复确定性验证和 Agent 审查，直到所有提交的候选项都达到 PASS。成功的空推荐胜过薄弱的凑数内容。

10. 提交未经改动、已验证并通过 Agent 审查的文件。使用 .asset-package.json.snapshot_hash，或使用 candidate validate 返回的 snapshot_hash：

ae-cli project-semantic candidate submit --project-id <project_id> --submit-file <tmp>/project-semantic-candidates.json --snapshot-hash <snapshot_hash>

11. 通过 CLI 审查并启用，以验证完整闭环：

ae-cli project-semantic candidate list --project-id <project_id>
ae-cli project-semantic candidate get --project-id <project_id> --candidate-id <candidate_id>
ae-cli project-semantic candidate enable --project-id <project_id> --candidate-ids '["candidate_1"]'
ae-cli project-semantic get --project-id <project_id> --id <semantic_id> --mark-used

生命周期管理与推荐审查刻意分开：

ae-cli project-semantic disable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
ae-cli project-semantic list --project-id <project_id> --status disabled
ae-cli project-semantic delete-impact --project-id <project_id> --semantic-id <semantic_id>
ae-cli project-semantic delete --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>
ae-cli project-semantic enable --project-id <project_id> --semantic-id <semantic_id> --expected-version <version> --reason <reason>

禁用意味着“不要使用，也不要再次推荐”。处于禁用状态时，可以启用相同语义，也可以检查影响并将其物理删除。物理删除意味着该语义已不存在，未来扫描时可能会重新发现。切勿仅为重新生成推荐而删除。

严格质量标准

候选文件必须满足以下所有条件，否则不可接受：

• 基于受治理的证据，或记录明确批准的更广泛范围，并对依赖未认证资产的声明降低置信度。
• 生成候选项之前，先按 L2 业务主题域分组。
• 每个主题组都包含提交契约字段 topic_domain_key、topic_domain_title、topic_group_key 和 topic_group_title。
• 不得为每项资产单独创建一个候选项。
• 不得将事件、属性或指标名称提升为项目语义标题。
• 每个候选项的 resource_refs 都要绑定真实资产的名称、类型和 ID，或包中的名称。
• 每个候选项都要说明其含义、适用范围、使用方式和排除项。
• 每个候选项的正文都要以项目使用的自然语言涵盖业务定义、适用问题、决策或计算规则、Agent 用法，以及边界或例外。具体标题不属于机器契约。
• 具体的业务判断应放在决策或计算内容中；资产名称和数量应放在 resource_refs、evidence 和 recommendation_reason 中，而非语义正文中。
• 如果一批候选项的正文相同，仅更换了资产名称或数量，则该批候选项无法通过审核。
• 每个候选项都要包含证据摘录或来源标题，说明推荐理由。
• 每个候选项都要改变 Agent 对业务问题的理解方式、默认资产选择方式，或项目级规则的应用方式。
• 每个候选项都要声明 query-routing-v5.md 中有证据支持的推荐类型之一：QUERY_ROUTING、RECALL_SHORTCUT 或 ANALYSIS_PLAYBOOK。
• 公式、阈值、状态、事件、属性、报表或资产名称都是辅助 L1 证据，不能单独作为候选项。
• 路由必须包含有意义的资产选择分支；捷径必须包含最小资源包、停止条件和回退方案；攻略必须有注释支持，或明确标记为依据结构推断的推荐路径。
• 提交前要检查已有的已发布和已禁用语义；已禁用语义不得重新创建。
• 只有在定义、工作单元结构、用法或注释提供佐证时，未认证资产才可用于支持路由、捷径或攻略。切勿仅因资产已导出，就将其描述为经过认证的项目规则。
• 证据稀少时，应跳过该项或标记较低置信度；不要夸大薄弱建议。

通用提取协议

该协议必须能够直接适用于游戏、零售、金融、SaaS、运营以及未知项目领域。

1. 盘点证据，不要预先判断主题。分别记录已认证和未认证的仪表板／报告，记录导出范围和选择原因，并将现有的受治理语义与支持性 L1 元数据区分开来。
2. 仅根据实际读取的证据发现语义族。将以下跨领域维度作为问题，而不是预填的答案：
   • 业务对象、状态和别名；
   • 分析主体和去重粒度；
   • 度量、聚合、分子、分母和转换；
   • 纳入范围、排除范围和筛选范围；
   • 查询范围、群组窗口、观察窗口和数据新鲜度；
   • 单位、货币、标准化和归因；
   • 默认资产选择以及资产之间的关系；
   • 适用性、例外和冲突边界。
3. 比较每个语义族内的定义变体。只有证据表明存在一个权威变体时，候选项才能声明默认值。存在冲突的变体时，必须提供消歧规则或警告，不得臆造标准。
4. 理解语义族后再形成主题领域。领域标题必须使用项目自然的业务语言，并说明为什么要将其候选项放在一起审查。
5. 只有移除某个候选项会导致未来的 Agent 更可能选错业务对象、资产、粒度、公式、范围、单位、窗口或例外时，才生成该候选项。
6. 对正文中的每项主张，都要找出直接支持该主张的证据。将资产名称和摘录放在 resource_refs、evidence 和 recommendation_reason 中；将可复用的业务知识放在 content 中。
7. 根据候选项对 Agent 行为的影响进行比较。将会导向相同解读和执行的候选项合并；将能独立检索的问题拆分为不同候选项。
8. 进行反例检查：审查可能违反拟议规则的少数定义和资产。缩小结论范围，或删除缺乏支持的结论。
9. 在编写候选项之前，先构建有证据支持的问题框架并分配资产角色。使用 query-routing-v5.md；不要为了候选项数量或每项资产对应一个候选项而优化。
10. 为发现的问题框架保留决策台账，记录路由、捷径、操作手册、仅定义和证据不足等处置方式。

防止过拟合规则

• 绝不在此技能或 CLI 生成代码中编码客户名称、项目名称、项目 ID、资产 ID、预期主题标题、预期候选项标题或预期候选项数量。
• 绝不从固定的行业分类体系或关键词词典入手。只有在发现语义族之后，关键词才能用于定位证据；不得用关键词决定结果。
• 测试包是评估样本，不是可复用规则的来源。只有当协议变更适用于其他无关领域时，才对其进行调整。
• 质量应以证据支持程度和 Agent 行为是否改变来衡量，而不是看是否匹配先前批准的主题列表。

面向用户的推荐展示

向用户展示 CLI 推荐结果时，绝不要将候选项压平成单一编号列表。面向用户的回答必须采用与候选项 JSON 和前端审核界面相同的层级结构：

Project semantic recommendation scan completed

Summary:
- Topic domains: <N>
- Candidate semantics: <N>
- Validation: passed | failed

Topic domain: <topic_domain_title> (<candidate_count> semantics)
- [<semantic_type>] <candidate title>
  <one-sentence summary>
  Evidence: <asset title 1>, <asset title 2>, ...

规则：

• 先展示主题领域，再展示各领域下的候选项。
• 包含每个领域的语义数量。
• 包含每个候选项的语义类型、标题、简短摘要和主要证据资产标题。
• 如果 CLI 命令返回 topic_groups，展示顺序和计数应直接使用该字段。
• 将完整 JSON 路径或提交命令与面向用户的摘要分开展示。
• 不要展示类似 1. semantic A 2. semantic B ... 的扁平列表，除非用户明确要求原始候选顺序。

输出规范

报告推荐结果时，请包含：

• 运行的命令；
• 资产范围、已导出／已认证／未认证资产数量，以及快照哈希；
• 主题领域、每个领域的语义数量，以及按领域分组的候选标题；
• 每个候选项的证据资产；
• 质量警告（如有）；
• 问题框架覆盖情况，以及被拒绝的浅层机会警告；
• 写入后提交／审核／发布 ID。