README
¶
einox
A general-purpose agent base built on cloudwego/eino.
通用 agent 基座：在 eino 之上提供完整的 agent 运行时——循环引擎、会话、HITL 审批、沙箱、检查点、skill 机制、多代理编排、通用工具族。面向把 agent 作为组件嵌入业务系统的场景：业务系统对基座只装配、不修改。
einox 是独立的第三方开源项目，与 CloudWeGo / ByteDance 无隶属关系。
为什么需要 einox
agent 的价值不在通用聊天框，而在嵌入领域系统后获得的数据、权限与流程。einox 的定位是可装配的库，不是应用——交互形态与业务面归应用，机制归基座。
三层栈：eino（LLM 应用框架）→ einox（agent 运行时基座）→ 业务 agent。会话生命周期、HITL 审批、沙箱执行、网络容错、上下文整形这些「怎么跑起来」的运行时关切不在 eino 的面里，也不该散落在每个业务系统里各造一遍——einox 把它们收敛为机制，一次实现、处处装配。完整论证与选型思考见 docs/01-positioning.md。
核心能力
- 循环引擎：ReAct 主循环、失控护栏、确定性拓扑（supervisor/deep）选配
- 会话域：会话归属与快照、续聊、排队消息、运行中改向（steering）、TTL 清理
- HITL 审批：三档模式（manual 逐写审批 / plan 计划卡 / auto 直过）+ 参数级强制审批（任何模式不豁免）、fail-closed
- 沙箱：Linux Landlock + seccomp、Windows restricted token、macOS Seatbelt；出口治理（私网默认阻断 + DNS pinning）
- 网络容错：流式空闲哨兵、错误分类（致命停机/可重试）、有界重连
- harness：出站上下文经济（超长结果外置换指针）、长会话摘要、子代理编排（同步/后台派生）、动态工具装载
- 通用工具族：apply_patch / 文件面 / 命令执行 / 代码仓 worktree / 网页提取 / docx·xlsx 等
- 测试假模型：
llmtest零真实端点跑通引擎与工具循环
全量清单见 docs/02-capabilities.md。
快速开始
要求 Go 1.26+。
go get github.com/jumeng/einox
最小装配（四项必填 Options + 运行面）见 docs/03-assembly.md；测试注入 llmtest 假模型即可零真实端点跑通引擎 + 工具循环。
文档
| 关注点 | 文档 |
|---|---|
| 定位与选型：为什么在 eino 与业务 agent 之间放一层基座 | docs/01-positioning.md |
| 能力清单：引擎 / 工具族 / harness / 提示词 / 沙箱 / 模型面 | docs/02-capabilities.md |
| 装配：快速使用、自由裁剪、业务扩展 | docs/03-assembly.md |
状态
早期开发中，API 不稳定，随时破坏兼容。欢迎 issue 讨论与试用反馈。
布局
| 目录 | 职责 |
|---|---|
contract/ |
契约面（零 eino import，业务只见此面） |
engine/ |
循环引擎 |
session/ |
会话与快照 |
hitl/ |
人在环审批 |
mid/ |
工具中间件链 |
llm/ |
模型工厂与网络容错 |
checkpoint/ |
检查点 |
skills/ |
skill 机制 |
workspace/ |
工作区 |
tools/ |
通用工具族 |
prompts/ |
内置提示词 |
einoext/ |
eino 双向桥 |
llmtest/ |
测试假模型 |
贡献
欢迎 issue 与 PR。仓库工作说明（命令、架构约定、许可与溯源）见 AGENTS.md；提交前 go build ./... && go test ./... 全绿。
许可
Directories
¶
| Path | Synopsis |
|---|---|
|
Package checkpoint 是会话检查点的文件存储（adk Get/Set 两方法；自产品 internal/agent/checkpoint.go 迁入）。
|
Package checkpoint 是会话检查点的文件存储（adk Get/Set 两方法；自产品 internal/agent/checkpoint.go 迁入）。 |
|
Package contract 是 einox 对应用层暴露的最小契约面：工具/事件/审批/ 上下文注入协议。
|
Package contract 是 einox 对应用层暴露的最小契约面：工具/事件/审批/ 上下文注入协议。 |
|
Package einoext 是 eino 组件双向桥：Adapt 把契约工具（contract.Tool）适配 为 eino 工具供引擎组装消费；Bridge 把 eino/eino-ext 组件接入契约面（第三方 件依赖与适配归基座）。
|
Package einoext 是 eino 组件双向桥：Adapt 把契约工具（contract.Tool）适配 为 eino 工具供引擎组装消费；Bridge 把 eino/eino-ext 组件接入契约面（第三方 件依赖与适配归基座）。 |
|
Package engine 是 einox 循环引擎（自产品 internal/agent/agent.go 迁入泛化）： 每轮 Run 组装——Providers 解析 → NewModel 构造 ChatModel（测试可注入假 模型）→ adk ChatModelAgent（Instruction + 工具面 [hitl 审批包装 × einoext 适配] + skill middleware）→ Runner（EnableStreaming + CheckPoints 注入）→ Run + WithCheckPointID（续聊 = 会话域 History 回传，checkpoint 只承担中断/ 取消恢复）→ 事件泵分类为契约事件族。
|
Package engine 是 einox 循环引擎（自产品 internal/agent/agent.go 迁入泛化）： 每轮 Run 组装——Providers 解析 → NewModel 构造 ChatModel（测试可注入假 模型）→ adk ChatModelAgent（Instruction + 工具面 [hitl 审批包装 × einoext 适配] + skill middleware）→ Runner（EnableStreaming + CheckPoints 注入）→ Run + WithCheckPointID（续聊 = 会话域 History 回传，checkpoint 只承担中断/ 取消恢复）→ 事件泵分类为契约事件族。 |
|
Package hitl 是审批包装器（挂起-续流 HITL 机制；自产品 internal/agent interrupt.go 迁入，对齐官方 approval_wrapper 形态 + fail-closed 语义）。
|
Package hitl 是审批包装器（挂起-续流 HITL 机制；自产品 internal/agent interrupt.go 迁入，对齐官方 approval_wrapper 形态 + fail-closed 语义）。 |
|
internal
|
|
|
tstore
Package tstore 是基座测试用会话存储（tmpdir 目录实现 session.Store 与 checkpoint.UserStore——布局约定同产品 FileStore：users/<op>/<rel> 子树 + .tmp 临时域 + 数据根）。
|
Package tstore 是基座测试用会话存储（tmpdir 目录实现 session.Store 与 checkpoint.UserStore——布局约定同产品 FileStore：users/<op>/<rel> 子树 + .tmp 临时域 + 数据根）。 |
|
Package llmtest 提供剧本化假模型（应用侧测试注入——公开面零 eino 类型， 业务测试不 import eino 即可模拟模型行为）。
|
Package llmtest 提供剧本化假模型（应用侧测试注入——公开面零 eino 类型， 业务测试不 import eino 即可模拟模型行为）。 |
|
Package mid 是工具中间件链（guard / errFeed）：业务错误回喂模型自纠、 防死循环提醒、单工具执行硬上限。
|
Package mid 是工具中间件链（guard / errFeed）：业务错误回喂模型自纠、 防死循环提醒、单工具执行硬上限。 |
|
Package prompts 自研通用提示词资产（业务无关——对位 ext/tools 的提示词 层；将来抽仓随 ext 同走）。
|
Package prompts 自研通用提示词资产（业务无关——对位 ext/tools 的提示词 层；将来抽仓随 ext 同走）。 |
|
Linux 后端编排：施加序与探测子进程（真源 §2.1/§1.3）。
|
Linux 后端编排：施加序与探测子进程（真源 §2.1/§1.3）。 |
|
Package session 是会话域（自产品 internal/agent/session.go 迁入）：内存 注册表 + users/<op>/sessions/<sid>/session.json 落盘（用户隔离）。
|
Package session 是会话域（自产品 internal/agent/session.go 迁入）：内存 注册表 + users/<op>/sessions/<sid>/session.json 落盘（用户隔离）。 |
|
Package tools 是 einox 通用工具面基设：类型化工具构造（InferTool——结构体 反射出参数 JSON Schema，schema 推断复用 eino 反射器保证与既有工具面完全 同构）与通用工具族（fs/todo/web/时间/问答/命令/补丁，自原 ext/tools 迁入）。
|
Package tools 是 einox 通用工具面基设：类型化工具构造（InferTool——结构体 反射出参数 JSON Schema，schema 推断复用 eino 反射器保证与既有工具面完全 同构）与通用工具族（fs/todo/web/时间/问答/命令/补丁，自原 ext/tools 迁入）。 |
|
applypatch
Package applypatch 提供 apply_patch 工具：codex `*** Begin Patch` 格式的 解析与应用（多文件 增/改/删/改名，事务性——任一失败全部不落盘）。
|
Package applypatch 提供 apply_patch 工具：codex `*** Begin Patch` 格式的 解析与应用（多文件 增/改/删/改名，事务性——任一失败全部不落盘）。 |
|
askuser
Package askuser 提供 ask_user 工具：长任务中途向用户结构化提问（单选/ 多选/自由文本），经挂起-续流通道（contract.Suspend 哨兵 → 适配层转引擎 Interrupt×Resume）。
|
Package askuser 提供 ask_user 工具：长任务中途向用户结构化提问（单选/ 多选/自由文本），经挂起-续流通道（contract.Suspend 哨兵 → 适配层转引擎 Interrupt×Resume）。 |
|
currenttime
Package currenttime 提供 get_current_time 工具：时钟/周界语义——周报周期 与 deadline 计算的正确性底线。
|
Package currenttime 提供 get_current_time 工具：时钟/周界语义——周报周期 与 deadline 计算的正确性底线。 |
|
egress
Package egress 提供工具层网络出口治理（Phase S-9，真源 findings/2026-08-26-einox-sandbox-design.md §9；移植蓝本 = nanobot nanobot/security/network.py，344 行 Python 的 Go 直译收敛）。
|
Package egress 提供工具层网络出口治理（Phase S-9，真源 findings/2026-08-26-einox-sandbox-design.md §9；移植蓝本 = nanobot nanobot/security/network.py，344 行 Python 的 Go 直译收敛）。 |
|
fsutil
Package fsutil 提供工作区文件工具四件：read_file / list_dir / search_files / delete_file（读-搜为主 + 显式删除——删除走审批卡直白话，比拼 rm 命令可控； 内容写面归 applypatch / str_replace_editor / runcommand）。
|
Package fsutil 提供工作区文件工具四件：read_file / list_dir / search_files / delete_file（读-搜为主 + 显式删除——删除走审批卡直白话，比拼 rm 命令可控； 内容写面归 applypatch / str_replace_editor / runcommand）。 |
|
office
Package office 提供 office 文档读写工具族（2026-08-25 裁决：office 读写是 通用能力，归基座）：read_xlsx / write_xlsx / read_docx / write_docx / read_pptx。
|
Package office 提供 office 文档读写工具族（2026-08-25 裁决：office 读写是 通用能力，归基座）：read_xlsx / write_xlsx / read_docx / write_docx / read_pptx。 |
|
plan
Package plan 提供 submit_plan 工具：计划文档提交（用户域 plans/<sid>/ <seq>.md 持久落盘）+ 挂起送审（Suspend → 引擎转 plan_request 事件卡 → approve 端点决议 → Resume 消费）。
|
Package plan 提供 submit_plan 工具：计划文档提交（用户域 plans/<sid>/ <seq>.md 持久落盘）+ 挂起送审（Suspend → 引擎转 plan_request 事件卡 → approve 端点决议 → Resume 消费）。 |
|
repo
Package repo 是代码仓挂载与 git 面工具族（会话域件）：open_repo 把采集缓存 仓以 git worktree 挂载进会话工作区 repos/<短名>/（任务分支 agent/<sid>-<n>， 会话级持久——工作区任务收尾清理排除 repos/）；status/diff 只读面、commit 写 面（应用层 ArgsForce 级人工确认）与补丁导出。
|
Package repo 是代码仓挂载与 git 面工具族（会话域件）：open_repo 把采集缓存 仓以 git worktree 挂载进会话工作区 repos/<短名>/（任务分支 agent/<sid>-<n>， 会话级持久——工作区任务收尾清理排除 repos/）；status/diff 只读面、commit 写 面（应用层 ArgsForce 级人工确认）与补丁导出。 |
|
runcommand
Package runcommand 提供 run_command 工具：工作区内 shell 命令执行（P1b 简版——超时/输出头尾截断/cwd 圈进工作区；后台任务形态 P2 随编码子代理）。
|
Package runcommand 提供 run_command 工具：工作区内 shell 命令执行（P1b 简版——超时/输出头尾截断/cwd 圈进工作区；后台任务形态 P2 随编码子代理）。 |
|
todo
Package todo 提供 todo_write 任务清单工具：多步任务的自跟踪与用户可见 进度。
|
Package todo 提供 todo_write 任务清单工具：多步任务的自跟踪与用户可见 进度。 |
|
webfetch
Package webfetch 提供 web_fetch 工具：URL → 正文 markdown 提取（httprequest 只回裸 HTML，真实网页数百 KB 直接爆上下文——本工具做「提取」而非「全文」）。
|
Package webfetch 提供 web_fetch 工具：URL → 正文 markdown 提取（httprequest 只回裸 HTML，真实网页数百 KB 直接爆上下文——本工具做「提取」而非「全文」）。 |
|
Package workspace 是会话工作区模型（用户域）：一轮任务一清的临时 落盘面——spill 溢出、编码循环中间产物（2026-08-25 起 repos/ 子目录为 会话级持久挂载区，wipe 排除）。
|
Package workspace 是会话工作区模型（用户域）：一轮任务一清的临时 落盘面——spill 溢出、编码循环中间产物（2026-08-25 起 repos/ 子目录为 会话级持久挂载区，wipe 排除）。 |
Click to show internal directories.
Click to hide internal directories.