标签 · ZeroWorks 用户指南

标签如何工作

标签是加在对话上的附加标记，和状态最大的区别是它不互斥：一个状态只能选一个，标签可以同时贴多个，也可以一个都不贴。

你可以按项目、主题、优先级或任何自己关心的维度来归类对话，之后按这些维度筛选，就能把相关的一批对话迅速聚到一起。

特性	说明
多选	一条对话可以同时贴多个标签
层级	标签可以嵌套成组，最多 5 层
配色	每个标签以一个彩色圆点呈现
带取值	声明 valueType 后，可带文本、数字、日期或链接值
自动打标	可以用正则规则从消息内容里自动贴标签

按工作区配置

标签按工作区配置，每个工作区各自一套，互不干扰。配置文件放在该工作区目录下的 labels 子目录里。

新建工作区时工作台会写入一份默认标签，可以直接用，也可以整份替换掉：默认包含开发组（代码、缺陷、自动化）、内容组（写作、研究、设计）两个分组，以及优先级、项目两个带取值的标签。

试一试

~/.zero-works/workspaces/{workspace-slug}/labels/config.json

创建标签

最简单的做法是直接编辑配置文件。每个标签包含标识、显示名与颜色，颜色可以写系统语义色名，也可以写区分浅色与深色两套取值的自定义颜色对象。

标识：全小写短横线形式，例如 bug。
显示名：界面上看到的文字，可以随意改。
颜色：系统语义色名或自定义颜色对象，建议先用系统色，需要精确匹配品牌色时再自定义。

试一试

{ "version": 1, "labels": [ { "id": "bug", "name": "缺陷", "color": "destructive" }, { "id": "feature", "name": "功能", "color": "accent" } ] }

valueType	会话示例	约束
未设置	bug	只有存在与否，不保存抽取值
string	project::ZeroWorks	文本值
number	priority::3	手工值使用十进制数字，例如 -1 或 1.5；不使用 high、逗号或科学计数法
date	due::2026-10-30	YYYY-MM-DD 或 YYYY-MM-DDTHH:mm；带时间形式按 UTC 解析
link	docs::https://example.com/guide	保留链接文本；可打开的协议仍受界面安全校验

{ "version": 1, "labels": [ { "id": "bug", "name": "缺陷", "color": "destructive" }, { "id": "priority", "name": "优先级", "valueType": "number" }, { "id": "due", "name": "截止日期", "valueType": "date" }, { "id": "project", "name": "项目", "valueType": "string" }, { "id": "docs", "name": "文档", "valueType": "link" } ] }

层级标签

标签可以嵌套成树：父子关系通过 children 数组表达，数组里的先后顺序就是界面上的显示顺序，不需要额外的排序字段。

最常见的用法是先按团队或领域分组，再在组下面细分具体条目，比如工程下面再分前端与后端。

试一试

{ "version": 1, "labels": [ { "id": "eng", "name": "工程", "color": "info", "children": [ { "id": "frontend", "name": "前端", "children": [{ "id": "react", "name": "React" }] }, { "id": "backend", "name": "后端" } ] }, { "id": "bug", "name": "缺陷", "color": "destructive" } ] }

层级规则

这些约束在保存配置时就会被检查，避免出现两处同名标签导致筛选结果对不上的情况。

标识使用全小写字母、数字与短横线，不使用空格与中文。
标识在整棵树里全局唯一，父子之间也不能重名。
最多嵌套 5 层，再深就会影响侧栏的可读性。
父子关系由 children 数组表达，调整数组顺序就等于调整显示顺序。

自动应用规则

自动规则扫描用户发送的消息文本，不会扫描助手回复、隐藏系统消息或自动读取附件正文。正则同步匹配；语义规则在后台判断，不阻塞当前轮次。

两类规则都会先剥离 Markdown 围栏代码块与行内代码，因此把示例 issue ID 放进代码块不会触发。正则不需要决策模型；语义规则需要独立配置的决策层。

flags 未设置时使用 gi：全局、忽略大小写。显式 flags 仍强制补 g；例如 flags: "g" 可保留区分大小写。
正则每条消息最多新增 10 个去重后的匹配；已有标签或已存在的同值不会重复计入。规则按配置树顺序扫描，达到上限后停止。
带值标签优先使用 valueTemplate；没有模板时，存在捕获组则取第一组，没有捕获组则取整个匹配。没有 valueType 时始终只应用裸 ID。
数字自动抽取会去掉千位逗号、处理常见金额符号与 k/M/B 后缀；日期要由规则直接产生支持的 ISO 格式，不能把任意自然语言日期自动变成有效值。
语义规则需要 decisionLayer.enabled 和 features.semanticLabels。剥离代码并 trim 后不足 20 字符的消息跳过，最多发送前 8000 字符；是概率达到阈值才应用标签。
语义扫描也有最多 10 个匹配的上限。关闭、超时、失败或低于阈值时不新增对应标签；正则规则仍独立运行。

规则字段

规则放在每个标签的 autoRules 数组。下面是可合并到 labels/config.json 的完整结构：issue 抽取议题编号，topic 使用语义判断并保存固定值，bug 只记录存在与否。

pattern：JSON 字符串里的正则；例如 \d 在 JSON 中必须写成 \\d。示例已包含正确转义，复制后不要再多加一层。
flags：可选，默认 gi；运行时总会确保 g 存在。
valueTemplate：正则规则使用 $1、$2 引用捕获组；引用不存在的组会得到空文本，应当用真实消息检查结果。
semantic：不超过 500 字符的是非问题；不能与 pattern 写在同一条规则中。
threshold：语义规则的“是”概率阈值，默认 0.9，必须大于 0 且不大于 1。
value：语义规则的固定字符串值，只在标签有 valueType 时保存；语义规则不能使用 valueTemplate，正则规则也不使用 value。
description：可选的人类说明；autoRules 可有多条规则，普通标签只保留一次存在标记，带值标签可收集多个不同值。

试一试

{ "version": 1, "labels": [ { "id": "issue", "name": "议题", "color": "accent", "valueType": "string", "autoRules": [ { "pattern": "\\b([A-Z]+-\\d+)\\b", "flags": "gi", "valueTemplate": "$1", "description": "从用户正文抽取议题编号" } ] }, { "id": "topic", "name": "主题", "valueType": "string", "autoRules": [ { "semantic": "用户是否在询问账单或发票？", "threshold": 0.9, "value": "billing" } ] }, { "id": "bug", "name": "缺陷", "autoRules": [ { "pattern": "\\bbug\\b" } ] } ] }

校验与排查

修改前备份 labels/config.json。先校验 JSON 与字段，再用一条普通消息检查实际标签结果。读取或解析失败可能回退默认标签，不应依赖始终保留上一份自定义配置。

ID 使用全小写短横线形式，在整棵树内唯一，层级不超过 5 层。
正则必须能编译、flags 合法；避免嵌套量词。捕获组与模板要按实际输入核对，不要把配置检查通过等同于抽取结果正确。
需要抽取值却只出现裸 ID：检查标签是否声明 valueType、模板是否得到空文本，以及值是否符合声明的类型。
语义问题不能为空且最多 500 字符，threshold 必须处于 (0, 1]；确认总开关和 semanticLabels 都已开启并通过 Test。
语义规则不触发时，检查正文剥离代码后是否至少 20 字符、是否位于前 8000 字符、概率是否达到阈值，以及决策服务是否超时。
手工值不合法时更正后重试，例如数字标签用 priority::3，而不是 priority::high；日期按支持的 ISO 格式提交。
颜色使用系统语义色或浅深色对象；筛选父标签时包含子孙是正常行为，不是重复打标。