rozenite-agent-sdk

Rozenite Agent SDK

当用户需要以代码优先的方式通过 Rozenite 访问 Agent 时，使用此技能。

查看 references/code-patterns.md，获取可直接复制粘贴的示例。

规则

• 优先使用导入 @rozenite/agent-sdk 的一次性 Node ESM 脚本。
• 默认流程：createAgentClient() -> client.withSession(...) -> 检查或调用工具 -> 退出。
• 使用 session.domains.list() 作为实时内置域和运行时域的事实来源。
• 仅在需要实时检查或确认参数时，使用 session.tools.list({ domain }) 和 session.tools.getSchema({ domain, tool })。
• 优先使用任何可用官方插件 ./sdk 导出中的类型化插件 SDK 描述符，并通过 session.tools.call(descriptor, args) 调用工具。
• 仅当没有匹配的 ./sdk 描述符，或工具是在运行时动态发现时，才回退到 session.tools.call({ domain, tool, args })。
• 通过 session.tools.list({ domain }) 发现工具时，将返回的 shortName 视为后续按名称调用时必须使用的规范工具名称。不要自行编造 camelCase 别名或规范化工具名称。
• 优先使用稳定的 SDK 域标识符，例如内置域 ID（network、react、memory）和插件 ID（@rozenite/storage-plugin、@rozenite/tanstack-query-plugin），而不是衍生出的面向 CLI 的域标记（如 storage）。
• 对于分页工具，每次只调用一次，并在下一次调用中明确传入返回的 page.nextCursor。分页封装和游标由插件负责。
• 如果插件仅在导航后挂载，请先导航，然后使用 session.domains.list() 或 session.tools.list(...) 刷新实时视图，再调用插件工具。
• 如需使用 client.openSession() 或 client.attachSession(sessionId) 进行高级会话控制，请参阅参考模式。
• 如果脚本遇到意外的运行时错误，应让脚本明确失败。不要通过打印占位 JSON 来掩盖失败。

移交

• 当任务由 Shell 驱动、需要可复用的 CLI 会话、直接通过 rozenite agent ... 操作，或要求在选择 deviceId 前枚举目标时，改用 rozenite-agent。