intools-cli 1.0.4 → 1.0.6

package/PLUGIN_API.md

@@ -1,11 +1,201 @@
-# InTools 插件 API 参考
+# InTools 插件开发完整指南
 
-> 本文档包含 InTools 插件开发可用的全部 API。
+> 本文档包含 InTools 插件开发所需的全部信息，包括 Manifest 配置规范和 API 参考。
 > - **UI/渲染进程**：`window.intools.{模块名}`
 > - **插件后端**：`context.api.{模块名}`
 
 ---
 
+# 第一部分：Manifest 配置规范
+
+## manifest.json 基本结构
+
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "type": "utility",
+  "displayName": "我的插件",
+  "description": "插件描述",
+  "main": "dist/main.js",
+  "ui": "ui/index.html",
+  "icon": "icon.png",
+  "pluginSetting": {
+    "single": true,
+    "height": 400
+  },
+  "window": {
+    "width": 800,
+    "height": 600
+  },
+  "features": [
+    {
+      "code": "main",
+      "explain": "主功能",
+      "cmds": [{ "type": "keyword", "value": "关键词" }]
+    }
+  ]
+}
+```
+
+## 顶层字段
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| name | string | ✓ | 插件唯一标识 |
+| version | string | ✓ | 版本号 |
+| type | string | | 类型（utility/productivity/developer/system/media/network/ai/entertainment/other） |
+| displayName | string | ✓ | 显示名称 |
+| description | string | | 插件描述 |
+| main | string | ✓ | 后端入口文件 |
+| ui | string | | UI 入口文件 |
+| preload | string | | 自定义 preload 脚本（可使用 Node.js） |
+| icon | string/object | | 插件图标（路径/URL/SVG） |
+| features | array | ✓ | 功能入口列表 |
+| pluginSetting | object | | 插件行为设置 |
+| window | object | | 独立窗口配置 |
+
+## PluginSetting 配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| single | boolean | true | 单例模式（不允许多开） |
+| height | number | - | 初始高度 |
+
+## Window 配置
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| width | 500 | 默认宽度 |
+| height | 400 | 默认高度 |
+| minWidth | 300 | 最小宽度 |
+| minHeight | 200 | 最小高度 |
+| maxWidth | - | 最大宽度 |
+| maxHeight | - | 最大高度 |
+
+## Feature 字段
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| code | string | ✓ | 功能代码 |
+| explain | string | ✓ | 功能说明 |
+| cmds | array | ✓ | 触发命令列表 |
+| mode | string | | 模式（ui/silent/detached） |
+| route | string | | UI 路由路径 |
+| icon | string/object | | 功能独立图标 |
+| mainHide | boolean | | 触发时隐藏主窗口 |
+| mainPush | boolean | | 向搜索框推送内容 |
+
+## Cmd 命令类型
+
+| type | 触发方式 | 可用字段 |
+|------|----------|----------|
+| keyword | 关键词匹配 | `value`（关键词） |
+| regex | 正则匹配 | `match`（正则）, `explain?`, `label?`（指令名称）, `minLength?`, `maxLength?` |
+| files | 文件拖入 | `exts?`, `fileType?`（file/directory/any, 默认 any）, `match?`（文件名正则, 与 exts 二选一）, `minLength?`, `maxLength?` |
+| img | 图片拖入 | `exts?` |
+| over | 选中文本 | `label?`（指令名称）, `exclude?`（排除正则）, `minLength?`, `maxLength?`（默认 10000） |
+
+### 示例
+
+```json
+{
+  "features": [
+    {
+      "code": "format",
+      "explain": "格式化 JSON",
+      "cmds": [
+        { "type": "keyword", "value": "json" },
+        { "type": "regex", "match": "^\\s*[{\\[]", "explain": "检测到 JSON" }
+      ]
+    },
+    {
+      "code": "process-pdf",
+      "explain": "处理 PDF 文件",
+      "cmds": [
+        { "type": "files", "exts": [".pdf"], "minLength": 1, "maxLength": 10 }
+      ]
+    },
+    {
+      "code": "folder-tool",
+      "explain": "文件夹工具",
+      "cmds": [
+        { "type": "files", "fileType": "directory" }
+      ]
+    }
+  ]
+}
+```
+
+## Icon 图标配置
+
+```json
+// 字符串简写
+"icon": "icon.png"
+"icon": "https://example.com/icon.png"
+"icon": "<svg>...</svg>"
+
+// 对象形式
+"icon": { "type": "file", "value": "assets/logo.png" }
+"icon": { "type": "url", "value": "https://example.com/icon.png" }
+"icon": { "type": "svg", "value": "<svg>...</svg>" }
+```
+
+## Preload 配置（自定义 Node.js 能力）
+
+配置自定义 preload 脚本，可在渲染进程中直接使用 Node.js 能力。
+
+### 配置方式
+
+```json
+{
+  "preload": "preload.js"
+}
+```
+
+### preload.js 示例
+
+```javascript
+// preload.js - 遵循 CommonJS 规范
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+
+// 通过 window 暴露给前端
+window.myApi = {
+  getHomeDir: () => os.homedir(),
+  readFile: (filePath) => fs.readFileSync(filePath, 'utf-8'),
+  platform: process.platform
+}
+```
+
+### 前端调用
+
+```typescript
+// 在 UI 组件中使用
+const homeDir = window.myApi?.getHomeDir()
+const content = window.myApi?.readFile('/path/to/file.txt')
+
+// 核心 API 仍然可用
+const text = await window.intools.clipboard.readText()
+```
+
+### 注意事项
+
+| 项目 | 说明 |
+|------|------|
+| 文件格式 | CommonJS 格式，使用 `require()` 导入模块 |
+| 代码规范 | 必须是清晰可读的源码，**不能压缩/混淆** |
+| 可用模块 | Node.js 原生模块 + 第三方 npm 模块 |
+| API 暴露 | 通过 `window.xxx` 暴露自定义 API |
+| 核心 API | `window.intools` 核心 API 仍然可用 |
+| 安全性 | 有完整 Node.js 权限，需注意安全风险 |
+| 打包 | 运行 `intools pack` 会自动包含 preload 文件 |
+
+---
+
+# 第二部分：API 参考
+
 ## 1. 剪贴板 (clipboard)
 
 | 方法 | 环境 | 说明 |
@@ -233,8 +423,35 @@
 | `setFeature(feature)` | B | 注册动态指令 |
 | `removeFeature(code)` | B | 删除动态指令 |
 
-**DynamicFeatureInput**: `code`, `explain`, `icon`, `platform`, `mode`, `route`, `cmds`  
-**mode**: `'ui' | 'silent' | 'detached'`
+**DynamicFeatureInput**:
+- `code` - 指令代码
+- `explain` - 说明文字
+- `icon` - 图标（路径/SVG/URL）
+- `platform` - 平台限制
+- `mode` - 模式：`'ui' | 'silent' | 'detached'`
+- `route` - 路由路径
+- `mainHide` - 触发时隐藏主窗口
+- `mainPush` - 向搜索框推送内容
+- `cmds` - 命令数组
+
+### cmds 命令类型
+
+| 类型 | 字段 | 说明 |
+|------|------|------|
+| `keyword` | `value` | 关键词匹配 |
+| `regex` | `match`, `explain?`, `label?`, `minLength?`, `maxLength?` | 正则匹配 |
+| `files` | `exts?`, `fileType?`, `match?`, `minLength?`, `maxLength?` | 文件匹配 |
+| `img` | `exts?` | 图片匹配 |
+| `over` | `label?`, `exclude?`, `minLength?`, `maxLength?` | 覆盖匹配 |
+
+**files 特殊字段**:
+- `fileType`: `'file' | 'directory' | 'any'` - 文件类型过滤 (默认 'any')
+- `match`: 匹配文件名的正则表达式 (与 `exts` 二选一)
+- `minLength` / `maxLength`: 文件数量限制
+
+**regex / over 特殊字段**:
+- `minLength` / `maxLength`: 输入文本长度限制 (over 默认为 10000)
+- `exclude`: 排除的正则表达式（仅 over）
 
 ---
 

package/README.md

@@ -183,11 +183,20 @@ my-plugin/
   "id": "my-plugin",
   "name": "my-plugin",
   "version": "1.0.0",
+  "type": "utility",
   "displayName": "我的插件",
   "description": "插件功能描述",
   "main": "dist/main.js",
   "ui": "ui/index.html",
   "icon": "icon.png",
+  "pluginSetting": {
+    "single": true,
+    "height": 400
+  },
+  "window": {
+    "width": 800,
+    "height": 600
+  },
   "features": [
     {
       "code": "main",
@@ -206,6 +215,7 @@ my-plugin/
 |------|------|------|------|
 | `name` | string | ✅ | 插件唯一标识（小写字母、数字、连字符） |
 | `version` | string | ✅ | 语义化版本 (x.y.z) |
+| `type` | string | ❌ | 插件类型 (utility/productivity/developer/system/media/network/ai/entertainment/other) |
 | `displayName` | string | ✅ | 用户看到的名称 |
 | `description` | string | ✅ | 功能描述 |
 | `id` | string | ✅ | 插件唯一 ID（推荐，优先于 name） |
@@ -213,6 +223,8 @@ my-plugin/
 | `ui` | string | ❌ | UI 文件路径（有界面时必填） |
 | `icon` | string/object | ❌ | 插件图标 |
 | `features` | array | ✅ | 功能入口列表 |
+| `pluginSetting` | object | ❌ | 插件行为设置 (`single`, `height`) |
+| `window` | object | ❌ | 独立窗口配置 (`width`, `height`, `minWidth`, etc.) |
 | `author` | string | ❌ | 作者名 |
 | `homepage` | string | ❌ | 项目主页 |
 | `minAppVersion` | string | ❌ | 最低 InTools 版本要求 |
@@ -251,16 +263,20 @@ my-plugin/
 | `cmds` | array | ✅ | 触发命令列表 |
 | `mode` | string | ❌ | `ui` / `silent` / `detached` |
 | `route` | string | ❌ | UI 路由（用于子窗口或页内路由） |
+| `icon` | string/object | ❌ | 功能独立图标 |
+| `mainHide` | boolean | ❌ | 触发时隐藏主窗口 |
+| `mainPush` | boolean | ❌ | 向搜索框推送内容 |
+
 
 #### 触发命令类型 (cmds)
 
-| type | 说明 | 额外字段 |
+| type | 说明 | 可用字段 |
 |------|------|----------|
 | `keyword` | 关键词触发 | `value`: 关键词 |
-| `regex` | 正则匹配 | `match`: 正则表达式, `explain`: 说明 |
-| `files` | 文件类型 | `exts`: [".json", ".txt"] |
-| `img` | 图片 | - |
-| `over` | 选中文本 | - |
+| `regex` | 正则匹配 | `match`: 正则表达式, `explain`: 说明, `label?`: 指令名称, `minLength?`, `maxLength?` |
+| `files` | 文件拖入 | `exts?`, `fileType?` (file/directory/any), `match?` (文件名正则), `minLength?`, `maxLength?` |
+| `img` | 图片拖入 | `exts?` |
+| `over` | 选中文本 | `label?` (指令名称), `exclude?` (排除正则), `minLength?`, `maxLength?` |
 
 #### 图标配置
 
@@ -275,6 +291,10 @@ my-plugin/
 
 // 3. 内联 SVG
 "icon": "<svg viewBox=\"0 0 24 24\" fill=\"currentColor\"><path d=\"...\"/></svg>"
+
+// 4. 对象形式（支持更多类型）
+"icon": { "type": "file", "value": "assets/logo.png" }
+"icon": { "type": "url", "value": "https://example.com/icon.png" }
 ```
 
 > 💡 **提示:** 未设置 `icon` 时，会自动尝试加载插件目录下的 `icon.png`
@@ -368,9 +388,42 @@ npm run build
 插件在沙箱中运行，通过 `context.api` 访问各种 API。
 
 > 📚 **完整 API 参考请查看 [`PLUGIN_API.md`](./PLUGIN_API.md)**
-> 
+>
 > 该文件会在创建插件时自动生成，包含全部 28 个 API 模块的详细说明。
 
+#### 可用 API 模块
+
+| 模块 | 说明 | 常用方法 |
+|------|------|----------|
+| `clipboard` | 剪贴板 | `readText`, `writeText`, `readImage` |
+| `filesystem` | 文件系统 | `readFile`, `writeFile`, `readdir` |
+| `storage` | 数据存储 | `get`, `set`, `remove` |
+| `dialog` | 系统对话框 | `showOpenDialog`, `showMessageBox` |
+| `notification` | 通知 | `show` |
+| `shell` | 系统外壳 | `openExternal`, `showItemInFolder` |
+| `http` | 网络请求 | `get`, `post`, `request` |
+| `system` | 系统信息 | `getSystemInfo`, `getPath` |
+| `screen` | 屏幕控制 | `capture`, `colorPick`, `getAllDisplays` |
+| `input` | 模拟输入 | `simulateKeyboardTap`, `hideMainWindowPasteText` |
+| `window` | 窗口控制 | `hide`, `setSize`, `create` |
+| `theme` | 主题 | `get`, `set` |
+| `plugin` | 插件管理 | `run`, `redirect`, `outPlugin` |
+| `features` | 动态功能 | `setFeature`, `removeFeature` |
+| `shortcut` | 全局快捷键 | `register`, `unregister` |
+| `permission` | 权限管理 | `request`, `getStatus` |
+| `security` | 安全 | `encryptString`, `decryptString` |
+| `tray` | 系统托盘 | `create`, `setIcon` |
+| `menu` | 上下文菜单 | `showContextMenu` |
+| `network` | 网络状态 | `isOnline` |
+| `power` | 电源监控 | `getSystemIdleTime`, `onAC` |
+| `media` | 媒体权限 | `hasCameraAccess` |
+| `geolocation` | 地理位置 | `getCurrentPosition` |
+| `tts` | 语音合成 | `speak` |
+| `host` | 主机控制 | `invoke` |
+| `sharp` | 图像处理 | `resize`, `toBuffer` |
+| `ffmpeg` | 音视频处理 | `run`, `download` |
+| `inbrowser` | 浏览器自动化 | `goto`, `click`, `evaluate` |
+
 #### 常用 API 快速示例
 
 ```typescript
@@ -380,7 +433,6 @@ await clipboard.writeText('Hello')
 
 // 通知
 notification.show('操作成功')
-notification.show('发生错误', 'error')
 
 // 存储
 await storage.set('key', { data: 'value' })
@@ -388,13 +440,17 @@ const data = await storage.get('key')
 
 // 文件系统
 const content = filesystem.readFile('/path/file.txt', 'utf-8')
-filesystem.writeFile('/path/output.txt', 'content', 'utf-8')
 
 // HTTP 请求
 const response = await http.post('https://api.example.com', { key: 'value' })
 
-// 对话框
-const files = await dialog.showOpenDialog({ properties: ['openFile'] })
+// 屏幕取色
+const color = await screen.colorPick()
+
+// 浏览器自动化
+await inbrowser.goto('https://google.com')
+await inbrowser.type('input[name="q"]', 'intools')
+await inbrowser.click('input[name="btnK"]')
 ```
 
 ---

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

@@ -122,7 +122,14 @@ function buildBackendMain(name) {
         route?: string
         mainHide?: boolean
         mainPush?: boolean
-        cmds: Array<string | { type: 'keyword' | 'regex'; value?: string; match?: string; explain?: string }>
+        cmds: Array<
+          | string
+          | { type: 'keyword'; value: string; explain?: string }
+          | { type: 'regex'; match: string; explain?: string; label?: string; minLength?: number; maxLength?: number }
+          | { type: 'files'; exts?: string[]; fileType?: 'file' | 'directory' | 'any'; match?: string; minLength?: number; maxLength?: number }
+          | { type: 'img'; exts?: string[] }
+          | { type: 'over'; label?: string; exclude?: string; minLength?: number; maxLength?: number }
+        >
       }) => void
       removeFeature: (code: string) => boolean
       redirectHotKeySetting: (cmdLabel: string, autocopy?: boolean) => void

package/dist/commands/pack.js

@@ -81,6 +81,17 @@ async function createArchive(cwd, outputPath, manifest) {
         if (fs.existsSync(uiDir)) {
             archive.directory(uiDir, 'ui');
         }
+        // 添加 preload 脚本（如果在 manifest 中配置了）
+        if (manifest.preload) {
+            const preloadPath = path.join(cwd, manifest.preload);
+            if (fs.existsSync(preloadPath)) {
+                archive.file(preloadPath, { name: manifest.preload });
+                console.log(chalk_1.default.gray(`  + ${manifest.preload}`));
+            }
+            else {
+                console.log(chalk_1.default.yellow(`警告: preload 文件不存在: ${manifest.preload}`));
+            }
+        }
         // 添加 README.md（如果存在）
         const readmePath = path.join(cwd, 'README.md');
         if (fs.existsSync(readmePath)) {

package/package.json

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