starred/AIClient-2-API-justlovemaki

Fork 0

mirror of https://github.com/justlovemaki/AIClient-2-API.git synced 2026-04-25 01:16:01 +03:00

[GH-ISSUE #128] GitHub 提问 (Issue) 高质量操作指南 #101

New issue

Open

opened 2026-02-27 07:17:59 +03:00 by kerem · 0 comments

kerem commented

2026-02-27 07:17:59 +03:00

Owner

Originally created by @justlovemaki on GitHub (Dec 23, 2025).
Original GitHub issue: https://github.com/justlovemaki/AIClient-2-API/issues/128

GitHub 提问 (Issue) 高质量操作指南

一、提问前的准备：不要做“伸手党”

在点击 New Issue 按钮之前，请务必完成以下步骤。这不仅是对维护者的尊重，也是向黑客文化致敬。

自我排查 (RTFM & STFW)
- 查阅文档 (Read The Fucking Manual): 确保你的问题不是文档中已经写明的操作步骤。
- 搜索网络 (Search The Fucking Web): 使用 Google 搜索错误代码或现象。
- 搜索旧 Issues: 在该仓库的 Issues 栏（包括 Closed 的）搜索关键词，很大概率有人遇到过相同问题。
- 自我尝试: 尝试阅读源码，或自己通过简单的调试（Debug）来定位问题。
明确这是 Bug 还是咨询
- 如果你不确定这是软件的缺陷，请不要在标题中轻易使用“Bug”这个词。
- 如果是询问用法（如“Java怎么学”），请确保你提供了足够的背景信息（参考下文）。

二、撰写 Issue：从模糊走向精确

1. 标题 (Title)

标题是决定开发者是否点击进来看的第一要素。

❌ 糟糕的标题：
- “救命啊！程序崩了！”
- “有个 Bug，急急急！”
- “为什么用不了？”
✅ 优秀的标题（对象 + 偏差）：
- 格式： [模块/版本] 在特定环境下出现预期外的行为
- 示例： “X.org 6.8.1 鼠标指针在 MV1005 芯片组下显示变形”
- 示例： “Spring Boot 2.5: 无法在 Docker 容器中正确加载配置文件”

2. 内容主体 (Description)

一个高质量的 Issue 应该包含以下三个核心维度：背景、目标、限制条件/复现步骤。

A. 如果是咨询类问题（How-to）

不要问“某某好用吗？”或“怎么做？”，需提供：

背景 (Identity/Context): 你的身份、当前技术水平、已掌握的知识。
目标 (Goal): 你最终想实现什么效果（而不是你现在卡在哪个中间步骤）。
限制 (Constraints): 预算、时间、硬件环境、网络环境。

示例：
“本人是大三学生（背景），需要完成期末项目，要在 500元/月预算内选择一个适合国内访问的云服务器（限制），用于部署一个轻量级 Java Web 应用（目标），请问有推荐的方案吗？”

B. 如果是技术故障类问题（Bug Report）

请务必包含以下结构化信息：

环境信息 (Environment):
- 操作系统及版本（如 Windows 10 21H2, Ubuntu 20.04）
- 软件/库的版本（如 Python 3.9, React 17.0.2）
- 硬件配置（如果相关，如显卡型号、内存大小）
复现步骤 (Steps to Reproduce):
- 按时间顺序列出导致问题的操作步骤。
- 如果是代码问题，必须提供“最小可复现代码” (Minimal Reproducible Example)。不要贴几百行无关代码，只贴能复现问题的最简片段。
现象描述 (Symptoms, not Guesses):
- 描述你看到了什么（错误日志、界面表现），而不是你猜哪里坏了。
- 引用日志： 使用 Markdown 的代码块（```）包裹错误日志，不要截图（截图无法被搜索）。
你做过的尝试:
- “我尝试了搜索 Google，找到了方案 A，但在我的环境下无效，报错如下...”

三、沟通礼仪与心态

话不在多而在精
- 使用清晰、合乎逻辑的语言。
- 排版整洁，善用 Markdown 格式（代码块、粗体、列表）。
- 不要使用大量感叹号、表情符号或“火星文”。
避免无意义的废话
- 不要问“有人能帮我吗？”（直接说事）。
- 不要标题党写“紧急”（你的问题对开发者来说通常并不紧急）。
- 不要低声下气（“我是小白，求大神”），也不要傲慢自大（“这也太烂了”）。保持专业、平等的交流态度。
后续跟进
- 如果解决了： 务必回到 Issue 下方回复解决方案，并关闭 Issue（Close Issue）。这对后来者是巨大的帮助。
- 如果被要求补充信息： 尽快补充。如果你看不懂开发者的回复，请诚实地说：“我看过文档了，但我不理解 -z 参数的含义，您是指...”

四、通用 Issue 模板

在 GitHub 提 Issue 时，如果仓库没有提供模板，建议使用以下格式：

问题描述 (Problem Description)

我在使用 [版本号] 进行 [操作] 时，发现了预期之外的行为。

环境信息 (Environment)

OS: [例如：macOS Monterey 12.3]
Software Version: [例如：v1.2.3]
Dependencies: [例如：Node.js v16.14.0]

复现步骤 (Steps to Reproduce)

运行命令 ...
点击按钮 ...
观察到错误 ...

预期行为 vs 实际行为 (Expected vs Actual)

预期： 应该输出 "Success"
实际： 输出了错误代码 500

错误日志/代码片段 (Logs/Code)

Error: Unable to connect to database...

尝试过的解决方案 (Attempts)

我查阅了官方文档第3章，但按照步骤操作无效。
我尝试搜索了 Issue #102，但那个解决方案不适用于我的版本。

记住：提问的质量，决定了解决问题的效率。做一个聪明的提问者，社区才会更愿意帮助你。

Originally created by @justlovemaki on GitHub (Dec 23, 2025). Original GitHub issue: https://github.com/justlovemaki/AIClient-2-API/issues/128 # GitHub 提问 (Issue) 高质量操作指南 ## 一、提问前的准备：不要做“伸手党” 在点击 `New Issue` 按钮之前，请务必完成以下步骤。这不仅是对维护者的尊重，也是向黑客文化致敬。 1. **自我排查 (RTFM & STFW)** * **查阅文档 (Read The Fucking Manual):** 确保你的问题不是文档中已经写明的操作步骤。 * **搜索网络 (Search The Fucking Web):** 使用 Google 搜索错误代码或现象。 * **搜索旧 Issues:** 在该仓库的 Issues 栏（包括 Closed 的）搜索关键词，很大概率有人遇到过相同问题。 * **自我尝试:** 尝试阅读源码，或自己通过简单的调试（Debug）来定位问题。 2. **明确这是 Bug 还是咨询** * 如果你不确定这是软件的缺陷，请不要在标题中轻易使用“Bug”这个词。 * 如果是询问用法（如“Java怎么学”），请确保你提供了足够的背景信息（参考下文）。 --- ## 二、撰写 Issue：从模糊走向精确 ### 1. 标题 (Title) 标题是决定开发者是否点击进来看的第一要素。 * **❌ 糟糕的标题：** * “救命啊！程序崩了！” * “有个 Bug，急急急！” * “为什么用不了？” * **✅ 优秀的标题（对象 + 偏差）：** * *格式：* `[模块/版本] 在特定环境下出现预期外的行为` * *示例：* “X.org 6.8.1 鼠标指针在 MV1005 芯片组下显示变形” * *示例：* “Spring Boot 2.5: 无法在 Docker 容器中正确加载配置文件” ### 2. 内容主体 (Description) 一个高质量的 Issue 应该包含以下三个核心维度：**背景、目标、限制条件/复现步骤**。 #### A. 如果是咨询类问题（How-to）不要问“某某好用吗？”或“怎么做？”，需提供： * **背景 (Identity/Context):** 你的身份、当前技术水平、已掌握的知识。 * **目标 (Goal):** 你最终想实现什么效果（而不是你现在卡在哪个中间步骤）。 * **限制 (Constraints):** 预算、时间、硬件环境、网络环境。 > **示例：** > “本人是大三学生（背景），需要完成期末项目，要在 500元/月预算内选择一个适合国内访问的云服务器（限制），用于部署一个轻量级 Java Web 应用（目标），请问有推荐的方案吗？” #### B. 如果是技术故障类问题（Bug Report）请务必包含以下结构化信息： * **环境信息 (Environment):** * 操作系统及版本（如 Windows 10 21H2, Ubuntu 20.04） * 软件/库的版本（如 Python 3.9, React 17.0.2） * 硬件配置（如果相关，如显卡型号、内存大小） * **复现步骤 (Steps to Reproduce):** * 按时间顺序列出导致问题的操作步骤。 * *如果是代码问题，必须提供“最小可复现代码” (Minimal Reproducible Example)*。不要贴几百行无关代码，只贴能复现问题的最简片段。 * **现象描述 (Symptoms, not Guesses):** * 描述你**看到了什么**（错误日志、界面表现），而不是你**猜**哪里坏了。 * *引用日志：* 使用 Markdown 的代码块（\`\`\`）包裹错误日志，不要截图（截图无法被搜索）。 * **你做过的尝试:** * “我尝试了搜索 Google，找到了方案 A，但在我的环境下无效，报错如下...” --- ## 三、沟通礼仪与心态 1. **话不在多而在精** * 使用清晰、合乎逻辑的语言。 * 排版整洁，善用 Markdown 格式（代码块、粗体、列表）。 * 不要使用大量感叹号、表情符号或“火星文”。 2. **避免无意义的废话** * 不要问“有人能帮我吗？”（直接说事）。 * 不要标题党写“紧急”（你的问题对开发者来说通常并不紧急）。 * 不要低声下气（“我是小白，求大神”），也不要傲慢自大（“这也太烂了”）。保持专业、平等的交流态度。 3. **后续跟进** * **如果解决了：** 务必回到 Issue 下方回复解决方案，并关闭 Issue（Close Issue）。这对后来者是巨大的帮助。 * **如果被要求补充信息：** 尽快补充。如果你看不懂开发者的回复，请诚实地说：“我看过文档了，但我不理解 -z 参数的含义，您是指...” --- ## 四、通用 Issue 模板在 GitHub 提 Issue 时，如果仓库没有提供模板，建议使用以下格式： ## 问题描述 (Problem Description)  我在使用 [版本号] 进行 [操作] 时，发现了预期之外的行为。 ## 环境信息 (Environment) - **OS:** [例如：macOS Monterey 12.3] - **Software Version:** [例如：v1.2.3] - **Dependencies:** [例如：Node.js v16.14.0] ## 复现步骤 (Steps to Reproduce) 1. 运行命令 `...` 2. 点击按钮 `...` 3. 观察到错误 ... ## 预期行为 vs 实际行为 (Expected vs Actual) - **预期：** 应该输出 "Success" - **实际：** 输出了错误代码 500 ## 错误日志/代码片段 (Logs/Code)  ```bash Error: Unable to connect to database... ``` ## 尝试过的解决方案 (Attempts) - 我查阅了官方文档第3章，但按照步骤操作无效。 - 我尝试搜索了 Issue #102，但那个解决方案不适用于我的版本。 --- **记住：提问的质量，决定了解决问题的效率。做一个聪明的提问者，社区才会更愿意帮助你。**

kerem referenced this issue

2026-02-27 07:18:44 +03:00

[PR #101] [MERGED] fix(antigravity): implement automatic Project ID discovery to resolve 403 errors #263

No labels

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/AIClient-2-API-justlovemaki#101

No description provided.

Rows
Columns