# 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。