技术方案
围绕业务目标与约束,系统性调研内部文档、外部技术资料与行业最佳实践,输出架构设计、关键模块、技术选型、性能估算、风险预案的完整技术方案文档,直接生成钉钉在线文档。
禁止事项
- 禁止以对话文本替代钉钉在线文档作为最终交付物
- 禁止在有钉钉原生工具可用时跳过内部文档检索直接使用外部搜索
- 禁止编造性能数据、技术选型结论或风险评估结果
- 禁止孤立引用性能数字(必须标注测试条件:硬件配置、数据规模、并发数等)
- 禁止绕过钉钉工具直接构造 API 请求
强制要求
- 本技能触发即代表用户期望生成钉钉在线文档,无需询问
- 草稿文件路径必须动态化,使用当前工作目录下的相对路径:
./draft_tech-solution_{方案名}_{YYYYMMDD_HHMMSS}.md - 技术选型必须有评估矩阵和明确结论,不得只列候选项
- 性能数据必须标注来源(官方文档/第三方评测/内部测试)
- 风险清单每条必须有降级方案和负责人
- 架构描述必须配合 ASCII 流程图(悟空平台暂不支持自动生成架构图)
能力清单
| 工具 | 用途 | 说明 |
|---|---|---|
dws doc search |
检索内部 PRD、架构文档、技术评审记录 | 关键词含项目名称 + 技术关键词,参数用 --query |
dws doc read |
读取关键文档详情 | 提取业务上下文、技术栈、历史决策 |
dws wiki(可选) |
检索钉钉知识库 | 业务上下文、技术栈、历史架构决策;仅在已连接钉钉知识库时可用,否则跳过该内部知识库步骤并标注「当前端无内部知识库检索能力,已跳过」 |
WebSearch |
广泛检索公开技术信息 | 技术选型对比、最佳实践、性能基准 |
WebFetch |
获取特定网页/文档全文 | 官方文档、技术博客、白皮书 |
dws doc create |
生成钉钉在线文档 | 直接输出技术方案,无需 Writer Agent |
⚠️ 架构图说明:原版使用
aily-diagram自动生成架构图,悟空平台暂无等价工具。本技能改为使用 ASCII 流程图 + 文字描述替代,功能可用但视觉效果有所降级。
工作流
用户输入(业务目标 + 可选约束条件)
|
v
Phase 1 — 需求与资料获取
→ A1: 需求理解(dws doc search + 可选 dws wiki)
→ A2: 现有系统调研(dws doc search + 可选 dws wiki)
→ A3: 技术调研(WebSearch + WebFetch)
→ A4: 性能与规模基准(WebSearch + WebFetch)
→ A5: 安全与合规(WebSearch + 可选 dws wiki)
→ 每步完成后追加写入 draft_tech-solution_{方案名}_{时间戳}.md
|
v
Phase 2 — 结构化分析
→ B1: 需求拆解与优先级
→ B2: 技术选型评估矩阵
→ B3: 架构设计原则
→ B4: 关键模块设计(含接口/数据模型/关键逻辑)
→ B5: 性能与容量估算
→ B6: 风险评估与降级方案
|
v
Phase 3 — 生成方案文档
→ 读取 draft.md 全部素材
→ dws doc create 生成钉钉在线文档
|
v
钉钉在线文档技术方案(含链接)
Phase 1 — 需求与资料获取
核心原则:钉钉工具优先获取内部资料,外部检索补充技术选型与最佳实践。每步产出的关键信息必须写入草稿文件。
A1. 需求理解
目标:完整理解业务目标、功能边界、非功能要求与约束条件。
调用策略:
# 检索内部 PRD/需求文档
dws doc search --query "{项目名称} PRD 需求文档"
dws doc search --query "{项目名称} 产品设计 功能规格"
# 知识库补充(可选:如已连接钉钉知识库可用 dws wiki 检索,否则跳过并标注「当前端无内部知识库检索能力,已跳过」)
dws wiki search --query "{项目名称} 业务背景 目标"
dws wiki search --query "{项目名称} 功能需求 用户场景"
dws wiki search --query "{项目名称} 非功能需求 性能 可用性 安全"
写入草稿(追加模式):
## 需求理解
### 业务背景
- 业务痛点:...
- 项目目标:...
### 功能需求
| 需求编号 | 需求描述 | 优先级 | 来源 |
|---------|---------|--------|------|
| F-001 | ... | P0 | PRD v2.1 |
### 非功能需求
- 性能:接口响应 P99 < 200ms,QPS >= 5000
- 可用性:SLA >= 99.95%
- 安全:用户数据加密存储,接口鉴权
- 扩展性:支持未来 3 年 10 倍流量增长
### 约束条件
- 技术栈约束:...
- 时间约束:...
- 人力约束:...
A2. 现有系统调研
目标:了解当前系统架构、技术债、可复用组件,避免重复建设。
调用策略:
# 检索架构/系统设计文档
dws doc search --query "{项目名称} 技术架构 系统设计"
dws doc search --query "{相关系统} 接口文档 API"
# 知识库补充(可选:如已连接钉钉知识库可用 dws wiki 检索,否则跳过并标注「当前端无内部知识库检索能力,已跳过」)
dws wiki search --query "{项目名称} 当前技术架构 技术栈"
dws wiki search --query "{项目名称} 已有组件 中间件 基础设施"
dws wiki search --query "{项目名称} 技术债 已知问题 瓶颈"
A3. 技术调研
目标:调研行业最佳实践、架构模式和候选技术方案,为选型决策提供依据。
调用策略:
# 多角度 WebSearch
WebSearch("{技术场景} 架构设计 最佳实践 {当前年}")
WebSearch("{技术A} vs {技术B} 对比 选型")
WebSearch("{业务场景} 技术方案 大厂实践")
WebSearch("{中间件} 生产环境 踩坑 经验")
# 深度阅读关键文章
WebFetch("https://{技术博客URL}")
典型调研方向:
- 架构模式:微服务 vs 单体、事件驱动 vs 请求驱动、CQRS、Serverless
- 数据存储:MySQL vs PostgreSQL vs TiDB、Redis vs Memcached
- 消息队列:Kafka vs RocketMQ vs Pulsar
- 服务通信:gRPC vs HTTP/REST vs GraphQL
A4. 性能与规模基准
目标:获取候选技术组件的性能基准数据,为容量规划提供依据。
调用策略:
WebSearch("{技术组件} benchmark 性能测试 QPS 延迟")
WebSearch("{数据库} 单表 亿级 性能 分库分表")
WebFetch("https://{官方benchmark报告URL}")
⚠️ 所有性能数字必须标注:测试工具、硬件配置、数据规模、并发数。
A5. 安全与合规
目标:确认安全要求和合规约束,确保技术方案满足安全基线。
调用策略:
WebSearch("{业务场景} 安全 最佳实践 OWASP")
WebSearch("API 安全 鉴权 限流 防护")
# 知识库补充(可选:如已连接钉钉知识库可用 dws wiki 检索,否则跳过并标注「当前端无内部知识库检索能力,已跳过」)
dws wiki search --query "公司安全规范 安全基线要求"
dws wiki search --query "数据分类分级 敏感数据处理规范"
Phase 2 — 结构化分析
基于 Phase 1 素材,进行系统性分析,形成可落地的技术决策。
B1. 需求拆解与优先级
按功能域拆解需求,明确优先级和依赖关系:
P0(必须):影响核心业务流程,上线前必须完成
P1(重要):提升用户体验或运营效率,可分期交付
P2(期望):锦上添花,资源充足时实现
B2. 技术选型评估矩阵
对每个关键技术决策点,建立多维度评估矩阵:
### {技术类别}选型
| 评估维度 | 方案A | 方案B | 方案C | 权重 |
|---------|-------|-------|-------|------|
| 性能 | 优 | 良 | 优 | 25% |
| 运维成本 | 低 | 中 | 高 | 20% |
| 团队经验 | 丰富 | 少量 | 无 | 20% |
| 生态兼容 | 优 | 优 | 良 | 15% |
| 扩展性 | 差 | 良 | 优 | 15% |
| 许可/成本 | 免费 | 免费 | 商业 | 5% |
| **综合得分** | **85** | **72** | **68** | — |
**结论**:选择方案A,理由:...。预留方案C迁移预案,当...时启动评估。
B3. 架构设计原则
明确本方案遵循的设计原则,作为后续模块设计的指导:
- 高内聚低耦合
- 渐进式演进
- 故障隔离
- 数据驱动
- 安全内建
- 可观测性
B4. 关键模块设计
对核心模块进行详细设计:
### 模块A: {名称}
#### 架构图(ASCII)
用户请求 | v API Gateway(鉴权/限流/路由) | v 业务服务A ──────→ MySQL(主数据) | Redis(缓存) v Kafka(异步消息) | v 业务服务B(消费者)
#### 接口设计
POST /api/v1/resource Request: { "field_a": "string", "field_b": 123 } Response: { "code": 0, "data": { "id": "string" } } 错误码: 10001-参数校验失败, 10002-资源不存在
#### 数据模型
表名: t_resource
| 字段 | 类型 | 必填 | 索引 | 说明 |
|---|---|---|---|---|
| id | BIGINT | 是 | PK | 自增主键 |
| biz_id | VARCHAR(64) | 是 | UNI | 业务唯一标识 |
| user_id | BIGINT | 是 | IDX | 用户ID |
| status | TINYINT | 是 | IDX | 0-草稿 1-生效 |
#### 关键逻辑
- 并发控制:Redis 分布式锁,锁粒度为 user_id
- 状态机:草稿 → 审核中 → 已生效 → 已过期
- 幂等设计:基于 biz_id 做幂等校验
B5. 性能与容量估算
### 流量模型
- 日活用户(DAU):XX 万
- 峰值 QPS:XX(按 20% 集中在 2 小时算)
### 资源估算
| 服务 | 实例数 | 配置 | 峰值 CPU | 峰值内存 |
|------|--------|------|---------|---------|
| API 网关 | 3 | 4C8G | 60% | 50% |
| 业务服务 | 6 | 4C8G | 70% | 60% |
| MySQL | 1主2从 | 8C32G | 40% | 60% |
| Redis | 3节点 | 4C16G | 30% | 70% |
B6. 风险评估与降级方案
### 风险清单
| 风险 | 概率 | 影响 | 降级方案 | 负责人 |
|------|------|------|---------|--------|
| 数据库主库宕机 | 低 | 严重 | 自动主从切换,30s 内恢复 | DBA |
| 缓存雪崩 | 中 | 严重 | 多级缓存 + 限流 + 本地缓存兜底 | 后端 |
| 第三方接口超时 | 高 | 中 | 熔断降级,返回缓存数据或默认值 | 后端 |
Phase 3 — 生成方案文档
主 Agent 完成 Phase 1-2 后,先把完整方案内容写入草稿文件,再调用 dws doc create:
dws doc create \
--name "{方案名称} 技术方案" \
--content-file ./draft_tech-solution_{方案名}_{YYYYMMDD_HHMMSS}.md \
--content-format markdown --fix-jsonml -y
报告模板结构:
# {方案名称} 技术方案
> 版本: v1.0 | 作者: @XX | 日期: YYYY-MM-DD
> 状态: 待评审
---
## 方案摘要(TL;DR)
1. **架构选择**:采用 XX 架构,原因是...
2. **核心技术栈**:XX + YY + ZZ
3. **性能目标**:QPS XX,P99 延迟 < XX ms
4. **关键风险**:XX 风险最高,降级方案为...
5. **预计排期**:共 XX 周,分 N 期交付
---
## 一、背景与目标
### 1.1 业务背景
### 1.2 技术目标
### 1.3 成功标准
| 维度 | 指标 | 目标值 | 度量方式 |
|------|------|--------|---------|
| 性能 | 接口 P99 延迟 | < 200ms | APM 监控 |
| 可用性 | 服务可用率 | >= 99.95% | SLA 报表 |
---
## 二、需求与约束
### 2.1 功能需求
### 2.2 非功能需求
### 2.3 约束条件
---
## 三、总体架构
### 3.1 架构图(ASCII)
┌─────────────────┐
用户请求 ──────────────→ │ API Gateway │ │ 鉴权/限流/路由 │ └────────┬────────┘ | ┌─────────────────┼─────────────────┐ v v v ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 业务服务A │ │ 业务服务B │ │ 业务服务C │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ | | | ┌──────▼──────────────────────────────────▼──────┐ │ 数据层 │ │ MySQL(主数据) Redis(缓存) Kafka(消息) │ └─────────────────────────────────────────────────┘
### 3.2 核心组件说明
| 组件 | 职责 | 技术选型 | 部署方式 |
|------|------|---------|---------|
| API Gateway | 统一入口、鉴权、限流 | Kong/Nginx | K8s |
| 业务服务 | 核心业务逻辑 | Go + gRPC | K8s |
| MySQL | 持久化存储 | MySQL 8.0 | 主从集群 |
| Redis | 缓存 + 分布式锁 | Redis 7.0 | 3主3从 |
| Kafka | 异步消息 | Kafka 3.x | 3 Broker |
---
## 四、关键模块设计
(每个模块:职责 + ASCII架构图 + 接口设计 + 数据模型 + 关键逻辑)
---
## 五、技术选型
### 5.1 选型决策
| 决策点 | 方案A | 方案B | 结论 |
|--------|-------|-------|------|
| 数据库 | MySQL 8.0 | PostgreSQL 15 | MySQL 8.0 |
| 缓存 | Redis Cluster | Memcached | Redis Cluster |
| 消息队列 | Kafka | RocketMQ | Kafka |
### 5.2 选型理由(每项说明选择原因和放弃原因)
---
## 六、性能与容量
### 6.1 性能估算
### 6.2 容量规划
### 6.3 压测方案
---
## 七、安全与合规
---
## 八、风险与降级
### 8.1 风险清单
### 8.2 降级层级
---
## 九、实施计划
| 阶段 | 时间 | 交付物 | 负责人 |
|------|------|--------|--------|
| 方案评审 | MM.DD | 评审通过 | TL |
| 开发实现 | MM.DD - MM.DD | 功能代码 | 开发团队 |
| 压测优化 | MM.DD - MM.DD | 压测报告 | SRE |
| 上线发布 | MM.DD | 线上版本 | PM |
意图映射
| 用户说 | 技能解读 | 处理方式 |
|---|---|---|
| 「技术方案」/ 「系统设计」 | 生成完整技术方案文档 | 询问业务目标和约束 |
| 「帮我做技术选型」 | 聚焦技术选型章节 | 收集候选技术后生成选型矩阵 |
| 「架构方案」 | 重点输出架构图和组件说明 | 优先完成架构设计部分 |
| 「技术调研报告」 | 输出调研结果,不含完整方案 | 可选:只输出 A3/A4 内容 |
易混淆场景
| 场景 | 本技能行为 | 注意 |
|---|---|---|
| 用户只提业务目标,无技术细节 | 先搜索内部文档,再外部调研 | 不要直接给出结论 |
| 用户要求生成架构图 | 输出 ASCII 流程图 | 说明悟空平台暂不支持自动生成图片架构图 |
| 用户要求对比 A/B 两种方案 | 生成技术选型评估矩阵 | 覆盖所有评估维度 |
| 性能数据无来源 | 拒绝引用,标注「需补充来源」 | 严禁孤立引用数字 |
错误处理
| 错误情况 | 处理方式 |
|---|---|
| dws doc search 无相关文档 | 标注「未找到内部参考文档」,继续外部调研 |
| WebSearch 无可靠性能数据 | 标注「暂无可靠基准数据,建议内部压测」 |
| dws wiki 无相关信息(或未连接知识库) | 标注「当前端无内部知识库检索能力或无相关记录,已跳过」 |
| dws doc create 失败 | 将完整 Markdown 输出到对话,提示用户手动创建 |
上下文传递表
| 字段 | 来源 | 传递给 |
|---|---|---|
| 方案名称/业务目标 | 用户输入 | 所有搜索关键词 |
| 草稿文件路径 | Phase 1 初始化 | 所有写入步骤 |
| 需求文档内容 | A1 dws doc read | B1 需求拆解 |
| 现有技术栈 | A2 dws wiki | B2 选型矩阵(团队经验维度) |
| 性能基准数据 | A4 WebSearch | B5 容量估算 |
| 安全合规要求 | A5 dws wiki | B6 风险评估 |