Metadata-Version: 2.4
Name: tabapp-protocol
Version: 1.0.0
Summary: Wire protocol for the tabapp agent platform — artifacts, events, tools, sessions.
Project-URL: Homepage, https://github.com/tabapp/tabapp
Project-URL: Documentation, https://github.com/tabapp/tabapp/tree/main/backend/libs/protocol
Project-URL: Source, https://github.com/tabapp/tabapp/tree/main/backend/libs/protocol
Author: tabapp
License: MIT
Keywords: agent,artifacts,events,protocol,schema
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.6
Description-Content-Type: text/markdown

# 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
```

## 构建与发布

```bash
# 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
```

或者用一键脚本:

```bash
./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 模型。
