# pvfUtility WebApi 完整接口文档（AI 读取版）

本文是 `public/README.md` 的结构化整理版，适合 AI、插件作者和脚本工具下载读取。

## 1. 基础信息

- 默认本地服务地址：`http://localhost:27000/Api/PvfUtiltiy/`
- 前提：pvfUtility 已启动，并且已经打开目标 PVF。
- 主要返回格式：JSON。
- 常见返回字段：
  - `Data`：业务数据。
  - `IsError`：是否错误，旧接口常见。
  - `Msg`：错误或提示信息。
  - `ErrorId`：错误码，新接口可能包含。

> 注意：原始 README 中少量接口路径写作 `/Api/PvfUtility/`，本文保留原始接口名；实际使用时以当前软件版本开放路由为准。

## 2. 通用返回示例

```json
{
  "Data": {},
  "IsError": false,
  "Msg": null,
  "ErrorId": 0
}
```

## 3. 接口总览

| 分类 | 方法 | 接口 | 用途 |
| --- | --- | --- | --- |
| 基础 | GET | `/getVersion` | 获取 pvfUtility 版本号 |
| 读取解析 | GET | `/getPvfRootDirectory` | 获取 PVF 根目录列表 |
| 读取解析 | GET | `/GetFileList` | 获取文件列表 |
| 读取解析 | GET | `/GetFileContent` | 获取单个文件内容 |
| 读取解析 | POST | `/GetFileContents` | 批量获取文件内容 |
| 读取解析 | GET | `/getFileData` | 获取结构化 JSON 文件数据 |
| 读取解析 | GET | `/GetAllLstFileList` | 获取主要 LST 文件列表 |
| 写入删除 | GET | `/DeleteFile` | 删除单个文件 |
| 写入删除 | POST | `/DeleteFiles` | 批量删除文件 |
| 写入删除 | POST | `/ImportFile` | 新增或覆盖单个文件内容 |
| 写入删除 | POST | `/ImportFiles` | 批量新增或覆盖文件内容 |
| 物品 | GET | `/GetItemInfo` | 根据文件路径获取物品信息 |
| 物品 | POST | `/GetItemInfos` | 批量获取物品信息 |
| UI 状态 | GET | `/GetTreeListFocusedFilePath` | 获取文件资源管理器焦点文件 |
| UI 状态 | GET | `/GetSearchPanelTreeListFocusedFilePath` | 获取查找面板焦点文件 |
| UI 状态 | GET | `/GetActiveDocumentFilePath` | 获取当前编辑文档路径 |
| 路径转换 | POST | `/FileListToLstRows` | 文件路径集合转换为 LST 行 |
| 状态检查 | GET | `/FileIsExists` | 判断文件是否存在 |
| UI 状态 | GET | `/GetTreeSelectedFiles` | 获取文件资源管理器选中文件 |
| UI 状态 | GET | `/GetSearchPanelSelectedFiles` | 获取查找面板选中文件 |
| 封包 | GET | `/SaveAsPvfFile` | PVF 另存为封包 |
| 封包 | GET | `/GetPvfPackFilePath` | 获取当前封包文件路径 |
| 搜索 | POST | `/SearchPvf` | 搜索 PVF |
| 物品/LST | GET | `/ItemCodeToFileInfo` | 物品代码转文件信息 |
| 物品/LST | POST | `/ItemCodesToFileInfos` | 批量物品代码转文件信息 |
| 资源 | GET | `/getFileIcon` | 获取文件图标 Base64 |
| 物品/LST | GET | `/getLstFileInfo` | 获取 LST 文件信息 |
| 字符串 | GET | `/getStringTable` | 获取 stringtable.bin 明文数据 |
| 资源 | POST | `/filesToIconBase64` | 批量获取图标 Base64 |
| 状态检查 | GET | `/folderExists` | 判断文件夹或文件是否存在 |
| UI 定位 | GET | `/goToTreeListNode` | 跳转到资源管理器节点 |

## 4. 基础接口

### GET /getVersion

获取 pvfUtility 版本号。

```http
GET http://localhost:27000/Api/PvfUtiltiy/getVersion
```

返回示例：

```json
{"Data":"2022.9.30.3","IsError":false,"Msg":null}
```

## 5. 文件读取与解析

### GET /getPvfRootDirectory

获取 PVF 根目录列表。

```http
GET http://localhost:27000/Api/PvfUtiltiy/getPvfRootDirectory
```

版本要求：2022.9.30.2+

### GET /GetFileList

获取指定目录下的文件列表。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetFileList?dirName=equipment&returnType=0&fileType=.equ
```

参数：

- `dirName`：目录名称，例如 `equipment`。
- `returnType`：返回形式，原始 README 示例包含 `returnType=1`。
- `fileType`：文件后缀过滤，例如 `.equ`。版本要求：2022.08.08.2+

### GET /GetFileContent

读取单个文件内容。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetFileContent?filePath=equipment/example.equ&useCompatibleDecompiler=false&encodingType=UTF8
```

参数：

- `filePath`：PVF 内文件路径。
- `useCompatibleDecompiler`：是否使用兼容性反编译器，`true` 或 `false`。
- `encodingType`：文本编码，可为 `CN`、`TW`、`KR`、`JP`、`UTF8`、`Unicode` 或 `null`。版本要求：2022.12.3.1+

### POST /GetFileContents

批量读取多个文件内容。

```http
POST http://localhost:27000/Api/PvfUtiltiy/GetFileContents
Content-Type: application/json

{
  "FileList": [
    "creature/aquajello/aquajello.cre",
    "creature/aquajello/attackinfo/overskill.atk"
  ],
  "UseCompatibleDecompiler": false,
  "EncodingType": null
}
```

### GET /getFileData

以 JSON 节点树返回 PVF 文件内容。

```http
GET http://localhost:27000/Api/PvfUtiltiy/getFileData?filePath=appendage/example.apd
```

返回节点模型字段：

- `SectionName`：标签名称。
- `IsSection`：是否为标签。
- `HasEndSection`：是否有结束标签。
- `DataType`：数据类型。
- `Value`：数据值。
- `Children`：子节点集合。

### GET /GetAllLstFileList

获取主要 LST 文件列表。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetAllLstFileList
```

## 6. 文件写入与删除

### GET /DeleteFile

删除单个文件。

```http
GET http://localhost:27000/Api/PvfUtiltiy/DeleteFile?filePath=equipment/example.equ
```

### POST /DeleteFiles

批量删除文件。

```http
POST http://localhost:27000/Api/PvfUtiltiy/DeleteFiles
Content-Type: application/json

[
  "equipment/creature/aquajello.equ",
  "equipment/creature/asuna.equ"
]
```

### POST /ImportFile

新增或覆盖单个文件内容。

```http
POST http://localhost:27000/Api/PvfUtiltiy/ImportFile?filePath=equipment/example.equ
Content-Type: text/plain

#PVF_File
...
```

### POST /ImportFiles

批量新增或覆盖文件内容。

```http
POST http://localhost:27000/Api/PvfUtiltiy/ImportFiles
Content-Type: application/json

[
  {"FilePath":"equipment/a.equ","FileContent":"#PVF_File..."},
  {"FilePath":"equipment/b.equ","FileContent":"#PVF_File..."}
]
```

## 7. 物品与 LST

### GET /GetItemInfo

根据文件路径获取物品名称和物品代码。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetItemInfo?filePath=equipment/character/common/amulet/100300001.equ
```

### POST /GetItemInfos

批量获取物品名称和物品代码。

```http
POST http://localhost:27000/Api/PvfUtiltiy/GetItemInfos
Content-Type: application/json

[
  "equipment/character/common/amulet/100300001.equ",
  "equipment/character/common/amulet/100300004.equ"
]
```

### GET /ItemCodeToFileInfo

使用物品代码转换为文件信息。

```http
GET http://localhost:27000/Api/PvfUtiltiy/ItemCodeToFileInfo?lstNames=equipment,stackable&itemCode=27098
```

参数：

- `lstNames`：物品代码所在 LST 名称，多个用英文逗号分隔。
- `itemCode`：物品代码。

提示：`lstNames` 如果包含 `/`，请 URL 编码。不要混传可能编号重复的不同职业技能 LST。

### POST /ItemCodesToFileInfos

批量使用物品代码转换为文件信息。

```http
POST http://localhost:27000/Api/PvfUtiltiy/ItemCodesToFileInfos
Content-Type: application/json

{
  "lstNames": ["equipment", "stackable"],
  "ItemCodes": [1251, 27098]
}
```

### GET /getLstFileInfo

获取 LST 文件信息字典。

```http
GET http://localhost:27000/Api/PvfUtiltiy/getLstFileInfo?filePath=equipment/equipment.lst
```

版本要求：2022.11.6.1+

### GET /getStringTable

获取 `stringtable.bin` 明文字符串表数据。

```http
GET http://localhost:27000/Api/PvfUtiltiy/getStringTable
```

版本要求：2022.11.11.1+

## 8. UI 状态、选择与定位

### GET /GetTreeListFocusedFilePath

获取文件资源管理器当前焦点文件路径。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetTreeListFocusedFilePath
```

### GET /GetSearchPanelTreeListFocusedFilePath

获取查找面板资源树当前焦点文件路径。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetSearchPanelTreeListFocusedFilePath
```

### GET /GetActiveDocumentFilePath

获取当前正在编辑的文档文件路径。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetActiveDocumentFilePath
```

### GET /GetTreeSelectedFiles

获取文件资源管理器当前选中文件集合。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetTreeSelectedFiles
```

### GET /GetSearchPanelSelectedFiles

获取查找面板资源树当前选中文件集合。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetSearchPanelSelectedFiles
```

### GET /goToTreeListNode

跳转到文件资源管理器节点，可选择打开编辑器文档。

```http
GET http://localhost:27000/Api/PvfUtility/goToTreeListNode?filePath=equipment/equipment.lst&openTextDocument=1
```

参数：

- `filePath`：PVF 内文件路径。
- `openTextDocument`：`1` 表示打开编辑器；`0` 表示只定位。

版本要求：2022.11.11.1+

## 9. 文件状态、封包与搜索

### GET /FileIsExists

判断文件是否存在。

```http
GET http://localhost:27000/Api/PvfUtiltiy/FileIsExists?filePath=equipment/example.equ
```

### GET /folderExists

判断文件夹或文件是否存在。

```http
GET http://localhost:27000/Api/PvfUtility/folderExists?filePath=equipment
```

版本要求：2022.11.11.1+

### POST /FileListToLstRows

将文件路径集合转换为 LST 行字典；未在 LST 注册的文件不会返回。

```http
POST http://localhost:27000/Api/PvfUtiltiy/FileListToLstRows
Content-Type: application/json

[
  "equipment/character/common/amulet/100300001.equ"
]
```

### GET /SaveAsPvfFile

将当前 PVF 另存为新的封包文件。

```http
GET http://localhost:27000/Api/PvfUtiltiy/SaveAsPvfFile?filePath=J%3A%5Cscript.pvf
```

中文路径或 Windows 完整路径请 URL 编码。

### GET /GetPvfPackFilePath

获取当前载入的封包文件路径。

```http
GET http://localhost:27000/Api/PvfUtiltiy/GetPvfPackFilePath
```

### POST /SearchPvf

搜索 PVF。

```http
POST http://localhost:27000/Api/PvfUtiltiy/SearchPvf
```

请求参数以当前软件搜索面板支持字段为准。

## 10. 图标与资源预览

### GET /getFileIcon

获取文件图标 Base64。

```http
GET http://localhost:27000/Api/PvfUtiltiy/getFileIcon?filePath=equipment/character/swordman/weapon/ssword/n_sswd_eleno.equ
```

版本要求：2022.9.30.2+

注意：不要频繁访问该接口，原始 README 提示 pvfUtility 限制约 0.5 秒只能访问一次。

### POST /filesToIconBase64

批量通过文件路径获取图标 Base64。

```http
POST http://localhost:27000/Api/PvfUtiltiy/filesToIconBase64
Content-Type: application/json

[
  "equipment/character/common/amulet/100300001.equ",
  "equipment/character/common/amulet/100300002.equ"
]
```

版本要求：2023.3.9.1+

## 11. 编码参数

`encodingType` 仅适用于文本文件，例如 `nut`、`str`、`txt` 等。

- `TW`：中国台湾文本。
- `CN`：中国大陆文本。
- `KR`：韩国文本。
- `JP`：日本文本。
- `UTF8`：UTF-8。
- `Unicode`：Unicode。
- `null`：由软件默认处理。

## 12. 推荐调用策略

1. 先调用 `/getVersion` 判断用户版本是否支持目标接口。
2. 大量读取文件时使用 `/GetFileContents`。
3. 大量读取图标时使用 `/filesToIconBase64`，不要循环高频调用 `/getFileIcon`。
4. 写入、删除、另存封包前先备份 PVF。
5. 所有路径参数建议 URL 编码，尤其是中文路径、Windows 路径、带 `/` 的 `lstNames`。