Djinn · 开源的 headless agent 运行时

Djinn 不是某个 IDE 的插件，也不是某家模型的 SDK——它是「agent 本体」。进程被 kill -9、OOM、容器重启之后，用同一个会话 id 重跑即可恢复；上次死在工具执行中途的调用会被自动重做。底层仅依赖 Node 内置模块，CommonJS，Node ≥ 18.17，没有任何第三方运行时依赖。

核心特性

为「长会话、弱网络、要可恢复」的生产场景而生，而不是为演示稿。

💾

持久化会话

append-only jsonl，每条记录产生即刻落盘。进程被杀、OOM、容器重启后用同一 --session-id 重跑即可恢复；死在工具执行中途的调用会被自动重做（dangling redo）。

🔀

OpenAI 兼容模型池

主模型 + 有序 fallback 链。429 / 5xx / 网络错误 / 空响应自动沿链切换；上下文超长走「压缩后同模型重试」而非盲目换模型。每个模型可带独立 maxInputTokens 与网关地址。

🧹

两条上下文压缩路径

主路径调 LLM 生成摘要（2 次尝试），失败或返回空时零成本确定性裁剪兜底（丢弃 reasoning 等低信息量记录）。触发线 = 当前模型输入上限 × 70%。

🛠️

内置工具集

read_file / write_file / edit_file / bash / read_image / grep / glob。工具失败一律转为 isError 结果喂回模型，不中断循环；图片按 OpenAI 协议聚合为紧随其后的多模态消息。

📜

headless 输出纪律

stdout 只写逐行 NDJSON 事件（8 类），日志一律 stderr；退出码 0 成功 / 1 错误 / 130 SIGINT 中断（会话已落盘）。天然适合被编排器 spawn 驱动、做流式拼接。

🧪

自带测试替身

@djinn/runtime 随包发布一个假 OpenAI 服务器（startFakeOpenAI），接入方无需网络即可编写自己的集成测试——Djinn 自己的 100+ 项测试就跑在它上面。

快速开始

零配置起步：装好、构建、link，给个 Key 就能跑。

终端里跑起来

# 安装依赖并构建
npm install
npm run build
npm link packages/cli        # 或：node packages/cli/dist/index.js

export DJINN_API_KEY=sk-...
djinn -p "把当前目录的 package.json 里的版本号改成 0.2.0"

# 输出（每行一个 JSON 事件）
{"type":"session","sessionId":"3f6c…","resumed":false}
{"type":"tool_call","name":"read_file","arguments":"{\"path\":\"package.json\"}"}
{"type":"token","text":"已把版本号改为 0.2.0"}
{"type":"done","sessionId":"3f6c…","turns":2,"usage":{...}}

# 中断后恢复（同一个会话 id）
djinn -p "继续，顺便把 README 也更新了" --session-id 3f6c…

嵌进你自己的进程（无需网络即可测试）

const { startFakeOpenAI, contentChunk } = require('@djinn/runtime');

const fake = await startFakeOpenAI(() => ({ sse: [contentChunk('你好')] }));
// …把 fake.baseUrl 当作 DJINN_API_BASE…
await fake.stop();

在数员（MiniABC）里

Djinn 是数员 AI 原生工作平台的第三种推理引擎底座（「底座 C 方案」）。在 harness-platform 中，租户只需一行 UPDATE tenants SET wbb_engine='djinn'（或自服务切换），即可把数字员工的推理切换到 Djinn，无需改代码、无需重启。

生产环境里 Djinn 以每租户独立系统用户降权运行，并挂入每次调用独立的 cgroup v2（内存/进程数硬顶），子进程环境变量为最小集——平台密钥（DB/JWT/其他引擎密钥）绝不注入降权进程。会话通过 --session-id 跨消息继承上下文，且 system prompt 经 --system-prompt-file 注入，与企业上下文、知识检索、能力指令共用同一套构建。

常见疑问

和 LangChain / AutoGen 这类框架有什么不同？

Djinn 不追求「万物皆可编排」，而是把「持久化会话 + 韧性模型池 + 上下文压缩 + 工具执行」收敛成一个 headless 二进制：stdout 只吐 NDJSON，天然适合被别的系统 spawn 驱动。它不绑定任何平台，也不替你做业务编排。

一定要用 OpenAI 吗？

只要是 OpenAI 兼容的网关即可（SSE 流式 + 错误分类）。主模型与 fallback 链各自可配独立网关地址与 maxInputTokens。

会话真的能恢复吗？

能。会话以 append-only jsonl 落盘，进程被杀后用同一 --session-id 重跑即可续上；中途死在工具调用的那一轮会被自动重做，不会卡在半状态。

MIT 许可零运行时依赖 Node ≥ 18.17 100+ 测试

在 GitHub 上 Star / Fork