From 48ae305cbd4d680ea14226e6df39fe0d93fbdf29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=A8=8B=E5=BA=8F=E5=91=98=E9=98=BF=E6=B1=9F=28Relakkes?=
 =?UTF-8?q?=29?= <relakkes@gmail.com>
Date: Wed, 29 Apr 2026 09:23:59 +0800
Subject: [PATCH] docs: make issue reports actionable for desktop triage

Most reports now come from desktop users, so the templates need to collect the operating system, desktop version, reproduction path, configuration screenshots, and logs before maintainers can diagnose failures.

Constraint: Desktop releases are the dominant support surface for external users
Rejected: Keep CLI-first fields at the top | it delays collecting the information needed for Windows and macOS desktop failures
Confidence: high
Scope-risk: narrow
Directive: Keep desktop OS and app version fields near the top of future issue template edits
Tested: git diff --check -- .github/ISSUE_TEMPLATE/bug_report.md .github/ISSUE_TEMPLATE/question.md
Not-tested: GitHub issue form rendering in browser
---
 .github/ISSUE_TEMPLATE/bug_report.md | 87 ++++++++++++++++++----------
 .github/ISSUE_TEMPLATE/question.md   | 81 ++++++++++++++++----------
 2 files changed, 108 insertions(+), 60 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 8e0804ca..382900c0 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,43 +1,68 @@
----  
-name: Bug 反馈  
-about: 创建一个 Bug 报告以帮助 cc-haha 项目改进  
-title: '[BUG] '  
-labels: bug  
-assignees: ''  
----  
+---
+name: Bug 反馈
+about: 提交桌面端或 CLI 的 Bug 报告
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
 
-## 🔍 问题检查清单  
-<!-- 请在提交 issue 前确认以下事项 -->  
+## 提交前确认
+<!-- 请在提交 issue 前确认以下事项 -->
 
-- [ ] 我已经仔细阅读了 [README 常见问题](https://github.com/NanmiCoder/cc-haha#常见问题) 部分
-- [ ] 我已经搜索并查看了[已关闭的 issues](https://github.com/NanmiCoder/cc-haha/issues?q=is%3Aissue+is%3Aclosed)  
-- [ ] 我确认这不是由于 API Key 配置错误、API 端点不兼容、Bun 版本过低等常见原因导致的问题  
+- [ ] 我已经阅读了 [README 常见问题](https://github.com/NanmiCoder/cc-haha#常见问题)
+- [ ] 我已经升级到最新版本后复现过这个问题
+- [ ] 我已经搜索过[现有 issues](https://github.com/NanmiCoder/cc-haha/issues)，确认没有重复问题
+- [ ] 我已经隐藏截图和日志中的 API Key、Token、Cookie 等敏感信息
 
-## 🐛 问题描述  
-<!-- 请详细描述你遇到的问题 -->  
+## 问题描述
+<!-- 请用 1-3 句话说明实际发生了什么、你原本期望发生什么 -->
 
 
-## 📝 复现步骤  
-1.   
-2.   
-3.   
+## 运行环境
+<!-- 桌面端问题请优先填写前 4 项；CLI 问题再补充 Bun / Node 信息 -->
 
-## 💻 运行环境  
-- 操作系统:   
-- Bun 版本 (`bun --version`):  
-- Node 版本 (`node --version`):  
-- API 提供商 (如 MiniMax / OpenRouter / Anthropic 官方等):  
-- 使用的模型:  
-- 启动方式 (TUI / --print / Recovery CLI):  
+- 使用方式: 桌面端 / CLI / 其他:
+- 操作系统: Windows / macOS / Linux:
+- 系统版本: 例如 Windows 11 23H2 / macOS 15.4:
+- 桌面端版本: 例如 v0.1.8（设置页 -> 关于 中可查看）:
+- 安装来源: GitHub Release / 源码本地构建 / 其他:
+- Bun 版本（CLI 问题填写，`bun --version`）:
+- Node 版本（CLI 问题填写，`node --version`）:
 
-## 📋 错误日志  
-<!-- 请提供完整的错误日志信息 -->  
-```shell  
-在此粘贴错误日志
+## Provider / 模型配置
+<!-- 请尽量提供配置截图；务必隐藏 API Key、Token 等敏感信息 -->
+
+- API 提供商: 例如 Anthropic 官方 / OpenRouter / MiniMax / Kimi / Ollama:
+- Base URL:
+- 使用的模型:
+- 相关配置截图:
+
+## 复现步骤
+<!-- 请写到别人可以照着操作复现；如果偶发，请说明大约出现频率 -->
+
+1.
+2.
+3.
+
+是否稳定复现: 是 / 否 / 不确定
+
+## 错误信息与日志
+<!--
+请粘贴完整错误信息。桌面端启动失败时，请复制错误弹窗中的 Recent server logs；
+如果是对话、配置或模型调用失败，请粘贴页面上的错误、终端输出或相关日志。
+-->
+
+```shell
+在此粘贴错误信息和日志
 ```
 
-## 📷 错误截图
-<!-- 如有，请提供错误截图 -->
+## 截图或录屏
+<!-- 请提供错误截图、配置截图或复现录屏；截图前请隐藏敏感信息 -->
+
+
+## 补充信息
+<!-- 最近是否升级过版本、换过 provider、改过配置，或是否有旧版本可以正常使用 -->
+
 
 ---
 <!-- 🤖 Dosu 机器人将自动响应此 issue -->
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
index 543b1f54..377a2f4e 100644
--- a/.github/ISSUE_TEMPLATE/question.md
+++ b/.github/ISSUE_TEMPLATE/question.md
@@ -1,39 +1,62 @@
----  
-name: 使用问题咨询  
-about: 提交使用过程中遇到的问题  
-title: '[问题] '  
-labels: question  
-assignees: ''  
----  
+---
+name: 使用问题咨询
+about: 咨询桌面端或 CLI 使用过程中遇到的问题
+title: '[问题] '
+labels: question
+assignees: ''
+---
 
-## ⚠️ 提交前确认  
-<!-- 请确认以下事项 -->  
-- [ ] 我已经仔细阅读了 [README 常见问题](https://github.com/NanmiCoder/cc-haha#常见问题) 部分
-- [ ] 我已经阅读了[第三方模型使用指南](https://github.com/NanmiCoder/cc-haha/blob/main/docs/guide/third-party-models.md)
-- [ ] 我已经搜索并查看了[已关闭的 issues](https://github.com/NanmiCoder/cc-haha/issues?q=is%3Aissue+is%3Aclosed)  
+## 提交前确认
+<!-- 请确认以下事项 -->
 
-## ❓ 问题描述  
-<!-- 清晰简洁地描述你遇到的问题 -->  
+- [ ] 我已经阅读了 [README 常见问题](https://github.com/NanmiCoder/cc-haha#常见问题)
+- [ ] 我已经阅读了[第三方模型使用指南](https://github.com/NanmiCoder/cc-haha/blob/main/docs/guide/third-party-models.md)（如使用第三方 provider）
+- [ ] 我已经搜索过[现有 issues](https://github.com/NanmiCoder/cc-haha/issues)，确认没有重复问题
+- [ ] 我已经隐藏截图和日志中的 API Key、Token、Cookie 等敏感信息
 
-## 🔍 使用场景  
-<!-- 描述你在使用哪个功能时遇到的问题 -->  
-- 使用功能: (如：TUI 交互 / --print 无头模式 / MCP 服务器 / Skills 等)  
-- API 提供商: (如：MiniMax / OpenRouter / Anthropic 官方 / LiteLLM 代理等)  
+## 问题描述
+<!-- 清晰简洁地描述你想做什么、现在卡在哪里 -->
 
-## 💻 环境信息  
-- 操作系统:   
-- Bun 版本 (`bun --version`):  
-- Node 版本 (`node --version`):  
-- API 提供商:  
-- 使用的模型:  
 
-## 📋 错误日志  
-```shell  
-在此粘贴完整的错误日志
+## 使用环境
+<!-- 桌面端问题请优先填写前 4 项；CLI 问题再补充 Bun / Node 信息 -->
+
+- 使用方式: 桌面端 / CLI / 其他:
+- 操作系统: Windows / macOS / Linux:
+- 系统版本: 例如 Windows 11 23H2 / macOS 15.4:
+- 桌面端版本: 例如 v0.1.8（设置页 -> 关于 中可查看）:
+- 安装来源: GitHub Release / 源码本地构建 / 其他:
+- Bun 版本（CLI 问题填写，`bun --version`）:
+- Node 版本（CLI 问题填写，`node --version`）:
+
+## 使用场景
+<!-- 描述你在使用哪个功能时遇到的问题 -->
+
+- 使用功能: 例如会话对话 / Provider 配置 / 模型调用 / MCP / Skills / 远程控制:
+- API 提供商: 例如 Anthropic 官方 / OpenRouter / MiniMax / Kimi / Ollama:
+- 使用的模型:
+
+## 配置截图
+<!-- 请尽量提供 Provider / 模型 / Base URL 等相关配置截图；务必隐藏 API Key、Token 等敏感信息 -->
+
+
+## 操作步骤
+<!-- 请说明你是怎么操作到这个问题的 -->
+
+1.
+2.
+3.
+
+## 错误信息与日志
+<!-- 如果页面、弹窗或终端里有错误，请粘贴完整内容 -->
+
+```shell
+在此粘贴错误信息和日志
 ```
 
-## 📷 错误截图
-<!-- 如有，请提供错误截图 -->
+## 截图或录屏
+<!-- 如有，请提供截图或录屏；截图前请隐藏敏感信息 -->
+
 
 ---
 <!-- 🤖 Dosu 机器人将自动响应此 issue -->