PyGai 连接器 API 技术文档

PyGai 连接器 API 旨在作为 AI 生成服务与 Gai 应用之间的桥梁，提供数据交互能力。核心 API 接口包括获取 AI 生成任务 (T1) 和提交 AI 生成结果 (T2)。辅助功能 API 包括重置提示指令状态 (T4) 和获取 JWT (T5)。T3 描述了提交结果后的后处理流程，这与 PyGaiCustomize 机制紧密相关，后者详细说明了系统可扩展的方法。

所有 API 响应均遵循 JSend 标准。为方便拥有编程经验的用户，文档中的 HTTP 相关术语（如 URL、Header、Params、Body、Status 等）保持英文。

核心数据实体概览

深入理解 PyGai 连接器 API，有必要了解其背后的数据模型。以下是主要数据表的简要定义（详细字段请参考 docs\pygai.sql）：

• 网站目录表 (gaiDirectory): 记录每个静态网站的页面存储目录。
• 时间表达式表 (gaiInterval): 存储常用的 Cron 格式时间表达式。
• 配置参数表 (gaiConfig): 记录常用的 AI 模型及参数设置。
• 系统指令表 (gaiInstruction): 存储自定义的系统指令或提示词前缀。
• 主题分类表 (gaiTopic): 用于组织和管理相关联的事项或内容主题。
• 提示指令表 (gaiPrompt): 预设在 PyGai 中使用的提示词。为了便于管理，建议与以下关联数据：intervalId (gaiInterval.id), configId (gaiConfig.id), topicId (gaiTopic.id), instId (gaiInstruction.id), dirId (gaiDirectory.id)。
• 生成内容表 (gaiContent): 记录 AI 生成的回传内容。
• 发布记录表 (gaiPublish): 记录 gaiContent 转换为静态文件的发布历史。

本连接器默认支持建站功能，即通过 AI 生成图文并茂的静态网页内容。

T1-获取 AI 生成任务

此接口用于从 PyGai 连接器获取一个可供 AI 模型生成内容的提示指令及相关配置。

• Method: GET
• Url: {{host}}/aiprompt/output/
• Header:
  • Authorization: Bearer {{token}}
• Query Parameters: (用于筛选提示指令)
  • id: int, optional, 对应 gaiPrompt.id。
  • intervalId: int, optional, 对应 gaiPrompt.intervalId。
  • topicId: int, optional, 对应 gaiPrompt.topicId。
  • dirId: int, optional, 对应 gaiPrompt.dirId。

响应数据 data 字段结构 (AI 生成任务载荷)

Name	Type	Required	Description
id	int	Y	提示指令的唯一 ID (gaiPrompt.id)。
type	string	Y	生成类型：gentxt (生成文本), genimg (生成图像)。
text	string	Y	提示指令文本。
files	list<string>	Y	附加文件 URL 数组，若无则为空数组。
instId	int	N	系统指令 ID (gaiInstruction.id)。
instName	string	N	系统指令名称。
instText	string	N	系统指令文本。
config	dict	N	AI 模型生成参数。

响应示例 (成功获取文本生成任务，无系统指令，无参数设定[无则用应用端参数])

• Status: 200 OK

• Body:

  json { "status": "success", "data": { "id": 1, "type": "gentxt", "text": "命题作文:今朝有酒今朝醉,明日愁来明日忧.体裁不限,请写一篇字数不少于500字的作文.", "files": [] } }

T2-提交 AI 生成结果

此接口用于将 AI 模型生成的图文内容回传至 PyGai 连接器，进行存储和可能的后续处理。

• Method: POST
• Url: {{host}}/aicontent/input/
• Header:
  • Authorization: Bearer {{token}}
  • Content-Type: application/json
• Query Parameters:
  • writetofile: bool, optional. 若设置为 true (非零即真，URL 中非空非 0 即真)，则在将内容记录到 gaiContent 表后，系统将进一步在 gaiPublish 表中记录发布信息并生成静态文件。

请求数据 data 字段结构 (提交内容载荷)

Name	Type	Required	Description
id	string	Y	外部唯一标识符，默认为空字符串。
text	string	Y	AI 生成的文本内容。
files	list<string>	Y	AI 生成的文件的 URL 数组，若无则为空数组。
cronId	string	Y	应用端定时任务 ID。
histId	string	Y	应用端日志 ID。
promptId	string	Y	对应的提示指令 ID (gaiPrompt.id)，与 T1 接口返回的 id 关联。

请求示例

{
    "status": "success",
    "data": {
        "id": "",
        "text": "窗外的雨丝斜斜地飘着，敲打着窗棂，发出淅淅沥沥的声响。我望着窗外，思绪也随着雨丝飘忽不定。......",
        "cronId": "_CRON_每日作文之今朝有酒今朝醉",
        "histId": "L-GTXT-1731317840133187",
        "promptId": "2",
        "files": [
            "http://localhost:8080/genimgs/139473250698292130.png"
        ]
    }
}

响应示例 (成功提交，无内容需客户端处理)

• Status: 200 OK

• Body:

  json { "status": "success", "data": { } }

T3-内容后处理与 PyGai 扩展机制

在成功提交 AI 生成结果后，系统将触发内容后处理逻辑。PyGai 提供了一个灵活的扩展机制 (PyGaiCustomize)，允许开发者通过自定义逻辑覆盖或增强系统默认功能，实现代码的干净分离和功能扩展。

内容后处理流程示例

以下代码片段展示了系统默认的内容发布（publish）流程：

# ~/Projects/pygai/gai/content.py

from gai.publish import publish

contentId: int = 1 # Example content ID
publishId = publish(contentId) # Calls the publish function to trigger post-processing

PyGai 扩展机制 (PyGaiCustomize)

PyGai 扩展机制通过查找特定路径下的同名函数来实现。例如，当系统调用 gai.publish.publish 方法时，它会首先尝试加载扩展路径 (~/Projects/pygaiext/) 中对应的 gai/publish.py 文件内的 publishHandler 方法。如果找到并启用，则会执行扩展逻辑而非系统默认逻辑。

项目结构示例:

• 应用路径: ~/Projects/pygai/
• 扩展路径: ~/Projects/pygaiext/

系统默认逻辑 (~/Projects/pygai/gai/publish.py):

# ~/Projects/pygai/gai/publish.py

# Imports the extension method utility
from pygai.ext import extMethod

def publish(contentId: int, reWrite: bool = False) -> None | int:
    """
    Main publish function that can be extended.
    It checks for a custom handler in the extension path.
    """
    extPublishHandler = extMethod('gai/publish', 'publishHandler')
    # If a custom handler exists in the extension path, use it; otherwise, use the default publishHandler.
    return extPublishHandler(contentId, reWrite) if extPublishHandler else publishHandler(contentId, reWrite)

def publishHandler(contentId: int, reWrite: bool = False) -> None | int:
    """
    Default content publish logic.
    This function handles the default actions like recording to gaiPublish and generating static files.
    """
    # Default implementation, e.g., generating static files based on contentId
    pass

自定义扩展逻辑 (~/Projects/pygaiext/gai/publish.py):

通过在扩展路径下创建同名文件和函数，可以覆盖默认行为：

# ~/Projects/pygaiext/gai/publish.py

def publishHandler(contentId: int, reWrite: bool = False) -> None | int:
    """
    Custom content publish logic.
    This function will be executed instead of the default one if the extension is enabled.
    """
    # print(f'pygaiext/gai/publish.py, publishHandler, contendId:{contentId}, reWrite:{reWrite}')
    # Add your custom publishing logic here, e.g., integrating with a CMS,
    # triggering webhooks, or advanced static site generation.
    pass

系统可扩展方法列表

以下是 PyGai 中可供扩展的关键方法：

• promptHandler: 位于 pygai\gai\prompt.py。
• resetHandler: 位于 pygai\gai\prompt.py。
• contentHandler: 位于 pygai\gai\content.py。
• publishHandler: 位于 pygai\gai\publish.py。

扩展应用场景简述

通过 PyGai 提供的扩展功能，开发者可以根据具体业务需求，轻松实现各种定制化集成和功能增强。例如：

• 内容管理系统 (CMS) 集成: 在 publishHandler 中添加逻辑，将 AI 生成的静态网页内容自动同步到现有的 CMS 平台。
• 社交互动功能: 通过扩展功能，可以实现为商品或文章添加评论，或为评论添加回复等功能。
• 多语言支持: 扩展 promptHandler 或 contentHandler，在获取或提交内容时增加语言检测和翻译处理逻辑。
• 第三方服务集成: 在内容生成或发布后，触发 Webhook 通知其他系统（如邮件营销、消息推送服务）。
• 高级数据分析: 在 contentHandler 中嵌入数据分析代码，对生成的内容进行实时监测和统计。

---

T4-重置提示指令状态

此接口用于重置已使用提示指令的状态，使其重新变为可用。当一个提示指令被用于生成内容并成功回传后，其可用数量通常会减少（若为 0 则禁用），并记录回传数据编号和时间。此 API 将清除这些标记，并恢复其可用状态，以便定时任务可以再次轮询并使用该提示指令。

• Method: GET
• Url: {{host}}/aiprompt/reset/
• Header:
  • Authorization: Bearer {{token}}

响应示例 (成功重置)

• Status: 200 OK

• Body:

  json { "status": "success", "data": { } }

---

T5-获取 JSON Web Token (JWT)

此接口用于用户身份认证，成功后将返回一个 JWT，此 Token 可用于访问所有受保护的 PyGai API 接口。

• Method: POST
• Url: {{host}}/signin
• Header:
  • Content-Type: application/x-www-form-urlencoded
• Request Body (Form Data):
  • username: {{email}} (用户邮箱)
  • password: {{passwd}} (用户密码)

响应示例 (成功获取 JWT)

• Status: 200 OK

• Body:

  json { "status": "success", "data": { "jwt": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..." } }