Lithe AI Core 是一个面向 IDE 的、Capability 驱动的 Rust Agent Runtime 微内核。
它要解决的不是“再做一个聊天页面”，也不是“再封装一层大模型 API”，而是提供一套稳定、可组合、可替换的 Agent 执行底座：IDE 或其他宿主只描述这次运行需要什么能力，Runtime 负责解析能力、执行 Agent Loop、调用模型与工具、记录事件，并把结果可靠地返回给宿主。
当前版本是 0.1.0 alpha。仓库已经打通一条可运行的纵向链路，但完整插件生命周期、可执行可视化 Graph 和正式 IDE 集成仍在建设中。
常见 Agent 应用会把下面这些东西写死在一个程序里：
- Agent Loop 如何推进；
- 使用哪个模型供应商；
- 工具如何注册和调用；
- 会话和事件保存在哪里；
- 输入输出经过哪些策略；
- UI、业务逻辑和执行逻辑如何连接。
这种写法做 Demo 很快，但一旦要更换 Provider、增加新的 Loop、接入 IDE、隔离第三方插件，或者让用户通过图形界面组合 Agent，代码就会迅速耦合。
Lithe 的方向是把稳定的执行语义留在微内核，把可变化的具体能力交给内置实现或插件：
Runtime = 稳定内核语义 + Capability 契约 + 本次运行的能力绑定
Agent = Agent Loop + Provider + Tools + Storage + Policies + ...
Runtime 不应该偷偷决定使用哪个模型、数据库或工具。每次运行都要显式绑定所需 Capability；能力不存在或配置无效时，直接返回可诊断错误，而不是静默降级。
Lithe 把一个 Agent 看成一组可替换能力的组合，而不是一个不可拆分的大对象。
| Capability | 负责什么 | 当前状态 |
|---|---|---|
agent.loop |
决定一次运行如何迭代、何时调用模型或工具、何时结束 | 已实现基础有界 Loop |
provider.model |
调用模型并返回统一结果 | 已实现 OpenAI、DeepSeek 和离线 Echo |
tool |
向 Agent 暴露外部动作 | 已实现注册、解析与调用链路 |
storage.session-events |
保存和重放有序会话事件 | 已实现进程内 Memory Store |
policy.input / policy.output |
校验、脱敏、拒绝或审核输入输出 | 规划中 |
events.sink |
日志、指标、审计和实时事件分发 | 规划中 |
memory / prompt / sandbox / telemetry |
提供长期记忆、提示词、隔离和可观测能力 | 规划中 |
例如，同一个 Runtime 可以组合成不同 Agent：
Coding Agent
= bounded-agent
+ OpenAI Provider
+ filesystem / terminal Tools
+ durable Session Store
+ command approval Policy
Offline Test Agent
= bounded-agent
+ echo-round-trip Provider
+ echo Tool
+ memory Session Store
两者共享同一套协议、生命周期边界、错误模型和事件顺序，但具体能力完全不同。
flowchart TB
subgraph Hosts["宿主层"]
Studio["Agent Studio"]
CLI["CLI / 其他客户端"]
IDEA["future Lithe-IDEA"]
end
Agentd["lithe-agentd<br/>协议分发与能力组装"]
subgraph Kernel["微内核层：lithe-runtime"]
Registry["Capability Registry<br/>注册、发现、route 解析"]
Executor["Session Executor<br/>绑定校验、取消、运行控制"]
Loop["Agent Loop<br/>模型与工具迭代"]
Events["Session Events<br/>有序记录与重放"]
end
subgraph Capabilities["可替换 Capability 实现"]
Provider["Provider Adapter<br/>OpenAI / DeepSeek / Echo"]
Tools["Tools<br/>Echo / future plugins"]
Store["Session Store<br/>Memory / future durable stores"]
Policies["Policies / Sandbox / Telemetry<br/>规划中"]
end
Protocol["lithe-protocol<br/>版本化 DTO、错误与事件契约"]
Studio -->|"versioned requests"| Agentd
CLI -->|"versioned requests"| Agentd
IDEA -->|"future host bridge"| Agentd
Agentd --> Registry
Agentd --> Executor
Executor --> Registry
Executor --> Loop
Loop --> Provider
Loop --> Tools
Executor --> Store
Executor --> Events
Policies -.->|"future capability routes"| Executor
Protocol -.->|"定义通信与领域契约"| Agentd
Protocol -.->|"定义稳定类型"| Kernel
上图描述的是一次运行中的调用关系。Rust crate 的编译依赖方向与调用方向并不完全相同；下图的箭头表示“左侧依赖右侧”：
flowchart LR
Host["Studio / CLI / future IDE hosts"] --> Agentd["lithe-agentd"]
Agentd --> Runtime["lithe-runtime"]
Agentd --> OpenAI["lithe-provider-openai"]
Agentd --> DeepSeek["lithe-provider-deepseek"]
Agentd --> Protocol["lithe-protocol"]
OpenAI --> Runtime
OpenAI --> HTTP["lithe-provider-http"]
OpenAI --> Protocol
DeepSeek --> Runtime
DeepSeek --> HTTP
DeepSeek --> Protocol
Runtime --> Protocol
lithe-protocol 不依赖 Runtime 或任何 Provider；应用入口负责选择具体实现，Runtime 本身不硬编码产品组合。
- Host 启动
lithe-agentd，通过initialize完成协议版本协商。 - Host 使用
capability.register注册本次进程可用的 Loop、Provider、Tool 和 Session Store 路由。 - Host 可以通过
capability.list查询 Registry，Studio 的 Provider、模型和 Tool 列表也来自这里。 - Host 发送
session.run，显式指定每类 Capability 的 route、模型和运行参数。 - Runtime 从 Registry 获取不可变的路由快照，并验证绑定、模型、工具和 Loop 上限。
- 选中的 Agent Loop 调用 Provider；如果模型请求 Tool，Loop 执行 Tool 后把结果送回 Provider，直到完成或达到上限。
- Session Store 按顺序记录输入、模型调用、工具调用、输出或失败事件。
- Sidecar 返回最终消息和有序
SessionEvent；缺少能力、重复运行或配置错误会返回稳定错误，而不是自动换实现。
当前协议请求和结果示例位于：
| 路径 | 当前职责 | 边界 |
|---|---|---|
src/crates/lithe-protocol |
版本化 wire DTO、ID、消息、Capability 注册与绑定、Graph / Plugin 文档、稳定错误、Session Event | 最稳定的公共契约，不依赖 Runtime 和 Adapter |
src/crates/lithe-runtime |
Capability trait、分类 Registry、route 解析、有界 Agent Loop、取消、Memory Store、事件重放和确定性测试实现 | 只依赖 Protocol，不知道 OpenAI、DeepSeek 或 UI |
src/crates/lithe-provider-http |
SecretRef 解析和可注入 HTTP Transport | 复用网络与凭证边界，不拥有 Agent 语义 |
src/crates/lithe-provider-openai |
将统一 Provider 能力映射到 OpenAI Responses API | Provider 专属 payload 留在 Adapter 内部 |
src/crates/lithe-provider-deepseek |
将统一 Provider 能力映射到 DeepSeek Chat Completions API | 不向 Runtime 泄漏供应商类型 |
src/crates/lithe-agentd |
stdio NDJSON sidecar、请求分发、内置能力和 Adapter 组装 | Composition Root；决定当前进程实际提供什么 |
src/studio |
浏览器对话工作区、Agent 配置无限画布、Node Host Bridge | UI 布局和草稿不是 Runtime Graph |
scripts |
Studio 启动和仓库检查入口 | 开发辅助，不参与 Runtime 执行 |
.agent |
产品计划、迭代记录和仓库开发约束 | 设计文档，不是产品运行时 |
这样的拆分不是为了制造 crate 数量，而是为了守住三个关键边界：
- 协议可以独立演进：IDE、sidecar 和插件围绕稳定 DTO 协作。
- Runtime 不依赖具体服务：增加 Provider 或 Storage 不需要修改内核语义。
- 宿主只负责组合和交互：Studio 的画布布局不会直接污染可执行 Graph。
- 通过版本化 NDJSON 请求执行
initialize、capability.register、capability.list、capability.unregister和session.run。 - 分别注册和解析
provider.model、agent.loop、storage.session-events与tool。 - 每次运行显式绑定 Capability route，不依赖隐式默认实现。
- 使用有界 Agent Loop 完成模型调用、Tool round trip、最大步数校验和重复运行保护。
- 生成并重放有序
SessionEvent，使用进程内 Memory Store 保存当前会话事件。 - 使用确定性的
echo-round-tripProvider 和echoTool 完成完全离线测试。 - 通过第一方 Adapter 调用 OpenAI Responses API 和 DeepSeek Chat Completions API。
- 只在实际执行时通过 SecretRef 解析 Provider 环境变量，不把密钥写入配置和事件。
- 在 Studio 中进行真实对话、动态发现 Registry 能力，并查看 Runtime 事件轨迹。
- 在 Studio 的 Agent 设置中使用无限画布平移、缩放、适配和编排 Agent Loop 配置。
下面这些是明确的后续工作，不应从当前原型中误判为已经完成：
- 完整插件系统：尚无插件包安装、Supervisor、健康检查、EffectScope、route lease、drain、rollback 和 hot unload。
- 第三方隔离宿主：尚无 WASM Component 或受监管 subprocess 插件 Host。
- 可执行可视化 Graph：Studio 已有无限画布和 graph-shaped 草稿，但节点与边还不会编译为 Runtime 执行计划。
- Graph Compiler：尚无从
GraphDocument到不可变RuntimePlan的校验、编译和执行链路。 - 策略能力：输入 Policy、输出 Policy、审批流和 Sandbox 仍在规划中。
- 持久化能力：当前 Session Store 只在进程内；SQLite、远程存储和跨进程恢复尚未实现。
- 流式执行：Provider 当前是同步、非流式完成；实时事件通知和可取消的在途 HTTP 流尚未实现。
- 正式 IDE 集成：尚未完成 Lithe-IDEA、Tauri 或 WKWebView 的生产级 Host Bridge、权限代理和打包。
最重要的边界是：Studio 里的无限画布目前是 Agent 配置界面，不是已经可以执行的 Runtime Graph 编辑器。 UI 坐标、视口和布局必须继续与可执行 Graph 语义分离。
需要 Rust 1.85+ 和 Node.js。Studio 本身没有第三方前端依赖，不需要执行 npm install。
./scripts/run-studio.sh脚本会启动本地 Host Bridge，等待健康检查通过，然后打开 http://127.0.0.1:4173。按 Ctrl+C 停止。
不自动打开浏览器：
LITHE_STUDIO_NO_OPEN=1 ./scripts/run-studio.sh修改端口：
LITHE_STUDIO_PORT=5173 ./scripts/run-studio.sh浏览 Provider 和编辑 Agent 配置不需要 API Key。发起真实模型请求前设置对应环境变量：
export OPENAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."更多 Studio 操作和当前 UI 边界见 src/studio/README_ZH.md。
cargo run -p lithe-agentd --lockedlithe-agentd 从 stdin 按行读取 JSON 请求，并向 stdout 按行返回 JSON 响应。客户端需要先初始化、注册 Capability，再发送带显式 bindings 的 session.run。如果依赖已经在本机缓存，可以追加 --offline。
Provider 的注册字段、凭证引用和手工调用说明见 docs/providers.md。
./scripts/check.sh该脚本依次执行：
cargo fmt --all -- --checkcargo clippy --workspace --all-targets --all-features --locked --offline -- -D warningscargo test --workspace --locked --offlinenpm --prefix src/studio run check
只检查 Studio：
npm --prefix src/studio run check当前：最小纵向 Agent Runtime
↓
Capability 生命周期与插件 Supervisor
↓
GraphDocument 校验与 RuntimePlan 编译
↓
可调试、可取消、事件驱动的 Graph 执行
↓
Lithe-IDEA / Tauri / WKWebView 正式集成
↓
第三方 Provider、Tool、Storage 与 Policy 插件生态
路线图的原则不是把所有功能都塞进 Runtime，而是逐步稳定微内核必须拥有的语义，让其余能力可以安全地注册、替换、组合和卸载。