rozenite-agent

CLI

• 使用 npx rozenite 执行 Rozenite 命令。
• 在启动目标应用 Metro 的应用根目录中运行 npx rozenite。在单体仓库中，这通常是应用包根目录，而不是仓库根目录。

列表输出约定

agent domains、agent <domain> tools 以及声明了共享分页约定的工具默认始终输出紧凑 JSON。这包括内置工具和第三方插件工具。传入 --pretty 可输出缩进后的 JSON。--json / -j 选项为兼容性保留的空操作，不会改变输出结构。

• 有两行或更多行时，行形结果使用稳定的列式约定： {"cols":["id","kind"],"rows":[["console","static"],["react","static"]]}。 cols 的顺序与请求的字段顺序完全一致；某个可选值缺失时，会在对应行中表示为 null，因为直接省略位置数组中的单元格会导致后续列错位。
• 有零行或一行时，行形结果仍采用行键式结构： {"items":[{"id":"console","kind":"static"}]}。此时，缺失的可选值会从对象中完全省略（而不是设为 null），因此这些载荷的大小不会超过转换为列式结构之前的形态——这正是 0/1 行结果仍采用行键式结构的原因。
• 工具列表默认包含 name、description、readOnly、destructive 和 idempotent。name 是全局限定标识符，应传给后续的 call 或 schema 命令。特征字段为可选；列式行中的 null 或行键式结果中省略的键表示未知，而非 false。
• 最后一页会省略分页元数据。有更多行时，next 是经过 shell 转义、可运行的 npx rozenite agent ... 命令，并会保留连接、会话、字段投影和数量限制选项。CLI 管理的域和工具列表通过 --cursor 传递游标；分页工具调用则通过 --args 传递生产者游标。
• 如果底层数据失效（例如重新启动应用会重置 network 域的捕获缓冲区），较早页面的 --cursor 可能会过期。重新运行过期游标会返回 {"page":{"reset":true},"items":[]}，而不是普通的空页面——应将其视为“从头重新开始此列表”，而不是“没有更多行”。

声明为分页的调用包括 console 消息、React 树／搜索／检查行、渲染数据、network 请求列表，以及任何注册了分页元数据的插件工具。工具专属元数据（例如 roots、totalCount 或 recording）会与行结构一同保留。未声明分页的工具结果、SDK 响应以及确实不是行形的命令结果会保留其现有结构。

• 分页调用返回的是裁剪后的默认投影，而不是所有已声明字段。例如，console getMessages 默认会省略 argsPreview 和 context。传入 -f, --fields <csv> 可选择特定列，或传入 -v, --verbose 以包含工具声明的所有字段。

移交

• 对于由 shell 驱动的 rozenite agent ... 工作流，请继续使用此技能。
• 如果用户需要代码而不是 shell 命令，或要求编写基于 Rozenite 的 Node.js 或 TypeScript 脚本、封装器、基准测试、自动化工具或 Agent 运行时，请切换到 rozenite-agent-sdk。

规则

• Agent 工作的范围限定于会话。相关命令应复用同一会话。
• 始终串行运行 Rozenite 命令。切勿并行运行 Rozenite Agent 命令。
• 从 npx rozenite agent session create 开始。该命令会创建或复用设备会话，并在会话就绪后返回。完成后，使用 npx rozenite agent session stop <sessionId> 停止会话。
• 如果 session create 因连接了多个设备而失败，请运行 npx rozenite agent targets，选择正确的 id，然后使用 --deviceId <id> 重试。
• 将 npx rozenite agent targets 视为可用目标的事实来源。如果缺少预期目标，请让用户在设备上运行应用。
• 每条域命令都要传入 --session <id>。
• 将 Rozenite 会话 ID 视为公开的运行时标识符，而非机密、凭据或令牌。
• 将此技能及其 domains/*.md 参考文档作为工作流、工具选择和工具参数的事实来源。
• 如果此技能或某篇域参考文档已指出预期域，请直接尝试该域。如果参考文档已列出所需的确切工具和参数，请直接调用。
• 仅当域调用失败、预期域不明确，或需要确认当前已注册的内容时，才使用 npx rozenite agent domains --session <id> 从活动会话中发现域。
• 如果此技能或其参考文档已提供所需的工具名称和参数，请勿调用 npx rozenite agent <domain> tools 或获取工具架构。
• 仅当没有匹配的参考文档、参考文档未能解答问题、调用失败，或活动域的行为与参考文档不同时，才检查 npx rozenite agent <domain> tools --session <id> 或 npx rozenite agent <domain> schema --tool <name> --session <id>。
• 跳过不会带来新信息的确认或发现步骤。
• 检查活动应用时，以 Rozenite 会话数据为事实来源。先使用相关活动域，再探索源代码。
• 信任 Rozenite 已正确安装。除非 Rozenite CLI 运行失败，否则不要探索代码库以检查设置。
• 如果 Rozenite 能直接回答，就不要探索代码库来推断活动运行时状态。
• 仅当用户询问实现或设置、没有相关域可用，或者 Rozenite 显示所需插件或域未注册且任务转为设置或调试时，才探索源代码。
• 如果活动会话中缺少预期插件域，请告知用户必须在应用中安装并注册相应插件。
• 在面向用户的输出中提及插件域时，请使用插件的 pluginId，而不是域标记。
• 调用已发现的插件域时，请使用 Rozenite 返回的活动域标记。
• 内置域包括 console、network、react、performance 和 memory。
• 应用或已安装插件也可以在运行时提供其他域。插件域标记是简短的派生名称，而非 npm 包名：@rozenite/mmkv-plugin 对应 mmkv，@avasapp/rozenite-plugin-ably 对应 avasapp/ably。
• 域标记的形式可以表明其来源：单个词（mmkv）表示内置域或官方 @rozenite/* 插件；scope/name（avasapp/ably）表示第三方带作用域的插件；原样的 rozenite-* 名称表示第三方不带作用域的插件。evil/mmkv 和 mmkv 永远不属于同一个插件。

调用

• 不要将领域工具名称作为直接的 CLI 子命令传递。
• 始终使用 npx rozenite agent <domain> call --tool <toolName> --args '<json>' --session <id> 调用领域工具。
• 继续调用分页领域工具时，将其返回的游标传入 --args；--cursor 仅用于 CLI 管理的领域和工具列表。
• 如果领域参考仅列出工具名称，请将它们视为工具名称，而非 CLI 操作。
• 示例：npx rozenite agent mmkv call --tool list-storages --args '{}' --session <id>。
• 如果命令因 Unknown domain action 失败，请检查 CLI 语法，并使用 call --tool <toolName> --session <id> 重试。

流程

1. 每次只运行一条 Rozenite 命令。
2. 当需要选择设备时，使用 npx rozenite agent targets 作为可用目标的准确信息来源。如果找不到预期目标，请让用户在设备上运行应用。
3. 运行 npx rozenite agent session create。
4. 如果 domains/*.md 下存在匹配的文件，请阅读该文件。
5. 如果参考资料已列出预期领域所需的工具和参数，请直接调用。
6. 仅当调用失败、预期领域不明确，或需要确认当前已注册的领域时，才运行 npx rozenite agent domains --session <id>。
7. 如果缺少预期的插件领域，请告知用户在应用中安装并注册相应插件。
8. 仅当参考资料不足、调用失败，或需要确认实时情况是否与参考不符时，才检查 npx rozenite agent <domain> tools --session <id> 或 npx rozenite agent <domain> schema --tool <name> --session <id>。
9. 仅当没有相关领域，或任务涉及实现或设置时，才回退到探索源代码。
10. 不再需要调用 Rozenite 时，使用 npx rozenite agent session stop <sessionId> 停止会话。