docs: fix relative paths in plugin standard docs after dev/ restructure
- dev/docs 插件标准文档中的相对路径适配到 dev/ 层级 - gitignore dev/docs/HD2/ 图标转换脚本与生成产物（cairosvg 输出等） Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Claude Code
@@ -79,3 +79,6 @@ bg.jpg
|
||||
/.claude/
|
||||
/hexi/config/
|
||||
/CLAUDE.md
|
||||
|
||||
# helldivers 图标素材&生成脚本(不入库)
|
||||
/dev/docs/HD2/
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# HeXi 插件规范化审计报告
|
||||
|
||||
> 依据 《插件结构标准》(docs/plugin-structure-standard.md) 与 《插件配置文件标准》(docs/plugin-config-standard.md)，
|
||||
> 并参照脚手架模板 `plugin_template/nonebot_plugin_template/`。
|
||||
> 并参照脚手架模板 `../plugin_template/nonebot_plugin_template`。
|
||||
> 说明:初版为**审计报告**;后续按用户确认已开始落地改造(见下方「本轮已落地改动」)。
|
||||
|
||||
---
|
||||
|
||||
## 0. 结论摘要
|
||||
|
||||
- 共 **24 个插件** 位于 `hexi/plugins/`,均由 `nonebot.load_plugins("hexi")` 加载,属于本地插件。
|
||||
- 共 **24 个插件** 位于 `../../hexi/plugins`,均由 `nonebot.load_plugins("hexi")` 加载,属于本地插件。
|
||||
- 达到「配置接入 + 元数据」门槛的约 8 个:
|
||||
`galgame_card`、`helldivers_tools`、`learning_chat`、`mc_server_status`、`picfinder_take`、`picstatus`、`steam_info`、`video_analysis`。
|
||||
其中 `galgame_card` 还具备 repository/models/web,最接近标准。
|
||||
@@ -137,7 +137,7 @@ nonebot_plugin_xxx/
|
||||
### 1.2 配置标准
|
||||
- `plugin_id` 必须 = NoneBot 插件模块名(`__name__`)。
|
||||
- 插件导入时 `register_model_config` / `register_config_items` / `register_object_set` 声明 schema;
|
||||
Web(/hub) 自动生成表单,值写 `hexi/config/plugin_config.json`。
|
||||
Web(/hub) 自动生成表单,值写 `../../hexi/config/plugin_config.json`。
|
||||
- 运行期读生效值 `get_effective_value(plugin_id, key, default)`,保证 Web 修改热生效。
|
||||
- 敏感字段 `secret=True`;来源无关项自带 getter/setter;权威源在插件自身用 `nosave=True`。
|
||||
- 禁止 `import *`、裸 `except`、`print()`(用 logger);数据路径用 `get_data_dir()`/插件路径,不硬编码。
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
## 0. 目标与一句话总结
|
||||
|
||||
- **核心原则**：插件只声明 `schema`，Web 自动生成表单；值统一写入值库；插件通过统一 API 读取生效值。
|
||||
- **一句话**：插件在导入时调用 `register_plugin_config(plugin_id, schema, apply, getter)` 声明配置；值写入 `hexi/config/plugin_config.json`；Web 端读 `{schema, values}` 渲染、保存后写回并热应用。
|
||||
- **一句话**：插件在导入时调用 `register_plugin_config(plugin_id, schema, apply, getter)` 声明配置；值写入 `../../hexi/config/plugin_config.json`；Web 端读 `{schema, values}` 渲染、保存后写回并热应用。
|
||||
|
||||
- **`plugin_id` 约定**：必须等于 NoneBot 插件模块名（如 `hexi.plugins.nonebot_plugin_helldivers_tools`）。Web 的 `/api/plugins/<id>/config` 才能命中，插件目录合表也用该 id。
|
||||
|
||||
@@ -103,7 +103,7 @@ hexi/
|
||||
**约定**
|
||||
- `key` 一律 snake_case。
|
||||
- `secret` 字段只返回 `****`，绝不返回明文；提交未修改的 `****` 表示保持原值，只有提交 `null` 才清除。
|
||||
- 复杂类型(`list`/`path`/`object`/`object_set`)在 `.env` 里不易安全表达，**只做运行期热更新**，不落 `.env`；重启需插件自行从值库读取。
|
||||
- 复杂类型(`list`/`path`/`object`/`object_set`)在 `../../.env` 里不易安全表达，**只做运行期热更新**，不落 `../../.env`；重启需插件自行从值库读取。
|
||||
|
||||
---
|
||||
|
||||
@@ -207,7 +207,7 @@ register_plugin_config(
|
||||
|
||||
1. 按 schema 字段的 type/`item_type` 做 **类型校验与转换**(string/int/float/bool/enum/list)。
|
||||
2. **写值库** `plugin_config.json`(原子写)。
|
||||
3. **写 .env**：非 list 字段写入 `os.environ` + `.env`(保证重启仍生效)；list/path/object 跳过，避免 `str(list)` 破坏重启解析。
|
||||
3. **写 .env**：非 list 字段写入 `os.environ` + `../../.env`(保证重启仍生效)；list/path/object 跳过，避免 `str(list)` 破坏重启解析。
|
||||
4. **调 `apply(values)`**：把值热应用到插件运行态对象(list/path/object 也在此生效)。
|
||||
5. 若插件未提供 apply，则 `hot_reload(plugin_id)` 让插件重载。
|
||||
|
||||
@@ -236,7 +236,7 @@ register_plugin_config(
|
||||
}
|
||||
```
|
||||
|
||||
前端 `hexi/web/src/pages/plugins/index.tsx` 已按 `type` 自动渲染：bool→开关、enum→下拉、text→多行、password→掩码、int/float→数字、secret→脱敏。
|
||||
前端 `../../hexi/web/src/pages/plugins/index.tsx` 已按 `type` 自动渲染：bool→开关、enum→下拉、text→多行、password→掩码、int/float→数字、secret→脱敏。
|
||||
|
||||
---
|
||||
|
||||
@@ -302,14 +302,14 @@ register_model_config(
|
||||
|
||||
## 13. 插件内部配置项(来源无关)接入标准
|
||||
|
||||
> **不只是 `.env`**：插件内部自己的配置项(module 常量、YAML/JSON 配置、数据库里的开关等)同样遵循统一 schema，Web 可读可改。核心是让每个配置项自带 **getter/setter**，与来源解耦。
|
||||
> **不只是 `../../.env`**：插件内部自己的配置项(module 常量、YAML/JSON 配置、数据库里的开关等)同样遵循统一 schema，Web 可读可改。核心是让每个配置项自带 **getter/setter**，与来源解耦。
|
||||
|
||||
### 13.1 四种来源与接入方式
|
||||
|
||||
| 配置来源 | 接入方式 | getter/setter | 持久化 | 运行期生效点 |
|
||||
|---|---|---|---|---|
|
||||
| pydantic Config(`.env` 驱动) | `register_model_config` | 自动(读写 Config 对象) | 写值库 + 写 `.env` | apply 热更新对象 |
|
||||
| 模块常量 | `register_config_items(..., store=模块)` | 自动(getattr/setattr) | 写值库(可选写 `.env`) | 需插件用 `get_effective_value` 读取 |
|
||||
| pydantic Config(`../../.env` 驱动) | `register_model_config` | 自动(读写 Config 对象) | 写值库 + 写 `../../.env` | apply 热更新对象 |
|
||||
| 模块常量 | `register_config_items(..., store=模块)` | 自动(getattr/setattr) | 写值库(可选写 `../../.env`) | 需插件用 `get_effective_value` 读取 |
|
||||
| 配置文件(dict/JSON/YAML) | `register_config_items(..., store=dict)` | 自动(读写 dict) | 插件自身写回文件 / 值库 | 插件从 dict 读取时即生效 |
|
||||
| 自定义(DB/运行态) | `register_config_items` 传 `getter`/`setter` | 自定义 | 自定义回写 | 自定义 |
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
|
||||
## 1. 包命名与位置
|
||||
|
||||
- 位置：`hexi/plugins/nonebot_plugin_<name>/`（`bot.py` 用 `nonebot.load_plugins("hexi")` 加载）。
|
||||
- 位置：`hexi/plugins/nonebot_plugin_<name>/`（`../../bot.py` 用 `nonebot.load_plugins("hexi")` 加载）。
|
||||
- 包名 = NoneBot 模块名 = `hexi.plugins.nonebot_plugin_<name>`。
|
||||
- **`plugin_id` 约定**：用于配置 schema / 插件控制 / Web 挂载的值，一律等于模块名（`__name__`）。
|
||||
|
||||
@@ -93,7 +93,7 @@ nonebot_plugin_xxx/
|
||||
|
||||
## 5. config.py 标准
|
||||
|
||||
### 4.1 环境驱动型（读 `.env` / NoneBot config）
|
||||
### 4.1 环境驱动型（读 `../../.env` / NoneBot config）
|
||||
```python
|
||||
from nonebot import get_plugin_config
|
||||
from pydantic import BaseModel
|
||||
@@ -145,7 +145,7 @@ register_object_set(__name__, "groups", [ {item_schema...} ], key_field="group_i
|
||||
|
||||
## 9. 插件迁移检查清单
|
||||
|
||||
- [ ] 包名改为 `nonebot_plugin_*`，位置在 `hexi/plugins/`。
|
||||
- [ ] 包名改为 `nonebot_plugin_*`，位置在 `../../hexi/plugins`。
|
||||
- [ ] 有 `__plugin_meta__`，`type="application"`。
|
||||
- [ ] 配置已接入统一标准（Web 能读能改，运行期/重启生效）。
|
||||
- [ ] 命令在 `handlers/`，业务在 `services/`，工具在 `utils/`。
|
||||
|
||||
Reference in New Issue
Block a user