2026-09-16 21:13:31 +08:00
|
|
|
|
# 00 · 文档索引（先看这份）
|
|
|
|
|
|
|
|
|
|
|
|
> 这套东西是**底座**：引导器 → 内核 → 驱动 → 程序(Skill，v0.2 占位)。
|
|
|
|
|
|
> 后面所有开发都长在它上面，所以文档按"用的人"分两组：**使用**（把驱动写出来跑起来）和
|
|
|
|
|
|
> **开发**（改底座本身）。每份文档只解决一类问题，写错的地方以**代码**为准。
|
|
|
|
|
|
|
|
|
|
|
|
## 30 秒概念速查（先记住这 8 条）
|
|
|
|
|
|
|
|
|
|
|
|
| 概念 | 一句话 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| 引导器 `UEFI.boot.py` | 内核的管家：体检环境 / 管内核进程的启停与记账；纯 stdlib，坏了也能报出为什么 |
|
|
|
|
|
|
| 内核 `内核/内核.py` | 常驻**总调度**：谁给谁、什么顺序、谁先谁后，全归它；纯 CLI + 日志，没有 TUI |
|
|
|
|
|
|
| 驱动 | **一个文件夹**：根目录有 `配置.efi.json` 才算；里面是源码 + venv 或可执行文件 |
|
|
|
|
|
|
| 契约 | 中立的能力名（如 `样板:心跳`）。驱动只声明"我产出什么 / 我要什么"，**不写对方名字** |
|
|
|
|
|
|
| 内存 | PostgreSQL 库 `efi_kernel`（8 张表）。`events` 表就是总线，**没有自造协议、没有 socket** |
|
|
|
|
|
|
| 两个真相 | PG 是活真相；驱动文件夹里的 `运行.efi.json` 是落盘快照（离线可读，不当状态源） |
|
|
|
|
|
|
| 三条日志道 | `内核.log`（结构化）/ `内核.out.log`（命令输出+崩溃原文）/ `引导器.log`；驱动日志各自一份 |
|
|
|
|
|
|
| 内核可以随时死 | 崩了不连累驱动（它们是独立会话）；下次启动先**收尸**认领回来 |
|
|
|
|
|
|
|
|
|
|
|
|
## 文档地图
|
|
|
|
|
|
|
|
|
|
|
|
| # | 文件 | 解决什么问题 | 什么时候看 |
|
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
| 01 | `01-快速上手.md` | 从零把整套跑起来（体检 → 建库 → 起内核 → 起驱动 → 收工） | 第一次接触 / 换机器 / 重装 |
|
|
|
|
|
|
| 02 | `02-写一个驱动.md` | 亲手写一个驱动：文件夹怎么摆、配置怎么写、怎么要别人的东西、怎么汇报 | 要加能力的时候 |
|
|
|
|
|
|
| 03 | `03-命令手册.md` | 每条命令、每个选项、退出码、`--json` 输出长什么样 | 天天用（贴在旁边） |
|
|
|
|
|
|
| 04 | `04-契约与调用.md` | 驱动之间的"牵线"机制：一次调用的完整生命周期 + 六条仲裁 | 驱动要调别人、调用被拒 |
|
|
|
|
|
|
| 05 | `05-日志与排障.md` | 三条日志道怎么读；"出事了先查哪"的症状表 | 出事的时候 |
|
|
|
|
|
|
| 06 | `06-架构与不变量.md` | 分层、必须守住的不变量、数据流、为什么没有协议/TUI | 动手改底座前**必读** |
|
|
|
|
|
|
| 07 | `07-模块与接口.md` | 每个文件管什么、公开函数表、"想改 X 要动哪几处" | 改底座的时候 |
|
|
|
|
|
|
| 08 | `08-数据模型.md` | 8 张表逐字段（谁写/谁读/生命周期）+ 事件字典 + 状态机 + 快照字段 | 写 SQL / 加字段 / 排查数据 |
|
|
|
|
|
|
| 09 | `09-扩展指南.md` | 六个 recipe：加子命令 / 加配置字段 / 加表 / 加日志来源 / 加自测 / 改判定 | 扩展底座的时候 |
|
|
|
|
|
|
| 10 | `10-验收与质量门.md` | 五份自测 + pyright 严格档 + AST 等价 + 端到端；发布前 checklist + 坑总表 | 每次改完代码 |
|
|
|
|
|
|
|
|
|
|
|
|
**设计档案**（为什么这么设计、字段表原文）在 `设计/`：`01-驱动规范.md`（配置字段表 / 校验 9 条 / 状态机）、
|
|
|
|
|
|
`02-内核设计.md`（DDL / 判定表 / CLI）、`03-引导器.md`（体检 6 项 / 台账）、`04-日志系统.md`（三条道 / 轮转 / 选项）。
|
|
|
|
|
|
老板自己写的原始需求在 `内核/内核设计.md`（**只读，别改**）。
|
|
|
|
|
|
|
|
|
|
|
|
## 三条命令跑起来
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
cd ~/桌面/工作区/内核
|
|
|
|
|
|
python3 UEFI.boot.py --check # 1 体检 6 项（PG 不通只 WARN，不算失败）
|
|
|
|
|
|
python3 UEFI.boot.py 内核 启动 --守护 # 2 后台常驻总调度
|
|
|
|
|
|
./.venv/bin/python 内核/内核.py 启动 样板常驻 # 3 起一个驱动
|
|
|
|
|
|
./.venv/bin/python 内核/内核.py 日志 样板常驻 -n 20 # 看它说话
|
|
|
|
|
|
python3 UEFI.boot.py 内核 停止 ; ./.venv/bin/python 内核/内核.py 停止 样板常驻 # 收工
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 事实源优先级
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
代码 > 设计/*.md > 文档/*.md > 技能 / 记忆
|
|
|
|
|
|
```
|
|
|
|
|
|
文档跟代码打架 → 以代码为准，并**当场把文档改掉**（底座文档一旦漂移，后面每个开发都踩一遍）。
|
|
|
|
|
|
改完代码的同步清单见 `09-扩展指南.md` 末尾。
|
2026-09-16 21:22:40 +08:00
|
|
|
|
|
|
|
|
|
|
## 许可
|
|
|
|
|
|
|
|
|
|
|
|
**GNU General Public License v3.0（GPL-3.0）** —— 全文见项目根 `LICENSE`。
|
|
|
|
|
|
版权 © 2026 Collaplex 克拉普莱克斯工作室。
|
|
|
|
|
|
|
|
|
|
|
|
一句话说清它管什么：**可以商用**（自己用、卖服务、随便改都行），但**对外分发或发布衍生作品时，必须同样以
|
|
|
|
|
|
GPL-3.0 开放源码**。这正是它跟 MIT 的区别（MIT 允许别人拿走直接闭源）。**内部自用不受任何约束**，
|
|
|
|
|
|
别人想把它嵌进闭源产品里卖 —— 那必须开源他们改的部分。
|
|
|
|
|
|
|
