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

34 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": "客户管理后台原型"
      },
      "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 读取文件内容 → 调用产物写入+发布接口 → 返回产物链接 artifact_write + artifact_publish
create_workitems_from_json .json 读取JSON数组 → 逐条调用工作项创建接口 → 返回创建结果 workitems_batch_create
mark_deprecated .json 读取旧版本清单 → 标记旧产物为过期（不删除） → 返回标记结果 工作项更新/文档备注

弱模型不需要理解文件内容。对于 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
         })
         action.result = { doc_url: result.url }
         action.status = "done"
       
       case "save_html_artifact":
         content = read_file(action.file_path)
         call_mcp("artifact_write", { filePath: action.file_path, content: content, mode: "final" })
         result = call_mcp("artifact_publish", { filePath: action.file_path })
         action.result = { artifact_url: result.url }
         action.status = "done"
       
       case "create_workitems_from_json":
         items = read_json(action.file_path)  // 结构化JSON数组，无需解析Markdown
         result = call_mcp("workitems_batch_create", { workitems: items })
         action.result = { created_count: result.count, items: result.items }
         action.status = "done"
       
       case "mark_deprecated":
         // 版本更新时标记旧产物
         old_actions = read_json(action.file_path)
         for each old in old_actions:
           // 根据旧action_type执行对应的"标记过期"操作
           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}"；对已创建的工作项更新状态或添加评论"需求已变更，请参考最新PRD"

串联失效规则

修改的产物 级联失效 用户操作
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 生成规则

  1. 需求不清晰时仅追问一次关键信息
  2. 一次写入产物文件
  3. 严格按模板结构填充
  4. 流程图用 mermaid graph TD，页面结构图用 markmap
  5. 禁止填充文案，验收标准必须可量化
  6. 技术约束白名单：用户在对话中提到的技术栈/数据库/框架等关键词（如"用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 生成规则

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

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": "{主题}原型" },
  "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

动作按钮（三选一）

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

分段控件

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

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

  1. :root 外无裸 hex
  2. 标题用 var(--font-display)、正文用 var(--font-body)
  3. 强调色每屏 ≤2 处
  4. 无紫蓝渐变、无 emoji 功能图标
  5. 无填充文案、无编造数据
  6. hover/focus/active 三态完整
  7. 移动端栅格折叠正常、无横向溢出
  8. <!doctype html> 恰好1次、<html> 恰好1个
  9. 动作按钮非死钮
  10. 弹窗默认隐藏
  11. 分段控件点击有可见变化
  12. 组件库启用时含 .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 数组，弱模型可直接消费）

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

为什么用JSON而不是Markdown：弱模型不需要从Markdown中解析父子树——JSON本身就是结构化的，弱模型只需递归遍历 children 数组，逐条调用 workitems_batch_create，parent 字段告诉它父子关系。

文件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

父子关系

  • parent 字段填写父工作项的 title（弱模型创建时先创建父项，拿到ID后再创建子项并关联）
  • children 数组嵌套子工作项

4.5 质量检查清单

  • 每个用户故事遵循 INVEST
  • 用户故事格式正确
  • 每个任务 ≤1人天
  • 任务工作量之和 = 父故事工作量
  • 父子关系树完整（parent字段 + children数组）
  • 优先级基于 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 上下文压缩规则（含技术约束白名单）

压缩规则

  1. 去除口语化词汇
  2. 补全隐含信息
  3. 按"目标用户+核心功能+业务价值"结构化
  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：关键设计原则

  1. 弱模型只做机械提交：读 .handoff.json 清单 → 逐条执行4种动作之一 → 返回结果。不做语义理解、不解析Markdown内容、不编排API
  2. TeleAgent负责所有复杂逻辑：需求分析、文档生成、工作项拆分、设计简报推断——全部在强模型侧完成
  3. 工作项输出用JSON不用Markdown：弱模型直接 JSON.parse 逐条创建，不需要从Markdown中解析父子树
  4. 交接协议极简：一个 .handoff.json 清单文件，4种 action_type，弱模型执行流程固定
  5. 版本管理+失效传播：产物文件名带版本号，修改时旧版本通过 mark_deprecated action 标记过期，级联失效由 TeleAgent 判断
  6. 技术约束白名单不压缩：数据库/框架/部署/性能/安全等关键词原样传递，避免压缩丢信息
  7. HTML原型允许分步生成：骨架→内容→交互→自检→交付，最多3轮自检修复，不强制一次写入
  8. 总控路由作为prompt参考：路由表/决策树注入Agent核心系统提示词，不作为独立技能加载，避免冗余序列化
  9. 单条action失败不阻断：弱模型逐条执行，失败跳过继续，最终输出摘要
  10. project_id/iteration_id从用户上下文获取：TeleAgent在handoff的params中标注"从用户上下文获取"，弱模型从会话上下文中读取，不需要TeleAgent提供
Reference in New Issue View Git Blame Copy Permalink