Setup | gbz185-sdk

运行环境

依赖	要求	说明
TypeScript Beta	Node.js `>=20`, TypeScript `>=5.8`	npm 包使用 ESM，并在开发凭证实现里使用 Node.js `crypto`。
Python Alpha 实验中	Python `>=3.10`	客户端 SDK 以 `gbz185_sdk` 包导入，当前推荐 GitHub subdirectory 或本地路径安装。
Go Alpha 实验中	Go `1.22`	模块路径是 `github.com/IchenDEV/gbz185-sdk/sdks/go`，业务包导入 `/gbz185`。
Rust Alpha 实验中	Rust edition `2021`	当前 crate 适合本地 path dependency 或企业私有 registry 试用。
Java Alpha 实验中	JDK `17`, Maven	artifact 为 `dev.idevlab:gbz185-sdk`，客户端返回 Jackson `JsonNode`。
包管理器	`pnpm`, `npm`, `pip`, `go`, `cargo`, `mvn`	仓库开发脚本以 `pnpm` 驱动主包；各语言 SDK 使用自己的生态工具验证。

安装方式

TypeScript Beta

npm 包是当前主分发入口，包含完整参考运行时。

npm install gbz185-sdk
# 或者
pnpm add gbz185-sdk

本地源码开发：

git clone https://github.com/IchenDEV/gbz185-sdk.git
cd gbz185-sdk
pnpm install
pnpm typecheck
pnpm test
pnpm build

Python Alpha 实验中

python -m pip install "git+https://github.com/IchenDEV/gbz185-sdk.git#subdirectory=sdks/python"

本地源码开发：

cd sdks/python
python -m pip install .
python -m unittest discover -s tests

Go Alpha 实验中

go get github.com/IchenDEV/gbz185-sdk/sdks/go/gbz185@main

业务代码导入：

import "github.com/IchenDEV/gbz185-sdk/sdks/go/gbz185"

Rust Alpha 实验中

[dependencies]
gbz185-sdk = { path = "../gbz185-sdk/sdks/rust" }

本地源码验证：

cd sdks/rust
cargo fmt --check
cargo test

Java Alpha 实验中

cd sdks/java
mvn install

<dependency>
  <groupId>dev.idevlab</groupId>
  <artifactId>gbz185-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

TypeScript 配置

推荐你的应用使用 ESM 或支持 ESM 依赖解析的构建器。最小配置如下。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true
  }
}

如果使用 Vite、Next.js、tsup 或其他 bundler，也可以使用 moduleResolution: "Bundler"，只要运行环境能消费 ESM。

验证安装

用当前示例语言跑一个最小 smoke test，确认 SDK 可以被导入、身份码可以生成。

import {
  createAgentInterconnectRuntime,
  formatIdentityCode,
  validateIdentityCode
} from "gbz185-sdk";

const runtime = createAgentInterconnectRuntime();
const id = formatIdentityCode({
  registrationServiceProvider: "A1",
  registrationRequester: "REQ001",
  ontologySerial: "CALENDAR",
  instanceSerial: "1"
});

console.log(validateIdentityCode(id)); // true
console.log(Boolean(runtime.client));  // true

from gbz185_sdk import AgentIdentityCodeParts, format_identity_code, validate_identity_code

agent_id = format_identity_code(AgentIdentityCodeParts(
    registration_service_provider="A1",
    registration_requester="REQ001",
    ontology_serial="CALENDAR",
    instance_serial="1",
))

print(validate_identity_code(agent_id))

parts := gbz185.AgentIdentityCodeParts{
    RegistrationServiceProvider: "A1",
    RegistrationRequester:       "REQ001",
    OntologySerial:              "CALENDAR",
    InstanceSerial:              "1",
}

agentID, err := gbz185.FormatIdentityCode(parts)
if err != nil {
    panic(err)
}
fmt.Println(gbz185.ValidateIdentityCode(agentID))

use gbz185_sdk::{format_identity_code, validate_identity_code, AgentIdentityCodeParts};

let parts = AgentIdentityCodeParts::new("A1", "REQ001", "CALENDAR", "1");
let agent_id = format_identity_code(&parts)?;
assert!(validate_identity_code(&agent_id));

import dev.idevlab.gbz185.AgentIdentityCodeParts;
import dev.idevlab.gbz185.IdentityCodes;

String agentId = IdentityCodes.formatIdentityCode(
    new AgentIdentityCodeParts("A1", "REQ001", "CALENDAR", "1")
);
boolean valid = IdentityCodes.validateIdentityCode(agentId);

选择运行方式

方式	入口	适合场景
内存参考运行时	`createAgentInterconnectRuntime()`	本地开发、测试、协议演示、示例应用。
自定义进程内操作	`InProcessJsonTransport.register()`	你已经有自己的服务对象，只想复用 SDK client。
HTTP JSON 网关	`new HttpJsonTransport({ endpoint })`	把 SDK client 接到一个统一 HTTP endpoint，由服务端按 `operation` 路由。
自定义网络协议	`JsonTransport`	WebSocket、MCP、消息队列、RPC 网关或企业内部总线。

生产接入边界

内置凭证实现只用于开发验证。 它使用 Node.js Ed25519 key pair 模拟凭证签发和验签，并提供 X.509-first 的接口形态；它不是生产 CA、国密算法或主管部门合规实现。

生产环境建议替换以下接口或仓库实现：

IdentityAccountStore：接数据库、审计日志、注册服务方治理流程。
DescriptionStore：接描述发布、审核和撤销状态存储。
CredentialIssuer：接生产 CA、证书签发、密钥托管和凭证生命周期。
CredentialVerifier 与 CertificateChainVerifier：接证书链、吊销状态、算法策略和授权策略。
JsonTransport：接你的网络协议，不需要改变业务模型。