状态配置

会话状态代表工作流状态。每个工作区都有自己的状态配置。

存储位置

• 配置文件: ~/.tentarc/workspaces/{id}/statuses/config.json
• 图标: ~/.tentarc/workspaces/{id}/statuses/icons/

默认状态

注意: 颜色是可选的。如果省略，将使用设计系统默认值。

颜色格式

颜色使用 EntityColor 类型——可以是系统颜色字符串或自定义颜色对象。

系统颜色

通过 CSS 变量自动适配浅色/深色主题，无需十六进制值。

添加 /opacity（整数 0–100）可设置透明度："foreground/50"、"info/80"。

自定义颜色

使用明确的 CSS 颜色值对象来定义浅色和深色主题：

{ "light": "#EF4444", "dark": "#F87171" }

如果省略 dark，将从 light 自动推导（亮度提高约 30%）。

light/dark 值支持的 CSS 颜色格式：

常见错误

• 纯颜色名称（"red"、"blue"）不受支持——请使用十六进制或系统颜色
• Tailwind 类名（"text-red-500"）无效——请直接使用系统颜色名称
• 不带 # 前缀的十六进制（"EF4444"）无效——必须包含 #
• 系统颜色透明度必须是 0–100 的整数（"foreground/50" 而非 "foreground/0.5"）

状态类型

• 固定（isFixed: true）：不能删除或重命名。必需的状态：todo、done、cancelled。
• 默认（isDefault: true）：随应用一起提供，可以修改但不能删除。
• 自定义（isFixed: false, isDefault: false）：用户创建，可完全编辑和删除。

分类系统

• open：会话显示在收件箱/活动列表中
• closed：会话显示在归档/已完成列表中

config.json 结构

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

注意: icon 字段是可选的。默认状态使用从 statuses/icons/{id}.svg 自动发现的 SVG 文件。

状态属性

图标配置

图标解析优先级：

1. 本地文件 - 从 statuses/icons/{id}.svg（或 .png、.jpg、.jpeg）自动发现
2. 表情符号 - 如果 icon 字段是表情符号字符串（如 "🔥"）
3. 后备方案 - 如果找不到图标则使用圆点字符

基于文件的图标（推荐用于默认状态）：

• 将 SVG 放在 statuses/icons/{status-id}.svg
• 无需配置 - 根据状态 ID 自动发现
• 示例：状态 ID blocked 对应 statuses/icons/blocked.svg

表情符号图标（快速简便）：

"icon": "🔥"

URL 图标（自动下载）：

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

URL 会自动下载到 statuses/icons/{id}.{ext}。

⚠️ 图标来源规则：

• 推荐 按照以下指南生成自定义 SVG 文件
• 推荐 从网络下载图标（如 Heroicons、Feather、Simple Icons）
• 推荐 使用表情符号作为快速、通用的图标

添加自定义状态

编辑工作区的 statuses/config.json：

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

或使用自定义十六进制颜色：

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

根据需要调整现有状态的 order 值。

SVG 图标指南

• 尺寸：24x24
• 使用 currentColor 作为描边/填充颜色（支持主题）
• stroke-width: 2
• stroke-linecap: round
• stroke-linejoin: round

自修复机制

• 缺失的图标文件会从内嵌默认值自动重建
• 会话上的无效状态 ID 会回退到 todo
• 损坏的配置会重置为默认值

验证

重要：创建或编辑状态后务必进行验证：

config_validate({ target: "statuses" })

验证内容包括：

• 必需的固定状态存在（todo、done、cancelled）
• 没有重复的状态 ID
• defaultStatusId 引用的是已存在的状态
• 引用的图标文件存在
• 每个分类（open/closed）至少有一个状态

无效配置在运行时会回退到默认值，但验证可以在问题产生影响之前发现它们。