Back to Details

azure-typespec-author

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Azure TypeSpec Author

Azure TypeSpec 编写工具

MCP Prerequisites

MCP 前置条件

Requires 
azure-sdk-mcp
server with TypeSpec authoring and validation tools.
需要配备TypeSpec编写和验证工具的
azure-sdk-mcp
服务器。

MCP Tools

MCP 工具

ToolPurpose
azsdk_typespec_generate_authoring_plan
Generate grounded authoring plan
azsdk_run_typespec_validation
Validate TypeSpec compilation + lint
工具名称用途
azsdk_typespec_generate_authoring_plan
生成基于实际情况的编写计划
azsdk_run_typespec_validation
验证TypeSpec编译及代码检查结果

Principles

原则

  1. Mandatory for ALL 
    .tsp
    edits     — even a single 
    ?
    change can be breaking.
  2. Minimal, scoped edits — only change what the request requires.
  3. Always validate — run 
    azsdk_run_typespec_validation
    after every edit.
  4. Always cite references — provide links that justify the approach.
  1. 所有.tsp文件编辑必须遵循——即使是单个
    ?
    的修改也可能导致破坏性变更。
  2. 最小化、范围明确的编辑——仅修改请求要求的内容。
  3. 始终执行验证——每次编辑后运行
    azsdk_run_typespec_validation
    。
  4. 始终引用参考资料——提供证明方法合理性的链接。

Task Classification

任务分类

Classify every request into exactly one of the two types below before proceeding.
  • API Version Evolution = adding a brand-new API version string (e.g. 
    2025-06-01-preview
    ) to the service. This is only about creating a new version entry and carrying over / excluding features. It is not about adding 
    @added
    /
    @removed
    decorators to individual properties or operations within an existing version — that falls under General Authoring.
  • General Authoring = everything else that modifies 
    .tsp
    files.
TypeDescriptionExamples
API Version Evolution (ARM only)Adding a new preview or stable API version to an existing ARM service. Data-plane API version evolution is not fully supported yet."Add a new preview API version 2026-01-01-preview for widget resource manager"
General AuthoringAny other TypeSpec authoring task that modifies 
.tsp
files		"Add an ARM resource named Asset with CRUD operations"
在开始处理前，需将每个请求准确归类为以下两种类型之一。
  • API版本演进 = 为服务添加全新的API版本字符串（例如
    2025-06-01-preview
    ）。这仅涉及创建新版本条目以及保留/排除功能，不包括在现有版本的单个属性或操作中添加
    @added
    /
    @removed
    装饰器——此类操作属于通用编写。
  • 通用编写 = 所有其他修改.tsp文件的操作。
类型描述示例
API版本演进（仅ARM）为现有ARM服务添加新的预览版或稳定版API版本。数据平面API版本演进目前尚未完全支持。"为Widget资源管理器添加新的预览版API版本2026-01-01-preview"
通用编写所有其他修改.tsp文件的TypeSpec编写任务"添加一个名为Asset的ARM资源并支持CRUD操作"

Steps

步骤

All tasks follow a 5-step workflow. Steps 2–3 branch by task type; the rest are shared.
  1. Analyze Project — Follow the project analysis guide to collect project context and determine task type.
  2. Intake & Clarification
    • API Version Evolution: determine the versioning scenario from Step 1, use agentic search in the document with the scenario URL below to collect information from user. Be sure to use a user-friendly way to collect required inputs from user. e.g., list the existing features (resources, operations, properties) from the latest version and then ask the user which to carry over or exclude, instead of asking for raw input.
      LatestTargetURL to fetch
      previewpreview
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/02-preview-after-preview/
      previewstable
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/03-stable-after-preview/
      stablepreview
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/04-preview-after-stable/
      stablestable
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/05-stable-after-stable/
    • General Authoring: follow intake guide.
  3. Retrieve Solution
    • API Version Evolution: search the downloaded guide content for implementation steps via agentic search and generate solution. No MCP tool call needed.
    • General Authoring: invoke 
      azsdk_typespec_generate_authoring_plan
      MCP tool with the following parameters:
      ParameterValue
      request
      		User request (verbatim)
      additionalInformation
      		All content gathered from Steps 1–2 (intake analysis, user answers, relevant 
      .tsp
      code read from the project)
      typeSpecProjectRootPath
      		TypeSpec project root path
      Do not proceed without a grounded plan from this tool.
  4. Apply Changes — Confirm uncertainties with user, make minimal 
    .tsp
    edits, prefer official templates from retrieved context.
  5. Validate — Follow the validation guide.
所有任务均遵循五步工作流。步骤2-3根据任务类型分支，其余步骤为通用步骤。
  1. 分析项目 — 遵循项目分析指南收集项目上下文并确定任务类型。
  2. 需求收集与澄清
    • API版本演进: 从步骤1确定版本场景，使用智能搜索在下方对应场景的URL文档中收集用户信息。请确保采用用户友好的方式收集所需输入，例如列出最新版本的现有功能（资源、操作、属性），然后询问用户保留或排除哪些，而非直接要求原始输入。
      当前版本目标版本获取URL
      previewpreview
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/02-preview-after-preview/
      previewstable
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/03-stable-after-preview/
      stablepreview
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/04-preview-after-stable/
      stablestable
      https://azure.github.io/typespec-azure/docs/howtos/versioning/arm/05-stable-after-stable/
    • 通用编写: 遵循需求收集指南。
  3. 获取解决方案
    • API版本演进: 通过智能搜索在下载的指南内容中查找实现步骤并生成解决方案。无需调用MCP工具。
    • 通用编写: 使用以下参数调用
      azsdk_typespec_generate_authoring_plan
      MCP工具：
      参数名称取值
      request
      		用户请求（原文）
      additionalInformation
      		步骤1-2中收集的所有内容（需求收集分析、用户回答、从项目中读取的相关.tsp代码）
      typeSpecProjectRootPath
      		TypeSpec项目根路径
      在未获取该工具生成的基于实际情况的计划前，请勿继续。
  4. 应用变更 — 与用户确认不确定的内容，进行最小化的.tsp文件编辑，优先使用从参考内容中获取的官方模板。
  5. 验证 — 遵循验证指南