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

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/scripts/extract_dtype_combinations.py

@@ -0,0 +1,200 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+"""
+Dtype 组合提取工具
+
+功能：从 def 文件提取 dtype 组合，输出 JSON 和测试用例模板
+"""
+
+import re
+import json
+import sys
+import logging
+from typing import List, Dict, Optional
+
+DTYPE_MAP = {
+    "ge::DT_FLOAT": "ACL_FLOAT",
+    "ge::DT_FLOAT16": "ACL_FLOAT16",
+    "ge::DT_BF16": "ACL_BF16",
+    "ge::DT_INT8": "ACL_INT8",
+    "ge::DT_INT16": "ACL_INT16",
+    "ge::DT_INT32": "ACL_INT32",
+    "ge::DT_INT64": "ACL_INT64",
+    "ge::DT_UINT8": "ACL_UINT8",
+    "ge::DT_UINT16": "ACL_UINT16",
+    "ge::DT_UINT32": "ACL_UINT32",
+    "ge::DT_UINT64": "ACL_UINT64",
+    "ge::DT_BOOL": "ACL_BOOL",
+    "ge::DT_DOUBLE": "ACL_DOUBLE",
+    "ge::DT_HIFLOAT8": "ACL_HIFLOAT8",
+    "ge::DT_FLOAT8_E5M2": "ACL_FLOAT8_E5M2",
+    "ge::DT_FLOAT8_E4M3FN": "ACL_FLOAT8_E4M3FN",
+}
+
+
+def _parse_tensor_dtype(content: str, name: str, tensor_type: str) -> Optional[Dict]:
+    """解析单个 Tensor 的 dtype 信息"""
+    array_pattern = rf'this->{tensor_type}\("{name}"\).*?\.DataType\(\{{([^}}]+)\}}\)'
+    list_pattern = rf'this->{tensor_type}\("{name}"\).*?\.DataTypeList\(\{{([^}}]+)\}}\)'
+    
+    dtype_array_match = re.search(array_pattern, content, re.DOTALL)
+    dtype_list_match = re.search(list_pattern, content, re.DOTALL)
+    
+    if dtype_array_match:
+        dtypes = re.findall(r'ge::DT_\w+', dtype_array_match.group(1))
+        return {"name": name, "type": "array", "dtypes": dtypes,
+                "acl_dtypes": [DTYPE_MAP.get(d, d) for d in dtypes]}
+    elif dtype_list_match:
+        dtypes = re.findall(r'ge::DT_\w+', dtype_list_match.group(1))
+        return {"name": name, "type": "list", "dtypes": dtypes,
+                "acl_dtypes": [DTYPE_MAP.get(d, d) for d in dtypes]}
+    return None
+
+
+def parse_def_file(file_path: str) -> Dict:
+    with open(file_path, 'r') as f:
+        content = f.read()
+    
+    inputs = []
+    outputs = []
+    
+    for match in re.finditer(r'this->Input\("([^"]+)"\)', content):
+        info = _parse_tensor_dtype(content, match.group(1), "Input")
+        if info:
+            inputs.append(info)
+    
+    for match in re.finditer(r'this->Output\("([^"]+)"\)', content):
+        info = _parse_tensor_dtype(content, match.group(1), "Output")
+        if info:
+            outputs.append(info)
+    
+    return {"inputs": inputs, "outputs": outputs}
+
+
+def generate_combinations(parsed: Dict) -> Dict:
+    array_inputs = [inp for inp in parsed["inputs"] if inp["type"] == "array"]
+    array_outputs = [out for out in parsed["outputs"] if out["type"] == "array"]
+    list_inputs = [inp for inp in parsed["inputs"] if inp["type"] == "list"]
+    list_outputs = [out for out in parsed["outputs"] if out["type"] == "list"]
+    
+    if not array_inputs:
+        combination_count = 0
+    else:
+        lengths = [len(inp["dtypes"]) for inp in array_inputs]
+        if len(set(lengths)) != 1:
+            return {
+                "error": "DataType 数组长度不一致",
+                "details": {inp["name"]: len(inp["dtypes"]) for inp in array_inputs}
+            }
+        combination_count = lengths[0]
+    
+    combinations = []
+    for i in range(combination_count):
+        combo = {"position": i}
+        for inp in array_inputs:
+            combo[inp["name"]] = inp["acl_dtypes"][i]
+        for inp in list_inputs:
+            combo[inp["name"]] = inp["acl_dtypes"][0] if inp["acl_dtypes"] else "UNKNOWN"
+        for out in array_outputs:
+            combo[out["name"]] = out["acl_dtypes"][i]
+        for out in list_outputs:
+            combo[out["name"]] = out["acl_dtypes"][0] if out["acl_dtypes"] else "UNKNOWN"
+        combinations.append(combo)
+    
+    fixed_dtypes = {}
+    for inp in list_inputs:
+        fixed_dtypes[inp["name"]] = inp["acl_dtypes"][0] if inp["acl_dtypes"] else "UNKNOWN"
+    for out in list_outputs:
+        fixed_dtypes[out["name"]] = out["acl_dtypes"][0] if out["acl_dtypes"] else "UNKNOWN"
+    
+    return {
+        "combination_count": combination_count,
+        "combinations": combinations,
+        "fixed_dtypes": fixed_dtypes
+    }
+
+
+def generate_test_code(op_name: str, combinations: List[Dict]) -> str:
+    lines = []
+    
+    for combo in combinations:
+        pos = combo["position"]
+        test_name = f"TEST_F(l2_{op_name}_test, case_{pos}_dtype)"
+        lines.append(test_name + " {")
+        
+        tensor_lines = []
+        for name, dtype in combo.items():
+            if name == "position":
+                continue
+            tensor_lines.append(f"    auto {name} = TensorDesc({{2, 3}}, {dtype}, ACL_FORMAT_ND);")
+        
+        lines.extend(tensor_lines)
+        lines.append("    uint64_t workspace_size = 0;")
+        lines.append("    EXPECT_EQ(ut.TestGetWorkspaceSize(&workspace_size), ACL_SUCCESS);")
+        lines.append("}")
+        lines.append("")
+    
+    return "\n".join(lines)
+
+
+def main():
+    logging.basicConfig(level=logging.INFO, format='%(message)s', stream=sys.stdout)
+    
+    if len(sys.argv) < 2:
+        logging.error("用法: python extract_dtype_combinations.py <def_file>")
+        logging.error("示例: python extract_dtype_combinations.py add_def.cpp")
+        sys.exit(1)
+    
+    def_file = sys.argv[1]
+    op_name = def_file.replace("_def.cpp", "").split("/")[-1]
+    
+    logging.info(f"解析文件: {def_file}")
+    logging.info(f"算子名称: {op_name}")
+    logging.info("=" * 60)
+    
+    parsed = parse_def_file(def_file)
+    
+    logging.info(f"\n输入 Tensor:")
+    for inp in parsed["inputs"]:
+        logging.info(f"  {inp['name']}: {inp['type']}, dtypes={inp['acl_dtypes'][:5]}...")
+    
+    logging.info(f"\n输出 Tensor:")
+    for out in parsed["outputs"]:
+        logging.info(f"  {out['name']}: {out['type']}, dtypes={out['acl_dtypes'][:5]}...")
+    
+    result = generate_combinations(parsed)
+    
+    if "error" in result:
+        logging.error(f"\n错误: {result['error']}")
+        logging.error(f"详情: {result['details']}")
+        sys.exit(1)
+    
+    logging.info(f"\n组合数量: {result['combination_count']}")
+    logging.info("\n合法 dtype 组合:")
+    for combo in result["combinations"]:
+        logging.info(f"  位置 {combo['position']}: {combo}")
+    
+    if result["fixed_dtypes"]:
+        logging.info(f"\n固定 dtype: {result['fixed_dtypes']}")
+    
+    output_json = f"/tmp/{op_name}_dtype_combinations.json"
+    with open(output_json, 'w') as f:
+        json.dump(result, f, indent=2)
+    logging.info(f"\nJSON 输出: {output_json}")
+    
+    logging.info("\n测试用例模板:")
+    logging.info("-" * 60)
+    test_code = generate_test_code(op_name, result["combinations"])
+    logging.info(test_code)
+
+
+if __name__ == "__main__":
+    main()

package/assets/ops-direct-invoke/skills/ascendc-ut-develop/scripts/generate_csv_template.py

@@ -0,0 +1,270 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+"""
+Ascend C Host UT CSV 重构辅助脚本
+
+功能：
+1. 从 xxx_def.cpp 自动提取算子定义信息（输入/输出/属性）
+2. 自动生成 CSV 列名行模板
+3. 自动生成 param.h 结构体框架
+"""
+
+import re
+import sys
+import logging
+from typing import List, Tuple
+from dataclasses import dataclass
+
+
+@dataclass
+class TensorInfo:
+    """Tensor 信息"""
+    name: str
+    param_type: str  # REQUIRED, DYNAMIC, OPTIONAL
+    data_types: List[str]
+    formats: List[str]
+
+
+@dataclass
+class AttrInfo:
+    """属性信息"""
+    name: str
+    attr_type: str  # REQUIRED, OPTIONAL
+    cpp_type: str   # Int, Float, String, Bool
+    default_value: str
+
+
+def parse_def_file(file_path: str) -> Tuple[List[TensorInfo], List[TensorInfo], List[AttrInfo]]:
+    """
+    解析 xxx_def.cpp 文件，提取算子定义信息
+    
+    Args:
+        file_path: def.cpp 文件路径
+    
+    Returns:
+        (inputs, outputs, attrs): 输入/输出/属性列表
+    """
+    with open(file_path, 'r', encoding='utf-8') as f:
+        content = f.read()
+    
+    inputs = []
+    outputs = []
+    attrs = []
+    
+    # 提取输入 Tensor
+    input_pattern = r'this->Input\("([^"]+)"\)\s*\.ParamType\(([^)]+)\)'
+    for match in re.finditer(input_pattern, content):
+        name = match.group(1)
+        param_type = match.group(2)
+        
+        # 提取 DataType（简化处理，实际可能需要更复杂的解析）
+        dtype_pattern = rf'this->Input\("{name}"\).*?\.DataTypeList?\(\{{([^}}]+)\}}\)'
+        dtype_match = re.search(dtype_pattern, content, re.DOTALL)
+        data_types = []
+        if dtype_match:
+            dtypes_str = dtype_match.group(1)
+            data_types = re.findall(r'ge::DT_\w+', dtypes_str)
+        
+        # 提取 Format
+        format_pattern = rf'this->Input\("{name}"\).*?\.FormatList\(\{{([^}}]+)\}}\)'
+        format_match = re.search(format_pattern, content, re.DOTALL)
+        formats = []
+        if format_match:
+            formats_str = format_match.group(1)
+            formats = re.findall(r'ge::FORMAT_\w+', formats_str)
+        
+        inputs.append(TensorInfo(name, param_type, data_types[:5], formats[:1]))  # 只取前5个dtype示例
+    
+    # 提取输出 Tensor
+    output_pattern = r'this->Output\("([^"]+)"\)\s*\.ParamType\(([^)]+)\)'
+    for match in re.finditer(output_pattern, content):
+        name = match.group(1)
+        param_type = match.group(2)
+        
+        dtype_pattern = rf'this->Output\("{name}"\).*?\.DataTypeList?\(\{{([^}}]+)\}}\)'
+        dtype_match = re.search(dtype_pattern, content, re.DOTALL)
+        data_types = []
+        if dtype_match:
+            dtypes_str = dtype_match.group(1)
+            data_types = re.findall(r'ge::DT_\w+', dtypes_str)
+        
+        format_pattern = rf'this->Output\("{name}"\).*?\.FormatList\(\{{([^}}]+)\}}\)'
+        format_match = re.search(format_pattern, content, re.DOTALL)
+        formats = []
+        if format_match:
+            formats_str = format_match.group(1)
+            formats = re.findall(r'ge::FORMAT_\w+', formats_str)
+        
+        outputs.append(TensorInfo(name, param_type, data_types[:5], formats[:1]))
+    
+    # 提取属性
+    attr_pattern = r'this->Attr\("([^"]+)"\)\.AttrType\(([^)]+)\)\.(\w+)\(([^)]+)\)'
+    for match in re.finditer(attr_pattern, content):
+        name = match.group(1)
+        attr_type = match.group(2)
+        cpp_type = match.group(3)
+        default_value = match.group(4)
+        
+        attrs.append(AttrInfo(name, attr_type, cpp_type, default_value))
+    
+    return inputs, outputs, attrs
+
+
+def generate_csv_headers(inputs: List[TensorInfo], outputs: List[TensorInfo], 
+                         attrs: List[AttrInfo], test_type: str = "infershape") -> str:
+    """
+    生成 CSV 列名行
+    
+    Args:
+        inputs: 输入 Tensor 列表
+        outputs: 输出 Tensor 列表
+        attrs: 属性列表
+        test_type: 测试类型（tiling 或 infershape）
+    
+    Returns:
+        CSV 列名行字符串
+    """
+    headers = ["case_name", "expectResult"]
+    
+    # 输入 Tensor 列
+    for tensor in inputs:
+        headers.extend([f"{tensor.name}_shape", f"{tensor.name}_dtype", f"{tensor.name}_format"])
+    
+    # 输出 Tensor 列
+    for tensor in outputs:
+        headers.extend([f"{tensor.name}_shape", f"{tensor.name}_dtype", f"{tensor.name}_format"])
+    
+    # 属性列
+    for attr in attrs:
+        headers.append(attr.name)
+    
+    # 测试类型专用列
+    if test_type == "tiling":
+        headers.extend(["expectTilingKey", "expectTilingDataHash"])
+    
+    headers.append("case_annotation")
+    
+    return ",".join(headers)
+
+
+def generate_param_struct(inputs: List[TensorInfo], outputs: List[TensorInfo], 
+                         attrs: List[AttrInfo], op_name: str) -> str:
+    """
+    生成 param.h 结构体框架（简化版）
+    
+    Args:
+        inputs: 输入 Tensor 列表
+        outputs: 输出 Tensor 列表
+        attrs: 属性列表
+        op_name: 算子名称（小写）
+    
+    Returns:
+        结构体代码框架
+    """
+    op_name_camel = "".join(word.capitalize() for word in op_name.split("_"))
+    op_name_upper = op_name.upper()
+    
+    code = f"// {op_name_camel} 参数结构体框架\n"
+    code += f"// 需要手动调整和补充完整\n\n"
+    
+    # 属性字段
+    code += "// 属性字段\n"
+    for attr in attrs:
+        cpp_type_map = {
+            "Int": "int64_t",
+            "Float": "float",
+            "String": "std::string",
+            "Bool": "bool"
+        }
+        cpp_type = cpp_type_map.get(attr.cpp_type, "int64_t")
+        code += f"{cpp_type} {attr.name};  // {attr.attr_type}, default: {attr.default_value}\n"
+    
+    # 输入 Tensor 字段
+    code += "\n// 输入 Tensor 字段（Tiling 测试）\n"
+    for tensor in inputs:
+        code += f"gert::TilingContextPara::TensorDescription {tensor.name} = TD_DEFAULT;  // {tensor.param_type}\n"
+    
+    # 输出 Tensor 字段
+    code += "\n// 输出 Tensor 字段（Tiling 测试）\n"
+    for tensor in outputs:
+        code += f"gert::TilingContextPara::TensorDescription {tensor.name} = TD_DEFAULT;  // {tensor.param_type}\n"
+    
+    return code
+
+
+def main():
+    logging.basicConfig(level=logging.INFO, format='%(message)s', stream=sys.stdout)
+    
+    if len(sys.argv) < 2:
+        logging.error("使用方法: python generate_csv_template.py <xxx_def.cpp>")
+        logging.error("示例: python generate_csv_template.py fused_infer_attention_score_def.cpp")
+        sys.exit(1)
+    
+    def_file = sys.argv[1]
+    
+    # 解析 def 文件
+    inputs, outputs, attrs = parse_def_file(def_file)
+    
+    logging.info(f"\n找到 {len(inputs)} 个输入 Tensor:")
+    for tensor in inputs:
+        logging.info(f"  - {tensor.name}: {tensor.param_type}")
+    
+    logging.info(f"\n找到 {len(outputs)} 个输出 Tensor:")
+    for tensor in outputs:
+        logging.info(f"  - {tensor.name}: {tensor.param_type}")
+    
+    logging.info(f"\n找到 {len(attrs)} 个属性:")
+    for attr in attrs:
+        logging.info(f"  - {attr.name}: {attr.cpp_type} ({attr.attr_type})")
+    
+    # 生成 CSV 列名行
+    logging.info("\n" + "=" * 80)
+    logging.info("CSV 列名行（InferShape 测试）:")
+    logging.info("=" * 80)
+    csv_headers = generate_csv_headers(inputs, outputs, attrs, "infershape")
+    logging.info(csv_headers)
+    
+    logging.info("\n" + "=" * 80)
+    logging.info("CSV 列名行（Tiling 测试）:")
+    logging.info("=" * 80)
+    csv_headers_tiling = generate_csv_headers(inputs, outputs, attrs, "tiling")
+    logging.info(csv_headers_tiling)
+    
+    # 生成参数结构体框架
+    op_name = def_file.replace("_def.cpp", "")
+    logging.info("\n" + "=" * 80)
+    logging.info("参数结构体框架:")
+    logging.info("=" * 80)
+    param_struct = generate_param_struct(inputs, outputs, attrs, op_name)
+    logging.info(param_struct)
+    
+    # 保存到文件
+    output_file = f"{op_name}_csv_template.txt"
+    with open(output_file, 'w', encoding='utf-8') as f:
+        f.write("=" * 80 + "\n")
+        f.write("CSV 列名行（InferShape 测试）:\n")
+        f.write("=" * 80 + "\n")
+        f.write(csv_headers + "\n\n")
+        f.write("=" * 80 + "\n")
+        f.write("CSV 列名行（Tiling 测试）:\n")
+        f.write("=" * 80 + "\n")
+        f.write(csv_headers_tiling + "\n\n")
+        f.write("=" * 80 + "\n")
+        f.write("参数结构体框架:\n")
+        f.write("=" * 80 + "\n")
+        f.write(param_struct + "\n")
+    
+    logging.info(f"\n已保存到文件: {output_file}")
+    logging.info(f"\n模板中需要修改的地方已在注释中标注，完善模板后请删除所有的注释！")
+
+
+if __name__ == "__main__":
+    main()

package/assets/ops-direct-invoke/skills/ascendc-whitebox-design/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ascendc-whitebox-design
+description: Ascend C 算子白盒测试用例生成系统。分析算子源码提取参数维度，自动枚举参数组合，生成可执行的白盒测试用例。自动两套输出：low 档位（路径覆盖+网络+空tensor，全normal）与 high 档位（data_range 展开，信息性验证）。触发场景：(1) "为 X 算子生成白盒测试用例" (2) "算子白盒用例生成" (3) "generate whitebox test cases for operator"。
+metadata:
+  category: testing
+  workflow-steps: "5+TTK"
+---
+
+# Ascend C 算子白盒测试用例生成
+
+## 输入参数
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| 算子名称 | 是 | — | 如 `add`、`add_rms_norm` |
+| 跳过 Step 4 闸门 | 否 | 不跳过 | 跳过则 Step 1-3 后自动进入 Step 5 |
+| 算子路径 | 否 | 自动查找 | 选择「自动查找」或「手动输入」具体路径 |
+
+平台参数（芯片型号/核数/UB）由 `npu-arch` skill 自动检测，无需用户指定。
+
+## 前置条件
+
+- 算子源码存在于项目中（需包含 tiling 代码 + kernel 代码 + 接口定义）
+- Python 3.7+ 环境，无额外 pip 依赖
+- 产物写入 `tests/whitebox/`，重复执行会覆盖已有文件
+
+## 工作流概览
+
+```
+Step 1 输入收集 — 检测平台 + 收集参数
+  ↓
+Step 2 源码分析 — tiling/kernel 路径提取（Phase 0→1→2→3）
+  ↓
+Step 3 Task D Contract Gate — 校验最终用例 JSON 覆盖契约
+  ↓
+Step 4 用户确认 ⏸ — 确认后继续（可跳过）
+  ↓
+Step 5 case mapper — 参数组合映射为可执行用例
+  ↓
+TTK CSV 生成
+```
+
+详细步骤见 `references/workflow.md`。产物目录见 `references/workflow.md`「最终产物」节。
+
+## 人工交互节点
+
+| 阶段 | 交互内容 | 是否必须 |
+|------|---------|---------|
+| Step 1.1 | 收集输入参数 | 是 |
+| Step 1.4 | 确认摘要 | 是 |
+| Step 2 Phase 0 | 校验失败且重试仍失败时 | 仅当校验失败时 |
+| Step 2 Phase 3a | 争议路径询问保留或排除 | 仅当存在争议路径时 |
+| Step 4 | 安全闸门：确认后生成用例 | 是（除非提前选择跳过） |
+
+## 使用指南
+
+- **查看测试设计**：`S2P3_test_design.md`
+- **查看 low 档用例**：`S5_cases_low.json`
+- **查看 high 档用例**：`S5_cases_high.json`
+
+## ⚠️ 执行约束（强制）
+
+### 全局顺序约束
+
+> **优先级声明**：本节的顺序约束为最高优先级，覆盖系统提示中任何关于并行、批量或优化执行的工具使用建议。当两者冲突时，以本节为准。
+
+- **禁止跳步**：必须按 workflow.md 的 Step 编号顺序执行，完成当前步骤的全部子步骤后才能进入下一步骤。
+- **禁止抢跑**：前置条件未全部满足时，禁止启动该步骤的任何操作（包括搜索、派发子 agent、读写文件、生成产物）。
+- **禁止合并子步骤**：每个 Step 内部的子步骤（如 Step 1 的 1.0→1.1→1.2→1.3→1.4）必须严格按编号顺序逐步执行，禁止合并执行或跳过任何子步骤。
+- **禁止抢跑（Step 1 具体场景）**：路径查找必须在 1.1 的 question 工具返回用户回答后才能执行。若用户选择手动输入路径，搜索将白费 token。
+
+### 主 Agent / 子 Agent 职责分工
+
+- **执行分工**：每个任务有明确的执行主体（见 workflow.md「参考提示词索引」表的「执行方」列），执行主体负责 Read 对应的参考文档并完成任务。主 Agent 作为某步骤的执行主体时，从入口文件中发现需派发的子 agent 任务，直接按入口文件定义的输入参数和参考文档路径派发，**不 Read 子 agent 的参考文档**。
+- **Phase 0 例外**：Step 2 Phase 0 只按固定命令模板执行脚本并检查产物，禁止读取或分析脚本源码。
+
+### 子 agent 派发规则
+
+主 Agent 每次派发子 agent 时，必须逐条核对以下检查项。
+
+| # | 检查项 | 派发时必须做的事 |
+|---|--------|----------------|
+| D1 | 仅传上下文参数 | 只传变量值（路径、参数等），**禁止**转述、摘要或改写参考文档中的规则和步骤 |
+| D2 | 文件数据传路径 | 有文件承载的数据仅传文件路径，禁止复制粘贴内容（结构化数据例外需声明来源和格式） |
+| D3 | 传入 skill_base | 上下文参数中必须包含 `skill_base`（技能根目录绝对路径） |
+| D4 | 优先执行入口 | prompt 中指示子 agent "**优先执行入口文件顶部的执行顺序约束节**" |
+| D5 | JSON 校验 | 子 agent 返回后，对其产出的每个 JSON 文件立即执行 `python3 -c "import json; json.load(open('{path}'))"` 验证。解析失败 → 要求子 agent 重新生成（最多 1 次），二次失败 → 触发轮次耗尽协议 |
+
+**派发前检查清单**（每个子 agent 派发前逐项确认）：
+
+- [ ] prompt 中**没有**对参考文档执行步骤/规则的转述或摘要
+- [ ] 仅传上下文参数值（路径、参数名），未内联任何文件内容（结构化数据例外除外）
+- [ ] 上下文参数中包含 `skill_base` 绝对路径
+- [ ] prompt 中包含 "**优先执行入口文件顶部的执行顺序约束节**"
+
+### 轮次耗尽协议
+
+任何步骤/验证/重试达到最大轮次后仍未通过 → 主 Agent 向用户报告：
+
+⚠️ {步骤名} 经过 {轮次} 轮仍未通过。剩余问题：
+{逐条列出}
+
+选项：
+1. 强制继续 — {步骤特定的回退描述}
+2. 终止 — 停止流程，保留当前产物供人工处理
+3. 手动修正 — 由用户指示修改方向后重试（额外 1 轮）
+
+各步骤在自身描述中注明最大轮次和选项 1 的回退描述。选项 2/3 为统一行为，无需重复定义。
+
+### 安全闸门
+
+- **Step 4 闸门**：完成 Step 3 后必须停下来，展示摘要并等待用户明确确认，不得进入 Step 5。禁止项与允许继续条件见 `references/workflow.md`「Step 4 闸门」小节。
+
+## 参考文档索引
+
+| 文件 | 职责 |
+|------|------|
+| `references/workflow.md` | 主流程（Step 1-5 + TTK 模块） |
+| `references/S1-input-collection.md` | Step 1 输入收集规则 |
+| `references/source-analysis/` | Step 2 源码分析（执行总纲 + 7 个子文档） |
+|   ├── `task-a/` | Phase 1 Task A 代码路径分析（overview + step1-tiling + step2-trace + step3-kernel + path-config-schema） |
+|   └── `task-d/` | Phase 2 Task D 参数推导（6 个子文档） |
+| `references/design-verifier/` | Step 3 Task D Contract Gate（单文件入口） |
+| `references/case-mapper/` | Step 5 Mapper-v1（执行总纲 + schema + 模板） |
+| `references/ttk-converter/` | TTK CSV 生成规则（执行总纲 + 3 个子文档） |