jiuzhang

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

本目录为 SDK 源码工程。设计文档位于仓库根的 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. 安装依赖

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

2. 安装 pre-commit 钩子

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

3. 本地质量四件套

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 — pre-commit 强制校验。

常见前缀：

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

5. 构建 wheel

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

6. 隔离环境验证

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

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

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

完整列表见 src/jiuzhang/__init__.py 的 __all__。

版本与发布

• 版本策略：../VERSIONING.md
• 变更日志：../CHANGELOG.md
• 发布 SOP：../RELEASING.md

设计参考

• SDK 架构设计 v0.1
• 应用层消息语义需求草案 v1.0
• 问题清单答复 v1.0

LICENSE

Proprietary — Copyright © 2026 九章量子. 详见仓库根的 LICENSE。