@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/blaze-investigation/investigation-report-template.md

@@ -0,0 +1,249 @@
+# Blaze Investigation 报告模板
+
+本模板由 `/ascendc-blaze-best-practice` Step 2 生成，固定写入 `<project-root>/operators/<operator_name>/docs/blaze/blaze-investigation-report.md`。文档内项目相对路径写为 `operators/<operator_name>/...`。它只记录 Blaze 源码调查事实，不给出项目路线、官方支持结论、场景匹配或实现建议。
+
+## 0. 报告元数据与 Blaze 源码边界
+
+```text
+report_kind: blaze_source_investigation
+project_root:
+operator_name:
+operator_root: <project-root>/operators/<operator_name>/
+project_contract_id:
+investigation_id:
+report_path: operators/<operator_name>/docs/blaze/blaze-investigation-report.md
+blaze_source_root: <project-root>/ops-tensor/
+target_chip:
+npu_arch:
+cann_version: <optional>
+source_version_status: current_checkout | same_investigation_source | consistent
+checkout_consistency: confirmed | blocking
+submodule_status:
+read_only_source_regions:
+  - <project-root>/ops-tensor/
+  - operators/<operator_name>/op_kernel/include/blaze/
+  - operators/<operator_name>/op_kernel/include/tensor_api/
+read_only_source_region_status:
+  blaze_source_root: confirmed | blocking
+  project_blaze_copy: confirmed | missing_for_exact_materialization | blocking
+  project_tensor_api_copy: confirmed | missing_for_exact_materialization | blocking
+read_only_source_region_evidence_refs:
+  blaze_source_root:
+  project_blaze_copy:
+  project_tensor_api_copy:
+source_read_roots:
+  - <project-root>/ops-tensor/
+actual_source_frontiers:
+unread_or_missing_areas:
+```
+
+机器字段含义：`upstream_read_roots`（如兼容记录需要）只能等于 `source_read_roots`，不得建立第二个源码根；`assembly_witness` 表示 Blaze 组装方案真实证据；`assembly_members` 表示其具体成员；`candidate_evaluation_id` 表示候选组装方案评估标识。Step 2 可以在没有 Step 1 handoff 时自行只读填写这些抽象状态，不读取 `environment.md`、外部 manifest 或其他工作流产物。项目内只读副本缺失不阻塞源码调查，但必须记录为 `missing_for_exact_materialization`，供 Step 3 编译一次性物化 action；根源码缺失或不一致仍为 `blocking`。
+
+## 1. 需求语义投影
+
+```text
+request_summary:
+math_contract:
+tensor_roles_and_extra_io:
+dtype_format_layout_constraints:
+topology_features:
+shape_and_tail_predicates:
+runtime_compile_time_axes:
+demand_partitions:
+hard_constraint_manifest:
+required_source_questions:
+out_of_scope:
+brief_amendments:
+```
+
+每个 requirement/constraint/source question 至少记录稳定 ID、适用 partitions、问题、重要性、来源和调查影响。Basic、Batch、Grouped、Quantized、MX 是可组合画像，不是预设路线或互斥场景。
+
+## 2. 调查范围与补充记录
+
+```text
+candidate_expansion_budget: 1
+candidate_expansion_log:
+supplement_scope: absent | completed
+supplement_history:
+  - requested_by: Step 3
+    attempt: 1
+    affected_requirement_ids:
+    semantic_questions:
+    required_blaze_source_frontier:
+    why_decision_is_blocked:
+    completion_evidence_ids:
+```
+
+`supplement_history` 最多一项。问题只描述待确认的需求语义和 Blaze 源码关系，不能包含场景 ID、场景路径、`blaze_custom`、路线或实现方案。
+
+## 3. 候选 Blaze 组装方案目录
+
+每个 discovery：
+
+```text
+discovery_id
+candidate_id
+partition_id
+candidate_result: found | not_found | unknown
+concrete_entry_seed
+coverage: indexed | deep | out_of_scope
+applicability_observations
+source_refs
+```
+
+每个 candidate evaluation：
+
+```text
+candidate_evaluation_id
+candidate_id
+partition_id
+assembly_status: complete | partial
+object_readiness: ready | partial | blocked | unknown
+assembly_witness:
+assembly_members:
+  kernel_entry
+  policy_and_specialization
+  block_mmad
+  block_scheduler
+  optional_epilogue
+  tilingdata_params_and_tiling_entry
+applicability_facts
+source_relationship_ids
+source_refs
+```
+
+`object_readiness` 只描述该对象事实是否闭合，不代表官方支持、项目可执行性或最终选型。`not_found` 不等于 `unsupported`。
+
+## 4. 依赖、Tiling 与 ABI 事实
+
+每个字段语义记录：
+
+```text
+fact_id
+candidate_evaluation_id_or_subject_id
+related_requirement_ids
+field_path
+field_type_and_unit
+consumer_and_semantics
+applies_when
+legal_domain_or_predicate
+cross_field_constraints
+tilingdata_mapping
+observed_value_scope
+evidence_status: source_observed | documented | example_assembled |
+                 not_applicable | conflict | unknown | unsupported
+source_refs
+```
+
+每个 ABI/API 记录：
+
+```text
+fact_id
+candidate_evaluation_id_or_subject_id
+caller_or_entry
+api_or_abi_element
+definition_or_specialization
+routing_and_guards
+arguments_returns_and_units
+effects_on_output_resource_or_sync
+related_requirement_ids
+evidence_status
+source_refs
+```
+
+## 5. 物理数据与输出数据流
+
+对每个 Tensor/metadata/额外 I/O 记录：
+
+```text
+tensor_fact_id
+role
+logical_shape_dtype_layout
+physical_shape_dtype_layout
+packing_padding_alignment
+index_stride_pitch_offset_and_units
+producer_consumer_and_location
+final_partial_and_lifecycle
+related_candidate_or_subject
+related_requirement_ids
+evidence_status
+source_refs
+```
+
+需求涉及输出后处理或 broadcast 时，只记录已观察到的 producer/consumer、mapping、adapter/同步（如存在）和未知事实。不得把这些记录组织为场景 bundle 或方案选择。
+
+## 6. 已观察限制与未闭合源码事实
+
+每个已观察限制或明确拒绝：
+
+```text
+observation_id
+related_requirement_ids
+candidate_or_subject_id
+classification: observed_limit | explicit_rejection
+fact
+scope_and_predicate
+source_refs
+```
+
+每个未闭合事实：
+
+```text
+unresolved_fact_id
+related_requirement_ids
+candidate_or_subject_id
+question
+searched_frontier
+why_unresolved
+evidence_status: unknown | conflict
+source_refs
+```
+
+`unsupported` 仅用于源码或官方约束明确拒绝的准确对象。`unknown`、未读范围、`not_found` 和缺失目录不得伪装成拒绝。
+
+## 7. 源码关系与证据账本
+
+```text
+source_relationships:
+  - relationship_id
+    relationship_kind: same_entry | caller_callee | type_reference |
+                       shared_params | shared_tiling_field | explicit_dispatch |
+                       explicit_prohibition
+    left_object_id
+    right_object_id
+    observed_constraint
+    source_refs
+
+evidence_ledger:
+  - evidence_id
+    source_kind: blaze_source | official_doc | example_or_ut
+    canonical_path
+    location
+    statement_or_observation
+    evidence_basis: source_observed | documented | example_assembled
+    related_object_ids
+    related_requirement_ids
+```
+
+## 8. 审计结论
+
+```text
+audit_checklist:
+  source_root_and_sibling_layout_confirmed:
+  recursive_submodules_confirmed:
+  normalized_chip_inputs_recorded:
+  project_copy_status_and_evidence_recorded:
+  request_projection_complete:
+  candidate_identity_and_witnesses_recorded:
+  dependency_and_physical_facts_recorded:
+  observed_limits_separated_from_unknowns:
+  read_boundaries_recorded:
+  supplement_limit_respected:
+  no_route_or_scene_fields:
+audit_notes:
+dependency_and_physical_data_facts: sections 4 and 5
+abi_and_signature_facts: section 4
+unresolved_source_facts: section 6
+```
+
+本报告结束时不写 `implementation_route`、`selected_scenario`、`unsupported_points`、官方支持状态、候选组合或场景匹配。Step 3 用精确需求消费本报告并作出唯一决策。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/blaze-investigation/source-investigation-method.md

@@ -0,0 +1,131 @@
+# Blaze 源码调查方法
+
+本文定义 Step 2 的 Brief、源码导航和候选/证据对象发现。它只建立 Blaze 源码事实，不恢复完整组装方案、不选择项目方案，也不读取场景注册表。
+
+## 1. 调查 Brief
+
+从 `project_root` 派生 `<project-root>/ops-tensor/`，只读复核当前 Blaze 源码版本、递归 submodule、一致性和只读边界，再将用户需求投影为以下调查 Brief。Step 1 handoff 可选；不存在时直接对当前 checkout 建立抽象状态，不读取外部工作流产物：
+
+```text
+request_summary
+math_contract
+tensor_roles_and_extra_io
+topology_features
+numeric_modes
+dtype_format_layout_constraints
+runtime_compile_time_axes
+demand_partitions
+hard_constraint_manifest
+required_source_questions
+out_of_scope
+candidate_expansion_budget: 1
+supplement_scope: absent | one semantic request
+```
+
+Basic、Batch、Grouped、Quantized、MX 不是互斥场景。按 topology、numeric、layout、transpose、dtype、shape 和额外 I/O 建立正交画像；只有会改变 specialization、真实入口、物理数据或 ABI 的轴才拆分 `demand_partition`。Shape 使用谓词域，不枚举数值，也不展开用户未要求的组合。
+
+每项 hard constraint 和 source question 必须有稳定 ID、适用条件、作用域、重要性和预期事实。发现新的 compile-time 轴时，记录 `brief_amendment`，使受影响对象重新核验；不得借 amendment 缩小用户范围。
+
+需求中的融合、广播或额外输出仅作为语义探针：记录需调查的数据依赖、逻辑/物理 mapping、输出时机或协作关系。它们不映射到场景 ID，也不预判开发路线。
+
+## 2. 补充调查边界
+
+Step 3 可向下一轮同一 Investigation 报告提出一次 `supplement_scope`。它仅包含：
+
+```text
+requested_by: Step 3
+attempt: 1
+affected_requirement_ids
+semantic_questions
+required_blaze_source_frontier
+why_decision_is_blocked
+```
+
+补充问题必须以需求语义和待确认的 Blaze 源码关系表述，例如“确认某输出路径的物理 shape、地址单位和完成时机”。不得出现注册表、场景 ID、场景文档、custom 路线或实现建议。Step 2 只在原范围之外追踪该有界前沿；补充后仍未知的事实写入报告，不自行继续扩展。
+
+## 3. 数据源和阅读顺序
+
+Blaze 源码能力只来自当前 `<project-root>/ops-tensor/` 工作区；不得回退到 `operators/<operator_name>/`、其他项目或历史工程：
+
+| 数据源 | 首要用途 | 证据依据 |
+|---|---|---|
+| `examples/`、`tests/UT/`、真实 wrapper/入口 | concrete 实例化与调用链种子 | `example_assembled` 或 `source_observed` |
+| `include/blaze/` | 公开定义、specialization、Params、架构守卫 | `source_observed` |
+| 实际 Tiling 目录 | TilingData/Params 消费和字段来源 | `source_observed` |
+| `include/tensor_api/` | 已发现调用的 API 定义与 Routing | `source_observed` |
+| 官方 API 文档 | 源码无法独立解释的语义 | `documented` |
+| README、构建文件 | include、架构与入口线索 | 线索，不能单独证明能力 |
+
+阅读顺序固定为：
+
+1. 从完整 demand partition 对应的 example、UT、wrapper 和真实 Kernel 入口寻找 using、alias、实例化和调用点。
+2. 回到公开定义解析 specialization、模板参数、Params 和架构守卫。
+3. 没有 concrete 种子时，才从目标公开 Kernel/Policy/Block 反向寻找 caller。
+4. 仅为解释候选实际语义读取 API 文档和构建文件。
+5. 不深挖未进入候选链的组件，不按相似文件名扩大范围。
+
+缺失目录记录为 `missing` 及其调查影响，不得写成 `unsupported`。Blaze skill Asset、历史 recipe 和项目代码不是 Blaze 源码证据。
+
+## 4. 候选与证据对象
+
+候选 Blaze 组装方案按需求语义和 demand partition 发现：
+
+```text
+candidate_discovery
+  discovery_id
+  partition_id
+  candidate_result: found | not_found | unknown
+  concrete_entry_seed
+  coverage: indexed | deep | out_of_scope
+  applicability_observations
+  source_refs
+```
+
+同一 concrete candidate 在不同 partition 下生成独立 `candidate_evaluation_id`。Candidate ID 标识真实入口/specialization，不承载项目可行性或路线状态。
+
+非组装方案证据对象使用：
+
+```text
+evidence_subject
+  subject_id
+  subject_kind: dataflow | physical_mapping | api | abi | sync | constraint
+  related_requirement_ids
+  source_frontier
+  subject_result: found | not_found | unknown
+  coverage: indexed | deep | out_of_scope
+```
+
+组件、接口、数据生产/消费点和同步控制流不得伪装成 Blaze 组装方案。`found` 只表示对象已经定位；原子事实仍须由依赖追溯闭合。
+
+## 5. 动态调查问题
+
+所有请求都调查 MatMul 基础链；再按需求添加问题：
+
+| 需求维度 | 调查增量 |
+|---|---|
+| Batch | batch 语义、stride/broadcast、metadata、入口与调度 |
+| Grouped | group metadata、per-group shape/offset、ordering/tail、workspace/final timing、group-aware ABI |
+| Quantized | scale/zero-point、packing/alignment、累加/转换与 specialization |
+| MX | scale metadata、packing/alignment、K-tail、layout 与 specialization |
+| 额外 I/O 或输出后处理 | 实际输出数据流、额外 operand 映射、物理地址和相关协作事实 |
+
+问题只要求事实，不证明不同维度能组合。Grouped Plain、Grouped Quantized、Grouped MX 必须分别在完整 partition 画像上找到 concrete witness。
+
+## 6. 一次候选扩展
+
+直接追踪已发现对象的真实定义和依赖不消耗额度。只有已声明问题在当前前沿没有答案、且源码显示存在有限相邻前沿时，才能消耗全报告一次候选广度扩展：
+
+1. 冻结触发 requirement、partition、起始对象和允许入口/sibling/dispatch 列表。
+2. 先检查同一真实入口显式列出的 sibling specialization。
+3. 再检查 dispatch 明确引用的 fallback 或当前候选实际引用的同族入口。
+4. 不按相似文件名、相邻目录或“可能兼容”扩大扫描。
+5. 新对象只用于关闭冻结问题，不递归产生第二次扩展。
+
+## 7. 产物与门禁
+
+本阶段产出 Brief、constraint/source-question definitions、候选 discoveries、证据 subjects、实际读取根、缺失/未读范围与扩展日志。
+
+- 每个已调查 partition 和 subject 必须有 `found`、`not_found` 或 `unknown`。
+- `not_found` 只表示冻结范围内没有发现，不能升级为 `unsupported`。
+- `indexed` 不能作为 Step 3 的完整设计依据；只有后续方法闭合 required facts 后才能记录 `deep`。
+- concrete candidate 进入[Blaze 组装方案恢复方法](assembly-recovery-method.md)；非组装方案证据对象进入[依赖追溯方法](dependency-trace-method.md)。

package/assets/ops-direct-invoke/skills/ascendc-blaze-best-practice/references/fundamentals/blaze-cmake-build-guide.md

@@ -0,0 +1,184 @@
+# Blaze 项目 CMake 编写指导
+
+> **定位**：Step 3 在生成包含 CMake configure/build action 的 PLAN 时读取本文，用于形成可执行的初始构建方案。本文不选择 Blaze 组装方案，不要求 Step 3 预判实际编译时才会暴露的配置问题，也不增加专用编译合同字段。
+
+## 1. 先执行的结论
+
+1. **优先使用项目内同源副本。** Kernel 构建使用由 Step 1 建立，或由 PLAN create-only 初始化 action 从当前 Blaze 源码原样物化到项目内只读区的 `blaze/`、`tensor_api/` 和确有依赖的同源公共头，不引用其他项目、历史副本或项目外源码目录。
+2. **CANN 只承担必要职责。** CANN 提供编译器、运行时，以及当前 Blaze/tensor_api 没有等价接口时确有必要的头文件和库；不要把宽泛 CANN include 或固定库清单作为默认配置。
+3. **配置绑定到具体 target。** 使用 `target_include_directories`、`target_compile_options` 和 `target_link_libraries`，避免全局 include/link 配置掩盖依赖来源。
+4. **PLAN 只冻结构建目标和验收结果。** 将项目构建文件登记为可修改目标，建立 configure/build action 与构建 checkpoint；include 顺序、编译选项和链接细节可在 Step 4 根据真实编译证据调整。
+5. **保持项目自包含。** 项目源码、项目内副本、生成物和自有依赖位于 `<project-root>/operators/<operator_name>/`；项目外位置只作为明确的工具链或只读资料来源。
+
+## 2. PLAN 中的最小构建信息
+
+若项目需要 CMake 构建，Step 3 使用现有 PLAN 结构记录：
+
+- 在 `target_file_manifest` 中列出项目 `CMakeLists.txt` 或实际构建文件，作为 Step 4 的初始构建基线；
+- 在 `ordered_actions` 中写明 configure/build 目标和预期产物；
+- 在 `validation_checkpoints` 中写明构建成功判据；
+- 在 `failure_rollback` 中要求保留错误和实际命令，并进入 Step 4 排障。
+
+不新增编译状态、环境 manifest 或专用构建合同。Step 3 无需通过预处理、include trace 或试编译提前证明全部构建细节。
+
+## 3. 目标级 CMake 骨架
+
+以下骨架只表达配置归属关系。尖括号内容按当前项目、工具链和 PLAN action 替换，不是固定库清单或可直接复制的 recipe。
+
+```cmake
+cmake_minimum_required(VERSION <current-project-minimum>)
+project(<project-name> LANGUAGES CXX)
+
+# 仅在当前工具链和项目入口使用 ASC CMake language module 时启用。
+find_package(ASC REQUIRED)
+enable_language(ASC)
+
+set(PROJECT_ROOT "${CMAKE_CURRENT_SOURCE_DIR}")
+set(PROJECT_INCLUDE_ROOT "${PROJECT_ROOT}/op_kernel/include")
+
+add_executable(<build-target>
+    <authorized-host-source>
+    <authorized-kernel-or-wrapper-source>
+    <authorized-tiling-source>
+)
+
+set_source_files_properties(
+    <authorized-asc-source>
+    PROPERTIES LANGUAGE ASC
+)
+
+target_include_directories(<build-target> PRIVATE
+    "${PROJECT_INCLUDE_ROOT}"
+    <project-local-blaze-public-include-root>
+    <project-local-tensor-api-public-include-root>
+    <other-required-project-local-include-root>
+)
+
+target_compile_options(<build-target> PRIVATE
+    "$<$<COMPILE_LANGUAGE:ASC>:<required-asc-option>>"
+    "$<$<COMPILE_LANGUAGE:ASC>:<required-target-option>>"
+)
+
+target_link_libraries(<build-target> PRIVATE
+    <libraries-required-by-current-project>
+)
+```
+
+使用骨架时：
+
+- 显式列出 Kernel、Wrapper、Tiling 和 Launcher 源文件，不用目录通配符隐藏 target 输入；
+- 只对设备侧源文件设置 ASC 语言和设备编译选项；
+- 只加入当前符号和运行时确实需要的库；
+- 当前工具链不使用示例中的 ASC CMake module 时，沿用项目实际可用的构建入口，不为匹配示例重写工具链。
+
+### 3.1 Host、ASC Host 与 Device 的分层核验
+
+同一工程可能同时包含普通 CXX Host、由 ASC 联合编译产生的 Host 部分和
+Device entry。`__CCE_AICORE__` 等设备宏只描述当前编译上下文，不能作为
+跨上下文 API 的唯一边界。把 Host 声明或定义包在设备专用宏内，可能使普通
+CXX 看不到它们；把 Host-only 实现暴露给 Device，又可能产生错误的符号或
+语言依赖。
+
+因此，PLAN 必须为实际存在的每种上下文写明 source、include 和语言归属，且
+至少分别验证：
+
+1. 普通 CXX Host 编译能看到所需 Host 声明和定义；
+2. ASC Host（工具链提供该编译阶段时）能看到联合入口需要的 Host 部分；
+3. Device entry 能看到 `__aicore__`/设备 helper 及其真实 ABI。
+
+共享头应按上下文拆分声明，或用当前 target 的真实预处理结果证明宏分支在三种
+上下文中都闭合。仅看到某个 `.asc` 文件存在 Host 分支，或仅通过普通 CXX
+编译，均不能证明联合编译和 Device entry 的符号闭合。
+
+### 3.2 独立 Host/CTest 的可选平台探针
+
+独立 Host 或 CTest target 可能没有运行时注入的完整平台对象；普通 Host
+预检中调用平台查询时，`PlatformAscendCManager` 或等价 probe 可能为空。可选
+平台探针必须先判空并记录 `probe skipped`，不能把空指针解引用伪装成 Tiling 或
+Device kernel 失败。
+
+Host 侧需要的平台事实分为两类：
+
+1. **必需事实**：当前 Host Tiling 算法没有它就无法构造合法 Params，应在该
+   target 的构建/运行合同中显式提供并在缺失时阻断；
+2. **诊断/优化探针**：只用于打印或选择非冻结路径，可在独立 CTest 中跳过，
+   但必须保留跳过原因，并单独验证 Host contract、target link/CTest 注册和
+   设备路径。
+
+不能为了让 CTest 通过而伪造平台库、探测零维资源或声明设备 PASS；具体 manager
+符号和 fallback 值仍以当前源码、DESIGN/PLAN 和实际 target 为准。
+
+### 3.3 CTest 与生成数据的前置闭合
+
+依赖 `data/input`、Golden 或 manifest 的 CTest 不能假设这些文件已经存在，也
+不能从旧目录补读。PLAN/Step 4 必须把数据生成和完整性校验作为 CTest 前置
+checkpoint，或者让测试自身在隔离临时目录中完成同一生成动作；生成器必须校验
+shape、dtype、`group_list`/metadata 和文件字节数，定向谓词还要在 manifest 中
+可复算并由测试入口断言。
+
+运行 CTest 前先用 `ctest -N`（或等价方法）确认预期测试已注册且测试数量非零，
+再使用本次 clean build 产物执行。缺失、截断、拒绝生成或 metadata 不匹配是
+Host/test-setup 失败，不是 Kernel、Tiling 或设备精度失败；应保留生成命令、
+实际输入目录和返回码，修复前不得继续汇总为 `device_verified`。不能用
+`set -e`、批处理返回码或历史输出掩盖单 case generator/verifier 失败。
+
+## 4. Blaze/tensor_api 与 CANN 的边界
+
+项目内编译输入通常位于：
+
+```text
+<project-root>/ops-tensor/                                      # Blaze 源码调查根，只读
+operators/<operator_name>/op_kernel/include/blaze/              # 同源项目副本，只读
+operators/<operator_name>/op_kernel/include/tensor_api/         # 同源项目副本，只读
+```
+
+构建使用项目内副本，不直接依赖 `ops-tensor/` 调查根。若 Blaze/tensor_api 的真实 include 链需要其他同源公共头，将其复制到项目只读区并以 target 级路径接入；不要引用其他工程或本机历史目录。
+
+复制或适配时不能只按文件名平铺。若源文件使用相对路径或项目根路径
+include，目标副本必须保留能使这些 include 解析的相对目录拓扑；有意迁移目录时，
+PLAN 必须同时冻结源到目标映射、include root 和必要的 include 改写。复制完成后，
+使用目标实际 compiler、语言模式、架构参数和 include roots 执行 include-closure
+预检或最小编译探针，确认直接及递归 include 都来自授权项目副本或工具链例外。
+
+CANN 头文件或库只有在以下情况接入对应 target：
+
+- ASC 编译器和设备语言本身需要；
+- Launcher、运行时或设备调用没有 Blaze/tensor_api 等价入口；
+- 选定 Blaze 组装方案的真实源码依赖直接要求。
+
+接入后仍应避免把整个 CANN include 或 link 目录全局暴露给所有 target。
+
+## 5. 编译期调整原则
+
+初始配置不能保证覆盖所有工具链差异。Step 4 应以实际 configure、compile 和 link 输出为准，在 `<project-root>/operators/<operator_name>/` 内修复或补充实现和构建文件，并重新执行受影响 checkpoint。
+
+静态库目标还必须核对当前 CANN/toolchain 的完整链接闭包：不仅要记录直接
+调用的库，还要从实际 link command 和符号解析结果确认其传递依赖、库顺序和
+版本来源。某个库“在头文件中可见”不代表它的实现依赖已经进入 target；清洁
+链接仍出现未解析符号时，应归类为当前 target 的依赖闭包缺口，不能复制其他
+工程或其他 CANN 版本的固定库清单。需要新增外部二进制依赖时回 Step 3 更新构建合同。
+
+允许的实现期调整包括：
+
+- 修正 ASC/host 源文件归属；
+- 调整项目内 include 路径和顺序；
+- 增减当前 target 的必要编译选项；
+- 修正当前项目和既有工具链/运行时依赖的链接配置。
+
+`-iquote` 不是默认选项。只有真实错误和头文件解析结果表明引号形式 include 选中了错误同名头，而项目内同源副本包含所需定义时，才对受影响的 ASC target 增加项目内 quote 路径。它不能修复尖括号 include、ABI 不一致或源码版本不兼容。
+
+如果修复需要改变 Blaze 组装方案、接口/ABI、数据语义、支持范围或验证范围，停止实现并返回 Step 3；需要新的 Blaze 源码事实时先回 Step 2。项目内新增文件不单独触发回退，新的外部依赖仍需回 Step 3 评估。
+
+## 6. 编译器与 include 原理
+
+### 6.1 ASC 语言与设备编译
+
+CMake 的语言启用、源文件 `LANGUAGE ASC` 属性和 target 编译选项共同决定设备侧命令。不同工具链可能以不同方式注入语言、平台和内置头路径，因此最终行为以实际 target 命令为准，不能只看 `CMakeLists.txt`。
+
+### 6.2 引号、尖括号与搜索路径
+
+`#include "..."` 与 `#include <...>` 使用的搜索路径类别不同。普通 `-I`、系统路径、编译器内置路径和 `-iquote` 的顺序取决于实际 compiler 与语言模式。同名头影响编译时，应查看当前 target 的真实命令和必要的预处理/include trace，再做最小调整。
+
+### 6.3 为什么优先同源副本
+
+Blaze 与 tensor_api 的模板、内部 include 和编译期约束通常需要同一 Blaze 源码版本下的定义协同工作。混用项目内副本、CANN 同名头和其他版本源码，可能产生声明、宏、模板或 constexpr 语义不一致。优先使用项目内同源副本，可以将工具链头限制在确有必要的边界内。