ccg-workflow Gemini Frontend 角色提示词解析：只读沙箱中的 React 前端开发与 Unified Diff 交付规范

• 人工智能
• AI 应用
• 开发工具
• CLI
• AI Agent
• dsh-plugin
• DeepSeek

ccg-workflow 是一个以 Claude 为编排中枢、Codex/Gemini 等模型协作执行的多模型开发系统。本文聚焦其 19 个专家提示词中 Gemini 专属的 templates/prompts/gemini/frontend.md，完整解析该角色提示词的约束体系、能力模型、输出规范与 .context 协作机制，并结合仓库源码说明它如何通过ROLE_FILE指令被注入外部模型、如何在/ccg:frontend前端工作流中落地。读完本文，你将掌握这一提示词的可复用骨架，并能把它移植到自己的多模型协作流水线中。

该提示词在 ccg-workflow 中的定位

ccg-workflow 的专家提示词库位于 templates/prompts/，共 19 个文件，按模型分成三组：claude/（6 个）、codex/（6 个）、gemini/（7 个）。根据 templates/CLAUDE.md 的目录总览，gemini/组比其他两组多出一个frontend.md——即"Gemini 前端开发专家"，这是 Gemini 专属角色，正好对应本项目"Claude 编排 + Codex 后端 + Gemini 前端"的协作分工。

该提示词的 frontmatter 注释标明其适用场景：

> For: /ccg:code, /ccg:frontend, /ccg:dev Phase 3

也就是说，它在三个入口被触发：/ccg:code（代码执行）、/ccg:frontend（前端专项工作流）以及/ccg:dev开发流程的 Phase 3（执行阶段）。安装时该文件被复制到用户环境的~/.claude/.ccg/prompts/gemini/frontend.md，由安装器 src/utils/installer.ts 在写入前完成模板变量替换。

注入机制：ROLE_FILE指令与只读沙箱

这个提示词并非给 Claude 自己读，而是通过 codeagent-wrapper 注入给外部模型。调用模板见 templates/engine/model-router.md：

Bash({ command: "~/.claude/bin/codeagent-wrapper {{LITE_MODE_FLAG}}--progress --backend $MODEL {{GEMINI_MODEL_FLAG}}... - \"$WORKDIR\" <<'CODEAGENT_EOF' ROLE_FILE: ~/.claude/.ccg/prompts/$MODEL/$ROLE.md <TASK> $TASK_CONTENT </TASK> OUTPUT: $OUTPUT_FORMAT CODEAGENT_EOF", run_in_background: true, timeout: 3600000, description: "$SHORT_DESCRIPTION" })

其中ROLE_FILE就是角色注入的钥匙。codeagent-wrapper 的 utils.go 实现了injectRoleFile()：它用正则(?m)^ROLE_FILE:\s*(.+)$匹配任务文本中行首的ROLE_FILE:指令，读取对应提示词文件内容并注入到任务上下文中，同时记录注入日志（Injected ROLE_FILE: <path> (N bytes)）。path_normalization_test.go还专门验证了该指令在 Windows 路径下的兼容性。

明确了注入链路后，就能理解该提示词开头三条"CRITICAL CONSTRAINTS"的用意：

• ZERO file system write permission—— 外部模型运行在 READ-ONLY 沙箱中，对文件系统零写入权限；
• OUTPUT FORMAT: Unified Diff Patch ONLY—— 输出只能以统一差异补丁形式返回；
• NEVER execute actual modifications—— 永远不要真正执行修改。

这一设计在整个 ccg-workflow 中是一致的：gemini/、codex/、claude/各组提示词均声明只读约束，而 templates/commands-legacy/frontend.md 的关键规则第 4 条写明"Claude 负责所有代码写入和文件操作"。这样既利用了外部模型的专业判断力，又把写文件这个唯一高风险动作收敛给拥有完整上下文和审计能力的编排者，从机制上杜绝了多个模型同时改文件的冲突。

核心能力矩阵

提示词为模型设定的专业领域是"资深前端开发者"，能力矩阵覆盖六条主线：

值得注意的是，这套能力域与 ccg-workflow 内置的前端知识域技能 templates/skills/domains/frontend-design/SKILL.md 形成互补：技能文件提供"做什么"的设计知识（排版、OKLCH 色彩、空间节奏、动效），角色提示词则规定"怎么产出"的工作范式，两者在/ccg:frontend工作流中按需配合。

工作方法：五条铁律

该角色的 Approach 部分是五条高度可执行的方法论：

1. Component-First—— 先构建可复用、可组合的 UI 单元，而不是一次性堆页面；
2. Mobile-First—— 先为小屏设计，再向大屏增强；
3. Accessibility Built-In—— 无障碍是内建属性而非事后补救；
4. Performance Budgets—— 以 3 秒内加载为目标预算；
5. Design Consistency—— 遵循既有设计系统模式，不另起炉灶。

其中"Design Consistency"在后文组件清单和 .context 机制中被反复强化：提示词要求组件不得硬编码颜色与尺寸、必须使用主题 token，这与 frontend-design 技能中"用 OKLCH 而非 HSL""避免纯黑纯白、一律调色"等反 AI-slop 设计准则（reference/color-and-contrast.md）同源。

输出格式：Unified Diff Patch

提示词要求的输出格式是标准 unified diff，模板如下：

--- a/src/components/Button.tsx +++ b/src/components/Button.tsx @@ -5,6 +5,10 @@ interface ButtonProps { children: React.ReactNode; + variant?: 'primary' | 'secondary' | 'danger'; + size?: 'sm' | 'md' | 'lg'; }

要点在于 hunk 头部@@ -5,6 +5,10 @@：-5,6表示原文件从第 5 行开始的 6 行，+5,10表示新文件从第 5 行开始变为 10 行，@@后跟随函数上下文（此处是interface ButtonProps）。因为补丁最终由 Claude 应用，所以要求外部模型输出必须上下文完整、行号准确、无模糊匹配——这也是为什么该提示词同时强调"组件分析先行、再给补丁"，而不是直接丢出可能失配的 diff。

组件交付清单

提示词内置了一份六项自检清单，任何组件交付前都必须逐项打勾：

• TypeScript props interface 已定义
• 在各断点（breakpoints）下响应式正常
• 键盘可访问（Tab、Enter、Escape）
• 为屏幕阅读器提供 ARIA 标签
• 已处理 loading 与 error 状态
• 无硬编码颜色/尺寸（使用主题）

这份清单与配套的 templates/prompts/gemini/reviewer.md 审查清单遥相呼应——后者把 Accessibility（语义化 HTML、ARIA、键盘导航、焦点管理、色彩对比度）、Design Consistency（token 使用、间距排版一致）、Code Quality、Performance、Responsive 拆成五组 20 项检查，并在/ccg:bugfix场景下要求输出 100 分制评分报告（UX/视觉一致性/无障碍/性能/浏览器兼容各 20 分）。这意味着 frontend.md 的开发清单不是孤立的自检，而是为了通过 reviewer.md 的验收而设计的最低交付门槛。

响应结构

提示词规定了四次输出必须遵循的固定结构，保证下游编排者（Claude）能稳定解析：

1. Component Analysis—— 分析现有模式与上下文，说明在哪个文件、什么模式上扩展；
2. Design Decisions—— 说明 UI/UX 取舍及理由（配合 .context 机制，这些决策会被沉淀为 ContextEntry）；
3. Implementation—— 输出 Unified Diff Patch；
4. Usage Example—— 给出组件用法示例。

这个四段式结构与 templates/prompts/gemini/architect.md（Analysis → Architecture Decision → Implementation Plan → Considerations）同构，说明 gemini 组提示词在"先分析、再决策、后产出、附示例"的信息架构上保持了一致的设计语言，便于编排者对多角色输出做统一处理。

.context 感知：让 AI 遵循项目既有约定

提示词规定，若项目存在.context/目录，必须执行四步：

1. 编码前读取.context/prefs/coding-style.md与.context/prefs/workflow.md；
2. 遵循其中全部约定（命名、模式、测试要求）；
3. 做设计决策（组件模式、状态管理等）时，在输出中明确说明理由与被否决的替代方案；
4. 遵循 workflow.md 的完整开发流程（implement → test → docs）。

这一机制让外部模型在每次新会话中都能快速对齐项目的"宪法"。/ccg:context命令（见 templates/commands/context.md）负责维护.context目录，包括初始化、记录决策日志（commits.jsonl）、压缩归档与历史查看。配套的 analyzer、architect、reviewer 提示词也都要求查阅commits.jsonl中的历史决策，避免当前改动与既往架构决策冲突——这正是多模型协作中防止"上下文漂移"的关键设计。

在/ccg:frontend工作流中的实际位置

在 templates/commands-legacy/frontend.md 定义的前端专项工作流中，frontend.md 提示词位于执行环节。整个工作流分六阶段：

执行阶段（Phase 3）即 frontend.md 的主场：Claude 将用户确认过的计划、阶段 1 收集的项目上下文、阶段 2 的分析结果打包进<TASK>，通过codeagent-wrapper调用前端模型，前端模型按本提示词要求输出 Unified Diff Patch，再由 Claude 负责实际写入。整个链路中前端模型全程无写权限，仅产出建议，写入始终由编排者执行。

从配置角度看，前端主模型由模板变量{{FRONTEND_PRIMARY}}控制，默认值为gemini，可在安装时配置为codex/claude（见 templates/CLAUDE.md 的模板变量表）；{{GEMINI_MODEL_FLAG}}默认替换为--gemini-model gemini-3.1-pro-preview，在未使用 Gemini 时替换为空字符串。这些占位符由 src/utils/installer-template.ts 的injectConfigVariables()在安装时一次性替换，运行时不再残留占位符（v2.1.14 起的关键设计决策）。

与前端测试角色的衔接

frontend.md 只负责"写出正确的组件"，而验证环节交给配套的 templates/prompts/gemini/tester.md。该测试角色同样声明只读约束与 diff-only 输出，策略覆盖组件测试（渲染、props 校验、事件处理、状态变化）、用户交互测试（表单、按钮、键盘导航、焦点管理）、可访问性测试（屏幕阅读器、纯键盘、ARIA、对比度）与覆盖率聚焦（面向用户行为而非实现细节），并强调优先使用getByRole、getByLabelText等可访问性查询、用waitFor/findBy处理异步。开发与测试角色分离、同样以 diff 交付，保证前端产物的正确性由独立视角验证。

小结：一个可移植的"只读专家"提示词范式

templates/prompts/gemini/frontend.md展示了 ccg-workflow 外部模型角色的通用范式：强约束（只读 + diff-only）→ 领域能力 → 方法铁律 → 交付清单 → 固定响应结构 → 项目上下文感知。它解决了多模型协作中最棘手的两个问题：一是通过零写权限与统一补丁格式，让多个模型在共享代码库上安全并行；二是通过 .context 强制对齐，让每次新会话的外部模型都能继承项目既定约定，避免输出风格与架构决策漂移。

如果你正在搭建自己的多模型开发流水线，可以直接复用这套骨架：把"角色提示词 + ROLE_FILE 注入 + 只读沙箱 + diff 交付 + 上下文前置读取"五件套组合起来，再配合本仓库 templates/prompts/ 下的 analyzer/architect/reviewer 系列提示词，即可快速构建出结构一致、行为可预期的协作专家团队。

• 人工智能
• AI 应用
• 开发工具
• CLI
• AI Agent
• dsh-plugin
• DeepSeek