deepseek-harness/packages/util/brand/README.zh.md

dsh-brand

English | 中文

Branded<B> 名义类型原语：一个微小的仅类型 包（无运行时代码，无 harness 包依赖），由每个拥有跨边界 id 的包共享。

Branded 是什么

品牌使 SessionId 和 CallId 这样结构相同的字符串在类型层面不可互换，尽管两者在运行时都是普通 string。

import type { Branded } from '@deepseek-ai/dsh-brand'

export type SessionId = Branded<'SessionId'>

/** Brand a string as a SessionId (a plain cast — zero runtime cost). */
export function SessionId(id: string): SessionId {
  return id as SessionId
}

构造操作通过所属包中针对每个 id 的工厂完成。比较、日志记录、JSON 序列化和协议格式与普通字符串表现相同；品牌会在编译时被擦除。

策略：为跨包边界的 id 添加品牌

包为自己拥有的 id 添加品牌：CallId 位于 dsh-llm，共享的 agent/会话 SessionId 位于 dsh-session，TaskId 位于 dsh-tasks。为可能被混淆的跨包 id 添加品牌，但无需为每个字符串都添加。

该包只负责原语。保持无依赖意味着，例如 dsh-tasks 可以为 TaskId 添加品牌，而无需仅为使用 Branded 而导入不相关的功能包。