68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# AGENTS.md
|
||
|
||
本文档面向 AI 编程助手，介绍本项目的结构、技术栈与开发约定。
|
||
|
||
## 项目概述
|
||
|
||
本项目是一个 [AstrBot](https://github.com/AstrBotDevs/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，而不是随意写入当前工作目录。
|