wx44wx/2026-heima-agent-setup

Files

T

Eric Wang 6e411afe9c init: 2026黑马复赛 agents-setup 初始提交

2026-09-23 09:02:54 +08:00

37 KiB

Raw Permalink Blame History

外部 Coding Agent 技能规范（研发云协同 · 算力分级分流）

架构定位：强模型（TeleAgent）离线生成高质量中间产物 → 弱模型（研发云数字员工）只做机械提交。

核心原则：弱模型的工作量降到最低——读一个清单 + 执行一个动作，不做语义理解、不做数据解析、不做 API 编排。

共 4 个域技能 + 1 套交接协议。技能0（总控路由）不作为独立技能加载，其路由表/决策树/缺失检测规则作为 TeleAgent Agent 核心的 prompt 参考（见附录D）。

交接协议（Handoff Protocol）—— 弱模型执行层规范

这是整个架构的关键层。TeleAgent 产出中间产物后，通过一个极简清单文件 .handoff.json 告诉弱模型"做什么动作、对哪个文件、用什么参数"。弱模型只读清单、逐条执行，不做任何语义理解。

H.1 交接清单格式（`.handoff.json`）

TeleAgent 每次完成产物生成后，在产物目录下生成一个 .handoff.json 文件：

{
  "protocol_version": "1.0",
  "batch_id": "batch-20260923-001",
  "generated_at": "2026-09-23T10:00:00",
  "generated_by": "TeleAgent",
  "target": "srdcloud-digital-employee",
  "actions": [
    {
      "action_id": "act-001",
      "action_type": "upload_file",
      "file_path": "PRD-客户跟进提醒.md",
      "file_content_type": "markdown",
      "params": {
        "doc_title": "PRD-客户跟进提醒",
        "folder": "Desktop"
      },
      "version": 1,
      "depends_on": null,
      "status": "pending"
    },
    {
      "action_id": "act-002",
      "action_type": "upload_file",
      "file_path": "tech-spec-客户跟进提醒.md",
      "file_content_type": "markdown",
      "params": {
        "doc_title": "技术规约-客户跟进提醒",
        "folder": "Desktop"
      },
      "version": 1,
      "depends_on": null,
      "status": "pending"
    },
    {
      "action_id": "act-003",
      "action_type": "save_html_artifact",
      "file_path": "客户管理后台-proto.html",
      "file_content_type": "html",
      "params": {
        "artifact_title": "客户管理后台原型",
        "write_mode": "final"
      },
      "version": 1,
      "depends_on": null,
      "status": "pending"
    },
    {
      "action_id": "act-004",
      "action_type": "create_workitems_from_json",
      "file_path": "workitems-batch-客户跟进提醒.json",
      "file_content_type": "json",
      "params": {
        "project_id": "从用户上下文获取",
        "iteration_id": "从用户上下文获取或null"
      },
      "version": 1,
      "depends_on": null,
      "status": "pending"
    }
  ]
}

H.2 弱模型动作目录（仅4种动作，穷举）

弱模型只需要识别以下 4 种 action_type，每种对应一个固定的执行流程：

action_type	输入文件类型	弱模型执行流程	研发云 MCP 工具
`upload_file`	.md / .txt	读取文件内容 → 调用文档上传接口 → 返回文档链接	`document_upload_to_desktop`
`save_html_artifact`	.html	读取文件内容 → 调用产物写入(mode=final)+发布接口 → 返回产物链接	`artifact_write`(mode=final) + `artifact_publish`
`create_workitems_from_json`	.json	读取扁平JSON数组 → 按顺序逐条创建工作项 → 用返回编号关联父子 → 返回创建结果	`workitems_batch_create` + `workitems_update_workitem`
`mark_deprecated`	.json	读取旧版本清单 → 对工作项加评论/对文档重新上传标注版本 → 产物无法标记则跳过	`workitems_create_comments` / `document_upload_to_desktop`

弱模型不需要理解文件内容。对于 create_workitems_from_json，TeleAgent 已将工作项拆分建议转化为结构化 JSON 数组（见技能4输出格式），弱模型只需逐条 POST 到研发云 API。

H.3 弱模型执行流程（伪代码）

// 弱模型收到 .handoff.json 后的执行逻辑
1. 读取 .handoff.json
2. 遍历 actions 数组：
   for each action in actions:
     if action.status != "pending": skip
     if action.depends_on != null:
       检查依赖的 action 是否已完成，未完成则跳过（等下一轮）
     switch action.action_type:
       case "upload_file":
         content = read_file(action.file_path)
         result = call_mcp("document_upload_to_desktop", {
           file_name: action.params.doc_title + ".md",
           file_content: content,
           folder: action.params.folder,
           mime_type: "text/plain"
         })
         action.result = { doc_url: result.url }
         action.status = "done"
       
       case "save_html_artifact":
         content = read_file(action.file_path)
         mode = action.params.write_mode || "final"
         call_mcp("artifact_write", { filePath: action.file_path, content: content, mode: mode })
         result = call_mcp("artifact_publish", { filePath: action.file_path })
         action.result = { artifact_id: result.artifact_id, published_path: result.published_relative_path }
         action.status = "done"
       
       case "create_workitems_from_json":
         // JSON是扁平有序数组，parent_index指向数组中父项位置
         items = read_json(action.file_path)
         created = []  // 记录每条创建结果
         for i, item in enumerate(items):
           // 构建创建参数
           create_params = {
             title: item.title,
             description: item.description,
             workitem_type: item.workitem_type,
             priority: item.priority,
             estimated_hours: item.estimated_hours,
             acceptance_criteria: item.acceptance_criteria
           }
           // 第一轮创建（不含parent，因为父编号还没拿到）
           result = call_mcp("workitems_batch_create", { workitems: [JSON.stringify(create_params)] })
           created.push(result[0])  // 记录返回的工作项编号
           // 如果有父项，用返回的编号关联
           if item.parent_index >= 0:
             parent_key = created[item.parent_index].workitem_key
             call_mcp("workitems_update_workitem", {
               workitemKeys: [result[0].workitem_key],
               fieldKey: "parent",
               op: "update",
               fieldValue: parent_key
             })
         action.result = { created_count: created.length, items: created }
         action.status = "done"
       
       case "mark_deprecated":
         // 版本更新时标记旧产物
         dep_info = read_json(action.file_path)
         for each dep in dep_info.deprecated_actions:
           // 工作项：添加评论标记过期
           if dep.action_type == "create_workitems_from_json":
             for each old_workitem in dep.result.items:
               call_mcp("workitems_create_comments", {
                 workitemKey: old_workitem.workitem_key,
                 content: "⚠️ 需求已变更，此工作项已过期，请参考最新版本 v" + dep.new_version
               })
           // 文档：重新上传标注版本（无法直接编辑已有文档备注）
           else if dep.action_type == "upload_file":
             // 文档无法直接标记过期，跳过（新版本上传后旧版本自然在历史中）
             pass
           // 产物：无法标记过期，跳过（新版本发布后旧版本在版本历史中）
           else if dep.action_type == "save_html_artifact":
             pass
         action.status = "done"
       
       case default:
         action.status = "error"
         action.error = "unknown action_type: " + action.action_type
3. 输出执行结果摘要（成功数/失败数/跳过数）
4. 将更新后的 .handoff.json（含各action的result和status）返回给用户

H.4 交接失败处理

失败场景	处理方式
弱模型找不到文件	action.status = "error"，error_message = "file not found: {path}"，跳过该条继续执行下一条
研发云 API 返回错误	action.status = "error"，error_message = API错误信息，跳过继续
依赖的 action 未完成	action.status = "blocked"，本轮跳过，等待下一轮重试
弱模型无法识别 action_type	action.status = "error"，error_message = "unknown action_type"，跳过继续

关键原则：单条 action 失败不阻断其他 action 执行。弱模型执行完后输出摘要，用户可决定是否重试失败的 action。

H.5 版本管理与失效传播

产物版本号

每个产物文件名带版本号：PRD-{项目名}-v{N}.md、tech-spec-{项目名}-v{N}.md、{主题}-proto-v{N}.html、workitems-batch-{项目名}-v{N}.json

修改时的失效传播

当 TeleAgent 重新生成某个产物的新版本时，在 .handoff.json 中追加一条 mark_deprecated action：

{
  "action_id": "act-005",
  "action_type": "mark_deprecated",
  "file_path": "deprecated-清单.json",
  "file_content_type": "json",
  "params": {
    "deprecated_actions": ["act-001"],
    "reason": "PRD内容已更新，旧版本标记为deprecated",
    "cascade": ["act-002", "act-003", "act-004"]
  },
  "version": 2,
  "depends_on": null,
  "status": "pending"
}

deprecated_actions：直接标记过期的旧 action
cascade：级联失效的下游 action（如 PRD 改了，架构/原型/拆分都需要重新生成）
弱模型执行 mark_deprecated 时：
- 工作项：对已创建的工作项添加评论"⚠️ 需求已变更，此工作项已过期，请参考最新版本 v{N+1}"（调用 workitems_create_comments）
- 文档：无法直接编辑已有文档备注，跳过（新版本上传后旧版本自然保留在文档历史中，用户可手动删除）
- 产物：无法标记旧版本过期，跳过（新版本发布后旧版本保留在产物版本历史中）

串联失效规则

修改的产物	级联失效	用户操作
PRD v1 → v2	架构 v1、原型 v1、工作项 v1 全部标记 deprecated	TeleAgent 重新生成 v2 链
架构 v1 → v2	原型 v1、工作项 v1 不一定失效（取决于改动范围）	TeleAgent 判断是否级联
原型 v1 → v2	无级联	仅原型重新提交
工作项 v1 → v2	无级联	弱模型创建新工作项，旧工作项标记 deprecated

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

1.1 职责

将用户需求描述转化为结构化产品需求文档（PRD），产出为 Markdown 文件 + 交接清单 action。

1.2 输入

字段	类型	必填	说明
`requirement_text`	String	是	用户原始需求描述或问需单内容摘要
`project_name`	String	否	项目名称，用于文档命名
`template_override`	String	否	用户自定义模板要求
`reference_docs`	String[]	否	参考文档内容
`tech_constraints_whitelist`	String	否	技术约束白名单（不压缩、原样传递的关键约束）
`version`	Integer	否	版本号，默认1，修改时递增

1.3 输出

文件1：PRD-{项目名}-v{N}.md（Markdown 格式）

文件2：追加到 .handoff.json 的 action：

{
  "action_id": "act-{序号}",
  "action_type": "upload_file",
  "file_path": "PRD-{项目名}-v{N}.md",
  "file_content_type": "markdown",
  "params": {
    "doc_title": "PRD-{项目名}",
    "folder": "Desktop"
  },
  "version": {N},
  "depends_on": null,
  "status": "pending"
}

标准模板结构（9 章）：

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

## 2. 需求描述
核心需求的简要描述。

## 3. 项目概述
**项目背景** / **目标用户** / **业务目标** / **关键指标(KPIs)**

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

### 流程图（Mermaid graph TD）
- 判断节点用菱形，流程节点用矩形
- 标注每步执行角色和核心操作

## 5. 功能列表

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

## 7. 页面列表

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

### 页面结构图（markmap）
- 层级：# 主模块 → ## 页面 → ### 功能区域 → #### 控件 → ##### 规则/反馈

## 9. 统计需求
### 用户行为统计（埋点表）
### 统计指标

1.4 生成规则

需求不清晰时仅追问一次关键信息
一次写入产物文件
严格按模板结构填充
流程图用 mermaid graph TD，页面结构图用 markmap
禁止填充文案，验收标准必须可量化
技术约束白名单：用户在对话中提到的技术栈/数据库/框架等关键词（如"用PostgreSQL不用MySQL""Spring Boot 3.x""部署到K8s"）不压缩、原样写入PRD第6章功能详细描述中

1.5 质量检查清单

9 章完整
Mermaid/markmap 语法正确
每个功能有输入/输出/实现逻辑
每个页面有布局/元素/交互/边界条件/错误处理
无填充文案、无编造数据
技术约束白名单内容已原样写入
文件名含版本号 PRD-{项目名}-v{N}.md
.handoff.json 已追加 upload_file action

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

2.1 职责

将 PRD 转化为可据以实现的技术规约，产出 Markdown 文件 + 交接清单 action。

2.2 输入

字段	类型	必填	说明
`prd_content`	String	是	PRD 文档内容
`tech_constraints`	String	否	技术约束（从PRD技术约束白名单传递 + 用户补充）
`project_name`	String	否	项目名称
`version`	Integer	否	版本号，默认1

2.3 输出

文件1：tech-spec-{项目名}-v{N}.md

文件2：追加到 .handoff.json：

{
  "action_id": "act-{序号}",
  "action_type": "upload_file",
  "file_path": "tech-spec-{项目名}-v{N}.md",
  "file_content_type": "markdown",
  "params": { "doc_title": "技术规约-{项目名}", "folder": "Desktop" },
  "version": {N},
  "depends_on": null,
  "status": "pending"
}

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

# 技术规约
> 状态：📝 草案 | 🧊 已冻结 | ⚠️ 已过期(见v{N+1})
> 版本：v{N}

## 1. 架构设计
- 整体架构 + 技术选型理由 + 部署架构
- 架构图（Mermaid graph TD/LR）

## 2. 模块拆分
| 模块 | 职责 | 依赖 |
- 模块依赖图（Mermaid）

## 3. 接口契约
每个接口：方法/路径、输入、输出(成功/失败)、错误码

## 4. 数据模型
| 字段 | 类型 | 约束 | 说明 |
- ER图（Mermaid erDiagram）

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

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

2.4 生成规则

仔细阅读PRD，理解每个功能意图。不清楚的标注 [待确认]
架构设计要具体：明确架构类型、选型理由、部署方案
接口契约是硬约束：字段名、类型、错误码都要明确
验收标准要可验证
技术约束优先级：用户明确指定的技术栈 > PRD技术约束白名单 > TeleAgent推荐
架构图/模块依赖图/ER图必须用 Mermaid
文件名含版本号

2.5 质量检查清单

架构设计明确 + 选型理由
Mermaid 语法正确
接口契约完整（方法/路径/输入/输出/错误码）
数据模型完整（字段/类型/约束/说明）
验收标准可验证
技术约束白名单内容已采纳
文件名含版本号
.handoff.json 已追加 action

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

3.1 职责

根据设计简报，生成生产级自包含 HTML 原型文件。

3.2 输入（设计简报）

字段	类型	必填	说明
`design_system`	String	是	设计体系（9选1）
`platform`	String	是	目标平台（6选1）
`page_type`	String	是	页面类型（13种或通用前端）
`page_topic`	String	是	页面主题
`target_audience`	String	否	目标受众
`core_content`	String	是	核心内容摘要
`component_library`	String	否	组件库（element-plus/shadcn）
`multi_view`	Boolean	否	是否多视图
`version`	Integer	否	版本号，默认1

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

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

默认：Neutral Modern

3.4 平台速查表（6种）

名称	关键词	默认联动
响应式Web	分享/多端/落地页	Neutral Modern
桌面Web	桌面/后台/大屏	Ant
iOS应用	iPhone/iOS	Neutral Modern
Android应用	Android	Neutral Modern
平板应用	iPad/平板	Neutral Modern
桌面应用	Electron/客户端	Neutral Modern

默认：响应式Web

3.5 页面类型速查表

关键词	页面类型	推荐设计体系	推荐平台
FAQ/帮助中心	faq-page	OpenAI	响应式Web
登录/注册	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-page	Neutral Modern	响应式Web
邮件/newsletter	email-marketing	MiniMax	响应式Web
海报/分享图	poster-hero	Runway	桌面Web
看板/kanban	kanban-board	Ant	桌面Web
发票/账单	invoice	Neutral Modern	响应式Web
文档/guide	docs-page	OpenAI	桌面Web
原型/demo/页面	通用前端	按关键词推断	按关键词推断

3.6 输出

文件1：{主题}-proto-v{N}.html（单个自包含 HTML）

文件2：追加到 .handoff.json：

{
  "action_id": "act-{序号}",
  "action_type": "save_html_artifact",
  "file_path": "{主题}-proto-v{N}.html",
  "file_content_type": "html",
  "params": { "artifact_title": "{主题}原型", "write_mode": "final" },
  "version": {N},
  "depends_on": null,
  "status": "pending"
}

3.7 分步生成策略（解决单次生成可靠性问题）

不强制一次写入。允许分步生成 + 自检修复，提高 P0 硬门控通过率。

生成步骤

步骤	产出	说明
Step 1：骨架	HTML骨架 + `:root`令牌注入 + `<meta>`平台约束	基础结构，不含页面内容
Step 2：内容	`<body>`页面内容 + 语义化标签 + 内联SVG	注入页面技能定义的区块
Step 3：交互	多视图JS + 弹窗JS + 分段控件JS	交互逻辑注入
Step 4：自检	P0门控逐项检查 → 修复不通过项	内部静默执行
Step 5：交付	写入文件 + 追加handoff action	最终产物

自检修复规则

P0 不通过项 → 就地修复后重新检查，最多3轮修复
3轮后仍不通过 → 降级交付（标注未通过项，让用户手动检查）
自检过程不输出给用户，仅最终交付时附自检摘要

3.8 代码合成铁律

设计令牌

tokens.css 的 :root 整体注入 <style> 首段
全文 var(--xxx) 引用，禁止 :root 外裸 hex
Chart.js 例外：通过 cssVar() 辅助函数读取

平台约束

Viewport / 断点 / 设备框架 / 触摸目标(≥44px iOS / 48dp Android)

多视图导航（≥2功能模块时）

单个自包含 HTML，data-view-link 切换
登录页作为首个无导航栏独立视图
移动端App ≥2功能区块强制底部tab

动作按钮（三选一）

data-open-dialog 弹窗
就地反馈 toast
aria-disabled 显式inert

分段控件

data-seg + data-seg-mode(panel/filter)，点击必须产生可见变化

3.9 P0 硬门控清单（自检用，不输出给用户）

:root 外无裸 hex
标题用 var(--font-display)、正文用 var(--font-body)
强调色每屏 ≤2 处
无紫蓝渐变、无 emoji 功能图标
无填充文案、无编造数据
hover/focus/active 三态完整
移动端栅格折叠正常、无横向溢出
<!doctype html> 恰好1次、<html> 恰好1个
动作按钮非死钮
弹窗默认隐藏
分段控件点击有可见变化
组件库启用时含 .ep-*/.sh-* 类且 :root 外零裸hex

3.10 2秒直觉检查

看页面2秒，是否像"这月见的每个AI创业公司首页"？若是，回去换具体内容、删强调色。

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

4.1 职责

将需求内容转化为结构化工作项 JSON 数组（不是 Markdown），弱模型直接逐条 POST 到研发云 API，无需解析 Markdown 内容。

4.2 输入

字段	类型	必填	说明
`requirement_content`	String	是	需求内容（PRD全文/问需单/自然语言）
`split_to_task`	Boolean	否	是否拆到任务级（默认true）
`team_members`	String[]	否	团队成员列表
`sprint_info`	String	否	迭代信息
`version`	Integer	否	版本号

4.3 输出（关键变化：JSON而非Markdown）

文件1：workitems-batch-{项目名}-v{N}.json（扁平有序JSON数组，弱模型按顺序逐条创建，parent_index 指向数组中父项的位置）

[
  {
    "seq": 0,
    "title": "客户管理模块-客户跟进提醒功能",
    "description": "实现客户跟进提醒功能，支持设置提醒时间、多渠道推送、逾期升级",
    "workitem_type": "feature",
    "priority": "high",
    "estimated_hours": 40,
    "parent_index": -1,
    "iteration": null,
    "acceptance_criteria": "1.可设置跟进提醒时间 2.支持企微/站内消息推送 3.逾期自动升级提醒",
    "assignee_suggestion": "待分配"
  },
  {
    "seq": 1,
    "title": "跟进提醒设置",
    "description": "作为销售，我希望设置跟进提醒时间，以便按时跟进客户",
    "workitem_type": "user_story",
    "priority": "high",
    "estimated_hours": 8,
    "parent_index": 0,
    "iteration": null,
    "acceptance_criteria": "1.可选择提醒时间 2.可设置提醒方式 3.保存成功有反馈",
    "assignee_suggestion": "待分配"
  },
  {
    "seq": 2,
    "title": "设计提醒时间字段",
    "description": "设计客户跟进提醒时间的数据字段和数据库表结构",
    "workitem_type": "task",
    "priority": "high",
    "estimated_hours": 4,
    "parent_index": 1,
    "task_type": "backend",
    "assignee_suggestion": "待分配"
  },
  {
    "seq": 3,
    "title": "实现提醒时间设置接口",
    "description": "开发提醒时间的CRUD接口",
    "workitem_type": "task",
    "priority": "high",
    "estimated_hours": 4,
    "parent_index": 1,
    "task_type": "backend",
    "assignee_suggestion": "待分配"
  }
]

为什么用扁平数组而不是嵌套树：弱模型不需要递归遍历 children、不需要展平树结构。按 seq 顺序逐条创建，parent_index 指向数组中父项的位置（-1 表示无父项）。弱模型创建第 i 项后，将返回的工作项编号存入 results[i]，后续项的 parent_index 直接索引到父项编号完成关联——纯机械循环，零语义理解。

文件2：追加到 .handoff.json：

{
  "action_id": "act-{序号}",
  "action_type": "create_workitems_from_json",
  "file_path": "workitems-batch-{项目名}-v{N}.json",
  "file_content_type": "json",
  "params": {
    "project_id": "从用户上下文获取",
    "iteration_id": "从用户上下文获取或null"
  },
  "version": {N},
  "depends_on": null,
  "status": "pending"
}

4.4 拆分规则

特性拆分

按功能模块拆分，每个模块一个「特性」
workitem_type: "feature"

用户故事拆分

遵循 INVEST 原则
格式：「作为{角色}，我希望{功能}，以便{价值}」
优先级基于 RICE 模型
workitem_type: "user_story"
工作量：1-3人天/故事

任务拆分（split_to_task=true）

每个故事 2-5 个任务，每个 ≤1人天
workitem_type: "task"
task_type: frontend/backend/test/doc
工时 = 人天 × 8

父子关系

扁平有序数组：所有工作项平铺在一个JSON数组中，按 seq 从0开始编号
parent_index 字段指向数组中父项的 seq 值（-1 表示无父项，即顶层特性）
顺序保证：父项必须出现在子项之前（parent_index < 自身seq），弱模型按顺序创建时父项编号已存在
弱模型创建逻辑：results = []; for i, item in items: result = create(item); results[i] = result; if item.parent_index >= 0: update_parent(result.key, results[item.parent_index].key)

4.5 质量检查清单

每个用户故事遵循 INVEST
用户故事格式正确
每个任务 ≤1人天
任务工作量之和 = 父故事工作量
父子关系完整（扁平数组中 parent_index 指向正确的父项 seq，且父项在子项之前）
每条含 seq 字段且从0递增无断号
parent_index = -1 的项为顶层特性
parent_index 值均 < 自身 seq（保证父项先创建）
优先级基于 RICE
预估工时 = 人天 × 8
JSON 格式合法（可被 JSON.parse 解析）
文件名含版本号
.handoff.json 已追加 action

附录A：完整串联流程（含交接协议）

用户原始输入
   │
   ▼
┌──────────────────────────────────────────────────┐
│  TeleAgent（强模型 · 离线生产层）                   │
│  ──────────────────────────────────────────────  │
│  Agent核心路由（参考附录D路由决策树）                 │
│  ├─ 技能1: PRD生成 → PRD-{项目名}-v1.md           │
│  ├─ 技能2: 架构设计 → tech-spec-{项目名}-v1.md    │
│  ├─ 技能3: HTML原型 → {主题}-proto-v1.html        │
│  └─ 技能4: 工作项拆分 → workitems-batch-v1.json   │
│                                                   │
│  生成 .handoff.json（交接清单）                     │
│  · 列出所有产物文件路径 + action_type + params      │
│  · 弱模型只读此清单，逐条执行                        │
└──────────────────┬───────────────────────────────┘
                   │ .handoff.json + 产物文件
                   ▼
┌──────────────────────────────────────────────────┐
│  研发云数字员工（弱模型 · 在线执行层）                │
│  ──────────────────────────────────────────────  │
│  1. 读取 .handoff.json                            │
│  2. 遍历 actions：                                 │
│     · upload_file → 读取.md → 上传文档空间          │
│     · save_html_artifact → 读取.html → 写入+发布   │
│     · create_workitems_from_json → 读取.json →    │
│       逐条创建工作项                                │
│     · mark_deprecated → 标记旧产物过期              │
│  3. 输出执行摘要（成功/失败/跳过）                    │
│  4. 返回更新后的 .handoff.json                      │
└──────────────────────────────────────────────────┘

串联执行示例

用户: "帮我做一个客户跟进提醒功能，要PRD、技术方案和原型"
                    │
                    ▼
         [TeleAgent Agent核心]
         路由: multi_step (PRD→架构+原型并行)
         技术约束白名单: 提取并保留用户提到的技术栈
         缺失检测: page_topic(阻断) → 追问
                    │
          用户回复: "客户管理后台"
                    │
                    ▼
         [技能1: PRD生成]
         输出: PRD-客户跟进提醒-v1.md
         handoff: +upload_file action
                    │
           ┌────────┴────────┐
           ▼                 ▼
    [技能2: 架构设计]   [技能3: HTML原型]
    输出: tech-spec-v1  输出: proto-v1.html
    handoff: +upload    handoff: +save_artifact
           │                 │
           └────────┬────────┘
                    ▼
         [可选: 技能4 工作项拆分]
         输出: workitems-batch-v1.json
         handoff: +create_workitems action
                    │
                    ▼
         生成完整 .handoff.json (4个action)
                    │
                    ▼
         [研发云数字员工]
         读取 .handoff.json → 逐条执行 → 返回结果

修改场景（版本+失效传播）

用户: "PRD里加一个客户标签管理功能"
                    │
                    ▼
         [TeleAgent]
         检测: PRD修改 → 版本 v1→v2
         失效传播: 架构v1/原型v1/工作项v1 级联deprecated
                    │
                    ▼
         [技能1: PRD生成 v2]
         输出: PRD-客户跟进提醒-v2.md
         handoff: +upload_file(v2) + mark_deprecated(v1, cascade:[架构,原型,工作项])
                    │
                    ▼
         [研发云数字员工]
         1. 上传 PRD-v2 到文档空间
         2. 标记 PRD-v1 为过期（追加备注）
         3. 标记 架构v1/原型v1/工作项v1 为过期
         4. 返回结果
                    │
                    ▼
         [TeleAgent 继续重新生成 v2 链]
         架构v2 → 原型v2 → 工作项v2
         handoff: 追加新action

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

技能	输入	输出文件	handoff action_type
PRD生成	需求描述+技术约束白名单	`PRD-{项目名}-v{N}.md`	`upload_file`
架构设计	PRD内容+技术约束	`tech-spec-{项目名}-v{N}.md`	`upload_file`
HTML原型	设计简报(9×6×13)	`{主题}-proto-v{N}.html`	`save_html_artifact`
工作项拆分	PRD内容+团队+迭代	`workitems-batch-{项目名}-v{N}.json`	`create_workitems_from_json`

附录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：TeleAgent Agent核心路由参考（不作为独立技能加载）

以下内容作为 TeleAgent Agent 核心系统提示词的参考知识注入，不作为独立技能加载。 Agent核心已在做意图识别和路由，这些路由表/决策树/缺失检测规则用于增强其路由准确性。

D.1 关键词→域技能路由表

关键词/语义模式	路由目标	action_type
PRD/需求文档/产品需求	srdcloud-prd-distilled	create/modify
架构/技术方案/接口设计/数据模型	architecture-design-doc-distilled	create/modify
原型/页面/demo/界面/UI/HTML	design-proto-distilled	create/modify
拆分/任务/工作项/排期/指派	workitem-split-advisor-distilled	create
做个功能/帮我实现/我想要一个	multi_step	create

D.2 复合请求串联顺序

信号组合	串联顺序
"做个XX功能"（无已有PRD）	PRD → 架构(并行) + 原型(并行) → 拆分(可选)
"做个XX功能"（已有PRD）	架构 + 原型 → 拆分
"根据需求做原型"	PRD → 原型
"写PRD然后拆任务"	PRD → 拆分

D.3 缺失信息检测（一次性追问）

检测项	阻断级别	追问示例	默认值
requirement_text 过于模糊	阻断	"能否详细描述核心功能和目标用户？"	无
page_topic 缺失（原型）	阻断	"页面主题是什么？"	无
project_name 缺失	非阻断	"属于哪个项目？"	"未命名项目"
design_system 无法推断	非阻断	"偏好哪种设计风格？"	Neutral Modern
team_members 缺失	非阻断	"提供团队成员列表？"	"待分配"
tech_constraints 缺失	非阻断	"有技术栈要求？"	按最佳实践推荐

D.4 上下文压缩规则（含技术约束白名单）

压缩规则

去除口语化词汇
补全隐含信息
按"目标用户+核心功能+业务价值"结构化
标注不确定项 [推断]、缺失项 [待确认]

技术约束白名单（不压缩、原样传递）

以下类型的关键词在上下文压缩时不压缩、原样保留，直接传递给下游技能：

类别	示例关键词	传递目标
数据库	PostgreSQL/MySQL/Redis/MongoDB/Oracle	架构设计技能
框架	Spring Boot/Django/Express/React/Vue	架构设计技能
部署	K8s/Docker/阿里云/腾讯云/私有化	架构设计技能
协议	gRPC/RESTful/WebSocket/GraphQL	架构设计技能
性能约束	"1000并发"/"响应<200ms"/"支持百万级"	架构设计技能+PRD
安全要求	"等保三级"/"数据加密"/"SSO"	架构设计技能+PRD
否定约束	"不用MySQL"/"不用Redis"	架构设计技能

白名单匹配规则：使用正则 /(PostgreSQL|MySQL|Redis|MongoDB|Oracle|Spring\s*Boot|Django|Express|React|Vue|K8s|Kubernetes|Docker|gRPC|RESTful|WebSocket|GraphQL|并发|响应|毫秒|等保|加密|SSO|不用|不使用)/i 扫描用户原始输入，命中的句子整句保留，不进入压缩摘要。

附录E：关键设计原则

弱模型只做机械提交：读 .handoff.json 清单 → 逐条执行4种动作之一 → 返回结果。不做语义理解、不解析Markdown内容、不递归遍历树结构
TeleAgent负责所有复杂逻辑：需求分析、文档生成、工作项拆分、设计简报推断——全部在强模型侧完成
工作项输出用扁平JSON数组：parent_index 指向数组中父项位置，弱模型按顺序逐条创建+关联，零递归、零展平
交接协议极简：一个 .handoff.json 清单文件，4种 action_type，弱模型执行流程固定
版本管理+失效传播：产物文件名带版本号，工作项通过添加评论标记过期，文档/产物新版本上传后旧版本自然保留在历史中
技术约束白名单不压缩：数据库/框架/部署/性能/安全等关键词原样传递，避免压缩丢信息
HTML原型允许分步生成：骨架→内容→交互→自检→交付，最多3轮自检修复，不强制一次写入
总控路由作为prompt参考：路由表/决策树注入Agent核心系统提示词，不作为独立技能加载，避免冗余序列化
单条action失败不阻断：弱模型逐条执行，失败跳过继续，最终输出摘要
project_id/iteration_id从用户上下文获取：TeleAgent在handoff的params中标注"从用户上下文获取"，弱模型从会话上下文中读取
save_html_artifact使用mode=final：TeleAgent已生成完整HTML，弱模型一次写入即可，通过 write_mode 参数显式指定

37 KiB Raw Permalink Blame History Unescape Escape

外部 Coding Agent 技能规范（研发云协同 · 算力分级分流）

交接协议（Handoff Protocol）—— 弱模型执行层规范

H.1 交接清单格式（.handoff.json）

H.2 弱模型动作目录（仅4种动作，穷举）

H.3 弱模型执行流程（伪代码）

H.4 交接失败处理

H.5 版本管理与失效传播

产物版本号

修改时的失效传播

串联失效规则

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

1.1 职责

1.2 输入

1.3 输出

1.4 生成规则

1.5 质量检查清单

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

2.1 职责

2.2 输入

2.3 输出

2.4 生成规则

2.5 质量检查清单

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

3.1 职责

3.2 输入（设计简报）

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

3.4 平台速查表（6种）

3.5 页面类型速查表

3.6 输出

3.7 分步生成策略（解决单次生成可靠性问题）

生成步骤

自检修复规则

3.8 代码合成铁律

设计令牌

平台约束

多视图导航（≥2功能模块时）

动作按钮（三选一）

分段控件

3.9 P0 硬门控清单（自检用，不输出给用户）

3.10 2秒直觉检查

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

4.1 职责

4.2 输入

4.3 输出（关键变化：JSON而非Markdown）

4.4 拆分规则

特性拆分

用户故事拆分

任务拆分（split_to_task=true）

父子关系

4.5 质量检查清单

附录A：完整串联流程（含交接协议）

串联执行示例

修改场景（版本+失效传播）

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

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

附录D：TeleAgent Agent核心路由参考（不作为独立技能加载）

D.1 关键词→域技能路由表

D.2 复合请求串联顺序

D.3 缺失信息检测（一次性追问）

D.4 上下文压缩规则（含技术约束白名单）

压缩规则

技术约束白名单（不压缩、原样传递）

附录E：关键设计原则

37 KiB

Raw Permalink Blame History

H.1 交接清单格式（`.handoff.json`）

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