From 0a9cad1c7691d4134be98b368ae9430618f1e061 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 12:52:40 +0800 Subject: [PATCH 01/13] =?UTF-8?q?feat(extension):=20=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=91=BD=E4=BB=A4=E4=B8=8E=E8=AE=BE=E7=BD=AE?= =?UTF-8?q?=E8=B4=A1=E7=8C=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 3 +- backend/README.md | 4 +- backend/app/container.py | 1 + backend/app/contracts.py | 92 +++ backend/app/extensions/__init__.py | 8 +- backend/app/extensions/contributions.py | 749 ++++++++++++++++++ backend/app/extensions/errors.py | 21 + backend/app/extensions/runtime.py | 233 +++++- backend/app/routes.py | 88 ++ .../plugins/text-tools/commands.yaml | 19 + .../extensions/plugins/text-tools/plugin.yaml | 4 + .../plugins/text-tools/settings.yaml | 31 + backend/tests/test_api.py | 4 + backend/tests/test_plugin_contributions.py | 296 +++++++ frontend/src/contracts/index.ts | 60 ++ frontend/src/services/pluginService.spec.ts | 84 ++ frontend/src/services/pluginService.ts | 63 +- 17 files changed, 1734 insertions(+), 26 deletions(-) create mode 100644 backend/app/extensions/contributions.py create mode 100644 backend/app/extensions/errors.py create mode 100644 backend/extensions/plugins/text-tools/commands.yaml create mode 100644 backend/extensions/plugins/text-tools/settings.yaml create mode 100644 backend/tests/test_plugin_contributions.py create mode 100644 frontend/src/services/pluginService.spec.ts diff --git a/README.md b/README.md index 10d735b..aa77036 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 92 项测试、前端 27 项测试，且生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 103 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 @@ -133,6 +133,7 @@ pnpm test | [第二阶段接口契约](docs/contracts/第二阶段接口契约-开发版.md) | 第二阶段公共 DTO、计划接口、SSE、错误码与联调顺序 | | [AI Core 与 Agent Core](docs/development/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | | [MCP Bridge 与 Plugin Host](docs/development/MCP-Bridge与Plugin-Host开发说明.md) | stdio MCP、隔离进程、Tool 映射、状态与错误边界 | +| [Plugin Command 与 Settings](docs/development/Plugin-Command与Settings开发说明.md) | Command Registry、Settings Schema、Secret 引用与联调边界 | | [Git 使用细则](docs/guides/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 | | [CI/CD 细则](docs/guides/CI-CD细则-团队开发版.md) | Gitea 流水线、质量门禁、产物、发布与回滚规则 | | [Agent Trace 复盘](docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md) | Agent 持久化、SSE 恢复、事件契约与脱敏问题复盘 | diff --git a/backend/README.md b/backend/README.md index 3d4fde4..b1a3bec 100644 --- a/backend/README.md +++ b/backend/README.md @@ -2,7 +2,7 @@ FastAPI + Pydantic 的本地 AI Core / Agent Core。项目使用 uv 管理依赖和虚拟环境。 -当前实现包含 Knowledge/Retrieval、Chat、Agent Runtime、Tool/Permission、Skill/Plugin、Provider Adapter、任务、索引和开发阶段凭据加密存储。Provider 支持 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama；OpenAI Responses、Anthropic Messages、MCP 独立 Host 和真实语音模型仍属于后续阶段。 +当前实现包含 Knowledge/Retrieval、Chat、Agent Runtime、Tool/Permission、Skill/Plugin、stdio MCP Host、Plugin Command/Settings、Provider Adapter、任务、索引和开发阶段凭据加密存储。Provider 支持 Mock、OpenAI Chat/OpenAI-Compatible 与 Ollama；OpenAI Responses、Anthropic Messages、操作系统级 Plugin 沙箱和真实语音模型仍属于后续阶段。 ```powershell uv sync @@ -23,7 +23,7 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 92 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。 +当前基线为 103 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。 团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 diff --git a/backend/app/container.py b/backend/app/container.py index 9263ca9..62b21be 100644 --- a/backend/app/container.py +++ b/backend/app/container.py @@ -53,6 +53,7 @@ def build_container() -> ApplicationContainer: plugins = PluginRuntime( tools, + credentials=credentials, # 当前 Python Host 尚无 OS 沙箱。生产构建必须保持关闭，直到 # Tauri/Rust Host 能签发绑定命令摘要的可信启动许可。 allow_unsandboxed_mcp=settings.environment == "development", diff --git a/backend/app/contracts.py b/backend/app/contracts.py index 8d1aace..e0d4869 100644 --- a/backend/app/contracts.py +++ b/backend/app/contracts.py @@ -486,6 +486,98 @@ class PluginHostStatus(Contract): error: str | None = None +class PluginCommandLocation(str, Enum): + command_palette = "command_palette" + context_menu = "context_menu" + toolbar = "toolbar" + + +class PluginCommand(Contract): + command_id: str + plugin_id: str + title: str + description: str = "" + icon: str | None = None + locations: list[PluginCommandLocation] = Field(default_factory=list) + when: list[str] = Field(default_factory=list) + parameters: dict[str, Any] = Field(default_factory=dict) + enabled: bool = True + + +class PluginCommandListResponse(Contract): + items: list[PluginCommand] = Field(default_factory=list) + + +class PluginCommandContext(Contract): + vault_id: str | None = None + note_id: str | None = None + file_path: str | None = None + selection: str | None = None + + +class PluginCommandExecuteRequest(Contract): + arguments: dict[str, Any] = Field(default_factory=dict) + context: PluginCommandContext = Field(default_factory=PluginCommandContext) + + +class PluginCommandEffect(Contract): + type: Literal["none", "notification", "navigate", "refresh", "job"] = "none" + payload: dict[str, Any] = Field(default_factory=dict) + + +class PluginCommandResult(Contract): + command_id: str + status: Literal["completed"] = "completed" + effect: PluginCommandEffect = Field(default_factory=PluginCommandEffect) + + +class PluginSettingType(str, Enum): + string = "string" + number = "number" + boolean = "boolean" + select = "select" + secret = "secret" + + +class PluginSettingField(Contract): + key: str + label: str + description: str = "" + type: PluginSettingType + required: bool = False + default: Any | None = None + minimum: float | None = None + maximum: float | None = None + options: list[str] = Field(default_factory=list) + + +class PluginSecretState(Contract): + configured: bool = False + + +class PluginSettingsSchema(Contract): + plugin_id: str + schema_version: int = Field(ge=1) + fields: list[PluginSettingField] = Field(default_factory=list) + values: dict[str, Any] = Field(default_factory=dict) + secrets: dict[str, PluginSecretState] = Field(default_factory=dict) + + +class PluginSettingsUpdateRequest(Contract): + schema_version: int = Field(ge=1) + values: dict[str, Any] = Field(default_factory=dict) + + +class PluginSecretWriteRequest(Contract): + secret: SecretStr + + +class PluginSecretStatus(Contract): + plugin_id: str + key: str + configured: bool + + class PluginPermissionGrantRequest(Contract): permissions: list[str] = Field(default_factory=list) diff --git a/backend/app/extensions/__init__.py b/backend/app/extensions/__init__.py index ed2e570..41c8599 100644 --- a/backend/app/extensions/__init__.py +++ b/backend/app/extensions/__init__.py @@ -1,9 +1,5 @@ -from app.extensions.runtime import ( - AgentConfiguration, - ExtensionError, - PluginRuntime, - SkillRuntime, -) +from app.extensions.errors import ExtensionError +from app.extensions.runtime import AgentConfiguration, PluginRuntime, SkillRuntime from app.extensions.mcp import McpBridge, McpBridgeError __all__ = [ diff --git a/backend/app/extensions/contributions.py b/backend/app/extensions/contributions.py new file mode 100644 index 0000000..6a17a38 --- /dev/null +++ b/backend/app/extensions/contributions.py @@ -0,0 +1,749 @@ +"""Plugin Command Registry 与 Settings/Secret 命名空间存储。""" + +from __future__ import annotations + +import asyncio +import inspect +import json +import math +import re +import threading +from collections import deque +from dataclasses import dataclass +from datetime import UTC, datetime +from pathlib import Path +from time import perf_counter +from typing import Any, Awaitable, Callable, Literal + +from jsonschema import Draft202012Validator +from jsonschema.exceptions import SchemaError, ValidationError as JsonSchemaValidationError +from pydantic import BaseModel, ConfigDict, Field + +from app.config import get_settings +from app.contracts import ( + PluginCommand, + PluginCommandContext, + PluginCommandEffect, + PluginCommandLocation, + PluginCommandResult, + PluginSecretState, + PluginSecretStatus, + PluginSettingField, + PluginSettingType, + PluginSettingsSchema, +) +from app.extensions.errors import ExtensionError +from app.providers.credentials import CredentialStoreError, EncryptedCredentialStore + +_CONTRIBUTION_ID = re.compile(r"^[a-z0-9][a-z0-9._-]*$") +_SETTING_KEY = re.compile(r"^[a-z][a-z0-9._-]{0,127}$") +_HOST_ICONS = {"bolt", "document", "edit", "link", "refresh", "search", "setting"} +_WHEN_TOKENS = { + "workspace.has_vault", + "editor.has_note", + "editor.has_selection", +} +_CONTEXT_KEYS = {"vault_id", "note_id", "file_path", "selection"} +_WHEN_CONTEXT = { + "workspace.has_vault": "vault_id", + "editor.has_note": "note_id", + "editor.has_selection": "selection", +} + + +class PluginCommandSpec(BaseModel): + """包内 commands.yaml 的宿主侧声明，不直接暴露 handler。""" + + model_config = ConfigDict(extra="forbid") + + command_id: str + title: str + description: str = "" + icon: str | None = None + locations: list[PluginCommandLocation] = Field(default_factory=list) + when: list[str] = Field(default_factory=list) + context: list[Literal["vault_id", "note_id", "file_path", "selection"]] = Field( + default_factory=list + ) + parameters: dict[str, Any] = Field( + default_factory=lambda: { + "type": "object", + "properties": {}, + "additionalProperties": False, + } + ) + permission: str | None = None + handler: Literal["echo", "uppercase_selection"] + timeout_seconds: int = Field(default=30, ge=1, le=120) + + +CommandExecutor = Callable[ + [dict[str, Any], dict[str, Any]], + PluginCommandEffect | Awaitable[PluginCommandEffect], +] + + +@dataclass(slots=True) +class _RegisteredCommand: + command: PluginCommand + spec: PluginCommandSpec + executor: CommandExecutor + + +@dataclass(frozen=True, slots=True) +class PluginCommandAuditEvent: + """不记录参数与上下文的轻量审计事件，避免把正文或 Secret 写入日志。""" + + command_id: str + plugin_id: str + status: Literal["completed", "failed"] + duration_ms: int + error_code: str | None + created_at: datetime + + +class CommandRegistry: + """只发布已启用 Plugin 的受控 Command Contribution。""" + + def __init__(self) -> None: + self._commands: dict[str, _RegisteredCommand] = {} + self._audit: deque[PluginCommandAuditEvent] = deque(maxlen=500) + self._lock = threading.RLock() + + def register( + self, + plugin_id: str, + spec: PluginCommandSpec, + executor: CommandExecutor, + ) -> None: + validate_command_spec(plugin_id, spec) + command = PluginCommand( + command_id=spec.command_id, + plugin_id=plugin_id, + title=spec.title, + description=spec.description, + icon=spec.icon, + locations=spec.locations, + when=spec.when, + parameters=spec.parameters, + enabled=True, + ) + with self._lock: + if spec.command_id in self._commands: + raise ExtensionError( + "PLUGIN_COMMAND_CONFLICT", + f"Plugin command is already registered: {spec.command_id}", + status_code=409, + details={"command_id": spec.command_id}, + ) + self._commands[spec.command_id] = _RegisteredCommand(command, spec, executor) + + def unregister(self, command_id: str) -> None: + with self._lock: + self._commands.pop(command_id, None) + + def contains(self, command_id: str) -> bool: + with self._lock: + return command_id in self._commands + + def list(self, location: PluginCommandLocation | None = None) -> list[PluginCommand]: + with self._lock: + items = [ + item.command.model_copy(deep=True) + for item in self._commands.values() + if location is None or location in item.command.locations + ] + return sorted(items, key=lambda item: item.command_id) + + def audit_events(self) -> list[PluginCommandAuditEvent]: + """返回有界审计快照；事件刻意不包含 arguments/context/effect。""" + + with self._lock: + return list(self._audit) + + async def execute( + self, + command_id: str, + arguments: dict[str, Any], + context: PluginCommandContext, + ) -> PluginCommandResult: + with self._lock: + registered = self._commands.get(command_id) + if registered is None: + raise ExtensionError( + "PLUGIN_COMMAND_NOT_FOUND", + f"Plugin command is not registered or enabled: {command_id}", + status_code=404, + details={"command_id": command_id}, + ) + started_at = perf_counter() + try: + Draft202012Validator(registered.spec.parameters).validate(arguments) + except JsonSchemaValidationError as exc: + error = ExtensionError( + "PLUGIN_COMMAND_ARGUMENT_INVALID", + "Plugin command arguments do not match the declared schema.", + details={"command_id": command_id, "path": list(exc.path)}, + ) + self._record_audit(registered, started_at, error.code) + raise error from exc + + raw_context = context.model_dump(exclude_none=True) + missing = [ + token + for token in registered.spec.when + if not raw_context.get(_WHEN_CONTEXT[token]) + ] + if missing: + error = ExtensionError( + "PLUGIN_COMMAND_CONTEXT_INVALID", + "Plugin command context does not satisfy its when conditions.", + details={"command_id": command_id, "missing": missing}, + ) + self._record_audit(registered, started_at, error.code) + raise error + scoped_context = { + key: raw_context[key] + for key in registered.spec.context + if key in raw_context + } + try: + effect = registered.executor(dict(arguments), scoped_context) + if inspect.isawaitable(effect): + effect = await asyncio.wait_for( + effect, timeout=registered.spec.timeout_seconds + ) + except TimeoutError as exc: + error = ExtensionError( + "PLUGIN_COMMAND_TIMEOUT", + "Plugin command execution timed out.", + status_code=504, + details={"command_id": command_id}, + ) + self._record_audit(registered, started_at, error.code) + raise error from exc + except ExtensionError as exc: + self._record_audit(registered, started_at, exc.code) + raise + except Exception as exc: + error = ExtensionError( + "PLUGIN_COMMAND_EXECUTION_FAILED", + "Plugin command execution failed.", + status_code=502, + details={"command_id": command_id}, + ) + self._record_audit(registered, started_at, error.code) + raise error from exc + if not isinstance(effect, PluginCommandEffect): + error = ExtensionError( + "PLUGIN_COMMAND_RESULT_INVALID", + "Plugin command returned an invalid effect.", + status_code=502, + details={"command_id": command_id}, + ) + self._record_audit(registered, started_at, error.code) + raise error + try: + encoded_effect = json.dumps(effect.model_dump(mode="json"), ensure_ascii=False) + except (TypeError, ValueError) as exc: + error = ExtensionError( + "PLUGIN_COMMAND_RESULT_INVALID", + "Plugin command returned a non-serializable effect.", + status_code=502, + details={"command_id": command_id}, + ) + self._record_audit(registered, started_at, error.code) + raise error from exc + if len(encoded_effect.encode("utf-8")) > 64 * 1024: + error = ExtensionError( + "PLUGIN_COMMAND_RESULT_TOO_LARGE", + "Plugin command effect exceeds the 64 KiB response limit.", + status_code=502, + details={"command_id": command_id}, + ) + self._record_audit(registered, started_at, error.code) + raise error + self._record_audit(registered, started_at, None) + return PluginCommandResult(command_id=command_id, effect=effect) + + def _record_audit( + self, + registered: _RegisteredCommand, + started_at: float, + error_code: str | None, + ) -> None: + event = PluginCommandAuditEvent( + command_id=registered.command.command_id, + plugin_id=registered.command.plugin_id, + status="failed" if error_code else "completed", + duration_ms=max(0, round((perf_counter() - started_at) * 1000)), + error_code=error_code, + created_at=datetime.now(UTC), + ) + with self._lock: + self._audit.append(event) + + +class PluginSettingsDefinition(BaseModel): + model_config = ConfigDict(extra="forbid") + + section_id: str + schema_version: int = Field(ge=1) + fields: list[PluginSettingField] = Field(default_factory=list) + + +class PluginSettingsStore: + """非敏感值写入插件命名空间；Secret 只保存加密凭据引用。""" + + def __init__(self, credentials: EncryptedCredentialStore) -> None: + self.credentials = credentials + self._lock = threading.RLock() + + @staticmethod + def _path() -> Path: + return get_settings().data_dir / "plugins" / "settings.json" + + def get( + self, plugin_id: str, definition: PluginSettingsDefinition + ) -> PluginSettingsSchema: + with self._lock: + entry = self._entry(self._read(), plugin_id) + stored_values = entry.get("values", {}) + secret_refs = entry.get("secret_refs", {}) + if not isinstance(stored_values, dict) or not isinstance(secret_refs, dict): + raise self._storage_format_error(plugin_id) + values = { + field.key: field.default + for field in definition.fields + if field.type != PluginSettingType.secret and field.default is not None + } + allowed_values = { + field.key + for field in definition.fields + if field.type != PluginSettingType.secret + } + fields = {field.key: field for field in definition.fields} + for key, value in stored_values.items(): + if key not in allowed_values: + continue + try: + _validate_setting_value(fields[key], value) + except ExtensionError as exc: + raise self._storage_format_error(plugin_id) from exc + values[key] = value + secrets: dict[str, PluginSecretState] = {} + for field in definition.fields: + if field.type != PluginSettingType.secret: + continue + reference = secret_refs.get(field.key) + secrets[field.key] = PluginSecretState( + configured=isinstance(reference, str) and self._has_secret(reference) + ) + return PluginSettingsSchema( + plugin_id=plugin_id, + schema_version=definition.schema_version, + fields=definition.fields, + values=values, + secrets=secrets, + ) + + def update( + self, + plugin_id: str, + definition: PluginSettingsDefinition, + schema_version: int, + values: dict[str, Any], + ) -> PluginSettingsSchema: + if schema_version != definition.schema_version: + raise ExtensionError( + "PLUGIN_SETTINGS_VERSION_CONFLICT", + "Plugin settings schema version is out of date.", + status_code=409, + details={ + "plugin_id": plugin_id, + "requested_version": schema_version, + "current_version": definition.schema_version, + }, + ) + fields = {field.key: field for field in definition.fields} + unknown = sorted(set(values) - set(fields)) + if unknown: + raise ExtensionError( + "PLUGIN_SETTINGS_FIELD_INVALID", + "Plugin settings contain unknown fields.", + details={"plugin_id": plugin_id, "fields": unknown}, + ) + secret_keys = sorted( + key for key in values if fields[key].type == PluginSettingType.secret + ) + if secret_keys: + raise ExtensionError( + "PLUGIN_SETTINGS_FIELD_INVALID", + "Secret fields must use the dedicated Secret endpoint.", + details={"plugin_id": plugin_id, "fields": secret_keys}, + ) + for key, value in values.items(): + _validate_setting_value(fields[key], value) + + with self._lock: + data = self._read() + entry = self._entry(data, plugin_id, create=True) + current = entry.get("values", {}) + if not isinstance(current, dict): + raise self._storage_format_error(plugin_id) + entry["values"] = current + current.update(values) + effective = { + field.key: field.default + for field in definition.fields + if field.type != PluginSettingType.secret and field.default is not None + } + effective.update(current) + missing = [ + field.key + for field in definition.fields + if field.required + and field.type != PluginSettingType.secret + and field.key not in effective + ] + if missing: + raise ExtensionError( + "PLUGIN_SETTINGS_FIELD_INVALID", + "Required Plugin settings are missing.", + details={"plugin_id": plugin_id, "fields": missing}, + ) + entry["schema_version"] = definition.schema_version + self._write(data) + return self.get(plugin_id, definition) + + def put_secret( + self, + plugin_id: str, + definition: PluginSettingsDefinition, + key: str, + secret: str, + ) -> PluginSecretStatus: + _secret_field(definition, plugin_id, key) + if not secret: + raise ExtensionError( + "PLUGIN_SECRET_VALUE_INVALID", + "Plugin secret cannot be empty.", + details={"plugin_id": plugin_id, "key": key}, + ) + if len(secret.encode("utf-8")) > 64 * 1024: + raise ExtensionError( + "PLUGIN_SECRET_VALUE_INVALID", + "Plugin secret exceeds the 64 KiB limit.", + details={"plugin_id": plugin_id, "key": key}, + ) + reference = _secret_reference(plugin_id, key) + with self._lock: + data = self._read() + entry = self._entry(data, plugin_id, create=True) + refs = entry.get("secret_refs", {}) + if not isinstance(refs, dict): + raise self._storage_format_error(plugin_id) + entry["secret_refs"] = refs + try: + previous = self.credentials.resolve(reference) + self.credentials.put(reference, secret) + except CredentialStoreError as exc: + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 + ) from exc + refs[key] = reference + entry["schema_version"] = definition.schema_version + try: + self._write(data) + except ExtensionError: + # 普通设置落盘失败时恢复凭据旧值，避免产生不可达的新 Secret。 + try: + if previous is None: + self.credentials.delete(reference) + else: + self.credentials.put(reference, previous) + except CredentialStoreError: + pass + raise + return PluginSecretStatus(plugin_id=plugin_id, key=key, configured=True) + + def delete_secret( + self, + plugin_id: str, + definition: PluginSettingsDefinition, + key: str, + ) -> PluginSecretStatus: + _secret_field(definition, plugin_id, key) + with self._lock: + data = self._read() + entry = self._entry(data, plugin_id) + refs = entry.get("secret_refs", {}) + if not isinstance(refs, dict): + raise self._storage_format_error(plugin_id) + reference = refs.pop(key, None) + if reference: + try: + self.credentials.delete(reference) + except CredentialStoreError as exc: + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 + ) from exc + if plugin_id in data: + self._write(data) + return PluginSecretStatus(plugin_id=plugin_id, key=key, configured=False) + + def resolve_secret( + self, plugin_id: str, definition: PluginSettingsDefinition, key: str + ) -> str | None: + _secret_field(definition, plugin_id, key) + with self._lock: + entry = self._entry(self._read(), plugin_id) + refs = entry.get("secret_refs", {}) + if not isinstance(refs, dict): + raise self._storage_format_error(plugin_id) + reference = refs.get(key) + try: + return self.credentials.resolve(reference) if isinstance(reference, str) else None + except CredentialStoreError as exc: + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 + ) from exc + + def remove_plugin(self, plugin_id: str) -> None: + with self._lock: + data = self._read() + entry = data.pop(plugin_id, None) + if isinstance(entry, dict): + refs = entry.get("secret_refs", {}) + if isinstance(refs, dict): + for reference in refs.values(): + if isinstance(reference, str): + try: + self.credentials.delete(reference) + except CredentialStoreError as exc: + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", + str(exc), + status_code=500, + ) from exc + if entry is not None: + self._write(data) + + def _has_secret(self, reference: str) -> bool: + try: + return self.credentials.has(reference) + except CredentialStoreError as exc: + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 + ) from exc + + @staticmethod + def _storage_format_error(plugin_id: str) -> ExtensionError: + return ExtensionError( + "PLUGIN_STORAGE_ERROR", + "Plugin settings namespace has an invalid format.", + status_code=500, + details={"plugin_id": plugin_id}, + ) + + def _entry( + self, + data: dict[str, dict[str, Any]], + plugin_id: str, + *, + create: bool = False, + ) -> dict[str, Any]: + entry = data.get(plugin_id) + if entry is None: + if create: + data[plugin_id] = {} + return data[plugin_id] + return {} + if not isinstance(entry, dict): + raise self._storage_format_error(plugin_id) + return entry + + def _read(self) -> dict[str, dict[str, Any]]: + path = self._path() + if not path.exists(): + return {} + try: + value = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + raise ExtensionError( + "PLUGIN_STORAGE_ERROR", + "Plugin settings storage cannot be loaded.", + status_code=500, + ) from exc + if not isinstance(value, dict): + raise ExtensionError( + "PLUGIN_STORAGE_ERROR", + "Plugin settings storage has an invalid format.", + status_code=500, + ) + return value + + def _write(self, value: dict[str, dict[str, Any]]) -> None: + path = self._path() + path.parent.mkdir(parents=True, exist_ok=True) + temporary = path.with_suffix(".tmp") + try: + temporary.write_text( + json.dumps(value, ensure_ascii=False, sort_keys=True), + encoding="utf-8", + ) + temporary.replace(path) + except OSError as exc: + raise ExtensionError( + "PLUGIN_STORAGE_ERROR", + "Plugin settings storage cannot be written.", + status_code=500, + ) from exc + + +def validate_settings_definition( + plugin_id: str, definition: PluginSettingsDefinition +) -> None: + if not _CONTRIBUTION_ID.fullmatch(definition.section_id): + raise _settings_schema_error(plugin_id, "Settings section id is invalid.") + if not definition.section_id.startswith(f"{plugin_id}."): + raise _settings_schema_error( + plugin_id, "Settings section id must use the Plugin namespace." + ) + keys: set[str] = set() + for field in definition.fields: + if not _SETTING_KEY.fullmatch(field.key) or field.key in keys: + raise _settings_schema_error(plugin_id, f"Invalid or duplicate setting key: {field.key}") + keys.add(field.key) + if field.type == PluginSettingType.select and not field.options: + raise _settings_schema_error(plugin_id, f"Select setting requires options: {field.key}") + if field.type != PluginSettingType.select and field.options: + raise _settings_schema_error(plugin_id, f"Only select settings accept options: {field.key}") + if field.type != PluginSettingType.number and ( + field.minimum is not None or field.maximum is not None + ): + raise _settings_schema_error(plugin_id, f"Only number settings accept bounds: {field.key}") + if field.minimum is not None and field.maximum is not None and field.minimum > field.maximum: + raise _settings_schema_error(plugin_id, f"Setting bounds are reversed: {field.key}") + if field.type == PluginSettingType.secret and field.default is not None: + raise _settings_schema_error(plugin_id, f"Secret settings cannot declare defaults: {field.key}") + if field.default is not None: + try: + _validate_setting_value(field, field.default) + except ExtensionError as exc: + raise _settings_schema_error(plugin_id, exc.message) from exc + + +def validate_command_spec(plugin_id: str, spec: PluginCommandSpec) -> None: + if not _CONTRIBUTION_ID.fullmatch(spec.command_id) or not spec.command_id.startswith( + f"{plugin_id}." + ): + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command id must be valid and use the Plugin namespace.", + details={"plugin_id": plugin_id, "command_id": spec.command_id}, + ) + if not spec.locations: + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command must declare at least one location.", + details={"command_id": spec.command_id}, + ) + if len(spec.locations) != len(set(spec.locations)): + raise ExtensionError("PLUGIN_COMMAND_INVALID", "Plugin command locations must be unique.") + if len(spec.when) != len(set(spec.when)) or len(spec.context) != len(set(spec.context)): + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command when/context entries must be unique.", + ) + unknown_when = sorted(set(spec.when) - _WHEN_TOKENS) + if unknown_when: + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command declares unsupported when tokens.", + details={"command_id": spec.command_id, "when": unknown_when}, + ) + required_context = {_WHEN_CONTEXT[token] for token in spec.when} + if not required_context.issubset(set(spec.context)): + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command context must include every field required by when.", + details={"command_id": spec.command_id}, + ) + if not set(spec.context).issubset(_CONTEXT_KEYS): + raise ExtensionError("PLUGIN_COMMAND_INVALID", "Plugin command context is invalid.") + if spec.icon and spec.icon not in _HOST_ICONS: + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command icon is not a supported Host icon.", + details={"command_id": spec.command_id, "icon": spec.icon}, + ) + if spec.parameters.get("type", "object") != "object": + raise ExtensionError("PLUGIN_COMMAND_INVALID", "Command parameters must be an object schema.") + try: + Draft202012Validator.check_schema(spec.parameters) + except SchemaError as exc: + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + f"Plugin command parameters contain invalid JSON Schema: {exc.message}", + ) from exc + + +def _validate_setting_value(field: PluginSettingField, value: Any) -> None: + valid = False + if field.type == PluginSettingType.string: + valid = isinstance(value, str) and len(value.encode("utf-8")) <= 64 * 1024 + elif field.type == PluginSettingType.number: + valid = ( + (isinstance(value, int) and not isinstance(value, bool)) + or (isinstance(value, float) and math.isfinite(value)) + ) + elif field.type == PluginSettingType.boolean: + valid = isinstance(value, bool) + elif field.type == PluginSettingType.select: + valid = isinstance(value, str) and value in field.options + if not valid: + raise ExtensionError( + "PLUGIN_SETTINGS_FIELD_INVALID", + f"Plugin setting has an invalid value: {field.key}", + details={"key": field.key}, + ) + if field.type == PluginSettingType.number: + if field.minimum is not None and value < field.minimum: + raise ExtensionError( + "PLUGIN_SETTINGS_FIELD_INVALID", + f"Plugin setting is below its minimum: {field.key}", + details={"key": field.key, "minimum": field.minimum}, + ) + if field.maximum is not None and value > field.maximum: + raise ExtensionError( + "PLUGIN_SETTINGS_FIELD_INVALID", + f"Plugin setting is above its maximum: {field.key}", + details={"key": field.key, "maximum": field.maximum}, + ) + + +def _secret_field( + definition: PluginSettingsDefinition, plugin_id: str, key: str +) -> PluginSettingField: + field = next((item for item in definition.fields if item.key == key), None) + if field is None or field.type != PluginSettingType.secret: + raise ExtensionError( + "PLUGIN_SECRET_FIELD_NOT_FOUND", + f"Plugin secret field does not exist: {key}", + status_code=404, + details={"plugin_id": plugin_id, "key": key}, + ) + return field + + +def _secret_reference(plugin_id: str, key: str) -> str: + return f"plugin.{plugin_id}.{key}" + + +def _settings_schema_error(plugin_id: str, message: str) -> ExtensionError: + return ExtensionError( + "PLUGIN_SETTINGS_SCHEMA_INVALID", + message, + details={"plugin_id": plugin_id}, + ) diff --git a/backend/app/extensions/errors.py b/backend/app/extensions/errors.py new file mode 100644 index 0000000..61ed7a8 --- /dev/null +++ b/backend/app/extensions/errors.py @@ -0,0 +1,21 @@ +from __future__ import annotations + +from typing import Any + + +class ExtensionError(RuntimeError): + """Extension Core 对 API 暴露的稳定领域错误。""" + + def __init__( + self, + code: str, + message: str, + *, + status_code: int = 422, + details: dict[str, Any] | None = None, + ) -> None: + super().__init__(message) + self.code = code + self.message = message + self.status_code = status_code + self.details = details or {} diff --git a/backend/app/extensions/runtime.py b/backend/app/extensions/runtime.py index 832b726..054424e 100644 --- a/backend/app/extensions/runtime.py +++ b/backend/app/extensions/runtime.py @@ -16,8 +16,15 @@ from app.agent.permissions import KNOWN_PERMISSIONS from app.contracts import ( ModelCapability, Plugin, + PluginCommand, + PluginCommandContext, + PluginCommandEffect, + PluginCommandLocation, + PluginCommandResult, PluginManifest, PluginHostStatus, + PluginSecretStatus, + PluginSettingsSchema, PluginStatus, RetrievalConfig, Skill, @@ -25,27 +32,21 @@ from app.contracts import ( SkillStatus, ToolDefinition, ) +from app.extensions.contributions import ( + CommandRegistry, + PluginCommandSpec, + PluginSettingsDefinition, + PluginSettingsStore, + validate_command_spec, + validate_settings_definition, +) +from app.extensions.errors import ExtensionError from app.extensions.mcp import McpBridge, McpBridgeError, McpDiscoveredTool +from app.providers.credentials import EncryptedCredentialStore _EXTENSION_ID = re.compile(r"^[a-z0-9][a-z0-9._-]*$") -class ExtensionError(RuntimeError): - def __init__( - self, - code: str, - message: str, - *, - status_code: int = 422, - details: dict[str, Any] | None = None, - ) -> None: - super().__init__(message) - self.code = code - self.message = message - self.status_code = status_code - self.details = details or {} - - @dataclass(frozen=True, slots=True) class AgentConfiguration: skill_id: str @@ -238,13 +239,42 @@ class DeclarativePluginHost: return {"text": str(values.get("text", "")).upper()} raise ExtensionError("PLUGIN_HANDLER_UNSUPPORTED", f"Unsupported handler: {handler}") + async def execute_command( + self, + handler: str, + arguments: dict[str, Any], + context: dict[str, Any], + settings: dict[str, Any], + ) -> PluginCommandEffect: + """执行宿主内置的白名单 Command handler，不导入 Plugin Python 代码。""" + + if handler == "echo": + message = str(arguments.get("message", context.get("selection", ""))) + return PluginCommandEffect( + type="notification", + payload={"level": "info", "message": message}, + ) + if handler == "uppercase_selection": + text = str(arguments.get("text", context.get("selection", ""))) + limit = int(settings.get("result_limit", 100)) + return PluginCommandEffect( + type="notification", + payload={"level": "success", "message": text[:limit].upper()}, + ) + raise ExtensionError( + "PLUGIN_HANDLER_UNSUPPORTED", f"Unsupported command handler: {handler}" + ) + @dataclass(slots=True) class _PluginRecord: plugin: Plugin tools: list[DeclarativeToolSpec] + commands: list[PluginCommandSpec] + settings_definition: PluginSettingsDefinition | None package_path: Path registered_tools: list[str] + registered_commands: list[str] mcp_remote_names: dict[str, str] @@ -256,12 +286,15 @@ class PluginRuntime: tools: ToolRegistry, host: DeclarativePluginHost | None = None, mcp_bridge: McpBridge | None = None, + credentials: EncryptedCredentialStore | None = None, *, allow_unsandboxed_mcp: bool = False, ) -> None: self.registry = tools self.host = host or DeclarativePluginHost() self.mcp = mcp_bridge or McpBridge() + self.commands = CommandRegistry() + self.settings = PluginSettingsStore(credentials or EncryptedCredentialStore()) self.allow_unsandboxed_mcp = allow_unsandboxed_mcp self._records: dict[str, _PluginRecord] = {} self._lock = threading.RLock() @@ -287,6 +320,8 @@ class PluginRuntime: _validate_backend(manifest) specs = [] if manifest.backend.type == "mcp" else self._load_tools(root) + command_specs = self._load_commands(root) + settings_definition = self._load_settings(root) if manifest.backend.type != "mcp": declared = set(manifest.contributes.tools) actual = {spec.name for spec in specs} @@ -305,6 +340,47 @@ class PluginRuntime: f"Tool permission is not declared by Plugin: {spec.permission}", details={"tool": spec.name, "permission": spec.permission}, ) + declared_commands = set(manifest.contributes.commands) + actual_commands = {spec.command_id for spec in command_specs} + if ( + declared_commands != actual_commands + or len(manifest.contributes.commands) != len(declared_commands) + or len(command_specs) != len(actual_commands) + ): + raise ExtensionError( + "PLUGIN_CONTRIBUTION_INVALID", + "plugin.yaml command contributions must exactly match commands.yaml", + details={ + "declared": sorted(declared_commands), + "actual": sorted(actual_commands), + }, + ) + for spec in command_specs: + validate_command_spec(manifest.plugin_id, spec) + if spec.permission and spec.permission not in manifest.permissions: + raise ExtensionError( + "PLUGIN_PERMISSION_UNDECLARED", + f"Command permission is not declared by Plugin: {spec.permission}", + details={"command": spec.command_id, "permission": spec.permission}, + ) + declared_sections = set(manifest.contributes.settings_sections) + actual_sections = ( + {settings_definition.section_id} if settings_definition is not None else set() + ) + if ( + declared_sections != actual_sections + or len(manifest.contributes.settings_sections) != len(declared_sections) + ): + raise ExtensionError( + "PLUGIN_CONTRIBUTION_INVALID", + "plugin.yaml settings contributions must exactly match settings.yaml", + details={ + "declared": sorted(declared_sections), + "actual": sorted(actual_sections), + }, + ) + if settings_definition is not None: + validate_settings_definition(manifest.plugin_id, settings_definition) record = _PluginRecord( plugin=Plugin( @@ -316,8 +392,11 @@ class PluginRuntime: ), ), tools=specs, + commands=command_specs, + settings_definition=settings_definition, package_path=root, registered_tools=[], + registered_commands=[], mcp_remote_names={}, ) self._records[manifest.plugin_id] = record @@ -368,6 +447,16 @@ class PluginRuntime: status_code=409, details={"plugin_id": plugin_id, "tools": conflicts}, ) + command_conflicts = [ + spec.command_id for spec in record.commands if self.commands.contains(spec.command_id) + ] + if command_conflicts: + raise ExtensionError( + "PLUGIN_COMMAND_CONFLICT", + "Plugin commands are already registered.", + status_code=409, + details={"plugin_id": plugin_id, "commands": command_conflicts}, + ) record.plugin.status = PluginStatus.starting try: if record.plugin.manifest.backend.type == "mcp": @@ -405,11 +494,36 @@ class PluginRuntime: executor, ) record.registered_tools.append(spec.name) + for spec in record.commands: + + async def command_executor( + arguments: dict[str, Any], + context: dict[str, Any], + _spec: PluginCommandSpec = spec, + _record: _PluginRecord = record, + ) -> PluginCommandEffect: + settings = ( + self.settings.get( + _record.plugin.manifest.plugin_id, + _record.settings_definition, + ).values + if _record.settings_definition is not None + else {} + ) + return await self.host.execute_command( + _spec.handler, arguments, context, settings + ) + + self.commands.register(plugin_id, spec, command_executor) + record.registered_commands.append(spec.command_id) except Exception as exc: # 注册过程必须具备回滚语义，防止半启用插件污染全局工具表。 for name in record.registered_tools: self.registry.unregister(name) record.registered_tools.clear() + for command_id in record.registered_commands: + self.commands.unregister(command_id) + record.registered_commands.clear() record.mcp_remote_names.clear() self.mcp.stop(plugin_id) record.plugin.status = PluginStatus.error @@ -468,6 +582,9 @@ class PluginRuntime: for name in record.registered_tools: self.registry.unregister(name) record.registered_tools.clear() + for command_id in record.registered_commands: + self.commands.unregister(command_id) + record.registered_commands.clear() record.mcp_remote_names.clear() if record.plugin.manifest.backend.type == "mcp": self.mcp.stop(plugin_id) @@ -479,6 +596,43 @@ class PluginRuntime: record = self._record(plugin_id) return self.mcp.status(plugin_id, record.plugin.manifest.backend) + def list_commands( + self, location: PluginCommandLocation | None = None + ) -> list[PluginCommand]: + return self.commands.list(location) + + async def execute_command( + self, + command_id: str, + arguments: dict[str, Any], + context: PluginCommandContext, + ) -> PluginCommandResult: + return await self.commands.execute(command_id, arguments, context) + + def get_settings(self, plugin_id: str) -> PluginSettingsSchema: + record = self._record(plugin_id) + definition = self._settings_definition(record) + return self.settings.get(plugin_id, definition) + + def update_settings( + self, plugin_id: str, schema_version: int, values: dict[str, Any] + ) -> PluginSettingsSchema: + record = self._record(plugin_id) + definition = self._settings_definition(record) + return self.settings.update(plugin_id, definition, schema_version, values) + + def put_setting_secret( + self, plugin_id: str, key: str, secret: str + ) -> PluginSecretStatus: + record = self._record(plugin_id) + definition = self._settings_definition(record) + return self.settings.put_secret(plugin_id, definition, key, secret) + + def delete_setting_secret(self, plugin_id: str, key: str) -> PluginSecretStatus: + record = self._record(plugin_id) + definition = self._settings_definition(record) + return self.settings.delete_secret(plugin_id, definition, key) + def restart_host(self, plugin_id: str) -> PluginHostStatus: with self._lock: return self._restart_host(plugin_id) @@ -506,6 +660,9 @@ class PluginRuntime: for name in record.registered_tools: self.registry.unregister(name) record.registered_tools.clear() + for command_id in record.registered_commands: + self.commands.unregister(command_id) + record.registered_commands.clear() record.mcp_remote_names.clear() self.mcp.stop(plugin_id) record.plugin.enabled = False @@ -567,6 +724,9 @@ class PluginRuntime: for name in record.registered_tools: self.registry.unregister(name) record.registered_tools.clear() + for command_id in record.registered_commands: + self.commands.unregister(command_id) + record.registered_commands.clear() record.mcp_remote_names.clear() record.plugin.enabled = False record.plugin.status = PluginStatus.error @@ -594,6 +754,7 @@ class PluginRuntime: # stop 只结束本次进程并保留状态供故障诊断；真正卸载时必须连同 # 历史状态一起遗忘，避免同 ID 重装继承旧协商信息。 self.mcp.remove(plugin_id) + self.settings.remove_plugin(plugin_id) del self._records[plugin_id] def _record(self, plugin_id: str) -> _PluginRecord: @@ -615,6 +776,46 @@ class PluginRuntime: except ValidationError as exc: raise _manifest_error("plugin tool", exc) from exc + @staticmethod + def _load_commands(root: Path) -> list[PluginCommandSpec]: + path = root / "commands.yaml" + if not path.exists(): + return [] + raw = _read_yaml(path) + try: + return [ + PluginCommandSpec.model_validate(item) + for item in raw.get("commands", []) + ] + except ValidationError as exc: + raise _manifest_error("plugin command", exc) from exc + + @staticmethod + def _load_settings(root: Path) -> PluginSettingsDefinition | None: + path = root / "settings.yaml" + if not path.exists(): + return None + raw = _read_yaml(path) + try: + return PluginSettingsDefinition.model_validate(raw) + except ValidationError as exc: + raise ExtensionError( + "PLUGIN_SETTINGS_SCHEMA_INVALID", + "Invalid Plugin settings schema.", + details={"errors": exc.errors(include_url=False)}, + ) from exc + + @staticmethod + def _settings_definition(record: _PluginRecord) -> PluginSettingsDefinition: + if record.settings_definition is None: + raise ExtensionError( + "PLUGIN_SETTINGS_NOT_FOUND", + "Plugin does not contribute a Settings section.", + status_code=404, + details={"plugin_id": record.plugin.manifest.plugin_id}, + ) + return record.settings_definition + def _package_dir(package_path: str | Path) -> Path: root = Path(package_path).expanduser().resolve() diff --git a/backend/app/routes.py b/backend/app/routes.py index 201973e..98a5f94 100644 --- a/backend/app/routes.py +++ b/backend/app/routes.py @@ -33,9 +33,17 @@ from app.contracts import ( PageMeta, PermissionDecisionRequest, Plugin, + PluginCommandExecuteRequest, + PluginCommandListResponse, + PluginCommandLocation, + PluginCommandResult, PluginHostStatus, PluginListResponse, PluginPermissionGrantRequest, + PluginSecretStatus, + PluginSecretWriteRequest, + PluginSettingsSchema, + PluginSettingsUpdateRequest, ProviderConfig, ProviderCreateRequest, ProviderListResponse, @@ -559,6 +567,86 @@ async def uninstall_plugin(plugin_id: str) -> OperationResponse: return OperationResponse(status="completed", resource_id=plugin_id, message="uninstalled") +# Plugin Command / Settings Contributions +@router.get( + "/plugin-contributions/commands", + response_model=PluginCommandListResponse, + tags=["Plugins"], +) +async def list_plugin_commands( + location: PluginCommandLocation | None = Query(default=None), +) -> PluginCommandListResponse: + return PluginCommandListResponse(items=container.plugins.list_commands(location)) + + +@router.post( + "/plugin-contributions/commands/{command_id}/execute", + response_model=PluginCommandResult, + tags=["Plugins"], +) +async def execute_plugin_command( + command_id: str, request: PluginCommandExecuteRequest +) -> PluginCommandResult: + try: + return await container.plugins.execute_command( + command_id, request.arguments, request.context + ) + except ExtensionError as exc: + raise ApiError(exc.status_code, exc.code, exc.message, exc.details) from exc + + +@router.get( + "/plugins/{plugin_id}/settings", + response_model=PluginSettingsSchema, + tags=["Plugins"], +) +async def get_plugin_settings(plugin_id: str) -> PluginSettingsSchema: + return extension_call(lambda: container.plugins.get_settings(plugin_id)) + + +@router.put( + "/plugins/{plugin_id}/settings", + response_model=PluginSettingsSchema, + tags=["Plugins"], +) +async def update_plugin_settings( + plugin_id: str, request: PluginSettingsUpdateRequest +) -> PluginSettingsSchema: + return extension_call( + lambda: container.plugins.update_settings( + plugin_id, request.schema_version, request.values + ) + ) + + +@router.put( + "/plugins/{plugin_id}/settings/{key}/secret", + response_model=PluginSecretStatus, + tags=["Plugins"], +) +async def put_plugin_setting_secret( + plugin_id: str, key: str, request: PluginSecretWriteRequest +) -> PluginSecretStatus: + return extension_call( + lambda: container.plugins.put_setting_secret( + plugin_id, key, request.secret.get_secret_value() + ) + ) + + +@router.delete( + "/plugins/{plugin_id}/settings/{key}/secret", + response_model=PluginSecretStatus, + tags=["Plugins"], +) +async def delete_plugin_setting_secret( + plugin_id: str, key: str +) -> PluginSecretStatus: + return extension_call( + lambda: container.plugins.delete_setting_secret(plugin_id, key) + ) + + # Providers @router.get( "/credentials/{credential_id}", diff --git a/backend/extensions/plugins/text-tools/commands.yaml b/backend/extensions/plugins/text-tools/commands.yaml new file mode 100644 index 0000000..611b516 --- /dev/null +++ b/backend/extensions/plugins/text-tools/commands.yaml @@ -0,0 +1,19 @@ +commands: + - command_id: text-tools.uppercase-selection + title: 转为大写 + description: 将当前选区或传入文本转换为大写并显示通知。 + icon: edit + locations: + - command_palette + - context_menu + when: + - editor.has_selection + context: + - selection + handler: uppercase_selection + parameters: + type: object + properties: + text: + type: string + additionalProperties: false diff --git a/backend/extensions/plugins/text-tools/plugin.yaml b/backend/extensions/plugins/text-tools/plugin.yaml index 4f70c0f..272d05f 100644 --- a/backend/extensions/plugins/text-tools/plugin.yaml +++ b/backend/extensions/plugins/text-tools/plugin.yaml @@ -6,6 +6,10 @@ permissions: [] contributes: tools: - text.uppercase + commands: + - text-tools.uppercase-selection + settings_sections: + - text-tools.general backend: type: internal_rpc transport: none diff --git a/backend/extensions/plugins/text-tools/settings.yaml b/backend/extensions/plugins/text-tools/settings.yaml new file mode 100644 index 0000000..171ef27 --- /dev/null +++ b/backend/extensions/plugins/text-tools/settings.yaml @@ -0,0 +1,31 @@ +section_id: text-tools.general +schema_version: 1 +fields: + - key: result_limit + label: 结果字符数 + description: Command 通知中最多保留的字符数。 + type: number + required: true + default: 100 + minimum: 1 + maximum: 1000 + - key: label_prefix + label: 标签前缀 + type: string + default: "" + - key: output_style + label: 输出样式 + type: select + default: notification + options: + - notification + - compact + - key: enabled_hint + label: 显示提示 + type: boolean + default: true + - key: api_key + label: API Key + description: Secret 示例字段；普通 Settings API 永不返回明文。 + type: secret + required: false diff --git a/backend/tests/test_api.py b/backend/tests/test_api.py index e76a1e8..3d5d2d5 100644 --- a/backend/tests/test_api.py +++ b/backend/tests/test_api.py @@ -95,6 +95,10 @@ def test_openapi_contains_documented_frontend_interfaces() -> None: "/api/plugins/install", "/api/plugins/{plugin_id}/host", "/api/plugins/{plugin_id}/host/restart", + "/api/plugin-contributions/commands", + "/api/plugin-contributions/commands/{command_id}/execute", + "/api/plugins/{plugin_id}/settings", + "/api/plugins/{plugin_id}/settings/{key}/secret", "/api/plugins/{plugin_id}/enable", "/api/plugins/{plugin_id}/disable", "/api/providers/test", diff --git a/backend/tests/test_plugin_contributions.py b/backend/tests/test_plugin_contributions.py new file mode 100644 index 0000000..d152beb --- /dev/null +++ b/backend/tests/test_plugin_contributions.py @@ -0,0 +1,296 @@ +import asyncio +import json +from pathlib import Path + +import pytest + +from app.agent import ToolRegistry +from app.config import BACKEND_DIR, get_settings +from app.container import build_container +from app.contracts import ( + PluginCommandContext, + PluginCommandEffect, + PluginSettingType, +) +from app.extensions import ExtensionError, PluginRuntime +from app.extensions.runtime import DeclarativePluginHost + +TEXT_TOOLS = BACKEND_DIR / "extensions" / "plugins" / "text-tools" + + +def run(coroutine): + return asyncio.run(coroutine) + + +def test_command_list_filter_and_lifecycle() -> None: + container = build_container() + + commands = container.plugins.list_commands() + palette = container.plugins.list_commands(location="command_palette") + + assert [item.command_id for item in commands] == ["text-tools.uppercase-selection"] + assert palette[0].plugin_id == "text-tools" + assert palette[0].icon == "edit" + assert palette[0].when == ["editor.has_selection"] + + container.plugins.disable("text-tools") + assert container.plugins.list_commands() == [] + with pytest.raises(ExtensionError) as exc: + run( + container.plugins.execute_command( + "text-tools.uppercase-selection", + {}, + PluginCommandContext(selection="hello"), + ) + ) + assert exc.value.code == "PLUGIN_COMMAND_NOT_FOUND" + + container.plugins.enable("text-tools") + assert len(container.plugins.list_commands()) == 1 + + +def test_command_executes_with_scoped_context_and_settings() -> None: + container = build_container() + container.plugins.update_settings("text-tools", 1, {"result_limit": 4}) + + result = run( + container.plugins.execute_command( + "text-tools.uppercase-selection", + {}, + PluginCommandContext( + vault_id="default", + note_id="note_private", + file_path="private.md", + selection="abcdef", + ), + ) + ) + + assert result.status == "completed" + assert result.effect.type == "notification" + assert result.effect.payload == {"level": "success", "message": "ABCD"} + + +def test_command_rejects_missing_context_and_invalid_arguments() -> None: + container = build_container() + + with pytest.raises(ExtensionError) as context_error: + run( + container.plugins.execute_command( + "text-tools.uppercase-selection", {}, PluginCommandContext() + ) + ) + assert context_error.value.code == "PLUGIN_COMMAND_CONTEXT_INVALID" + + with pytest.raises(ExtensionError) as argument_error: + run( + container.plugins.execute_command( + "text-tools.uppercase-selection", + {"unknown": True}, + PluginCommandContext(selection="hello"), + ) + ) + assert argument_error.value.code == "PLUGIN_COMMAND_ARGUMENT_INVALID" + + audit = container.plugins.commands.audit_events() + assert [event.error_code for event in audit[-2:]] == [ + "PLUGIN_COMMAND_CONTEXT_INVALID", + "PLUGIN_COMMAND_ARGUMENT_INVALID", + ] + # 审计事件不得携带参数、正文选区或返回 effect。 + assert "hello" not in repr(audit) + + +def test_command_only_receives_declared_context() -> None: + class CapturingHost(DeclarativePluginHost): + def __init__(self) -> None: + self.context = None + + async def execute_command(self, handler, arguments, context, settings): + self.context = context + return PluginCommandEffect(type="none") + + host = CapturingHost() + runtime = PluginRuntime(ToolRegistry(), host=host) + runtime.install(TEXT_TOOLS) + runtime.enable("text-tools") + + run( + runtime.execute_command( + "text-tools.uppercase-selection", + {}, + PluginCommandContext( + vault_id="default", note_id="note_private", selection="visible" + ), + ) + ) + + assert host.context == {"selection": "visible"} + + +def test_settings_schema_contains_defaults_and_hides_secret() -> None: + container = build_container() + + schema = container.plugins.get_settings("text-tools") + by_key = {field.key: field for field in schema.fields} + + assert schema.schema_version == 1 + assert schema.values == { + "result_limit": 100, + "label_prefix": "", + "output_style": "notification", + "enabled_hint": True, + } + assert "api_key" not in schema.values + assert schema.secrets["api_key"].configured is False + assert by_key["api_key"].type == PluginSettingType.secret + + +def test_settings_update_validates_version_type_bounds_and_secret_boundary() -> None: + container = build_container() + + updated = container.plugins.update_settings( + "text-tools", 1, {"result_limit": 20, "output_style": "compact"} + ) + assert updated.values["result_limit"] == 20 + assert updated.values["output_style"] == "compact" + + cases = [ + (2, {}, "PLUGIN_SETTINGS_VERSION_CONFLICT"), + (1, {"result_limit": 0}, "PLUGIN_SETTINGS_FIELD_INVALID"), + (1, {"enabled_hint": "yes"}, "PLUGIN_SETTINGS_FIELD_INVALID"), + (1, {"output_style": "unknown"}, "PLUGIN_SETTINGS_FIELD_INVALID"), + (1, {"api_key": "plaintext"}, "PLUGIN_SETTINGS_FIELD_INVALID"), + (1, {"unknown": True}, "PLUGIN_SETTINGS_FIELD_INVALID"), + ] + for version, values, code in cases: + with pytest.raises(ExtensionError) as exc: + container.plugins.update_settings("text-tools", version, values) + assert exc.value.code == code + + +def test_secret_roundtrip_never_enters_plain_settings_storage() -> None: + container = build_container() + plaintext = "stage-d-secret-value" + + status = container.plugins.put_setting_secret("text-tools", "api_key", plaintext) + schema = container.plugins.get_settings("text-tools") + settings_path = get_settings().data_dir / "plugins" / "settings.json" + credentials_path = get_settings().data_dir / "credentials" / "credentials.json" + + assert status.configured is True + assert schema.secrets["api_key"].configured is True + assert "api_key" not in schema.values + assert plaintext not in settings_path.read_text(encoding="utf-8") + assert plaintext not in credentials_path.read_text(encoding="utf-8") + assert container.credentials.resolve("plugin.text-tools.api_key") == plaintext + + deleted = container.plugins.delete_setting_secret("text-tools", "api_key") + assert deleted.configured is False + assert container.credentials.resolve("plugin.text-tools.api_key") is None + + +def test_uninstall_removes_plugin_settings_and_secret_namespace() -> None: + container = build_container() + container.plugins.update_settings("text-tools", 1, {"result_limit": 12}) + container.plugins.put_setting_secret("text-tools", "api_key", "temporary") + + container.plugins.uninstall("text-tools") + + settings_path = get_settings().data_dir / "plugins" / "settings.json" + stored = json.loads(settings_path.read_text(encoding="utf-8")) + assert "text-tools" not in stored + assert container.credentials.resolve("plugin.text-tools.api_key") is None + + +def test_invalid_command_and_settings_manifest_are_rejected(tmp_path: Path) -> None: + invalid_command = tmp_path / "invalid-command" + invalid_command.mkdir() + (invalid_command / "plugin.yaml").write_text( + """ +id: invalid-command +name: Invalid Command +version: 1.0.0 +contributes: + commands: [other.run] +""".strip(), + encoding="utf-8", + ) + (invalid_command / "commands.yaml").write_text( + """ +commands: + - command_id: other.run + title: Invalid + locations: [command_palette] + handler: echo +""".strip(), + encoding="utf-8", + ) + + invalid_settings = tmp_path / "invalid-settings" + invalid_settings.mkdir() + (invalid_settings / "plugin.yaml").write_text( + """ +id: invalid-settings +name: Invalid Settings +version: 1.0.0 +contributes: + settings_sections: [invalid-settings.general] +""".strip(), + encoding="utf-8", + ) + (invalid_settings / "settings.yaml").write_text( + """ +section_id: invalid-settings.general +schema_version: 1 +fields: + - key: token + label: Token + type: secret + default: leaked-default +""".strip(), + encoding="utf-8", + ) + + runtime = PluginRuntime(ToolRegistry()) + with pytest.raises(ExtensionError) as command_error: + runtime.install(invalid_command) + assert command_error.value.code == "PLUGIN_COMMAND_INVALID" + + with pytest.raises(ExtensionError) as settings_error: + runtime.install(invalid_settings) + assert settings_error.value.code == "PLUGIN_SETTINGS_SCHEMA_INVALID" + + +def test_settings_missing_and_secret_field_errors_are_stable() -> None: + container = build_container() + + with pytest.raises(ExtensionError) as missing: + container.plugins.get_settings("does-not-exist") + assert missing.value.code == "PLUGIN_NOT_FOUND" + + with pytest.raises(ExtensionError) as field: + container.plugins.put_setting_secret("text-tools", "result_limit", "secret") + assert field.value.code == "PLUGIN_SECRET_FIELD_NOT_FOUND" + + with pytest.raises(ExtensionError) as empty: + container.plugins.put_setting_secret("text-tools", "api_key", "") + assert empty.value.code == "PLUGIN_SECRET_VALUE_INVALID" + + +def test_corrupted_plugin_settings_namespace_returns_stable_error() -> None: + container = build_container() + settings_path = get_settings().data_dir / "plugins" / "settings.json" + settings_path.parent.mkdir(parents=True, exist_ok=True) + settings_path.write_text('{"text-tools": []}', encoding="utf-8") + + with pytest.raises(ExtensionError) as exc: + container.plugins.get_settings("text-tools") + + assert exc.value.code == "PLUGIN_STORAGE_ERROR" + + with pytest.raises(ExtensionError) as secret_exc: + container.plugins.put_setting_secret("text-tools", "api_key", "must-not-orphan") + + assert secret_exc.value.code == "PLUGIN_STORAGE_ERROR" + assert container.credentials.resolve("plugin.text-tools.api_key") is None diff --git a/frontend/src/contracts/index.ts b/frontend/src/contracts/index.ts index 8891885..b7a5e0a 100644 --- a/frontend/src/contracts/index.ts +++ b/frontend/src/contracts/index.ts @@ -271,6 +271,66 @@ export interface PluginHostStatus { error?: string | null } +export type PluginCommandLocation = 'command_palette' | 'context_menu' | 'toolbar' + +export interface PluginCommand { + command_id: string + plugin_id: string + title: string + description: string + icon?: string | null + locations: PluginCommandLocation[] + when: string[] + parameters: Record + enabled: boolean +} + +export interface PluginCommandContext { + vault_id?: string | null + note_id?: string | null + file_path?: string | null + selection?: string | null +} + +export interface PluginCommandEffect { + type: 'none' | 'notification' | 'navigate' | 'refresh' | 'job' + payload: Record +} + +export interface PluginCommandResult { + command_id: string + status: 'completed' + effect: PluginCommandEffect +} + +export type PluginSettingType = 'string' | 'number' | 'boolean' | 'select' | 'secret' + +export interface PluginSettingField { + key: string + label: string + description: string + type: PluginSettingType + required: boolean + default?: unknown + minimum?: number | null + maximum?: number | null + options: string[] +} + +export interface PluginSettingsSchema { + plugin_id: string + schema_version: number + fields: PluginSettingField[] + values: Record + secrets: Record +} + +export interface PluginSecretStatus { + plugin_id: string + key: string + configured: boolean +} + export interface PluginContribution { type: 'tool' | 'command' | 'importer' | 'exporter' | 'sidebar_panel' | 'settings_section' id: string diff --git a/frontend/src/services/pluginService.spec.ts b/frontend/src/services/pluginService.spec.ts new file mode 100644 index 0000000..612779a --- /dev/null +++ b/frontend/src/services/pluginService.spec.ts @@ -0,0 +1,84 @@ +// @vitest-environment happy-dom +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import * as pluginService from './pluginService' + +function jsonResponse(body: unknown) { + return new Response(JSON.stringify(body), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) +} + +beforeEach(() => { + vi.stubGlobal('fetch', vi.fn()) +}) + +afterEach(() => { + vi.unstubAllGlobals() + vi.restoreAllMocks() +}) + +describe('pluginService contribution adapter', () => { + it('lists and executes Plugin Commands with scoped wire fields', async () => { + const fetchMock = vi.mocked(fetch) + fetchMock + .mockResolvedValueOnce(jsonResponse({ items: [{ command_id: 'text-tools.uppercase-selection' }] })) + .mockResolvedValueOnce(jsonResponse({ + command_id: 'text-tools.uppercase-selection', + status: 'completed', + effect: { type: 'notification', payload: { message: 'HELLO' } }, + })) + + const commands = await pluginService.listPluginCommands('command_palette') + const result = await pluginService.executePluginCommand( + 'text-tools.uppercase-selection', + {}, + { note_id: 'note-1', selection: 'hello' }, + ) + + expect(commands[0].command_id).toBe('text-tools.uppercase-selection') + expect(result.effect.payload.message).toBe('HELLO') + expect(fetchMock.mock.calls[0][0]).toBe( + '/api/plugin-contributions/commands?location=command_palette', + ) + expect(JSON.parse(String(fetchMock.mock.calls[1][1]?.body))).toEqual({ + arguments: {}, + context: { note_id: 'note-1', selection: 'hello' }, + }) + }) + + it('uses separate Settings and Secret endpoints', async () => { + const fetchMock = vi.mocked(fetch) + fetchMock + .mockResolvedValueOnce(jsonResponse({ + plugin_id: 'text-tools', schema_version: 1, fields: [], + values: { result_limit: 10 }, secrets: { api_key: { configured: false } }, + })) + .mockResolvedValueOnce(jsonResponse({ + plugin_id: 'text-tools', schema_version: 1, fields: [], + values: { result_limit: 20 }, secrets: { api_key: { configured: false } }, + })) + .mockResolvedValueOnce(jsonResponse({ plugin_id: 'text-tools', key: 'api_key', configured: true })) + .mockResolvedValueOnce(jsonResponse({ plugin_id: 'text-tools', key: 'api_key', configured: false })) + + await pluginService.getPluginSettings('text-tools') + await pluginService.updatePluginSettings('text-tools', 1, { result_limit: 20 }) + await pluginService.putPluginSecret('text-tools', 'api_key', 'request-only-secret') + await pluginService.deletePluginSecret('text-tools', 'api_key') + + expect(fetchMock.mock.calls.map(([url]) => url)).toEqual([ + '/api/plugins/text-tools/settings', + '/api/plugins/text-tools/settings', + '/api/plugins/text-tools/settings/api_key/secret', + '/api/plugins/text-tools/settings/api_key/secret', + ]) + expect(JSON.parse(String(fetchMock.mock.calls[1][1]?.body))).toEqual({ + schema_version: 1, + values: { result_limit: 20 }, + }) + expect(JSON.parse(String(fetchMock.mock.calls[2][1]?.body))).toEqual({ + secret: 'request-only-secret', + }) + expect(fetchMock.mock.calls[3][1]?.method).toBe('DELETE') + }) +}) diff --git a/frontend/src/services/pluginService.ts b/frontend/src/services/pluginService.ts index 48b6a28..e9ec869 100644 --- a/frontend/src/services/pluginService.ts +++ b/frontend/src/services/pluginService.ts @@ -1,5 +1,17 @@ import apiClient from './apiClient' -import type { ApiPlugin, OperationResponse, Plugin, PluginContribution, PluginHostStatus } from '@/contracts' +import type { + ApiPlugin, + OperationResponse, + Plugin, + PluginCommand, + PluginCommandContext, + PluginCommandLocation, + PluginCommandResult, + PluginContribution, + PluginHostStatus, + PluginSecretStatus, + PluginSettingsSchema, +} from '@/contracts' function toPlugin(plugin: ApiPlugin): Plugin { const { manifest } = plugin @@ -62,6 +74,55 @@ export async function restartPluginHost(pluginId: string): Promise { + const query = location ? `?location=${encodeURIComponent(location)}` : '' + const response = await apiClient.get<{ items: PluginCommand[] }>(`/api/plugin-contributions/commands${query}`) + return response.items +} + +export async function executePluginCommand( + commandId: string, + argumentsValue: Record = {}, + context: PluginCommandContext = {}, +): Promise { + return apiClient.post(`/api/plugin-contributions/commands/${encodeURIComponent(commandId)}/execute`, { + arguments: argumentsValue, + context, + }) +} + +export async function getPluginSettings(pluginId: string): Promise { + return apiClient.get(`/api/plugins/${encodeURIComponent(pluginId)}/settings`) +} + +export async function updatePluginSettings( + pluginId: string, + schemaVersion: number, + values: Record, +): Promise { + return apiClient.put(`/api/plugins/${encodeURIComponent(pluginId)}/settings`, { + schema_version: schemaVersion, + values, + }) +} + +export async function putPluginSecret( + pluginId: string, + key: string, + secret: string, +): Promise { + return apiClient.put( + `/api/plugins/${encodeURIComponent(pluginId)}/settings/${encodeURIComponent(key)}/secret`, + { secret }, + ) +} + +export async function deletePluginSecret(pluginId: string, key: string): Promise { + return apiClient.delete( + `/api/plugins/${encodeURIComponent(pluginId)}/settings/${encodeURIComponent(key)}/secret`, + ) +} + export async function uninstallPlugin(pluginId: string): Promise { return apiClient.delete(`/api/plugins/${pluginId}`) } From c1bac00d12da4eb2f354810715f80787c4d00540 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 14:08:47 +0800 Subject: [PATCH 02/13] =?UTF-8?q?fix(extension):=20=E6=94=B6=E7=B4=A7?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=AF=86=E9=92=A5=E4=B8=8E=E5=91=BD=E4=BB=A4?= =?UTF-8?q?=E6=B8=85=E5=8D=95=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- backend/README.md | 2 +- backend/app/extensions/contributions.py | 8 ++ backend/app/extensions/runtime.py | 79 +++++++++++++++- backend/app/providers/credentials.py | 21 +++++ backend/app/providers/factory.py | 6 +- backend/app/routes.py | 19 +++- backend/tests/test_credentials.py | 32 ++++++- backend/tests/test_plugin_contributions.py | 103 ++++++++++++++++++++- 9 files changed, 263 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index aa77036..117f3aa 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 103 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 107 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 diff --git a/backend/README.md b/backend/README.md index b1a3bec..915a897 100644 --- a/backend/README.md +++ b/backend/README.md @@ -23,7 +23,7 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 103 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。 +当前基线为 107 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 diff --git a/backend/app/extensions/contributions.py b/backend/app/extensions/contributions.py index 6a17a38..6d2790d 100644 --- a/backend/app/extensions/contributions.py +++ b/backend/app/extensions/contributions.py @@ -73,6 +73,7 @@ class PluginCommandSpec(BaseModel): } ) permission: str | None = None + secrets: list[str] = Field(default_factory=list) handler: Literal["echo", "uppercase_selection"] timeout_seconds: int = Field(default=30, ge=1, le=120) @@ -81,6 +82,7 @@ CommandExecutor = Callable[ [dict[str, Any], dict[str, Any]], PluginCommandEffect | Awaitable[PluginCommandEffect], ] +PluginSecretResolver = Callable[[str], str | None] @dataclass(slots=True) @@ -656,6 +658,12 @@ def validate_command_spec(plugin_id: str, spec: PluginCommandSpec) -> None: "PLUGIN_COMMAND_INVALID", "Plugin command when/context entries must be unique.", ) + if len(spec.secrets) != len(set(spec.secrets)): + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command Secret entries must be unique.", + details={"command_id": spec.command_id}, + ) unknown_when = sorted(set(spec.when) - _WHEN_TOKENS) if unknown_when: raise ExtensionError( diff --git a/backend/app/extensions/runtime.py b/backend/app/extensions/runtime.py index 054424e..08d9321 100644 --- a/backend/app/extensions/runtime.py +++ b/backend/app/extensions/runtime.py @@ -24,6 +24,7 @@ from app.contracts import ( PluginManifest, PluginHostStatus, PluginSecretStatus, + PluginSettingType, PluginSettingsSchema, PluginStatus, RetrievalConfig, @@ -35,6 +36,7 @@ from app.contracts import ( from app.extensions.contributions import ( CommandRegistry, PluginCommandSpec, + PluginSecretResolver, PluginSettingsDefinition, PluginSettingsStore, validate_command_spec, @@ -245,6 +247,7 @@ class DeclarativePluginHost: arguments: dict[str, Any], context: dict[str, Any], settings: dict[str, Any], + resolve_secret: PluginSecretResolver, ) -> PluginCommandEffect: """执行宿主内置的白名单 Command handler，不导入 Plugin Python 代码。""" @@ -381,6 +384,32 @@ class PluginRuntime: ) if settings_definition is not None: validate_settings_definition(manifest.plugin_id, settings_definition) + secret_fields = ( + { + field.key + for field in settings_definition.fields + if field.type == PluginSettingType.secret + } + if settings_definition is not None + else set() + ) + for spec in command_specs: + unknown_secrets = sorted(set(spec.secrets) - secret_fields) + if unknown_secrets: + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "Plugin command references undeclared Secret settings.", + details={ + "command_id": spec.command_id, + "secrets": unknown_secrets, + }, + ) + if spec.secrets and "secrets.use" not in manifest.permissions: + raise ExtensionError( + "PLUGIN_PERMISSION_UNDECLARED", + "Commands using Secret settings require the secrets.use permission.", + details={"command_id": spec.command_id}, + ) record = _PluginRecord( plugin=Plugin( @@ -502,6 +531,16 @@ class PluginRuntime: _spec: PluginCommandSpec = spec, _record: _PluginRecord = record, ) -> PluginCommandEffect: + if ( + not _record.plugin.enabled + or _record.plugin.status != PluginStatus.ready + ): + raise ExtensionError( + "PLUGIN_COMMAND_NOT_FOUND", + "Plugin command is not available while its Plugin is inactive.", + status_code=404, + details={"command_id": _spec.command_id}, + ) settings = ( self.settings.get( _record.plugin.manifest.plugin_id, @@ -510,8 +549,38 @@ class PluginRuntime: if _record.settings_definition is not None else {} ) + def resolve_secret(key: str) -> str | None: + if key not in _spec.secrets: + raise ExtensionError( + "PLUGIN_SECRET_ACCESS_DENIED", + "Command cannot access an undeclared Plugin Secret.", + status_code=403, + details={ + "command_id": _spec.command_id, + "key": key, + }, + ) + if "secrets.use" not in _record.plugin.granted_permissions: + raise ExtensionError( + "PLUGIN_SECRET_ACCESS_DENIED", + "Plugin no longer has permission to access Secret settings.", + status_code=403, + details={"command_id": _spec.command_id, "key": key}, + ) + if _record.settings_definition is None: + return None + return self.settings.resolve_secret( + _record.plugin.manifest.plugin_id, + _record.settings_definition, + key, + ) + return await self.host.execute_command( - _spec.handler, arguments, context, settings + _spec.handler, + arguments, + context, + settings, + resolve_secret, ) self.commands.register(plugin_id, spec, command_executor) @@ -782,10 +851,16 @@ class PluginRuntime: if not path.exists(): return [] raw = _read_yaml(path) + items = raw.get("commands", []) + if not isinstance(items, list): + raise ExtensionError( + "EXTENSION_MANIFEST_INVALID", + "Invalid plugin command manifest: commands must be an array.", + ) try: return [ PluginCommandSpec.model_validate(item) - for item in raw.get("commands", []) + for item in items ] except ValidationError as exc: raise _manifest_error("plugin command", exc) from exc diff --git a/backend/app/providers/credentials.py b/backend/app/providers/credentials.py index 19e83c3..ae1cca6 100644 --- a/backend/app/providers/credentials.py +++ b/backend/app/providers/credentials.py @@ -13,6 +13,7 @@ from app.config import get_settings _CREDENTIAL_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$") +_PLUGIN_CREDENTIAL_PREFIX = "plugin." class CredentialStoreError(RuntimeError): @@ -23,6 +24,15 @@ class CredentialResolver(Protocol): def resolve(self, credential_id: str | None) -> str | None: ... +def validate_provider_credential_id(credential_id: str | None) -> None: + """阻止 Provider 和通用凭据 API 跨入 Plugin 私有命名空间。""" + + if credential_id and credential_id.casefold().startswith( + _PLUGIN_CREDENTIAL_PREFIX + ): + raise CredentialStoreError("Credential namespace is reserved for Plugin settings.") + + class EnvironmentCredentialResolver: """解析由桌面 Host 注入 Sidecar 进程的临时凭证上下文。""" @@ -170,3 +180,14 @@ class ChainedCredentialResolver: if value: return value return None + + +class ProviderCredentialResolver: + """Provider 专用防御层，避免配置绕过 HTTP 校验读取 Plugin Secret。""" + + def __init__(self, delegate: CredentialResolver) -> None: + self._delegate = delegate + + def resolve(self, credential_id: str | None) -> str | None: + validate_provider_credential_id(credential_id) + return self._delegate.resolve(credential_id) diff --git a/backend/app/providers/factory.py b/backend/app/providers/factory.py index 38d1687..84f08a7 100644 --- a/backend/app/providers/factory.py +++ b/backend/app/providers/factory.py @@ -1,6 +1,6 @@ from app.contracts import ModelCapability, ProviderConfig, ProviderPreset, ProviderType from app.providers.base import ModelProvider -from app.providers.credentials import CredentialResolver +from app.providers.credentials import CredentialResolver, ProviderCredentialResolver from app.providers.ollama import OllamaProvider from app.providers.openai_compatible import OpenAICompatibleProvider @@ -11,7 +11,9 @@ class UnsupportedProviderError(ValueError): class ProviderFactory: def __init__(self, credentials: CredentialResolver) -> None: - self.credentials = credentials + # ProviderFactory 是所有可配置 Provider 的创建边界，在此统一禁止 + # Provider 借用 Plugin Secret 引用，避免调用方漏包安全 Resolver。 + self.credentials = ProviderCredentialResolver(credentials) def build(self, config: ProviderConfig) -> ModelProvider: if config.provider_type in { diff --git a/backend/app/routes.py b/backend/app/routes.py index 98a5f94..962bec7 100644 --- a/backend/app/routes.py +++ b/backend/app/routes.py @@ -75,7 +75,10 @@ from app.extensions import ExtensionError from app.providers.registry import ProviderNotFoundError from app.providers.factory import UnsupportedProviderError from app.providers.base import ProviderError -from app.providers.credentials import CredentialStoreError +from app.providers.credentials import ( + CredentialStoreError, + validate_provider_credential_id, +) from app.retrieval.engine import engine from app.services import ( index_service, @@ -92,6 +95,13 @@ def utc_now() -> datetime: return datetime.now(timezone.utc) +def validate_public_credential_id(credential_id: str | None) -> None: + try: + validate_provider_credential_id(credential_id) + except CredentialStoreError as exc: + raise ApiError(422, "CREDENTIAL_NAMESPACE_RESERVED", str(exc)) from exc + + def as_sse(event: str, payload: str, *, event_id: int | None = None) -> str: id_line = f"id: {event_id}\n" if event_id is not None else "" return f"{id_line}event: {event}\ndata: {payload}\n\n" @@ -654,6 +664,7 @@ async def delete_plugin_setting_secret( tags=["Providers"], ) async def get_credential_status(credential_id: str) -> CredentialStatus: + validate_public_credential_id(credential_id) try: configured = container.credentials.has(credential_id) except CredentialStoreError as exc: @@ -669,6 +680,7 @@ async def get_credential_status(credential_id: str) -> CredentialStatus: async def put_credential( credential_id: str, request: CredentialWriteRequest ) -> CredentialStatus: + validate_public_credential_id(credential_id) try: container.credentials.put(credential_id, request.api_key.get_secret_value()) except CredentialStoreError as exc: @@ -682,6 +694,7 @@ async def put_credential( tags=["Providers"], ) async def delete_credential(credential_id: str) -> CredentialStatus: + validate_public_credential_id(credential_id) try: container.credentials.delete(credential_id) except CredentialStoreError as exc: @@ -718,6 +731,7 @@ async def get_provider(provider_id: str) -> ProviderConfig: tags=["Providers"], ) async def create_provider(request: ProviderCreateRequest) -> ProviderConfig: + validate_public_credential_id(request.credential_id) config = ProviderConfig( provider_id=f"provider_{uuid4().hex}", provider_type=request.provider_type, @@ -761,6 +775,8 @@ async def update_provider( "name and enabled cannot be null when explicitly provided.", ) updates = {name: getattr(request, name) for name in fields} + if "credential_id" in fields: + validate_public_credential_id(request.credential_id) config = ProviderConfig.model_validate( {**current.model_dump(mode="python"), **updates} ) @@ -820,6 +836,7 @@ async def list_provider_models(provider_id: str) -> ProviderModelsResponse: async def test_provider(request: ProviderTestRequest) -> ProviderTestResponse: registered = configurable_provider_or_404(request.provider_id) if request.credential_context_id: + validate_public_credential_id(request.credential_context_id) temporary_config = registered.config.model_copy( update={"credential_id": request.credential_context_id, "enabled": True} ) diff --git a/backend/tests/test_credentials.py b/backend/tests/test_credentials.py index d985827..37ac388 100644 --- a/backend/tests/test_credentials.py +++ b/backend/tests/test_credentials.py @@ -1,16 +1,20 @@ import asyncio import httpx +import pytest from app.config import get_settings from app.contracts import CredentialWriteRequest +from app.errors import ApiError from app.providers.credentials import ( ChainedCredentialResolver, + CredentialStoreError, EncryptedCredentialStore, EnvironmentCredentialResolver, ) +from app.providers.factory import ProviderFactory from app.providers.openai_compatible import OpenAICompatibleProvider -from app.routes import get_credential_status, put_credential +from app.routes import delete_credential, get_credential_status, put_credential def test_encrypted_credential_store_round_trip_without_plaintext_on_disk() -> None: @@ -72,3 +76,29 @@ def test_saved_credential_takes_precedence_over_environment_fallback(monkeypatch resolver = ChainedCredentialResolver(store, EnvironmentCredentialResolver()) assert resolver.resolve("deepseek") == "saved-key" + + +def test_public_credential_api_rejects_plugin_namespace() -> None: + operations = [ + get_credential_status("plugin.text-tools.api_key"), + put_credential( + "plugin.text-tools.api_key", + CredentialWriteRequest(api_key="must-not-write"), + ), + delete_credential("plugin.text-tools.api_key"), + ] + for operation in operations: + with pytest.raises(ApiError) as exc: + asyncio.run(operation) + assert exc.value.code == "CREDENTIAL_NAMESPACE_RESERVED" + + assert EncryptedCredentialStore().resolve("plugin.text-tools.api_key") is None + + +def test_provider_resolver_cannot_read_plugin_secret() -> None: + store = EncryptedCredentialStore() + store.put("plugin.text-tools.api_key", "private-plugin-secret") + resolver = ProviderFactory(store).credentials + + with pytest.raises(CredentialStoreError, match="reserved for Plugin settings"): + resolver.resolve("plugin.text-tools.api_key") diff --git a/backend/tests/test_plugin_contributions.py b/backend/tests/test_plugin_contributions.py index d152beb..d80bf7f 100644 --- a/backend/tests/test_plugin_contributions.py +++ b/backend/tests/test_plugin_contributions.py @@ -106,7 +106,9 @@ def test_command_only_receives_declared_context() -> None: def __init__(self) -> None: self.context = None - async def execute_command(self, handler, arguments, context, settings): + async def execute_command( + self, handler, arguments, context, settings, resolve_secret + ): self.context = context return PluginCommandEffect(type="none") @@ -128,6 +130,81 @@ def test_command_only_receives_declared_context() -> None: assert host.context == {"selection": "visible"} +def test_command_resolves_only_declared_plugin_secrets(tmp_path: Path) -> None: + class SecretHost(DeclarativePluginHost): + def __init__(self) -> None: + self.secret = None + self.denied_code = None + + async def execute_command( + self, handler, arguments, context, settings, resolve_secret + ): + self.secret = resolve_secret("api_key") + try: + resolve_secret("undeclared") + except ExtensionError as exc: + self.denied_code = exc.code + return PluginCommandEffect(type="none") + + host = SecretHost() + runtime = PluginRuntime(ToolRegistry(), host=host) + package = tmp_path / "secret-command" + package.mkdir() + (package / "plugin.yaml").write_text( + """ +id: secret-command +name: Secret Command +version: 1.0.0 +permissions: [secrets.use] +contributes: + commands: [secret-command.run] + settings_sections: [secret-command.general] +backend: + type: internal_rpc + transport: none +""".strip(), + encoding="utf-8", + ) + (package / "commands.yaml").write_text( + """ +commands: + - command_id: secret-command.run + title: Secret Command + locations: [command_palette] + secrets: [api_key] + handler: echo +""".strip(), + encoding="utf-8", + ) + (package / "settings.yaml").write_text( + """ +section_id: secret-command.general +schema_version: 1 +fields: + - key: api_key + label: API Key + type: secret +""".strip(), + encoding="utf-8", + ) + runtime.install(package) + runtime.set_permissions("secret-command", ["secrets.use"]) + runtime.enable("secret-command") + runtime.put_setting_secret("secret-command", "api_key", "runtime-only-secret") + + run( + runtime.execute_command( + "secret-command.run", + {}, + PluginCommandContext(selection="visible"), + ) + ) + + assert host.secret == "runtime-only-secret" + assert host.denied_code == "PLUGIN_SECRET_ACCESS_DENIED" + assert "runtime-only-secret" not in repr(runtime.commands.audit_events()) + + def test_settings_schema_contains_defaults_and_hides_secret() -> None: container = build_container() @@ -262,6 +339,30 @@ fields: assert settings_error.value.code == "PLUGIN_SETTINGS_SCHEMA_INVALID" +def test_null_command_list_returns_stable_manifest_error(tmp_path: Path) -> None: + package = tmp_path / "null-commands" + package.mkdir() + (package / "plugin.yaml").write_text( + """ +id: null-commands +name: Null Commands +version: 1.0.0 +contributes: + commands: [] +backend: + type: internal_rpc + transport: none +""".strip(), + encoding="utf-8", + ) + (package / "commands.yaml").write_text("commands:\n", encoding="utf-8") + + with pytest.raises(ExtensionError) as exc: + PluginRuntime(ToolRegistry()).install(package) + + assert exc.value.code == "EXTENSION_MANIFEST_INVALID" + + def test_settings_missing_and_secret_field_errors_are_stable() -> None: container = build_container() From cff38158f6ab760f35cace19974cd7624d4fea4f Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 14:52:03 +0800 Subject: [PATCH 03/13] =?UTF-8?q?fix(extension):=20=E5=AE=8C=E6=88=90MCP?= =?UTF-8?q?=E5=91=BD=E4=BB=A4=E7=9B=AE=E6=A0=87=E5=B9=B6=E6=94=B6=E7=B4=A7?= =?UTF-8?q?Schema=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- backend/README.md | 2 +- backend/app/agent/tools.py | 2 + backend/app/extensions/contributions.py | 25 ++++- backend/app/extensions/mcp.py | 10 +- backend/app/extensions/runtime.py | 98 +++++++++++++++++-- backend/app/schema_security.py | 70 +++++++++++++ .../fixtures/mcp-echo/commands.yaml | 20 ++++ .../extensions/fixtures/mcp-echo/plugin.yaml | 7 +- .../extensions/fixtures/mcp-echo/server.py | 36 ++++++- .../fixtures/mcp-echo/settings.yaml | 7 ++ backend/tests/test_extension_core.py | 49 +++++++++- backend/tests/test_plugin_contributions.py | 68 ++++++++++++- backend/tests/test_schema_security.py | 35 +++++++ 14 files changed, 403 insertions(+), 28 deletions(-) create mode 100644 backend/app/schema_security.py create mode 100644 backend/extensions/fixtures/mcp-echo/commands.yaml create mode 100644 backend/extensions/fixtures/mcp-echo/settings.yaml create mode 100644 backend/tests/test_schema_security.py diff --git a/README.md b/README.md index 117f3aa..073e8ea 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 107 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 116 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 diff --git a/backend/README.md b/backend/README.md index 915a897..9d32774 100644 --- a/backend/README.md +++ b/backend/README.md @@ -23,7 +23,7 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 107 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 +当前基线为 116 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 diff --git a/backend/app/agent/tools.py b/backend/app/agent/tools.py index df90158..33c6615 100644 --- a/backend/app/agent/tools.py +++ b/backend/app/agent/tools.py @@ -11,6 +11,7 @@ from jsonschema import Draft202012Validator from jsonschema.exceptions import ValidationError as JsonSchemaValidationError from app.contracts import ToolCall, ToolDefinition, ToolResult +from app.schema_security import reject_external_schema_references ToolExecutor = Callable[[BaseModel, "ToolExecutionContext"], Any | Awaitable[Any]] @@ -54,6 +55,7 @@ class ToolRegistry: arguments_model: type[BaseModel], executor: ToolExecutor, ) -> None: + reject_external_schema_references(definition.parameters) with self._lock: if definition.name in self._tools: raise ValueError(f"Tool already registered: {definition.name}") diff --git a/backend/app/extensions/contributions.py b/backend/app/extensions/contributions.py index 6d2790d..a496db5 100644 --- a/backend/app/extensions/contributions.py +++ b/backend/app/extensions/contributions.py @@ -3,6 +3,7 @@ from __future__ import annotations import asyncio +import hashlib import inspect import json import math @@ -17,7 +18,7 @@ from typing import Any, Awaitable, Callable, Literal from jsonschema import Draft202012Validator from jsonschema.exceptions import SchemaError, ValidationError as JsonSchemaValidationError -from pydantic import BaseModel, ConfigDict, Field +from pydantic import BaseModel, ConfigDict, Field, model_validator from app.config import get_settings from app.contracts import ( @@ -34,6 +35,10 @@ from app.contracts import ( ) from app.extensions.errors import ExtensionError from app.providers.credentials import CredentialStoreError, EncryptedCredentialStore +from app.schema_security import ( + SchemaReferenceError, + reject_external_schema_references, +) _CONTRIBUTION_ID = re.compile(r"^[a-z0-9][a-z0-9._-]*$") _SETTING_KEY = re.compile(r"^[a-z][a-z0-9._-]{0,127}$") @@ -74,9 +79,16 @@ class PluginCommandSpec(BaseModel): ) permission: str | None = None secrets: list[str] = Field(default_factory=list) - handler: Literal["echo", "uppercase_selection"] + handler: Literal["echo", "uppercase_selection"] | None = None + mcp_tool: str | None = None timeout_seconds: int = Field(default=30, ge=1, le=120) + @model_validator(mode="after") + def validate_execution_target(self) -> "PluginCommandSpec": + if (self.handler is None) == (self.mcp_tool is None): + raise ValueError("Command must declare exactly one handler or mcp_tool target.") + return self + CommandExecutor = Callable[ [dict[str, Any], dict[str, Any]], @@ -689,11 +701,13 @@ def validate_command_spec(plugin_id: str, spec: PluginCommandSpec) -> None: if spec.parameters.get("type", "object") != "object": raise ExtensionError("PLUGIN_COMMAND_INVALID", "Command parameters must be an object schema.") try: + reject_external_schema_references(spec.parameters) Draft202012Validator.check_schema(spec.parameters) - except SchemaError as exc: + except (SchemaReferenceError, SchemaError) as exc: + message = exc.message if isinstance(exc, SchemaError) else str(exc) raise ExtensionError( "PLUGIN_COMMAND_INVALID", - f"Plugin command parameters contain invalid JSON Schema: {exc.message}", + f"Plugin command parameters contain invalid JSON Schema: {message}", ) from exc @@ -746,7 +760,8 @@ def _secret_field( def _secret_reference(plugin_id: str, key: str) -> str: - return f"plugin.{plugin_id}.{key}" + digest = hashlib.sha256(f"{plugin_id}\0{key}".encode("utf-8")).hexdigest() + return f"plugin.{digest}" def _settings_schema_error(plugin_id: str, message: str) -> ExtensionError: diff --git a/backend/app/extensions/mcp.py b/backend/app/extensions/mcp.py index 68f056b..510494c 100644 --- a/backend/app/extensions/mcp.py +++ b/backend/app/extensions/mcp.py @@ -29,6 +29,10 @@ from app.contracts import ( PluginHostStatus, ToolDefinition, ) +from app.schema_security import ( + SchemaReferenceError, + reject_external_schema_references, +) MCP_PROTOCOL_VERSION = "2025-11-25" SUPPORTED_PROTOCOL_VERSIONS = { @@ -676,11 +680,13 @@ class McpBridge: f"MCP tool inputSchema must be an object schema: {remote_name}", ) try: + reject_external_schema_references(schema) Draft202012Validator.check_schema(schema) - except SchemaError as exc: + except (SchemaReferenceError, SchemaError) as exc: + message = exc.message if isinstance(exc, SchemaError) else str(exc) raise McpBridgeError( "MCP_TOOL_SCHEMA_INVALID", - f"Invalid MCP tool schema for {remote_name}: {exc.message}", + f"Invalid MCP tool schema for {remote_name}: {message}", ) from exc metadata = raw.get("_meta") permission = ( diff --git a/backend/app/extensions/runtime.py b/backend/app/extensions/runtime.py index 08d9321..3020451 100644 --- a/backend/app/extensions/runtime.py +++ b/backend/app/extensions/runtime.py @@ -5,13 +5,14 @@ import threading from dataclasses import dataclass from pathlib import Path from typing import Any, Literal +from uuid import uuid4 import yaml from jsonschema import Draft202012Validator from jsonschema.exceptions import SchemaError from pydantic import BaseModel, ConfigDict, Field, ValidationError, create_model -from app.agent.tools import ToolExecutionContext, ToolRegistry +from app.agent.tools import ToolExecutionContext, ToolExecutionError, ToolRegistry from app.agent.permissions import KNOWN_PERMISSIONS from app.contracts import ( ModelCapability, @@ -45,6 +46,10 @@ from app.extensions.contributions import ( from app.extensions.errors import ExtensionError from app.extensions.mcp import McpBridge, McpBridgeError, McpDiscoveredTool from app.providers.credentials import EncryptedCredentialStore +from app.schema_security import ( + SchemaReferenceError, + reject_external_schema_references, +) _EXTENSION_ID = re.compile(r"^[a-z0-9][a-z0-9._-]*$") @@ -410,6 +415,22 @@ class PluginRuntime: "Commands using Secret settings require the secrets.use permission.", details={"command_id": spec.command_id}, ) + if spec.mcp_tool is not None: + _validate_id("MCP command target", spec.mcp_tool) + if manifest.backend.type != "mcp" or not spec.mcp_tool.startswith( + f"{manifest.plugin_id}." + ): + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "MCP Command target must use the current Plugin namespace.", + details={"command_id": spec.command_id}, + ) + if spec.mcp_tool in manifest.contributes.tools: + raise ExtensionError( + "PLUGIN_COMMAND_INVALID", + "MCP Command target cannot also be exposed as an Agent Tool.", + details={"command_id": spec.command_id}, + ) record = _PluginRecord( plugin=Plugin( @@ -492,14 +513,21 @@ class PluginRuntime: discovered = self._start_mcp(record) actual = {item.definition.name for item in discovered} declared = set(declared_tools) - if actual != declared: + command_targets = { + spec.mcp_tool for spec in record.commands if spec.mcp_tool is not None + } + expected = declared | command_targets + if actual != expected: raise ExtensionError( "PLUGIN_CONTRIBUTION_INVALID", - "Discovered MCP tools must exactly match Plugin contributions.", - details={"declared": sorted(declared), "actual": sorted(actual)}, + "Discovered MCP tools must exactly match Tool and Command targets.", + details={"declared": sorted(expected), "actual": sorted(actual)}, ) for item in discovered: - self._register_mcp_tool(record, item) + if item.definition.name in declared: + self._register_mcp_tool(record, item) + else: + record.mcp_remote_names[item.definition.name] = item.remote_name else: for spec in record.tools: arguments_model = _arguments_model(spec) @@ -549,6 +577,7 @@ class PluginRuntime: if _record.settings_definition is not None else {} ) + def resolve_secret(key: str) -> str | None: if key not in _spec.secrets: raise ExtensionError( @@ -569,11 +598,62 @@ class PluginRuntime: ) if _record.settings_definition is None: return None - return self.settings.resolve_secret( + value = self.settings.resolve_secret( _record.plugin.manifest.plugin_id, _record.settings_definition, key, ) + field = next( + item + for item in _record.settings_definition.fields + if item.key == key + ) + if field.required and value is None: + raise ExtensionError( + "PLUGIN_SECRET_REQUIRED", + "A required Plugin Secret has not been configured.", + status_code=409, + details={"command_id": _spec.command_id, "key": key}, + ) + return value + + if _spec.mcp_tool is not None: + remote_name = _record.mcp_remote_names[_spec.mcp_tool] + secret_values = { + key: value + for key in _spec.secrets + if (value := resolve_secret(key)) is not None + } + try: + effect = await self.mcp.call_tool( + _record.plugin.manifest.plugin_id, + remote_name, + { + "_notesagent": { + "command_id": _spec.command_id, + "arguments": arguments, + "context": context, + "secrets": secret_values, + } + }, + request_id=f"command:{uuid4().hex}", + ) + except ToolExecutionError as exc: + raise ExtensionError( + exc.code, + "MCP Command target execution failed.", + status_code=502, + details={"command_id": _spec.command_id}, + ) from exc + try: + return PluginCommandEffect.model_validate(effect) + except ValidationError as exc: + raise ExtensionError( + "PLUGIN_COMMAND_RESULT_INVALID", + "MCP Command target returned an invalid effect.", + status_code=502, + details={"command_id": _spec.command_id}, + ) from exc return await self.host.execute_command( _spec.handler, @@ -963,11 +1043,13 @@ def _arguments_model_from_schema( def _validate_tool_schema(spec: DeclarativeToolSpec) -> None: schema = spec.parameters or {"type": "object", "properties": {}} try: + reject_external_schema_references(schema) Draft202012Validator.check_schema(schema) - except SchemaError as exc: + except (SchemaReferenceError, SchemaError) as exc: + message = exc.message if isinstance(exc, SchemaError) else str(exc) raise ExtensionError( "PLUGIN_TOOL_SCHEMA_INVALID", - f"Invalid JSON Schema for tool {spec.name}: {exc.message}", + f"Invalid JSON Schema for tool {spec.name}: {message}", details={"tool": spec.name}, ) from exc if schema.get("type", "object") != "object" or not isinstance( diff --git a/backend/app/schema_security.py b/backend/app/schema_security.py new file mode 100644 index 0000000..52e87d6 --- /dev/null +++ b/backend/app/schema_security.py @@ -0,0 +1,70 @@ +"""共享 JSON Schema 安全约束。""" + +from __future__ import annotations + +from typing import Any +from urllib.parse import unquote + + +class SchemaReferenceError(ValueError): + """Schema 引用不符合宿主的离线、文档内解析约束。""" + + +class ExternalSchemaReferenceError(SchemaReferenceError): + def __init__(self, keyword: str, reference: Any) -> None: + super().__init__(f"External JSON Schema reference is not allowed: {reference!r}") + self.keyword = keyword + self.reference = reference + + +class UnresolvableLocalSchemaReferenceError(SchemaReferenceError): + def __init__(self, reference: str) -> None: + super().__init__(f"Local JSON Schema reference cannot be resolved: {reference!r}") + self.reference = reference + + +def reject_external_schema_references(schema: Any) -> None: + """只允许可解析的文档内 Fragment，禁止文件和网络检索。""" + + pending = [schema] + local_references: list[str] = [] + anchors: set[str] = set() + while pending: + value = pending.pop() + if isinstance(value, dict): + for key, child in value.items(): + if key in {"$ref", "$dynamicRef"}: + if not isinstance(child, str) or not child.startswith("#"): + raise ExternalSchemaReferenceError(key, child) + local_references.append(child) + elif key in {"$anchor", "$dynamicAnchor"} and isinstance(child, str): + anchors.add(child) + pending.append(child) + elif isinstance(value, list): + pending.extend(value) + + for reference in local_references: + if not _local_reference_exists(schema, reference, anchors): + raise UnresolvableLocalSchemaReferenceError(reference) + + +def _local_reference_exists(schema: Any, reference: str, anchors: set[str]) -> bool: + fragment = unquote(reference[1:]) + if not fragment: + return True + if not fragment.startswith("/"): + return fragment in anchors + + current = schema + for encoded_segment in fragment[1:].split("/"): + segment = encoded_segment.replace("~1", "/").replace("~0", "~") + if isinstance(current, dict) and segment in current: + current = current[segment] + elif isinstance(current, list) and segment.isdecimal(): + index = int(segment) + if index >= len(current): + return False + current = current[index] + else: + return False + return True diff --git a/backend/extensions/fixtures/mcp-echo/commands.yaml b/backend/extensions/fixtures/mcp-echo/commands.yaml new file mode 100644 index 0000000..0428b86 --- /dev/null +++ b/backend/extensions/fixtures/mcp-echo/commands.yaml @@ -0,0 +1,20 @@ +commands: + - command_id: mcp-fixture.notify + title: MCP 通知 + description: 通过隔离 MCP Host 返回宿主白名单通知 effect。 + icon: bolt + locations: + - command_palette + when: + - editor.has_selection + context: + - selection + secrets: + - api_key + mcp_tool: mcp-fixture.command + parameters: + type: object + properties: + message: + type: string + additionalProperties: false diff --git a/backend/extensions/fixtures/mcp-echo/plugin.yaml b/backend/extensions/fixtures/mcp-echo/plugin.yaml index 34c4312..06fc59e 100644 --- a/backend/extensions/fixtures/mcp-echo/plugin.yaml +++ b/backend/extensions/fixtures/mcp-echo/plugin.yaml @@ -1,9 +1,10 @@ id: mcp-fixture name: MCP Fixture version: 1.0.0 -description: 阶段 C 离线联调 Fixture，覆盖 MCP Tool 生命周期与错误边界。 +description: 阶段 C/D 离线联调 Fixture，覆盖 MCP Tool、Command 与错误边界。 permissions: - notes.read + - secrets.use contributes: tools: - mcp-fixture.echo @@ -12,6 +13,10 @@ contributes: - mcp-fixture.large - mcp-fixture.environment - mcp-fixture.exit + commands: + - mcp-fixture.notify + settings_sections: + - mcp-fixture.general backend: type: mcp transport: stdio diff --git a/backend/extensions/fixtures/mcp-echo/server.py b/backend/extensions/fixtures/mcp-echo/server.py index b1fefda..ba61194 100644 --- a/backend/extensions/fixtures/mcp-echo/server.py +++ b/backend/extensions/fixtures/mcp-echo/server.py @@ -54,6 +54,11 @@ TOOLS = { "large": tool("large", "Return a result larger than the host limit."), "environment": tool("environment", "Report whether host secrets leaked into the process."), "exit": tool("exit", "Terminate the fixture process."), + "command": tool( + "command", + "Execute a NotesAgent Plugin Command envelope.", + {"_notesagent": {"type": "object"}}, + ), } # suffix 是可选字段，用于验证 Host 不会把缺省值擅自补成 null。 TOOLS["echo"]["inputSchema"]["required"] = ["text"] @@ -62,6 +67,28 @@ TOOLS["echo"]["inputSchema"]["required"] = ["text"] def call_tool(request_id: int, params: dict[str, Any]) -> None: name = params.get("name") arguments = params.get("arguments") or {} + if name == "command": + envelope = arguments.get("_notesagent") or {} + command_arguments = envelope.get("arguments") or {} + context = envelope.get("context") or {} + secrets = envelope.get("secrets") or {} + message = command_arguments.get("message") or context.get("selection") or "" + respond( + request_id, + { + "content": [{"type": "text", "text": "command completed"}], + "structuredContent": { + "type": "notification", + "payload": { + "level": "success", + "message": str(message), + "secret_configured": isinstance(secrets.get("api_key"), str), + }, + }, + "isError": False, + }, + ) + return if name == "echo": text = str(arguments.get("text", "")) structured_content = {"echo": text} @@ -183,7 +210,14 @@ def main() -> None: elif params.get("cursor") == "page-2": respond( request_id, - {"tools": [TOOLS["large"], TOOLS["environment"], TOOLS["exit"]]}, + { + "tools": [ + TOOLS["large"], + TOOLS["environment"], + TOOLS["exit"], + TOOLS["command"], + ] + }, ) else: respond( diff --git a/backend/extensions/fixtures/mcp-echo/settings.yaml b/backend/extensions/fixtures/mcp-echo/settings.yaml new file mode 100644 index 0000000..dfc3aa9 --- /dev/null +++ b/backend/extensions/fixtures/mcp-echo/settings.yaml @@ -0,0 +1,7 @@ +section_id: mcp-fixture.general +schema_version: 1 +fields: + - key: api_key + label: Fixture API Key + type: secret + required: true diff --git a/backend/tests/test_extension_core.py b/backend/tests/test_extension_core.py index 29a2d92..25539b8 100644 --- a/backend/tests/test_extension_core.py +++ b/backend/tests/test_extension_core.py @@ -11,6 +11,7 @@ from app.container import build_container from app.contracts import ( AgentRunCreateRequest, AgentRunStatus, + PluginCommandContext, SkillStatus, ToolCall, ) @@ -33,7 +34,7 @@ def mcp_container(): container = build_container() installed = container.plugins.install(MCP_FIXTURE) assert installed.status == "permission_required" - container.plugins.set_permissions("mcp-fixture", ["notes.read"]) + container.plugins.set_permissions("mcp-fixture", ["notes.read", "secrets.use"]) try: yield container finally: @@ -349,7 +350,7 @@ def test_mcp_stdio_host_discovers_namespaced_tools_and_maps_results( ToolExecutionContext(run_id="run_mcp_fixture"), ) - assert status.tools_count == 6 + assert status.tools_count == 7 assert status.protocol_version == "2025-11-25" assert status.server_name == "notesagent-mcp-fixture" assert definition.permission == "notes.read" @@ -396,6 +397,46 @@ def test_mcp_stdio_host_discovers_namespaced_tools_and_maps_results( run(scenario()) +def test_mcp_command_target_receives_scoped_context_and_declared_secret( + mcp_container, +) -> None: + async def scenario() -> None: + mcp_container.plugins.enable("mcp-fixture") + + assert not mcp_container.tools.contains("mcp-fixture.command") + with pytest.raises(ExtensionError) as missing: + await mcp_container.plugins.execute_command( + "mcp-fixture.notify", + {}, + PluginCommandContext(selection="来自选区"), + ) + assert missing.value.code == "PLUGIN_SECRET_REQUIRED" + + mcp_container.plugins.put_setting_secret( + "mcp-fixture", "api_key", "mcp-command-secret" + ) + result = await mcp_container.plugins.execute_command( + "mcp-fixture.notify", + {}, + PluginCommandContext( + note_id="must-not-enter-envelope", + selection="来自选区", + ), + ) + + assert result.effect.type == "notification" + assert result.effect.payload == { + "level": "success", + "message": "来自选区", + "secret_configured": True, + } + assert "mcp-command-secret" not in repr( + mcp_container.plugins.commands.audit_events() + ) + + run(scenario()) + + def test_agent_calls_mcp_tool_through_registry_and_writes_trace(mcp_container) -> None: async def scenario() -> None: mcp_container.plugins.enable("mcp-fixture") @@ -531,7 +572,7 @@ def test_production_rejects_unsandboxed_mcp_host(monkeypatch) -> None: container = build_container() installed = container.plugins.install(MCP_FIXTURE) assert installed.status == "permission_required" - container.plugins.set_permissions("mcp-fixture", ["notes.read"]) + container.plugins.set_permissions("mcp-fixture", ["notes.read", "secrets.use"]) try: with pytest.raises(ExtensionError) as exc: container.plugins.enable("mcp-fixture") @@ -565,7 +606,7 @@ def test_mcp_abnormal_exit_unregisters_tools_and_restart_recovers(mcp_container) restarted = mcp_container.plugins.restart_host("mcp-fixture") assert restarted.status == "ready" - assert restarted.tools_count == 6 + assert restarted.tools_count == 7 assert mcp_container.tools.contains("mcp-fixture.echo") run(scenario()) diff --git a/backend/tests/test_plugin_contributions.py b/backend/tests/test_plugin_contributions.py index d80bf7f..cd994f4 100644 --- a/backend/tests/test_plugin_contributions.py +++ b/backend/tests/test_plugin_contributions.py @@ -13,6 +13,7 @@ from app.contracts import ( PluginSettingType, ) from app.extensions import ExtensionError, PluginRuntime +from app.extensions.contributions import _secret_reference from app.extensions.runtime import DeclarativePluginHost TEXT_TOOLS = BACKEND_DIR / "extensions" / "plugins" / "text-tools" @@ -260,24 +261,39 @@ def test_secret_roundtrip_never_enters_plain_settings_storage() -> None: assert "api_key" not in schema.values assert plaintext not in settings_path.read_text(encoding="utf-8") assert plaintext not in credentials_path.read_text(encoding="utf-8") - assert container.credentials.resolve("plugin.text-tools.api_key") == plaintext + stored_settings = json.loads(settings_path.read_text(encoding="utf-8")) + reference = stored_settings["text-tools"]["secret_refs"]["api_key"] + assert reference.startswith("plugin.") + assert len(reference) == 71 + assert "text-tools" not in reference and "api_key" not in reference + assert container.credentials.resolve(reference) == plaintext deleted = container.plugins.delete_setting_secret("text-tools", "api_key") assert deleted.configured is False - assert container.credentials.resolve("plugin.text-tools.api_key") is None + assert container.credentials.resolve(reference) is None def test_uninstall_removes_plugin_settings_and_secret_namespace() -> None: container = build_container() container.plugins.update_settings("text-tools", 1, {"result_limit": 12}) container.plugins.put_setting_secret("text-tools", "api_key", "temporary") + settings_path = get_settings().data_dir / "plugins" / "settings.json" + reference = json.loads(settings_path.read_text(encoding="utf-8"))[ + "text-tools" + ]["secret_refs"]["api_key"] container.plugins.uninstall("text-tools") - settings_path = get_settings().data_dir / "plugins" / "settings.json" stored = json.loads(settings_path.read_text(encoding="utf-8")) assert "text-tools" not in stored - assert container.credentials.resolve("plugin.text-tools.api_key") is None + assert container.credentials.resolve(reference) is None + + +def test_plugin_secret_reference_has_fixed_credential_safe_length() -> None: + reference = _secret_reference("p" * 512, "k" * 128) + + assert reference.startswith("plugin.") + assert len(reference) <= 128 def test_invalid_command_and_settings_manifest_are_rejected(tmp_path: Path) -> None: @@ -363,6 +379,42 @@ backend: assert exc.value.code == "EXTENSION_MANIFEST_INVALID" +def test_external_command_schema_reference_is_rejected(tmp_path: Path) -> None: + package = tmp_path / "external-ref" + package.mkdir() + (package / "plugin.yaml").write_text( + """ +id: external-ref +name: External Ref +version: 1.0.0 +contributes: + commands: [external-ref.run] +backend: + type: internal_rpc + transport: none +""".strip(), + encoding="utf-8", + ) + (package / "commands.yaml").write_text( + """ +commands: + - command_id: external-ref.run + title: External Ref + locations: [command_palette] + handler: echo + parameters: + $ref: file:///host/private-schema.json +""".strip(), + encoding="utf-8", + ) + + with pytest.raises(ExtensionError) as exc: + PluginRuntime(ToolRegistry()).install(package) + + assert exc.value.code == "PLUGIN_COMMAND_INVALID" + assert "External JSON Schema reference" in exc.value.message + + def test_settings_missing_and_secret_field_errors_are_stable() -> None: container = build_container() @@ -394,4 +446,10 @@ def test_corrupted_plugin_settings_namespace_returns_stable_error() -> None: container.plugins.put_setting_secret("text-tools", "api_key", "must-not-orphan") assert secret_exc.value.code == "PLUGIN_STORAGE_ERROR" - assert container.credentials.resolve("plugin.text-tools.api_key") is None + credentials_path = get_settings().data_dir / "credentials" / "credentials.json" + credential_ids = ( + json.loads(credentials_path.read_text(encoding="utf-8")).keys() + if credentials_path.exists() + else [] + ) + assert not any(item.startswith("plugin.") for item in credential_ids) diff --git a/backend/tests/test_schema_security.py b/backend/tests/test_schema_security.py new file mode 100644 index 0000000..257faa1 --- /dev/null +++ b/backend/tests/test_schema_security.py @@ -0,0 +1,35 @@ +import pytest + +from app.schema_security import ( + ExternalSchemaReferenceError, + UnresolvableLocalSchemaReferenceError, + reject_external_schema_references, +) + + +@pytest.mark.parametrize( + "schema", + [ + {"$ref": "file:///host/private-schema.json"}, + {"properties": {"value": {"$ref": "https://schema.invalid/value.json"}}}, + {"allOf": [{"$dynamicRef": "https://schema.invalid/dynamic"}]}, + ], +) +def test_external_json_schema_references_are_rejected(schema) -> None: + with pytest.raises(ExternalSchemaReferenceError): + reject_external_schema_references(schema) + + +def test_local_json_schema_fragment_reference_is_allowed() -> None: + reject_external_schema_references( + { + "$defs": {"value": {"type": "string"}}, + "properties": {"value": {"$ref": "#/$defs/value"}}, + } + ) + + +@pytest.mark.parametrize("reference", ["#/$defs/missing", "#missing-anchor"]) +def test_unresolvable_local_schema_reference_is_rejected(reference: str) -> None: + with pytest.raises(UnresolvableLocalSchemaReferenceError): + reject_external_schema_references({"type": "object", "$ref": reference}) From ec88795b113aaee2becc118c8acf870bcefaaff1 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 15:31:39 +0800 Subject: [PATCH 04/13] =?UTF-8?q?fix(extension):=20=E4=BF=9D=E6=8A=A4?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=87=AD=E6=8D=AE=E5=BC=95=E7=94=A8=E4=B8=8E?= =?UTF-8?q?=E5=88=A0=E9=99=A4=E4=BA=8B=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- backend/README.md | 2 +- backend/app/extensions/contributions.py | 93 ++++++++++++++++------ backend/app/providers/credentials.py | 47 ++++++++--- backend/tests/test_credentials.py | 28 +++++++ backend/tests/test_plugin_contributions.py | 75 +++++++++++++++++ 6 files changed, 211 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 073e8ea..65ea3f4 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 116 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 121 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 diff --git a/backend/README.md b/backend/README.md index 9d32774..2f32253 100644 --- a/backend/README.md +++ b/backend/README.md @@ -23,7 +23,7 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 116 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 +当前基线为 121 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 diff --git a/backend/app/extensions/contributions.py b/backend/app/extensions/contributions.py index a496db5..783a7d5 100644 --- a/backend/app/extensions/contributions.py +++ b/backend/app/extensions/contributions.py @@ -326,6 +326,7 @@ class PluginSettingsStore: secret_refs = entry.get("secret_refs", {}) if not isinstance(stored_values, dict) or not isinstance(secret_refs, dict): raise self._storage_format_error(plugin_id) + validated_refs = self._validate_secret_refs(plugin_id, secret_refs) values = { field.key: field.default for field in definition.fields @@ -349,7 +350,7 @@ class PluginSettingsStore: for field in definition.fields: if field.type != PluginSettingType.secret: continue - reference = secret_refs.get(field.key) + reference = validated_refs.get(field.key) secrets[field.key] = PluginSecretState( configured=isinstance(reference, str) and self._has_secret(reference) ) @@ -457,6 +458,7 @@ class PluginSettingsStore: refs = entry.get("secret_refs", {}) if not isinstance(refs, dict): raise self._storage_format_error(plugin_id) + self._validate_secret_refs(plugin_id, refs) entry["secret_refs"] = refs try: previous = self.credentials.resolve(reference) @@ -494,16 +496,28 @@ class PluginSettingsStore: refs = entry.get("secret_refs", {}) if not isinstance(refs, dict): raise self._storage_format_error(plugin_id) - reference = refs.pop(key, None) - if reference: - try: - self.credentials.delete(reference) - except CredentialStoreError as exc: - raise ExtensionError( - "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 - ) from exc - if plugin_id in data: + self._validate_secret_refs(plugin_id, refs) + reference = _secret_reference(plugin_id, key) + had_reference = refs.pop(key, None) is not None + if plugin_id in data and had_reference: self._write(data) + try: + self.credentials.delete(reference) + except CredentialStoreError as exc: + if had_reference: + refs[key] = reference + try: + self._write(data) + except ExtensionError as rollback_exc: + raise ExtensionError( + "PLUGIN_STORAGE_ERROR", + "Plugin Secret deletion failed and its reference could not be restored.", + status_code=500, + details={"plugin_id": plugin_id, "key": key}, + ) from rollback_exc + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 + ) from exc return PluginSecretStatus(plugin_id=plugin_id, key=key, configured=False) def resolve_secret( @@ -515,7 +529,7 @@ class PluginSettingsStore: refs = entry.get("secret_refs", {}) if not isinstance(refs, dict): raise self._storage_format_error(plugin_id) - reference = refs.get(key) + reference = self._validate_secret_refs(plugin_id, refs).get(key) try: return self.credentials.resolve(reference) if isinstance(reference, str) else None except CredentialStoreError as exc: @@ -527,21 +541,48 @@ class PluginSettingsStore: with self._lock: data = self._read() entry = data.pop(plugin_id, None) - if isinstance(entry, dict): + references: list[str] = [] + if entry is not None and not isinstance(entry, dict): + raise self._storage_format_error(plugin_id) + if entry is not None: refs = entry.get("secret_refs", {}) - if isinstance(refs, dict): - for reference in refs.values(): - if isinstance(reference, str): - try: - self.credentials.delete(reference) - except CredentialStoreError as exc: - raise ExtensionError( - "PLUGIN_SECRET_STORE_ERROR", - str(exc), - status_code=500, - ) from exc + if not isinstance(refs, dict): + raise self._storage_format_error(plugin_id) + references = list(self._validate_secret_refs(plugin_id, refs).values()) if entry is not None: self._write(data) + try: + self.credentials.delete_many(references) + except CredentialStoreError as exc: + if entry is not None: + data[plugin_id] = entry + try: + self._write(data) + except ExtensionError as rollback_exc: + raise ExtensionError( + "PLUGIN_STORAGE_ERROR", + "Plugin uninstall failed and its Settings namespace could not be restored.", + status_code=500, + details={"plugin_id": plugin_id}, + ) from rollback_exc + raise ExtensionError( + "PLUGIN_SECRET_STORE_ERROR", str(exc), status_code=500 + ) from exc + + def _validate_secret_refs( + self, plugin_id: str, refs: dict[Any, Any] + ) -> dict[str, str]: + validated: dict[str, str] = {} + for key, reference in refs.items(): + if ( + not isinstance(key, str) + or not _SETTING_KEY.fullmatch(key) + or not isinstance(reference, str) + or reference != _secret_reference(plugin_id, key) + ): + raise self._storage_format_error(plugin_id) + validated[key] = reference + return validated def _has_secret(self, reference: str) -> bool: try: @@ -599,15 +640,19 @@ class PluginSettingsStore: def _write(self, value: dict[str, dict[str, Any]]) -> None: path = self._path() - path.parent.mkdir(parents=True, exist_ok=True) temporary = path.with_suffix(".tmp") try: + path.parent.mkdir(parents=True, exist_ok=True) temporary.write_text( json.dumps(value, ensure_ascii=False, sort_keys=True), encoding="utf-8", ) temporary.replace(path) except OSError as exc: + try: + temporary.unlink(missing_ok=True) + except OSError: + pass raise ExtensionError( "PLUGIN_STORAGE_ERROR", "Plugin settings storage cannot be written.", diff --git a/backend/app/providers/credentials.py b/backend/app/providers/credentials.py index ae1cca6..88d9485 100644 --- a/backend/app/providers/credentials.py +++ b/backend/app/providers/credentials.py @@ -119,17 +119,26 @@ class EncryptedCredentialStore: def _write_tokens(self, tokens: dict[str, str]) -> None: _, store_path = self._paths() - store_path.parent.mkdir(parents=True, exist_ok=True) - self._restrict(store_path.parent, 0o700) temporary = store_path.with_suffix(".tmp") - temporary.write_text( - json.dumps(tokens, ensure_ascii=True, sort_keys=True), - encoding="utf-8", - ) - self._restrict(temporary, 0o600) - # 凭据表同样使用原子替换，确保并发读取只会看到完整 JSON。 - temporary.replace(store_path) - self._restrict(store_path, 0o600) + try: + store_path.parent.mkdir(parents=True, exist_ok=True) + self._restrict(store_path.parent, 0o700) + temporary.write_text( + json.dumps(tokens, ensure_ascii=True, sort_keys=True), + encoding="utf-8", + ) + self._restrict(temporary, 0o600) + # 凭据表同样使用原子替换，确保并发读取只会看到完整 JSON。 + temporary.replace(store_path) + self._restrict(store_path, 0o600) + except OSError as exc: + try: + temporary.unlink(missing_ok=True) + except OSError: + pass + raise CredentialStoreError( + "Encrypted credential store cannot be written." + ) from exc def put(self, credential_id: str, secret: str) -> None: self._validate_id(credential_id) @@ -168,6 +177,24 @@ class EncryptedCredentialStore: self._write_tokens(tokens) return removed + def delete_many(self, credential_ids: list[str]) -> set[str]: + """用一次原子替换删除多个凭据，避免插件卸载只删除部分 Secret。""" + + for credential_id in credential_ids: + self._validate_id(credential_id) + with self._lock: + tokens = self._read_tokens() + removed = { + credential_id + for credential_id in credential_ids + if credential_id in tokens + } + if removed: + for credential_id in removed: + del tokens[credential_id] + self._write_tokens(tokens) + return removed + class ChainedCredentialResolver: def __init__(self, *resolvers: CredentialResolver) -> None: diff --git a/backend/tests/test_credentials.py b/backend/tests/test_credentials.py index 37ac388..ca09176 100644 --- a/backend/tests/test_credentials.py +++ b/backend/tests/test_credentials.py @@ -1,4 +1,5 @@ import asyncio +from pathlib import Path import httpx import pytest @@ -35,6 +36,33 @@ def test_encrypted_credential_store_round_trip_without_plaintext_on_disk() -> No assert store.resolve("deepseek") is None +def test_encrypted_credential_store_deletes_multiple_credentials_atomically() -> None: + store = EncryptedCredentialStore() + store.put("plugin.first", "first") + store.put("plugin.second", "second") + store.put("openai", "keep") + + removed = store.delete_many(["plugin.first", "plugin.second"]) + + assert removed == {"plugin.first", "plugin.second"} + assert store.resolve("plugin.first") is None + assert store.resolve("plugin.second") is None + assert store.resolve("openai") == "keep" + + +def test_credential_write_os_error_uses_stable_store_error(monkeypatch) -> None: + store = EncryptedCredentialStore() + store.put("existing", "value") + + def fail_replace(_path: Path, _target: Path) -> Path: + raise OSError("injected replace failure") + + monkeypatch.setattr(Path, "replace", fail_replace) + + with pytest.raises(CredentialStoreError, match="cannot be written"): + store.put("new", "value") + + def test_credential_api_never_returns_secret() -> None: written = asyncio.run( put_credential( diff --git a/backend/tests/test_plugin_contributions.py b/backend/tests/test_plugin_contributions.py index cd994f4..f3e77c2 100644 --- a/backend/tests/test_plugin_contributions.py +++ b/backend/tests/test_plugin_contributions.py @@ -15,6 +15,7 @@ from app.contracts import ( from app.extensions import ExtensionError, PluginRuntime from app.extensions.contributions import _secret_reference from app.extensions.runtime import DeclarativePluginHost +from app.providers.credentials import CredentialStoreError TEXT_TOOLS = BACKEND_DIR / "extensions" / "plugins" / "text-tools" @@ -296,6 +297,80 @@ def test_plugin_secret_reference_has_fixed_credential_safe_length() -> None: assert len(reference) <= 128 +def test_tampered_secret_reference_cannot_cross_credential_namespace() -> None: + container = build_container() + container.credentials.put("openai", "provider-private-secret") + settings_path = get_settings().data_dir / "plugins" / "settings.json" + settings_path.parent.mkdir(parents=True, exist_ok=True) + settings_path.write_text( + json.dumps( + { + "text-tools": { + "schema_version": 1, + "values": {}, + "secret_refs": {"api_key": "openai"}, + } + } + ), + encoding="utf-8", + ) + + with pytest.raises(ExtensionError) as read_error: + container.plugins.get_settings("text-tools") + with pytest.raises(ExtensionError) as uninstall_error: + container.plugins.uninstall("text-tools") + + assert read_error.value.code == "PLUGIN_STORAGE_ERROR" + assert uninstall_error.value.code == "PLUGIN_STORAGE_ERROR" + assert container.credentials.resolve("openai") == "provider-private-secret" + + +def test_secret_delete_restores_reference_when_credential_delete_fails( + monkeypatch, +) -> None: + container = build_container() + container.plugins.put_setting_secret("text-tools", "api_key", "keep-me") + settings_path = get_settings().data_dir / "plugins" / "settings.json" + original = settings_path.read_text(encoding="utf-8") + reference = _secret_reference("text-tools", "api_key") + + def fail_delete(_credential_id: str) -> bool: + raise CredentialStoreError("injected delete failure") + + monkeypatch.setattr(container.credentials, "delete", fail_delete) + + with pytest.raises(ExtensionError) as exc: + container.plugins.delete_setting_secret("text-tools", "api_key") + + assert exc.value.code == "PLUGIN_SECRET_STORE_ERROR" + assert settings_path.read_text(encoding="utf-8") == original + assert container.credentials.resolve(reference) == "keep-me" + + +def test_uninstall_restores_settings_when_atomic_secret_delete_fails( + monkeypatch, +) -> None: + container = build_container() + container.plugins.update_settings("text-tools", 1, {"result_limit": 12}) + container.plugins.put_setting_secret("text-tools", "api_key", "keep-me") + settings_path = get_settings().data_dir / "plugins" / "settings.json" + original = settings_path.read_text(encoding="utf-8") + reference = _secret_reference("text-tools", "api_key") + + def fail_delete_many(_credential_ids: list[str]) -> set[str]: + raise CredentialStoreError("injected batch delete failure") + + monkeypatch.setattr(container.credentials, "delete_many", fail_delete_many) + + with pytest.raises(ExtensionError) as exc: + container.plugins.uninstall("text-tools") + + assert exc.value.code == "PLUGIN_SECRET_STORE_ERROR" + assert settings_path.read_text(encoding="utf-8") == original + assert container.credentials.resolve(reference) == "keep-me" + assert container.plugins.get("text-tools").manifest.plugin_id == "text-tools" + + def test_invalid_command_and_settings_manifest_are_rejected(tmp_path: Path) -> None: invalid_command = tmp_path / "invalid-command" invalid_command.mkdir() From b16230ac4c5822d106c8c995f3f1d5c837fe949a Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 15:47:54 +0800 Subject: [PATCH 05/13] =?UTF-8?q?fix(extension):=20=E6=8C=89Schema?= =?UTF-8?q?=E8=B5=84=E6=BA=90=E4=BD=9C=E7=94=A8=E5=9F=9F=E6=A0=A1=E9=AA=8C?= =?UTF-8?q?=E5=BC=95=E7=94=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- backend/README.md | 2 +- backend/app/agent/tools.py | 1 + backend/app/extensions/contributions.py | 9 ++- backend/app/extensions/mcp.py | 2 +- backend/app/extensions/runtime.py | 2 +- backend/app/schema_security.py | 72 ++++++++++------------ backend/pyproject.toml | 1 + backend/tests/test_plugin_contributions.py | 37 +++++++++++ backend/tests/test_schema_security.py | 30 +++++++++ backend/uv.lock | 2 + 11 files changed, 114 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 65ea3f4..7026ca3 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 121 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 126 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 diff --git a/backend/README.md b/backend/README.md index 2f32253..a087fa7 100644 --- a/backend/README.md +++ b/backend/README.md @@ -23,7 +23,7 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 121 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 +当前基线为 126 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 diff --git a/backend/app/agent/tools.py b/backend/app/agent/tools.py index 33c6615..fb53ed2 100644 --- a/backend/app/agent/tools.py +++ b/backend/app/agent/tools.py @@ -55,6 +55,7 @@ class ToolRegistry: arguments_model: type[BaseModel], executor: ToolExecutor, ) -> None: + Draft202012Validator.check_schema(definition.parameters) reject_external_schema_references(definition.parameters) with self._lock: if definition.name in self._tools: diff --git a/backend/app/extensions/contributions.py b/backend/app/extensions/contributions.py index 783a7d5..7be209a 100644 --- a/backend/app/extensions/contributions.py +++ b/backend/app/extensions/contributions.py @@ -682,6 +682,13 @@ def validate_settings_definition( field.minimum is not None or field.maximum is not None ): raise _settings_schema_error(plugin_id, f"Only number settings accept bounds: {field.key}") + if any( + bound is not None and not math.isfinite(bound) + for bound in (field.minimum, field.maximum) + ): + raise _settings_schema_error( + plugin_id, f"Number setting bounds must be finite: {field.key}" + ) if field.minimum is not None and field.maximum is not None and field.minimum > field.maximum: raise _settings_schema_error(plugin_id, f"Setting bounds are reversed: {field.key}") if field.type == PluginSettingType.secret and field.default is not None: @@ -746,8 +753,8 @@ def validate_command_spec(plugin_id: str, spec: PluginCommandSpec) -> None: if spec.parameters.get("type", "object") != "object": raise ExtensionError("PLUGIN_COMMAND_INVALID", "Command parameters must be an object schema.") try: - reject_external_schema_references(spec.parameters) Draft202012Validator.check_schema(spec.parameters) + reject_external_schema_references(spec.parameters) except (SchemaReferenceError, SchemaError) as exc: message = exc.message if isinstance(exc, SchemaError) else str(exc) raise ExtensionError( diff --git a/backend/app/extensions/mcp.py b/backend/app/extensions/mcp.py index 510494c..dc3e62f 100644 --- a/backend/app/extensions/mcp.py +++ b/backend/app/extensions/mcp.py @@ -680,8 +680,8 @@ class McpBridge: f"MCP tool inputSchema must be an object schema: {remote_name}", ) try: - reject_external_schema_references(schema) Draft202012Validator.check_schema(schema) + reject_external_schema_references(schema) except (SchemaReferenceError, SchemaError) as exc: message = exc.message if isinstance(exc, SchemaError) else str(exc) raise McpBridgeError( diff --git a/backend/app/extensions/runtime.py b/backend/app/extensions/runtime.py index 3020451..a6f0730 100644 --- a/backend/app/extensions/runtime.py +++ b/backend/app/extensions/runtime.py @@ -1043,8 +1043,8 @@ def _arguments_model_from_schema( def _validate_tool_schema(spec: DeclarativeToolSpec) -> None: schema = spec.parameters or {"type": "object", "properties": {}} try: - reject_external_schema_references(schema) Draft202012Validator.check_schema(schema) + reject_external_schema_references(schema) except (SchemaReferenceError, SchemaError) as exc: message = exc.message if isinstance(exc, SchemaError) else str(exc) raise ExtensionError( diff --git a/backend/app/schema_security.py b/backend/app/schema_security.py index 52e87d6..791fa62 100644 --- a/backend/app/schema_security.py +++ b/backend/app/schema_security.py @@ -3,7 +3,13 @@ from __future__ import annotations from typing import Any -from urllib.parse import unquote +from urllib.parse import urljoin + +from referencing import Registry +from referencing.exceptions import Unresolvable +from referencing.jsonschema import DRAFT202012 + +_SCHEMA_BASE_URI = "https://notesagent.invalid/local-schema" class SchemaReferenceError(ValueError): @@ -24,47 +30,31 @@ class UnresolvableLocalSchemaReferenceError(SchemaReferenceError): def reject_external_schema_references(schema: Any) -> None: - """只允许可解析的文档内 Fragment，禁止文件和网络检索。""" + """只允许可解析的文档内 Fragment，并按 JSON Schema Resource 作用域解析。""" - pending = [schema] - local_references: list[str] = [] - anchors: set[str] = set() - while pending: - value = pending.pop() - if isinstance(value, dict): - for key, child in value.items(): - if key in {"$ref", "$dynamicRef"}: - if not isinstance(child, str) or not child.startswith("#"): - raise ExternalSchemaReferenceError(key, child) - local_references.append(child) - elif key in {"$anchor", "$dynamicAnchor"} and isinstance(child, str): - anchors.add(child) - pending.append(child) - elif isinstance(value, list): - pending.extend(value) - - for reference in local_references: - if not _local_reference_exists(schema, reference, anchors): - raise UnresolvableLocalSchemaReferenceError(reference) + root = DRAFT202012.create_resource(schema) + root_uri = urljoin(_SCHEMA_BASE_URI, root.id() or "") + registry = Registry().with_resource(_SCHEMA_BASE_URI, root).crawl() + resolver = registry.resolver(root_uri) + _validate_resource_references(root, resolver) -def _local_reference_exists(schema: Any, reference: str, anchors: set[str]) -> bool: - fragment = unquote(reference[1:]) - if not fragment: - return True - if not fragment.startswith("/"): - return fragment in anchors +def _validate_resource_references(resource, resolver: Any) -> None: + contents = resource.contents + if isinstance(contents, dict): + for keyword in ("$ref", "$dynamicRef"): + if keyword not in contents: + continue + reference = contents[keyword] + if not isinstance(reference, str) or not reference.startswith("#"): + raise ExternalSchemaReferenceError(keyword, reference) + try: + resolver.lookup(reference) + except Unresolvable as exc: + raise UnresolvableLocalSchemaReferenceError(reference) from exc - current = schema - for encoded_segment in fragment[1:].split("/"): - segment = encoded_segment.replace("~1", "/").replace("~0", "~") - if isinstance(current, dict) and segment in current: - current = current[segment] - elif isinstance(current, list) and segment.isdecimal(): - index = int(segment) - if index >= len(current): - return False - current = current[index] - else: - return False - return True + for subresource in resource.subresources(): + _validate_resource_references( + subresource, + resolver.in_subresource(subresource), + ) diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 3688aaa..6c3d4c0 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -10,6 +10,7 @@ dependencies = [ "httpx>=0.28,<1.0", "jsonschema>=4.25,<5.0", "pyyaml>=6.0,<7.0", + "referencing>=0.36,<1.0", "sqlite-vec>=0.1.9", "uvicorn[standard]>=0.35,<1.0", ] diff --git a/backend/tests/test_plugin_contributions.py b/backend/tests/test_plugin_contributions.py index f3e77c2..def7204 100644 --- a/backend/tests/test_plugin_contributions.py +++ b/backend/tests/test_plugin_contributions.py @@ -430,6 +430,43 @@ fields: assert settings_error.value.code == "PLUGIN_SETTINGS_SCHEMA_INVALID" +@pytest.mark.parametrize("bound", [".nan", ".inf", "-.inf"]) +def test_non_finite_setting_bounds_are_rejected(tmp_path: Path, bound: str) -> None: + package = tmp_path / f"invalid-bound-{bound.replace('.', 'dot').replace('-', 'neg')}" + package.mkdir() + (package / "plugin.yaml").write_text( + """ +id: invalid-bound +name: Invalid Bound +version: 1.0.0 +contributes: + settings_sections: [invalid-bound.general] +backend: + type: none + transport: none +""".strip(), + encoding="utf-8", + ) + (package / "settings.yaml").write_text( + f""" +section_id: invalid-bound.general +schema_version: 1 +fields: + - key: limit + label: Limit + type: number + minimum: {bound} +""".strip(), + encoding="utf-8", + ) + + with pytest.raises(ExtensionError) as exc: + PluginRuntime(ToolRegistry()).install(package) + + assert exc.value.code == "PLUGIN_SETTINGS_SCHEMA_INVALID" + assert "must be finite" in exc.value.message + + def test_null_command_list_returns_stable_manifest_error(tmp_path: Path) -> None: package = tmp_path / "null-commands" package.mkdir() diff --git a/backend/tests/test_schema_security.py b/backend/tests/test_schema_security.py index 257faa1..cac9412 100644 --- a/backend/tests/test_schema_security.py +++ b/backend/tests/test_schema_security.py @@ -33,3 +33,33 @@ def test_local_json_schema_fragment_reference_is_allowed() -> None: def test_unresolvable_local_schema_reference_is_rejected(reference: str) -> None: with pytest.raises(UnresolvableLocalSchemaReferenceError): reject_external_schema_references({"type": "object", "$ref": reference}) + + +def test_root_reference_cannot_use_anchor_from_nested_schema_resource() -> None: + schema = { + "$defs": { + "nested": { + "$id": "nested", + "$anchor": "inside", + "type": "string", + } + }, + "properties": {"value": {"$ref": "#inside"}}, + } + + with pytest.raises(UnresolvableLocalSchemaReferenceError): + reject_external_schema_references(schema) + + +def test_nested_schema_resource_can_resolve_its_own_anchor() -> None: + schema = { + "$defs": { + "nested": { + "$id": "nested", + "$anchor": "inside", + "allOf": [{"$ref": "#inside"}], + } + } + } + + reject_external_schema_references(schema) diff --git a/backend/uv.lock b/backend/uv.lock index 03432b5..16eefd2 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -374,6 +374,7 @@ dependencies = [ { name = "httpx" }, { name = "jsonschema" }, { name = "pyyaml" }, + { name = "referencing" }, { name = "sqlite-vec" }, { name = "uvicorn", extra = ["standard"] }, ] @@ -390,6 +391,7 @@ requires-dist = [ { name = "httpx", specifier = ">=0.28,<1.0" }, { name = "jsonschema", specifier = ">=4.25,<5.0" }, { name = "pyyaml", specifier = ">=6.0,<7.0" }, + { name = "referencing", specifier = ">=0.36,<1.0" }, { name = "sqlite-vec", specifier = ">=0.1.9" }, { name = "uvicorn", extras = ["standard"], specifier = ">=0.35,<1.0" }, ] From 09c1bdac21afca2e579808d92aa4c490fc65f699 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 18:23:32 +0800 Subject: [PATCH 06/13] =?UTF-8?q?fix(extension):=20=E5=90=91MCP=E5=91=BD?= =?UTF-8?q?=E4=BB=A4=E4=BC=A0=E9=80=92=E6=8F=92=E4=BB=B6=E8=AE=BE=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/app/extensions/runtime.py | 1 + backend/extensions/fixtures/mcp-echo/server.py | 2 ++ backend/extensions/fixtures/mcp-echo/settings.yaml | 4 ++++ backend/tests/test_extension_core.py | 5 ++++- 4 files changed, 11 insertions(+), 1 deletion(-) diff --git a/backend/app/extensions/runtime.py b/backend/app/extensions/runtime.py index a6f0730..6a5e918 100644 --- a/backend/app/extensions/runtime.py +++ b/backend/app/extensions/runtime.py @@ -633,6 +633,7 @@ class PluginRuntime: "command_id": _spec.command_id, "arguments": arguments, "context": context, + "settings": settings, "secrets": secret_values, } }, diff --git a/backend/extensions/fixtures/mcp-echo/server.py b/backend/extensions/fixtures/mcp-echo/server.py index ba61194..f9d480f 100644 --- a/backend/extensions/fixtures/mcp-echo/server.py +++ b/backend/extensions/fixtures/mcp-echo/server.py @@ -71,8 +71,10 @@ def call_tool(request_id: int, params: dict[str, Any]) -> None: envelope = arguments.get("_notesagent") or {} command_arguments = envelope.get("arguments") or {} context = envelope.get("context") or {} + settings = envelope.get("settings") or {} secrets = envelope.get("secrets") or {} message = command_arguments.get("message") or context.get("selection") or "" + message = f"{settings.get('message_prefix', '')}{message}" respond( request_id, { diff --git a/backend/extensions/fixtures/mcp-echo/settings.yaml b/backend/extensions/fixtures/mcp-echo/settings.yaml index dfc3aa9..3ddb40e 100644 --- a/backend/extensions/fixtures/mcp-echo/settings.yaml +++ b/backend/extensions/fixtures/mcp-echo/settings.yaml @@ -1,6 +1,10 @@ section_id: mcp-fixture.general schema_version: 1 fields: + - key: message_prefix + label: Message Prefix + type: string + default: "" - key: api_key label: Fixture API Key type: secret diff --git a/backend/tests/test_extension_core.py b/backend/tests/test_extension_core.py index 25539b8..b96f648 100644 --- a/backend/tests/test_extension_core.py +++ b/backend/tests/test_extension_core.py @@ -415,6 +415,9 @@ def test_mcp_command_target_receives_scoped_context_and_declared_secret( mcp_container.plugins.put_setting_secret( "mcp-fixture", "api_key", "mcp-command-secret" ) + mcp_container.plugins.update_settings( + "mcp-fixture", 1, {"message_prefix": "Fixture: "} + ) result = await mcp_container.plugins.execute_command( "mcp-fixture.notify", {}, @@ -427,7 +430,7 @@ def test_mcp_command_target_receives_scoped_context_and_declared_secret( assert result.effect.type == "notification" assert result.effect.payload == { "level": "success", - "message": "来自选区", + "message": "Fixture: 来自选区", "secret_configured": True, } assert "mcp-command-secret" not in repr( From 1218b5cd7196e9602e6347652611d92ccb324274 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 20:03:39 +0800 Subject: [PATCH 07/13] =?UTF-8?q?fix(extension):=20=E6=94=B6=E7=B4=A7?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=91=BD=E4=BB=A4=E8=BF=90=E8=A1=8C=E6=97=B6?= =?UTF-8?q?=E5=A5=91=E7=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/app/contracts.py | 84 +++++++++++- backend/app/extensions/contributions.py | 25 +++- backend/app/extensions/runtime.py | 127 +++++++++++++++--- .../extensions/fixtures/mcp-echo/server.py | 10 +- backend/tests/test_extension_core.py | 122 ++++++++++++++++- backend/tests/test_plugin_contributions.py | 92 ++++++++++++- frontend/src/contracts/index.ts | 28 +++- frontend/src/services/pluginService.spec.ts | 3 +- 8 files changed, 455 insertions(+), 36 deletions(-) diff --git a/backend/app/contracts.py b/backend/app/contracts.py index e0d4869..f95e890 100644 --- a/backend/app/contracts.py +++ b/backend/app/contracts.py @@ -1,6 +1,6 @@ from datetime import datetime from enum import Enum -from typing import Any, Literal +from typing import Annotated, Any, Literal from pydantic import BaseModel, ConfigDict, Field, SecretStr @@ -520,15 +520,89 @@ class PluginCommandExecuteRequest(Contract): context: PluginCommandContext = Field(default_factory=PluginCommandContext) -class PluginCommandEffect(Contract): - type: Literal["none", "notification", "navigate", "refresh", "job"] = "none" - payload: dict[str, Any] = Field(default_factory=dict) +class PluginNotificationEffectPayload(Contract): + level: Literal["info", "success", "warning", "error"] = "info" + message: str = Field(min_length=1, max_length=4096) + + +class PluginNavigateEffectPayload(Contract): + route: Literal[ + "vault-entry", + "workspace", + "search", + "chat", + "agent", + "tasks", + "skills", + "plugins", + "themes", + "settings", + ] + + +class PluginRefreshEffectPayload(Contract): + scope: Literal["workspace", "commands", "settings", "plugins"] + + +class PluginJobEffectPayload(Contract): + job_id: str = Field( + min_length=1, + max_length=128, + pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]*$", + ) + + +class PluginNoEffectPayload(Contract): + pass + + +class PluginNoEffect(Contract): + type: Literal["none"] = "none" + payload: PluginNoEffectPayload = Field(default_factory=PluginNoEffectPayload) + + +class PluginNotificationEffect(Contract): + type: Literal["notification"] = "notification" + payload: PluginNotificationEffectPayload + + +class PluginNavigateEffect(Contract): + type: Literal["navigate"] = "navigate" + payload: PluginNavigateEffectPayload + + +class PluginRefreshEffect(Contract): + type: Literal["refresh"] = "refresh" + payload: PluginRefreshEffectPayload + + +class PluginJobEffect(Contract): + type: Literal["job"] = "job" + payload: PluginJobEffectPayload + + +PluginCommandEffect = Annotated[ + PluginNoEffect + | PluginNotificationEffect + | PluginNavigateEffect + | PluginRefreshEffect + | PluginJobEffect, + Field(discriminator="type"), +] + +PLUGIN_COMMAND_EFFECT_TYPES = ( + PluginNoEffect, + PluginNotificationEffect, + PluginNavigateEffect, + PluginRefreshEffect, + PluginJobEffect, +) class PluginCommandResult(Contract): command_id: str status: Literal["completed"] = "completed" - effect: PluginCommandEffect = Field(default_factory=PluginCommandEffect) + effect: PluginCommandEffect = Field(default_factory=PluginNoEffect) class PluginSettingType(str, Enum): diff --git a/backend/app/extensions/contributions.py b/backend/app/extensions/contributions.py index 7be209a..5402f42 100644 --- a/backend/app/extensions/contributions.py +++ b/backend/app/extensions/contributions.py @@ -22,6 +22,7 @@ from pydantic import BaseModel, ConfigDict, Field, model_validator from app.config import get_settings from app.contracts import ( + PLUGIN_COMMAND_EFFECT_TYPES, PluginCommand, PluginCommandContext, PluginCommandEffect, @@ -248,7 +249,7 @@ class CommandRegistry: ) self._record_audit(registered, started_at, error.code) raise error from exc - if not isinstance(effect, PluginCommandEffect): + if not isinstance(effect, PLUGIN_COMMAND_EFFECT_TYPES): error = ExtensionError( "PLUGIN_COMMAND_RESULT_INVALID", "Plugin command returned an invalid effect.", @@ -362,6 +363,28 @@ class PluginSettingsStore: secrets=secrets, ) + def runtime_values( + self, plugin_id: str, definition: PluginSettingsDefinition + ) -> dict[str, Any]: + """返回可供 Command 使用的完整普通设置，并拦截未配置的必填项。""" + + schema = self.get(plugin_id, definition) + missing = [ + field.key + for field in definition.fields + if field.required + and field.type != PluginSettingType.secret + and field.key not in schema.values + ] + if missing: + raise ExtensionError( + "PLUGIN_SETTINGS_REQUIRED", + "Required Plugin settings have not been configured.", + status_code=409, + details={"plugin_id": plugin_id, "fields": missing}, + ) + return schema.values + def update( self, plugin_id: str, diff --git a/backend/app/extensions/runtime.py b/backend/app/extensions/runtime.py index 6a5e918..960554e 100644 --- a/backend/app/extensions/runtime.py +++ b/backend/app/extensions/runtime.py @@ -9,8 +9,18 @@ from uuid import uuid4 import yaml from jsonschema import Draft202012Validator -from jsonschema.exceptions import SchemaError -from pydantic import BaseModel, ConfigDict, Field, ValidationError, create_model +from jsonschema.exceptions import ( + SchemaError, + ValidationError as JsonSchemaValidationError, +) +from pydantic import ( + BaseModel, + ConfigDict, + Field, + TypeAdapter, + ValidationError, + create_model, +) from app.agent.tools import ToolExecutionContext, ToolExecutionError, ToolRegistry from app.agent.permissions import KNOWN_PERMISSIONS @@ -20,6 +30,8 @@ from app.contracts import ( PluginCommand, PluginCommandContext, PluginCommandEffect, + PluginNoEffect, + PluginNotificationEffect, PluginCommandLocation, PluginCommandResult, PluginManifest, @@ -258,15 +270,15 @@ class DeclarativePluginHost: if handler == "echo": message = str(arguments.get("message", context.get("selection", ""))) - return PluginCommandEffect( - type="notification", + if not message: + return PluginNoEffect() + return PluginNotificationEffect( payload={"level": "info", "message": message}, ) if handler == "uppercase_selection": text = str(arguments.get("text", context.get("selection", ""))) limit = int(settings.get("result_limit", 100)) - return PluginCommandEffect( - type="notification", + return PluginNotificationEffect( payload={"level": "success", "message": text[:limit].upper()}, ) raise ExtensionError( @@ -284,6 +296,7 @@ class _PluginRecord: registered_tools: list[str] registered_commands: list[str] mcp_remote_names: dict[str, str] + mcp_command_schemas: dict[str, dict[str, Any]] class PluginRuntime: @@ -448,6 +461,7 @@ class PluginRuntime: registered_tools=[], registered_commands=[], mcp_remote_names={}, + mcp_command_schemas={}, ) self._records[manifest.plugin_id] = record return record.plugin.model_copy(deep=True) @@ -488,6 +502,8 @@ class PluginRuntime: status_code=403, details={"plugin_id": plugin_id}, ) + if record.settings_definition is not None: + self.settings.runtime_values(plugin_id, record.settings_definition) declared_tools = list(record.plugin.manifest.contributes.tools) conflicts = [name for name in declared_tools if self.registry.contains(name)] if conflicts: @@ -528,6 +544,18 @@ class PluginRuntime: self._register_mcp_tool(record, item) else: record.mcp_remote_names[item.definition.name] = item.remote_name + record.mcp_command_schemas[item.definition.name] = ( + item.definition.parameters + ) + for spec in ( + command + for command in record.commands + if command.mcp_tool == item.definition.name + ): + _validate_mcp_command_target_schema( + item.definition.parameters, + spec.command_id, + ) else: for spec in record.tools: arguments_model = _arguments_model(spec) @@ -570,10 +598,10 @@ class PluginRuntime: details={"command_id": _spec.command_id}, ) settings = ( - self.settings.get( + self.settings.runtime_values( _record.plugin.manifest.plugin_id, _record.settings_definition, - ).values + ) if _record.settings_definition is not None else {} ) @@ -624,19 +652,23 @@ class PluginRuntime: for key in _spec.secrets if (value := resolve_secret(key)) is not None } + envelope = _mcp_command_envelope( + _spec, + arguments=arguments, + context=context, + settings=settings, + secrets=secret_values, + ) + _validate_mcp_command_envelope( + _record.mcp_command_schemas[_spec.mcp_tool], + envelope, + _spec.command_id, + ) try: effect = await self.mcp.call_tool( _record.plugin.manifest.plugin_id, remote_name, - { - "_notesagent": { - "command_id": _spec.command_id, - "arguments": arguments, - "context": context, - "settings": settings, - "secrets": secret_values, - } - }, + envelope, request_id=f"command:{uuid4().hex}", ) except ToolExecutionError as exc: @@ -647,7 +679,7 @@ class PluginRuntime: details={"command_id": _spec.command_id}, ) from exc try: - return PluginCommandEffect.model_validate(effect) + return TypeAdapter(PluginCommandEffect).validate_python(effect) except ValidationError as exc: raise ExtensionError( "PLUGIN_COMMAND_RESULT_INVALID", @@ -675,6 +707,7 @@ class PluginRuntime: self.commands.unregister(command_id) record.registered_commands.clear() record.mcp_remote_names.clear() + record.mcp_command_schemas.clear() self.mcp.stop(plugin_id) record.plugin.status = PluginStatus.error record.plugin.error_message = _safe_extension_message(exc) @@ -736,6 +769,7 @@ class PluginRuntime: self.commands.unregister(command_id) record.registered_commands.clear() record.mcp_remote_names.clear() + record.mcp_command_schemas.clear() if record.plugin.manifest.backend.type == "mcp": self.mcp.stop(plugin_id) record.plugin.enabled = False @@ -814,6 +848,7 @@ class PluginRuntime: self.commands.unregister(command_id) record.registered_commands.clear() record.mcp_remote_names.clear() + record.mcp_command_schemas.clear() self.mcp.stop(plugin_id) record.plugin.enabled = False record.plugin.status = PluginStatus.installed @@ -878,6 +913,7 @@ class PluginRuntime: self.commands.unregister(command_id) record.registered_commands.clear() record.mcp_remote_names.clear() + record.mcp_command_schemas.clear() record.plugin.enabled = False record.plugin.status = PluginStatus.error record.plugin.error_message = message @@ -1030,6 +1066,61 @@ def _arguments_model(spec: DeclarativeToolSpec) -> type[BaseModel]: return _arguments_model_from_schema(spec.name, schema) +def _mcp_command_envelope( + spec: PluginCommandSpec, + *, + arguments: dict[str, Any], + context: dict[str, Any], + settings: dict[str, Any], + secrets: dict[str, str], +) -> dict[str, Any]: + return { + "_notesagent": { + "command_id": spec.command_id, + "arguments": arguments, + "context": context, + "settings": settings, + "secrets": secrets, + } + } + + +def _validate_mcp_command_envelope( + schema: dict[str, Any], + envelope: dict[str, Any], + command_id: str, +) -> None: + """执行前用目标 Tool Schema 校验包含真实业务数据的宿主信封。""" + + try: + Draft202012Validator(schema).validate(envelope) + except JsonSchemaValidationError as exc: + raise ExtensionError( + "PLUGIN_COMMAND_TARGET_SCHEMA_MISMATCH", + "MCP Command envelope does not match the target inputSchema.", + status_code=502, + details={"command_id": command_id, "path": list(exc.path)}, + ) from exc + + +def _validate_mcp_command_target_schema( + schema: dict[str, Any], command_id: str +) -> None: + """启用时只检查稳定信封入口，避免用伪造业务值误判合法 Schema。""" + + properties = schema.get("properties") + envelope_schema = ( + properties.get("_notesagent") if isinstance(properties, dict) else None + ) + if not isinstance(envelope_schema, dict) or envelope_schema.get("type") != "object": + raise ExtensionError( + "PLUGIN_CONTRIBUTION_INVALID", + "MCP Command target inputSchema must directly declare " + "_notesagent with type object.", + details={"command_id": command_id}, + ) + + def _arguments_model_from_schema( tool_name: str, schema: dict[str, Any] ) -> type[BaseModel]: diff --git a/backend/extensions/fixtures/mcp-echo/server.py b/backend/extensions/fixtures/mcp-echo/server.py index f9d480f..fed5e55 100644 --- a/backend/extensions/fixtures/mcp-echo/server.py +++ b/backend/extensions/fixtures/mcp-echo/server.py @@ -73,6 +73,15 @@ def call_tool(request_id: int, params: dict[str, Any]) -> None: context = envelope.get("context") or {} settings = envelope.get("settings") or {} secrets = envelope.get("secrets") or {} + if not isinstance(secrets.get("api_key"), str): + respond( + request_id, + { + "content": [{"type": "text", "text": "declared secret missing"}], + "isError": True, + }, + ) + return message = command_arguments.get("message") or context.get("selection") or "" message = f"{settings.get('message_prefix', '')}{message}" respond( @@ -84,7 +93,6 @@ def call_tool(request_id: int, params: dict[str, Any]) -> None: "payload": { "level": "success", "message": str(message), - "secret_configured": isinstance(secrets.get("api_key"), str), }, }, "isError": False, diff --git a/backend/tests/test_extension_core.py b/backend/tests/test_extension_core.py index b96f648..bdffc8c 100644 --- a/backend/tests/test_extension_core.py +++ b/backend/tests/test_extension_core.py @@ -17,7 +17,10 @@ from app.contracts import ( ) from app.extensions import ExtensionError from app.extensions.mcp import McpStdioClient -from app.extensions.runtime import _arguments_model_from_schema +from app.extensions.runtime import ( + _arguments_model_from_schema, + _validate_mcp_command_target_schema, +) from app.services import note_service from app.config import BACKEND_DIR, get_settings @@ -428,10 +431,9 @@ def test_mcp_command_target_receives_scoped_context_and_declared_secret( ) assert result.effect.type == "notification" - assert result.effect.payload == { + assert result.effect.payload.model_dump() == { "level": "success", "message": "Fixture: 来自选区", - "secret_configured": True, } assert "mcp-command-secret" not in repr( mcp_container.plugins.commands.audit_events() @@ -440,6 +442,120 @@ def test_mcp_command_target_receives_scoped_context_and_declared_secret( run(scenario()) +def test_mcp_command_target_rejects_incompatible_envelope_schema(tmp_path) -> None: + package = tmp_path / "mcp-bad-command" + shutil.copytree(MCP_FIXTURE, package) + for filename in ("plugin.yaml", "commands.yaml", "settings.yaml"): + path = package / filename + path.write_text( + path.read_text(encoding="utf-8").replace( + "mcp-fixture", "mcp-bad-command" + ), + encoding="utf-8", + ) + server_path = package / "server.py" + server_path.write_text( + server_path.read_text(encoding="utf-8").replace( + '{"_notesagent": {"type": "object"}}', + '{"unexpected": {"type": "string"}}', + ), + encoding="utf-8", + ) + container = build_container() + container.plugins.install(package) + container.plugins.set_permissions( + "mcp-bad-command", ["notes.read", "secrets.use"] + ) + try: + with pytest.raises(ExtensionError) as exc: + container.plugins.enable("mcp-bad-command") + assert exc.value.code == "PLUGIN_CONTRIBUTION_INVALID" + assert container.plugins.get("mcp-bad-command").status == "error" + finally: + container.plugins.shutdown() + + +def test_mcp_command_target_enable_check_only_requires_protocol_marker() -> None: + # `not`/`oneOf` 等完整语义由实际调用前的官方 Validator 处理；启用检查 + # 只确认不可被引用或组合隐藏的稳定宿主入口，避免维护不完整的求解器。 + _validate_mcp_command_target_schema( + { + "type": "object", + "properties": { + "_notesagent": { + "type": "object", + "not": {"type": "object"}, + } + }, + }, + "marker.run", + ) + + invalid_markers = [ + { + "$defs": {"envelope": {"type": "object"}}, + "properties": {"_notesagent": {"$ref": "#/$defs/envelope"}}, + }, + { + "allOf": [ + {"properties": {"_notesagent": {"type": "object"}}}, + ] + }, + ] + for schema in invalid_markers: + with pytest.raises(ExtensionError) as exc: + _validate_mcp_command_target_schema(schema, "marker.run") + assert exc.value.code == "PLUGIN_CONTRIBUTION_INVALID" + + +def test_mcp_command_validates_actual_envelope_before_call(tmp_path) -> None: + package = tmp_path / "mcp-runtime-schema" + shutil.copytree(MCP_FIXTURE, package) + for filename in ("plugin.yaml", "commands.yaml", "settings.yaml"): + path = package / filename + path.write_text( + path.read_text(encoding="utf-8").replace( + "mcp-fixture", "mcp-runtime-schema" + ), + encoding="utf-8", + ) + server_path = package / "server.py" + server_path.write_text( + server_path.read_text(encoding="utf-8").replace( + '{"_notesagent": {"type": "object"}}', + '{"_notesagent": {"type": "object", "properties": ' + '{"arguments": {"type": "object", "maxProperties": 0}, ' + '"context": {"type": "object", "properties": ' + '{"selection": {"type": "string"}}, "required": ["selection"]}}, ' + '"required": ["arguments", "context"]}}', + ), + encoding="utf-8", + ) + container = build_container() + container.plugins.install(package) + container.plugins.set_permissions( + "mcp-runtime-schema", ["notes.read", "secrets.use"] + ) + try: + # context.selection 是 Command 的 when/context 契约保证的真实字段； + # 启用期结构检查不得因没有伪造该业务值而拒绝目标 Schema。 + container.plugins.enable("mcp-runtime-schema") + container.plugins.put_setting_secret( + "mcp-runtime-schema", "api_key", "configured" + ) + with pytest.raises(ExtensionError) as exc: + run( + container.plugins.execute_command( + "mcp-runtime-schema.notify", + {"message": "must be rejected locally"}, + PluginCommandContext(selection="visible"), + ) + ) + assert exc.value.code == "PLUGIN_COMMAND_TARGET_SCHEMA_MISMATCH" + finally: + container.plugins.shutdown() + + def test_agent_calls_mcp_tool_through_registry_and_writes_trace(mcp_container) -> None: async def scenario() -> None: mcp_container.plugins.enable("mcp-fixture") diff --git a/backend/tests/test_plugin_contributions.py b/backend/tests/test_plugin_contributions.py index def7204..1235d6f 100644 --- a/backend/tests/test_plugin_contributions.py +++ b/backend/tests/test_plugin_contributions.py @@ -3,6 +3,7 @@ import json from pathlib import Path import pytest +from pydantic import TypeAdapter, ValidationError from app.agent import ToolRegistry from app.config import BACKEND_DIR, get_settings @@ -10,6 +11,7 @@ from app.container import build_container from app.contracts import ( PluginCommandContext, PluginCommandEffect, + PluginNoEffect, PluginSettingType, ) from app.extensions import ExtensionError, PluginRuntime @@ -70,7 +72,40 @@ def test_command_executes_with_scoped_context_and_settings() -> None: assert result.status == "completed" assert result.effect.type == "notification" - assert result.effect.payload == {"level": "success", "message": "ABCD"} + assert result.effect.payload.model_dump() == { + "level": "success", + "message": "ABCD", + } + + +def test_echo_command_returns_none_for_empty_message() -> None: + host = DeclarativePluginHost() + + empty = run(host.execute_command("echo", {}, {}, {}, lambda _: None)) + populated = run( + host.execute_command("echo", {"message": "hello"}, {}, {}, lambda _: None) + ) + + assert isinstance(empty, PluginNoEffect) + assert populated.type == "notification" + assert populated.payload.message == "hello" + + +@pytest.mark.parametrize( + ("effect_type", "payload"), + [ + ("none", {"unexpected": True}), + ("notification", {"level": "debug", "message": "invalid"}), + ("navigate", {"route": "https://example.com"}), + ("refresh", {"scope": "everything"}), + ("job", {"job_id": "invalid job id"}), + ], +) +def test_command_effect_rejects_untrusted_payloads(effect_type, payload) -> None: + with pytest.raises(ValidationError): + TypeAdapter(PluginCommandEffect).validate_python( + {"type": effect_type, "payload": payload} + ) def test_command_rejects_missing_context_and_invalid_arguments() -> None: @@ -112,7 +147,7 @@ def test_command_only_receives_declared_context() -> None: self, handler, arguments, context, settings, resolve_secret ): self.context = context - return PluginCommandEffect(type="none") + return PluginNoEffect() host = CapturingHost() runtime = PluginRuntime(ToolRegistry(), host=host) @@ -146,7 +181,7 @@ def test_command_resolves_only_declared_plugin_secrets(tmp_path: Path) -> None: resolve_secret("undeclared") except ExtensionError as exc: self.denied_code = exc.code - return PluginCommandEffect(type="none") + return PluginNoEffect() host = SecretHost() runtime = PluginRuntime(ToolRegistry(), host=host) @@ -248,6 +283,57 @@ def test_settings_update_validates_version_type_bounds_and_secret_boundary() -> assert exc.value.code == code +def test_required_plain_setting_blocks_enable_until_configured(tmp_path: Path) -> None: + package = tmp_path / "required-setting" + package.mkdir() + (package / "plugin.yaml").write_text( + """ +id: required-setting +name: Required Setting +version: 1.0.0 +contributes: + commands: [required-setting.run] + settings_sections: [required-setting.general] +backend: + type: internal_rpc + transport: none +""".strip(), + encoding="utf-8", + ) + (package / "commands.yaml").write_text( + """ +commands: + - command_id: required-setting.run + title: Required Setting + locations: [command_palette] + handler: echo +""".strip(), + encoding="utf-8", + ) + (package / "settings.yaml").write_text( + """ +section_id: required-setting.general +schema_version: 1 +fields: + - key: endpoint + label: Endpoint + type: string + required: true +""".strip(), + encoding="utf-8", + ) + runtime = PluginRuntime(ToolRegistry()) + runtime.install(package) + + with pytest.raises(ExtensionError) as exc: + runtime.enable("required-setting") + assert exc.value.code == "PLUGIN_SETTINGS_REQUIRED" + assert runtime.get("required-setting").status == "installed" + + runtime.update_settings("required-setting", 1, {"endpoint": "local"}) + assert runtime.enable("required-setting").status == "ready" + + def test_secret_roundtrip_never_enters_plain_settings_storage() -> None: container = build_container() plaintext = "stage-d-secret-value" diff --git a/frontend/src/contracts/index.ts b/frontend/src/contracts/index.ts index b7a5e0a..901cf43 100644 --- a/frontend/src/contracts/index.ts +++ b/frontend/src/contracts/index.ts @@ -292,10 +292,30 @@ export interface PluginCommandContext { selection?: string | null } -export interface PluginCommandEffect { - type: 'none' | 'notification' | 'navigate' | 'refresh' | 'job' - payload: Record -} +export type PluginCommandEffect = + | { type: 'none'; payload: Record } + | { + type: 'notification' + payload: { level: 'info' | 'success' | 'warning' | 'error'; message: string } + } + | { + type: 'navigate' + payload: { + route: + | 'vault-entry' + | 'workspace' + | 'search' + | 'chat' + | 'agent' + | 'tasks' + | 'skills' + | 'plugins' + | 'themes' + | 'settings' + } + } + | { type: 'refresh'; payload: { scope: 'workspace' | 'commands' | 'settings' | 'plugins' } } + | { type: 'job'; payload: { job_id: string } } export interface PluginCommandResult { command_id: string diff --git a/frontend/src/services/pluginService.spec.ts b/frontend/src/services/pluginService.spec.ts index 612779a..8239921 100644 --- a/frontend/src/services/pluginService.spec.ts +++ b/frontend/src/services/pluginService.spec.ts @@ -26,7 +26,7 @@ describe('pluginService contribution adapter', () => { .mockResolvedValueOnce(jsonResponse({ command_id: 'text-tools.uppercase-selection', status: 'completed', - effect: { type: 'notification', payload: { message: 'HELLO' } }, + effect: { type: 'notification', payload: { level: 'success', message: 'HELLO' } }, })) const commands = await pluginService.listPluginCommands('command_palette') @@ -37,6 +37,7 @@ describe('pluginService contribution adapter', () => { ) expect(commands[0].command_id).toBe('text-tools.uppercase-selection') + if (result.effect.type !== 'notification') throw new Error('expected notification effect') expect(result.effect.payload.message).toBe('HELLO') expect(fetchMock.mock.calls[0][0]).toBe( '/api/plugin-contributions/commands?location=command_palette', From 0bbff0090e2b082cce5718e3c125deb483d6c3d5 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Wed, 2 Sep 2026 20:22:06 +0800 Subject: [PATCH 08/13] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E7=AC=AC?= =?UTF-8?q?=E4=BA=8C=E9=98=B6=E6=AE=B5=E8=BF=9B=E5=BA=A6=E4=B8=8E=E6=89=A9?= =?UTF-8?q?=E5=B1=95=E5=A4=8D=E7=9B=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 7 ++++--- backend/README.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 7026ca3..a8b7637 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > 本文件用于团队开发期间快速配置环境和启动项目，不是正式的项目 README。 -> 当前基线：2026-08-30。第一阶段 Web 联调版的前端页面、Knowledge/Retrieval Core、AI/Agent Core、Extension Core、Provider 预设与本地加密凭据链路均已实现；Tauri Host、Stronghold、真实桌面文件系统和 Sync Server 尚未接入。 +> 当前基线：2026-09-02。第一阶段 Web 联调前后端已经完成；第二阶段已完成 Workspace 去 Mock、Agent Trace 持久化与 SSE 恢复、stdio MCP Bridge、隔离 Plugin Host，以及 Plugin Command/Settings 后端 Contract 和前端 Service。真实音频、Provider 协议增强、Benchmark、导出、主题包、Trace 可视化、Mermaid 与函数图像仍在后续开发；Tauri Host、Stronghold、原生多 Vault 文件系统和 Sync Server 尚未接入。 ## 当前目录 @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 126 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 136 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 @@ -134,6 +134,7 @@ pnpm test | [AI Core 与 Agent Core](docs/development/AI-Core与Agent-Core开发说明.md) | Provider、Agent、Tool、Permission 与 Extension Core | | [MCP Bridge 与 Plugin Host](docs/development/MCP-Bridge与Plugin-Host开发说明.md) | stdio MCP、隔离进程、Tool 映射、状态与错误边界 | | [Plugin Command 与 Settings](docs/development/Plugin-Command与Settings开发说明.md) | Command Registry、Settings Schema、Secret 引用与联调边界 | +| [Plugin Command 与 Settings 复盘](docs/retrospectives/Plugin-Command与Settings问题与修复复盘.md) | 阶段 D 连续审阅发现的安全、事务、Schema 与运行时契约问题 | | [Git 使用细则](docs/guides/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 | | [CI/CD 细则](docs/guides/CI-CD细则-团队开发版.md) | Gitea 流水线、质量门禁、产物、发布与回滚规则 | | [Agent Trace 复盘](docs/retrospectives/Agent-Core第二阶段问题与修复复盘.md) | Agent 持久化、SSE 恢复、事件契约与脱敏问题复盘 | @@ -147,6 +148,6 @@ pnpm test - 后端附件目录默认是 `backend/data/attachments`，可通过 `APP_ATTACHMENTS_PATH` 覆盖；该目录由桌面 Host 管理。 - 跨模块接口发生变化时，需要同步更新前后端类型和 `docs` 中的接口说明。 - 当前已实现接口见 `docs/contracts/后端接口契约-开发版.md`，第二阶段规划接口见 `docs/contracts/第二阶段接口契约-开发版.md`；已实现能力以 `/openapi.json` 为准。 -- 前端页面、交互、状态管理和第一阶段验收要求见 `docs/contracts/前端页面需求说明-开发版.md`。 +- 前端页面、交互、状态管理及当前阶段后续页面需求见 `docs/contracts/前端页面需求说明-开发版.md`。 - 分支、提交、Pull Request、Review 和冲突处理规范见 `docs/guides/Git使用细则-团队开发版.md`。 - CI 检查、产物、发布和回滚规范见 `docs/guides/CI-CD细则-团队开发版.md`。 diff --git a/backend/README.md b/backend/README.md index a087fa7..a857f76 100644 --- a/backend/README.md +++ b/backend/README.md @@ -23,7 +23,7 @@ uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 uv run pytest ``` -当前基线为 126 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 +当前基线为 136 项测试通过。Provider API Key 可通过前端设置页写入，也可用 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY` 或 `AINOTE_CREDENTIAL_` 注入；不要把真实密钥写入仓库。`plugin.*` 是 Plugin Settings 的保留凭据命名空间，通用 Provider 凭据接口不能读写。 团队接口清单见 `../docs/contracts/后端接口契约-开发版.md`，机器可读契约以运行时的 `/openapi.json` 为准。 From 0c392eebe41f000ff5aff4e85e98c75ba9ea5f77 Mon Sep 17 00:00:00 2001 From: KiriAky 107 Date: Thu, 3 Sep 2026 14:22:29 +0800 Subject: [PATCH 09/13] feat(frontend): complete MCP plugin management UI --- README.md | 2 +- .../components/common/CommandPalette.spec.ts | 77 +++++ .../src/components/common/CommandPalette.vue | 95 +++++- frontend/src/components/common/TitleBar.vue | 2 +- .../src/features/editor/EditorPane.spec.ts | 3 + .../features/plugins/PluginMcpPanel.spec.ts | 109 +++++++ .../src/features/plugins/PluginMcpPanel.vue | 275 ++++++++++++++++++ frontend/src/features/plugins/PluginsView.vue | 4 +- .../features/workspace/FileTreePanel.spec.ts | 7 +- frontend/src/router/index.ts | 12 +- .../src/services/workspaceService.spec.ts | 2 +- frontend/src/services/workspaceService.ts | 14 +- frontend/src/stores/editor.ts | 6 +- frontend/src/stores/workspace.ts | 6 +- 14 files changed, 596 insertions(+), 18 deletions(-) create mode 100644 frontend/src/components/common/CommandPalette.spec.ts create mode 100644 frontend/src/features/plugins/PluginMcpPanel.spec.ts create mode 100644 frontend/src/features/plugins/PluginMcpPanel.vue diff --git a/README.md b/README.md index a8b7637..cd85754 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ cd frontend pnpm test ``` -当前回归基线为后端 136 项测试、前端 29 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 +当前回归基线为后端 136 项测试、前端 32 项测试，且 TypeScript 类型检查和生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。 构建产物位于 `frontend/dist`，该目录不提交到 Git。 diff --git a/frontend/src/components/common/CommandPalette.spec.ts b/frontend/src/components/common/CommandPalette.spec.ts new file mode 100644 index 0000000..114cd32 --- /dev/null +++ b/frontend/src/components/common/CommandPalette.spec.ts @@ -0,0 +1,77 @@ +// @vitest-environment happy-dom +import { flushPromises, mount } from '@vue/test-utils' +import { createPinia, setActivePinia } from 'pinia' +import { createMemoryHistory, createRouter } from 'vue-router' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import * as pluginService from '@/services/pluginService' +import { useEditorStore } from '@/stores/editor' +import { useWorkspaceStore } from '@/stores/workspace' +import CommandPalette from './CommandPalette.vue' + +vi.mock('@/services/pluginService', async (loadOriginal) => { + const original = await loadOriginal() + return { ...original, listPluginCommands: vi.fn(), executePluginCommand: vi.fn() } +}) + +beforeEach(() => { + setActivePinia(createPinia()) + vi.mocked(pluginService.listPluginCommands).mockResolvedValue([{ + command_id: 'demo.selection', + plugin_id: 'demo', + title: '处理选区', + description: '', + icon: null, + locations: ['command_palette'], + when: ['workspace.has_vault', 'editor.has_note', 'editor.has_selection'], + parameters: { type: 'object', properties: {}, additionalProperties: false }, + enabled: true, + }]) + vi.mocked(pluginService.executePluginCommand).mockResolvedValue({ + command_id: 'demo.selection', + status: 'completed', + effect: { type: 'notification', payload: { level: 'success', message: '完成' } }, + }) +}) + +afterEach(() => { + document.body.innerHTML = '' + vi.restoreAllMocks() +}) + +describe('CommandPalette Plugin Command', () => { + it('filters by when context and sends stable backend identities plus the captured selection', async () => { + const workspace = useWorkspaceStore() + workspace.hasVault = true + workspace.vaultId = 'vault-default' + const editor = useEditorStore() + editor.currentNoteId = 'note-1' + editor.currentFilePath = '/note.md' + + vi.spyOn(window, 'getSelection').mockReturnValue({ + toString: () => 'selected text', + } as Selection) + + const router = createRouter({ + history: createMemoryHistory(), + routes: [{ path: '/', component: { template: '
' } }], + }) + await router.push('/') + const wrapper = mount(CommandPalette, { attachTo: document.body, global: { plugins: [router] } }) + + window.dispatchEvent(new KeyboardEvent('keydown', { key: 'p', ctrlKey: true })) + await flushPromises() + const command = Array.from(document.querySelectorAll('button')).find((button) => button.textContent?.includes('处理选区')) + expect(command).toBeTruthy() + command!.click() + await flushPromises() + + expect(pluginService.executePluginCommand).toHaveBeenCalledWith('demo.selection', {}, { + vault_id: 'vault-default', + note_id: 'note-1', + file_path: '/note.md', + selection: 'selected text', + }) + expect(document.body.textContent).toContain('完成') + wrapper.unmount() + }) +}) diff --git a/frontend/src/components/common/CommandPalette.vue b/frontend/src/components/common/CommandPalette.vue index 9ab6aa5..b5a99f6 100644 --- a/frontend/src/components/common/CommandPalette.vue +++ b/frontend/src/components/common/CommandPalette.vue @@ -5,18 +5,26 @@ import { useEditorStore } from '@/stores/editor' import { useThemeStore } from '@/stores/theme' import { useWorkspaceStore } from '@/stores/workspace' import * as workspaceService from '@/services/workspaceService' +import * as pluginService from '@/services/pluginService' +import type { PluginCommand, PluginCommandEffect } from '@/contracts' +import { usePluginStore } from '@/stores/plugin' const router = useRouter() const editorStore = useEditorStore() const themeStore = useThemeStore() const workspaceStore = useWorkspaceStore() +const pluginStore = usePluginStore() const open = ref(false) const query = ref('') const input = ref(null) +const pluginCommands = ref([]) +const commandError = ref('') +const commandNotice = ref('') +const selectionSnapshot = ref(null) interface Command { id: string; label: string; hint: string; run: () => void | Promise } -const commands = computed(() => [ +const builtinCommands = computed(() => [ { id: 'workspace', label: '打开工作区', hint: '导航', run: () => router.push('/workspace') }, { id: 'search', label: '全局搜索', hint: '导航', run: () => router.push('/search') }, { id: 'chat', label: '打开 AI 对话', hint: '导航', run: () => router.push('/chat') }, @@ -28,14 +36,37 @@ const commands = computed(() => [ { id: 'new-note', label: '创建笔记', hint: '工作区', run: createNote }, ]) +const commands = computed(() => [ + ...builtinCommands.value, + ...pluginCommands.value.filter(isPluginCommandAvailable).map((command) => ({ + id: 'plugin:' + command.command_id, + label: command.title, + hint: 'Plugin · ' + command.plugin_id, + run: () => executePluginCommand(command), + })), +]) + +function isPluginCommandAvailable(command: PluginCommand) { + if (!command.enabled) return false + return command.when.every((condition) => { + if (condition === 'workspace.has_vault') return Boolean(workspaceStore.vaultId) + if (condition === 'editor.has_note') return Boolean(editorStore.currentNoteId) + if (condition === 'editor.has_selection') return Boolean(selectionSnapshot.value) + return false + }) +} + const filteredCommands = computed(() => { const value = query.value.trim().toLocaleLowerCase() return value ? commands.value.filter((command) => `${command.label} ${command.hint}`.toLocaleLowerCase().includes(value)) : commands.value }) function show() { + selectionSnapshot.value = window.getSelection()?.toString() || null open.value = true query.value = '' + commandError.value = '' + void loadPluginCommands() void nextTick(() => input.value?.focus()) } @@ -44,7 +75,11 @@ function hide() { open.value = false } async function execute(command: Command | undefined) { if (!command) return hide() - await command.run() + try { + await command.run() + } catch (error) { + commandNotice.value = error instanceof Error ? error.message : '命令执行失败' + } } async function createNote() { @@ -58,6 +93,55 @@ async function createNote() { await router.push('/workspace') } +async function loadPluginCommands() { + try { + pluginCommands.value = await pluginService.listPluginCommands('command_palette') + } catch (error) { + commandError.value = error instanceof Error ? error.message : 'Plugin 命令加载失败' + } +} + +function hasRequiredArguments(command: PluginCommand) { + return Array.isArray(command.parameters.required) && command.parameters.required.length > 0 +} + +async function executePluginCommand(command: PluginCommand) { + if (hasRequiredArguments(command)) { + pluginStore.selectPlugin(command.plugin_id) + await router.push('/extensions/plugins') + commandNotice.value = '请在 Plugin 详情页填写参数后执行“' + command.title + '”。' + return + } + const result = await pluginService.executePluginCommand(command.command_id, {}, { + vault_id: workspaceStore.hasVault ? workspaceStore.vaultId : null, + note_id: editorStore.currentNoteId, + file_path: editorStore.currentFilePath, + selection: selectionSnapshot.value, + }) + await applyPluginEffect(result.effect) +} + +async function applyPluginEffect(effect: PluginCommandEffect) { + if (effect.type === 'notification') { commandNotice.value = effect.payload.message; return } + if (effect.type === 'navigate') { + const routes: Record = { + 'vault-entry': '/', workspace: '/workspace', search: '/search', chat: '/chat', + agent: '/agent/runs', tasks: '/tasks', skills: '/extensions/skills', + plugins: '/extensions/plugins', themes: '/themes', settings: '/settings', + } + await router.push(routes[effect.payload.route]) + return + } + if (effect.type === 'refresh') { + if (effect.payload.scope === 'plugins') await pluginStore.loadPlugins() + if (effect.payload.scope === 'commands') await loadPluginCommands() + commandNotice.value = '相关数据已刷新。' + return + } + if (effect.type === 'job') { commandNotice.value = '后台任务已创建：' + effect.payload.job_id; return } + commandNotice.value = 'Plugin 命令执行完成。' +} + function handleKeydown(event: KeyboardEvent) { if ((event.ctrlKey || event.metaKey) && event.key.toLocaleLowerCase() === 'p') { event.preventDefault() @@ -72,10 +156,14 @@ onBeforeUnmount(() => window.removeEventListener('keydown', handleKeydown))