标签

使用彩色标签和结构化元数据组织会话

标签是可以应用到会话的可叠加彩色标签。与状态（互斥 —— 每个会话一个）不同，标签支持多选 —— 一个会话可以拥有零个或多个标签。它们支持通过嵌套树进行分层组织。

标签如何工作#

标签让你按项目、主题、优先级或其他任意维度对对话进行分类 —— 方便以后过滤并查找相关会话。

工作区级配置#

标签按工作区配置。每个工作区初始没有标签 —— 你可以创建所需的标签。配置存储于：

~/.xiantong/workspaces/{workspace-id}/labels/config.json

创建标签#

只需询问你的 Agent。 创建标签最简单的方式是描述你需要什么：

• “创建一个红色的 Bug 标签”
• “在 Engineering 组下添加 Alpha 和 Beta 项目标签”
• “设置一个带数字值的 Priority 标签”

Agent 会自动处理配置。

你也可以通过编辑配置文件手动创建标签。

基本示例#

{
"version": 1,
"labels": [
{
"id": "bug",
"name": "Bug",
"color": "destructive"
},
{
"id": "feature",
"name": "Feature",
"color": "accent"
}
]
}

分层标签#

标签形成嵌套树。父/子关系通过 children 数组表达。数组顺序决定显示顺序。

{
"version": 1,
"labels": [
{
"id": "eng",
"name": "Engineering",
"color": "info",
"children": [
{
"id": "frontend",
"name": "Frontend",
"children": [
{ "id": "react", "name": "React", "color": { "light": "#3B82F6", "dark": "#60A5FA" } }
]
},
{ "id": "backend", "name": "Backend" }
]
},
{ "id": "bug", "name": "Bug", "color": "destructive" }
]
}

这会在侧边栏显示为一个树状结构：

Engineering
|- Frontend
| \- React
\- Backend
Bug

层级规则#

• ID 是简单的 slug（小写字母数字 + 连字符）
• ID 必须在整棵树中全局唯一
• 最大嵌套深度：5 层
• 数组顺序 = 显示顺序（无需 order 字段）
• 按父级过滤会包含所有子孙会话

标签属性#

每个标签对象支持以下属性：

颜色#

标签在 UI 中显示为彩色圆点。你可以使用系统颜色或自定义十六进制值。

系统颜色#

使用语义颜色名称表示常见含义：

系统颜色也支持透明度："accent/80"、"info/50" 等。

自定义颜色#

为精准控制，可使用明暗模式配色对：

{
"color": { "light": "#6366F1", "dark": "#818CF8" }
}

支持十六进制、OKLCH、RGB 和 HSL 格式。

对子标签使用自定义颜色对象可以获得精确的颜色控制。将系统颜色保留给顶层类别。

标签值#

标签可以选带一个值和特定类型。这让标签成为结构化元数据 —— 例如，一个带值 3 的“priority”标签，或一个带日期的“due”标签。

存储格式#

会话将标签存储为字符串数组。布尔标签仅 ID，带值标签使用 :: 分隔符：

{
"labels": ["bug", "priority::3", "due::2026-01-30", "linear::CRA-456"]
}

• 布尔标签："bug" —— 仅表示存在，无值
• 带值标签："priority::3" —— ID 与值之间用 :: 分隔
• 仅在第一次出现 :: 时拆分（值中可以包含 ::）

值类型#

值在解析时根据原始字符串推断：

推断顺序： 先检查 ISO 日期 -> 再检查数字 -> 最后字符串回退。配置中的 valueType 仅供 UI 提示 —— 解析器总是根据原始值推断类型。

侧边栏行为#

标签以多层可展开区域显示在左侧栏。点击标签会筛选会话列表，仅显示匹配的会话。点击父标签会包括所有子孙标签的会话。

验证#

每次修改配置后都要验证。

编辑配置文件后，请执行验证以捕捉错误：

config_validate({ target: "labels" })

验证器会检查：

• 有效的 JSON 与递归结构
• 整棵树中 ID 全局唯一
• 有效的 slug 格式（小写字母数字 + 连字符）
• 最大嵌套深度（5 层）

与状态的主要差异#