# zn-ai 脚本录制与管理功能开发计划

## 项目概述

基于参考图片中的脚本管理 UI 设计，为 zn-ai 项目规划脚本录制与管理功能的开发路线。该功能允许用户录制、编辑、保存和运行基于 Playwright 的浏览器自动化脚本，以扩展应用对各类 OTA 平台的适配能力。

## 核心目标

1. **实现脚本管理中心**：创建、编辑、删除、启用/禁用自动化脚本
2. **支持脚本录制**：通过 Playwright 等工具录制用户浏览器操作并生成脚本代码
3. **提供脚本编辑器**：支持代码高亮、语法检查的基础编辑体验
4. **实现脚本执行**：保存的脚本可在本地 Chrome 环境中运行
5. **集成现有架构**：与 zn-ai 现有状态管理、IPC 通信、任务执行系统深度融合

## 技术约束

- **前端框架**：Vue 3 Composition API
- **状态管理**：Pinia
- **UI 组件库**：Element Plus + Tailwind CSS
- **自动化引擎**：Playwright (已集成)
- **持久化存储**：`electron/scripts/` 文件目录 (脚本代码) + electron-store / dexie (脚本元数据及渲染进程状态)
- **脚本存储目录**：`electron/scripts/` 作为脚本源文件夹，直接存放 `.mjs` 脚本文件，供管理面板进行删除、编辑、测试
- **IPC 通信**：现有 `hostApiFetch` / `ipcRenderer.invoke` 机制
- **脚本执行**：复用 `executeScriptService` 和 `runTaskOperationService`

## 开发原则

1. **分阶段实施**：优先核心管理功能，再逐步增强录制能力
2. **渐进式增强**：先实现手动创建/编辑脚本，再接入录制能力
3. **代码复用**：最大化复用现有任务执行、Chrome 连接、标签页管理逻辑
4. **类型安全**：使用 TypeScript 确保脚本类型和配置的类型安全
5. **向后兼容**：新功能不影响现有 OTA 脚本和任务执行流程

---

## 阶段一：基础架构与数据模型

### 目标
建立脚本管理功能的基础架构，包括类型定义、数据持久化、状态管理和底层服务接口。

### 任务清单

#### 1.1 创建脚本类型定义
- **文件**：`src/common/types/script.ts`
- **内容**：
  - 定义 `AutomationScript` 核心类型（id, name, description, code, enabled, channel, createdAt, updatedAt）
  - 定义 `ScriptCreateInput`、`ScriptUpdateInput`、`ScriptExecutionResult` 等 DTO
  - 定义脚本状态枚举：`ScriptStatus`（idle, running, success, error）
  - 定义录制状态枚举：`RecordingStatus`（idle, recording, paused, stopped）
- **依赖**：无
- **预估工时**：2 小时

#### 1.2 创建脚本存储服务（主进程）
- **文件**：`src/main/service/script-store-service.ts`
- **内容**：
  - 以 `electron/scripts/` 为脚本根目录，通过 Node.js `fs` API 直接管理 `.mjs` 脚本文件
  - 提供 `getScripts`、`getScriptById`、`saveScript`、`deleteScript`、`toggleScript`、`runScript` 方法
  - 脚本元数据（name, description, enabled, channel, createdAt, updatedAt）通过 `electron-store` 或同级 `scripts.meta.json` 索引文件维护
  - 初始化时检测 `electron/scripts/` 目录是否存在，不存在则自动创建并写入默认脚本种子数据（如参考图中的 change model / pause 等示例脚本）
  - 脚本管理面板的所有增删改查操作均同步更新文件系统及元数据索引
- **依赖**：Node.js `fs`/`path` 模块、`electron-store`（用于元数据索引）、脚本类型定义
- **预估工时**：4 小时

#### 1.3 创建 IPC 接口层
- **文件**：`src/main/ipc/script-ipc.ts`（主进程）及 `src/renderer/api/script.ts`（渲染进程）
- **内容**：
  - 定义 IPC 通道常量：`IPC_EVENTS.SCRIPT_*`
  - 主进程注册脚本相关 IPC 处理器
  - 渲染进程封装 `scriptApi` 调用层（getAll, getById, create, update, delete, run / test, startRecording, stopRecording）
- **依赖**：script-store-service
- **预估工时**：3 小时

#### 1.4 创建 Pinia Store
- **文件**：`src/renderer/store/script.ts`
- **内容**：
  - 状态：`scripts`、`currentScript`、`recordingStatus`、`executionLogs`、`loading`
  - Actions：`fetchScripts`、`saveScript`、`deleteScript`、`toggleScript`、`runScript`、`startRecording`、`stopRecording`
  - Getters：按启用状态过滤脚本、按渠道分组
- **依赖**：`scriptApi`、脚本类型定义
- **预估工时**：4 小时

#### 1.5 创建国际化资源
- **文件**：`src/renderer/i18n/locales/{zh,en,ja}/script.json`
- **内容**：
  - 脚本管理页面文本（脚本管理、新建脚本、编辑、运行、删除等）
  - 录制相关文本（开始录制、停止录制、录制中...）
  - 状态和提示文本（启用、禁用、运行成功、运行失败）
- **依赖**：现有 i18n 配置
- **预估工时**：2 小时

### 交付成果
- 完整的脚本类型系统
- 主进程脚本持久化服务（基于 `electron/scripts/` 文件系统）
- 渲染进程 Pinia store（可工作）
- 国际化资源就绪

### 阶段验收标准
- TypeScript 编译无错误
- Store 通过 IPC 可正确在 `electron/scripts/` 目录下创建、读取、更新、删除 `.mjs` 脚本文件
- 元数据索引与文件系统保持同步
- 国际化键值正确加载

---

## 阶段二：脚本管理 UI 开发

### 目标
开发脚本管理功能的用户界面，复用 Element Plus 和 Tailwind CSS 保持与现有界面一致。

### 任务清单

#### 2.1 创建脚本管理主页面
- **文件**：`src/renderer/pages/scripts/index.vue`
- **内容**：
  - 页面标题"脚本管理"和"新建脚本"主按钮
  - 脚本网格/卡片列表布局（参考图片中的卡片样式）
  - 空状态展示
  - 加载状态和错误处理
- **依赖**：Script store、国际化
- **预估工时**：4 小时

#### 2.2 创建脚本卡片组件
- **文件**：`src/renderer/pages/scripts/components/ScriptCard.vue`
- **内容**：
  - 脚本图标/类型标识（如 JavaScript 图标/channel 图标）
  - 脚本名称和描述
  - 启用/禁用状态开关（`el-switch`）
  - "编辑"和"运行"操作按钮
  - 最后运行状态/时间展示
  - 悬停阴影和过渡动画效果
- **依赖**：Script store、Element Plus 组件、Tailwind CSS
- **预估工时**：5 小时

#### 2.3 创建脚本编辑/录制对话框
- **文件**：`src/renderer/pages/scripts/components/ScriptEditorDialog.vue`
- **内容**：
  - 弹窗表单：脚本名称、描述、目标渠道选择
  - 脚本代码编辑区（集成 Monaco Editor 或 `vue-codemirror`，按需高亮 JS 语法）
  - "开始录制" / "停止录制"按钮及录制状态指示
  - "保存"和"取消"按钮
  - 表单验证（名称必填、代码非空）
- **依赖**：Script store、Monaco/Codemirror、Element Plus
- **预估工时**：8 小时

#### 2.4 创建脚本执行日志面板
- **文件**：`src/renderer/pages/scripts/components/ScriptLogPanel.vue`
- **内容**：
  - 展示最近一次脚本执行的输出日志
  - 支持成功/失败状态着色
  - 可清空的日志视图
- **依赖**：Script store、Tailwind CSS
- **预估工时**：3 小时

#### 2.5 集成路由和导航
- **文件**：`src/renderer/router/index.ts`、`SideMenus.vue`
- **内容**：
  - 添加 `/scripts` 路由
  - 在侧边栏菜单添加"脚本管理"入口（配合图标）
- **依赖**：主页面组件
- **预估工时**：2 小时

### 交付成果
- 完整的脚本管理页面和组件
- 脚本编辑/录制弹窗
- 路由和导航集成完毕

### 阶段验收标准
- 所有组件可独立渲染且样式与参考图一致
- 表单验证正常工作
- 响应式布局适配不同窗口尺寸

---

## 阶段三：脚本录制与执行引擎

### 目标
实现脚本录制能力和脚本执行流程，与现有 Playwright 自动化体系打通。

### 任务清单

#### 3.1 实现录制服务（主进程）
- **文件**：`src/main/service/script-recorder-service.ts`
- **内容**：
  - 封装 Playwright `codegen` 能力，或基于 CDP 监听用户操作生成代码
  - 录制前确保本地 Chrome 已启动 (`launchLocalChrome`)
  - 将生成的 Playwright 脚本代码格式化并返回给渲染进程
  - 支持指定起始 URL（渠道登录页）
- **依赖**：Playwright、`launchLocalChrome`、现有 tabs.js 逻辑
- **预估工时**：8 小时

#### 3.2 实现脚本执行服务（主进程）
- **文件**：`src/main/service/script-execution-service.ts`
- **内容**：
  - 复用 `executeScriptService` 直接运行 `electron/scripts/` 目录下的 `.mjs` 脚本文件
  - 执行时通过 `__filename` 或注入的环境变量传递脚本路径，无需创建额外临时文件
  - 注入预置上下文（如 Chrome CDP 端口、渠道配置、`common/tabs.js` 等公共模块路径）
  - 收集并返回 stdout/stderr 和执行结果，更新脚本最后运行状态到元数据索引
  - 面板"测试"按钮直接调用该服务执行目标脚本，并实时回传日志
- **依赖**：`executeScriptService`、`runTaskOperationService`
- **预估工时**：6 小时

#### 3.3 集成录制状态到 UI
- **内容**：
  - 编辑对话框中连接"开始录制"按钮到录制 IPC
  - 录制过程中显示加载状态/录制指示器
  - 录制完成后自动将生成的代码填充到编辑器
  - 错误处理（Chrome 未启动、录制超时等）
- **依赖**：Script store、录制服务
- **预估工时**：4 小时

#### 3.4 集成脚本测试/运行到 UI
- **内容**：
  - 脚本卡片"测试"按钮直接调用 `scriptExecutionService` 运行 `electron/scripts/` 目录下对应脚本
  - 执行过程中按钮显示 loading 状态
  - 执行完成后在日志面板展示结果
  - 失败时显示错误信息和重试入口
- **依赖**：Script store、脚本执行服务
- **预估工时**：4 小时

#### 3.5 添加脚本模板和默认脚本
- **内容**：
  - 提供常用模板（点击元素、输入文本、等待页面加载）
  - 预置参考图中的示例脚本（change model、pause、pause resume 等）作为 `.mjs` 文件放置到 `electron/scripts/seed/` 目录
  - 应用首次启动或检测到 `electron/scripts/` 为空时，将 seed 目录下的示例脚本复制/同步到主目录，并注册到元数据索引
  - 用户通过面板删除默认脚本时，直接删除对应的 `.mjs` 文件及索引条目
- **依赖**：script-store-service
- **预估工时**：3 小时

### 交付成果
- 用户可通过 UI 录制浏览器操作并生成脚本，保存为 `electron/scripts/` 下的 `.mjs` 文件
- 用户可在面板中直接测试/运行 `electron/scripts/` 目录中的任意脚本并查看执行结果
- 内置常用脚本模板及默认示例脚本

### 阶段验收标准
- 录制功能至少能生成可运行的 Playwright 代码并正确落盘
- 面板中的"测试"或"运行"按钮能直接执行 `electron/scripts/` 目录下的真实脚本文件
- 脚本执行输出完整呈现在日志面板
- 默认脚本从 `electron/scripts/seed/` 同步后可正常加载和运行

---

## 阶段四：测试、优化与完善

### 目标
确保功能稳定可靠，优化性能和用户体验，补充高级能力。

### 任务清单

#### 4.1 编写单元测试
- **文件**：`tests/unit/script-store.test.ts`、`tests/unit/script-recorder.test.ts`
- **内容**：
  - Store 逻辑测试
  - 录制服务核心逻辑测试
  - 工具函数和类型守卫测试
- **依赖**：Vitest、Vue Test Utils
- **预估工时**：5 小时

#### 4.2 添加集成测试
- **文件**：`tests/e2e/scripts.spec.ts`
- **内容**：
  - 脚本创建 -> 运行 -> 删除的完整流程
  - 录制流程测试（需 mock Chrome 环境）
  - 错误场景测试
- **依赖**：Playwright E2E 测试
- **预估工时**：5 小时

#### 4.3 安全与沙箱优化
- **内容**：
  - 用户脚本执行前进行基础安全检查（禁止 `require` 危险模块、文件系统操作限制）
  - 在独立子进程中运行用户脚本，隔离主进程环境
  - 录制和执行超时控制
- **依赖**：Node.js 子进程、vm/sandbox 机制
- **预估工时**：4 小时

#### 4.4 性能和体验优化
- **内容**：
  - Monaco Editor 懒加载，减少首屏体积
  - 脚本列表虚拟滚动（脚本数量大时）
  - 执行日志历史分页/自动清理策略
- **预估工时**：3 小时

#### 4.5 高级功能增强（可选）
- **内容**：
  - 脚本导入/导出（JSON / JS 文件）
  - 参数化脚本（支持变量注入）
  - 脚本执行调度（与 Cron 功能联动，定时执行脚本）
  - 脚本共享（团队脚本库）
- **预估工时**：10 小时（可选）

#### 4.6 文档编写
- **内容**：
  - 用户操作指南（如何录制和运行脚本）
  - 脚本开发 API 文档（预注入的上下文变量和工具函数）
  - 维护文档（新增渠道适配脚本的最佳实践）
- **预估工时**：3 小时

### 交付成果
- 完整的测试覆盖
- 安全隔离的用户脚本执行环境
- 性能优化后的流畅体验
- 可选的高级功能

### 阶段验收标准
- 核心流程测试覆盖率达到 80% 以上
- 用户脚本在主进程隔离环境中运行
- 性能和稳定性满足日常办公场景

---

## 时间总览

| 阶段 | 任务数 | 预估工时 | 累计工时 |
|------|--------|----------|----------|
| 阶段一 | 5 | 15 小时 | 15 小时 |
| 阶段二 | 5 | 22 小时 | 37 小时 |
| 阶段三 | 5 | 25 小时 | 62 小时 |
| 阶段四 | 6 | 30 小时 | 92 小时 |
| **总计** | **21** | **92 小时** | **92 小时** |

*注：阶段四的高级功能增强为可选，如不包括则总工时为 82 小时*

---

## 风险与缓解措施

### 技术风险

#### 风险 1：Playwright codegen 录制质量不稳定
- **描述**：Playwright codegen 生成的代码可能包含不稳定的选择器，或无法覆盖 iframe、Shadow DOM 等复杂场景
- **影响**：录制脚本可用性低，用户需要大量手动修改
- **概率**：中
- **缓解措施**：
  1. 在代码生成后做简单后处理（优先使用 role/text 选择器）
  2. 提供录制后编辑能力，引导用户修正选择器
  3. 针对不同渠道提供录制建议和最佳实践文档

#### 风险 2：用户脚本执行安全风险
- **描述**：用户编辑或外部导入的 `electron/scripts/` 下的脚本可能被篡改，执行恶意代码
- **影响**：主进程或本地系统受到威胁
- **概率**：低
- **缓解措施**：
  1. 始终在独立子进程中执行 `electron/scripts/` 目录下的脚本（复用 `executeScriptService`）
  2. 禁用 `require` 和 `fs` 等危险 Node.js API
  3. 添加执行超时和异常捕获
  4. 未来可引入脚本签名/沙箱策略

#### 风险 3：与现有任务执行系统冲突
- **描述**：新脚本执行和现有 `runTaskOperationService` 可能并发操作同一浏览器实例导致冲突
- **影响**：任务失败或浏览器崩溃
- **概率**：中
- **缓解措施**：
  1. 复用现有任务队列和锁机制（如有），或引入脚本执行队列
  2. 执行前检测 Chrome 是否正被其他任务占用
  3. 提供明确的任务/脚本执行状态提示

### 资源风险

#### 风险 1：开发时间超出预期
- **描述**：录制引擎和编辑器集成复杂度可能高于预期
- **影响**：项目延期
- **概率**：中
- **缓解措施**：
  1. 优先完成阶段一至三的核心功能
  2. 阶段四作为后续迭代
  3. Monaco Editor 可选降级为轻量级 CodeMirror

#### 风险 2：跨平台兼容性
- **描述**：Playwright codegen 和 Chrome 启动在不同系统上表现可能不一致
- **影响**：Windows / macOS 用户体验差异
- **概率**：低
- **缓解措施**：
  1. 复用现有 `launchLocalChrome` 的跨平台逻辑
  2. 录制服务使用纯 Playwright API，避免操作系统特有命令
  3. 在目标平台（macOS 和 Windows）分别验证

---

## 成功标准

### 功能成功标准
1. 用户可以创建、编辑、删除自动化脚本
2. 用户可以通过录制生成可运行的 Playwright 脚本
3. 脚本可一键运行并在日志面板查看结果
4. 启用/禁用开关可控制脚本是否在任务中心可用
5. 用户界面直观，与参考设计图一致

### 技术成功标准
1. 代码与现有任务执行系统良好集成，无冲突
2. 用户脚本在主进程隔离环境中安全运行
3. 测试覆盖核心流程
4. 可维护性和可扩展性好，便于新增渠道脚本

### 业务成功标准
1. 降低新渠道适配的脚本开发门槛
2. 提升用户自定义自动化流程的灵活性
3. 为后续脚本市场/共享功能奠定基础

---

## 下一步行动

1. **需求确认**：与产品确认参考图中脚本类型、默认脚本列表和录制流程细节
2. **技术预研**：验证 Playwright codegen 在 zn-ai 现有 Chrome 启动流程中的集成方式
3. **编辑器选型**：确认脚本编辑器使用 Monaco Editor 还是 CodeMirror（体积和加载性能）
4. **开始实施**：按阶段一任务开始开发类型定义和 IPC 接口层

---

## 附录

### A. 文件结构规划

```
electron/
└── scripts/
    ├── scripts.meta.json        # 脚本元数据索引（名称、启用状态、渠道等）
    ├── change-model.mjs         # 默认示例脚本（由 seed/ 自动同步）
    ├── pause.mjs
    ├── pause-resume.mjs
    └── seed/                    # 预置种子脚本目录（应用自带，只读模板源）
        ├── change-model.mjs
        ├── pause.mjs
        └── pause-resume.mjs

src/
├── common/
│   └── types/
│       └── script.ts            # 脚本相关类型定义
├── main/
│   ├── ipc/
│   │   └── script-ipc.ts        # 主进程 IPC 处理器
│   └── service/
│       ├── script-store-service.ts      # 脚本持久化服务（读写 electron/scripts/）
│       ├── script-recorder-service.ts   # 脚本录制服务
│       └── script-execution-service.ts  # 脚本执行服务（直接运行 electron/scripts/ 下脚本）
├── renderer/
│   ├── api/
│   │   └── script.ts            # 渲染进程 API 封装
│   ├── store/
│   │   └── script.ts            # Pinia store
│   ├── pages/
│   │   └── scripts/
│   │       ├── components/
│   │       │   ├── ScriptCard.vue
│   │       │   ├── ScriptEditorDialog.vue
│   │       │   └── ScriptLogPanel.vue
│   │       └── index.vue        # 脚本管理主页面
│   └── i18n/
│       └── locales/
│           ├── zh/
│           │   └── script.json
│           ├── en/
│           │   └── script.json
│           └── ja/
│               └── script.json
```

### B. 依赖库评估

1. **代码编辑器**：`@codemirror/lang-javascript` + `vue-codemirror`（轻量、加载快）或 `monaco-editor-vue3`（功能强但体积大）
2. **录制引擎**：`playwright` 内置 `codegen` CLI（已集成在项目依赖中）
3. **脚本格式化**：`prettier`（可选，用于美化生成的代码）
4. **状态管理**：Pinia（项目已使用）

### C. 与现有系统集成点

1. **Chrome 启动**：复用 `launchLocalChrome.ts`
2. **脚本执行**：复用 `executeScriptService`
3. **标签页管理**：用户脚本中可引入 `common/tabs.js`
4. **渠道配置**：读取 `src/renderer/constant/channel.ts` 中的渠道信息
5. **任务调度**：未来可与 Cron 功能联动，实现定时执行脚本

---

*本计划将根据实际情况进行迭代更新。建议每阶段结束后进行回顾和调整。*