mulby-cli 1.1.6 → 1.1.7

package/PLUGIN_DEVELOP_PROMPT.md

@@ -2,26 +2,29 @@
 
 > **Architecture**: Mulby is built on the **Electron** framework. Plugins run in a multi-process environment.
 > **Contexts**: `UI` = **Renderer Process** (`window.mulby.{module}`), `Main` = **Main Process** (`context.api.{module}`). Most APIs are available in both contexts (marked as **R/B**).
+> **Source of Truth (when available in this repo)**: `docs/apis/README.md`, the specific `docs/apis/*.md` files, and `src/shared/types/electron.d.ts` are authoritative. The API section in this file is a curated quick reference and may lag behind newly added modules.
 
 ## 1. Project Structure
 
 ```text
 my-plugin/
-├── manifest.json       # Plugin Configuration (Manifest V2)
-├── package.json        # Dependencies (React, Vite, etc.)
-├── tsconfig.json       # TypeScript Configuration
-├── vite.config.ts      # Vite Configuration
-├── preload.cjs         # Node.js Bridge (Optional, MUST be .cjs)
-├── src/
-│   ├── main.ts         # Backend Logic (Node.js context)
-│   └── ui/             # Frontend Logic (React context)
-│       ├── main.tsx    # Entry Point
-│       ├── App.tsx     # Main Component
-│       ├── styles.css  # Styles
-│       ├── hooks/      # Custom Hooks
-│       │   └── useMulby.ts
-│       └── vite-env.d.ts
-└── assets/             # Icons, etc.
+|- manifest.json        # Plugin Configuration (Manifest V2)
+|- package.json         # Dependencies (React, Vite, etc.)
+|- tsconfig.json        # TypeScript Configuration
+|- vite.config.ts       # Vite Configuration
+|- preload.cjs          # Node.js Bridge (Optional, MUST be .cjs)
+|- src/
+|  |- main.ts           # Backend Logic (Node.js context)
+|  |- types/
+|  |  `- mulby.d.ts     # Mulby type definitions generated by the template
+|  `- ui/               # Frontend Logic (React context)
+|     |- index.html
+|     |- main.tsx       # Entry Point
+|     |- App.tsx        # Main Component
+|     |- styles.css
+|     `- hooks/
+|        `- useMulby.ts
+`- assets/              # Icons, etc.
 ```
 
 ## 1.1 Entry Points & Patterns
@@ -30,18 +33,25 @@ my-plugin/
 ```typescript
 interface PluginContext {
   api: { clipboard: any; notification: any; /* ... */ }
-  input?: string;      // Initial input (if triggered by text)
-  featureCode?: string; // Feature code structure
+  input?: string;
+  featureCode?: string;
+  attachments?: Array<{ path?: string; name?: string; kind?: 'file' | 'image' }>;
 }
 
-// Lifecycle Hooks within export
 export function onLoad() { /* Plugin Loaded */ }
 export function onUnload() { /* Plugin Unloaded */ }
+export function onEnable() { /* Plugin Enabled */ }
+export function onDisable() { /* Plugin Disabled */ }
 export async function run(context: PluginContext) {
   const { notification } = context.api;
   notification.show('Plugin Started');
 }
-export default { onLoad, onUnload, run };
+export const host = {
+  async ping(_context: PluginContext) {
+    return { ok: true };
+  }
+};
+export default { onLoad, onUnload, onEnable, onDisable, run, host };
 ```
 
 **Frontend (`src/ui/App.tsx`)**:
@@ -54,6 +64,55 @@ export default function App() {
 }
 ```
 
+## 1.2 Fixed AI Development Workflow
+
+When AI is used to generate or modify a Mulby plugin, it MUST follow this fixed workflow.
+The goal is not "write some code", but "produce a plugin that can really attach to Mulby".
+
+### Phase 0: Integration Recon
+Before proposing implementation details, inspect the current integration skeleton:
+- `manifest.json`
+- `src/main.ts`
+- `src/ui/App.tsx` (if the plugin has UI)
+- `preload.cjs` (if present)
+
+### Phase 1: Define the Plugin Contract
+Lock down the contract before coding:
+- Which `features[].code` values exist
+- Which `cmds` trigger each feature
+- Whether each feature is `ui`, `silent`, or `detached`
+- Which logic belongs to UI, backend, and preload
+- Whether background mode / scheduler / host APIs are needed
+
+### Phase 2: Build a Minimum Runnable Path
+Implement one end-to-end happy path first:
+- `manifest.json` points to the correct entry files
+- `src/main.ts` contains the real entry logic
+- UI plugins have a usable `src/ui/App.tsx`
+- `preload.cjs` is only added when Node.js / Electron bridging is required
+
+### Phase 3: Expand Features
+Only after the minimum path is attachable should you:
+- add additional feature triggers
+- refine UX and styling
+- add host methods or background capabilities
+
+### Phase 4: Validate Before Handoff
+Before claiming completion, verify all of the following:
+- `manifest.json` required fields are complete
+- every `feature.code` maps to real handling logic
+- `main`, `ui`, and `preload` paths point to files that really exist
+- `preload` uses `.cjs` and CommonJS when present
+- the plugin can be built successfully
+
+### Manual Host-Side Acceptance Checklist
+The final delivery should tell the user to test these points inside Mulby:
+1. The plugin can be installed / loaded without manifest errors
+2. At least one trigger path (`keyword`, `regex`, `files`, `img`, or `over`) actually enters the plugin
+3. The expected UI opens, or the silent feature completes without UI
+4. Detached / background / preload behavior works if configured
+5. The core user task succeeds on a realistic sample input
+
 ## 2. Manifest Configuration (`manifest.json`)
 
 ```json
@@ -154,10 +213,12 @@ window.myPluginApi = {
 }
 ```
 
-## 4. API Reference (TypeScript Definition)
+## 4. API Reference (TypeScript Quick Reference)
 
 > **R/B** = Available in both Renderer (`window.mulby`) and Backend (`context.api`).
 > **R** = Renderer only. **B** = Backend only.
+>
+> This section is intentionally a high-value quick reference, not a full spec. When you are working inside the Mulby repo, prefer `docs/apis/README.md`, the specific `docs/apis/*.md` files, and `src/shared/types/electron.d.ts` for exact current signatures. Newer modules such as `pluginStore`, `systemPage`, `systemPlugin`, `trayMenu`, and `appEvents` may exist even if they are not fully expanded below.
 
 ### Core Modules
 
@@ -766,22 +827,28 @@ interface SubInput {
 // plugin (R) - Plugin Management
 interface Plugin {
   getAll(): Promise<PluginInfo[]>;
+  listCommands(pluginId?: string): Promise<any[]>;
   search(query: string): Promise<PluginSearchResult[]>;
-  run(id: string, code: string, input?: any): Promise<void>;
-  install(path: string): Promise<void>;
+  run(id: string, code: string, input?: any): Promise<{ success: boolean; hasUI?: boolean; error?: string }>;
+  runCommand(input: any): Promise<{ success: boolean; hasUI?: boolean; error?: string }>;
+  getRecentUsed(limit?: number): Promise<any[]>;
+  install(path: string): Promise<{ success: boolean; error?: string }>;
   enable(name: string): Promise<{ success: boolean; error?: string }>;
   disable(name: string): Promise<{ success: boolean; error?: string }>;
-  uninstall(id: string): Promise<void>;
-  outPlugin(kill?: boolean): Promise<void>;
+  uninstall(id: string): Promise<{ success: boolean; error?: string }>;
+  outPlugin(kill?: boolean): Promise<boolean>;
   redirect(label: string, payload?: any): Promise<boolean>;
-  getReadme(id: string): Promise<string>;
+  getReadme(id: string): Promise<string | null>;
   
   // Background & Process Management
   listBackground(): Promise<any[]>;
   startBackground(pluginId: string): Promise<{ success: boolean; error?: string }>;
   stopBackground(pluginId: string): Promise<{ success: boolean }>;
-  getBackgroundInfo(pluginId: string): Promise<any>;
-  stopPlugin(pluginId: string): Promise<void>;
+  getBackgroundInfo(pluginId: string): Promise<any | null>;
+  stopPlugin(pluginId: string): Promise<{ success: boolean; error?: string }>;
+  listCommandShortcuts?(pluginId?: string): Promise<any[]>;
+  bindCommandShortcut?(input: any): Promise<{ success: boolean; error?: string }>;
+  unbindCommandShortcut?(bindingId: string): Promise<{ success: boolean }>;
 }
 
 // theme (R)
@@ -829,10 +896,10 @@ interface Screen {
   getPrimaryDisplay(): Promise<any>;
   getCursorScreenPoint(): Promise<{ x: number; y: number }>;
   capture(opts?: { sourceId?: string; format?: 'png'|'jpeg' }): Promise<Buffer>;
-  captureRegion(rect: { x: number; y: number; w: number; h: number }, opts?: any): Promise<Buffer>;
-  screenCapture(): Promise<string>; // R only, Interactive
-  colorPick(): Promise<{ hex: string }>; // R only
-  getSources(opts?: { types: string[] }): Promise<any[]>;
+  captureRegion(region: { x: number; y: number; width: number; height: number }, opts?: any): Promise<Buffer>;
+  screenCapture(): Promise<string | null>; // R only, Interactive
+  colorPick(): Promise<{ hex: string } | null>; // R only
+  getSources(opts?: { types?: string[]; thumbnailSize?: { width: number; height: number } }): Promise<any[]>;
 }
 
 // input (R/B) - Simulate Input
@@ -962,9 +1029,10 @@ export function onUnload() { /* Cleanup (Called on app exit or manual stop) */ }
 
 ### 5.3 Management API
 
-- **Check Status**: `api.plugin.listBackground()`
-- **Stop**: `api.plugin.stopBackground(pluginId)`
-- **Start**: `api.plugin.startBackground(pluginId)`
+- **Backend Lifecycle Hooks**: `onBackground()` / `onForeground()` in `src/main.ts`
+- **Renderer Status List**: `window.mulby.plugin.listBackground()`
+- **Renderer Start / Stop**: `window.mulby.plugin.startBackground(pluginId)` / `window.mulby.plugin.stopBackground(pluginId)`
+- **Renderer Inspect / Stop Running Plugin**: `window.mulby.plugin.getBackgroundInfo(pluginId)` / `window.mulby.plugin.stopPlugin(pluginId)`
 
 ### 5.4 UI Plugin Integration
 
@@ -973,10 +1041,13 @@ For plugins with UI (`"ui": "..."` in manifest):
 2. **Frontend** (`src/ui/...`) stops when window closes.
 3. Use IPC (via `api.messaging` or `host` module) to communicate between active UI and background backend.
 
-## 6. Task Scheduler (Backend Only)
+## 6. Task Scheduler (Backend-First)
 
 Schedule tasks to run at specific times or intervals. Tasks persist across app restarts.
 
+- Use `context.api.scheduler` in backend code to create and manage the current plugin's own tasks.
+- Use `window.mulby.scheduler` in renderer code for task dashboards, task counts, cleanup, and other management UI.
+
 ### 6.1 Creating Tasks
 
 ```typescript
@@ -1030,29 +1101,25 @@ export async function onBackup({ api }) {
 ### 6.3 Managing Tasks
 
 ```typescript
-// List tasks (current plugin only)
+// Backend: list tasks created by the current plugin
 const tasks = await api.scheduler.list();
 const pending = await api.scheduler.list({ status: 'pending' });
 
-// Pagination
-const page1 = await api.scheduler.list({ limit: 20, offset: 0 });
-const totalCount = await api.scheduler.count({ status: 'pending' });
+// Backend pagination and details
+const page1 = await api.scheduler.list({ limit: 20 });
+const task = await api.scheduler.get(taskId);
+const history = await api.scheduler.getExecutions(taskId, 10);
 
-// Control tasks
+// Backend control
 await api.scheduler.pause(taskId);
 await api.scheduler.resume(taskId);
 await api.scheduler.cancel(taskId);
 
-// Batch operations
-await api.scheduler.deleteTasks([taskId1, taskId2, taskId3]);
-
-// Cleanup old tasks (completed/failed/cancelled)
-await api.scheduler.cleanup();  // Default: 7 days ago
-await api.scheduler.cleanup(Date.now() - 30 * 24 * 60 * 60 * 1000);  // 30 days
-
-// Query
-const task = await api.scheduler.get(taskId);
-const history = await api.scheduler.getExecutions(taskId, 10);
+// Renderer: management UI / dashboards
+const visibleTasks = await window.mulby.scheduler.listTasks({ status: 'pending' });
+const totalCount = await window.mulby.scheduler.getTaskCount({ status: 'pending' });
+await window.mulby.scheduler.deleteTasks([taskId1, taskId2, taskId3]);
+await window.mulby.scheduler.cleanupTasks(Date.now() - 30 * 24 * 60 * 60 * 1000);
 ```
 
 ### 6.4 Advanced Options

package/README.md

@@ -781,6 +781,19 @@ Mulby CLI 内置了智能任务规划系统，自动识别复杂任务并帮助
 3. **逐步执行** - 按照计划执行，完成一项勾选一项
 4. **进度保存** - 中途退出自动保存，下次可继续
 
+### AI 插件开发固定流程
+
+对 `mulby create <name> --ai`，建议始终遵循这 6 个阶段：
+
+1. 先读取 `manifest.json`、`src/main.ts`、`src/ui/App.tsx`
+2. 明确 `features/cmds`、UI/主进程/预加载的职责边界
+3. 先确认接入契约，再开始改文件
+4. 先做一个能在 Mulby 里触发的最小闭环
+5. 再补完整功能与体验
+6. 完成前运行 `validate_plugin`，确认接入检查通过
+
+这个流程借鉴了 uTools 官方开发文档里“先锁定插件入口契约，再调试、打包、发布”的成熟做法。
+
 ### 使用方式
 
 **自动触发（推荐）**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mulby-cli",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Mulby 插件开发 CLI 工具",
   "main": "dist/index.js",
   "files": [
@@ -12,8 +12,10 @@
     "mulby": "dist/index.js"
   },
   "scripts": {
-    "build": "tsc && cp src/services/ai/*.md dist/services/ai/",
-    "dev": "tsc -w"
+    "build": "tsc && node scripts/copy-ai-assets.mjs",
+    "dev": "tsc -w",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm run build"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.71.2",