From 05bf02bf1deecbd19fcee7d7d8171c274f0da054 Mon Sep 17 00:00:00 2001
From: "guangfei.zhao" <guangfei.zhao@t-systems.com>
Date: Tue, 21 Apr 2026 23:16:39 +0800
Subject: [PATCH] first commit

---
 README.md                  |  41 +++
 atlas-zero-agent-design.md | 513 +++++++++++++++++++++++++++++++++++++
 2 files changed, 554 insertions(+)
 create mode 100644 README.md
 create mode 100644 atlas-zero-agent-design.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6e9a43a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# Atlas Zero Agent
+
+`Atlas Zero Agent` 是一个通用的 chatbox agent 项目，目标是结合 `LangChain` 的组件化能力与更偏 agent runtime 的任务执行特性，构建一个可扩展、可编排、可观测的智能体系统。
+
+## Goals
+
+- 通用聊天入口
+- 多 agent 协同
+- 工具调用与任务执行
+- Memory 与 RAG
+- FastAPI 服务化
+- 可观测与可治理
+
+## Agent Naming
+
+项目使用《海贼王》蛋头岛 `Vegapunk satellites` 的命名体系：
+
+- `Stella`: 主控入口
+- `Atlas`: 执行型 agent
+- `Edison`: 规划与编排 agent
+- `Pythagoras`: 记忆与知识 agent
+- `Shaka`: 安全与规则 agent
+- `Lilith`: 探索与实验 agent
+- `York`: 资源与成本 agent
+
+## Docs
+
+- 设计草案：`atlas-zero-agent-design.md`
+
+## Planned Stack
+
+- `FastAPI`
+- `LangChain`
+- `LangGraph`
+- `PostgreSQL`
+- `Redis`
+- `pgvector`
+
+## Status
+
+当前仓库处于早期设计阶段，优先完善架构、agent 分工与最小可运行骨架。
diff --git a/atlas-zero-agent-design.md b/atlas-zero-agent-design.md
new file mode 100644
index 0000000..8d29a4e
--- /dev/null
+++ b/atlas-zero-agent-design.md
@@ -0,0 +1,513 @@
+# Atlas Zero Agent 设计草案
+
+## 1. 项目目标
+
+`atlas-zero-agent` 目标是做成一个通用的 `chatbox agent` 平台：
+
+- 对用户来说，它首先是一个好用的聊天入口，支持普通对话、工具调用、长期上下文和知识检索。
+- 对系统来说，它不只是一个单轮聊天接口，而是一个可编排、可扩展、可观测的 agent runtime。
+- 对工程实现来说，它希望同时吸收 `LangChain` 的组件化能力，以及 `harness agent` 一类系统在任务执行、工具编排、状态管理上的特性。
+
+一句话定位：
+
+> 一个以聊天为入口、以 agent runtime 为核心、以多人格分工为产品语言的通用智能体系统。
+
+## 2. 贝加庞克分身设定
+
+《海贼王》蛋头岛篇里，贝加庞克把自己的不同人格侧面拆成了多个 `satellites`。本体叫 `Stella`，分身共有 6 个：
+
+- `Shaka`
+- `Lilith`
+- `Edison`
+- `Pythagoras`
+- `Atlas`
+- `York`
+
+这些分身本质上不是完全独立的新角色，而是同一个超级科学家不同侧面的拆分与外化。这一点和 agent 设计非常契合，因为一个完整 agent 往往也会被拆成：规划、执行、记忆、安全、探索、资源调度等不同能力模块。
+
+## 3. 分身名称、性格与来源
+
+下面的“来源”分两层理解：
+
+- 第一层是 `One Piece` 设定中的人格侧面。
+- 第二层是角色名字在现实世界中可能对应的神话、历史人物、哲学家或文化意象。
+
+需要说明的是：作品中“人格职责”是明确设定；而“名字来源”很多属于高概率命名致敬或常见解读，不一定都有作者正式逐条说明。
+
+### 3.1 Shaka
+
+- 作品内定位：`Good`，代表“善”
+- 角色气质：冷静、克制、规则感强、像总控和秩序维护者
+- 常见名字来源解读：
+  - 最常见的理解是来自 `Shaka`，也就是日语中对释迦牟尼的称呼之一，关联佛教中的理性、觉悟、秩序与道德判断。
+  - 也有一些二级解读会联系到其他历史人物或天体命名，但核心印象仍然是“理性、正面、克制”。
+- 适合映射的 agent 角色：
+  - 安全策略 agent
+  - 系统规则 agent
+  - 审核与 guardrails agent
+  - 风险判定 agent
+
+为什么适合：
+
+- 一个通用 chat agent 不能只有能力，还必须有边界。
+- `Shaka` 很适合做“是否允许继续执行”“是否触发敏感操作确认”“是否需要降级回答”的决策层。
+
+### 3.2 Lilith
+
+- 作品内定位：`Evil`，代表“恶”
+- 角色气质：激进、冒险、追求结果、手段不那么保守
+- 常见名字来源解读：
+  - `Lilith` 在美索不达米亚与犹太传统里常被视为带有黑暗、反叛、原初女性恶魔等色彩的形象。
+  - 在现代流行文化中，`Lilith` 也常被用来代表“不服从、危险、诱惑、边界突破”。
+- 适合映射的 agent 角色：
+  - 探索型 agent
+  - 实验型 agent
+  - 自主搜索与假设验证 agent
+  - “尝试不同路径” 的发散 agent
+
+为什么适合：
+
+- 很多 agent 系统失败，不是因为不会回答，而是不会“试”。
+- `Lilith` 可以承担更激进的探索任务，例如多路搜索、失败重试、方案比较、信息侦察。
+- 但她不应拥有最终批准权，最好受 `Shaka` 约束。
+
+### 3.3 Edison
+
+- 作品内定位：`Think`，代表“想”
+- 角色气质：灵感驱动、发明导向、快速出点子
+- 常见名字来源解读：
+  - 明确对应现实中的发明家 `Thomas Edison`。
+  - 象征发明、工程实现、原型驱动、把抽象想法落成机制。
+- 适合映射的 agent 角色：
+  - 规划型 agent
+  - 工具编排 agent
+  - 工作流生成 agent
+  - 任务分解与步骤生成 agent
+
+为什么适合：
+
+- 你的系统如果想兼具 `LangChain` 与 harness 风格，就需要一个专门负责“把用户目标转为可执行步骤”的角色。
+- `Edison` 很适合做 planner，决定先检索、再调用工具、再总结，或者什么时候需要拆任务并回写状态。
+
+### 3.4 Pythagoras
+
+- 作品内定位：`Wisdom`，代表“知”
+- 角色气质：整理、分析、汇总、把知识结构化
+- 常见名字来源解读：
+  - 明确对应古希腊哲学家、数学家 `Pythagoras`。
+  - 象征数学、结构、抽象、归纳、规律与知识体系。
+- 适合映射的 agent 角色：
+  - 知识库 agent
+  - `RAG` agent
+  - memory agent
+  - 数据分析与事实整理 agent
+
+为什么适合：
+
+- 一个“通用 chatbox agent”如果没有稳定的记忆和知识管理，就很容易变成只会临场生成文本的壳。
+- `Pythagoras` 非常适合负责检索、重排、引用、会话摘要、长期记忆写入与知识组织。
+
+### 3.5 Atlas
+
+- 作品内定位：`Violence`，代表“暴”
+- 角色气质：行动直接、执行果断、解决问题优先
+- 常见名字来源解读：
+  - 最直观来源是希腊神话中的巨人 `Atlas`，常见印象是“扛起天空的人”。
+  - 这个名字还有“地图册、承载世界结构”的延伸含义，但在角色气质上更突出的是力量、承担、推进。
+- 适合映射的 agent 角色：
+  - 执行型 agent
+  - 行动派 agent
+  - 工具调用 agent
+  - 任务落地 agent
+
+为什么适合：
+
+- 如果 `Edison` 负责想，`Atlas` 就负责做。
+- 她最适合做实际执行层，例如调用工具、跑工作流、操作外部服务、提交任务结果。
+- 对你的项目名来说，`Atlas` 也很强，因为它兼具力量感和工程执行感。
+
+### 3.6 York
+
+- 作品内定位：`Greed`，代表“欲”
+- 角色气质：偏向资源占用、需求满足、为整体系统承担身体性与消耗性工作
+- 常见名字来源解读：
+  - `York` 的来源没有前几个那么明确，常见解读并不统一。
+  - 从作品功能上看，她更像“欲望 / 需求 / 资源消耗”的人格化承载体。
+  - 也有一些解读会把它和天体、地名或科学人物关联，但都不如她在故事中的“欲望代理”功能重要。
+- 适合映射的 agent 角色：
+  - 资源调度 agent
+  - 队列与吞吐 agent
+  - 成本控制 agent
+  - 配额、缓存、优先级管理 agent
+
+为什么适合：
+
+- 一个能跑起来的 agent 系统，除了会想、会做，还要知道“资源够不够、应该先跑谁、哪个模型值得调用、要不要缓存”。
+- `York` 非常适合负责 token 成本、模型路由、任务队列、优先级、配额和后台任务管理。
+
+### 3.7 Stella
+
+- 作品内定位：本体
+- 名称含义：`Stella` 在拉丁语中有“星”之意
+- 适合映射的系统角色：
+  - 主控人格
+  - 对外统一身份
+  - 路由入口
+  - 多 agent 聚合层
+
+为什么适合：
+
+- 用户不一定需要直接知道背后有多少子 agent。
+- 对外可以统一叫 `Atlas Zero Agent`，内部再由 `Stella` 作为总入口路由到不同分身能力。
+
+## 4. 推荐的命名分工方案
+
+如果你准备把这套世界观真正用进产品，我建议不要把这些名字只当作皮肤，而是让它们对应真实职责。
+
+### 4.1 推荐的一号方案
+
+- `Stella`：主控入口 / orchestrator
+- `Atlas`：执行型 agent
+- `Edison`：规划与工具编排 agent
+- `Pythagoras`：记忆、RAG、知识整理 agent
+- `Shaka`：安全、审核、边界控制 agent
+- `Lilith`：探索、实验、侦察 agent
+- `York`：资源、成本、队列调度 agent
+
+这个方案的优点：
+
+- 人设和能力匹配度高。
+- 后续做多 agent 扩展时可自然拆模块。
+- 即使后面只实现其中 2 到 3 个角色，也不会浪费命名体系。
+
+### 4.2 适合你的产品表达方式
+
+对外产品文案可以写成：
+
+- `Atlas Zero` 是统一对话入口。
+- 内部由多个 `satellite agents` 协同工作。
+- 用户默认只看到一个 chatbox，但系统会自动路由到最合适的能力模块。
+
+这样既保留世界观，也不会把产品做得过度复杂。
+
+## 5. 项目架构建议
+
+你的目标不是单纯搭一个聊天接口，而是做一个“通用 agent 平台”。所以架构上建议分成六层。
+
+### 5.1 总体分层
+
+1. `Interface Layer`
+2. `Application Layer`
+3. `Agent Runtime Layer`
+4. `Knowledge and Memory Layer`
+5. `Tool and Integration Layer`
+6. `Observability and Governance Layer`
+
+### 5.2 各层职责
+
+#### Interface Layer
+
+建议技术：`FastAPI`
+
+职责：
+
+- 提供聊天接口
+- 提供流式响应接口，建议支持 `SSE`
+- 提供会话管理接口
+- 提供 agent 配置与调试接口
+- 未来可扩展 `WebSocket`
+
+建议接口：
+
+- `POST /api/chat`
+- `POST /api/chat/stream`
+- `GET /api/sessions/{session_id}`
+- `POST /api/sessions/{session_id}/messages`
+- `GET /api/agents`
+- `POST /api/agents/run`
+- `GET /api/health`
+
+#### Application Layer
+
+职责：
+
+- 处理 API 请求与响应模型
+- 维护会话上下文
+- 调用 orchestrator
+- 统一错误处理
+- 做鉴权、租户、多用户隔离
+
+这一层尽量不要直接写复杂推理逻辑，而是作为业务编排层。
+
+#### Agent Runtime Layer
+
+建议技术：`LangGraph` + `LangChain`
+
+职责：
+
+- 管理多 agent 状态流转
+- 管理 planner、executor、memory、safety 等节点
+- 支持可中断、可恢复、可追踪执行
+- 统一处理工具调用结果
+- 支持多步任务执行
+
+为什么这里建议 `LangGraph` 而不是只用 `LangChain`：
+
+- `LangChain` 适合组件和工具接线。
+- `LangGraph` 更适合处理 agent 的状态机、分支、恢复、checkpoint 和长任务。
+- 你的目标已经超出简单 chain，更接近一个小型 runtime。
+
+#### Knowledge and Memory Layer
+
+职责：
+
+- 会话短期记忆
+- 用户长期记忆
+- 文档知识库检索
+- 摘要压缩
+- 事实缓存和向量检索
+
+建议拆成三类存储：
+
+- `Session Store`：保存对话消息和运行状态
+- `Memory Store`：保存用户长期偏好、画像、任务历史
+- `Vector Store`：保存 RAG 文档嵌入和检索索引
+
+适合由 `Pythagoras` 主导。
+
+#### Tool and Integration Layer
+
+职责：
+
+- 封装本地工具
+- 封装外部 API
+- 封装搜索、数据库、文件、浏览器等工具
+- 统一工具协议和权限边界
+
+这层适合由 `Atlas` 执行、由 `Edison` 编排。
+
+如果后面要做得更像现代 agent 平台，可以预留：
+
+- `MCP` 兼容层
+- sandbox 执行层
+- 第三方 connectors
+
+#### Observability and Governance Layer
+
+职责：
+
+- trace
+- prompt 版本管理
+- tool call 日志
+- token 和成本统计
+- 审计与安全策略
+- 人工接管与审批
+
+这层很关键，因为真正可用的 agent 系统一定需要可观测性，而不是只有“能回话”。
+
+`Shaka` 和 `York` 最适合共同负责这一层。
+
+## 6. 推荐的内部多 agent 结构
+
+如果以“单 chatbox，多内部人格”的方式实现，建议这样组织：
+
+### 6.1 最小闭环版本
+
+- `Stella Router`
+- `Edison Planner`
+- `Atlas Executor`
+- `Pythagoras Memory`
+- `Shaka Guard`
+
+这是最适合第一阶段落地的组合。
+
+对应流程：
+
+1. 用户输入进入 `Stella Router`
+2. `Shaka Guard` 先做风险检查与权限判断
+3. `Edison Planner` 生成执行步骤
+4. `Pythagoras Memory` 补充上下文、检索记忆与知识
+5. `Atlas Executor` 调用工具或执行动作
+6. `Stella Router` 汇总结果并输出给用户
+
+### 6.2 第二阶段扩展
+
+新增：
+
+- `Lilith Explorer`
+- `York Resource Manager`
+
+用途：
+
+- `Lilith` 用于多路探索、网络搜索、候选方案试探、故障 fallback
+- `York` 用于模型路由、预算控制、优先级与后台任务调度
+
+## 7. 推荐的目录结构
+
+如果你准备用 `FastAPI + LangGraph + LangChain`，我建议从下面这个目录开始，而不是一上来就堆太多文件。
+
+```text
+atlas-zero-agent/
+  app/
+    api/
+      routes/
+        chat.py
+        sessions.py
+        agents.py
+      schemas/
+        chat.py
+        session.py
+        agent.py
+    core/
+      config.py
+      logging.py
+      security.py
+    runtime/
+      orchestrator.py
+      state.py
+      graph.py
+    agents/
+      stella.py
+      atlas.py
+      edison.py
+      pythagoras.py
+      shaka.py
+      lilith.py
+      york.py
+    memory/
+      session_store.py
+      memory_store.py
+      vector_store.py
+      summarizer.py
+    tools/
+      registry.py
+      web_search.py
+      browser.py
+      filesystem.py
+      knowledge.py
+    services/
+      chat_service.py
+      session_service.py
+      agent_service.py
+    observability/
+      tracing.py
+      metrics.py
+      audit.py
+    main.py
+  docs/
+    architecture.md
+    agents.md
+  tests/
+    test_chat_api.py
+    test_runtime_flow.py
+    test_memory.py
+  pyproject.toml
+  README.md
+```
+
+这个结构的重点：
+
+- `api` 只管接口
+- `runtime` 只管状态流转和 orchestrator
+- `agents` 只放角色级逻辑
+- `memory` 和 `tools` 独立，方便后续扩展
+- `observability` 独立，避免后期难补
+
+## 8. 推荐的技术栈
+
+### 8.1 后端核心
+
+- `FastAPI`：对外 API
+- `Pydantic`：请求响应模型与配置
+- `LangChain`：模型、prompt、tools、retriever 抽象
+- `LangGraph`：多 agent 编排与状态管理
+- `Uvicorn`：服务运行
+
+### 8.2 存储层
+
+- `PostgreSQL`：会话、用户、任务、审计
+- `Redis`：缓存、队列、短期状态
+- `pgvector` 或独立向量库：RAG 检索
+
+### 8.3 观测层
+
+- `LangSmith`：链路追踪和调试
+- `OpenTelemetry`：统一 trace/metrics
+- `Prometheus` + `Grafana`：运行指标
+
+### 8.4 前端
+
+- 如果先做后端验证：先不急着做复杂前端
+- 如果要快速出 chatbox：
+  - `Next.js`
+  - 或直接参考 `langchain-ai/agent-chat-ui`
+
+## 9. 产品能力建议
+
+你说的是“通用 chatbox agent”，那我建议第一版不要贪多，优先做下面这些能力：
+
+### 第一阶段必须有
+
+- 多轮对话
+- 流式输出
+- session 持久化
+- 工具调用
+- 基础 RAG
+- 安全拦截
+- trace 日志
+
+### 第二阶段再加
+
+- 多 agent 协同
+- 用户长期记忆
+- 文件上传解析
+- 后台异步任务
+- 模型路由
+- 成本统计与预算限制
+
+### 第三阶段再加
+
+- 人工审批
+- MCP 工具接入
+- 插件市场
+- 多租户
+- 可视化工作流
+
+## 10. 命名建议结论
+
+如果你希望这个项目既有故事感，又能长期演化，我建议这样定：
+
+- 项目总名：`atlas-zero-agent`
+- 对外产品名：`Atlas Zero`
+- 内部 orchestrator：`Stella`
+- 核心执行 agent：`Atlas`
+- 规划 agent：`Edison`
+- 记忆与知识 agent：`Pythagoras`
+- 安全与审查 agent：`Shaka`
+- 探索与实验 agent：`Lilith`
+- 资源与预算 agent：`York`
+
+这样命名的好处是：
+
+- 有统一世界观
+- 每个名字都有明确职责
+- 后续做文档、UI、日志、trace 时都很好表达
+- 未来如果你要把系统从单 agent 进化到多 agent，也不需要重命名
+
+## 11. 最推荐的启动路线
+
+如果现在就开始做，我建议按这个顺序推进：
+
+1. 先做 `FastAPI` 聊天接口和 `SSE` 流式输出
+2. 接入一个基础 `LangChain` chat model
+3. 用 `LangGraph` 搭建 `Stella -> Shaka -> Edison -> Pythagoras -> Atlas` 的最小图
+4. 接入 session store 和基础 memory
+5. 接入 2 到 3 个最常用工具
+6. 增加 trace、审计和成本统计
+7. 最后再扩展 `Lilith` 和 `York`
+
+## 12. 一句话设计原则
+
+`Atlas Zero` 不应该只是“会聊天的模型壳”，而应该是：
+
+> 以 `Atlas` 为执行核心、以 `Stella` 为统一入口、以多分身协作为内部机制的通用 agent runtime。