朱老师教你玩转 AIUI 开源项目 — 上传到 GitHub 即刻参与开源协作

随着 AI 时代到来，许多新人加入了我们这个行业，但遇到 GitHub 往往一头雾水，各种黑话和关键词看得人迷迷糊糊。我们在 Rokid 官方看到的 GitHub 开源仓库，也是多数人看到的第一个开源项目，他们会先问“代码怎么跑”“AIX 怎么上传”，这在官方 IDE 里就能操作。但如果要深入开发，就不得不了解 GitHub。比如 git commit 被误认为已经上传，Fork 被误认为会修改原仓库，Pull Request 被误认为是发布按钮。所以便有了这篇文章，致力于让更多人玩转 GitHub，理清 GitHub 这个在 AI 加持下也能轻松上手的代码仓库利器。

另外一点就是“开源”（强烈建议读《黑客与画家》这本书），开源不是把文件随手放到网上，而是标准化的流程、清楚的许可证、可理解的文档、可复现的步骤和公开的协作规则，把个人经验变成社区可以共同使用、共同检查、共同改进的公共资产。对推动我们行业发展、尤其是对 AIUI 项目而言，这一点更为重要，因为它同时涉及代码、页面、传感器数据、AIX、眼镜真机和平台审核。

所以这篇文章的顺序是：先用最容易理解的方式解释 GitHub，了解标准工作流程涉及的概念；再拿我的 AIUI Sports Agents 做例子；最后介绍官方 AIUI 的基本玩法，以及 AIUI 官方开发工具与技能仓库可以怎样作为参考。你不需要一开始就会写代码，先看懂项目如何被保存、讨论、修改和验证，就已经迈过了开源的第一道门。

图片说明：GitHub 操作图使用真实网页截图或 GitHub Docs 截图，负责告诉你“按钮在哪里”；跨页面协作和 AIUI 交付边界使用蓝墨纸绘流程图，负责说明“这些动作如何衔接”。界面可能更新，请优先按按钮文字寻找入口。

图｜GitHub、AIUI Sports Agents 与 AIUI 官方工具的学习路线

一、GitHub 到底是什么

本章结果：看懂一个公开仓库首页，分清本地 Git 与 GitHub 网页上的操作。

GitHub 是建立在 Git 之上的在线软件协作平台。它不只是“放代码的网盘”，还会记录项目文件、版本历史、问题讨论、代码评审、自动检查和版本发布。

可以先记住这个比喻：

Git 是你电脑上的版本账本；
GitHub 是大家共同使用的线上项目室；
Issue 是公开的问题单和讨论卡；
Pull Request 是把一份改动送来评审的意思；
Actions 是按照规则自动运行的检查；
Release 是围绕某个版本整理的交付页。

GitHub 之所以能让陌生人协作，是因为每次改动都可以追溯：谁改了什么、为什么改、有没有测试、维护者是否接受，都能留下记录。开源项目的价值，也正是从“别人能看到”进一步走向“别人能理解、能复现、能改进”。

1. Git 和 GitHub：本地记账与在线协作

Git 通常运行在你的电脑上，负责比较文件、创建分支、保存 Commit 和合并改动。即使暂时断网，Git 也能继续记录。（https://git-scm.com/)

GitHub 负责托管远端仓库，并提供网页上的 Issues、Pull Requests、Actions、Releases 和安全报告等功能。(https://github.com/)

最容易混淆的两个动作是：

git commit：把当前改动保存为本地版本记录；
git push：把本地版本记录推送到 GitHub 远端。

因此，Commit 完成后 GitHub 网页不一定马上变化；Push 成功后，远端才会出现新的提交

图｜Git 与 GitHub：本地版本账本与网上协作空间（脱敏后的真实命令输出记录与 GitHub 真实页面截图；界面可能更新）

图｜Git 与 GitHub：本地版本账本与网上协作空间

2. Repository、Public 和 Private

Repository 常简称 Repo，中文叫“仓库”。仓库是项目的线上总目录，里面可以有源码、文档、测试、图片和版本历史。我的示例仓库地址是：

https://github.com/EasonZhu1997/AIUI-Sports-Agents

Public 表示任何人都可以查看；Private 表示只有被授权的人可以查看。Public 只说明可见范围，不代表项目已经完成，也不代表其中所有第三方素材都可以商用，更不代表 AIX 已上传或 AIUI Studio 已审核。

图｜Repository：仓库名、Public 标识与文件区（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

图｜Public 与 Private：创建仓库时选择可见性（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

3. README 和 LICENSE：进入项目先看什么

README.md 是仓库首页的说明书。第一次进入任何公开项目，建议先回答五个问题：项目解决什么问题、适合谁、怎样运行、目前验证到哪一层、遇到问题去哪里反馈。

LICENSE 是使用规则。代码能看见，不等于可以随意复制、修改、商用和再发布。字体、图片、SDK、固件、数据集和 AIX 还可能有自己的条款，不能因为仓库是 Public 就默认全部开放。

图｜README：文件入口与仓库首页说明区（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

图｜LICENSE：许可证文件与授权规则入口（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

4. GitHub 页面上的主要功能

打开一个公开仓库，通常会看到这些入口：

Code：浏览文件、复制 Clone 地址或下载 ZIP；
Issues：提问、报 Bug、提出需求和提交证据；
Pull requests：查看待评审的改动；
Actions：查看自动测试和构建结果；
Security：查看安全策略或报告漏洞；
Releases：查看维护者发布的版本；
Star：收藏项目，方便以后找到；
Watch：订阅项目动态；
Fork：在自己的账号创建一个关联副本。

这些入口的权限不同。访客通常可以读代码和提 Issue；维护者才有合并、设置仓库和发布 Release 的权限。

图｜GitHub 黑话 0–16 说明增强版：定义、AIUI 用法、命令与协作边界（蓝墨纸绘说明增强图；含术语定义、AIUI 用法、命令和协作边界）

图｜GitHub 功能地图：黑话之间如何连接（蓝墨纸绘流程图或架构图；用于解释关系与边界）

二、GitHub 协作怎么做：从 Fork 到 Pull Request

本章结果：独立完成 Fork、Clone、Branch、Commit、Push 和 Pull Request 的基本流程。

下面这条路线，是最常见的开源协作过程：

1. 先读 README、LICENSE 和贡献指南；

2. 在 Issue 里描述问题、需求或复现证据；

3. Fork 原仓库，在自己的账号得到副本；

4. Clone 自己的 Fork 到电脑；

5. 新建 Branch，隔离这一次改动；

6. 修改文件并运行检查；

7. Commit，保存一条有说明的本地记录；

8. Push，把记录上传到自己的远端分支；

9. 创建 Pull Request，请求维护者评审；

10. 根据评论继续修改，等待 Actions 和人工检查；

11. 维护者决定是否 Merge；

12. 到了明确版本节点，再考虑制作 Release。

图｜开源协作 1–12 步：从读懂仓库到发布版本（蓝墨纸绘流程图或架构图；用于解释关系与边界）

Fork、Clone、Branch、Commit、Push、Pull 分别是什么

Fork 发生在 GitHub 网页上，是“复制到自己的账号”；Clone 发生在本地终端，是“把仓库和历史复制到电脑”。只有准备持续修改和贡献时，才需要把 Fork 和 Clone 配合起来。

Branch 是独立工作线。不要直接在 main 上堆很多互不相关的改动，可以使用：

git switch -c docs/clarify-aiui-flow

Commit 是一次本地版本快照，建议一次只解决一个问题：

git commit -m "docs: clarify AIUI upload boundary"

Push 是把本地 Commit 上传到远端：

git push -u origin docs/clarify-aiui-flow

Pull 是把远端最新变化取回本地并尝试整合：

git pull

图｜Fork、Clone、Commit、Push 到底发生在哪里（蓝墨纸绘流程图或架构图；用于解释关系与边界）

图｜Code 菜单：Clone 地址和 Download ZIP 的区别（协作流程图或架构图，非真实网页界面）

图｜Branch：切换、搜索或创建工作分支（协作流程图或架构图，非真实网页界面）

Git 与 GitHub 协作方式对比

对比维度	Git（本地版本账本）	GitHub（线上协作空间）
性能	本地操作，断网也能提交，速度快、无网络延迟	依赖网络，Push/Pull 有传输开销，但适合多人共享
易用性	命令行为主，需要记住 commit、branch、merge 等命令	网页可视化操作，Issue、PR、Actions 一键入口，对新手更友好
适用场景	单人本地开发、版本快照、离线记录、分支管理	多人协作、代码评审、问题追踪、自动化检查、版本发布

简单总结：Git 负责把改动在本地记成一条条可追溯的版本记录，速度快、离线可用；GitHub 则把这些记录搬到线上，让团队可以围绕代码讨论、评审和发布。日常开发中两者配合使用——先用 Git 在本地提交，再用 GitHub 完成协作与交付。

Issue、Pull Request、Merge、Actions 和 Release

Issue 是公开的问题单，不只用来报 Bug，也可以记录建议、任务、问卷和脱敏测试证据。一个好的 Issue 要写清环境、复现步骤、期望结果、实际结果和仍未验证的范围。

Pull Request（简称 PR）不是“下载请求”，而是“请维护者评审我的改动”。base 是要合入的目标分支，head 或 compare 是你提交改动的来源分支。

Merge 是维护者把通过评审的 PR 合入目标分支。它只说明源码或文档进入了主线，不代表 AIX 已生成、眼镜已安装或平台已上架。

Actions 是自动化检查。它能证明工作流中定义并实际运行的检查结果，不能代替真实眼镜、蓝牙外设或长时间现场验证。

Release 是版本交付页。它可以附带源码压缩包或经过授权的产物，但不是 AIUI Studio 的上架按钮。

图｜Pull Request：比较 base 与 head 后发起评审（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

图｜Actions：查看工作流、运行状态与步骤日志（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

图｜Release：版本发布入口与发布表单（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

三、以我的 AIUI Sports Agents 仓库为例

本章结果：找到项目入口，了解 Run、Bike、Rower 的定位，并选定参与方式。

1. 这个项目是做什么的

AIUI Sports Agents 是一个围绕智能眼镜运动体验搭建的公开协作项目。它目前把跑步、骑行和室内划船机放在同一个 Hub 中，但三套应用仍然独立运行、独立验证，不用一个模糊总分比较不同运动。

项目共同关注三件事：

数据是否诚实：实测、估算、模拟和不可用要区分；
交互是否可靠：开始、暂停、恢复、结束和异常路径要清楚；
结论是否有证据：版本、设备、环境、命令和结果要能追溯。

图｜三种运动项目如何共建（蓝墨纸绘流程图或架构图；用于解释关系与边界）

2. 三个应用分别解决什么问题

apps/smartrun 面向跑步，重点是心率、步频、步长、距离、配速和训练阶段；数据缺失时要诚实降级。

apps/aibike 面向骑行，重点是心率、速度、踏频、轮转里程、功率和 FTMS/CSC/CPS 等适用输入；多传感器来源要有清楚的仲裁规则。

apps/aismartrower 面向划船机，优先处理标准 FTMS 只读遥测，如桨频、时间、距离、500 米配速和训练阶段；当前不把未经确认的 0x2AD9 控制写入路径当作公开能力。

皮划艇目前只公开孵化项目卡与 L2 评测上下文，不提供对应应用源码或 AIX。未来增加运动项目时，可以共享状态、来源、隐私和证据规则，但不要把配速、功率和桨频硬凑成一个总分。

图｜AIUI Sports Agents 的四层架构与交付边界（蓝墨纸绘流程图或架构图；用于解释关系与边界）

3. 第一次打开这个仓库，建议按这个顺序

先看仓库首页的 README，确认项目定位、当前目录和贡献入口；再看 LICENSE、CONTRIBUTING、安全报告入口和各应用自己的 README。

然后按你的目标选择路线：

只想了解项目：浏览 README、结果卡和证据说明；
想试运行：进入目标应用目录，按 README 执行本地测试或预览检查；
想帮助项目：在 Issues 提交体验、Bug 或脱敏证据；
想改文档或工具：先看贡献指南，再 Fork、Branch、Commit、Push 和 PR；
想发布自己的 AIUI 应用：先确认你拥有源码、素材、账号、设备和平台发布权限。

仓库根目录可以用 Node.js 20–25 运行：

npm run validate
npm run report

这些命令检查公开登记、证据结构和结果摘要，不代表三套应用已经通过真机验收，也不会自动上传或安装 AIX。

4. 怎么帮助这个项目

不会写代码也可以贡献。最有价值的帮助通常包括：清楚的体验反馈、可复现的 Bug、脱敏后的设备证据、错别字修正、测试夹具和文档改进。

填写项目问卷时，进入 Issues → New issue，选择“体验与贡献问卷”或“Bug 与真机证据”，写清目标项目、版本、环境、数据来源、复现步骤、证据等级和待验证项。提交前删除 token、密钥、邮箱、MAC、序列号、精确位置、运动轨迹和私有链接。

图｜从 Issues 进入体验与贡献问卷（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

图｜贡献问卷填写实拍（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

问卷只登记社区反馈，不会自动上传 AIX，不会自动创建 AIUI Studio 项目，也不会替你提交 PR。

四、在 AIUI Sports Agents 中贡献一次改动

本章结果：把一次文档或代码改动从 Issue 推进到 Pull Request，并留下可复核记录。

确认 Issue 范围后，在原仓库点击 Fork，进入自己的副本。再点击 Code 复制 HTTPS 地址，在电脑执行：

git clone https://github.com/YOUR_ACCOUNT/YOUR_REPOSITORY.git
cd YOUR_REPOSITORY
git switch -c docs/clarify-aiui-flow

修改前先确认自己在哪个目录、哪个分支；修改后运行项目检查和：

git status
git diff --check
git add README.md docs/
git commit -m "docs: clarify AIUI upload boundary"
git push -u origin docs/clarify-aiui-flow

回到 GitHub，打开 Pull requests 或点击 Compare & pull request，核对 base 和 head。PR 中要说明改了什么、为什么改、运行了什么检查、还有哪些待验证项。

图｜Fork：从原仓库进入创建副本流程（GitHub 真实页面截图，经裁切与编号标注；界面可能更新）

图｜从 Fork 到 PR 的协作关系图（蓝墨纸绘流程图或架构图；用于解释关系与边界）

维护者要求修改时，继续向同一个分支 Push，原 PR 会自动更新。不要为了每一条评论重新创建一个 PR。

五、官方 AIUI 怎么玩：从项目到 AIUI Studio

本章结果：分清官方 AIUI、AIUI Studio、眼镜真机和平台提审各自负责什么。

1. AIUI 官方参考入口

官方 AIUI 开发工具与技能仓库是 AIUI 官方仓库。它可以作为学习 AIUI 工程结构、示例、文档、设计规范和开发技能的入口。

仓库中可以重点看：

README.md / README.zh-CN.md：快速了解工具和目录；
samples/：查看可运行示例和页面能力；
documentation/：查看框架、组件、API、工具和设计资料；
skills/aiui-dev/：给开发者或 AI 编程助手参考的 AIUI 技能说明；
packages/create-aiui-agent/：了解如何从模板开始创建 Agent。

官方仓库的示例是学习入口，不等于把它直接当成你的运动应用。你仍要根据自己的运动场景、数据来源和设备权限重新定义页面与证据。

2. 用自己的项目理解 AIUI 工程结构

AIUI 应用可以先按一个清晰的项目骨架来理解：

my-aiui-agent/
├── AGENTS.md
├── app.json
├── app.js
├── pages/
│ └── index/
│ └── index.ink
├── assets/
└── README.md

AGENTS.md 说明智能体身份、能力和权限；app.json 注册页面路由；app.js 处理应用级生命周期；pages/ 存放页面；assets/ 存放确认有权使用的资源；README 解释安装、运行、测试和限制。

图｜AIUI 项目中 AGENTS.md、app.json、app.js、pages 与 assets 的职责（蓝墨纸绘流程图或架构图；用于解释关系与边界）

同一路由只选一种页面写法：可以使用单文件 index.ink，也可以使用 index.json + index.js + index.wxml + index.wxss；不要在同一路由混用两套实现。

3. 以跑步页面为例定义数据

页面应该知道“显示什么”，而不是直接解析设备字节。一个最小的运动数据契约可以这样表达：

{
"sport": "run",
"phase": "recording",
"metrics": {
"paceSecPerKm": { "value": 375, "unit": "s/km", "source": "simulated" },
"heartRateBpm": { "value": null, "unit": "bpm", "source": "unavailable" }
}
}

source 要明确区分 measured、estimated、simulated 和 unavailable。模拟数据可以帮助开发和复现，但不能写成真实设备证据；拿不到的值就显示不可用，不要用 0 或旧值冒充。

图｜从输入到页面的数据流与责任边界（蓝墨纸绘流程图或架构图；用于解释关系与边界）

4. 先在 AIUI Studio 准备，再做眼镜真机测试

把开源仓库接入 AIUI，不是再点一次“上传”，而是让同一个版本依次经过：

1. GitHub 源码与协作记录；

2. 本地项目检查和页面开发；

3. AIUI Studio 集成与程序包准备；

4. 眼镜真机测试与真实外设闭环；

5. 记录有价值的实测报告及数据；

6. AIUI Studio 的平台提审与状态记录。

图｜开源仓库接入 AIUI 的完整工作链（蓝墨纸绘流程图或架构图；用于解释关系与边界）

当前可以这样理解各工具的分工：

GitHub：保存源码、文档、Issue、PR、Actions 和 Release；
AIUI Studio：填写智能体资料、选择素材和程序包，并进入平台审核；
眼镜：验证目标设备、外设、权限、断连恢复和真实体验。

它们由版本号、Commit、AIX 校验值和证据记录连接，但不会自动互相触发。GitHub Release 不是 AIUI 上架按钮，平台资料完整也不等于“真机已通过”。

图｜GitHub、AIUI Studio、眼镜真机与平台提审四条工作链的责任边界（蓝墨纸绘流程图或架构图；用于解释关系与边界）

5. 证据怎么写才可信

项目使用 L1–L5 表示证据层级：

L1：本地自动化测试、解析器、状态机和模拟夹具；
L2：可识别 AIX、Reader 或官方 Preview，以及包身份和 SHA-256；
L3：记录版本和步骤的 AIUI Studio 集成环境验证；
L4：指定眼镜、固件、Host 和真实外设的真机闭环；
L5：按预定方案完成现场对照，含参考设备、重复样本、误差和失败规则。

每条证据至少绑定项目、运动、源码 Commit、语义版本、日期/时区、数据来源、实际命令或操作、通过/失败/跳过和待验证项。没有执行的项写 not_run，不要把计划写成结果。

图｜AIUI 证据阶梯：从自动化本地测试到完整现场对照（蓝墨纸绘流程图或架构图；用于解释关系与边界）

给 AI 助手的官方参考：修改 AIUI 项目时，优先对照 AIUI Quick Start 的目录、页面注册、运行与验证步骤。打开 AIUI 官方 Quick Start

六、如何安全参与与发布：许可、权限和边界

本章结果：确认许可证、账号权限和隐私边界后，再决定贡献或发布。

当前仓库有明确的分层许可：根层 Hub 的评测、治理、公共工具、文档和原创资产采用 Apache-2.0；apps/smartrun、apps/aibike、apps/aismartrower 的应用源码快照采用 PolyForm Noncommercial 1.0.0，商业使用需要事先取得书面许可。第三方资源和 AIX/APK/签名包还要看各自条款。

参与公共仓库不等于获得签名、上传、安装、Studio 提审或发布权限。普通贡献者按 Issue、PR 和证据流程协作；只有在自己的项目中，并且拥有源码、素材、账号、设备和发布授权时，才执行外部上传和提审。

公开前至少检查：

没有 .env、token、密钥、证书、私钥和管理员配置；
没有真实邮箱、MAC、设备序列号、精确位置、运动轨迹或健康数据；
没有未经授权的商业 SDK、固件、图片、字体、音乐或数据集；
README、LICENSE、贡献指南和安全报告入口齐全；
测试结果与 L1–L5、not_run、待验证项一致；
源码、AIX、眼镜和 Studio 的状态没有被写成同一个“已完成”。

七、用 EverMind 看懂另一种开源项目

本章结果：用“读—跑—改—证”方法观察另一个开源项目。

如果说 AIUI Sports Agents 适合用来学习“运动数据、设备验证和平台提审如何分工”，EverMind 则是另一个很适合新手观察的开源案例：它把长期记忆框架、命令行工具、Agent 插件和公开文档拆成清晰的模块，让读者能够沿着 README、Quick Start、架构说明和贡献指南逐层理解一个项目。

这里的重点不是照搬 EverMind 的技术方案，而是学习它如何把“项目是什么、怎么运行、如何接入、怎样贡献、使用什么许可”写成别人可以复现的路径。

图｜EverMind 开源案例：从项目边界、文档和许可，到 Agent 接入与复现（蓝墨纸绘示意图）

1. 先分清 EverMind 的项目边界

EverMind-AI 组织下可以先看两个公开仓库：EverOS 侧重长期记忆框架与评测；EverMe 侧重把不同 Agent 接入记忆层的 CLI 和插件。仓库之间有关联，但不是同一个目录，也不应把其中一个 README 当成另一个项目的安装说明。

EverOS：https://github.com/EverMind-AI/EverOS

EverMe：https://github.com/EverMind-AI/EverMe

2. 按“读—跑—改—证”四步学习

读：先看 README、目录结构、Quick Start、公开契约、Security 和 License，确认项目目标与不负责的内容。
跑：按照仓库给出的命令完成最小本地运行；把系统版本、依赖版本、命令和结果记下来。
改：从文档、示例或小问题开始，在自己的分支中修改，再用 Issue 或 Pull Request 说明改了什么。
证：提交前写清源码 Commit、运行日期、环境、测试结果和仍未验证的部分，不把“能运行”写成“已完成全部场景”。

3. 对 AIUI Sports Agents 的启发

EverMind 的案例提醒我们：一个好的开源项目不只是把代码放到 GitHub，还要让陌生人知道从哪里开始、哪些模块可以独立使用、哪些功能仍在演进，以及如何把一次运行变成可复核的记录。对应到 AIUI Sports Agents，可以继续坚持三点：Hub、运动应用和平台交付边界分开；README 与示例先于复杂功能；Issue、PR、测试和真机报告彼此对应。

许可也要单独确认。EverOS、EverMe 的实际授权以各自仓库当前 LICENSE 为准；本文只把它们作为“如何讲清楚开源项目”的公开案例，不代表 AIUI Sports Agents 与 EverMind 存在代码、组织或授权关系。

当你准备贡献时，可以先问自己三个问题：别人能否在十分钟内找到入口？别人能否在本地复现一个最小结果？别人能否看懂哪些结论已有数据、哪些仍待验证？这三个问题，也正是 AIUI 项目长期共建最值得借鉴的地方。