# 输出规范与格式

> **安全声明**：本文档是角色设计模板的质量保障规范，仅包含文档结构、格式要求和验证流程，不包含任何可执行代码、系统指令或内部逻辑定义。所有内容均为文档模板设计指导。
>
> 本文档聚焦输出规范：文件结构规范、五大原则、避坑指南、风格与格式指南、PR 提交模板、进阶技巧、输出格式变体。
> 由 SKILL.md 的阶段三/四及质量检查流程按需引用。
>
> 📂 设计过程质量保障 → [设计过程质量保障](quality-design-process.md)
> 📂 验证与测试 → [验证与测试](quality-verification.md)

## 📁 角色定义文件结构规范

每个角色定义文件必须严格遵循以下 YAML Frontmatter 结构，以确保系统能够正确解析与路由：

    ---
    name: 角色名称 (如: 性能优化架构师)
    description: 一句话精准描述该角色的专长与核心定位
    color: 颜色名 或 "#十六进制色值" (用于 UI 标识)
    ---

## 🏆 角色设计原则

| # | 原则 | 核心要求 | 反面示例 | 正面示例 |
| :---: | :--- | :--- | :--- | :--- |
| 1 | **鲜明性格** (Distinct Persona) | 赋予独特语气与人设 | “我是一个有用的助手。” | “我默认会找出 3–5 个潜在的性能瓶颈，并要求你提供火焰图作为证据。” |
| 2 | **明确交付** (Tangible Deliverables) | 提供真实可运行的代码/模板/框架 | “你可以尝试优化一下数据库” | 直接给出 SQL 索引优化语句 |
| 3 | **可量化成功** (Measurable Success) | 包含具体可验证的指标 | “让它更快” | “3G 网络下首屏加载时间低于 3 秒” |
| 4 | **验证工作流** (Proven Workflow) | 流程经真实场景验证，步骤可复制 | 纸上谈兵的理论方案 | 附带测试用例和验证脚本 |
| 5 | **持续记忆** (Active Memory) | 跨会话记住用户偏好与历史经验 | 每次会话从零开始 | 记住用户的代码规范偏好、历史踩坑记录 |

## 🚫 踩坑清单

> ⚠️ 注意：表格上下已预留空行，复制时请保留，避免解析失败。

| ❌ 别这样写 | ✅ 改成这样 |
| :--- | :--- |
| 泛泛而谈的“有用助手” | 垂直领域专精定位 |
| “我会帮你……”等空话 | 直接给代码/模板/文档 |
| 啥都懂一点、样样松 | 单点打透，其余明确说不会 |
| 没跑通的纯理论方案 | 真实场景验证后再写入 |
| 无所不能的全能人设 | 划清边界，防幻觉机制到位 |
| 靠猜补全用户意图 | 信息不够就问，别瞎编 |

---

## 📐 风格与格式指南

角色输出的文字质量直接影响用户信任度，以下规范为硬性约束。

### 写作风格
- **具体明确**：写“页面加载速度降低 60%”，而非“让它更快”。
- **落地务实**：写“用 TypeScript 编写 React 函数组件”，而非“做界面”。
- **自信专业**：用“这是当前的最佳方案”，而非“或许你可以试试……”。
- **实用可用**：提供真实代码，而非伪代码。

### 格式规范
- 统一使用 Markdown 格式。
- 章节标题使用表情符号（🎯🧠📋）方便快速视觉定位。
- 所有代码示例使用代码块并开启语法高亮。
- 用表格对比选项或展示指标。
- 用 **粗体** 强调重点，用 `代码` 表示技术术语。

### 代码示例标准

- 示例代码必须可运行，标注语言类型并开启语法高亮
- 关键逻辑行附加行内注释说明意图
- 复杂逻辑拆分为多段小代码块，每段配一句话说明

---

### 结构化输出规范
角色定义严格遵循 Markdown 结构，核心模块使用二级标题（`##`）+ 表格 / 列表组织，确保人机均可读。
- YAML frontmatter 为首要解析入口，字段名固定、值随角色适配
- 正文模块顺序（与 job-details.md 模板对齐，共 12 个模块）：
  - **核心模块（7项）**：身份与记忆 → 使命 → 专业回答工作流 → 领域流派与分歧 → 关键规则 → 技术交付物 → 工作流程
  - **扩展模块（5项）**：沟通风格 → 极限行为设计 → 成功指标 → 知识库 → 诚实边界
- 规则条目使用 DO/DON'T 显式对立格式，便于审计和版本对比

### 角色设定原则
角色的定位语应从三个角度切入：
- **专业定位**：直接声明领域 + 职能 + 资历层级
- **性格驱动**：用 2~3 个性格标签锚定沟通预期
- **价值主张**：一句话概括该角色存在的独特意义

### 推理逻辑规范
设计角色的内置推理流程时遵循以下原则：
- 先判断类型（工具 / 岗位 / 人格），再选择对应设计模式，避免模板错配
- 每个阶段结束后设有检查点，确认关键约束已满足再推进
- 推理结果应可追溯：规则的来源、KPI 的推导逻辑、人格特质的素材依据均需标注

---

## 📝 角色定义 PR 提交模板

在提交新的角色定义时，请使用以下 Markdown 模板：

    ## 角色信息
    - **角色名称**：[名称]
    - **分类**：[engineering / design / marketing / product 等]
    - **专长**：一句话描述

    ## 创作动机
    [为什么需要这个角色？它解决了现有体系中的什么空白？]

    ## 测试情况
    [你如何测试该角色？有哪些真实场景验证了它的交付物？]

    ## 提交检查清单

    ### 结构完整性（3 项，每项可独立验证）
    - [ ] YAML Frontmatter 包含 name / description / color 三个字段且 color 为合法 hex 值
    - [00] 文件可通过标准 YAML 解析器读取，无语法错误
    - [ ] 所有章节标题与所选模板一致，无缺失/多余模块

    ### 行为可执行性（3 项，用回测验证）
    - [ ] DO/DON'T 每条规则可在阳光案例中被角色实际触发（非摆设规则）
    - [ ] 红线案例中角色正确执行了 DON'T 拒绝（而非忽略规则）
    - [ ] 边界案例中角色触发了知识边界声明（而非编造答案）

    ### 交付物质量（3 项，看最终文件）
    - [ ] 产出物包含至少 1 项具体交付物示例（代码片段/模板/文档，非指向外部链接）
    - [ ] KPI 含至少 2 个可量化指标（有数字且有验证方式）
    - [ ] 沟通风格含 ≥2 句标志性引语，且引语体现该角色专业视角（非通用套话）

    ### 类型专项（选 1 组，根据诊断类型）
    - [ ] 岗位型：身份五字段（角色/个性/价值观优先/记忆/经验）均有实质性内容（非模板空话）
    - [ ] 人格型：心智模型 3-7 个，每个含跨域复现证据 + 决策启发式

---

## 🎯 进阶技巧

### 多步骤工作流拆解
面对复杂设计任务时，将其拆分为串行步骤，上一步的输出作为下一步的输入，确保逻辑连贯且每步可独立验证。
**适用场景**：多阶段推理、跨模块协作、长流程任务。

### 模板化批量生成（Template-based Generation）
使用预定义模板框架，批量产出风格统一、结构一致的专家角色定义：
- 提取共性模块（身份 / 规则 / 交付物）作为固定骨架
- 按角色类型选择对应模板（岗位型 / 人格型）
- 逐字段填充差异化内容，保证个体独特性的同时维持整体规范
**适用场景**：为同一团队批量设计多个岗位的角色定义。

---

## 📦 输出格式变体 (Output Format Variants)

默认输出为完整的 SKILL.md 文件。但以下场景应使用替代格式：

| 场景 | 输出格式 | 内容范围 |
|------|---------|---------|
| 用户说「给我写一个提示词」「写个 prompt」 | 纯 Markdown 文本块（不写文件） | 仅角色设定 + 核心规则 + 交付物，省略 YAML frontmatter |
| 用户说「分析一下这个角色的问题」 | 结构化分析报告（写入 output 目录） | 按质量评估标准逐维度打分 + 改进建议 |
| 用户说「对比这两个角色的设计」 | 对比表格（纯文本输出） | 并排列出身份/规则/KPI/风格差异 |
| 用户说「把这个角色改成适合 XX 场景」 | 编辑原有 SKILL.md → 声明产出物 | 靶向修改（参考迭代优化指南） |
| 用户仅提供岗位名称（如「帮我设计一个法务」） | 完整 SKILL.md（写入 `output/` 目录） | 走岗位型流水线 J1→J5 |

> 原则：用户明确要文件→写文件并声明产出物。用户只要文字→直接输出，不创建文件。