注释

注释是可以添加到LLM输出中的错误、警告或提示信息。它们会被提取并集成到VSCode或您的CI环境中。

$`Report issues with this code using annotations.`

配置

如果在脚本文本中使用annotation但没有指定system字段，默认会添加system.annotations。

利用system.annotations系统提示功能，可以让LLM生成错误、警告和注释信息。

script({
    ...
    system: [..., "system.annotations"]
})

要在Markdown预览中获得漂亮的渲染效果，可以尝试使用Markdown Preview for GitHub Alerts扩展。

行号

system.annotations提示功能会自动为所有def部分启用行号注入。这一增强功能提高了LLM响应的准确性，并减少了幻觉发生的可能性。

GitHub Action 命令

默认情况下，注释使用GitHub Action Commands语法。这意味着如果您在GitHub Action中运行脚本，GitHub将自动提取这些注释。

GitHub拉取请求审查评论

在cli run中使用--pull-request-reviews (-prr)标志，将注释作为review comments添加到拉取请求中。

npx --yes genaiscript run ... --pull-request-reviews

Visual Studio Code 程序

注释会被转换为Visual Studio的诊断信息，这些信息通过问题面板呈现给用户。这些诊断信息还会在编辑器中以波浪线的形式显示。

静态分析结果交换格式 (SARIF)

GenAIScript将这些注解转换为SARIF文件，可以上传为安全报告，类似于CodeQL报告。

SARIF Viewer扩展功能有助于可视化这些报告。

name: "Upload SARIF"

# Run workflow each time code is pushed to your repository and on a schedule.
# The scheduled workflow runs every Thursday at 15:45 UTC.
on:
    push:
    schedule:
        - cron: "45 15 * * 4"
jobs:
    build:
        runs-on: ubuntu-latest
        permissions:
            # required for all workflows
            security-events: write
            # only required for workflows in private repositories
            actions: read
            contents: read
        steps:
            # This step checks out a copy of your repository.
            - name: Checkout repository
              uses: actions/checkout@v4
            # Run GenAIScript tools
            - name: Run GenAIScript
              run: npx --yes genaiscript ... -oa result.sarif
            # Upload the generated SARIF file to GitHub
            - name: Upload SARIF file
              if: success() || failure()
              uses: github/codeql-action/upload-sarif@v3
              with:
                  sarif_file: result.sarif

限制条件

访问安全报告的权限可能因您的仓库可见性和组织规则而异。如需进一步帮助，请参阅GitHub文档。
您的组织可能会对拉取请求的GitHub Actions执行施加限制。请参阅GitHub文档获取更多指导。

筛选

你可以使用defOutputProcessor函数来过滤注释。

defOutputProcessor((annotations) => {
    // only allow errors
    const errors = annotations.filter(({ level }) => level === "error")
    return { annotations: errors }
})