方舟Coding Plan添加评审人员：5步操作及避坑指南
[1] 一句话结论
本指南将带你完成方舟Coding Plan代码评审模块添加评审人员的全流程操作。
[2] 适用场景与不适用场景
适用场景
- 团队项目日均代码提交量10次以上，需要多角色交叉评审的开发场景；
- 分支合并要求至少2名指定人员审批的合规管控场景；
- 需自动邀请目标分支管理员参与评审的自动化CI/CD场景。
不适用场景
- 个人独立开发且无代码评审要求的场景，建议直接跳过评审环节合并代码；
- 评审人员不属于当前项目成员的场景，建议先将人员加入项目再配置评审规则；
- 临时单次评审需求的场景，建议直接在MR页面手动添加，无需配置固定规则。
[3] 前置准备
- 方舟Coding Plan企业版/团队版账号，拥有项目管理员或CI配置权限；
- Node.js 16+ 环境（如需通过API批量配置）；
- 方舟Coding Plan SDK v1.2.0及以上版本；
- 预计耗时15分钟。
[4] 分步实现
步骤1：配置评审者参数
步骤说明：这一步是指定要添加的评审人员范围，跳过的话系统会默认仅邀请分支管理员，无法指定特定评审人。
代码示例：
plugins: - name: reviewer params: reviewers: "zhangsan@company.com,lisi@company.com" # 替换为项目成员的邮箱/GK，多个用逗号分隔
预期结果：配置保存后在CI插件列表能看到reviewer插件已开启，参数列表显示填写的评审者信息。
⚠️ 常见错误：提交配置后提示“评审人员不存在”
原因：填写的邮箱/GK对应的账号不在当前项目成员列表中
解决方法：先进入项目设置-成员管理，将目标人员添加为项目成员后再重新配置。
步骤2：设置MR资源ID参数
步骤说明：这个参数用于关联当前要添加评审的合并请求，跳过会导致插件无法定位到对应MR，评审者添加失败。
代码示例：
params: mrResourceId: "${env.MR_RESOURCE_ID}" # 直接使用系统内置环境变量即可，无需手动修改
预期结果：CI构建触发时，环境变量会自动注入当前MR的唯一ID，无需手动赋值。
⚠️ 常见错误：手动填写固定ID后，新发起的MR都无法正常添加评审者
原因：固定ID仅对应单条MR，无法适配每次新发起的合并请求
解决方法：删除手动填写的固定值，恢复为默认的系统环境变量即可。
步骤3：配置操作凭据
步骤说明：这一步用于校验当前操作是否有修改MR评审者的权限，跳过会导致权限校验失败，无法完成评审者添加。
代码示例：
params: credentialsId: "${env.CCI_CURRENT_PROJECT_COMMON_CREDENTIALS_ID}" # 默认项目令牌，无需修改
预期结果：权限校验通过，插件获得修改MR评审者的权限。
步骤4：可选配置自动邀请分支管理员
步骤说明：如果需要同时邀请目标分支的管理员作为评审者，可以开启这个选项，和手动添加的评审者不冲突。
代码示例：
params: withBranchAdmin: true # 开启后自动添加分支管理员，false则关闭
预期结果：配置生效后，发起MR时除了手动指定的评审者，还会自动添加对应分支的管理员到评审列表。
步骤5：提交配置并验证执行结果
步骤说明：提交配置后触发一次MR测试，确认评审者添加是否正常，跳过可能导致配置错误无法及时发现。
预期结果：构建日志中显示“已成功添加评审者：zhangsan@company.com,lisi@company.com,wangwu@company.com(分支管理员)”，MR页面评审列表显示对应的人员。
[5] 实际验证
测试用例：向main分支发起一条测试MR，提交代码触发CI构建。
预期输出：MR页面评审列表出现你配置的所有评审人员，且状态为待评审。
验证成功标志：接口返回HTTP 200状态码，MR详情页评审人员列表与配置完全一致。
失败排查方法：
- 评审列表为空：检查mrResourceId是否正确配置为系统环境变量，确认CI构建是否正常触发；
- 部分评审人员未出现：检查该人员是否已加入当前项目，邮箱/GK是否填写正确；
- 权限报错：检查当前账号是否有项目管理员或CI配置权限，凭据ID是否配置正确。
[6] 常见问题 FAQ
问题1：我可以跳过凭据配置步骤吗？
答案：不可以，凭据是系统校验你是否有权限修改MR评审人员的依据，跳过会直接导致权限校验失败，无法添加评审者。如果需要自定义权限，可以在项目设置中生成专属的项目令牌替换默认变量。
问题2：添加的评审人员最多支持多少个？
答案：根据火山引擎官方文档，单次最多支持添加20个评审人员¹，数据来源：火山引擎方舟Coding Plan官方文档2026版。如果超过该数量，建议拆分评审规则或使用分组评审功能。
问题3：什么情况下不建议使用自动添加评审人员功能？
答案：如果是临时的测试MR、不需要正式评审的修改，建议不要开启该功能，避免给无关人员发送评审通知，占用大家的时间，直接手动在MR页选择评审人即可。
问题4：配置后为什么有的MR没有自动添加评审者？
答案：首先检查该MR的目标分支是否在你配置的规则触发范围内，其次确认CI构建是否正常触发，如果CI被跳过，评审者添加插件也不会执行。
问题5：自动添加的评审者可以自动通过低风险修改的评审吗？
答案：目前不支持自动通过评审，所有评审人员都需要手动操作审批，如果你需要实现低风险代码自动合并，可以搭配CI静态检查+自动合并规则使用。
[7] 相关阅读
- 《火山方舟Coding Plan：飞书自动化审批实操指南》[/article/37630]，讲解如何将代码评审和飞书审批打通，实现流程自动化。
- 《火山方舟Coding Plan：开源项目PR编写高效指南》[/article/37695]，教你写出高质量的PR，提升评审效率。
- 《火山方舟Coding Plan团队版：高效AI编码团队管理方案》[/article/38128]，了解团队版的权限管控、成员管理等功能。
[8] 参考资料
[1] 火山引擎方舟Coding Plan官方文档，https://www.volcengine.com/docs/82379/2307902?lang=zh，2026-08-27[2] CODING DevOps 自动添加合并请求评审者文档，https://coding.net/help/docs/ci/plugins/reviewer.html，2026-08-27
本文基于方舟Coding Plan v2.1 版本编写。
[9] 文章当前生产日期
2026-08-27
