efi-kernel/README.md

# 内核（efi-kernel）

**用户级虚拟 OS 底座**：UEFI 引导器 → 内核 → 驱动 → 程序(Skill)。
不是玩具 OS —— 它把"一台机器上的软件"按内核/驱动/进程那套语义重新组织：**引导器管环境与内核进程，
内核常驻调度驱动，驱动只声明契约、互不相识**。

三条定调：**纯 CLI + 日志**（没有 TUI）/ **PostgreSQL 当内存**（不引入 socket、消息队列、私有协议）/
**一个文件只装一种内容**（日志三条道、快照、配置各归各的）。

## 是什么

| 层 | 位置 | 管什么 |
|---|---|---|
| 引导器 | `UEFI.boot.py` | 体检 6 项 / venv / 包台账 / 内核进程启停记账 / 参数原样透传 |
| 内核 | `内核/` | 常驻总调度：命令消费、驱动契约仲裁（六条）、依赖链巡检、收尸、独一份调度锁 |
| 驱动 | `驱动/<名>/` | **一个文件夹 = 一个驱动**（根目录有 `配置.efi.json` 才认）；只经 PG 表与外界说话 |
| 程序(Skill) | 驱动内的 `技能/*.json` | 声明式、模型驱动，**归驱动管**（内核不掺和）；只列不执行的样例 `驱动/样板技能/`，真跑一遍的样例 `驱动/技能执行/`，规范 `设计/05` |

驱动之间**零耦合**：不 import、不互调、配置里也不写对方名字 —— 只声明"我要什么 / 我产出什么"（契约名），
谁给、什么顺序、怎么送达全归内核。

## 要求

Python **3.11+**、PostgreSQL（本机 18，库 `efi_kernel`）。其余零依赖：核心代码纯标准库，
只有驱动侧汇报用得上 `psycopg2`。

## 快速开始

```bash
python3 UEFI.boot.py --check                    # 体检 6 项 (解释器 / venv / 包 / 驱动目录 / PG)
python3 UEFI.boot.py 内核 启动 --守护            # 起内核 (常驻)
./.venv/bin/python 内核/内核.py 状态             # 看驱动清单与状态
./.venv/bin/python 内核/内核.py 启动 样板常驻     # 起一个驱动
./.venv/bin/python 内核/内核.py 日志 样板常驻 -f   # 跟它的日志
python3 UEFI.boot.py 内核 停止                   # 收工 (驱动不动, 下次启动会认领)
```

## 仓库结构

| 路径 | 内容 |
|---|---|
| `UEFI.boot.py` | 引导器（纯 stdlib，唯一入口） |
| `内核/` | 内核本体：`内核.py` 常驻调度 + `扫描.py` 校验契约 + `状态.py` 状态机快照 + `db.py`（**唯一碰 SQL**）+ `进程.py` + `日志.py` + `文本.py` |
| `内核/自测*.py` | 五份**真机**自测（进程 / 内核 / 配置 / db / 日志） |
| `试跑引导器.py` | 端到端验收（11 项，含残留检查） |
| `驱动/` | 五个：`Json解码`(oneshot，提供 `Json解码:解析`) / `样板常驻`(resident + 提供服务) / `样例消费器`(消费契约) / `样板技能`(skill 归驱动管，main+small 两档，只列不执行) / `技能执行`(**示例驱动**：把 skill 真跑一遍 —— 选模型 / 拼 prompt / 校验输出) |
| `设计/` | 设计档案 `01-驱动规范` ~ `05-技能规范`（字段表、DDL、判定表的原文在这里） |
| `文档/` | 使用与开发文档 `00-索引` ~ `10-验收与质量门` |
| `归档/` | 修前的证据存档（如日志系统重做前的原始 `内核.log`） |

## 验收（四道门，改完必过）

```bash
uvx --from pyright pyright     # 门 1: 严格档 -> 0 errors / 0 warnings
for t in 自测进程 自测内核 自测配置 自测db 自测日志; do ./.venv/bin/python 内核/$t.py; done   # 门 2
python3 内核/自测AST等价.py <改前备份> <文件>    # 门 3: 只改注释时证明逻辑零动
python3 试跑引导器.py           # 门 4: PASS 11 | FAIL 0 | 残留: 无
```

自测**不 mock**：真起进程、真写库、真轮转 6MB 日志文件（跑完核对 8 张表行数与开跑前一致）。

## 文档

**入口 → [`文档/00-索引.md`](文档/00-索引.md)**（文档地图 + 30 秒概念速查）

- 用起来：`01-快速上手` / `02-写一个驱动` / `03-命令手册` / `04-契约与调用` / `05-日志与排障`
- 改底座：`06-架构与不变量` / `07-模块与接口` / `08-数据模型` / `09-扩展指南` / `10-验收与质量门`

事实源优先级：**代码 > `设计/` > `文档/` > 技能/记忆**；文档跟代码打架，以代码为准并当场改文档。

## 许可

**GNU General Public License v3.0（GPL-3.0）** —— 全文见 [`LICENSE`](LICENSE)。

可以商用（自己用、卖服务、随便改）；**对外分发或发布衍生作品时，必须同样以 GPL-3.0 开放源码**；
内部自用不受任何约束。版权 © 2026 Collaplex 克拉普莱克斯工作室。