版本历史与社区支持

本文档汇总 iOS-JL_Bluetooth（杰理之家 SDK）的版本发布历史、版本命名与发布记录渠道，以及社区支持资源与问题反馈流程，帮助开发者追踪 SDK 演进、定位合适的 SDK 版本并获取官方支持。

Purpose and Scope

本页面向开发者介绍：

• 版本历史：README 中记录的正式发布版本、发布日期与主要更新内容；
• 版本追踪方式：如何通过 Git Tag、发布记录 PDF 与文档中心确认当前使用的 SDK 版本；
• 社区与支持渠道：在线文档中心、官方网站、SDK 接入文档、问题反馈入口等官方资源；
• 许可证与使用边界：Apache License 2.0 下的使用约束。

以下相关主题由其他页面单独介绍，本页不展开：SDK 集成与工程结构（见"快速开始"）、Info.plist 权限与工程配置（见"配置说明"）、日志与设备调试（见"调试技巧"）。本页聚焦于版本演进与支持生态，而非具体 API 用法。

Overview

iOS-JL_Bluetooth 是珠海市杰理科技股份有限公司为杰理音箱、耳机类产品提供的蓝牙控制开发平台，基于 RCSP（远程控制系统协议）。随着固件芯片（AC693X、AC697X、AC695X、JL701N、AC707N 等）与功能（ANC、彩屏仓、AI 翻译、Auracast、LE Audio 等）的演进，SDK 以语义化版本号持续迭代。

版本信息在仓库中以三种形式维护，互为补充：

1. README 版本历史表（README.md "八、版本历史"）——面向开发者的快速摘要，列出每个版本的发布日期与主要更新要点；
2. Git Tag（README 顶部徽章链接至 GitHub Tags 页面）——面向工程集成的精确版本锚点，可 git checkout 对应 tag 获取特定版本源码；
3. 发布记录 PDF（docs/杰理之家SDK(iOS)发布记录.pdf）——官方完整发布记录，包含更详细的变更明细。

社区支持方面，官方通过文档中心、接入文档、SDK 测试助手（SDKTestHelper）与 GitHub Issues 提供全链路支持；问题反馈是开发者与官方协作的主要通道。

Architecture

下图展示版本信息与社区支持资源的组织方式，以及开发者获取版本信息、提交反馈的路径：

flowchart TD
    subgraph sg_Repo["仓库 iOS-JL_Bluetooth"]
        README["README.md<br/>版本历史表 / 社区资源"]
        PDF["docs/杰理之家SDK(iOS)发布记录.pdf"]
        TAGS["Git Tags<br/>v1.5.0 ... v1.14.0"]
    end

    subgraph sg_Official["杰理官方资源"]
        DOC["文档中心<br/>doc.zh-jieli.com"]
        SDK_DOC["SDK 接入文档"]
        WEB["官方网站<br/>www.zh-jieli.com"]
    end

    subgraph sg_Feedback["反馈通道"]
        ISSUES["GitHub Issues<br/>问题反馈"]
        HELPER["SDKTestHelper<br/>测试助手"]
    end

    Developer["开发者"] --> README
    Developer --> TAGS
    Developer --> PDF
    Developer --> DOC
    Developer --> SDK_DOC
    Developer --> WEB
    Developer --> ISSUES
    Developer --> HELPER
    README -->|"链接跳转"| DOC
    README -->|"链接跳转"| SDK_DOC
    README -->|"链接跳转"| ISSUES
    README -->|"链接跳转"| PDF

说明：README 是版本与支持信息的"入口枢纽"——它通过相对链接引用发布记录 PDF、通过绝对链接跳转到文档中心/接入文档/问题反馈页，并通过徽章指向 Git Tags。开发者既可以只读 README 快速了解版本概况，也可以深入 PDF 或 Tag 获取精确的版本差异，最终通过 Issues 或测试助手与官方协作。

版本历史

正式版本一览

以下版本记录摘自 README.md 的"八、版本历史"章节：

版本演进观察

• 发布节奏：从表格可见 SDK 的发布周期并不固定（2021–2026 年共 8 个记录版本），重大功能版本（如 v1.13.0 彩屏仓、v1.14.0 AI 翻译/LE Audio）之间间隔约半年到一年，中间以小版本修复为主。
• 版本号跳跃：表中存在 v1.10.0 → v1.6.4 的编号回落，说明 README 表格记录的是面向客户的重要发布，并非仓库全部 tag；完整的逐版本明细以 发布记录 PDF 与 Git Tags 为准。
• 功能演进主线：音质与降噪（v1.5.0 ANC）→ 耳机形态适配（v1.6.x 挂脖/辅听）→ 表盘与 OTA（v1.10–v1.12）→ 彩屏仓与天气（v1.13.0）→ 新一代音频生态 LE Audio / Auracast / AI 翻译（v1.14.0）。

版本追踪与获取

通过 Git Tag 锁定版本

README 顶部通过徽章链接到 GitHub Tags 页面（tag download），标识仓库当前发布的最新 tag。工程集成时可通过 tag 拉取对应版本的源码：

git clone https://github.com/Jieli-Tech/iOS-JL_Bluetooth.git
cd iOS-JL_Bluetooth
git checkout v1.14.0

Source: README.md

设计意图：以 Tag 而非分支作为版本锚点，可保证集成环境的可复现性——同一 tag 下的代码与 libs/ 目录中的 XCFramework 严格对应，避免分支持续演进导致的行为漂移。

发布记录 PDF

官方完整发布记录存放于 docs/ 目录：

该文件在 README"七、社区与支持"的资源链接表中被引用（README.md L238），是核对版本差异、判断是否需要升级的首选依据。

升级决策流程

flowchart TD
    Start([需要评估 SDK 版本]) --> Check["查看 README 版本历史表<br/>确认最新版本与功能"]
    Check --> Need{"是否需要新功能<br/>或修复?"}
    Need -->|"否"| Keep["保持当前版本<br/>无需升级"]
    Need -->|"是"| ReadPDF["阅读发布记录 PDF<br/>确认变更明细与兼容性"]
    ReadPDF --> Verify{"固件芯片是否支持?<br/>AC693X/AC697X/AC695X<br/>JL701N/AC707N"}
    Verify -->|"支持"| Upgrade["切换 Git Tag 升级<br/>并参考示例工程迁移"]
    Verify -->|"不支持"| Contact["联系官方/社区<br/>确认固件方案"]
    Keep --> End([结束])
    Upgrade --> End
    Contact --> End

社区支持渠道

官方资源链接

以下资源链接摘自 README.md L229-L240：

开发辅助工具

仓库内提供 SDKTestHelper（Swift 测试工具），用于 SDK 功能测试、设备连接调试、音频功能验证、Auracast 广播测试、日志查看与性能监控，可在反馈问题前先行自测定位（README.md L96-L112）：

# 打开测试助手工程
open code/SDKTestHelper/SDKTestHelper.xcworkspace

Source: README.md

问题反馈流程

sequenceDiagram
    participant Dev as 开发者
    participant Helper as SDKTestHelper
    participant Doc as 文档中心/调试说明
    participant Issues as GitHub Issues
    participant Team as 杰理官方

    Dev->>Helper: 复现问题并收集日志
    Dev->>Doc: 查阅 SDK 调试说明/导出打印日志说明
    Doc-->>Dev: 排查建议
    alt 仍未解决
        Dev->>Issues: 提交问题（附版本号、固件型号、日志）
        Issues-->>Team: 通知官方
        Team-->>Dev: 反馈结论/修复版本
    end

建议：提交 Issue 时附带 SDK 版本号（README 表格中的 tag 名）、目标固件芯片型号（如 AC697X）与 SDKTestHelper 导出的日志，可显著加速官方定位。

许可证

本项目采用 Apache License 2.0 开源协议，版权归珠海市杰理科技股份有限公司所有（README.md L259-L277）：

Copyright 2024 珠海市杰理科技股份有限公司

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Source: README.md

Apache 2.0 允许商用、修改与再分发，但需保留版权声明并注明修改；使用前请阅读完整 LICENSE 文件确认义务条款。

边界情况与注意事项

• README 表格并非完整 tag 列表：表中版本号存在不连续（如 v1.10.0 之后直接是 v1.6.4），中间版本未列入。判断"是否有更新"应以 发布记录 PDF 与 Git Tags 为准，而不是仅看 README 表格。
• 版本与固件芯片强绑定：不同版本支持不同芯片方案（v1.10.0 支持 JL701N、v1.12.0 兼容 AC707N）。升级 SDK 前必须确认目标设备的固件是否满足对应版本要求，否则可能出现协议不兼容。
• 文档中心与仓库可能不同步：文档中心（doc.zh-jieli.com）是独立托管的站点，其内容更新节奏与 GitHub/Gitee 仓库不完全一致；遇到文档与源码不一致时，以仓库源码与发布记录 PDF 为准。
• 仓库镜像差异：README 中的克隆地址与问题反馈入口指向 GitHub，而本仓库同时托管于 Gitee；访问受限时可通过 Gitee 镜像获取源码，但 Issues 提交入口以 README 标注的链接为准。
• Xcode 版本要求：SDK 建议使用最新版本 Xcode 开发（README.md L73），旧版 Xcode 可能无法编译新版 XCFramework 或示例工程。

运维与发布观察

• 版本追溯：工程集成时可在 Info.plist 或构建脚本中记录 SDK tag，便于线上问题回溯到具体 SDK 版本；结合 SDKTestHelper 的日志与性能监控功能，可快速判断问题属于 SDK、固件还是业务代码。
• 升级策略：对于生产环境，建议采用"先小版本修复、后大版本功能"的渐进升级路径，并在升级后回归验证蓝牙连接稳定性与音频链路，因为 RCSP 协议变更（如 v1.14.0 引入 LE Audio 并存）可能影响既有连接行为。
• 发布节奏无固定承诺：从历史记录看，SDK 发布由产品与芯片方案驱动而非固定周期；对功能需求的预期应以官方发布记录为准。

社区参与与扩展点

• 提交问题（Issues）：官方指定的反馈入口，适用于 bug 报告与功能建议。良好的 Issue 应包含：SDK 版本、固件型号、复现步骤、SDKTestHelper 日志。
• 阅读调试文档：反馈前可先参考 SDK调试说明 与 杰理之家导出打印日志说明（README"六、调试技巧"），使用 xcode Console 查看实时日志辅助定位（README.md L218-L224）。
• License 合规：基于 Apache 2.0 的二次开发与商用需保留版权声明；社区贡献（如提交 PR）同样受该协议约束。

Related Links

• SDK 接入文档（文档中心）
• 发布记录 PDF
• README.md（仓库总览）
• 问题反馈 Issues
• SDK 调试说明