# IJS 插件开发文档 (v1.1)

## 目录

- [插件结构](#插件结构)
- [快速开始](#快速开始)
- [插件代码规范](#插件代码规范)
- [Symja API 完整参考](#symja-api-完整参考)

---

## 插件结构

插件是 JSON 格式的配置文件，包含以下字段：

```json
{
  "id": "plugin_id",
  "name": "插件名称",
  "description": "插件描述",
  "icon": "📐",
  "command": "cmd",
  "inputs": [
    {
      "name": "input1",
      "label": "输入标签",
      "defaultValue": "0",
      "placeholder": "提示文本"
    }
  ],
  "jsCode": "function calculate(inputs, Symja) { ... }"
}
```

### 字段说明

- `id` - 插件唯一标识符
- `name` - 插件显示名称
- `description` - 插件功能描述
- `icon` - 插件图标（emoji）
- `command` - 快捷命令（可选），用于命令行执行
- `inputs` - 输入参数数组
  - `name` - 参数名称（代码中访问）
  - `label` - 参数标签（显示给用户）
  - `defaultValue` - 默认值（可选）
  - `placeholder` - 提示文本（可选）
- `jsCode` - 插件计算代码

---

## 快速开始

### 示例 1：圆面积计算器

```json
{
  "id": "circle_area",
  "name": "圆面积计算器",
  "description": "计算圆的面积",
  "icon": "⭕",
  "command": "circle",
  "inputs": [
    {
      "name": "radius",
      "label": "半径",
      "defaultValue": "1",
      "placeholder": "输入半径"
    }
  ],
  "jsCode": "function calculate(inputs, Symja) {\n  const r = inputs.radius;\n  if (!r || parseFloat(r) <= 0) {\n    throw new Error('半径必须是正数');\n  }\n  Symja.print(`计算半径为 ${r} 的圆面积`);\n  return `Pi*${r}^2`;\n}"
}
```

**使用方式：**
- 对话框：点击插件图标打开
- 命令行：`circle[5]` 直接计算半径为 5 的圆面积
- 结果引用：`%` 可引用上次结果，如 `% /. Pi->3.14`

### 示例 2：导数计算器

```json
{
  "id": "derivative_calculator",
  "name": "导数计算器",
  "description": "计算函数的导数",
  "icon": "📈",
  "command": "deriv",
  "inputs": [
    {
      "name": "function",
      "label": "函数表达式",
      "defaultValue": "x^2 + 3*x",
      "placeholder": "例如: x^2 + 3*x"
    },
    {
      "name": "variable",
      "label": "变量",
      "defaultValue": "x",
      "placeholder": "例如: x"
    }
  ],
  "jsCode": "function calculate(inputs, Symja) {\n  const func = inputs.function;\n  const variable = inputs.variable;\n  if (!func || !variable) {\n    throw new Error('请输入函数和变量');\n  }\n  Symja.print(`对 ${func} 关于 ${variable} 求导`);\n  return Symja.differentiate(func, variable);\n}"
}
```

**使用方式：**
- 命令行：`deriv[x^3, x]` 计算 x³ 的导数
- 列表参数：`deriv[{x^2, x^3}, x]` 列表作为一个参数

---

## 插件代码规范

### v1.1 核心特性

1. **输入自动转换**
   - 用户输入会自动验证并转换为 Symja 可运算类型
   - 插件可直接使用 `inputs.xxx` 进行计算

2. **Symja.print() 输出**
   - 用于输出说明文本，不影响返回值
   - 示例：`Symja.print('计算中...')`

3. **返回值要求**
   - 必须返回有效的 Symja 表达式（如 `'x^2'`、`'Pi*r^2'`）
   - 系统会自动验证返回值
   - 返回值可通过 `%` 在后续计算中引用

4. **命令执行语法**
   - 定义 `command` 字段后，可用 `command[arg1, arg2]` 直接执行
   - 支持列表参数：`command[{1,2}, {3,4}]` 有 2 个参数
   - 支持嵌套：`command[{{1,2},{3,4}}]` 矩阵作为 1 个参数

5. **自动补全**
   - 输入命令时自动提示参数
   - 按 Tab 或点击补全

### 代码模板

```javascript
function calculate(inputs, Symja) {
  // 1. 获取输入（已自动转换为可运算类型）
  const param1 = inputs.param1;
  
  // 2. 输入验证
  if (!param1) {
    throw new Error('请输入参数');
  }
  
  // 3. 输出说明信息（可选）
  Symja.print('正在计算...');
  
  // 4. 执行计算
  const result = Symja.eval(`SomeFunction[${param1}]`);
  
  // 5. 返回可运算的 Symja 表达式
  return result;
}
```

### 重要规则

- ✅ 函数签名必须是 `function calculate(inputs, Symja) { ... }`
- ✅ 输入值自动转换，可直接用于计算
- ✅ 必须返回有效的 Symja 表达式
- ✅ 使用 `Symja.print()` 输出说明，不影响返回值
- ✅ 使用 `throw new Error()` 抛出错误
- ✅ 所有 Symja API 参数都是字符串类型

---

## Symja API 完整参考

### 输入输出

| API | 说明 | 示例 |
|-----|------|------|
| `inputs.xxx` | 获取输入参数（已自动转换） | `inputs.radius` |
| `Symja.print(msg)` | 输出说明文本 | `Symja.print('计算中...')` |
| `return expr` | 返回可运算表达式 | `return 'Pi*r^2'` |

### 基础计算

| API | 说明 | 示例 |
|-----|------|------|
| `Symja.eval(expr)` | 执行任意 Symja 表达式 | `Symja.eval('2+2')` |

### 微积分

| API | 说明 | 示例 |
|-----|------|------|
| `differentiate(expr, var)` | 求导数 | `Symja.differentiate('x^2', 'x')` |
| `integrate(expr, var)` | 求不定积分 | `Symja.integrate('x^2', 'x')` |
| `limit(expr, var, point, dir)` | 求极限 | `Symja.limit('Sin[x]/x', 'x', '0')` |
| `series(expr, var, point, order)` | 泰勒级数 | `Symja.series('Exp[x]', 'x', '0', '5')` |

### 代数运算

| API | 说明 | 示例 |
|-----|------|------|
| `solve(eq, var)` | 解方程 | `Symja.solve('x^2-4==0', 'x')` |
| `simplify(expr)` | 化简 | `Symja.simplify('(x^2-1)/(x-1)')` |
| `expand(expr)` | 展开 | `Symja.expand('(x+1)^3')` |
| `factor(expr)` | 因式分解 | `Symja.factor('x^2-4')` |
| `apart(expr, var)` | 部分分式 | `Symja.apart('1/(x^2-1)', 'x')` |
| `together(expr)` | 通分 | `Symja.together('1/x + 1/y')` |
| `trigSimplify(expr)` | 三角化简 | `Symja.trigSimplify('Sin[x]^2+Cos[x]^2')` |

### 求和与求积

| API | 说明 | 示例 |
|-----|------|------|
| `sum(expr, var, start, end)` | 求和 | `Symja.sum('i^2', 'i', '1', '10')` |
| `product(expr, var, start, end)` | 求积 | `Symja.product('i', 'i', '1', '5')` |

### 矩阵运算

| API | 说明 | 示例 |
|-----|------|------|
| `matrix.det(matrix)` | 行列式 | `Symja.matrix.det('{{1,2},{3,4}}')` |
| `matrix.inverse(matrix)` | 逆矩阵 | `Symja.matrix.inverse('{{1,2},{3,4}}')` |
| `matrix.transpose(matrix)` | 转置 | `Symja.matrix.transpose('{{1,2},{3,4}}')` |
| `matrix.eigenvalues(matrix)` | 特征值 | `Symja.matrix.eigenvalues('{{1,2},{3,4}}')` |
| `matrix.rank(matrix)` | 矩阵秩 | `Symja.matrix.rank('{{1,2},{3,4}}')` |

### 数论

| API | 说明 | 示例 |
|-----|------|------|
| `gcd(a, b)` | 最大公约数 | `Symja.gcd('12', '18')` |
| `lcm(a, b)` | 最小公倍数 | `Symja.lcm('12', '18')` |
| `factorInteger(n)` | 质因数分解 | `Symja.factorInteger('60')` |
| `isPrime(n)` | 判断素数 | `Symja.isPrime('17')` |

### 组合数学

| API | 说明 | 示例 |
|-----|------|------|
| `fibonacci(n)` | 斐波那契数 | `Symja.fibonacci('10')` |
| `binomial(n, k)` | 组合数 C(n,k) | `Symja.binomial('5', '2')` |

### 数值计算

| API | 说明 | 示例 |
|-----|------|------|
| `numeric(expr, precision)` | 高精度数值计算 | `Symja.numeric('Pi', '50')` |

### LaTeX 支持

| API | 说明 | 示例 |
|-----|------|------|
| `toTeX(expr)` | 转换为 LaTeX | `Symja.toTeX('x^2 + 2*x + 1')` |
| `renderLatex(latex)` | 渲染 LaTeX | `Symja.renderLatex('\\frac{1}{2}')` |

---

## 插件位置

插件文件保存在：
```
/storage/emulated/0/Android/data/com.nonvioce.ijs/files/plugins/
```

可以直接在该目录创建 `.json` 文件来添加插件。