Lime 集成接口

选择集成层

Lime 提供 TypeScript App Server 客户端与运行时封装。需要直接管理连接、线程和双向请求时使用 @limecloud/app-server-client；需要标准轮次操作与事件接口时使用 @limecloud/agent-runtime-client。一次性自动化也可以直接调用 lime exec。

安装 TypeScript 客户端

客户端包使用 ESM，需要 Node.js 20 或更高版本。以下示例使用公开发布的 App Server 客户端 1.66.0 与运行时客户端 0.1.1，必须配合相同协议的运行组件。安装客户端库不会自动安装运行组件、配置模型服务或授予权限。

npm install --save-exact @limecloud/app-server-client@1.66.0 @limecloud/agent-runtime-client@0.1.1

升级前核对安装版本的声明文件、发布说明与运行组件协议。不能只检查包能导入，也不能把新版 threadId 参数交给旧版 sessionId 接口。

本地运行组件

Node 或桌面宿主通过 connectAppServerSidecar 启动独立运行组件，并完成 initialize/initialized 握手。指定可信二进制路径；正式分发时按发布清单验证摘要。backendMode 需要显式选择 runtime，mock 只用于测试。

import { connectAppServerSidecar } from "@limecloud/app-server-client";

const binaryPath = process.env.LIME_APP_SERVER_BIN;
const appId = process.env.LIME_APP_ID;
if (!binaryPath || !appId) {
  throw new Error("缺少运行组件路径或应用 ID");
}

const connected = await connectAppServerSidecar(
  { binaryPath, listenUrl: "stdio://", backendMode: "runtime" },
  { clientInfo: { name: "my_lime_app", version: "1.0.0" } },
);
const started = await connected.connection.startSession({ appId });
const sessionId = started.result.session.sessionId;

appId 应来自目标运行组件中真实存在、当前用户获准使用的应用。这个公开版本使用 session 对象；新版 Thread/Turn 协议的返回值不同。宿主退出时调用 connected.sidecar.close()，并处理启动失败与连接中断。请求超时后先查询原会话，避免重发有副作用的操作。

运行时客户端

import { createAgentRuntimeClient } from "@limecloud/agent-runtime-client";

const runtime = createAgentRuntimeClient(connected.connection, {
  request: { timeoutMs: 120_000 },
});
const subscription = runtime.subscribeEvents((event) => {
  renderAgentEvent(event);
});
await runtime.startTurn({
  sessionId,
  input: { text: "读取项目指令并说明测试入口" },
});
await runtime.nextEvent(120_000);
const current = await runtime.readThread({ sessionId });

示例续接前一段公开版本的连接，renderAgentEvent 由宿主实现。nextEvent 读取并分发一个事件；实际宿主要持续消费，直到当前轮次达到终态，期间处理权限与输入请求。startTurn 返回表示请求已接受，readThread 用于查询权威状态。

生命周期由运行组件拥有，宿主不要另造完成状态。离开界面时调用 subscription.unsubscribe()，应用结束时关闭底层连接。新版客户端可能改用生命周期与信号订阅，按安装版本的类型使用。

远程连接

远程集成需要与服务端匹配的 WebSocket 传输、认证与初始化流程。当前公开的 1.66.0 包没有 connectRemoteAppServer 导出；需要该助手时，先取得包含此接口且与服务端协议配套的客户端版本。也可以按 App Server 协议自行实现传输。

新版远程助手使用 websocketUrl、authToken 与 initialize 参数，校验服务身份和协议。认证放在请求头，令牌不进入 URL。公网令牌连接使用 WSS；令牌存储、轮换、租户隔离和生产可用性由宿主与服务部署层负责。

浏览器与 Renderer

已有宿主 App Server 网关时，从 @limecloud/agent-runtime-client/sessionGateway 导入 createAgentRuntimeClientFromSessionGateway。公开版本网关提供 startTurn、readSession、cancelTurn、respondAction，以及可选 nextEvent 或 drainEvents。适配器把 readSession 暴露为客户端的 readThread。

把网关方法封装成闭包，避免类方法失去 this。不要在浏览器包导入 Node 子进程、Sidecar 或本机密钥能力。新版网关参数和事件有变化，前后端必须配套升级，不使用生产 mock 回退。

反向请求与结构化结果

公开版本通过 respondAction 回答 action_required：携带实际 sessionId、requestId、actionType 和用户确认结果，不从其他 ID 猜测审批身份。新版协议可能改用服务器发起的 JSON-RPC 请求，必须按外层 request ID 响应；respondServerRequest 与 rejectServerRequest 不是上述公开包的接口。

需要结构化结果时，先检查目标运行组件与安装版本提供的 Schema 和字段。输出结构通过验证与业务操作成功分别检查。恢复会话后分页读取真实历史，不让客户端假造旧消息。

从程序启动 CLI

使用参数数组启动子进程，不把用户提示拼成 Shell 命令。分别读取标准输出、错误输出和退出码，为任务设置超时与取消机制。

import { spawn } from "node:child_process";

const child = spawn("lime", ["exec", "--json", "--cd", projectPath, task], {
  stdio: ["ignore", "pipe", "pipe"],
});
let pending = "";
child.stdout.setEncoding("utf8");
child.stdout.on("data", (chunk) => {
  pending += chunk;
  const lines = pending.split("\n");
  pending = lines.pop() ?? "";
  for (const line of lines) {
    if (line.trim()) handleEvent(JSON.parse(line));
  }
});
child.stderr.on("data", (chunk) => logDiagnostic(chunk.toString()));
child.on("error", handleLaunchError);
child.on("close", (code) => {
  if (pending.trim()) handleEvent(JSON.parse(pending));
  finishRun(code);
});

示例中的事件处理、日志、错误与完成函数由你的应用实现。生产实现还需捕获 JSON 解析错误、限制日志内容，并在取消后等待进程退出。

继续同一段上下文

SDK 保存真实 sessionId，以及服务端返回的 threadId、turnId 和所属用户。CLI 则保存真实线程 ID，再使用 lime exec resume。不要只保存最后一条文字回复，也不要在多用户服务中用“最近一次任务”选择上下文。

接入 App Server

直接接入当前 App Server 时，启动 lime app-server --backend runtime --stdio，通过标准输入输出发送逐行协议消息。先 initialize，等待结果后发送 initialized，再按当前协议创建线程、开始轮次并消费事件。需要双向处理服务器发起的审批和用户输入请求。

这里描述当前 Thread/Turn 协议。上面的固定 npm 版本示例使用较早的 session 协议，两者不能混用；遇到协议不匹配时升级配套客户端和运行组件，或按当前协议直接连接。

数据、权限与生命周期

• 区分线程、轮次和条目 ID，保存稳定关联。
• 按实际返回的模型目录选择能力，不硬编码服务权益。
• 取消任务时发送中断请求，并等待最终状态。
• 限制可访问目录、网络与提供方凭据。
• 断连后读取原线程与轮次状态，确认是否已有副作用。

兼容与升级

以安装版本的协议 Schema 和行为测试为准。未知通知应可忽略，未知状态应可展示为未识别；不要通过猜字段或静默默认值掩盖协议错误。升级时测试初始化、流式输出、审批、取消、断连恢复和错误处理。

Python 与其他语言

当前没有对应原生 Python SDK 包。可以安全地以参数数组调用 lime exec、解析 JSONL 并检查退出结果，或实现 App Server 双向协议。输入来自外部系统时明确标注为数据，保留用户指令、业务数据与权限的边界。