From 01301b887aa7c2a711d58abc3a8ad11236801f2f Mon Sep 17 00:00:00 2001 From: jxxghp Date: Sun, 11 Oct 2026 13:59:38 +0800 Subject: [PATCH] fix(plugin): accept underscore IDs in instance validation (#6962) --- app/schemas/plugin.py | 9 +++-- docs/architecture-overview.md | 4 +- docs/refactor/optimization-checklist.md | 2 +- .../architecture/dependency-baseline.json | 6 ++- tests/test_plugin_id_validation.py | 37 +++++++++++++++++++ tests/test_plugin_instance_directory.py | 31 ++++++++++++++++ ...st_plugin_instance_purge_path_traversal.py | 12 ++++-- 7 files changed, 90 insertions(+), 11 deletions(-) create mode 100644 tests/test_plugin_id_validation.py diff --git a/app/schemas/plugin.py b/app/schemas/plugin.py index 9f5761ab1..e3fb79b69 100644 --- a/app/schemas/plugin.py +++ b/app/schemas/plugin.py @@ -9,6 +9,7 @@ from pydantic import BeforeValidator as _BeforeValidator from pydantic import PrivateAttr as _PrivateAttr from pydantic import computed_field as _computed_field +from app.domain.plugin import is_physical_plugin_id as _is_physical_plugin_id from app.schemas.common import JsonData @@ -49,14 +50,16 @@ def validate_plugin_id(value: str) -> str: 公开可调用：凡是把实例 ID 拼进文件系统路径、模块名或路由段的入口都应当先过这道 校验，而不是各自另写一套字符白名单——多套规则之间迟早出现缝隙。 + 实例与源插件复用安装侧的 ASCII 身份规则，兼容既有下划线 ID；不改写大小写， + 以免改变配置、数据和路由命名空间。 :param value: 待校验的插件实例 ID :return: 原样返回的合法 ID - :raise ValueError: ID 为空、不以字母开头、含字母数字以外的字符或超长 + :raise ValueError: ID 为空、不以字母开头、含 ASCII 字母数字及下划线以外的字符或超长 """ - if not value or not value[0].isalpha() or not value.isalnum(): - raise ValueError("插件 ID 必须以字母开头且只能包含字母和数字") if len(value) > 128: raise ValueError("插件 ID 长度不能超过 128 个字符") + if not _is_physical_plugin_id(value): + raise ValueError("插件 ID 必须以字母开头且只能包含 ASCII 字母、数字或下划线") return value diff --git a/docs/architecture-overview.md b/docs/architecture-overview.md index 083e77091..f92fa047a 100644 --- a/docs/architecture-overview.md +++ b/docs/architecture-overview.md @@ -763,7 +763,7 @@ flowchart LR | 指标 | 当前值 | |---|---:| | Python 模块 | 1114 | -| 内部导入边 | 9,430 | +| 内部导入边 | 9,432 | | 非平凡 SCC | 1（精确 containment 的 TMDB 移植包环） | | Application / Chain 具体 Adapter 直连 | 0 / 0 | | Direct egress | 49（债务已清零，49 条精确 containment） | @@ -773,7 +773,7 @@ flowchart LR | Model/Oper 自动事务与自建 Session | 0 | | 组合根外 `SystemConfigOper()` | 0 | -整理失败反馈由 `app.application.transfer.feedback` 集中投影；已整理下载的站点字幕复用 `app.chain.transfer` 自动整理队列；网络连通性检测按 `app.application.nettest` 归档，并覆盖 HTTP 与 WebSocket 探测。未启用智能助手的消息音乐交互由 `app.chain.music_interaction` 包中的解析展示与订阅协调模块处理；音乐标签准入与批次共识由 `app.chain.transfer.music` 负责，预览证据由 `app.application.transfer.projection` 只读投影；宿主依赖边现为 9,430；种子下载限流窗口由 `app.domain.torrent` 定义，失败冷却 owner 复用同一语义，新增 1 条合法 Chain 到 Domain 的导入边；工作流添加下载动作由 `app.workflow.actions.add_download` 转换工作流 Schema 为下载链领域上下文，新增 5 条模块导入边；资源过滤动作 `app.workflow.actions.filter_torrents` 与动作包共用的领域还原函数同样把 Schema 资源还原为领域对象后再交给过滤链，新增 6 条模块导入边。音乐来源链与识别缓存复用领域身份核验，音乐交互包未新增 SCC，插件一次性任务 owner `app.scheduler.oncejob` 带来 1 个模块和 9 条依赖边。Agent 持久回执新增 Application 端口及 DB Model/Oper/Adapter 四个冷导入模块。缓存组合根只在启动时选用 Redis 缓存才导入 Redis 适配器，依赖 langchain_core 的对话记忆模型归属 `app.agent.memory`，文件缓存且未启用智能体的实例不再加载 redis 与 langchain_core。Telegram 渠道改用模块内 `app.modules.telegram.botapi` 精简 Bot API 客户端，经 `RequestUtils` 出站，宿主不再导入 pyTelegramBotAPI，启用 Telegram 的实例也不会因该 SDK 加载 redis；该依赖暂时保留给插件使用。Web Push 协议（aes128gcm 加密、VAPID 签名与经 `RequestUtils` 投递）由网络适配器 `app.adapters.network.webpush` 直接基于 http-ece 与 py-vapid 实现，消息端点与 `WebPushModule` 共用，宿主不再导入 pywebpush 及其连带的 aiohttp；该依赖同样暂时保留给插件使用。飞书渠道改用模块内 `app.modules.feishu.openapi` OpenAPI 客户端（经 `RequestUtils` 出站）与网络适配器 `app.adapters.network.feishu` 事件长连接（websocket-client 同步收发 pbbp2 帧），宿主不再导入 lark-oapi 及其上万个生成模块，长连接也不再依赖 SDK 的模块级事件循环；插件经 `app.sdk.feishu` 复用同一长连接，lark-oapi 暂时保留给尚未迁移的插件使用。API 文档路由由 `app.adapters.web.docs` 按 `API_DOCS_ENABLE` 逐请求开放，默认关闭，未开放时不生成文档。当前 `app.startup.lifecycle` 为 582、`app.factory` 为 595、`app.main` 为 597。音乐调用观察 `app.application.music.observation` 新增一个轻量模块，记录来源结果及请求预算；AcoustID及路径识别复用此上下文传递有界指纹候选，保留旧单ID模块合同。站点图片域名快照新增 `app.application.security.image`，各启动入口增加一个模块；性能基线只同步模块数量，原有耗时预算、历史采样和生命周期资源约束保持有效。 +整理失败反馈由 `app.application.transfer.feedback` 集中投影；已整理下载的站点字幕复用 `app.chain.transfer` 自动整理队列；网络连通性检测按 `app.application.nettest` 归档，并覆盖 HTTP 与 WebSocket 探测。未启用智能助手的消息音乐交互由 `app.chain.music_interaction` 包中的解析展示与订阅协调模块处理；音乐标签准入与批次共识由 `app.chain.transfer.music` 负责，预览证据由 `app.application.transfer.projection` 只读投影；宿主依赖边现为 9,432；插件实例校验复用 `app.domain.plugin` 的物理身份规则，兼容下划线 ID，新增 2 条 Schema 到 Domain 的合法依赖边（含父包展开）；种子下载限流窗口由 `app.domain.torrent` 定义，失败冷却 owner 复用同一语义，新增 1 条合法 Chain 到 Domain 的导入边；工作流添加下载动作由 `app.workflow.actions.add_download` 转换工作流 Schema 为下载链领域上下文，新增 5 条模块导入边；资源过滤动作 `app.workflow.actions.filter_torrents` 与动作包共用的领域还原函数同样把 Schema 资源还原为领域对象后再交给过滤链，新增 6 条模块导入边。音乐来源链与识别缓存复用领域身份核验，音乐交互包未新增 SCC，插件一次性任务 owner `app.scheduler.oncejob` 带来 1 个模块和 9 条依赖边。Agent 持久回执新增 Application 端口及 DB Model/Oper/Adapter 四个冷导入模块。缓存组合根只在启动时选用 Redis 缓存才导入 Redis 适配器，依赖 langchain_core 的对话记忆模型归属 `app.agent.memory`，文件缓存且未启用智能体的实例不再加载 redis 与 langchain_core。Telegram 渠道改用模块内 `app.modules.telegram.botapi` 精简 Bot API 客户端，经 `RequestUtils` 出站，宿主不再导入 pyTelegramBotAPI，启用 Telegram 的实例也不会因该 SDK 加载 redis；该依赖暂时保留给插件使用。Web Push 协议（aes128gcm 加密、VAPID 签名与经 `RequestUtils` 投递）由网络适配器 `app.adapters.network.webpush` 直接基于 http-ece 与 py-vapid 实现，消息端点与 `WebPushModule` 共用，宿主不再导入 pywebpush 及其连带的 aiohttp；该依赖同样暂时保留给插件使用。飞书渠道改用模块内 `app.modules.feishu.openapi` OpenAPI 客户端（经 `RequestUtils` 出站）与网络适配器 `app.adapters.network.feishu` 事件长连接（websocket-client 同步收发 pbbp2 帧），宿主不再导入 lark-oapi 及其上万个生成模块，长连接也不再依赖 SDK 的模块级事件循环；插件经 `app.sdk.feishu` 复用同一长连接，lark-oapi 暂时保留给尚未迁移的插件使用。API 文档路由由 `app.adapters.web.docs` 按 `API_DOCS_ENABLE` 逐请求开放，默认关闭，未开放时不生成文档。当前 `app.startup.lifecycle` 为 582、`app.factory` 为 595、`app.main` 为 597。音乐调用观察 `app.application.music.observation` 新增一个轻量模块，记录来源结果及请求预算；AcoustID及路径识别复用此上下文传递有界指纹候选，保留旧单ID模块合同。站点图片域名快照新增 `app.application.security.image`，各启动入口增加一个模块；性能基线只同步模块数量，原有耗时预算、历史采样和生命周期资源约束保持有效。 架构专项验证分为两个 CI 投影：`Check event semantic policy` 先运行依赖、Adapter、出口和 Event 语义门禁，`Check host architecture snapshot` 再执行快照测试及一次 diff --git a/docs/refactor/optimization-checklist.md b/docs/refactor/optimization-checklist.md index fcdc474b1..c87393293 100644 --- a/docs/refactor/optimization-checklist.md +++ b/docs/refactor/optimization-checklist.md @@ -98,7 +98,7 @@ ARCH-201 至 ARCH-204 均达到实现、验证、提交、推送和远端门禁 | 指标 | 当前值 | 解释 | |---|---:|---| -| 宿主 Python 模块 / 内部依赖边 | 1114 / 9,430 | `dependency-baseline.json` 当前快照；种子失败冷却复用 `app.domain.torrent` 的限流语义，新增 1 条合法导入边；系统设置合同按 `app.application.settings` 包组织，系统设置 API 端点独立按 `app.api.endpoints.settings` 归档；消息音乐交互由 `app.chain.music_interaction` 包中的音乐解析/展示与订阅协调模块处理；已整理下载的站点字幕经 `app.chain.transfer` 自动整理队列完成命名与归档；网络连通性检测按 `app.application.nettest` 归档；工作流添加下载动作由 `app.workflow.actions.add_download` 转换工作流 Schema 为下载链领域上下文，新增 5 条合法模块导入边，资源过滤动作复用同一还原再新增 6 条；LLM 独占连接关闭复用宿主线程池；歌词字形转换复用 `app.foundation.text`；订阅创建使用 `app.domain.context.MediaInfo` 和运行时配置端口，将非 TMDB 影视身份投影为 TMDB 身份 | +| 宿主 Python 模块 / 内部依赖边 | 1114 / 9,432 | `dependency-baseline.json` 当前快照；插件实例校验复用 `app.domain.plugin` 的物理身份规则，兼容下划线 ID，新增 2 条合法依赖边（含父包展开）；种子失败冷却复用 `app.domain.torrent` 的限流语义，新增 1 条合法导入边；系统设置合同按 `app.application.settings` 包组织，系统设置 API 端点独立按 `app.api.endpoints.settings` 归档；消息音乐交互由 `app.chain.music_interaction` 包中的音乐解析/展示与订阅协调模块处理；已整理下载的站点字幕经 `app.chain.transfer` 自动整理队列完成命名与归档；网络连通性检测按 `app.application.nettest` 归档；工作流添加下载动作由 `app.workflow.actions.add_download` 转换工作流 Schema 为下载链领域上下文，新增 5 条合法模块导入边，资源过滤动作复用同一还原再新增 6 条；LLM 独占连接关闭复用宿主线程池；歌词字形转换复用 `app.foundation.text`；订阅创建使用 `app.domain.context.MediaInfo` 和运行时配置端口，将非 TMDB 影视身份投影为 TMDB 身份 | | 非平凡 SCC | 1 | 仅保留精确 containment 的 29 模块 TMDB 移植包环 | | 跨层 DB 边界债务 | 0 | Application、Chain、API、Agent、Runtime、Workflow 到 DB 的受控债务均为零 | | Model/Oper 事务债务 | 0 | 自建 Session、自动事务装饰器、直接 commit/rollback 等基线均为零 | diff --git a/tests/fixtures/architecture/dependency-baseline.json b/tests/fixtures/architecture/dependency-baseline.json index 7f3d91477..263bb5da0 100644 --- a/tests/fixtures/architecture/dependency-baseline.json +++ b/tests/fixtures/architecture/dependency-baseline.json @@ -941,8 +941,8 @@ "runtime_only": true } }, - "edge_count": 9430, - "edge_sha256": "e2e7ef5284db0d923080a54cb3ff25d5cca80e571324786576a432e4b6b6bcd4", + "edge_count": 9432, + "edge_sha256": "e4629849e18bc7fcdc153cd39ad4f735b3736d59579f5e0cf8201d08c862ea82", "edges": [ "app -> app.foundation", "app -> app.foundation.environment", @@ -9196,6 +9196,8 @@ "app.schemas.notification -> app.schemas.types", "app.schemas.openai -> app.schemas", "app.schemas.openai -> app.schemas.common", + "app.schemas.plugin -> app.domain", + "app.schemas.plugin -> app.domain.plugin", "app.schemas.plugin -> app.schemas", "app.schemas.plugin -> app.schemas.common", "app.schemas.query -> app.schemas", diff --git a/tests/test_plugin_id_validation.py b/tests/test_plugin_id_validation.py new file mode 100644 index 000000000..9738d9c44 --- /dev/null +++ b/tests/test_plugin_id_validation.py @@ -0,0 +1,37 @@ +"""插件实例与安装来源的 ID 合同一致性回归测试。""" + +import pytest +from pydantic import ValidationError + +from app.domain.plugin import is_physical_plugin_id +from app.schemas.plugin import PluginInstance, validate_plugin_id + + +@pytest.mark.parametrize("plugin_id", ["DemoPlugin", "nullbr_search", "Nullbr_Search2", "A" * 128]) +def test_instance_ids_accept_installed_plugin_identity(plugin_id: str) -> None: + """市场允许的物理身份必须能用于本体及共享源码分身，且不改变大小写。""" + assert is_physical_plugin_id(plugin_id) + assert validate_plugin_id(plugin_id) == plugin_id + host = PluginInstance(instance_id=plugin_id, source_plugin_id=plugin_id) + assert host.is_host + assert host.instance_id == plugin_id + if len(plugin_id) < 128: + clone = PluginInstance(instance_id=f"{plugin_id}x2", source_plugin_id=plugin_id) + assert not clone.is_host + assert clone.source_plugin_id == plugin_id + + +@pytest.mark.parametrize( + "plugin_id", + ["", "_Plugin", "1Plugin", "../Plugin", "a/b", "a\\b", "a.b", "a-b", "a@b", + "a b", "a\n", "插件", "Ｐlugin", "A" * 129], +) +def test_instance_ids_reject_unsafe_or_unsupported_identity(plugin_id: str) -> None: + """实例校验保持字母开头、ASCII、路径安全和长度限制，与安装侧一致。""" + assert not is_physical_plugin_id(plugin_id) + with pytest.raises(ValueError): + validate_plugin_id(plugin_id) + with pytest.raises(ValidationError): + PluginInstance(instance_id=plugin_id, source_plugin_id="DemoPlugin") + with pytest.raises(ValidationError): + PluginInstance(instance_id="DemoPlugin", source_plugin_id=plugin_id) diff --git a/tests/test_plugin_instance_directory.py b/tests/test_plugin_instance_directory.py index bb986b185..ce16d34a2 100644 --- a/tests/test_plugin_instance_directory.py +++ b/tests/test_plugin_instance_directory.py @@ -3,6 +3,8 @@ from types import SimpleNamespace from unittest.mock import MagicMock +from app.db.oper.plugininstance import PluginInstanceOper +from app.runtime.extensions.plugin.storage import PluginInstanceStore, PluginStorage from app.startup.initializers import plugins as plugins_initializer @@ -43,3 +45,32 @@ def test_plugin_instance_directory_skips_invalid_records_on_every_read(monkeypat assert [item.instance_id for item in directory.list_enabled()] == [valid.instance_id] assert logger.warning.call_count == 4 assert invalid.instance_id in str(logger.warning.call_args) + + +def test_underscore_host_can_be_disabled_without_repeated_projection_warnings(monkeypatch) -> None: + """含下划线的存量本体能在卸载时停用，保留配置的重复读取也不误报无效行。""" + plugin_id = "nullbr_search" + oper = PluginInstanceOper() + logger = MagicMock() + monkeypatch.setattr(plugins_initializer, "logger", logger) + directory = plugins_initializer._build_plugin_instance_directory() + storage = PluginStorage(read=lambda _key: None, write=lambda _key, _value: None) + store = PluginInstanceStore(storage=lambda: storage, directory=lambda: directory) + try: + oper.save(instance_id=plugin_id, source_plugin_id=plugin_id, is_enabled=True) + oper.save_config_data( + instance_id=plugin_id, source_plugin_id=plugin_id, config_data={"token": "kept"} + ) + assert plugin_id in store.enabled_hosts() + assert store.disable_host(plugin_id) + assert not store.disable_host(plugin_id) + for _ in range(3): + host = store.get_host(plugin_id) + assert host is not None and host.is_enabled is False + assert plugin_id in store.all_hosts() + assert store.for_source(plugin_id) == [] + assert plugin_id not in store.enabled_hosts() + assert oper.get_config_data(plugin_id) == {"token": "kept"} + logger.warning.assert_not_called() + finally: + oper.delete(plugin_id) diff --git a/tests/test_plugin_instance_purge_path_traversal.py b/tests/test_plugin_instance_purge_path_traversal.py index a208f22dd..b291e0b76 100644 --- a/tests/test_plugin_instance_purge_path_traversal.py +++ b/tests/test_plugin_instance_purge_path_traversal.py @@ -196,19 +196,25 @@ def test_purge_refuses_every_malformed_instance_id( assert _sentinels_intact(config_root) +@pytest.mark.parametrize("instance_id", ["DemoPlugin", "nullbr_search"]) def test_purge_deletes_the_directory_for_a_well_formed_instance_id( config_root: Path, + instance_id: str, ) -> None: - """合法标识照常清理，且只动它自己那一层。""" + """普通和含下划线的合法标识照常清理，且只动它自己那一层。""" calls: list[tuple] = [] + target = config_root / "plugins" / instance_id + target.mkdir(exist_ok=True) + (target / "cache.bin").write_text("x", encoding="utf-8") result = _purge_command(calls).purge( - "DemoPlugin", PluginPurgeScope(data_directory=True) + instance_id, PluginPurgeScope(data_directory=True) ) assert result.success is True assert result.purged == ("data_directory",) - assert not (config_root / "plugins" / "DemoPlugin").exists() + assert not target.exists() + assert calls == [("stop", instance_id), ("own_db", instance_id)] assert (config_root / "protected" / "keep.txt").is_file() assert (config_root / "user.db").is_file()