GitHubHelp

thautwarm/context-rpg

Context management via Arrow keys & Esc/Enter/E. Gamepad support coming soon.

★ 0Forks 0TypeScriptGitHub ↗Compare

README

context-rpg

Atlas 把与 Agent 的交互从「时间序的会话列表」变成「空间序的节点地图」：

  • 地图上的点是一次构建产物（一次用户指令 + Agent 的一轮执行）。
  • 点与点之间的有向连线决定上下文流向。
  • 要构建哪个点，就沿入边向上回溯，得到一份线性上下文。

界面示意

像素风 tilemap，纯键盘操作。

┌──────────────────────────────────────────────┐
│ 面包屑：主地图 / 子地图A           [构建中●]   │
├──────────────────────────────────────────────┤
│                                              │
│   画布（16×16 逻辑像素网格）                  │
│   · turn 点   = 卷轴 sprite                  │
│   · submap 点 = 房子 sprite                  │
│   · 边        = 像素连线                      │
│   · 光标      = 闪烁方框（RPG 光标）          │
│                                              │
└──────────────────────────────────────────────┘

特性

  • turn 点存放一次构建，submap 点内嵌一张子图，submap 可以嵌套。
  • 多执行器：opencode / claude / codex / 自定义 CLI，默认 codex。
  • 多项目：数据在 ~/.atlas（可用 ATLAS_HOME 换位置），项目可增删、可进回收站。
  • 每个项目配置 agentCwd（agent 工作目录），未配置的 CLI 构建会被拒绝。
  • 纯键盘客户端，键位只有方向键 / Enter / Esc / E / Tab。
  • 构建实时推进（SSE），可取消；崩溃重启后中断的构建标记为 failed。

结构

├── atlas.sh           # 服务管理（up/down/logs/status）
├── server/            # HTTP API + SSE 构建流 + 静态托管
│   ├── src/atlas.ts       # 核心数据模型与操作集
│   ├── src/executor.ts    # 执行层契约，环境/配置驱动的执行器
│   ├── src/executor-cli/  # CLI 适配：spawn + 各家解码器
│   └── test/              # 单元 + 黄金测试
└── web/               # JRPG 像素客户端
    └── src/           # 状态机 + 渲染 + 窗口件

快速开始

前置：Node.js 22+，以及一个可选用的 CLI（codex / opencode / claude）。

npm install     # npm workspace，装齐 server 与 web
./atlas.sh up   # 启动，默认 7391，执行器 codex
# 浏览器打开 http://localhost:7391
命令 作用
./atlas.sh up [--port N] [--executor NAME] 启动；web/dist 缺失时自动编译
./atlas.sh down [--port N] 停止
./atlas.sh logs 实时日志
./atlas.sh status 当前状态

支持 ATLAS_PORT、ATLAS_EXECUTOR 环境变量注入。执行器 opencode / claude / codex / echo，也可在 UI 的 CONFIG 菜单里改。

执行层

每次构建起一个外部 agent CLI 进程（codex exec / opencode run / claude -p），跑完即退：

  • 出去只有一种形状：把装配好的上下文投影成单份 Markdown 转写稿，需要时经链接或本地文件下钻。
  • 回来按 CLI 各配一张映射表。结构化输出是会漂移的私有契约，所以解码器按 CLI 分文件，先抓真实输出存样本，再按样本写。

数据模型

两个节点类型加一个嵌套容器：

  • TurnNode：一次构建。
  • SubmapNode：指向一张内嵌子图。
  • AtlasMap 与 Edge：容器与纯接线，边上没有 payload。

不变量：入度 ≤ 1、无环、边不跨图。唯一会调用 LLM 的操作是 buildTurn；createNote、createSubmap 不调 LLM。

测试

cd server && npx tsc --noEmit && node --test test/*.test.ts

126 项测试，跑全量不需要外部服务。

文档

docs/design-v0.md 数据模型与操作语义 · docs/executor-cli.md 执行层 · docs/client-ux.md 客户端交互。

Contributors

thautwarm

Issues