# https://github.com/xianyu-sheng/Xenon 项目说明书
生成时间：2026-07-31 04:57:05 UTC
## 目录
- [项目概览与快速开始](#page-1)
- [系统架构总览](#page-2)
- [执行引擎与推理范式](#page-3)
- [Cache Rails 与提示词缓存](#page-4)
- [用户治理记忆系统](#page-5)
- [终端交互界面与命令系统](#page-6)
- [MCP 与 Agent Skills 生态](#page-7)
- [工具系统、安全与模型路由](#page-8)
## 项目概览与快速开始
### 相关页面
相关主题：[系统架构总览](#page-2), [终端交互界面与命令系统](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/xianyu-sheng/Xenon/blob/main/README.md)
- [docs/GUIDE.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/GUIDE.md)
- [docs/OPERATION_GUIDE.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/OPERATION_GUIDE.md)
- [pyproject.toml](https://github.com/xianyu-sheng/Xenon/blob/main/pyproject.toml)
- [xenon/main.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/main.py)
- [xenon/cli/repl.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/cli/repl.py)
- [xenon/core/agent.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/core/agent.py)
- [xenon/core/model_pool.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/core/model_pool.py)
- [xenon/mcp/manager.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/mcp/manager.py)
# 项目概览与快速开始
## 一、项目定位与设计目标
Xenon（氙气轨道）是一款面向终端开发者的多模型 Agent CLI/TUI 工具，以交互式 REPL 为主要入口，强调"模型路由 + 工具协议 + 用户治理记忆 + 可观测性"四位一体的产品形态。其核心目标不是单一模型的封装,而是为 DeepSeek、火山方舟 Ark、OpenAI、Anthropic 等多 Provider 提供统一的会话壳层,并允许在同一会话内灵活切换引擎而不破坏提示缓存与工具契约。
```mermaid
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 已形成以下四大支柱能力:
| 支柱 | 关键能力 | 代表命令 |
| --- | --- | --- |
| 模型路由 | 多 Provider 注册、会话粘性、限流退避、配置热加载 | `/import_models` |
| 工具协议 | MCP 云端库（Smithery）、Skill 云端库、惰性加载 | `/mcp discover`、`/skill-discover` |
| 用户治理记忆 | 四层作用域（user / project-local / project-shared / session） | `/memory` 子命令 |
| 上下文连续性 | Per-model Cache Rails、工作记忆、检索记忆、每轮引导冻结 | 自动维持 |
资料来源：[README.md:40-150]() [docs/OPERATION_GUIDE.md:20-120]()。
## 三、安装与启动
### 3.1 依赖与运行入口
Xenon 通过 `pyproject.toml` 声明依赖,以 Python 模块方式启动,典型入口为 `xenon/main.py`。最简安装与运行命令如下:
```bash
# 安装（推荐使用 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 `：在会话内切换模型（保持 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 一次最小任务流
```text
> /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]()。
---
**下一步建议**:阅读《模型路由与配置》了解 `/import_models` 与 Provider 权重细节;阅读《MCP 与 Skill 集成》掌握云端库与惰性加载语义。
---
## 系统架构总览
### 相关页面
相关主题：[项目概览与快速开始](#page-1), [执行引擎与推理范式](#page-3), [工具系统、安全与模型路由](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [docs/ARCHITECTURE.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/ARCHITECTURE.md)
- [xenon/__init__.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/__init__.py)
- [xenon/engine/base.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/base.py)
- [xenon/nodes/base.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/nodes/base.py)
- [xenon/repl/session.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/session.py)
- [xenon/router/auto.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/router/auto.py)
- [xenon/memory/governed.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/governed.py)
- [xenon/cache/rails.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/cache/rails.py)
- [xenon/mcp/manager.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/mcp/manager.py)
- [xenon/cli.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/cli.py)
# 系统架构总览
## 架构定位与设计原则
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 采用自底向上的三层核心结构，辅以横切子系统：
| 层级 | 职责 | 关键模块 |
|------|------|---------|
| **Engine 层** | 模型推理适配、消息装配、工具 schema 序列化 | `xenon/engine/base.py` |
| **Nodes 层** | 任务图编排、Plan-Execute 并行工作器、节点间事件传递 | `xenon/nodes/base.py` |
| **REPL 层** | 终端交互、命令解析、TUI 双线输入框、会话生命周期 | `xenon/repl/session.py` |
横切子系统包括 `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]()。
## 数据流与会话生命周期
```mermaid
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 能够在多模型、多工具并发的场景下保持可恢复、可审计、可治理的运行特性。
---
## 执行引擎与推理范式
### 相关页面
相关主题：[系统架构总览](#page-2), [Cache Rails 与提示词缓存](#page-4), [工具系统、安全与模型路由](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [xenon/engine/react_engine.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/react_engine.py)
- [xenon/engine/plan_execute_engine.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/plan_execute_engine.py)
- [xenon/engine/reflection_engine.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/reflection_engine.py)
- [xenon/engine/combined_engines.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/combined_engines.py)
- [xenon/engine/plan_dag.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/plan_dag.py)
- [xenon/engine/scheduler.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/scheduler.py)
# 执行引擎与推理范式
## 概述
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 共同构成会话级不变量：即使模型发生切换或调度策略变化，仍可恢复出确定性的执行轨迹。
## 选型指引
| 范式 | 适用场景 | 关键文件 |
|---|---|---|
| ReAct | 短链工具调用、低延迟 | `react_engine.py` |
| Plan-Execute | 多步、可并行的复合任务 | `plan_execute_engine.py` + `plan_dag.py` |
| Reflection | 需要自我纠错的探索性任务 | `reflection_engine.py` |
| Combined | 复杂会话内范式切换 | `combined_engines.py` |
---
## Cache Rails 与提示词缓存
### 相关页面
相关主题：[执行引擎与推理范式](#page-3), [MCP 与 Agent Skills 生态](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [xenon/utils/deepseek_cache.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/utils/deepseek_cache.py)
- [xenon/utils/cache_telemetry.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/utils/cache_telemetry.py)
- [xenon/utils/prompt_compiler.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/utils/prompt_compiler.py)
- [xenon/utils/token_estimate.py](https://github.com/xianyu-sheng/Xenon/utils/token_estimate.py)
- [docs/deepseek-guide.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/deepseek-guide.md)
- [docs/DEEPSEEK_INTEGRATION.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/DEEPSEEK_INTEGRATION.md)
# 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 失效阈值。
```mermaid
flowchart LR
A[用户输入] --> B[prompt_compiler.py]
B --> C{是否命中既有 Rail?}
C -- 命中 --> D[deepseek_cache.py
追加变量段]
C -- 未命中 --> E[新建 per-model Rail]
D --> F[推理后端]
E --> F
F --> G[cache_telemetry.py
记入命中/边界]
G --> H[token_estimate.py
预算回写]
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 通过四类边界来维持隔离语义，禁止跨边界复用：
| 边界类型 | 含义 | 典型触发 |
|---------|------|---------|
| engine | 推理引擎或 SDK 路径变化 | provider 切换、SDK 升级 |
| phase | 会话阶段（如 plan / execute / reflect）切换 | 进入 Plan-Execute、进入反思 |
| tool-contract | 工具契约 schema 变化 | MCP 工具增删、参数签名变更 |
| context-epoch | 上下文纪元（如隐式压缩、长任务刷新） | 长任务节流、长上下文重置 |
任意一类边界变化都会冻结旧 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]()
---
## 用户治理记忆系统
### 相关页面
相关主题：[系统架构总览](#page-2), [终端交互界面与命令系统](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [xenon/memory/service.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/service.py)
- [xenon/memory/models.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/models.py)
- [xenon/memory/registry.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/registry.py)
- [xenon/memory/retrieval.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/retrieval.py)
- [xenon/memory/candidate.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/candidate.py)
- [xenon/memory/backend.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/memory/backend.py)
# 用户治理记忆系统
## 概述与定位
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]()。
## 作用域模型与分类存储
记忆按可见性与生命周期被划分到四个互不重叠的作用域，构成嵌套优先级的检索层：
| 作用域 | 生命周期 | 写入触发 | 典型用途 |
|--------|----------|----------|----------|
| `user` | 跨项目永久 | 用户手动 | 跨工程复用的偏好 |
| `project-shared` | 项目内多人共享 | 用户手动/团队约定 | 团队约定 |
| `project-local` | 单项目内 | 自动候选 + 确认 | 项目事实库默认落点 |
| `session` | 当前会话 | 自动 | 短上下文工作记忆 |
每个作用域内进一步切分为小型 Markdown 分类文件，便于用户用普通编辑器直接打开审计；分类单元由 `xenon/memory/registry.py` 登记并维护类别到目录的映射。资料来源：[xenon/memory/registry.py:1-120]()、[xenon/memory/models.py:30-140]()。
## 候选机制与持久化守卫
```mermaid
flowchart LR
A[模型输出候选] --> B{命中现有事实?}
B -- 否 --> C[写入候选池
默认 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 在记忆侧的稳态保证：每次会话开始就把记忆状态固化下来，使长期事实与短期协作在同一份连续上下文中协同工作。
---
## 终端交互界面与命令系统
### 相关页面
相关主题：[项目概览与快速开始](#page-1), [工具系统、安全与模型路由](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [xenon/repl/repl.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/repl.py)
- [xenon/repl/commands.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/commands.py)
- [xenon/repl/status_bar.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/status_bar.py)
- [xenon/repl/input_buffer.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/input_buffer.py)
- [xenon/repl/shortcut_manager.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/shortcut_manager.py)
- [xenon/repl/context_manager.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/repl/context_manager.py)
# 终端交互界面与命令系统
## 概述与职责范围
终端交互界面与命令系统是 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]()
## 模块组成与职责划分
| 模块 | 文件 | 主要职责 |
| --- | --- | --- |
| 主循环 | `repl.py` | 启动 Logo 动画、装配组件、调度命令分发与会话恢复 |
| 命令注册表 | `commands.py` | 斜杠命令的注册、解析、权限拦截、补全建议 |
| 输入缓冲 | `input_buffer.py` | 双线输入框渲染、字符流编辑、多行输入栈 |
| 快捷键 | `shortcut_manager.py` | 全局/上下文敏感热键，例如 `Ctrl+Alt+V` 视觉桥接 |
| 状态栏 | `status_bar.py` | "值+分隔符"实时状态条（v0.5.4 重构后的形态） |
| 上下文 | `context_manager.py` | 工作记忆、检索记忆、本轮指引、执行边界维护 |
资料来源：[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）。
```mermaid
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 ` 一键安装并持久化；`/mcp list` 区分"惰性 vs 已连接"；`/mcp_call ` 首次调用才启动子进程（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]()
---
## MCP 与 Agent Skills 生态
### 相关页面
相关主题：[系统架构总览](#page-2), [Cache Rails 与提示词缓存](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [xenon/mcp/client.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/mcp/client.py)
- [xenon/mcp/registry.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/mcp/registry.py)
- [xenon/mcp/transport.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/mcp/transport.py)
- [xenon/integration_cli.py](https://github.com/xianyu-sheng/Xenon/integration_cli.py)
- [docs/AGENT_SKILLS.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/AGENT_SKILLS.md)
- [docs/INTEGRATIONS.md](https://github.com/xianyu-sheng/Xenon/blob/main/docs/INTEGRATIONS.md)
# MCP 与 Agent Skills 生态
## 概述与设计目标
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]()。
- **集成 CLI**`xenon 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 ` 一键安装并把元数据持久化到本地注册表 资料来源：[docs/INTEGRATIONS.md:60-150]()。
```mermaid
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 discover` | 浏览 Smithery 注册中心 | 30 分钟本地缓存 |
| `/mcp install ` | 一键安装并持久化 | 远程 SSE / 本地 npx |
| `/mcp list` | 列出注册表 | 显示惰性 vs 已连接 |
| `/mcp_call` | 触发懒连接 | 首次调用才启子进程 |
| `/skill-discover` | 浏览精选 Skill 库 | v0.6.0 起 28 个 |
| `xenon integrations verify [--connect-mcp]` | 只读 / 握手校验 | 机器可读报告 |
通过"惰性 + 可校验 + 多层作用域"三原则，MCP 与 Agent Skills 生态让 Xenon 在保持终端轻启动的同时具备企业级 Agent 工具接入能力。
---
## 工具系统、安全与模型路由
### 相关页面
相关主题：[系统架构总览](#page-2), [执行引擎与推理范式](#page-3), [终端交互界面与命令系统](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [xenon/nodes/tool_registry.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/nodes/tool_registry.py)
- [xenon/nodes/tool_node.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/nodes/tool_node.py)
- [xenon/nodes/tool_executor.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/nodes/tool_executor.py)
- [xenon/engine/tool_runtime.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/tool_runtime.py)
- [xenon/engine/circuit_breaker.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/circuit_breaker.py)
- [xenon/engine/tool_tracker.py](https://github.com/xianyu-sheng/Xenon/blob/main/xenon/engine/tool_tracker.py)
# 工具系统、安全与模型路由
Xenon 的工具层、安全层与模型路由层共同支撑 Agent 在终端中的"行动—监督—调度"闭环。本页围绕 `xenon/nodes/` 下的工具节点族与 `xenon/engine/` 下的运行时分发族，梳理其职责边界、协作方式以及关键的不变量。
## 一、工具节点族：注册、节点、执行三层
工具在 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]()。
三层之间的数据流可以用如下表格描述：
| 层 | 输入 | 输出 | 持有状态 |
|---|---|---|---|
| registry | 工具声明字典 | 查询命中的工具描述 | 元数据、权限标签 |
| tool_node | 模型 tool_call | 可执行调用句柄 | 当前回合上下文 |
| tool_executor | 句柄 + 实参 | 执行结果 / 异常 | 子进程、超时、缓存键 |
## 二、安全层：熔断器与执行追踪
工具一旦拥有写文件、起子进程、访问网络的能力，就必须有"刹车"和"黑匣子"，这正是 `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 回合中闭环。
---
---
## Doramagic 踩坑日志
项目：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