SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场tech-design

tech-design

办公与效率

查看项目

更新于 10-16 08:54

技能介绍

用途

Tech Design 是一个团队版技术设计文档生成器。它帮助用户按照标准模板撰写结构化的技术设计文档（RFC），并将生成的内容保存到团队语雀知识库中，供团队评审。

适用时机

  • 用户想要撰写技术设计文档或 RFC，并保存到团队仓库。
  • 用户表达类似「帮我写技术方案到团队库」「write a tech design for the team」「团队技术方案」的意图。
  • 用户描述了一个功能或系统，需要将其正式化为设计文档以便团队评审。

主要能力

该技能依赖 yuque-mcp 服务器提供的以下工具：

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

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

使用方式

第一步：理解需求

从用户处收集以下信息：

字段 是否必填 说明
项目/功能名称 是 正在设计的内容
背景与问题 是 为什么需要、解决什么问题
目标 是 成功的样子
约束条件 否 技术约束、时间线、预算
已有方案 否 已有做法或先例
团队标识 (Group login) 是 团队的语雀 group login

如果用户提供的是简要描述，应提出澄清问题，例如：

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

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

第二步：（可选）搜索上下文

如有需要，可在语雀中搜索相关的现有文档：

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

这有助于避免与现有设计重复、引用先前的决策、了解当前架构。

第三步：生成设计文档

从 references/template.md 加载模板，根据用户输入和技术分析填写各章节。需填写的主要章节包括：

  • 背景 (Background) — 问题陈述、现状
  • 目标 (Goals) — 本设计达成什么、非目标
  • 方案设计 (Design) — 核心技术方案
    • 架构图描述（必要时用文本/ASCII 描述）
    • 核心组件及其职责
    • 数据模型 / API 设计
    • 关键流程（操作序列）
  • 技术选型 (Tech Stack) — 为何选择特定技术
  • 方案对比 (Alternatives) — 考虑过的其他方案及被否原因
  • 排期 (Timeline) — 里程碑与预估工作量
  • 风险评估 (Risks) — 可能出什么问题及缓解策略
  • 参考资料 (References) — 相关文档、链接、先例

第四步：与用户评审

保存前将草稿呈现给用户，询问：

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

第五步：保存到团队语雀

先查找知识库：

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

找到或询问目标团队仓库（常见命名如「技术方案」「设计文档」或「RFC」）。

再创建文档：

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

第六步：确认

完成后的确认格式示例：

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

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

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

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

指导原则

  • 默认用中文撰写设计文档，除非用户指定英文。
  • 方案设计部分要具体，包含数据模型、API 签名、流程描述。
  • 技术栈对比使用表格，列出优缺点。
  • 保持文档可执行，让他人能够依此实现。
  • 若用户需求模糊，做合理假设并用「【假设】」标记注明。
  • 不要过度设计，让设计复杂度与项目范围匹配。
  • 确认信息始终以「请团队评审后发布」结尾，团队设计需要评审。
  • 该技能保存到团队仓库；个人仓库请使用 yuque-personal 插件中的 tech-design 技能。

错误处理

情况 处理方式
用户提供非常模糊的需求 生成前先问 2-3 个针对性的问题
yuque_search 发现冲突的现有设计 指出并询问用户如何协调
yuque_create_doc 失败 显示错误，提议输出 markdown 供手动复制
用户想更新现有设计文档 用 yuque_search 找到它，然后建议创建 v2 或附录
未提供 group login 向用户询问团队的 group login
未配置团队 Token 告知用户团队仓库需要团队级 Token

适用场景

  • 团队内部需要撰写技术方案、RFC 或设计文档。
  • 需要将功能或系统构想标准化为可评审的文档。
  • 希望文档保存到语雀团队知识库并接受团队评审。

限制

  • 依赖 yuque-mcp 服务器及其工具。
  • 保存到团队仓库需要配置团队级 Token。
  • 需要用户提供团队的 group login。
  • 文档创建后为草稿状态，需团队评审后发布。
  • 个人仓库场景需使用 yuque-personal 插件中的同类技能。