插件接口
- Proposal Name:
plugin_interfaces - Start Date: 2026-11-08
- RFC PR: oceanbase/powercontext#2549
概要
本提案重新定义 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 等系统的插件模型也说明,宿主定义接口和调用时机、 插件只实现接口,足以支撑大量第三方扩展。
本提案的目标:
- 插件作者只需写一个
plugin.py:一个声明对象和几个方法,不需要理解插件管理的内部机制。 - 调用方不感知插件:Source 和 Artifact 的现有接口对插件产生的数据同样适用。
- 插件代码只在 core 管理的子进程中执行(Worker 或插件宿主进程),插件故障不影响 Server 和其他插件。
- 插件结果进入
pc_sources/pc_artifacts,与消费进度原子提交。 - core 只管理这两类核心数据及其消费进度;内容结构、索引和其他存储交给插件自己。
- 插件对核心数据的写入只经过 core 提供的写入器,覆盖 Artifact 的全部通用写操作,并沿用 core 现有的校验规则。
- 用户对插件 Artifact 的修改经过插件,插件自有存储能与修改同步更新。
- Artifact 生成可以按调度执行,也可以由新 Source 触发。
- 用户只需部署一个 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.pyplugin.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 或其他插件重复 |
inputs | None | Inputs(source_types=..., projection=..., projections={...}, max_sources=50):消费的 Source 类型、每条 Source 交付的 Projection、单个窗口的条数上限;为空表示不消费 Source。projection 适用于所有类型,projections 按 Source 类型指定不同的 Projection,每个类型必须有其一 |
on_sources | False | 新 Source 到达后触发;需要 inputs |
schedule | None | Interval(seconds=...) 或 Cron(expression=..., timezone=...)。schedule 和 on_sources 都不配置时插件没有后台生成,不需要实现 generate,Artifact 只由用户修改和插件接口写入(例如笔记) |
scopes | None | 可服务的 Scope 名单;配置了 schedule 但不消费 Source 的插件必须填写 |
timeout_seconds | 300 | 整次调用的时限 |
transaction_timeout_seconds | 30 | 写事务块的时限,不超过 timeout_seconds |
max_workers | 1 | 跨 Scope 的并发上限 |
host_processes | 1 | 每个 Server 进程中本插件宿主进程数的建议上限,部署者可以按插件覆盖;接口请求较重的插件可以调大 |
change_timeout_seconds | 30 | 一次用户修改调用的时限,包括其中的写事务块 |
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 历史、tags | GET .../{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}/search | search_artifacts |
| 为 Agent 准备上下文 | POST /v1/context/prepare 的 assembly.sections 中列出插件 family | search_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}/merges | merge_artifacts |
| 遗忘 | POST .../{artifact_id}/forget | forget_artifact |
| 恢复、恢复到旧 revision、撤销合并 | POST .../{artifact_id}/restorations | restore_artifact |
| 修改 tags | PUT .../{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 |
generate | Artifact 插件 | 配置了 schedule 或 on_sources 时是 | 定时,或新 Source 到达 | Worker |
render_artifact | Artifact 插件 | 是 | 默认展示接口 | 宿主进程 |
search_artifacts | Artifact 插件 | 否 | 通用检索接口;Prepared Context 中列出该 family | 宿主进程 |
create_artifact、update_artifact、merge_artifacts、forget_artifact、restore_artifact | Artifact 插件 | 否 | 对应的通用修改接口 | 宿主进程 |
列出、读取当前内容或指定 revision、revision 历史、治理状态和 tags 不调用插件方法,由 core 直接从它保存的数据提供。
必须实现的方法在宿主进程执行 setup 之后核对,缺少时插件加载失败,状态为 failed。
5. 调度与触发
插件的后台调用(generate)的调度和触发都交给现有的 Artifact processing Supervisor;同步调用由请求触发,
不经过 Supervisor。每个插件在启动时注册为一个 Supervisor binding,
binding 名为 plugin:<name>,调度键是 (binding, Scope)。
Artifact 插件:
| 声明 | 何时派发 Worker | request.reason |
|---|---|---|
schedule=Interval(...) 或 schedule=Cron(...) | 到期时,对有待处理工作的 Scope | 有新 Source 时为 sources,否则为 schedule |
on_sources=True | Scope 的 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 的表,不防止恶意插件;插件目录本身被当作可信代码。
- SQLite:数据目录下的
- 模型:
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 引用后才算生效。这不需要两阶段提交,按下面的做法即可保持一致:
- 在写事务块内、拿到
ArtifactSnapshot之后写自有存储,键为(artifact_id, revision),不覆盖其他 revision 的条目。 这样自有存储的写入失败会让核心写入一起回滚。 - 写事务提交失败时,自有存储会留下一个没有提交的 revision 的条目,而当前 revision 的条目仍在。后台调用重试时会再次 写入同一个键;用户修改没有重试,留下的条目在下一次写入同一 revision 号时被覆盖,或被定期清理。
- 检索时,插件返回命中的精确 revision,core 只保留当前、active、调用者可读的 revision(参考级说明第 7 节),回滚 留下的条目和旧 revision 的条目都不会出现在结果中。插件在其他地方读取自有存储时,以 core 的当前快照为准。旧 revision 的条目由插件定期清理,也可以按 core 数据重建索引。
- 大块内容(正文、分块、文件字节)按内容摘要存成不可变的记录:先写入并提交到自有存储,再在写事务块中提交内容里
带有该摘要的 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_onlyContent 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}/restorations | operation 为 restore(默认,可指定 revision 恢复到旧内容)或 undo_merge;按组执行级联恢复和退役 |
| 情况 | 响应 |
|---|---|
| 插件没有实现对应方法 | 422,说明该 family 不支持此操作 |
插件抛出 InvalidContent | 422,带插件给出的消息和字段 |
| 版本不一致 | 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 | 宿主进程 |
generate | Supervisor 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_onlyContent Source;SourceDefinition/SourceProjection、Source journal 与消费游标。
未决问题
| 问题 | 说明 |
|---|---|
| 写事务块的时限与限额默认值 | 默认 30 秒是否合适;SQLite 与 OceanBase 是否采用不同默认值;单块操作数与字节上限 |
| 宿主进程的默认参数 | 同步调用时限、单个宿主进程的并发上限、心跳时限、空闲停止时间、宿主进程总上限和重启退避的默认值 |
| 专属存储的建库权限 | Server 的数据库登录没有建库权限时,除了由部署者事先建库,是否允许退回到 core 库中按插件名前缀建表 |
| 插件 family 接入 Recall | Prepared 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 安装插件,每个插件独立的依赖环境,以及记录各实例加载的插件版本的登记表。

