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

> **架构定位**：强模型（TeleAgent）离线生成高质量中间产物 → 弱模型（研发云数字员工）只做机械提交。
>
> **核心原则**：弱模型的工作量降到最低——**读一个清单 + 执行一个动作**，不做语义理解、不做数据解析、不做 API 编排。
>
> **共 4 个域技能 + 1 套交接协议**。技能0（总控路由）不作为独立技能加载，其路由表/决策树/缺失检测规则作为 TeleAgent Agent 核心的 prompt 参考（见附录D）。

---

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

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

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

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

```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：

```json
{
  "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：
```json
{
  "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 章）：

```markdown
## 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`：
```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章 + 修订历史）：

```markdown
# 技术规约
> 状态：📝 草案 | 🧊 已冻结 | ⚠️ 已过期(见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`：
```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

#### 动作按钮（三选一）
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数组**，弱模型按顺序逐条创建，`parent_index` 指向数组中父项的位置）

```json
[
  {
    "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`：
```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 上下文压缩规则（含技术约束白名单）

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