@aixnn/aixautots 0.0.0-stage → 0.5.3

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# 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.
+aixautobot 的 TypeScript 客户端 SDK。core/react 是 headless 的数据/传输/鉴权层；ui 既提供细粒度
+部件，也提供**开箱即用的成品页面**（设备/任务/市场/脚本/编辑器/检查器）+ 一套可换肤主题，
+让任意项目都能"轻松接入"。桌面端 `frontend/` 是全量改用本 SDK 的参考实现。
+
+子路径导出：
+
+| 子包 | 职责 |
+|---|---|
+| `aixautots/core` | 资源 REST 客户端（`AixClient`）+ 会话层（设备通道 / Flow / 镜像）+ 类型 + 错误 |
+| `aixautots/react` | 上述能力的 React hooks（`AixProvider` + 资源/会话 hooks） |
+| `aixautots/ui` | 设备向细粒度部件（`MirrorView`/`ControlBar`/`ScriptEditor`/`DebugConsole`/`ScriptPanel`） |
+| `aixautots/ui/primitives` | 基础件（`Button`/`Input`/`Select`/`Badge`/`Dialog`/`Popover`） |
+| `aixautots/ui/{devices,tasks,market,scripts,editor,inspector}` | 成品页面组件 |
+| `aixautots/nav` | 路由无关导航注入（`AixNavProvider`/`useAixNav`） |
+| `aixautots/i18n` | 内置 i18n（`AixI18nProvider`/`useAixT`，en/zh，无 i18next 依赖） |
+| `aixautots/tailwind-preset` · `aixautots/styles.css` | Tailwind 预设 + 主题 token |
+
+```bash
+npm i aixautots   # peer: react（react 子包用）；ui 子包另需 @uiw/react-codemirror
+```
+
+## 接入（三步）
+
+用到 `aixautots/ui` 的成品页面/部件时，按以下三步接入样式与运行时上下文：
+
+**1) 样式** —— Tailwind 预设 + 主题 token + content 扫描：
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require('aixautots/tailwind-preset')],
+  content: [
+    './src/**/*.{ts,tsx}',
+    './node_modules/aixautots/dist/**/*.js', // 关键：否则 aixautots 组件的类名不会被生成
+  ],
+}
+```
+
+```css
+/* 入口 CSS */
+@import "aixautots/styles.css";   /* :root 浅色 + .dark 深色 token，可覆盖换肤 */
+```
+
+**2) Provider** —— 在 `AixProvider` 内注入导航与语言：
+
+```tsx
+import { AixProvider } from 'aixautots/react'
+import { AixNavProvider } from 'aixautots/nav'
+import { AixI18nProvider } from '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 'aixautots/ui/devices'
+import { ScriptEditorPage } from 'aixautots/ui/editor'
+
+<DevicesPage />
+<ScriptEditorPage scriptId={params.id} />
+```
+
+## Quickstart
+
+```ts
+import { AixClient } from '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 '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 '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 '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/chunk-5BMFMDQR.js

@@ -0,0 +1,18 @@
+import { createContext, createElement, useContext } from 'react';
+
+// src/ui/nav/index.ts
+var NavContext = createContext(null);
+function AixNavProvider({ nav, children }) {
+  return createElement(NavContext.Provider, { value: nav }, children);
+}
+function useAixNav() {
+  const nav = useContext(NavContext);
+  if (nav) return nav;
+  return {
+    navigate: (to) => {
+      console.warn(`[aixautots] useAixNav(): no <AixNavProvider>; navigate(${to}) ignored`);
+    }
+  };
+}
+
+export { AixNavProvider, useAixNav };