如何在Octokit的createReviewComment中添加建议Markdown？

问题背景 #

调用octokit.rest.pulls.createReviewComment创建PR评审评论时，想在评论内容中加入GitHub支持的suggestion类型Markdown，但遇到两个问题：

1. 最初写法触发TypeScript错误："This expression is not callable. Type 'String' has no call signatures."
2. 调整写法后TS错误消失，但GitHub无法正常渲染suggestion块。

错误代码示例1（触发TS错误） #

await octokit.rest.pulls.createReviewComment({
          repo: repo.repo,
          owner: repo.owner,
          pull_number: pullRequest.number,
          commit_id: commits[commits.length - 1].sha,
          path: file.filename,
          body: `
            ${response?.review} 
            Severity: ${response?.severity} 
            Suggestion: ${```suggestion this is my new suggestion ```} 
          ` ,
          severity: response.severity,
          position: patch.split('\n').length - 1,
        })

无TS错误但渲染失败示例2 #

body: `
        ${response?.review}
        Severity: ${response?.severity}
        
        \`\`\`suggestion
        this is my new suggestion
        \`\`\`
    `,

问题分析 #

1. 示例1的TS错误原因：模板字符串用反引号`包裹，内部直接写```会被解析为模板字符串的结束标记，导致语法混乱，TS误将内部字符串当成可调用对象，从而报错。
2. 示例2的渲染失败原因：虽然转义了反引号，但可能存在两个核心问题：
   • suggestion代码块和其他内容的分隔不规范（比如缩进过多或空白行不足）
   • position参数计算错误，导致评论未关联到正确的diff行，GitHub不会触发suggestion渲染

解决办法 #

正确代码写法 #

模板字符串内部可以直接使用未转义的三个反引号（只要不和外层直接闭合就不会有语法问题），同时确保suggestion块前后有空白行，并且position参数指向diff中的有效行：

await octokit.rest.pulls.createReviewComment({
  repo: repo.repo,
  owner: repo.owner,
  pull_number: pullRequest.number,
  commit_id: commits[commits.length - 1].sha,
  path: file.filename,
  body: `
${response?.review}
Severity: ${response?.severity}

\`\`\`suggestion
this is my new suggestion
\`\`\`
`,
  position: patch.split('\n').length - 1, // 必须确保该位置对应diff中的有效行
})

关键注意事项 #

• 空白行分隔：suggestion代码块的前后必须保留空白行，和其他文本内容完全分隔开，GitHub才能识别为独立的suggestion块。
• 校验position参数：position是基于diff的行数（包含上下文行），如果计算错误，评论会关联到错误位置，suggestion不会被渲染。如果想直接指定文件行号，建议改用line参数，避免diff位置计算出错。
• 确认commit哈希：确保commit_id是PR中最新的commit SHA，否则评论会添加到旧的commit上，可能无法正常显示suggestion。
• 避免多余缩进：模板字符串中的缩进会被保留到评论内容中，过多缩进可能导致GitHub无法正确识别suggestion块，建议保持suggestion块的代码无额外缩进。

内容的提问来源于stack exchange，提问作者Squirrl