# Forguncy Plugin Expert

> 活字格插件开发专家 - 为活字格低代码平台创建服务器命令(ServerCommand)、单元格类型(CellType)、客户端命令(ClientCommand)、服务器API和中间件。当用户提到"做个插件"、"创建自定义命令"、"开发单元格类型"、"Forguncy扩展"、"活字格自定义功能"，或请求"帮我写个服务器命令"、"实现一个控件"时，必须使用此技能。即使用户没有明确说"插件专家"，只要涉及活字格功能开发，都应该触发此技能。

- Skill: `nimotea/forguncy-plugin-expert` (Agent Skill, multi-file: 78 files)
- Install (CLI): `npx skillmds@latest add nimotea/forguncy-plugin-expert`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nimotea/forguncy-plugin-expert/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: nimotea (https://skillmd.com/u/nimotea)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nimotea/forguncy-plugin-expert

---


# 活字格 (Forguncy) 插件开发专家

## 核心职责

帮助开发者创建高质量、生产就绪的活字格插件。熟悉 .NET、活字格 SDK 和最佳实践。

## 何时使用

以下场景必须触发此技能：

- 用户说"做个插件"、"创建自定义命令"、"开发单元格类型"
- 用户提到 Forguncy/活字格 + 开发/扩展/自定义功能
- 用户请求实现 ServerCommand、CellType、ClientCommand、ServerAPI、Middleware
- 用户询问活字格插件开发的 API 或最佳实践

## 核心文档（必读）

- [DOC\_INDEX.md](references/DOC_INDEX.md) - 开发任务入口，先读它
- [CLI\_Reference.md](references/CLI_Reference.md) - CLI 项目创建指南
- [SDK\_BestPractices.md](references/SDK_BestPractices.md) - 编码规范
- [API\_Cheatsheet.md](references/API_Cheatsheet.md) - API 速查

## 关键规则

### 为什么这些规则重要

| 规则                                | 原因                      | 违规风险      |
| --------------------------------- | ----------------------- | --------- |
| 使用 `scripts/` 脚本                  | 统一环境配置，避免路径问题           | 构建失败      |
| Windows 用 PowerShell              | Bash 在 Windows 下路径处理不一致 | 命令执行失败    |
| 用 `this.Context.DataAccess`       | 活字格已封装连接池和事务            | 资源泄漏、性能问题 |
| 参数化查询                             | 防止 SQL 注入               | 安全漏洞      |
| 用 `Logger` 而非 `Console.WriteLine` | 日志统一管理，便于排查             | 生产环境无法调试  |
| 更新 `PluginConfig.json`            | 设计与运行时必须一致              | 功能不可用     |
| 路径问题问用户                           | 避免猜测导致更多问题              | 浪费时间      |
| 使用路径缓存加速开发                     | 避免重复询问用户活字格安装路径        | 重复沟通      |

### 核心要点速记

- **数据访问**：`this.Context.DataAccess`
- **日志**：`Logger.Info()` / `Logger.Error()`（静态类）
- **构建命令**：`dotnet build`（在项目根目录）
- **构建器**：必须用 `forguncy-plugin-create` CLI（参数化模式）
- **路径缓存**：首次询问后自动记录，下次直接使用

## 插件类型选择

| 类型                | 适用场景                | 前端需求       |
| ----------------- | ------------------- | ---------- |
| **ServerCommand** | 后端逻辑、数据库操作、文件处理     | 否          |
| **CellType**      | 自定义 UI 控件、图表、复杂交互组件 | Vue + TS   |
| **ClientCommand** | 纯前端逻辑、页面跳转、浏览器 API  | JavaScript |
| **ServerAPI**     | 外部系统 HTTP 接口        | 否          |
| **Middleware**    | 请求拦截、全局异常处理、认证      | 否          |

## 工作流程

### Step 1: 知识检索

先读 [DOC\_INDEX.md](references/DOC_INDEX.md)，找到对应插件类型的文档，再开始编写代码。

### Step 2: 项目初始化

使用 `forguncy-plugin-create` CLI 创建项目（**严禁 GUI 模式**）：

```bash
forguncy-plugin-create --name <PluginName> --types <types> --framework vue --lang ts --forguncy-path "<Path>" --plugin-path "<OutputPath>"
```
- **注意**：`--plugin-path` 必须是完整的项目文件夹路径（包含插件名称），不是父目录
  - 错误：`d:\Code\WorkSpace` + name: `QRCodeGenerator`
  - 正确：`d:\Code\WorkSpace\QRCodeGenerator`

**路径缓存流程**：

1. 查询缓存路径（`.forguncy-path-cache.json`）
2. 验证缓存路径是否有效（含自动补全逻辑）
3. 有效则使用，无效则使用默认路径
4. 尝试创建项目
5. 如果创建失败，询问用户实际路径
6. **创建成功后，AI 必须写入缓存文件**：
   - 文件位置：`forguncy-plugin-expert\.forguncy-path-cache.json`
   - 写入时机：CLI 返回退出码 0 后，立即写入
   - **缓存内容**：存储传给 CLI 的路径（截取后的版本号目录），不是用户提供原始路径
   - 格式：
     ```json
     {
       "forguncyPath": "D:\\ForguncyDesigner\\11.0.4-stable\\Forguncy 11",
       "lastUpdated": "2026-03-17T10:30:00Z"
     }
     ```

**活字格路径说明**：
- 实际可执行文件位于 `WebSite\designerBin\Forguncy.exe`
- **验证阶段**：检查路径时需要检查子目录 `WebSite\designerBin\Forguncy.exe`
  - 缓存路径同理：缓存存的是 `Forguncy 11`，验证时要查 `Forguncy 11\WebSite\designerBin\Forguncy.exe`
  - 只要子目录存在 exe，就说明路径有效
- **传参阶段**：提取 `WebSite` 的父目录传给 CLI（而不是 `designerBin` 子目录）
  - 用户提供完整路径 → 提取上级目录传给 CLI
  - 用户提供上级目录 → 直接传给 CLI

详细流程见 [CLI\_Reference.md](references/CLI_Reference.md)，包括：

- 环境预检（.NET SDK、CLI、活字格路径、Node.js）
- 参数组装（插件名称、类型、框架、语言）
- 退出码处理（0=成功，1=失败）

### Step 3: 需求分析与计划

正式编码前，先写计划文档：

- 位置：`plans/序号_需求简述.md`
- 内容：需求分析、模板选择、参考文档、代码变更点
- **必须等用户确认后再开始编码**

### Step 4: 编码实现

遵循 [SDK\_BestPractices.md](references/SDK_BestPractices.md)：

- `Execute` 方法返回 `ExecutionResult`
- 属性带 `[DisplayName]`（中文）
- 关键逻辑用 `try-catch` 包裹
- 用 `Logger` 记录关键步骤

### Step 5: 构建验证

```bash
dotnet build
```

MSBuild 会自动处理前端依赖（`npm install` + `npm run build`），**不要手动执行**。

### Step 6: 环境修复

遇到构建失败、程序集引用丢失：

1. 停止任务
2. 询问用户活字格安装路径（**不要猜测**）
3. 获得路径后执行 `scripts/update_references.ps1`

## 常见场景示例

**场景 1：创建新插件**

> 用户："帮我做个二维码生成的插件"
>
> 响应：检查环境 → 组装 CLI 参数 → 执行创建 → 确认成功 → 开始编写业务代码

**场景 2：实现服务器命令**

> 用户："写一个服务器命令，查询订单表"
>
> 响应：检索 DOC\_INDEX → 读取 ServerCommand 文档 → 生成计划 → 确认后编码

**场景 3：构建失败**

> 用户："dotnet build 报错了"
>
> 响应：停止任务 → 询问活字格路径 → 更新引用 → 重新构建

## 快速命令参考

```bash
# 创建项目（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"
```