什么是元数据？¶

元数据 是附加在工作项（Issue）上、核心字段之外的结构化类型化数据。核心字段涵盖每个工作项都需要的基本信息：主题、状态、负责人、优先级；元数据则用来记录团队关心的其他信息，例如 git 分支、故事点估算、严重程度、发布日期。每条元数据都是一个带名称的 标识（key）加一个类型化的 值（value），由元数据架构定义，因此同一组字段在所有使用它们的工作项上保持一致。

为什么不直接写进描述里？¶

你可以在描述里写上“branch: feature/login, 5 points, severity major”。但元数据更好，因为它是 类型化、结构化 的，而不是自由文本：

• 一致。 所有人用同样的方式填写同样的字段。不会这个工作项写“5 pts”，下一个写“five story points”。
• 可筛选。 工作项列表可以按元数据筛选，你可以一次调出所有 severity = critical 的工作项，或所有涉及某个分支的工作项。描述里的自由文本做不到这一点，至少做不到可靠。
• 有校验。 enum 字段只接受允许的选项；number 字段只接受数字。不符合架构的值，Specivo 一律拒绝，无论它来自工作项页面、REST API 还是 AI 智能体（AI agent）。校验针对的是本次变更写入的内容，而不是工作项已有的值，所以旧值不会把工作项锁死。参见哪些值会被拒绝。

字段类型¶

架构为每个字段定义一种类型，类型决定你能输入什么，以及 Specivo 如何校验。

数组字段用来在同一个标识下记录多个值，例如多个 git 分支、一组标签、一串拉取请求，而不必把它们塞进同一个字符串。

元数据在工作项上如何显示¶

当某个架构应用于工作项时，它的字段会在工作项详情页中单独成一个区域，与核心字段并列显示。填写方式和其他字段一样：输入字符串、选择日期、选取枚举值，或向数组添加项。留空的字段保持为空即可。

下一步¶

• 元数据架构：字段如何分组并绑定到项目和追踪器，以及内置的预设。
• 使用元数据值：设置值、编辑数组字段，以及按元数据筛选工作项列表。