xiantong 文档
状态

自定义状态

添加自定义状态并修改现有状态

只需向你的 Agent 说明即可。 自定义状态最简单的方式就是描述你的需求：

  • “添加一个红色的阻塞状态”
  • “为暂停的对话创建一个等待状态”
  • “在进行中和完成之间添加一个复审状态”

Agent 会自动处理相应配置。

你也可以通过编辑工作区的状态配置文件手动自定义状态。

配置文件#

状态配置存储在：

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

配置架构#

配置文件具有以下结构：

{
"version": 1,
"statuses": [
{
"id": "todo",
"label": "Todo",
"category": "open",
"isFixed": true,
"isDefault": false,
"order": 0
}
],
"defaultStatusId": "todo"
}

状态属性#

每个状态对象支持以下属性：

属性类型必需描述
idstring是唯一标识符（仅小写字母和连字符）
labelstring是UI 中显示的名称
category"open" | "closed"是决定属于收件箱还是归档
isFixedboolean是如果为 true，则不能删除或更改名称
isDefaultboolean是如果为 true，则不能删除但可以修改
ordernumber是显示顺序（数值越小越靠前）
colorstring否十六进制颜色（例如 "#EF4444"）或 Tailwind 类
iconstring否表情符号（例如 "🔥"）或图标文件的 URL

如果省略 color，将使用设计系统的默认值。若省略 icon，应用会在 statuses/icons/{id}.{ext} 下查找自动识别的文件（支持 .svg、.png、.jpg、.jpeg）。

添加自定义状态#

要添加像 “Blocked” 或 “Waiting” 这样的自定义状态，只需在 statuses 数组中添加一个新对象：

{
"id": "blocked",
"label": "Blocked",
"color": "#EF4444",
"icon": "🚫",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 3
}

如有需要，请调整其他状态的 order 值以确保新状态位于正确位置。

示例：添加多个自定义状态#

{
"version": 1,
"statuses": [
{
"id": "backlog",
"label": "Backlog",
"category": "open",
"isFixed": false,
"isDefault": true,
"order": 0
},
{
"id": "todo",
"label": "Todo",
"category": "open",
"isFixed": true,
"isDefault": false,
"order": 1
},
{
"id": "in-progress",
"label": "In Progress",
"icon": "🔄",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 2
},
{
"id": "blocked",
"label": "Blocked",
"color": "#EF4444",
"icon": "🚫",
"category": "open",
"isFixed": false,
"isDefault": false,
"order": 3
},
{
"id": "waiting",
"label": "Waiting",
"category": "open",
"icon": "⏳",
"isFixed": false,
"isDefault": false,
"order": 4
},
{
"id": "needs-review",
"label": "Needs Review",
"category": "open",
"isFixed": false,
"isDefault": true,
"order": 5
},
{
"id": "done",
"label": "Done",
"category": "closed",
"isFixed": true,
"isDefault": false,
"order": 6
},
{
"id": "cancelled",
"label": "Cancelled",
"category": "closed",
"isFixed": true,
"isDefault": false,
"order": 7
}
],
"defaultStatusId": "todo"
}

自定义图标#

图标可以通过多种方式配置：

基于文件的图标（推荐）

将 SVG 文件放在 statuses/icons/ 目录下，文件名以状态 ID 命名：

statuses/icons/blocked.svg
statuses/icons/waiting.svg

这些文件会自动被识别——无需配置。

表情符号图标

将 icon 属性设置为表情符号：

"icon": "🔥"

简单快捷，适用于所有场景。

URL 图标

提供图标文件的 URL：

"icon": "https://example.com/icon.svg"

图标会自动下载并缓存到本地。

SVG 图标指南#

创建自定义 SVG 图标时：

  • 大小：24x24 像素
  • 使用 currentColor 作为描边/填充，支持主题
  • stroke-width：2
  • stroke-linecap：round
  • stroke-linejoin：round

更改颜色#

设置 color 属性来自定义状态外观：

{
"id": "blocked",
"label": "Blocked",
"color": "#EF4444",
...
}

可使用：

  • 十六进制颜色："#EF4444"、"#22C55E"
  • Tailwind 类："text-red-500"、"text-green-500"

固定状态#

以下状态不可删除或重命名：

ID固定原因
todo新对话的默认状态
done完成工作的必需关闭状态
cancelled放弃工作的必需关闭状态

你仍然可以自定义它们的 color 和 icon 属性。

验证#

修改配置后务必验证配置。

编辑配置文件后，运行验证以在问题发生前捕获错误：

config_validate({ target: "statuses" })

验证器会检查：

  • 强制状态（todo、done、cancelled）是否存在
  • 状态 ID 没有重复
  • defaultStatusId 是否指向已存在的状态
  • 每个类别（open 和 closed）至少有一个状态
  • 所引用的图标文件是否存在

无效配置在运行时会回退到默认值，但验证能帮助提早发现问题。

上一页状态