wx44wx/2026-heima-agent-setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e411afe9c8da093355da58f2e86de77519a953d
2026-heima-agent-setup/docs/external-agent-skill-specs_v2.md
T

46 KiB
Raw Blame History

外部 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）

{
  "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"

输出：

{
  "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、技术方案和原型"

输出：

{
  "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同时出技术方案和原型"

输出：

{
  "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的对应章节）与研发云数字员工协同。

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

{
  "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 章，用户无自定义要求时使用）：

## 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 交付给研发云数字员工的指令

{
  "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 章 + 修订历史）：

# 技术规约

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

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

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

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

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

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

### 接口：{接口名}
- **方法/路径**：`POST /api/xxx`
- **输入**：
  ```json
  { "field": "type" }
  • 输出（成功）： 
    { "field": "type" }
  • 输出（失败）： 
    { "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 交付给研发云数字员工的指令

{
  "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 格式）

输出结构：

# 工作项拆分建议

> 生成时间：{日期}
> 需求来源：{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 交付给研发云数字员工的指令

{
  "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. 设计简报预提取：总控在路由含原型时自动预提取设计参数，下游无需再次推断
Reference in New Issue View Git Blame Copy Permalink