Atlas

中文 · English

Atlas 是一个跑在本机 Windows 上的多模型工作流引擎：用 YAML 画一张有向图，让不同厂商的模型各司其职——并行调研、交叉审查、改代码、人工拍板——每个节点的完整输入输出都实时落在你自己的磁盘上。

它解决一个具体的问题：把多个 LLM 调用串成一条可靠流水线时，"看起来成功了"和"真的成功了"是两回事。Atlas 对每一次调用做假成功检测（空输出、截断、缺字段都过不了关），对每一份产物做哈希断言，对每一笔花销记账。出问题时你能看到是哪一步、哪个模型、为什么。

点开任意节点,可以看到它的完整输入投影、输出产物、实际使用的模型、token 与耗时;运行暂停在人工门时,审批条会直接列出待审材料与完整投影(带哈希),点开即审——批准绑定的就是这份材料的哈希,驳回则必须写明理由。

它长什么样

一张图 = 一个 YAML 文件。比如让三个视角并行分析、汇总后交给编程 agent 改代码、再由人审批：

name: stage-d-custom
nodes:
  - { id: left,  type: llm, model: Deepseek:deepseek-v4-flash,
      prompt: "给出任务的一个侧面要点", consumes: [task] }
  - { id: mid,   type: llm, model: Deepseek:deepseek-v4-flash,
      prompt: "给出另一个侧面要点",     consumes: [task] }
  - { id: right, type: llm, model: Deepseek:deepseek-v4-flash,
      prompt: "给出第三个侧面要点",     consumes: [task] }
  - { id: joiner, type: llm, model: Deepseek:deepseek-v4-flash,
      prompt: "汇总三个要点为执行摘要", consumes: [task, left.output, mid.output, right.output] }
  - { id: coder,  type: coding_agent, workdir: demo-project,
      prompt: "按摘要实施改动并自测", consumes: [task, joiner.output] }
  - { id: checker, type: llm, model: Deepseek:deepseek-v4-flash,
      prompt: "核对 diff 是否精确完成任务,输出 verdict", consumes: [task, coder.diff] }
  - { id: gate, type: human, prompt: "审阅改动与核对结论后批准或驳回" }
edges:
  - { from: left,  to: joiner }
  - { from: mid,   to: joiner }
  - { from: right, to: joiner }
  - { from: joiner, to: coder }
  - { from: coder,  to: checker }
  - { from: checker, to: gate }
  - { from: gate, to: END }
guards:
  timeout_s: 1800

这是一次真实运行的记录（2026-08-19，DeepSeek deepseek-v4-flash）：7 个节点全部完成，编程 agent 精确地在 demo 项目 README 追加了要求的一行文本，diff 审查判定 pass，人工批准后结束。全程 4 分 44 秒，已知成本 $0.0442——账本里每个节点的 token 数、耗时、费用逐条可查。

Related MCP server: MEMGRAPH-MCP

真实案例

以下均来自发布前用真实供应商 API 跑过的运行，包括失败的（失败也是记录的一部分）。

修复循环 + 代码审查 + 人工门（code-change-review-approve 示例，SuperAI doubao-seed-2.0-lite）。任务："修复 demo-project 中的示例错误并自测"。第一轮：implementer 修好了 fizzbuzz 的判断顺序错误，但顺手多建了两个无关文件，也没真正跑测试；reviewer 输出结构化判定 repair，列出问题清单。第二轮：implementer 清理了多余文件，reviewer 判定 pass。人工批准，结束。两轮共 $0.96，两次 diff 都作为产物留档可下载。（如实说明：当前回边不携带审查意见，第二轮是从冻结 baseline 的重新实施——"循环携带反馈"列在 BACKLOG。）

10 节点自定义图，MCP 直跑（2026-08-22，DeepSeek + SuperAI 四个模型）。对装了 Atlas skill 的 AI 助手描述目标，它当场写了一张 10 节点图：三路并行调研 → 汇总 → 结构化审查（条件路由）→ 修订分支（消费审查意见）→ 复审 → 终稿 → 人工审批 → 门后收尾。整图作为 atlas_run_workflow 的 yaml 参数经 MCP HTTP 端点直接运行，不落盘。8 个执行节点全部一次通过（审查首轮 pass，未进修订轮），人工批准后收尾完成：全程 361 秒（其中 294 秒在等人工），约 $0.01，每个产物的哈希事后独立复验一致。

诚实记录的失败。同一测试矩阵里也出现过：推理型模型把输出预算烧在思考上导致可见文本为空（被空输出检查拦下）、prompt 只送达 1%（被截断哨兵抓到）、agent 首次尝试自报约 $10.5 后自动 retry 被人工终止——这次事故直接催生了现在的成本预留机制和"所有真实 agent 运行必须配预算"的纪律。完整矩阵见 docs/VERIFICATION-2026-08-28.md。

快速开始

需要 Windows 10/11 x64、Python 3.12、uv。Git clone 用户还需 Node.js 22.12+ 构建一次前端；官方 Release 的 bundle 包已内置构建好的前端（atlas-web 自动识别，也可用 --dist 参数或 ATLAS_WEB_DIST 环境变量显式指定）。

git clone https://github.com/Ctrl1CandV/Atlas.git
cd Atlas
uv sync --locked --all-groups
npm --prefix web ci
npm --prefix web run build
uv run atlas-web

一条命令同时启动 Web 界面（http://127.0.0.1:8321）和 MCP 端点（http://127.0.0.1:8321/mcp）。在 Claude Code / ZCode / Cursor 里把 MCP server 指向该 URL，你的 AI 助手就能替你写图、校验、预演、运行；仓库自带的 .mcp.json 也指向该端点。配置细节见 docs/mcp.md。

首次启动会从模板生成本机配置（不覆盖已有文件），凭据只放 config/.env。六个随附示例（并行综合、辩论裁决、map-reduce、重试循环、人工审批管线、代码实施审查）开箱即可校验和预演；真实运行前给每个节点绑定你配置好的模型。

设计原则

• 先预演后付费：validate 和 dry_run 零成本，dry-run 与真跑使用同一份有效规格，可用哈希绑定两者身份。

• 完整性优先：产物按引用传递（文件 + SHA-256），读取时断言哈希；缺失产物显式失败，绝不给下游喂空串；超长不截断而是报错。

• 假成功即降级：HTTP 200 不算成功。空输出、截断、缺必填字段都会触发跨厂商 fallback 链，降级在界面上显式标注。

• 全程可审计：append-only JSONL 事件账本是唯一真相，界面显示的一切都能在账本里找到出处；审批证据绑定 baseline/result/patch 三摘要。

• 崩溃可恢复：控制器被杀后运行自动判定 interrupted，恢复只补未完成节点，成本预留不重算预算。

• 人在环：human 节点把图暂停在界面里；审批条列出待审材料与完整投影（带哈希，点开即审），驳回必须填写理由。

能力边界（如实说明）

• 仅支持 Windows 10/11 x64；以源码 sdist 发布，未上 PyPI，无预编译安装器。当前正式版本 v0.1.0，Git clone 与 sdist 内容略有差异（见 Release 说明）。

• Web 只绑回环地址，没有多用户认证；不要暴露到网络。

• 编程 agent 通过 Claude CLI 以当前用户身份下的宿主进程运行（需 config/agents.json 显式 "runner": "local_cli"，供应商须提供 anthropicBaseUrl 与凭据）。目录副本不是 OS 沙箱：进程理论上能访问当前用户有权访问的任何路径。allowed_paths、回环绑定都不是安全边界。Atlas 不写原目录，diff 由冻结 baseline 的普通文件字节清单生成完整文本 unified diff，二进制变更大声失败。

• allow_web: false 只是不授予 Claude CLI 的 WebSearch/WebFetch 工具；可写 agent 有 Bash，仍可能联网。max_turns 是校验过的规格字段，但当前 Claude CLI 没有硬轮次参数，硬限制来自 deadline 与已配置预算。

• research/coding_agent 节点缺省不自动重跑（retry 缺省 0）；显式声明 retry: N 后，dry-run 必须出现放大风险警告。

• 成本帽只在费率已知的调用上精确生效；费率未知时保守占满剩余预算，但不能证明供应商实际账单没超。

• "多厂商辩论"等名称只表达拓扑；只有绑定了真实不同的供应商，意见才独立。

• 审批证据绑定 baseline_digest、result_digest 与 patch_digest 三摘要；可写 coding agent 与 allowed_paths 的组合会在创建 run 前被拒绝（Claude --add-dir 不是只读边界）。

测试与验证

2026-08-28 基线：Python 测试 666 passed / 2 skipped（另有 5 个真实供应商测试默认排除、需主动运行且可能收费）；Web 测试 22 passed、lint 0 告警、生产构建通过；公开 CI 在 main 分支三 job 通过（另有 workflow_dispatch/release 触发的可选浏览器 e2e 冒烟 5 用例——键盘审批流跑 Chromium/Edge/Firefox 三浏览器 + 终局卡片 dark/light × 100%/200% 四组合基线截图，不计入主门）。10 节点自定义图经 MCP HTTP 端点真实运行全链路通过（含人工审批，见上文真实案例）。

2026-08-19 发布基线：Python 测试 427 passed；Web 测试 22 passed、lint 0 告警、生产构建通过；六个示例工作流严格离线 validate/dry-run，0 次供应商调用；发布 sdist 100 个条目、0 扫描发现。数字对应当时的源状态；当前基线与真实端到端证据见 docs/VERIFICATION-2026-08-28.md。

开发验证：

uv lock --check
uv run python -m compileall -q atlas
uv run pytest
npm --prefix web test && npm --prefix web run lint && npm --prefix web run build

文档

• docs/VERIFICATION-2026-08-28.md — 验证报告：基线、真实端到端证据、已知发现

• docs/mcp.md — MCP 工具面与调用口径

• docs/mcp.md — harness 接入配置

• skill/SKILL.md — 给 AI 助手看的操作手册

• SECURITY.md · CONTRIBUTING.md · CHANGELOG.md

许可证

Apache License 2.0。见 LICENSE 与 NOTICE。