init: 2026黑马复赛 agents-setup 初始提交

docs/external-agent-skill-specs_v4.md

@@ -0,0 +1,907 @@
+# 外部 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` 参数显式指定