一、项目定位与设计目标

Xenon（氙气轨道）是一款面向终端开发者的多模型 Agent CLI/TUI 工具，以交互式 REPL 为主要入口，强调"模型路由 + 工具协议 + 用户治理记忆 + 可观测性"四位一体的产品形态。其核心目标不是单一模型的封装,而是为 DeepSeek、火山方舟 Ark、OpenAI、Anthropic 等多 Provider 提供统一的会话壳层,并允许在同一会话内灵活切换引擎而不破坏提示缓存与工具契约。

flowchart LR
    User[用户] --> REPL[Xenon REPL]
    REPL --> Router[AutoRouter / 调度层]
    Router --> Pool[ModelPool]
    Pool --> DS[DeepSeek]
    Pool --> Ark[Volcano Ark]
    Pool --> Other[其他 Provider]
    REPL --> Tools[Tools / MCP / Skills]
    REPL --> Memory[User-Governed Memory]
    Tools --> Exec[执行环境]

资料来源：README.md:1-80 docs/GUIDE.md:1-60。

二、四大产品支柱

根据 v0.5.x 至 v0.7.x 的迭代脉络,Xenon 已形成以下四大支柱能力:

资料来源：README.md:40-150 docs/OPERATION_GUIDE.md:20-120。

三、安装与启动

3.1 依赖与运行入口

Xenon 通过 pyproject.toml 声明依赖,以 Python 模块方式启动,典型入口为 xenon/main.py。最简安装与运行命令如下:

# 安装（推荐使用 uv 或 pip）
pip install -e .

# 启动 REPL
xenon

# 指定配置文件启动
xenon --config ~/.xenon/config.toml

资料来源：pyproject.toml:1-40 xenon/main.py:1-60。

3.2 首次启动向导

首次运行会进入交互式向导,引导用户:

1. 选择主 Provider（默认 DeepSeek）并填入凭证
2. 选择 /import_models 的批量注册上限（受 OMNIAGENT_MAX_MODELS_PER_PROVIDER 控制）
3. 是否启用 MCP 惰性加载（默认开启,以缩短启动时间）
4. 是否启用 Vision Bridge 与视觉热键 Ctrl+Alt+V

资料来源：xenon/cli/repl.py:1-120 xenon/core/model_pool.py:1-90。

四、基础使用示例

4.1 斜杠命令速查

REPL 中所有用户可见功能均以 / 前缀暴露,常用命令包括:

• /help：列出全部命令
• /model <name>：在会话内切换模型（保持 Cache Rails）
• /mcp list | discover | install | call：管理 MCP 服务器
• /skill-discover | /skill-load：浏览与装载 Skill
• /vision on|off：切换视觉桥接器
• /memory add|list|forget：操作用户治理记忆
• /import_models：批量注册 Provider 模型

资料来源：xenon/cli/repl.py:120-260 xenon/core/agent.py:40-160。

4.2 一次最小任务流

> /model deepseek-chat
> /mcp install filesystem
> 请把当前目录的 README 摘要成 5 个 bullet

执行过程会触发：模型路由 → 工具契约下发 → MCP 子进程惰性连接 → 工作记忆更新 → 结果回显。资料来源：xenon/core/agent.py:160-280 xenon/mcp/manager.py:1-140。

4.3 升级与稳定性注意

v0.7.2 起,损坏的旧账本（ledger）会被一次性恢复并清理;v0.7.3 引入的 Cache Rails 在跨模型切换时保持 append-only,不重建缓存前缀,因此升级后无需手工清理会话历史。建议升级前备份 ~/.xenon/ 目录。资料来源：docs/OPERATION_GUIDE.md:120-220。

架构定位与设计原则

Xenon 是一个面向本地与云端混合场景的 Agent REPL（Read-Eval-Print Loop）框架，核心目标是在单一终端会话内统一管理模型路由、工具调用、记忆持久化与外部生态（MCP、Skill、Provider）集成。其架构遵循四条基本原则：

1. 会话不变性优先：会话状态、工具契约、记忆与缓存边界被提升为一等会话不变量，模型切换不会破坏这些不变量 资料来源：xenon/repl/session.py:1-60。
2. 惰性加载与按需连接：MCP 子进程、视觉桥接器、模型连接均采用首次调用才初始化的设计，避免 REPL 启动阻塞 资料来源：xenon/mcp/manager.py:20-80。
3. 用户治理的记忆：记忆写入需经显式确认，默认候选作用域为项目本地，未经确认绝不持久化 资料来源：xenon/memory/governed.py:30-90。
4. 生态可验证契约：对外暴露 xenon integrations verify 等机器可读 CLI，使 ArkCLI、VeADK 等外部 Agent 框架可执行端到端互操作校验 资料来源：xenon/cli.py:100-160。

核心分层结构

Xenon 采用自底向上的三层核心结构，辅以横切子系统：

横切子系统包括 xenon/router/（智能调度）、xenon/cache/（Cache Rails）、xenon/memory/（用户治理记忆）、xenon/mcp/（协议桥接）与 xenon/skills/（Agent Skills 注册中心）。Engine 层向上提供统一的模型调用接口，Nodes 层负责将单次 REPL 输入拆解为可并行执行的子任务，REPL 层则承载用户交互与状态展示 资料来源：xenon/engine/base.py:1-50 资料来源：xenon/nodes/base.py:1-50。

关键子系统

智能调度路由层

xenon/router/auto.py 中的 AutoRouter 基于 ModelPool（而非 ModelRegistry）选择模型，支持批量注册、会话粘性、资源感知、限流退避与配置热加载。每个 Provider 的注册上限可通过环境变量 OMNIAGENT_MAX_MODELS_PER_PROVIDER 调节，修复了 --config 仅喂 ModelRegistry 而未喂 ModelPool 的隐藏 bug 资料来源：xenon/router/auto.py:40-120。

Cache Rails（v0.7.3）

Cache Rails 是每个模型的仅追加（append-only）缓存边界，跨越模型切换而保留，并区分 engine、phase、tool-contract、context-epoch 四类不变量。工作记忆、检索记忆、轮次指引与执行边界被冻结进 Cache Rails，使提示缓存连续性成为会话级不变量而非模型级偶然行为 资料来源：xenon/cache/rails.py:1-70。

用户治理记忆（v0.7.0）

记忆系统引入 user、project-local、project-shared、session 四层作用域。metadata.json 保存权威状态、创建/更新/检索/使用时间戳、计数、重要度、置信度、固定、过期、来源与替代链；小型 Markdown 分类文件供用户直接人工审计。自动候选默认落在项目本地，未经用户确认绝不持久化 资料来源：xenon/memory/governed.py:30-130。

MCP 与 Skill 集成（v0.6.0+）

MCP 集成采用惰性加载：启动时不再阻塞于子进程连接（实测 12306-mcp 节省约 4.4s），首次 /mcp_call 才按需启动子进程。Smithery 云端库提供 7000+ 可发现服务器，支持 SSE 远程与 npx 本地两种传输，离线时回退至 30 分钟本地缓存。Skill 系统同样提供云端发现与本地精选两类来源 资料来源：xenon/mcp/manager.py:20-110。

数据流与会话生命周期

sequenceDiagram
    participant U as 用户
    participant R as REPL Session
    participant N as Nodes 编排
    participant E as Engine
    participant P as Model Pool
    participant T as 工具/MCP

    U->>R: 输入消息或斜杠命令
    R->>R: 解析意图、加载 Cache Rails
    R->>N: 派发为 Plan-Execute 任务图
    N->>E: 调用模型（含 Vision Bridge 兜底）
    E->>P: AutoRouter 选择模型实例
    P-->>E: 流式增量 + 工具调用请求
    E->>T: 执行工具/MCP 调用（惰性连接）
    T-->>E: 结果回传
    E-->>N: 增量事件
    N-->>R: 聚合输出 + 记忆候选
    R->>R: 用户治理记忆确认
    R-->>U: TUI 渲染（双线输入框）

REPL 会话在 v0.7.2 引入工具生命周期检查点与每次执行的 active ledger，Plan-Execute 并行工作器通过父会话持久化恢复事件，损坏的历史 ledger 仅重试一次后正确移除 资料来源：xenon/repl/session.py:60-140。这一会话级不变量体系使 Xenon 能够在多模型、多工具并发的场景下保持可恢复、可审计、可治理的运行特性。

概述

Xenon 的执行引擎层位于会话调度与模型调用之间，负责把抽象的"用户目标"拆解为可执行的推理步骤、工具调用序列与恢复点。xenon/engine/ 目录承载了多种推理范式的具体实现，每种范式都暴露统一的会话接口，使得 REPL、TUI 与外部 CLI（如 xenon integrations verify）能够以一致方式调度不同时序的 Agent 行为。

在 v0.7.x 演进过程中，这一层从单一 ReAct 循环扩展为可组合的多范式框架，并引入了持久化的执行账本以支持崩溃后的精确恢复。资料来源：xenon/engine/react_engine.py:1-40

推理范式分类

ReAct 循环引擎

react_engine.py 实现最基础的 ReAct（Reason + Act）范式：以 思考 → 行动 → 观察 三段式循环驱动单轮内的即时决策。该引擎是延迟最低的入口，适合轻量级多步工具调用场景。资料来源：xenon/engine/react_engine.py:42-110

引擎在每次循环中维护：

• 当前步的工作记忆片段
• 已调用工具的 JSON Schema 契约快照
• 最近一次观察的结构化结果

Plan-Execute 引擎

plan_execute_engine.py 提供计划-执行两阶段范式：先用一次模型调用产出完整子任务列表，再按计划分步执行。该范式在 v0.7.2 中引入了并行工作子节点，每个子任务由独立的 worker 进程处理并把恢复事件持久化回父会话账本。资料来源：xenon/engine/plan_execute_engine.py:55-180

并行能力的关键约束是：子任务之间的依赖关系必须显式建模，这由 plan_dag.py 提供的 DAG 结构保证。

反思引擎

reflection_engine.py 在主循环之外引入自我评估通道：当一次执行未达成目标置信度时，反思引擎会请求模型复盘失败原因并产出修订策略，再交回上层引擎重试。这一机制与 v0.7.0 引入的 User-Governed Memory 配合，使"经验教训"可以被显式候选并允许用户确认后持久化。资料来源：xenon/engine/reflection_engine.py:30-95

组合引擎

combined_engines.py 暴露范式编排接口，允许在同一会话内按阶段切换不同的推理范式，例如 ReAct → Reflection → Plan-Execute。所有切换都遵循 v0.7.3 的 Cache Rails 边界：每个范式保留独立的 engine / phase / tool-contract / context-epoch 上下文，避免跨范式提示缓存污染。资料来源：xenon/engine/combined_engines.py:20-70

Plan DAG 与调度

plan_dag.py 负责把 Plan-Execute 引擎产出的子任务列表转换为有向无环图，并暴露拓扑序、依赖闭包与并行 frontier 等查询接口。调度器 scheduler.py 消费该 DAG，按资源感知策略在并发 worker 之间分配子节点；v0.5.5 的智能调度路由层增强为该调度器注入了会话粘性、限流退避与配置热加载能力。资料来源：xenon/engine/plan_dag.py:18-82、xenon/engine/scheduler.py:40-130

调度器与模型池（ModelPool）联动：当子任务被路由到不同模型时，v0.7.3 的 per-model Cache Rails 保证各自的 append-only 提示前缀不会跨模型串扰。

状态持久化与恢复

v0.7.2 起每个执行引擎都维护一份活动账本（active ledger），记录工具生命周期检查点与每轮执行边界。异常退出时，下一次启动会读取该账本并由 combined_engines.py 的恢复逻辑决定是续跑、跳过还是回滚到上一个稳定检查点。损坏的旧格式账本只尝试一次修复并正确清除。资料来源：xenon/engine/combined_engines.py:130-205

这一设计与 Cache Rails 共同构成会话级不变量：即使模型发生切换或调度策略变化，仍可恢复出确定性的执行轨迹。

选型指引

概述与设计目标

Cache Rails 是 Xenon v0.7.3 引入的会话级不变量机制，用于把"提示词缓存连续性"提升为一等公民。在 DeepSeek 等支持 prompt cache 的推理后端里，前缀稳定才能命中 KV cache，进而摊薄输入 token 计费与首字延迟。Xenon 的目标是：用户在一次会话中即使切换模型或调整阶段，缓存命中的前缀仍可继续复用，避免每次手动重放历史。资料来源：xenon/utils/deepseek_cache.py:1-40

具体落地形态是"per-model append-only Cache Rails"：每个已注册的模型各自拥有一条只追加的轨道，而不是所有模型共用一条。前缀追加是单向的，回退或截断都视为新边界，由此保证 KV cache 的对齐语义。资料来源：xenon/utils/cache_telemetry.py:1-40

架构与组件协作

Cache Rails 由三个核心工具协作支撑：

• deepseek_cache.py 负责构造稳定的"缓存友好前缀"，把系统提示、工具契约、执行边界等块按 DeepSeek 缓存策略对齐成连续段。
• prompt_compiler.py 负责把工作记忆、检索记忆、当轮引导与执行边界编译进同一份 prompt，并显式标注哪些段属于"冻结前缀"、哪些属于"变量尾巴"。
• cache_telemetry.py 记录每次追加的命中状态、边界事件和 epoch 编号，供 /cache 命令与诊断面板使用。
• token_estimate.py 为追加前的草稿做近似 token 预算校验，防止单次追加跨越某个 provider 的 cache 失效阈值。

flowchart LR
    A[用户输入] --> B[prompt_compiler.py]
    B --> C{是否命中既有 Rail?}
    C -- 命中 --> D[deepseek_cache.py<br/>追加变量段]
    C -- 未命中 --> E[新建 per-model Rail]
    D --> F[推理后端]
    E --> F
    F --> G[cache_telemetry.py<br/>记入命中/边界]
    G --> H[token_estimate.py<br/>预算回写]
    H --> B

资料来源：xenon/utils/prompt_compiler.py:1-60、xenon/utils/cache_telemetry.py:40-120、xenon/utils/token_estimate.py:1-50

四类不变量边界

每条 Cache Rail 通过四类边界来维持隔离语义，禁止跨边界复用：

任意一类边界变化都会冻结旧 Rail、开启新 Rail，确保命中不会跨越不兼容的前缀段。资料来源：xenon/utils/deepseek_cache.py:60-140、docs/deepseek-guide.md:1-80

与模型路由的关系

Xenon 同时提供智能调度路由（v0.5.5 的 P0–P3 增强），可在会话中自由切换模型。Cache Rails 把"路由灵活"与"缓存连续"解耦：切换模型只是打开对应模型自己的 Rail，旧 Rail 仍可被同模型的后续调用复用。资料来源：docs/DEEPSEEK_INTEGRATION.md:1-120

这种设计的两个直接收益是：(1) 用户在 /import_models 批量注册后切换模型不会清空历史；(2) Plan-Execute 的并发 worker 各自维持独立 Rail，结束后由父会话合并遥测。资料来源：xenon/utils/cache_telemetry.py:120-200

使用建议与观测

• 通过 /cache 查看当前每个模型的 Rail 长度、命中比例与最近边界事件。
• 当命中比骤降时，先检查是否触发了 tool-contract 或 phase 边界，再考虑清理重复前缀。
• 长会话里依赖隐式压缩时，关注 context-epoch 递增；过度重置会浪费已建立的 cache 锚点。

资料来源：xenon/utils/cache_telemetry.py:200-260、docs/deepseek-guide.md:80-160

概述与定位

Xenon 用户治理记忆系统（User-Governed Memory）于 v0.7.0 引入，作为继工具执行、模型路由、会话连续性之后的第四大产品支柱，定位为"由用户掌控"而非"由模型暗箱积累"的长期事实库。其核心原则是：任何候选记忆未经显式确认绝不持久化，避免 Agent 在长会话中悄然把噪声固化为"知识"。服务入口封装在 xenon/memory/service.py 中，对上层提供 CRUD、按上下文注入、替代链追踪等原子能力；同时通过 xenon/memory/backend.py 抽象底层读写，使文件系统、向量库、可插拔 Provider 同等接入。资料来源：xenon/memory/service.py:1-80、xenon/memory/backend.py:1-60。

作用域模型与分类存储

记忆按可见性与生命周期被划分到四个互不重叠的作用域，构成嵌套优先级的检索层：

每个作用域内进一步切分为小型 Markdown 分类文件，便于用户用普通编辑器直接打开审计；分类单元由 xenon/memory/registry.py 登记并维护类别到目录的映射。资料来源：xenon/memory/registry.py:1-120、xenon/memory/models.py:30-140。

候选机制与持久化守卫

flowchart LR
    A[模型输出候选] --> B{命中现有事实?}
    B -- 否 --> C[写入候选池<br/>默认 project-local]
    B -- 是 --> D[合并 / 替代链更新]
    C --> E{用户确认?}
    E -- 否 --> F[丢弃或保留为草稿]
    E -- 是 --> G[提升为持久条目]
    D --> H[更新元数据]
    G --> H

xenon/memory/candidate.py 实现"候选-确认"双段写入：模型或工具在推理中产生的任何新事实先落入候选池（默认 project-local，可被用户改写），随后等待用户通过终端回执或显式命令确认。未经确认的候选只参与本回合的上下文注入，不会写盘，也不会进入未来检索。这一守卫把"会不会记住"的决定权完全交给用户，避免 v0.7.0 之前的隐式累积风险。资料来源：xenon/memory/candidate.py:1-110。

元数据规范与替代链

权威状态统一在每条记忆伴生的 metadata.json 中保存，字段集合包括：创建/更新/检索/使用时间戳、使用计数、importance、confidence、pinned（固定）、expires_at（过期）、source（来源：user/tool/model），以及指向被取代条目的 supersedes/superseded_by 链表。该规范在 xenon/memory/models.py 中以强类型 schema 定义，避免运行期字段漂移。资料来源：xenon/memory/models.py:140-260。

检索、注入与上下文连续性

检索由 xenon/memory/retrieval.py 提供查询接口，作用域优先级自上而下为 user → project-shared → project-local → session，返回结果按 importance、confidence 与时效加权排序。检索粒度支持：单条精确、分类聚合、作用域批量与上下文自动注入四种调用形态。后者在每次会话开始时把工作记忆、检索到的长期记忆和当前轮指引（per-turn guidance）一并冻结到 Cache Rails，确保模型即使切换、上下文 epoch 重建也不会回退到无记忆起点。资料来源：xenon/memory/retrieval.py:1-160、xenon/memory/service.py:80-200。

边界与版本约束

• 单条、分类、作用域、上下文注入四种粒度全部受相同的确认守卫约束，无任何路径绕过用户确认。
• 候选默认作用域可由用户在回执中改写，但不会自动升级到 user 或 project-shared。
• 替代链（supersession）只允许同作用域内链接，跨作用域需要用户显式迁移。

资料来源：xenon/memory/candidate.py:110-180、xenon/memory/models.py:260-320。

小结

用户治理记忆系统把记忆的"产生、确认、分类、检索、冻结"五个环节显式化：service.py 统一对外契约，models.py 固化权威 schema，registry.py 管理分类映射，backend.py 解耦介质，retrieval.py 提供四粒度检索，candidate.py 守好最后一道用户确认关口。它既是对 v0.7.0 之前隐式记忆风险的修订，也是 v0.7.3 Cache Rails 在记忆侧的稳态保证：每次会话开始就把记忆状态固化下来，使长期事实与短期协作在同一份连续上下文中协同工作。

概述与职责范围

终端交互界面与命令系统是 Xenon Agent 暴露给最终用户的主交互面，承担"输入 → 解析 → 路由 → 渲染 → 上下文维持"的完整会话回路。所有模型调用、工具执行、记忆读写、MCP/Skill 集成均通过该层下发与回收，是连接 CLI 用户、ReAct 主循环、外部 Provider 与本地文件系统之间的统一门面。

其设计目标是：

• 提供零阻塞、低延迟的 REPL 启动体验（v0.6.0 起 MCP 子进程改为惰性加载）
• 在不重启会话的前提下热切换命令、热绑定热键、热加载模型配置
• 把"模型路由、工具协议、权限回执、上下文连续性"四类信号在终端层做统一收敛（v0.7.0 系统性加固）
• 保持会话不变量（Cache Rails、User-Governed Memory 作用域、Tool 生命周期 checkpoint）在用户切换命令与模型时不被破坏

资料来源：xenon/repl/repl.py:1-80

模块组成与职责划分

资料来源：xenon/repl/repl.py:1-60、xenon/repl/commands.py:1-60

主循环与会话装配

repl.py 是整个终端层的入口。它在启动阶段按以下顺序工作：

1. 输出"氙气轨道 Σ-3"启动动画 Logo，并在终端标签页写入 ✦ Xenon（v0.6.1）
2. 装配 ShortcutManager、InputBuffer、StatusBar、ContextManager，再把它们注入到命令分发器
3. 进入读-求值-打印循环：阻塞读取用户输入 → 派发到 commands.py 或 ReAct 引擎 → 收集流式事件 → 渲染到 stdout/stderr

主循环同时负责"会话不变量"的恢复：从磁盘读取 Cache Rail 与 Tool 生命周期 checkpoint，校验 model 切换后 engine、phase、tool-contract、context-epoch 边界是否仍然完整（v0.7.3 Cache Rails）。

flowchart LR
    A[用户按键/粘贴] --> B[ShortcutManager]
    A --> C[InputBuffer]
    B --> D[REPL 主循环]
    C --> D
    D --> E{输入以 / 开头?}
    E -- 是 --> F[Commands 路由]
    E -- 否 --> G[ReAct 主循环]
    F --> H[StatusBar 反馈]
    G --> H
    H --> I[ContextManager 写回]

资料来源：xenon/repl/repl.py:60-180、xenon/repl/shortcut_manager.py:1-80、xenon/repl/context_manager.py:1-80

斜杠命令系统

commands.py 是所有显式操作的注册中心。当前已知的命令族包括：

• MCP 系列：/mcp discover 实时浏览 Smithery 注册中心 7000+ 服务器；/mcp install <name> 一键安装并持久化；/mcp list 区分"惰性 vs 已连接"；/mcp_call <name> 首次调用才启动子进程（v0.6.0）
• Skill 系列：/skill-discover 浏览 28 个精选 Skill（v0.6.0）
• 模型调度：/import_models 批量注册多 provider 模型（v0.5.5）
• 视觉桥接：/vision on 开启多模态模式，配合 Ctrl+Alt+V 粘贴图片触发自动转录（v0.6.1）
• 集成校验：xenon integrations verify（CLI 入口）默认只读检查四层 Agent Skill 根目录、MCP 配置、stdio 命令与凭证权限；显式 --connect-mcp 后执行真实 MCP 握手（v0.7.1）

命令系统对每个分发动作都套上权限拦截：例如工具调用前会要求用户回执确认；参数拦截被破坏时，v0.5.3 修复了"参数拦截恢复提示"的回显问题。

资料来源：xenon/repl/commands.py:1-200、xenon/repl/commands.py:200-400

输入缓冲、快捷键与状态栏

输入缓冲（input_buffer.py）在 v0.5.4 被重做为 Claude Code 风格的双线输入框——两条平行横线框出输入区域，使多轮上下文下的光标定位与命令历史更易识别。

快捷键（shortcut_manager.py）采用"首次按下才初始化"的惰性策略：例如视觉桥接器在 Ctrl+Alt+V 首次触发时才建立模型连接，因此 REPL 启动零开销；匹配算法先扫描 ModelPool，再兜底读取 credentials，并过滤掉 embedding 模型，结果以 SHA256 缓存去重避免重复调用（v0.6.1）。

状态栏（status_bar.py）使用"值+分隔符"的紧凑形态，去除冗余标签，集中显示当前模型、会话粘性、限流退避状态等指标（v0.5.4）。

资料来源：xenon/repl/input_buffer.py:1-120、xenon/repl/shortcut_manager.py:80-200、xenon/repl/status_bar.py:1-120

上下文与会话连续性

context_manager.py 是会话不变量的"记忆中枢"，承担四类职责：

1. 工作记忆与检索记忆：在每轮推理前冻结到当前 context-epoch，模型切换后仍可被检索（v0.7.3）
2. 本轮指引（per-turn guidance）：与执行边界一同写入 Cache Rail，确保 prompt-cache 续期不丢字段
3. User-Governed Memory 作用域：在 v0.7.0 中引入 user / project-local / project-shared / session 四层，自动候选默认落在项目本地，未经用户确认绝不持久化
4. Tool 生命周期 checkpoint：v0.7.2 起为并行 Plan-Execute worker 提供持久化的 active ledger，malformed legacy ledger 可被一次性恢复并清理

资料来源：xenon/repl/context_manager.py:80-260

演进里程碑（与本主题相关）

• v0.5.4：双线输入框 + 状态栏重构 + 仓库清理
• v0.5.5：智能调度路由层增强 P0–P3，落地 /import_models 与配置热加载
• v0.6.0：MCP/Skill 云端库 + 惰性加载，REPL 启动不再阻塞子进程
• v0.6.1：视觉桥接器、Ctrl+Alt+V 热键、启动动画 Logo ✦ Xenon
• v0.7.0：终端交互系统性加固 + User-Governed Memory
• v0.7.1：CLI 形态的 xenon integrations verify 与 Ark Provider 一等接入
• v0.7.3：Cache Rails 作为跨模型切换的会话不变量

资料来源：xenon/repl/repl.py:1-40、xenon/repl/commands.py:1-40

概述与设计目标

Xenon 在 v0.6.0 引入 MCP（Model Context Protocol）与 Skill 云端库，并把"惰性加载"作为该生态的第一原则；v0.7.1 进一步把 Agent Skills 与集成 CLI 升级为接入 ArkCLI、VeADK 等外部 Agent 的稳定契约基线。该生态的核心目标，是让 Xenon 终端 Agent 能够以可插拔、机器可校验、零启动阻塞的方式接入外部工具协议与领域知识技能 资料来源：docs/INTEGRATIONS.md:1-40。

核心组件与运行时行为

生态由五个相互衔接的模块组成：

• MCP 客户端封装 stdio / SSE 两种传输通道，对外暴露统一的工具调用接口；本地缓存 30 分钟用于离线兜底 资料来源：xenon/mcp/client.py:1-160。
• MCP 注册中心维护 Smithery 远程服务器（SSE）与本地服务器（npx）两类来源；/mcp list 同时显示"惰性"与"已连接"两种状态 资料来源：xenon/mcp/registry.py:30-180。
• 传输层抽象统一协议头封装，让注册中心与客户端不必关心底层是子进程还是 HTTP 长连接 资料来源：xenon/mcp/transport.py:1-120。
• Skill 发现层实现 user / project-local / project-shared / session 四层根目录的搜索与合并，与 v0.7.0 引入的 User-Governed Memory 作用域形成镜像 资料来源：docs/AGENT_SKILLS.md:20-110。
• 集成 CLIxenon integrations verify 默认只读扫描技能根目录、MCP 配置、stdio 命令与凭证权限；显式传入 --connect-mcp 后执行真实 initialize → initialized 握手，输出机器可读报告 资料来源：xenon/integration_cli.py:60-220。

启动阶段不再预先 fork 所有 MCP 子进程——以 12306-mcp 为例，此举节省约 4.4 秒；只有当用户首次触发 /mcp_call 时，注册中心才会按需启动对应子进程。/mcp discover 实时浏览 Smithery 上 7000+ 远端条目，/mcp install <name> 一键安装并把元数据持久化到本地注册表 资料来源：docs/INTEGRATIONS.md:60-150。

sequenceDiagram
    participant U as 用户
    participant REPL as Xenon REPL
    participant CLI as integrations verify
    participant SK as Skill 层
    participant RG as MCP 注册中心
    participant SV as 远程/本地 MCP 服务
    U->>REPL: 启动
    REPL->>SK: 扫描四层根目录
    REPL->>RG: 加载注册表(惰性)
    CLI->>REPL: --connect-mcp
    REPL->>RG: 选择 stdio/SSE
    RG->>SV: initialize → initialized
    SV-->>RG: tools/list
    RG-->>REPL: 工具清单(就绪)
    U->>REPL: /mcp_call
    REPL->>SV: 调用具体工具

互操作校验与生态契约

v0.7.1 把"配置合法"与"握手可达"两种验证状态显式区分：xenon integrations verify 不带参数时只检查四层 Agent Skill 根目录是否存在、MCP 配置是否完整、stdio 命令是否可解析、凭证权限是否齐备；带 --connect-mcp 时才真正发起 initialize → initialized 握手并比对 tools/list 结果 资料来源：xenon/integration_cli.py:120-260。同时，llms.txt 被设为 Skill 描述的优先文档检索来源，使模型在上下文窗口里优先看到 Skill 元数据 资料来源：docs/AGENT_SKILLS.md:130-180。Smithery SSE 与本地 npx 并存，体现"远程优先 + 本地兜底"的弹性拓扑。

与其它支柱的关系及常用命令

• User-Governed Memory (v0.7.0)：Skill 自动候选默认进入 project-local 作用域，未经用户确认绝不持久化；与四层 Skill 根目录在路径与权限模型上保持一致 资料来源：docs/AGENT_SKILLS.md:20-110。
• Cache Rails (v0.7.3)：MCP 工具契约被冻结到工具-契约边界，使模型切换不会破坏外部协议侧的提示缓存 资料来源：docs/INTEGRATIONS.md:160-220。
• 视觉桥接器 (v0.6.1)：当 Skill 触发多模态推理时复用同一惰性加载路径，避免额外 MCP 进程 资料来源：xenon/mcp/client.py:200-280。

通过"惰性 + 可校验 + 多层作用域"三原则，MCP 与 Agent Skills 生态让 Xenon 在保持终端轻启动的同时具备企业级 Agent 工具接入能力。

一、工具节点族：注册、节点、执行三层

工具在 Xenon 中被拆分为三个角色，互不重叠且单向依赖：

• tool_registry.py：负责工具定义与元数据的集中注册。注册表维护工具名、参数 schema、能力标签（capability）、来源（本地 / MCP / Skill），并提供查询接口供 tool_node 在回合开始时拉取可见集合 资料来源：xenon/nodes/tool_registry.py:1-80。
• tool_node.py：作为 ReAct 循环中的"决策节点"。它根据模型输出中的 tool_call 名称，从 registry 解析为可执行对象，构造参数并下发给执行器；负责把结果回填到上下文消息流 资料来源：xenon/nodes/tool_node.py:40-120。
• tool_executor.py：唯一真正"动手"的层。它封装同步/异步调用、超时控制、MCP stdio/SSE 子进程生命周期、惰性连接（首次 /mcp_call 才启动）以及结果序列化；所有副作用在此落地 资料来源：xenon/nodes/tool_executor.py:30-110。

三层之间的数据流可以用如下表格描述：

二、安全层：熔断器与执行追踪

工具一旦拥有写文件、起子进程、访问网络的能力，就必须有"刹车"和"黑匣子"，这正是 engine 下两个模块的职责。

• circuit_breaker.py：为每个工具维护半开 / 关闭 / 打开三态。连续失败达到阈值后熔断器跳闸，冷却期内 tool_node 的调用请求会被快速失败而不是真正执行；半开态按可配置比例放行探测请求，确认恢复后才回到关闭 资料来源：xenon/engine/circuit_breaker.py:20-90。这直接呼应 v0.7.2 的 Stability Hardening 主题——"Durable tool lifecycle checkpoints and per-execution active ledgers"——确保一个工具反复崩溃不会拖垮整个会话。
• tool_tracker.py：记录每次执行的"四元组"：工具名、参数哈希、起止时间、退出码与输出摘要。这些记录在 v0.7.2 之后被持久化到活动账本（active ledger），用于崩溃恢复后回放 Plan-Execute worker 的恢复事件 资料来源：xenon/engine/tool_tracker.py:1-70。
• tool_runtime.py：扮演 host，对上接 tool_node、对下同时调度 executor、breaker、tracker，保证副作用因果链路一致；任何一次工具调用都携带 execution_id 穿越三层 资料来源：xenon/engine/tool_runtime.py:50-130。

三、模型路由与配置链路

工具之外，模型侧的路由同样关键。v0.5.5 智能调度路由层增强（P0–P3）打通了如下不变量：

• ModelRegistry 与 ModelPool 同时接收 --config：修复了 v0.5.5 之前的隐藏 bug——AutoRouter 使用的是 ModelPool，若 --config 只注入 ModelRegistry，配置实际上失效；同时修复了 load_from_file 中 weight 字段丢失的问题，并新增 OMNIAGENT_MAX_MODELS_PER_PROVIDER 控制首跑 / 向导时每个 provider 的注册上限 资料来源：xenon/engine/tool_runtime.py:80-140。
• 批量注册 /import_models：由新模块 batch_importer 提供一次写入多 provider、多模型的能力，避免手工反复输入，便于粘性会话在 provider 故障后批量切换 资料来源：xenon/nodes/tool_registry.py:60-120。
• 限流退避与配置热加载：路由层维护会话粘性（同一会话优先同一 provider），并在 429/5xx 时按退避策略降级到次选 provider；配置文件被监听，热加载无需重启进程 资料来源：xenon/engine/tool_runtime.py:140-200。

四、与上层特性的一致性

Cache Rails（v0.7.3）要求"工作记忆、检索记忆、按轮指引、执行边界"被冻结到 per-model 的追加式轨道中。tool_tracker 写入的执行边界正是"执行边界"的载体——当用户在同一会话切换模型时，新模型的 Cache Rail 会以旧模型的执行账本为种子续写，从而保留 engine / phase / tool-contract / context-epoch 四个边界 资料来源：xenon/engine/tool_tracker.py:60-110。

综合来看，工具节点族提供"能做什么"，安全层提供"何时停"，模型路由层提供"交给谁"，三层通过 tool_runtime 的统一调度在每个 ReAct 回合中闭环。

Pitfall Log / 踩坑日志

项目：xianyu-sheng/Xenon

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/xianyu-sheng/Xenon | host_targets=mcp_host, claude, chatgpt, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/xianyu-sheng/Xenon | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/xianyu-sheng/Xenon | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/xianyu-sheng/Xenon | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/xianyu-sheng/Xenon | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/xianyu-sheng/Xenon | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/xianyu-sheng/Xenon | release_recency=unknown