Skip to content

Commit 57a764b

Browse files
pear-studiopear-studio
committed
docs: 创建 Agent 文档结构 (rules + skills)
1 parent 97d1800 commit 57a764b

File tree

8 files changed

+483
-21
lines changed

8 files changed

+483
-21
lines changed

‎.trae/rules‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/agent/rules

‎.trae/rules/agent.md‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

‎.trae/skills‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/agent/skills

‎docs/agent/link-to-trae.bat‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
@echo off
2+
chcp 65001 >nul
3+
:: 创建符号链接：docs/agent/ -> .trae/
4+
:: 需要管理员权限运行
5+
6+
cd /d %~dp0\..\..
7+
8+
:: 检查源目录是否存在
9+
if not exist "docs\agent\rules" (
10+
echo 错误: 源目录 docs\agent\rules 不存在
11+
pause
12+
exit /b 1
13+
)
14+
if not exist "docs\agent\skills" (
15+
echo 错误: 源目录 docs\agent\skills 不存在
16+
pause
17+
exit /b 1
18+
)
19+
20+
echo 正在创建符号链接...
21+
22+
:: 确保 .trae 目录存在
23+
if not exist ".trae" mkdir ".trae"
24+
25+
:: 删除旧目录/链接
26+
if exist ".trae\rules" (
27+
rmdir /s /q ".trae\rules" 2>nul
28+
del ".trae\rules" 2>nul
29+
echo 已删除 .trae\rules
30+
)
31+
if exist ".trae\skills" (
32+
rmdir /s /q ".trae\skills" 2>nul
33+
del ".trae\skills" 2>nul
34+
echo 已删除 .trae\skills
35+
)
36+
37+
:: 创建符号链接
38+
mklink /D ".trae\rules" "docs\agent\rules"
39+
mklink /D ".trae\skills" "docs\agent\skills"
40+
41+
echo.
42+
echo 符号链接创建完成:
43+
echo .trae\rules -^> docs\agent\rules
44+
echo .trae\skills -^> docs\agent\skills
45+
pause

‎docs/agent/rules/ai-usage.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Agent Rules
2+
3+
## 依赖
4+
- 唯一声明: `pyproject.toml`
5+
- 安装: `uv pip install .` / `".[dev]"`
6+
7+
## 命令
8+
```bash
9+
uv venv .venv && uv pip install ".[dev]" # 初始化
10+
uv run pytest # 测试
11+
uv run pytest tests/module/roll/ -v # 模块测试
12+
uv run python bot.py # 运行
13+
```
14+
15+
## 测试
16+
- 文件: `test_*.py`
17+
- 目录: `tests/`
18+
19+
## 风格
20+
- 最小化变更, 不确定先询问
21+
- 提交前 `uv run pytest`, 不自动push
22+
- git comment主要用中文
23+
- 有大的修改后主动更新`docs/agent/rules/dicepp.md`
24+
25+
## 配置文件
26+
- 依赖: `pyproject.toml`
27+
- 测试: `pyproject.toml` [tool.pytest.ini_options]
28+
- 覆盖率: `.coveragerc`
29+
- 环境变量: `.env`
30+
31+
## 规范文件
32+
- `docs/agent/rules/dicepp.md` - DicePP 开发规范

‎docs/agent/rules/dicepp.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
alwaysApply: false
3+
description: 编写 DicePP 插件代码
4+
---
5+
# DicePP 开发规范
6+
7+
## 技术栈
8+
9+
- Python 3.10+ / NoneBot2 2.4+
10+
- OneBot v11 适配器
11+
- aiohttp / aiofiles (异步IO)
12+
- openpyxl (Excel处理)
13+
- SQLite3 (查询数据库)
14+
15+
## 项目结构
16+
17+
```
18+
src/plugins/DicePP/
19+
├── core/ # 核心框架
20+
│ ├── bot.py # Bot 主类
21+
│ ├── command/ # 命令处理
22+
│ ├── communication/ # 消息通信
23+
│ ├── config/ # 配置管理
24+
│ ├── data/ # 数据持久化
25+
│ └── localization/ # 本地化
26+
├── module/ # 功能模块
27+
│ ├── common/ # 通用命令 (help, master等)
28+
│ ├── roll/ # 掷骰命令
29+
│ ├── query/ # 查询命令
30+
│ ├── deck/ # 抽卡命令
31+
│ ├── character/ # 角色卡
32+
│ ├── initiative/ # 先攻管理
33+
│ └── misc/ # 杂项命令
34+
├── adapter/ # NoneBot 适配器
35+
└── utils/ # 工具函数
36+
```
37+
38+
## 命令结构
39+
40+
```
41+
module/xxx/
42+
├── xxx_command.py # 命令实现
43+
├── xxx_data.py # 数据定义 (可选)
44+
└── __init__.py
45+
```
46+
47+
## 命名规范
48+
49+
- Command 类: PascalCase + Command (`RollDiceCommand`)
50+
- DataChunk 类: PascalCase + DataChunk (`UserDataChunk`)
51+
- 本地化 Key: UPPER_SNAKE_CASE (`LOC_ROLL_RESULT`)
52+
- 配置 Key: UPPER_SNAKE_CASE (`CFG_ROLL_ENABLE`)
53+
54+
## 创建新命令
55+
56+
1. 继承 `UserCommandBase`
57+
2. 使用 `@custom_user_command` 装饰器
58+
3. 实现 `can_process_msg` 和 `process_msg` 方法
59+
60+
```python
61+
from core.command import UserCommandBase, custom_user_command
62+
from core.command.const import *
63+
64+
@custom_user_command(
65+
readable_name="示例命令",
66+
priority=DPP_COMMAND_PRIORITY_DEFAULT,
67+
flag=DPP_COMMAND_FLAG_FUN
68+
)
69+
class ExampleCommand(UserCommandBase):
70+
def __init__(self, bot):
71+
super().__init__(bot)
72+
bot.loc_helper.register_loc_text("loc_key", "默认文本", "注释")
73+
74+
def can_process_msg(self, msg_str, meta):
75+
if msg_str.startswith(".example"):
76+
return True, False, msg_str[8:].strip()
77+
return False, False, None
78+
79+
def process_msg(self, msg_str, meta, hint):
80+
# 处理逻辑
81+
return [BotSendMsgCommand(self.bot.account, "回复", [port])]
82+
83+
def get_help(self, keyword, meta):
84+
return ".example 示例命令"
85+
86+
def get_description(self):
87+
return ".example 示例命令"
88+
```
89+
90+
## 数据访问
91+
92+
```python
93+
# 读取数据
94+
data = self.bot.data_manager.get_data(
95+
DC_USER_DATA, # DataChunk 标识
96+
[user_id, "key"], # 路径
97+
default_val="default" # 默认值
98+
)
99+
100+
# 写入数据
101+
self.bot.data_manager.set_data(
102+
DC_USER_DATA,
103+
[user_id, "key"],
104+
"new_value"
105+
)
106+
```
107+
108+
## 本地化
109+
110+
```python
111+
# 注册
112+
bot.loc_helper.register_loc_text(
113+
"loc_key",
114+
"你好 {name}!",
115+
"用户问候语"
116+
)
117+
118+
# 使用
119+
text = self.format_loc("loc_key", name="用户")
120+
```
121+
122+
## 工具导入
123+
124+
```python
125+
# 推荐: 从 utils 包直接导入
126+
from utils import read_json, update_json, read_xlsx, update_xlsx
127+
128+
# 避免: 从子模块导入
129+
# from utils.localdata import read_json # 不推荐
130+
```
131+
132+
## 安全规范
133+
134+
- 禁止硬编码敏感信息
135+
- 使用 `.env` 管理环境变量
136+
- 数据文件使用 `.gitignore` 忽略
137+
138+
## 测试规范
139+
140+
- 测试文件放在 `tests/` 目录
141+
- 命名: `test_*.py`
142+
- 使用 pytest fixtures: `shared_bot`, `fresh_bot`

‎docs/agent/skills/onboard/SKILL.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: onboard
3+
description: Help new developers understand the DicePP project structure and get started with development.
4+
license: MIT
5+
metadata:
6+
author: DicePP
7+
version: "1.0"
8+
---
9+
10+
Help new developers understand the DicePP project structure and get started with development.
11+
12+
**Input**: None required. This skill provides an overview of the project.
13+
14+
**Steps**
15+
16+
1. **Project Overview**
17+
18+
DicePP 是一个基于 NoneBot2 的 QQ 骰子机器人插件，主要用于 TRPG（桌面角色扮演游戏）场景。
19+
20+
**核心功能**:
21+
- 掷骰系统 (支持多种骰子表达式)
22+
- 查询系统 (DND5E 等规则书资料)
23+
- 角色卡管理 (COC/DND)
24+
- 先攻管理
25+
- 抽卡/随机生成器
26+
- 日志记录
27+
28+
2. **Directory Structure**
29+
30+
```
31+
nonebot-dicepp/
32+
├── src/plugins/DicePP/ # 主插件代码
33+
│ ├── core/ # 核心框架
34+
│ ├── module/ # 功能模块
35+
│ ├── adapter/ # NoneBot 适配器
36+
│ └── utils/ # 工具函数
37+
├── tests/ # 测试文件
38+
├── docs/ # 文档
39+
├── openspec/ # 变更规范
40+
├── bot.py # 入口文件
41+
└── pyproject.toml # 项目配置
42+
```
43+
44+
3. **Core Framework**
45+
46+
| 目录 | 说明 |
47+
|------|------|
48+
| `core/bot.py` | Bot 主类，管理所有命令和数据 |
49+
| `core/command/` | 命令基类和装饰器 |
50+
| `core/data/` | 数据持久化 (DataManager) |
51+
| `core/config/` | 配置管理 (ConfigManager) |
52+
| `core/localization/` | 本地化管理 |
53+
| `core/communication/` | 消息通信抽象 |
54+
55+
4. **Module System**
56+
57+
每个功能模块位于 `module/` 目录下：
58+
59+
| 模块 | 说明 |
60+
|------|------|
61+
| `common/` | 通用命令 (help, master, mode 等) |
62+
| `roll/` | 掷骰命令 (.r, .rd, .rh 等) |
63+
| `query/` | 查询命令 (.查询, .q) |
64+
| `deck/` | 抽卡命令 (.draw) |
65+
| `character/` | 角色卡 (COC/DND5E) |
66+
| `initiative/` | 先攻管理 (.ri, .init) |
67+
68+
5. **How to Add a New Command**
69+
70+
1. 在合适的模块目录下创建 `xxx_command.py`
71+
2. 继承 `UserCommandBase` 类
72+
3. 使用 `@custom_user_command` 装饰器
73+
4. 实现必要的方法:
74+
- `can_process_msg()` - 判断是否处理消息
75+
- `process_msg()` - 处理消息并返回回复
76+
- `get_help()` - 返回帮助文本
77+
- `get_description()` - 返回命令描述
78+
79+
6. **Development Setup**
80+
81+
```powershell
82+
# 克隆项目
83+
git clone <repo>
84+
cd nonebot-dicepp
85+
86+
# 初始化环境并安装依赖
87+
uv venv .venv && uv pip install ".[dev]"
88+
89+
# 配置环境
90+
cp .env.example .env
91+
# 编辑 .env 填入 QQ 账号等信息
92+
93+
# 运行测试
94+
uv run pytest -v
95+
96+
# 启动机器人
97+
uv run python bot.py
98+
```
99+
100+
7. **Key Concepts**
101+
102+
**DataChunk**: 数据持久化单元，用于保存用户数据、配置等
103+
104+
**LocalizationText**: 本地化文本，支持多语言和自定义回复
105+
106+
**MessageMetaData**: 消息元数据，包含发送者、群组等信息
107+
108+
**BotCommandBase**: 机器人执行的命令（发送消息、发送文件等）
109+
110+
8. **Useful Files to Read**
111+
112+
- `src/plugins/DicePP/core/bot.py` - 了解 Bot 生命周期
113+
- `src/plugins/DicePP/core/command/user_command.py` - 命令基类
114+
- `src/plugins/DicePP/module/roll/roll_dice_command.py` - 掷骰命令示例
115+
- `docs/agent/rules/dicepp.md` - 开发规范
116+
117+
**Output**
118+
119+
输出项目概览和入门指南，帮助开发者快速理解项目结构。
120+
121+
**Next Steps**
122+
123+
1. 阅读 `docs/agent/rules/dicepp.md` 了解开发规范

0 commit comments

Comments
 (0)