DiAL/openspec/specs/target-identity/spec.md at c51bc5a0d8ebc26120c833b1bbaaa574453eab2e

Files

lanyuanxiaoyao 31fd3a2a43 refactor: 统一 target name/description 可空语义，前端展示 fallback 到 id

- schema: name/description 允许省略或显式 null，TypeBox Union([Null, String])
- 类型: RawTargetConfig/ResolvedTargetBase/子类型/StoredTarget/TargetStatus name 改为 string | null
- checker resolve: name: t.name ?? null，不再 fallback 到 id
- 语义校验: 拒绝空字符串和纯空白 name
- SQLite: targets.name 列改为可空 TEXT
- 前端: 新增 getTargetDisplayName(target) 展示 name ?? id
- 测试: 覆盖 name/description null 全场景，查找改为按 id
- 文档: 更新 README/DEVELOPMENT 和 6 个 openspec specs

2026-05-17 20:12:39 +08:00

5.4 KiB

Raw Blame History

Purpose

定义 target 的 id/name 双字段标识体系：id 作为唯一标识符，name 作为可选展示名称。

Requirements

Requirement: target id 字段

每个 target SHALL 包含必填的 id 字段作为唯一标识符。id SHALL 符合 [a-zA-Z0-9][a-zA-Z0-9_-]* 命名规则。id 长度 MUST 为 1 到 30 个字符。id MUST 在所有 targets 中全局唯一。id MUST NOT 参与变量替换。

Scenario: 合法 id

WHEN target 配置 id: "api-health"
THEN 系统 SHALL 使用该 id 作为 target 的唯一标识符

Scenario: id 包含下划线和连字符

WHEN target 配置 id: "db_check-01"
THEN 系统 SHALL 使用该 id 作为 target 的唯一标识符

Scenario: id 缺失报错

WHEN target 未配置 id 字段
THEN 系统 SHALL 以配置错误退出，提示该 target 缺少 id 字段

Scenario: id 为空字符串报错

WHEN target 配置 id: ""
THEN 系统 SHALL 以配置错误退出，提示 id 不能为空

Scenario: id 超过最大长度报错

WHEN target 配置超过 30 个字符的 id
THEN 系统 SHALL 以配置错误退出，提示 id 长度不合法

Scenario: id 不合法报错

WHEN target 配置 id: "_invalid" 或 id: "-start" 或 id: "has space"
THEN 系统 SHALL 以配置错误退出，提示 id 不符合命名规则

Scenario: id 重复报错

WHEN 两个 target 配置相同的 id: "api-health"
THEN 系统 SHALL 以配置错误退出，提示 id 重复

Requirement: target name 字段

每个 target SHALL 支持可选的 name 字段作为展示名称元信息。name 缺省或显式配置为 null 时 SHALL 在配置解析、运行时模型、存储和 API 中保留为 null。前端展示目标名称时 SHALL 使用 name ?? id，但该 fallback MUST NOT 改变 target 本身的 name 值。显式配置的 name MUST 为长度 1 到 30 个字符的字符串，且去除首尾空白后 MUST 不为空。name SHALL 支持变量替换。name MUST NOT 要求全局唯一，MUST NOT 参与 target 唯一性判定。

Scenario: 配置 name

WHEN target 配置 id: "api-health" 和 name: "API 健康检查"
THEN 系统 SHALL 在解析后保留 name 为 "API 健康检查"

Scenario: name 使用变量

WHEN target 配置 name: "${env} API 健康检查" 且 variables 中 env: "生产"
THEN 系统 SHALL 将 name 解析为 "生产 API 健康检查"

Scenario: name 缺省保留为 null

WHEN target 配置 id: "api-health" 但未配置 name
THEN 系统 SHALL 在解析、存储和 API 响应中保留 name 为 null

Scenario: name 显式 null

WHEN target 配置 id: "api-health" 和 name: null
THEN 系统 SHALL 接受该配置，并在解析、存储和 API 响应中保留 name 为 null

Scenario: name 空 YAML 值

WHEN target 配置 id: "api-health" 且 name: 后不提供值
THEN 系统 SHALL 将该 name 按 null 处理，并接受该配置

Scenario: name 为 null 时展示 fallback

WHEN 前端展示 name 为 null 的 target
THEN 前端 SHALL 显示该 target 的 id 作为目标名称文案

Scenario: name 为空字符串报错

WHEN target 配置 name: ""
THEN 系统 SHALL 以配置错误退出，提示 name 不能为空

Scenario: name 仅包含空白字符报错

WHEN target 配置 name: " "
THEN 系统 SHALL 以配置错误退出，提示 name 不能为空

Scenario: name 超过最大长度报错

WHEN target 配置超过 30 个字符的 name
THEN 系统 SHALL 以配置错误退出，提示 name 长度不合法

Scenario: 多个 target 使用相同 name

WHEN 两个 target 配置不同 id 但相同 name: "健康检查"
THEN 系统 SHALL 接受该配置，不报错（name 不要求全局唯一）

Requirement: target description 字段

每个 target SHALL 支持可选的 description 字段作为目标说明。description 缺省或显式配置为 null 时 SHALL 在配置解析、运行时模型、存储和 API 中保留为 null。description SHALL 支持变量替换。description 字符串长度 MUST 不超过 500 个字符，且允许为空字符串。description MUST NOT 参与 target 唯一性判定。

Scenario: 配置 description

WHEN target 配置 description: "检查生产 API 健康状态"
THEN 系统 SHALL 使用该值作为目标说明

Scenario: description 使用变量

WHEN target 配置 description: "${env} 环境健康检查" 且 variables 中 env: "生产"
THEN 系统 SHALL 将目标说明解析为 "生产环境健康检查"

Scenario: description 缺省

WHEN target 未配置 description
THEN 系统 SHALL 接受该配置，且目标说明为 null

Scenario: description 显式 null

WHEN target 配置 description: null
THEN 系统 SHALL 接受该配置，且目标说明为 null

Scenario: description 空 YAML 值

WHEN target 配置 description: 后不提供值
THEN 系统 SHALL 将该 description 按 null 处理，并接受该配置

Scenario: description 为空字符串

WHEN target 配置 description: ""
THEN 系统 SHALL 接受该配置，且目标说明为空字符串

Scenario: description 超过最大长度报错

WHEN target 配置超过 500 个字符的 description
THEN 系统 SHALL 以配置错误退出，提示 description 长度不合法

5.4 KiB Raw Blame History Unescape Escape