LuminaCode

LuminaCode 是一个本地运行的通用 Agent。它由 Go 后端和 TypeScript TUI 组成，提供项目上下文、工具、skills、MCP、记忆、session 和 Agent Team。

Agent 能力

• 默认把启动目录作为项目根目录。
• 读取 LUMINA.md / AGENTS.md，并支持 <AppRoot>/config/instructions 用户级回退。
• 加载项目、用户和内置 skills。
• 调用文件、Shell、Web、MCP、记忆和任务工具，并带权限控制。
• 保存可恢复 session：transcript、state、tasks、tool results、skill recovery 和 session memory。
• 将 runtime 活动记录为有序、可重放事件，并支持崩溃恢复和幂等 submit。
• 支持 OpenAI-compatible 和 Anthropic-compatible 流式 API。
• 将可见对话与工具 payload、tool result、runtime 记录分离。
• 支持 sub-agent、Agent Team、headless 和 benchmark harness。

架构

安装后会有两个命令：

• lumina：TypeScript 终端前端，也是默认用户入口。
• lumina-backend：Go runtime，负责 Agent 执行、工具、skills、MCP、记忆、session、headless 和 benchmark 模式。

交互会话通过 localhost WebSocket 通信：

<AppRoot>/state/run/backend.json

后端只监听 127.0.0.1，连接必须携带 auth token；支持多个 session，同一个 session 内串行 submit。Headless 路径由 lumina-backend 处理。

持久化 Runtime Journal

每个交互 session 使用一个权威 SQLite journal：

<AppRoot>/data/sessions/active/{session-id}/runtime.sqlite

Journal 使用 WAL 模式，记录 session、run、step、message、model、tool、task、 Team、memory、usage、warning 和 checkpoint event。事件同时具有全局序号和 stream 内序号，并通过乐观并发检查避免冲突写入。大型 payload 可进入 content-addressed blob 表；可重建 projection 和 consumer offset 用于跟踪 重放进度。

Runtime 通过 typed capability 和确定性 hook 组装。Memory preparation、skill context、MCP 注册、context compilation、model response、权限、工具和 sub-agent 共享同一个 session scope，不依赖 TUI 才能工作。

WebSocket protocol v3 会推送带 journal sequence 的 durable event。TUI 发现 序号缺口时，会先调用 session.events 拉取并 reduce 缺失事件，再处理实时事件。 Submit command 带幂等 key，因此断线重试会返回原结果，不会启动重复 run。

恢复 session 时，尚未结束的 run、step 和 tool 会追加明确的 interrupted event。 Task 状态由 lifecycle event 重建，Team child stream 使用无损 runtime checkpoint。旧 JSON/JSONL session 文件和 Team sidecar 会在备份后一次性导入； 新 session 不再生成这些 sidecar。

多进程、多实例集群模式

local 仍是默认模式，继续使用上面的 SQLite journal。cluster 是显式且 fail-closed 的运行模式：

• PostgreSQL 是 Session stream、event、checkpoint、command result、blob、 consumer offset、Team checkpoint 和 Memory Fabric 的耐久事实源。
• Redis 保存带 TTL 的实例注册与 Session lease、单调递增 fencing token、 Redis Streams RPC 和实时事件提示；Pub/Sub 永远不是事实源。
• 任意 Hertz gateway 都能接受 WebSocket，并透明转发到 Session owner。 Team、sub-agent、permission、artifact 和 A2A 继承父 Session 的 owner 与 fence。
• 所有 PostgreSQL runtime 写入都校验 fencing token；旧 owner 在接管后无法提交。
• TUI 使用 UUID request ID 和 Authorization: Bearer <JWT>，断线后最多重连 30 秒，执行 resume、按 seq 补齐事件，再用相同 UUID 重试已确认 mutation。
• /healthz 只表示进程存活；/readyz 还会检查 Redis、PostgreSQL、schema 和实例注册。

可在用户 settings.json 或对应的 LUMINA_* 环境变量中配置：

{
  "session_runtime_backend": "cluster",
  "memory_fabric_store": "postgres",
  "cluster_id": "production",
  "instance_id": "backend-1",
  "cluster_listen_addr": "0.0.0.0:8080",
  "cluster_advertise_addr": "backend-1:8080",
  "redis_url": "redis://...",
  "postgres_url": "postgres://...",
  "jwt_issuer": "https://issuer.example",
  "jwt_audience": "lumina",
  "jwt_jwks_url": "https://issuer.example/.well-known/jwks.json"
}

连接 URL、私钥和 JWT 只能来自用户配置或 Secret Manager，不会进入默认配置、 endpoint 文件或诊断输出。JWT 仅接受 RS256、ES256、EdDSA，并强制校验 exp/iss/aud/sub/tenant。读写 scope 分别是 lumina:session:read/write， shutdown 与 drain 需要 lumina:admin。

本机多进程可生成 Ed25519 keypair 和 admin token：

lumina-backend cluster init-local --tenant local
export LUMINA_JWT="$(cat <AppRoot>/config/cluster/admin.jwt)"
export LUMINA_BACKEND_URL=ws://127.0.0.1:8080/v1/ws

要求 PostgreSQL 15+、pgvector 0.8.6+、Redis 7.2+。固定依赖版本为 Hertz 0.10.6、go-redis 9.20.0、pgx 5.10.0、pgvector-go 0.4.1 和 golang-jwt 5.3.1。Hertz 使用 Go standard transport，并通过官方 HTTP adaptor 复用现有 gorilla/websocket handler。SQL schema 与部署示例位于 deploy/。 各实例必须通过共享持久卷或外部 Git/Object Storage 看到同一 project workspace； 源码和 artifact 内容不会写入 Redis/PostgreSQL。

长期记忆

Local 模式下，Memory Fabric 使用两个 SQLite 数据库保存持久化跨 Session 状态，并构建 一个可替换的 BGE-M3 检索索引：

<AppRoot>/data/memory/fabric/ledger.sqlite
<AppRoot>/data/memory/fabric/index.sqlite
<AppRoot>/data/memory/fabric/retrieval-bge-m3.sqlite

Cluster 模式把 ledger、node、conflict、resolution、job、generated FTS、语义 vector(1024)、event window halfvec(1024)、learned-sparse posting、graph edge 和 index build state 全部按 tenant/project 存入 PostgreSQL。少于 50,000 个 vector 的 space 使用 exact cosine，超过阈值后使用 HNSW；模型变化只重建派生 索引，不改写 durable evidence。

记忆写入流程

1. 持久化原始证据：先把可见的 user、assistant 和 tool event 写成不可变、 可定位来源的 ledger row，再进行任何语义处理。
2. 绑定上下文与 provenance：记录 project space、context、session、actor、 时间、turn 顺序、checksum 和 source offset，确保每条事件都能还原。
3. 语义编译：可选地使用配置的 API 模型筛选持久记忆，并生成有原文依据的 node、identity、slot、时间 scope、检索线索和冲突候选。每个 node 都必须 引用 source event 并通过本地 grounding 校验。
4. 冲突处理：明确更新由本地权威和时间规则处理；歧义情况保持 pending， 或使用配置的 adjudicator。原始证据永远不会被覆盖。
5. 本地 BGE-M3 索引：生成 dense vector，以及检索需要的 event/span dense、 learned sparse、FTS 和图表示。
6. 可恢复发布：后台任务支持 checkpoint，派生索引原子发布。模型、 tokenizer 或 schema 变化时从 ledger 重建派生数据，无需重新写入对话。

记忆检索流程

检索完全在本地执行，所有普通自然语言查询统一走同一条管线：

1. 对齐检查：验证检索索引的模型、tokenizer、schema 和 ledger checksum， 必要时增量补齐缺失事件。
2. Query encoding：生成 BGE-M3 dense、learned sparse 和全 token 表示。
3. 候选召回：span FTS5、event dense 和 learned sparse 三个通道各召回 最多 128 个候选。
4. 融合与图扩散：reciprocal-rank fusion 形成召回池，再对 event、context、 semantic node 和 sparse concept 图执行 Personalized PageRank。
5. 精确 span 打分：使用 BGE-M3 dense、learned sparse 和全 token ColBERT MaxSim，融合权重固定为 1.0 : 0.3 : 1.0。
6. 证据选择：按 source event 去重，再用 submodular objective 在配置的 evidence 数量和 token 预算内最大化相关性与覆盖。
7. 上下文组织：应用 reference time 与冲突状态过滤，对证据进行一致分组， 并为回答模型保留时间、actor、context、source ID 和 span 位置。

ID、路径和引用文本只作为 lexical candidate feature，query 内容不会绕过 BGE-M3。生产检索没有远程 query expansion、题型路由、benchmark 实体、本地 答案 bypass。

LongMemEval-S

在 LongMemEval-S 500 题完整 haystack 评测中，LuminaCode Memory Fabric 使用本地 BGE-M3 检索，并以 mimo-v2.5-pro 作为回答模型和 official evaluator，取得 83.00%（415/500）。

题型	正确数	准确率
Knowledge update	74/78	94.87%
Single-session user	65/70	92.86%
Temporal reasoning	114/133	85.71%
Multi-session	103/133	77.44%
Single-session assistant	40/56	71.43%
Single-session preference	19/30	63.33%

端到端检索平均耗时 1.02 秒（P50 0.99 秒，P95 1.29 秒）。

公开 LongMemEval 成绩按分数排序如下，仅用于定位：

系统	准确率	公开评测设置
Exabase M-1	96.4%	Gemini 3 Flash，Top 50；厂商公开结果
Mastra Observational Memory	94.87%	GPT-5-mini；实现和 runner 开源
Mem0 Platform	94.8%	Mem0 当前 benchmark，Top 50
Honcho	92.6%	公开报告；完整运行配置未披露
Engram	91.6%	GPT-5 composer、GPT-4o judge；公开 prompt 和运行产物
Hindsight	91.4%	Gemini 3 Pro；公开 benchmark 仓库
HydraDB	90.79%	Gemini 3 Pro；论文报告
LuminaCode（LongMemEval-S）	83.0%	完整 haystack；mimo-v2.5-pro 回答及 official evaluator；完整 500 题
LiCoMemory	73.8%	GPT-4o-mini，5 次均值
Mem0-G	64.8%	GPT-4o-mini 同设置 baseline
Mem0	62.6%	GPT-4o-mini 同设置 baseline
Zep	58.6%	GPT-4o-mini 同设置 baseline
A-Mem	55.0%	GPT-4o-mini 同设置 baseline
MemOS	51.2%	GPT-4o-mini 同设置 baseline

来源：LongMemEval、 Mem0 benchmark、 LiCoMemory 论文、 Mastra Observational Memory、 Hindsight benchmark、 Engram benchmark、 HydraDB 论文、 Honcho 以及 Exabase M-1 公告。 Exabase 和 Honcho 使用公开报告分数，但完整复现材料相对有限。不同报告的 reader、检索深度、上下文预算、回答模型和 judge 不完全一致，因此这不是严格 同口径排行榜。

Agent Team

Agent Team 模式让一组互相隔离的专家 Agent 协作完成任务。每个成员都有独立 prompt、skills、上下文、任务状态和 A2A inbox/outbox，同时复用同一套 backend runtime 和工具系统。

命令：

/Team      选择已安装 Team 并进入 Team 模式
/TeamOut   退出 Team 模式
/NewTeam   创建一个新的可编辑 Team 模板

TUI 会像群聊一样展示 Team 对话。原始 tool payload、完整 tool result、MCP payload 和隐藏 reasoning 只进入 runtime 日志。

Runtime 要点：

• Loop：observe -> plan -> dispatch -> agent work -> collect -> gate -> finalize。
• 停止条件：用户打断或任务完成。
• 失败会进入下一轮恢复，而不是静默成功。
• 普通 Agent 上下文和 Team Agent 上下文隔离。
• Team 对话、activity、artifact、gate 和成员状态以 checkpoint 形式写入父 session runtime.sqlite 内的 child stream。
• 已有文件式 Team runtime 数据仍可作为一次性迁移来源；新 Team session 不再 写入独立 runtime 目录。

内置 Team

安装位置：<AppRoot>/app/resources/teams/

• product-development：全栈开发 Team，包含 team-leader、research、frontend、backend、qa、reviewer、devops、ux-design。启用 contract、QA、Reviewer、task policy 和 follow-up/deferral gate。
• deep-research：研究 Team，包含 team-leader、scope-planner、search-strategist、source-reader、evidence-analyst、report-writer、qa、reviewer。使用 SearxNG WebSearch / WebFetch 和 arXiv MCP，可导出报告与证据文件。

Team 读取顺序为：项目 .Lumina/TEAM、用户 <AppRoot>/config/teams、安装内置 <AppRoot>/app/resources/teams。

创建新的 Team

/NewTeam 会询问展示名并创建：

<AppRoot>/config/teams/{team_name}/
├── team.yaml
├── team-system.md
├── shared-prompt.md
├── completion-policy.md
└── team-leader/
    ├── agent.yaml
    ├── system.md
    └── skills/

模板默认只有 team-leader。新增成员时创建新的 agent 目录，并把 id 写入 team.yaml。

Team 配置文件

team.yaml 示例结构：

name: my-team
display_name: My Team
entry_agent: team-leader
loop:
  max_iterations: 0
  max_parallel_agents: 2
  completion_policy: team_leader_only
  stop_policy: user_interrupt_or_task_complete_only
gates:
  require_contract: false
  checks: []
transcript:
  show_member_dialogue: true
  show_tool_details: false
  show_thinking: false
agents:
  - team-leader

Agent agent.yaml：

name: team-leader
display_name: Team Leader
communicates_with: all
model: inherit
tools: inherit
max_turns_per_task: 0
private_skills: true

communicates_with 可以是 all 或 agent id 列表。专属 skill 放在该 agent 的 skills/ 目录。

快速开始

安装 CLI：

# macOS/Linux
make install

Windows PowerShell：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1

进入任意项目目录启动：

cd /path/to/project
lumina

执行一次性 prompt：

lumina -p "分析一下这个项目"

列出历史 session：

lumina --list

恢复历史 session：

lumina --resume <session-id>

启动目录就是默认工作目录。

API 配置

不内置默认模型。通过环境变量、命令行参数或 <AppRoot>/config/settings.json 配置：

export LUMINA_API_KEY="你的 API Key"
export LUMINA_API_BASE_URL="https://api.deepseek.com/anthropic"
export LUMINA_API_MODEL="deepseek-v4-pro[1m]"
export LUMINA_API_TYPE="anthropic"

也兼容 LLM_*，但 LUMINA_* 优先。等价参数：

lumina \
  --api-key "$LUMINA_API_KEY" \
  --base-url "https://api.deepseek.com/anthropic" \
  --api-type anthropic \
  --model "deepseek-v4-pro[1m]" \
  --max-tokens 1000000

配置优先级固定为：编译默认值、用户 config/settings.json、项目 .Lumina/CONFIG/defaults.json、环境变量、CLI 参数。默认路径由 apppaths 解析，不再写入用户 settings。

api-type：anthropic、openai_compatible、auto。

可以为所有运行链路配置独立的 fallback：

{
  "fallback_api_enabled": true,
  "fallback_api_key": "...",
  "fallback_api_base_url": "https://api.example.com/anthropic",
  "fallback_api_model": "fallback-model",
  "fallback_api_type": "anthropic"
}

主模型重试耗尽后，只在 429、5xx、timeout、EOF 和网络错误时切换。无效 Key、错误参数和模型配置错误不会被掩盖；主模型已经输出文本或 tool call 后也不会切换，避免重复输出和重复执行。配置会在下一轮热加载。

--max-tokens 是本地上下文窗口长度，用于统计和 80% 压缩阈值。API 请求不会强制携带供应商侧 completion max_tokens。runtime 配置会在每轮 Agent 请求前热读取。

远程记忆模型

BGE-M3 embedding 和可选 reranker 可以在 <AppRoot>/config/settings.json 中分别配置 OpenAI-compatible 远程服务：

{
  "memory_bge_provider": "openai_compatible",
  "memory_bge_api_key": "...",
  "memory_bge_base_url": "https://models.example.com/v1",
  "memory_bge_model": "BAAI/bge-m3",
  "memory_reranker_enabled": true,
  "memory_reranker_provider": "openai_compatible",
  "memory_reranker_api_key": "...",
  "memory_reranker_base_url": "https://models.example.com/v1",
  "memory_reranker_model": "BAAI/bge-reranker-v2-m3"
}

Embedding 服务需要实现 POST /v1/embeddings 并返回 1024 维 float 向量。Reranker 使用包含 query、documents 和 top_n 的 OpenAI-compatible rerank 扩展，兼容 /rerank 与 /reranks 响应中的 results[].relevance_score 或 data[].score。阿里云百炼的 compatible-mode/v1 Base URL 会自动规范化到其文档指定的 compatible-api/v1/reranks。切换 embedding endpoint 或 model 会改变检索指纹并重建派生向量，不会混用不同向量空间；API Key 不会进入指纹或诊断信息。 这些记忆模型字段只从用户 settings.json 读取，项目 defaults 和环境变量不能 覆盖。

项目说明文件

读取顺序：

1. {cwd}/LUMINA.md
2. {cwd}/AGENTS.md
3. <AppRoot>/config/instructions/LUMINA.md
4. <AppRoot>/config/instructions/AGENTS.md

这些文件都可以不存在。

Skills

Skill 是包含 SKILL.md 的指令包，读取位置：

• {project_root}/skills/
• {project_root}/.Lumina/PROJECT_SKILLS/
• <AppRoot>/config/skills/
• <AppRoot>/app/resources/skills/

Skill 上下文会注入本轮模型请求，但不进入可见对话。

/review 检查认证流程有没有安全问题

工具与权限

工具覆盖文件编辑、Shell、任务、记忆、WebSearch/WebFetch 和 MCP。敏感操作和项目 MCP 可要求人工确认。

MCP

项目 MCP 配置：.mcp.json。信任记录：

<AppRoot>/data/projects/{project-id}/trust/mcp.json

使用 /mcp 查看已注册 MCP 工具。

会话与运行数据

AppRoot 分为五个 ownership layer：

<AppRoot>/

• app/：可原子替换的程序、前端、内置资源和扩展。
• config/：用户设置、MCP、instructions、skills 和 teams。
• data/：长期记忆、session、项目 manifest/trust/team 和 legacy 数据。
• state/：endpoint、日志、服务、迁移报告和 tool-results。
• cache/：模型、下载和可重建临时文件。

项目级 runtime 数据：

<AppRoot>/data/projects/{project-id}/

• project.json
• trust/mcp.json
• teams/（旧 Team runtime 数据，遇到时执行导入）

项目内用户资源：

• {project_root}/skills/
• {project_root}/.Lumina/PROJECT_SKILLS/

active session 默认位于 <AppRoot>/data/sessions/active，archive 位于 <AppRoot>/data/sessions/archive：

{session_dir}/{session_id}/

• runtime.sqlite：权威 event journal 和 runtime checkpoint
• meta.json：体积较小、可重建的 session list projection
• migration-v2.json：旧 session 导入时生成的迁移报告
• .migration-backup/v1/：旧 session 导入时保留的源文件备份

数据库打开期间可能存在 runtime.sqlite-wal 和 runtime.sqlite-shm。一旦 `runtime.sqlite