# Wukong Doc Technical Solution

> 触发词：「技术方案」「系统设计」「架构方案」「技术选型」。 围绕业务目标与约束，输出架构设计、关键模块、技术选型、风险与实施计划的完整技术方案， 最终生成结构清晰的钉钉在线文档。

- Skill: `ahang1598/wukong-doc-technical-solution` (Agent Skill)
- Install (CLI): `npx get-skill add ahang1598/wukong-doc-technical-solution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/wukong-doc-technical-solution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ahang1598 (https://skillmd.com/u/ahang1598)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/ahang1598/wukong-doc-technical-solution

---


# 技术方案

围绕业务目标与约束，系统性调研内部文档、外部技术资料与行业最佳实践，输出架构设计、关键模块、技术选型、性能估算、风险预案的完整技术方案文档，直接生成钉钉在线文档。

---

## 禁止事项

- 禁止以对话文本替代钉钉在线文档作为最终交付物
- 禁止在有钉钉原生工具可用时跳过内部文档检索直接使用外部搜索
- 禁止编造性能数据、技术选型结论或风险评估结果
- 禁止孤立引用性能数字（必须标注测试条件：硬件配置、数据规模、并发数等）
- 禁止绕过钉钉工具直接构造 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 "{项目名称} 非功能需求 性能 可用性 安全"
```

**写入草稿**（追加模式）：
```markdown
## 需求理解

### 业务背景
- 业务痛点：...
- 项目目标：...

### 功能需求
| 需求编号 | 需求描述 | 优先级 | 来源 |
|---------|---------|--------|------|
| 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. 技术选型评估矩阵

对每个关键技术决策点，建立多维度评估矩阵：

```markdown
### {技术类别}选型
| 评估维度 | 方案A | 方案B | 方案C | 权重 |
|---------|-------|-------|-------|------|
| 性能 | 优 | 良 | 优 | 25% |
| 运维成本 | 低 | 中 | 高 | 20% |
| 团队经验 | 丰富 | 少量 | 无 | 20% |
| 生态兼容 | 优 | 优 | 良 | 15% |
| 扩展性 | 差 | 良 | 优 | 15% |
| 许可/成本 | 免费 | 免费 | 商业 | 5% |
| **综合得分** | **85** | **72** | **68** | — |

**结论**：选择方案A，理由：...。预留方案C迁移预案，当...时启动评估。
```

### B3. 架构设计原则

明确本方案遵循的设计原则，作为后续模块设计的指导：
1. 高内聚低耦合
2. 渐进式演进
3. 故障隔离
4. 数据驱动
5. 安全内建
6. 可观测性

### B4. 关键模块设计

对核心模块进行详细设计：

```markdown
### 模块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. 性能与容量估算

```markdown
### 流量模型
- 日活用户（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. 风险评估与降级方案

```markdown
### 风险清单
| 风险 | 概率 | 影响 | 降级方案 | 负责人 |
|------|------|------|---------|--------|
| 数据库主库宕机 | 低 | 严重 | 自动主从切换，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
```

**报告模板结构**：

```markdown
# {方案名称} 技术方案

> 版本: 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 风险评估 |

---
