RFCs

插件接口

查看 Markdown

概要

本提案重新定义 PowerContext 的第三方插件模型:插件只实现几个固定接口,PC Server 在需要时调用;调用方不直接调用插件, 而是像使用内置能力一样使用现有的 Source 和 Artifact 接口。

  • Artifact 插件:拥有一个 Artifact family,实现 generate 把尚未消费的 Source 加工成 Artifact,实现 render_artifact 给出默认展示,可选实现检索和用户修改。插件可以自带 Source 类型,用来记录用户提交给它的内容。
  • 插件形态:一个插件是一个目录,包含 plugin.py,其中把一个声明对象 ArtifactPlugin 赋给 plugin。 声明写在代码里,没有单独的清单文件;部署相关的设置由插件从环境变量读取。
  • 调用方式:
    • 写入插件自带类型的 Source,使用现有的 Source 写入接口。
    • 读取、检索 Artifact,使用现有的 Artifact 接口。
    • 新建、编辑、合并、遗忘、恢复插件 Artifact,也使用现有的 Artifact 接口。core 负责鉴权、版本校验和溯源,再同步调用 插件对应的方法;插件校验内容、维护自己的存储,并通过写入器写入。插件没有实现某项操作时,该接口返回 422。
  • 执行:
    • generate 是后台调用,在 Supervisor 管理的 Worker 子进程中执行,沿用现有的隔离、超时、并发预算、领导租约和失败退避。
    • Source 写入时的 resolve 与 Projection、展示、检索和用户对插件 Artifact 的修改是同步调用,在 core 管理的常驻 插件宿主进程中执行。每个 Server 进程为每个加载的插件启动一个宿主进程,部署者不需要管理它。
  • 写入:Artifact 插件在 async with writer.transaction() 块中执行写操作,块结束时 core 把写入、消费游标和 完成确认一起提交,异常则整体回滚。插件读不到也改不了游标。
  • core 的职责:只管理 pc_sources、pc_artifacts(含 heads、lineage、合并记录、生命周期、handle 和 tags)及其 消费进度。插件可以有自己的索引和存储,由插件自己管理;core 在部署使用的数据库后端上为每个插件提供一块专属存储, 并把 Server 已配置的模型提供给插件使用。
  • 生命周期:插件在 Server 启动时按目录加载,变更需要重启。每个 Server 进程只在内存中记录本进程已激活的插件, 不持久化插件的启用状态、注册代次或管理阶段。

本提案取代 Artifact 插件框架 RFC #2175 的插件契约与管理机制。旧框架随 v1.5 发布, 但目前没有对外发布的插件,因此本提案不保留兼容:旧的插件清单、管理接口和插件管理相关的表直接移除,旧插件写入的自定义 Artifact 数据不迁移。为了不悄悄丢失数据,升级前的迁移检查发现旧框架留有数据时拒绝升级,由部署者在旧版本上先导出和 清理(见参考级说明第 10 节)。

独立的 Source 插件,即只提供 Source 类型,或从外部系统持续采集(采集目标、checkpoint、在设备上采集并汇报到中心), 不在本提案范围内,由后续提案定义并取代 Source 插件框架 RFC #2012。在那之前,旧 Source 插件框架保持不变。

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

动机

现有的 Artifact 插件框架让 PowerContext 替第三方插件承担了大量生命周期管理:

框架Server 为插件承担的工作
Artifact 插件(#2175)在 pc_artifact_processing_binding_states 中维护 desired_state、phase、binding_generation、last_error;七种管理状态及其转换;enable-all / reload / enable / disable / unload 管理接口与 expected_generation 并发校验;用注册代次屏蔽旧 Worker 提交;在 pc_artifact_family_schemas 中固化内容 schema 和索引定义,变更返回 409;框架负责自定义声明式索引的构建、重建和可用状态

这些机制的代价由所有人承担:

  • 插件作者需要理解 binding、generation、schema 固化规则和索引声明等框架概念,才能写出一个插件。
  • 部署者需要编写清单文件,并通过管理 API 让插件进入可运行状态。
  • 调用方需要区分内置能力和插件能力,使用不同的接口。
  • 维护者需要为第三方代码维护状态机、并发屏蔽、schema 和索引治理以及恢复路径,这部分代码的规模和测试面已经超过 插件业务本身。

插件真正需要的是:在合适的时机被调用,拿到需要的输入,把结果交回 core。调度、隔离、消费进度和事务提交是 core 本来就有的能力,Supervisor 已经为内置 Artifact 提供了这些能力。Dify 等系统的插件模型也说明,宿主定义接口和调用时机、 插件只实现接口,足以支撑大量第三方扩展。

本提案的目标:

  1. 插件作者只需写一个 plugin.py:一个声明对象和几个方法,不需要理解插件管理的内部机制。
  2. 调用方不感知插件:Source 和 Artifact 的现有接口对插件产生的数据同样适用。
  3. 插件代码只在 core 管理的子进程中执行(Worker 或插件宿主进程),插件故障不影响 Server 和其他插件。
  4. 插件结果进入 pc_sources / pc_artifacts,与消费进度原子提交。
  5. core 只管理这两类核心数据及其消费进度;内容结构、索引和其他存储交给插件自己。
  6. 插件对核心数据的写入只经过 core 提供的写入器,覆盖 Artifact 的全部通用写操作,并沿用 core 现有的校验规则。
  7. 用户对插件 Artifact 的修改经过插件,插件自有存储能与修改同步更新。
  8. Artifact 生成可以按调度执行,也可以由新 Source 触发。
  9. 用户只需部署一个 Server;插件随 Server 启动加载。

指南级说明

1. 总体设计

flowchart LR
    Caller["应用 / Agent / 宿主"]
    subgraph Server["PC Server(core)"]
        SourceAPI["现有 Source 接口<br/>写入 Source"]
        ArtifactAPI["现有 Artifact 接口<br/>读取、检索、修改"]
        Sup["Supervisor<br/>调度 / 触发 / 预算 / 退避"]
        Core[("core 数据<br/>pc_sources / pc_artifacts / 游标")]
    end
    subgraph Host["插件宿主进程(常驻,core 管理)"]
        Sync["resolve / Projection / render_artifact<br/>search_artifacts / create_artifact / ..."]
    end
    subgraph AW["Worker:Artifact 插件"]
        Generate["generate(request, writer)"]
        Tx["writer.transaction()"]
        Generate --> Tx
    end
    Caller --> SourceAPI
    Caller --> ArtifactAPI
    SourceAPI -->|"同步调用"| Sync
    ArtifactAPI -->|"读取"| Core
    ArtifactAPI -->|"展示、检索,同步调用"| Sync
    ArtifactAPI -->|"修改,同步调用"| Sync
    Sync -->|"Source 或 Artifact 写入,一次提交"| Core
    Sync -.-> Own
    Core -->|"新 Source 触发"| Sup
    Sup -->|"未消费的 Source 窗口"| Generate
    Tx -->|"Artifact 写入、游标、确认,一次提交"| Core
    Generate -.-> Own[("插件自有存储 / 模型")]

图中有两条路径,一次调用只执行一个插件:

  • 生成路径:新 Source 进入 journal 后,关注这些 Source 的 Artifact 插件被标记为待处理;Supervisor 派发 Worker,传入 该 Scope 尚未消费的 Source 窗口和写入器;插件在写事务块中写入 Artifact,core 连同游标和确认一起提交。
  • 同步路径:调用方写入插件类型的 Source、展示或检索插件 Artifact、修改插件 Artifact 时,Server 完成鉴权和版本校验后,把请求交给该插件的 宿主进程;插件在宿主进程中完成转换或写入,结果在一个事务中提交后同步返回给调用方。

调用方只和 core 的现有接口打交道:

调用方要做的事使用的接口插件参与的方式
提交一条插件类型的 Source现有 Source 写入接口宿主进程执行插件定义的 resolve 和 Projection
浏览、读取 Artifact现有 Artifact 读取接口不参与
展示、检索插件 Artifact展示接口、现有检索接口、Prepared Context宿主进程执行 render_artifact、search_artifacts
新建、编辑、合并、遗忘、恢复、撤销合并现有 Artifact 新建与编辑接口、通用合并接口宿主进程执行插件对应的方法;未实现返回 422
打 tag、按 tag 查询现有 tags 接口不参与;tags 是 core 数据

职责划分:

职责归属
认证、Scope 授权、公开 HTTP / MCP 接口、用户修改的版本校验与溯源记录core
何时调用:调度、触发合并、Worker 预算、超时、退避、领导租约core(现有 Supervisor)
宿主进程的启动、复用、超时终止与重启core
读取输入、提供受约束的写事务、在同一事务中提交核心数据 / 游标 / 完成确认core(Worker 或宿主进程中的插件执行器)
插件专属存储空间的分配、Server 已配置模型的封装core
插件自带 Source 类型的定义与 Projection 计算;Artifact 内容结构、生成算法、展示、检索、用户提交内容的校验、插件自有的索引与存储及其一致性插件
插件代码、依赖和环境变量的部署部署者

插件代码只做一件事:给定输入,产出结果或抛出异常。抛出异常即失败,core 不提交任何核心数据;后台调用下次重试同一输入, 同步调用把错误返回给调用方。

2. 插件的形态

Server 从 POWERCONTEXT_SERVER_PLUGINS_DIR 加载插件。每个直接子目录是一个插件,目录名就是插件名;目录中必须有 plugin.py,可以有其他模块:

/opt/powercontext/plugins/
├── knowledge-base/
│   ├── plugin.py
│   └── parsers.py
└── incident-report/
    └── plugin.py

plugin.py 把一个声明对象赋给模块级变量 plugin:

plugin = ArtifactPlugin(family="incident-report", ..., setup=setup)

声明对象回答 core 在运行插件代码之前需要知道的问题:插件提供什么(Artifact family 和自带的 Source 类型)、消费什么、何时调用、 资源上限多少。它是普通的 Python 对象,由 Pydantic 校验;没有 YAML 或其他清单文件。

  • 部署设置:插件自己的凭据、外部服务地址等随部署变化的值,由插件在 setup 中从环境变量读取。Server 不保存、 不传递也不记录这些值。
  • core 提供的资源:插件需要数据库和模型时,不必另行配置,通过上下文使用 core 封装好的对象(见参考级说明 1.2):
    • ctx.storage:部署所用数据库后端上的一块插件专属空间。SQLite 是数据目录下的一个单独文件,OceanBase 和 seekdb 是一个单独的库。插件拿到的连接只指向这块空间,不指向 core 的表。
    • ctx.models:Server 已配置的生成模型和 embedding 模型。插件只能调用,拿不到模型的地址和凭据;调用计入现有的模型 用量统计。
  • 启用与停用:目录存在且检查通过,插件就可用;需要停用时移出目录并重启 Server。
  • 检查:Server 启动时在有时限的子进程中导入 plugin.py,校验声明,不调用 setup。检查失败只影响该插件。

3. 插件自带的 Source 类型

Artifact 插件可以在声明的 definitions 中提供自己的 Source 类型(见 4.2)。插件用它记录"用户要求做什么",例如上传了 一份文档、改写了一个分块,再在 generate 中把这些 Source 加工成 Artifact。这样每次变化都有对应的 Source,来源可以追溯, 而不需要另写一个 Source 插件。

plugin = ArtifactPlugin(
    family="knowledge-base",
    definitions=(DocumentUploadDefinition(),),       # Source 类型 kb-document
    inputs=Inputs(source_types=("kb-document",), projection="knowledge-base.upload@1"),
    on_sources=True,
    setup=setup,
)
  • 定义:沿用现有的 SourceDefinition:input_class 校验输入,resolve 把输入解析为 Source,Projection 给出消费方 读取的形态。
  • 写入:调用方通过现有的 Source 写入接口提交(POST /v1/scopes/{scope_id}/sources,source_type 为插件定义的类型), 插件自己的代码通过 ctx.sources.submit 提交。校验、resolve 和 Projection 在插件的宿主进程中执行,保存语义与内置 Source 一致。
  • 只能追加:与所有内置 Source 一样,没有修改和删除;要更正内容,提交一条新的 Source。
  • 大块内容:resolve 必须是纯函数,现有 Source 写入接口也只接受 JSON。文件、图片由插件自定义接口接收 (见 RFC #2579),插件存进自己的存储,Source 中只记录位置、摘要 和媒体类型等元数据。
  • 消费:插件在 inputs.source_types 中列出这些类型即可消费;其他 Artifact 插件也可以消费它们。

4. Artifact 插件

4.1 要实现的接口

接口必需说明
setup(ctx) -> ArtifactGenerator是插件对象的工厂(不是新建 Artifact);Worker 中每次调用执行一次,宿主进程中只执行一次后复用
generate(request, writer) -> None配置了 schedule 或 on_sources 时是读取 request.sources(未消费的 Source 窗口),在写事务块中写入 Artifact
render_artifact(request) -> Rendering是给出一个精确 revision 的默认展示内容(Markdown 或纯文本),见参考级说明第 7 节
search_artifacts(request) -> SearchResult否用插件自己的索引检索,返回命中的 revision 和片段;通用检索接口和 Prepared Context 调用它
create_artifact(request, writer) -> None否用户新建;request.artifact_id 由 core 分配
update_artifact(request, writer) -> None否用户编辑指定 ID 的 Artifact,request.expected_revision 为调用方看到的 revision
merge_artifacts(request, writer) -> None否用户合并;结果的 ID 由 core 分配
forget_artifact(request, writer) -> None否用户遗忘
restore_artifact(request, writer) -> None否用户恢复、恢复到旧 revision 或撤销合并

后五个方法处理用户修改(见 4.4),每个都是可选的:没有实现的操作,对应接口返回 422,表示这个 family 不支持该操作。 插件在这些方法中校验用户提交的内容、更新自己的存储,并通过写入器完成 core 要求的那一项写操作。

core 不为插件 family 建立任何索引,也不理解 content 的结构:插件的内容怎样分块、是否可以全文或向量检索、怎样展示, 只有插件知道。因此展示和检索都交给插件:render_artifact 必须实现,search_artifacts 可选,未实现时通用检索接口和 Prepared Context 对该 family 返回 422。

4.2 声明

字段默认值说明
family必填插件拥有的 Artifact family,不能与内置 family 或其他插件重复
inputsNoneInputs(source_types=..., projection=..., projections={...}, max_sources=50):消费的 Source 类型、每条 Source 交付的 Projection、单个窗口的条数上限;为空表示不消费 Source。projection 适用于所有类型,projections 按 Source 类型指定不同的 Projection,每个类型必须有其一
on_sourcesFalse新 Source 到达后触发;需要 inputs
scheduleNoneInterval(seconds=...) 或 Cron(expression=..., timezone=...)。schedule 和 on_sources 都不配置时插件没有后台生成,不需要实现 generate,Artifact 只由用户修改和插件接口写入(例如笔记)
scopesNone可服务的 Scope 名单;配置了 schedule 但不消费 Source 的插件必须填写
timeout_seconds300整次调用的时限
transaction_timeout_seconds30写事务块的时限,不超过 timeout_seconds
max_workers1跨 Scope 的并发上限
host_processes1每个 Server 进程中本插件宿主进程数的建议上限,部署者可以按插件覆盖;接口请求较重的插件可以调大
change_timeout_seconds30一次用户修改调用的时限,包括其中的写事务块
definitions()插件自带的 Source 类型,随插件加载登记,见第 3 节和参考级说明第 2 节
setup必填见上表

4.3 示例

下面的插件为每条工单 Source 生成一份报告:先用自己的向量索引查找相似的已有报告,命中则修订那份报告,否则新建; 同时把报告写进自己的向量索引。它还支持用户编辑报告,没有实现的新建、合并、遗忘、恢复对该 family 返回 422。向量索引 放在 core 分配的专属存储中,模型使用 Server 已配置的模型。

from powercontext.plugins import (
    ArtifactPlugin, ArtifactWriter, GenerateRequest, Inputs, InvalidContent, PluginContext, Rendering, RenderRequest,
    SearchHit, SearchRequest, SearchResult, UpdateRequest,
)
from powercontext.sources import TextEvidence


class IncidentReports:
    def __init__(self, index: VectorIndex, model: Summarizer) -> None:
        self.index, self.model = index, model

    async def generate(self, request: GenerateRequest, writer: ArtifactWriter) -> None:
        # 1. 耗时工作放在写事务之外:模型调用、向量计算
        planned = []
        for source in request.sources:
            evidence = TextEvidence.model_validate(source.projection)
            summary = await self.model.summarize(evidence.content)
            planned.append((source, summary, await self.model.embed(summary)))

        # 2. 短写事务:块内读取能看到本块已写入的内容
        async with writer.transaction() as tx:
            for source, summary, vector in planned:
                match = await self.index.nearest(request.scope_id, vector, threshold=0.92)
                current = await tx.get(match.artifact_id) if match else None
                artifact_id = current.ref.artifact_id if current else writer.stable_id(
                    "report", source.ref.source_type, source.ref.source_id)
                written = await tx.put(artifact_id, content={"title": "工单报告", "summary": summary},
                                       source_refs=[source.ref])
                # 拿到真实的 artifact_id 与 revision 后写入自有索引,键为 (artifact_id, revision)
                await self.index.upsert(request.scope_id, written.ref.artifact_id, written.ref.revision, vector)
        # 块正常结束:core 提交 Artifact 写入、游标推进与完成确认

    async def update_artifact(self, request: UpdateRequest, writer: ArtifactWriter) -> None:
        # 用户编辑:校验内容,重算向量,再写入 core 和自有索引
        report = Report.model_validate(request.content)          # 不合格时抛出 InvalidContent,接口返回 422
        vector = await self.model.embed(report.summary)
        async with writer.transaction() as tx:
            written = await tx.put(request.artifact_id, content=report.model_dump(),
                                   expected_revision=request.expected_revision)
            await self.index.upsert(request.scope_id, written.ref.artifact_id, written.ref.revision, vector)

    async def render_artifact(self, request: RenderRequest) -> Rendering:
        report = Report.model_validate(request.artifact.content)
        return Rendering(text=f"# {report.title}\n\n{report.summary}")

    async def search_artifacts(self, request: SearchRequest) -> SearchResult:
        # 通用检索请求原样转交;本插件只支持向量检索
        if request.search.mode not in (None, "vector"):
            raise InvalidContent("only vector search is supported", field="mode")
        vector = await self.model.embed(request.search.query)
        hits = await self.index.nearest_many(request.scope_id, vector, limit=request.search.limit)
        return SearchResult(hits=[SearchHit(ref=hit.ref, text=hit.summary, score=hit.score) for hit in hits])


async def setup(ctx: PluginContext) -> IncidentReports:
    index = await ctx.enter_async_context(VectorIndex.connect(ctx.storage.engine()))
    return IncidentReports(index, Summarizer(ctx.models))


plugin = ArtifactPlugin(
    family="incident-report",
    inputs=Inputs(source_types=("example-ticket",), projection="powercontext.text-evidence@1"),
    on_sources=True,
    setup=setup,
)

块内抛出异常时,core 回滚块内全部 Artifact 写入,游标不动,下次重试同一窗口。插件自有索引不在 core 的事务中: 插件按 (artifact_id, revision) 写入,旧 revision 的条目保留到被清理;检索结果由 core 过滤为当前 revision,回滚留下的 条目不会被返回(见参考级说明 3.5)。

4.4 调用方怎么使用

调用方使用现有的 Artifact 接口访问插件 family。读取接口直接读 pc_artifacts,不运行插件代码;展示、检索和修改接口 由 core 鉴权后,同步调用插件对应的方法:

用途接口插件方法
浏览GET /v1/scopes/{scope_id}/artifacts/{family}无
读取当前内容、指定 revision、revision 历史、tagsGET .../{artifact_id}、GET .../{artifact_id}/revisions/{revision}、GET .../{artifact_id}/revisions、GET .../{artifact_id}/tags无
默认展示GET .../{artifact_id}/rendering(可带 revision)render_artifact
检索(请求原样转交,检索方式由插件解释)POST /v1/scopes/{scope_id}/artifacts/{family}/searchsearch_artifacts
为 Agent 准备上下文POST /v1/context/prepare 的 assembly.sections 中列出插件 familysearch_artifacts
新建(只提交内容,ID 由 core 分配)POST /v1/scopes/{scope_id}/artifacts,请求体为 {"family": ..., "content": {...}}create_artifact
编辑(提交完整内容,If-Match 校验当前 revision)PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}update_artifact
读取治理状态(遗忘、合并前取得 state_version)GET .../{artifact_id}/governance无
合并POST /v1/scopes/{scope_id}/artifacts/{family}/mergesmerge_artifacts
遗忘POST .../{artifact_id}/forgetforget_artifact
恢复、恢复到旧 revision、撤销合并POST .../{artifact_id}/restorationsrestore_artifact
修改 tagsPUT .../{artifact_id}/tags;按 tag 查询用 POST /v1/scopes/{scope_id}/artifact-tags/query无,由 core 处理

修改同步返回结果。插件拒绝内容或请求时返回 422,插件没有实现对应方法时也返回 422,宿主进程超时或不可用时返回 503。

4.5 方法一览

方法适用必须实现调用时机执行位置
setup(ctx)所有插件是宿主进程启动时一次;Worker 每次调用一次宿主进程、Worker
Source 定义:input_class、resolve、Projection 的 project、read声明了 definitions 的插件是Source 写入(通用写入接口、ctx.sources.submit);把 Source 交付给 generate 时计算 Projection宿主进程、Worker
generateArtifact 插件配置了 schedule 或 on_sources 时是定时,或新 Source 到达Worker
render_artifactArtifact 插件是默认展示接口宿主进程
search_artifactsArtifact 插件否通用检索接口;Prepared Context 中列出该 family宿主进程
create_artifact、update_artifact、merge_artifacts、forget_artifact、restore_artifactArtifact 插件否对应的通用修改接口宿主进程

列出、读取当前内容或指定 revision、revision 历史、治理状态和 tags 不调用插件方法,由 core 直接从它保存的数据提供。 必须实现的方法在宿主进程执行 setup 之后核对,缺少时插件加载失败,状态为 failed。

5. 调度与触发

插件的后台调用(generate)的调度和触发都交给现有的 Artifact processing Supervisor;同步调用由请求触发, 不经过 Supervisor。每个插件在启动时注册为一个 Supervisor binding, binding 名为 plugin:<name>,调度键是 (binding, Scope)。

Artifact 插件:

声明何时派发 Workerrequest.reason
schedule=Interval(...) 或 schedule=Cron(...)到期时,对有待处理工作的 Scope有新 Source 时为 sources,否则为 schedule
on_sources=TrueScope 的 Source journal 超过该插件的游标,约 2 秒内派发sources
  • 配置了 inputs 的插件,每次调用都附带该 Scope 尚未消费的 Source 窗口;窗口中没有匹配的 Source 时不调用插件, 直接推进游标并确认。
  • 未配置 inputs 的插件(例如每天整理一次已有 Artifact)不消费 Source,到期即对 scopes 中的每个 Scope 调用一次; 第一版只支持 Interval。
  • Cron 只能用于配置了 inputs 的插件,且不能与 on_sources 同时使用:Supervisor 的每个 binding 只接受一种 interval 或 cron 策略。

同一插件、同一 Scope 同时最多运行一个 Worker。运行期间到达的触发由 Supervisor 合并成结束后的一次调用。

6. 运维

  • 启动:Server 逐个检查插件目录。某个插件检查失败(缺少 plugin.py、导入失败、声明无效、family 或 Source 类型 与内置或其他插件冲突)只影响该插件,Server 和其他插件正常启动。
  • 查看(都需要 server.admin,只读):检查结果来自启动检查,任何 Server 角色都相同;setup 之后才发现的失败(例如 缺少必需方法)只出现在启动了宿主进程的实例上,background 角色的实例看不到:
    • GET /v1/plugins、GET /v1/plugins/{name}:每个插件的检查结果、类型、family 或 Source 类型、消费的 Source 类型、 触发方式和 Scope 范围。
    • GET /v1/plugins/{name}/scopes:每个 Scope 是否有待处理的工作、已消费到的 journal 位置和当前 journal 位置。
    • 调用失败的原因通过日志和指标排查,不在接口中保存。
  • 变更:修改代码后重启 Server。Server 不监视文件,也不在运行中重新加载插件。
  • 停用:从插件目录移走后重启。已保存的 Source、Artifact 和游标都保留,但该插件的 family 和 Source 类型不再注册:通用接口读取、检索或修改该 family 时返回 404,与不存在的 family 相同。插件 Artifact 的内容通常只 记录摘要或位置,正文、分块和文件在插件自己的存储中,没有插件就无法解释,因此不提供脱离插件的读取。插件 Source 类型的 新写入返回 404,与未知的 Source 类型相同。重新部署同名插件时,读取恢复,生成从原游标继续。插件的专属存储 不随之删除,由部署者保留或清理。
  • 宿主进程:插件加载后由 core 启动,按负载增减,失去响应时重启。部署者可以调整每个插件的进程数上限和总上限(见参考 级说明第 6 节),不需要管理单个进程。宿主进程的启动、终止和重启只体现在日志和指标中。

参考级说明

1. 公共契约

公开接口位于新模块 powercontext.plugins,替换现有的 powercontext.artifact_plugins。接口以 typing.Protocol 和 Pydantic 模型表达。

1.1 声明与加载

class Interval(BaseModel):
    seconds: float                        # > 0

class Cron(BaseModel):
    expression: str
    timezone: str | None = None           # 默认为 Server 所在机器的时区

class ArtifactPlugin(BaseModel):          # 字段见指南级说明 4.2
    family: str
    inputs: Inputs | None = None
    ...
    setup: Callable[[PluginContext], Awaitable[ArtifactGenerator]]
  • 插件名取自目录名,必须匹配 ^[a-z][a-z0-9-]{0,63}$。
  • 声明在构造时校验,包括调度组合、inputs 与 scopes 的依赖、时限关系和 family 命名。setup 必须是 async 函数。
  • 声明中除 setup、definitions 等代码对象外的部分可以序列化,Server 在检查子进程中得到它, 用于注册 binding 和回答运维查询。
  • 检查时,core 记录插件目录的代码指纹(按文件内容计算)。Worker 和宿主进程导入插件前核对,不一致则调用失败并提示 重启 Server,同一个 Server 进程中的调用不会混用新旧代码。

1.2 上下文

class PluginContext:
    name: str                          # 插件名
    scope_id: str | None               # Worker 调用的 Scope;宿主进程中为 None,Scope 随每个请求传入
    plugin_dir: Path                   # 插件目录(只读约定)
    logger: logging.Logger             # 已绑定插件名的 logger
    storage: PluginStorage             # 插件专属存储
    models: PluginModels | None        # Server 已配置的模型;未配置时为 None

    async def enter_async_context(self, cm: AbstractAsyncContextManager[T]) -> T: ...

class PluginStorage(Protocol):
    backend: Literal["sqlite", "oceanbase", "seekdb"]
    def engine(self) -> AsyncEngine: ...   # 只指向本插件的专属空间

class ChatMessage(BaseModel):
    role: Literal["system", "user", "assistant"]
    content: str

class PluginModels(Protocol):
    embedding_available: bool                    # Server 是否配置了 embedding 模型
    embedding_dimension: int | None              # 向量维度;未配置时为 None
    generation_available: bool                   # Server 是否配置了生成模型
    async def embed(self, texts: Sequence[str], /) -> Sequence[Sequence[float]]: ...
    async def generate(self, messages: Sequence[ChatMessage], /, *, max_tokens: int | None = None) -> str: ...
    # 调用未配置的模型时抛出 ModelUnavailable;同步调用中返回 503
  • 工厂在每次 Worker 调用中执行一次,实例不跨调用复用;在宿主进程中只执行一次,实例服务所有 Scope 的请求,在宿主进程 存续期间复用,资源占用不随 Scope 数量增长。宿主进程中的每个请求都带有 scope_id。需要关闭的资源(包括插件自有存储的 连接)通过 ctx.enter_async_context 注册,Worker 调用结束或宿主进程停止时由执行器释放。
  • 专属存储:core 使用 Server 现有的数据库连接配置,在同一个后端上为插件分配一块空间,不需要额外的数据库账号:
    • SQLite:数据目录下的 plugins/<插件名>.sqlite3。
    • OceanBase / seekdb:同一个租户或实例上名为 powercontext_plugin_<插件名> 的库(- 换成 _),插件加载时由 core 创建,已存在则直接使用。Server 的数据库登录没有建库权限时,由部署者事先建好。库不存在又无法创建,或者库名超过 64 个字符 (插件名超过 44 个字符)时,插件照常加载,访问 ctx.storage 时报错并说明原因。一个租户或实例只承载一套部署, 库名因此不区分部署。
    • 表结构和迁移由插件自己管理,core 不读取、不迁移、不备份这块空间。它不在 core 的事务中,与核心数据的一致性按 3.5 处理。
    • 这块空间属于整个插件,不按 Scope 隔离。插件按 scope_id 划分自己的数据,并在读取时自行确认数据属于本次请求的 Scope, 不能只凭调用方给出的 ID 返回数据。
    • 插件与 Server 使用同一个数据库登录,这一划分防止插件误写 core 的表,不防止恶意插件;插件目录本身被当作可信代码。
  • 模型:models 封装 Server 的推理配置,插件拿不到模型的地址、请求头和凭据。Server 两种模型都没有配置时 models 为 None;只配置了其中一种时,插件用 embedding_available、generation_available 判断。插件应把 embedding_dimension 等 embedding 配置记在自己的索引上,配置变化后重建,避免把不同模型的向量混在一起比较。调用沿用 Server 的超时设置,并计入现有的模型用量统计。插件也可以从环境变量读取自己的 模型配置,自行创建客户端。
  • 插件得不到 core 数据库的连接,也没有游标的写入接口。插件对核心数据的写入只有两条路径:宿主进程中 resolve 的 返回值,和 ArtifactWriter。

2. 插件 Source 类型契约

  • 定义注册:definitions 中的 Source 类型与 Projection 在加载时登记到现有的 Source 定义清单 (pc_source_definition_manifests)。与内置类型、旧 Source 插件框架登记的类型或其他插件冲突时,检查失败。
  • 写入:core 按 definition.input_class 校验输入,调用 resolve 得到 Source,计算各 Projection 后保存,语义与内置 Source 写入一致。校验、resolve 和 Projection 在该插件的宿主进程中同步执行,使用 Server 的同步调用时限。resolve 必须是纯函数,不能有复制文件等副作用。
  • Source 身份:由 resolve 决定。重复提交同一内容得到相同身份时,沿用现有去重规则,不产生重复 Source;身份相同但 内容不同时返回冲突。
  • 权限:写入需要调用者对该 Scope 有 Source 写权限,并且 Scope 在插件的 scopes 范围内。
  • 发现:GET /v1/capabilities 与 pc_source_capabilities 列出已加载插件的 Source 类型。

3. Artifact 插件契约

3.1 请求

class ArtifactGenerator(Protocol):
    # 配置了 schedule 或 on_sources 时必须实现
    async def generate(self, request: GenerateRequest, writer: ArtifactWriter, /) -> None: ...

class GenerateRequest(BaseModel):
    scope_id: str
    reason: Literal["schedule", "sources"]
    sources: Sequence[GenerationSource]   # 本次窗口;未配置 inputs 时为空

class GenerationSource(BaseModel):
    ref: SourceRef                        # 精确 Source 引用
    position: int                         # Source 在 journal 中的位置,用于按写入顺序处理
    projection: JsonValue                 # 按该 Source 类型声明的 Projection 内容

3.2 写入器与写事务

class ArtifactWriter(ArtifactReads):
    family: str                           # 固定为声明中的 family
    def stable_id(self, *parts: str) -> str: ...
    def transaction(self) -> AbstractAsyncContextManager[ArtifactTransaction]: ...

class ArtifactTransaction(ArtifactReads):
    ...                                   # 读取(见 3.4)加写操作(见下表)

generate 的执行分两部分:

  • 事务外:插件通过 writer 读取已提交的数据(每次读取使用独立的只读短事务),完成模型调用、向量计算等耗时工作。
  • 写事务块:async with writer.transaction() as tx:。
    • 块开始时,core 开启写事务并重新校验 Supervisor 租约和调用意图。
    • 块内的写操作直接在该事务中执行,立即返回写入后的 ArtifactSnapshot(含精确 revision);块内读取能看到本块已写入的内容。
    • 块正常结束时,core 在同一事务中以 CAS 推进游标、确认本次调用并提交。
    • 块内抛出异常、超过 transaction_timeout_seconds 或提交冲突,事务整体回滚,本次调用失败。

规则:

  • 每次调用最多开启一个写事务块;第二次开启抛出异常。游标和调用确认只随这一个事务提交,因此一个窗口的核心数据不会 被部分提交。
  • 插件没有开启写事务块就正常返回,表示本窗口无需产出,执行器单独提交游标推进和调用确认。
  • 写事务块提交后,generate 中后续代码抛出的异常不再影响已提交的结果,执行器记录为提交后错误,不重试该窗口。 插件应把写事务块作为 generate 的最后一步。
  • 写事务块的时限计入整次调用的 timeout_seconds。块内只应做读取、写操作和插件自有存储的写入,不应调用模型。

3.3 写操作

写事务覆盖 Artifact 的全部通用写操作,每个操作复用 core 现有的实现与校验规则,违反规则时立即抛出异常:

操作语义
put(artifact_id, *, content, source_refs=(), artifact_refs=(), expected_revision=None)不存在则新建 revision 1;已存在则按当前 head 追加 revision。给出 expected_revision 时,当前 revision 不一致即冲突;不给出时,使用本次调用在事务外读到的 revision(见 3.5),没有读过则不校验。事务外读过的 Artifact 还会按读到的治理状态版本校验(见 3.5)。内容与当前 revision 相同时不写入,返回当前快照,本次传入的 source_refs 和 artifact_refs 不会被记录(见下方写入约束)。用户修改中的 put 例外,见 4.1
revert(artifact_id, *, to_revision)以历史 revision 的内容追加新 revision,记录 restored_from_revision;目标已被遗忘或被合并冻结时一并恢复。返回 ArtifactChange:目标的新快照,以及一并恢复和退役的其他 Artifact 的精确引用
set_lifecycle(artifact_id, state, *, replacement_artifact_id=None)deprecated 为遗忘,active 为恢复,retired 不可逆。恢复走共享恢复流程:记录一个内容相同的新 revision,被合并冻结的输入会撤销冻结它的合并,按组恢复。遗忘和退役不追加 revision。返回值同 revert,插件据此同步更新自有索引中受级联影响的条目
merge(inputs, *, into, content, source_refs=(), artifact_refs=())沿用公共合并方法(RFC #1859):以 inputs 的当前 revision 为输入,新建 into,记录合并关系并冻结输入。into 必须是新 ID;同一组输入在撤销后再次合并时,插件应把输入 revision 纳入 stable_id,避免与已退役的结果撞号
preview_undo_merge(artifact_id) / undo_merge(artifact_id)撤销产生该 Artifact 的合并,恢复输入并退役结果,返回恢复与退役的精确引用
bind_handle(handle_key, ref)把稳定 handle 绑定到指定 revision
set_tags(artifact_id, tags)整体替换该 Artifact 的 tags

写入约束:

  • 只能写本 Scope、声明中 family 的 Artifact,插件不能写其他 family 或 Scope。
  • source_refs 在 generate 中只能引用本次窗口中的 Source,在用户修改中只能引用目标 Artifact 当前 lineage 中已有的 Source(用于保留原始输入)。artifact_refs 可以引用本 Scope 中任意 family 实际存在的 revision;to_revision 和 bind_handle 的目标只能是本 family 中实际存在的 revision。
  • 内容不变时不产生 revision,与内置 Atomic Memory 的处理一致:模型判断已有记忆已经表达了新 Source 的内容时,该记忆 不追加 revision,新 Source 也不进入它的 lineage。插件需要把新 Source 记为某个 Artifact 的证据时,应同时修改其内容。
  • core 不为插件 family 提取检索文本或建立索引,检索由插件用自己的索引完成(见第 7 节)。
  • core 在每个 revision 的元数据中记录写入它的插件名和插件版本摘要,便于在多个 Server 加载了不同版本时追溯每个 revision 由哪个版本写入(见第 10 节)。
  • 每个写事务块的操作数、单份内容大小和总字节数有上限,超出即抛出异常并回滚,不截断、不部分提交。
  • core 不校验 content 的业务结构,也不保存或固化 schema。内容结构的演进由插件负责,插件可以在 content 中自带版本字段。

3.4 读取

ArtifactWriter(事务外,只读已提交数据)和 ArtifactTransaction(事务内,同时看到本块已写入的内容)提供相同的读取方法, 范围默认为本 Scope、本 family。reads(family) 返回同一 Scope 中其他 family 的只读视图,方法相同,可以读取内置 family 和其他插件的 family(内容按原样 JSON 返回),不能写入。这让一个插件可以基于另一个插件的结果工作,例如知识库插件读取 文档插件写入的 Artifact:

class ArtifactSnapshot(BaseModel):
    ref: ArtifactRef                      # 精确 revision
    content: dict[str, JsonValue]
    lineage: ArtifactLineage              # 直接引用的 Source 与 Artifact
    lifecycle_state: LifecycleState       # active / deprecated / retired
    merged_into_id: str | None            # 被合并冻结时指向合并结果
    replacement_artifact_id: str | None
    governance_generation: int            # 治理状态版本,用于判断读取后是否被修改

class ArtifactChange(BaseModel):          # revert / set_lifecycle 的返回值
    artifact: ArtifactSnapshot            # 目标的新快照
    restored: Sequence[ArtifactRef]       # 一并恢复的其他 Artifact
    retired: Sequence[ArtifactRef]        # 一并退役的其他 Artifact

class ArtifactReads(Protocol):
    async def get(self, artifact_id: str, *, revision: int | None = None) -> ArtifactSnapshot | None: ...
    async def revisions(self, artifact_id: str, *, cursor: str | None = None, limit: int = 50) -> ArtifactPage: ...
    async def list(self, *, states: Collection[LifecycleState] = ("active",), tags: Collection[str] = (),
                   cursor: str | None = None, limit: int = 50) -> ArtifactPage: ...
    async def by_source(self, ref: SourceRef) -> Sequence[ArtifactSnapshot]: ...
    async def merge_inputs(self, artifact_id: str) -> Sequence[ArtifactRef]: ...
    async def tags(self, artifact_id: str) -> Sequence[str]: ...
    async def resolve_handle(self, handle_key: str) -> ArtifactRef | None: ...
    def reads(self, family: str) -> ArtifactReads: ...   # 同一 Scope 中其他 family 的只读视图
  • 快照同时携带精确 revision、lineage 和当前治理状态,插件不需要再分别读取 lineage 和生命周期。
  • get 可以读当前内容或指定 revision;revisions 列出完整历史;merge_inputs 读取合并结果的精确输入。
  • list 可以按生命周期状态和 tags 过滤,包括 deprecated、retired 和被合并冻结的 Artifact,用于查找之前已经存在的数据。
  • by_source 反查 lineage 引用了某条 Source 的 Artifact,用于 Source 更新后找到需要修订的 Artifact。
  • 读取返回的快照都带精确 revision,可以直接作为写操作的 artifact_refs 或 to_revision。

3.5 一致性与幂等

  • 核心数据:每个窗口的 Artifact 写操作、游标推进和调用确认在一个事务中提交。失败时核心数据完全不变,重试从干净状态 开始;成功后游标已越过该窗口,同一窗口不会再次投递。冲突(例如 head 在读取后被用户修改)在操作时或提交时报告,整体 回滚后由 Supervisor 重新调度,下一次调用读到修改后的状态。
  • 重复处理同一业务对象:不消费 Source 的定时整理等场景会再次处理已经处理过的对象。插件用 writer.stable_id(...) 从业务 身份派生 Artifact ID;put 在内容相同时为 no-op,set_lifecycle 目标状态与当前相同时为 no-op,merge 在输入已全部 合并到同一结果时为 no-op,从而不会产生重复 Artifact 或无意义的 revision。
  • 事务外读取后写入:插件在事务外读到某个 Artifact,又在写事务块中对它 put 而没有给出 expected_revision 时,core 以事务外读到的 revision 作为期望值。读取后该 Artifact 被用户修改,写入即冲突,本次调用回滚后重新调度。这与内置 Atomic Memory 在提交前核对所读记忆是否变化的做法一致,用户修改不会被插件基于旧内容的写入静默覆盖。 遗忘、恢复和合并不一定改变 revision,所以 core 同时核对事务外读到的治理状态版本(governance_generation):读取后该 Artifact 被遗忘、恢复或合并,写入同样冲突。这项校验由 core 自动完成,插件不需要传入参数;给出 expected_revision 时也照常进行。改 tags 不改变治理状态版本,不会引起冲突。
  • 插件自有存储:插件的索引和其他存储(core 分配的专属存储,或插件自己连接的任何数据库、对象存储、向量库)不在 core 的事务中。插件用自己的客户端写入并提交自有存储,core 不参与,也不保证两者一致。core 的事务是核心数据的唯一提交点: 自有存储中的数据只有被 core 中已提交的 revision 引用后才算生效。这不需要两阶段提交,按下面的做法即可保持一致:
    1. 在写事务块内、拿到 ArtifactSnapshot 之后写自有存储,键为 (artifact_id, revision),不覆盖其他 revision 的条目。 这样自有存储的写入失败会让核心写入一起回滚。
    2. 写事务提交失败时,自有存储会留下一个没有提交的 revision 的条目,而当前 revision 的条目仍在。后台调用重试时会再次 写入同一个键;用户修改没有重试,留下的条目在下一次写入同一 revision 号时被覆盖,或被定期清理。
    3. 检索时,插件返回命中的精确 revision,core 只保留当前、active、调用者可读的 revision(参考级说明第 7 节),回滚 留下的条目和旧 revision 的条目都不会出现在结果中。插件在其他地方读取自有存储时,以 core 的当前快照为准。旧 revision 的条目由插件定期清理,也可以按 core 数据重建索引。
    4. 大块内容(正文、分块、文件字节)按内容摘要存成不可变的记录:先写入并提交到自有存储,再在写事务块中提交内容里 带有该摘要的 Artifact。不能用 (artifact_id, revision) 作为键:写事务回滚后,同一个 revision 号会再次分配给内容 不同的写入。按内容摘要存储时,重试写入同样的内容得到同一个键;提交失败只会留下没有被任何 revision 引用的记录, 由插件按"不被引用"定期清理。
  • 对插件自有存储的要求:上述做法与存储的种类无关,但存储需要满足三点,插件选型时自行确认,core 不做检查:
    • 能按插件给定的键幂等写入(upsert 或"不存在才插入")。只能由存储分配 ID 的系统,需要插件先确定 ID 再写入。
    • 写入返回时数据已经持久化。
    • 写入后立即可读。有刷新延迟的系统(例如 Elasticsearch 的 refresh 间隔、异步建索引的向量库)可能出现 core 已经引用、 自有存储中暂时读不到的情况,插件读取时需要重试或按暂时缺失处理。
  • generate 本身可能因失败重试而执行多次,模型调用和插件发出的外部请求不是恰好一次。

4. 用户对插件 Artifact 的修改

用户修改使用 core 的通用 Artifact 接口。Server 完成鉴权和版本预检后,把请求交给该插件的宿主进程;插件方法在宿主进程中 执行,通过写入器完成写入,结果在一个短事务中提交并同步返回。用户修改不进入 Supervisor,也不排队。

4.1 请求与方法

class CreateRequest(BaseModel):
    scope_id: str
    artifact_id: str                      # core 分配,调用方不提交
    content: dict[str, JsonValue]

class UpdateRequest(BaseModel):
    scope_id: str
    artifact_id: str
    expected_revision: int
    content: dict[str, JsonValue]

class MergeRequest(BaseModel):
    scope_id: str
    inputs: Sequence[MergeInput]          # 每项为 artifact_id、revision、state_version
    into: str                             # core 分配的结果 ID
    content: dict[str, JsonValue]

class ForgetRequest(BaseModel):
    scope_id: str
    artifact_id: str
    expected_revision: int
    expected_state_version: int

class RestoreRequest(BaseModel):
    scope_id: str
    artifact_id: str
    operation: Literal["restore", "undo_merge"]
    revision: int | None = None           # restore 时可指定恢复到的 revision

class InvalidContent(Exception):          # 插件拒绝内容;接口返回 422,消息和字段返回给调用方
    def __init__(self, message: str, *, field: str | None = None) -> None: ...
方法插件必须完成的写操作
create_artifact(request, writer)恰好一次 put(request.artifact_id, ...),目标此前不存在
update_artifact(request, writer)恰好一次 put(request.artifact_id, ..., expected_revision=request.expected_revision)
merge_artifacts(request, writer)恰好一次 merge(输入 ID, into=request.into, ...),输入与请求一致
forget_artifact(request, writer)恰好一次 set_lifecycle(request.artifact_id, "deprecated")
restore_artifact(request, writer)restore 为恰好一次 revert 或 set_lifecycle(..., "active");undo_merge 为恰好一次 undo_merge(request.artifact_id)
  • 这些调用中的写事务只允许上表对应的那一项写操作,以及对同一 Artifact 的 set_tags;写其他 Artifact 时立即抛出异常。 方法正常返回但没有完成要求的写操作,core 回滚并返回 502,表示插件没有按约定完成。
  • 请求中的 content 由插件解释。插件可以规范化内容(例如补全默认字段),也可以把它当作对一次修改的描述,据此算出要 写入的内容。写入的内容以插件交给写入器的为准。
  • create_artifact、update_artifact 中的 put 总是追加 revision,内容与当前 revision 相同时也一样。这与内置 family 的 编辑一致:每次用户编辑都有一条新的 lineage_only Content Source(见 4.2),需要一个新 revision 记录它。
  • 插件应在写事务块中、拿到快照之后更新自己的存储,做法同 3.5。

4.2 core 负责的部分

  • 鉴权:与内置 family 相同。新建和新建合并结果需要 Scope 的贡献权限,结果归属于调用者;修改已有 Artifact 需要该 Artifact 的写权限(artifact.write)。插件在这些调用中只获得完成本次请求所需的写入范围。
  • 版本校验:调用插件前先检查 If-Match、revision 和 state_version,不一致直接返回 412 或 409,不调用插件;提交时 在写事务中再次校验,期间被其他写入改变则回滚并返回 409。
  • 溯源:与内置 family 相同,新建、编辑、恢复和撤销合并时,core 在同一事务中把调用方提交的内容另存为一条内部 Content Source(lineage_only,操作分别为 artifact_create、artifact_replace、artifact_restore、artifact_undo_merge), 作为新 revision 的直接来源记入 lineage。新建和编辑时保存的是请求中的 content 原文;插件写入的内容与它不同时, 这条 Source 仍是调用方提交的那一份,插件写入的内容在新 revision 中。这类 Source 由 core 写入,不进入任何插件的输入窗口。
  • 合并注册表:通用的合并、遗忘、恢复接口建立在共享合并引擎(RFC #1859)的注册表之上,对所有登记过的 family 生效。内置 family 登记了 Experience 和 Atomic Memory, 由各自的适配器处理;插件 family 在加载时登记,处理方式是转交给插件对应的方法。没有登记的 family 返回 422。
  • 不提供预览:Atomic Memory 的专用接口支持先预览恢复影响、再凭签名 token 执行。通用接口不提供预览,也就不需要签名 密钥;恢复和撤销合并按执行时的当前状态进行,合并和遗忘依靠 revision 与 state_version 校验。
  • tags:GET / PUT .../{artifact_id}/tags 和 POST /v1/scopes/{scope_id}/artifact-tags/query 对插件 family 与内置 family 相同,由 core 直接处理,不调用插件,也不产生新的内容 revision。

4.3 接口

接口规则
POST /v1/scopes/{scope_id}/artifacts请求体增加插件分支 {"family": "<插件 family>", "content": {...}},family 不能是内置 family 的名字;ID 由 core 分配;响应与内置 family 的新建相同,包括 Location 和 ETag
PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}请求体为 {"content": {...}};If-Match 与当前 revision 不一致返回 412;Artifact 必须已存在
GET .../{artifact_id}/governance返回当前 revision、生命周期状态、state_version 和合并目标;由 core 处理
POST /v1/scopes/{scope_id}/artifacts/{family}/merges输入为至少两个当前 Artifact 的 artifact_id、revision、state_version,以及结果的完整内容;新建结果 Artifact 并冻结所有输入
POST .../{artifact_id}/forget携带 revision 和 state_version;把 Artifact 标为 deprecated(无替代者),不追加 revision,退出检索
POST .../{artifact_id}/restorationsoperation 为 restore(默认,可指定 revision 恢复到旧内容)或 undo_merge;按组执行级联恢复和退役
情况响应
插件没有实现对应方法422,说明该 family 不支持此操作
插件抛出 InvalidContent422,带插件给出的消息和字段
版本不一致412(If-Match)或 409(revision、state_version)
插件抛出其他异常500,只记录异常类型,不返回异常消息
插件没有完成要求的写操作502
超过 change_timeout_seconds、宿主进程不可用或处于重启退避503
  • 新建请求的插件分支没有判别映射:OpenAPI 无法为任意插件 family 写映射。内置分支保留原来按 family 的判别,插件分支与它 并列,由 family 名决定走哪个分支,内置 family 的请求不会被插件分支接受。这与 tags 接口把 family 改为字符串的处理相同。
  • 只有删除语义的需求(例如撤下一份文档)使用遗忘;core 不提供物理删除。插件可以在 forget_artifact 中清理自己存储中的 正文和索引,core 中的 revision 与 Source 保留。
  • 并发:用户修改与后台的 generate 可能同时发生。generate 对事务外读过的 Artifact 写入时,core 按读到的 revision 校验(见 3.5),发现冲突即整体回滚,下一次调用基于修改后的状态重新决策;用户修改不会被插件基于旧内容的写入静默覆盖。

5. 消费游标

Artifact 插件的每次后台调用处理该 Scope 中游标之后的一个 Source 窗口:

  • 窗口不超过 inputs.max_sources 条。窗口中没有匹配的 Source 时不加载插件,直接推进游标并确认。
  • 窗口内类型不匹配的 Source 被过滤,但游标仍推进过整个窗口;匹配类型的 Source 缺少所需 Projection 时调用失败,不跳过。
  • 游标只在执行器的提交事务中以 CAS 推进,插件得不到游标值,也没有写入接口。读取窗口与提交之间即使发生领导权变更或 重复派发,同一窗口也只提交一次。
  • 是否有待处理的工作由持久化数据判断(Source journal 位置与游标之差),Server 重启后不会丢失待处理输入。 on_sources 的插件在新 Source 写入后约 2 秒内被派发。
  • 未配置 scopes 时,自动调度对所有 journal 超过游标的 Scope 生效;配置了 scopes 时只接受名单内的 Scope。

6. 插件宿主进程

同步调用需要在请求时限内返回,不能每次都启动 Worker:每个 Worker 都是全新的 Python 进程,导入 core 的执行模块需要数秒。 因此同步调用交给常驻的宿主进程:

调用执行位置
Source 写入的输入校验、resolve、Projection宿主进程
create_artifact、update_artifact、merge_artifacts、forget_artifact、restore_artifact宿主进程
render_artifact、search_artifacts宿主进程
generateSupervisor Worker
  • 每个插件一组进程:每个 Server 进程为每个加载的插件维护一组宿主进程,不同插件不共用进程。一个插件阻塞、崩溃或被 终止不影响其他插件;以后按插件隔离依赖时,每个插件也需要自己的解释器。
  • 数量:插件加载后启动一个宿主进程并一直保留,插件都要实现 render_artifact,所以每个加载的插件至少有一个。本插件的 进程都在处理请求、且有请求排队时,core 再启动一个,直到本插件的上限;多出的进程空闲 5 分钟后停止。本插件的上限取 声明中的 host_processes,部署者可以用 POWERCONTEXT_SERVER_PLUGIN_HOST_PROCESSES(按插件名的 JSON)覆盖。所有插件的 宿主进程总数不超过 POWERCONTEXT_SERVER_PLUGIN_TOTAL_HOST_PROCESSES,达到总上限时不再为负载启动新进程,请求在已有进程上排队;每个插件常驻的第一个进程不受总上限限制。 新进程启动需要数秒,增加进程只对持续的负载有效。
  • 执行:宿主进程启动时导入一次 plugin.py 并核对声明,写入器在宿主进程中执行。一个宿主进程可以并发处理多个请求, 并发上限由 Server 配置决定;请求分给进行中请求最少的进程。
  • 超时:每次调用受各自的时限约束(Source 写入、展示和检索使用 Server 的同步调用时限,用户修改使用 change_timeout_seconds)。请求超过时限时,core 只取消这一个请求:插件在等待 I/O 时取消立即生效,写事务回滚,该请求 返回 504,同一进程中的其他请求不受影响。
  • 失去响应:宿主进程定时向 Server 报告心跳。插件阻塞了事件循环(CPU 密集的计算、没有 await 的阻塞调用)时,取消 无法生效,心跳也会中断;超过心跳时限后 core 终止该进程。在此之前已经超过自身时限的请求返回 504,终止时仍在进行中的 请求(包括造成阻塞的那个)返回 503。进程崩溃时进行中的请求同样返回 503。插件应把 CPU 密集的工作放进 asyncio.to_thread 或后台的 generate。
  • 重启:本插件没有可用的宿主进程时,core 在退避后重新启动;退避期间该插件的同步调用返回 503,后台调用不受影响。
  • 耗时的工作放到后台:增加进程只能缓解"慢但能在时限内完成"的请求。解析大文件、批量计算向量等以分钟计的工作, 插件应在接口中保存输入并提交 Source 后立即返回,由 generate 在 Worker 中处理,页面查询处理状态。
  • 代码变更:宿主进程在存续期间不重新导入插件,启动时核对代码指纹。修改插件后需要重启 Server,与 Worker 的规则一致。
  • 隔离:与 Worker 相同,宿主进程隔离普通故障,不是不可信代码的沙箱。

已激活插件的内存记录:每个 Server 进程在内存中记录本进程加载的插件:插件名、目录、类型、声明摘要、检查结果,以及 宿主进程的当前状态(未启动、运行中、重启退避)。路由用户请求、启动宿主进程和派发 Worker 都以这份记录为准。它不持久化, 也不跨进程同步;Server 重启后按插件目录重新建立。运维接口返回检查结果、声明和本实例宿主进程报告的永久失败,宿主进程的 运行状态通过日志和指标查看。

7. 公开读取、展示与检索

读取由 core 直接提供,不执行插件代码:

  • list / get / revisions / governance / tags 复用现有的通用 Artifact 读取路径。插件 family 的 content 按插件写入时的 JSON 原样返回,不需要 pc_artifact_family_schemas 中的 schema。被合并冻结、deprecated 和 retired 的 Artifact 按公共 合并与生命周期规则展示。
  • list 返回的条目只含元数据,title 和 summary 对插件 family 为空;内容需要通过 get 读取。

插件可能只在 content 中保存摘要或引用,把大块内容放在自己的存储中(例如知识库文档只记录切块组的摘要),这时原样返回 的 content 不足以展示。展示和检索因此交给插件:

class RenderRequest(BaseModel):
    scope_id: str
    artifact: ArtifactSnapshot            # 要展示的精确 revision
    caller: Caller | None

class Rendering(BaseModel):
    format: Literal["markdown", "text"] = "markdown"
    text: str

class SearchRequest(BaseModel):
    scope_id: str
    search: dict[str, JsonValue]          # 通用检索接口的完整请求(JSON),原样转交
    max_bytes: int | None = None          # 来自 Prepared Context 时,请求的字节预算
    caller: Caller | None

class SearchHit(BaseModel):
    ref: ArtifactRef                      # 命中的精确 revision
    text: str                             # 用作上下文的片段,例如一个切块
    score: float | None = None
    locator: dict[str, JsonValue] | None = None   # 片段在 Artifact 中的位置,例如页码、切块序号

class SearchResult(BaseModel):
    hits: Sequence[SearchHit]
  • 展示:GET .../{artifact_id}/rendering 调用 render_artifact,返回插件给出的默认展示内容;原始 content 仍由读取 接口返回,供程序使用。同一 revision 在同一插件版本下的展示结果不变,core 可以按 family、ID、revision 和插件版本缓存。 内置 family 不提供这个接口。
  • 检索:通用检索接口把 SearchArtifactsRequest 的全部字段(query、query_vector、indexes、mode、filters、 admission、fusion、rerank、min_score 等,include_scores 除外,它只决定 core 是否返回分数)原样交给 search_artifacts,由插件按自己的索引解释;插件不支持的参数 抛出 InvalidContent,接口返回 422。core 只保留命中中调用者有权读取的 active 当前 revision,按插件给出的顺序返回 精确 revision,include_scores 时附带插件给出的分数。插件因此不能借检索返回调用者看不到的数据。过滤后的结果可能 少于请求的数量,core 不补取。
  • Prepared Context:assembly.sections 可以列出插件 family。core 以 Prepared Context 的 query、该项的 limit 和 请求的字节预算调用 search_artifacts,把命中的片段作为上下文条目按 section 顺序装填,与内置 family 一样带精确 revision 引用、计入字节预算和回执,超出预算的条目被截断或省略。插件不可用(宿主进程不可用、超时或检索失败)时,core 省略该 section,在回执中记录省略的原因,其他 section 照常返回。每项可以携带可选的 search,内容是检索请求中除 query、 limit 以外的字段,原样转交插件;内置 family 携带 search 时返回 422。
  • Review 和 Recall 不对插件 family 开放,对应接口返回明确的“不支持”错误;GET /v1/capabilities 列出插件 family。

8. 加载与生命周期

  • Server 启动时检查 POWERCONTEXT_SERVER_PLUGINS_DIR 的每个直接子目录(未设置则不加载插件):在有时限的子进程中导入 plugin.py 并校验声明,不调用 setup。检查通过后注册插件提供的 Source 类型或 family(读取、检索和通用合并接口), 有调度或触发时注册 Supervisor binding,并写入本进程的已激活插件记录。检查失败只影响该插件。
  • Server 停止时先停止接受同步调用、结束宿主进程,再按现有流程停止 Supervisor 并回收 Worker。
  • 插件只有 loaded 和 failed 两种结果,只存在于进程内存中。Server 不持久化插件的启用状态、注册代次或配置快照; 每次启动按当时的目录内容重新检查。插件代码只在检查子进程、宿主进程和 Worker 中导入,Server 进程不导入插件代码。
  • 没有热加载,因此不需要注册代次来屏蔽旧 Worker,现有的 Supervisor 租约 fence 已经足以屏蔽领导权变更后的旧提交。
  • Worker 每次调用重新导入插件代码,导入前核对代码指纹(见 1.1)。插件目录在 Server 运行期间被修改后,新的 Worker 调用 和新启动的宿主进程都会失败并提示重启,不会出现同一个 Server 中新旧代码混用。部署者应在修改后重启 Server。
  • api 角色的 Server 实例不运行后台任务,但也会检查插件并注册 family 和 Source 类型,用于读取、检索、Source 写入和用户 修改;它启动宿主进程,不派发 Worker。background 角色的实例不接收请求,不启动宿主进程。
  • 运行中增减插件(热加载)和插件自定义 API 见 RFC #2579,建立在宿主进程之上。

9. 执行约束

  • 隔离:generate 在 Supervisor 启动的 Worker 子进程中执行,同步调用在宿主进程中执行,崩溃、内存泄漏和 阻塞不影响 Server。子进程隔离普通故障,不是不可信代码的沙箱:插件以子进程的操作系统权限运行,可以访问其文件、网络和 环境变量。
  • 超时与预算:timeout_seconds 是 Worker 总时限,transaction_timeout_seconds 是写事务块时限,max_workers 是该插件 跨 Scope 的并发上限,分别映射到 Supervisor binding 的现有参数或由执行器强制。
  • 写事务的锁影响:写事务块持有期间会锁住涉及的 head 和游标行;在 SQLite 上,写事务会阻塞整个数据库的其他写入。 因此写事务块必须短,时限超出即回滚。
  • 遗留的调用意图:插件移除后,它遗留的调用意图不再被处理,也不阻塞数据库就绪检查。
  • 失败与退避:调用失败时不提交任何核心数据,该插件该 Scope 进入 Supervisor 现有的退避,不影响其他 Scope 和插件。 core 不会因为重复失败自动跳过输入;持续失败需要修复插件或数据后重启。
  • 多实例部署:OceanBase 多 Server 实例时,派发只发生在持有 Supervisor 领导租约的实例上;Source 写入、读取、 展示、检索和用户修改可以在任意实例执行,各实例使用自己的宿主进程。插件自有存储需要能被所有实例访问;core 分配的专属存储 位于共享的数据库后端上,天然满足这一点。SQLite 部署只有一个 Server 进程。

10. 持久化

数据处理
pc_sources、Projection、Source journal、pc_source_definition_manifests保留;插件 Source 类型的定义与写入结果
pc_artifacts、pc_artifact_heads、pc_artifact_lineage_*、合并记录、handle、tags保留;Artifact 插件的结果
pc_source_cursors保留;Artifact 插件的消费游标,键为 (scope_id, plugin:<name>)
Supervisor 的调用意图、pending、租约表保留;插件 binding 与内置 binding 共用,也是 GET /v1/plugins/{name}/scopes 的数据来源。插件 binding 以 plugin: 开头,不在数据库中登记
pc_artifacts 的新列 metadata新增;可为空,按与 content 相同的方式保存规范化 JSON 字节,存放不参与检索的附加信息。插件写入的 revision 记录插件名和插件版本摘要,内置 family 为空。不参与内容摘要的计算
pc_artifact_fts 与 pc_artifact_heads.searchable_text只用于内置 family;插件 family 不写入
pc_artifact_processing_binding_states 中为旧插件框架新增的列(期望状态、管理阶段、注册代次等)移除
pc_artifact_family_schemas移除
自定义 family 声明式索引使用的搜索状态与向量索引数据移除;实现 PR 确认内置 family 不依赖后删除对应表
旧 Artifact 插件写入的 Artifact、head、lineage不迁移;留有数据时拒绝升级,见下文
插件专属存储(plugins/<插件名>.sqlite3 或 powercontext_plugin_<插件名> 库)不属于 core 的 schema;core 只负责分配,表结构、迁移和清理由插件和部署者负责
插件自有的其他索引与存储不属于 core,由插件和部署者管理

新增与移除通过一个新的迁移版本完成,已发布版本的迁移资源保持不变。迁移说明中列出新增、删除的表、列和数据范围。 迁移检查(preflight)先确认旧 Artifact 插件框架没有留下数据:旧插件 family 的 Artifact、旧插件的登记与调用意图。 发现任何一项时拒绝升级,指出保留记录的存储,数据库保持不变。 这些数据库目前没有受支持的原地升级路径。卸载插件、删除插件目录或导出归档不会清除框架保留的记录,即使没有生成 Artifact 也是如此。请保留数据库并继续使用旧版本,等待受支持的迁移方案。可以使用独立的新数据库运行新版本,但这不会迁移旧插件数据;不要手工删除框架记录来绕过检查。只有这些表为空时,迁移才删除它们。

这个版本的就绪检查(Server 每次启动时对当前数据库执行)与旧版本有两点不同:

  • 调用意图中以 plugin: 开头的 binding 视为插件 binding,不要求在数据库中登记。插件被移除后遗留的意图不处理、 可以在运维接口中看到,不阻止 Server 启动;同名插件重新放入后继续处理。
  • 全文索引的核对只覆盖内置 family 的数据。

导出与恢复(portable archive)中 Artifact revision 记录的格式版本加一,包含 metadata。恢复旧格式的导出时 metadata 为空;旧版本的 Server 不能恢复新格式的导出。

11. 接口变更

变更内容
移除/v1/admin/artifact-plugins 及其子路径;旧 Artifact 插件的 plugin.yml 清单
移除自定义 family 的声明式索引(ArtifactSearchDeclaration、TextIndex 等)、ArtifactFamily 的 schema 声明、ArtifactDraft 和旧的 Worker 插件执行器
新增powercontext.plugins:ArtifactPlugin、Inputs、Interval、Cron、PluginContext、PluginStorage、PluginModels、写入器与读取接口、用户修改的请求模型与 InvalidContent、展示与检索的请求和结果模型
调整POST /v1/scopes/{scope_id}/artifacts 的请求体增加插件分支 {"family", "content"},ID 由 core 分配,由插件的 create_artifact 处理。CreateArtifactRequest 改为内置分支 CreateBuiltinArtifactRequest(原有的按 family 区分的联合类型)与插件分支 CreatePluginArtifactRequest 的二选一,按 family 名选择:内置 family 名走内置分支,校验与原来相同;其他名字走插件分支,没有插件提供该 family 时返回 422。生成的 Python 客户端中,内置请求多包一层;ArtifactCreated.family 从内置 family 枚举改为字符串
调整POST /v1/scopes/{scope_id}/sources 的 source_type 从只能是 content 的枚举改为字符串(默认仍为 content),可以是插件定义的 Source 类型,此时 content 是该类型的输入,由插件校验并解析为 Source;未知类型返回 404。SourceType 枚举保留
新增GET /v1/plugins、GET /v1/plugins/{name}、GET /v1/plugins/{name}/scopes(server.admin,只读)
新增GET .../{artifact_id}/governance、POST /v1/scopes/{scope_id}/artifacts/{family}/merges、POST .../{artifact_id}/forget、POST .../{artifact_id}/restorations:基于共享合并引擎注册表的通用接口,对所有登记过的 family 生效(内置为 Experience 和 Atomic Memory,以及加载的插件 family;插件 family 由插件对应的方法处理)。Atomic Memory 的专用接口保持不变
调整PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id} 接受插件 family,请求体为 {"content": {...}},由插件的 update_artifact 处理
调整tags 接口接受插件 family:TaggableArtifactFamily 从枚举改为与 ArtifactReadFamily 相同格式的字符串,服务端校验为内置 family 或已加载的插件 family。网络上的数据格式不变,生成的客户端少了这个枚举类型
调整通用 Artifact 读取接口支持插件 family;通用检索接口对插件 family 把完整请求交给插件的 search_artifacts,未实现时返回 422;GET /v1/capabilities 列出插件 family
新增GET /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}/rendering:插件 family 的默认展示内容,由插件的 render_artifact 提供
调整POST /v1/context/prepare:ContextAssemblySection.family 从枚举改为字符串,可以是已加载的插件 family;新增可选的 search(检索请求中除 query、limit 以外的字段),只对插件 family 生效;回执中条目的 family 从枚举改为字符串,可以是插件 family
调整导出与恢复的 Artifact revision 记录格式版本加一,增加 metadata
调整环境变量 POWERCONTEXT_SERVER_PLUGINS_DIR 取代 POWERCONTEXT_SERVER_ARTIFACT_PLUGINS_DIR
新增环境变量 POWERCONTEXT_SERVER_PLUGIN_HOST_PROCESSES(按插件名覆盖宿主进程数上限的 JSON)、POWERCONTEXT_SERVER_PLUGIN_TOTAL_HOST_PROCESSES(每个 Server 进程中宿主进程的总上限)

openapi/powercontext.yaml 按上表更新后重新生成 src/powercontext/http/_generated/ 和各集成的操作表。

12. 可观测性

插件调用复用 Supervisor 与 Worker 现有的操作词汇、执行身份和结果字段,不为定时调用生成 request ID。新增的字段标识 插件名、调用的方法、执行位置(Worker 或宿主进程)、触发原因和写入规模;宿主进程的启动、终止和重启各记录一条事件。

  • 指标标签可以使用插件名、方法和执行位置,不包含 Scope ID。
  • 日志经 log_safely 输出,不包含 Source 内容、Projection、Artifact 内容和环境变量值;插件异常只记录类型和 已知错误分类,不记录异常消息。
  • 新增字段按开发指南登记到允许列表,并在中英文可观测性文档中说明。
  • 调用结果只进入日志和指标,不持久化,运维接口不提供“最近一次调用结果”。

缺点

  • 宿主进程常驻占用资源:每个 Server 进程为每个加载的插件至少多一个常驻进程,负载高时更多,多实例部署时数量随实例数 增加。每个宿主进程都是完整的解释器,加载了 core 运行时和插件,内存占用与 Server 进程同一量级,插件依赖越多占用越大。 同步调用多一次进程间往返和序列化。
  • 同步调用依赖插件可用:宿主进程崩溃或处于重启退避时,该插件的 Source 写入和用户修改返回 503;插件代码中的缺陷会 直接表现为用户请求失败。阻塞事件循环的插件会让同一进程中的其他请求一起失败。
  • 写事务持锁:写事务块期间持有数据库锁,SQLite 上会阻塞其他写入。插件若在块内执行慢操作,会拖慢整个 Server 的写入, 直到块超时回滚。
  • 插件自有存储与核心数据不保证一致:两者不在同一事务中,提交失败可能在自有存储中留下条目。插件需要按稳定 ID 覆盖、 按内容摘要保存不可变记录、清理未被引用的记录,并以 core 的当前数据为准;自有存储还要满足幂等写入、写入即持久和 写后可读的要求。
  • 后台调用每次都要启动 Worker 并加载插件:子进程启动和工厂初始化有固定开销,不适合秒级高频的后台调用;插件不能在 Worker 调用之间复用连接或缓存。
  • 专属存储只按约定隔离:插件与 Server 使用同一个数据库登录,技术上能访问 core 的表。
  • 新旧 Source 扩展方式并存:在后续提案落地前,添加 Source 类型有两种方式:本提案中插件自带的 Source 类型,以及旧 Source 插件框架的 write 插件。两者登记到同一份定义清单,名字不能重复。
  • 不是安全沙箱:Worker 隔离普通故障,不限制插件的文件、网络和凭据访问,也不提供硬性的内存或 CPU 配额。
  • 依赖必须兼容:所有插件与 Server 共用一个 Python 环境,依赖冲突需要部署者解决。
  • 同一份代码部署多次需要额外处理:family 写在声明中,同一份代码复制成两个目录会因 family 冲突而检查失败。需要多次 部署时,插件应从环境变量读取 family 等标识。
  • 内容结构不受 core 治理:core 不校验 content 的 schema,用户提交的内容由插件校验;历史 revision 的解释需要插件和 应用自行保持兼容。
  • 展示和检索依赖插件:插件 family 的展示、检索和 Prepared Context 都要进入宿主进程,插件不可用时展示和检索返回 503,Prepared Context 省略该 section; 插件没有实现 search_artifacts 时,它的数据不能通过通用检索和 Prepared Context 使用。
  • 多个 Server 的插件版本可能不一致:core 记录每个 revision 由哪个插件版本写入,但不阻止不同实例加载不同版本;新旧 版本能否同时读写同一份数据,由插件负责。汇总各实例当前加载的版本需要维护一张实例登记表,留给插件安装的后续提案。
  • 代码变更需要重启:没有热加载,插件更新期间 Server 会短暂不可用。

理由与备选

方案取舍
保留现有设计,只简化接口插件作者体验改善有限,生命周期状态机、管理服务和 schema 固化的维护成本仍在
清单文件(YAML)描述插件插件需要同时维护清单和代码,两者的字段要保持一致;清单中的变量替换、配置模型和导出约定又是一套额外规则。声明写在代码里,由同一个 Pydantic 模型校验,插件作者只写 Python
插件在 Server 进程内执行部署和调用最简单,但插件故障会拖垮 Server;Supervisor 已经提供隔离和调度,没有理由另起一套
插件完全自管存储和游标core 读取接口无法直接使用,各插件需要重复实现窗口读取与幂等,游标与结果也难以原子提交
插件返回草稿,或由写入器在内存中暂存操作,最后统一提交可以原子提交,但插件在提交前拿不到真实的 revision,难以同步写入自有索引;合并、撤销合并、生命周期等操作需要在内存中重新实现一遍 core 的语义;检索也看不到暂存内容
用一个事务包住整个 generate模型调用可能持续数分钟,长时间持锁会阻塞其他写入,SQLite 上会阻塞整个数据库;插件自有存储是另一个数据库,一个事务本来也覆盖不了
generate 内的短写事务块(本提案)耗时工作在块外;块内直接复用 core 的写操作和校验,拿到真实 revision,读取能看到本块写入;块结束时与游标、确认一起提交,异常即回滚。代价是块内持锁,需要时限约束
用户修改排队,插件在下一次后台调用中处理调用方只能异步等待;一个始终失败的修改会阻塞该 Scope 的后续生成;还需要持久化请求队列,而 core 目前没有任务管理机制
用户修改由 core 直接执行,不经过插件实现简单,但插件拿不到用户提交的内容:无法校验,自有存储和索引只能等之后重建才能跟上。存储由插件决定,修改也应由插件处理;内置 family 的新建和编辑同样经过各自的 family 代码
用一个 write 方法同时处理新建和编辑新建不带 ID、由 core 分配,编辑必须指定 ID 和期望 revision;两者的输入和校验不同,合成一个方法需要插件自己分辨
同步调用每次派发一个 Worker复用现有机制,但 Worker 每次都启动新的 Python 进程,仅导入 core 模块就需要数秒,不能放在用户请求路径上
Source 的 resolve 等代码在 Server 进程中执行省去进程间往返,但插件阻塞或崩溃会影响 Server;插件的同级模块以顶层名字进入 sys.modules,多个插件的同名模块会互相冲突,后续也无法可靠地重新加载
常驻宿主进程处理同步调用,Worker 处理后台调用(本提案)同步调用不需要每次启动进程,Server 进程不导入插件代码;后台调用保留 Worker 的按次隔离和预算。代价是常驻进程的资源占用和进程管理
插件存储进入 core 的事务(插件在 core 库中建表)可以原子提交,但 core 要管理插件的迁移、升级和权限,三种后端都要支持,插件数据会混入 core 的 schema。插件的存储由插件决定,不放进 core
插件存储与 core 之间用两阶段提交对象存储、向量库等多数插件存储不支持 XA,core 也要为每种存储实现协调者。按内容摘要先写不可变记录、以 core 的提交为唯一生效点,就能得到需要的一致性
一个插件声明多个 family可以在一个事务中写多个 family,但声明、权限和合并注册都要按多 family 设计。需要配合的场景用两个插件加跨 family 只读即可
把 core 的环境变量或数据库配置交给插件core 的配置不全来自环境变量;插件拿到 core 的数据库凭据就能绕过写入器。提供封装好的 ctx.storage 和 ctx.models
插件专用的触发与管理接口调用方要区分插件与内置能力;现有的 Source 与 Artifact 接口已经覆盖调用方需要的操作
通用合并接口只对插件 family 开放需要在接口里额外维护一份 family 白名单。能操作哪些 family 本来就由注册表决定,没有适配器的 family 无法登记;内置 family 的权限检查在引擎内,两个入口走同一套检查
core 按声明的字段为插件 family 建全文索引插件作者不用自建索引,但 core 不知道内容怎样分块、是否适合全文或向量检索,建出的索引常常用不上;还要与内置 family 共用索引表,就绪检查也要区分两者。检索交给插件,core 只负责权限过滤
读取也经过插件(例如 read_artifact 展开内容)通用读取就能拿到完整内容,但最常用的读取路径每次都要进入宿主进程,插件不可用时连读取都失败。读取保持由 core 提供,展示另设接口
在数据库中登记插件 binding 与 family(旧 Artifact 插件框架的做法)能发现其他插件冒用已有 family 和遗留的调用意图,但 core 要保存并维护插件状态,还要提供解除冲突的管理操作。新框架没有稳定的插件身份,登记表能多发现的问题有限;留到插件安装与分发的提案中,与插件身份一起设计
插件版本记在单独的表、created_by 或 content 的保留键中单独的表同样要进入导出与恢复;改动 created_by 或 content 会改变已有字段的含义和内容摘要。metadata 列只需一次加列和导出格式升级
本提案中支持热加载需要处理多实例各自重新扫描、旧 Worker 提交的屏蔽和宿主进程切换,单独提案更清楚

选择这一方案的原因:

  • 插件作者只需写一个 plugin.py:一个声明、一个工厂、一两个方法。
  • 调用方只用现有的 Source 与 Artifact 接口,不感知插件。
  • 隔离、调度、触发、退避和领导权都复用已经在生产中使用的 Supervisor。
  • 写操作直接复用 core 现有实现,插件写入和用户修改遵循同一套语义;用户修改经过插件,插件存储能同步更新。
  • Source 与 Artifact 留在 core 的统一存储中,现有读取接口、lineage、合并记录和访问控制直接适用。
  • core 只管理两类核心数据及其进度,其余交给插件。

先例

  • Dify 插件:按插件类型定义接口,插件实现对应方法,Dify 在工作流或应用需要时调用;插件运行在独立的插件守护进程中。 本提案沿用“宿主定义接口与调用时机”的思路:同步调用使用 core 管理的常驻宿主进程,后台调用复用 PowerContext 已有的 Supervisor Worker。
  • pytest 插件与 setuptools entry points:插件以 Python 对象声明自己提供的能力,宿主导入后读取,不需要单独的清单文件。
  • 事务上下文管理器:SQLAlchemy 的 async with engine.begin() 等接口在块开始时开启事务、正常结束时提交、异常时回滚。 writer.transaction() 沿用这一使用方式,并在提交时附带游标与调用确认。
  • PowerContext 现有基础:Artifact processing Supervisor 的调度、调用意图、 Worker 与租约 fence;公共合并方法;通用 Artifact 读写接口与内置 family 编辑时记录的 lineage_only Content Source;SourceDefinition / SourceProjection、Source journal 与消费游标。

未决问题

问题说明
写事务块的时限与限额默认值默认 30 秒是否合适;SQLite 与 OceanBase 是否采用不同默认值;单块操作数与字节上限
宿主进程的默认参数同步调用时限、单个宿主进程的并发上限、心跳时限、空闲停止时间、宿主进程总上限和重启退避的默认值
专属存储的建库权限Server 的数据库登录没有建库权限时,除了由部署者事先建库,是否允许退回到 core 库中按插件名前缀建表
插件 family 接入 RecallPrepared Context 已接入,Recall 是否需要接入、候选内容怎样定义
通用检索结果带片段通用检索接口目前只返回精确 revision,插件返回的片段只用于 Prepared Context。是否在检索结果中增加片段和位置
family 与 Source 类型的命名是否要求以插件名为前缀,从命名上避免不同插件冒用同一个 family。要求前缀后,plugin.py 导入失败时 core 也能从 family 名找到对应的插件目录,对该 family 返回 503 而不是 404,与插件已移除区分
Prepared Context 的检索控制内置 family 也接受每项的 search,是新增的可选字段,不影响现有调用,建议另行提案。Prepared Context 中其他按功能定制的参数,移除或改名是不兼容变更,需要新的 API 版本,不在 v1 中整理
窗口大小的回退内置 Atomic Memory 在模型超时时会缩小下一次的 Source 窗口。插件无法影响窗口大小,过大的窗口会持续超时。是否允许插件以约定的异常请求缩小该 Scope 的窗口
持续失败的窗口始终失败的 Source 窗口会阻塞该 Scope 的后续调用。是否提供跳过或转入死信的运维操作,以及如何记录被跳过的输入
消费全部 Source 类型inputs.source_types 需要逐一列出类型;内置 Atomic Memory 消费所有可用于生成的 Source。是否支持 "*" 表示全部类型
内置专属能力Scope Prompt 管理、写入闸门与决策观测、模型用量统计目前只服务内置 family,插件无法接入。是否以及如何向插件开放
Atomic Memory 专用接口的去留通用合并接口上线后,Atomic Memory 的合并、遗忘、恢复同时有专用和通用两个入口,行为一致。专用接口是否保留,或改为通用接口的别名

后续可能

  • 热加载与插件自定义 API(含插件页面):建立在宿主进程之上,见 RFC #2579。
  • 独立的 Source 插件与采集:只提供 Source 类型的插件;采集目标的集中配置与设备拉取同步;在设备上运行采集并把 Source 汇报到中心;大文件的传输。由后续提案定义,并取代旧 Source 插件框架。
  • 后台调用也改用常驻进程,在保持接口不变的前提下复用连接和初始化结果。
  • 更多插件类型,例如为 Recall 提供候选内容、为 Prepared Context 提供文本片段。
  • 插件安装与依赖:从 PyPI、Git 地址或 wheel 安装插件,每个插件独立的依赖环境,以及记录各实例加载的插件版本的登记表。

On this page