XKZOOM Gateway

XKZOOM Gateway is the local runtime boundary for XKZOOM agents, mobile REST, mobile WebSocket, owned tools, memory, skills, and reply dispatch.

The default runtime is gateway-core. The package does not ship the retired external gateway runtime, retired bundled skills, third-party chat channel entries, web control UI, or tunnel/TUN entries.

Install

pnpm add xkzoom

For direct CLI use:

pnpm dlx xkzoom

The package exposes the xkzoom bin and keeps runtime state under ~/.xkzoom by default.

What This Package Includes

• Owned XKZOOM gateway runtime under gateway-core.
• CLI entrypoints for local gateway startup and mobile pairing helpers.
• Mobile REST and /mobile/ws runtime used by XKZOOM Desktop and the mobile client.
• Owned reply runtime, owned tools, agent workspace loading, and local state bootstrap.

The npm package is intentionally runtime-focused. It does not publish source tests, internal docs, retired gateway host material, source maps, TypeScript declarations, third-party chat channel integrations, web control UI, tunnel entries, or VPS deployment scripts.

Release Notes

1.5.7

发布日期: 2026-07-16

对外版本真源: xkzoom-gateway（desktop / app / company web 同步至 1.5.7）

概述

1.5.7 把 XKZOOM 从单一聊天窗口进一步推进为可长期工作的本地 Agent 工作台：桌面端完成项目工作台、Goal 模式、通知中心与自绘安装器闭环；网关补齐知识库、文档与多媒体工具、更多服务商适配和 Agent 工作区种子；移动端同步 Goal 生命周期、结构化选择题与跨设备状态。

网关运行时（xkzoom npm）

• Goal 模式闭环。 支持目标创建、进度反馈、暂停/继续与终止状态在桌面和移动端同步；用户中途补充要求时可直接转向当前回合，不再依赖另开会话。
• 结构化 ask_user 更稳定。 补齐批量选项、文本回答续接、已回答卡片收口、强制工具重试与跨设备同步，避免选择卡反复出现或回答后卡住。
• 知识库与长期工作上下文。 新增知识库记忆桥接与检索引用约束，让 Agent 可在明确边界内读取已沉淀的项目资料。
• 文档与多媒体工具扩展。 新增 DOCX/PDF 工具，并扩展 Exa 搜索、OpenAI/Gemini/xAI 图像能力、xAI 视频、OpenAI/ElevenLabs 语音与 ElevenLabs 声音克隆等服务商实现；各能力仍需用户自行配置对应 API Key。
• 代理网络支持。 本机网关与相关工具可读取桌面代理配置，模型、文档和媒体请求在受限网络下获得一致的代理路径。
• Agent 工作区补种。 新建 Agent、owned seed 和存量启动补种统一确保 AGENTS.md 与 TOOLS.md 到位；已有 MEMORY.md、USER.md、TOOLS.md 不会被覆盖，HEARTBEAT.md 仍只属于默认 Zoom 首次引导。
• 流式与中断语义加固。 修复工具回合中的推理流、用户转向时的多余中断提示、生成媒体重复入库和空回复重派边界。

桌面客户端（xkzoom-desktop）

• 项目工作台正式成形。 统一项目文件树、批量与拖拽文件操作、多标签检查器、真实终端、运行配置、内嵌浏览器预览和项目内 Agent 对话；右键文件或文件夹时不再导致中间内容消失。
• 文件预览与编辑体验扩展。 支持代码/文本、Markdown、图片标注、音频、视频、PDF 与 Office 文件；Office 统一进入原貌预览路径，并在准备期间显示 Loading Office preview…。本机 Office/LibreOffice 转换与可选 ONLYOFFICE WOPI 保存回写均有真实门禁覆盖。
• 模型与网关目录更新。 扩充 OpenAI、Anthropic、Google、xAI/Grok、MiniMax、通义、DeepSeek 等常见厂商和新型号，并按模型目录维护 contextWindow / maxTokens，减少错误默认值导致的截断或请求失败。
• 助手扩展能力扩充。 设置页按真实 provider 显示搜索、图像、视频、语音、声音克隆、文档与输入类能力；MiniMax 不再以含义不清的单独“高级扩展”出现。
• Goal 模式与消息交互。 新增目标进度轨、生命周期控制、跨设备输入状态、结构化选择卡、引用与草稿恢复；聊天流式滚动和工具回合反馈进一步稳定。
• Agent 领取与通知中心。 Agent 目录、我的 Agent 覆盖层、领取反馈和空状态重新整理；新增单向通知 feed、未读状态、本地已读记录与 Markdown 公告详情。
• 首次体验与发布路径。 增加产品引导；自绘 Windows 安装器支持旧版检测、覆盖升级/全新安装分流、.xkzoom 数据位置确认、真实解压进度、稳定清单与公开下载烟测。

移动端（xkzoom-app）

• Goal 模式生命周期控制与进度视图已和网关对齐，冻结中的群聊入口按产品口径隐藏。
• 修复跨设备待回复状态、ask_user 选项与文本回答续接、Relay 鉴权提示和配置变化后的自动重连。
• 完成移动端壳层与聊天体验整理，并新增 Android 正式签名构建脚手架；密钥与 keystore 仅保存在本机，不进入仓库。

升级说明

• 从 1.5.6 升级到 1.5.7 无需手工迁移会话或 Agent 数据；默认状态目录继续使用 ~/.xkzoom。
• 存量 Agent 的工作区缺失文件会按需补齐，但不会覆盖用户已编辑的 Markdown 文件。
• 正式 Windows 包使用自绘安装器与 updates/stable/latest.json；安装器会优先识别旧安装和当前 .xkzoom 位置，再进入升级流程。

1.5.6

发布日期: 2026-07-02

对外版本真源: xkzoom-gateway（desktop / app 同步至 1.5.6）

概述

1.5.6 修复「回复气泡为空、只剩一条折叠推理」的问题（根因是模型输出预算 max_tokens 全线被一刀切压在 8192），并完成网关回复链路的一轮大重构（反空转策略收敛到业界极简范式、回合循环统一、上下文投影单一化）。

网关运行时（xkzoom npm）—— 有功能变更

• max_tokens 语义重构：配置真源优先。 模型行配置的 maxTokens 现在直接覆盖请求体 max_tokens（此前取 min，会被协议兜底静默压低）；移除 MiniMax 专属默认值与环境变量，统一为协议级兜底 PROTOCOL_FALLBACK_MAX_TOKENS = 16384（仅在配置完全缺失时使用）。
• 回复链路重构（收敛到极简反空转范式）：
  • exec 工具语义成为工具失败的单一信号源；RunLedger 主动断路退役（仅保留遥测），新增完成证据校验。
  • dispatchMessage 拆分为 dispatch/* 契约模块，两个原生 runner 共享统一回合循环 runModelTurnLoop。
  • transcript projection：projectMessagesForAPI 成为模型可见内容的单一 API 视图，统一上下文窗口预算阈值，内部工具对 API 透明过滤。
  • 可见文本质量：空气泡最终摘要源（P0-B）、分段保留原始尾部（P0-C）、流式管道加固。
  • 原生路由与管线成功语义收紧；route-miss 遥测上报真实未命中原因。
• 新增 owned 工具 ask_user（结构化选择题）。 模型需要用户在明确候选项之间做决策时，可给出 question + options（支持 allowMultiple 多选），客户端渲染为可点击的选项卡；工具不阻塞等待，用户点选后其选择作为下一条用户消息发回。
  • 终结型收轮提速：ask_user 调用成功即结束本轮，不再把 tool_result 回灌模型跑一次收尾迭代（省一次完整模型往返，推理模型场景还省一整段 thinking），选择卡出现速度显著加快；调用失败仍走正常回灌让模型修正。
  • 连环追问：工具契约明确支持多轮逐题追问（苏格拉底式引导、逐步收敛需求）——每轮一题，收到用户选择后可立即再问下一题，信息足够即收敛为结论。
  • System Tool Contract 补充 ask_user 专节：明确「候选项必须用工具、禁止 Markdown 表格/列表代替选择卡」的产品口径，与 tools[] schema 对齐。
  • 可见正文泄漏修复：ask_user 成功收轮后，runner 与流管线 P0-B 空气泡兜底均不再合成「工具 ask_user 已完成…」类摘要，避免内部 tool_result 指引泄漏到选择卡下方。
• 工具栏强制触发契约 forcedToolName。 SendMessageRequest 新增可选字段；桌面端右侧工具箱「填到输入框 / 立即发送」显式指定本轮必须调用的 owned 工具名。网关优先于示例词文本匹配设置 tool_choice 策略，并在该轮 user turn 末尾注入模型可见硬性指令（UI 仍只展示用户原文）。
• MiniMax Anthropic 兼容端点 tool_choice 诚实降级。 官方 Messages API 的 ToolChoice schema 仅支持 auto / none；HTTP 层写入 required 或具名 function 会被服务端静默忽略。适配器改为如实声明不支持线上强制，强制意图改走 system prompt + user turn 双通道指令（日志 tool_choice=prompt-directive(...)）。

修复（桌面客户端 xkzoom-desktop）

• 回复气泡为空、只显示折叠的「推理」条。 根因：model-provider-catalog.json 此前所有模型 maxTokens 一刀切 8192，思考型模型的推理内容即耗尽全部输出预算，正文归零。现已逐厂商按官方文档核定各模型 maxTokens / contextWindow（如 MiniMax M3 8192→131072、M2.7 →65536、qwen-plus →32768 等），目录表成为唯一配置真源。
• 存量用户配置智能迁移：仅当旧值等于旧一刀切默认 8192 且目录表新值不同才升级，不误伤真实上限就是 8192 的模型；且迁移前置到网关子进程 spawn 之前落盘，老用户升级后第一次启动即生效，无需二次重启。
• 程序内「检查更新」下载安装包新增实时进度条（流式字节进度）。
• 回复完成后冻结气泡内时间线重排：最终答案下沉到底部，无需回滚即可看到结论。
• 输入框粘贴修复：从外部 / 终端复制的文字（含夹带路径、图片链接的普通文本）此前可能被附件导入逻辑劫持而粘不进输入框；现改为文本优先——仅「真实文件」或「整段内容就是路径/图片源」才走附件导入，其余一律按文本粘贴，且导入失败时自动把原文本放回光标处。主聊天与项目仓小窗对话同时生效。
• 新增输入框右键菜单：剪切 / 复制 / 粘贴 / 全选。
• 新增消息气泡右键菜单：「复制内容」（优先复制选中文本）与「引用这条对话」——引用后输入框上方出现引用芯片，发送时引用内容随消息一起传给模型，并以显式标注告知模型这是用户引用的历史消息（超长引用自动截断，纯文本协议、无需网关改动）。
• 新增 Agent 选择卡（配合网关 ask_user 工具）：Agent 抛出的候选项在聊天里渲染成可点击的选项卡，单选点击即回复、多选勾选后一键发送；已作答的卡片保留选中痕迹并锁定，历史回放不会重复作答。主聊天与项目仓小窗对话同时生效。
• 右侧工具箱强制触发：forcedToolName 随发送上行；「填到输入框」登记待强制工具，「立即发送」一键带强制信号发出（配合网关 ask_user 等工具，避免仅填示例词、模型仍走纯文本表格）。

升级说明

• 网关端从 1.5.5 升到 1.5.6 无需手动迁移；注意若模型行配置了 maxTokens，现在会严格按配置发送（不再被协议兜底取 min 压低）。
• 桌面客户端升级到 1.5.6 后，首次启动自动完成 maxTokens 迁移并即时生效。

1.5.5

发布日期: 2026-07-01

对外版本真源: xkzoom-gateway（desktop / app 同步至 1.5.5）

概述

1.5.5 在 1.5.4 基础上，网关运行时新增「本机 Agent 名册热感知」能力（1.5.4 网关运行时无功能变更），并修复桌面客户端两个问题。

网关运行时（xkzoom npm）—— 有功能变更

• 新增 /mobile/ws 事件 agents_changed。网关新增对本机 Agent 名册真源的文件系统监听：
  • $STATE_ROOT/agents/ 递归（仅认顶层目录条目变化 = 名册成员增减/改名，与各 Agent IDENTITY.md = 展示名/头像；过滤 memory/session/diary 等聊天期高频写入）；
  • $STATE_ROOT/xkzoom.json（名册配置真源，经父目录监听以抗 purchase-done / upsertRuntimeAgentConfig 的 tmp + rename 原子替换）。 变化经 ~400ms debounce 合并后，向所有 /mobile/ws 连接广播 agents_changed；客户端（桌面 / 移动）收到即重新拉取 GET /api/agents/list 热加载，无需重连或重启。监听句柄均 unref（不额外维持进程存活），recursive 监听在不支持的平台（如 Linux）自动降级为仅 xkzoom.json 监听（名册成员变化必写 json，仍覆盖）。

修复（桌面客户端 xkzoom-desktop）

• 领取 / 领回本机 Agent 后，左侧聊天列表不出现该 Agent，需要 Ctrl+R 强制刷新才可见。 根因：桌面聊天侧栏的本机 Agent 名册（来自网关 GET /api/agents/list）与商店运行时名册是两份独立状态；领取（写盘）后，前端对本机 Agent 列表的检测不实时（无轮询、无热加载）。现改为由网关 agents_changed 事件驱动——收到即重拉列表，占位会话在写盘后自动出现，无需强刷。（配套网关侧新增能力见上。）
• 初次启动新会话发送首条消息时出现两条相同用户气泡。 为乐观气泡引入贯穿「乐观气泡 → 服务端回显」的稳定 clientMessageId，草稿 → 真实会话重绑时按稳定键去重合并，而非盲目追加，消除首条消息重复。

升级说明

• 网关端从 1.5.4 升到 1.5.5 无需任何迁移或配置变更；新增的名册监听在网关启动时自动生效。
• 桌面客户端需内嵌 1.5.5 网关运行时并同步至 desktop 1.5.5，方可获得「领取即热加载」体验（旧网关不广播 agents_changed）。

1.5.4

发布日期: 2026-07-01

对外版本真源: xkzoom-gateway（desktop / app 同步至 1.5.4）

概述

1.5.4 是在 1.5.3 基础上的修复版本。网关运行时相较 1.5.3 无功能变更，本次问题与修复集中在桌面客户端；网关 npm 包随版本线对齐发布，供 desktop 1.5.4 安装包内嵌。

修复（桌面客户端 xkzoom-desktop）

• 智能体商店领取 Agent 后首条消息无回复、Agent 空转、上下文面板报 "session not found"。 桌面端会为“已领取但尚未开聊”的 Agent 在会话列表生成占位入口（agent-placeholder:*）。此前发送时把该客户端自造的占位 id 原样发给网关，网关据此把一个以占位 id 为真实 id 的会话落库，与前端占位检测冲突，导致草稿永远无法重绑到真实会话。现在占位草稿发送时改发空 sessionId，由网关 mint 正规会话 id，前端既有的 ACK / 事件 / 接收自动切换逻辑完成“占位 → 真实会话”重绑；selectSession 增加“尚未落库才按草稿处理”的防御，历史存量里被错误落库的占位会话也能正常加载历史。
• 程序内右上角“检查更新”始终显示“更新检查失败：fetch failed”。 更新检查只请求 CDN 自定义域名 download.xkzoom.com，在部分网络下对该域名直连超时（UND_ERR_CONNECT_TIMEOUT）。现在清单与安装包请求都新增 OSS 原始域名同路径兜底（download.xkzoom.com → xkzoom-installers.oss-cn-hangzhou.aliyuncs.com），CDN 与 OSS 任一可达即成功；清单请求另加约 6s 连接超时以快速切换（大文件下载不设超时）。结果：无新版显示“已是最新版本”，有新版可在程序内直接下载并拉起安装器。

网关运行时（xkzoom npm）

• 无功能变更，与 1.5.3 一致。仅版本号对齐至 1.5.4。

维护 / CI（不影响 npm 包内容）

• release-gate 的 release-artifact-shape 校验前先执行 pnpm run build，修复独立 matrix job 因缺少 dist 产物导致的误报。

升级说明

• 已装 1.5.3 的用户升级到 desktop 1.5.4 后，上述两个问题即修复。
• 网关端从 1.5.3 升到 1.5.4 无需任何迁移或配置变更。

1.5.3

• Hardens native provider calls against transient upstream connection failures: OpenAI-compatible and Anthropic-compatible request paths now retry retryable network/connect failures once before surfacing a failed assistant turn.
• Adds shared retry diagnostics for native provider fetches, including attempt counts, retry decisions, request shape, and cause-chain error codes without logging prompts or API keys.
• Applies the retry path to the owned turn runners used by Desktop/App replies and to the legacy text-stream helpers, keeping HTTP errors, aborts, and empty stream failures honest.
• Adds regression coverage for UND_ERR_CONNECT_TIMEOUT recovery on both OpenAI-compatible and Anthropic-compatible native turn paths.

1.5.2

• Publishes the 1.5.x owned gateway runtime with complete npm package metadata so npmjs.com renders the README and install guidance correctly.
• Adds release-package validation that treats README.md and npm readme metadata as required release artifacts, preventing another metadata-only package from being published without docs.
• Documents the public runtime surface for desktop packaging: CLI entrypoints, mobile REST, /mobile/ws, owned tools, local state bootstrap, and the trimmed runtime-only package shape.
• Carries forward the 1.5.1 runtime baseline for desktop installer builds while making the package easier to verify from the npm page.

1.5.1

• Updates the published xkzoom runtime used by XKZOOM Desktop packaging to the current owned/native gateway baseline.
• Keeps the npm artifact focused on runnable gateway material: dist, gateway-core, runtime scripts, license, notice, and package manifest.
• Preserves the mobile gateway contract used by Desktop and App, including mobile REST, /mobile/ws, relay connector runtime, and pairing helpers.
• Removes development-only package surface from the public tarball, including source tests, internal docs, source maps, TypeScript declaration files, retired host material, tunnel/control UI entries, and VPS deployment material.

Runtime

• Start the gateway with pnpm run gateway:run or the xkzoom bin.
• The default state root is ~/.xkzoom.
• Set XKZOOM_STATE_DIR to use an explicit state root.
• gateway-core/runtime/gateway/owned-gateway-entry.cjs owns the gateway CLI entry.
• gateway-core/runtime/reply/load-owned-reply-runtime.cjs owns reply runtime loading.
• gateway-core/runtime/mobile-relay owns relay and connector processes.

Product Surface

• Skills are read from agent workspaces and XKZOOM global skills.
• The API does not return retired bundled skills by default.
• Agent creation uses the native XKZOOM skeleton writer.
• Mobile REST and /mobile/ws are part of the owned gateway path.
• Third-party chat software integrations, web control UI, tunnel, and TUN are disabled product surfaces.

Verification

Run the core checks before publishing or handing off:

pnpm run build
pnpm run typecheck:test
pnpm run verify:release-artifact:shape
pnpm run verify:zero-legacy-source

Useful focused checks:

pnpm run test:mobile:regression
pnpm run test:dev-tools
pnpm run verify:mobile:runtime

Documentation

• Gateway Core
• State Root
• Skills And Agents
• Mobile Relay Connector
• Release Verification