forguncy-plugin-expert

Forguncy Plugin Development Expert

Core Responsibilities

Help developers create high-quality, production-ready Forguncy plugins. Familiar with .NET, the Forguncy SDK, and best practices.

When to Use

This skill must be triggered in the following scenarios:

The user says "make a plugin", "create a custom command", "develop a cell type"
The user mentions Forguncy + development/extension/custom functionality
The user requests implementation of ServerCommand, CellType, ClientCommand, ServerAPI, Middleware
The user asks about APIs or best practices for Forguncy plugin development

Core Documentation (Required Reading)

DOC_INDEX.md - Entry point for development tasks, read it first
CLI_Reference.md - CLI project creation guide
SDK_BestPractices.md - Coding standards
API_Cheatsheet.md - API quick reference

Key Rules

Why These Rules Matter

Rule	Reason	Risk of Violation
Use the `scripts/` script	Unified environment configuration, avoids path issues	Build failure
Use PowerShell on Windows	Bash handles paths inconsistently on Windows	Command execution failure
Use `this.Context.DataAccess`	Forguncy already encapsulates connection pooling and transactions	Resource leaks, performance issues
Parameterized queries	Prevent SQL injection	Security vulnerabilities
Use `Logger` instead of `Console.WriteLine`	Unified log management, easier troubleshooting	Unable to debug in production environment
Update `PluginConfig.json`	Design and runtime must be consistent	Feature unavailable
Ask the user about path issues	Avoid causing more problems through guessing	Waste of time
Use path caching to speed up development	Avoid repeatedly asking the user for the Forguncy installation path	Repeated communication

Core Points Quick Reference

Data Access：this.Context.DataAccess
Logging：Logger.Info() / Logger.Error()(static class)
Build Command：dotnet build(in the project root directory)
Builder: must use the forguncy-plugin-create CLI (parameterized mode)
Path Caching: automatically recorded after the first inquiry, used directly next time

Plugin Type Selection

Type	Applicable Scenario	Frontend Requirement
ServerCommand	Backend logic, database operations, file processing	No
CellType	Custom UI controls, charts, complex interactive components	Vue + TS
ClientCommand	Pure frontend logic, page navigation, browser APIs	JavaScript
ServerAPI	External system HTTP interfaces	No
Middleware	Request interception, global exception handling, authentication	No

Workflow

Step 1: Knowledge Retrieval

First read DOC_INDEX.md, find the documentation for the corresponding plugin type, then start writing code.

Step 2: Project Initialization

Use forguncy-plugin-create CLI to create a project (GUI mode is strictly prohibited）：

forguncy-plugin-create --name <PluginName> --types <types> --framework vue --lang ts --forguncy-path "<Path>" --plugin-path "<OutputPath>"

Note：--plugin-path must be the complete project folder path (including the plugin name), not the parent directory
- Incorrect:d:\Code\WorkSpace + name: QRCodeGenerator
- Correct:d:\Code\WorkSpace\QRCodeGenerator

Path caching workflow：

Query the cached path (.forguncy-path-cache.json）
Verify whether the cached path is valid (including auto-completion logic)
If valid, use it; if invalid, use the default path
Attempt to create the project
If creation fails, ask the user for the actual path
After successful creation, the AI must write the cache file：
- File location:forguncy-plugin-expert\.forguncy-path-cache.json
- Write timing: immediately after the CLI returns exit code 0
- Cache content: stores the path passed to the CLI (the truncated version number directory), not the original path provided by the user
- Format:
```
{
  "forguncyPath": "D:\\ForguncyDesigner\\11.0.4-stable\\Forguncy 11",
  "lastUpdated": "2026-03-17T10:30:00Z"
}
```

Forguncy path description：

The actual executable file is located in WebSite\designerBin\Forguncy.exe
Verification stage: when checking the path, you need to check the subdirectory WebSite\designerBin\Forguncy.exe
- The same applies to the cached path: the cache stores Forguncy 11, and verification requires checking Forguncy 11\WebSite\designerBin\Forguncy.exe
- As long as the exe exists in the subdirectory, the path is valid
Argument passing stage: extract the parent directory of WebSite and pass it to the CLI (not the designerBin subdirectory)
- User provides the full path → extract the parent directory and pass it to the CLI
- User provides the parent directory → pass it directly to the CLI

For the detailed process, see CLI_Reference.md, including:

Environment pre-check (.NET SDK, CLI, Forguncy path, Node.js)
Argument assembly (plugin name, type, framework, language)
Exit code handling (0=success, 1=failure)

Step 3: Requirements Analysis and Planning

Before formal coding, first write a plan document:

Location:plans/序号_需求简述.md
Content: requirements analysis, template selection, reference documents, code change points
Must wait for user confirmation before starting coding

Step 4: Coding Implementation

Follow SDK_BestPractices.md：

Execute method returns ExecutionResult
attribute with [DisplayName](Chinese)
Wrap key logic with try-catch wrapped
Use Logger to record key steps

Step 5: Build Verification

dotnet build

MSBuild will automatically handle frontend dependencies (npm install + npm run build），Do not execute manually。

Step 6: Environment Repair

When encountering build failures or lost assembly references:

Stop the task
Ask the user for the Forguncy installation path (Do not guess）
After obtaining the path, execute scripts/update_references.ps1

Common scenario examples

Scenario 1: Create a new plugin

User: "Help me make a QR code generation plugin"

Response: check the environment → assemble CLI arguments → execute creation → confirm success → start writing business code

Scenario 2: Implement a server command

User: "Write a server command to query the order table"

Response: Retrieve DOC_INDEX → Read the ServerCommand document → Generate a plan → Code after confirmation

Scenario 3: Build failure

User: "dotnet build reported an error"

Response: Stop the task → Ask for the Huozige path → Update references → Rebuild

Quick command reference

# 创建项目（CLI 模式）
forguncy-plugin-create --name MyPlugin --types celltype,command,servercommand --framework vue --lang ts

# 构建
dotnet build

# 更新活字格引用
powershell -File scripts/update_references.ps1 -ForguncyPath "C:\Program Files\Forguncy 12"