astrbot_plugin_njupt_suan/AGENTS.md

AGENTS.md

本文档面向 AI 编程助手，介绍本项目的结构、技术栈与开发约定。

项目概述

本项目是一个 AstrBot 插件，目录名为 astrbot_plugin_njupt_suan，但当前代码是基于 AstrBot 官方插件模板的初始状态。插件仅实现了一个简单的 helloworld 指令，用于演示 AstrBot 插件的基本写法。

• 技术栈：Python 3（异步 asyncio）
• 运行方式：不能独立运行，必须由 AstrBot 主程序动态加载
• 项目规模：极简单文件插件，目前仅包含一个入口模块

项目结构

.
├── main.py           # 插件主代码，注册指令与事件处理逻辑
├── metadata.yaml     # AstrBot 插件元数据（名称、版本、作者等）
├── README.md         # 面向用户的项目说明
├── LICENSE           # 许可证文件
├── .gitignore        # Python 通用 gitignore
└── AGENTS.md         # 本文档

注意：项目中不存在 pyproject.toml、setup.py、requirements.txt、package.json 等常规构建配置文件，因为 AstrBot 插件是直接在宿主环境中运行的动态模块。

核心文件说明

main.py

• 定义插件类 MyPlugin，继承自 astrbot.api.star.Star
• 使用 @register(...) 装饰器向 AstrBot 注册插件
• 使用 @filter.command("helloworld") 注册聊天指令 /helloworld
• 实现了可选的生命周期方法 initialize()（初始化）和 terminate()（卸载）

metadata.yaml

• AstrBot 识别插件的核心配置文件
• 关键字段：name（唯一标识名）、version、author、desc、repo
• 当前内容仍为模板默认值（helloworld），后续开发需根据实际功能更新

开发与修改约定

1. 单文件扩展：当前所有逻辑集中在 main.py。若功能变复杂，可在同目录下新增 .py 模块并在 main.py 中导入。
2. 命名规范：
   • 插件唯一名（metadata.yaml 中的 name）建议以 astrbot_plugin_ 开头
   • 类名使用大驼峰（如 MyPlugin）
   • 指令名使用小写英文+下划线
3. 注释语言：代码内注释以中文为主，README 为中英混合。新增注释建议保持中文。
4. 依赖管理：如需引入第三方 Python 包，请在 metadata.yaml 同级目录下创建 requirements.txt，AstrBot 会在安装插件时尝试自动安装。但目前项目中尚未创建该文件。

构建与测试

• 无独立构建步骤：插件无需编译或打包成 wheel。
• 测试方式：需在本地部署 AstrBot 主程序，将本目录放入 AstrBot 的 plugins/ 文件夹（或通过 AstrBot 插件市场/控制台安装），然后启动 AstrBot 进行联调。
• 目前无单元测试：目录内没有 tests/ 文件夹或测试框架配置。

部署流程

1. 修改 metadata.yaml 中的 name、display_name、desc、version、author、repo 为实际信息。
2. 修改 main.py 中的 @register(...) 参数与 metadata.yaml 保持一致。
3. 如需额外依赖，添加 requirements.txt。
4. 将代码推送到远程仓库后，可在 AstrBot 插件市场提交或通过 Git 链接直接安装。

安全提示

• 插件运行在 AstrBot 主程序的 Python 进程中，拥有与宿主相同的权限。
• 避免在插件中执行不可信的外部命令或随意 eval 用户输入。
• 若需存储持久化数据，建议使用 AstrBot 提供的配置/数据目录 API，而不是随意写入当前工作目录。