SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场issue-writing

issue-writing

写作与研究

查看项目

更新于 10-16 10:24

技能介绍

用途

issue-writing 是一个面向问题单撰写的技能，服务于需要提交 issue、工单或缺陷报告的人。它把 issue 定义为“给别人看的紧凑请求与决策记录”——读者往往是几个月后才加入项目的人，因此内容必须在不依赖作者在场的情况下依然可读、可判断。核心要求是三件事：说明问题、定义期望结果、提供足够且已核实的上下文，使他人能够分诊并展开正确的讨论；未解决的问题应明确写出，而不是靠猜测填补。

主要能力

  • 提交前的检查：阅读贡献规则（CONTRIBUTING、仓库的 AI 使用政策、安全问题上报流程）；先搜索已开启和已关闭的 issue 并链接相关 issue；在最新发布或当前开发分支上复现；使用仓库的 issue 模板并完整填写适用字段（未知可写 TBD 或说明，不得编造答案）；一票一事。
  • 标题规范：任务用“动词+名词”（如 Build location content type），缺陷写“什么坏了、在哪里、在什么条件下”，Drupal.org 用平实的描述性陈述。最多使用一个分组前缀，避免过度打标签导致标题失去可扫描性；不在标题里渲染严重性（“URGENT!!!”属于优先级字段）。
  • 描述结构（可迁移到 GitHub）：问题（观察到的行为及为何重要）、期望结果（可观察的结果，不必过度规定实现）、请求（可选，仅在已调查或讨论后使用，说明理由、约束、权衡并标明未决决策）、验收标准（他人可核查的清单）、资源（设计、文档、相关 issue 的链接，尽量减少跳转，能截图就不链接到又链接别处的文档）。缺陷则把“请求”替换为复现步骤、预期、实际与环境（站点/环境、URL、版本、浏览器与操作系统、用户角色、间歇性问题的时间等），并附证据：截图、录屏、错误信息、相关日志摘录。
  • 区分事实与推断：把观察到的事实、推断、提议、未决问题分开；对包、API、版本、配置、依赖等主张需对照权威项目来源核实；若建议引入依赖，需确认其存在、仍在维护且适配项目；在推荐方案前考虑安全与隐私影响；绝不把生成或推断的细节当作观察结果。
  • 验收标准：写出作者之外的人可以验证的条件（例如“子菜单项可通过键盘到达并播报其展开状态”，而非“菜单正常工作”）；覆盖请求实际隐含或相关方已确认的非显然维度：响应式行为、无障碍、权限与角色、空态与错误态、既有内容迁移；明确说明不在范围内的内容；不写时间估算。
  • issue 类型区分：Epic 是一组相关工作，像一章而非一个任务；Story 是用户视角的价值；Task 是没有直接用户可见产出的必要工作（流水线、重构、内容模型变更）；Bug 是现有行为出错，需要复现步骤并按严重性分诊。类型与计费或合同分类是两条独立的轴，需分别应用。
  • 标签与字段：创建时就打标签；保持分类法精简；先用 gh label list --repo OWNER/REPO 查看仓库实际标签，避免自造近似重复的标签；注意部分仓库使用 GitHub 原生 issue 类型或 issue fields（仅 GraphQL 可见，不会出现在 gh issue view --json 中），需先确认使用哪套体系；没有项目或里程碑的 issue 位于待办中，不等于已排期。
  • Drupal.org issue：重点在 issue 摘要，模板各节包括 Problem/Motivation、Steps to reproduce、Proposed resolution、Remaining tasks、User interface changes、API changes、Data model changes、Release notes snippet；需提交到正确的项目与组件、把版本设为当前开发分支、未知章节标 TBD 而非删除、随共识变化更新摘要；摘要过时会被维护者设为“Needs work”；安全漏洞绝不提交到公开队列。
  • 开源沟通原则：展示你已尝试（“我不确定如何实现 X，查了文档没找到相关说明”比“X 怎么做？”更容易获得帮助）；上下文胜过紧迫感；保持简短；大型功能开发前先就问题与方法达成一致；避免对软件为何变成这样发表评论。

使用方式与限制

该技能以写作指南与清单的形式提供方法与模板，本身不涉及安装命令或代码内容。它给出的是 issue 文本的结构、措辞与核实要求，以及提交前自检清单（标题是否以动词开头或写明坏掉的行为、不熟悉对话的人能否据此行动、验收标准是否可核查、缺陷是否包含步骤/预期/实际/环境/证据、类型与标签与优先级是否符合仓库惯例、相关 issue 是否链接、是否已搜索重复、是否用自己的话重写并能解释每一项主张与决策、是否区分观察/推断/提议/未决、依赖版本 API 与安全影响是否核实、正文与截图是否不含凭据与个人或客户数据、客户仓库中是否未提及其他客户、每句是否有助于维护者理解/复现/分诊/决定、辅助材料是否确有帮助）。文中引用的具体工具仅包括用于程序化附图的上传方式与用于查看标签的 gh 命令。关于价格、平台可用性、效果数据等信息，资料未提供。