yuque-group-tech-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tech Design — Technical Design Document Generator (Team)

Tech Design — 技术设计文档生成器（团队版）

Help the user write a structured technical design document following a standard template, then save it to the team's Yuque knowledge base for group review.

帮助用户按照标准模板编写结构化的技术设计文档，随后保存到团队的Yuque知识库供团队评审。

When to Use

适用场景

User wants to write a technical design document or RFC and save it to the group repo
User says "帮我写技术方案到团队库", "write a tech design for the team", "团队技术方案"
User describes a feature/system and needs it formalized into a design doc for group review

用户需要编写技术设计文档或RFC并保存到团队仓库
用户提及「帮我写技术方案到团队库」、「为团队编写技术设计文档」、「团队技术方案」
用户描述某个功能/系统，需要将其正式化为设计文档供团队评审

Required MCP Tools

所需MCP工具

All tools are from the

yuque-mcp

server:

```
yuque_search
```
— (Optional) Search for related existing docs for context
```
yuque_list_repos
```
— Find the target group knowledge base
```
yuque_create_doc
```
— Create the design document

所有工具均来自

yuque-mcp

服务端：

```
yuque_search
```
— （可选）搜索相关现有文档获取上下文
```
yuque_list_repos
```
— 查找目标团队知识库
```
yuque_create_doc
```
— 创建设计文档

Reference

参考资料

The full template is in references/template.md. Load it when generating the document.

完整模板位于references/template.md，生成文档时请加载该模板。

Workflow

工作流

Step 1: Understand the Requirements

步骤1：理解需求

Gather from the user:

Field	Required	Description
项目/功能名称	Yes	What is being designed
背景与问题	Yes	Why this is needed, what problem it solves
目标	Yes	What success looks like
约束条件	No	Technical constraints, timeline, budget
已有方案	No	Any existing approaches or prior art
团队标识 (Group login)	Yes	The team's Yuque group login

If the user provides a brief description, ask clarifying questions:

"这个功能要解决什么问题？"
"有什么技术约束吗？比如必须用某个框架、要兼容现有系统？"
"预期的时间节点是什么？"

If the user hasn't specified a group login, ask: "请告诉我团队的语雀团队标识（group login），我来把技术方案存到团队知识库。"

从用户处收集以下信息：

字段	必填	说明
项目/功能名称	是	设计的对象是什么
背景与问题	是	为什么需要做这个设计，它解决什么问题
目标	是	成功的标准是什么
约束条件	否	技术约束、时间线、预算等
已有方案	否	任何现有方案或先前的同类设计
团队标识 (Group login)	是	团队的Yuque团队标识

如果用户仅提供了简短描述，询问澄清问题：

"这个功能要解决什么问题？"
"有什么技术约束吗？比如必须用某个框架、要兼容现有系统？"
"预期的时间节点是什么？"

如果用户未指定团队标识，询问："请告诉我团队的语雀团队标识（group login），我来把技术方案存到团队知识库。"

Step 2: (Optional) Search for Context

步骤2：（可选）搜索上下文

If relevant, search Yuque for related existing documents:

Tool: yuque_search
Parameters:
  query: "<related keywords>"
  type: "doc"

This helps:

Avoid duplicating existing designs
Reference prior decisions
Understand the current architecture

如果有相关内容，在Yuque中搜索相关现有文档：

Tool: yuque_search
Parameters:
  query: "<相关关键词>"
  type: "doc"

这有助于：

避免重复设计现有方案
参考过往决策
理解当前架构

Step 3: Generate the Design Document

步骤3：生成设计文档

Load the template from

references/template.md

and fill in each section based on the user's input and your technical analysis.

Key sections to fill:

背景 (Background) — Problem statement, current situation
目标 (Goals) — What this design achieves, non-goals
方案设计 (Design) — The core technical approach
- Architecture diagram description (describe in text/ASCII if needed)
- Core components and their responsibilities
- Data model / API design
- Key flows (sequence of operations)
技术选型 (Tech Stack) — Why specific technologies were chosen
方案对比 (Alternatives) — Other approaches considered and why they were rejected
排期 (Timeline) — Milestones and estimated effort
风险评估 (Risks) — What could go wrong and mitigation strategies
参考资料 (References) — Related docs, links, prior art

从

references/template.md

加载模板，根据用户输入和你的技术分析填充每个章节。

需要填充的核心章节：

背景 (Background) — 问题描述、当前现状
目标 (Goals) — 本设计要实现的内容，非目标
方案设计 (Design) — 核心技术思路
- 架构图描述（如有需要可用文本/ASCII图描述）
- 核心组件及其职责
- 数据模型 / API设计
- 核心流程（操作顺序）
技术选型 (Tech Stack) — 选择特定技术的原因
方案对比 (Alternatives) — 考虑过的其他方案以及被否决的原因
排期 (Timeline) — 里程碑和预估工作量
风险评估 (Risks) — 可能出现的问题及缓解策略
参考资料 (References) — 相关文档、链接、先前的同类设计

Step 4: Review with User

步骤4：与用户评审

Present the draft to the user before saving. Ask:

"方案内容是否准确？有需要调整的地方吗？"
"要补充其他技术细节吗？"

保存前将草稿展示给用户，询问：

"方案内容是否准确？有需要调整的地方吗？"
"要补充其他技术细节吗？"

Step 5: Save to Team Yuque

步骤5：保存到团队Yuque

Tool: yuque_list_repos
Parameters:
  login: "<group_login>"
  type: "group"

Find or ask for the target group repo (often "技术方案" or "设计文档" or "RFC").

Tool: yuque_create_doc
Parameters:
  repo_id: "<namespace>"    # e.g., "my-team/tech-docs"
  title: "[技术方案] <项目名称>"
  body: "<formatted design document>"
  format: "markdown"

Tool: yuque_list_repos
Parameters:
  login: "<group_login>"
  type: "group"

找到或询问用户目标团队仓库（通常是「技术方案」、「设计文档」或「RFC」）。

Tool: yuque_create_doc
Parameters:
  repo_id: "<namespace>"    # 例如："my-team/tech-docs"
  title: "[技术方案] <项目名称>"
  body: "<格式化后的设计文档>"
  format: "markdown"

Step 6: Confirm

步骤6：确认结果

markdown

✅ 技术方案已创建（草稿状态）！

📄 **[[技术方案] 项目名称](文档链接)**
📚 已保存到：「团队知识库名称」

markdown

✅ 技术方案已创建（草稿状态）！

📄 **[[技术方案] 项目名称](文档链接)**
📚 已保存到：「团队知识库名称」

文档结构

背景与目标
方案设计（含 X 个核心模块）
技术选型对比
排期（预计 X 周）
风险评估（X 个风险点）

💡 文档为草稿状态，请团队评审后发布。

undefined

背景与目标
方案设计（含 X 个核心模块）
技术选型对比
排期（预计 X 周）
风险评估（X 个风险点）

💡 文档为草稿状态，请团队评审后发布。

undefined

Guidelines

使用规范

Write the design doc in Chinese (default) unless the user specifies English
Be specific in the design section — include data models, API signatures, flow descriptions
For tech stack comparison, use a table with pros/cons
Keep the document actionable — someone should be able to implement from this doc
If the user's requirements are vague, make reasonable assumptions and note them clearly with "【假设】" markers
Don't over-engineer — match the design complexity to the project scope
Always end the confirmation with "请团队评审后发布" — group designs need review
This skill saves to group repos — for personal repos, use the
```
tech-design
```
skill in the
```
yuque-personal
```
plugin

默认使用中文编写设计文档，除非用户指定用英文
设计章节内容要具体——包含数据模型、API签名、流程描述
技术选型对比使用带优缺点的表格呈现
保证文档可落地——其他人可以根据该文档进行实现
如果用户需求模糊，做出合理假设并使用「【假设】」标记明确标注
不要过度设计——设计复杂度要匹配项目范围
确认信息末尾始终附上「请团队评审后发布」——团队设计文档需要评审
本技能存储到团队仓库——如果是个人仓库，请使用
```
yuque-personal
```
插件中的
```
tech-design
```
技能

Error Handling

错误处理

Situation	Action
User provides very vague requirements	Ask 2-3 targeted questions before generating
`yuque_search` finds conflicting existing designs	Mention them and ask user how to reconcile
`yuque_create_doc` fails	Show error, offer to output the markdown for manual copy
User wants to update an existing design doc	Use `yuque_search` to find it, then suggest creating a v2 or appendix
Group login not provided	Ask user for the team's group login
Team Token not configured	Inform user that group repos require a team-level Token

场景	处理方式
用户提供的需求非常模糊	生成前提出2-3个针对性问题询问
`yuque_search` 找到存在冲突的现有设计	告知用户并询问如何协调
`yuque_create_doc` 调用失败	展示错误信息，提供markdown格式内容供用户手动复制
用户想要更新现有设计文档	使用 `yuque_search` 找到对应文档，建议创建v2版本或附录
未提供团队标识	询问用户的团队group login
未配置团队Token	告知用户团队仓库需要团队级Token