tabapp-protocol 1.0.0

Wire protocol for the tabapp agent platform — artifacts, events, tools, sessions.

tabapp-protocol

tabapp agent 平台的 wire 协议层 —— artifact / event / tool / session 的 canonical schema。一份源生成两个发行包:

发行	包名	安装	import
PyPI	tabapp-protocol	pip install tabapp-protocol	from tabapp_protocol import ...
npm	@tabapp/protocol	pnpm add @tabapp/protocol	import { ... } from '@tabapp/protocol'

Python Pydantic 模型是权威源。schemas/ 下的 JSON Schema 由 Python 导出,TS 类型再从 JSON Schema 自动生成。

目录

backend/libs/protocol/
├── pyproject.toml             Python 包配置(tabapp-protocol)
├── version.py                 PROTOCOL_VERSION 单一来源
├── _common.py                 共享原子类型(ProducerRef 等)
├── artifacts/                 /v1/audio /v1/image ... + discriminated union
├── events/                    EventEnvelope + 15 种事件类型
├── tools/                     ToolDescriptor + 副作用枚举
├── session/                   SessionConfig + subagent 模板
├── tenancy/                   TenantIdentity / AuthContext / UsageRecord
├── api/                       HTTP 请求/响应壳
├── openapi/generate.py        生成 schemas/*.schema.json
├── schemas/                   生成的 JSON Schema(已入版本)
└── codegen/
    └── ts/                    @tabapp/protocol —— TS 包源码与 codegen

构建与发布

# Python —— wheel + sdist 进 dist/
cd backend/libs/protocol
python -m build
twine upload dist/*

# TypeScript —— 先刷新 JSON Schema,再 transpile
python -m libs.protocol.openapi.generate     # 刷新 schemas/*.schema.json
cd codegen/ts
pnpm install
pnpm run build                                # codegen + tsc → dist/
pnpm publish --access public

或者用一键脚本:

./scripts/publish-protocol.sh --dry-run      # 校验版本 + 出包到本地
./scripts/publish-protocol.sh                # 真发(需登录)

版本规则

version.py 里的 PROTOCOL_VERSION 是单一来源。pyproject.toml 与 codegen/ts/package.json 必须保持同步 —— 发布脚本会校验,任一不一致 直接退出。

升档	触发	wire 影响
MAJOR	破坏性变更	启用 /v2/...,过渡期 ≥ 6 个月
MINOR	加 artifact / event / 字段,扩 enum	向后兼容
PATCH	文档 / codegen / 边角修复	无 schema 变化

monorepo 内部使用

仓库内代码用 from libs.protocol import ...。PyPI wheel 把目录 重命名成 tabapp_protocol/,外部 consumer 用 from tabapp_protocol import ...。两条 import 路径指向同一份 Pydantic 模型。