第12章　完成开源审查并发布`v1.0`

第11章形成了v1.0.0-rc.1发布候选。本章在受控环境中开展小规模试用，并修复阻塞问题。随后完成各类发布审查，把允许公开的部分发布为v1.0。

发布候选
→ 小规模试用
→ 问题分级与修复
→ 全项目评审
→ 开源权利与安全检查
→ 发布包复现
→ v1.0.0
→ 维护入口

开源发布不是把内部仓库改为公开。外部使用者应能了解项目目标、取得方法和构建方法。发布材料还要说明支持的硬件、模型和数据来源。许可证、已知限制和问题报告方法也应明确。

早期开源实践常以公开源代码为主要目标。项目依赖增多后，只有代码还不足以支持复现和维护。版本、依赖、权利和安全信息也要同时交付，其代价是发布前需要更严格的审查和清理。

完成本章后，应当能够：

组织不超出课程风险边界的小规模用户试用；
把试用反馈转成可复现议题并确定优先级；
对发布候选开展跨代码、模型、硬件和产品的联合评审；
盘点项目中每类材料的权利与公开范围；
使用许可证标识和第三方声明保存来源；
生成并核对软件物料清单；
从干净环境复现构建和核心验证；
区分内部源仓库、公开发布仓库和发布构建物；
编写README.md、贡献指南、安全说明和发布说明；
创建不可移动的v1.0.0标签并验证发布包；
建立v1.0后的问题、修复和模型更新流程。

12.1 规划小规模试用

12.1.1 试用只验证批准范围

试用前固定：

产品版本：v1.0.0-rc.1或后续候选
固件构建物及SHA-256：
模型版本及SHA-256：
策略版本：
硬件修订：
服务器版本：
EVENT-001版本：
试用场景：
参与者和授权记录：
开始与结束时间：
停止条件：

课程原型不得用于医疗诊断、公共安全处置或其他超出产品定义的高风险用途。试用者知道系统仍是候选版本，重要行动不能只依赖自动判断。

12.1.2 试用任务要可观察

用户验收测试（User Acceptance Testing，UAT）用于观察产品能否支持预定任务。

每项任务包含：

## 试用任务UAT-01
- 目标：验证用户能否理解并处理一条目标事件
- 前置条件：设备在线，用户已授权
- 操作：在批准场景产生目标输入
- 记录：
  - 设备是否形成事件
  - 用户何时看到反馈
  - 用户是否理解事件含义
  - 用户采取了什么行动
  - 是否出现错误或隐私疑问
- 停止条件：连续异常通知、设备过热、数据越界或其他安全问题

结果应记录实际行为和反馈，不能以教师演示结果代替用户结果。

12.1.3 数据采集遵守最小必要

试用默认记录：

事件标识和版本身份；
系统延迟与错误状态；
用户主动提交的反馈；
经批准的设备运行指标。

不因为“后续可能训练模型”就持续保存全部原始传感数据。若需要收集新数据，建立独立采集会话、用途、授权、保留期和访问控制。

12.2 把反馈转成工程议题

12.2.1 一条可复现缺陷

# 事件页面显示时间与设备日志相差8 h

## 版本
- 产品：v1.0.0-rc.1
- 固件：
- 服务器：
- 用户端：
- 浏览器/环境：

## 前置条件
<时区和账户设置>

## 复现步骤
1.
2.
3.

## 实际结果
<页面和日志中的实际时间>

## 预期结果
页面按产品规格显示本地时间，并保留原始UTC时间可追溯。

## 证据
- event_id：
- 日志：
- 截图：

## 数据处理
证据已脱敏。

AI可以根据记录整理议题，但不得补写没有发生的复现步骤和环境。

12.2.2 按发布影响分级

等级	说明	发布处理
Blocker	安全、隐私、数据损坏、核心闭环不可用	必须修复并重新验证
High	主要需求无法可靠完成	原则上修复后发布
Medium	存在替代操作的非核心问题	评估修复或记录限制
Low	轻微体验或后续改进	可进入`v1.1`候选

优先级依据影响和发生条件，不依据提交者身份或AI判断。改变等级要在议题中说明理由。

12.2.3 候选版本修复仍走完整工作流

试用Issue
→ 任务分支
→ 失败测试或复现
→ 受限AI实施
→ 本地检查
→ CI
→ 同伴评审
→ 合并
→ 新候选标签
→ 受影响试用复测

每个候选标签保持不动：

v1.0.0-rc.1
v1.0.0-rc.2
后续候选标签按序增加

12.3 开展发布前联合评审

发布评审按工程对象分工：

评审方向	主要问题
产品	`v1.0`范围是否完成，限制是否准确
Git与代码	提交、分支、依赖和构建是否可复查
硬件	物料清单、接线、修订和资源是否与发布一致
数据与模型	来源、授权、数据集清单、模型清单、评价和模型卡是否完整
测试	自动、实机和试用证据是否指向候选提交
安全与隐私	凭据、日志、数据、接口和默认配置是否安全
开源权利	自有、第三方和不可公开材料是否区分
运维	安装、升级、回退、故障和支持入口是否明确

评审者在发布合并请求中提交阻塞意见。发布负责人汇总但不能替代各领域评审。

12.4 盘点可以公开的材料

12.4.1 建立权利与公开清单

docs/release/disclosure-inventory.md：

| 路径/构建物 | 类型 | 来源/作者 | 许可证或授权 | 可公开 | 处理 |
|---|---|---|---|---|---|
| `firmware/` | 自有代码 | 项目成员 | 待选项目许可证 | 是或否 | 保留或移除 |
| `server/` | 自有代码 | 项目成员 | 待选项目许可证 | 是或否 |  |
| `third_party/<子目录>` | 第三方代码 | <来源> | <实际许可证> | 待核查 | 声明或替换 |
| `datasets/<子目录>` | 数据清单 | 课程项目 | <授权范围> | 是或否 | 脱敏 |
| `model.tflite` | 模型 | <模型发布包> | <实际权利> | 是或否 | 发布或仅提供取得方法 |
| `hardware/<子目录>` | 硬件资料 | <作者> | <实际权利> | 是或否 |  |

“可以在技术上访问”不等于“可以公开再分发”。每一项必须有来源和权利依据。

12.4.2 不同材料可能使用不同许可证

项目可能同时包含：

软件源代码；
教程和文档；
硬件设计文件；
数据；
模型；
第三方依赖。

一个软件许可证不能自动覆盖所有对象。课程组根据出版社、学校和项目权利要求选择许可证，并在README.md中说明各目录适用范围。教材不替项目作法律结论。

12.4.3 保留第三方声明

对允许再分发的第三方材料：

保留原版权和许可证文本；
在THIRD_PARTY_NOTICES.md记录组件、来源、版本和许可证；
源文件需要时保留规定的许可证头；
不把第三方代码改名后表述为项目原创；
检查模型、数据和字体等非代码材料。

若无法确认权利，默认不进入公开发布包，建立议题继续核查或替换。

12.5 选择和标识项目许可证

12.5.1 许可证选择是发布决定

选择前回答：

是否允许商业使用；
是否允许修改和再分发；
衍生作品是否必须使用相同许可证；
是否包含专利条款；
文档、硬件、数据和模型是否需要单独许可；
第三方依赖是否兼容；
学校或出版社是否有指定要求。

决定通过技术与治理合并请求评审，LICENSE保存完整文本，README.md说明适用对象。

12.5.2 使用标准许可证标识

软件包数据交换（Software Package Data Exchange，SPDX）提供标准化的许可证标识。若许可证具有SPDX短标识，可以在源文件中按注释语法添加：

// SPDX-License-Identifier: <approved-license-id>

不要把占位符提交到正式版本。自动添加标识前先确认文件确实由项目拥有并适用该许可证，第三方文件保持其原有声明。

12.6 检查依赖与软件物料清单

12.6.1 依赖清单回答“发布了什么”

软件物料清单（Software Bill of Materials，SBOM）记录发布构建中包含的软件组件及其关系。它有助于：

确认依赖版本；
检查许可证；
在组件出现安全问题时定位影响；
比较两个发布版本的组成；
支持供应链审查。

项目工具生成课程批准格式：

python tools/project.py sbom

输出至少包括：

项目与版本；
依赖名称和版本；
包标识或下载位置；
文件或包散列值；
许可证声明；
直接或间接关系；
生成工具和时间。

12.6.2 自动结果需要人工核对

检查：

[ ] 固件库和服务器依赖都被覆盖
[ ] 实际构建版本与锁定文件一致
[ ] 本地复制的第三方源代码没有遗漏
[ ] 未识别许可证已建立Issue
[ ] 开发依赖和运行依赖能够区分
[ ] SBOM指向当前发布候选

软件物料清单不是安全或许可证合规的自动结论，它是供评审核对的组成清单。

12.7 清理公开边界

12.7.1 扫描当前树和历史

检查：

python tools/secret_check.py
git grep -n -I -E "token|password|secret|api[_-]?key"
git log --all --stat

人工检查：

内部域名和IP；
个人路径与用户名；
设备真实标识；
测试账户；
原始访谈和数据；
未审查模型；
私有服务器拓扑；
临时日志和崩溃转储。

当前文件已删除不代表Git历史中不存在。发现秘密时先吊销并报告，再由维护者决定历史处理和公开方式。

12.7.2 内部仓库与公开仓库分开

建议：

校内GitLab内部仓库
  ├─ 完整开发历史与受控材料
  └─ 经过批准的公开发布内容
           ↓
    学校批准的公开代码托管平台

是否保留完整历史取决于历史审计结果。若历史包含不可公开材料，应通过经过评审的流程导出公开仓库。同时保存内部提交到公开提交的映射和发布清单。不得直接公开整个内部仓库。

12.8 完善开源仓库入口

公开候选至少包含：

README.md
LICENSE
CHANGELOG.md
CONTRIBUTING.md
SECURITY.md
SUPPORT.md
THIRD_PARTY_NOTICES.md
docs/
contracts/
hardware/中批准公开的资料
模型卡和批准公开的模型构建物或取得说明
构建与测试代码

12.8.1 `README.md`以复现为中心

README.md结构：

# 智能感知终端

## 项目简介
<用户问题、产品结果和v1.0范围>

## 系统结构
<设备、服务器和用户端关系>

## v1.0支持
- 硬件修订：
- 事件类别：
- 模型版本：
- 已验证环境：

## 快速开始
1. 克隆指定版本；
2. 检查环境；
3. 取得并验证模型；
4. 构建服务器和固件；
5. 执行最小端到端验证。

## 版本和构建物
<标签、散列值和发布入口>

## 数据、模型与隐私
<来源、限制和默认数据行为>

## 当前限制
<错报、漏报、场景、网络、硬件和非适用用途>

## 贡献、安全与支持
<对应文档链接>

## 许可证
<各类材料的适用范围>

12.8.2 CONTRIBUTING描述实际工作流

说明：

怎样建立议题；
怎样命名分支；
怎样配置AI工具边界；
必须运行哪些本地检查；
合并请求如何填写；
哪些变化需要数据、模型或硬件评审；
怎样处理个人数据和秘密；
提交需要遵守的许可证要求。

不要要求外部贡献者访问校内模型服务才能完成所有基础贡献。AI工具可以是开发方式之一，验收标准应落在文件、测试和证据上。

12.8.3 `SECURITY.md`建立非公开报告通道

安全问题不应先发布为公开议题。SECURITY.md说明：

支持的版本；
报告入口；
需要提供的最小信息；
不应提交的秘密和个人数据；
项目响应范围；
修复与发布方法。

联系信息必须是课程组批准且能持续维护的入口。

12.9 从干净环境复现发布

12.9.1 重新克隆候选标签

在与日常工作目录不同的干净位置执行：

git clone <公开候选仓库地址>
cd intelligent-sensing-terminal
git switch --detach v1.0.0-rc.<实际编号>
git status --short

按照README.md完成：

python tools/project.py doctor
python tools/project.py fetch-model <发布模型版本>
python tools/project.py verify-model <发布模型版本>
python tools/project.py release-check
python tools/project.py build-firmware --release

再完成一次真实设备最小闭环。

12.9.2 复现记录

# v1.0发布复现记录

- 候选标签：
- Git提交：
- 操作系统：
- 工具链：
- 硬件修订：
- 模型版本和散列：
- 构建命令：
- 自动检查结果：
- 固件散列：
- 实机事件ID：
- 服务器版本：
- 用户端结果：
- 未解决差异：

若README.md缺少步骤或依赖个人环境，不直接在主分支修改；建立发布文档议题和合并请求，形成新的候选标签后重新复现。

12.10 编写发布说明

AI可以从里程碑、合并请求和CHANGELOG.md生成初稿：

请根据v0.5.0到当前候选提交之间已经合并的MR，
按“用户变化、工程变化、数据与模型、硬件、修复、
已知限制、升级与回退”整理发布说明。

每一项必须附MR或Issue编号。
不得补充仓库中没有的性能、兼容性和安全结论。

人工逐项核对。发布说明至少包括：

v1.0产品范围；
支持硬件与环境；
固件、模型、策略和契约版本；
与v0.5相比的变化；
构建物及SHA-256；
安装或升级步骤；
回退步骤；
已知限制；
安全、隐私和数据说明；
许可证和第三方材料；
问题报告入口。

12.11 创建`v1.0.0`正式版本

12.11.1 最终门禁

[ ] 最终候选完成小规模试用
[ ] Blocker和High问题已处理
[ ] 发布联合评审全部通过
[ ] 权利与公开清单无未决阻塞项
[ ] LICENSE和第三方声明已批准
[ ] SBOM已生成并核对
[ ] 敏感信息与公开边界检查通过
[ ] 干净环境构建和实机闭环通过
[ ] README.md、发布说明和回退步骤准确
[ ] 发布构建物和散列值已经固定

12.11.2 标签和发布记录

在最终批准提交上：

git switch main
git pull --ff-only
git status --short
git tag -a v1.0.0 -m "v1.0.0 first stable course release"
git show v1.0.0
git push origin v1.0.0

由流水线为该标签生成发布包。上传前核对：

构建物来自v1.0.0提交；
文件名包含产品、版本和硬件目标；
SHA-256与发布说明一致；
软件物料清单与第三方声明包含在发布资料中；
不含秘密和未授权数据。

正式标签创建后不移动、不覆盖构建物。任何修改发布为v1.0.1或后续版本。

12.12 建立`v1.0`后的维护流程

12.12.1 问题入口

议题模板至少包括：

缺陷报告；
功能建议；
硬件兼容性；
模型或事件效果；
文档问题。

安全问题使用SECURITY.md入口，不使用公开议题。

12.12.2 修复版本

v1.0.0发现兼容性缺陷
→ 议题与复现
→ 修复分支
→ 自动与实机回归
→ 合并请求评审
→ v1.0.1

若改变公开事件契约或其他不兼容接口，不能按普通修复版本处理，应评估主版本变化和迁移说明。

12.12.3 模型持续更新

试用数据支持模型改进时：

新授权采集会话
→ 新数据集版本
→ 新训练运行
→ 新模型发布包
→ 主机和设备基准样例测试
→ 策略重新评价
→ 小规模试用
→ 新产品版本

不在服务器或设备上静默替换模型文件。每个模型更新都要保留原版本、散列、评价、适用边界和回退路径。

12.12.4 维护能力要与公开范围匹配

公开项目应明确：

当前维护者；
支持版本；
大致响应范围；
不接受或暂不支持的需求；
版本弃用方法；
无法继续维护时的说明。

开源不等于承诺无限支持。准确说明维护边界比建立大量无人处理的模板更有价值。

12.13 本章小结

本章完成了智能感知终端从发布候选到v1.0的全过程。小规模试用提供真实使用证据。联合评审检查代码、硬件、数据、模型、测试和运维。开源审查确认公开权利与安全边界。干净环境复现用于证明外部使用者能够取得正确构建物。

AI用于整理议题、生成发布说明初稿和辅助清单检查。许可证、公开范围、风险接受和最终发布由人负责。v1.0不是项目终点，而是首个公开、可复查、可维护的稳定接口基线。

第13—18章转入学生主导项目。学生将复用前12章的方法，在六周内从项目原点推进到v1.0。各组还要根据项目类型作出需求、硬件、模型、测试和开源决策。

12.14 综合实践

为本组候选版本设计小规模试用。形成用户任务、记录字段、停止条件和隐私边界，并把一次反馈转为可复现议题。
完成权利与公开范围清单。为代码、文档、硬件、数据、模型和图片分别给出保留、替换、移除或只提供取得方法的决定。
生成软件物料清单，并抽查一个依赖是否确实进入发布构建。记录自动结果与人工核查的差异。
由未参与编写文档的成员从干净目录复现候选版本。把隐含步骤转成文档合并请求，再重新复现。
形成v1.0.0发布包、散列值、发布说明和维护入口。另建一个后续议题，说明版本演进和回退路径。

12.15 拓展阅读

SPDX许可证标识和软件物料清单规范；
语义化版本2.0.0规范；
校内GitLab发布、受保护标签和安全变量文档；
项目所选许可证的正式文本。

第12章 完成开源审查并发布v1.0