#介绍

intent-runtime 是 TypeScript / Node.js 模块。它把调用方明确提供的当前用户请求，表达为结构化的意图记录，并根据 schema-dsl 定义提取所选业务字段。

它适合需要把自然语言交给业务应用处理的场景：理解用户要做什么、对象是谁、有哪些要求与禁止事项、哪些动作需要澄清或确认，以及材料中能确定哪些业务字段。

#两种接入方式

两条路径共享同一套公共结果与本地校验逻辑。API 路径通过 Intent.parse() 完成；MCP 路径由宿主重复执行 prepare → accept，直到结果或错误。

#两阶段流程

1. core：默认意图。 识别当前有效请求，生成归一化表达、主要意图、动作列表、要求与禁止事项。
2. data：业务字段。 存在所选扩展字段时，根据 Schema 和明确材料提取字段，检查类型、描述、来源和问题。fields: [] 跳过该阶段。

候选 JSON、结构或来源引用不符合输出契约时，会产生 MODEL_OUTPUT_INVALID；候选完整、请求未取消且仍有修复次数时，模块会要求模型修复候选。默认每阶段允许一次修复。

材料中的真实业务信息缺失、冲突或业务约束不满足会产生 DATA_EXTRACTION_FAILED，直接反馈问题，不通过候选修复猜测补齐。鉴权、限流、取消等错误也不会触发候选修复。

最终交付完整 IntentResult，或带阶段和问题说明的错误。data 阶段失败可保留已经验证的默认结果，部分结果中的 data 为 {}。

#输入与职责

调用方提供原始 input，并选择是否补充显式 context。模块不会自行读取文件、加载完整聊天历史或发现业务工具。最终 input 保留模块收到的字符串；宿主提交前是否改写原文，需要在集成中验证。

ready 是理解状态。业务权限、用户批准和实际动作执行由应用负责。使用该模块不会自动查询订单、删除文件或发布内容。

来源匹配和结构校验能够发现部分错误，真实语义是否正确仍需目标模型评测与独立复核。

#运行要求

本文档适用于 1.0.x 公共接口。包名为 @devcodex/intent-runtime，要求 Node.js ≥20.0.0，使用 ESM；具体包版本见站点导航和发布记录。

接下来阅读快速开始、意图契约或测试与兼容。