@tanzerfe/page-use 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TanzerFE Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,182 @@
+# @tanzerfe/page-use
+
+基于 [page-agent](https://github.com/alibaba/page-agent) 的页面操作智能体：接收自然语言指令，在当前页面中模拟点击与输入完成操作，并返回结论。
+
+- **框架无关**：核心不依赖 Vue / React，UI 为 Lit Web Component，在 Shadow DOM 中与宿主样式隔离。
+- **可供其它智能体调用**：支持模块 API、function calling 工具、结构化指令块与全局对象 `window.__TZ_PAGE_USE__`。
+- **Vue 适配层**：`@tanzerfe/page-use/vue` 提供 `PageUseHost` 组件。
+
+## 安装
+
+```bash
+pnpm add @tanzerfe/page-use zod
+```
+
+`zod` 为必需的 peer 依赖；`vue` / `vue-router` 仅在使用 `@tanzerfe/page-use/vue` 时需要。
+
+## 快速开始
+
+### 非 Vue 项目
+
+```ts
+import { createPageUse, mountPageUseUI, readLauncherSwitch } from '@tanzerfe/page-use'
+
+const handle = createPageUse({
+  llm: { baseURL: '/api/llm-proxy/v1', model: 'deepseek-chat' },
+  appName: '订单管理系统',
+  getMenus: () => myMenus,          // [{ label, path, hidden?, children? }]
+  routerMode: 'hash',               // 或 'history'
+})
+
+// 调试面板：URL 参数 ?pageUseDebug=1 / 0 可临时开关，否则使用 fallback
+const unmount = mountPageUseUI({ launcher: readLauncherSwitch(import.meta.env.DEV) })
+
+// 登出 / 卸载时
+unmount()
+handle.destroy()
+```
+
+### Vue 3 项目
+
+```vue
+<template>
+  <PageUseHost v-if="options.llm.baseURL" :options="options" :launcher="launcher" />
+</template>
+
+<script setup lang="ts">
+import { PageUseHost, readLauncherSwitch, type PageUseOptions } from '@tanzerfe/page-use/vue'
+
+const options: PageUseOptions = {
+  llm: { baseURL: import.meta.env.VITE_PAGE_USE_BASE_URL },
+  appName: '订单管理系统',
+  getMenus: () => permissionStore.menus,
+}
+const launcher = readLauncherSwitch(import.meta.env.DEV) && { scenarios: [/* ... */] }
+</script>
+```
+
+`PageUseHost` 自动完成初始化、UI 挂载与卸载销毁，并从 vue-router 推导 `routerMode`、`getCurrentPath`、`resolveRouteName`（显式传入优先）。UI 挂在 `document.body` 下，无需配置 `isCustomElement`。
+
+## 配置 `PageUseOptions`
+
+| 选项 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `llm.baseURL` | `string` | — | OpenAI 兼容端点（到版本前缀为止），可用相对路径。**为空时能力不可用** |
+| `llm.apiKey` | `string` | 空 | 前端直连时使用，生产环境建议留空 |
+| `llm.model` | `string` | `deepseek-chat` | 需支持 function calling。默认值仅为示例，使用其它端点时应显式指定 |
+| `llm.maxSteps` | `number` | `20` | 单任务最大步数 |
+| `llm.disableNamedToolChoice` | `boolean` | `false` | 模型不支持对象形式 `tool_choice` 时开启 |
+| `llm.extraBody` | `object` | `{}` | 合并进请求体 |
+| `llm.sessionHeader` | `string \| false` | `x-opencode-session` | 会话 ID 请求头，`false` 不发送 |
+| `appName` | `string` | — | 写入系统提示 |
+| `getMenus` | `() => PageUseMenuNode[]` | 空 | 可见菜单树，用于生成站点地图 |
+| `routerMode` | `'hash' \| 'history'` | `'hash'` | 路由模式 |
+| `getCurrentPath` | `() => string` | 从 location 读取 | 当前路由路径，不含 `#` |
+| `resolveRouteName` | `(path) => string` | — | 由路径解析路由名，用于匹配 `routeHints` |
+| `routeHints` | `Record<string, string>` | `{}` | 按页操作提示，key 为路由名或路径（不带前导 `/`） |
+| `layoutHint` | `string` | 通用描述 | 替换系统提示中的「页面结构」段落 |
+| `beforeTask` | `() => void \| Promise<void>` | — | 任务开始前的预处理，如展开侧栏 |
+| `beforeTaskLabel` | `string` | — | `beforeTask` 在设置面板中的显示名 |
+| `storageKeyPrefix` | `string` | `tz-page-use` | 本地存储键前缀 |
+| `pageAgentOptions` | `Partial<PageAgentConfig>` | `{}` | 透传给 page-agent |
+| `exposeGlobal` | `boolean` | `true` | 是否安装 `window.__TZ_PAGE_USE__` |
+
+### 调试面板 `PageUseLauncherConfig`
+
+| 选项 | 说明 |
+|---|---|
+| `title` | 标题，默认 `Page Use` |
+| `presets` | 追加到「常用」分组的快捷指令 `{ label, task }[]` |
+| `scenarios` | 「复杂场景」分组的快捷指令 |
+| `menuPresetLimit` | 由菜单生成「打开 XX」的数量上限，默认 6 |
+| `sourceLabels` | 任务来源到展示名的映射，如 `{ assistant: 'AI 助手' }` |
+
+## 对接方式
+
+### 1. 模块 API
+
+```ts
+import { pageUseCapability } from '@tanzerfe/page-use'
+
+if (pageUseCapability.isReady()) {
+  const result = await pageUseCapability.run('打开订单列表，筛选待发货并查询，告诉我第一条订单的收货地址', {
+    source: 'my-agent',
+    signal: controller.signal,
+    onProgress: (event) => { if (event.type === 'activity') console.log(event.text) },
+    onAskUser: async (question) => askInMyChat(question), // 可选
+  })
+  // result.status: completed | failed | stopped | error；result.summary 为结论
+}
+```
+
+`run()` 不会 reject。任务未能开始时 `status='error'` 并带 `errorCode`：
+
+| errorCode | 含义 |
+|---|---|
+| `NOT_CONFIGURED` | 未初始化或未配置 `llm.baseURL` |
+| `NOT_READY` | 已 `destroy` |
+| `BUSY` | 已有任务在执行（同一时刻仅一个任务） |
+| `EMPTY_TASK` | 指令为空 |
+| `AGENT_ERROR` | agent 构造或钩子抛出错误 |
+
+- 模型提问时依次交由 `onAskUser`、调试面板处理；两者都不可用时自动回复「无法补充信息」。
+- 进度可订阅 `pageUseStore` 获取，Vue 中使用 `usePageUseState()`。
+
+### 2. LLM function calling
+
+```ts
+import { PAGE_USE_TOOL, PAGE_USE_TOOL_NAME, runPageUseTool } from '@tanzerfe/page-use'
+
+// tools: [PAGE_USE_TOOL, ...]
+// 模型返回的 tool_call.name === PAGE_USE_TOOL_NAME 时：
+const { content } = await runPageUseTool(toolCall.function.arguments, { source: 'my-agent' })
+// content 作为 role=tool 的消息回给模型
+```
+
+### 3. 结构化指令块
+
+模型在回复中输出 `{ "type": "pageAction", "instruction": "..." }`，前端用 `isPageUseCommand(value)` 校验后调用 `pageUseCapability.run(value.instruction)`。
+
+### 4. 全局对象
+
+`window.__TZ_PAGE_USE__` 包含 `pageUseCapability` 的全部方法及 `tool`、`runTool`，可用于控制台调试、E2E 脚本和同源外部脚本：
+
+```js
+await window.__TZ_PAGE_USE__.run('打开首页')
+```
+
+## API Key 安全
+
+`llm.apiKey` 会出现在浏览器请求和前端产物中。**生产环境应由网关或代理注入 Key**，前端只传代理地址。
+
+本地开发可用 Vite 代理规避 CORS：
+
+```ts
+// vite.config.ts
+server: {
+  proxy: {
+    '/__page-use-llm': {
+      target: 'https://api.deepseek.com/v1',
+      changeOrigin: true,
+      rewrite: (p) => p.replace(/^\/__page-use-llm/, ''),
+    },
+  },
+}
+```
+
+## 主题
+
+在宿主页面设置 CSS 变量调整配色，例如 `:root { --tz-page-use-primary: #1677ff }`：
+
+| 变量 | 默认 | 用途 |
+|---|---|---|
+| `--tz-page-use-primary` | `#0879ff` | 主色：入口、按钮、光晕 |
+| `--tz-page-use-cyan` / `--tz-page-use-indigo` | `#36cfc9` / `#597ef7` | 光晕渐变 |
+| `--tz-page-use-warning` | `#fa8c16` | 光晕误触警示 |
+| `--tz-page-use-success` / `--tz-page-use-error` / `--tz-page-use-warning-text` | — | 面板状态色 |
+
+模拟光标配色见导出常量 `PAGE_USE_MASK_COLORS`。
+
+## License
+
+MIT