@aixnn/aixautots 0.0.0-stage → 0.5.2

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# @aixnn/aixautots
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+发布包已迁移到 npm 用户 `aixnn` 的 scope，完整包名为 `@aixnn/aixautots`。本仓库目录仍为 `aixautots/`，各子包入口保持不变，例如 `@aixnn/aixautots/core`。
+
+```sh
+npm install @aixnn/aixautots
+```
+
+发布（在 `aixautots/` 目录，使用有权限的 npm 账号）：
+
+```sh
+npm run typecheck
+npm test
+npm run build
+python3 ../scripts/npm-with-access-key.py publish --access public
+```
+
+发布脚本读取 `~/.aixenv` 的 `NPM_ACCESS_KEY`，通过临时 npm 配置使用令牌，结束后删除临时配置，不修改全局登录配置。令牌需拥有 `@aixnn/aixautots` 的发布权限；第三方项目也可使用自身 npm 凭据执行 `npm publish --access public`。若令牌未允许绕过双重验证，npm 仍可能要求一次性验证码。
+
+aixautobot 的 TypeScript 客户端 SDK。core/react 是 headless 的数据/传输/鉴权层；ui 既提供细粒度
+部件，也提供**开箱即用的成品页面**（设备/任务/市场/脚本/编辑器/检查器）+ 一套可换肤主题，
+让任意项目都能"轻松接入"。桌面端 `frontend/` 是全量改用本 SDK 的参考实现。
+
+子路径导出：
+
+| 子包 | 职责 |
+|---|---|
+| `@aixnn/aixautots/core` | 资源 REST 客户端（`AixClient`）+ 会话层（设备通道 / Flow / 镜像）+ 类型 + 错误 |
+| `@aixnn/aixautots/react` | 上述能力的 React hooks（`AixProvider` + 资源/会话 hooks） |
+| `@aixnn/aixautots/ui` | 设备向细粒度部件（`MirrorView`/`ControlBar`/`ScriptEditor`/`DebugConsole`/`ScriptPanel`） |
+| `@aixnn/aixautots/ui/primitives` | 基础件（`Button`/`Input`/`Select`/`Badge`/`Dialog`/`Popover`） |
+| `@aixnn/aixautots/ui/{devices,tasks,market,scripts,editor,inspector}` | 成品页面组件 |
+| `@aixnn/aixautots/nav` | 路由无关导航注入（`AixNavProvider`/`useAixNav`） |
+| `@aixnn/aixautots/i18n` | 内置 i18n（`AixI18nProvider`/`useAixT`，en/zh，无 i18next 依赖） |
+| `@aixnn/aixautots/tailwind-preset` · `@aixnn/aixautots/styles.css` | Tailwind 预设 + 主题 token |
+
+```bash
+npm i @aixnn/aixautots   # peer: react（react 子包用）；ui 子包另需 @uiw/react-codemirror
+```
+
+## 接入（三步）
+
+用到 `@aixnn/aixautots/ui` 的成品页面/部件时，按以下三步接入样式与运行时上下文：
+
+**1) 样式** —— Tailwind 预设 + 主题 token + content 扫描：
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require('@aixnn/aixautots/tailwind-preset')],
+  content: [
+    './src/**/*.{ts,tsx}',
+    './node_modules/@aixnn/aixautots/dist/**/*.js', // 关键：否则 aixautots 组件的类名不会被生成
+  ],
+}
+```
+
+```css
+/* 入口 CSS */
+@import "@aixnn/aixautots/styles.css";   /* :root 浅色 + .dark 深色 token，可覆盖换肤 */
+```
+
+**2) Provider** —— 在 `AixProvider` 内注入导航与语言：
+
+```tsx
+import { AixProvider } from '@aixnn/aixautots/react'
+import { AixNavProvider } from '@aixnn/aixautots/nav'
+import { AixI18nProvider } from '@aixnn/aixautots/i18n'
+import { useNavigate } from 'react-router-dom' // 任意路由库都行
+
+function Providers({ children }) {
+  const navigate = useNavigate()
+  return (
+    <AixProvider config={{ baseUrl, auth }}>
+      <AixNavProvider nav={{ navigate }}>
+        <AixI18nProvider lang="zh">{children}</AixI18nProvider>
+      </AixProvider>
+    </AixNavProvider>
+  )
+}
+```
+
+**3) 用页面** —— 直接挂成品页面，路由参数以 props 传入：
+
+```tsx
+import { DevicesPage } from '@aixnn/aixautots/ui/devices'
+import { ScriptEditorPage } from '@aixnn/aixautots/ui/editor'
+
+<DevicesPage />
+<ScriptEditorPage scriptId={params.id} />
+```
+
+## Quickstart
+
+```ts
+import { AixClient } from '@aixnn/aixautots/core'
+
+const client = new AixClient({
+  baseUrl: 'https://aixautobot.com',
+  auth: { kind: 'user', getToken: async () => myUserJwt },
+})
+
+const devices = await client.devices.list()
+const { run_id } = await client.fleet.start({ flow, device_ids: [devices[0].id] })
+```
+
+React：
+
+```tsx
+import { AixProvider, useDevices } from '@aixnn/aixautots/react'
+
+function App() {
+  return (
+    <AixProvider config={{ baseUrl, auth: { kind: 'user', getToken } }}>
+      <DeviceList />
+    </AixProvider>
+  )
+}
+function DeviceList() {
+  const { data, loading, refetch } = useDevices()
+  // ...
+}
+```
+
+## 鉴权
+
+`AixConfig.auth` 接受单个或多个凭据；SDK 按请求 **scope** 自动选用并注入请求头。**浏览器只需 bearer 或
+project key/secret——不需要、也不应携带网关 `X-API-Key`**（后端 `require_principal` 已放行任一有效主体）。
+
+```ts
+type Credential =
+  | { kind: 'project';   key: string; secret: string }              // 第三方：X-Project-Key / X-Project-Secret
+  | { kind: 'user';      getToken: () => string | Promise<string> } // 自家前端：user JWT
+  | { kind: 'developer'; getToken: () => string | Promise<string> } // 项目管理 / 平台管理
+```
+
+| Scope | 用到的凭据 | 覆盖的资源 |
+|---|---|---|
+| `caller` | project key/secret **或** user JWT | devices / scripts / clusters / fleet / tasks / locators / nodes |
+| `developer` | developer JWT | projects / auth 管理 / webhooks / llm |
+| `admin` | developer JWT（后端校验 admin） | admin（rate/plan/billing）/ images |
+| `public` | 无 | auth.login / register / send-code / verify-code |
+
+多凭据示例（自家前端同时持 developer + user）：
+
+```ts
+auth: [
+  { kind: 'user', getToken: currentUserToken },        // caller 资源用
+  { kind: 'developer', getToken: () => devJwt },        // developer/admin 资源用
+]
+```
+
+第三方前端（浏览器不持 project secret）：后端铸 user JWT，前端用 `createCachedUserCredential` 自动缓存/刷新（按 `expiresIn` 或 JWT `exp`，并发去重）：
+
+```ts
+import { createCachedUserCredential } from '@aixnn/aixautots/core'
+
+const auth = createCachedUserCredential({
+  mint: () => fetch('/mint-token').then((r) => r.json()), // 你的后端 → { token, expiresIn? } 或 token 字符串
+})
+new AixClient({ baseUrl, auth })
+```
+
+> 兼容旧写法：`getAuthToken: () => userJwt` 等价于 `auth: { kind: 'user', getToken }`。
+
+## 资源总览（`AixClient` + hooks）
+
+| 资源 | `client.*` | React hook |
+|---|---|---|
+| 鉴权 | `auth` | `useAuth` |
+| 项目 | `projects` | `useProjects` |
+| 设备 | `devices` | `useDevices` / `useDeviceActions` |
+| 节点 | `nodes` | `useNodes` |
+| 集群 | `clusters` | `useClusters` |
+| 脚本 | `scripts` | `useScripts` |
+| 定位器 | `locators` | `useLocators` |
+| Fleet 运行 | `fleet` | `useFleetRun` |
+| Webhook 任务 | `tasks` | `useTasks` / `useTaskStatus` |
+| Webhook 配置 | `webhooks` | `useWebhooks` |
+| LLM | `llm` | `useLlm` |
+| 管理/计费/镜像 | `admin` | `useAdmin` / `useImages` |
+| 巡检（截图+UI树） | （`devices.op`） | `useInspector` |
+
+## 设备操作：两条路径
+
+| | REST `devices.op` | WS `DeviceChannel` |
+|---|---|---|
+| 形态 | 一次性、无状态 | 长连、低延迟 |
+| 适用 | 截图 / UI 树 / 安装 / 电源 等 | adb / wda / frida / scriptlet 流式 + 原始隧道、重交互调试 |
+| 入口 | `client.devices.op(id, { op, ... })` | `DeviceChannel.open(cfg, id)` |
+
+**通用命令**：`devices.op(id, op)` 是唯一入口，`op` 类型为开放联合——已知命令有自动补全，
+**任意新命令无需新 SDK 方法**直接透传。`screenshot()/captureUiTree()/installApkUrl()/power()` 等都是它的薄包装。
+
+```ts
+await client.devices.screenshot(id)                        // 薄糖
+await client.devices.op(id, { op: 'some_future_op', x: 1 }) // 新命令零改动
+```
+
+## 运行 flow：两条链路
+
+| | Fleet（`fleet` / `useFleetRun`） | Webhook 任务（`FlowRun` / `tasks` / `useTaskStatus`） |
+|---|---|---|
+| 端点 | `POST /api/fleet/runs` | `POST /api/webhook/tasks` |
+| 触发方 | 自家 app 交互式运行 | 第三方 webhook |
+| 进度 | 轮询 `fleet.get(runId)` | 流式 `/ws/execution/:task_id`（`FlowRun`）或轮询 `tasks.get(id)` / 事件 `tasks.events(id)` |
+| 控制 | `cancel` / `pause` / `resume` | `tasks.cancel(id)`（v1：DB 侧取消未完成 target） |
+
+## AI（生成 / 精炼 / 解释）
+
+LLM 由后端网关代理（OpenAI 兼容），developer scope。
+
+```ts
+const { flow } = await client.llm.generate({ prompt: '写一个登录流程', platform: 'android' })
+const refined  = await client.llm.refine({ flow, instruction: '登录后再点设置' }) // → { ok, flow? }
+const { explanation } = await client.llm.explain(flow)                            // → 自然语言说明
+```
+
+React：`useLlm()` → `{ generate, refine, explain, test }`（参考实现见 frontend 的 `AIPanel`）。
+
+## 镜像
+
+```ts
+import { MirrorSession } from '@aixnn/aixautots/core'
+const s = await MirrorSession.join(cfg, deviceId)
+s.onStream((stream) => { videoEl.srcObject = stream })
+s.sendInput({ t: 'tap', x, y })   // 归一坐标 [0,1]
+```
+
+React：`useMirror(deviceId)` → `{ stream, sendInput }`；UI：`<MirrorView>` + `<ControlBar>`。
+
+## 错误
+
+所有失败抛 `AixError`（含网络层失败，`code: 'offline'`）。按 `code` 区分：
+`auth` / `timeout` / `offline` / `locked` / `protocol` / `unknown`。
+
+## 参考实现 & 规划
+
+- 参考实现：`frontend/`（Tauri 桌面控制台，全量消费本 SDK）。
+- 规划与契约：`docs/superpowers/plans/2026-06-07-aixautots-full-client-sdk.md`。

package/dist/ScriptStudio-DaCqOF5H.d.ts

@@ -0,0 +1,43 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/** Context handed to host-injected slots (agent / inspector). */
+interface ScriptStudioSlotContext {
+    /** Persisted script id (undefined until first save). */
+    scriptId?: string;
+    /** Currently selected run device id. */
+    deviceId: string | null;
+    /** Resolved platform of the selected device ('android' | 'ios' | …). */
+    platform: 'android' | 'ios';
+    /** Current editor source. */
+    code: string;
+    /** Replace the entire editor source. */
+    setCode: (code: string) => void;
+    /** Append a snippet to the editor source (newline-separated). */
+    insertSnippet: (snippet: string) => void;
+    /** Open the host-injected device inspector (same as the header button). */
+    openInspector: () => void;
+}
+interface ScriptStudioProps {
+    /** Route param: the script to open. Undefined ⇒ a fresh "New Script". */
+    scriptId?: string;
+    /** Called after the first create assigns an id, so the host can switch the
+     *  URL to `/editor/:id` (the SDK does not depend on a router). */
+    onScriptIdChange?: (id: string) => void;
+    /** Host-injected LLM agent panel (right column). Not rendered if omitted. */
+    renderAgentPanel?: (ctx: ScriptStudioSlotContext) => ReactNode;
+    /** Host-injected device inspector (modal/overlay). Not rendered if omitted.
+     *  `open`/`onClose` are driven by the studio's "设备/Inspector" button. */
+    renderInspector?: (ctx: ScriptStudioSlotContext & {
+        open: boolean;
+        onClose: () => void;
+    }) => ReactNode;
+    /** localStorage key for the resizable console height. */
+    consoleHeightStorageKey?: string;
+    /** Extra controls rendered at the right end of the header (e.g. a language
+     *  toggle). The studio itself stays app-chrome-agnostic. */
+    headerExtra?: ReactNode;
+}
+declare function ScriptStudio({ scriptId, onScriptIdChange, renderAgentPanel, renderInspector, consoleHeightStorageKey, headerExtra, }: ScriptStudioProps): react.JSX.Element;
+
+export { type ScriptStudioProps as S, type ScriptStudioSlotContext as a, ScriptStudio as b };

package/dist/agent-runner-V60B0is1.d.ts

@@ -0,0 +1,57 @@
+/**
+ * LLM agent 传输的注入接口。`AgentPanel` 的 UI 与可移植逻辑在 aixautots 内，但「如何
+ * 真正跑一个本地 agent」是宿主特有的（桌面端经 Tauri IPC spawn claude/codex CLI，
+ * 经事件流式回传）——所以这部分由宿主实现 `AgentRunner` 注入，aixautots 不依赖 Tauri。
+ *
+ * 非桌面/无本地 agent 的宿主可传 `available: false`，面板会显示「需在桌面应用中使用」。
+ *
+ * ── 实现是可替换的：Tauri 只是其中一种 ──
+ * 本接口刻意与传输解耦，`AgentPanel` 不知底层是本机还是服务端。已有/可有的实现：
+ *   1) 本机 CLI（现状）：桌面端 `frontend/src/lib/agentRunner.ts` 用 Tauri `invoke`/`listen`
+ *      spawn 本机 claude/codex CLI（密钥/算力在用户机器）。
+ *   2) 服务端 agent：服务器跑 claude/codex CLI（密钥/算力在后端），HTTP 起停 + SSE 流式
+ *      回传。**SDK 已内置实现** `createBackendAgentRunner(client)`（见 `backend-agent-runner.ts`）；
+ *      editor 薄壳按环境切换即可，aixautots 与 AgentPanel 零改动：
+ *        agentRunner={isTauri() ? tauriAgentRunner : createBackendAgentRunner(client)}
+ *      （仅待后端落地 `/api/agent/*` 端点；客户端侧已就绪。）
+ *
+ *   后端端点契约（详见 `backend-agent-runner.ts`）：`POST /api/agent/{start,send,stop}` +
+ *   `GET /api/agent/stream`(SSE)；事件载荷映射到本文件的 `AgentStreamEvent`
+ *   （`stream: 'stdout'|'stderr'|'done'`，done 带最终 `script` 全文）。鉴权复用 user JWT。
+ *   失败可经 `stream:'stderr'` 文本上报，或 `done` 不带 `script` 表示无产出。
+ */
+type AgentKind = 'claude' | 'codex';
+interface AgentStreamEvent {
+    /** 该事件所属脚本 id（面板按当前 scriptId 过滤）。 */
+    scriptId: string;
+    stream: 'stdout' | 'stderr' | 'done';
+    /** stdout/stderr 增量文本。 */
+    chunk?: string;
+    /** done 时回带的最终 script.ts 全文（非空且有变化则替换编辑器）。 */
+    script?: string;
+}
+interface AgentSendRequest {
+    agent: AgentKind;
+    scriptId: string;
+    code: string;
+    deviceId: string;
+    userMsg: string;
+    /** 本轮是否是会话首轮（决定 start vs send 语义，由实现自行处理）。 */
+    isFirst: boolean;
+}
+interface AgentRunner {
+    /** 本机 agent 后端是否可用（如桌面/Tauri 环境）。false 时面板显示提示而不渲染交互。 */
+    available: boolean;
+    /** 可选：从宿主设置读默认 agent / 权限模式（面板挂载时调用）。 */
+    defaults?: () => Promise<{
+        agent?: AgentKind;
+    }>;
+    /** 启动或继续一轮 agent。权限模式等宿主细节由实现内部处理。 */
+    send: (req: AgentSendRequest) => Promise<void>;
+    /** 停止进行中的一轮。 */
+    stop: (scriptId: string) => Promise<void>;
+    /** 订阅流式输出；返回取消订阅函数。面板内部按 scriptId 过滤事件。 */
+    subscribe: (on: (ev: AgentStreamEvent) => void) => () => void;
+}
+
+export type { AgentKind as A, AgentRunner as a, AgentSendRequest as b, AgentStreamEvent as c };

package/dist/automation-queue-8HqRJV_K.d.ts

@@ -0,0 +1,72 @@
+import { a as RunEventKind, A as AixConfig, R as ResolvedConfig } from './config-Bm1hmXhD.js';
+import { S as Script } from './types-C2WXVcam.js';
+
+interface FlowSubmit {
+    /** Inline flow JSON (XOR scriptId). */
+    flow?: unknown;
+    /** Reference a stored script by id (XOR flow). */
+    scriptId?: string;
+    /** Internal device UUIDs (non-empty). */
+    deviceIds: string[];
+    params?: unknown;
+    mode?: unknown;
+    expiresIn?: number;
+}
+/** A normalized per-device execution event. */
+interface FlowEvent {
+    deviceId: string;
+    event: RunEventKind;
+}
+declare class FlowRun {
+    readonly taskId: string;
+    readonly targets: string[];
+    private readonly socket;
+    private readonly eventListeners;
+    private readonly doneListeners;
+    private readonly finished;
+    private doneFired;
+    private cursor;
+    private constructor();
+    static submit(cfg: AixConfig | ResolvedConfig, body: FlowSubmit): Promise<FlowRun>;
+    on(event: 'event', cb: (e: FlowEvent) => void): () => void;
+    on(event: 'done', cb: () => void): () => void;
+    /** Called (via microtask) when submit() returns targets:[]. */
+    fireDoneIfEmpty(): void;
+    private onMessage;
+    close(): void;
+}
+
+/** 批次派发模式。`'round-robin'` 为默认(行分摊到设备);`'broadcast'` 每行全量。 */
+type QueueMode = 'round-robin' | 'broadcast';
+/** 一个批次的输入。`script` 与 `flow` 二选一(与 `FlowRun`/后端的 flow XOR
+ *  script 约束一致)。`rows` 每项是一组动态参数值(覆写 `flow.variables`);空
+ *  数组等价于「无参数」单组(提交一次,沿用脚本自带 variables)。 */
+interface BatchConfig {
+    /** 引用已存库脚本(XOR flow)。 */
+    script?: Pick<Script, 'id'> & {
+        id: string;
+    };
+    /** 内联 flow JSON(XOR script)。 */
+    flow?: unknown;
+    /** 每行 = 一组动态参数(如不同账户)。空 ⇒ 视作单组空参数,提交一次。 */
+    rows: Array<Record<string, unknown>>;
+    /** 目标设备内部 UUID(非空)。 */
+    deviceIds: string[];
+    /** 派发模式,默认 `'round-robin'`。 */
+    mode?: QueueMode;
+    /** 透传给 `FlowRun.submit` 的任务过期秒数(可选)。 */
+    expiresIn?: number;
+}
+/** 把 rows×mode 展开为多次 `FlowRun.submit`,返回每次提交得到的 task id 顺序数组。
+ *  逐行顺序提交(保留行序);任一行失败即抛出(已提交的行不回滚——它们是独立任务)。 */
+declare function submitBatch(cfg: AixConfig | ResolvedConfig, config: BatchConfig): Promise<string[]>;
+/** 自动化队列的薄封装:绑定一份 config,`submit(batch)` 即提交。无状态——
+ *  追踪/暂停/恢复由 `TasksApi`(`useAutomationQueue`)负责。 */
+declare class AutomationQueue {
+    private readonly cfg;
+    constructor(cfg: AixConfig | ResolvedConfig);
+    /** 展开并提交一个批次,返回 task id 数组。见 [`submitBatch`]。 */
+    submit(config: BatchConfig): Promise<string[]>;
+}
+
+export { AutomationQueue as A, type BatchConfig as B, type FlowEvent as F, type QueueMode as Q, FlowRun as a, type FlowSubmit as b, submitBatch as s };