858 lines
34 KiB
Markdown
858 lines
34 KiB
Markdown
# 外部 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": "客户管理后台原型"
|
||
},
|
||
"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：
|
||
|
||
```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}"；对已创建的工作项更新状态或添加评论"需求已变更，请参考最新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：
|
||
```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": "{主题}原型" },
|
||
"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 数组，弱模型可直接消费）
|
||
|
||
```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`：
|
||
```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提供
|