Qoder自定义插件开发入门教程实战指南

当Qoder内置功能无法满足特定业务场景时，自定义插件便成为扩展能力的关键途径。无论是集成内部系统，还是对识别结果进行二次处理，均可通过标准化的开发流程实现。本文将手把手带您完成Qoder扩展开发的完整实战路径。

一、理解Qoder插件架构与执行时机

在开始开发前，需深入理解插件系统的运行机制。Qoder采用“后处理钩子”架构，即核心引擎（如OCR识别、代码分析模块）首先完成原始任务并生成输出，随后触发插件系统，允许开发者对结果进行再加工。

开发前需明确以下关键点：

第一，确认开发环境。 并非所有Qoder版本均支持自定义插件。IDEA插件版暂未开放此功能。目前仅Qoder桌面版与CLI（命令行）环境支持插件开发。

第二，找准介入时机。 插件仅在主任务完成后被调用，例如文本识别或代码分析结束之后。插件无法干预核心模型内部的推理过程，这确保了系统核心的稳定性。

第三，遵守输入约定。 插件的核心方法 receive 将接收一个 List[str] 类型参数。该列表包含初步结构化的原始结果，例如OCR识别出的文本段落或解析后的代码块。

二、创建标准插件目录结构

Qoder通过固定的目录结构识别插件。遵循规范是插件生效的前提。

创建过程可分为四个步骤：

1. 新建插件文件夹。 在Qoder工作区根目录下创建新文件夹。建议采用功能描述性名称，并使用小写字母与短横线组合的命名格式（kebab-case），例如 invoice-field-extractor。

2. 创建核心声明文件。 进入新建的文件夹，创建名为 SKILL.md 的文件。此文件是插件的身份标识与功能说明书，不可或缺。

3. 组织脚本和资源。 根据功能需求，可在插件文件夹下建立子目录。主要Python处理脚本应置于 scripts/ 目录下（如 extract_invoice.py）。如需调用Shell脚本或其他工具，亦可放置于此。此外，若插件需参考外部文档或API说明，可建立 references/ 目录进行存放。

4. 确保结构清晰。 一个规范的功能插件目录应呈现清晰的层次结构。

三、编写SKILL.md声明文件

SKILL.md 是插件配置的核心。Qoder启动时将读取此文件，以获取插件名称、功能描述及启动方式。

编写时需注意以下细节：

首先，文件首行不能为空。 通常以FrontMatter区块开头，该区块由三条短横线包裹，采用YAML格式定义元数据。

```yaml name: 发票字段提取器 description: 从OCR识别文本中自动抽取发票号码、开票日期、金额等关键结构化字段 ```

其次，在FrontMatter后空一行，开始编写用法说明。 此部分使用标准Markdown语法，清晰描述插件处理的输入类型及预期输出。提供示例有助于用户快速理解。

最后，在文件末尾指定执行脚本路径。 这是最关键的一行，用于告知Qoder核心逻辑的位置。例如：script: scripts/extract_invoice.py。该路径相对于插件根目录。

四、实现核心处理逻辑（Python示例）

完成声明文件配置后，即可编写核心处理逻辑。以下以发票OCR文本字段提取插件为例进行说明。

1. 创建脚本文件。 在预先规划的 scripts/ 目录下，新建Python文件，如 extract_invoice.py。

2. 编写receive函数。 此函数具有固定签名，接收字符串列表 texts 参数，并返回字典（dict）或None。返回的字典内容将被Qoder收集并展示给用户，或传递给后续插件。

```python def receive(texts): import re result = {} # 将列表中的文本合并为完整字符串进行处理 full_text = "\n".join(texts) # 示例：使用正则表达式匹配发票号码 invoice_no = re.search(r"发票号码[：:]*([A-Z0-9]+)", full_text) if invoice_no: result["invoice_number"] = invoice_no.group(1).strip() # 可在此继续添加匹配日期、金额等逻辑... # date_match = re.search(...) # amount_match = re.search(...) return result ```

3. 注意脚本的纯洁性。 建议在此Python文件中仅定义 receive 函数，避免在最外层编写立即执行的代码。因为Qoder通过动态导入模块的方式加载插件，顶层执行语句可能导致意外行为。

五、注册并启用插件

插件开发完成后，需进行注册方可生效。该过程支持热加载，无需重启Qoder。

1. 打开终端。 在Qoder中，使用快捷键 Ctrl+` 打开内置终端。

2. 执行注册命令。 确保终端当前目录位于插件文件夹的父目录。随后运行注册命令：
qodercli plugin register ./invoice-field-extractor

3. 确认注册成功。 若一切顺利，终端将显示类似 Registered plugin: invoice-field-extractor (v1.0.0) 的成功信息。

4. 测试插件效果。 现在，您可以实际使用Qoder的OCR识别或代码分析功能。任务完成后，请观察界面右侧边栏。若插件生效，将出现新的输出面板，其中展示的正是插件提取的结构化字段。

至此，您专属的Qoder插件已成功部署并开始运行。整个过程如同搭建积木，只要理解架构并遵循规范，功能扩展将变得直观而高效。