lou
53e7d1e5f2
文档/ (2026-09-16; 老板定调: 这是 agent 底座, 所以必须扎实, 现在越扎实以后开发越简单)
00-索引 文档地图 + 30 秒概念速查 + 三条命令跑起来 + 事实源优先级
01-快速上手 体检 -> 建库 -> 起内核 -> 起驱动 -> 收工, 全带实测输出; 第一次最易踩的四个坑
02-写一个驱动 五分钟最小驱动 / 形态选择 / 能碰哪些表 / 汇报与调用两份模板 / 交付检查表
03-命令手册 两层每条命令 + 日志选项 + 退出码约定 + --json 样例 + 日常十条
04-契约与调用 一次调用的完整生命周期 / 六条仲裁 / 锁与按需拉起 / 排障表
05-日志与排障 三条道怎么读 + "症状->判据->处置"总表 + 断电收尸语义
06-架构与不变量 分层 / 14 条硬不变量 / 主流程表 / 双真相 / 为什么故意不做 / 已知薄弱点
07-模块与接口 逐模块职责与公开接口 + "想改 X -> 动哪几处"连带清单
08-数据模型 8 张表逐字段 (谁写谁读) + events.kind 字典 + 状态机 + 快照 + 排查 SQL
09-扩展指南 六个配方 (加子命令/加字段/加表/加日志来源/加自测/改判定) + 同步清单
10-验收与质量门 四道门 + 五份自测明细 + pyright 严格档 + 26 条已知坑总表 + 发布 checklist
规矩: 不重复设计文档 / 每条命令实测过再写 (含 jq 表达式) / 代码>设计>文档 的事实源优先级 /
改代码必须同步文档 (清单在 09 末尾) / 暂时没做到的事写成"已知边界"不含糊过去
修复: 同锁串行化原来是死的 (实测抓到的真缺陷)
旧行为: db.领调用 只领 pending (waiting 没人再碰) + db.同锁在跑 把 waiting 也算"占着锁"
-> 同一把锁上两条请求互相排队, 双双停在 waiting 谁也不跑 (实测 id 16/17);
而 收权超时 只收 running -> 排队连超时都没有 = 死锁
修法: ① db.领调用 的 SQL 改 state IN ('pending','waiting') -- 每轮把排队的领回来重判, 锁一空就推进
② db.同锁在跑 只认 state='running' (排队的还没拿到锁, 不挡人)
③ 内核.转发调用 waiting 分支补 deadline (排队也立期限); 内核.收权超时 遍历 running + waiting
④ 抽出 内核.期限文本() 统一算 deadline
实测: 两条同锁调用串行跑完 (19.started_at == 18.finished_at); 排队者超时被收权 (events 有记录)
回归: 自测db.py 调用组 +4 条断言 (waiting 不算占着锁 / waiting 会被重新领 / ...);
去掉一条依赖生产库全局计数的脆弱断言
其它: 内核 与 引导器 的 用法() 末尾加文档指引
验收: uvx pyright 0 errors / 0 warnings; 五份自测全过 (进程/内核 58/配置/db/日志 86);
试跑引导器.py PASS 11 / FAIL 0 / 残留无; 残留进程 0
4.1 KiB
4.1 KiB
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（只读，别改）。
三条命令跑起来
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 末尾。