Go SDK | Nuva SDK

本预览版本供接口评估与集成规划使用。API 和数据结构可能在正式发布前调整。

NewClient · 初始化

使用客户级服务凭证创建 Nuva 客户端。服务地址内置在 SDK 中。

client, err := nuva.NewClient(nuva.ClientConfig{
    ServiceToken: os.Getenv("NUVA_SERVICE_TOKEN"),
})
if err != nil {
    return err
}

参数	类型	说明
`ServiceToken`	`string`	客户级 Nuva 服务凭证，仅保存在后端。

返回：Nuva 客户端与 error。配置无效时返回错误。

示例使用 nuva 作为 Go SDK 包别名。客户端用于调用 Nuva 服务，用户登录验证及应用路由由现有后端处理。

CreateClientToken · 申请用户 token

在应用完成用户认证后，传入已验证的用户 ID 和权限声明，为该用户申请 Nuva token。

grant, err := client.CreateClientToken(ctx, nuva.ClientTokenRequest{
    UserID:      authenticatedUser.ID,
    Permissions: permissions,
})
if err != nil {
    return err
}

// 将 grant.Token 和 grant.ExpiresAt 返回给前端。

参数

type ClientTokenRequest struct {
    UserID      string          `json:"userId"`
    Permissions json.RawMessage `json:"permissions"`
}

字段	说明
`UserID`	客户内的用户唯一标识，来自已验证的登录会话。
`Permissions`	服务端提供的权限声明。技能使用权限属于该声明；具体字段结构尚未定稿。

permissions 表示调用方的权限声明，示例不定义其 JSON 内容。Nuva 校验客户服务凭证及申请范围后签发用户 token。

返回值

type ClientToken struct {
    Token     string    `json:"token"`
    ExpiresAt time.Time `json:"expiresAt"`
}

返回 ClientToken 与 error。身份参数、权限校验或服务请求失败时返回错误。应用后端将 token 和到期时间交给前端，前端使用该 token 与 Nuva 通信。

RegisterSkill · 注册自定义技能

提交 Markdown 使用说明及可选的 hostCall 定义，将技能保存到当前客户名下。

instructions, err := os.ReadFile("./SKILL.md")
if err != nil {
    return err
}

skill, err := client.RegisterSkill(ctx, nuva.SkillDefinition{
    Name:         "vidmuse-workspace",
    Instructions: string(instructions),
    HostCalls:    hostCalls,
})
if err != nil {
    return err
}

// skill.Ref.ID 和 skill.Ref.Revision 标识已保存的技能定义。

参数与返回类型

type SkillDefinition struct {
    Name         string               `json:"name"`
    Instructions string               `json:"instructions"`
    HostCalls    []HostCallDefinition `json:"hostCalls,omitempty"`
}

type HostCallDefinition struct {
    Type         string          `json:"type"`
    Description  string          `json:"description"`
    InputSchema  json.RawMessage `json:"inputSchema"`
    OutputSchema json.RawMessage `json:"outputSchema,omitempty"`
}

type RegisteredSkill struct {
    Ref DefinitionRef `json:"ref"`
}

type DefinitionRef struct {
    ID       string `json:"id"`
    Revision string `json:"revision"`
}

字段	说明
`Name`	技能名称。
`Instructions`	Markdown 使用说明。
`HostCalls`	可选的网站交互定义。处理函数保留在应用中。
`HostCalls[].Type`	方法名称，对应客户端调用中的 toolName。
`InputSchema`	方法输入的 JSON Schema。
`OutputSchema`	可选的结果 JSON Schema。提供时需要回传结果；省略时不要求结果。

返回：RegisteredSkill 与 error。Ref 提供已保存定义的 ID 和版本。定义校验、注册权限或服务请求失败时返回错误。

技能注册使用客户后端的服务凭证。用户是否可使用该技能由 Permissions 授权范围决定，注册不自动授予所有用户使用权限。

Go 类型与调用示例