开发与 API
查看 Markdown

编写插件

插件是放在 Server 插件目录下的一个文件夹,入口是其中的 plugin.py。它可以:

能力说明
生成自己的 Artifact声明一个 Artifact family,读取 Source,写出这个 family 的 Artifact;结果通过现有的 Artifact 接口读取、打标签
展示和检索给出每个版本的默认展示;按需实现检索,让通用检索接口和 Prepared Context 能用上插件的数据
支持用户修改实现新建、修改、合并、遗忘、恢复方法,让通用 Artifact 接口作用于插件的 family
定义 Source 类型声明插件自己的 Source 类型和 Projection,记录用户要求做的事,例如一次上传
提供接口声明 HTTP 路由,挂在 /v1/plugins/<插件名>/api/ 下,由 core 认证并转发给插件
提供 Dashboard 页面随插件提供静态页面,在 Dashboard 中以沙箱 iframe 展示
使用专属存储和模型在 core 分配的独立存储中保存自己的数据,调用 Server 配置的 embedding 和生成模型

插件代码在 Server 的 Python 环境中运行,被当作可信代码,权限与部署者相同。只加载你信任的插件。

启用插件目录

设置插件目录,然后重启 Server:

export POWERCONTEXT_SERVER_PLUGINS_DIR=/srv/powercontext/plugins
powercontext server run
  • 目录下每个子目录是一个插件,子目录名就是插件名(小写字母开头,只含小写字母、数字和 -)。
  • 插件依赖的第三方库需要装进 Server 的 Python 环境,例如 uv pip install pypdf。插件目录中的 requirements.txt 只是给 部署者看的说明,Server 不会自动安装。
  • 修改插件后需要重启 Server。Server 在加载时记录插件目录的内容指纹,运行中发现插件文件变了会拒绝执行,避免新旧代码混用。

用管理员凭据查看加载结果:

curl -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8000/v1/plugins

每个插件的 status 为 loaded 或 failed;失败时 error 给出原因,例如声明字段不合法、导入失败。

第一个插件:把文本整理成笔记

在插件目录下新建 notes/plugin.py:

from powercontext.plugins import (
    ArtifactPlugin, ArtifactWriter, GenerateRequest, Inputs, Rendering, RenderRequest, SearchHit, SearchRequest,
    SearchResult,
)


class Notes:
    def __init__(self, ctx):
        self.ctx = ctx

    async def generate(self, request: GenerateRequest, writer: ArtifactWriter) -> None:
        async with writer.transaction() as tx:
            for source in request.sources:
                text = source.projection["content"]
                await tx.put(writer.stable_id(source.ref.source_id), content={"text": text}, source_refs=[source.ref])

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

    async def search_artifacts(self, request: SearchRequest) -> SearchResult:
        query = request.search["query"]
        page = await self.ctx.reads(request.scope_id).list(limit=200)
        hits = [
            SearchHit(ref=item.ref, text=item.content["text"])
            for item in page.items
            if query in item.content["text"]
        ]
        return SearchResult(hits=hits[: request.search.get("limit", 10)])


async def setup(ctx):
    return Notes(ctx)


plugin = ArtifactPlugin(
    family="notes",
    inputs=Inputs(source_types=("content",), projection="powercontext.text-evidence@1"),
    on_sources=True,
    setup=setup,
)

重启 Server 后写入一条文本 Source,几秒后就能读到插件生成的 Artifact:

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/sources -d '{"content": "发布先进入华东区域"}'

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes/$ARTIFACT_ID/rendering
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes/search -d '{"query": "华东"}'

这个插件包含了插件的基本部分:

  • 声明 plugin = ArtifactPlugin(...):告诉 core 插件拥有哪个 family、消费哪些 Source、什么时候运行。
  • 工厂 setup(ctx):返回插件对象。从环境变量读取插件自己的配置、打开需要的资源,都放在这里。
  • 生成 generate(request, writer):收到一批新 Source,写出 Artifact。
  • 展示 render_artifact(request):给出一个版本的默认展示,必须实现。
  • 检索 search_artifacts(request):用插件自己的方式检索,可选。这个例子只做了子串匹配;正式的插件会用自己的全文或 向量索引。

声明

字段说明
family插件拥有的 Artifact family,不能与内置 family 或其他插件重复
inputsInputs(source_types=..., projection=..., projections={...}, max_sources=50):消费哪些 Source 类型、每种类型以哪个 Projection 交付、一次最多交付多少条。projection 适用于所有类型,projections 按类型单独指定
on_sources有新 Source 时运行
scheduleInterval(seconds=...) 或 Cron(expression=..., timezone=...),定时运行;timezone 不填时使用 Server 所在机器的时区。schedule 和 on_sources 都不填时插件没有后台生成,不需要实现 generate,Artifact 只由用户修改和插件接口写入
scopes只服务这些 Scope;配置了 schedule 但不消费 Source 的插件必须填写
timeout_seconds、transaction_timeout_seconds一次生成和其中写事务的时限
change_timeout_seconds一次用户修改、展示或检索的时限
host_processes每个 Server 进程中本插件宿主进程数的上限,默认 1;部署者可以覆盖
definitions插件自己的 Source 定义,见"定义 Source 类型"
api插件的接口,见"提供接口"
pagesDashboard 页面,见"Dashboard 页面"
setup工厂函数,必须是 async 函数

Server 在一个独立的子进程中导入 plugin.py 并检查声明,导入失败或声明不合法时插件为 failed,不影响 Server 和其他插件。 宿主进程调用 setup 之后检查必须实现的方法:缺少 render_artifact,或者声明了 schedule、on_sources 却缺少 generate,插件同样为 failed。

插件对象上的方法:

方法必须实现何时调用
render_artifact是展示接口
generate声明了 schedule 或 on_sources 时定时,或有新 Source
search_artifacts否通用检索接口;Prepared Context 中列出该 family
create_artifact、update_artifact、merge_artifacts、forget_artifact、restore_artifact否对应的通用修改接口
路由的处理函数声明了路由时插件自己的接口

列出、读取版本和历史、治理状态和标签不调用插件方法,由 core 直接提供。

生成 Artifact

generate 在 Server 启动的独立 Worker 进程中运行,每个 Scope 一次调用:

  • request.scope_id 是本次调用的 Scope;request.sources 是这次交付的 Source,每条带 ref(来源引用)和 projection (按声明的 Projection 转换后的内容)。
  • 写入放在 async with writer.transaction() as tx: 里。块内的写操作在一个事务中提交,并与"这批 Source 已处理"的记录一起 提交;生成失败或超时,这批 Source 会再次交付。
  • 调用模型、解析文件等慢操作放在事务之外,事务里只做写入。
  • tx.put(artifact_id, content=..., source_refs=[...]) 写一个新版本,source_refs 记录出处。内容与当前版本相同时不产生新版本, 所以重复交付不会写出重复的版本。writer.stable_id(...) 按输入生成稳定的 ID,便于同一条 Source 总是写到同一个 Artifact。
  • 事务外用 writer.get 等方法读过的 Artifact,写入时 core 会核对它之后有没有变化:内容被修改过,或者被遗忘、恢复、合并过, 这次写入都会冲突,整批 Source 稍后再次交付,插件基于新状态重新决定。插件不需要自己比较。
  • 还可以用 tx.set_lifecycle、tx.merge、tx.revert、tx.set_tags 等方法,以及 writer.get、writer.list、 writer.by_source 读取当前状态。 tx.revert 和 tx.set_lifecycle 返回 ArtifactChange:result.artifact 是目标快照, result.restored 和 result.retired 列出同一次变更影响的其他 Artifact。
  • core 在每个版本上记录写入它的插件名和插件代码的内容摘要,多个 Server 加载了不同版本的插件时可以据此追溯。

生成的 Artifact 与内置 Artifact 一样,可以通过 /v1/scopes/{scope_id}/artifacts/{family} 系列接口读取、打标签。

展示和检索

core 不理解插件 Artifact 的内容结构,也不为插件建立索引;展示和检索由插件自己完成。

展示:render_artifact(request) 收到一个确切版本(request.artifact),返回 Rendering(format="markdown", text=...), format 也可以是 "text"。调用方通过下面的接口获取,不带 revision 时取当前版本:

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8000/v1/scopes/$SCOPE_ID/artifacts/notes/$ARTIFACT_ID/rendering?revision=2"

同一个版本的展示应该稳定,调用方可以按 family、ID、版本和插件版本缓存。

检索:search_artifacts(request) 收到通用检索接口的完整请求(request.search,包含 query、limit、mode、 filters、fusion 等调用方发送的全部字段;include_scores 由 core 处理,不转交),用插件自己的索引检索,返回 SearchResult(hits=[SearchHit(ref=..., text=..., score=...)]):

  • 不支持的字段请抛出 InvalidContent,接口返回 422,而不是静默忽略。
  • core 只保留调用者有权读取、仍是当前版本且处于 active 状态的命中,保持插件给出的顺序和分数。
  • text 是放进智能体上下文的片段,可以是内容的一部分,也可以是展示文本。
  • 插件没有实现 search_artifacts 时,通用检索接口和 Prepared Context 对该 family 返回 422。

Prepared Context:POST /v1/context/prepare 的 assembly.sections 可以列出插件 family。core 用请求的 query 和该项的 limit 调用 search_artifacts,request.max_bytes 是本次请求的字节预算;命中按 section 顺序装进上下文,并引用确切版本。 该项可以带 search,其中的字段原样交给插件:

{
  "scope_id": "team-a",
  "query": "发布区域",
  "assembly": {"sections": [{"family": "memory", "limit": 4}, {"family": "notes", "limit": 3, "search": {"mode": "hybrid"}}]}
}

支持用户修改

插件对象上实现下列方法后,通用 Artifact 接口就对插件的 family 生效;没有实现的方法,对应接口返回 422:

方法对应接口
create_artifact(request, writer)POST /v1/scopes/{scope_id}/artifacts,请求体 {"family": "<family>", "content": {...}}
update_artifact(request, writer)PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id},带 If-Match
merge_artifacts(request, writer)POST /v1/scopes/{scope_id}/artifacts/{family}/merges
forget_artifact(request, writer)POST .../{artifact_id}/forget
restore_artifact(request, writer)POST .../{artifact_id}/restorations
from powercontext.plugins import InvalidContent


class Notes:
    async def update_artifact(self, request, writer) -> None:
        if not request.content.get("text"):
            raise InvalidContent("text is required", field="text")
        async with writer.transaction() as tx:
            await tx.put(request.artifact_id, content=request.content, expected_revision=request.expected_revision)

    async def forget_artifact(self, request, writer) -> None:
        async with writer.transaction() as tx:
            await tx.set_lifecycle(request.artifact_id, "deprecated")
  • core 先检查调用者的权限和版本,再调用方法;提交写入时按调用者给出的版本再校验一次,期间被其他写入改变则返回 409 (修改内容时为 412),插件不必自己重复检查。方法只负责校验内容并完成约定的那一次写入。
  • 接口返回本次写入提交的版本,即使之后已有其他写入。
  • 抛出 InvalidContent 时接口返回 422,错误信息展示给调用者。
  • 用户修改会以修改人的身份记录出处,与内置 Artifact 的修改相同。记录的是请求中的 content 原文:方法可以把它当作对一次 修改的描述,写入另行算出的内容,出处里保留的仍是调用者提交的那一份。

定义 Source 类型

Source 记录"发生了什么、用户要求做什么"。插件可以定义自己的 Source 类型,例如"上传了一个文件"或"编辑了一段内容", 并在生成时消费它们:

from pydantic import BaseModel
from powercontext.sources import Source, SourceMaterialization


class TicketInput(BaseModel):            # 提交时的输入
    key: str
    title: str


class TicketSource(Source):              # 保存在 core 中的 Source
    title: str


class TicketProjection:                  # 交付给 generate 的内容
    name = "tickets.ticket"
    version = "1"
    source_class = TicketSource
    output_class = TicketInput

    def project(self, source, /):
        return TicketInput(key=source.name, title=source.title)


class TicketDefinition:
    name = "ticket"                      # Source 类型名
    version = "1"
    input_class = TicketInput
    source_class = TicketSource
    projections = (TicketProjection(),)

    async def resolve(self, value, /):
        return TicketSource(
            name=value.key, definition_version=self.version,
            materialization=SourceMaterialization.CAPTURED, description="A ticket", title=value.title,
        )

    async def read(self, source, /):
        return TicketProjection().project(source)


plugin = ArtifactPlugin(
    family="tickets",
    inputs=Inputs(source_types=("ticket",), projection="tickets.ticket@1"),
    on_sources=True,
    definitions=(TicketDefinition(),),
    setup=setup,
)
  • 插件加载时,core 登记这些 Source 类型。之后调用方可以用通用 Source 接口写入: POST /v1/scopes/{scope_id}/sources,请求体 {"source_type": "ticket", "content": {"key": "OPS-7", "title": "..."}}。 插件校验输入并解析成 Source;输入不合法返回 422。

  • 插件自己的接口中用 ctx.sources.submit(scope_id, "ticket", TicketInput(...)) 提交。

  • Source 的 name 是它在 Scope 中的身份,同一个 name 重复提交得到同一条 Source。

  • 修改了 Source 或 Projection 的结构时,提高定义的 version,并在 resolve 中把 definition_version 设为新版本。core 按 名称和版本登记,新旧版本并存;已经保存的旧 Source 仍按旧版本解读。

  • 一个插件消费多种 Source 类型、各自需要不同的 Projection 时,用 projections 分别指定:

    Inputs(source_types=("upload", "edit"), projections={"upload": "kb.upload@1", "edit": "kb.edit@1"})

    generate 中按 source.ref.source_type 区分。

提供接口

插件可以声明自己的 HTTP 路由,处理函数是插件对象上的 async 方法:

from pydantic import BaseModel
from powercontext.plugins import ApiError, ApiRequest, PluginApi, Route


class NewTicket(BaseModel):
    scope_id: str
    key: str
    title: str


class Tickets:
    def __init__(self, ctx):
        self.ctx = ctx

    async def open_ticket(self, request: ApiRequest) -> dict:
        body: NewTicket = request.body
        await self.ctx.require("scope.contribute", body.scope_id)
        ref = await self.ctx.sources.submit(body.scope_id, "ticket", TicketInput(key=body.key, title=body.title))
        return {"source_id": ref.source_id}


plugin = ArtifactPlugin(
    ...,
    api=PluginApi(routes=(
        Route(method="POST", path="/tickets", handler="open_ticket", access="authenticated",
              body="json", request_model=NewTicket),
    )),
)
  • 路由挂在 /v1/plugins/<插件名>/api<path>,例如 POST /v1/plugins/tickets/api/tickets。调用方使用与其他接口相同的凭据。
  • access 决定 core 在调用前做的检查:
    • authenticated:只要求已登录;
    • scope.read / scope.contribute:要求调用者对 scope_param 指定的路径参数中的 Scope 具备该权限。
  • 处理函数里用 ctx.require(action, scope_id) 检查其他权限,不具备时接口返回 403;ctx.allowed(...) 只返回真假。 接口只是接受请求、之后由 generate 修改已有 Artifact 时,先用 ctx.require("artifact.write", scope_id, artifact_id=...) 检查调用者对这个 Artifact 的写权限:后台写入时没有调用者身份。 这项检查只针对本插件 family 的 Artifact。
  • 读写核心数据:ctx.reads(scope_id) 按调用者权限读取;ctx.writer(scope_id) 和 ctx.sources.submit(...) 只能用于本次 请求中已经确认 scope.contribute 的 Scope(路由声明了该权限,或处理函数先调用了 ctx.require)。修改已有 Artifact (包括标签、handle 和生命周期)还需要调用者对该 Artifact 有 artifact.write 权限,与通用接口相同;没有权限时接口返回 403。
  • 接口中的写入不会自动记录"谁做了什么"。需要这类出处时,像上面的例子一样把操作作为 Source 提交,由 generate 写入新版本并 引用它。
  • 需要创建 Scope 时用 ctx.scopes.create(title=..., summary=..., idempotency_key=...),要求调用者具备 server.admin。 ctx.scopes.list() 返回本插件创建、且调用者可读的 Scope。ctx.scopes.update(scope_id, expected_version=..., title=..., summary=...) 修改本插件创建的 Scope,同样要求 server.admin;Scope 不存在时接口返回 404,不是本插件创建的返回 403。
  • request.body 按 body 声明是校验后的 request_model 实例、bytes 或 None;request.path_params、request.query、 request.caller 分别是路径参数、查询参数和调用者。
  • 返回值:Pydantic 模型或 dict 返回 JSON;BinaryResponse(content=..., content_type=..., filename=...) 返回文件; None 返回 204。抛出 ApiError(status, code, message) 返回对应的 4xx 错误。
  • 请求体上限:JSON 默认 1 MiB,二进制默认 32 MiB,可以用 max_body_bytes 为单个路由声明,但不会超过部署者设置的 POWERCONTEXT_SERVER_PLUGIN_API_MAX_BODY_BYTES。超出时 core 返回 413,不调用插件。
  • 每次调用受 timeout_seconds(默认 30 秒)约束,超时返回 504。

接口、展示、检索和用户修改方法在宿主进程中执行。每个插件有自己的一组宿主进程,不与其他插件共用:插件加载后启动第一个并 一直保留;所有进程都忙、且有请求排队时再启动一个,直到 host_processes;多出的进程空闲 5 分钟后停止。工厂 setup(ctx) 在每个宿主进程中执行一次,插件对象服务该进程收到的所有请求,所以不要假设所有请求都在同一个进程中。

  • 一个宿主进程同时处理多个请求,都在同一个事件循环上。调用超过时限时,core 只取消这个请求(写事务随之回滚)并返回 504, 同一进程中的其他请求不受影响。
  • 阻塞事件循环会让取消无法生效,宿主进程的心跳也随之中断。心跳中断 5 秒后 core 终止该进程:在此之前已经超过自身时限的 请求返回 504,终止时仍在进行中的请求(包括造成阻塞的那个)返回 503,进程退避后重启。CPU 密集或同步阻塞的代码放进 await asyncio.to_thread(...);需要几分钟的工作交给 后台的 generate。
  • Prepared Context 中的插件 section 在插件不可用(超时、宿主进程不可用或检索失败)时省略,回执中记录该 family 的检索 失败,其他 section 照常返回。

专属存储和模型

from sqlalchemy import text


async def setup(ctx):
    engine = ctx.storage.engine()          # 只指向本插件的存储
    async with engine.begin() as connection:
        await connection.execute(text("CREATE TABLE IF NOT EXISTS notes_index (id TEXT PRIMARY KEY, body TEXT)"))
    return Notes(ctx)
  • ctx.storage.engine() 返回一个 SQLAlchemy 异步引擎,只指向本插件的存储,使用 Server 的数据库后端和连接配置:SQLite 部署是数据目录下的 plugins/<插件名>.sqlite3;OceanBase 和 seekdb 部署是同一个租户或实例上名为 powercontext_plugin_<插件名> 的库(- 换成 _)。ctx.storage.backend 给出后端(sqlite、oceanbase 或 seekdb), 插件据此选择建表语句和索引。表结构和迁移由插件自己管理,core 不读取、不备份这块存储。
  • OceanBase 和 seekdb 上的库在插件加载时由 core 创建,已存在则直接使用。Server 的数据库登录没有建库权限时,由部署者 事先建好并授权。库不存在又无法创建,或者库名超过 64 个字符(插件名超过 44 个字符)时,插件照常加载,调用 ctx.storage.engine() 时报错并说明原因。
  • 这块存储不在 core 的事务里。大块内容(文件、向量)建议按内容摘要保存,再在 Artifact 中引用摘要:写入重试或事务回滚只会 留下没人引用的记录,不会让 Artifact 指向错误的数据。
  • 存储属于整个插件,不按 Scope 隔离。按 scope_id 划分数据,并在读取时确认数据属于本次请求的 Scope。
  • ctx.models 是 Server 配置的模型,两种都没配置时为 None:
    • await ctx.models.embed(["..."]) 返回向量,ctx.models.embedding_dimension 是维度;
    • await ctx.models.generate([ChatMessage(role="user", content="...")], max_tokens=500) 返回生成的文本;
    • 用 embedding_available、generation_available 判断是否配置;调用未配置的模型时抛出 ModelUnavailable。

Dashboard 页面

声明了接口的插件可以提供页面:

plugin = ArtifactPlugin(..., pages=PluginPages(directory="ui", entry="index.html", title={"zh": "工单", "en": "Tickets"}))

ui/index.html 中引用 core 提供的客户端脚本,通过它调用本插件的接口:

<script src="/dashboard/plugins/_client.js"></script>
<script>
  const client = powercontextPluginClient();
  const { language, theme, scopeId } = await client.context();
  const response = await client.request("POST", "/tickets", { json: { scope_id: scopeId, key: "OPS-7", title: "磁盘满" } });
  if (response.ok) console.log(response.json);
</script>
  • 页面出现在 Dashboard 左侧导航中,地址是 /dashboard/plugins/<插件名>。
  • 页面运行在沙箱 iframe 中,拿不到用户的登录会话;请求由 Dashboard 以当前用户的身份转发,只能调用本插件声明的路由和本插件 family 的通用 Artifact 接口。
  • client.request(method, path, options) 的 options 可以有 json、body(例如文件的 ArrayBuffer)、contentType 和 query;返回 status、ok、json、blob、filename。
  • client.artifacts(method, path, options) 调用本插件 family 的通用 Artifact 接口,不需要声明路由。path 接在 /v1/scopes/{scope_id}/artifacts/{family} 之后:空字符串是列表(GET)或新建(POST),/{artifact_id} 是读取或编辑, /{artifact_id}/forget 是遗忘,依此类推。options 另有 scopeId(默认是页面当前的 Scope)和 ifMatch;返回值另有 etag 和 location。权限、版本校验和出处记录与直接调用通用接口相同,页面不能指定其他 family。
  • 页面要做成单页应用:页面跳转后 Dashboard 会停止转发,提示用户重新打开。沙箱中不能使用 alert、confirm 等浏览器对话框。
  • 只提供静态文件(HTML、JavaScript、CSS、图片、字体),单个文件不超过 5 MiB;脚本只能来自插件自己的目录和 /dashboard/plugins/_client.js。

排错

现象处理
/v1/plugins 中插件为 failed查看 error:导入失败时检查依赖是否装进了 Server 环境;缺少必须实现的方法时补上方法
接口返回 503宿主进程正在启动或重启,或者因事件循环被阻塞而被终止;查看 Server 日志中的插件错误
接口返回 504 plugin_timeout调用超过了时限;耗时的工作放进 asyncio.to_thread 或交给 generate,或者调大时限
接口返回 500 plugin_error处理函数抛出了未处理的异常;Server 日志记录了异常类型
修改插件后 Worker 不再执行插件文件在运行中被修改,重启 Server
生成的 Artifact 没有出现用 GET /v1/plugins/<插件名>/scopes 查看各 Scope 是否还有待处理的 Source

当前限制

  • 插件更新需要重启 Server,还不支持热加载。
  • 插件依赖由部署者手动安装到 Server 环境。
  • 插件代码与 Server 有相同的权限,宿主进程和 Worker 隔离的是故障,不是不可信代码。

On this page