zenmux-feedback

zenmux-feedback

帮助用户以尽可能简单的方式向 ZenMux GitHub 仓库提交问题和反馈。

ZenMux 以公开方式开发——用户的每一条反馈都会直接影响产品。你的任务是让提交过程毫不费力：通过自然对话收集足够的信息，撰写结构清晰的问题并提交。目标仓库是 ZenMux/zenmux-doc。

步骤 0：同步参考资料并检查前置条件（必须首先运行）

0a. 验证 GitHub CLI

gh --version 2>&1 && gh auth status 2>&1

如果未安装 gh — 停止工作流并告知用户：

1. 此技能需要 GitHub CLI（gh） 才能提交问题
2. 安装方法：
   • macOS：brew install gh
   • Linux：sudo apt install gh 或 sudo dnf install gh
   • Windows：winget install --id GitHub.cli
   • 其他：https://cli.github.com/
3. 然后运行 gh auth login 进行身份验证
4. 说明 ZenMux 使用结构化的问题模板——用户可以在 skills/zenmux-feedback/references/zenmux-doc/.github/ISSUE_TEMPLATE/ 浏览模板，预览每种问题类型所需的字段
5. 不要继续操作——等待用户先完成安装和身份验证

如果已安装 gh 但尚未通过身份验证 — 告知用户运行 gh auth login，然后重新运行此技能。

0b. 从上游更新问题模板

运行更新脚本以克隆或拉取最新的 zenmux-doc 仓库：

bash skills/zenmux-feedback/scripts/update-references.sh

然后读取 skills/zenmux-feedback/references/zenmux-doc/.github/ISSUE_TEMPLATE/ 下的所有 .yml 文件，以获取最新字段、下拉选项和验证规则。这些模板是事实依据——如果模板字段与下文描述的内容不同，请以模板为准。

0c. 获取可用的仓库标签

gh label list --repo ZenMux/zenmux-doc --limit 100

缓存此列表。在步骤 5 中，只应用此列表中存在的标签。如果下方类型映射中的标签在仓库中不存在，请直接忽略——切勿将不存在的标签传递给 gh issue create。

如果所有检查均通过

继续执行步骤 1。

步骤 1：确定提交类型

根据用户的消息，确定适合的类型：

类型	特征	标题前缀	标签（仅应用仓库中存在的标签）
错误报告	功能异常、报错或行为与预期不符	[Bug]:	bug
功能请求	希望新增功能或改进现有功能	[Feature]:	enhancement
提供商/模型请求	希望新增 LLM 提供商或模型	[Provider]:	enhancement
文档反馈	文档错误、内容缺失或链接失效	[Docs]:	documentation
常规反馈	使用感受、体验、建议或比较	[Feedback]:	enhancement

注意： 上游问题模板定义了其他标签（needs-triage、provider-request、feedback、community），但它们可能尚未存在于仓库中。步骤 0c 获取的标签列表是权威依据——只能使用确认存在的标签。

通常可以推断出类型。例如：

• “流式传输时 API 返回 500” → 错误报告
• “希望 ZenMux 能支持 Mistral” → 提供商/模型请求
• “希望控制面板能显示每个模型的费用” → 功能请求
• “快速入门指南的链接失效了” → 文档反馈
• “用了一个月 ZenMux，这是我的看法” → 常规反馈

如果无法确定，请简短询问——但不要过度分类。使用 AskUserQuestion 和上述选项，方便用户快速选择。

步骤 2：通过对话收集信息

从用户已经提供的信息中尽可能提取内容。然后只询问真正缺失的信息——将相关问题合并询问，最多分 1 到 2 轮提问。

各类型需要收集的信息

错误报告（必填 → 选填）：

• 错误描述 ← 用户通常已在消息中说明
• 复现步骤
• 预期行为与实际行为
• 类别（API / 流式传输 / 路由 / 协议 / 多模态 / 工具调用 / 等）
• API 协议（OpenAI / Anthropic / Gemini / Platform / 不适用）
• 严重程度（严重 / 高 / 中 / 低）
• 选填：环境信息、generation_id、集成工具（Claude Code / Cursor / Cline / 等）、截图

功能请求（必填 → 选填）：

• 问题或痛点 ← 通常已在消息中说明
• 建议的解决方案或期望行为
• 类别（API / 路由 / 流式传输 / 可观测性 / 计费 / 等）
• 优先级（严重 / 高 / 中 / 低）
• 选填：用例、考虑过的替代方案、是否愿意协助实现

服务商/模型请求（必填 → 选填）：

• 服务商名称
• 请求的模型
• 请求类型（新增服务商 / 为现有服务商新增模型 / 模型更新）
• 模型类型（文本 / 代码 / 图像 / 视频 / 嵌入 / 多模态 / 推理 / 等）
• 用例
• 优先级
• 选填：API 协议兼容性、API 文档链接

文档反馈（必填 → 选填）：

• 受影响的章节
• 问题类型（信息不正确 / 内容缺失 / 翻译错误 / 链接失效 / 不清晰 / 等）
• 问题描述
• 语言版本（英语 / 中文 / 两者）
• 选填：页面 URL、建议的修复方案、是否愿意提交 PR

一般反馈（必填 → 选填）：

• 反馈类型（产品印象 / 用户体验 / 模型质量 / 定价 / 对比 / 等）
• 反馈内容
• 选填：满意度、主要用例、角色、套餐、希望改变的一件事、如何了解到 ZenMux

对话指南

• 如果用户的初始消息已涵盖大部分必填字段，就不要重复询问。确认你的理解，只补充缺失信息。
• 对于有固定选项的字段（类别、严重程度、优先级），使用 AskUserQuestion——这样比手动输入更快。
• 对于选填字段，仅在上下文表明这些信息确实有价值时才询问。除非用户报告的是 API 错误，否则不要询问 generation_id。
• 鼓励用户——他们的反馈塑造着 ZenMux。再小的反馈也很重要。

步骤 3：撰写议题

用 Markdown 编写格式良好的议题正文。结构应与 GitHub 议题模板保持一致。仅包含有实际内容的字段——跳过空的选填部分。

各类型的正文格式

错误报告：

### Category
[e.g., API (request handling, response, errors)]

### API protocol used
[e.g., OpenAI Chat Completions (/api/v1)]

### Describe the bug
[Clear description]

### Steps to reproduce
1. ...
2. ...

### Expected behavior
[What should happen]

### Actual behavior
[What actually happened, including error messages/codes if any]

### Severity
[e.g., High - Major feature is broken, no workaround]

### Environment
- SDK: [e.g., Python (openai) v1.x.x]
- Model slug: [e.g., openai/gpt-5]
- Integration tool: [e.g., Claude Code]

### Additional context
[If any]

功能请求：

### Category
[e.g., Observability (logs, cost tracking, usage analytics)]

### Problem / Pain point
[What problem this solves]

### Proposed solution
[How the user wants it to work]

### Use case
[Real-world scenario]

### How important is this to you?
[e.g., High - Would significantly improve my experience]

### Alternatives considered
[If any]

服务商/模型请求：

### Provider name
[e.g., Mistral]

### Model(s) requested
- model-name-1
- model-name-2

### Request type
[New provider / New model from existing provider / Update]

### Model type
[e.g., Text generation, Code generation]

### Use case
[Why they need this]

### How urgently do you need this?
[e.g., Medium - Would be nice to have]

文档反馈：

### Documentation section
[e.g., Getting started / Quickstart]

### What kind of issue?
[e.g., Incorrect or outdated information]

### Language version affected
[English / Chinese / Both]

### Description
[The issue or suggestion]

### Page URL
[If provided]

一般反馈：

### Feedback type
[e.g., Product impressions / First experience]

### Your feedback
[The feedback content]

### How satisfied are you with ZenMux overall?
[If provided]

### What do you primarily use ZenMux for?
[If provided]

### If you could change one thing about ZenMux, what would it be?
[If provided]

步骤 4：预览并确认

提交前向用户展示完整议题：

1. 显示标题（带有 [Feature]: ... 之类的前缀）
2. 清晰地显示格式化后的正文
3. 说明将应用哪些标签
4. 请用户确认或提出修改

未经明确确认，绝不提交。

步骤 5：提交

由于已在步骤 0 中确认 gh 可用，请将正文写入临时文件并提交。**提交前，请对照步骤 0c 中获取的标签列表进行核验——只包含仓库中实际存在的标签。**如果所需标签都不存在，则完全省略 --label 标志。

# Write body to temp file to avoid shell escaping issues
cat > /tmp/zenmux-issue-body.md << 'ISSUE_BODY'
[composed body here]
ISSUE_BODY

gh issue create \
  --repo ZenMux/zenmux-doc \
  --title "[Type]: Title" \
  --body-file /tmp/zenmux-issue-body.md \
  --label "label1"

成功后，向用户显示议题 URL，并清理临时文件（rm /tmp/zenmux-issue-body.md）。

步骤 6：提交后

• 将议题 URL 分享给用户
• 提及公开路线图——他们可以在那里跟踪进展
• 对于不太适合提交为议题的讨论或问题，建议使用 GitHub Discussions 或 Discord 社区
• 感谢他们——公开构建项目时，每一份贡献都很重要

语言

使用用户所用的语言回复。如果用户用中文交流，就用中文对话并撰写问题。如果用户用英文交流，就使用英文。ZenMux 团队都能阅读这两种语言。

主动沟通

如果在对话中（尤其是在使用 zenmux-context 技能时）发现用户遇到了实际问题或对产品有强烈看法，请温和地询问：“需要我帮你将此事作为问题或建议提交给 ZenMux 吗？这有助于团队确定优先级。”不要强求，只需让用户知道有这个选项。