github.com/qiniu/go-sdk/v7@v7.27.0/.agents/skills/_shared/common-error-template.md (about)

     1  # 统一错误输出模板
     2  
     3  各 skill 遇到错误时，按以下模板输出，确保用户能快速定位问题并提供所需信息。
     4  
     5  ## 1. 参数校验失败
     6  
     7  当必填参数缺失或格式不合法时使用。
     8  
     9  ```text
    10  参数校验失败
    11  
    12  缺失/无效参数: <参数名>
    13  要求: <参数格式说明>
    14  收到: <实际值 或 "未提供">
    15  
    16  用法: <skill名> <参数提示（来自 frontmatter argument-hint）>
    17  示例: <一个合法的调用示例>
    18  ```
    19  
    20  规则：
    21  - 一次性列出所有校验失败项，不要逐个报告。
    22  - 参数提示直接引用 frontmatter 的 `argument-hint`。
    23  - 包含至少一个合法示例。
    24  
    25  ## 2. 步骤执行阻塞
    26  
    27  当某步骤因权限、凭证、外部依赖等原因无法继续时使用。
    28  
    29  ```text
    30  阻塞: 步骤 <N> - <步骤名称>
    31  
    32  阻塞点: <具体描述>
    33  已执行命令: <实际执行的命令>
    34  报错信息: <关键错误行>
    35  已尝试: <已做的排查/修复动作>
    36  
    37  需要用户提供:
    38  - <具体所需信息或操作 1>
    39  - <具体所需信息或操作 2>
    40  ```
    41  
    42  规则：
    43  - 立即停止当前步骤，不进入下一步。
    44  - 保留前序步骤的成功结果。
    45  - "已执行命令"必须是实际执行的命令，不是模板。
    46  - "报错信息"取关键行，不要完整日志。
    47  
    48  ## 3. 外部依赖缺失
    49  
    50  当缺少环境变量、工具、网络连接等外部依赖时使用。
    51  
    52  ```text
    53  外部依赖缺失: <依赖名称>
    54  
    55  说明: <依赖的用途>
    56  检查命令: <用于确认依赖的命令>
    57  配置参考: <文档路径或设置说明>
    58  
    59  当前影响: <跳过哪些步骤/使用什么降级方案>
    60  ```
    61  
    62  规则：
    63  - 明确说明跳过步骤的影响范围。
    64  - 对于可降级的依赖，说明降级方案。
    65  
    66  ## 适用场景映射
    67  
    68  | 错误类型 | 模板 | 典型场景 |
    69  |----------|------|----------|
    70  | 必填参数缺失 | 参数校验失败 | PR 编号未指定、URL 格式错误 |
    71  | 参数值非法 | 参数校验失败 | issue 编号非正整数 |
    72  | 权限不足 | 步骤执行阻塞 | gh 命令 403、API 无权限 |
    73  | 命令执行失败 | 步骤执行阻塞 | make unittest 失败、git merge 冲突 |
    74  | 环境变量缺失 | 外部依赖缺失 | GITHUB_TOKEN 未配置 |
    75  | 工具未安装 | 外部依赖缺失 | staticcheck、gofumpt 不可用 |