intools-cli 1.0.6 → 1.0.8

package/PLUGIN_API.md

@@ -141,56 +141,172 @@
 "icon": { "type": "svg", "value": "<svg>...</svg>" }
 ```
 
-## Preload 配置（自定义 Node.js 能力）
+## Preload 预加载脚本 ⭐ 核心概念
 
-配置自定义 preload 脚本，可在渲染进程中直接使用 Node.js 能力。
+> [!IMPORTANT]
+> **Preload 是 InTools 插件访问 Node.js 能力的核心机制。** 对于需要在渲染进程（UI）中使用 Node.js API、第三方 npm 模块或 Electron 渲染进程 API 的插件来说，Preload 是**必不可少**的。
+
+### 什么是 Preload？
+
+Preload 脚本是一个特殊的 JavaScript 文件，在**渲染进程加载之前**执行，具有以下特点：
+
+| 特性 | 说明 |
+|------|------|
+| 🔧 **Node.js 完整支持** | 可以使用 `require()` 导入任何 Node.js 原生模块和 npm 包 |
+| 🖥️ **Electron API 访问** | 可以调用 Electron 渲染进程 API |
+| 🌉 **桥接能力** | 通过 `window.xxx` 将原生能力暴露给前端 React/Vue 组件 |
+| ⚡ **同步执行** | 在页面 DOM 加载前执行，确保 API 可用 |
+
+### 适用场景
+
+以下场景**需要使用** Preload：
+
+- 📂 使用 `pdf-lib`、`sharp`、`ffmpeg` 等需要 Node.js 环境的 npm 包
+- 🔐 调用 Node.js 加密模块 (`crypto`)、子进程 (`child_process`)
+- 📁 需要比 `window.intools.filesystem` 更底层的文件操作
+- 🔗 与本地数据库交互 (SQLite、LevelDB 等)
+- 🎯 任何需要原生能力但又想在前端统一调用的场景
+
+---
 
 ### 配置方式
 
+在 `manifest.json` 中添加 `preload` 字段，指定预加载脚本路径：
+
 ```json
 {
-  "preload": "preload.js"
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "displayName": "我的插件",
+  "main": "dist/main.js",
+  "ui": "ui/index.html",
+  "preload": "preload.js",  // 👈 指定预加载脚本
+  "features": [...]
 }
 ```
 
-### preload.js 示例
+---
+
+### preload.js 编写规范
 
 ```javascript
-// preload.js - 遵循 CommonJS 规范
+// preload.js - 必须使用 CommonJS 规范
 const fs = require('fs')
 const os = require('os')
 const path = require('path')
-
-// 通过 window 暴露给前端
-window.myApi = {
+const { PDFDocument } = require('pdf-lib')  // 可使用 npm 包
+
+/**
+ * 通过 window 对象暴露 API 给前端
+ * 命名建议：window.{插件名}Api 或 window.{功能名}Api
+ */
+window.myPluginApi = {
+  // 同步方法
   getHomeDir: () => os.homedir(),
-  readFile: (filePath) => fs.readFileSync(filePath, 'utf-8'),
-  platform: process.platform
+  getPlatform: () => process.platform,
+  
+  // 异步方法
+  readFile: async (filePath) => {
+    return fs.promises.readFile(filePath, 'utf-8')
+  },
+  
+  // 复杂功能封装
+  mergePDFs: async (pdfPaths, outputPath) => {
+    const mergedPdf = await PDFDocument.create()
+    for (const pdfPath of pdfPaths) {
+      const pdfBytes = fs.readFileSync(pdfPath)
+      const pdf = await PDFDocument.load(pdfBytes)
+      const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices())
+      pages.forEach(page => mergedPdf.addPage(page))
+    }
+    const bytes = await mergedPdf.save()
+    fs.writeFileSync(outputPath, bytes)
+    return outputPath
+  }
 }
+
+console.log('[Preload] API 已挂载到 window.myPluginApi')
 ```
 
-### 前端调用
+---
+
+### 前端调用示例
 
-```typescript
-// 在 UI 组件中使用
-const homeDir = window.myApi?.getHomeDir()
-const content = window.myApi?.readFile('/path/to/file.txt')
+```tsx
+// 在 React 组件中调用
+import { useEffect, useState } from 'react'
 
-// 核心 API 仍然可用
-const text = await window.intools.clipboard.readText()
+// 类型声明（推荐单独放在 types.d.ts）
+declare global {
+  interface Window {
+    myPluginApi?: {
+      getHomeDir: () => string
+      getPlatform: () => string
+      readFile: (path: string) => Promise<string>
+      mergePDFs: (paths: string[], output: string) => Promise<string>
+    }
+  }
+}
+
+export function MyComponent() {
+  const [homeDir, setHomeDir] = useState('')
+  
+  useEffect(() => {
+    // 使用可选链确保安全访问
+    if (window.myPluginApi) {
+      setHomeDir(window.myPluginApi.getHomeDir())
+    }
+  }, [])
+  
+  const handleMerge = async () => {
+    const result = await window.myPluginApi?.mergePDFs(
+      ['/path/to/1.pdf', '/path/to/2.pdf'],
+      '/path/to/merged.pdf'
+    )
+    console.log('合并完成:', result)
+  }
+  
+  // 核心 API 仍然可用
+  const handleCopy = async () => {
+    const text = await window.intools.clipboard.readText()
+    console.log('剪贴板内容:', text)
+  }
+  
+  return <div>Home: {homeDir}</div>
+}
 ```
 
+---
+
+### 与 Main 后端的区别
+
+| 对比项 | Preload 脚本 | Main 后端 (main.js) |
+|--------|--------------|---------------------|
+| 执行环境 | 渲染进程（带 Node.js 权限） | 独立 Worker 进程 |
+| 调用方式 | `window.xxxApi.method()` | `window.intools.host.invoke()` |
+| 适合场景 | 同步操作、UI 紧密相关的原生功能 | 后台任务、长时间运行的操作 |
+| 进程通信 | 无需 IPC，直接调用 | 需要 IPC，异步调用 |
+| 生命周期 | 随 UI 窗口创建/销毁 | 独立管理，可持久化 |
+
+> [!TIP]
+> **选择建议**：如果功能与 UI 紧密相关且需要快速响应，使用 **Preload**；如果是后台任务或需要在无 UI 时运行，使用 **Main 后端**。
+
+---
+
 ### 注意事项
 
 | 项目 | 说明 |
 |------|------|
-| 文件格式 | CommonJS 格式，使用 `require()` 导入模块 |
-| 代码规范 | 必须是清晰可读的源码，**不能压缩/混淆** |
-| 可用模块 | Node.js 原生模块 + 第三方 npm 模块 |
-| API 暴露 | 通过 `window.xxx` 暴露自定义 API |
-| 核心 API | `window.intools` 核心 API 仍然可用 |
-| 安全性 | 有完整 Node.js 权限，需注意安全风险 |
-| 打包 | 运行 `intools pack` 会自动包含 preload 文件 |
+| 📝 文件格式 | **必须是 CommonJS** 格式，使用 `require()` 导入模块 |
+| 🔍 代码规范 | 必须是清晰可读的源码，**禁止压缩/混淆**（安全审查需要） |
+| 📦 可用模块 | Node.js 原生模块 + 已安装的 npm 包 |
+| 🌐 API 暴露 | 通过 `window.xxx` 暴露，建议使用 `window.{插件名}Api` 命名 |
+| 🔧 核心 API | `window.intools` 核心 API 在 Preload 环境中**仍然可用** |
+| ⚠️ 安全性 | 拥有完整 Node.js 权限，**请谨慎处理用户输入** |
+| 📦 打包 | `intools pack` 会自动包含 preload 及其依赖 |
+
+> [!CAUTION]
+> Preload 脚本拥有完整的 Node.js 权限，可以访问文件系统、网络等敏感资源。请确保代码安全，避免执行不可信的用户输入。
 
 ---
 
@@ -215,7 +331,7 @@ const text = await window.intools.clipboard.readText()
 | 方法 | 环境 | 说明 |
 |------|------|------|
 | `readFile(path, encoding?)` | R/B | 读取文件 → `Buffer | string` |
-| `writeFile(path, data, encoding?)` | R/B | 写入文件 |
+| `writeFile(path, data, encoding?)` | R/B | 写入文件 (`data`: `string \| Buffer \| ArrayBuffer`) |
 | `exists(path)` | R/B | 检查是否存在 → `boolean` |
 | `unlink(path)` | R/B | 删除文件 |
 | `readdir(path)` | R/B | 读取目录 → `string[]` |
@@ -281,10 +397,10 @@ const text = await window.intools.clipboard.readText()
 
 | 方法 | 环境 | 说明 |
 |------|------|------|
-| `request(options)` | R/B | 发起请求 → `HttpResponse` |
+| `request(options)` | R/B | 发起请求 (`body`: `string \| object \| Buffer \| ArrayBuffer`) → `HttpResponse` |
 | `get(url, headers?)` | R/B | GET 请求 |
-| `post(url, body?, headers?)` | R/B | POST 请求 |
-| `put(url, body?, headers?)` | R/B | PUT 请求 |
+| `post(url, body?, headers?)` | R/B | POST 请求 (`body`: `string \| object \| Buffer \| ArrayBuffer`) |
+| `put(url, body?, headers?)` | R/B | PUT 请求 (`body`: `string \| object \| Buffer \| ArrayBuffer`) |
 | `delete(url, headers?)` | R/B | DELETE 请求 |
 
 **HttpRequestOptions**: `url`, `method`, `headers`, `body`, `timeout`  
@@ -332,7 +448,7 @@ const text = await window.intools.clipboard.readText()
 | 方法 | 环境 | 说明 |
 |------|------|------|
 | `hideMainWindowPasteText(text)` | R/B | 粘贴文本到焦点应用 |
-| `hideMainWindowPasteImage(image)` | R/B | 粘贴图片到焦点应用 |
+| `hideMainWindowPasteImage(image)` | R/B | 粘贴图片到焦点应用 (`image`: `Path \| Buffer \| DataURL \| ArrayBuffer`) |
 | `hideMainWindowPasteFile(paths)` | R/B | 粘贴文件到焦点应用 |
 | `hideMainWindowTypeString(text)` | R/B | 模拟键入文本 |
 | `simulateKeyboardTap(key, ...modifiers)` | R/B | 模拟按键 |
@@ -489,7 +605,7 @@ const text = await window.intools.clipboard.readText()
 |------|------|------|
 | `isEncryptionAvailable()` | R/B | 检查加密可用性 |
 | `encryptString(plainText)` | R/B | 加密字符串 → `Buffer` |
-| `decryptString(encrypted)` | R/B | 解密字符串 → `string` |
+| `decryptString(encrypted)` | R/B | 解密字符串 (`encrypted`: `Buffer \| ArrayBuffer`) → `string` |
 
 ---
 

package/dist/commands/create/basic.js

@@ -55,6 +55,14 @@ async function createBasicProject(targetDir, name) {
     const mainTs = (0, basic_1.buildBasicMain)(name);
     fs.writeFileSync(path.join(targetDir, 'src/main.ts'), mainTs);
     console.log(chalk_1.default.green('  ✓ src/main.ts'));
+    // 创建 .gitignore
+    const gitignore = (0, basic_1.buildGitignore)();
+    fs.writeFileSync(path.join(targetDir, '.gitignore'), gitignore);
+    console.log(chalk_1.default.green('  ✓ .gitignore'));
+    // 创建 README.md
+    const readme = (0, basic_1.buildBasicReadme)(name);
+    fs.writeFileSync(path.join(targetDir, 'README.md'), readme);
+    console.log(chalk_1.default.green('  ✓ README.md'));
     // 复制 API 参考文档
     const apiDocSrc = path.join(__dirname, '../../..', 'PLUGIN_API.md');
     if (fs.existsSync(apiDocSrc)) {

package/dist/commands/create/react.js

@@ -54,6 +54,8 @@ async function createReactProject(targetDir, name) {
     createBackendMain(targetDir, name);
     createReactUI(targetDir, name);
     createIntoolsTypes(targetDir);
+    createGitignore(targetDir);
+    createReadme(targetDir, name);
     // 复制 API 参考文档
     const apiDocSrc = path.join(__dirname, '../../..', 'PLUGIN_API.md');
     if (fs.existsSync(apiDocSrc)) {
@@ -110,3 +112,13 @@ function createIntoolsTypes(targetDir) {
     fs.writeFileSync(path.join(targetDir, 'src/types/intools.d.ts'), typesDts);
     console.log(chalk_1.default.green('  ✓ src/types/intools.d.ts'));
 }
+function createGitignore(targetDir) {
+    const gitignore = (0, react_1.buildGitignore)();
+    fs.writeFileSync(path.join(targetDir, '.gitignore'), gitignore);
+    console.log(chalk_1.default.green('  ✓ .gitignore'));
+}
+function createReadme(targetDir, name) {
+    const readme = (0, react_1.buildReactReadme)(name);
+    fs.writeFileSync(path.join(targetDir, 'README.md'), readme);
+    console.log(chalk_1.default.green('  ✓ README.md'));
+}

package/dist/commands/create/templates/basic.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildBasicManifest = buildBasicManifest;
 exports.buildBasicPackageJson = buildBasicPackageJson;
 exports.buildBasicMain = buildBasicMain;
+exports.buildGitignore = buildGitignore;
+exports.buildBasicReadme = buildBasicReadme;
 function buildBasicManifest(name) {
     return {
         id: name,
@@ -93,3 +95,68 @@ const plugin = { onLoad, onUnload, onEnable, onDisable, run }
 export default plugin
 `;
 }
+function buildGitignore() {
+    return `node_modules
+dist
+.DS_Store
+*.log
+`;
+}
+function buildBasicReadme(name) {
+    return `# ${name}
+
+插件描述
+
+## 功能特性
+
+- 功能 1
+- 功能 2
+- 功能 3
+
+## 触发方式
+
+- \`${name}\` - 主功能
+
+## 开发
+
+### 安装依赖
+
+\`\`\`bash
+npm install
+\`\`\`
+
+### 开发模式
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### 构建
+
+\`\`\`bash
+npm run build
+\`\`\`
+
+### 打包
+
+\`\`\`bash
+npm run pack
+\`\`\`
+
+## 项目结构
+
+\`\`\`
+${name}/
+├── manifest.json              # 插件配置
+├── package.json
+├── src/
+│   └── main.ts                # 后端入口
+├── dist/                      # 构建输出
+└── icon.png                   # 插件图标
+\`\`\`
+
+## 许可证
+
+MIT License
+`;
+}

package/dist/commands/create/templates/react.js

@@ -10,6 +10,8 @@ exports.buildMainTsx = buildMainTsx;
 exports.buildAppTsx = buildAppTsx;
 exports.buildStylesCss = buildStylesCss;
 exports.buildUseIntools = buildUseIntools;
+exports.buildGitignore = buildGitignore;
+exports.buildReactReadme = buildReactReadme;
 exports.buildIntoolsTypes = buildIntoolsTypes;
 function buildReactManifest(name) {
     return {
@@ -676,6 +678,82 @@ export function useIntools(pluginId?: string) {
 }
 `;
 }
+function buildGitignore() {
+    return `node_modules
+dist
+ui
+.DS_Store
+*.log
+`;
+}
+function buildReactReadme(name) {
+    return `# ${name}
+
+插件描述
+
+## 功能特性
+
+- 功能 1
+- 功能 2
+- 功能 3
+
+## 触发方式
+
+- \`${name}\` - 主功能
+
+## 开发
+
+### 安装依赖
+
+\`\`\`bash
+npm install
+\`\`\`
+
+### 开发模式
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+### 构建
+
+\`\`\`bash
+npm run build
+\`\`\`
+
+### 打包
+
+\`\`\`bash
+npm run pack
+\`\`\`
+
+## 项目结构
+
+\`\`\`
+${name}/
+├── manifest.json              # 插件配置
+├── package.json
+├── src/
+│   ├── main.ts                # 后端入口
+│   ├── ui/
+│   │   ├── App.tsx            # 主应用
+│   │   ├── main.tsx           # UI 入口
+│   │   ├── index.html         # HTML 模板
+│   │   ├── styles.css         # 全局样式
+│   │   ├── hooks/
+│   │   │   └── useIntools.ts  # InTools API Hook
+│   │   └── types/
+│   │       └── intools.d.ts   # 类型定义
+├── dist/                      # 后端构建输出
+├── ui/                        # UI 构建输出
+└── icon.png                   # 插件图标
+\`\`\`
+
+## 许可证
+
+MIT License
+`;
+}
 function buildIntoolsTypes() {
     return `// InTools API 类型定义
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intools-cli",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "InTools 插件开发 CLI 工具",
   "main": "dist/index.js",
   "files": [