fusion-issue-authoring

问题编写

Agent 模式

此技能使用内部 Agent 模式，根据类型采用不同的草拟逻辑：

• agents/bug.agent.md：侧重 Bug 的问题草拟和分诊结构
• agents/feature.agent.md：侧重功能的范围和验收结构
• agents/user-story.agent.md：由角色、工作流和场景驱动的用户故事结构
• agents/task.agent.md：以清单为先的任务分解和依赖规划
• agents/devils-advocate.agent.md：始终启用的质量协作者，在分类后提出关键疑虑（moderate 模式）；在用户明确要求、范围或标准存在重大缺口，或从 fusion-issue-task-planning 调用且存在两个或更多架构歧义信号时，进行完整的结构化访谈（interrogator 模式）

Agent 模式会根据问题类型分类在内部激活。用户无需直接引用 Agent 文件。共享关卡（标签、受派人确认、草稿审阅、发布确认和变更顺序）仍由此技能负责。

适用场景

适用于将想法、Bug、功能请求或用户需求转化为清晰、可执行的 GitHub 问题，也可作为创建和更新问题的顶层路由器。

常见触发语：

• “创建一个问题”
• “起草一个工单”
• “把这个整理成 GitHub 问题”
• “帮我构建这个工作项”
• “更新 / 维护 / 清理这个问题”
• “将其添加为子问题 / 设置父问题 / 链接为子项”

不适用场景

• 实现代码变更
• 编写或审查 PR
• 不会形成问题草稿的一般研究
• 未经用户明确确认就变更 GitHub 状态

必需输入

发布前收集：

• 目标仓库
• 问题意图 / 背景和类型（Bug、Feature、User Story、Task）
• 更新问题时，提供现有问题编号 / URL
• 仓库标签集（或确认有意跳过标签）。按仓库缓存完整标签集，并在本地筛选。优先使用主机端会话记忆；否则使用 .tmp/ 缓存文件（绝不提交）。
• 父问题 / 相关问题链接及依赖方向（子问题还是阻塞项）
• 受派人偏好（@me、特定人员或不指定）。复用已缓存的受派人候选结果；如果用户提供了 @me 或确切登录名，则跳过搜索。

如果缺少必需信息，请从 references/questions.md 中提出简洁的澄清问题。 如果问题的目标位置不明确，请在起草变更命令前明确询问应在哪里创建 / 更新问题。

说明

步骤 1 — 分类并路由

将请求分类为 Bug、Feature、User Story 或 Task，然后激活匹配的 Agent 模式：

• Bug -> agents/bug.agent.md
• Feature -> agents/feature.agent.md
• User Story -> agents/user-story.agent.md
• Task -> agents/task.agent.md

如果类型不明确，只提出必要的澄清问题。

魔鬼代言人审查：agents/devils-advocate.agent.md 始终以 moderate 模式启用——分类后提出 2–3 个最重要的疑虑，不打断流程。当用户要求“盘问”、说“对这个进行压力测试”、范围或标准存在重大缺口，或从 fusion-issue-task-planning 调用且存在两个或更多架构歧义信号时，升级到 interrogator 模式，在类型专属 Agent 开始工作前进行完整的结构化访谈。魔鬼代言人会返回已确认的决策和记录的风险，然后移交给类型专属的起草 Agent。

步骤 2 — 确定仓库和模板

• 在进行任何变更前，先确定目标仓库。
• 如果没有明确指定仓库，请检查当前工作区中的贡献者指南（CONTRIBUTING.md、contribute/），查找按类型定义默认问题路由的说明。提出询问前，先应用找到的任何路由规则。
• 如果仓库中没有路由说明，请明确询问应在哪里创建问题。
• 模板优先级：
  1. 仓库模板（.github/ISSUE_TEMPLATE/）
  2. 专用备用模板

步骤 3 — 检查重复项

使用 mcp_github::search_issues 进行一次有针对性的重复项搜索，并在起草／发布前展示匹配结果。 除非用户大幅更改范围／标题，否则不要重复进行宽泛的重复项扫描。

步骤 4 — 先起草

写入前，检查用户偏好和会话记忆中是否指定了首选草稿位置。如果存在已保存的偏好，就使用该位置。如果未找到偏好且意图不明确，只询问一次，并在本次会话中记住答案。如果未找到偏好，且没有需要询问的问题，则默认使用 .tmp/{TYPE}-{CONTEXT}.md。使用 GitHub Flavored Markdown 编写草稿。

步骤 5 — 审核并确认

• 先询问是否需要修改内容。
• 执行更改前，明确询问是否确认发布。
• 除非用户明确确认，否则不要在首次起草时同时发布／更新。

步骤 6 — 执行共享门控

更改前，确认：

• 标签（仅使用目标仓库中存在的标签）
• 指派对象意图（@me、特定登录名或不指派）

共享门控缓存策略：

• 首次查询 owner/repo 的标签时，获取一次仓库标签集，并在当前会话中缓存。如果主机提供会话记忆，优先使用 /memories/session/<owner>-<repo>-labels.json；否则使用 .tmp/issue-authoring-labels-<owner>-<repo>.json。
• 命中缓存时，在本地验证请求的标签。不要针对每个请求的标签重复进行单项查询。
• 如果主机仅支持单项标签查询，且尚无缓存的标签集，不要逐个循环查询标签。询问用户是跳过可选标签，还是仅在首次 mcp_github::issue_write 调用中包含用户确认的标签，并处理一次拒绝情况。
• 如果用户已提供 @me 或准确的 GitHub 登录名，则跳过 mcp_github::search_users。
• 需要查询指派对象时，按 owner/repo（或 owner）和查询内容作为键，在当前会话中缓存候选结果。优先使用 /memories/session/<owner>-<repo>-assignee-candidates.json 或 /memories/session/<owner>-assignee-candidates.json；否则使用 .tmp/issue-authoring-assignee-candidates-<owner>-<repo>.json。
• 如果速率限制阻止了可选的标签或指派对象补充查询，应询问用户是否在不进行这些查询的情况下继续，而不是循环重试。

步骤 7 — 通过 MCP 执行更改（按顺序）

获得明确确认后，按以下顺序执行 MCP 更改：

1. 使用完整的已知负载（title、body，并且仅在受支持时包含 labels、assignees、type），通过 mcp_github::issue_write 创建／更新
2. 仅当步骤 1 中某些必需字段未知、之后才变得可用时，才可额外调用一次 mcp_github::issue_write
3. 仅当用户要求更改关系／顺序时，才调用 mcp_github::sub_issue_write
4. 仅当用户明确要求添加阻塞／状态说明时，才调用 mcp_github::add_issue_comment

如果由于缺少 MCP 服务／身份验证／配置而导致更改失败：

• 清楚说明失败原因
• 引导用户按照 references/mcp-server.md 中的步骤完成设置
• 用户确认设置完成后再重试

速率限制处理：

• 清楚识别并报告速率限制错误（API rate limit exceeded、secondary rate limit、GraphQL 配额耗尽）。
• 遇到速率限制时，停止非必要查询并跳过可选补充查询。
• 保留草稿文件，并提供安全的重试计划，不要循环重试。
• 如果存在等效 MCP 功能，优先使用 MCP 工具，而不是临时进行 gh api／GraphQL 重试。
• 使用 GraphQL 回退方案时：每次更改会消耗 5 个次级限制点（查询为 1 点），因此应将字段合并到一次更改调用中，并在两次更改调用之间至少暂停 1 秒。
• 重试任何请求前，遵守 retry-after 和 x-ratelimit-reset 标头的要求。

type 规则：

• 仅当仓库配置了问题类型时才使用 type。
• 有可用的组织级缓存问题类型时，使用缓存。
• 仅在缓存未命中或无效时调用 mcp_github::list_issue_types。
• 如果不支持问题类型，则本次会话余下时间都省略 type。

步骤 8 — 验证关联关系

建立关联之前：

• 使用子议题进行拆分
• 使用子议题排序表示前置条件
• 确保依赖关系图不存在矛盾

在 references/instructions.md 和 references/mcp-server.md 中查看详细的行为说明和负载示例。

需要保留的核心行为

• 分类优先工作流
• 路由至 Agent 模式的工作流
• 草稿优先工作流
• 缺少关键上下文时提出澄清问题
• 执行任何 GitHub 修改前都要明确确认

在 references/instructions.md 中查看详细的编写指南。 回退模板位置：

• Bug：assets/issue-templates/bug.md
• Feature：assets/issue-templates/feature.md
• User Story：assets/issue-templates/user-story.md
• Task：assets/issue-templates/task*.md

预期输出

• 所选 Agent 模式路径
• .tmp/ 下的议题草稿文件路径
• 使用的模板来源（仓库模板路径或回退资源路径）
• 建议的标题、正文摘要和标签
• 议题类型计划
• 依赖计划（顺序 + 建议的子议题/阻塞关联）
• 指派计划（指派对象，或明确决定不指派）
• 明确的状态：执行任何发布/更新命令前为 Awaiting user content approval
• 找到的任何相关/重复议题链接
• 确认后要运行的确切创建/更新命令
• 仅在确认修改后提供已创建/更新议题的 URL/编号
• 当仓库模板缺失或不完善时，建议后续维护模板

安全与约束

绝不：

• 未经用户明确确认，运行 mcp_github::issue_write 创建/更新议题
• 在用户确认草稿内容正确之前发布/更新议题
• 假定用户想要发布到 GitHub
• 请求或泄露秘密/凭据
• 未经明确确认执行破坏性命令

始终：

• 保持草稿简洁且便于编辑
• 议题文本优先说明 WHAT/WHY，而非实现 HOW
• 使用完整的仓库议题引用（例如 owner/repo#123）
• 当需要关闭议题时，使用议题关闭关键词（例如 fixes owner/repo#123、resolves owner/repo#123 或 closes owner/repo#123）