diff --git a/README.md b/README.md index c286ca2..ebb6663 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ inspect runtime state, and resume the thread later from durable local history. It is not just a chat UI. ExAgent includes the runtime pieces needed for recoverable agent work: event replay, persistent shell sessions, approval-gated -tools, subagents, goal tracking, procedural memory, MCP tools, and a desktop -inspector for what the agent is doing. +tools, subagents, goal tracking, project memory, MCP tools, workflow runs, and +a desktop inspector for what the agent is doing. ## Highlights @@ -34,7 +34,10 @@ inspector for what the agent is doing. - Durable sessions that can be reopened from local project history - GUI provider setup for API-key and OAuth-based model providers - Approval-gated coding tools with live transcript and event inspection -- Persistent shells, subagents, goals, MCP tools, and `SKILL.md` support +- Project memory with automatic recall, explicit memory tools, local curation, + and audit state +- Persistent shells, subagents, goals, MCP tools, workflows, and `SKILL.md` + support ## Download @@ -78,6 +81,33 @@ or file mutation, the app shows an approval card in the transcript. For a fuller operator walkthrough, see [docs/demo/exagent-walkthrough.md](docs/demo/exagent-walkthrough.md). +## Architecture At A Glance + +ExAgent is organized around a local Rust runtime exposed to the desktop through +a typed app-server boundary. The Tauri shell stays project-aware while the +runtime owns thread execution, model calls, tools, state, and live events. + +- Each thread runs behind an actor-backed `ThreadRuntime`, so turns are + serialized while snapshots, status, and events stream back to the GUI. +- `ThreadSession` assembles the long-lived pieces for one thread: agent, + context, rollout storage, tools, goals, memory, policy, and execution + sessions. +- The context layer keeps real conversation history separate from prompt-only + internal context such as memory recall, goal state, skills, and project docs; + compaction can replace long history with structured summaries. +- Local durability is append-first: each thread has a `rollout.jsonl` ledger, + while `IndexDb` stores cross-thread indexes for projects, threads, goals, + memory, and review state. +- The tool system separates public tool contracts in `src/tools` from per-turn + runtime orchestration in `src/runtime/tool`; agent policy gates both tool + visibility and execution. +- The memory system supports automatic prompt recall, explicit memory tools, + candidate saves, local promotion/archive/forget flows, and audit state. +- The model layer normalizes provider-specific APIs into ExAgent conversation, + tool-call, multimodal, reasoning, and streaming types. +- The workflow runtime powers structured runs such as deep search as a + phase-based scheduler parallel to the normal chat turn loop. + ## Development Useful commands from `apps/desktop`: @@ -115,11 +145,23 @@ Current non-goals: - [apps/desktop](apps/desktop): Tauri desktop shell and React workbench - [apps/desktop/src-tauri](apps/desktop/src-tauri): desktop Rust commands, settings, provider auth, and Tauri entrypoint +- [src/app_server](src/app_server): typed desktop/runtime boundary, request + processors, live views, and projections - [src/runtime](src/runtime): live execution kernel, thread actor, session turn loop, agent sampling, tool runtime, policy, and exec sessions +- [src/runtime/agent_profile](src/runtime/agent_profile): agent role catalog + and capability policy +- [src/runtime/goal](src/runtime/goal): structured goal state, accounting, and + continuation effects +- [src/runtime/memory](src/runtime/memory): runtime memory bridge into context + and tools +- [src/runtime/workflow](src/runtime/workflow): structured workflow and deep + search runtime - [src/tools](src/tools): tool trait, registry, and built-in coding tools -- [src/state](src/state): durable rollout models plus desktop index storage +- [src/state](src/state): durable rollout models, desktop index storage, and + memory state - [src/model](src/model): model provider adapters and conversation types +- [src/mcp](src/mcp): MCP configuration and tool integration - [tests](tests): integration coverage for runtime, protocol, policy, tools, and storage - [docs/demo](docs/demo): desktop-first walkthroughs diff --git a/README.zh-CN.md b/README.zh-CN.md index b883f0b..8393386 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -20,7 +20,7 @@ ExAgent 是一个桌面优先的代理工作台，底层是 Rust 运行时，桌面应用使用 Tauri 和 React 构建。它面向本地项目里的长时间编码工作：启动会话、选择 provider/model、审批工具动作、检查运行时状态，并在之后从本地持久历史中恢复线程。 -它不只是一个聊天 UI。ExAgent 包含可恢复代理工作的运行时能力：事件回放、持久 shell 会话、带审批的工具、子代理、目标跟踪、过程记忆、MCP 工具，以及用于观察代理行为的桌面检查器。 +它不只是一个聊天 UI。ExAgent 包含可恢复代理工作的运行时能力：事件回放、持久 shell 会话、带审批的工具、子代理、目标跟踪、项目记忆、MCP 工具、workflow runs，以及用于观察代理行为的桌面检查器。 ## 亮点 @@ -28,7 +28,8 @@ ExAgent 是一个桌面优先的代理工作台，底层是 Rust 运行时，桌 - 可从本地项目历史重新打开的持久会话 - 用 GUI 配置 API key 和 OAuth 模型 provider - 带审批的编码工具、实时 transcript 和事件检查 -- 持久 shell、子代理、目标、MCP 工具和 `SKILL.md` 支持 +- 项目记忆，支持自动 recall、显式 memory tools、本地治理和 audit state +- 持久 shell、子代理、目标、MCP 工具、workflows 和 `SKILL.md` 支持 ## 下载 @@ -64,6 +65,19 @@ npm run tauri:dev 更完整的操作 walkthrough 见 [docs/demo/exagent-walkthrough.md](docs/demo/exagent-walkthrough.md)。 +## 架构概览 + +ExAgent 围绕本地 Rust runtime 组织，并通过 typed app-server boundary 暴露给桌面端。Tauri shell 负责项目感知的桌面入口，runtime 负责 thread 执行、模型调用、工具、状态和实时事件。 + +- 每个 thread 都运行在 actor-backed `ThreadRuntime` 后面，因此同一 thread 的 turns 会被串行化，同时 snapshots、status 和 events 会流回 GUI。 +- `ThreadSession` 装配一个 thread 的长期运行部件：agent、context、rollout storage、tools、goals、memory、policy 和 execution sessions。 +- context 层把真实 conversation history 和 prompt-only internal context 分开；memory recall、goal state、skills、project docs 等只进入 prompt，compaction 可以把长历史替换成结构化摘要。 +- 本地持久化是 append-first：每个 thread 有自己的 `rollout.jsonl` ledger，`IndexDb` 存 projects、threads、goals、memory 和 review state 的跨线程索引。 +- tool system 把 `src/tools` 里的公开 tool contracts 和 `src/runtime/tool` 里的 per-turn runtime orchestration 分开；agent policy 同时约束工具可见性和执行权限。 +- memory system 支持自动 prompt recall、显式 memory tools、candidate saves、本地 promote/archive/forget 流程和 audit state。 +- model 层把不同 provider 的 API 统一成 ExAgent 内部的 conversation、tool-call、multimodal、reasoning 和 streaming 类型。 +- workflow runtime 以 phase-based scheduler 的方式运行 deep search 等结构化任务，它和普通 chat turn loop 是平行的执行模型。 + ## 开发 在 `apps/desktop` 下常用命令： @@ -99,10 +113,16 @@ ExAgent 仍处于早期阶段，当前主要面向个人工作站上的本地优 - [apps/desktop](apps/desktop)：Tauri 桌面 shell 和 React 工作台 - [apps/desktop/src-tauri](apps/desktop/src-tauri)：桌面 Rust commands、settings、provider auth 和 Tauri entrypoint +- [src/app_server](src/app_server)：typed desktop/runtime boundary、request processors、live views 和 projections - [src/runtime](src/runtime)：实时执行内核、thread actor、session turn loop、agent sampling、tool runtime、policy 和 exec sessions +- [src/runtime/agent_profile](src/runtime/agent_profile)：agent role catalog 和 capability policy +- [src/runtime/goal](src/runtime/goal)：structured goal state、accounting 和 continuation effects +- [src/runtime/memory](src/runtime/memory)：runtime memory bridge，负责接入 context 和 tools +- [src/runtime/workflow](src/runtime/workflow)：structured workflow 和 deep search runtime - [src/tools](src/tools)：tool trait、registry 和内置编码工具 -- [src/state](src/state)：持久 rollout model 和桌面 index storage +- [src/state](src/state)：持久 rollout model、桌面 index storage 和 memory state - [src/model](src/model)：模型 provider adapters 和 conversation types +- [src/mcp](src/mcp)：MCP configuration 和 tool integration - [tests](tests)：runtime、protocol、policy、tools 和 storage 的集成测试 - [docs/demo](docs/demo)：桌面优先 walkthrough