ZCode Compatibility Core

简体中文 | English

社区维护的 ZCode 请求兼容库，提供客户端签名、配置读取、端点映射， 以及针对官方公开提交的源码集成补丁。

功能

• 客户端签名握手、密钥解密、Ed25519 签名、PoW、并发握手复用和一次签名刷新。
• 按账户隔离的签名开关与端点映射配置；映射目标受 HTTPS 和来源白名单约束。
• 公开活动说明的读取与字段过滤；客户端补丁通过原有 Host 配置服务展示说明。
• 可直接应用的源码补丁，内含核心源码。
• 离线测试和发布检查脚本。

版本边界：补丁基于官方源码提交 872ad960de7ec172591f7e1952f7849229f94521，其 package.json 为 3.14.0。 协议分析参考官方 3.14.1 发行包。

快速验证

需要 Node.js 24+、pnpm 10+ 和 Git。

pnpm install --frozen-lockfile --ignore-scripts
pnpm check

检查包含 TypeScript 构建、离线行为测试、补丁重新生成和隐私扫描。 测试使用内存传输和 .invalid 地址；安装依赖需要访问 npm。

应用集成补丁

在本仓库目录运行：

git clone https://github.com/zai-org/ZCode.git ../zcode-upstream
git -C ../zcode-upstream checkout --detach 872ad960de7ec172591f7e1952f7849229f94521
node scripts/check-upstream.mjs ../zcode-upstream
git -C ../zcode-upstream apply ../zcode-compat-core/integration/zcode-872ad960.patch

如果本仓库目录名不同，请调整最后一行补丁路径。检查脚本核对被修改文件的 SHA-256 以及补丁完整性，以确认目标源码与补丁基线一致。

按上游构建说明安装依赖、构建或启动。请求兼容层需要显式启用：

cd ../zcode-upstream
pnpm install
ZCODE_COMPAT_CORE=1 pnpm dev:desktop

桌面应用按上游流程构建。通过图形界面启动应用时，也需要在启动环境中设置 ZCODE_COMPAT_CORE=1。

补丁为明确配置为 Coding Plan 的提供商接入兼容链路，支持个人、团队及套餐 API Key。 普通自定义 API Key 提供商和非套餐模型保持原有链路。启用后由核心库处理动态端点映射， 替代上游固定网关改写；用户 HTTP 代理在最终传输层处理。

界面展示的活动说明来自官方公开配置，具体活动资格与额度扣减以服务端结果为准。

行为与配置

• 签名失败或连续拒绝时，默认停止本次模型请求并报错。 独立库可显式选择 onSigningFailure: 'unsigned'；客户端补丁保持默认报错。
• 配置开关关闭或首次配置获取失败时，请求按正常无签名路径发送。
• 配置统一缓存五分钟、失败退避三十秒。
• 日志、遥测及宿主网络行为沿用上游客户端设置。
• 调用者需要提供 transport，并将 clientVersion 设置为实际客户端构建版本。
• 模块范围为请求兼容层及活动说明展示；其他桌面功能由上游客户端提供。

验证状态

已通过离线协议验证、核心类型检查、固定提交补丁应用检查及适配层隔离测试。 待验证项包括完整 Electron 构建、图形交互、跨平台运行，以及独立实现的真实服务握手与计费。

详见 集成说明、来源说明、 验证记录 和 发布维护。

许可

本项目采用 Apache License 2.0。集成补丁包含上游 Apache-2.0 源码上下文， 分发时请保留许可证及相关版权声明。上游来源见 NOTICE。