huyu-project 组织介绍
★ 这是什么:huyu-project 是 Huyu / HuyuOS 项目的代码组织。
本文件说明组织里有哪些仓库、每个仓库干什么。
★ 数据实测于 2026-10-08(批次 HY/HZ 整改后)。★★ 本文的"规模/文件数"是快照、会变
⇒ 引用前用命令重测(文末附全部判据命令)。★ 这是本项目的既定纪律:「计数不复制」。
一、一句话:这个组织在做什么
★ 自研一套系统编程语言(Huyu),再用它做一个操作系统(HuyuOS) ——
并且做到自举:用 Huyu 自己写编译器的一部分,再用这个编译器编译它们,跑在内核里验证。
★ 为什么值得做:语言和操作系统是同一个人从零做的 ⇒ 两者可以互相为对方设计
(内核不需要迁就外部语言的运行时,语言也不需要对内核做特殊妥协)。
★ 技术上最硬的一件事:hyc 把汇编器 hyas 与链接器 hyld 的源码直接编进自己
⇒ 一个二进制里装着完整的编译链(见 huyu-core/huyu)。
二、组织总览(15 个仓)
★ 分四层:治理 / 工具链 / 操作系统 / 基础设施。
★ 命令 find . -name .git -maxdepth 6 -not -path "*/.git/*" 实测 15 个 git 根。
| 层 |
仓 |
一句话职能 |
| 治理 |
meta |
跨仓治理资产(台账/纪律/总纲/本文件) |
| 治理 |
docs |
全部设计、验证、构建文档 |
| 工具链 |
huyu-core/huyu |
★ 编译器 hyc + 8 个后端工具(最大仓) |
| 工具链 |
huyu-core/bootstrap |
★ 自举链(用 Huyu 写的编译器各阶段) |
| 工具链 |
huyu-core/std |
语言标准库 |
| 工具链 |
huyu-core/rt |
运行时(字符串/动态数组的底层) |
| 工具链 |
huyu-core/abi |
★ 跨仓中立契约头(跨仓接口唯一真相源) |
| 工具链 |
huyu-core/rfcs |
架构决策记录(RFC) |
| 工具链 |
huyu-core/book |
语言书稿(面向学习者) |
| 操作系统 |
huyu-os/kernel |
★ 内核(含引导/内存/中断/系统调用/驱动/文件系统/网络/进程) |
| 操作系统 |
huyu-os/sdk |
SDK + 容器运行时 |
| 操作系统 |
huyu-os/devices |
设备与图形栈 |
| 基础设施 |
huyu-infra/build |
构建系统(hybuild) |
| 基础设施 |
huyu-infra/ci |
★ CI 管线 + 机械守卫群(★ 个数刻意不写死 —— 实测口径 find huyu-infra/ci/checks -name 'check_*.py';check_guard_wiring 的 W14 钉住 ci/README.md 记录行的计数。本品曾写 33,后改 35,两次漂移后改为不写死) |
| 基础设施 |
huyu-infra/testsuite |
测试套件 + ★ 公共测试框架
|
三、各仓详解(逐个说明职能)
3.1 治理层(2 个)
meta —— 跨仓治理资产
| 项 |
内容 |
| 是什么 |
★ 只装「跨工作区」的治理资产,不含任何业务代码
|
| 语言 |
Markdown |
| 规模 |
128 个文件(2026-10-08 快照;★ 会变,以 git -C meta ls-files | wc -l 为准) |
| 关键文件 |
PROJECT_MAP.md(项目地图/接手起点)· TASK_LOG.md + TASK_LOG/(任务全量明细,按月分片)· WORK_DISCIPLINE_AND_SKILLS.md(唯一操作入口,任务前必读)· README.md(工作区总入口)· REDESIGN_IMPLEMENTATION.md(组织重组基线)· ORGANIZATION.md(本文件) |
| 为什么独立成仓 |
★ 这些资产不属于任何单个业务仓(它们是"跨仓"的)。2026-10-08 批次 HY 从原「工作区根仓」拆出 |
| 远端 |
git@gitee.com:huyu-project/meta.git |
docs —— 设计与验证文档
| 项 |
内容 |
| 是什么 |
★ 全部设计 / 验证 / 构建文档的权威仓 |
| 语言 |
Markdown(+ 少量脚本) |
| 关键内容 |
HUYUOS_ARCHITECTURE_LEGO.md(架构完全指南)· MCB_FORMAL_VERIFICATION.md(内核编译期形式化验证计划)· BRICK_ASSEMBLY_IMPLEMENTATION.md(砖装配 + ★ 缺陷编号唯一登记处)· INVARIANT_IDS.md(不变量 ID 单一真相源)· HUYU_BUILD_FLOW.md(★ 构建总说明书)· docs/archive/HUYU_ANALYSIS_2026-10-02.md(全维度分析报告)· 零基础教程 tutorial/
|
| 远端 |
git@gitee.com:huyu-project/docs.git |
3.2 工具链层(7 个,huyu-core/ 下)
huyu-core/huyu —— 编译器与后端工具 ★ 最大仓
| 项 |
内容 |
| 是什么 |
★ hyc 编译器 + 8 个后端工具 + 工具链测试 |
| 语言 |
C++(717 个文件 / 187,327 行级别的主力) |
| 规模 |
236 文件 / 81,786 行(compiler 46,439 + tools 33,209) |
| 8 个工具 |
hyas(汇编器)· hyld(链接器)· hyar(打包)· hynm(符号表)· hyobjdump(反汇编)· hydebug(调试器)· hyprof(性能)· hykpkg(★ 砖装配器) |
| ★ 关键设计 |
hyc 把 hyas/hyld 的源码直接编进自己(compiler/frontend/Makefile 的 HYC_SRCS)⇒ 无进程隔离,但也没有重复实现 |
| 远端 |
git@gitee.com:huyu-project/huyu.git |
huyu-core/bootstrap —— 自举链 ★ 最特别的仓
| 项 |
内容 |
| 是什么 |
★ 用 Huyu 语言写的编译器各阶段(自举链):hylexer hyparser hytypeck hyhirgen hycodegen + hyanalyze hyformat hyregistry
|
| 语言 |
★ 主要是 Huyu(.hyu):62 个文件 / 19,300 行 + 3 个工具的 C++ 版 |
| 规模 |
118 文件 / 27,855 行 |
| ★ 为什么重要 |
这些 .hyu 源码被 hyc 编译成 ELF 固件、嵌进内核、在 QEMU 里运行 ⇒ 运行成功 = 自举成功(工程上最硬的证明) |
| 实测证据 |
QEMU 串口输出五个 ALL PASSED(HYC-L/P/T/H/C,全 result=0) |
| 远端 |
git@gitee.com:huyu-project/bootstrap.git |
huyu-core/std —— 语言标准库
| 项 |
内容 |
| 是什么 |
Huyu 语言的标准库(容器 / 字符串 / 网络等基础能力) |
| 规模 |
36 文件 / 7,486 行 |
| 远端 |
git@gitee.com:huyu-project/std.git |
huyu-core/rt —— 运行时
| 项 |
内容 |
| 是什么 |
★ 运行时库 hy_std_rt —— 字符串 / 动态数组的底层实现(类比 libc) |
| 规模 |
15 文件 / 2,571 行 |
| ★ 为什么独立 |
它是所有编译产物都要链接的东西 ⇒ 必须单一真相源(有守卫 check_hy_std_rt_single_source 盯着) |
| 产物 |
build/hy_std_rt.o(实测 21,328 字节),编译时用 --rt 指定 |
| 远端 |
git@gitee.com:huyu-project/rt.git |
huyu-core/abi —— 跨仓契约头 ★ 架构关键
| 项 |
内容 |
| 是什么 |
★ 跨仓中立契约头(huyu/*_iface.h)—— 跨仓接口的唯一真相源
|
| 规模 |
84 文件 / 13,833 行 |
| ★ 规则(已拍板) |
跨仓消费(≥2 个 git 仓 include 它)⇒ 必须放本仓 headers/;单仓消费 ⇒ 留在本仓 include/huyu/;单仓却在 abi ⇒ 必须在守卫里显式登记 |
| 为什么要这条规则 |
★ 让 kernel 保持「可以独立构建」(不必先拉 abi 仓)—— 强行合并会让它背上硬依赖
|
| 远端 |
git@gitee.com:huyu-project/abi.git |
huyu-core/rfcs —— 架构决策记录
| 项 |
内容 |
| 是什么 |
RFC(Request for Comments)= 架构决策记录 |
| 规模 |
6 个文件(README.md / 模板 / RFC-0000 / RFC-0001-architecture-baseline / RFC-0002-route-and-governance) |
| ★ 诚实说明 |
目前只有 3 篇 ⇒ ★ 规模很小;但它是「决策历史」,与 docs 的「现状文档」性质不同,故独立成仓。观察条件:若长期不增长,应重估是否合并进 docs
|
| 远端 |
git@gitee.com:huyu-project/rfcs.git |
huyu-core/book —— 语言书稿
| 项 |
内容 |
| 是什么 |
面向学习者的书稿(学习路径 / 语言教程) |
| 规模 |
38 个文件(纯文档) |
★ 与 docs 的分工 |
book 是「想学」时读;docs 是「想查」时读 |
| 远端 |
git@gitee.com:huyu-project/book.git |
3.3 操作系统层(3 个,huyu-os/ 下)
huyu-os/kernel —— 内核 ★ 文件数最多
| 项 |
内容 |
| 是什么 |
★ HuyuOS 内核:引导 / 内存管理 / 中断 / 系统调用 / 驱动 / 文件系统 / 网络 / 进程 |
| 语言 |
C++(+ 少量 C、asm、.hyu 固件) |
| 规模 |
★ 461 个文件 / ≈45,400 行(文件数全场最多) |
| 内部结构 |
core/(199 文件;含 arch boot interrupt memory syscall)· drivers/(37)· fs/(28)· net/(10)· process/(19)· elf/(7)· bricks/(4,砖装配层) |
| ★ 关键设计 |
乐高式砖装配:38 块砖(core 5 / boot 29 / runtime 4)由 hykpkg 按 bricks/*.brick 的 requires 算出拓扑序再装配 |
| ★ 形式化验证 |
MCB(微内核核心)性质用 constexpr + static_assert 编译期证明(V1–V6 已落地:context switch / CR3 / syscall / Buddy / IRQ dispatch / APIC namespace) |
| 远端 |
git@gitee.com:huyu-project/kernel.git |
huyu-os/sdk —— SDK 与容器运行时
| 项 |
内容 |
| 是什么 |
面向应用的 SDK + 容器运行时
|
| 规模 |
13 文件 / 2,542 行 |
| 远端 |
git@gitee.com:huyu-project/sdk.git |
huyu-os/devices —— 设备与图形栈
| 项 |
内容 |
| 是什么 |
设备驱动接口 + 图形栈(含合成器 compositor) |
| 规模 |
42 文件 / 10,487 行 |
| 远端 |
git@gitee.com:huyu-project/devices.git |
3.4 基础设施层(3 个,huyu-infra/ 下)
huyu-infra/build —— 构建系统
| 项 |
内容 |
| 是什么 |
构建系统 hybuild(含 huyu.build 清单格式 + schema) |
| 规模 |
32 文件 / 4,361 行 |
| ★ 也是公共库的 provider |
sha256.cpp 在此仓,被构建系统与 hyc 两处消费(★ 「一个源文件被多个 Makefile 引用」的范例) |
| 远端 |
git@gitee.com:huyu-project/build.git |
huyu-infra/ci —— CI 管线与守卫 ★ 项目纪律的执行者
| 项 |
内容 |
| 是什么 |
★ CI 管线(run_pipeline.sh)+ 机械守卫群(★ 个数不写死 —— 以 huyu-infra/ci/checks/check_*.py 实测为准,由 check_guard_wiring 的 W14 钉住记录行计数) |
| 语言 |
Python(+ Shell) |
| 规模 |
42 文件 / 16,932 行(2026-10-08 快照;含新增的 check_remote_convention.py) |
| ★ 守卫在干什么 |
把「文档与代码一致」变成机器可判:单一真相源(7 个)、文档体积/表格/行号锚点、缺陷号唯一性、台账分片一致性、管线仓射程… |
| ★ 为什么重要 |
本项目的核心纪律是「同一事实只能存一处,且要有判据盯着」⇒ 守卫就是这个纪律的物理实现
|
| 车道 |
lane.sh quick(20s)/ doc(83s)/ build(55s)/ selfhost(30s)/ full(13–24min) |
| 远端 |
git@gitee.com:huyu-project/ci.git |
huyu-infra/testsuite —— 测试套件 + ★ 公共测试框架
| 项 |
内容 |
| 是什么 |
工具链测试 + 平台测试 + scratch(临时试验场) |
| 规模 |
17 文件 / 2,144 行 |
| ★★ 隐藏身份 |
toolchain_tests/unit/test_runner.h(123 行)是全项目工具测试的公共框架 —— 实测被 70 处引用(37 处 include 路径 + 31 处显式依赖)。★ 它是事实上的公共库
|
| ★ 已知待办 |
它未登记为公共库、也没有守卫(而同目录的 test_peak_rss.h 却有守卫)⇒ 已登记为缺陷 #202 同族,待处置 |
| 远端 |
git@gitee.com:huyu-project/testsuite.git |
四、四层之间的依赖关系
┌───────────────── 治理层 ─────────────────┐
│ meta(台账/纪律/总纲) docs(设计/验证) │
└────────┬──────────────────────┬───────────┘
│ 治理、记录 │ 描述
↓ ↓
┌────────── 工具链层 huyu-core/ ──────────┐ ┌── 操作系统层 huyu-os/ ──┐
│ huyu(hyc + 8 工具)← 依赖 abi 契约头 │ │ kernel ← 依赖 abi 契约头 │
│ bootstrap(自举 .hyu) │ │ devices / sdk │
│ std / rt(库与运行时) │ └──────────┬──────────────┘
└──────────────┬──────────────────────────┘ │
│ 产物(hyc / .o / 固件) │
└──────────────→ 喂给内核 ←───────────────┘
↑
┌──────── 基础设施层 huyu-infra/ ────────┐
│ build(构建系统) ci(守卫) testsuite(测试)│
└───────────────────────────────────────┘
★ 跨仓依赖的现状(诚实):目前靠 Makefile 里的相对路径(如 -I../../../../huyu-core/abi)
⇒ ★ 没有集中声明。实测被引用最多的是 huyu-infra/testsuite(70 次)与 huyu-core/abi(56 次)。
★ 对比:内核的砖依赖用 bricks/*.brick 的 requires { brick "..." } 显式声明
⇒ ★ 同一个项目里,"砖"有显式声明,"Makefile 跨仓"没有(已登记为待改进项)。
五、远端与协作约定
| 项 |
约定 |
| 托管 |
Gitee |
| 组织 |
huyu-project |
| 地址格式 |
git@gitee.com:huyu-project/<仓名>.git |
| 仓名 |
与本地目录名一致(如 huyu-core/kernel ⇒ huyu-project/kernel) |
| 分支 |
main |
| 提交 |
各仓独立提交(不用 submodule 聚合)· 提交 message 用中文 + Conventional 风格 + 批次标签
|
| 推送 |
★ 需显式授权(不自动推) |
★ 核对命令:
for p in meta docs huyu-core/* huyu-infra/* huyu-os/*; do
[ -d "$p/.git" ] && printf "%-24s %s\n" "$p" "$(git -C $p remote get-url origin 2>/dev/null)"
done
★ 退役仓的归档:原「工作区根仓」已归档为裸仓
/Volumes/Data/huyu-archive/root-repo.git(含 281 提交历史,封存 tag archive-root-final-2026-10-08)。
六、上手路径(我是谁 → 从哪开始)
| 你是 |
从哪开始 |
| 完全不懂编程 |
docs/tutorial/README.md(零基础教程 4 课 + 速查表) |
| 想了解整体 |
meta/README.md(总入口)→ 本文件 → meta/PROJECT_MAP.md
|
| 想改编译器 |
docs/HUYU_BUILD_FLOW.md(构建说明书)→ huyu-core/huyu/README.md
|
| 想改内核 |
docs/HUYUOS_ARCHITECTURE_LEGO.md(乐高架构)→ huyu-os/kernel/README.md
|
| 想查缺陷/进度 |
docs/BRICK_ASSEMBLY_IMPLEMENTATION.md(缺陷登记处)· meta/TASK_LOG/
|
| 想知道规则 |
meta/WORK_DISCIPLINE_AND_SKILLS.md(★ 唯一操作入口) |
附:本文数字的实测命令
cd /Volumes/Data/huyunew
# 仓数与仓名
find . -name .git -maxdepth 6 -not -path "*/.git/*" | sed 's|/.git$||' | sort
# 各仓规模
for d in meta docs huyu-core/huyu huyu-os/kernel; do
echo "$d: $(git -C $d ls-files | wc -l) 文件"
done
# 语言分布
for ext in cpp h hyu py sh md; do
echo ".$ext: $(find . -name "*.$ext" -not -path "*/.git/*" | wc -l) 个"
done
# 跨仓依赖排名
grep -rhoE '\.\./\.\./\.\.?/?[a-z-]+/[a-z-]+' --include="Makefile" . | sort | uniq -c | sort -rn | head
# 远端
for p in meta docs huyu-core/*; do git -C "$p" remote get-url origin 2>/dev/null; done