XiHan Framework 处于预览阶段

查看获取方式
跳转到内容

Python SDK ​

framework-sdk-python 是 XiHan Spec 的 Python 实现:原语层、清单、调用上下文、管道、操作契约与进程外插件运行时。语义与线上编码以规范为准,行为与 .NET 参考实现(XiHan.Framework)一致(结果取决于平台内部的地方由 ADR-0236 写死在规范里);规范以 submodule 放在 SDK 仓库的 spec/,一致性由规范仓库的向量验证。用它写的进程外插件怎样接进 .NET 宿主见进程外插件,规范、一致性档与各语言 SDK 的关系见规范与多语言。

安装 ​

bash
pip install xihan-framework

导入名是 xihan_framework。核心五块运行时零依赖;写进程外插件要装 extra plugin(见写一个插件)。

PyPI 上目前只有占名用的版本,首个版本尚未发布,现在从源码安装:克隆仓库,在仓库根建好虚拟环境后执行 python -m pip install -e ".[plugin]"(Windows 上建虚拟环境用 py -3.13 -m venv .venv)。

模块 ​

包内容规范
primitivesError / 错误码、Result[T]、Maybe[T]、TypedId[V]、LifecycleState、PipelineStage、Stability、Baggage 键、消息键与模板、Catalog、FrameworkErrorRFC-0001、RFC-0010、conventions/
manifestxihan.manifest.json 的模型(冻结的 dataclass,构造时校验各字段,validate() 核对字段之间的约束)、按规范顺序的读取与逐字相同的写出,能力声明与依赖文本RFC-0002、manifest/manifest.schema.json
invocation不可变的 Context:截止时间、可跨线程触发的 Cancellation、W3C 追踪(traceparent 只认版本 00 与小写十六进制、不合法的当作没给,采样只看标志的最低位,写出只带采样位 00 / 01,没有上游时写 01)、已登记的 Baggage(已登记键的值非空、按 UTF-16 码元计最多 256、不含控制字符,由一组 Baggage 构造上下文时丢弃不合的成员,with_baggage 给出不合的值则抛 ValueError,幂等键两种情形都例外)、类型化键的对象袋;Context.run(call) 进入时截止时间已过即返回 KERNEL_TIMEOUT_001 + kernel.invocation.deadline_before_start(不核对取消),之后把一个派生的上下文交给 call,它的信号在调用方取消或到达截止时间时触发;取消与截止时间只经信号通知,不取消 call 的任务,call 抛出 CancelledError 或写下取消结果时翻译为 KERNEL_TIMEOUT_001 / KERNEL_CANCELLED_001,照常返回的结果原样交回RFC-0003
pipeline固定阶段的 Builder:use / use_at / use_named_instance、before / after(按类型名或实例名)、阶段可写成清单里的名字、extend 接上另一个构建器;命名实例只按实例名引用、默认实例按类型名引用;重复登记、未知阶段与约束主体未登记或有歧义在登记时报,约束目标的问题与成环在排序时报(逐个阶段处理),消息是各语言逐字相同的英文原文,命名实例写成 类型名[名字],成环时列出全部卡住的中间件;describe / dump、build;排序规则与错误码 KERNEL_PIPELINE_00xRFC-0004
operationContract、Schema、异步处理器、容量 10000 的 Registry、经完整管道执行的 Invoker(XGI:JSON 请求与响应,带三个内置步骤)与类型化入口 invoke_typedRFC-0011
plugin进程外插件运行时(协议 xihan.plugin.v1):Plugin 在监听之前核对清单与声明,读宿主下发的环境变量,在本机端点上以 grpc.aio 提供 Plugin 服务并写握手行;每个 RPC 先按常数时间核对会话令牌;按 lifecycle.md §7 处理调用次序、配置(含类型化读取)、就绪、健康、停止,以及 stdin 关闭或 SIGTERM 的收尾(最多 3 秒);调用经 SDK 的 Invoker 与完整管道执行,事件按(主题,订阅方式,类型)依次交给处理器;宿主回调客户端 Host(invoke 与批量的 publish,端点取 XIHAN_PLUGIN_HOST_ADDRESS 里第一个 grpcio 能连的项,发出前在本地核对权限与租户);stderr 上的 JSON 日志;运行时的消息目录(10 种区域,供本地渲染,不随握手发送)。协议代码在 plugin.v1,由 spec/plugin/plugin.proto 生成。依赖 grpcio 与 protobuf,装 extra:pip install "xihan-framework[plugin]"RFC-0017、spec/plugin/

快速开始 ​

python
import asyncio
from dataclasses import dataclass

from xihan_framework import operation, pipeline
from xihan_framework.invocation import Context
from xihan_framework.primitives import BAGGAGE_TENANT, Error, PipelineStage, Result, Stability, Unit, fail, ok


@dataclass(frozen=True)
class CreateOrder:
    quantity: int


@dataclass(frozen=True)
class OrderCreated:
    id: str
    tenant: str | None


async def create_order(ctx: Context, request: CreateOrder) -> Result[OrderCreated]:
    if request.quantity <= 0:
        return fail(
            Error.validation("ORDERS_VALIDATION_001", "orders.quantity.invalid", {"quantity": request.quantity})
        )
    return ok(OrderCreated(id="o-1", tenant=ctx.tenant))


async def observe(ctx: Context, next_step: pipeline.Step) -> Result[Unit]:
    outcome = await next_step(ctx)
    print(operation.current(ctx), outcome)
    return outcome


async def main() -> None:
    registry = operation.Registry()
    registry.add(
        operation.Contract("orders.create", stability=Stability.EXPERIMENTAL, expose=(operation.EXPOSE_HTTP,)),
        create_order,
        request_type=CreateOrder,
        response_type=OrderCreated,
    )
    builder = pipeline.Builder().use_at(pipeline.func("Observe", observe), PipelineStage.OBSERVE)
    invoker = operation.Invoker(registry, builder)

    ctx = Context(timeout=2, baggage={BAGGAGE_TENANT: "t1"})
    response = await invoker.invoke(ctx, operation.Request("orders.create", b'{"quantity":2}'))
    print(response.outcome.is_ok, response.payload)  # True b'{"id":"o-1","tenant":"t1"}'


asyncio.run(main())
  1. 可恢复失败返回 fail(Error...),不抛异常;错误码按 <领域大写>_<KIND>_<NNN>,文案用消息键(最长 128 个字符)+ 参数,Error.message 先经 set_default_messages(Catalog(...), locale) 安装的目录解析,再找 SDK 自带的内核错误英文模板(BUILT_IN_CATALOG,含清单读取的错误,与规范向量 kernel-messages 逐字相同,如 Operation 'orders.create' is not registered.),都解析不了时是 键 (参数)。配置与编程错误(非法参数、清单字段不合格式、管道约束成环、操作重复登记)抛 FrameworkError,它是 ValueError 的子类,带错误码;操作重复登记与登记表已满的 FrameworkError 经 to_error() 交回带消息键与参数的错误(kernel.operation.duplicate / kernel.operation.registry_full)。
  2. 模板按 RFC-0010「模板」:{name} / {0},{{ }} 转义。值先归到值模型(空、布尔、字符串、64 位整数、双精度浮点、数组、对象):浮点在 1e-4 ≤ |x| < 1e17 时写最短往返的定点形式(整数值不带小数点,2.0 写 2),范围外写 1E+17、9.9E-05 这样的形式,负零写 -0,非数与无穷写 NaN、Infinity、-Infinity;数组与对象写成紧凑的 JSON,对象成员按名字的 UTF-16 码元序排列,超过 64 层的容器写 null。说明符只认 D、X / x、F、N 加至多两位精度(F02 即 F2),D 与 X 只用于整数(X 只用于非负整数),F 与 N 用于整数与浮点,按精确值舍入、正好一半取偶({n:F2} 取 0.125 得 0.12);其余说明符(E2、0.00、yyyy-MM-dd、printf 风格的 %05d)与不适用的场合一律按无格式写出。format_message / try_format_message / format_argument 可带 locale,Catalog.resolve 按请求的区域格式化:区域只改变小数点与分组符(de-DE、es-ES、pt-BR 是 , 与 .,fr-FR 是 , 与 U+202F,ru-RU 是 , 与 U+00A0,区域名不区分大小写,其余区域与不给区域都是 . 与 ,),小数点用于无格式的浮点与 F、N,分组符只用于 N,D、X 与数组、对象里的数字不受区域影响。describe 不随区域变化,参数按名字的 UTF-16 码元序排列。format_message 是宽松格式化(缺值的占位符原样保留),try_format_message 与 Catalog 是严格格式化(缺值即失败,退回描述)。
  3. 请求与响应是 dataclass(也可以是原语、list / tuple / 键为 str 的 dict、枚举、X | None、Maybe[T]、TypedId 子类,或自带 from_json_value / to_json_value 的类型),用标准库编解码;成员名用 field(metadata=operation.json_field("ttlMs")) 改写。载荷按 RFC-0011 规则 2 解码,不合法返回 KERNEL_VALIDATION_001,reason 只写 JSON 路径:先过共同的 JSON 读取检查(语法错误、只有空白、BOM、嵌套超过 64 层、非法 UTF-8、孤立的代理项都写 $,任何一层有重复成员时写第一处重复的路径,先于一切类型问题);再按请求类型解码:成员名区分大小写,未知成员忽略,数字不从字符串读,整数不接受 1.0 与 1e2,超出范围即不符,浮点接受整数写法、1e400 为无穷;按文本顺序报第一处类型不符的路径($.lines[1].quantity,成员名含 .、空格、引号、括号、/、\ 或几个空白控制字符时写 $['unit price']),必填成员缺少时在所在对象结束时报该对象的路径($、$.inner);null 载荷与不是对象的载荷写 $。空载荷等价于 {}。载荷的文本按 JSON 值比较,空白、转义与数字的写法不是契约;JsonValue / Any 类型的成员原样保留读到的值,数字读成保留原文的 primitives.JsonNumber(float 的子类,text 是原文),写回时与读到的 JSON 值相等:1e400 不变成 null 或无穷,超出双精度的整数保持精确,2.0 与 2 的区别保留。
  4. 处理器与中间件都是 async def。Invoker 带三个内置步骤,位置按 RFC-0011 规则 10:都按归属 xihan.kernel.core 放在所在阶段的 Beginning,与同位置的其他中间件按归属的序数序排序,invoker.dump() 打印实际执行的管道。Observe 阶段的 ObserveMiddleware 把排在它之后的中间件与处理器抛出的异常(Exception)翻译为 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception,上线的错误不带异常文本,完整异常经 logging 的 xihan_framework.operation 记下;排在它之前的(Ingress 阶段,或 Observe 阶段 Beginning 上归属排在 xihan.kernel.core 之前的,如归属 app)抛出的异常原样交给调用方。Resilience 阶段的 DeadlineMiddleware 就是 Context.run:进入时截止时间已过即 deadline_before_start;之后的中间件与处理器拿到的上下文在截止时间到了或 ctx.cancellation.cancel()(可以在任何线程调用)时触发信号。取消与截止时间只经信号通知(RFC-0003 规则 1):调用器不取消处理器的任务,处理器读 ctx.is_cancelled、await ctx.cancellation.wait() 或调用 ctx.cancellation.raise_if_cancelled() 自己停下;抛出取消或写下 KERNEL_CANCELLED_001 时,截止时间已到即 KERNEL_TIMEOUT_001,否则 KERNEL_CANCELLED_001;信号触发后照常返回的结果就是调用的结果;任务被别处取消时 CancelledError 照常传播。Validate 阶段的 ValidationMiddleware 解码原始调用的载荷(解码好的请求经 operation.decoded_request_of(ctx) 取),类型化调用跳过。进入管道之前只核对未登记(KERNEL_NOTFOUND_001)与类型化调用的类型不符(KERNEL_VALIDATION_002,参数只有 id)。中间件以成功短路、handle 没有执行时,invoke 与 invoke_typed 都返回 KERNEL_UNEXPECTED_001 + kernel.operation.no_response(规则 9)。XGI 入口在管道结束之后才把响应编码成载荷,管道里的中间件经 operation.response_of(ctx) 看到编码之前的对象;写不出时(类型化的浮点是 NaN 或无穷,或编码不了的值)返回 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception,框架异常的错误放进 inner,不抛给调用方,没有载荷,NaN 不写成 null 或字符串。
  5. 清单:manifest.read(data) / manifest.read_file(path) 返回 Result[Manifest],失败都是 KERNEL_CAPABILITY_006,按 RFC-0002 解析规则 2 的顺序只报第一处问题:不是 JSON 为 kernel.manifest.invalid_json(reason 为 $ 或第一处重复成员的路径,read 不跳过 BOM,read_file 按 UTF-8 读并跳过开头的 UTF-8 BOM),根是 null 为 kernel.manifest.empty,不合 Schema 为 kernel.manifest.invalid(reason 是第一处问题的路径:成员按文本顺序,每个成员依次查 Schema 之外的成员、null、类型、取值,对象查完后按 required 的顺序报缺少的成员),字段之间的约束保留 primitives.manifest.* 的键与 id 参数(Manifest.validate() 的同一组错误,码换成 KERNEL_CAPABILITY_006),文件不存在为 kernel.manifest.file_missing(path);message 是这些键的英文模板格式化后的句子,与 kernel-messages 向量相同。接口版本是不带前导零的正整数,不超过 2147483647。插件声明了 contributes.pipeline 时只有 Wasm 插件的中间件生效,由宿主在发现插件时核对,读取不拒绝。manifest.write(m) 按 RFC-0002「写出」输出:两个空格缩进、LF、末尾不换行,成员顺序固定,列表总写(空列表 []),role 缺省写 provider,activation 缺省写 ["onStartup"],字符串只转义 "、\、控制字符与孤立的代理项。

写一个插件 ​

这一节是插件一侧的写法;宿主怎样发现、启动与降级插件,见进程外插件。

bash
pip install "xihan-framework[plugin]"

grpcio 与 protobuf 只在 extra plugin 里,核心五块不依赖它们;没有装就导入 xihan_framework.plugin 时,错误里给出这条安装命令。

python
import sys
from dataclasses import dataclass
from pathlib import Path

from xihan_framework import operation
from xihan_framework.invocation import Context
from xihan_framework.plugin import Envelope, Plugin, Subscription, SubscriptionHandler, run
from xihan_framework.primitives import Result, Unit, ok, success


@dataclass(frozen=True)
class Echo:
    text: str


async def echo(ctx: Context, request: Echo) -> Result[Echo]:
    return ok(request)


async def on_event(ctx: Context, envelope: Envelope, attempt: int) -> Result[Unit]:
    # 至少一次投递:处理器必须幂等,可按信封 id 去重
    return success()


def build() -> Plugin:
    registry = operation.Registry()
    registry.add(operation.Contract("echoes.create"), echo, request_type=Echo, response_type=Echo)
    return Plugin(
        Path(__file__).with_name("xihan.manifest.json").read_bytes(),
        operations=registry,
        subscriptions=[SubscriptionHandler(Subscription("echo.events"), on_event)],
    )


sys.exit(run(build))

清单 xihan.manifest.json 与脚本放在插件目录里:

json
{
  "$schema": "https://spec.xihanfun.com/manifest/v1.json",
  "id": "xihan.samples.echo-python",
  "version": "0.1.0",
  "primitives": "1",
  "stability": "experimental",
  "kind": "plugin",
  "isolation": "out-of-process",
  "contributes": { "operations": ["echoes.create"] },
  "activation": ["onStartup"],
  "entry": "echo"
}
  1. 清单与启动前的核对:kind 为 plugin、isolation 为 out-of-process,不写 contributes.pipeline(只有 Wasm 插件能贡献中间件),primitives 是本 SDK 实现的原语层大版本 1;登记的每个操作都要列在 contributes.operations,健康项列在 contributes.health,配置节写在 contributes.config.section(宿主还要授予 config:<配置节>);回调宿主要在 permissions 里声明 capability:kernel.pipeline(Host.invoke)与 capability:messaging.queue(Host.publish)。Plugin 构造时核对这些,以及订阅(同一(主题,类型)只声明一次)与消息目录(含 en-US,不能用运行时目录的名字 plugins.protocol),不合即抛出 FrameworkError。进程入口 run(build) 构造插件,构造失败时不监听、不写握手行,在 stderr 记一条 error 日志后以退出码 1 结束,宿主看到的是进程在握手之前退出(handshake.md §1)。握手交给宿主的是 Plugin 收到的清单文本去掉开头的 BOM(省略时读工作目录里的文件),必须与插件目录里的文件一致。

  2. 启动脚本:entry 是相对插件目录的可执行文件。宿主只继承 PATH、用户目录、临时目录等少数环境变量(handshake.md §1),所以脚本里写解释器与插件脚本的绝对路径,不依赖 VIRTUAL_ENV。Unix 上是带 shebang 的 sh 脚本,并 chmod +x;Windows 上是 .cmd,entry 写 echo.cmd(没有扩展名时宿主补的是 .exe)。

    sh
    #!/bin/sh
    exec /path/to/.venv/bin/python /path/to/echo/echo.py "$@"
    bat
    @echo off
    "C:\path\to\.venv\Scripts\python.exe" "C:\path\to\echo\echo.py" %*
  3. 插件端点:默认是 Unix 域套接字,Linux、macOS 与 Windows 都用它(Windows 10 1803 起支持 AF_UNIX,grpcio 在 Windows 上同样能监听 unix: 地址)。套接字放在本进程新建的私有目录里(mkdtemp:名字随机、权限 0700、只新建不复用),套接字文件 0600,停止后删除;Windows 上 chmod 只管只读位,私有目录在当前用户的临时目录下,靠目录的访问控制。握手行的地址不能有空白(handshake.md §2 的空白集合),临时目录的路径带空白(如带空格的用户名)时改为监听回环 TCP。Plugin(network=Network.TCP) 只绑定 127.0.0.1 的随机端口,握手行写 127.0.0.1:<端口>,同机的其他用户连得上,隔离只靠会话令牌。grpcio 不支持 Windows 命名管道,插件不监听 npipe,命名管道的访问控制因此不涉及本 SDK。

  4. 回调端点:XIHAN_PLUGIN_HOST_ADDRESS 是宿主按偏好排好、以 ; 分隔的端点列表(handshake.md §4),任何一项不合法整个值就不合法。SDK 按顺序取第一个 unix 或 tcp 项(grpcio 连不了命名管道),之后不换;宿主总把回环 TCP 放在最后,所以 Windows 上的 .NET 宿主(npipe \\.\pipe\…;tcp 127.0.0.1:…)经回环 TCP 回调,其他系统经 Unix 域套接字回调。变量缺失、不合法或没有能连的项时插件照常服务,启动时在 stderr 记一条 warning,每次回调都以 PLUGINS_UNAVAILABLE_001 + plugins.host.unavailable(reason 为 no supported callback endpoint)失败、不发请求。

  5. 次序、配置与就绪(lifecycle.md §7.1–§7.3):每个 RPC 先按常数时间核对元数据 xihan-plugin-session,必须恰好一个值,缺失、两个及以上(即使其中一个对)或不对都以 Unauthenticated 拒绝,先于次序核对与读流的第一帧。Handshake 只在 Declared 接受,Configure 只在 Resolved,Start 只在 Configured,Stop 在握手之前、停止中与停止之后不接受;不在次序表里的调用以 FailedPrecondition 拒绝,状态不变。Handshake 选宿主列表里最高的共同版本(没有即 FailedPrecondition),交出清单、只有一元操作的声明(契约与 JSON Schema)、按声明顺序且 mode 总写 competing 或 broadcast 的订阅,以及作者自己的消息目录。Configure 的配置节为空等同 {};不是 JSON 对象(含通不过共同的 JSON 读取检查)时不调 Hooks.configure,以 PLUGINS_UNEXPECTED_001 + plugins.process.failed(phase 为 configure,reason 为 the configuration is not a JSON object)进入 Failed。配置节原样交给作者(宿主写出的叶子都是字符串),Configuration.decode(T) 按类型读:成员名按 ASCII 不区分大小写匹配,字符串叶子按 JSON 数字文法读成 int / float,true / false(ASCII 不区分大小写)读成 bool,读不出时抛出带 JSON 路径的 FrameworkError。Start 在启动回调成功后进入 Started,有健康回调时立即求一次,按结果进入 Ready、Degraded 或 Failed(报其他状态的按 Ready,抛出的按 Degraded)之后才应答;只有 Ready 与 Degraded 可服务,其余状态下的调用与投递以 PLUGINS_UNAVAILABLE_001 + plugins.process.unavailable(state 是状态名,如 Configured)失败。

  6. 健康(lifecycle.md §7.4):Health 与 WatchHealth 任何状态都可以调用;Start 之前报本地状态(Declared、Resolved、Configured),没有健康项、不调回调。可服务期间每次 Health 都求一次 Hooks.health:报 Ready、Degraded、Failed 的照办(Failed 之后不再回来),报其他状态的不改变状态;名字不在 contributes.health 里的健康项丢掉,同一个名字只记一条 warning;回调抛出时这一次报 Degraded,error 为 plugins.process.failed(phase 为 health),没有健康项,状态与回调报了 Degraded 一样迁过去,之后的结果照常决定状态。WatchHealth 先推当前状态,之后状态、健康项或 error 变化时推送,可服务期间每 10 秒重新求一次回调,进入 Draining 时推一次,应答 Stop 之后结束流。

  7. 停止与收尾(lifecycle.md §7.5–§7.7):启动回调没有成功过时 Stop 不调 Hooks.stop,应答 ok 后以退出码 0 退出。启动成功过的进入 Draining(之后进入 Failed 的不迁移),新的调用与投递返回 PLUGINS_UNAVAILABLE_001,在途调用最长等到宽限期(grace_seconds 为 0 按 5 秒),到时触发它们的取消信号、不再等,然后调 Hooks.stop(reason, grace)(进程里最多一次),应答后以退出码 0 退出;停止回调失败或抛出写进 StopResponse.status,照常退出。stdin 读到结尾或收到 SIGTERM 时,可服务的插件进入 Draining,立即触发全部在途调用的取消信号并等它们结束,启动成功过而停止回调还没调过的调一次 Hooks.stop("shutdown", …);从收到起最多 3 秒(短于宿主发出终止信号后再等的 5 秒),进行中的 Stop 同样受这个时限,run 到时不论是否完成都以退出码 0 结束进程。生命周期与健康回调抛出时,交给宿主的 reason 只是异常的简单类型名(如 ValueError),异常文本可能含路径或连接串,只写进 stderr。

  8. 调用与事件(invocation.md §1、§2、§4):Invoke 依次核对会话令牌、操作是否声明(否则 Unimplemented)、是否可服务,再从元数据还原上下文:trace_parent 按 RFC-0003 的文法取,不合即没有父 Span;trace_state 不进上下文;Baggage 只留已登记的键(xihan.principal 原样交给作者);deadline 按规范的严格文法读(2026-11-18 03:25:00Z 这类写法不算),读不出当作没有,生效的截止时间取它与 gRPC 截止时间中较早的一个。然后经 Invoker 与完整管道执行,payload 为空等同 {}。调用方取消或截止时间到了只触发信号,不取消处理器的任务(RFC-0003 规则 1)。本 SDK 不提供流式操作:InvokeStream 读第一帧,流在第一帧之前结束或第一帧不是 start 时为 InvalidArgument,是 start 时为 Unimplemented,不论操作是否声明、插件是否就绪。HandleEvent 依次核对:没有信封或 mode 不是空、competing、broadcast 为 InvalidArgument;按(主题,方式,类型)找订阅,一个也没有即 KERNEL_NOTFOUND_001 + plugins.event.unsubscribed(id、topic、type、mode,空方式写 competing);不可服务为 PLUGINS_UNAVAILABLE_001;之后匹配的订阅按声明顺序依次执行,第一个失败即投递结果,处理器抛出为 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception。

  9. 回调(invocation.md §5):host_of(ctx) 取宿主客户端(运行时建的每个调用与投递的上下文里都有,别的上下文抛出 FrameworkError),await host.invoke(ctx, "orders.create", payload) 与 await host.publish(ctx, envelopes)(批量,逐项结果)。发出之前按宿主的顺序在本地核对,不合不发:所需权限既在清单 permissions 里、也在 Configure 授予的权限里,否则 PLUGINS_DENIED_002 + plugins.callback.denied;上下文的 xihan.tenant 必须是插件正在处理的某个调用或投递的租户,否则 plugins.callback.tenant_denied;publish 的这两项都是整批的结果;最后,上下文的截止时间已过或已被取消时也不发请求,结果与映射表相应的一行相同(截止时间已过按 DeadlineExceeded,已被取消按调用方已取消的 Cancelled)。端点排在这些核对之前。信封的 xihantenant 不在本地核对,交给宿主逐项判定。请求带会话令牌,metadata 取自上下文:当前 Span 的 traceparent、UTC 七位小数加 +00:00 写法的 deadline(gRPC 截止时间与它相同)、已登记的 Baggage,trace_state 为空。调用方取消即取消途中的回调;截止时间到了(含管道里 Context.run 在截止时间触发的信号)不在本地取消,由 grpcio 按同一个截止时间以 DeadlineExceeded 结束。gRPC 失败只按规范的表映射,不另按时钟或令牌改写(grpcio 按截止时间中止的调用报的就是 DeadlineExceeded):Unauthenticated 为 plugins.callback.session_invalid,PermissionDenied 为 plugins.callback.denied,DeadlineExceeded 为 KERNEL_TIMEOUT_001,调用方已取消的 Cancelled 为 KERNEL_CANCELLED_001,其余 Cancelled、Unavailable 与连接失败为 plugins.host.unavailable(reason 为 <状态名>: <说明>),Host.invoke 的 Unimplemented 与 InvalidArgument 为 kernel.operation.unknown 与 kernel.operation.invalid_payload,其他为 plugins.process.failed;publish 的 RPC 失败时每一项同一个错误,宿主返回的结果数与信封数不同时每一项都是 plugins.process.failed。宿主写来的 Status 按 invocation.md §3 读:错误码不合文法时整个错误换成 plugins.process.failed(phase 一律为 invoke,Host.publish 的结果也一样,原来的 inner 丢掉);带键的错误不取 text,消息键不合文法的成为自由文本错误(text 为空或只有空白时取 code);details 为空、只有空白、是空对象、通不过共同的 JSON 读取检查、不是对象,或任何一层有超出双精度的数时没有细节(下溢的数读成 0,超出 64 位的整数读成双精度);ok 为假却没有 error、或整个 status 缺失时为 plugins.process.failed(phase 为操作 ID 或 publish,reason 为 the host reported a failure without an error)。

  10. 错误、消息键与日志(invocation.md §3、§6、§8):业务失败走 Status.error,gRPC 状态只表示传输失败。带消息键的错误写出时 text 留空,由宿主按目录翻译成调用方的语言;只有 Error.literal 的自由文本错误写 text;details 是参数的 JSON 对象文本,没有时为空,inner 照写。运行时与宿主共用的键是 plugins.process.unavailable、plugins.process.failed、plugins.event.unsubscribed、plugins.host.unavailable、plugins.callback.denied、plugins.callback.tenant_denied 与 plugins.callback.session_invalid,错误的 details 就是它们的参数。宿主有这些键的目录,SDK 不随握手发送它们;plugin.CATALOG(目录名 plugins.protocol,10 种区域,文案与参考实现相同)供本地渲染,运行时用它写 stderr 日志里的错误文案。run 与 Plugin.run() 在根日志没有处理器时接上 JsonLogHandler:stderr 一行一个 JSON 对象,level 为 trace / debug / information / warning / error / critical,另有 message 与其余作用域属性。

用黑盒运行器验证(在 SDK 仓库检出的 spec/conformance 里运行,需要 Go,版本见 spec/conformance/go.mod):

bash
cd spec/conformance
go run ./cmd/xihan-conformance plugin --dir <插件目录> --exclude echoes.crash --sample 'echoes.create={"text":"hi"}' --config '{"greeting":"hello"}'

完整的示例在 examples/echo:操作、故意崩溃的 echoes.crash、事件订阅、健康项、类型化读取的配置与宿主回调。

与宿主共用的行为 ​

Result、Error、Maybe 的 JSON 编码按 RFC-0001「Result」:有值成功 {"ok":true,"value":…},无值成功(success())只写 {"ok":true},失败 {"ok":false,"error":{…}}。读取分三种:Result.from_json_value(有值,value 必填且不能是 null)、Result.unit_from_json_value(无值,带了 value 即拒绝,{} 与 null 也算)、Result.maybe_from_json_value(值是 Maybe,null 即无值);Error 的 message 必填,不能为空也不能只有空白,可选成员写成 null 不合法,未知成员忽略;从文本读取时先过共同的 JSON 读取检查,任何一层出现重复的成员名即不合法,含 value、details 与 inner 的内部。数字按值模型往返:64 位范围内的整数原样(9007199254740993 不会变成 9007199254740992),整数值的浮点写成 2.0、-0.0、1E+17,读回来仍是浮点;非有限的浮点写成字符串 NaN、Infinity、-Infinity。

这些规则与生命周期迁移表、管道阶段顺序、错误码、Baggage 键与能力依赖的文法都由 spec/conformance/vectors 验证。插件协议的握手行、版本协商、回调端点列表、截止时间、回调失败的映射与运行时的消息键由 spec/conformance/vectors/plugin/ 验证;握手、会话令牌、调用次序、生命周期、未知操作、声明的操作、未就绪时的调用与投递、事件投递、找不到订阅、流式调用的第一帧、配置节不是对象、启动之前的停止与 stdin 关闭即退出由规范仓库的黑盒运行器验证(见写一个插件)。

语言映射 ​

规范把一部分写法交给各语言自己声明,Python 的写法如下。

  • 请求类型的必填与可选:dataclass 里没有缺省值的字段是必填的(Maybe 字段例外,没写时为无值);有缺省值的字段(= 0、= None、field(default_factory=list))是可选的,缺少时取缺省值。必填只要求成员出现,值为 null 也算出现。
  • 接受 null 的成员:只有 X | None、Maybe[X]、JsonValue / Any 接受 null,null 即没有值(None)。规范里接受 null 的字符串、数组与对象在 Python 里写成 str | None、list[X] | None、Inner | None,数组项要接受 null 时写 list[str | None];写成 str、list[str] 的成员遇到 null 按类型不符报出。整数、浮点、布尔不写 | None,null 即类型不符,与规范一致。
  • 数字类型:int 是 64 位有符号整数;Python 没有更窄的整数类型,32 位整数写成 Annotated[int, operation.Int32],其他范围用 operation.IntRange(最小, 最大),超出范围即类型不符。float 是双精度浮点,也接受整数写法,解码出普通的 float;bool 不是数字。JsonValue / Any 成员里的数字是 JsonNumber(64 位范围内的整数仍是 int)。
  • 模板的值模型:None、bool、str(含 StrEnum 等 str 的子类)、int(含 IntEnum;超出 64 位的是浮点)、float;Decimal、Fraction 等其他实数换成最接近的双精度浮点;Mapping 是对象(键取它的文本),list、tuple 与其他序列、set / frozenset、bytes 是数组。模型之外的值取 str(value):datetime(2026, 11, 16, 8, 30) 写 2026-11-16 08:30:00,UUID 写带连字符的小写形式,普通 Enum 写 Color.RED;它们不跨语言,插件要跨语言格式化时先转成字符串。
  • 线上编码的值:Result 的值与错误细节里,超出 64 位的 int 按值模型写成浮点(精度随之丢失),float('nan') 与无穷写成字符串;操作的响应里非有限的浮点写不出(见快速开始第 4 条),JsonNumber 写回原文。
  • JSON 文本与文法:读取不用 json.loads(它接受 NaN、孤立的代理项、重复成员与很深的嵌套),由 SDK 自己按 RFC 8259 读;str 里的代理项码点按不合法的 Unicode 处理。规范的正则一律 re.fullmatch,结尾的换行不会被放过。
  • 空白:空白指 RFC-0001「空白字符」写死的 25 个码位(U+0009–U+000D、U+0020、U+0085、U+00A0、U+1680、U+2000–U+200A、U+2028、U+2029、U+202F、U+205F、U+3000),不用 str.isspace,它另把 U+001C–U+001F 算作空白;握手行与 Error 的 message、自由文本共用这张表(xihan_framework.plugin.is_whitespace)。Error.literal 与 with_text 的文案为空或只有空白时抛出 FrameworkError(PRIMITIVES_VALIDATION_001)。

设计取舍 ​

面向 Python 应用、脚本型插件与 AI 工具链:Python 3.12+,处理器与中间件基于 asyncio,核心五块运行时零依赖。进程外插件运行时基于 grpc.aio,与处理器在同一个事件循环里;grpcio 与 protobuf 只在 extra plugin 里。

一致性 ​

  • 现状:primitives、manifest、invocation、pipeline、operation 与进程外插件运行时 plugin(xihan.plugin.v1,基于 grpc.aio,以 extra xihan-framework[plugin] 引入 grpcio 与 protobuf)可用,示例插件 echo 通过规范黑盒运行器的全部用例。远程 Provider 的操作集(如 caching.distributed@1)仍未提供;Wasm 载体不在本 SDK 范围。
  • 钉的规范版本:SDK 仓库 spec/ 子模块指向的提交。
  • 认领的档(RFC-0024):core 与 plugin。
  • 缺口:无。
  • 成熟度:在有钉在规范标签上的发布版之前是 Experimental。
  • 怎样验证:单元测试直接读取 spec/conformance/vectors/ 下的向量回放;SDK 仓库的 tests/test_vectors.py 按档表 spec/conformance/profiles.json 核对认领的档要求的每个向量要么有测试回放、要么列为缺口并写明理由;示例插件 echo 由规范的黑盒运行器跑全部用例。CI 在 Linux 与 Windows 上都跑这些测试。

破坏性改动与迁移 ​

首个版本尚未发布,还没有登记的破坏性改动。

Released under The MIT License