Metadata-Version: 2.4
Name: jiuzhang
Version: 0.1.0a10
Summary: 九章光量子真机云接入软件包（jiuzhang SDK）
Author: 九章量子 SDK 团队
License: Proprietary
Keywords: gbs,jiuzhang,photonic,quantum,sdk
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# jiuzhang

九章光量子真机云接入软件包（Python SDK）。

> 本目录为 SDK 源码工程。设计文档位于仓库根的 [`doc/`](../doc/)。

## 状态

当前阶段 **`v0.1.0-alpha.9`**（骨架阶段后期）：

- ✅ 工程骨架、工具链、版本策略、CHANGELOG 就位
- ✅ L1 Domain：异常体系（`JiuzhangError` + 8 个子类）+ `make_result()` + `get_logger()`
- ✅ L2 Protocol：`Envelope` JSON 编解码、14 种消息 payload dataclass、`Correlator`、`HeartbeatThread`
- ✅ L3 Transport：`Transport` ABC + `TcpTransport`（同步阻塞 socket，长度前缀分帧，16 MiB 上限）
- ⏳ L1 Domain 三核心类的业务方法体已实装（`TokenManager.validate_token`、
  `PhotonicMachine.connect/disconnect`、`GaussianBosonSampler.init_status/run`）。
  `SimulatorServer` 已可作为本地对端，端到端链路已跑通。剩余 PR-11 端到端冒烟测试 / RC
- ⏳ 公开 API surface **尚未冻结**，将在 `v0.1.0` release 时冻结

测试规模：233 用例 / 覆盖率 86%。

## 工程结构

```
code/
├── pyproject.toml           # 项目元数据 + ruff/mypy/pytest 配置
├── .pre-commit-config.yaml  # pre-commit 钩子（format/lint/typecheck/commitlint）
├── .python-version          # Python 3.12
├── README.md                # 本文件
├── src/
│   └── jiuzhang/            # SDK 包（src-layout）
│       ├── __init__.py      # 公开 API: __all__
│       ├── version.py
│       ├── exceptions.py    # 异常体系
│       ├── errors.py        # 错误码 + 映射
│       ├── result.py        # 统一返回结构
│       ├── logging_utils.py
│       ├── auth/            # L1 Domain — TokenManager
│       ├── hardware/        # L1 Domain — PhotonicMachine
│       ├── sampling/        # L1 Domain — GaussianBosonSampler
│       ├── protocol/        # L2 Protocol — Session/Codec/Correlator/Heartbeat
│       ├── transport/       # L3 Transport — Transport ABC + TcpTransport
│       └── testkit/         # SimulatorServer（本地模拟器）
└── tests/
    ├── conftest.py
    └── unit/
        ├── test_smoke.py            # 包导入 / 公开 API / 异常继承
        ├── test_exceptions.py       # 异常体系 + to_result()
        ├── test_result.py           # make_result()
        ├── test_logging_utils.py    # get_logger()
        ├── test_envelope.py         # Envelope JSON 编解码
        ├── test_messages.py         # 14 种 payload dataclass
        ├── test_correlator.py       # Correlator 请求-响应配对
        ├── test_heartbeat.py        # HeartbeatThread 后台线程
        ├── test_tcp_transport.py    # TcpTransport（含 _EchoServer loopback）
        ├── test_session.py          # ProtocolSession 集成测试（含 _MockServer）
        └── test_domain.py           # Domain 三核心类单元测试
```

## 开发流程

### 1. 安装依赖

```bash
cd d:/PyProjects/jiuzhang_SDK/code
uv sync --extra dev
```

### 2. 安装 pre-commit 钩子

```bash
uv run pre-commit install
uv run pre-commit install --hook-type commit-msg
```

### 3. 本地质量四件套

```bash
uv run ruff format src tests       # 格式化
uv run ruff check src tests        # lint（含 docstring D 规则）
uv run mypy src                    # 严格类型检查
uv run pytest                      # 测试 + 覆盖率
```

四件套全绿才能提交。

### 4. 提交规范

[Conventional Commits](https://www.conventionalcommits.org/) — pre-commit 强制校验。

常见前缀：

- `feat:` 新功能 → CHANGELOG `Added`
- `fix:` Bug 修复 → CHANGELOG `Fixed`
- `refactor:` 重构（不改外部行为）
- `perf:` 性能优化
- `docs:` 文档变更
- `chore:` 构建/工具/杂项
- `test:` 测试相关
- 在 footer 加 `BREAKING CHANGE:` → 触发 MAJOR/0.x MINOR 版本号变更

### 5. 构建 wheel

```bash
uv build
# 产出 dist/jiuzhang-<version>-py3-none-any.whl + dist/jiuzhang-<version>.tar.gz
```

### 6. 隔离环境验证

```bash
uv run --isolated --with dist/jiuzhang-*-py3-none-any.whl \
    python -c "import jiuzhang; print(jiuzhang.__version__)"
```

## 公开 API（v0.1.0-alpha.9，仍可能微调）

```python
from jiuzhang import (
    TokenManager,
    PhotonicMachine,
    GaussianBosonSampler,
    JiuzhangError,
)
```

完整列表见 [`src/jiuzhang/__init__.py`](./src/jiuzhang/__init__.py) 的 `__all__`。

## 版本与发布

- 版本策略：[`../VERSIONING.md`](../doc/overview/VERSIONING.md)
- 变更日志：[`../CHANGELOG.md`](../CHANGELOG.md)
- 发布 SOP：[`../RELEASING.md`](../doc/overview/RELEASING.md)

## 设计参考

- [SDK 架构设计 v0.1](../doc/SDK%20架构设计-v0.1.md)
- [应用层消息语义需求草案 v1.0](../doc/应用层消息语义需求草案-v1.0.md)
- [问题清单答复 v1.0](../doc/jiuzhang%20SDK%20问题清单答复-v1.0.md)

## LICENSE

Proprietary — Copyright © 2026 九章量子. 详见仓库根的 [LICENSE](../LICENSE)。
