factual-fox-sdk

factual-fox-sdk 是面向业务后端 Node.js 服务的 Factual Fox SDK。

它当前提供三类正式能力：

1. 查询标签定义与单患者画像
2. 发起业务写入：ingest、ingestBatch、directUpsertTrait
3. 发起正式业务对话回复生成

它不提供以下能力：

• provider/config 管理
• debug session / debug extraction / debug stream
• reset、delete、replay 等运维或后台控制操作
• scene 配置管理

安装

npm install factual-fox-sdk

运行环境建议：

• Node.js 18+

说明：

• SDK 使用 fetch 和 ReadableStream
• 流式能力面向业务后端 Node.js 服务调用，不直接给浏览器前端使用

初始化

import { FactualFoxClient } from 'factual-fox-sdk';

const foxClient = new FactualFoxClient({
  baseURL: 'http://factual-fox-api:3040'
});

也可以通过环境变量初始化：

export FACTUAL_FOX_BASE_URL=http://factual-fox-api:3040

const foxClient = new FactualFoxClient();

API

listTraits(options?)

查询标签定义列表。

const response = await foxClient.listTraits({
  trait_kind: 'base',
  dimension: 'clinical',
  include_inactive: false
});

getTrait(traitKey)

查询单个标签定义。

const trait = await foxClient.getTrait('patient_level');

getPatientProfile(patientId, options?)

查询单个患者画像 JSON。

const profile = await foxClient.getPatientProfile('patient-001', {
  includeEvidence: true
});

ingest(request, idempotencyKey?)

提交一条证据并触发异步抽取。

const accepted = await foxClient.ingest(
  {
    patient_id: 'patient-001',
    source_type: 'followup',
    source_ref: 'followup-001',
    system_code: 'crm',
    event_time: '2026-03-29T08:00:00.000Z',
    raw_content: '患者反馈最近三天餐后血糖偏高。'
  },
  'idem-ingest-001'
);

ingestBatch(request)

批量提交多条证据。

const acceptedBatch = await foxClient.ingestBatch({
  items: [
    {
      patient_id: 'patient-001',
      source_type: 'followup',
      source_ref: 'followup-001',
      system_code: 'crm',
      event_time: '2026-03-29T08:00:00.000Z',
      raw_content: '患者反馈最近三天餐后血糖偏高。'
    }
  ]
});

directUpsertTrait(request, idempotencyKey?)

从可信业务系统直接写入基础标签。

推荐使用当前服务端 contract 中的 trait_code 字段：

const writeResult = await foxClient.directUpsertTrait(
  {
    patient_id: 'patient-001',
    source_type: 'crm',
    source_ref: 'visit-001',
    system_code: 'crm',
    event_time: '2026-03-29T08:00:00.000Z',
    traits: [
      { trait_code: 'patient_level', trait_value: 'tier_1' }
    ]
  },
  'idem-write-001'
);

appendTraits(request, idempotencyKey?)

appendTraits 作为历史兼容别名保留，内部行为等同于 directUpsertTrait。

await foxClient.appendTraits({
  patient_id: 'patient-001',
  source_type: 'crm',
  source_ref: 'visit-001',
  system_code: 'crm',
  event_time: '2026-03-29T08:00:00.000Z',
  traits: [
    { trait_code: 'patient_level', trait_value: 'tier_1' }
  ]
});

generateDialogueReply(request)

按正式业务接口获取一次性完整回复。

const reply = await foxClient.generateDialogueReply({
  patient_id: 'patient-001',
  scene_code: 'followup_general',
  request_timestamp: '2026-03-23T10:30:00.000Z',
  caller_id: 'caregiver-001'
});

请求字段：

• patient_id: 必填，业务患者 ID
• scene_code: 必填，factual-fox 后台维护的 dialogue route key（不是业务方管理的 scene 资源 ID，也不是直接 agent ID）
• request_timestamp: 必填，同一 patient_id + scene_code + request_timestamp 视为同一次回复请求
• caller_id: 选填，用于统计调用方使用量
• force_regenerate: 选填，默认 false，为 true 时跳过复用逻辑

streamDialogueReply(request)

以事件流方式获取回复，返回 AsyncIterable，适合业务后端直接 for await 消费。

for await (const event of foxClient.streamDialogueReply({
  patient_id: 'patient-001',
  scene_code: 'followup_general',
  request_timestamp: '2026-03-23T10:30:00.000Z'
})) {
  if (event.type === 'reply.delta' && event.field === 'content') {
    process.stdout.write(event.delta ?? '');
  }
}

对话能力边界

正式业务对话路径里，业务系统不需要自己管理 route 绑定的 agent/config、thinking level、prompt 拼装或 streaming 策略，这些都由 factual-fox 后台维护。

CLI

安装后会附带 factual-fox-sync 命令，用于同步基础标签定义。

npx factual-fox-sync http://factual-fox-api:3040

factual-fox-sync 只负责标签定义同步，不负责写入、provider/config、debug 或 reset。

错误处理

SDK 在 HTTP 非 2xx 时会直接抛错，错误信息中包含状态码和响应文本。

业务写接口在以下情况下也会直接在本地抛错：

• 缺少 system_code
• directUpsertTrait / appendTraits 既没有单标签字段，也没有非空 traits

正式业务对话常见失败原因：

• scene_code 对应的 dialogue route key 不存在
• scene_code 对应的 dialogue route key 已禁用
• route 不允许流式回复但调用了流式接口
• route 绑定的 dialogue agent 不可用

说明

如果需要项目内更完整的接入说明，可同时参考仓库文档：

• docs/sdk-usage-guide.md