Files

T

lou 8fd8c8411e 加"样板技能"驱动: skill 归驱动管的样例 (主模型 / 小模型两档)

老板口径 (2026-09-16): skill 可以写个示例, 但 skill 是归驱动管的, 所以只要样例就行, 分主模型和小模型 skill.

驱动/样板技能/  (第 4 个样板驱动)
  配置.efi.json            oneshot / interpreter system / 无契约
  技能.py                  只列不执行: 把自带的 skill 读出来打印 (档次 / 步骤数 / 样例数 / 边界数)
  技能/请求解析-主模型.json  tier=main    步骤 3 (抽象, 规划权交给模型) / 样例 1 / 边界 3
  技能/请求解析-小模型.json  tier=small   步骤 5 (编号写死, 每步一个判据) / 样例 3 (含 2 条反例) / 边界 4

口径
  内核不认识 skill (只管确定性代码能力的接入与仲裁); 读它 / 选模型 / 拼 prompt / 校验输出 / 重试 全归驱动
  同一件事写两份: main 靠模型规划 / small 靠结构稳 (args 键白名单 + confidence 只许 0/0.5/1 + 反例 few-shot)
  样例任务选"把一句话解析成 calls 的 want+args" -- 正是底座里主模型(规划多步)与小模型(填固定结构)的真实分工

设计/05-技能规范.md (新): 归谁管 / 字段表 12 项 / 两档对照 / 版本边界(v0.1 不做加载器·选模型·校验·重试) / 连带清单
文档同步: README(程序(Skill) 行 + 驱动清单 3->4 + 设计档案 01~05) / 文档02(新增"驱动可以带 skill"节, 原第 8 节顺移为 9) /
         文档06(分层表那条) / 文档07(依赖图加技能声明一行) / 文档01(驱动列表快照补第 4 行) / 设计01(第 7 节指向 设计/05)

验收: 扫描 驱动 4 / 有效 4 / 运行 0; 启动 样板技能 -> oneshot 退出码 0, 日志里两档 skill 都列出来;
      uvx pyright 0 errors / 0 warnings (新驱动代码过严格档; json.loads 收窄成 dict[Unknown,Unknown] 那处用 cast 修掉);
      五份自测全过; 试跑引导器 PASS 11 / FAIL 0 / 残留无

2026-09-16 21:37:25 +08:00

8.6 KiB

Raw Permalink Blame History

01 · 快速上手（从零到跑起来）

目标：一台装好 Python 3.11+ 和 PostgreSQL 的 Linux 上，10 分钟内让引导器 + 内核 + 一个驱动 真跑起来，并且每一步都能看见证据。所有输出都是 2026-09-16 在本机实测的原样。

0. 前置条件（本机已经满足的）

项	本机现状	怎么自查
项目根	`~/桌面/工作区/内核/`	`ls` 应看到 `UEFI.boot.py` / `内核/` / `驱动/` / `环境.efi.json`
Python	3.11.15（`.venv` 里跑；3.14 那个只是系统备着）	`./.venv/bin/python -V`
uv	有（建 venv / 装包用）	`uv --version`
PostgreSQL	18，数据目录 `/home/lou/pgdata`，socket `/home/lou/pgdata/socket`，用户 `lou`	`psql -h /home/lou/pgdata/socket -l`
库 `efi_kernel`	已建（8 张表由内核 `CREATE TABLE IF NOT EXISTS` 自动建）	`psql -h /home/lou/pgdata/socket -d efi_kernel -c '\dt'`

PG 连接信息只写在 环境.efi.json 的 db 段（name/host/port/user）。host 填 unix socket 目录 不是主机名 —— 本机 PG 走 peer 认证，写 localhost:5432 反而要密码。

1. 体检（永远先跑这条）

cd ~/桌面/工作区/内核
python3 UEFI.boot.py --check

输出（全绿时）：

体检通过: 解释器 3.11.15 | venv 健康 | 包 2/2 | 驱动目录 可写 | PG 通

六项的阻塞级别记牢，这决定了"出问题还能不能干活"：

#	检查	过不了会怎样
1	解释器版本满足 `环境.efi.json` 的 `python`	阻塞（内核跑不起来）
2	`.venv` 存在	阻塞
3	`.venv` 健康（`pyvenv.cfg` 与实际解释器一致、能 import）	阻塞
4	包状态（只有必需包缺失才阻塞，可选包缺失写进详情）	阻塞
5	驱动目录可读写	阻塞
6	PG 能连	只 WARN —— 引导器自己的命令（体检/环境/包）要能在 PG 挂了时照样报出原因

有阻塞项时它会把整张表打出来，每行带一句修复命令：

$ python3 UEFI.boot.py --check
序号  检查          结果  必需  详情                                              修复
────  ────────────  ────  ────  ────────────────────────────────────────────────  ──────────
1     解释器版本    过    是    用 /…/.venv/bin/python = 3.11.15 (要求 >=3.11)
…

不自动修、不自动装、不自动升级 —— 引导器只报，动手要你显式敲（下面两条）。

2. 修环境（只在需要时）

python3 UEFI.boot.py 环境 重建      # 按 环境.efi.json 的 python 重建 .venv（旧 venv 改名 .venv.bak-<时间戳> 留退路）
python3 UEFI.boot.py 包 安装        # 装 环境.efi.json 里列的包（走国内源 pypi.tuna）

实测一次真实修复（2026-09-16 首次跑时踩到的三连）：

体检当场抓出: venv 被搬过 (pyvenv.cfg 记 3.14.4 vs 实际 3.11.15) / psycopg2-binary 缺失 / 库 efi_kernel 不存在
→ 环境 重建 (uv venv --python 3.11) → 包 安装 (清华源 6.6s) → createdb efi_kernel → 6 项全绿

库不存在就一条命令建（引导器不替你建库，那是 DBA 的事）：

createdb -h /home/lou/pgdata/socket efi_kernel

3. 起内核（总调度）

python3 UEFI.boot.py 内核 启动 --守护

输出：

[INFO] 内核 启动 --守护 pid=20406 命令=/home/lou/桌面/工作区/内核/.venv/bin/python /home/lou/桌面/工作区/内核/内核/内核.py
体检通过: 解释器 3.11.15 | venv 健康 | 包 2/2 | 驱动目录 可写 | PG 通
[守护] /home/lou/桌面/工作区/内核/.venv/bin/python /home/lou/桌面/工作区/内核/内核/内核.py
[守护] 日志: /home/lou/桌面/工作区/内核/内核/logs/内核.log
[守护] 已拉起 pid=20406 pgid=20406

看它活着没：

python3 UEFI.boot.py 内核 状态

内核: 运行中 (pid 20406)   入口: …/内核/内核.py
启动时刻: 2026-09-16T20:55:37+08:00   已跑: 00:03:12
今日运行: 3 次   台账: kernel_runs（最近一条 ok=true, mode=daemon）

同一时间只允许一个内核（pg_try_advisory_lock 会话级锁）。起第二个被秒拒：

2026-09-16T12:57:29+08:00 ERROR [内核] 已经有一个内核在跑了 (抢不到调度锁) -- 同一份 PG 内存只能有一个调度器, 别起第二个

4. 起一个驱动

./.venv/bin/python 内核/内核.py 扫描            # 先扫一遍：认文件夹 + 校验 + 写注册表
./.venv/bin/python 内核/内核.py 启动 样板常驻

样板常驻: 已拉起 pid=20444

看状态（直读 /proc，不信库里的旧 pid）：

./.venv/bin/python 内核/内核.py 状态

状态    驱动名      形态    PID    运行时长  配置  说明
──────  ──────────  ──────  ─────  ────────  ────  ──────────────────────────────
已退出  Json解码    python  —      —         一致  把 web.json 解出来打印 -- 程序/Skill 层样本
停止    样板技能    python  —      —         一致  演示 skill 归驱动管: skill 是声明式文件 (技能/*.json), 分主模型 / 小模型两档
停止    样例消费器  python  —      —         一致  要别人的东西时不认识对方, 只往 calls 表发契约请求
运行    样板常驻    python  20444  00:00:12  一致  常驻 + 打印心跳 + 往 events 表汇报

驱动 3 / 有效 3 / 运行 1 / 无效 0    扫描 #43  20:55:37

看它说话（驱动日志 = 内核重定向的 stdout/stderr，每轮启动前有一条分隔头）：

./.venv/bin/python 内核/内核.py 日志 样板常驻 -n 6

样板常驻: 心跳
==== 启动 样板常驻  python3 /…/驱动/样板常驻/心跳.py  2026-09-16T20:55:47+08:00 ====
样板常驻: 起来了 pid= 20444  工作目录= /…/驱动/样板常驻
样板常驻: EFI_DB = 有
样板常驻: 已经在 LISTEN driver_样板常驻

5. 看总线（events 表）

驱动之间、驱动与内核之间没有协议，全靠这张表：

./.venv/bin/python 内核/内核.py 事件 -n 8

时间         级别  类型       来源  驱动       内容
───────────  ────  ─────────  ────  ─────────  ─────────────────────────────────────────
09-16 20:55  info  scan       内核  —          扫描完成 drivers=3 valid=3 invalid=0 version=43
09-16 20:55  info  start      内核  样板常驻    样板常驻 起来了 pid=20444 pgid=20444
09-16 20:55  warn  exit       内核  样板常驻    样板常驻: running -> crashed (断电 / 被杀)

6. 收工（停干净，别留孤儿）

./.venv/bin/python 内核/内核.py 停止 样板常驻     # 先校验 cmdline 再 SIGTERM 进程组（连子树一起收）
python3 UEFI.boot.py 内核 停止                    # 停内核（内核死了驱动照跑，所以顺序是"先驱动后内核"）
ps -eo pid,stat,cmd | grep -E "内核/内核.py|心跳.py" | grep -v grep   # 复查：应为空

内核停止 是幂等的（没在跑也回 0），并且会顺手给 kernel_runs 里没写 finished_at 的行收尾（断电留下的半截记录）。

7. 一键验收（改过代码后跑这个）

python3 试跑引导器.py          # 11 项端到端，全跑真命令，退出码 0 = 没 FAIL

  合计: PASS 11 | 预期 0 | FAIL 0
  残留: 无
  结论: 全过

第一次跑最可能踩的四个坑

症状	原因	处置
`体检不过: venv 不健康`	`.venv` 被搬过目录（`pyvenv.cfg` 里的版本/路径对不上）	`python3 UEFI.boot.py 环境重建`
`连不上 PG (efi_kernel@/home/lou/pgdata/socket)`	库没建 / PG 没起 / socket 路径不对	`createdb …`；查 `pg_isready -h /home/lou/pgdata/socket`
内核起来又秒退，日志里写 `抢不到调度锁`	已经有一个内核在跑	`python3 UEFI.boot.py 内核状态`，要重启用 `内核重启`
驱动 `无效`，`error` 写 `契约无人提供`	它 `needs` 的契约没有任何驱动的 `provides` 对上	看 `状态` 表的说明，或 `设计/01` 第 5 节第 8 条

下一步：想加自己的驱动 → 02-写一个驱动.md；日常命令 → 03-命令手册.md；出事 → 05-日志与排障.md。

8.6 KiB Raw Permalink Blame History Unescape Escape