# 外部 Coding Agent 技能规范（研发云协同 · 离线生产层）

> **定位**：外部 Coding Agent 不访问研发云 MCP，专注离线生成高质量中间产物（文档/代码/分析建议），交付给研发云数字员工（在线执行层）落地。
>
> **共 5 个技能**（1 个总控 + 4 个域技能），总控负责意图路由与任务规划，4 个域技能按优先级排序：PRD 生成 → 架构设计文档 → HTML 原型 → 工作项拆分建议。

---

## 技能 0：意图路由与任务规划（orchestrator-router-distilled）

### 0.1 职责

分析用户原始输入，完成**意图识别 → 域路由 → 任务拆解 → 上下文压缩**，生成标准化任务指令（JSON），分发给下游 4 个域技能之一或多个。这是外部 Coding Agent 的**总控入口**——所有用户请求先经过本技能分析，再路由到具体域技能执行。

### 0.2 核心价值

| 价值点 | 说明 |
|--------|------|
| **意图识别** | 从模糊自然语言中精确判断用户想做什么（生成PRD？做原型？拆工作项？） |
| **域路由** | 根据意图自动选择对应的域技能，避免用户手动指定 |
| **任务拆解** | 复合请求拆成有序子任务链（如"帮我做个客户管理功能"→PRD→架构→原型→拆分） |
| **上下文压缩** | 把长对话/多文档/历史消息压缩成结构化上下文摘要，降低下游技能的 token 消耗 |
| **参数预填** | 从用户输入中提取域技能所需的关键参数（项目名、设计体系、平台等），减少下游交互轮次 |
| **缺失检测** | 识别关键信息缺失项，一次性向用户追问，避免下游技能多次打断 |

### 0.3 输入

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `user_input` | String | 是 | 用户原始话术（未经加工的自然语言） |
| `conversation_history` | String | 否 | 对话历史摘要（多轮对话场景，最近5轮） |
| `attached_files` | String[] | 否 | 用户附件内容摘要（文档/图片/截图的文本描述） |
| `user_context` | Object | 否 | 用户上下文（项目ID、团队信息、当前迭代等已知信息） |

### 0.4 输出（标准化任务指令 JSON）

```json
{
  "meta": {
    "request_id": "唯一标识",
    "timestamp": "生成时间",
    "user_input_raw": "用户原始话术",
    "intent_confidence": 0.0-1.0
  },
  "intent": {
    "primary_domain": "prd | architecture | prototype | workitem_split | multi_step",
    "secondary_domains": ["architecture", "prototype"],
    "action_type": "create | modify | query | analyze",
    "description": "一句话描述识别到的意图"
  },
  "task_plan": {
    "execution_mode": "single | sequential | parallel",
    "steps": [
      {
        "step_id": 1,
        "skill": "srdcloud-prd-distilled",
        "skill_label": "PRD生成",
        "depends_on": [],
        "status": "ready"
      },
      {
        "step_id": 2,
        "skill": "architecture-design-doc-distilled",
        "skill_label": "架构设计文档",
        "depends_on": [1],
        "status": "blocked"
      }
    ]
  },
  "context_summary": {
    "project_name": "从输入提取或推断的项目名",
    "requirement_text": "整理后的需求描述（去除口语化、补全隐含信息）",
    "key_entities": ["客户管理", "跟进提醒", "消息推送"],
    "tech_constraints": "已识别的技术约束（框架/数据库/平台等，无则null）",
    "design_hints": {
      "design_system": "Neutral Modern | null（未指定）",
      "platform": "响应式Web | null",
      "page_type": "dashboard | null"
    },
    "team_info": "团队成员信息（无则null）",
    "sprint_info": "迭代信息（无则null）"
  },
  "missing_info": [
    {
      "field": "project_name",
      "reason": "用户未提及项目名",
      "question": "请问这个需求属于哪个项目？",
      "is_blocking": false,
      "default_value": "未命名项目"
    }
  ],
  "delivery_instructions": [
    {
      "target_skill": "srdcloud-prd-distilled",
      "parameters": {
        "requirement_text": "{context_summary.requirement_text}",
        "project_name": "{context_summary.project_name}"
      }
    }
  ]
}
```

### 0.5 意图识别规则

#### 关键词 → 域技能路由表

| 关键词/语义模式 | 路由目标 | action_type | 说明 |
|----------------|---------|-------------|------|
| PRD/需求文档/产品需求/写需求 | srdcloud-prd-distilled | create | 生成PRD |
| 修改PRD/更新需求文档/补充需求 | srdcloud-prd-distilled | modify | 修改已有PRD |
| 架构/技术方案/技术规约/接口设计/数据模型 | architecture-design-doc-distilled | create | 生成架构设计文档 |
| 修改架构/调整技术方案 | architecture-design-doc-distilled | modify | 修改已有架构文档 |
| 原型/页面/demo/界面/UI/设计稿/HTML | design-proto-distilled | create | 生成HTML原型 |
| 换风格/调平台/改文案/换色/调布局 | design-proto-distilled | modify | 迭代修改已有原型 |
| 拆分/拆任务/工作项/用户故事/排期/指派 | workitem-split-advisor-distilled | create | 生成工作项拆分建议 |
| 做个功能/帮我实现/我想要一个 | multi_step | create | 复合请求，需多技能串联 |

#### 复合请求识别（multi_step）

当用户输入同时包含以下信号时，判定为复合请求，触发多技能串联：

| 信号组合 | 串联顺序 |
|---------|---------|
| "做个XX功能"（无已有PRD） | PRD → 架构 → 原型 → 拆分 |
| "做个XX功能"（已有PRD） | 架构 → 原型 → 拆分 |
| "根据这个需求做个原型" | PRD → 原型 |
| "写个PRD然后拆任务" | PRD → 拆分 |
| "需求文档+技术方案+原型" | PRD → 架构 → 原型 |

#### 置信度评估

| 置信度 | 判定条件 | 处理方式 |
|--------|---------|---------|
| ≥0.8 | 关键词明确命中单一域 | 直接路由，不追问 |
| 0.5-0.8 | 关键词部分命中或有多域信号 | 路由到主域，标注次要域 |
| <0.5 | 关键词模糊或无明确意图 | 向用户追问一次，提供选项 |

### 0.6 上下文压缩规则

#### 需求描述整理

将用户口语化输入转化为结构化需求描述：
1. **去除口语化**：删除"帮我""我想""能不能"等无信息量词汇
2. **补全隐含信息**：根据上下文推断省略的主语、宾语
3. **结构化**：按"目标用户 + 核心功能 + 业务价值"三要素整理
4. **标注不确定项**：对推断的部分标注 `[推断]`，对缺失的部分标注 `[待确认]`

#### 关键实体提取

从需求描述中提取以下实体类型：
- **功能模块**：如"客户管理""跟进提醒""消息推送"
- **用户角色**：如"销售""主管""运营"
- **技术关键词**：如"Spring Boot""MySQL""Redis"（用于架构设计预填）
- **设计关键词**：如"后台""仪表盘""登录页"（用于原型设计预填）
- **业务约束**：如"7天内完成""支持1000并发"

#### 设计简报预提取

当路由目标包含 `design-proto-distilled` 时，从需求中预提取设计简报参数：

| 参数 | 提取规则 | 默认值 |
|------|---------|--------|
| `design_system` | 匹配9套设计体系关键词表 | Neutral Modern |
| `platform` | 匹配6种平台关键词表 | 响应式Web |
| `page_type` | 匹配13种页面类型关键词表 | 通用前端 |
| `page_topic` | 提取页面主题（产品名/功能名） | [待确认] |
| `target_audience` | 提取目标用户角色 | null |
| `core_content` | 提取核心功能描述（1-2句） | [待确认] |
| `multi_view` | 检测是否含≥2个功能模块 | false |

> 预提取的设计简报参数直接注入 `delivery_instructions` 的 `parameters` 中，下游技能无需再次推断。

### 0.7 缺失信息检测

检测下游技能所需但用户未提供的关键信息，生成追问清单：

| 检测项 | 对应域技能 | 阻断级别 | 追问示例 |
|--------|-----------|---------|---------|
| `project_name` 缺失 | PRD/架构/拆分 | 非阻断（有默认值） | "请问这个需求属于哪个项目？" |
| `requirement_text` 过于模糊 | PRD | 阻断 | "能否详细描述一下核心功能和目标用户？" |
| `page_topic` 缺失（原型） | 原型 | 阻断 | "请问页面的主题是什么？比如'客户管理后台'" |
| `design_system` 无法推断 | 原型 | 非阻断（有默认值） | "请问偏好哪种设计风格？" |
| `team_members` 缺失（拆分） | 拆分 | 非阻断（标注"待分配"） | "请提供团队成员列表，用于处理人建议" |
| `sprint_info` 缺失（拆分） | 拆分 | 非阻断（跳过迭代规划） | "是否需要规划到特定迭代？" |
| `tech_constraints` 缺失（架构） | 架构 | 非阻断（按最佳实践推荐） | "是否有技术栈要求？如指定框架/数据库" |

#### 追问规则
1. **一次性追问**：所有缺失项合并为一次提问，不分多次打断
2. **阻断项优先**：阻断项排在前面，非阻断项排在后面并标注默认值
3. **提供选项**：对设计体系/平台等枚举型参数，提供选项列表
4. **最多追问一次**：用户回复后不再追问，按回复值或默认值执行

### 0.8 任务编排规则

#### 单步模式（single）

当 `intent.primary_domain` 为单一域且无 `secondary_domains` 时：
- 直接生成1条 `delivery_instructions`，路由到对应域技能
- `task_plan.execution_mode = "single"`
- `task_plan.steps` 仅含1个步骤

#### 串联模式（sequential）

当识别为复合请求时：
- 按依赖关系生成有序步骤链
- 前序步骤的输出作为后序步骤的输入
- `task_plan.execution_mode = "sequential"`
- 每步 `depends_on` 指向前序步骤ID
- **执行策略**：逐步执行，前序完成后将输出注入后序的 `parameters`

#### 并行模式（parallel）

当复合请求中存在无依赖关系的步骤时：
- 如"架构设计 + 原型设计"（两者都依赖PRD但互不依赖）
- `task_plan.execution_mode = "parallel"`
- 无依赖的步骤 `depends_on` 相同（都指向PRD步骤）
- **执行策略**：PRD完成后，架构和原型可并行生成

#### 依赖关系矩阵

| 下游技能 | 依赖上游 | 依赖字段 |
|---------|---------|---------|
| 架构设计 | PRD | `prd_content` ← PRD输出文件内容 |
| 原型 | PRD（页面设计章节） | `core_content` / `page_topic` ← PRD第8章 |
| 拆分 | PRD（功能列表章节） | `requirement_content` ← PRD全文 |
| 架构 ← → 原型 | 无直接依赖 | 可并行 |

### 0.9 质量检查清单

- [ ] `intent.primary_domain` 是否准确匹配用户意图
- [ ] `intent_confidence` 是否合理（≥0.5）
- [ ] `task_plan.steps` 的依赖关系是否正确（无循环依赖）
- [ ] `context_summary.requirement_text` 是否已去除口语化、补全隐含信息
- [ ] `context_summary.key_entities` 是否提取了所有功能模块和用户角色
- [ ] `context_summary.design_hints` 是否在路由含原型时已预提取
- [ ] `missing_info` 中的阻断项是否已识别
- [ ] `delivery_instructions` 的 `parameters` 是否已用 `context_summary` 预填
- [ ] 复合请求的串联顺序是否符合依赖矩阵

### 0.10 输出示例

#### 示例1：单步请求

**用户输入**："帮我写一个在线商城的PRD"

**输出**：
```json
{
  "meta": {
    "request_id": "req-001",
    "timestamp": "2026-09-22T10:00:00",
    "user_input_raw": "帮我写一个在线商城的PRD",
    "intent_confidence": 0.95
  },
  "intent": {
    "primary_domain": "prd",
    "secondary_domains": [],
    "action_type": "create",
    "description": "用户要求生成在线商城的PRD文档"
  },
  "task_plan": {
    "execution_mode": "single",
    "steps": [
      {
        "step_id": 1,
        "skill": "srdcloud-prd-distilled",
        "skill_label": "PRD生成",
        "depends_on": [],
        "status": "ready"
      }
    ]
  },
  "context_summary": {
    "project_name": "在线商城",
    "requirement_text": "在线商城系统，支持商品浏览、购物车、订单管理、支付等功能",
    "key_entities": ["在线商城", "商品浏览", "购物车", "订单管理", "支付"],
    "tech_constraints": null,
    "design_hints": null,
    "team_info": null,
    "sprint_info": null
  },
  "missing_info": [
    {
      "field": "tech_constraints",
      "reason": "用户未提及技术栈要求",
      "question": "是否有技术栈要求？如指定框架/数据库",
      "is_blocking": false,
      "default_value": null
    }
  ],
  "delivery_instructions": [
    {
      "target_skill": "srdcloud-prd-distilled",
      "parameters": {
        "requirement_text": "在线商城系统，支持商品浏览、购物车、订单管理、支付等功能",
        "project_name": "在线商城"
      }
    }
  ]
}
```

#### 示例2：复合请求（串联模式）

**用户输入**："帮我做一个客户跟进提醒功能，要PRD、技术方案和原型"

**输出**：
```json
{
  "meta": {
    "request_id": "req-002",
    "timestamp": "2026-09-22T10:05:00",
    "user_input_raw": "帮我做一个客户跟进提醒功能，要PRD、技术方案和原型",
    "intent_confidence": 0.9
  },
  "intent": {
    "primary_domain": "multi_step",
    "secondary_domains": ["prd", "architecture", "prototype"],
    "action_type": "create",
    "description": "用户要求完整的产品设计流程：PRD→架构设计→HTML原型"
  },
  "task_plan": {
    "execution_mode": "sequential",
    "steps": [
      {
        "step_id": 1,
        "skill": "srdcloud-prd-distilled",
        "skill_label": "PRD生成",
        "depends_on": [],
        "status": "ready"
      },
      {
        "step_id": 2,
        "skill": "architecture-design-doc-distilled",
        "skill_label": "架构设计文档",
        "depends_on": [1],
        "status": "blocked"
      },
      {
        "step_id": 3,
        "skill": "design-proto-distilled",
        "skill_label": "HTML原型",
        "depends_on": [1],
        "status": "blocked"
      }
    ]
  },
  "context_summary": {
    "project_name": "客户跟进提醒",
    "requirement_text": "客户跟进提醒功能，支持设置跟进提醒时间、多渠道消息推送（企微/站内）、逾期升级提醒、主管逾期客户看板",
    "key_entities": ["客户跟进", "提醒设置", "消息推送", "企微通知", "站内消息", "逾期升级", "主管看板"],
    "tech_constraints": null,
    "design_hints": {
      "design_system": "Ant",
      "platform": "桌面Web",
      "page_type": "dashboard"
    },
    "team_info": null,
    "sprint_info": null
  },
  "missing_info": [
    {
      "field": "page_topic",
      "reason": "原型页面主题需确认",
      "question": "原型的页面主题是什么？如'客户管理后台'或'跟进提醒看板'",
      "is_blocking": true,
      "default_value": null
    }
  ],
  "delivery_instructions": [
    {
      "target_skill": "srdcloud-prd-distilled",
      "parameters": {
        "requirement_text": "客户跟进提醒功能，支持设置跟进提醒时间、多渠道消息推送（企微/站内）、逾期升级提醒、主管逾期客户看板",
        "project_name": "客户跟进提醒"
      }
    }
  ]
}
```

> **注意**：步骤2和步骤3的 `delivery_instructions` 在步骤1完成后动态生成，将PRD输出内容注入为 `prd_content` 参数。

#### 示例3：并行模式

**用户输入**："根据这个PRD同时出技术方案和原型"

**输出**：
```json
{
  "meta": {
    "request_id": "req-003",
    "timestamp": "2026-09-22T10:10:00",
    "user_input_raw": "根据这个PRD同时出技术方案和原型",
    "intent_confidence": 0.85
  },
  "intent": {
    "primary_domain": "multi_step",
    "secondary_domains": ["architecture", "prototype"],
    "action_type": "create",
    "description": "用户已有PRD，要求并行生成架构设计文档和HTML原型"
  },
  "task_plan": {
    "execution_mode": "parallel",
    "steps": [
      {
        "step_id": 1,
        "skill": "architecture-design-doc-distilled",
        "skill_label": "架构设计文档",
        "depends_on": [],
        "status": "ready"
      },
      {
        "step_id": 2,
        "skill": "design-proto-distilled",
        "skill_label": "HTML原型",
        "depends_on": [],
        "status": "ready"
      }
    ]
  },
  "context_summary": {
    "project_name": "[从对话历史提取]",
    "requirement_text": "[从对话历史提取PRD内容]",
    "key_entities": [],
    "tech_constraints": null,
    "design_hints": {
      "design_system": "Ant",
      "platform": "桌面Web",
      "page_type": "dashboard"
    },
    "team_info": null,
    "sprint_info": null
  },
  "missing_info": [],
  "delivery_instructions": [
    {
      "target_skill": "architecture-design-doc-distilled",
      "parameters": {
        "prd_content": "{从对话历史提取的PRD全文}",
        "project_name": "{从对话历史提取}"
      }
    },
    {
      "target_skill": "design-proto-distilled",
      "parameters": {
        "design_system": "Ant",
        "platform": "桌面Web",
        "page_type": "dashboard",
        "page_topic": "{从PRD第8章提取}",
        "core_content": "{从PRD提取核心功能描述}"
      }
    }
  ]
}
```

### 0.11 交付给研发云数字员工的总指令

总控技能本身不直接交付文件给研发云数字员工，而是将 `delivery_instructions` 分发给下游域技能执行。下游域技能完成后，各自按其交付指令（见技能1-4的对应章节）与研发云数字员工协同。

当所有步骤完成后，总控技能可生成一份**执行摘要**：

```json
{
  "execution_summary": {
    "request_id": "req-002",
    "total_steps": 3,
    "completed_steps": 3,
    "artifacts": [
      {
        "step_id": 1,
        "skill": "srdcloud-prd-distilled",
        "artifact_path": "PRD-客户跟进提醒.md",
        "delivery_action": "upload_to_doc_space"
      },
      {
        "step_id": 2,
        "skill": "architecture-design-doc-distilled",
        "artifact_path": "tech-spec-客户跟进提醒.md",
        "delivery_action": "upload_to_doc_space"
      },
      {
        "step_id": 3,
        "skill": "design-proto-distilled",
        "artifact_path": "客户管理后台-proto.html",
        "delivery_action": "save_to_design_center"
      }
    ],
    "next_step_suggestion": "可继续调用工作项拆分建议技能，将PRD转化为工作项"
  }
}
```

---

## 技能 1：PRD 生成（srdcloud-prd-distilled）

### 1.1 职责

将用户需求描述（自然语言/问需单内容/附件摘要）转化为**结构化产品需求文档（PRD）**，产出为 Markdown 文件，交付给研发云数字员工上传文档空间或关联到工作项。

### 1.2 输入

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `requirement_text` | String | 是 | 用户原始需求描述或问需单内容摘要 |
| `project_name` | String | 否 | 项目名称，用于文档命名 `PRD-{项目名称}.md` |
| `template_override` | String | 否 | 用户自定义模板要求（章节结构/格式约束） |
| `reference_docs` | String[] | 否 | 参考文档内容（已有PRD、竞品分析等） |
| `existing_workitems` | String | 否 | 已有工作项摘要（用于增量PRD场景） |

### 1.3 输出（中间产物）

**文件**：`PRD-{项目名称}.md`（Markdown 格式）

**标准模板结构**（9 章，用户无自定义要求时使用）：

```markdown
## 1. 功能名
[功能名称]

## 2. 需求描述
核心需求的简要描述，确保开发团队快速理解总体目标。

## 3. 项目概述
**项目背景**: 简述项目背景和启动原因。
**目标用户**: 描述主要用户群体及其特征。
**业务目标**: 明确项目旨在解决的问题或达成的目标。
**关键指标(KPIs)**: 定义衡量项目成功的KPI。

## 4. 用户旅程
**触发点** → **第一步** → **第二步** → ... → **结束点**

### 流程图（Mermaid graph TD 格式）
- 判断节点用菱形，流程节点用矩形
- 标注每步执行角色和核心操作
- 正确使用 Mermaid 语法，不生成中文标点

## 5. 功能列表
列出所有功能模块名称。

## 6. 功能详细描述
每个功能包含：详细描述、实现逻辑、输入、输出。

## 7. 页面列表
列出所有页面名称。

## 8. 页面详细设计
每个页面包含：布局、元素、交互、边界条件、错误处理。

### 页面结构图（markmap 格式）
- 层级：# 主模块 → ## 页面 → ### 功能区域 → #### 控件/操作 → ##### 规则/反馈
- 覆盖控件输入规则、默认文案、交互动作、成功/失败反馈
- 节点命名 ≤12 字

## 9. 统计需求
### 用户行为统计（埋点表）
| 序号 | 埋点名称 | 含义 | key值 | 参数 | 备注 |

### 统计指标
| 序号 | 统计指标名称 | 定义/公式 | 数据来源 | 目的/用途 | 备注 |
```

### 1.4 生成规则

1. **需求不清晰时仅追问一次**关键信息，若仍不清晰则按现有信息生成并标注不确定部分
2. **一次写入**产物文件，不分两步操作
3. **严格按模板结构**填充，保持核心章节完整性
4. 流程图必须使用 `mermaid graph TD` 语法，页面结构图必须使用 `markmap` 语法
5. 所有内容必须**真实可执行**，禁止填充文案（lorem ipsum / "feature one"）
6. 验收标准必须**可量化**（能明确判断通过/不通过）

### 1.5 质量检查清单

- [ ] 9 个章节是否完整（功能名/需求描述/项目概述/用户旅程/功能列表/功能详细描述/页面列表/页面详细设计/统计需求）
- [ ] 流程图是否使用正确的 Mermaid graph TD 语法
- [ ] 页面结构图是否使用正确的 markmap 语法，层级覆盖到控件级
- [ ] 每个功能是否有输入/输出/实现逻辑
- [ ] 每个页面是否有布局/元素/交互/边界条件/错误处理
- [ ] 统计需求是否包含埋点表和统计指标表
- [ ] 是否无填充文案、无编造数据
- [ ] 文件名是否为 `PRD-{项目名称}.md`

### 1.6 交付给研发云数字员工的指令

```json
{
  "skill": "prd-upload",
  "artifact_path": "PRD-{项目名称}.md",
  "action": "upload_to_doc_space",
  "doc_title": "PRD-{项目名称}",
  "next_step_hint": "上传文档空间后，可关联到工作项或用于后续架构设计"
}
```

---

## 技能 2：架构设计文档生成（architecture-design-doc-distilled）

### 2.1 职责

将 PRD 或需求设计文档转化为**可据以实现的技术规约（架构设计文档）**，产出为 Markdown 文件。这是从需求到实现的桥梁——规约一旦冻结，就是开发的唯一依据。

### 2.2 输入

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `prd_content` | String | 是 | PRD 文档内容（来自技能1的输出或用户提供） |
| `tech_constraints` | String | 否 | 技术约束（指定框架/数据库/部署环境等） |
| `existing_architecture` | String | 否 | 已有架构描述（增量设计场景） |
| `project_name` | String | 否 | 项目名称，用于文档命名 |

### 2.3 输出（中间产物）

**文件**：`tech-spec-{项目名称}.md`（Markdown 格式）

**标准模板结构**（5 章 + 修订历史）：

```markdown
# 技术规约

> 状态：📝 草案 | 🧊 已冻结
> 版本：v1.0
> 冻结日期：（冻结后填写）

## 1. 架构设计
- **整体架构**：（前后端分离 / 单体 / 微服务）+ 架构图（Mermaid）
- **技术选型**：
  - 框架：___（理由：）
  - 数据库：___（理由：）
  - 关键库：___（理由：）
- **部署架构**：（如相关）

### 架构图（Mermaid）
使用 graph TD 或 graph LR，标注组件间依赖关系和数据流向。

## 2. 模块拆分
| 模块 | 职责 | 依赖 |
|------|------|------|

### 模块依赖图（Mermaid）
使用 graph TD 展示模块间依赖。

## 3. 接口契约（最关键）
每个对外接口必须定义：

### 接口：{接口名}
- **方法/路径**：`POST /api/xxx`
- **输入**：
  ```json
  { "field": "type" }
  ```
- **输出（成功）**：
  ```json
  { "field": "type" }
  ```
- **输出（失败）**：
  ```json
  { "error": "string", "code": "number" }
  ```
- **错误码**：400 参数错误 / 401 认证失败 / 429 限流

## 4. 数据模型
### 实体：{实体名}
| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|

### ER 图（Mermaid erDiagram）
展示实体间关系。

## 5. 验收标准
对应 PRD 的每个功能，写可验证的验收点：

### 功能：{功能名}
- [ ] 验收点 1：___
- [ ] 验收点 2：___

---

## 修订历史
| 版本 | 日期 | 变更内容 | 原因 |
|------|------|---------|------|
```

### 2.4 生成规则

1. **仔细阅读 PRD**，理解每个功能的意图、非功能需求、范围边界。不清楚的地方在文档中标注 `[待确认]`
2. **架构设计要具体**：明确整体架构类型、技术选型理由、部署方案
3. **接口契约是硬约束**：字段名、类型、错误码都要明确，实现时不得偏离
4. **验收标准要可验证**：每条都能明确判断"通过"或"不通过"
5. **技术选型要说明理由**——为什么选这个、不选那个
6. 如果 PRD 涉及 UI，规约里应包含前端组件/页面的结构定义
7. 架构图、模块依赖图、ER 图必须使用 Mermaid 语法
8. **规约要具体到可实现、可验收**——模糊的规约（如"提供良好的用户体验"）无法接受

### 2.5 质量检查清单

- [ ] 架构设计是否明确整体架构类型 + 技术选型理由
- [ ] 架构图是否使用正确的 Mermaid 语法
- [ ] 模块拆分表是否完整（模块/职责/依赖三列）
- [ ] 每个接口是否包含：方法/路径、输入、输出（成功/失败）、错误码
- [ ] 数据模型是否包含：字段、类型、约束、说明
- [ ] ER 图是否使用正确的 Mermaid erDiagram 语法
- [ ] 验收标准是否对应 PRD 中的每个功能，且每条可验证
- [ ] 是否无模糊描述（"良好的用户体验"等不可验收的描述）
- [ ] 文件名是否为 `tech-spec-{项目名称}.md`

### 2.6 交付给研发云数字员工的指令

```json
{
  "skill": "tech-spec-upload",
  "artifact_path": "tech-spec-{项目名称}.md",
  "action": "upload_to_doc_space",
  "doc_title": "技术规约-{项目名称}",
  "next_step_hint": "上传后可关联到版本或工作项，作为开发依据"
}
```

---

## 技能 3：HTML 原型生成（design-proto-distilled）

### 3.1 职责

根据设计简报，生成**生产级自包含 HTML 原型文件**。这是外部 Coding Agent 价值最高的技能——直接产出可运行的 HTML 文件，交付给研发云数字员工保存到设计中心。

### 3.2 输入（设计简报 Design Brief）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `design_system` | String | 是 | 设计体系（9选1，见下方速查表） |
| `platform` | String | 是 | 目标平台（6选1，见下方速查表） |
| `page_type` | String | 是 | 页面类型（13种子技能或通用前端） |
| `page_topic` | String | 是 | 页面主题（如"AI产品发布会""客户管理后台"） |
| `target_audience` | String | 否 | 目标受众（如"技术开发者""销售团队"） |
| `core_content` | String | 是 | 核心内容摘要（1-2句话描述页面主要内容） |
| `component_library` | String | 否 | 组件库（element-plus / shadcn，不传则不启用） |
| `multi_view` | Boolean | 否 | 是否多视图（≥2个功能模块时为true） |

### 3.3 设计体系速查表（9套）

| 编号 | 名称 | 主色调 | 适用场景 | 关键词 |
|------|------|--------|---------|--------|
| 1 | Neutral Modern | 浅蓝 | 通用极简、B2B、仪表盘 | 简约/现代/清爽 |
| 2 | Claude | 暖棕 | 文档、博客、内容型 | 中文/博客/温暖 |
| 3 | ElevenLabs | 青蓝 | 音频、轻量化 | 音频/语音/优雅 |
| 4 | Hugging Face | 暖黄 | 开发者工具、ML | ML/开源/模型 |
| 5 | MiniMax | 淡紫 | 数字人、多模态 | 海螺/视频/中国AI |
| 6 | Runway | 亮蓝 | 创意AIGC、影视 | 电影/创意/影视 |
| 7 | OpenAI | 极简白 | AI研究、极简科技 | AI/OpenAI/研究 |
| 8 | Ant | 商务蓝 | 政企金融、后台 | 后台/数据/企业 |
| 9 | Colorful | 灼橙 | 多彩创意 | 多彩/活泼/创意 |

> 默认值：Neutral Modern

### 3.4 平台速查表（6种）

| 编号 | 名称 | 关键词 | 默认设计体系联动 |
|------|------|--------|-----------------|
| 1 | 响应式Web | 分享/多端/落地页/网页 | Neutral Modern |
| 2 | 桌面Web | 桌面/后台/大屏 | Ant |
| 3 | iOS应用 | iPhone/iOS | Neutral Modern |
| 4 | Android应用 | Android | Neutral Modern |
| 5 | 平板应用 | iPad/平板 | Neutral Modern |
| 6 | 桌面应用 | Electron/客户端 | Neutral Modern |

> 默认值：响应式Web

### 3.5 页面类型速查表（13种子技能 + 通用前端）

| 关键词 | 页面类型 | 推荐设计体系 | 推荐平台 |
|--------|---------|-------------|---------|
| FAQ/常见问题/帮助中心 | faq-page | OpenAI | 响应式Web |
| 登录/注册/sign in | login-flow | Neutral Modern | 响应式Web |
| 简历/CV/求职 | resume-modern | Claude | 响应式Web |
| 文章/博客/长文 | article-magazine | Claude | 响应式Web |
| 数据报告/可视化/周报 | data-report | Ant | 桌面Web |
| 管理后台/控制台/仪表盘 | dashboard | Ant | 桌面Web |
| SaaS/落地页/产品页 | saas-landing | OpenAI | 响应式Web |
| 定价/套餐/pricing | pricing-page | Neutral Modern | 响应式Web |
| 邮件/newsletter | email-marketing | MiniMax | 响应式Web |
| 海报/朋友圈/分享图 | poster-hero | Runway | 桌面Web |
| 看板/kanban/task board | kanban-board | Ant | 桌面Web |
| 发票/invoice/账单 | invoice | Neutral Modern | 响应式Web |
| 文档/docs/guide/tutorial | docs-page | OpenAI | 桌面Web |
| 原型/prototype/demo/页面 | 通用前端 | 按关键词推断 | 按关键词推断 |

### 3.6 输出（中间产物）

**文件**：`{page_topic}-proto.html`（单个自包含 HTML 文件）

**产物必须满足**：
1. **自包含**：所有 CSS 和 JS 内联在单个 HTML 文件中，不引入任何 CDN/外部脚本
2. **可直接运行**：保存为 .html 文件后双击即可在浏览器中打开
3. **语义化**：使用 HTML5 语义化标签
4. **可访问**：键盘可达、ARIA 属性正确、对比度达标
5. **无占位符泄漏**：所有内容都是真实的、与简报相关的文本

### 3.7 代码合成规则（铁律）

#### 设计令牌注入
- 将设计体系的 `tokens.css` 中的 `:root { ... }` 块整体注入 HTML `<style>` 首段
- **全文通过 `var(--xxx)` 引用颜色和字体，禁止 `:root` 之外出现裸 hex 值**
- Chart.js 例外：canvas 渲染不解析 CSS var()，通过辅助函数读取令牌

#### 平台约束注入
- Viewport 写入 `<meta name="viewport">`
- 断点写入媒体查询
- 设备框架包裹（iOS/Android/平板/桌面应用）
- 触摸目标 ≥44px（iOS）/ 48dp（Android）

#### 页面内容注入
- 遵循页面技能定义的区块顺序，不跳过不重排
- 使用语义化 HTML 标签
- 所有图片使用内联 SVG 或 CSS 占位（禁止外部占位图 CDN）
- 所有链接为 `#`，无真实路由

#### 多视图导航（≥2个功能模块时触发）
- 收敛为**单个自包含 HTML 文件**，不拆分多个 HTML
- 使用 `data-view-link` 属性实现视图切换（show/hide）
- 登录页作为首个独立视图（无导航栏），登录按钮触发切换到主应用视图
- 移动端 App（iOS/Android/平板）含 ≥2 功能区块时**强制**启用底部 tab 多视图导航

#### 动作按钮交互（三种标准处置，必选其一）
1. **打开弹窗** → `data-open-dialog` 属性
2. **就地反馈** → toast/状态切换
3. **显式 inert** → `aria-disabled="true"` 标注

#### 分段控件（视图内筛选/切换）
- `data-seg` 属性 + `data-seg-mode`（panel/filter）
- 点击必须产生可见变化，禁止装饰性死控件

### 3.8 工艺自检清单（P0 硬门控）

生成代码后，逐项内部验证（不输出自检过程）：

1. `:root` 之外是否无裸 hex 值（全部经 `var(--xxx)` 引用）？
2. 标题是否用 `var(--font-display)`、正文是否用 `var(--font-body)`？
3. 强调色每屏是否 ≤2 处？
4. 是否无紫蓝渐变、无 Tailwind indigo 默认色、无 emoji 当功能图标？
5. 是否无填充文案（lorem ipsum / "feature one" / "your text here"）？
6. 是否无编造数据（"10× faster" 无来源就删）？
7. hover / focus / active 三态是否完整？
8. 移动端栅格是否折叠正常、无横向溢出？
9. `<!doctype html>` 是否恰好出现一次、`<html>` 根元素是否恰好一个？
10. 动作按钮是否非死钮（接弹窗/就地反馈/显式inert）？
11. 弹窗是否默认隐藏（`.modal { display: none }`）？
12. 分段控件点击是否产生可见变化？

### 3.9 2秒直觉检查

看页面2秒，自评：是否像"这月见的每个AI创业公司首页"？是否"无辨识度落地页"？是否"特性行=图标+标题+三行模糊利益文案"？若任一命中，回去把一格换成更具体内容，删一个强调色。

### 3.10 交付给研发云数字员工的指令

```json
{
  "skill": "proto-save",
  "artifact_path": "{page_topic}-proto.html",
  "action": "save_to_design_center",
  "design_system": "Neutral Modern",
  "platform": "响应式Web",
  "page_type": "dashboard",
  "next_step_hint": "保存到设计中心后，可关联到PRD或工作项"
}
```

---

## 技能 4：工作项拆分建议（workitem-split-advisor-distilled）

### 4.1 职责

将需求内容（PRD/问需单/自然语言描述）转化为**工作项拆分建议表**，包含特性→用户故事→任务的完整父子关系树、优先级、工作量估算。**不实际创建工作项**——只生成结构化建议，交付给研发云数字员工执行批量创建。

### 4.2 输入

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `requirement_content` | String | 是 | 需求内容（PRD全文/问需单内容/自然语言描述） |
| `split_to_task` | Boolean | 否 | 是否拆分到任务级（默认true，false则只到用户故事级） |
| `team_members` | String[] | 否 | 团队成员列表（用于处理人建议） |
| `sprint_info` | String | 否 | 迭代信息（名称/时间范围/剩余容量，用于迭代规划建议） |

### 4.3 输出（中间产物）

**文件**：`workitem-split-suggestion-{日期}.md`（Markdown 格式）

**输出结构**：

```markdown
# 工作项拆分建议

> 生成时间：{日期}
> 需求来源：{PRD/问需单/直接描述}
> 总工作量估算：{X}人天（{Y}工时）

## 一、拆分概览

| 维度 | 数量 |
|------|------|
| 特性 | {N}个 |
| 用户故事 | {N}个 |
| 任务 | {N}个 |
| 总工作量 | {X}人天 |

## 二、父子关系树

### 🔶 [特性] {特性标题} [优先级：高/中/低]

**描述**：{特性描述}
**验收条件**：{可量化的验收条件}
**预估工时**：{人天×8}工时

#### 🟢 [用户故事] {故事标题} [优先级：高/中/低]

**用户故事**：作为{角色}，我希望{功能描述}，以便{业务价值}
**验收条件**：{可量化的验收条件}
**预估工时**：{人天×8}工时

##### 🔴 [任务] {任务标题} [优先级：高/中/低]

**任务描述**：{任务详细描述}
**任务类型**：前端/后端/测试/文档
**预估工时**：{人天×8}工时
**处理人建议**：{团队成员名或"待分配"}

（重复上述结构...）

## 三、统计

### 优先级分布
| 优先级 | 特性 | 用户故事 | 任务 | 合计 |
|--------|------|---------|------|------|
| 高 | | | | |
| 中 | | | | |
| 低 | | | | |

### 工作量分布
| 模块 | 用户故事数 | 任务数 | 工作量(人天) |
|------|-----------|--------|-------------|

### 迭代规划建议（可选）
**建议迭代**：{迭代名称}（{时间范围}）
**匹配理由**：{总工作量X人天，迭代剩余容量Y人天，匹配/不匹配}
```

### 4.4 拆分规则

#### 特性拆分
- 按需求中的**功能模块**拆分，每个功能模块生成一个「特性」
- 特性描述基于需求内容自动生成
- 特性验收条件基于需求分析自动生成

#### 用户故事拆分
- 每个特性下的功能点拆分为「用户故事」
- 遵循 **INVEST 原则**（Independent、Negotiable、Valuable、Estimable、Small、Testable）
- 格式：「作为{角色}，我希望{功能描述}，以便{业务价值}」
- 优先级基于 RICE 模型（Reach × Impact × Confidence / Effort）
- 工作量估算：默认 1-3 人天/故事

#### 任务拆分（split_to_task=true 时）
- 每个用户故事拆分为 **2-5 个任务**
- 任务粒度：每个任务 ≤1 人天，可独立完成
- 任务类型识别：
  - **前端任务**：涉及UI/交互
  - **后端任务**：涉及接口/数据处理
  - **测试任务**：涉及验证/测试
  - **文档任务**：涉及文档编写
- 任务命名按开发流程：接口设计、前端实现、数据层、联调测试等
- 优先级继承父用户故事，有依赖关系的被依赖任务提高一级
- **工作量分配**：任务工作量之和 = 用户故事工作量，每个任务默认 0.5-1 人天

#### 工时换算
- **人天转工时**：预估工时 = 工作量（人天）× 8（小时/天）
- 例如：2人天 = 16工时，0.5人天 = 4工时

#### 迭代规划建议（sprint_info 提供时）
- 汇总所有工作项总工作量（人天）
- 工作日估算：≤5人天→约5工作日，5-10→约10，10-20→约15，>20→约20
- 匹配逻辑：优先当前进行中迭代，其次最近未开始迭代
- 若未找到合适迭代：提示"未找到合适的迭代，建议手动规划"

### 4.5 质量检查清单

- [ ] 每个用户故事是否遵循 INVEST 原则
- [ ] 用户故事格式是否为"作为{角色}，我希望{功能}，以便{价值}"
- [ ] 每个任务是否 ≤1 人天
- [ ] 任务工作量之和是否 = 父用户故事工作量
- [ ] 父子关系树是否完整（特性→用户故事→任务）
- [ ] 优先级是否基于 RICE 模型
- [ ] 预估工时是否 = 人天 × 8
- [ ] 验收条件是否可量化
- [ ] 统计表是否完整（优先级分布/工作量分布）
- [ ] 是否标注"工作量为预估值，建议人工复核"

### 4.6 交付给研发云数字员工的指令

```json
{
  "skill": "workitem-batch-create",
  "artifact_path": "workitem-split-suggestion-{日期}.md",
  "action": "batch_create_workitems",
  "project_id": "{项目ID}",
  "iteration_id": "{迭代ID或null}",
  "split_to_task": true,
  "next_step_hint": "按建议表批量创建工作项，建立父子关系，指派处理人"
}
```

---

## 附录A：5 技能串联流程（含总控）

```
用户原始输入
   │
   ▼
┌──────────────────────────────────────────────────────────┐
│  技能0: 意图路由与任务规划（总控）                           │
│  · 意图识别 → 域路由 → 任务拆解                             │
│  · 上下文压缩 → 参数预填 → 缺失检测                         │
│  · 输出: 标准化任务指令(JSON)                               │
│  · 缺失阻断项 → 一次性追问用户                              │
└──────────┬───────────────────────────────────────────────┘
           │ 任务指令分发
           │
     ┌─────┼─────┬──────────┐
     │     │     │          │
     ▼     ▼     ▼          ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│技能1   │ │技能2   │ │技能3   │ │技能4   │
│PRD生成 │ │架构设计 │ │HTML原型│ │工作项  │
│        │ │文档    │ │        │ │拆分建议│
└───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
    │          │          │          │
    ▼          ▼          ▼          ▼
  PRD.md    tech-spec  proto.html  split.md
    │          │          │          │
    └──────────┴──────────┴──────────┘
               │
               ▼
    研发云数字员工（在线执行层）
    · 上传文档空间(PRD/架构)
    · 保存设计中心(原型)
    · 批量创建工作项(拆分建议)
```

### 串联执行示例（复合请求）

```
用户: "帮我做一个客户跟进提醒功能，要PRD、技术方案和原型"
                    │
                    ▼
         [技能0: 总控]
         意图: multi_step
         串联: PRD → 架构(并行) + 原型(并行)
         缺失: page_topic(阻断) → 追问用户
                    │
          用户回复: "客户管理后台"
                    │
                    ▼
         [技能1: PRD生成]
         输出: PRD-客户跟进提醒.md
         交付: → 研发云上传文档空间
                    │
           ┌────────┴────────┐
           ▼                 ▼
    [技能2: 架构设计]   [技能3: HTML原型]
    输入: PRD内容        输入: 设计简报(预填)
    输出: tech-spec.md   输出: proto.html
    交付: → 上传文档空间  交付: → 保存设计中心
           │                 │
           └────────┬────────┘
                    ▼
         [可选: 技能4 工作项拆分]
         输入: PRD内容
         输出: split-suggestion.md
         交付: → 研发云批量创建工作项
```


---

## 附录B：各技能输入输出速查表

| 技能 | 输入 | 输出文件 | 交付动作 |
|------|------|---------|---------|
| 意图路由与任务规划（总控） | 用户原始话术+对话历史+附件 | 标准化任务指令(JSON) | 分发给下游域技能 |
| PRD生成 | 需求描述/问需单内容 | `PRD-{项目名}.md` | 上传文档空间 |
| 架构设计文档 | PRD内容+技术约束 | `tech-spec-{项目名}.md` | 上传文档空间 |
| HTML原型 | 设计简报(9体系×6平台×13页面类型) | `{主题}-proto.html` | 保存设计中心 |
| 工作项拆分建议 | PRD内容+团队成员+迭代信息 | `workitem-split-suggestion-{日期}.md` | 批量创建工作项 |

## 附录C：设计体系 × 平台 × 页面类型 联动推荐

当用户未明确指定设计体系或平台时，按页面类型自动联动推荐：

| 页面类型 | 推荐设计体系 | 备选 | 推荐平台 |
|---------|-------------|------|---------|
| resume-modern | Claude | Neutral Modern | 响应式Web |
| article-magazine | Claude | OpenAI | 响应式Web |
| docs-page | OpenAI | Hugging Face/Claude | 桌面Web |
| dashboard | Ant | Neutral Modern | 桌面Web |
| data-report | Ant | Neutral Modern | 桌面Web |
| saas-landing | OpenAI | Neutral Modern/MiniMax | 响应式Web |
| pricing-page | Neutral Modern | OpenAI | 响应式Web |
| login-flow | Neutral Modern | ElevenLabs | 响应式Web |
| faq-page | OpenAI | Claude/Neutral Modern | 响应式Web |
| email-marketing | MiniMax | Neutral Modern/ElevenLabs | 响应式Web |
| poster-hero | Runway | MiniMax/Claude | 桌面Web |
| kanban-board | Ant | Neutral Modern | 桌面Web |
| invoice | Neutral Modern | Claude | 响应式Web |
| 通用前端 | 按关键词推断 | Neutral Modern(默认) | 按关键词推断 |

> 联动推荐与用户明确指定的设计体系/平台冲突时，**优先用户指定值**。

## 附录D：总控路由决策树

```
用户输入
   │
   ▼
是否含"PRD/需求文档"关键词？
   ├─ 是 → 是否已有PRD？
   │       ├─ 是 → action=modify → 路由: srdcloud-prd-distilled
   │       └─ 否 → action=create → 路由: srdcloud-prd-distilled
   │
   否 → 是否含"架构/技术方案/接口设计"关键词？
   │       ├─ 是 → 是否已有架构文档？
   │       │       ├─ 是 → action=modify → 路由: architecture-design-doc-distilled
   │       │       └─ 否 → action=create → 路由: architecture-design-doc-distilled
   │       │
   │       否 → 是否含"原型/页面/demo/UI/HTML"关键词？
   │               ├─ 是 → 是否已有原型？
   │               │       ├─ 是 → action=modify → 路由: design-proto-distilled
   │               │       └─ 否 → action=create → 路由: design-proto-distilled
   │               │
   │               否 → 是否含"拆分/任务/工作项/排期"关键词？
   │                       ├─ 是 → 路由: workitem-split-advisor-distilled
   │                       │
   │                       否 → 是否含"做个功能/帮我实现"？
   │                               ├─ 是 → multi_step
   │                               │       检测已有产物 → 确定串联链
   │                               │       缺失检测 → 追问
   │                               │       生成 task_plan
   │                               │
   │                               否 → 置信度 < 0.5
   │                                       追问用户一次
   │                                       提供选项: PRD/架构/原型/拆分
```

## 附录E：关键设计原则

1. **总控技能必须独立**：路由逻辑不混入域技能，避免"偷懒"直接跳转丢失分析价值
2. **5 个技能可独立调用也可串联**：总控负责编排，域技能可被总控调度也可直接调用
3. **每个域技能产出标准化文件**（.md 或 .html），研发云数字员工可稳定消费
4. **每个域技能附带 JSON 指令**，告诉研发云数字员工下一步动作
5. **外部 Agent 不访问研发云**，只生成中间产物；研发云数字员工负责在线落地
6. **上下文压缩是总控核心价值**：把长对话/多文档压缩成结构化摘要，降低下游 token 消耗
7. **缺失信息一次性追问**：总控检测所有缺失项，合并为一次提问，不分多次打断
8. **设计简报预提取**：总控在路由含原型时自动预提取设计参数，下游无需再次推断