first commit
This commit is contained in:
513
atlas-zero-agent-design.md
Normal file
513
atlas-zero-agent-design.md
Normal file
@@ -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。
|
||||
Reference in New Issue
Block a user