@vectorx/cloud-agent

@vectorx/cloud-agent 是一个 Coding Agent：你给它一个 rootDir（工程目录）和一个“模型流式调用器”，它会通过约定的工具协议（XML <use_tool>）驱动内置工具（read/write/ls/glob/grep/bash/fetch）完成读写、搜索、执行命令等任务，并在过程中向上层 UI 持续吐出可渲染/可执行的事件。

安装

pnpm add @vectorx/cloud-agent

最小用法（只用内置 Qwen Legacy SSE）

适合快速跑通：只需要提供 DASHSCOPE_API_KEY，或通过 config 传 apiKey。

import { CloudAgent } from "@vectorx/cloud-agent";

const agent = new CloudAgent({
  rootDir: process.cwd(),
  model: {
    id: "qwen3-coder-plus",
    apiKey: process.env.DASHSCOPE_API_KEY,
    temperature: 0.7,
    maxTokens: 4096,
  },
});

const res = await agent.runWithAt({
  prompt: "请读取 @package.json 并总结这个项目做什么",
});

console.log(res.text);

标准用法（外部注入 StreamingModelCaller）

你也可以把任意模型接入成 StreamingModelCaller：

import {
  CloudAgent,
  type StreamingModelCaller,
} from "@vectorx/cloud-agent";

const streamingCallModel: StreamingModelCaller = async function* ({ messages }) {
  // 你自行对接 OpenAI / Azure / 自建服务，
  // 只要把“流式增量”标准化成下面两类 chunk 即可。
  // yield { type: "text-delta", delta: "...", text: "..." }
  // yield { type: "finish", text: "...", usage?: {...} }
};

const agent = new CloudAgent({
  rootDir: "/path/to/workspace",
  streamingCallModel,
});

for await (const evt of agent.runWithAtStream({ prompt: "..." })) {
  // UI 侧消费（见下文）
}

UI 适配（事件流 / SSE / Bridge）

事件入口

• 推荐：使用 runWithAtStream()（或兼容别名 runWithAtStreaming()）获取 AsyncIterable<LoopStreamEvent>。
• 非流式：runWithAt() 返回最终结果（text/turns/toolCalls）。

LoopStreamEvent（UI 侧应重点处理的事件）

在 runWithAtStream() 中会产出如下事件（均为 JSON 结构，适合直接做 SSE data: <json>\n\n 透传）：

• text-delta
  • 用于渲染助手回复的实时增量文本。
• reasoning-delta
  • 某些 provider 会输出推理增量（如果你的 provider 没有，就不会出现）。
• tool-use
  • 包含 toolUse: { id, name, input, description? }，用于在 UI 上显示“即将调用的工具 + 入参”。
• tool-approve
  • approved: boolean，用于 UI 展示“批准/拒绝”。（是否真的弹窗由上层 onToolApprove 决定）
• tool-result-detail
  • 包含 toolResult: { llmContent, returnDisplay?, isError? }，用于 UI 展示结构化结果（比 tool-result 更完整）。
• tool-call / tool-result
  • 旧版兼容事件：只包含 toolName/turn/output 等轻量字段。
• message
  • 每次 History 落库时吐出完整 NormalizedMessage，适合做“消息列表/调试面板”。
• meta
  • turns/toolCalls 汇总。
• finish
  • 本次会话完成（最终文本在 text）。
• error
  • 异常事件；同时为了兼容旧逻辑，agent 也会再额外吐一次 finish(text=error)。

原始模型 chunk（用于 Debug 面板）

你可以在调用时传入 onChunk(chunk, requestId)：

• 当模型适配层能拿到 provider 的 raw chunk 时，会在 chunk.raw 或 chunk.type === "raw" 中携带
• 推荐 UI 侧单独做一个“raw chunk 面板”用于排查协议差异

Playground 调试

本包自带调试 UI（便于排查流式、工具调用与结果）：

pnpm --filter @vectorx/cloud-agent playground:ui

• 主界面：http://localhost:3001/
• Stream Debug：http://localhost:3001/stream-debug.html
  • 展示：SSE 全量事件、debug:onChunk、debug:onMessage、tool_use/approve/result_detail

工具协议（模型输出要求）

模型若要调用工具，需要在回复中输出：

<use_tool>
  <tool_name>read</tool_name>
  <arguments>{"file_path":"package.json"}</arguments>
</use_tool>

Agent 会执行对应工具并把结果作为 tool_result 形式写入历史，再进入下一轮对话。