使用元数据值¶

元数据架构应用到工作项（Issue）后，就可以填写其中的元数据字段了。本页介绍如何查看和设置值、编辑列表（数组）字段，以及按元数据筛选工作项列表。

查看元数据¶

打开任意工作项。元数据字段在工作项详情页上有自己的区域，与核心字段并列显示。尚未填写的字段显示为空。

每个字段都带有 名称。在架构中定义了标题的字段，会在工作项页面、工作项历史记录、搜索筛选、REST API 和 MCP 中显示该标题（支持多语言）。没有标题的字段，则显示由键名转换成的可读名称（story_points 显示为“Story Points”）。通过导入带入的字段保留它们在旧系统中的名称。

保存 成员 或 版本 的字段显示的是该成员或版本的名称，而不是内部 ID，前提是你有权查看它们；否则显示存储的原始值。

设置值¶

编辑工作项，按字段类型填写：

• 字符串：输入文本（例如 component = Backend）。
• 数字 / 整数：输入数值（例如 story_points = 5）。
• 日期：在日期选择器中选一个日期。
• 枚举：从字段的固定选项列表中选择一项（例如 severity = major）。

Specivo 会边填边校验：枚举字段只接受允许的选项，数字字段拒绝非数字输入。保存工作项即可存储这些值。

哪些值会被拒绝¶

保存时，Specivo 会根据工作项的架构检查值，并拒绝不匹配的值：数字字段里的文字、不在列表中的选项、不符合字段模式的列表项、架构不允许的键。工作项页面、REST API（返回 422，错误码为 validation_error，字段为 metadata.<key>）和 AI 智能体（其元数据工具会返回指明字段的错误）都执行同样的检查。在元数据面板中，提示信息显示在 保存元数据 旁边，你的修改会保留下来，方便改正。

新建工作项时，还必须填写架构中标记为 必填 的所有字段。

Specivo 检查的是本次改动，而不是整个工作项。 只有本次保存改动的字段才会被检查：

• 已有值不再匹配架构的工作项（比如架构后来收紧了，或者值来自导入）仍然可以编辑。你可以修改它的状态、其他字段和其他元数据。
• 修改、追加或删除保存了这种值的字段会被拒绝，直到该字段符合架构为止。对列表来说，这也包括在旧的无效项仍在时追加一个有效项：需要把整个列表改正确。
• 删除必填字段会被拒绝；旧工作项缺少必填字段则不会被拒绝。
• 把工作项移到其他项目或追踪器时，不会重新检查保持不变的值。

重复任务的值在保存重复模板时检查，因此即使架构之后发生变化，它的工作项仍会继续创建。

要找出值不符合架构的工作项，管理员可以在服务器上运行 python -m specivo.cli.admin metadata-check（加上 --project KEY 只检查一个项目）。它按架构列出工作项和字段名，不会显示值，也不会修改任何内容。参见升级。

编辑数组字段¶

数组 字段保存一组值：多个分支、几个标签、一批拉取请求。逐个添加项，不再需要的项可以随时删除。例如，branches 字段一开始可能只有 main，随着工作分散到多个分支，变成 main、feature/login。数组字段可以和工作项上的其他字段任意搭配使用，没有限制。

按元数据筛选工作项列表¶

跨工作项搜索时，元数据的价值就体现出来了。工作项列表可以用“键 = 值”匹配 按元数据筛选：

• 选择元数据键，再选择要匹配的值。例如 severity = critical 只看严重缺陷，或 content_status = draft 找出所有仍在草稿状态的内容。
• 对 数组 字段，只要数组 包含 该值即匹配。按 feature/login 筛选 branches，会返回所有分支列表中包含 feature/login 的工作项，即使它们还列出了其他分支。

这就是元数据相对于自由文本的优势：值有类型且保持一致，所以筛选结果正好是你想要的那些工作项。

你也可以直接从任意工作项进入按元数据筛选的搜索。当工作项有 数组 类型的元数据值（例如 branches 或 tags 字段）时，每个值都会在工作项元数据中显示为 可点击的标签。点击标签会打开一个搜索，在 你有权访问的所有项目 中筛选同一个值。这样不必从项目列表开始，就能快速找到带有某个分支、标签或类别的全部内容。