Python SDK
framework-sdk-python 是 XiHan Spec 的 Python 实现:原语层、清单、调用上下文、管道、操作契约与进程外插件运行时。语义与线上编码以规范为准,行为与 .NET 参考实现(XiHan.Framework)一致(结果取决于平台内部的地方由 ADR-0236 写死在规范里);规范以 submodule 放在 SDK 仓库的 spec/,一致性由规范仓库的向量验证。用它写的进程外插件怎样接进 .NET 宿主见进程外插件,规范、一致性档与各语言 SDK 的关系见规范与多语言。
安装
pip install xihan-framework导入名是 xihan_framework。核心五块运行时零依赖;写进程外插件要装 extra plugin(见写一个插件)。
PyPI 上目前只有占名用的版本,首个版本尚未发布,现在从源码安装:克隆仓库,在仓库根建好虚拟环境后执行 python -m pip install -e ".[plugin]"(Windows 上建虚拟环境用 py -3.13 -m venv .venv)。
模块
| 包 | 内容 | 规范 |
|---|---|---|
primitives | Error / 错误码、Result[T]、Maybe[T]、TypedId[V]、LifecycleState、PipelineStage、Stability、Baggage 键、消息键与模板、Catalog、FrameworkError | RFC-0001、RFC-0010、conventions/ |
manifest | xihan.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_00x | RFC-0004 |
operation | Contract、Schema、异步处理器、容量 10000 的 Registry、经完整管道执行的 Invoker(XGI:JSON 请求与响应,带三个内置步骤)与类型化入口 invoke_typed | RFC-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/ |
快速开始
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())- 可恢复失败返回
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)。 - 模板按 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是严格格式化(缺值即失败,退回描述)。 - 请求与响应是 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的区别保留。 - 处理器与中间件都是
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或字符串。 - 清单:
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"],字符串只转义"、\、控制字符与孤立的代理项。
写一个插件
这一节是插件一侧的写法;宿主怎样发现、启动与降级插件,见进程外插件。
pip install "xihan-framework[plugin]"grpcio 与 protobuf 只在 extra plugin 里,核心五块不依赖它们;没有装就导入 xihan_framework.plugin 时,错误里给出这条安装命令。
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 与脚本放在插件目录里:
{
"$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"
}清单与启动前的核对:
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(省略时读工作目录里的文件),必须与插件目录里的文件一致。启动脚本:
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" %*插件端点:默认是 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。回调端点:
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)失败、不发请求。次序、配置与就绪(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)失败。健康(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之后结束流。停止与收尾(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。调用与事件(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。回调(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)。错误、消息键与日志(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):
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,以 extraxihan-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 上都跑这些测试。
破坏性改动与迁移
首个版本尚未发布,还没有登记的破坏性改动。
