RFCs

插件热加载与自定义接口

查看 Markdown

概要

本提案在 插件接口 RFC #2549 之上增加三项能力:

  • 热加载:每个 Server 进程定期扫描插件目录,发现新增、更新或移除的插件后在运行中生效,不需要重启 Server。 检查通过的每个版本都会被复制成一份按内容摘要命名的只读快照,宿主进程和 Worker 只从快照导入。更新插件就是让新的 子进程使用新快照,不在已运行的 Python 进程中替换模块,正在执行的调用也不会读到新代码。
  • 插件自定义接口:插件可以声明自己的 HTTP 路由,core 把它们挂载到独立的分组 /v1/plugins/{name}/api/... 下, 完成认证和所需的授权检查后,把请求交给插件的宿主进程处理。插件可以选择把路由同时作为 MCP 工具提供给 Agent。插件的 Artifact 仍然可以通过通用 Artifact 接口读取和检索。
  • 插件页面:插件可以随代码提供静态页面,在 Dashboard 中以沙箱 iframe 展示;页面通过宿主页面转发调用本插件的接口, 拿不到用户的会话。

部署者仍然只需要把插件目录放到 POWERCONTEXT_SERVER_PLUGINS_DIR 下;core 不在数据库中保存插件状态,也不分发插件代码。

本文描述目标设计,不代表主线或发布版本已经可用。接口名称和代码示例用于说明契约,最终语法以实现为准。

动机

RFC #2549 定义了插件接口,但有两处限制:

  • 变更需要重启:新增、更新或移除插件都要重启 Server,期间所有接口短暂不可用。插件迭代频繁时,这对共享的中心记忆 服务影响很大。

  • 只能通过现有接口使用插件:调用方只能使用 core 已有的 Source 和 Artifact 接口。很多插件需要领域专用的操作,例如:

    • 文档知识库需要创建知识库、上传文件、读取原始文件,以及跨多个知识库的混合检索;
    • 插件需要给用户展示自己的处理进度、配置或检索结果页面。

    这些操作放进 core 的通用接口并不合适,插件又没有别的入口。

RFC #2549 已经为热加载和自定义接口铺好了基础:

  • Server 进程不导入插件代码,同步调用在 core 管理的宿主进程中执行,后台调用每次启动新的 Worker;
  • 每个 Server 进程在内存中维护已激活插件的记录,不持久化插件状态。

旧版 Artifact 插件框架(RFC #2175)的热加载依赖持久化的期望状态、管理阶段和注册代次。本提案不重新引入这些机制: 插件集合由目录内容决定,切换只发生在子进程层面。

目标:

  1. 部署者把插件目录放入、替换或移出,Server 在两个扫描周期内生效(内容需要连续两次扫描相同才检查),不需要重启,也不需要调用管理接口。
  2. 每次调用从开始到结束只使用一个版本的插件代码,不会出现新旧代码混用,也不会出现用新声明提交旧代码结果的情况。
  3. 插件可以声明自己的 HTTP 接口;core 负责路由、认证、授权、请求大小和时限,插件只写处理函数。
  4. 插件接口对核心数据的写入与 RFC #2549 的用户修改遵循同样的权限和溯源规则。
  5. 插件页面拿不到用户的 PowerContext 会话。它只能请 Dashboard 以当前用户的身份调用本插件的接口和本插件 family 的通用 Artifact 接口,不能借用户会话调用其他 Server 接口。

指南级说明

1. 热加载

部署者直接操作插件目录:

操作效果
放入新的插件目录下一次扫描时检查并加载;检查通过后,Source 类型、family、接口和页面开始可用
替换已有插件目录的内容下一次扫描时重新检查;通过后,新的同步调用和后台调用使用新版本,进行中的调用按旧版本完成
移出插件目录下一次扫描时卸载;Source 类型、family、接口和页面不再可用,已保存的数据保留
  • 生效时间:每个 Server 进程每隔 POWERCONTEXT_SERVER_PLUGINS_RESCAN_SECONDS(默认 60 秒)扫描一次。插件数量多、 目录大时可以调大;设为 0 时关闭热加载,行为与 RFC #2549 相同。
  • 替换要整体完成:同一个插件目录在两次连续扫描中内容不变,才会被检查。部署者应先把新版本写到临时目录,再整体改名 替换,避免扫描到写了一半的文件。
  • 更新失败时继续使用旧版本:新版本检查失败时,该插件继续以当前版本运行,同时记录检查失败的事件;修复后的版本被扫描到 时再切换。新放入的插件检查失败时不加载。
  • 依赖要先装好:插件依赖安装在 Server 的 Python 环境中,不在插件目录里,扫描检测不到依赖的变化。新版本需要新的依赖时, 部署者应先安装依赖,再替换插件目录。
  • 多实例:每个 Server 实例各自扫描自己机器上的插件目录。代码由部署者分发到各实例;在各实例都完成扫描之前,不同实例 可能短暂使用不同版本。
  • 数据升级由插件负责:插件可以在声明中提供 upgrade(ctx),core 在每次加载一个插件版本时调用一次,由插件自己判断 是否需要升级、怎样升级。插件数据存在哪里、是什么格式,core 不知道,也不检查兼容性;新版本读不了或消费不了旧数据,由 插件负责。插件可以在代码中兼容旧格式,也可以在 upgrade 中统一改写,或者两者结合。

2. 插件自定义接口

插件在声明中加上 api,列出自己的路由;处理函数是 setup(ctx) 返回对象上的方法。下面的文档插件把每个知识库对应为 一个 Scope:创建知识库就是创建一个 Scope,上传的文件存进插件存储,Source 只记录位置和摘要:

from pydantic import BaseModel

from powercontext.plugins import ApiError, ApiRequest, ArtifactPlugin, BinaryResponse, PluginApi, Rendering, Route


class NewKnowledgeBase(BaseModel):
    title: str
    summary: str
    idempotency_key: str


class KnowledgeBase(BaseModel):
    scope_id: str


class UploadResult(BaseModel):
    source_id: str


class Documents:
    def __init__(self, ctx) -> None:
        self.ctx = ctx

    async def render_artifact(self, request) -> Rendering:
        return Rendering(text="# " + request.artifact.content["name"])

    async def create_knowledge_base(self, request: ApiRequest) -> KnowledgeBase:
        body: NewKnowledgeBase = request.body
        # 以调用者身份创建 Scope,权限与 POST /v1/scopes 相同(server.admin)
        scope = await self.ctx.scopes.create(title=body.title, summary=body.summary,
                                             idempotency_key=body.idempotency_key)
        return KnowledgeBase(scope_id=scope.scope_id)

    async def upload(self, request: ApiRequest) -> UploadResult:
        # 原始字节按内容摘要存进插件存储,Source 只记录位置和摘要
        location, digest = await save_original(self.ctx.storage, request.scope_id, request.body)
        ref = await self.ctx.sources.submit(
            request.scope_id, "document-input",
            DocumentInput(location=location, sha256=digest, name=request.query["name"][0]),
        )
        return UploadResult(source_id=ref.source_id)

    async def original(self, request: ApiRequest) -> BinaryResponse:
        # 专属存储不按 Scope 隔离:按 (scope_id, source_id) 查找,不属于该知识库的文件视为不存在
        found = await load_original(self.ctx.storage, request.scope_id, request.path_params["source_id"])
        if found is None:
            raise ApiError(404, "document_not_found", "document not found in this knowledge base")
        return BinaryResponse(content=found.content, content_type=found.media_type)


async def setup(ctx) -> Documents:
    return Documents(ctx)


plugin = ArtifactPlugin(
    family="kb-document",
    definitions=(DocumentInputDefinition(),),
    api=PluginApi(routes=(
        Route(method="POST", path="/knowledge-bases", handler="create_knowledge_base", access="authenticated",
              body="json", request_model=NewKnowledgeBase, response_model=KnowledgeBase),
        Route(method="POST", path="/knowledge-bases/{kb_id}/documents", handler="upload",
              access="scope.contribute", scope_param="kb_id", body="binary", response_model=UploadResult),
        Route(method="GET", path="/knowledge-bases/{kb_id}/documents/{source_id}/original", handler="original",
              access="scope.read", scope_param="kb_id"),
    )),
    setup=setup,
)

调用方这样使用:

POST /v1/plugins/documents/api/knowledge-bases                                    (JSON 请求体)
POST /v1/plugins/documents/api/knowledge-bases/{kb_id}/documents?name=sop.md      (请求体为文件字节)
GET  /v1/plugins/documents/api/knowledge-bases/{kb_id}/documents/{source_id}/original
GET  /v1/plugins/documents/openapi.json                                            (该插件接口的 OpenAPI 描述)
  • 插件路由是独立的一组,挂在 /v1/plugins/{name}/api/ 下,路径由插件决定,不与 core 的路由混在一起。
  • core 先认证调用者,再按路由声明的 access 检查权限:
    • scope.read、scope.contribute:scope_param 指定哪个路径参数是 Scope ID,core 检查调用者对它的权限后才调用插件;
    • authenticated:只要求调用者已登录,处理函数需要的其他权限用 ctx.require(...) 检查,例如跨多个知识库检索时逐个 检查各 Scope。
  • 处理函数可以读写核心数据,规则与 RFC #2549 的用户修改相同:写入以调用者身份进行,core 检查权限并记录溯源。
  • 插件可以以调用者身份创建 Scope,权限与 POST /v1/scopes 相同,需要 server.admin。
  • 插件 family 的 Artifact 仍然通过通用 Artifact 接口浏览、读取、检索和修改;插件接口只补充领域专用的操作。
  • 插件接口不属于 openapi/powercontext.yaml,生成的客户端不包含它们;每个插件的接口描述由 core 根据声明生成。
  • 路由声明 mcp=True 时,core 同时把它作为 MCP 工具提供,Agent 可以像调用内置工具一样调用,例如跨知识库检索。

3. 插件页面

插件在声明中加上 pages,指向插件目录中的静态文件:

from powercontext.plugins import PluginPages

plugin = ArtifactPlugin(
    ...,
    pages=PluginPages(directory="ui", entry="index.html", title={"zh": "文档", "en": "Documents"}),
)
  • Dashboard 导航中出现该插件的页面。打开后,Dashboard 在当前 Scope 下以沙箱 iframe 加载插件页面。
  • 插件页面运行在不透明来源中,读不到 Dashboard 的 cookie,直接请求 Server 时也不会带上用户会话。调用本插件的接口时, 页面通过 postMessage 请 Dashboard 转发,Dashboard 以当前登录用户的身份调用。
  • 页面可以链接、跳转或在新窗口中打开外部站点,例如把检索结果交给外部的 RAG 服务页面展示。插件是可信代码,页面访问外部 站点不受限制;core 只保证页面借不到用户的 PowerContext 会话。
  • Artifact 插件的页面还可以调用本插件 family 的通用 Artifact 接口(RFC #2549):读取、历史、治理状态、新建、编辑、合并、 遗忘、恢复和 tags。这些调用同样由 Dashboard 以当前用户的身份转发,与直接调用通用接口等价:权限、版本前置条件和溯源 都由 core 处理,修改交给插件的用户修改方法。页面不需要为此声明路由。
  • 页面只能是静态文件(HTML、JavaScript、CSS、图片、字体),由 core 直接从插件的当前版本快照提供,不运行插件代码。

页面中的调用:

const client = powercontextPluginClient();            // 由 core 提供的小脚本,封装 postMessage
const { scopeId } = await client.context();
const result = await client.request("GET", `/knowledge-bases/${scopeId}/documents/${sourceId}/original`);

// 本插件 family 的通用 Artifact 接口;路径接在 /v1/scopes/{scopeId}/artifacts/{family} 之后
const document = await client.artifacts("GET", `/${artifactId}`, { scopeId });
await client.artifacts("PUT", `/${artifactId}`, { scopeId, json: { content }, ifMatch: document.etag });

参考级说明

1. 热加载

1.1 扫描与检查

  • 每个 Server 进程启动时和每隔扫描间隔,为插件目录的每个直接子目录计算内容摘要。

  • 摘要与当前版本相同则跳过;与上一次扫描不同时先等待,连续两次扫描相同、且与当前版本不同时才检查,避免检查写了一半的 目录。

  • 检查与 RFC #2549 的启动检查相同,在版本快照上执行(见 1.3);根据结果新增、更新或卸载插件。

  • 摘要按文件内容计算,与 RFC #2549 的代码指纹相同。只看文件大小和修改时间不够:用时间戳归一化的归档解压出的新版本, 大小和修改时间可能与旧版本完全相同。

  • 扫描成本与插件目录的总字节数成正比。在 2 核开发机上,对 14 MB、676 个文件计算一次摘要约需 230 ms;插件目录不包含依赖, 通常远小于此。每次扫描的耗时记录在指标中,部署者可以据此调整扫描间隔。

  • 声明摘要由检查子进程对可序列化的声明部分计算,记录在已激活插件记录中,用于判断声明是否变化。

  • 启动时的第一次扫描不需要等待稳定,与 RFC #2549 的启动加载相同。

1.2 切换

情况处理
新增,检查通过注册 Source 类型、family(读取、检索、合并注册表)、自定义接口和页面;本进程是 Supervisor 领导者时注册 binding
新增,检查失败不加载,记录检查失败;GET /v1/plugins 中该插件为 failed
更新,检查通过,声明不变切换到新快照:替换宿主进程(见 1.4);后台调用从下一次派发起使用新快照
更新,检查通过,声明改变按新声明重新注册:新增的 Source 类型、路由、页面生效,移除的不再可用;binding 的调度参数按新声明更新;切换到新快照
更新,检查失败继续使用当前快照,记录检查失败;GET /v1/plugins 中给出最近一次检查失败的分类
移除注销 Source 类型、family、接口、页面和 binding;等待进行中的同步调用结束或超时后停止宿主进程
  • family 改名等同于移除旧 family、新增新 family。旧 family 的 Artifact 保留在 core 中,处理方式与 RFC #2549 中停用插件相同。
  • 移除的 Source 类型不再接受写入,返回 422;已保存的 Source 保留。
  • 移除插件后遗留的调用意图不再被处理,规则与 RFC #2549 的执行约束相同;同名插件重新放入后从原游标和 checkpoint 继续。
  • Supervisor 的 binding 由领导者进程注册。领导权转移时,新领导者按自己的已激活插件记录注册 binding。

1.3 版本快照

插件目录由部署者随时修改,不能直接从中导入:替换目录后,已经运行的进程中尚未执行的延迟导入会读到新文件,一次调用里就会 混用新旧代码。因此插件代码只从版本快照导入:

  • 生成:摘要稳定后,core 把插件目录复制成数据目录下的只读快照,以内容摘要命名,在快照上执行检查。依赖不在插件目录中, 快照通常很小。
  • 使用:检查子进程、宿主进程和 Worker 都把快照目录加入导入路径,ctx.plugin_dir 指向快照;页面的静态文件也从当前 快照提供。插件目录本身只用于扫描。
  • 取代代码指纹核对:RFC #2549 中 Worker 和宿主进程在导入前核对代码指纹。有了快照,派发时直接把快照路径交给 Worker, 快照不会被修改,不再需要核对;热加载关闭时,仍按 RFC #2549 的规则核对。
  • 清理:每个 Server 进程只删除自己生成、且既不是当前版本、也没有本进程的宿主进程或 Worker 在使用的快照,在下一次 扫描中删除。Server 启动时只删除早于本进程启动时间、且不是任何当前版本的快照。同一台机器上的多个 Server 进程(例如 api 与 background 角色)共用数据目录时,一个进程启动不会删掉另一个进程正在使用的快照。快照是本机的派生文件,删除后 可以从插件目录重新生成,不属于需要备份的数据。

1.4 宿主进程的替换与后台调用

  • 新版本检查通过后,core 从新快照启动新的宿主进程;新进程就绪后,新的同步调用和自定义接口请求发往新进程。

  • 旧进程不再接受请求,继续用旧快照完成进行中的请求,超过该调用的时限后终止。

  • 新宿主进程启动失败时,按检查失败处理:继续使用旧进程和旧快照。

  • Worker 派发时携带快照路径。已派发的 Worker 用旧快照完成,结果按旧版本的声明提交,相当于"更新前刚好完成";新派发的 Worker 使用新快照。现有的 Supervisor 租约 fence 继续负责屏蔽领导权变更后的旧提交。

  • 一次调用只在一个快照中执行,因此同步调用、自定义接口和后台调用都不会混用新旧代码,不需要持久化的注册代次。

1.5 进程间的差异

已激活插件记录只在本进程内存中,不跨进程同步:

  • 在所有实例都完成扫描之前,同一个请求在不同实例上可能得到不同结果(例如一个实例已加载新插件、另一个还没有)。
  • GET /v1/plugins 和 GET /v1/plugins/{name} 返回处理该请求的实例的视图,响应中增加 version_digest(当前快照的内容 摘要)、declaration_digest、state(loaded、failed)、activated_at 和最近一次检查失败的分类,便于部署者比对 各实例是否一致。
  • 后台调用只在领导者的 Worker 中执行,使用领导者本机的快照;同步调用在接收请求的实例上执行,使用该实例当前的快照。

1.6 插件数据升级

async def upgrade(ctx: PluginContext) -> None:
    """每次加载本版本时调用;自行判断已有数据是否需要升级。"""

plugin = ArtifactPlugin(..., setup=setup, upgrade=upgrade, upgrade_timeout_seconds=600)
  • 调用时机:每次加载一个插件版本都会调用,包括 Server 启动时加载和热加载切换到新版本,不只在首次安装时调用。插件 自己记录数据的版本(例如写在专属存储中,或写进 Artifact 内容),与代码中的版本比较后决定做什么。
  • 在哪里执行:每个加载新版本的 Server 实例都执行,不论角色。接收请求的实例由新宿主进程在 setup(ctx) 之前执行, 完成后才报告就绪,新版本就绪之前 core 不向它转发同步调用和接口请求。background 角色的实例不运行宿主进程,由一个只 执行 upgrade 的短时子进程执行,完成后才用新快照派发后台调用。这样新版本的 generate 只会在本实例的 upgrade 完成后 运行。
  • 只做快速、可重复的变更:upgrade 用于插件存储的 schema 变更等很快完成的工作,不用于大规模改写数据。大量数据的 格式变化,在读取时惰性迁移(新代码兼容读取旧格式,写回时使用新格式),或由插件提供独立的迁移脚本,由部署者在升级 前执行;迁移脚本使用插件自己的存储和 core 的公开接口,core 不为它提供额外机制。
  • 失败:upgrade 抛出异常或超过 upgrade_timeout_seconds(默认 600 秒)时,按新版本检查失败处理:热加载时继续使用 旧版本;Server 启动时插件为 failed。
  • 上下文:专属存储、模型和日志;ctx.reads(scope_id) 与 ctx.writer(scope_id) 以插件自身的身份执行,与 Worker 相同,不检查调用者权限,用于改写少量旧格式的 Artifact;写事务规则与 Worker 相同,一次 upgrade 最多开启一个写事务块。core 不提供"列出插件数据所在的 Scope",插件按自己的记录 遍历。Artifact 的历史版本不可修改,读取历史版本的代码仍需兼容旧格式。
  • 重复与并发:每个 Server 实例、每次加载都会调用,core 不在实例之间协调。upgrade 必须可以重复执行,也可以在多个 实例上同时执行;需要互斥时,由插件在专属存储中自己加锁。
  • 新旧版本并存:多实例逐个完成扫描、热加载切换的过程中,旧版本可能仍在读写同一份数据。插件应先做新旧版本都能使用的 变更,等旧版本不再运行后,在后续版本中再清理。
  • 不支持降级:core 不记录插件的数据版本,也不阻止加载更旧的代码;旧代码读不了新数据,由插件负责。
  • Source 定义:core 按名称和版本登记 Source 定义,新旧版本可以并存。新版本插件仍需读取旧版本的 Source 时,应继续 声明旧版本的定义。

2. 插件自定义接口

2.1 声明

class Route(BaseModel):
    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"]
    path: str                                   # 相对路径,以 / 开头,可含 {参数}
    handler: str                                # setup(ctx) 返回对象上的方法名
    access: Literal["authenticated", "scope.read", "scope.contribute"]
    scope_param: str | None = None              # access 为 Scope 权限时必填:作为 Scope ID 的路径参数
    body: Literal["none", "json", "binary"] = "none"
    max_body_bytes: int | None = None           # 本路由的请求体上限;JSON 默认 1 MiB,二进制默认取部署上限
    request_model: type[BaseModel] | None = None    # body 为 json 时用于校验和生成接口描述
    response_model: type[BaseModel] | None = None
    timeout_seconds: float = 30
    description: str | None = None              # 接口描述与 MCP 工具描述
    mcp: bool = False                           # 同时作为 MCP 工具提供

class PluginApi(BaseModel):
    routes: Sequence[Route]
  • ArtifactPlugin 和 RFC #2617 的 SourcePlugin 都可以声明 api。声明 api 的插件需要宿主进程。
  • 路由挂载在 /v1/plugins/{name}/api{path}。同一插件内 (method, path) 不能重复;handler 必须存在且是 async 方法, 在检查子进程中校验。
  • access 为 scope.read 或 scope.contribute 时,scope_param 必须是 path 中的参数;core 检查调用者对该 Scope 的 权限,通过后把它作为 ApiRequest.scope_id。access 为 authenticated 时不能设置 scope_param,scope_id 为空。
  • 写核心数据之前,必须确认调用者对目标 Scope 的 scope.contribute:路由声明 access="scope.contribute",或在处理函数中 调用 ctx.require("scope.contribute", scope_id)。后一种适合路径中没有 Scope ID 的路由,例如知识库这类把 Scope 隐藏在 插件自己 ID 之后的接口。ctx.writer 和 ctx.sources.submit 只对本次请求中已经确认过的 Scope 可用。
  • 路由本身不能声明 server.admin;需要管理员权限的操作在处理函数中用 ctx.require("server.admin") 检查,或由 core 在 ctx.scopes 中检查。

2.2 请求与响应

class Caller(BaseModel):
    principal_id: str                           # 调用者身份;不含凭据

class ApiRequest(BaseModel):
    scope_id: str | None                        # scope_param 对应的 Scope;authenticated 路由为 None
    route: str                                  # 声明中的 path 模板
    path_params: dict[str, str]
    query: dict[str, list[str]]
    body: BaseModel | bytes | None              # 按 body 声明:request_model 实例、字节或 None
    caller: Caller

class BinaryResponse(BaseModel):
    content: bytes
    content_type: str
    filename: str | None = None

class ApiError(Exception):
    def __init__(self, status: int, code: str, message: str) -> None: ...   # status 必须是 4xx
  • 处理函数返回 response_model 的实例(序列化为 JSON,状态码 200)、BinaryResponse,或 None(204)。
  • 抛出 ApiError 时按其状态码返回,状态码必须在 400–499 之间,且不能是 401 或 403(认证和授权由 core 决定); 抛出其他异常返回 500,只记录异常类型。
  • 请求和响应大小有上限:路由可以用 max_body_bytes 声明自己的请求体上限,不声明时 JSON 为 1 MiB、二进制为部署上限。 部署上限 POWERCONTEXT_SERVER_PLUGIN_API_MAX_BODY_BYTES(默认 32 MiB)同时限制所有插件路由的请求体和响应,路由声明 的值超过它时按部署上限执行。插件路由不受 Server 通用请求体上限 POWERCONTEXT_SERVER_HTTP_MAX_REQUEST_BODY_BYTES 约束, 只受部署上限约束,这样部署者为插件上传放大上限时,不必放大所有接口的上限。超出时 core 直接返回 413,不调用插件。
  • 超过 timeout_seconds 返回 504;宿主进程不可用返回 503;插件或路由不存在返回 404。
  • core 不为插件接口提供幂等键或请求记录,重试语义由插件定义;需要幂等时,插件在请求中要求调用方提供幂等键。

2.3 处理函数能做什么

处理函数在宿主进程中执行,setup(ctx) 在每个宿主进程中只执行一次,Scope 随每个请求传入(与 RFC #2549 相同)。除了 RFC #2549 的上下文(专属存储、模型、日志),自定义接口调用还提供:

能力说明
ctx.require(action, scope_id=None, *, artifact_id=None)检查调用者是否具备 scope.read、scope.contribute(需要 scope_id)、server.admin,或对本插件 family 中某个 Artifact 的 artifact.write(需要 scope_id 和 artifact_id),不具备时抛出异常,接口返回 403。用于 authenticated 路由和跨 Scope 的操作;artifact.write 用于先接受请求、之后由 generate 修改已有 Artifact 的接口:写入发生在后台,那时没有调用者身份,所以要在接受请求时检查
ctx.reads(scope_id)指定 Scope 的 Artifact 只读视图,读取前按调用者权限检查;可用 reads(...).reads(family) 读取其他 family
ctx.writer(scope_id)Artifact 插件的写入器,范围为指定 Scope 和本插件的 family;只能用于本次请求中已确认 scope.contribute 的 Scope
ctx.sources.submit(scope_id, definition, value)提交一条本插件定义的 Source(Source 插件,或声明了 definitions 的 Artifact 插件),执行与 Source 写入接口相同的校验、resolve 和 Projection,返回 SourceRef;只能用于本次请求中已确认 scope.contribute 的 Scope
ctx.scopes.create(*, title, summary, idempotency_key, parent_scope_id=None)以调用者身份创建 Scope,复用 POST /v1/scopes 的实现:需要调用者具备 server.admin,调用者成为新 Scope 的管理员,相同幂等键返回同一个 Scope
ctx.scopes.update(scope_id, *, expected_version, title=None, summary=None)以调用者身份修改 Scope 的标题和摘要,权限与 PUT /v1/scopes/{scope_id} 相同;只能修改本插件创建的 Scope
ctx.scopes.list()列出本插件创建、调用者可见的 Scope

写入规则:

  • 自定义接口中的写入以调用者身份进行,权限与通用接口相同:新建需要 Scope 的贡献权限,结果归属于调用者;修改已有 Artifact 需要调用者对它的写权限(artifact.write)。core 在每个写操作执行时检查,不满足即抛出异常,接口返回 403。
  • 自定义接口中的写入不是 RFC #2549 的用户修改:core 不自动记录 lineage_only Content Source,写入器也只能引用本次调用 窗口中的 Source,而接口调用没有窗口,所以新版本不带出处。需要记录"谁做了什么"时,插件把这次操作作为本插件定义的 Source 提交,由 generate 写入新版本并引用它;修改基于的版本在 generate 中核对,已变化时放弃这次修改。接口返回时修改尚未 生效,插件应提供查询修改状态(待处理、已应用、已放弃)的方式,让调用方知道修改是否被放弃。知识库示例的切块编辑 就是这样实现的。
  • 一次请求最多开启一个写事务块,块内写操作在一个事务中提交,与 RFC #2549 的写事务规则相同。
  • 处理函数不能推进游标或 checkpoint,也不能写其他插件的 family。
  • 专属存储不按 Scope 隔离(见 RFC #2549 参考级说明 1.2)。处理函数按 request.scope_id 读写自己的数据,不能只凭路径中的 其他 ID 返回数据,否则对一个 Scope 有权限的调用者能读到其他 Scope 的数据。core 中单个 Artifact 的授权(例如 Artifact 查看者、所有者)只在 Scope 权限之外追加访问,不收窄 Scope 成员的读取范围,所以按 Scope 检查后从自有存储返回正文不会 越权;core 以后若增加收窄单个 Artifact 读取的规则,插件接口需要随之按 Artifact 检查。

插件创建的 Scope:

  • core 在创建时给 Scope 加上外部引用 {"kind": "powercontext.plugin", "value": "<插件名>"},ctx.scopes.list() 和 ctx.scopes.update() 据此判断归属,部署者也能看出 Scope 由哪个插件创建。
  • 创建 Scope 的权限要求不因插件而放宽。允许非管理员创建 Scope(例如在父 Scope 下创建子 Scope)需要修改 core 的授权 模型,不在本提案范围内。
  • 插件的业务配置(例如知识库的分块策略)不写入 Scope,由插件以 scope_id 为键存进自己的存储。先创建 Scope,再写配置; 写配置失败时,调用方以相同的幂等键重试,得到同一个 Scope 后重新写入。

2.4 MCP 工具

声明 mcp=True 的路由由 core 生成为 MCP 工具,与 Server 现有的 MCP 工具使用同一个 MCP 端点:

  • 只有 body 为 none 或 json 的路由可以开启;二进制路由不能开启,检查时报错。
  • 工具名为 <插件名>__<handler>,插件名原样保留(可以含 -),与 handler 之间用双下划线分隔。插件名不含下划线,第一个 双下划线之前就是插件名,因此不同插件的工具名不会相撞。工具名不超过 64 个字符,超出或与内置工具重名时插件检查失败。 描述取自 description,开启时必须填写。工具参数由路径参数、查询参数和 request_model 合成,scope_param 对应的参数就是 Scope ID。
  • 调用工具等同于以 MCP 会话的身份调用该路由,认证、access 授权、时限和错误处理与 HTTP 调用相同。
  • GET 且 access 为 scope.read 或 authenticated 的路由标为只读工具,其他标为写入工具,宿主据此决定是否需要用户确认。
  • 热加载新增、更新或移除插件时,工具随之增删;MCP 客户端下一次列出工具时看到变化,core 能通知的会话会收到工具列表 变化的通知。
  • 只有插件显式开启的路由会成为工具,避免工具数量过多占用 Agent 的上下文。

2.5 接口描述

GET /v1/plugins/{name}/openapi.json(需要认证)返回 core 根据路由声明生成的 OpenAPI 文档:路径、方法、权限要求、 request_model 和 response_model 的 JSON Schema,以及统一的错误响应。插件接口的兼容性由插件自己负责,需要不兼容的 变更时,插件可以在路径中自带版本(例如 /v2/knowledge-bases)。

3. 插件页面

3.1 声明与静态文件

class PluginPages(BaseModel):
    directory: str = "ui"                       # 插件目录内的相对路径
    entry: str = "index.html"
    title: dict[str, str]                       # 按语言给出的导航标题,至少包含 en
  • 静态文件路径为 /dashboard/plugins/{name}/ui/{path},只提供当前快照中 directory 下的文件,拒绝 .. 和指向目录外的 符号链接。
  • 只允许以下类型:.html、.js、.css、.json、.svg、.png、.jpg、.webp、.woff2;单个文件不超过 5 MiB。
  • 静态文件只包含插件代码和资源,不含用户数据,因此不要求登录。
  • 响应头中的 CSP:
    • 以 sandbox 指令让页面即使被直接打开,也运行在不透明来源中,读不到 Dashboard 的 cookie。它直接请求 Server 时属于跨站 请求,浏览器不会带上 SameSite=Strict 的会话 cookie,页面也没有 API 凭据。
    • 脚本只能来自插件快照,页面运行的代码与插件版本一致。
    • 链接、表单、弹窗和对外部 HTTPS 站点的请求都允许:插件是可信代码,可以把用户带到外部服务,或调用外部服务的公开接口。 这些请求都不带用户的 PowerContext 会话。
    • 只允许 Dashboard 嵌入。

3.2 宿主页面与转发

  • 宿主页面:/dashboard/plugins/{name} 是 core 的 Dashboard 页面,要求登录。它以沙箱 iframe 加载插件页面,iframe 第一次 加载后把当前 Scope、语言和主题发给页面;之后只接受来自该 iframe 的请求消息,路径必须匹配本插件声明的路由,或者是本插件 family 的通用 Artifact 接口,再以同源请求经服务端转发,结果用消息传回(二进制响应以 Blob 传回)。
  • 服务端转发:/dashboard/plugins/{name}/api/... 是 Dashboard 的服务端路由,要求 Dashboard 会话,并要求请求的 Sec-Fetch-Site 为 same-origin(缺失时校验 Origin 与 Server 一致)。它沿用 Dashboard 现有的做法,以会话对应的身份 调用 /v1/plugins/{name}/api/...。
  • 通用 Artifact 接口的转发:/dashboard/plugins/{name}/artifacts/{scope_id}/... 是另一条 Dashboard 服务端路由,会话和 同源要求与上一条相同。它以会话对应的身份调用 /v1/scopes/{scope_id}/artifacts/{family}/...,其中 family 由 Dashboard 按 该插件的声明填入,页面不能指定;新建(POST /dashboard/plugins/{name}/artifacts/{scope_id})转成通用新建接口的插件分支, family 同样由 Dashboard 填入。请求的 If-Match 和请求体原样传给通用接口,响应的状态码、ETag、Location 和响应体 原样返回。转发层不做授权判断,也不解释内容。没有声明 family 的插件(Source 插件)没有这条路由。
  • 会话隔离:Dashboard 的会话 cookie 是 HttpOnly、SameSite=Strict,路径为 /dashboard。插件页面处于不透明来源, 脚本读不到 cookie;Server 也不接受 Origin: null 的转发请求。
  • 跳转后停止转发:沙箱 iframe 可以把自己导航到外部站点,CSP 无法阻止。外部页面同样能向宿主页面发送 postMessage, 并且通过 event.source 校验。宿主页面因此在 iframe 第二次加载后停止转发,外部页面借不到用户会话。插件页面应实现为 单页应用;在插件页面之间跳转同样会停止转发。
  • 范围:宿主页面只转发到本插件已声明的路由和本插件 family 的通用 Artifact 接口;转发后的请求仍由 core 按调用者权限 检查,插件页面不能借此访问调用者无权访问的 Scope 或其他 family 的 Artifact。
  • 页面客户端脚本:core 在 /dashboard/plugins/_client.js 提供一个小脚本,封装上述消息协议,插件页面可以直接引用。

4. 执行约束

  • 自定义接口在宿主进程中执行,与 RFC #2549 的同步调用共用本插件的宿主进程组,遵循同样的并发上限、超时取消、失去响应 时终止和重启退避规则:超过 timeout_seconds 的请求只取消它自己并返回 504,不影响同一进程中的其他请求。接口请求较重的 插件可以调大 host_processes,以分钟计的工作应转入后台的 generate(见 RFC #2549 参考级说明第 6 节)。
  • 自定义接口的请求体在 Server 进程中读取并校验大小后,以字节或已校验的模型传给宿主进程;request_model 的校验在宿主进程 中执行,失败返回 422。
  • 静态页面文件由 Server 进程直接从当前快照读取,不进入宿主进程。切换版本后,新请求立即读到新快照的文件。

5. 持久化

除 RFC #2549 已有的 Source 定义清单外,不新增数据库数据。热加载新版本时,新增或变化的 Source 定义按名称和版本登记到 pc_source_definition_manifests;已有 Source 引用这些定义,所以插件版本卸载时不删除它们。插件集合、版本、路由表和页面 注册都只存在于各 Server 进程的内存中,Server 重启后按插件目录重建。版本 快照是数据目录下的本机文件,可以随时从插件目录重新生成。插件接口写入的核心数据与 RFC #2549 相同;插件创建的 Scope 是 普通的 Scope;插件自己的数据存放在插件存储中。

6. 接口变更

变更内容
新增/v1/plugins/{name}/api/...:插件声明的路由
新增GET /v1/plugins/{name}/openapi.json
新增/dashboard/plugins/{name}、/dashboard/plugins/{name}/ui/...、/dashboard/plugins/{name}/api/...、/dashboard/plugins/{name}/artifacts/{scope_id}/...、/dashboard/plugins/_client.js
新增插件声明 mcp=True 的路由作为 MCP 工具出现在 Server 的 MCP 端点
新增powercontext.plugins:PluginApi、Route、ApiRequest、BinaryResponse、ApiError、Caller、PluginPages;上下文的 require、reads、writer、sources、scopes
调整SourcePlugin、ArtifactPlugin 增加 api、pages、upgrade 和 upgrade_timeout_seconds 字段
调整GET /v1/plugins、GET /v1/plugins/{name} 的响应增加 version_digest、declaration_digest、state、activated_at、最近一次检查失败的分类、路由列表和页面信息
新增环境变量 POWERCONTEXT_SERVER_PLUGINS_RESCAN_SECONDS(默认 60,0 关闭热加载)、POWERCONTEXT_SERVER_PLUGIN_API_MAX_BODY_BYTES(默认 32 MiB)

openapi/powercontext.yaml 只描述 /v1/plugins/{name}/openapi.json 和 /v1/plugins 的变化,不包含插件自己的路由。

7. 可观测性

字段含义
plugin_name插件名
plugin_eventloaded、updated、removed、check_failed、upgrade_failed
version_digest本次生效的快照内容摘要
declaration_digest本次生效的声明摘要
plugin_route自定义接口的路由模板(例如 GET /knowledge-bases/{kb_id}/documents/{source_id}/original),不含实际参数值
plugin_method沿用 RFC #2549,新增 api
scan_ms一次扫描从开始到完成的耗时,毫秒
  • 每次加载、更新、移除和检查失败记录一条事件;检查失败只记录已知的失败分类,不记录异常消息。
  • 指标标签可以使用 plugin_name、plugin_route 和响应状态类别(2xx、4xx、5xx),不包含 Scope ID、路径参数或查询参数。
  • 日志不包含请求体、响应体和文件内容。新增字段按开发指南登记到允许列表,并在中英文可观测性文档中说明。

缺点

  • 多实例存在不一致窗口:各实例独立扫描,插件版本在一个扫描周期内可能不一致;调用方可能在不同实例上看到不同的结果。
  • 扫描有持续开销:每个 Server 进程定期读取插件目录的全部内容计算摘要,开销随插件目录总字节数增加。
  • 快照占用磁盘:每个版本在数据目录下保存一份插件目录的副本,旧版本在不再使用后清理。
  • 依赖变化不会被检测:插件依赖在共用的 Python 环境中,更新依赖需要部署者先安装;依赖与插件代码不兼容时,检查会失败。
  • 插件接口在主契约之外:插件路由不进入 openapi/powercontext.yaml,没有生成的客户端;作为 MCP 工具提供的路由,其名称 和参数也随插件变化。兼容性由插件自己保证。
  • 插件页面要做成单页应用:页面跳转后宿主页面停止转发,多页面的插件页面需要重新打开。
  • 处理函数是可信代码:宿主进程隔离普通故障,不是沙箱。插件接口以调用者身份写入核心数据,插件代码中的缺陷可能以用户 名义写入错误数据,这一点与 RFC #2549 的用户修改相同。

理由与备选

方案取舍
文件系统监听(inotify 等)响应更快,但各平台行为不同,容器和网络文件系统上不可靠,还会收到写了一半的事件;定期扫描加稳定判断更简单
按文件大小和修改时间判断变化不需要读文件内容,但时间戳归一化的归档解压后,不同内容可能有相同的大小和修改时间,更新会被永久忽略
管理接口触发重新加载只能作用于收到请求的实例,多实例时需要再做分发;定期扫描自然覆盖所有实例。是否增加"立即扫描本实例"的接口见未决问题
持久化插件集合与注册代次(旧 Artifact 插件框架)可以让各实例严格一致,但需要重新引入期望状态、管理阶段和代次屏蔽,这是 RFC #2549 刚删掉的机制
在 Server 进程内重新导入插件模块Python 无法可靠地替换已加载模块:插件的同级模块以顶层名字进入 sys.modules,旧对象仍被引用。替换子进程没有这个问题
子进程直接从插件目录导入,用指纹屏蔽旧代码不需要复制,但目录替换后,已运行进程中的延迟导入会读到新文件,同一次调用混用新旧代码;提交前核对指纹也挡不住同步调用
按版本快照导入(本提案)每次调用固定在一个不可变的版本上,更新失败时可以继续使用旧版本;代价是复制和清理快照
更新失败时停用插件行为简单,但一次错误的部署会让插件的同步调用和接口全部不可用;有快照后保留旧版本没有额外成本
插件接口在 Server 进程中执行延迟最低,但插件阻塞或崩溃会影响整个 Server,也会重新把插件代码导入 Server 进程
插件接口每次请求派发 Worker复用现有机制,但每次都要启动新的 Python 进程,延迟以秒计
插件路由一律挂在 Scope 下授权规则统一,但创建知识库这类不属于任何 Scope 的操作无处安放;改为插件自定路径,Scope 授权由 scope_param 声明
插件声明 server.admin 路由插件可以提供管理功能,但会在路由层引入第二套管理员授权;第一版只在处理函数中用 ctx.require 检查
插件创建 Scope 时放宽权限普通用户也能创建知识库,但这改变了"Scope 由管理员创建"的 core 授权规则,应另行提案
插件页面与 Dashboard 同源实现最简单,但页面脚本可以带着用户的会话调用任何 Dashboard 和 Server 接口,等于冒充用户
插件页面禁止访问外部站点需要同时限制请求、表单、弹窗和导航,CSP 无法完整做到;插件本身是可信代码,服务端也能访问外部,禁止页面访问外部没有实际意义
插件页面使用独立端口或域名也能隔离来源,但部署者要额外配置端口、证书和反向代理;沙箱 iframe 不需要额外配置
插件页面由插件代码在服务端渲染页面能直接拿到数据,但每次页面请求都要进入宿主进程,并且要定义模板和转义规则;静态页面加接口调用更简单
所有插件路由自动成为 MCP 工具不需要额外声明,但工具数量随插件增长,占用 Agent 的上下文,二进制路由也不适合作为工具;改为按路由开启,只开放 JSON 路由
core 记录插件的数据版本,调用时传入旧版本号(Moodle、Home Assistant)插件不必自己记录版本,但那些项目中被迁移的数据由宿主保管;本提案中插件专属存储的位置和格式只有插件知道,Artifact 内容的格式也由插件定义,core 记录的版本号无法反映这些数据的实际状态
core 按阶段执行插件提供的迁移脚本(Kong 的 up / teardown)能处理多实例滚动升级,但要求 core 理解插件的存储并提供迁移运行器和命令;本提案只调用一个钩子,把"先做兼容变更、旧版本停止后再清理"作为对插件的要求
插件数据升级由插件在钩子中自行判断(本提案,与 Backstage、WordPress 相同)core 只约定调用时机和失败处理,不感知插件数据;代价是兼容性完全由插件保证,core 不兜底
插件接口不提供 MCP 工具实现最少,但 Agent 是 PowerContext 的主要使用方,插件的领域操作(例如跨知识库检索)对 Agent 不可用。现有 MCP 工具本来就由 HTTP 接口生成,插件路由可以复用同一机制

先例

  • Dify 插件守护进程:每个插件包按 <作者-名字-版本>@<校验和> 解压到独立的工作目录,并从该目录启动运行时;新版本 使用新目录,与旧版本互不影响。本提案的版本快照采用相同的做法,但依赖仍共用 Server 的 Python 环境。
  • 旧 Artifact 插件框架:保存插件目录的内容指纹,Worker 加载前重新核验。本提案沿用按内容计算的摘要。
  • Chrome 扩展:扩展页面运行在扩展自己的来源中,通过声明的权限和消息传递与网页及浏览器交互,不能直接使用网页的会话。 本提案的插件页面采用相同的隔离思路:不透明来源,加上只能调用本插件接口的消息转发。
  • VS Code Webview:扩展的界面运行在 iframe 中,通过 postMessage 与扩展通信,并要求设置 CSP。插件页面的消息协议与之类似。
  • Dify 插件的 Endpoint 扩展:插件可以声明 HTTP 端点,由 Dify 挂载并转发请求。本提案的自定义接口同样由宿主统一挂载, 并由 core 完成认证和授权。
  • 插件数据升级:Backstage 的后端插件在初始化时自行执行数据库迁移,框架明确不负责插件的结构迁移;WordPress 的激活钩子 在插件更新时不一定触发,插件的通行做法是自己保存数据版本、每次加载时比较。本提案的 upgrade 采用同样的分工,并在每次 加载时都调用。Kong 把插件迁移分成不破坏旧数据的 up 和清理用的 teardown,以支持新旧节点并存,本提案把这一点作为对插件 的要求。Moodle 和 Home Assistant 由宿主记录版本并传入旧版本号,适用于数据由宿主保管的场景。
  • Gunicorn 等进程管理器的平滑重载:先启动新的工作进程,再让旧进程处理完已有请求后退出。宿主进程的替换采用同样的顺序。
  • PowerContext 现有基础:RFC #2549 的宿主进程、已激活插件记录、用户修改规则和插件专属存储;Supervisor 的 binding、 租约 fence 和退避;Scope 的创建接口与幂等键;Dashboard 的会话与服务端调用方式。

未决问题

问题说明
立即扫描是否提供 POST /v1/plugins/rescan(server.admin)让部署者立即触发本实例扫描;多实例时只作用于收到请求的实例
扫描间隔默认值60 秒是否合适;是否需要在大插件目录下限制每次扫描的字节数
接口限流是否为插件接口提供按路由或按调用者的限流,还是沿用 Server 现有的入口限制
Desktop 中的插件页面Desktop 应用是否嵌入插件页面,以及其 WebView 中的沙箱和 CSP 行为
浏览器行为验证CSP sandbox 指令下 'self' 对子资源的匹配,以及不透明来源请求的 SameSite 处理,需要在主流浏览器上验证后确定最终响应头
二进制请求的流式处理第一版在 Server 进程中完整读入请求体再转给宿主进程;大文件是否需要流式传输

后续可能

  • 插件页面在 Desktop 应用中展示。
  • 插件之间通过声明的接口互相调用。
  • 为插件接口提供生成的客户端或 SDK 辅助。

On this page