一个精简的 native coding agent:LuaJIT + libcurl + C,无 Node / Python / WebView / Electron。 骨架借 Pi,DeepSeek 原生与缓存优先借 Reasonix,工具行为借 opencode。
它把四件事当作硬约束,其余都围着这四条转:
| 做法 | 换来 | |
|---|---|---|
| 缓存优先 | system prompt 字节稳定;时钟/轮次拼在消息尾部;召回块只在每轮首次请求追加到最末尾 | 前缀命中 ~97%,计费 miss 少 72% |
| 有界上下文 | 默认丢弃优先:超线从最新往回装,更老整条丢,缺什么 recall 召回 |
长会话不用摘要也不炸;LITE_COMPACT=1 才回到「先摘要」 |
| 本地记忆 | 每个目录一份 mem.bin(C + mmap 零拷贝),旧轮次不进 prompt |
丢了能查回来,跨会话、跨迭代 |
| 无框架依赖 | 工具就是 Lua 表;系统 .so 直接 FFI;缺能力自己编译;/reboot 自动重启拿新工具 |
加能力不引运行时;重启换新进程但会话/记忆不丢 |
./tools/build.sh # 编译 C(KV cache / image / x11)+ 检查 LuaJIT
./tools/release.sh # 构建 + 打包 + 安装(源码安装把 lua/ 软链过来,改完重启即生效)
export DEEPSEEK_API_KEY=... # 或写进 .env / ~/.config/lite/.env
./tools/run.sh --tui # TUI:改文件后自动弹两栏 diff(Ctrl+G 手动看),/session 选会话,/reboot [提示词] 自动重启并从那句接着干
./tools/run.sh --tui --thinking --reasoning-effort high
./tools/run.sh --once --json "解释这个项目" # 无 UI 一轮,JSONL 事件
./tools/run.sh --recall "关键词" # 查当前目录的本地记忆
./tools/run.sh --memory-export kb.jsonl # 知识层导出成 JSONL(省略文件 / - 打 stdout)
./tools/run.sh --memory-import kb.jsonl # 导入合并进当前目录 mem.bin(加 --dry-run 先看)
./tools/run.sh plugins --json # helper/ 插件清单 + 加载错误
./tools/run.sh serve --port 8765 # headless 服务端
./tools/run.sh attach --port 8765 # 任意终端/tmux tab attach
./tools/run.sh serve --wake 300 --task "检查 CI" # 无人值守定时唤醒
./tools/test.sh # 依赖 + 单元 + CLI + TUI(tmux) 冒烟调试与自观察:--debug(JSONL 记录 system prompt 与原始 response)、
--tui --snapshot FILE(整屏文本快照)、state --json / sessions --json。
配置优先级:flag → 环境变量 → .env → ~/.config/lite/config.lua → 默认值。
内置(schema 在 API tools 字段里,system prompt 只列名字):
bash lua web read ocr write edit resize native todo remember recall。
- 输出统一 头尾双端裁剪(bash 32KB,其余 30KB):只留头部会把编译报错/测试结论砍掉,模型只能重跑。
- 失败可自修:报错带原始参数 +
required键 + 退出码语义(124 超时 /126 不可执行 /127 未找到); 同一调用连续失败第 2 次起追加[this exact call has now failed N times],成功清账。 read支持文本/目录/图片,paths数组一次读 N 个文件(图片一次一张)。write有append=true:长文档分段落盘,write(新建) →write(append) 循环, 别指望一次请求写完(超LITE_MAX_OUTPUT_TOKENS会把参数 JSON 截断)。bash异步执行,长命令不冻结 TUI,Ctrl+C取消;--approval ask|deny逐次确认。
随包插件(./tools/run.sh plugins 看本机实际加载):
| 工具 | 作用 | 依赖 |
|---|---|---|
cgrep |
多线程正则扫目录,出 path:line: text |
自带 C |
adb |
Android:screenshot/tap/swipe/text/open/shell/push | adb |
wechat |
微信:搜联系人 → 进会话 → 发消息/文件 | X11 + libxdo + OCR |
uimap |
视觉定位按钮并真点确认,产出坐标表 | 截图 + OCR |
usb |
麦克风/音箱/摄像头:record/play/photo/video/volume | ffmpeg/arecord/pactl |
music |
后台常驻 VLC 放歌,WebDAV 整库流播不下载 | vlc + dbus-send |
search / fetch |
DeepSeek 搜索 / URL → Markdown 正文 | DEEPSEEK_API_KEY |
tokens |
每日 token 账本(prompt/completion/命中率) | 本地 /agent/usage |
pdftext |
抽 PDF 文本 | 纯 FFI 直连 libpoppler-glib |
md2png / trending |
Markdown/GitHub Trending → 长图 PNG(无 Chrome) | libmd4c + 自带 liblite_html |
共享逻辑放 helper/lib/(子目录不参与发现,不会冒出多余工具)。
缺能力先造,不降级。native 走三步:build(C/C++ → helper/<name>-<ts>.so)→
run(喂真实输入验边界)→ wrap(生成 helper/<name>.lua + schema,按名即调)。
-- helper/wordcount.lua:一个文件同时声明工具与实现
return {
schema = { name = "wordcount", description = "统计词数",
parameters = { type = "object", properties = { text = { type = "string" } },
required = { "text" } } },
run = function(args) return tostring(#(args.text:gmatch("%S+"))) end,
}只返回 hooks(before_tool / after_tool / on_user_turn / on_compact / on_session_end)
的插件不进工具列表,只当钩子;hook 抛错一律 fail-open。插件与 agent 同进程同权限,
跑不受信任的仓库用 --no-plugins 全关。
清单冻结,派发动态:schema 只在会话启动扫一次(前缀缓存的代价),但执行侧每次
loadfile 重读、.so 按清单重新 ffi.load —— 改插件立刻生效,新建插件按名可调,
下次会话才出现在 API tools 里。运行期试新代码用 lua 工具(子进程,默认 30s 超时)。
项目目录/mem.bin mmap 数据(轮次 / 事实 / 工作态) mem.idx 索引
- 命名空间:
/agent/knowledge/*(本目录长期事实)、/agent/session/<id>/*(消息、摘要、todo)、/agent/working/*(wake 等运行态,不注入 prompt)。 - 每轮开始按当前输入召回一块
<retrieved_memory>,追加到请求最末尾(只影响请求,不写会话); 同一轮的工具循环不重复注入。 - 局部记忆:召回 query 用 ASCII 词 + 中文 bigram,短追问会拼上一轮 user 改善「继续/那个」。
- 每条消息镜像进
/msg/<seq>,只保留最近LITE_SESSION_RAW_KEEP(200)条非 user 原文, user 永久保留;tool 结果入库截到LITE_TOOL_RESULT_CHARS(8192)。更老的靠 turn 摘要和recall。 mem.lock:写实例持锁,--recall/--memory-export/state/sessions只读不加锁,运行中也能诊断。- 删除
mem.bin= 清空该目录记忆。
mem.bin 是本机私有脑(按目录分、mmap + 独占写锁,第二个进程只能只读),
memdb/ 是公共的一份:一个目录、一个文件 mem.shared.jsonl,所有 agent 都往里面 append。
不加锁、不合并、不覆盖——O_APPEND 单行写入原子,谁写的记在每行的 o 字段里。
冗余是设计选择——同一条事实被三个 agent 各写一遍很正常,去重和判断可信度是读的人的事。
export LITE_MEMDB_DIR=/srv/lite-memdb # 指到共享盘(NFS/WebDAV 挂载点)就天然多机共享
export LITE_MEMDB_FILE=/srv/lite-memdb/mem.shared.jsonl # 可选,单独指定那个文件
export LITE_AGENT_NAME=box-a # 可选,缺省 = <hostname>-<cwd 名>,只作署名
export LITE_MEMDB_SPLIT=1 # 仅在多机 NFS 上用:退回每 agent 一个文件
./tools/run.sh --memdb # 有多少条、谁写的
./tools/run.sh --memdb-search "ollama 端口" # 全库搜(ASCII 词 + 中文 bigram)默认位置 ~/.local/share/lite-memdb/mem.shared.jsonl(安装目录之外:
早先放在 share/lite/memdb,而 tools/install.sh 升级时 rm -rf 安装目录,
每次 release 都会把共享库清空——老路径的数据会一次性自动搬过来),
cat/grep/git diff 都行,人工改也不会坏(坏行读取时跳过)。
remember写完mem.bin后顺手 append 进共享库;recall先给本地结果, 再补最多 3 条shared@<origin>(和本地重复的、自己刚写的都会先剔掉)。- 写入靠
O_APPEND单行原子性:40 个进程并发写同一文件,实测 200/200 行完好、无交织。 - 读到半行/坏行直接跳过,别人正在写的文件不会拖垮整次读取。
- 搬迁想用 SQL/全文索引再说;现在这套的定位是「便宜、能 grep、能 git diff、坏了只丢一行」。
mem.bin 是 mmap 的二进制,还带指针偏移,不能跨机器/跨版本直接拷。要搬就过一遍 JSONL:
./tools/run.sh --memory-export # 只导 /agent/knowledge/,打到 stdout
./tools/run.sh --memory-export kb.jsonl --all # 连 session/working 一起导
./tools/run.sh --memory-export kb.jsonl --prefix /agent/session/ --prefix /agent/knowledge/lite/
./tools/run.sh --memory-import kb.jsonl --dry-run # 只报数,不落盘
./tools/run.sh --memory-import kb.jsonl # 同 key 覆盖,逐行容错- 行格式一行一条,可
grep、可git diff、能手写:{"k":"/agent/knowledge/lite/hand/edit","v":"纯文本","ttl":0},v也可以是{"text":"...","tags":[...]}这样的表。 - 手写时 key 不带命名空间(直接写
lite/hand/edit)会自动补/agent/knowledge/, 否则落在根上,recall和导出都扫不到。 ttl固定导 0:C 层没有剩余寿命查询,且值得搬的 fact 本来就该永久。- 导入只写目标库,不是双向同步;
--dry-run报new/overwrite数,出错行进 stderr 不影响其余行。 - 语义回环稳定:导出 → 导入 → 再导出,内容一致(表内键序可能不同)。
上下文预算默认 LITE_CONTEXT_CHARS=120000(整条请求的字符数:system + digest + 尾巴 + 工具 schema 都算在内):
跨过触发线(预算 85%)就从最新往回装窗口、
更老的整条丢,session.messages 和记忆一条不删 —— 「压缩」在这里只是缩小发出去的窗口。
LITE_COMPACT=1 恢复三段式摘要(稳定前缀 / 结构化 digest / 近期原文尾巴)。
/compact 手动把窗口滑到 budget*LITE_KEEP_RATIO。
| 变量 | 默认 | 说明 |
|---|---|---|
DEEPSEEK_API_KEY |
— | 必需 |
DEEPSEEK_BASE_URL |
https://api.deepseek.com |
API 地址 |
DEEPSEEK_MODEL |
deepseek-flash |
模型 |
LITE_ENV_FILE |
自动探测 | .env 路径;/dev/null 全关。顺序:cwd 向上 12 级 → ~/.config/lite/.env → $ROOT/.env,已设变量优先 |
LITE_CWD |
当前目录 | workspace |
LITE_MAX_TURNS |
256 | 单次循环上限 |
LITE_TEMPERATURE |
0 | 采样温度 |
LITE_THINKING / LITE_REASONING_EFFORT |
— | thinking 开关 / high·medium·low |
LITE_MAX_RETRIES |
2 | 429/5xx/网络错误重试次数 |
LITE_CONTEXT_CHARS |
120000 | 整条请求的字符预算(含 system/digest/schema) |
LITE_CONTEXT_TURNS |
16 | 摘要尾巴的 user 轮数上限 |
LITE_CONTEXT_WINDOW |
64000 | 模型窗口 tokens(算触发线与 output limit) |
LITE_RESERVE_TOKENS |
8192 | 预留输出 tokens |
LITE_MAX_OUTPUT_TOKENS |
8192 | 单次输出上限;超限时工具参数 JSON 会被截断(报错里带 finish_reason=length,按截断处理而不是当成模型写错 JSON) |
LITE_TOKEN_BUDGET |
0 | 会话 token 预算,0 不限 |
LITE_COMPACT |
0 | 1 = 先摘要(有三段式 checkpoint),默认丢弃优先 |
LITE_KEEP_RATIO |
0.6 | 丢窗口时保留比例(0.3~0.95) |
LITE_BUDGET_HINT |
— | 1 在尾部块里播报剩余预算(默认关,纯噪声) |
LITE_AUTO_DIFF |
1 | edit/write 改完文件自动弹两栏 diff(0 只留 Ctrl+G 手动看) |
LITE_TUI_MEM_NOTICE |
— | 1 = 召回命中在 transcript 里留一行 memory: N hits · key, ...(默认静音,状态栏也不再显示 hit:N) |
LITE_TUI_MEM_VERBOSE |
— | 1 = 上面那行再展开成 key + 正文摘要(要配合 LITE_TUI_MEM_NOTICE) |
LITE_MEMORY_MB |
100 | mem.bin 容量 |
LITE_MEMORY_FLUSH |
30 | 落盘间隔(秒) |
LITE_MEMORY_DIR |
— | 覆盖 mem.bin 所在目录 |
LITE_SESSION_RAW_KEEP |
200 | 保留的最近非 user 原文条数 |
LITE_TOOL_RESULT_CHARS |
8192 | tool 结果入库截断 |
LITE_INSTRUCTIONS_FILE |
自动探测 | AGENTS.md/CLAUDE.md/.lite/instructions.md;/dev/null 禁用 |
LITE_INSTRUCTIONS_CHARS |
16000 | 指令文件截断 |
LITE_READ_DIRS |
$TMPDIR:/tmp:/var/tmp |
额外允许只读图片的目录 |
LITE_JSON |
— | 1 等价 --json |
LITE_APPROVAL |
auto | auto / ask / deny |
LITE_SANDBOX / LITE_SANDBOX_NET |
— / 1 | bwrap bash 沙箱 / 沙箱内网络 |
LITE_PLUGINS |
1 | 0 关闭插件与 hook |
LITE_DEBUG_LOG |
— | JSONL 调试日志 |
LITE_SERVE_PORT |
8765 | serve/attach 默认端口 |
LITE_WAKE_SEC / LITE_WAKE_TASK / LITE_WAKE_TASK_FILE / LITE_WAKE_MAX |
— / — / .lite/wake.md / 0 |
定时唤醒 |
LITE_DISPLAY / LITE_SHOT_DIR |
:0 / 临时目录 |
X11 截图目标显示 / 落盘目录 |
LITE_OCR_LIB / LITE_OCR_MODELS / LITE_ORT |
third_party/ocr/... |
OCR 库、模型、onnxruntime |
LITE_VOICE_MIC / TAIL / MIN / CHUNK / GATE / AUTO_SEND |
default / 1.5 / 2 / 20 / -38 / 1 |
语音:设备、尾静音秒、最短、最长、静音门限 dB、转写完是否自动发 |
SENSEVOICE_BIN / _MODEL / _LANG / _THREADS |
/opt/SenseVoice.cpp/bin/sense-voice-main / /data/models/sense-voice-small-q4_k.gguf / auto / 4 |
ASR CLI 与权重(固定 CPU) |
随包自带:LuaJIT、cjson、liblite_cache.so(C KV cache)、liblite_image.so
(PNG/JPEG/WebP 解码+缩放)、liblite_capture.so(X11 截图)及它们的非 libc 依赖。
需要系统提供:libcurl(否则无法调 API)、libX11/libxdo(否则无截图与鼠标键盘)、
OpenMP 运行库(否则 KV cache 加载失败)。./tools/check_deps.sh 逐项检查。
可选,默认不打包:OCR 与语音输入,不装只影响对应工具,其余功能一行不少。
| 组件 | 体积 | 默认 | 拷到哪里 |
|---|---|---|---|
| PP-OCRv4 模型(det + rec + 字典) | 14.8 MB | ❌ | dist/lite-linux-x64/models/ocr/ |
| onnxruntime CPU 版 | 22 MB | ❌ | dist/lite-linux-x64/lib/ |
| onnxruntime GPU 版 | 26 MB | ❌ | 同上 |
libonnxruntime_providers_cuda.so |
329 MB | ❌ | 同上(仅 GPU;永不打包) |
ffmpeg + SenseVoice.cpp CPU + gguf |
— | ❌ | 系统包 + /opt、/data,只调外部 CLI |
CPU/GPU 核心库都这么大是因为
.text里 17.4 MB 是 MLAS 算子 kernel 矩阵(每算子 × dtype × 指令集一份),跟 CUDA 无关;GPU 版只多 3.2 MB,真正的大头是 329 MB 的 CUDA provider。
# OCR:拷模型和 onnxruntime 进 dist(真拷贝,dist 可整体搬走)
cd dist/lite-linux-x64
./tools/ort_link.sh models /path/to/lite/third_party/ocr/models/ocr
LITE_ORT_PREFER=cpu ./tools/ort_link.sh copy
./tools/ort_link.sh status
# 单张小图 CPU 更快(0.80s vs GPU 2.41s,GPU 每次都要建 CUDA 上下文);
# 想随包分发:LITE_DIST_WITH_OCR=1 LITE_DIST_WITH_ORT=1 ./tools/package.sh(包体 3.3M → 27M)
# 语音:系统装 ffmpeg + pulseaudio-utils,编 SenseVoice.cpp(CPU),下 gguf 模型
./tools/lua.sh -e 'local v=require("core.voice"); print(v.available())'构建期:gcc / cmake / pkg-config / OpenMP、libpng libjpeg libwebp 开发包。
P0 基础设施 · P1 无 UI agent · P1.5 上下文记忆 · P2 TUI · P3 serve/attach · 插件与自扩展 全部落地。 未做:无人值守下的完整审批/沙箱收口、上下文逐轮曲线落 KV。
设计取舍见 design.md;开发/测试规范与插件细节见 AGENTS.md。
用 lite 这套体系开别的项目(同样必须遵守,不是 lite 私有):
./tools/newproject.sh <目录> --name <名字> 生成可跑骨架(LuaJIT FFI + Lua 编排 + C 内核 +
唯一 .so 解析点 + see.lua 定位截图 + test.sh 三层验收),规范全文
templates/PROJECT_STANDARD.md;
./tools/newproject.sh --refresh-ffi 把最新 lua/ffi/{x11,xdo}.lua 自包含对刷进模板。
- Pi https://github.com/badlogic/pi-mono · Reasonix https://github.com/esengine/reasonix · opencode https://github.com/anomalyco/opencode