lazycat-sdk-dev

name: lazycat-sdk-dev description: Use when building LazyCat SDK integrations in Go/JS, WebShell frontend features, notifications, MCP providers, MCP gateway aggregation, Skill/MCP resource discovery, dynamic MCP tool lists, import_resources/resource_exports, .lzcx app access, or user-delegated LazyCat app-to-app calls.

LazyCat SDK 开发

协助开发者使用官方 SDK 与 LazyCat 微服务系统交互。

支持语言

即将支持：Rust、Dart、Cpp、Java、Python、Ruby、C#、PHP、Objective-C、Kotlin。

参考文档

开发工作流

Phase 1: 环境初始化

输入: 开发环境已准备（Go/Node.js） 输出: SDK 已安装，可调用 API Gateway

Step 1.1: 安装 SDK

# Go 项目
go get gitee.com/linakesi/lzc-sdk/lang/go

# JavaScript/TypeScript 项目
npm install @lazycatcloud/sdk

Step 1.2: 创建 API Gateway

Go:

gw, err := gohelper.NewAPIGateway(ctx)
if err != nil {
    return err  // ⚠️ 检查点：创建失败时返回错误，不要继续
}
defer gw.Close()  // ✅ 必须关闭！

JavaScript:

const api = new lzcAPIGateway(window.location.origin, false)

Phase 2: 业务开发

输入: API Gateway 已创建 输出: 完成用户/设备/应用管理等功能

Step 2.1: 确定需求类型

Step 2.2: 添加用户上下文（HTTP Handler 必须）

⚠️ 检查点: 如果是 HTTP Handler，必须传递用户上下文

可用 Headers:

示例:

// Gin 框架示例
userID := c.GetHeader("x-hc-user-id")        // 必须是小写
userRole := c.GetHeader("x-hc-user-role")

// 添加到 gRPC context (metadata key 必须小写)
ctx = metadata.AppendToOutgoingContext(ctx,
    "x-hc-user-id", userID,
    "x-hc-user-role", userRole,
)

Step 2.3: 编写业务代码

参考 常用示例 或具体参考文档。

Phase 3: 错误处理与测试

输入: 业务代码完成 输出: 稳定运行，错误有 fallback

Step 3.1: 添加超时控制

推荐超时值:

示例:

// 查询类操作
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()

// 状态变更类操作
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

Step 3.2: 处理 SDK 错误

result, err := gw.Service.Method(ctx, &Request{...})
if err != nil {
    // ⚠️ 检查点：记录日志，返回 fallback 响应
    log.Printf("SDK call failed: %v", err)
    return fallbackValue
}

快速开始

Go SDK

import (
    "context"
    gohelper "gitee.com/linakesi/lzc-sdk/lang/go"
    "gitee.com/linakesi/lzc-sdk/lang/go/common"
)

func main() {
    ctx := context.TODO()

    gw, err := gohelper.NewAPIGateway(ctx)
    if err != nil {
        panic(err)
    }
    defer gw.Close()

    // 查询用户信息
    userInfo, _ := gw.Users.QueryUserInfo(ctx, &common.UserID{Uid: "lazycat"})
    fmt.Println("User:", userInfo.Nickname)

    // 列出设备
    devices, _ := gw.Devices.ListEndDevices(ctx, &common.ListEndDeviceRequest{Uid: "lazycat"})
    for _, d := range devices.Devices {
        fmt.Printf("Device: %s, Online: %v\n", d.Name, d.IsOnline)
    }
}

JavaScript SDK

import { lzcAPIGateway } from "@lazycatcloud/sdk"

const api = new lzcAPIGateway(window.location.origin, false)
const apps = await api.pkgm.QueryApplication({ appidList: [] })
console.log("Applications:", apps.infoList)

MCP / Skill 资源

最小 provider 导出：

# lzc-build.yml
resource_exports:
  - kind: mcp-providers
    source: ./resources/mcp-providers

# resources/mcp-providers/<provider-id>/mcp.yml
endpoint: /mcp

MCP endpoint 推荐使用 Streamable HTTP：POST /mcp。如果应用需要同时支持 LazyCat 内部访问和外部客户端，使用双认证：

• LazyCat 模式：只在明确环境开关开启时信任 X-HC-User-ID / X-HC-SOURCE 等平台 header。
• 外部模式：使用用户级 Authorization: Bearer <token>，token 只保存 hash，明文只返回一次。

动态工具聚合：

• 对每个启用 provider 建 MCP client，执行 Initialize + ListTools。
• 将上游工具名改写为 <provider_slug>__<tool_name>，避免冲突。
• 调用聚合工具时还原上游原始工具名并转发 arguments。
• provider 不可达时保留本地 tools，不要让整个 /mcp 失效。

详见 references/mcp-resources.md。

核心 API 概览

Go SDK 服务

核心模式

// 1. 创建 API Gateway
gw, err := gohelper.NewAPIGateway(ctx)
if err != nil {
    return err
}
defer gw.Close()  // 必须关闭！

// 2. 调用 SDK 方法
result, err := gw.Service.Method(ctx, &Request{...})

HTTP Handler 中的用户上下文

LazyCat 通过 HTTP headers 注入用户信息：

// 从 headers 提取
userID := c.GetHeader("x-hc-user-id")
userRole := c.GetHeader("x-hc-user-role")

// 添加到 gRPC context
ctx = metadata.AppendToOutgoingContext(ctx, "x-hc-user-id", userID)

可用 Headers:

常用示例

1. 查询已安装应用

resp, _ := gw.PkgManager.QueryApplication(ctx, &sys.QueryApplicationRequest{})
for _, app := range resp.InfoList {
    if app.Status == sys.AppStatus_Installed {
        fmt.Println("App:", app.Appid)
    }
}

2. 启动/暂停应用

// 启动
gw.PkgManager.Resume(ctx, &sys.AppInstance{
    Appid: appID,
    Uid:   userID,
})

// 暂停
gw.PkgManager.Pause(ctx, &sys.AppInstance{
    Appid: appID,
    Uid:   userID,
})

3. 控制 LED

// 获取当前状态
boxInfo, _ := gw.Box.QueryInfo(ctx, nil)
fmt.Println("LED on:", boxInfo.PowerLed)

// 切换 LED
gw.Box.ChangePowerLed(ctx, &common.ChangePowerLedRequest{
    PowerLed: !boxInfo.PowerLed,
})

4. 关机/重启

// 重启
gw.Box.Shutdown(ctx, &common.ShutdownRequest{
    Action: common.ShutdownRequest_Reboot,
})

// 关机
gw.Box.Shutdown(ctx, &common.ShutdownRequest{
    Action: common.ShutdownRequest_Poweroff,
})

前端客户端能力

LazyCat iOS/Android 客户端为 WebShell 内运行的前端应用注入了丰富的原生能力。

环境判断

import base from "@lazycatcloud/sdk/dist/extentions/base"

const isIOS = base.isIosWebShell()
const isAndroid = base.isAndroidWebShell()
const isClient = isIOS || isAndroid

能力矩阵概览

AppCommon 快速示例

import { AppCommon } from "@lazycatcloud/sdk/dist/extentions"

// 打开其他应用
await AppCommon.LaunchApp(url, "cloud.lazycat.app.photo")

// 进入全屏
await AppCommon.SetFullScreen()

// 分享文件
await AppCommon.ShareWithFiles("/path/to/file.pdf")

系统通知快速示例

import { lzcAPIGateway } from "@lazycatcloud/sdk"
import base from "@lazycatcloud/sdk/dist/extentions/base"

const api = new lzcAPIGateway(window.location.origin, false)

// ⚠️ 检查点：非 WebShell 环境跳过
if (base.isIosWebShell() || base.isAndroidWebShell()) {
  try {
    const device = await api.currentDevice
    // ⚠️ 检查点：确认 notification 能力可用
    if (device?.notification?.Notify) {
      await device.notification.Notify({
        title: "任务完成",
        body: "导入任务已经处理完成",
        deeplinkUrl: "lzc://app/cloud.lazycat.app.demo",
      })
    }
  } catch (err) {
    console.error("[notification] send failed:", err)
  }
}

⚠️ 前置条件：package.yml 需声明 user.notify 权限（lzcos >= v1.6.0）

❌ 不要做：

• 不要在非 WebShell 环境直接调用（device.notification 为 undefined）
• 不要高频循环推送（系统可能限流）
• 不要把通知当数据同步通道（仅用于用户感知提醒）

详见 references/frontend-extensions.md

扩展模块

minidb（类 MongoDB 数据库）

import { Minidb } from "@lazycatcloud/minidb"
const db = new Minidb("myapp")

await db.insert({ name: "item1" })
await db.find({ name: "item1" })
await db.update({ name: "item1" }, { $set: { value: 200 } })
await db.remove({ name: "item1" })

文件选择器

import { pickFiles } from "@lazycatcloud/lzc-file-pickers"

const files = await pickFiles({
  multiple: true,
  accept: [".pdf", ".doc"]
})

错误处理与边界条件

常见错误场景

边界条件处理

MCP / Skill 反例黑名单

Fallback 模式示例

func queryDevices(ctx context.Context, uid string) ([]Device, error) {
    // 边界条件：空用户ID
    if uid == "" {
        return []Device{}, nil
    }

    gw, err := gohelper.NewAPIGateway(ctx)
    if err != nil {
        // Fallback: 返回空列表而非失败
        return []Device{}, fmt.Errorf("gateway unavailable: %w", err)
    }
    defer gw.Close()

    ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
    defer cancel()

    resp, err := gw.Devices.ListEndDevices(ctx, &common.ListEndDeviceRequest{Uid: uid})
    if err != nil {
        // Fallback: 返回空列表，记录日志
        log.Printf("device query failed: %v", err)
        return []Device{}, nil
    }

    // 边界条件：空设备列表
    if resp.Devices == nil {
        return []Device{}, nil
    }

    return resp.Devices, nil
}

前端能力可用性检查

import base from "@lazycatcloud/sdk/dist/extentions/base"
import { AppCommon } from "@lazycatcloud/sdk/dist/extentions"

// ⚠️ 检查点：调用原生能力前必须判断环境
const isClient = base.isIosWebShell() || base.isAndroidWebShell()

if (isClient) {
    // 安全调用原生能力
    await AppCommon.SetFullScreen()
} else {
    // Fallback: 浏览器兼容方案
    document.documentElement.requestFullscreen()
}

最佳实践

1. 总是关闭 API Gateway: defer gw.Close()
2. 添加用户上下文: metadata.AppendToOutgoingContext(ctx, "x-hc-user-id", userID)
3. 优雅处理错误: SDK 调用可能失败，提供 fallback
4. 复用连接: 每次操作创建一个 gateway，而非每次调用
5. 使用超时: context.WithTimeout(ctx, 10*time.Second)

参考资料

• 官方文档: https://developer.lazycat.cloud
• SDK 仓库: https://gitee.com/linakesi/lzc-sdk
• npm 包: https://www.npmjs.com/search?q=%40lazycatcloud