intent-runtime

    快速开始

    本页完成一次 Node.js 调用：识别“查询订单000123，不取消订单”，找到目标与禁止事项。无需先配置业务字段。其他接入方式可直接选择：

    你要做什么使用入口模型来源
    在 Node.js 应用中识别意图本页示例你的 API 或执行器
    在 Codex 中调用Codex 接入当前模型或所配 API
    启动独立 MCP独立服务由服务配置决定
    给已有 MCP 添加tools集成现有服务当前宿主或所配 API

    1. 安装到项目

    需要 Node.js ≥20 和 ESM。在应用目录执行：

    npm install @devcodex/intent-runtime

    所需依赖由 npm 自动安装。现有 JavaScript / TypeScript 项目可以直接接入。下面使用 ESM：项目的 package.json 设置 "type": "module"；独立 JavaScript 文件也可保存为 .mjs。其他安装方式见安装与版本。

    本文先识别目标与约束，不配置业务Schema。需要订单编号等结构化参数时，再运行订单字段示例。

    这一条路径使用你的模型 API 凭据。希望复用 Codex 当前模型、无需额外模型 Key 时，直接按 Codex 接入操作。

    2. 配置模型

    例子使用OpenAI Responses API。将 INTENT_API_KEY 和 INTENT_MODEL 设为你的凭据与可用模型名。这两个环境变量由应用读取，不是库自动读取的固定配置。xAI与自有网关见模型接入。

    PowerShell：

    $env:INTENT_API_KEY = "你的 API Key"
$env:INTENT_MODEL = "你的模型名称"

    Bash：

    export INTENT_API_KEY="你的 API Key"
export INTENT_MODEL="你的模型名称"

    3. 保存并运行

    选择与你的项目一致的语言。JavaScript 保存为 basic.js，TypeScript 保存为 basic.ts；包导入从文件位置解析。

    JavaScript
    TypeScript
    import {Intent, IntentError} from '@devcodex/intent-runtime';
import {createApiExecutor} from '@devcodex/intent-runtime/adapters/api';

const apiKey = process.env.INTENT_API_KEY;
const model = process.env.INTENT_MODEL;
if (!apiKey || !model) throw new Error('Set INTENT_API_KEY and INTENT_MODEL in your environment.');
const intent = new Intent({
  language: 'zh-CN',
  executor: createApiExecutor({provider: 'openai', apiKey, model}),
});
try {
  const result = await intent.parse({input: '查询订单000123，不取消订单'});
  console.log(JSON.stringify(result, null, 2));
  // Read goals and constraints from effective; no order query is executed.
  console.log('目标：', result.effective.intents.map(node => node.goal));
  console.log('需要澄清：', result.issues.map(issue => issue.message));
} catch (error) {
  if (!(error instanceof IntentError)) throw error;
  console.error(JSON.stringify(error.toJSON()));
  process.exitCode = 1;
} finally {
  await intent.dispose();
}
    node basic.js

    4. 读取结果

    本例的理解结果应保留查询目标和禁止取消的约束。订单编号会出现在自然语言目标中；只有另行配置Schema并选择orderId后，才提取到inputs。完整文本与生成ID可以变化。

    检查项应观察到什么
    目标查询订单000123
    约束prohibition：不取消订单
    参数本例没有选字段，inputs 没有新提取的 orderId
    问题按实际 issues 判断是否需要补充，不以是否打印 JSON 作为理解正确的唯一依据

    如需对照完整结构，可下载无 Schema 完整示例或查看带订单字段的 Native 响应。

    • effective.intents是目标树；同时读取全局与各目标的constraints。
    • issues说明歧义、缺失或冲突；先补充材料，不自行执行某个候选。
    • fields默认[]，省略它仍识别意图，但不新增业务字段提取。
    • complete不代表字段齐全、授权或业务已执行。程序不会查询或取消订单。

    下一步读如何读取结果，或运行订单字段和多轮修改的完整示例。需要其他模型供应商时查模型接入，调用失败时查错误与恢复。