From 5b4d6b1d2ef6a1d24b663c218a1c32d86e6da5b7 Mon Sep 17 00:00:00 2001
From: "guangfei.zhao" <guangfei.zhao@t-systems.com>
Date: Tue, 21 Apr 2026 23:35:44 +0800
Subject: [PATCH] docs: update README and architecture

---
 README.md            | 113 ++++++++--
 docs/architecture.md | 491 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 583 insertions(+), 21 deletions(-)
 create mode 100644 docs/architecture.md

diff --git a/README.md b/README.md
index 6e9a43a..7f8039c 100644
--- a/README.md
+++ b/README.md
@@ -1,41 +1,112 @@
 # Atlas Zero Agent
 
-`Atlas Zero Agent` 是一个通用的 chatbox agent 项目，目标是结合 `LangChain` 的组件化能力与更偏 agent runtime 的任务执行特性，构建一个可扩展、可编排、可观测的智能体系统。
+`Atlas Zero Agent` 是一个面向通用对话场景的 `chatbox agent` 项目。
 
-## Goals
+它以聊天作为统一入口，内部通过多 agent 协作完成规划、执行、知识检索、记忆管理、安全审查和资源调度，目标是做成一个可扩展、可服务化、可观测的 agent runtime，而不是一个只会单轮回答的聊天壳。
 
-- 通用聊天入口
-- 多 agent 协同
-- 工具调用与任务执行
-- Memory 与 RAG
-- FastAPI 服务化
-- 可观测与可治理
+## Vision
 
-## Agent Naming
+- 一个对外统一的聊天入口
+- 一个对内可编排的 agent runtime
+- 一套可持续扩展的 memory、RAG 与 tools 体系
+- 一套适合产品化落地的 API、状态管理与治理能力
 
-项目使用《海贼王》蛋头岛 `Vegapunk satellites` 的命名体系：
+## Core Ideas
 
-- `Stella`: 主控入口
-- `Atlas`: 执行型 agent
-- `Edison`: 规划与编排 agent
-- `Pythagoras`: 记忆与知识 agent
-- `Shaka`: 安全与规则 agent
-- `Lilith`: 探索与实验 agent
-- `York`: 资源与成本 agent
+- `Chatbox First`: 用户只面对一个自然的聊天入口
+- `Agent Runtime Inside`: 内部通过多个职责明确的 agents 协同工作
+- `FastAPI Native`: 后端优先采用服务化接口设计
+- `LangChain + LangGraph`: 用组件抽象连接模型、工具和知识，用状态图管理多步执行
+- `Observable by Default`: 从一开始就考虑 trace、审计、成本和运行状态
 
-## Docs
+## Agent Roles
 
-- 设计草案：`atlas-zero-agent-design.md`
+项目借用了《海贼王》蛋头岛 `Vegapunk satellites` 的命名体系，但这些名字不只是皮肤，而是对应真实职责：
+
+- `Stella`: 主控入口与 orchestrator
+- `Atlas`: 执行型 agent，负责工具调用和任务落地
+- `Edison`: 规划型 agent，负责步骤拆解与工具编排
+- `Pythagoras`: 知识与记忆 agent，负责 RAG、总结与长期上下文
+- `Shaka`: 安全与规则 agent，负责 guardrails、风险判定与权限控制
+- `Lilith`: 探索型 agent，负责多路搜索、试探和实验性路径
+- `York`: 资源型 agent，负责模型路由、配额、队列和成本控制
+
+## Architecture
+
+建议采用分层结构：
+
+- `Interface Layer`: `FastAPI` 对外接口、流式输出、会话 API
+- `Application Layer`: 请求编排、权限、会话上下文、服务层
+- `Agent Runtime Layer`: `LangGraph` 编排多 agent 状态流转
+- `Knowledge Layer`: session memory、long-term memory、RAG
+- `Tool Layer`: 本地工具、外部 API、未来的 `MCP` 接入
+- `Observability Layer`: trace、审计、指标、成本治理
+
+更详细的工程版设计见：
+
+- `atlas-zero-agent-design.md`
+- `docs/architecture.md`
 
 ## Planned Stack
 
 - `FastAPI`
+- `Pydantic`
 - `LangChain`
 - `LangGraph`
 - `PostgreSQL`
 - `Redis`
 - `pgvector`
+- `LangSmith` or `OpenTelemetry`
 
-## Status
+## API Direction
 
-当前仓库处于早期设计阶段，优先完善架构、agent 分工与最小可运行骨架。
+第一阶段建议优先做这些接口：
+
+- `POST /api/chat`
+- `POST /api/chat/stream`
+- `GET /api/sessions/{session_id}`
+- `POST /api/sessions/{session_id}/messages`
+- `GET /api/agents`
+- `GET /api/health`
+
+## Roadmap
+
+### Phase 1
+
+- 基础 chat API
+- 流式输出
+- session 持久化
+- 最小多 agent 执行链路
+- 基础 memory 与 RAG
+
+### Phase 2
+
+- 多 agent 扩展
+- 用户长期记忆
+- 文件上传与知识入库
+- 模型路由与预算控制
+- 更完整的 observability
+
+### Phase 3
+
+- 异步任务与队列
+- 人工审批
+- `MCP` 工具接入
+- 多租户与插件化
+
+## Current Status
+
+当前仓库处于设计和骨架规划阶段，重点先明确：
+
+- 命名体系
+- agent 职责边界
+- runtime 架构
+- API 设计
+- 最小可运行实现路径
+
+## Repository Notes
+
+- 设计草案：`atlas-zero-agent-design.md`
+- 工程架构：`docs/architecture.md`
+
+后续可以从一个最小闭环开始：`Stella -> Shaka -> Edison -> Pythagoras -> Atlas`。
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..9f3b3be
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,491 @@
+# Architecture
+
+## Overview
+
+`Atlas Zero Agent` 采用“单 chatbox 入口 + 多 agent 内部协作”的架构。
+
+对外，系统暴露为一个统一的聊天服务；对内，系统通过 `Stella` orchestrator 把请求分发给不同职责的 agent 节点，结合 `LangGraph` 管理状态流转，结合 `LangChain` 管理模型、工具、检索器和提示词。
+
+工程目标有三点：
+
+- 让 chat 成为统一入口
+- 让 agent runtime 成为核心执行层
+- 让 memory、tools、observability 从一开始就是一等公民
+
+## Design Goals
+
+- 支持通用聊天与多轮对话
+- 支持工具调用与多步任务执行
+- 支持短期记忆、长期记忆与知识检索
+- 支持流式输出和可恢复执行
+- 支持成本、权限、审计和 trace 管理
+- 支持后续扩展到多租户和插件体系
+
+## High-Level Architecture
+
+```text
+Client / UI
+  -> FastAPI API Layer
+  -> Application Services
+  -> Stella Orchestrator
+  -> LangGraph Runtime
+     -> Shaka Guard
+     -> Edison Planner
+     -> Pythagoras Memory / RAG
+     -> Atlas Executor
+     -> Lilith Explorer
+     -> York Resource Manager
+  -> Tool Layer / Memory Layer / Model Layer
+  -> Persistence + Observability
+```
+
+## Layered Architecture
+
+### 1. Interface Layer
+
+职责：
+
+- 对外暴露 HTTP API
+- 提供同步与流式聊天接口
+- 提供会话查询与管理接口
+- 提供健康检查、调试和管理接口
+
+建议技术：
+
+- `FastAPI`
+- `Pydantic`
+- `SSE`，后续可选 `WebSocket`
+
+建议目录：
+
+- `app/api/routes/`
+- `app/api/schemas/`
+
+这一层只处理：
+
+- 请求解析
+- 参数校验
+- 响应序列化
+- 状态码和错误格式
+
+这一层不应该直接写复杂 agent 逻辑。
+
+### 2. Application Layer
+
+职责：
+
+- 接收 API 请求并转成应用层命令
+- 维护 session、user、tenant 上下文
+- 管理鉴权、限流、权限边界
+- 调用 orchestrator 与服务层
+
+建议目录：
+
+- `app/services/`
+- `app/core/`
+
+应用层负责解决“系统怎么接住一个请求”，而不是“模型怎么思考”。
+
+### 3. Agent Runtime Layer
+
+职责：
+
+- 管理多 agent 状态流转
+- 管理节点输入输出和共享状态
+- 管理 checkpoint、中断、恢复和回放
+- 统一 tool call、fallback 和 error routing
+
+建议技术：
+
+- `LangGraph`
+- `LangChain`
+
+建议目录：
+
+- `app/runtime/`
+- `app/agents/`
+
+核心设计原则：
+
+- 每个 agent 有清晰职责
+- 节点之间通过统一 `state` 共享信息
+- 最终只允许少数节点产生对用户可见的最终输出
+- 失败路径必须可观测、可恢复、可降级
+
+### 4. Knowledge and Memory Layer
+
+职责：
+
+- 保存当前会话消息
+- 保存长期用户偏好与任务历史
+- 提供知识库检索与重排
+- 提供对话摘要和记忆压缩
+
+建议拆成三类存储：
+
+- `Session Store`
+- `Memory Store`
+- `Vector Store`
+
+建议目录：
+
+- `app/memory/`
+
+建议原则：
+
+- 短期记忆和长期记忆分开建模
+- 检索上下文和用户消息分开处理
+- 避免把所有历史直接塞进 prompt
+- 优先通过摘要、选择性检索和结构化 memory 控制上下文长度
+
+### 5. Tool and Integration Layer
+
+职责：
+
+- 封装内部工具
+- 封装第三方 API
+- 控制工具权限与调用边界
+- 统一工具描述、输入和输出格式
+
+建议目录：
+
+- `app/tools/`
+
+工具层应该满足：
+
+- 可测试
+- 可复用
+- 可审计
+- 可在 runtime 中统一注册
+
+后续可预留：
+
+- `MCP` 接入
+- browser / search 工具
+- filesystem 工具
+- knowledge connectors
+
+### 6. Observability and Governance Layer
+
+职责：
+
+- 跟踪每次请求的执行链路
+- 记录 tool call、模型调用与成本
+- 记录安全拦截与人工审批事件
+- 输出 metrics、audit log 和 trace
+
+建议目录：
+
+- `app/observability/`
+
+建议技术：
+
+- `LangSmith`
+- `OpenTelemetry`
+- `Prometheus`
+- `Grafana`
+
+这个层不是后补件，而是 agent 系统能否产品化的关键部分。
+
+## Agent Topology
+
+### External Identity
+
+- `Atlas Zero`: 对外统一产品身份
+
+### Internal Roles
+
+- `Stella`: orchestrator / router
+- `Shaka`: safety and policy guard
+- `Edison`: planner and workflow builder
+- `Pythagoras`: memory and retrieval manager
+- `Atlas`: executor and tool runner
+- `Lilith`: exploration and fallback agent
+- `York`: resource and budget manager
+
+## Minimum Execution Flow
+
+第一阶段建议实现如下链路：
+
+```text
+User Message
+  -> API Layer
+  -> Session Service
+  -> Stella
+  -> Shaka
+  -> Edison
+  -> Pythagoras
+  -> Atlas
+  -> Stella Response Composer
+  -> Streaming / Final Response
+```
+
+各节点职责：
+
+- `Stella`: 创建运行上下文，决定是否直接回答还是进入执行链路
+- `Shaka`: 校验风险、权限和策略边界
+- `Edison`: 生成任务计划、决定工具和步骤
+- `Pythagoras`: 读取 session memory、long-term memory 和知识库
+- `Atlas`: 执行工具调用、收集结果、产出 observation
+- `Stella Response Composer`: 汇总结果并形成最终回答
+
+## Optional Extended Flow
+
+在第二阶段可扩展：
+
+```text
+Stella
+  -> Shaka
+  -> Edison
+  -> Pythagoras
+  -> Lilith
+  -> Atlas
+  -> York
+  -> Stella
+```
+
+扩展后的作用：
+
+- `Lilith`: 做多路探索、候选方案试探、失败路径补救
+- `York`: 做模型选择、预算控制、异步任务排队和优先级管理
+
+## Runtime State Model
+
+建议定义统一运行时状态对象，例如：
+
+```text
+RunState
+- run_id
+- session_id
+- user_id
+- tenant_id
+- input_message
+- messages
+- memory_context
+- retrieved_documents
+- plan
+- tool_calls
+- tool_results
+- safety_decision
+- final_response
+- status
+- started_at
+- finished_at
+- usage
+- errors
+```
+
+建议原则：
+
+- 所有节点都读写同一个共享状态模型
+- 用户可见输出和内部推理中间态要分开存储
+- 工具结果、检索结果、摘要结果要有明确字段
+- 状态对象需要可序列化，方便 checkpoint 和回放
+
+## API Design
+
+### Core Endpoints
+
+- `POST /api/chat`
+- `POST /api/chat/stream`
+- `GET /api/sessions/{session_id}`
+- `GET /api/sessions/{session_id}/messages`
+- `POST /api/sessions/{session_id}/messages`
+- `GET /api/agents`
+- `POST /api/agents/run`
+- `GET /api/runs/{run_id}`
+- `GET /api/health`
+
+### Example `POST /api/chat`
+
+Request:
+
+```json
+{
+  "session_id": "sess_123",
+  "message": "帮我总结这个项目的架构",
+  "agent": "atlas-zero",
+  "stream": false,
+  "metadata": {
+    "user_id": "user_001"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "run_id": "run_123",
+  "session_id": "sess_123",
+  "message": {
+    "role": "assistant",
+    "content": "..."
+  },
+  "usage": {
+    "input_tokens": 0,
+    "output_tokens": 0
+  },
+  "trace_id": "trace_123"
+}
+```
+
+### Example `POST /api/chat/stream`
+
+建议返回 `SSE` 事件流，事件类型可包括：
+
+- `run.started`
+- `message.delta`
+- `tool.started`
+- `tool.finished`
+- `retrieval.finished`
+- `run.completed`
+- `run.failed`
+
+这样前端不仅能展示文字流，还能展示 agent 执行过程。
+
+## Suggested Project Structure
+
+```text
+app/
+  api/
+    routes/
+      chat.py
+      sessions.py
+      agents.py
+      runs.py
+    schemas/
+      chat.py
+      session.py
+      run.py
+  core/
+    config.py
+    logging.py
+    security.py
+  runtime/
+    graph.py
+    orchestrator.py
+    state.py
+    checkpoints.py
+  agents/
+    stella.py
+    shaka.py
+    edison.py
+    pythagoras.py
+    atlas.py
+    lilith.py
+    york.py
+  memory/
+    session_store.py
+    memory_store.py
+    vector_store.py
+    summarizer.py
+  tools/
+    registry.py
+    search.py
+    browser.py
+    knowledge.py
+    filesystem.py
+  services/
+    chat_service.py
+    session_service.py
+    run_service.py
+  observability/
+    tracing.py
+    metrics.py
+    audit.py
+  main.py
+```
+
+## Persistence Design
+
+### Recommended Storage
+
+- `PostgreSQL`: sessions、messages、runs、audit logs
+- `Redis`: cache、rate limit、ephemeral state、queue metadata
+- `pgvector` or vector DB: embeddings、document chunks、memory retrieval
+
+### Minimum Tables
+
+- `users`
+- `sessions`
+- `messages`
+- `runs`
+- `tool_calls`
+- `documents`
+- `document_chunks`
+- `memories`
+- `audit_logs`
+
+## Security and Governance
+
+### Shaka Responsibilities
+
+- 敏感请求识别
+- 工具权限控制
+- 高风险动作审批
+- 输出降级和拒答
+
+### Governance Rules
+
+- 所有工具调用都必须可审计
+- 高风险工具必须支持 allowlist 或人工确认
+- 模型输出不直接代表工具执行成功
+- 用户输入、检索上下文、工具 observation 要分开处理
+
+## Observability
+
+每个 `run` 至少应采集：
+
+- `run_id`
+- `trace_id`
+- `session_id`
+- `agent path`
+- `model usage`
+- `tool usage`
+- `latency`
+- `cost`
+- `failure reason`
+
+建议从第一版就支持：
+
+- request tracing
+- prompt versioning
+- run replay
+- structured logs
+
+## Delivery Plan
+
+### Phase 1
+
+- `FastAPI` 基础骨架
+- `POST /api/chat` 与 `POST /api/chat/stream`
+- `Stella -> Shaka -> Edison -> Pythagoras -> Atlas` 最小链路
+- session 持久化
+- 基础 RAG
+
+### Phase 2
+
+- `Lilith` 扩展探索路径
+- `York` 模型路由和预算控制
+- 文件上传、文档切分与知识入库
+- 更完整的 trace 和 metrics
+
+### Phase 3
+
+- checkpoint 和 resume
+- async job queue
+- approval workflow
+- `MCP` compatibility
+- multi-tenant support
+
+## Non-Goals for Early Version
+
+第一阶段不建议过早投入：
+
+- 复杂可视化工作流编辑器
+- 过多 agent 角色同时上线
+- 过重的插件市场系统
+- 过早拆成微服务
+
+建议先把最小闭环跑通，再逐步扩展。