指南：如何把文档能力接入你的智能体

不要把「让智能体处理文档」理解成「把文件丢进对话框」。正确的接入是：先判断这一步该不该由软件确定执行，再选择 MCP 或命令行，最后按四种结果分别处理。同一次调用必须冻结入口。

1. 先判断：这件事该不该交给执行内核

适合接入的：解析、抽取、格式转换、比对、合并、确定计算、受控产物生成。 不适合接入的：意图理解、补问、专业复核、业务审批、对外动作。

判断标准只有一条：这一步的结果能否由软件确定产生并可独立验收。能，则接入；不能，则留在智能体或人工环节。

2. 两种入口，同一契约

入口	适用场景	特点
MCP（stdio）	桌面智能体直接调用工具面	工具面由能力目录自动生成
CLI（非交互式）	脚本、定时任务、自动化编排	标准输出只承载机器可读结果

两个入口由同一能力目录与同一契约投影产生，共享调度、Schema、错误、任务、产物、幂等与副作用语义。同一次调用必须冻结入口，失败后不静默切换。

3. 接入四步

第一步：发现能力

先调用能力发现（list_registered_capability_descriptors、get_capability_availability）。这两类调用不需要激活租约，可用来确认本机可用能力。

可用性状态封闭为：已登记、已安装、已就绪、暂不可用、已禁用。暂不可用会给出原因与恢复条件。

第二步：组装完整调用

调用必须包含能力身份与精确契约修订、请求与关联标识、完整结构化参数、执行模式、截止时间；有副作用的调用必须带幂等键。

不要提交预期契约摘要——服务端会把该修订对应的真实公开摘要绑定到本次执行。

第三步：处理四种结果

结果	处理方式
succeeded	直接使用结构化结果
accepted	长耗时执行已创建任务，按任务标识查询
blocked	前置条件不足，执行尚未发生；补齐事实后发起新的完整调用
failed	执行失败且副作用明确；按错误语义决定是否重试

blocked 不是等待状态，不创建交互会话。不要为它设计「等用户回复」的逻辑。

第四步：管理产物

产物通过受控引用返回，包含摘要、媒体类型、大小、访问范围、创建事实与保留期限。产物先写入独立事务区，成功提交后才原子发布；失败、取消或超时不会留下半成品。

4. 长耗时调用

• 只有能力描述符明确声明为异步的调用才会创建技术任务。
• 任务状态封闭为：已受理、排队、等待资源、运行中、恢复中、完成、失败、已取消、结果未知。
• 任务只表达技术执行，不等待用户输入、专业复核、确认或外部回执。
• 同一主体可查询与取消自己创建的任务；跨主体访问在读取结果或取消前被拒绝。

5. 错误处理的正确姿势

错误包含稳定错误码、类别、可重试性、执行影响（未应用/已应用/未知）、具体缺失或冲突字段、必要的重试间隔与安全诊断摘要。

• 执行影响为「未知」时不要自动重试有副作用的调用。
• 错误只表达机器事实，不要把它渲染成用户话术再回灌给模型。
• 入口契约错误的退出码与业务失败不同，监控要分开统计。

6. 并发与幂等

• 有界持久队列 + 明确背压，支持多调用同时安全接纳、排队、查询与取消。
• 有副作用的调用由「主体 + 能力 + 资源范围 + 幂等键 + 规范化输入摘要」共同约束：同键同内容已完成则复用结果，同键不同内容返回幂等冲突。
• 同一对象并发写受独占声明与版本校验保护；不同对象不被全局串行化。

7. 常见反模式

反模式	后果	正确做法
让模型即兴拼参数	结果不稳定	由技能提供参数映射与校验
把 blocked 当成等待用户	流程卡死	补齐事实后重新发起完整调用
忽略退出码只看输出	失败被吞	按退出码矩阵分支处理
用私有轮询面管理任务	形成第二执行主体	只投影同一任务事实源
在不同入口间失败切换	幂等语义被破坏	同一次调用冻结入口

为什么要把这一步交给本机执行内核，见《为什么文档智能需要本地执行内核》；完整能力、交付形态与授权方式，见《智能体文档执行引擎产品说明》。