Overview

DomainAtlas

DomainAtlas 是一个知识地图式的领域学习 Agent，帮助用户在有限时间内进入陌生领域，建立第一版有边界、有结构、有来源、可探索、可验证的认知框架。

当前状态：第一版可运行 Demo（v0.1）。

它能做什么

DomainAtlas 将一次学习任务组织成一个可探索的 Atlas，而不是一次性生成一篇长报告：

Planning：把宽泛主题整理成有边界的学习框架；
Research：在受控候选资料中整理带来源的证据；
Atlas：构建模块、概念、关系、机制、案例、学习路径和自测；
学习工作区：通过迷雾地图逐步探索概念关系，查看来源，记录节点进度；
自测：完成简单测验，获得反馈并定位需要复习的概念。

完整的演示闭环是：

创建学习任务
→ 校准范围
→ 确认学习框架
→ 研究和整理证据
→ 构建并检查 Atlas
→ 按地图或路径学习
→ 自测并定位薄弱点

当前版本已经打通“创建学习任务 → 确认框架 → 研究与建图 → 迷雾探索 → 自测”的完整演示链路。

当前版本的特点

用户确认或修改学习框架后，才会开始研究和建图；
live、hybrid、fixture 三种执行结果会在界面中明确标识；
auto 模式下，模型或网络异常会透明降级到演示数据，并显示 HYBRID MODE；
Research 阶段只使用受控的中文维基百科候选结果，每个模块最多保留一条候选来源，避免模型自行编造网页来源；
Atlas 的结构、引用、覆盖度和图连通性会经过确定性校验；
仍然保留原有 POST /agent 流式聊天原型，方便后续接入真实模型。

在一台新电脑上运行

以下步骤不依赖本机的绝对路径。克隆或解压仓库后，在项目根目录 DomainAtlas 中执行即可。

1. 安装基础环境

需要：

Git（如果通过 Git 克隆项目）；
Python 3.12 或更高版本；
uv；
Node.js 22 或更高版本；
pnpm 11（可执行 npm install -g pnpm@11.9.0 安装）。

检查安装是否成功：

python --version
uv --version
node --version
pnpm --version

2. 获取项目并安装依赖

git clone https://github.com/ghost200156/DomainAtlas.git
cd DomainAtlas

uv sync --directory backend
pnpm --dir frontend install --frozen-lockfile

如果电脑上安装了 GNU Make，也可以执行：

make setup

Windows 用户不需要为了运行项目额外安装 Make。

3. 配置模型服务

先复制配置模板。

Windows PowerShell：

Copy-Item backend/.env.example backend/.env
Copy-Item frontend/.env.example frontend/.env

macOS / Linux：

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

打开 backend/.env，填写自己的 OpenAI 兼容服务信息：

OPENAI_API_KEY=your-api-key
OPENAI_API_BASE=https://your-compatible-api.example.com/v1
OPENAI_MODEL=qwen3.5-plus
DEMO_AGENT_MODE=auto

配置说明：

OPENAI_API_BASE 必须以服务提供的 OpenAI 兼容 /v1 地址结尾；
OPENAI_MODEL 必须是该 API Key 实际可以调用的模型；
DEMO_AGENT_MODE=auto 会在模型或网络异常时回退到演示数据；
没有 API Key 也能查看固定演示流程，但不会生成真实的 Agent 结果；
不要把包含真实 API Key 的 backend/.env 提交到 Git。

前端默认配置如下，通常不需要修改：

VITE_API_URL=http://127.0.0.1:8000/agent
VITE_API_BASE=http://127.0.0.1:8000/api

4. 启动开发环境

需要打开两个终端，并保持两个终端都在运行。

终端 1：启动后端。

cd backend
uv run uvicorn app.main:app --app-dir src --host 127.0.0.1 --port 8000 --reload

终端 2：从仓库根目录启动前端。

pnpm --dir frontend dev

然后访问：

停止项目时，在两个终端中分别按 Ctrl + C。

启动后可以使用首页预填的“Agent 系统设计”样例走完整个演示流程。

5. 启动本地生产构建

先构建前端：

pnpm --dir frontend build

启动后端：

cd backend
uv run uvicorn app.main:app --app-dir src --host 127.0.0.1 --port 8000

另开一个终端启动构建后的前端。

Windows PowerShell：

$env:HOST="127.0.0.1"
$env:PORT="5173"
pnpm --dir frontend start

macOS / Linux：

HOST=127.0.0.1 PORT=5173 pnpm --dir frontend start

这仍然是单机 Demo，不代表已经具备正式生产部署能力。

使用流程

在首页输入想了解的领域、已有背景、学习目标和可用时间。
创建任务，等待 Planning 阶段生成范围校准和学习框架。
检查模块、核心问题、重点和排除项；必要时修改计划。
确认学习框架后，等待 Research 和 Atlas 阶段完成。
进入 Atlas 工作区，从已解锁的节点开始探索概念、关系和来源。
为概念记录 unvisited、unclear 或 understood 状态。
完成自测，根据反馈回到需要复习的概念。

API 概览

Demo 主链路提供以下接口：

POST  /api/runs
GET   /api/runs/{run_id}
POST  /api/runs/{run_id}/clarifications
PATCH /api/runs/{run_id}/plan
POST  /api/runs/{run_id}/plan/confirm
POST  /api/runs/{run_id}/retry
GET   /api/runs/{run_id}/events
GET   /api/runs/{run_id}/atlas
PATCH /api/runs/{run_id}/progress/{concept_id}
POST  /api/runs/{run_id}/assessments/{assessment_id}
GET   /api/demo/fixture
GET   /health

原有聊天原型继续提供：

POST /agent
Content-Type: application/json
Response: text/event-stream

请求体使用 AI SDK 消息格式，并至少包含一条用户消息：

{
  "messages": [
    {
      "role": "user",
      "content": "What's 15 + 27 + 8?",
      "parts": [
        {
          "type": "text",
          "text": "What's 15 + 27 + 8?"
        }
      ]
    }
  ]
}

检查与测试

不依赖 Make 的跨平台命令：

uv run --directory backend pytest -q
uv run --directory backend ruff check .
pnpm --dir frontend typecheck
pnpm --dir frontend build

安装了 GNU Make 时也可以执行：

make test

常见问题

页面显示 NetworkError：通常是后端没有启动，先访问 /health 检查；
页面显示 HYBRID MODE：模型调用失败或超时，检查 API Key、兼容地址和模型名；
5173 或 8000 端口被占用：关闭旧的开发进程后重新启动；
修改 .env 后没有生效：停止并重新启动后端；
旧任务仍显示旧模型或混合模式：任务会保存创建时的状态，请新建一次任务验证新配置；
后端重启后任务停在生成中：当前 Demo 没有可恢复任务队列，需要重新发起该任务。

当前限制

当前版本适合单机演示，不是生产产品：

JSON 文件存储只适合单机 Demo，不支持多用户并发和事务；
后台任务依赖当前后端进程，重启后不会自动恢复正在生成的任务；
外部研究源目前仅使用中文维基百科的单条候选摘要，证据覆盖有限；
QualityReport 主要来自确定性检查和演示评分，没有独立 Reviewer Agent；
尚无不可变 Atlas 版本、数据迁移和回滚机制；
没有认证、限流、调用预算、监控和正式部署配置；
自测暂时只形成最小反馈，不会自动生成个性化复习路线；
复杂结构化输出可能超时，auto 模式会回退到演示数据。

项目文档

以下文档位于项目仓库中：

Navigation Menu