# zephyrrtos.cn 使用指南（会员版）

> 写给刚加入 zephyrrtos.cn 的会员：先过一遍「第一周清单」，十分钟内把账号、镜像和入口跑起来；后面是各项资源的完整用法。所有页面都可以从官网 https://zephyrrtos.cn/ 进入。

## 0. 你在用什么

zephyrrtos.cn 是一个围绕 Zephyr 的**中文工作组**，定位是「基于 Zephyr 生态，建立独立完整的中国驱动软件系统 + 人才纽带」，按八个方向组织：操作系统 / 系统优化 / 体系架构 / 编译器 / 行业应用 / 数据加密 / 开发工具 / AI。

会员账号就是进入这条链的钥匙。你手上的资源分这几块：

| 资源 | 入口 | 状态 |
|---|---|---|
| 自建协作平台（Gitea） | https://zephyrrtos.cn:3000 | 已上线 |
| Zephyr 国内镜像 | 一条 git 配置 → `www.zephyrrtos.cn:3000/zephyrrtos_china` | 已上线 |
| 远端开发沙盒（ROCK 5B+） | https://zephyrrtos.cn/sandbox.html | 已上线 |
| 工作组工具与插件（四件套） | https://zephyrrtos.cn/plugins.html | 已上线 |
| 动态与订阅源 | https://zephyrrtos.cn/news.html · `/feed.xml` · `/feed.json` | 已上线 |
| 智能体答疑 | https://www.chatglm.cn/main/gdetail/69992fe43e659c7211733083 | 已上线 |
| 中文资料 / 国产芯片适配仓库 / 技术分享 | 建设中，会员优先 | 建设中 |

## 1. 第一周清单

- [ ] 登录 Gitea，首次登录改密码
- [ ] 配置 SSH 公钥或访问令牌（克隆、推送与镜像都要认证）
- [ ] 配置国内镜像重定向（第 3 节）
- [ ] 跑通 `west init` / `west update`，或直接跑一键脚本
- [ ] 编译第一个样例 `samples/hello_world`
- [ ] 收藏两个入口：动态页、智能体
- [ ] （可选）装 `dsh-ubuntu-sandbox`，用上 ROCK 5B+ 沙盒
- [ ] 在 Gitea 里找到与自己对口的仓库，读一读最近的 Issue

## 2. 账号与协作平台（Gitea）

- **地址**：https://zephyrrtos.cn:3000
- **账号**：申请会员时提供的用户名；初始密码见开通邮件，**收到后立即修改**。
- **设置 SSH 公钥**：Settings → SSH Keys，添加你的公钥后即可用 `git@zephyrrtos.cn:<owner>/<repo>.git` 克隆与推送。
- **访问令牌**：Settings → Applications 生成，HTTPS 克隆时把它当密码用。

```bash
# HTTPS 克隆（需账号凭据）
git clone https://zephyrrtos.cn:3000/<owner>/<repo>.git

# SSH 克隆（需已配置公钥）
git clone git@zephyrrtos.cn:<owner>/<repo>.git
```

注意事项：

- 镜像仓库与适配类仓库是**私有**的，克隆 / 推送必须登录；Gitea 1.27 起匿名 API 一律返回 403，写脚本也别指望匿名访问。
- 凭据只放在 git credential / SSH key / 访问令牌里，不要拼进 URL、写进脚本或工程文件。
- 提问与贡献：问题提 Issue（附板子、版本、复现步骤）；适配、文档、工具改进开 PR。仓库列表见 https://zephyrrtos.cn:3000/explore/repos

## 3. Zephyr 国内镜像（west 工作流）

一条 git 配置，把 `github.com/zephyrproject-rtos/*` 整体重定向到 zephyrrtos.cn 的镜像（组织 `zephyrrtos_china`）。之后 `west init` / `west update` / 手动 `git clone` 全部走国内，命令与官方流程完全一致，不需要改工程文件。

```bash
# 1) 依赖（Ubuntu / Debian 示例）
sudo apt install --no-install-recommends git cmake ninja-build gperf ccache \
  dfu-util device-tree-compiler wget python3-dev python3-venv python3-tk \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

# 2) Python 环境 + west
python3 -m venv ~/zephyrproject/.venv
source ~/zephyrproject/.venv/bin/activate
pip install west

# 3) 启用镜像重定向
git config --global url."https://www.zephyrrtos.cn:3000/zephyrrtos_china/".insteadOf "https://github.com/zephyrproject-rtos/"
git config --global --get-regexp 'url\..*\.insteadOf'    # 确认已写入

# 4) 初始化工作区
cd ~/zephyrproject
west init .
west update

# 5) 工具链 SDK（体量大，走镜像比直连 GitHub Releases 稳）
git clone https://www.zephyrrtos.cn:3000/zephyrrtos_china/zephyr_sdk

# 6) 第一个样例
source ~/zephyrproject/.venv/bin/activate
cd ~/zephyrproject/zephyr
west build -b <your_board> samples/hello_world
```

不想逐条敲：一键脚本 https://zephyrrtos.cn/files/zephyr_cn_setup.sh （只要重定向：https://zephyrrtos.cn/files/zephyr_redirect.sh ）。

已有工程怎么切到镜像（只改单个远端、只对当前工程生效、恢复官方源、临时绕过镜像）：见 https://zephyrrtos.cn/import.html 的表格。

**排错速查**

| 现象 | 原因 / 处理 |
|---|---|
| 401 / 403 认证失败 | 账号、公钥或令牌没配好；确认 `git config --global --get-regexp url` 里的地址无误 |
| 仍从 GitHub 拉取 | `insteadOf` 未生效（看 `--get-regexp` 输出），注意子模块可能带独立配置 |
| 某个模块 404 | 该模块尚未同步到镜像，用 `west list` 核对后把缺失模块反馈给我们 |
| `west update` 中断 | 直接重跑（git 支持断点续传）；想快可 `west update --narrow -o=--depth=1` |

## 4. 远端开发沙盒（ROCK 5B+）

一台 Radxa ROCK 5B+（RK3588，8 核，15 GiB 内存，eMMC + 双 NVMe RAID1），用来跑 Zephyr 构建与调试，通过 DSH 插件 `dsh-ubuntu-sandbox` 远程使用：命令、文件读写、`cd`、后台任务都像本地一样，默认 tmux 持久会话，断线重连状态不丢。

**怎么用**

1. 装插件（三选一）：
   - 市场：DSH Desktop → Community Market 添加源 https://zephyrrtos.cn/dsh-ubuntu-sandbox/catalog-source.json
   - 命令行：`dsh plugin --profile <profile> add @hakehuang/dsh-ubuntu-sandbox@0.1.1`
   - 手工离线：见 https://zephyrrtos.cn/plugin.html
2. 前置条件：DSH ≥ 0.1.2-rc.1；目标主机写进 `~/.dsh/dsh-ssh.json`（与 `@linxin666/dsh-ssh` 共用）；远端装好 tmux。
3. 重启 DSH，确认工具列表出现 `sb_cwd` / `sb_exec` / `sb_ls` / `sb_read` / `sb_write` / `sb_session`。
4. 常用流程：`sb_cwd` 选主机与目录 → `sb_exec` 跑命令 → `sb_session` 管理持久会话。

同一台板子还有 **AMP 异构环境**（A 核 Linux + A55 core3 上的 Zephyr guest，配 A/B 双分支自回滚），见 https://zephyrrtos.cn/amp.html 。

## 5. 工作组工具与插件（四件套）

| 插件 | 一句话场景 | 安装与说明 |
|---|---|---|
| `dsh-ubuntu-sandbox` | 板子在机柜里、你想在 Windows 上写代码 —— 远端沙盒 | https://zephyrrtos.cn/plugin.html |
| `dsh-llm-router` | 一轮里规划用强模型、执行用便宜模型 | https://zephyrrtos.cn/llm-router.html |
| `dsh-compliance` | 车规 / 工业项目把 AI 代理放进流程，最怕说不清「已完成」的依据 | https://zephyrrtos.cn/compliance.html （私有 registry） |
| `dsh-handoff` | 上下文真的用尽时，把工作交接给新会话继续 | https://zephyrrtos.cn/handoff.html （私有 registry） |

总览与选择建议：https://zephyrrtos.cn/plugins.html

装插件通用的两件事（不记住必踩坑）：

- `dsh plugin` 只装依赖、**不写挂载清单** —— 装完确认 profile 的 `dsh.profile.bundles` 含包名；
- 升级或重装后**要重启 DSH**，新插件不会热加载。

## 6. 动态与订阅

- 动态页：https://zephyrrtos.cn/news.html ，每条动态有独立页面（`/news/<id>.html`），分享链接直接指向它
- 订阅：RSS https://zephyrrtos.cn/feed.xml ｜ JSON Feed https://zephyrrtos.cn/feed.json ｜ 原始数据 https://zephyrrtos.cn/news.json
- 站点信息（给脚本或智能体读取）：https://zephyrrtos.cn/info.json

## 7. 智能体答疑

智谱清言上的「工作组智能体」，内置 18 个工具，能查站点事实、分析 Kconfig / 设备树、给构建与调试指引：

- Zephyr 入门、环境搭建、镜像导入
- 沙盒与插件用法、会员信息
- 报错排查（把报错原文贴给它）

地址：https://www.chatglm.cn/main/gdetail/69992fe43e659c7211733083

日常问题优先问它（最快，不用等邮件）。

## 8. 建设中的资源（会员优先获取）

- **中文资料与教程**：环境搭建、west 工作流、Kconfig / 设备树、驱动与系统优化的中文整理
- **国产芯片适配仓库**：面向国产 MCU / 开发板的 BSP 适配与示例工程
- **技术分享与答疑**：月度技术分享、年度开发者沙龙与会员答疑通道

这些正在建设中，会员优先获取，也欢迎一起补：对上哪个方向，就在 Gitea 里提 Issue / PR 参与。

## 9. 会员期限与续费

| 项 | 说明 |
|---|---|
| 体验会员 | 3 个月免费，从开通日算起 |
| 正式会员 | 年费 RMB 200，可选；到期前提醒一次 |
| 续费方式 | 不自动续费、不强制；收到提醒邮件后回复即可 |
| 费用去向 | 服务器、域名与证书等基础设施，以及中文内容建设、国产芯片适配与工具维护的持续投入 |

## 10. 支持渠道

| 渠道 | 适合 | 地址 |
|---|---|---|
| 智能体 | 日常技术答疑（最快） | https://www.chatglm.cn/main/gdetail/69992fe43e659c7211733083 |
| Gitea Issue | 需要留痕、跟进的问题 | https://zephyrrtos.cn:3000/explore/repos |
| 邮件 | 账号、续费、企业 / 高校合作 | hakehuang@gmail.com |

## 附：常用链接速查

| 用途 | 链接 |
|---|---|
| 官网首页 | https://zephyrrtos.cn/ |
| 加入会员 | https://zephyrrtos.cn/join.html |
| 协作平台（Gitea） | https://zephyrrtos.cn:3000 |
| 镜像导入教程 | https://zephyrrtos.cn/import.html |
| 远端沙盒 | https://zephyrrtos.cn/sandbox.html |
| AMP 异构环境 | https://zephyrrtos.cn/amp.html |
| 插件总览 | https://zephyrrtos.cn/plugins.html |
| 动态 | https://zephyrrtos.cn/news.html |
| 智能体 | https://www.chatglm.cn/main/gdetail/69992fe43e659c7211733083 |