Intelligence SDK
Intelligence SDK
概述
Intelligence SDK 提供插件访问 AI 能力的统一接口,支持多种 AI Provider(OpenAI、Anthropic、DeepSeek、SiliconFlow 等)。
介绍
快速开始
import { intelligence } from '@talex-touch/utils/plugin/sdk'
const status = await intelligence.getCapabilityStatus({ capabilityId: 'text.chat' })
const providers = await intelligence.getProviderModelOptions({ capabilityId: 'text.chat' })
if (status.available) {
const chatRes = await intelligence.text.chat({
messages: [{ role: 'user', content: 'Hello!' }]
}, {
allowedProviderIds: providers.filter(provider => provider.available).map(provider => provider.providerId)
})
console.log(chatRes.result)
}
插件运行时 handler 也可以通过 context.utils.intelligence 或 context.utils.plugin.intelligence 使用同一套能力发现与调用接口,再决定是否渲染 AI 动作。
延伸阅读
/docs/dev/intelligence(开发者专章)/docs/dev/intelligence/configuration/docs/dev/intelligence/capabilities/docs/dev/intelligence/troubleshooting
API 参考
Plugin intelligence SDK
插件 UI 与生命周期代码应使用 plugin SDK 导出的 intelligence,或运行时注入的 context.utils.intelligence。两者都会解析到 typed Intelligence domain SDK,并在权限检查调用里携带当前插件的 sdkapi marker。
import { intelligence } from '@talex-touch/utils/plugin/sdk'
void intelligence
仅 CoreApp renderer 内部代码可以从 @talex-touch/utils/renderer 使用 useIntelligenceSdk(),通过 TuffTransport 获取同一套 typed domain SDK。
返回值包含以下属性和方法:
| 属性/方法 | 说明 |
|---|---|
invoke / stream | 自定义或新注册 Capability ID 的通用能力调用 |
contextInvoke / contextStream | 宿主组装的 text.chat 执行,接收 new/continue/stateless intent,只返回 metadata-only context 摘要 |
text / embedding / code | 文本、向量、代码能力的类型化 wrapper |
intent / sentiment / content / keywords | 分析类能力的类型化 wrapper |
vision / image / audio | OCR、图片、音频能力的类型化 wrapper |
rag / search | RAG、语义搜索、重排序 wrapper |
workflow / agent | Workflow 执行与 Agent 运行 wrapper |
getCapabilityStatus | 只读能力可用性检查 |
getProviderModelOptions | 只读 provider/model 发现 |
ttsSpeak / workflow* / agent* / knowledge* / context* | CoreApp renderer 宿主使用的播放、workflow、agent session、知识库与受治理上下文管理 runtime API |
CoreApp renderer 宿主 SDK 保留完整上下文管理面。插件 facade 会隐藏 raw contextPrepareTurn(),以及 Memory list/save/edit/enable/delete。插件改用 contextInvoke() / contextStream():宿主在主进程内完成 ContextPackage prepare、最终复核、预算与 provider message 组装,插件只收到 metadata-only 摘要。contextEvaluateMemory() 与 metadata-only checkpoint/package-log 查询仍可使用。插件来源调用被隐藏的 host-only event 会得到 INTELLIGENCE_HOST_ONLY_CAPABILITY。
在 workspace/project memory 获得稳定 scopeRef 前,宿主管理 UI 仍可查看它们,但它们不会注入 ContextPackage。当前只允许 global memory,以及 sourceSessionId 精确匹配的 session memory;ttl 表示从最近一次保存(updatedAt)开始计算的正数毫秒生命周期。
useIntelligence() 与 useIntelligenceStats() 仍从 renderer barrel 导出,作为 loading/error 状态与统计 helper 的兼容壳。
getProviderModelOptions 与实际调用使用同一套 runtime method 检查。Capability binding 优先;未启用 binding 时,内置 OpenAI-compatible provider 会暴露能力专属默认模型,不会把聊天模型泄漏到图片、音频或 embedding-backed 搜索选择器。
能力调用
Plugin intelligence SDK 暴露 typed domain 方法,不会恢复已裁切的 chat 旧别名,也不会暴露 host-only Memory 管理方法。插件入口应先用发现接口判断能力是否可用,再调用对应 wrapper,例如 intelligence.text.chat(payload, options);自定义能力则继续使用 intelligence.invoke<Result>(capabilityId, payload, options)。
CoreBox 类对话入口应优先使用 contextInvoke() 或 contextStream()。当前 contract 只支持 text.chat,不会信任调用方提供的 user/assistant history。宿主只保留调用方 system message,再按有界顺序加入已验证的 summary、recent turns、Memory、retrieval context 与当前输入。mode 可取 new、continue 或 stateless;继续会话必须携带上一轮安全 context 摘要返回的 sessionId。
let contextSessionId: string | undefined;
const execution = await intelligence.contextInvoke({
capabilityId: "text.chat",
input: "总结当前选中文本",
payload: {
messages: [{ role: "system", content: "请简洁回答。" }],
},
context: {
mode: contextSessionId ? "continue" : "new",
sessionId: contextSessionId,
scope: "retrieval",
tokenBudget: 1200,
},
});
console.log(execution.invocation.result);
console.log(execution.context.packageId); // 仅安全 metadata,不含 ContextPackage items
contextSessionId = execution.context.sessionId;
Capability ID
| 领域 | Capability ID | Domain wrapper | 返回值 |
|---|---|---|---|
| 文本 | text.chat | text.chat() | 对话文本 |
| 文本 | text.translate | text.translate() | 翻译文本 |
| 文本 | text.summarize | text.summarize() | 摘要文本 |
| 文本 | text.rewrite | text.rewrite() | 改写文本 |
| 文本 | text.grammar | text.grammar() | 语法检查结果 |
| 文本 | text.classify | text.classify() | 分类结果 |
| 向量 | embedding.generate | embedding.generate() | 数字向量 |
| 代码 | code.generate | code.generate() | 代码生成结果 |
| 代码 | code.explain | code.explain() | 代码解释结果 |
| 代码 | code.review | code.review() | 代码审查结果 |
| 代码 | code.refactor | code.refactor() | 重构结果 |
| 代码 | code.debug | code.debug() | 调试结果 |
| 分析 | intent.detect | intent.detect() | 意图识别结果 |
| 分析 | sentiment.analyze | sentiment.analyze() | 情感分析结果 |
| 分析 | content.extract | content.extract() | 内容/实体提取结果 |
| 分析 | keywords.extract | keywords.extract() | 关键词提取结果 |
| 视觉 | vision.ocr | vision.ocr() | OCR 结果 |
| 视觉 | image.caption | image.caption() | 图片描述结果 |
| 视觉 | image.analyze | image.analyze() | 图片分析结果 |
| 视觉 | image.translate.e2e | image.translateE2e() | 端到端图片翻译结果 |
| 视觉 | image.generate | image.generate() | 图片生成结果 |
| 视觉 | image.edit | image.edit() | 图片编辑结果 |
| 音频 | audio.tts | audio.tts() | TTS 结果 |
| 音频 | audio.stt | audio.stt() | 语音转文字结果 |
| 音频 | audio.transcribe | audio.transcribe() | 音频转写结果 |
| RAG | rag.query | rag.query() | RAG 查询结果 |
| RAG | search.semantic | search.semantic() | 语义搜索结果 |
| RAG | search.rerank | search.rerank() | 重排序结果 |
| Workflow | workflow.execute | workflow.execute() | Workflow 执行结果 |
| Agent | agent.run | agent.run() | Agent 运行结果 |
Workflow 执行与 Agent 运行是内部编排能力。声明 text.chat 的 provider 即可参与运行,无需重复声明 workflow.execute 或 agent.run;若这两个能力没有已启用的专用 binding,provider 发现和模型选择会继承已启用的 text.chat binding。
useIntelligence() 的旧 renderer wrapper 仍可用于 loading/error 状态与旧调用点,但新的插件和 renderer 代码应优先使用 typed domain SDK wrapper 与能力发现。
AI 对话
import { useIntelligenceSdk } from '@talex-touch/utils/renderer'
const intelligence = useIntelligenceSdk()
const status = await intelligence.getCapabilityStatus({ capabilityId: 'text.chat' })
const providers = await intelligence.getProviderModelOptions({ capabilityId: 'text.chat' })
if (status.available) {
const result = await intelligence.text.chat({
messages: [
{ role: 'system', content: '你是一个翻译助手' },
{ role: 'user', content: '翻译:Hello World' }
],
temperature: 0.7,
maxTokens: 1000
}, {
allowedProviderIds: providers.filter(provider => provider.available).map(provider => provider.providerId)
})
console.log(result.result)
console.log(result.usage)
## }
OCR 文字识别
const result = await intelligence.vision.ocr({
source: {
type: 'data-url',
dataUrl: 'data:image/png;base64,...'
},
language: 'zh-CN',
includeLayout: true,
includeKeywords: true
})
## console.log(result.result.text)
Image Source 类型:
const sourceDataUrl = { type: 'data-url', dataUrl: 'data:image/png;base64,...' } as const
const sourceFile = { type: 'file', filePath: '/path/to/image.png' } as const
const sourceBase64 = { type: 'base64', base64: '...' } as const
## console.log(sourceDataUrl.type, sourceFile.type, sourceBase64.type)
RAG 重排序
const result = await intelligence.search.rerank({
query: '搜索查询',
documents: searchResults,
topK: 5
})
## console.log(result.result)
通用调用
自定义能力或尚未提供 domain wrapper 的新注册 Capability ID,仍可直接使用 invoke:
const result = await intelligence.invoke('custom.extract-json', {
text: 'name: Ada Lovelace'
})
## console.log(result.result)
调用选项
invoke(capabilityId, payload, options) 的第三个参数使用下列对象;text.chat(payload, options) 等类型化 wrapper 的第二个参数复用同一对象:
interface IntelligenceInvokeOptions {
strategy?: string // 策略 ID
modelPreference?: string[] // 优先模型列表
costCeiling?: number // 成本上限
latencyTarget?: number // 目标延迟 (ms)
timeout?: number // 超时时间 (ms)
stream?: boolean // 是否流式输出
preferredProviderId?: string // 优先 Provider
allowedProviderIds?: string[] // 允许的 Provider 列表
promptTemplate?: string // text.chat 的显式 system prompt 模板
promptVariables?: Record<string, unknown> // 模板 Mustache 变量
}
const \_invokeOptions: IntelligenceInvokeOptions = {}
void \_invokeOptions
strategy 的优先级低于显式 preferredProviderId 和 modelPreference。支持 adaptive-default(默认)、rule-based-default、round-robin:前两个目前都按 capability binding / provider 的稳定 priority 顺序路由,不是基于延迟或成本的优化器;round-robin 会按每个 capability 的已排序可用 provider 轮换,并按同一循环顺序尝试后备 provider。旧值 adaptive、priority 会分别归一化为前两个值;未知策略会安全回退到稳定的 priority 路由。
AI Command Prompt 模板
插件定义 AI Command 时,可将 promptTemplate 和 promptVariables 作为一等调用选项传入。显式模板优先于 legacy metadata 形式和 capability 已配置 binding;宿主只渲染一次,并在路由切换到后备 provider 时保留同一模板。
const status = await intelligence.getCapabilityStatus({ capabilityId: 'text.chat' })
if (!status.available) throw new Error(status.reason || 'AI 不可用')
const selectedText = '为最新变更编写发布说明。'
const response = await intelligence.text.chat(
{ messages: [{ role: 'user', content: selectedText }] },
{
promptTemplate: '请面向{{audience}},以{{tone}}语气改写输入。',
promptVariables: { audience: '开发者', tone: '简洁' },
},
)
## console.log(response.result)
插件 manifest 必须声明 intelligence.basic,并在展示动作前执行 capability discovery。模板变量会进入 provider 输入,禁止放入凭证或 secret;审计只保留 prompt hash,不保留原始模板。
响应结构
所有 invoke 调用都返回统一的响应结构:
interface IntelligenceInvokeResult<T> {
result: T // 结果数据
usage: {
promptTokens: number
completionTokens: number
totalTokens: number
cost?: number
}
model: string // 使用的模型
latency: number // 请求延迟 (ms)
traceId: string // 追踪 ID
provider: string // 使用的 Provider
}
const \_invokeResult = {} as IntelligenceInvokeResult<string>
void \_invokeResult
Stream 事件
stream() 与 contextStream() 使用 callback,并返回 Promise<StreamController>;当前 runtime 只允许 chat capability 进入 stream。controller 暴露 streamId、cancelled 与 cancel()。
let answer = ''
let finalRoute: { traceId?: string; provider?: string; model?: string } = {}
const controller = await intelligence.stream<string>(
'text.chat',
{
messages: [{ role: 'user', content: '请总结这段文本。' }]
},
{
onDelta(delta, event) {
answer += delta
finalRoute = {
traceId: event.traceId,
provider: event.provider,
model: event.model
}
},
onUsage(usage, event) {
finalRoute = {
traceId: event.traceId,
provider: event.provider,
model: event.model
}
console.log(usage.totalTokens)
},
onEnd(event) {
finalRoute = {
traceId: event.traceId,
provider: event.provider,
model: event.model
}
console.log(answer, finalRoute, event.metadata?.latency)
},
onError(error) {
console.error(error)
}
}
)
// owning UI 销毁时调用 controller.cancel()。
void controller
调用方必须把 event 边界视为 transport 细节:
start可能先携带客户端 provisional routing metadata;最终后端路由应取delta、usage或end中最近的非空traceId、provider、model。- 最终 usage 通过
onUsage交付;最终 latency 位于end.metadata.latency。 - provider 可以在没有文本 delta 时结束;UI 必须独立消费
usage/end,不能把空 delta 当作失败。 - 默认 Nexus provider 使用已认证
/api/v1/intelligence/streamSSE,逐步透传真实 provider token delta、后端路由 metadata 与 terminal usage。只允许在首个可见 delta 前 retry/fallback;已输出 delta 后的失败直接上抛,避免回放重复文本。不能依赖 delta 数量或切分粒度。 - 未上报后端 metadata 的 provider 继续兼容,因此 route 字段都是可选值。
完整示例
翻译插件
import { intelligence, useClipboard } from '@talex-touch/utils/plugin/sdk'
const clipboard = useClipboard()
async function translateAndPaste(content: string, targetLang: string) {
const status = await intelligence.getCapabilityStatus({ capabilityId: 'text.translate' })
if (!status.available) return
const result = await intelligence.text.translate({
text: content,
targetLang
})
await clipboard.copyAndPaste({ text: result.result })
}
void translateAndPaste
OCR 识别插件
import { intelligence } from '@talex-touch/utils/plugin/sdk'
async function recognizeText(imageDataUrl: string) {
// 与上例相同的能力发现门:未配置 provider 时该能力不可用。
const status = await intelligence.getCapabilityStatus({ capabilityId: 'vision.ocr' })
if (!status.available) return null
const result = await intelligence.vision.ocr({
source: { type: 'data-url', dataUrl: imageDataUrl },
includeKeywords: true
})
return {
text: result.result.text,
keywords: result.result.keywords
}
}
void recognizeText
状态管理
import { watch } from 'vue'
import { useIntelligence } from '@talex-touch/utils/renderer'
const { isLoading, lastError } = useIntelligence()
watch(isLoading, loading => console.log('loading', loading))
watch(lastError, error => console.log('error', error))
Provider 类型
enum IntelligenceProviderType {
OPENAI = 'openai',
ANTHROPIC = 'anthropic',
DEEPSEEK = 'deepseek',
SILICONFLOW = 'siliconflow',
LOCAL = 'local',
CUSTOM = 'custom'
}
void IntelligenceProviderType.OPENAI
能力类型
import { IntelligenceCapabilityType } from '@talex-touch/utils/types/intelligence'
// 文本
void IntelligenceCapabilityType.CHAT // 'chat'
void IntelligenceCapabilityType.GRAMMAR_CHECK // 'grammar-check'
// 代码
void IntelligenceCapabilityType.CODE_GENERATE // 'code-generate'
void IntelligenceCapabilityType.CODE_DEBUG // 'code-debug'
// 分析
void IntelligenceCapabilityType.INTENT_DETECT // 'intent-detect'
void IntelligenceCapabilityType.SENTIMENT_ANALYZE // 'sentiment-analyze'
// 视觉
void IntelligenceCapabilityType.VISION_OCR // 'vision-ocr'
void IntelligenceCapabilityType.IMAGE_TRANSLATE_E2E // 'image-translate-e2e'
// RAG / Workflow
void IntelligenceCapabilityType.SEMANTIC_SEARCH // 'semantic-search'
void IntelligenceCapabilityType.AGENT // 'agent'
最佳实践
- 根据配额与订阅状态选择能力,避免调用失败。
- 对用户输入做敏感信息脱敏,必要时提示确认。
- 对高频调用做缓存与限流,控制成本。
技术原理
- Intelligence SDK 在渲染进程封装调用,由主进程负责路由到具体 Provider。
- 统一返回结构包含耗时与 token 统计,便于监控与优化。