Star252
59
代码
代码
Issues63
Pull Requests3
Actions
项目讨论
Wiki
分析
Star252
59
已开启
add ai declaration check guide #112
Guangyue-Xu创建于 8月3日
add ai declaration check guide #112
已开启
Guangyue-Xu创建于 8月3日
从Guangyue-Xu/infrastructure_cannxgy_dec合入到cann/infrastructuremaster
共 1 个文件变更+146-0
Adocs/robot/ai_declaration_check_guide.md+146-0
@@ -0,0 +1,146 @@
1+# AI 声明合规检查指南
2+ 
3+## 概述
4+ 
5+### 触发流程
6+ 
7+1. 创建 PR 时，PR 模板中会包含 **"AI 参与"** 勾选项，格式类似：
8+ 
9+ ```
10+ 当前PR是否有AI参与:
11+ [x] 否
12+ 
13+ [ ] 是
14+ __1. AI Agent 平台:
15+ __2. AI 模型:
16+ __3. Prompt上下文 :
17+ ```
18+ 
19+2. 当你勾选 **「是」** 并填写 AI Agent 平台和 AI 模型后提交 PR，机器人会自动为 PR 添加 `ai-co-authored` 标签。
20+3. 当 PR 带有 `ai-co-authored` 标签时，机器人会自动触发 **AI 声明合规性检查**，检查模板中填写的 AI 工具/模型以及所有 commit message 中的 AI 声明是否合规。
21+4. 当你后续将勾选改为 **「否」** 时，机器人会自动移除 `ai-co-authored` 标签，不再进行 AI 声明检查。
22+ 
23+检查通过后，PR 会被打上 `ai-compliance-successful` 标签；检查不通过则打上 `ai-compliance-failed` 标签，同时机器人会评论反馈。
24+ 
25+---
26+ 
27+## 如何正确声明 AI 使用
28+ 
29+### 第一步：在 PR 模板中勾选「是」并填写 AI 信息
30+ 
31+创建 PR 时，PR 模板中的 **"AI 参与"** 选项必须勾选 **「是」**，并且在下方三个字段中填写具体信息：
32+ 
33+```
34+当前PR是否有AI参与:
35+[ ] 否
36+[x] 是
37+__1. AI Agent 平台: Claude Code
38+__2. AI 模型: DeepSeek-V3
39+__3. Prompt上下文: 重构 user 模块，补充单元测试
40+```
41+ 
42+| 字段 | 说明 | 示例 |
43+|------|------|------|
44+| **AI Agent 平台** | 使用的 AI 工具名称 | `Claude Code`、`Copilot`、`Cursor` |
45+| **AI 模型** | 使用的模型名称 | `DeepSeek-V3`、`GPT-4`、`Claude Opus 4` |
46+| **Prompt上下文** | 简要描述 AI 协助完成的任务 | `重构 user 模块，补充单元测试` |
zhunaipan
zhunaipanzhunaipan8月6日

这里的信息是如何校验准确性的，如果是强校验，建议先作为参考信息；

加入我直接用的是网页版的DS去生成一些资料文档，那上面的AI Agent平台应该怎么填？

likedislike
Guangyue-Xu
Guangyue-Xu
8月6日 评论：
47+ 
48+> ℹ️ **非强校验**：此处不校验大小写和书写格式，请尽量保证拼写正确即可。
49+ 
50+> ⚠️ **必须填写。** 如果 AI Agent 平台或 AI 模型为空，检查将不通过。
51+ 
52+### 第二步：在 commit message 中同步声明
53+ 
54+当你在 PR 模板中勾选了「是」，机器人会检查 commit message 中是否包含 AI 声明。**AI 参与的 commit 都需要带上声明**，纯手工的 commit 不需要。
55+ 
56+> 💡 **小技巧**：可在 AI 工具的提示词 / 系统指令中配置，让 AI 提交代码时自动在 commit message 中携带模型信息，避免遗漏。
57+ 
58+核心要求：**commit message 中必须体现使用的 AI 模型信息**，格式不做强制限制，例如：
59+ 
60+ ```
61+ fix: resolve performance issue
62+ Co-authored-by: DeepSeek-V3
63+ ```
64+ 
65+> ℹ️ **格式灵活**：`Co-authored-by`、`Generated-By`、`Assisted-By` 等 trailer 均可，关键是要写明使用的 AI 模型（如 `DeepSeek-V3`、`GPT-4` 等）。
66+ 
67+> **注意**：如果 PR 模板勾选「否」，则不会检查 commit message，不影响合规判定。
68+ 
69+### 完整示例
70+ 
71+**PR 模板填写**：
72+```
73+当前PR是否有AI参与:
74+[ ] 否
75+[x] 是
76+__1. AI Agent 平台: Claude Code
77+__2. AI 模型: DeepSeek-V3
78+__3. Prompt上下文: 重构 user 模块接口，补充单元测试
79+```
80+ 
81+**Commit message**：
82+```
83+refactor: extract user service interface
84+Co-authored-by: DeepSeek-V3
85+```
atomgit-bot
atomgit-botatomgit-bot8月3日

🟠 High Priority

问题链：

  1. 变更行（第 73-74 行 vs 第 82 行）：文档的「完整示例」中，PR 模板声明了 AI 模型为 DeepSeek-V3（第 74 行），但 commit message 中仅出现了 Co-authored-by: Claude <noreply@anthropic.com>（第 82 行），DeepSeek-V3 模型名称完全未出现在 commit message 中。

  2. 受影响的规则/合约：根据关联 Issue #223 中机器人实际的检查提示——"Commit messages must include the AI model, and it must be consistent with the PR description"（commit 中必须包含 AI 模型名且与 PR 描述一致），以及本文档自身第 110-114 行的规则——"模板中填写的工具/模型与 commit message 中声明的不一致"会导致检查不通过。

  3. 失败模式：用户如果严格按照这个「完整示例」来填写（模板写 DeepSeek-V3，commit 只写 Claude），机器人的模型一致性检查将会因为 commit 中找不到 DeepSeek-V3 而判定不通过（打上 ai-compliance-failed 标签）。这份文档的"正确示范"实际上会导致检查失败，严重误导开发者。

建议：在 commit message 示例中补充模型名称，使示例与机器人检查规则一致。可考虑两种方案：(1) 在 commit body 中增加模型说明，如 Used DeepSeek-V3 via Claude Code；(2) 若机器人实际以工具名匹配即可通过，则应在文档中明确说明匹配规则，消除歧义。同时将第 59 行的独立示例一并修正以保持一致。

likedislike
86+ 
87+---
88+ 
89+## 检查不通过的常见原因及修复方法
90+ 
91+检查不通过时，机器人会评论反馈并打上 `ai-compliance-failed` 标签。常见失败原因及修复方法如下：
92+ 
93+### 1. 字段未填写
94+ 
95+「AI Agent 平台」或「AI 模型」字段为空。机器人提示 `no AI tool usage declaration detected`。
96+ 
97+**修复**：填写真实的工具和模型名称。
98+ 
99+### 2. 工具或模型名称不真实
100+ 
101+- 工具名拼写错误、虚构或不明确
102+- 模型名称无法识别（大多数热门平台和模型均已收录）
103+ 
104+**修复**：使用准确的标准名称。若确认工具/模型真实存在但检查仍未通过（如新工具或偏冷门的工具），请联系基础设施负责人添加名单。
105+ 
106+### 3. Commit message 未声明
107+ 
108+模板勾选了「是」，但所有 commit message 中均未出现 AI 声明。
109+ 
110+**修复**：AI 参与的 commit 需要带上 AI 声明。可通过 `git commit --amend` 在对应 commit 中补充 `Co-authored-by`。
111+ 
112+### 4. 模板与 commit 声明不一致
113+ 
114+模板中填写的工具/模型与 commit message 中声明的不一致。
115+ 
116+**修复**：确保模板和 commit message 中的工具/模型名称保持一致。
117+ 
118+### 5. 检查服务异常
119+ 
120+机器人提示 `check failed, please try again later`，非你的声明问题。
121+ 
122+**修复**：等待几分钟后重新 push 触发重检，重试失败请联系管理员修复。
123+ 
124+---
125+ 
126+## 常见问题
127+ 
128+**Q：我的 AI 工具/模型是真实存在的，但检查失败了怎么办？**
129+ 
130+A：大多数热门平台和模型均已收录，若遇到新产物或偏冷门工具未被识别，请联系基础设施负责人添加名单。
131+ 
132+**Q：同一个 PR 中使用了多个 AI 工具，怎么声明？**
133+ 
134+A：在 PR 描述中将所有使用的工具都列出来，commit message 中对应标注每个 commit 使用的工具。
135+ 
136+**Q：commit message 需要每个 commit 都声明吗？**
137+ 
138+A：AI 参与的 commit 需要声明，纯手工的 commit 不需要。
139+ 
140+**Q：声明格式有严格要求吗？**
141+ 
142+A：没有严格要求。同时支持其他常见的声明方式，例如 `Generated-By: xxx`、`Assisted-By: xxx` 等，机器人会智能识别，不做强制格式校验。
143+ 
144+---
145+ 
146+*文档更新日期：2026-08-03*