简介

AtlasAgent 是一套可运行的 AI Agent 控制平面与中文工程教程。它把原始事件、长期记忆、知识库检索、技能指引、工具调用、Artifact 和 Checkpoint 放进同一条可追溯链路，集中处理六个生产边界：事实从哪里来、记忆为什么可信、资料引用能否追溯、工具何时允许执行、任务如何恢复，以及每一步如何审计。

同一套 FastAPI 控制平面同时服务 Next.js Web（PWA）与 Textual TUI，并配有从基础服务到 Memory / RAG / Skill / Tool Control Plane 的 0–56 章教程（共 55 章）。

🎉 最近更新

• [2026.08] 🎯 步骤内多轮工具调用 + 原生 Function Calling：模型在单个步骤内自主多次调用工具、观察结果再决策，真正像 Agent 一样工作。
• [2026.08] 🎯 Web 端升级为 PWA：可安装到桌面 / 移动端，离线缓存应用外壳；移除 Electron 桌面客户端，收敛为 Web + TUI 双客户端。
• [2026.08] 🎯 任务失败后从断点续跑：复用已有计划、跳过已完成步骤，从失败处继续，不必从头再来。
• [2026.08] 🎯 直答分流与推理直播：普通问答直接流式回答，思考过程实时展示并可回看。
• [2026.08] 🎯 知识库自动召回 + 带引用作答：每轮对话自动召回相关文档并标注来源。
• [2026.08] 🎯 网页正文读取作答与工具自愈：补上读取真实网页正文的能力。

✨ 核心能力

🏗️ 运行机制

控制面的事实优先级很明确：原始事件与 Artifact 是事实源，任务状态是可重建的物化视图，Checkpoint 是经过验证的恢复点。

一次任务会沿着这条链路推进：

1. 创建带目标和验收标准的结构化任务。
2. 从候选记忆中筛选有来源、未过期且相关的事实。
3. 工具进入统一 Runtime，先经过风险、权限和幂等检查，再执行 handler。
4. 大输出转为内容寻址 Artifact，调用过程写入审计记录。
5. 状态哈希、环境指纹和校验报告共同生成可恢复 Checkpoint。

Plan / Execute / Reflect / Summarize 执行机

工具型对话使用项目内的、不依赖工作流框架的异步状态机推进；普通问答仍走直接流式回答。每个执行步骤内部，StepAgentLoop 驱动模型进行多轮工具调用，直到给出该步骤的结论。

flowchart LR
    subgraph Clients["客户端"]
        direction TB
        Web["Web · Next.js (PWA)"]
        TUI["TUI · Textual"]
    end

    Gateway["Nginx Gateway"]
    API["FastAPI Control Plane"]

    subgraph Runtime["Agent Runtime"]
        direction TB
        Planner["Planning & Events"]
        Loop["StepAgentLoop · 多轮工具调用"]
        Tools["Tool Runtime"]
        Memory["Memory & Checkpoints"]
    end

    subgraph Data["事实与基础设施"]
        direction TB
        Postgres["PostgreSQL"]
        Redis["Redis"]
        Sandbox["Sandbox & Artifacts"]
    end

    Web --> Gateway
    TUI --> API
    Gateway --> API
    API --> Planner
    API --> Loop
    Loop --> Tools
    API --> Memory
    Planner --> Redis
    Tools --> Sandbox
    Memory --> Postgres

需要 Git、Docker 与 Docker Compose v2。

git clone https://github.com/malevrigns/atlas-agent-control-plane.git
cd atlas-agent-control-plane
cp .env.example .env
BUILD=true ./scripts/start.sh

启动后访问：

• Web 工作台（PWA）：http://localhost:8088
• API 健康检查：http://localhost:8088/api/status
• 数据库状态：http://localhost:8088/api/status/database

启动脚本会为 API 与 PostgreSQL 生成随机密钥，并在终端打印 Web 登录所需的 API Key。除 /api/status 外的接口都需要浏览器 HttpOnly 会话或 X-Atlas-API-Key 请求头。

Windows 请在 Git Bash 或已启用 Docker 集成的 WSL 中运行同一脚本。再次启动无需重建：

./scripts/start.sh

停止服务：

./scripts/stop.sh                      # 保留数据卷
CLEAN_VOLUMES=true ./scripts/stop.sh   # 连同数据库、Redis、上传文件一起清理

[!TIP]
默认网关端口为 8088。端口冲突时设置 NGINX_PORT=18088 后重新启动。

📱 客户端

TUI 的快捷键与客户端配置见 客户端指南。

🧩 Control Plane 最小调用

1. 创建结构化任务

ATLAS_KEY="$(sed -n 's/^ATLAS_API_KEY=//p' .env)"
curl -X POST http://localhost:8088/api/control-plane/tasks -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" -d '{"title": "更新交付物", "goal": "完成可验证升级", "acceptance_criteria": ["测试通过"], "project_id": "atlas"}'

2. 通过统一 Runtime 调用工具

curl -X POST http://localhost:8088/api/agent-core/tools/draft_plan/invoke -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" -d '{"arguments": {"task": "检查交付质量"}, "project_id": "atlas", "allowed_permissions": [], "idempotency_key": "demo-001"}'

3. 回读工具审计

curl -H "X-Atlas-API-Key: ${ATLAS_KEY}" "http://localhost:8088/api/control-plane/tool-invocations?project_id=atlas"

4. 检索知识库并拿到带引用的证据

curl -X POST http://localhost:8088/api/rag/knowledge-bases/${KB_ID}/query -H "X-Atlas-API-Key: ${ATLAS_KEY}" -H "Content-Type: application/json" -d '{"query": "数据库迁移怎么回滚", "top_k": 3}'

完整数据模型、生命周期和接口说明见 Memory 与 Tool Control Plane 与 RAG 与 Skill 注册中心。

⚙️ 配置与安全

服务端常用配置集中在根目录的 .env.example：

• LLM_API_KEY：模型服务密钥；未配置时仍可使用不依赖模型的演示与控制平面能力。任何 OpenAI 兼容服务都可接入：在 backend/api/config/llm.yaml 中把 base_url 换成服务商地址（如 DeepSeek https://api.deepseek.com/v1、阿里云百炼 https://dashscope.aliyuncs.com/compatible-mode/v1），default_model 换成对应模型名。llm.thinking: true 可开启思考过程流式输出（Qwen enable_thinking），Web 端实时展示并支持事后展开回看；llm.vision_model 启用多模态 RAG。
• ATLAS_API_KEY：控制平面与 Sandbox 的共享访问密钥；启动脚本会替换示例占位符。
• NGINX_PORT：统一网关端口，默认 8088。
• NGINX_HOST：默认 127.0.0.1；确需远程访问时必须配合 TLS 与上游身份系统。
• TOOL_AUTO_APPROVE_RISK：工具自动批准的最高风险等级。
• TOOL_DEFAULT_TIMEOUT_SECONDS：工具默认超时。
• TOOL_OUTPUT_INLINE_LIMIT：大输出转为 Artifact 的阈值。
• RAG_VECTOR_BACKEND：RAG 向量后端，pgvector（默认）或 qdrant。
• RAG_EMBEDDING_PROVIDER：auto 按 llm.yaml 与密钥自动选择，local_hash 强制离线哈希向量。
• EMBEDDING_API_KEY：OpenAI 兼容 embedding 服务密钥；留空时自动降级为本地向量。

TUI 通过 ATLAS_API_URL 与 ATLAS_API_KEY 连接后端。

[!IMPORTANT]
不要提交真实 .env、模型密钥或第三方服务凭据。stdio MCP、MCP HTTP 与 A2A HTTP 默认关闭或无允许主机，必须由运维通过 allowlist 显式放行。内置 API Key 是单租户/内网边界，互联网多用户部署仍应在网关前接入 TLS、OIDC/RBAC 与限流。

🛠️ 本地开发

先准备 PostgreSQL 与 Redis：

docker compose up -d postgres redis

开发与验证：

# 后端测试
cd backend/api
uv run python -m unittest discover -s tests

# TUI 测试
cd ../../frontend/tui
uv run python -m unittest discover -s tests

# Web 类型检查与构建
cd ../web
pnpm typecheck
pnpm build

📁 项目结构

atlas-agent-control-plane/
├── frontend/
│   ├── web/       Next.js Web 客户端（PWA）
│   └── tui/       Textual 终端客户端
├── backend/
│   ├── api/       FastAPI、数据库迁移、Control Plane 与测试
│   └── sandbox/   文件、Shell、浏览器与 VNC 隔离执行环境
├── nginx/         统一网关配置
├── docs/          Control Plane 与客户端专题文档
├── tutorial/      0–56 章中文工程教程（55 章）
├── scripts/       启停与运行时配置脚本
├── tests/         根级生产配置测试
└── docker-compose.yml

📚 文档与教程

• 整体架构
• API 架构
• Memory / Tool Control Plane
• RAG 知识库与 Skill 注册中心
• Web 与 TUI 客户端
• 完整教程目录 —— 从最小可运行服务逐步演进到完整控制平面

🤝 贡献

欢迎提交 Issue 与 Pull Request。提交前请运行对应的测试与类型检查，并确保不提交真实密钥与 .env。

📄 License

MIT License