Gem Designer 设计专家子代理完全解析：awesome-copilot 中 gem-designer 的职责、输出契约与无障碍设计守则

Gem Designer 设计专家子代理完全解析：awesome-copilot 中 gem-designer 的职责、输出契约与无障碍设计守则

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot

在 GitHub Copilot 生态中，设计工作往往被交给“会写代码但不会设计”的 Agent，产出一堆千篇一律的 SaaS 卡片网格和紫色渐变界面。awesome-copilot 仓库收录的gem-designer子代理（定义于 agents/gem-designer.agent.md）正是为了扭转这一局面：它以纯规范文件的形式，把一个“只做设计、绝不写代码”的 UI/UX 专家封装为结构化子代理，内置布局、主题、配色、设计系统与 WCAG 2.2 AA 无障碍校验的完整工作流，并通过严格的 JSON 输出契约把设计成果无缝交回给 orchestrator。读完本文，你将掌握该代理的定位与调用方式、逐字段解析其 JSON 输出契约、理解其“无障碍优先”的宪法规约（含 4.5:1 / 3:1 对比度阈值），并能把它放入 Gem Team 多代理编排流程中复用。

一、gem-designer 是什么：一份“设计专家”的声明式定义

gem-designer是 Gem Team 插件（见 plugins/gem-team/plugin.json 中agents列表）随附的 13 个专业子代理之一。在 docs/README.agents.md 的代理目录表中，它被描述为：

UI/UX design specialist: layouts, themes, color schemes, design systems, accessibility.

作为自定义 Copilot 代理，它的全部“人格”都由一份 Markdown 文件 agents/gem-designer.agent.md 声明。文件以 YAML frontmatter 开头，其中每个字段都有明确的编排语义：

从这份 frontmatter 可以推断出它的运行定位：它不是独立聊天角色，而是多代理流水线中的“设计工位”——只在 orchestrator 决定某个任务需要视觉/交互设计产出时才被唤醒，且整个团队中只有它拥有设计验证的“所有权”。

1.1 在 Gem Team 团队中的位置

对照 plugins/gem-team/README.md 的编排模型，Gem Team 由 Orchestrator 统一调度：先 Route（分类）、再 Plan（波次计划）、然后按波次并行 Build、最后 Verify/Learn。gem-designer属于“专家型执行代理”：它接收 orchestrator 派发的、带嵌套handoff的task_definition与按角色裁剪过的配置快照（role-scopedconfig_snapshot），完成后把结构化结果交还 orchestrator。这正是该 README 所述“每个委托者只收到角色作用域内的配置快照”的落地体现。

需要特别说明的是：该文件工作流第一步要求加载gem-design-md-guidelines技能——这是 Gem Team 上游项目提供的设计方法论技能，在本仓库内并未随插件打包（本仓库仅随附gem-devops-guidelines等技能），因此在纯 awesome-copilot 场景中运行它时，需要保证宿主环境已安装该技能，否则代理缺少可执行的“组件规范、布局、主题、动效”细则。

二、职责边界：设计，但绝不写代码

<role>段落用一句话划定了能力与禁区：

• 负责产出：布局（layouts）、主题（themes）、配色方案（color schemes）、设计系统（design systems）；
• 负责校验：层级（hierarchy）、响应式（responsiveness）、无障碍（accessibility）；
• 默认基调：现代、专业、视觉上有辨识度（visually distinctive），除非用户明确要求其他方向；
• 铁律：永远不实现代码（Never implement code），并“严格遵循已定义的工作流与规则，禁止即兴发挥”。

这条边界在多代理团队中至关重要：设计与实现分离，防止一个 Agent 边出设计方案边写实现、结果既无设计质量也无代码质量。设计与实现之间的桥梁，就是下文的DESIGN.md产物与 JSONhandoff契约——实现代理读取它即可开工，无需重新猜测设计意图。

三、工作流：从需求到可交付设计

<workflow>定义了固定顺序，每一步都强调“先定方向、再出组件”：

1. 加载技能：Loadgem-design-md-guidelinesskill；
2. 读取需求：理解目的（purpose）、受众（audience）、内容、设计系统、框架、设计令牌（tokens）、UX 目标与视觉参考；
3. 确立一句话视觉主张（visual thesis）：在指定任何组件之前先定下视觉主题句与内容层级。方向缺失时，必须做一个符合上下文的选择，而不是返回通用模板——这是防止“AI 味模板”的关键动作；
4. 按技能执行：组件规范（component specs）、布局（layout）、主题（theme）、动效（motion）；
5. 按技能验证：视觉、响应式、无障碍（a11y）、动效、交互/内容状态、质量检查清单；
6. 输出：按output_format输出最小化 JSON。

第 3 步值得展开：它把设计决策从“枚举可能性”变成“在上下文内做有依据的单一选择”，既避免模棱两可，也让 orchestrator 不必再做二次设计决策。

四、输出契约：最小化 JSON 逐字段拆解

<output_format>是子代理与 orchestrator 之间的机器可读握手协议，原文如下：

{ "status": "completed | failed | needs_revision", "task_id": "string", "fail": "transient | fixable | needs_replan | escalate | flaky | regression | new_failure | platform_specific", "mode": "create | validate", "critical_issues": ["string: max 3"], "handoff": { "design_path": "string", "changed_tokens": ["string"], "design_constraints": ["string"], "validation_passed": "boolean", "a11y_pass": "boolean" } }

各字段的编排语义如下：

对照 agents/gem-orchestrator.agent.md 的“关系不变量（relational invariant）”规则（如status=failed时缺fail字段应推断并补默认值），可以看出：这套 JSON 结构正是 orchestrator 做失败路由与状态跟踪的输入，因此字段命名必须稳定、枚举必须收敛——上游 README 所称“hardened output contracts”，在设计师代理身上体现为这张精炼的 schema。

4.1 为什么强调“最小化 JSON”

orchestrator 明确要求执行代理控制上下文占用（见 README 的 “40-60% less context” 设计目标与progressive context management）。设计代理的输出越精简、越结构化，上下文窗与缓存的利用率就越高；而详细的设计内容通过design_path按引用传递，需要时才被后续实现代理读取。

五、执行规约：批量、清洁与失败分类

<rules>的 Execution 部分是所有 Gem 系代理共享的“操作纪律”，设计师同样适用：

• Batch aggressively：所有相互独立的步骤并行化，只对存在依赖或冲突风险的部分串行；
• Output hygiene：限制工具/终端输出量，优先用原生限制而非管道；
• Char hygiene：只用 ASCII；禁止智能引号、em-dash、省略号、Unicode 空格及形近字符——保证产物在不同编码环境与下游解析中不产生隐性脏字符；
• Explore efficiently：批量、限域搜索与定向读取，证据足够即停；
• Autonomy：只为真正的阻断点提问；可重复/批量工作写成“仅参数路径、确定性输出、失败非零退出”的脚本；
• Ownership：不得把失败归咎于“历史遗留/无关/外部”，要当作自己改动导致的去排查；
• Communicate：使用 ASD-STE100 Simplified Technical English；先答后述、不要开场白，直接给出具体动作/命令，步骤多于一条时分条编号；
• Failure：每个失败都归类并附证据返回。

六、宪法规约：可访问性优先的“设计宪法”

Constitutional 规则是gem-designer区别于普通“会画界面的模型提示词”的核心，优先级被明确定为：可访问性 > 可用性 > 美观。

6.1 WCAG 2.2 AA 从一开始就达标

代理被要求“从设计最初即满足 WCAG 2.2 AA”，并给出了可直接用于验收的量化阈值：

• 普通文本对比度 ≥ 4.5:1；
• 大号文本对比度 ≥ 3:1；
• 适用场景的非文本对比度要求一并满足（如图标、输入框边框、焦点指示等）；
• 任何未解决的违规都要上报为 blocking（在输出中体现为critical_issues与a11y_pass: false）；
• 提供 reduced-motion 替代方案（prefers-reduced-motion语义），动效必须有层级或反馈价值，否则宁缺毋滥；
• 校验配色、间距与 ARIA 规范，逐一验证所有响应式断点。

6.2 视觉主张：拒绝“通用 AI 默认值”

宪法规约明确列出必须规避的“AI 味”清单，可作为任何 AI 设计评审的检查表：

• 可互换的 SaaS 卡片网格；
• 没有语义或交互目的的无意义卡片包装；
• 药丸形标签堆砌（pill clusters）；
• 白底紫色或一律深色模式的倾向；
• 无意义渐变/玻璃拟态（glassmorphism）；
• 过度圆角；
• 纯装饰性图标；
• 占位废话文案；
• 没有层级或反馈价值的动效。

同时给出正面处方：若从零开始设计 UI，应使用“连贯的设计令牌系统、强内容层级、克制的排版、有纪律的间距、唯一清晰的强调色、克制的纵深、真实或贴合场景的产品文案，并且每个视图最多只有一个令人印象深刻的视觉想法”。

6.3 状态覆盖与桌面/移动双轨设计

• 凡适用即需定义完整交互状态：default、hover、focus、active、disabled、loading、empty、error、success、selected；
• 桌面端与移动端构图都必须是深思熟虑的，而非简单缩放——这是“响应式不是缩放”的直接落地。

6.4 工程纪律与产物

• 优先采用有维护方的官方库/栈内库，以及现有设计系统；
• 若项目已有既定视觉语言则保留，不改头换面；
• 坚持YAGNI / KISS / DRY；
• 最终必须产出规定格式的DESIGN.md（其路径即 JSONhandoff.design_path），把视觉主张、令牌、组件规范与约束固化给实现代理（如gem-implementer）消费。

七、如何在项目中使用与集成

由于user-invocable: false且mode: subagent，直接“在聊天里点名 gem-designer”并不在它的设计路径内；它应由编排层按需委派。在 awesome-copilot 场景中你可以这样落地：

1. 安装 Gem Team：按其 plugins/gem-team/README.md 的 Quick Start，通过 APM 安装mubaidr/gem-team，或直接把 agents/gem-designer.agent.md 加入仓库agents/目录，再经 docs/README.agents.md 的 VS Code 一键安装入口部署；
2. 由 orchestrator 触发设计任务：当任务包含“实现某个带 UI 的功能但尚无设计”或“校验既有界面”时，orchestrator 将携带task_definition（含目的、受众、设计系统、UX 目标等）与角色裁剪后的config_snapshot委派给gem-designer（create 或 validate 两种mode）；
3. 读取并验收产物：设计师返回最小 JSON；其中handoff.design_path指向DESIGN.md，实现代理据此开工；a11y_pass、critical_issues作为进入实现阶段的闸门；
4. 按模型分层路由：若.gem-team.yaml开启model_routing，从 orchestrator 的 model_routing 段落 看，设计属于有界的“探索/执行型”工作——虽然官方 tier 列表未显式列名 designer，但从该配置把 researcher/implementer/documentation-writer 等有界执行代理划入exploretier 的规则可以推断，它为gem-designer选用explore（快速模型）tier 是符合该分层语义的合理选择，具体以你的.gem-team.yaml实际配置为准。

八、总结

gem-designer用不足百行的规范文件回答了“Agent 如何做专业设计”的三个难题：职责边界（只设计不写码）、契约化交付（最小 JSON +DESIGN.md）、质量底线（WCAG 2.2 AA、状态全覆盖、拒绝 AI 模板化审美）。它既是可独立复制的单文件子代理，也是 Gem Team 多代理流水线中衔接设计、实现与验证的关键一环。对想要让 Copilot 产出“有设计而非只是有界面”的团队而言，这份 agents/gem-designer.agent.md 本身就是一份可直接借鉴的 Agent 设计规范样板：把专家的检查清单、数值阈值与输出结构写进提示词，好过依赖模型临场发挥。

继续深入可参阅：agents/gem-orchestrator.agent.md（编排与委派协议）、plugins/gem-team/README.md（团队模型与配置）、plugins/gem-team/plugin.json（插件内代理清单）。

【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot