From c9795f0f76935c2d5d4bf35b288654e5d3a691ab Mon Sep 17 00:00:00 2001 From: xianyu-sheng <2107644732@qq.com> Date: Thu, 23 Jul 2026 10:33:20 +0800 Subject: [PATCH 1/2] docs(community): add Xenon interoperability guide --- .../docs/framework/community/meta.en.json | 2 +- .../docs/framework/community/meta.json | 2 +- .../docs/framework/community/xenon.en.mdx | 97 +++++++++++++++++++ .../docs/framework/community/xenon.mdx | 89 +++++++++++++++++ 4 files changed, 188 insertions(+), 2 deletions(-) create mode 100644 docs/content/docs/framework/community/xenon.en.mdx create mode 100644 docs/content/docs/framework/community/xenon.mdx diff --git a/docs/content/docs/framework/community/meta.en.json b/docs/content/docs/framework/community/meta.en.json index ddb62d95..3e89e892 100644 --- a/docs/content/docs/framework/community/meta.en.json +++ b/docs/content/docs/framework/community/meta.en.json @@ -1,4 +1,4 @@ { "title": "Community", - "pages": ["langchain", "ide-support"] + "pages": ["langchain", "xenon", "ide-support"] } diff --git a/docs/content/docs/framework/community/meta.json b/docs/content/docs/framework/community/meta.json index 3e1d2a5d..f0236ace 100644 --- a/docs/content/docs/framework/community/meta.json +++ b/docs/content/docs/framework/community/meta.json @@ -1,4 +1,4 @@ { "title": "社区支持", - "pages": ["langchain", "ide-support"] + "pages": ["langchain", "xenon", "ide-support"] } diff --git a/docs/content/docs/framework/community/xenon.en.mdx b/docs/content/docs/framework/community/xenon.en.mdx new file mode 100644 index 00000000..a0ed9a08 --- /dev/null +++ b/docs/content/docs/framework/community/xenon.en.mdx @@ -0,0 +1,97 @@ +--- +title: "Xenon Interoperability" +--- + +[Xenon](https://github.com/xianyu-sheng/Xenon) is a terminal AI coding +workspace. VeADK and Xenon both support directory-based `SKILL.md` files and +standard MCP, so the same local Skill and MCP Server can be reused in both +environments without converting it to a vendor-specific format. + + + This page covers component interoperability. It does not mean that VeADK + supports `Agent(runtime="xenon")`. Using Xenon as an inner VeADK runtime + requires a separate runtime adapter and event translation. + + + + The integration commands below require Xenon `3166f47` or later; they are + newer than the `v0.7.0` tag. Install Xenon from its `main` branch until a + release containing them is available. + + +## Basic usage + +The [`codex_with_skill_and_mcp`](https://github.com/volcengine/veadk-python/tree/main/examples/codex_with_skill_and_mcp) +example includes a weather Skill and a stdio MCP Server that exposes +`get_weather`. Configure the same components in Xenon with these commands: + +```bash +cd examples/codex_with_skill_and_mcp + +xenon skill install ./skills/weather-style --scope project --json +xenon mcp add veadk-weather "$(command -v python)" --json -- ./mcp_server.py +xenon integrations verify --connect-mcp --server veadk-weather --json +``` + +The verification command performs MCP `initialize`, +`notifications/initialized`, and `tools/list`, but does not call a tool. A +successful result reports one reachable server and one `get_weather` tool: + +```json +{ + "ok": true, + "checks": { + "mcp_connectivity": { + "reachable_server_count": 1, + "tool_count": 1 + } + } +} +``` + +Start `xenon` from the current project directory and ask for the weather in a +city. Xenon loads the response format from the project Skill and obtains the +weather data through the configured MCP Server. + +```text +What is the weather in Beijing? +``` + +Remove the MCP configuration after the test: + +```bash +xenon mcp remove veadk-weather --json +``` + +## Component mapping + +```mermaid +flowchart LR + S["Local SKILL.md"] --> V["VeADK SkillToolset"] + S --> X["Xenon project Skill"] + M["stdio MCP Server"] --> V + M --> X +``` + +| Capability | VeADK | Xenon | Interoperability | +| :-- | :-- | :-- | :-- | +| Local Skill | `load_skill_from_dir` + `SkillToolset` | `xenon skill install` | Reuses `SKILL.md` and its resource directory directly | +| stdio MCP | `MCPToolset` + `StdioServerParameters` | `xenon mcp add` | Reuses the command, arguments, and environment variables | +| Ark model | `MODEL_AGENT_*` configuration | `ARK_*` configuration | API-compatible; credentials are managed separately | +| Agent runtime | `adk`, `codex`, and `piagent` | Xenon engines | No `runtime="xenon"` adapter yet | + +## Integration checks + +External installers can read Xenon machine-readable contract before deciding +where to write configuration: + +```bash +xenon integrations describe --json +xenon skill doctor --json +xenon mcp doctor --json +``` + +The capability contract publishes Skill roots, MCP transports, and versioned +commands, so an installer does not need to modify Xenon private YAML directly. +See the [Xenon integration CLI](https://github.com/xianyu-sheng/Xenon/blob/main/docs/INTEGRATIONS.md) +for the field-level contract. diff --git a/docs/content/docs/framework/community/xenon.mdx b/docs/content/docs/framework/community/xenon.mdx new file mode 100644 index 00000000..a889b34a --- /dev/null +++ b/docs/content/docs/framework/community/xenon.mdx @@ -0,0 +1,89 @@ +--- +title: "Xenon 互操作" +--- + +[Xenon](https://github.com/xianyu-sheng/Xenon) 是终端 AI 编程工作区。VeADK 与 +Xenon 都支持目录式 `SKILL.md` 和标准 MCP，因此同一份本地 Skill 与 MCP Server +可以在两个运行环境中复用，无需转换为厂商私有格式。 + + + 本页介绍组件互操作，不表示 VeADK 已支持 `Agent(runtime="xenon")`。Xenon 作为 + VeADK 内层运行时需要独立的运行时适配与事件转换。 + + + + 以下集成命令需要 Xenon `3166f47` 或更高版本；它们晚于 `v0.7.0` tag。正式版本 + 发布前，请从 Xenon 的 `main` 分支安装。 + + +## 基本使用 + +仓库中的 [`codex_with_skill_and_mcp`](https://github.com/volcengine/veadk-python/tree/main/examples/codex_with_skill_and_mcp) +示例包含一个天气 Skill 和一个提供 `get_weather` 的 stdio MCP Server。以下命令把 +同一组组件配置到 Xenon： + +```bash +cd examples/codex_with_skill_and_mcp + +xenon skill install ./skills/weather-style --scope project --json +xenon mcp add veadk-weather "$(command -v python)" --json -- ./mcp_server.py +xenon integrations verify --connect-mcp --server veadk-weather --json +``` + +验证命令执行 MCP `initialize`、`notifications/initialized` 和 `tools/list`，但不会 +调用工具。成功结果包含一个可达服务器和一个 `get_weather` 工具： + +```json +{ + "ok": true, + "checks": { + "mcp_connectivity": { + "reachable_server_count": 1, + "tool_count": 1 + } + } +} +``` + +从当前项目目录启动 `xenon`，然后询问城市天气。Xenon 从项目 Skill 根目录加载回答 +格式，并通过已配置的 MCP Server 获取天气数据。 + +```text +北京天气怎么样？ +``` + +测试结束后可删除 MCP 配置： + +```bash +xenon mcp remove veadk-weather --json +``` + +## 组件映射 + +```mermaid +flowchart LR + S["本地 SKILL.md"] --> V["VeADK SkillToolset"] + S --> X["Xenon 项目 Skill"] + M["stdio MCP Server"] --> V + M --> X +``` + +| 能力 | VeADK | Xenon | 互操作状态 | +| :-- | :-- | :-- | :-- | +| 本地 Skill | `load_skill_from_dir` + `SkillToolset` | `xenon skill install` | 直接复用 `SKILL.md` 与资源目录 | +| stdio MCP | `MCPToolset` + `StdioServerParameters` | `xenon mcp add` | 复用命令、参数和环境变量 | +| Ark 模型 | `MODEL_AGENT_*` 配置 | `ARK_*` 配置 | API 兼容，凭证分别管理 | +| Agent runtime | `adk`、`codex`、`piagent` | Xenon 自身引擎 | 尚无 `runtime="xenon"` 适配 | + +## 集成检查 + +外部安装器可以先读取 Xenon 的机器可读契约，再决定写入位置： + +```bash +xenon integrations describe --json +xenon skill doctor --json +xenon mcp doctor --json +``` + +能力契约公开 Skill 根目录、MCP transport 和版本化命令，不需要直接修改 Xenon 的 +私有 YAML。详细字段见 [Xenon 外部集成 CLI](https://github.com/xianyu-sheng/Xenon/blob/main/docs/INTEGRATIONS.md)。 From f9ece477690b26660628b594566b5c4ef820b4c9 Mon Sep 17 00:00:00 2001 From: xianyu-sheng <2107644732@qq.com> Date: Thu, 23 Jul 2026 11:56:03 +0800 Subject: [PATCH 2/2] docs(community): target Xenon v0.7.1 release --- docs/content/docs/framework/community/xenon.en.mdx | 7 +++---- docs/content/docs/framework/community/xenon.mdx | 5 ++--- 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/content/docs/framework/community/xenon.en.mdx b/docs/content/docs/framework/community/xenon.en.mdx index a0ed9a08..e95cbabb 100644 --- a/docs/content/docs/framework/community/xenon.en.mdx +++ b/docs/content/docs/framework/community/xenon.en.mdx @@ -13,10 +13,9 @@ environments without converting it to a vendor-specific format. requires a separate runtime adapter and event translation. - - The integration commands below require Xenon `3166f47` or later; they are - newer than the `v0.7.0` tag. Install Xenon from its `main` branch until a - release containing them is available. + + The integration commands below require the published Xenon `v0.7.1` release + or later. ## Basic usage diff --git a/docs/content/docs/framework/community/xenon.mdx b/docs/content/docs/framework/community/xenon.mdx index a889b34a..a7256d98 100644 --- a/docs/content/docs/framework/community/xenon.mdx +++ b/docs/content/docs/framework/community/xenon.mdx @@ -11,9 +11,8 @@ Xenon 都支持目录式 `SKILL.md` 和标准 MCP，因此同一份本地 Skill VeADK 内层运行时需要独立的运行时适配与事件转换。 - - 以下集成命令需要 Xenon `3166f47` 或更高版本；它们晚于 `v0.7.0` tag。正式版本 - 发布前，请从 Xenon 的 `main` 分支安装。 + + 以下集成命令需要已正式发布的 Xenon `v0.7.1` 或更高版本。 ## 基本使用