From a1c9f9bccb1abccdb0359b20a0ad96a64522dc0b Mon Sep 17 00:00:00 2001
From: passthem <Passthem183@gmail.com>
Date: Sat, 7 Mar 2026 12:06:37 +0800
Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E7=BB=99=20AI=20=E9=98=85?=
 =?UTF-8?q?=E8=AF=BB=E7=9A=84=20AGENTS.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md        | 188 +++++++++++++++++++++++++++++++++++++++++++++++
 QWEN.md          | 187 ----------------------------------------------
 docs/artifact.md |  26 +++++++
 3 files changed, 214 insertions(+), 187 deletions(-)
 create mode 100644 AGENTS.md
 delete mode 100644 QWEN.md
 create mode 100644 docs/artifact.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..90bcda9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,188 @@
+# AGENTS.md
+
+本文件面向两类协作者：
+
+- 手写代码的人类朋友
+- 会在此仓库中协助开发的 AI Agents
+
+这个项目以手写为主，欢迎协作，但请先理解这里的约束和结构，再开始改动。
+
+## 项目定位
+
+- 这是一个娱乐性质的、私域使用的 QQ Bot 项目。
+- 虽然主要用于熟人环境，但依然要按“不信任输入”的标准写代码。
+- 不要因为使用场景偏内部，就默认消息内容、安全边界、调用参数一定可靠。
+
+## 基本原则
+
+### 1. 默认不信任用户输入
+
+所有来自聊天消息、命令参数、平台事件等的输入，都应视为不可信。
+
+开发时至少注意以下几点：
+
+- 不假设输入类型正确，先校验再使用。
+- 不假设输入长度合理，注意超长文本、大量参数、异常嵌套结构。
+- 不假设输入内容安全，避免直接拼接到文件路径、SQL、shell 参数、HTML 或模板中。
+- 不假设用户一定按预期使用命令，错误输入要能优雅失败。
+- 对任何外部请求、文件读写、渲染、执行型逻辑，都要先考虑滥用风险。
+
+### 2. 优先保持现有风格
+
+- 这是一个以人工维护为主的项目，改动应尽量贴近现有写法。
+- 除非有明确收益，不要为了“看起来更现代”而大规模重构。
+- 新增能力时，优先复用已有通用模块，而不是重复造轮子。
+
+### 3. 小步修改，影响清晰
+
+- 尽量做局部、明确、可解释的改动。
+- 修改插件时，避免顺手改动无关插件。
+- 如果要调整公共模块，先确认是否会影响大量插件行为。
+
+## 仓库结构
+
+### `konabot/`
+
+核心代码目录。
+
+#### `konabot/common/`
+
+通用模块目录。
+
+- 放置可复用的基础能力、工具模块、公共逻辑。
+- 如果某段逻辑可能被多个插件共享，应优先考虑放到这里。
+- 修改这里的代码时，要额外关注兼容性，因为它可能被很多插件依赖。
+
+#### `konabot/docs/`
+
+Bot 内部文档系统使用的文档目录。
+
+- 这是给用户看的文档来源。
+- 文档会通过 `man` 指令被触发和展示。
+- 虽然文档文件通常使用 `.txt` 后缀，但内容可以按 markdown 风格书写。
+- `.md` 后缀文件会被忽略，因此 `.md` 更适合只留给仓库维护者阅读的附加说明。
+- 文档文件名就是用户查询时使用的指令名，应保持简洁、稳定、易理解。
+
+补充说明：
+
+- `konabot/docs/user/` 是直接面向用户检索的文档。
+- `konabot/docs/lib/` 更偏向维护者参考。
+- `konabot/docs/concepts/` 用于记录概念。
+- `konabot/docs/sys/` 用于特定范围可见的系统文档。
+
+#### `konabot/plugins/`
+
+插件目录。
+
+- 插件数量很多，是本项目最主要的功能承载位置。
+- 插件可以是单文件，也可以是文件夹形式。
+- 新增插件或修改插件时，请先观察相邻插件的组织方式，再决定采用单文件还是目录结构。
+- 如果逻辑已经明显超出单文件可维护范围，应拆成目录插件，不要把一个文件堆得过大。
+
+## 根目录文档
+
+### `docs/`
+
+仓库根目录下的 `docs/` 主要用于记录一些可以通用的模块说明和开发文档。
+
+- 这里的内容主要面向开发和维护。
+- 适合放公共模块说明、集成说明、配置说明、开发笔记。
+- 不要把面向 `man` 指令直接展示给用户的文档放到这里；那类内容应放在 `konabot/docs/` 下。
+
+## 对 AI Agents 的具体要求
+
+如果你是 AI Agent，请遵守以下约定：
+
+### 修改前
+
+- 先阅读将要修改的文件以及相关上下文，不要只凭文件名猜用途。
+- 先判断目标逻辑属于公共模块、用户文档，还是某个具体插件。
+- 如果需求可以在局部完成，就不要扩大改动范围。
+
+### 修改时
+
+- 优先延续现有命名、目录结构和编码风格。
+- 不要因为“顺手”而批量格式化整个项目。
+- 不要擅自重命名大量文件、移动目录、替换现有架构。
+- 涉及用户输入、路径、网络、数据库、渲染时，主动补上必要的校验与防御。
+- 如果要新增 `konabot/common/` 或其他会被多处依赖的模块，优先考虑 NoneBot2 框架下的依赖注入方式，而不是把全局状态或硬编码依赖散落到调用方。
+- 写文档时，区分清楚是给 `man` 系统看的，还是给仓库维护者看的。
+
+### 修改后
+
+- 检查改动是否误伤其他插件或公共模块。
+- 如果新增了用户可见功能，考虑是否需要补充 `konabot/docs/` 下对应文档。
+- 如果新增或调整了通用能力，考虑是否需要补充根目录 `docs/` 下的说明。
+
+## 插件开发建议
+
+- 单个插件内部优先保持自洽，不要把特定业务逻辑过早抽成公共模块。
+- 当多个插件开始重复同类逻辑时，再考虑上移到 `konabot/common/`。
+- 插件应尽量对异常输入有稳定反馈，而不是直接抛出难理解的错误。
+- 如果插件会访问外部服务，要考虑超时、失败降级和返回内容校验。
+
+### 最基本的用户交互书写建议
+
+- 先用清晰、可收敛的规则匹配消息，再进入处理逻辑，不要一上来就在 handler 里兜底解析所有输入。
+- 在 handler 里尽早提取纯文本、拆分命令和参数，并对缺失参数、非法参数、异常格式给出稳定反馈。
+- 如果用户输入只允许有限枚举值，先定义允许集合，再进行归一化和校验。
+- 输出优先保持简单直接；能一句话说明问题时，不要返回难懂的异常堆栈或过度技术化提示。
+- 涉及渲染、网络请求、图片生成等较重操作时，先确认输入合理，再执行昂贵逻辑。
+- 如果插件只是做单一交互，优先保持 handler 简短，把渲染、请求、转换等逻辑拆成独立函数。
+- 倾向于使用 `UniMessage` / `UniMsg` 这一套消息抽象来组织收发消息，而不是把平台细节和文本拼接散落在各处。
+- 倾向于显式构造返回消息并发送，而不是大量依赖 NoneBot2 原生的 `.finish()` 作为主要输出路径，除非该场景确实更简单清晰。
+
+### 关于公共能力的依赖方式
+
+- 新建通用能力时，优先设计成可注入、可替换、可测试的接口。
+- 如果一个模块未来可能被多个插件依赖，优先考虑 NoneBot2 的依赖注入，而不是让调用方手动维护重复的初始化流程。
+- 除非确有必要，不要让插件直接依赖隐藏的全局副作用。
+- 如果使用单例、缓存或全局管理器，要明确其生命周期、并发行为以及关闭时机。
+
+## 运行环境与部署限制
+
+这个项目默认会跑在 Docker 环境里，修改功能时请先意识到运行环境不是一台“什么都有”的开发机。
+
+### 容器环境
+
+- 运行时基础镜像是 `python:3.13-slim`，不是完整桌面 Linux；很多系统库默认不存在。
+- 项目运行依赖 Playwright Chromium、字体库、图形相关库，以及部分额外二进制工具。
+- 构建阶段和运行阶段是分离的；不要假设在 builder 里装过的系统包，runtime 里也一定可用。
+- 额外制品目前通过多阶段构建放进镜像，例如 `typst`。
+
+### Docker 相关要求
+
+- 如果你新增的 Python 依赖背后还需要 Linux 动态库、字体、图形库、编译工具或其他系统包，必须同步检查并在 `Dockerfile` 中补齐。
+- 不要只让本地虚拟环境能跑；要默认以容器可运行作为完成标准之一。
+- 如果新功能依赖系统命令、共享库、浏览器能力或字体，请在提交说明里明确写出原因。
+- `.dockerignore` 当前会排除 `/.env`、`/.git`、`/data` 等内容；不要依赖这些文件被复制进镜像。
+- 关于额外制品的管理，优先先阅读根目录文档 `docs/artifact.md`；适合统一管理的二进制或外部资源，倾向于复用 `konabot/common/artifact.py`，而不是在各插件里各自处理下载和校验。
+
+### 本地运行
+
+- 本地开发可参考 `justfile`，当前主要入口是 `just watch`。
+- 如果你的改动影响启动方式、依赖准备方式或运行命令，记得同步更新对应文档或脚本。
+
+## 分支与协作流程
+
+- 本项目托管在个人 Gitea 实例：`https://gitea.service.jazzwhom.top/mttu-developers/konabot`。
+- 如果需要创建 Pull Request，优先倾向使用 `tea` CLI：`https://gitea.com/gitea/tea`。
+- Pull Request 创建后，当前主要会有自动机器人做初步评审，项目维护者会手动查看；不要催促立即合并，也不要默认会马上进主分支。
+- 如果当前是在仓库本体上直接开发、而不是在 fork 上工作，尽量提醒用户不要直接在主分支持续改动，优先使用功能分支。
+- 除非用户明确要求，否则不要擅自把改动直接合并到主分支。
+
+## 文档编写建议
+
+### 面向 `man` 的文档
+
+- 放在 `konabot/docs/` 对应子目录。
+- 文件名直接对应用户查询名称。
+- 建议内容简洁，优先说明“做什么、怎么用、示例、注意事项”。
+- 使用 `.txt` 后缀；内容可以写成接近 markdown 的可读格式。
+
+### 面向开发者的文档
+
+- 放在仓库根目录 `docs/`。
+- 主要描述公共模块、配置方法、设计说明、维护经验。
+- 可以使用 `.md`。
+
diff --git a/QWEN.md b/QWEN.md
deleted file mode 100644
index 5def88b..0000000
--- a/QWEN.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Konabot Project Context
-
-## Project Overview
-
-Konabot is a multi-platform chatbot built using the NoneBot2 framework, primarily used within MTTU (likely an organization or community). The bot supports multiple adapters including Discord, QQ (via Onebot), Minecraft, and Console interfaces.
-
-### Key Features
-- Multi-platform support (Discord, QQ, Minecraft, Console)
-- Rich plugin ecosystem with over 20 built-in plugins
-- Asynchronous database system with connection pooling (SQLite-based)
-- Advanced image processing capabilities
-- Integration with external services like Bilibili analysis
-- Support for Large Language Models (LLM)
-- Web rendering capabilities for advanced image generation
-
-## Technology Stack
-
-- **Framework**: NoneBot2
-- **Language**: Python 3.12+
-- **Dependency Management**: Poetry
-- **Database**: SQLite with aiosqlite for async operations
-- **Build System**: Just (task runner)
-- **Containerization**: Docker
-- **CI/CD**: Drone CI
-- **Testing**: Pytest
-
-## Project Structure
-
-```
-konabot/
-├── bot.py                  # Main entry point
-├── pyproject.toml          # Project dependencies and metadata
-├── justfile                # Task definitions
-├── Dockerfile              # Container build definition
-├── .drone.yml             # CI/CD pipeline configuration
-├── konabot/               # Main source code
-│   ├── common/            # Shared utilities and modules
-│   │   ├── database/      # Async database manager with connection pooling
-│   │   ├── llm/           # Large Language Model integration
-│   │   ├── web_render/    # Web-based image rendering
-│   │   └── ...            # Other utilities
-│   ├── plugins/           # Plugin modules (core functionality)
-│   │   ├── air_conditioner/
-│   │   ├── bilibili_fetch/
-│   │   ├── gen_qrcode/
-│   │   ├── hanzi/
-│   │   ├── idiomgame/
-│   │   ├── image_process/
-│   │   ├── roll_dice/
-│   │   ├── weather/
-│   │   └── ... (20+ plugins)
-│   └── test/
-├── tests/                 # Test suite
-├── scripts/               # Utility scripts
-├── docs/                  # Documentation
-├── assets/                # Static assets
-└── data/                  # Runtime data storage
-```
-
-## Development Environment Setup
-
-### Prerequisites
-- Python 3.12+
-- Git
-- Poetry (installed via pipx)
-
-### Installation Steps
-1. Clone the repository:
-   ```bash
-   git clone https://gitea.service.jazzwhom.top/Passthem/konabot.git
-   cd konabot
-   ```
-2. Install dependencies:
-   ```bash
-   poetry install
-   ```
-3. Configure environment:
-   - Copy `.env.example` to `.env`
-   - Modify settings as needed for your platform adapters
-
-### Platform Adapters Configuration
-- **Discord**: Set `ENABLE_DISCORD=true` and configure bot token
-- **QQ (Onebot)**: Set `ENABLE_QQ=true` and configure connection
-- **Console**: Enabled by default, disable with `ENABLE_CONSOLE=false`
-- **Minecraft**: Set `ENABLE_MINECRAFT=true`
-
-## Building and Running
-
-### Development
-- Auto-reload development mode:
-  ```bash
-  poetry run just watch
-  ```
-- Manual start:
-  ```bash
-  poetry run python bot.py
-  ```
-
-### Production
-- Docker container build and run:
-  ```bash
-  docker build -t konabot .
-  docker run konabot
-  ```
-
-## Testing
-
-Run the test suite with:
-```bash
-poetry run pytest
-```
-
-Tests are located in the `tests/` directory and focus primarily on core functionality like the database manager.
-
-## Database System
-
-The project implements a custom asynchronous database manager (`konabot/common/database/__init__.py`) with these features:
-- Connection pooling for performance
-- Parameterized queries for security
-- SQL file execution support
-- Support for both string and Path objects for file paths
-- Automatic resource management
-
-Example usage:
-```python
-from konabot.common.database import DatabaseManager
-
-db = DatabaseManager()
-results = await db.query("SELECT * FROM users WHERE age > ?", (18,))
-await db.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("John", "john@example.com"))
-```
-
-## Plugin Architecture
-
-Plugins are organized in `konabot/plugins/` and follow the NoneBot2 plugin structure. Each plugin typically consists of:
-- `__init__.py`: Main plugin logic using Alconna command parser
-- Supporting modules for specific functionality
-
-Popular plugins include:
-- `roll_dice`: Dice rolling with image generation
-- `weather`: Weather radar image fetching
-- `bilibili_fetch`: Bilibili video analysis
-- `image_process`: Image manipulation tools
-- `markdown`: Markdown rendering
-
-## CI/CD Pipeline
-
-Drone CI is configured with two pipelines:
-1. **Nightly builds**: Triggered on pushes to master branch
-2. **Release builds**: Triggered on git tags
-
-Both pipelines:
-- Build Docker images
-- Test plugin loading
-- Verify Playwright functionality
-- Send notifications via ntfy
-
-## Development Conventions
-
-- Use Poetry for dependency management
-- Follow NoneBot2 plugin development patterns
-- Write async code for database operations
-- Use Alconna for command parsing
-- Organize SQL queries in separate files when complex
-- Write tests for core functionality
-- Document features in the `docs/` directory
-
-## Common Development Tasks
-
-1. **Add a new plugin**:
-   - Create a new directory in `konabot/plugins/`
-   - Implement functionality in `__init__.py`
-   - Use Alconna for command definition
-
-2. **Database operations**:
-   - Use the `DatabaseManager` class
-   - Always parameterize queries
-   - Store complex SQL in separate `.sql` files
-
-3. **Image processing**:
-   - Leverage existing utilities in `image_process` plugin
-   - Use Pillow and Skia-Python for advanced graphics
-
-4. **Testing**:
-   - Add tests to the `tests/` directory
-   - Use pytest with async support
-   - Mock external services when needed
\ No newline at end of file
diff --git a/docs/artifact.md b/docs/artifact.md
new file mode 100644
index 0000000..37c81fe
--- /dev/null
+++ b/docs/artifact.md
@@ -0,0 +1,26 @@
+# artifact 模块说明
+
+`konabot/common/artifact.py` 用于管理项目运行过程中依赖的额外制品，尤其是二进制文件、外部工具和按平台区分的运行时资源。
+
+## 适用场景
+
+- 某个插件或公共模块依赖额外下载的可执行文件或二进制资源。
+- 依赖需要按操作系统或架构区分。
+- 希望在启动时统一检测、按需下载并校验哈希。
+
+如果额外制品适合在镜像构建阶段直接打包进 Docker 镜像，也可以在 `Dockerfile` 中通过多阶段构建处理；但对于需要在运行环境按平台管理、懒下载或统一校验的资源，优先考虑复用 `artifact.py`。
+
+## 推荐做法
+
+- 新增额外制品时，先判断它更适合放进镜像构建阶段，还是更适合交给 `artifact.py` 管理。
+- 如果该资源会被多个插件或环境复用，倾向于统一通过 `ArtifactDepends` 和 `register_artifacts(...)` 管理。
+- 为下载资源提供稳定来源，并填写 `sha256` 校验值，不要只校验“能不能下载下来”。
+- 使用 `required_os` 和 `required_arch` 限制平台，避免无意义下载。
+- 需要代理时，确认其行为与当前 NoneBot2 配置兼容。
+
+## 注意事项
+
+- 不要把是否存在额外制品的判断散落到多个插件里各自实现。
+- 不要跳过哈希校验，除非该资源确实无法提供稳定校验值，并且有明确理由。
+- 如果一个新能力除了额外制品，还依赖 Linux 动态库、字体、浏览器或系统命令，仍然需要同步检查并更新 `Dockerfile`。
+- 如果镜像构建和运行阶段都依赖该制品，要分别确认 builder 和 runtime 的可用性。