From 24d7c64e17acca9f5ee5958a57dc5917a85fc9f2 Mon Sep 17 00:00:00 2001 From: sans Date: Thu, 3 Sep 2026 15:40:43 +0800 Subject: [PATCH] docs: fix relative paths in plugin standard docs after dev/ restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dev/docs 插件标准文档中的相对路径适配到 dev/ 层级 - gitignore dev/docs/HD2/ 图标转换脚本与生成产物（cairosvg 输出等） Co-Authored-By: Claude Code --- .gitignore | 3 +++ dev/docs/plugin-audit-report.md | 6 +++--- dev/docs/plugin-config-standard.md | 14 +++++++------- dev/docs/plugin-structure-standard.md | 6 +++--- 4 files changed, 16 insertions(+), 13 deletions(-) diff --git a/.gitignore b/.gitignore index 0e3fa2f..3effee7 100644 --- a/.gitignore +++ b/.gitignore @@ -79,3 +79,6 @@ bg.jpg /.claude/ /hexi/config/ /CLAUDE.md + +# helldivers 图标素材&生成脚本(不入库) +/dev/docs/HD2/ diff --git a/dev/docs/plugin-audit-report.md b/dev/docs/plugin-audit-report.md index 29f56b6..d7653e2 100644 --- a/dev/docs/plugin-audit-report.md +++ b/dev/docs/plugin-audit-report.md @@ -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()`/插件路径,不硬编码。 diff --git a/dev/docs/plugin-config-standard.md b/dev/docs/plugin-config-standard.md index 0921182..3448c5e 100644 --- a/dev/docs/plugin-config-standard.md +++ b/dev/docs/plugin-config-standard.md @@ -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//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` | 自定义 | 自定义回写 | 自定义 | diff --git a/dev/docs/plugin-structure-standard.md b/dev/docs/plugin-structure-standard.md index 5b4c2fb..0c7ce3b 100644 --- a/dev/docs/plugin-structure-standard.md +++ b/dev/docs/plugin-structure-standard.md @@ -13,7 +13,7 @@ ## 1. 包命名与位置 -- 位置：`hexi/plugins/nonebot_plugin_/`（`bot.py` 用 `nonebot.load_plugins("hexi")` 加载）。 +- 位置：`hexi/plugins/nonebot_plugin_/`（`../../bot.py` 用 `nonebot.load_plugins("hexi")` 加载）。 - 包名 = NoneBot 模块名 = `hexi.plugins.nonebot_plugin_`。 - **`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/`。